1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.lang3.concurrent;
18
19 import java.util.concurrent.atomic.AtomicReference;
20
21 /**
22 * <p>
23 * A specialized {@code ConcurrentInitializer} implementation which is similar
24 * to {@link AtomicInitializer}, but ensures that the {@link #initialize()}
25 * method is called only once.
26 * </p>
27 * <p>
28 * As {@link AtomicInitializer} this class is based on atomic variables, so it
29 * can create an object under concurrent access without synchronization.
30 * However, it implements an additional check to guarantee that the
31 * {@link #initialize()} method which actually creates the object cannot be
32 * called multiple times.
33 * </p>
34 * <p>
35 * Because of this additional check this implementation is slightly less
36 * efficient than {@link AtomicInitializer}, but if the object creation in the
37 * {@code initialize()} method is expensive or if multiple invocations of
38 * {@code initialize()} are problematic, it is the better alternative.
39 * </p>
40 * <p>
41 * From its semantics this class has the same properties as
42 * {@link LazyInitializer}. It is a "save" implementation of the lazy
43 * initializer pattern. Comparing both classes in terms of efficiency is
44 * difficult because which one is faster depends on multiple factors. Because
45 * {@code AtomicSafeInitializer} does not use synchronization at all it probably
46 * outruns {@link LazyInitializer}, at least under low or moderate concurrent
47 * access. Developers should run their own benchmarks on the expected target
48 * platform to decide which implementation is suitable for their specific use
49 * case.
50 * </p>
51 *
52 * @since 3.0
53 * @version $Id: AtomicSafeInitializer.java 1309977 2012-04-05 17:53:39Z ggregory $
54 * @param <T> the type of the object managed by this initializer class
55 */
56 public abstract class AtomicSafeInitializer<T> implements
57 ConcurrentInitializer<T> {
58 /** A guard which ensures that initialize() is called only once. */
59 private final AtomicReference<AtomicSafeInitializer<T>> factory =
60 new AtomicReference<AtomicSafeInitializer<T>>();
61
62 /** Holds the reference to the managed object. */
63 private final AtomicReference<T> reference = new AtomicReference<T>();
64
65 /**
66 * Get (and initialize, if not initialized yet) the required object
67 *
68 * @return lazily initialized object
69 * @throws ConcurrentException if the initialization of the object causes an
70 * exception
71 */
72 @Override
73 public final T get() throws ConcurrentException {
74 T result;
75
76 while ((result = reference.get()) == null) {
77 if (factory.compareAndSet(null, this)) {
78 reference.set(initialize());
79 }
80 }
81
82 return result;
83 }
84
85 /**
86 * Creates and initializes the object managed by this
87 * {@code AtomicInitializer}. This method is called by {@link #get()} when
88 * the managed object is not available yet. An implementation can focus on
89 * the creation of the object. No synchronization is needed, as this is
90 * already handled by {@code get()}. This method is guaranteed to be called
91 * only once.
92 *
93 * @return the managed data object
94 * @throws ConcurrentException if an error occurs during object creation
95 */
96 protected abstract T initialize() throws ConcurrentException;
97 }