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 import com.liferay.portal.service.UserLocalServiceUtil; 025 026 import java.io.Serializable; 027 028 import java.util.List; 029 030 import javax.sql.DataSource; 031 032 /** 033 * The base interface for all persistence classes. 034 * 035 * @author Brian Wing Shun Chan 036 * @see com.liferay.portal.service.persistence.impl.BasePersistenceImpl 037 */ 038 public interface BasePersistence<T extends BaseModel<T>> { 039 040 /** 041 * Clears the cache for all instances of this model. 042 * 043 * <p> 044 * The {@link com.liferay.portal.kernel.dao.orm.EntityCache} and {@link 045 * com.liferay.portal.kernel.dao.orm.FinderCache} are both cleared by this 046 * method. 047 * </p> 048 * 049 * <p> 050 * Caching information and settings can be found in 051 * <code>portal.properties</code> 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 an instance of this model by its primary key, or return 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 does not exist 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 an instance of this model by its primary key, or throw an exception 093 * 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 does not exist 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("unchecked") 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. 123 * </p> 124 * 125 * <p> 126 * <code>start</code> and <code>end</code> are not primary keys, they are 127 * indexes in the result set. Thus, <code>0</code> refers to the first 128 * result in the set. Setting both <code>start</code> and <code>end</code> 129 * to {@link com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS} will 130 * return the full result set, functionally equivalent to {@link 131 * #findWithDynamicQuery(DynamicQuery)}. 132 * </p> 133 * 134 * @param dynamicQuery the dynamic query to search with 135 * @param start the lower bound of the range of model instances to return 136 * @param end the upper bound of the range of model instances to return 137 * (not inclusive) 138 * @return the matching rows 139 * @throws SystemException if a system exception occurred 140 * @see com.liferay.portal.kernel.dao.orm.QueryUtil#list( 141 * com.liferay.portal.kernel.dao.orm.Query, 142 * com.liferay.portal.kernel.dao.orm.Dialect, int, int) 143 */ 144 @SuppressWarnings("unchecked") 145 public List findWithDynamicQuery( 146 DynamicQuery dynamicQuery, int start, int end) 147 throws SystemException; 148 149 /** 150 * Finds an ordered range of all the instances of this model that match the 151 * dynamic query. 152 * 153 * <p> 154 * <code>start</code> and <code>end</code> are not primary keys, they are 155 * indexes in the result set. Thus, <code>0</code> refers to the first 156 * result in the set. Setting both <code>start</code> and <code>end</code> 157 * to {@link com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS} will 158 * return the full result set. 159 * </p> 160 * 161 * @param dynamicQuery the dynamic query to search with 162 * @param start the lower bound of the range of model instances to return 163 * @param end the upper bound of the range of model instances to return 164 * (not inclusive) 165 * @param orderByComparator the comparator to order the results by 166 * @return all the instances of this model inside the specified range 167 * @throws SystemException if a system exception occurred 168 */ 169 @SuppressWarnings("unchecked") 170 public List findWithDynamicQuery( 171 DynamicQuery dynamicQuery, int start, int end, 172 OrderByComparator orderByComparator) 173 throws SystemException; 174 175 /** 176 * Gets the data source for this model. 177 * 178 * @return the data source for this model 179 * @see #setDataSource(DataSource) 180 */ 181 public DataSource getDataSource(); 182 183 /** 184 * Gets the listeners registered for this model. 185 * 186 * @return the listeners registered for this model 187 * @see #registerListener(ModelListener) 188 */ 189 public ModelListener<T>[] getListeners(); 190 191 /** 192 * Registers a new listener for this model. 193 * 194 * <p> 195 * A model listener is notified whenever a change is made to an instance of 196 * this model, such as when one is added, updated, or removed. 197 * </p> 198 * 199 * @param listener the model listener to register 200 */ 201 public void registerListener(ModelListener<T> listener); 202 203 /** 204 * Removes the model instance identified by the primary key from the 205 * database, and notifies the appropriate model listeners. 206 * 207 * @param primaryKey the primary key of the model instance to remove 208 * @return the model instance that was removed 209 * @throws NoSuchModelException if an instance of this model with the 210 * primary key does not exist 211 * @throws SystemException if a system exception occurred 212 */ 213 public T remove(Serializable primaryKey) 214 throws NoSuchModelException, SystemException; 215 216 /** 217 * Removes the model instance from the database and notifies the appropriate 218 * model listeners. 219 * 220 * @param model the model instance to remove 221 * @return the model instance that was removed 222 * @throws SystemException if a system exception occurred 223 */ 224 public T remove(T model) throws SystemException; 225 226 /** 227 * Sets the data source for this model. 228 * 229 * @param dataSource the data source to use for this model 230 */ 231 public void setDataSource(DataSource dataSource); 232 233 /** 234 * Unregisters the model listener. 235 * 236 * @param listener the model listener to unregister 237 * @see #registerListener(ModelListener) 238 */ 239 public void unregisterListener(ModelListener<T> listener); 240 241 /** 242 * Updates the model instance in the database or adds it if it does not yet 243 * exist. Also notifies the appropriate model listeners. 244 * 245 * <p> 246 * Typically not called directly, use local service update model methods 247 * instead. For example, {@link 248 * UserLocalServiceUtil#updateUser(com.liferay.portal.model.User)}. 249 * </p> 250 * 251 * @param model the model instance to update 252 * @param merge whether to merge the model instance with the current 253 * session. See {@link 254 * BatchSession#update(com.liferay.portal.kernel.dao.orm.Session, 255 * BaseModel, boolean)} for an explanation. 256 * @return the model instance that was updated 257 * @throws SystemException if a system exception occurred 258 */ 259 public T update(T model, boolean merge) throws SystemException; 260 261 /** 262 * Updates the model instance in the database or adds it if it does not yet 263 * exist, within a different service context. Also notifies the appropriate 264 * model listeners. 265 * 266 * @param model the model instance to update 267 * @param merge whether to merge the model instance with the current 268 * session. See {@link 269 * BatchSession#update(com.liferay.portal.kernel.dao.orm.Session, 270 * BaseModel, boolean)} for an explanation. 271 * @param serviceContext the service context to perform the update in 272 * @return the model instance that was updated 273 * @throws SystemException if a system exception occurred 274 */ 275 public T update(T model, boolean merge, ServiceContext serviceContext) 276 throws SystemException; 277 278 }