one.world.core
Class Tuple

java.lang.Object
  |
  +--one.world.core.Tuple

All Implemented Interfaces:

Cloneable, Serializable

Direct Known Subclasses:

AudioDescriptor, Channel, CheckPoint, Data, Descriptor, Environment.Descriptor, Event, FetcherProtocol.UserDescriptor, Name, Operation.ChainingClosure, Query, RemoteDescriptor, SioResource, UserPreferences

public abstract class Tuple

extends Object

implements Cloneable, Serializable

Abstract base class for tuples. Tuples are the core data structures. They can either be statically typed or dynamically typed.

Statically Typed Tuples

Statically typed tuples are Java objects that directly or indirectly inherit from this base class. The data for statically typed tuples is provided by their public, non-static, non-final, non-transient fields. Tuples must not have any non-public, final, or transient fields. Furthermore, subclasses of a tuple may not introduce any instance fields that have the same name as a field of a superclass.

The types for non-static fields are restricted. They can be of any primitive Java type, the boxed version of a primitive types, a string, a Class, a Throwable, a Guid, an InetAddress, an event handler, a tuple, a Box containing an arbitrary serialized object, or a one-dimensional array of one of the previously listed types. When declaring a field to be some event handler, that field should not be declared to be a specific event handler (unless the event handler is a SymbolicHandler) but always an EventHandler. Otherwise, the tuple cannot be passed between concurrency and protection domains, because event handlers are wrapped when being passed across concurrency and protection domains.

Note that the field type restrictions are currently only enforced when passing tuples between protection domains. This may change in a future release of one.world.

Statically typed tuples must not have any static fields, unless they are final and of a primitive type, the boxed version of a primitive type, a string, a class, a GUID, an Internet address, a box, or an object (but not a subclass of it).

Serialization for statically typed tuples must be straight-forward. In other words, statically typed tuples must not have a serialPersistentFields field and must not implement a writeObject(), writeExternal(), writeReplace(), readObject(), readExternal(), or readResolve method.

Dynamically Typed Tuples

Dynamically typed tuples are instances of class DynamicTuple. They implement a mapping from field names to values. Mappings can be dynamically added and removed from a dynamic tuple, and values are dynamically typed.

Required Fields

By subclassing from this class, all tuples have a public, non-transient, non-static field named "id" of type Guid, which specifies the ID of the tuple, and a public, non-transient, non-static field named "metaData" of type DynamicTuple, which specifies the meta-data for the tuple. All tuples (must) also have a public no-argument constructor.

Since dynamically typed tuples are also events, they have four statically typed fields, for the ID (id), the meta-data (metaData), the source (source), and the closure (closure).

Accessing Tuple Fields

Statically and dynamically typed tuples alike implement the same uniform operations to access their fields. Though, the fields of statically typed tuples can be accessed directly as well.

Remarks

The methods implemented by this class automatically work for all subclasses that implement valid tuples. If a subclass does not follow the tuple specification, invoking any of the methods defined by this class will result in a Bug.

Even though the get(String), set(String,Object), hasField(String), getType(String), and fields() methods are not declared to be final (since the implementation of dynamic tuple, for example, needs to reimplement them), they must not be overriden by statically typed tuples. Statically typed tuples that override, for example, the get() method defined by this class do not validate.

Note that even if the class of a tuple is declared to not be public, all its fields are still accessible through the methods implemented by this class. There is no way to restrict access to the fields of a tuple, besides not passing it out.

Version:

$Revision: 1.27 $

See Also:

Serialized Form

Field Summary

static String	CLOSURE The name of the closure field.
Guid	id The ID for this tuple.
static String	ID The name of the ID field.
static String	META_DATA The name of the meta-data field.
DynamicTuple	metaData The meta-data for this tuple.
static String	SOURCE The name of the source field.

Constructor Summary

Tuple()
Create a new tuple.

Tuple(Guid id)
Create a new tuple.

Method Summary

Object	clone() Make a shallow copy of this tuple.
boolean	containsNonSymbolicHandler() Determine whether this tuple contains at least one non-symbolic event handler.
boolean	equals(Object o) Determine whether this tuple equals the specified object.
List	fields() Get a list of this tuple's field names.
Object	get(String name) Get the value of the specified field.
Object	getMetaData(String name) Get the value of the meta-data field with the specified name.
Class	getType(String name) Get the declared type of the field with the specified name.
boolean	hasField(String name) Determine whether this tuple has a field with the specified name.
int	hashCode() Get a hashcode for this tuple.
boolean	hasMetaData(String name) Determine whether this tuple has a meta-data field with the specified name.
Object	remove(String name) Remove the specified field from this tuple.
void	set(String name, Object value) Set the specified field to the specified value.
void	setMetaData(String name, Object value) Set the meta-data field with the specified name to the specified value.
String	toString() Get a string representation for this tuple.
void	validate() Validate this tuple.
void	wrap(Wrapper wrapper) Wrap this tuple.

Methods inherited from class java.lang.Object

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

Field Detail

ID

public static final String ID

The name of the ID field.

META_DATA

public static final String META_DATA

The name of the meta-data field.

SOURCE

public static final String SOURCE

