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 Session openSession() throws ORMException; 223 224 public SystemException processException(Exception e); 225 226 /** 227 * Registers a new listener for this model. 228 * 229 * <p> 230 * A model listener is notified whenever a change is made to an instance of 231 * this model, such as when one is added, updated, or removed. 232 * </p> 233 * 234 * @param listener the model listener to register 235 */ 236 public void registerListener(ModelListener<T> listener); 237 238 /** 239 * Removes the model instance with the primary key from the database. Also 240 * notifies the appropriate model listeners. 241 * 242 * @param primaryKey the primary key of the model instance to remove 243 * @return the model instance that was removed 244 * @throws NoSuchModelException if an instance of this model with the 245 * primary key could not be found 246 * @throws SystemException if a system exception occurred 247 */ 248 public T remove(Serializable primaryKey) 249 throws NoSuchModelException, SystemException; 250 251 /** 252 * Removes the model instance from the database. Also notifies the 253 * appropriate model listeners. 254 * 255 * @param model the model instance to remove 256 * @return the model instance that was removed 257 * @throws SystemException if a system exception occurred 258 */ 259 public T remove(T model) throws SystemException; 260 261 /** 262 * Sets the data source for this model. 263 * 264 * @param dataSource the data source to use for this model 265 */ 266 public void setDataSource(DataSource dataSource); 267 268 /** 269 * Unregisters the model listener. 270 * 271 * @param listener the model listener to unregister 272 * @see #registerListener(ModelListener) 273 */ 274 public void unregisterListener(ModelListener<T> listener); 275 276 /** 277 * Updates the model instance in the database or adds it if it does not yet 278 * exist. Also notifies the appropriate model listeners. 279 * 280 * <p> 281 * Typically not called directly, use local service update model methods 282 * instead. For example, {@link 283 * com.liferay.portal.service.UserLocalServiceUtil#updateUser( 284 * com.liferay.portal.model.User)}. 285 * </p> 286 * 287 * @param model the model instance to update 288 * @return the model instance that was updated 289 * @throws SystemException if a system exception occurred 290 */ 291 public T update(T model) throws SystemException; 292 293 /** 294 * @deprecated As of 6.2.0, replaced by {@link #update(BaseModel)}} 295 */ 296 public T update(T model, boolean merge) throws SystemException; 297 298 /** 299 * @deprecated As of 6.2.0, replaced by {@link #update(BaseModel, 300 * ServiceContext)}} 301 */ 302 public T update(T model, boolean merge, ServiceContext serviceContext) 303 throws SystemException; 304 305 /** 306 * Updates the model instance in the database or adds it if it does not yet 307 * exist, within a different service context. Also notifies the appropriate 308 * model listeners. 309 * 310 * @param model the model instance to update 311 * @param serviceContext the service context to be applied 312 * @return the model instance that was updated 313 * @throws SystemException if a system exception occurred 314 */ 315 public T update(T model, ServiceContext serviceContext) 316 throws SystemException; 317 318 }