001 /** 002 * Copyright (c) 2000-2011 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 one instance 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 model the instance of this model to clear the cache for 068 */ 069 public void clearCache(T model); 070 071 public void closeSession(Session session); 072 073 /** 074 * Returns the number of rows that match the dynamic query. 075 * 076 * @param dynamicQuery the dynamic query 077 * @return the number of rows that match the dynamic query 078 * @throws SystemException if a system exception occurred 079 */ 080 public long countWithDynamicQuery(DynamicQuery dynamicQuery) 081 throws SystemException; 082 083 /** 084 * Returns the model instance with the primary key or returns 085 * <code>null</code> if it could not be found. 086 * 087 * @param primaryKey the primary key of the model instance 088 * @return the model instance, or <code>null</code> if an instance of this 089 * model with the primary key could not be found 090 * @throws SystemException if the primary key is <code>null</code>, or if a 091 * system exception occurred 092 */ 093 public T fetchByPrimaryKey(Serializable primaryKey) throws SystemException; 094 095 /** 096 * Returns the model instance with the primary key or throws a {@link 097 * NoSuchModelException} if it could not be found. 098 * 099 * @param primaryKey the primary key of the model instance 100 * @return the model instance 101 * @throws NoSuchModelException if an instance of this model with the 102 * 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 findByPrimaryKey(Serializable primaryKey) 107 throws NoSuchModelException, SystemException; 108 109 /** 110 * Performs a dynamic query on the database and returns the matching rows. 111 * 112 * @param dynamicQuery the dynamic query 113 * @return the matching rows 114 * @throws SystemException if a system exception occurred 115 */ 116 @SuppressWarnings("rawtypes") 117 public List findWithDynamicQuery(DynamicQuery dynamicQuery) 118 throws SystemException; 119 120 /** 121 * Performs a dynamic query on the database and returns a range of the 122 * matching rows. 123 * 124 * <p> 125 * Useful when paginating results. Returns a maximum of <code>end - 126 * start</code> instances. <code>start</code> and <code>end</code> are not 127 * primary keys, they are indexes in the result set. Thus, <code>0</code> 128 * refers to the first result in the set. Setting both <code>start</code> 129 * and <code>end</code> to {@link 130 * com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS} will return the full 131 * result set. 132 * </p> 133 * 134 * @param dynamicQuery the dynamic query 135 * @param start the lower bound of the range of matching rows 136 * @param end the upper bound of the range of matching rows (not inclusive) 137 * @return the range of matching rows 138 * @throws SystemException if a system exception occurred 139 * @see com.liferay.portal.kernel.dao.orm.QueryUtil#list( 140 * com.liferay.portal.kernel.dao.orm.Query, 141 * com.liferay.portal.kernel.dao.orm.Dialect, int, int) 142 */ 143 @SuppressWarnings("rawtypes") 144 public List findWithDynamicQuery( 145 DynamicQuery dynamicQuery, int start, int end) 146 throws SystemException; 147 148 /** 149 * Performs a dynamic query on the database and returns an ordered range of 150 * the matching rows. 151 * 152 * <p> 153 * Useful when paginating results. Returns a maximum of <code>end - 154 * start</code> instances. <code>start</code> and <code>end</code> are not 155 * primary keys, they are indexes in the result set. Thus, <code>0</code> 156 * refers to the first result in the set. Setting both <code>start</code> 157 * and <code>end</code> to {@link 158 * com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS} will return the full 159 * result set. 160 * </p> 161 * 162 * @param dynamicQuery the dynamic query 163 * @param start the lower bound of the range of matching rows 164 * @param end the upper bound of the range of matching rows (not inclusive) 165 * @param orderByComparator the comparator to order the results by 166 * (optionally <code>null</code>) 167 * @return the ordered range of matching rows 168 * @throws SystemException if a system exception occurred 169 */ 170 @SuppressWarnings("rawtypes") 171 public List findWithDynamicQuery( 172 DynamicQuery dynamicQuery, int start, int end, 173 OrderByComparator orderByComparator) 174 throws SystemException; 175 176 /** 177 * Returns the data source for this model. 178 * 179 * @return the data source for this model 180 * @see #setDataSource(DataSource) 181 */ 182 public DataSource getDataSource(); 183 184 /** 185 * Returns the listeners registered for this model. 186 * 187 * @return the listeners registered for this model 188 * @see #registerListener(ModelListener) 189 */ 190 public ModelListener<T>[] getListeners(); 191 192 public Session openSession() throws ORMException; 193 194 public SystemException processException(Exception e); 195 196 /** 197 * Registers a new listener for this model. 198 * 199 * <p> 200 * A model listener is notified whenever a change is made to an instance of 201 * this model, such as when one is added, updated, or removed. 202 * </p> 203 * 204 * @param listener the model listener to register 205 */ 206 public void registerListener(ModelListener<T> listener); 207 208 /** 209 * Removes the model instance with the primary key from the database. Also 210 * notifies the appropriate model listeners. 211 * 212 * @param primaryKey the primary key of the model instance to remove 213 * @return the model instance that was removed 214 * @throws NoSuchModelException if an instance of this model with the 215 * primary key could not be found 216 * @throws SystemException if a system exception occurred 217 */ 218 public T remove(Serializable primaryKey) 219 throws NoSuchModelException, SystemException; 220 221 /** 222 * Removes the model instance from the database. Also notifies the 223 * appropriate model listeners. 224 * 225 * @param model the model instance to remove 226 * @return the model instance that was removed 227 * @throws SystemException if a system exception occurred 228 */ 229 public T remove(T model) throws SystemException; 230 231 /** 232 * Sets the data source for this model. 233 * 234 * @param dataSource the data source to use for this model 235 */ 236 public void setDataSource(DataSource dataSource); 237 238 /** 239 * Unregisters the model listener. 240 * 241 * @param listener the model listener to unregister 242 * @see #registerListener(ModelListener) 243 */ 244 public void unregisterListener(ModelListener<T> listener); 245 246 /** 247 * Updates the model instance in the database or adds it if it does not yet 248 * exist. Also notifies the appropriate model listeners. 249 * 250 * <p> 251 * Typically not called directly, use local service update model methods 252 * instead. For example, {@link 253 * com.liferay.portal.service.UserLocalServiceUtil#updateUser( 254 * com.liferay.portal.model.User)}. 255 * </p> 256 * 257 * @param model the model instance to update 258 * @param merge whether to merge the model instance with the current 259 * session. See {@link 260 * BatchSession#update(com.liferay.portal.kernel.dao.orm.Session, 261 * BaseModel, boolean)} for an explanation. 262 * @return the model instance that was updated 263 * @throws SystemException if a system exception occurred 264 */ 265 public T update(T model, boolean merge) throws SystemException; 266 267 /** 268 * Updates the model instance in the database or adds it if it does not yet 269 * exist, within a different service context. Also notifies the appropriate 270 * model listeners. 271 * 272 * @param model the model instance to update 273 * @param merge whether to merge the model instance with the current 274 * session. See {@link 275 * BatchSession#update(com.liferay.portal.kernel.dao.orm.Session, 276 * BaseModel, boolean)} for an explanation. 277 * @param serviceContext the service context to perform the update in 278 * @return the model instance that was updated 279 * @throws SystemException if a system exception occurred 280 */ 281 public T update(T model, boolean merge, ServiceContext serviceContext) 282 throws SystemException; 283 284 }