001 /** 002 * Copyright (c) 2000-2013 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.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 032 import javax.sql.DataSource; 033 034 /** 035 * The base interface for all ServiceBuilder persistence classes. This interface 036 * should never need to be used directly. 037 * 038 * <p> 039 * Caching information and settings can be found in 040 * <code>portal.properties</code> 041 * </p> 042 * 043 * @author Brian Wing Shun Chan 044 * @see com.liferay.portal.service.persistence.impl.BasePersistenceImpl 045 */ 046 public interface BasePersistence<T extends BaseModel<T>> { 047 048 /** 049 * Clears the cache for all instances of this model. 050 * 051 * <p> 052 * The {@link com.liferay.portal.kernel.dao.orm.EntityCache} and {@link 053 * com.liferay.portal.kernel.dao.orm.FinderCache} are both cleared by this 054 * method. 055 * </p> 056 */ 057 public void clearCache(); 058 059 /** 060 * Clears the cache for a List instances of this model. 061 * 062 * <p> 063 * The {@link com.liferay.portal.kernel.dao.orm.EntityCache} and {@link 064 * com.liferay.portal.kernel.dao.orm.FinderCache} are both cleared by this 065 * method. 066 * </p> 067 * 068 * @param modelList the List instances of this model to clear the cache for 069 */ 070 public void clearCache(List<T> modelList); 071 072 /** 073 * Clears the cache for one instance of this model. 074 * 075 * <p> 076 * The {@link com.liferay.portal.kernel.dao.orm.EntityCache} and {@link 077 * com.liferay.portal.kernel.dao.orm.FinderCache} are both cleared by this 078 * method. 079 * </p> 080 * 081 * @param model the instance of this model to clear the cache for 082 */ 083 public void clearCache(T model); 084 085 public void closeSession(Session session); 086 087 /** 088 * Returns the number of rows that match the dynamic query. 089 * 090 * @param dynamicQuery the dynamic query 091 * @return the number of rows that match the dynamic query 092 * @throws SystemException if a system exception occurred 093 */ 094 public long countWithDynamicQuery(DynamicQuery dynamicQuery) 095 throws SystemException; 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 * @throws SystemException if a system exception occurred 104 */ 105 public long countWithDynamicQuery( 106 DynamicQuery dynamicQuery, Projection projection) 107 throws SystemException; 108 109 /** 110 * Returns the model instance with the primary key or returns 111 * <code>null</code> if it could not be found. 112 * 113 * @param primaryKey the primary key of the model instance 114 * @return the model instance, or <code>null</code> if an instance of this 115 * model with the primary key could not be found 116 * @throws SystemException if the primary key is <code>null</code>, or if a 117 * system exception occurred 118 */ 119 public T fetchByPrimaryKey(Serializable primaryKey) throws SystemException; 120 121 /** 122 * Returns the model instance with the primary key or throws a {@link 123 * NoSuchModelException} if it could not be found. 124 * 125 * @param primaryKey the primary key of the model instance 126 * @return the model instance 127 * @throws NoSuchModelException if an instance of this model with the 128 * primary key could not be found 129 * @throws SystemException if the primary key is <code>null</code>, or if a 130 * system exception occurred 131 */ 132 public T findByPrimaryKey(Serializable primaryKey) 133 throws NoSuchModelException, SystemException; 134 135 /** 136 * Performs a dynamic query on the database and returns the matching rows. 137 * 138 * @param dynamicQuery the dynamic query 139 * @return the matching rows 140 * @throws SystemException if a system exception occurred 141 */ 142 @SuppressWarnings("rawtypes") 143 public List findWithDynamicQuery(DynamicQuery dynamicQuery) 144 throws SystemException; 145 146 /** 147 * Performs a dynamic query on the database and returns a range of the 148 * matching rows. 149 * 150 * <p> 151 * Useful when paginating results. Returns a maximum of <code>end - 152 * start</code> instances. <code>start</code> and <code>end</code> are not 153 * primary keys, they are indexes in the result set. Thus, <code>0</code> 154 * refers to the first result in the set. Setting both <code>start</code> 155 * and <code>end</code> to {@link 156 * com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS} will return the full 157 * result set. 158 * </p> 159 * 160 * @param dynamicQuery the dynamic query 161 * @param start the lower bound of the range of matching rows 162 * @param end the upper bound of the range of matching rows (not inclusive) 163 * @return the range of matching rows 164 * @throws SystemException if a system exception occurred 165 * @see com.liferay.portal.kernel.dao.orm.QueryUtil#list( 166 * com.liferay.portal.kernel.dao.orm.Query, 167 * com.liferay.portal.kernel.dao.orm.Dialect, int, int) 168 */ 169 @SuppressWarnings("rawtypes") 170 public List findWithDynamicQuery( 171 DynamicQuery dynamicQuery, int start, int end) 172 throws SystemException; 173 174 /** 175 * Performs a dynamic query on the database and returns an ordered range of 176 * the matching rows. 177 * 178 * <p> 179 * Useful when paginating results. Returns a maximum of <code>end - 180 * start</code> instances. <code>start</code> and <code>end</code> are not 181 * primary keys, they are indexes in the result set. Thus, <code>0</code> 182 * refers to the first result in the set. Setting both <code>start</code> 183 * and <code>end</code> to {@link 184 * com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS} will return the full 185 * result set. 186 * </p> 187 * 188 * @param dynamicQuery the dynamic query 189 * @param start the lower bound of the range of matching rows 190 * @param end the upper bound of the range of matching rows (not inclusive) 191 * @param orderByComparator the comparator to order the results by 192 * (optionally <code>null</code>) 193 * @return the ordered range of matching rows 194 * @throws SystemException if a system exception occurred 195 */ 196 @SuppressWarnings("rawtypes") 197 public List findWithDynamicQuery( 198 DynamicQuery dynamicQuery, int start, int end, 199 OrderByComparator orderByComparator) 200 throws SystemException; 201 202 public void flush() throws SystemException; 203 204 public Session getCurrentSession() throws ORMException; 205 206 /** 207 * Returns the data source for this model. 208 * 209 * @return the data source for this model 210 * @see #setDataSource(DataSource) 211 */ 212 public DataSource getDataSource(); 213 214 /** 215 * Returns the listeners registered for this model. 216 * 217 * @return the listeners registered for this model 218 * @see #registerListener(ModelListener) 219 */ 220 public ModelListener<T>[] getListeners(); 221 222 public Class<T> getModelClass(); 223 224 public Session openSession() throws ORMException; 225 226 public SystemException processException(Exception e); 227 228 /** 229 * Registers a new listener for this model. 230 * 231 * <p> 232 * A model listener is notified whenever a change is made to an instance of 233 * this model, such as when one is added, updated, or removed. 234 * </p> 235 * 236 * @param listener the model listener to register 237 */ 238 public void registerListener(ModelListener<T> listener); 239 240 /** 241 * Removes the model instance with the primary key from the database. Also 242 * notifies the appropriate model listeners. 243 * 244 * @param primaryKey the primary key of the model instance to remove 245 * @return the model instance that was removed 246 * @throws NoSuchModelException if an instance of this model with the 247 * primary key could not be found 248 * @throws SystemException if a system exception occurred 249 */ 250 public T remove(Serializable primaryKey) 251 throws NoSuchModelException, SystemException; 252 253 /** 254 * Removes the model instance from the database. Also notifies the 255 * appropriate model listeners. 256 * 257 * @param model the model instance to remove 258 * @return the model instance that was removed 259 * @throws SystemException if a system exception occurred 260 */ 261 public T remove(T model) throws SystemException; 262 263 /** 264 * Sets the data source for this model. 265 * 266 * @param dataSource the data source to use for this model 267 */ 268 public void setDataSource(DataSource dataSource); 269 270 /** 271 * Unregisters the model listener. 272 * 273 * @param listener the model listener to unregister 274 * @see #registerListener(ModelListener) 275 */ 276 public void unregisterListener(ModelListener<T> listener); 277 278 /** 279 * Updates the model instance in the database or adds it if it does not yet 280 * exist. Also notifies the appropriate model listeners. 281 * 282 * <p> 283 * Typically not called directly, use local service update model methods 284 * instead. For example, {@link 285 * com.liferay.portal.service.UserLocalServiceUtil#updateUser( 286 * com.liferay.portal.model.User)}. 287 * </p> 288 * 289 * @param model the model instance to update 290 * @return the model instance that was updated 291 * @throws SystemException if a system exception occurred 292 */ 293 public T update(T model) throws SystemException; 294 295 /** 296 * @deprecated As of 6.2.0, replaced by {@link #update(BaseModel)}} 297 */ 298 public T update(T model, boolean merge) throws SystemException; 299 300 /** 301 * @deprecated As of 6.2.0, replaced by {@link #update(BaseModel, 302 * ServiceContext)}} 303 */ 304 public T update(T model, boolean merge, ServiceContext serviceContext) 305 throws SystemException; 306 307 /** 308 * Updates the model instance in the database or adds it if it does not yet 309 * exist, within a different service context. Also notifies the appropriate 310 * model listeners. 311 * 312 * @param model the model instance to update 313 * @param serviceContext the service context to be applied 314 * @return the model instance that was updated 315 * @throws SystemException if a system exception occurred 316 */ 317 public T update(T model, ServiceContext serviceContext) 318 throws SystemException; 319 320 }