The name of the source field.

CLOSURE

public static final String CLOSURE

The name of the closure field.

id

public Guid id

The ID for this tuple.

metaData

public DynamicTuple metaData

The meta-data for this tuple. The fields of the dynamic tuple should be named using the same naming conventions as those used for Java package names or system properties.

Constructor Detail

Tuple

public Tuple()

Create a new tuple. This constructor creates a new tuple with a freshly created ID.

Tuple

public Tuple(Guid id)

Create a new tuple. This constructor creates a new tuple with the specified ID.

Parameters:

id - The ID for the new tuple.

Method Detail

clone

public Object clone()

Make a shallow copy of this tuple. The copy contains the same values as this tuple, including its ID and its meta-data.

Overrides:

clone in class Object

Returns:

A shallow copy of this tuple.

hashCode

public final int hashCode()

Get a hashcode for this tuple.

Overrides:

hashCode in class Object

Returns:

A hashcode for this tuple.

equals

public final boolean equals(Object o)

Determine whether this tuple equals the specified object. This tuple equals the specified object, if the specified object is a tuple of the same type and all fields of this tuple, besides the id and metaData fields, are equal to the corresponding fields of the specified object.

Overrides:

equals in class Object

Parameters:

o - The object to compare to.

Returns:

true if this tuple equals the specified object.

get

public Object get(String name)

Get the value of the specified field. This method returns the value of the specified field or null if this tuple does not have a field with the specified name.

Parameters:

name - The name of the field.

Returns:

The value of the specified field, or null if this tuple has no such field.

set

public void set(String name,
                Object value)

Set the specified field to the specified value. This method sets the value of the field with the specified name to the specified value. If this tuple is a dynamically typed tuple and does not have a field with the specified name, the field is added to the tuple.

Parameters:

name - The name of the field.

value - The new value for the field.

Throws:

IllegalArgumentException - Signals that a statically typed tuples does not have a field with the specified name or that the specified value is of the wrong type.

remove

public final Object remove(String name)

Remove the specified field from this tuple. For dynamically typed tuples, this method removes the specified field from the tuple if it exists.

Parameters:

name - The name of the field to remove.

Returns:

The value of the removed field.

Throws:

IllegalArgumentException - Signals that the field cannot be removed because it is a statically typed field.

hasField

public boolean hasField(String name)

Determine whether this tuple has a field with the specified name.

Parameters:

name - The name of the field to test for.

Returns:

true if this tuple has a field with the specified name.

getType

public Class getType(String name)

Get the declared type of the field with the specified name. The declared type of a dynamic tuple's dynamically typed fields is java.lang.Object.

Parameters:

name - The name of the field.

fields

public List fields()

Get a list of this tuple's field names. Modifications to the list have no effect on the corresponding fields.

Returns:

A list of this tuple's field names.

getMetaData

public final Object getMetaData(String name)

Get the value of the meta-data field with the specified name.

This convenience method is equivalent to:

   return ((null == metaData)?
           null :
           metaData.get(name));
 

Parameters:

name - The name of the meta-data field.

Returns:

The value of the corresponding field, or null if this tuple does not have a meta-data field with the specified field.

setMetaData

public final void setMetaData(String name,
                              Object value)

Set the meta-data field with the specified name to the specified value.

This convenience method is equivalent to:

   if (null == metaData) {
     metaData = new DynamicTuple();
   }
   metaData.set(name, value);
 

Parameters:

name - The name of the meta-data field.

value - The new value for the specified field.

hasMetaData

public final boolean hasMetaData(String name)

Determine whether this tuple has a meta-data field with the specified name.

This convenience method is equivalent to:

   return ((null == metaData)?
           false :
           metaData.hasField(name));
 

Parameters:

name - The name of the meta-data field.

Returns:

true if this tuple has a meta-data field with the specified name.

validate

public void validate()
              throws TupleException

Validate this tuple. This method ensures that this tuple is well-formed. Subclasses that overwrite this method must first call the superclass's validate() method.

This method ensures that this tuple's class is a valid tuple class. It also ensures that this tuple's ID is not null. This tuple's meta-data is not validated.

Throws:

TupleException - Signals that the tuple is either malformed (i.e., does not conform to the tuple specification) or invalid (i.e., does not conform to the semantic constraints of its type).

See Also:

MalformedTupleException, InvalidTupleException, Type.validate(Class)

wrap

public final void wrap(Wrapper wrapper)

Wrap this tuple. This method applies the specified wrapper to all event handlers referenced by this tuple (and any nested tuples). The tuple is modified in place. Note that if the result of wrapping an event handler cannot be assigned back to the field, this method will throw a Bug.

Parameters:

wrapper - The wrapper to apply on all event handlers.

containsNonSymbolicHandler

public final boolean containsNonSymbolicHandler()

Determine whether this tuple contains at least one non-symbolic event handler. This method is useful for one.world.rep, which requires that events do not contain non-symbolic event handlers.

Returns:

true if this tuple contains at least one non-symbolic event handler.

See Also:

SymbolicHandler

toString

public String toString()

Get a string representation for this tuple.

Overrides:

toString in class Object

Returns:

A string representation for this tuple.