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