1 /** 2 * Copyright (C) 2010 Google, Inc. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.google.inject.persist; 18 19 /** 20 * This interface is used to gain manual control over the unit of work. This is mostly to do 21 * work in non-request, non-transactional threads. Or where more fine-grained control over the unit 22 * of work is required. Starting and ending a unit of work directly corresponds to opening and 23 * closing a {@code Session}, {@code EntityManager} or {@code ObjectContainer} respectively. 24 * <p> The 25 * Unit of Work referred to by UnitOfWork will always be local to the calling thread. Be careful to 26 * end() in a finally block. Neither JPA, nor Hibernate supports threadsafe sessions (reasoning 27 * behind thread-locality of Unit of Work semantics). 28 * 29 * <ul> 30 * <li>Using UnitOfWork with the PersistFilter inside a request is not recommended.</li> 31 * <li>Using UnitOfWork with session-per-txn strategy is not terribly clever either.</li> 32 * <li>Using UnitOfWork with session-per-request strategy but *outside* a request (i.e. in a 33 * background or bootstrap thread) is probably a good use case.</li> 34 * </ul> 35 * 36 * @author Dhanji R. Prasanna (dhanji@gmail com) 37 */ 38 public interface UnitOfWork { 39 40 /** 41 * Starts a Unit Of Work. Underneath, causes a session to the data layer to be opened. If there 42 * is already one open, the invocation will do nothing. In this way, you can define arbitrary 43 * units-of-work that nest within one another safely. 44 * 45 * Transaction semantics are not affected. 46 */ begin()47 void begin(); 48 49 /** 50 * Declares an end to the current Unit of Work. Underneath, causes any open session to the data 51 * layer to close. If there is no Unit of work open, then the call returns silently. You can 52 * safely invoke end() repeatedly. 53 * <p> 54 * Transaction semantics are not affected. 55 */ end()56 void end(); 57 } 58