001 /** 002 * Copyright (c) 2000-2013 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 * Deletes the model instance in the database, and possibly flushes the 042 * session. 043 * 044 * <p> 045 * The session will be flushed if one of the following is <code>true</code>: 046 * </p> 047 * 048 * <ul> 049 * <li> 050 * Update batching is disabled 051 * </li> 052 * <li> 053 * The batch size is set to zero 054 * </li> 055 * <li> 056 * Enough updates and/or deletions have been queued to fill another batch 057 * </li> 058 * </ul> 059 * 060 * <p> 061 * The batch size may be set in portal.properties with the key 062 * <code>hibernate.jdbc.batch_size</code>. 063 * </p> 064 * 065 * @param session the session to perform the update on 066 * @param model the model instance to update 067 * @throws ORMException if a database exception occurred 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 "detached", 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 134 * session 135 * @throws ORMException if a database exception occurred 136 */ 137 public void update(Session session, BaseModel<?> model, boolean merge) 138 throws ORMException; 139 140 }