Eclipse Platform Release 3.7

## org.eclipse.core.commands.common
Class HandleObject

    java.lang.Object
      org.eclipse.core.commands.common.EventManager
          org.eclipse.core.commands.common.HandleObject

All Implemented Interfaces:
  IIdentifiable

Direct Known Subclasses:
  NamedHandleObject, ParameterType

    public abstract class HandleObject

extends EventManager
implements IIdentifiable

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.

To enforce good coding practice, all handle objects must implement `equals` and `toString`. Please use `string` to cache the result for `toString` once calculated.

All handle objects are referred to using a single identifier. This identifier is a instance of `String`. 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 `Command` with a given identifier.

Since:
  3.1

Field Summary
`protected boolean` `defined` Whether this object is defined.
`protected String` `id` The identifier for this object.
`protected String` `string` The string representation of this object.

Constructor Summary
`protected` `HandleObject(String id)` Constructs a new instance of `HandleObject`.

Method Summary
`boolean` `equals(Object object)` Tests whether this object is equal to another object.
`String` `getId()` Returns the identifier for this object.
`int` `hashCode()` Computes the hash code for this object based on the id.
`boolean` `isDefined()` Whether this instance is defined.
`abstract String` `toString()` The string representation of this object -- for debugging purposes only.
`abstract void` `undefine()` Makes this object becomes undefined.

Methods inherited from class org.eclipse.core.commands.common.EventManager
`addListenerObject, clearListeners, getListeners, isListenerAttached, removeListenerObject`

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

### defined

    protected transient boolean defined

  Whether this object is defined. A defined object is one that has been fully initialized. By default, all objects start as undefined.

### id

    protected final String id

  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 `null`.

### string

    protected transient String string

  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.

Constructor Detail

### HandleObject

    protected HandleObject(String id)

  Constructs a new instance of `HandleObject`.

  Parameters:
    `id` - The id of this handle; must not be `null`.

Method Detail

### equals

    public boolean equals(Object object)

  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.

  Overrides:
    `equals` in class `Object`
  Parameters:
    `object` - The object with which to compare; may be `null`.
  Returns:
    `true` if the objects are equal; `false` otherwise.

### getId

    public final String getId()

  Description copied from interface: `IIdentifiable`
  Returns the identifier for this object.

  Specified by:
    `getId` in interface `IIdentifiable`
  Returns:
    The identifier; never `null`.

### hashCode

    public final int hashCode()

  Computes the hash code for this object based on the id.

  Overrides:
    `hashCode` in class `Object`
  Returns:
    The hash code for this object.

### isDefined

    public final boolean isDefined()

  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.

  Returns:
    `true` if this object is defined; `false` otherwise.

### toString

    public abstract String toString()

  The string representation of this object -- for debugging purposes only. This string should not be shown to an end user.

  Overrides:
    `toString` in class `Object`
  Returns:
    The string representation; never `null`.

### undefine

    public abstract void undefine()

  Makes this object becomes undefined. This method should make any defined properties `null`. It should also send notification to any listeners that these properties have changed.

Eclipse Platform Release 3.7

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2011. All rights reserved.