orc.trace.handles
Class Handle<E>

java.lang.Object
  orc.trace.handles.Handle<E>

All Implemented Interfaces:

java.io.Externalizable, java.io.Serializable

Direct Known Subclasses:

FirstHandle, LastHandle, OnlyHandle, RepeatHandle

public abstract class Handle<E>
extends java.lang.Object
implements java.io.Externalizable

Works with HandleInputStream and HandleOutputStream to explicitly manage the lifetime of serialized pointers. Handles are used in place of non-null pointers. There are four types of handles:

FirstHandle

The first references to a value with at least two references.

RepeatHandle

Neither the first nor the last reference to a value with at least three references.

LastHandle

The last reference to a value with at least two references.

OnlyHandle

The only reference to a value. This is functionally equivalent to a regular pointer.

It is up to the programmer to choose the appropriate handle type according to the number of references and the order in which values are serialized. In other words, you're performing your own memory management.

WARNING: DO NOT use this with a regular ObjectOutput or ObjectInput. It only works with subtypes of HandleOutputStream and HandleInputStream.

FIXME: Handles do not deserialize circular references correctly. This should be straightforward to fix (if a handle detects that it needs to point to a value which is currently being read, it should register with the HandleInputStream to be updated once the value is read), but so far I haven't needed it.

Author:

quark

See Also:

HandleOutputStream, Serialized Form

Field Summary

protected E

value

Constructor Summary

Handle()
Required by Externalizable, but should never be called when not deserializing.

Handle(E value)
Create a handle to a value, which must be non-null.

Method Summary

boolean	equals(java.lang.Object that) Handles are equal if the values they point to are equal.
E	get() Get the value pointed to by this handle.
int	hashCode() Handles which point to the same value should use the same hash code.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.io.Externalizable

readExternal, writeExternal

Field Detail

value

protected E value

Constructor Detail

Handle

public Handle()

Required by Externalizable, but should never be called when not deserializing.

Handle

public Handle(E value)

Create a handle to a value, which must be non-null.

Method Detail

get

public final E get()

Get the value pointed to by this handle.

toString

public final java.lang.String toString()

Overrides:

toString in class java.lang.Object

equals

public final boolean equals(java.lang.Object that)

Handles are equal if the values they point to are equal.

Overrides:

equals in class java.lang.Object

hashCode

public final int hashCode()

Handles which point to the same value should use the same hash code.

Overrides:

hashCode in class java.lang.Object