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 Set<String> getBadColumnNames(); 193 194 public Session getCurrentSession() throws ORMException; 195 196 /** 197 * Returns the data source for this model. 198 * 199 * @return the data source for this model 200 * @see #setDataSource(DataSource) 201 */ 202 public DataSource getDataSource(); 203 204 /** 205 * Returns the listeners registered for this model. 206 * 207 * @return the listeners registered for this model 208 * @see #registerListener(ModelListener) 209 */ 210 public ModelListener<T>[] getListeners(); 211 212 public Class<T> getModelClass(); 213 214 public Session openSession() throws ORMException; 215 216 public SystemException processException(Exception e); 217 218 /** 219 * Registers a new listener for this model. 220 * 221 * <p> 222 * A model listener is notified whenever a change is made to an instance of 223 * this model, such as when one is added, updated, or removed. 224 * </p> 225 * 226 * @param listener the model listener to register 227 */ 228 public void registerListener(ModelListener<T> listener); 229 230 /** 231 * Removes the model instance with the primary key from the database. Also 232 * notifies the appropriate model listeners. 233 * 234 * @param primaryKey the primary key of the model instance to remove 235 * @return the model instance that was removed 236 * @throws NoSuchModelException if an instance of this model with the 237 * primary key could not be found 238 */ 239 public T remove(Serializable primaryKey) throws NoSuchModelException; 240 241 /** 242 * Removes the model instance from the database. Also notifies the 243 * appropriate model listeners. 244 * 245 * @param model the model instance to remove 246 * @return the model instance that was removed 247 */ 248 public T remove(T model); 249 250 /** 251 * Sets the data source for this model. 252 * 253 * @param dataSource the data source to use for this model 254 */ 255 public void setDataSource(DataSource dataSource); 256 257 /** 258 * Unregisters the model listener. 259 * 260 * @param listener the model listener to unregister 261 * @see #registerListener(ModelListener) 262 */ 263 public void unregisterListener(ModelListener<T> listener); 264 265 /** 266 * Updates the model instance in the database or adds it if it does not yet 267 * exist. Also notifies the appropriate model listeners. 268 * 269 * <p> 270 * Typically not called directly, use local service update model methods 271 * instead. For example, {@link 272 * com.liferay.portal.service.UserLocalServiceUtil#updateUser( 273 * com.liferay.portal.model.User)}. 274 * </p> 275 * 276 * @param model the model instance to update 277 * @return the model instance that was updated 278 */ 279 public T update(T model); 280 281 /** 282 * @deprecated As of 6.2.0, replaced by {@link #update(BaseModel)}} 283 */ 284 @Deprecated 285 public T update(T model, boolean merge); 286 287 /** 288 * @deprecated As of 6.2.0, replaced by {@link #update(BaseModel, 289 * ServiceContext)}} 290 */ 291 @Deprecated 292 public T update(T model, boolean merge, ServiceContext serviceContext); 293 294 /** 295 * Updates the model instance in the database or adds it if it does not yet 296 * exist, within a different service context. Also notifies the appropriate 297 * model listeners. 298 * 299 * @param model the model instance to update 300 * @param serviceContext the service context to be applied 301 * @return the model instance that was updated 302 */ 303 public T update(T model, ServiceContext serviceContext); 304 305 }