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