KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > core > commands > common > HandleObject


1 /*******************************************************************************
2  * Copyright (c) 2004, 2006 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package org.eclipse.core.commands.common;
12
13 import org.eclipse.core.internal.commands.util.Util;
14
15 /**
16  * <p>
17  * An object that can exist in one of two states: defined and undefined. This is
18  * used by APIs that want to give a handle to an object, even though the object
19  * does not fully exist yet. This way, users can attach listeners to objects
20  * before they come into existence. It also protects the API from users that do
21  * not release references when they should.
22  * </p>
23  * <p>
24  * To enforce good coding practice, all handle objects must implement
25  * <code>equals</code> and <code>toString</code>. Please use
26  * <code>string</code> to cache the result for <code>toString</code> once
27  * calculated.
28  * </p>
29  * <p>
30  * All handle objects are referred to using a single identifier. This identifier
31  * is a instance of <code>String</code>. It is important that this identifier
32  * remain unique within whatever context that handle object is being used. For
33  * example, there should only ever be one instance of <code>Command</code>
34  * with a given identifier.
35  * </p>
36  *
37  * @since 3.1
38  */
39 public abstract class HandleObject extends EventManager implements
40         IIdentifiable {
41
42     /**
43      * The constant integer hash code value meaning the hash code has not yet
44      * been computed.
45      */
46     private static final int HASH_CODE_NOT_COMPUTED = -1;
47     
48     /**
49      * A factor for computing the hash code for all schemes.
50      */
51     private static final int HASH_FACTOR = 89;
52
53     /**
54      * The seed for the hash code for all schemes.
55      */
56     private static final int HASH_INITIAL = HandleObject.class.getName()
57             .hashCode();
58
59     /**
60      * Whether this object is defined. A defined object is one that has been
61      * fully initialized. By default, all objects start as undefined.
62      */
63     protected transient boolean defined = false;
64
65     /**
66      * The hash code for this object. This value is computed lazily, and marked
67      * as invalid when one of the values on which it is based changes.
68      */
69     private transient int hashCode = HASH_CODE_NOT_COMPUTED;
70
71     /**
72      * The identifier for this object. This identifier should be unique across
73      * all objects of the same type and should never change. This value will
74      * never be <code>null</code>.
75      */
76     protected final String JavaDoc id;
77
78     /**
79      * The string representation of this object. This string is for debugging
80      * purposes only, and is not meant to be displayed to the user. This value
81      * is computed lazily, and is cleared if one of its dependent values
82      * changes.
83      */
84     protected transient String JavaDoc string = null;
85
86     /**
87      * Constructs a new instance of <code>HandleObject</code>.
88      *
89      * @param id
90      * The id of this handle; must not be <code>null</code>.
91      */
92     protected HandleObject(final String JavaDoc id) {
93         if (id == null) {
94             throw new NullPointerException JavaDoc(
95                     "Cannot create a handle with a null id"); //$NON-NLS-1$
96 }
97
98         this.id = id;
99     }
100
101     /**
102      * Tests whether this object is equal to another object. A handle object is
103      * only equal to another handle object with the same id and the same class.
104      *
105      * @param object
106      * The object with which to compare; may be <code>null</code>.
107      * @return <code>true</code> if the objects are equal; <code>false</code>
108      * otherwise.
109      */
110     public boolean equals(final Object JavaDoc object) {
111         // Check if they're the same.
112 if (object == this) {
113             return true;
114         }
115
116         // Check if they're the same type.
117 if (!(object instanceof HandleObject)) {
118             return false;
119         }
120
121         // Check each property in turn.
122 final HandleObject handle= (HandleObject) object;
123         return Util.equals(id, handle.id)
124                 && (this.getClass() == handle.getClass());
125     }
126     
127     public final String JavaDoc getId() {
128         return id;
129     }
130
131     /**
132      * Computes the hash code for this object based on the id.
133      *
134      * @return The hash code for this object.
135      */
136     public final int hashCode() {
137         if (hashCode == HASH_CODE_NOT_COMPUTED) {
138             hashCode = HASH_INITIAL * HASH_FACTOR + Util.hashCode(id);
139             if (hashCode == HASH_CODE_NOT_COMPUTED) {
140                 hashCode++;
141             }
142         }
143         return hashCode;
144     }
145
146     /**
147      * Whether this instance is defined. A defined instance is one that has been
148      * fully initialized. This allows objects to effectively disappear even
149      * though other objects may still have references to them.
150      *
151      * @return <code>true</code> if this object is defined; <code>false</code>
152      * otherwise.
153      */
154     public final boolean isDefined() {
155         return defined;
156     }
157
158     /**
159      * The string representation of this object -- for debugging purposes only.
160      * This string should not be shown to an end user.
161      *
162      * @return The string representation; never <code>null</code>.
163      */
164     public abstract String JavaDoc toString();
165
166     /**
167      * Makes this object becomes undefined. This method should make any defined
168      * properties <code>null</code>. It should also send notification to any
169      * listeners that these properties have changed.
170      */
171     public abstract void undefine();
172 }
173
Popular Tags