001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.lang3.concurrent; 018 019/** 020 * <p> 021 * This class provides a generic implementation of the lazy initialization 022 * pattern. 023 * </p> 024 * <p> 025 * Sometimes an application has to deal with an object only under certain 026 * circumstances, e.g. when the user selects a specific menu item or if a 027 * special event is received. If the creation of the object is costly or the 028 * consumption of memory or other system resources is significant, it may make 029 * sense to defer the creation of this object until it is really needed. This is 030 * a use case for the lazy initialization pattern. 031 * </p> 032 * <p> 033 * This abstract base class provides an implementation of the double-check idiom 034 * for an instance field as discussed in Joshua Bloch's "Effective Java", 2nd 035 * edition, item 71. The class already implements all necessary synchronization. 036 * A concrete subclass has to implement the {@code initialize()} method, which 037 * actually creates the wrapped data object. 038 * </p> 039 * <p> 040 * As an usage example consider that we have a class {@code ComplexObject} whose 041 * instantiation is a complex operation. In order to apply lazy initialization 042 * to this class, a subclass of {@code LazyInitializer} has to be created: 043 * </p> 044 * 045 * <pre> 046 * public class ComplexObjectInitializer extends LazyInitializer<ComplexObject> { 047 * @Override 048 * protected ComplexObject initialize() { 049 * return new ComplexObject(); 050 * } 051 * } 052 * </pre> 053 * 054 * <p> 055 * Access to the data object is provided through the {@code get()} method. So, 056 * code that wants to obtain the {@code ComplexObject} instance would simply 057 * look like this: 058 * </p> 059 * 060 * <pre> 061 * // Create an instance of the lazy initializer 062 * ComplexObjectInitializer initializer = new ComplexObjectInitializer(); 063 * ... 064 * // When the object is actually needed: 065 * ComplexObject cobj = initializer.get(); 066 * </pre> 067 * 068 * <p> 069 * If multiple threads call the {@code get()} method when the object has not yet 070 * been created, they are blocked until initialization completes. The algorithm 071 * guarantees that only a single instance of the wrapped object class is 072 * created, which is passed to all callers. Once initialized, calls to the 073 * {@code get()} method are pretty fast because no synchronization is needed 074 * (only an access to a <b>volatile</b> member field). 075 * </p> 076 * 077 * @since 3.0 078 * @version $Id: LazyInitializer.java 1583482 2014-03-31 22:54:57Z niallp $ 079 * @param <T> the type of the object managed by this initializer class 080 */ 081public abstract class LazyInitializer<T> implements ConcurrentInitializer<T> { 082 /** Stores the managed object. */ 083 private volatile T object; 084 085 /** 086 * Returns the object wrapped by this instance. On first access the object 087 * is created. After that it is cached and can be accessed pretty fast. 088 * 089 * @return the object initialized by this {@code LazyInitializer} 090 * @throws ConcurrentException if an error occurred during initialization of 091 * the object 092 */ 093 @Override 094 public T get() throws ConcurrentException { 095 // use a temporary variable to reduce the number of reads of the 096 // volatile field 097 T result = object; 098 099 if (result == null) { 100 synchronized (this) { 101 result = object; 102 if (result == null) { 103 object = result = initialize(); 104 } 105 } 106 } 107 108 return result; 109 } 110 111 /** 112 * Creates and initializes the object managed by this {@code 113 * LazyInitializer}. This method is called by {@link #get()} when the object 114 * is accessed for the first time. An implementation can focus on the 115 * creation of the object. No synchronization is needed, as this is already 116 * handled by {@code get()}. 117 * 118 * @return the managed data object 119 * @throws ConcurrentException if an error occurs during object creation 120 */ 121 protected abstract T initialize() throws ConcurrentException; 122}