KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > tc > util > concurrent > SetOnceRef


1 /**
2  * All content copyright (c) 2003-2006 Terracotta, Inc., except as may otherwise be noted in a separate copyright notice. All rights reserved.
3  */
4 package com.tc.util.concurrent;
5
6 /**
7  * An object reference holder class in which the reference can only be set once. This might be useful for a member
8  * variable that you'd like to make final, but that you aren't able to set within a constructor. I suppose this class is
9  * a lot like TCFuture, but this class doesn't offer methods to wait for a value to set. The use case for this class has
10  * nothing to do with communication/synchronization between threads. This class is meant to make sure you can't change a
11  * reference once it's been set (ie. it provides a reference member variable that behaves like it was marked "final" and
12  * won't let anyone read it until it has been set)
13  *
14  * @author teck
15  */
16 public final class SetOnceRef {
17   private Object JavaDoc ref;
18   private boolean set;
19   private final Object JavaDoc lock = new Object JavaDoc();
20   private final boolean allowsNullValue;
21
22   /**
23    * Create a new <code>set()</code> 'able instance This instance <b>will not </b> permitted to contain a null
24    * reference
25    */
26   public SetOnceRef() {
27     this(null, false, false);
28   }
29
30   /**
31    * Create and immediately <code>set()</code> to the given reference. This instance <b>will not </b> permitted to
32    * contain a null reference
33    *
34    * @param ref The reference to hold
35    * @throws IllegalArgumentException If the reference to hold is null
36    */
37   public SetOnceRef(Object JavaDoc ref) {
38     this(ref, false, true);
39   }
40
41   /**
42    * Create and immediately <code>set()</code> to the given refernce
43    *
44    * @param ref the reference to hold
45    * @param allowNull true to allow nulls to be stored in this instance
46    * @throws IllegalArgumentException if allowNull is true and the given reference is null
47    */
48   public SetOnceRef(Object JavaDoc ref, boolean allowNull) {
49     this(ref, allowNull, true);
50   }
51
52   /**
53    * Create a new <code>set()</code> 'able instance
54    *
55    * @param allowNull true to allow this instance to hold the value null
56    */
57   public SetOnceRef(boolean allowNull) {
58     this(null, allowNull, false);
59   }
60
61   private SetOnceRef(final Object JavaDoc ref, final boolean allowNull, final boolean init) {
62     this.allowsNullValue = allowNull;
63
64     if (init) {
65       set(ref);
66     }
67   }
68
69   /**
70    * Can null ever be the value of this reference
71    *
72    * @return true if null is allowed, false otherwise
73    */
74   public boolean allowsNull() {
75     return this.allowsNullValue;
76   }
77
78   /**
79    * Attmept to set the reference to the given value
80    *
81    * @param ref the reference to set in this instance
82    * @throws IllegalStateException if the reference has already been set by another thread
83    * @throws IllegalArgumentException if the given reference is null and this instance does not allow the null value
84    */
85   public void set(final Object JavaDoc ref) {
86     synchronized (lock) {
87       if (set) { throw new IllegalStateException JavaDoc("Reference has already been set"); }
88
89       if ((!allowsNull()) && (ref == null)) { throw new IllegalArgumentException JavaDoc(
90                                                                                  "This instance cannot hold a null reference value"); }
91
92       set = true;
93       this.ref = ref;
94     }
95   }
96
97   /**
98    * Get the reference value contained in this instance
99    *
100    * @return the reference, may be null if this instance allow nulls (see <code>allowNull</code>
101    * @throws IllegalStateException if a valid reference value has not yet been set
102    */
103   public Object JavaDoc get() {
104     synchronized (lock) {
105       if (!set) { throw new IllegalStateException JavaDoc("Reference has not been set"); }
106
107       return ref;
108     }
109   }
110
111   /**
112    * Has someone set the reference yet
113    *
114    * @return true iff the reference has been set
115    */
116   public boolean isSet() {
117     synchronized (lock) {
118       return set;
119     }
120   }
121 }
Popular Tags