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.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 /** 190 * Returns the data source for this model. 191 * 192 * @return the data source for this model 193 * @see #setDataSource(DataSource) 194 */ 195 public DataSource getDataSource(); 196 197 /** 198 * Returns the listeners registered for this model. 199 * 200 * @return the listeners registered for this model 201 * @see #registerListener(ModelListener) 202 */ 203 public ModelListener<T>[] getListeners(); 204 205 public Session openSession() throws ORMException; 206 207 public SystemException processException(Exception e); 208 209 /** 210 * Registers a new listener for this model. 211 * 212 * <p> 213 * A model listener is notified whenever a change is made to an instance of 214 * this model, such as when one is added, updated, or removed. 215 * </p> 216 * 217 * @param listener the model listener to register 218 */ 219 public void registerListener(ModelListener<T> listener); 220 221 /** 222 * Removes the model instance with the primary key from the database. Also 223 * notifies the appropriate model listeners. 224 * 225 * @param primaryKey the primary key of the model instance to remove 226 * @return the model instance that was removed 227 * @throws NoSuchModelException if an instance of this model with the 228 * primary key could not be found 229 * @throws SystemException if a system exception occurred 230 */ 231 public T remove(Serializable primaryKey) 232 throws NoSuchModelException, SystemException; 233 234 /** 235 * Removes the model instance from the database. Also notifies the 236 * appropriate model listeners. 237 * 238 * @param model the model instance to remove 239 * @return the model instance that was removed 240 * @throws SystemException if a system exception occurred 241 */ 242 public T remove(T model) throws SystemException; 243 244 /** 245 * Sets the data source for this model. 246 * 247 * @param dataSource the data source to use for this model 248 */ 249 public void setDataSource(DataSource dataSource); 250 251 /** 252 * Unregisters the model listener. 253 * 254 * @param listener the model listener to unregister 255 * @see #registerListener(ModelListener) 256 */ 257 public void unregisterListener(ModelListener<T> listener); 258 259 /** 260 * Updates the model instance in the database or adds it if it does not yet 261 * exist. Also notifies the appropriate model listeners. 262 * 263 * <p> 264 * Typically not called directly, use local service update model methods 265 * instead. For example, {@link 266 * com.liferay.portal.service.UserLocalServiceUtil#updateUser( 267 * com.liferay.portal.model.User)}. 268 * </p> 269 * 270 * @param model the model instance to update 271 * @param merge whether to merge the model instance with the current 272 * session. See {@link 273 * BatchSession#update(com.liferay.portal.kernel.dao.orm.Session, 274 * BaseModel, boolean)} for an explanation. 275 * @return the model instance that was updated 276 * @throws SystemException if a system exception occurred 277 */ 278 public T update(T model, boolean merge) throws SystemException; 279 280 /** 281 * Updates the model instance in the database or adds it if it does not yet 282 * exist, within a different service context. Also notifies the appropriate 283 * model listeners. 284 * 285 * @param model the model instance to update 286 * @param merge whether to merge the model instance with the current 287 * session. See {@link 288 * BatchSession#update(com.liferay.portal.kernel.dao.orm.Session, 289 * BaseModel, boolean)} for an explanation. 290 * @param serviceContext the service context to perform the update in 291 * @return the model instance that was updated 292 * @throws SystemException if a system exception occurred 293 */ 294 public T update(T model, boolean merge, ServiceContext serviceContext) 295 throws SystemException; 296 297 }