001    /**
002     * Copyright (c) 2000-2010 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)}, {@link
030     * com.liferay.portal.verify.VerifyProcessUtil#verifyProcess(boolean, boolean)}
031     * , and {@link
032     * com.liferay.portal.convert.ConvertPermissionAlgorithm#doConvert()}.
033     * </p>
034     *
035     * @author Raymond Augé
036     * @author Brian Wing Shun Chan
037     */
038    public interface BatchSession {
039    
040            /**
041             * Determines if update batching is enabled
042             *
043             * @return <code>true</code> if update batching is enabled;
044             *                 <code>false</code> otherwise
045             */
046            public boolean isEnabled();
047    
048            /**
049             * Sets whether update batching is enabled.
050             *
051             * @param enabled whether update batching is enabled.
052             */
053            public void setEnabled(boolean enabled);
054    
055            /**
056             * Updates the model instance in the database or adds it if it does not yet
057             * exist, and possibly flushes the session.
058             *
059             * <p>
060             * The session will be flushed if one of the following is <code>true</code>:
061             * </p>
062             *
063             * <ul>
064             * <li>
065             * Update batching is disabled
066             * </li>
067             * <li>
068             * The batch size is set to zero
069             * </li>
070             * <li>
071             * Enough updates have been queued to fill another batch
072             * </li>
073             * </ul>
074             *
075             * <p>
076             * The batch size may be set in portal.properties with the key
077             * <code>hibernate.jdbc.batch_size</code>.
078             * </p>
079             *
080             * <p>
081             * The <code>merge</code> parameter controls a special case of persistence.
082             * If the session that a model instance was originally loaded from is
083             * closed, that instance becomes &quot;detached&quot;, and changes to it
084             * will not be persisted automatically. To persist its changes, the detached
085             * instance must be merged with the current session. This will load a new
086             * copy of the model instance from the database, copy the changes to it, and
087             * persist it.
088             * </p>
089             *
090             * <p>
091             * This process is most commonly necessary if a model instance is modified
092             * in the controller or view, as the database session is closed when control
093             * leaves the model layer. However, local service update model methods use
094             * merging by default, so in most cases this nuance is handled
095             * automatically. See {@link
096             * com.liferay.portal.service.UserLocalService#updateUser(
097             * com.liferay.portal.model.User)} for an example.
098             * </p>
099             *
100             * @param  session the session to perform the update on
101             * @param  model the model instance to update
102             * @param  merge whether to merge the model instance with the current
103             *                 session
104             * @throws ORMException if a database exception occurred
105             */
106            public void update(Session session, BaseModel<?> model, boolean merge)
107                    throws ORMException;
108    
109    }