| /******************************************************************************* |
| * Copyright (c) 2004, 2006 IBM Corporation and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| *******************************************************************************/ |
| package org.eclipse.core.commands.common; |
| |
| import org.eclipse.core.internal.commands.util.Util; |
| |
| /** |
| * <p> |
| * An object that can exist in one of two states: defined and undefined. This is |
| * used by APIs that want to give a handle to an object, even though the object |
| * does not fully exist yet. This way, users can attach listeners to objects |
| * before they come into existence. It also protects the API from users that do |
| * not release references when they should. |
| * </p> |
| * <p> |
| * To enforce good coding practice, all handle objects must implement |
| * <code>equals</code> and <code>toString</code>. Please use |
| * <code>string</code> to cache the result for <code>toString</code> once |
| * calculated. |
| * </p> |
| * <p> |
| * All handle objects are referred to using a single identifier. This identifier |
| * is a instance of <code>String</code>. It is important that this identifier |
| * remain unique within whatever context that handle object is being used. For |
| * example, there should only ever be one instance of <code>Command</code> |
| * with a given identifier. |
| * </p> |
| * |
| * @since 3.1 |
| */ |
| public abstract class HandleObject extends EventManager implements |
| IIdentifiable { |
| |
| /** |
| * The constant integer hash code value meaning the hash code has not yet |
| * been computed. |
| */ |
| private static final int HASH_CODE_NOT_COMPUTED = -1; |
| |
| /** |
| * A factor for computing the hash code for all schemes. |
| */ |
| private static final int HASH_FACTOR = 89; |
| |
| /** |
| * The seed for the hash code for all schemes. |
| */ |
| private static final int HASH_INITIAL = HandleObject.class.getName() |
| .hashCode(); |
| |
| /** |
| * Whether this object is defined. A defined object is one that has been |
| * fully initialized. By default, all objects start as undefined. |
| */ |
| protected transient boolean defined = false; |
| |
| /** |
| * The hash code for this object. This value is computed lazily, and marked |
| * as invalid when one of the values on which it is based changes. |
| */ |
| private transient int hashCode = HASH_CODE_NOT_COMPUTED; |
| |
| /** |
| * The identifier for this object. This identifier should be unique across |
| * all objects of the same type and should never change. This value will |
| * never be <code>null</code>. |
| */ |
| protected final String id; |
| |
| /** |
| * The string representation of this object. This string is for debugging |
| * purposes only, and is not meant to be displayed to the user. This value |
| * is computed lazily, and is cleared if one of its dependent values |
| * changes. |
| */ |
| protected transient String string = null; |
| |
| /** |
| * Constructs a new instance of <code>HandleObject</code>. |
| * |
| * @param id |
| * The id of this handle; must not be <code>null</code>. |
| */ |
| protected HandleObject(final String id) { |
| if (id == null) { |
| throw new NullPointerException( |
| "Cannot create a handle with a null id"); //$NON-NLS-1$ |
| } |
| |
| this.id = id; |
| } |
| |
| /** |
| * Tests whether this object is equal to another object. A handle object is |
| * only equal to another handle object with the same id and the same class. |
| * |
| * @param object |
| * The object with which to compare; may be <code>null</code>. |
| * @return <code>true</code> if the objects are equal; <code>false</code> |
| * otherwise. |
| */ |
| public boolean equals(final Object object) { |
| // Check if they're the same. |
| if (object == this) { |
| return true; |
| } |
| |
| // Check if they're the same type. |
| if (!(object instanceof HandleObject)) { |
| return false; |
| } |
| |
| // Check each property in turn. |
| final HandleObject handle= (HandleObject) object; |
| return Util.equals(id, handle.id) |
| && (this.getClass() == handle.getClass()); |
| } |
| |
| public final String getId() { |
| return id; |
| } |
| |
| /** |
| * Computes the hash code for this object based on the id. |
| * |
| * @return The hash code for this object. |
| */ |
| public final int hashCode() { |
| if (hashCode == HASH_CODE_NOT_COMPUTED) { |
| hashCode = HASH_INITIAL * HASH_FACTOR + Util.hashCode(id); |
| if (hashCode == HASH_CODE_NOT_COMPUTED) { |
| hashCode++; |
| } |
| } |
| return hashCode; |
| } |
| |
| /** |
| * Whether this instance is defined. A defined instance is one that has been |
| * fully initialized. This allows objects to effectively disappear even |
| * though other objects may still have references to them. |
| * |
| * @return <code>true</code> if this object is defined; <code>false</code> |
| * otherwise. |
| */ |
| public final boolean isDefined() { |
| return defined; |
| } |
| |
| /** |
| * The string representation of this object -- for debugging purposes only. |
| * This string should not be shown to an end user. |
| * |
| * @return The string representation; never <code>null</code>. |
| */ |
| public abstract String toString(); |
| |
| /** |
| * Makes this object becomes undefined. This method should make any defined |
| * properties <code>null</code>. It should also send notification to any |
| * listeners that these properties have changed. |
| */ |
| public abstract void undefine(); |
| } |