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 "detached", 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 }