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.kernel.dao.orm.ORMException;
018    import com.liferay.portal.kernel.dao.orm.Session;
019    import com.liferay.portal.model.BaseModel;
020    
021    /**
022     * Tracks database updates and flushes them from the session in batches.
023     *
024     * <p>
025     * Although all database updates ultimately pass through this class, its
026     * batching functionality is only used for large sets of contiguous updates. For
027     * usage examples see {@link
028     * com.liferay.portal.service.impl.LayoutLocalServiceImpl#importLayouts(long,
029     * long, boolean, java.util.Map, java.io.File)}, and {@link
030     * com.liferay.portal.verify.VerifyProcessUtil#verifyProcess(boolean, boolean,
031     * boolean)}.
032     * </p>
033     *
034     * @author     Raymond Aug??
035     * @author     Brian Wing Shun Chan
036     * @deprecated As of 6.2.0, see LPS-30598.
037     */
038    @Deprecated
039    public interface BatchSession {
040    
041            /**
042             * Deletes the model instance in the database, and possibly flushes the
043             * session.
044             *
045             * <p>
046             * The session will be flushed if one of the following is <code>true</code>:
047             * </p>
048             *
049             * <ul>
050             * <li>
051             * Update batching is disabled
052             * </li>
053             * <li>
054             * The batch size is set to zero
055             * </li>
056             * <li>
057             * Enough updates and/or deletions have been queued to fill another batch
058             * </li>
059             * </ul>
060             *
061             * <p>
062             * The batch size may be set in portal.properties with the key
063             * <code>hibernate.jdbc.batch_size</code>.
064             * </p>
065             *
066             * @param session the session to perform the update on
067             * @param model the model instance to update
068             */
069            public void delete(Session session, BaseModel<?> model) throws ORMException;
070    
071            /**
072             * Returns <code>true</code> if update batching is enabled
073             *
074             * @return <code>true</code> if update batching is enabled;
075             *         <code>false</code> otherwise
076             */
077            public boolean isEnabled();
078    
079            /**
080             * Sets whether update batching is enabled.
081             *
082             * @param enabled whether update batching is enabled.
083             */
084            public void setEnabled(boolean enabled);
085    
086            /**
087             * Updates the model instance in the database or adds it if it does not yet
088             * exist, and possibly flushes the session.
089             *
090             * <p>
091             * The session will be flushed if one of the following is <code>true</code>:
092             * </p>
093             *
094             * <ul>
095             * <li>
096             * Update batching is disabled
097             * </li>
098             * <li>
099             * The batch size is set to zero
100             * </li>
101             * <li>
102             * Enough updates/or deletions have been queued to fill another batch
103             * </li>
104             * </ul>
105             *
106             * <p>
107             * The batch size may be set in portal.properties with the key
108             * <code>hibernate.jdbc.batch_size</code>.
109             * </p>
110             *
111             * <p>
112             * The <code>merge</code> parameter controls a special case of persistence.
113             * If the session that a model instance was originally loaded from is
114             * closed, that instance becomes &quot;detached&quot;, and changes to it
115             * will not be persisted automatically. To persist its changes, the detached
116             * instance must be merged with the current session. This will load a new
117             * copy of the model instance from the database, copy the changes to it, and
118             * persist it.
119             * </p>
120             *
121             * <p>
122             * This process is most commonly necessary if a model instance is modified
123             * in the controller or view, as the database session is closed when control
124             * leaves the model layer. However, local service update model methods use
125             * merging by default, so in most cases this nuance is handled
126             * automatically. See {@link
127             * com.liferay.portal.service.UserLocalService#updateUser(
128             * com.liferay.portal.model.User)} for an example.
129             * </p>
130             *
131             * @param session the session
132             * @param model the model instance
133             * @param merge whether to merge the model instance with the current session
134             */
135            public void update(Session session, BaseModel<?> model, boolean merge)
136                    throws ORMException;
137    
138    }