001 /** 002 * Copyright (c) 2000-present Liferay, Inc. All rights reserved. 003 * 004 * This library is free software; you can redistribute it and/or modify it under 005 * the terms of the GNU Lesser General Public License as published by the Free 006 * Software Foundation; either version 2.1 of the License, or (at your option) 007 * any later version. 008 * 009 * This library is distributed in the hope that it will be useful, but WITHOUT 010 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 011 * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more 012 * details. 013 */ 014 015 package com.liferay.portal.service.persistence; 016 017 import com.liferay.portal.exception.NoSuchModelException; 018 import com.liferay.portal.kernel.dao.orm.DynamicQuery; 019 import com.liferay.portal.kernel.dao.orm.ORMException; 020 import com.liferay.portal.kernel.dao.orm.Projection; 021 import com.liferay.portal.kernel.dao.orm.Session; 022 import com.liferay.portal.kernel.exception.SystemException; 023 import com.liferay.portal.kernel.util.OrderByComparator; 024 import com.liferay.portal.model.BaseModel; 025 import com.liferay.portal.model.ModelListener; 026 import com.liferay.portal.service.ServiceContext; 027 028 import java.io.Serializable; 029 030 import java.util.List; 031 import java.util.Map; 032 import java.util.Set; 033 034 import javax.sql.DataSource; 035 036 /** 037 * The base interface for all ServiceBuilder persistence classes. This interface 038 * should never need to be used directly. 039 * 040 * <p> 041 * Caching information and settings can be found in 042 * <code>portal.properties</code> 043 * </p> 044 * 045 * @author Brian Wing Shun Chan 046 * @see com.liferay.portal.service.persistence.impl.BasePersistenceImpl 047 */ 048 public interface BasePersistence<T extends BaseModel<T>> { 049 050 /** 051 * Clears the cache for all instances of this model. 052 * 053 * <p> 054 * The {@link com.liferay.portal.kernel.dao.orm.EntityCache} and {@link 055 * com.liferay.portal.kernel.dao.orm.FinderCache} are both cleared by this 056 * method. 057 * </p> 058 */ 059 public void clearCache(); 060 061 /** 062 * Clears the cache for a List instances of this model. 063 * 064 * <p> 065 * The {@link com.liferay.portal.kernel.dao.orm.EntityCache} and {@link 066 * com.liferay.portal.kernel.dao.orm.FinderCache} are both cleared by this 067 * method. 068 * </p> 069 * 070 * @param modelList the List instances of this model to clear the cache for 071 */ 072 public void clearCache(List<T> modelList); 073 074 /** 075 * Clears the cache for one instance of this model. 076 * 077 * <p> 078 * The {@link com.liferay.portal.kernel.dao.orm.EntityCache} and {@link 079 * com.liferay.portal.kernel.dao.orm.FinderCache} are both cleared by this 080 * method. 081 * </p> 082 * 083 * @param model the instance of this model to clear the cache for 084 */ 085 public void clearCache(T model); 086 087 public void closeSession(Session session); 088 089 /** 090 * Returns the number of rows that match the dynamic query. 091 * 092 * @param dynamicQuery the dynamic query 093 * @return the number of rows that match the dynamic query 094 */ 095 public long countWithDynamicQuery(DynamicQuery dynamicQuery); 096 097 /** 098 * Returns the number of rows that match the dynamic query. 099 * 100 * @param dynamicQuery the dynamic query 101 * @param projection the projection to apply to the query 102 * @return the number of rows that match the dynamic query 103 */ 104 public long countWithDynamicQuery( 105 DynamicQuery dynamicQuery, Projection projection); 106 107 /** 108 * Returns the model instance with the primary key or returns 109 * <code>null</code> if it could not be found. 110 * 111 * @param primaryKey the primary key of the model instance 112 * @return the model instance, or <code>null</code> if an instance of this 113 * model with the primary key could not be found 114 */ 115 public T fetchByPrimaryKey(Serializable primaryKey); 116 117 public Map<Serializable, T> fetchByPrimaryKeys( 118 Set<Serializable> primaryKeys); 119 120 /** 121 * Returns the model instance with the primary key or throws a {@link 122 * NoSuchModelException} if it could not be found. 123 * 124 * @param primaryKey the primary key of the model instance 125 * @return the model instance 126 */ 127 public T findByPrimaryKey(Serializable primaryKey) 128 throws NoSuchModelException; 129 130 /** 131 * Performs a dynamic query on the database and returns the matching rows. 132 * 133 * @param dynamicQuery the dynamic query 134 * @return the matching rows 135 */ 136 public <V> List<V> findWithDynamicQuery(DynamicQuery dynamicQuery); 137 138 /** 139 * Performs a dynamic query on the database and returns a range of the 140 * matching rows. 141 * 142 * <p> 143 * Useful when paginating results. Returns a maximum of <code>end - 144 * start</code> instances. <code>start</code> and <code>end</code> are not 145 * primary keys, they are indexes in the result set. Thus, <code>0</code> 146 * refers to the first result in the set. Setting both <code>start</code> 147 * and <code>end</code> to {@link 148 * com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS} will return the full 149 * result set. 150 * </p> 151 * 152 * @param dynamicQuery the dynamic query 153 * @param start the lower bound of the range of matching rows 154 * @param end the upper bound of the range of matching rows (not inclusive) 155 * @return the range of matching rows 156 * @see com.liferay.portal.kernel.dao.orm.QueryUtil#list( 157 * com.liferay.portal.kernel.dao.orm.Query, 158 * com.liferay.portal.kernel.dao.orm.Dialect, int, int) 159 */ 160 public <V> List<V> findWithDynamicQuery( 161 DynamicQuery dynamicQuery, int start, int end); 162 163 /** 164 * Performs a dynamic query on the database and returns an ordered range of 165 * the matching rows. 166 * 167 * <p> 168 * Useful when paginating results. Returns a maximum of <code>end - 169 * start</code> instances. <code>start</code> and <code>end</code> are not 170 * primary keys, they are indexes in the result set. Thus, <code>0</code> 171 * refers to the first result in the set. Setting both <code>start</code> 172 * and <code>end</code> to {@link 173 * com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS} will return the full 174 * result set. 175 * </p> 176 * 177 * @param dynamicQuery the dynamic query 178 * @param start the lower bound of the range of matching rows 179 * @param end the upper bound of the range of matching rows (not inclusive) 180 * @param orderByComparator the comparator to order the results by 181 * (optionally <code>null</code>) 182 * @return the ordered range of matching rows 183 */ 184 public <V> List<V> findWithDynamicQuery( 185 DynamicQuery dynamicQuery, int start, int end, 186 OrderByComparator<V> orderByComparator); 187 188 public void flush(); 189 190 public Set<String> getBadColumnNames(); 191 192 public Session getCurrentSession() throws ORMException; 193 194 /** 195 * Returns the data source for this model. 196 * 197 * @return the data source for this model 198 * @see #setDataSource(DataSource) 199 */ 200 public DataSource getDataSource(); 201 202 /** 203 * Returns the listeners registered for this model. 204 * 205 * @return the listeners registered for this model 206 * @see #registerListener(ModelListener) 207 */ 208 public ModelListener<T>[] getListeners(); 209 210 public Class<T> getModelClass(); 211 212 public Session openSession() throws ORMException; 213 214 public SystemException processException(Exception e); 215 216 /** 217 * Registers a new listener for this model. 218 * 219 * <p> 220 * A model listener is notified whenever a change is made to an instance of 221 * this model, such as when one is added, updated, or removed. 222 * </p> 223 * 224 * @param listener the model listener to register 225 */ 226 public void registerListener(ModelListener<T> listener); 227 228 /** 229 * Removes the model instance with the primary key from the database. Also 230 * notifies the appropriate model listeners. 231 * 232 * @param primaryKey the primary key of the model instance to remove 233 * @return the model instance that was removed 234 */ 235 public T remove(Serializable primaryKey) throws NoSuchModelException; 236 237 /** 238 * Removes the model instance from the database. Also notifies the 239 * appropriate model listeners. 240 * 241 * @param model the model instance to remove 242 * @return the model instance that was removed 243 */ 244 public T remove(T model); 245 246 /** 247 * Sets the data source for this model. 248 * 249 * @param dataSource the data source to use for this model 250 */ 251 public void setDataSource(DataSource dataSource); 252 253 /** 254 * Unregisters the model listener. 255 * 256 * @param listener the model listener to unregister 257 * @see #registerListener(ModelListener) 258 */ 259 public void unregisterListener(ModelListener<T> listener); 260 261 /** 262 * Updates the model instance in the database or adds it if it does not yet 263 * exist. Also notifies the appropriate model listeners. 264 * 265 * <p> 266 * Typically not called directly, use local service update model methods 267 * instead. For example, {@link 268 * com.liferay.portal.service.UserLocalServiceUtil#updateUser( 269 * com.liferay.portal.model.User)}. 270 * </p> 271 * 272 * @param model the model instance to update 273 * @return the model instance that was updated 274 */ 275 public T update(T model); 276 277 /** 278 * @deprecated As of 6.2.0, replaced by {@link #update(BaseModel)}} 279 */ 280 @Deprecated 281 public T update(T model, boolean merge); 282 283 /** 284 * @deprecated As of 6.2.0, replaced by {@link #update(BaseModel, 285 * ServiceContext)}} 286 */ 287 @Deprecated 288 public T update(T model, boolean merge, ServiceContext serviceContext); 289 290 /** 291 * Updates the model instance in the database or adds it if it does not yet 292 * exist, within a different service context. Also notifies the appropriate 293 * model listeners. 294 * 295 * @param model the model instance to update 296 * @param serviceContext the service context to be applied 297 * @return the model instance that was updated 298 */ 299 public T update(T model, ServiceContext serviceContext); 300 301 }