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.exception.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             */
127            public T findByPrimaryKey(Serializable primaryKey)
128                    throws NoSuchModelException;
129    
130            /**
131             * Performs a dynamic query on the database and returns the matching rows.
132             *
133             * @param  dynamicQuery the dynamic query
134             * @return the matching rows
135             */
136            public <V> List<V> findWithDynamicQuery(DynamicQuery dynamicQuery);
137    
138            /**
139             * Performs a dynamic query on the database and returns a range of the
140             * matching rows.
141             *
142             * <p>
143             * Useful when paginating results. Returns a maximum of <code>end -
144             * start</code> instances. <code>start</code> and <code>end</code> are not
145             * primary keys, they are indexes in the result set. Thus, <code>0</code>
146             * refers to the first result in the set. Setting both <code>start</code>
147             * and <code>end</code> to {@link
148             * com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS} will return the full
149             * result set.
150             * </p>
151             *
152             * @param  dynamicQuery the dynamic query
153             * @param  start the lower bound of the range of matching rows
154             * @param  end the upper bound of the range of matching rows (not inclusive)
155             * @return the range of matching rows
156             * @see    com.liferay.portal.kernel.dao.orm.QueryUtil#list(
157             *         com.liferay.portal.kernel.dao.orm.Query,
158             *         com.liferay.portal.kernel.dao.orm.Dialect, int, int)
159             */
160            public <V> List<V> findWithDynamicQuery(
161                    DynamicQuery dynamicQuery, int start, int end);
162    
163            /**
164             * Performs a dynamic query on the database and returns an ordered range of
165             * the matching rows.
166             *
167             * <p>
168             * Useful when paginating results. Returns a maximum of <code>end -
169             * start</code> instances. <code>start</code> and <code>end</code> are not
170             * primary keys, they are indexes in the result set. Thus, <code>0</code>
171             * refers to the first result in the set. Setting both <code>start</code>
172             * and <code>end</code> to {@link
173             * com.liferay.portal.kernel.dao.orm.QueryUtil#ALL_POS} will return the full
174             * result set.
175             * </p>
176             *
177             * @param  dynamicQuery the dynamic query
178             * @param  start the lower bound of the range of matching rows
179             * @param  end the upper bound of the range of matching rows (not inclusive)
180             * @param  orderByComparator the comparator to order the results by
181             *         (optionally <code>null</code>)
182             * @return the ordered range of matching rows
183             */
184            public <V> List<V> findWithDynamicQuery(
185                    DynamicQuery dynamicQuery, int start, int end,
186                    OrderByComparator<V> orderByComparator);
187    
188            public void flush();
189    
190            public Set<String> getBadColumnNames();
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             */
235            public T remove(Serializable primaryKey) throws NoSuchModelException;
236    
237            /**
238             * Removes the model instance from the database. Also notifies the
239             * appropriate model listeners.
240             *
241             * @param  model the model instance to remove
242             * @return the model instance that was removed
243             */
244            public T remove(T model);
245    
246            /**
247             * Sets the data source for this model.
248             *
249             * @param dataSource the data source to use for this model
250             */
251            public void setDataSource(DataSource dataSource);
252    
253            /**
254             * Unregisters the model listener.
255             *
256             * @param listener the model listener to unregister
257             * @see   #registerListener(ModelListener)
258             */
259            public void unregisterListener(ModelListener<T> listener);
260    
261            /**
262             * Updates the model instance in the database or adds it if it does not yet
263             * exist. Also notifies the appropriate model listeners.
264             *
265             * <p>
266             * Typically not called directly, use local service update model methods
267             * instead. For example, {@link
268             * com.liferay.portal.service.UserLocalServiceUtil#updateUser(
269             * com.liferay.portal.model.User)}.
270             * </p>
271             *
272             * @param  model the model instance to update
273             * @return the model instance that was updated
274             */
275            public T update(T model);
276    
277            /**
278             * @deprecated As of 6.2.0, replaced by {@link #update(BaseModel)}}
279             */
280            @Deprecated
281            public T update(T model, boolean merge);
282    
283            /**
284             * @deprecated As of 6.2.0, replaced by {@link #update(BaseModel,
285             *             ServiceContext)}}
286             */
287            @Deprecated
288            public T update(T model, boolean merge, ServiceContext serviceContext);
289    
290            /**
291             * Updates the model instance in the database or adds it if it does not yet
292             * exist, within a different service context. Also notifies the appropriate
293             * model listeners.
294             *
295             * @param  model the model instance to update
296             * @param  serviceContext the service context to be applied
297             * @return the model instance that was updated
298             */
299            public T update(T model, ServiceContext serviceContext);
300    
301    }