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             * @throws SystemException if the primary key is <code>null</code>, or if a
115             *         system exception occurred
116             */
117            public T fetchByPrimaryKey(Serializable primaryKey);
118    
119            public Map<Serializable, T> fetchByPrimaryKeys(
120                    Set<Serializable> primaryKeys);
121    
122            /**
123             * Returns the model instance with the primary key or throws a {@link
124             * NoSuchModelException} if it could not be found.
125             *
126             * @param  primaryKey the primary key of the model instance
127             * @return the model instance
128             * @throws NoSuchModelException if an instance of this model with the
129             *         primary key could not be found
130             * @throws SystemException if the primary key is <code>null</code>, or if a
131             *         system exception occurred
132             */
133            public T findByPrimaryKey(Serializable primaryKey)
134                    throws NoSuchModelException;
135    
136            /**
137             * Performs a dynamic query on the database and returns the matching rows.
138             *
139             * @param  dynamicQuery the dynamic query
140             * @return the matching rows
141             */
142            public <V> List<V> findWithDynamicQuery(DynamicQuery dynamicQuery);
143    
144            /**
145             * Performs a dynamic query on the database and returns a range of the
146             * 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
159             * @param  start the lower bound of the range of matching rows
160             * @param  end the upper bound of the range of matching rows (not inclusive)
161             * @return the range of matching rows
162             * @see    com.liferay.portal.kernel.dao.orm.QueryUtil#list(
163             *         com.liferay.portal.kernel.dao.orm.Query,
164             *         com.liferay.portal.kernel.dao.orm.Dialect, int, int)
165             */
166            public <V> List<V> findWithDynamicQuery(
167                    DynamicQuery dynamicQuery, int start, int end);
168    
169            /**
170             * Performs a dynamic query on the database and returns an ordered range of
171             * the matching rows.
172             *
173             * <p>
174             * Useful when paginating results. Returns a maximum of <code>end -
175             * start</code> instances. <code>start</code> and <code>end</code> are not
176             * primary keys, they are indexes in the result set. Thus, <code>0</code>
177             * refers to the first result in the set. Setting both <code>start</code>
178             * and <code>end</code> to {@link
179             * com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS} will return the full
180             * result set.
181             * </p>
182             *
183             * @param  dynamicQuery the dynamic query
184             * @param  start the lower bound of the range of matching rows
185             * @param  end the upper bound of the range of matching rows (not inclusive)
186             * @param  orderByComparator the comparator to order the results by
187             *         (optionally <code>null</code>)
188             * @return the ordered range of matching rows
189             */
190            public <V> List<V> findWithDynamicQuery(
191                    DynamicQuery dynamicQuery, int start, int end,
192                    OrderByComparator<V> orderByComparator);
193    
194            public void flush();
195    
196            public Session getCurrentSession() throws ORMException;
197    
198            /**
199             * Returns the data source for this model.
200             *
201             * @return the data source for this model
202             * @see    #setDataSource(DataSource)
203             */
204            public DataSource getDataSource();
205    
206            /**
207             * Returns the listeners registered for this model.
208             *
209             * @return the listeners registered for this model
210             * @see    #registerListener(ModelListener)
211             */
212            public ModelListener<T>[] getListeners();
213    
214            public Class<T> getModelClass();
215    
216            public Session openSession() throws ORMException;
217    
218            public SystemException processException(Exception e);
219    
220            /**
221             * Registers a new listener for this model.
222             *
223             * <p>
224             * A model listener is notified whenever a change is made to an instance of
225             * this model, such as when one is added, updated, or removed.
226             * </p>
227             *
228             * @param listener the model listener to register
229             */
230            public void registerListener(ModelListener<T> listener);
231    
232            /**
233             * Removes the model instance with the primary key from the database. Also
234             * notifies the appropriate model listeners.
235             *
236             * @param  primaryKey the primary key of the model instance to remove
237             * @return the model instance that was removed
238             * @throws NoSuchModelException if an instance of this model with the
239             *         primary key could not be found
240             */
241            public T remove(Serializable primaryKey) throws NoSuchModelException;
242    
243            /**
244             * Removes the model instance from the database. Also notifies the
245             * appropriate model listeners.
246             *
247             * @param  model the model instance to remove
248             * @return the model instance that was removed
249             */
250            public T remove(T model);
251    
252            /**
253             * Sets the data source for this model.
254             *
255             * @param dataSource the data source to use for this model
256             */
257            public void setDataSource(DataSource dataSource);
258    
259            /**
260             * Unregisters the model listener.
261             *
262             * @param listener the model listener to unregister
263             * @see   #registerListener(ModelListener)
264             */
265            public void unregisterListener(ModelListener<T> listener);
266    
267            /**
268             * Updates the model instance in the database or adds it if it does not yet
269             * exist. Also notifies the appropriate model listeners.
270             *
271             * <p>
272             * Typically not called directly, use local service update model methods
273             * instead. For example, {@link
274             * com.liferay.portal.service.UserLocalServiceUtil#updateUser(
275             * com.liferay.portal.model.User)}.
276             * </p>
277             *
278             * @param  model the model instance to update
279             * @return the model instance that was updated
280             */
281            public T update(T model);
282    
283            /**
284             * @deprecated As of 6.2.0, replaced by {@link #update(BaseModel)}}
285             */
286            @Deprecated
287            public T update(T model, boolean merge);
288    
289            /**
290             * @deprecated As of 6.2.0, replaced by {@link #update(BaseModel,
291             *             ServiceContext)}}
292             */
293            @Deprecated
294            public T update(T model, boolean merge, ServiceContext serviceContext);
295    
296            /**
297             * Updates the model instance in the database or adds it if it does not yet
298             * exist, within a different service context. Also notifies the appropriate
299             * model listeners.
300             *
301             * @param  model the model instance to update
302             * @param  serviceContext the service context to be applied
303             * @return the model instance that was updated
304             */
305            public T update(T model, ServiceContext serviceContext);
306    
307    }