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