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