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