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