AtomicSafeInitializer (Apache Commons Lang 3.17.0 API)
Description: declaration: package: org.apache.commons.lang3.concurrent, class: AtomicSafeInitializer

Package org.apache.commons.lang3.concurrent

# Class AtomicSafeInitializer<T>

java.lang.Object
org.apache.commons.lang3.concurrent.AbstractConcurrentInitializer<T,ConcurrentException>
org.apache.commons.lang3.concurrent.AtomicSafeInitializer<T>

Type Parameters:
  `T` - the type of the object managed by this initializer class

All Implemented Interfaces:
  `ConcurrentInitializer<T>`, `FailableSupplier<T,ConcurrentException>`

public class AtomicSafeInitializer<T> extends AbstractConcurrentInitializer<T,ConcurrentException>
A specialized `ConcurrentInitializer` implementation which is similar to `AtomicInitializer`, but ensures that the `AbstractConcurrentInitializer.initialize()` method is called only once.

As `AtomicInitializer` this class is based on atomic variables, so it can create an object under concurrent access without synchronization. However, it implements an additional check to guarantee that the `AbstractConcurrentInitializer.initialize()` method which actually creates the object cannot be called multiple times.

Because of this additional check this implementation is slightly less efficient than `AtomicInitializer`, but if the object creation in the `initialize()` method is expensive or if multiple invocations of `initialize()` are problematic, it is the better alternative.

From its semantics this class has the same properties as `LazyInitializer`. It is a "save" implementation of the lazy initializer pattern. Comparing both classes in terms of efficiency is difficult because which one is faster depends on multiple factors. Because `AtomicSafeInitializer` does not use synchronization at all it probably outruns `LazyInitializer`, at least under low or moderate concurrent access. Developers should run their own benchmarks on the expected target platform to decide which implementation is suitable for their specific use case.

Since:
  3.0

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `AtomicSafeInitializer.Builder<I extends AtomicSafeInitializer<T>,T>`
  Builds a new instance.

  ## Nested classes/interfaces inherited from class org.apache.commons.lang3.concurrent.AbstractConcurrentInitializer

  `AbstractConcurrentInitializer.AbstractBuilder<I extends AbstractConcurrentInitializer<T,E>,T,B extends AbstractConcurrentInitializer.AbstractBuilder<I,T,B,E>,E extends Exception>`

- ## Field Summary

  ### Fields inherited from interface org.apache.commons.lang3.function.FailableSupplier

  `NUL`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AtomicSafeInitializer()`
  Constructs a new instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <T> AtomicSafeInitializer.Builder<AtomicSafeInitializer<T>,T>`
  `builder()`
  Creates a new builder.
  `final T`
  `get()`
  Gets (and initialize, if not initialized yet) the required object
  `protected ConcurrentException`
  `getTypedException(Exception e)`
  Gets an Exception with a type of E as defined by a concrete subclass of this class.
  `boolean`
  `isInitialized()`
  Tests whether this instance is initialized.

  ### Methods inherited from class org.apache.commons.lang3.concurrent.AbstractConcurrentInitializer

  `close, initialize`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### AtomicSafeInitializer

    public AtomicSafeInitializer()
    Constructs a new instance.

- ## Method Details

  - ### builder

    public static <T> AtomicSafeInitializer.Builder<AtomicSafeInitializer<T>,T> builder()
    Creates a new builder.
    Type Parameters:
      `T` - the type of object to build.
    Returns:
      a new builder.
    Since:
      3.14.0

  - ### get

    public final T get() throws ConcurrentException
    Gets (and initialize, if not initialized yet) the required object
    Returns:
      lazily initialized object
    Throws:
      `ConcurrentException` - if the initialization of the object causes an exception

  - ### getTypedException

    protected ConcurrentException getTypedException(Exception e)
    Gets an Exception with a type of E as defined by a concrete subclass of this class.
    Specified by:
      `getTypedException` in class `AbstractConcurrentInitializer<T,ConcurrentException>`
    Parameters:
      `e` - The actual exception that was thrown
    Returns:
      a new exception with the actual type of E, that wraps e.

  - ### isInitialized

    public boolean isInitialized()
    Tests whether this instance is initialized. Once initialized, always returns true.
    Specified by:
      `isInitialized` in class `AbstractConcurrentInitializer<T,ConcurrentException>`
    Returns:
      whether this instance is initialized. Once initialized, always returns true.
    Since:
      3.14.0