View Javadoc
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 &quot;save&quot; 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  }