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    }