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