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    }