1 package org.apache.onami.persist;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import javax.persistence.EntityManager;
23
24 /**
25 * The Unit of work correlates with the life cycle of the {@link EntityManager}.
26 * According to JPA every thread should use its own {@link EntityManager}. Therefore the unit of
27 * work will control the life cycle of the {@link EntityManager} on a per thread basis. This means
28 * the UnitOfWork is thread safe.
29 * <p/>
30 * Most of the time it is not recommended to manual control the unit of work.
31 * <p/>
32 * For applications running in a container the {@link PersistenceFilter} is recommended.
33 * It will start a unit of work for every incoming request and properly close it at the end.
34 * <p/>
35 * For stand alone application it is recommended to relay on the {@link Transactional @Transactional} annotation.
36 * The transaction handler will automatically span a unit of work around a transaction.
37 * <p/>
38 * The most likely scenario in which one would want to take manual control over the unit of work
39 * is in a background thread within a container (i.e. timer triggered jobs).
40 * <p/>
41 * Recommended pattern:
42 * <pre>
43 * public void someMethod() {
44 * final boolean unitOfWorkWasInactive = ! unitOfWork.isActive();
45 * if (unitOfWorkWasInactive) {
46 * unitOfWork.begin();
47 * }
48 * try {
49 * // do work
50 * }
51 * finally {
52 * if (unitOfWorkWasInactive) {
53 * unitOfWork.end();
54 * }
55 * }
56 * }
57 * </pre>
58 */
59 public interface UnitOfWork
60 {
61
62 /**
63 * Begins the unit of work.
64 * When a unit of work has already been started for the current thread an {@link IllegalStateException} is thrown.
65 *
66 * @throws IllegalStateException if a unit of work is already active for this thread.
67 */
68 void begin();
69
70 /**
71 * @return {@code true} if the unit of work is active for the current thread
72 * {@code false} otherwise.
73 */
74 boolean isActive();
75
76 /**
77 * Ends the unit of work.
78 * When the unit of work is not active this method will do nothing.
79 */
80 void end();
81
82 }