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 */ 115 public T fetchByPrimaryKey(Serializable primaryKey); 116 117 public Map<Serializable, T> fetchByPrimaryKeys( 118 Set<Serializable> primaryKeys); 119 120 /** 121 * Returns the model instance with the primary key or throws a {@link 122 * NoSuchModelException} if it could not be found. 123 * 124 * @param primaryKey the primary key of the model instance 125 * @return the model instance 126 * @throws NoSuchModelException if an instance of this model with the 127 * primary key could not be found 128 */ 129 public T findByPrimaryKey(Serializable primaryKey) 130 throws NoSuchModelException; 131 132 /** 133 * Performs a dynamic query on the database and returns the matching rows. 134 * 135 * @param dynamicQuery the dynamic query 136 * @return the matching rows 137 */ 138 public <V> List<V> findWithDynamicQuery(DynamicQuery dynamicQuery); 139 140 /** 141 * Performs a dynamic query on the database and returns a range of the 142 * matching rows. 143 * 144 * <p> 145 * Useful when paginating results. Returns a maximum of <code>end - 146 * start</code> instances. <code>start</code> and <code>end</code> are not 147 * primary keys, they are indexes in the result set. Thus, <code>0</code> 148 * refers to the first result in the set. Setting both <code>start</code> 149 * and <code>end</code> to {@link 150 * com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS} will return the full 151 * result set. 152 * </p> 153 * 154 * @param dynamicQuery the dynamic query 155 * @param start the lower bound of the range of matching rows 156 * @param end the upper bound of the range of matching rows (not inclusive) 157 * @return the range of matching rows 158 * @see com.liferay.portal.kernel.dao.orm.QueryUtil#list( 159 * com.liferay.portal.kernel.dao.orm.Query, 160 * com.liferay.portal.kernel.dao.orm.Dialect, int, int) 161 */ 162 public <V> List<V> findWithDynamicQuery( 163 DynamicQuery dynamicQuery, int start, int end); 164 165 /** 166 * Performs a dynamic query on the database and returns an ordered range of 167 * the matching rows. 168 * 169 * <p> 170 * Useful when paginating results. Returns a maximum of <code>end - 171 * start</code> instances. <code>start</code> and <code>end</code> are not 172 * primary keys, they are indexes in the result set. Thus, <code>0</code> 173 * refers to the first result in the set. Setting both <code>start</code> 174 * and <code>end</code> to {@link 175 * com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS} will return the full 176 * result set. 177 * </p> 178 * 179 * @param dynamicQuery the dynamic query 180 * @param start the lower bound of the range of matching rows 181 * @param end the upper bound of the range of matching rows (not inclusive) 182 * @param orderByComparator the comparator to order the results by 183 * (optionally <code>null</code>) 184 * @return the ordered range of matching rows 185 */ 186 public <V> List<V> findWithDynamicQuery( 187 DynamicQuery dynamicQuery, int start, int end, 188 OrderByComparator<V> orderByComparator); 189 190 public void flush(); 191 192 public Session getCurrentSession() throws ORMException; 193 194 /** 195 * Returns the data source for this model. 196 * 197 * @return the data source for this model 198 * @see #setDataSource(DataSource) 199 */ 200 public DataSource getDataSource(); 201 202 /** 203 * Returns the listeners registered for this model. 204 * 205 * @return the listeners registered for this model 206 * @see #registerListener(ModelListener) 207 */ 208 public ModelListener<T>[] getListeners(); 209 210 public Class<T> getModelClass(); 211 212 public Session openSession() throws ORMException; 213 214 public SystemException processException(Exception e); 215 216 /** 217 * Registers a new listener for this model. 218 * 219 * <p> 220 * A model listener is notified whenever a change is made to an instance of 221 * this model, such as when one is added, updated, or removed. 222 * </p> 223 * 224 * @param listener the model listener to register 225 */ 226 public void registerListener(ModelListener<T> listener); 227 228 /** 229 * Removes the model instance with the primary key from the database. Also 230 * notifies the appropriate model listeners. 231 * 232 * @param primaryKey the primary key of the model instance to remove 233 * @return the model instance that was removed 234 * @throws NoSuchModelException if an instance of this model with the 235 * primary key could not be found 236 */ 237 public T remove(Serializable primaryKey) throws NoSuchModelException; 238 239 /** 240 * Removes the model instance from the database. Also notifies the 241 * appropriate model listeners. 242 * 243 * @param model the model instance to remove 244 * @return the model instance that was removed 245 */ 246 public T remove(T model); 247 248 /** 249 * Sets the data source for this model. 250 * 251 * @param dataSource the data source to use for this model 252 */ 253 public void setDataSource(DataSource dataSource); 254 255 /** 256 * Unregisters the model listener. 257 * 258 * @param listener the model listener to unregister 259 * @see #registerListener(ModelListener) 260 */ 261 public void unregisterListener(ModelListener<T> listener); 262 263 /** 264 * Updates the model instance in the database or adds it if it does not yet 265 * exist. Also notifies the appropriate model listeners. 266 * 267 * <p> 268 * Typically not called directly, use local service update model methods 269 * instead. For example, {@link 270 * com.liferay.portal.service.UserLocalServiceUtil#updateUser( 271 * com.liferay.portal.model.User)}. 272 * </p> 273 * 274 * @param model the model instance to update 275 * @return the model instance that was updated 276 */ 277 public T update(T model); 278 279 /** 280 * @deprecated As of 6.2.0, replaced by {@link #update(BaseModel)}} 281 */ 282 @Deprecated 283 public T update(T model, boolean merge); 284 285 /** 286 * @deprecated As of 6.2.0, replaced by {@link #update(BaseModel, 287 * ServiceContext)}} 288 */ 289 @Deprecated 290 public T update(T model, boolean merge, ServiceContext serviceContext); 291 292 /** 293 * Updates the model instance in the database or adds it if it does not yet 294 * exist, within a different service context. Also notifies the appropriate 295 * model listeners. 296 * 297 * @param model the model instance to update 298 * @param serviceContext the service context to be applied 299 * @return the model instance that was updated 300 */ 301 public T update(T model, ServiceContext serviceContext); 302 303 }