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 Set<String> getBadColumnNames();
193    
194            public Session getCurrentSession() throws ORMException;
195    
196            /**
197             * Returns the data source for this model.
198             *
199             * @return the data source for this model
200             * @see    #setDataSource(DataSource)
201             */
202            public DataSource getDataSource();
203    
204            /**
205             * Returns the listeners registered for this model.
206             *
207             * @return the listeners registered for this model
208             * @see    #registerListener(ModelListener)
209             */
210            public ModelListener<T>[] getListeners();
211    
212            public Class<T> getModelClass();
213    
214            public Session openSession() throws ORMException;
215    
216            public SystemException processException(Exception e);
217    
218            /**
219             * Registers a new listener for this model.
220             *
221             * <p>
222             * A model listener is notified whenever a change is made to an instance of
223             * this model, such as when one is added, updated, or removed.
224             * </p>
225             *
226             * @param listener the model listener to register
227             */
228            public void registerListener(ModelListener<T> listener);
229    
230            /**
231             * Removes the model instance with the primary key from the database. Also
232             * notifies the appropriate model listeners.
233             *
234             * @param  primaryKey the primary key of the model instance to remove
235             * @return the model instance that was removed
236             * @throws NoSuchModelException if an instance of this model with the
237             *         primary key could not be found
238             */
239            public T remove(Serializable primaryKey) throws NoSuchModelException;
240    
241            /**
242             * Removes the model instance from the database. Also notifies the
243             * appropriate model listeners.
244             *
245             * @param  model the model instance to remove
246             * @return the model instance that was removed
247             */
248            public T remove(T model);
249    
250            /**
251             * Sets the data source for this model.
252             *
253             * @param dataSource the data source to use for this model
254             */
255            public void setDataSource(DataSource dataSource);
256    
257            /**
258             * Unregisters the model listener.
259             *
260             * @param listener the model listener to unregister
261             * @see   #registerListener(ModelListener)
262             */
263            public void unregisterListener(ModelListener<T> listener);
264    
265            /**
266             * Updates the model instance in the database or adds it if it does not yet
267             * exist. Also notifies the appropriate model listeners.
268             *
269             * <p>
270             * Typically not called directly, use local service update model methods
271             * instead. For example, {@link
272             * com.liferay.portal.service.UserLocalServiceUtil#updateUser(
273             * com.liferay.portal.model.User)}.
274             * </p>
275             *
276             * @param  model the model instance to update
277             * @return the model instance that was updated
278             */
279            public T update(T model);
280    
281            /**
282             * @deprecated As of 6.2.0, replaced by {@link #update(BaseModel)}}
283             */
284            @Deprecated
285            public T update(T model, boolean merge);
286    
287            /**
288             * @deprecated As of 6.2.0, replaced by {@link #update(BaseModel,
289             *             ServiceContext)}}
290             */
291            @Deprecated
292            public T update(T model, boolean merge, ServiceContext serviceContext);
293    
294            /**
295             * Updates the model instance in the database or adds it if it does not yet
296             * exist, within a different service context. Also notifies the appropriate
297             * model listeners.
298             *
299             * @param  model the model instance to update
300             * @param  serviceContext the service context to be applied
301             * @return the model instance that was updated
302             */
303            public T update(T model, ServiceContext serviceContext);
304    
305    }