gumbo.util.relation
Class Relationship

java.lang.Object
  |
  +--gumbo.util.AbstractDisposable
        |
        +--gumbo.util.relation.Relationship

All Implemented Interfaces:

Disposable, java.io.Serializable

Direct Known Subclasses:

TestRelationship, TreeNodes.Tree

public abstract class Relationship

extends AbstractDisposable

implements java.io.Serializable

An abstract base class for a set of related and possibly interconnected relations of a given type and purpose. Provides observability of and access to the relationship as a whole.

Note that serialization does not include the relations. This avoids serialization loops when serializing a network of relations (which can cause stack overflow for large networks); and, it is consistent with the notion that relation networks are of interest, not the relationship per se. Thus, during deserialized a relation is is responsible for adding itself to its relationship, using relationship.implAddRelation(). To serialize a relationship and its relations use the writeRelationship() and readRelationship() utilities.

Version:

$Revision: 1.2 $

Author:

Jon Barrilleaux (jonb@jmbaai.com) of JMB and Associates Inc.

See Also:

Serialized Form

Constructor Summary

Relationship()
Creates an instance.

Method Summary

protected abstract void	checkRelation(Relation relation) Called by the system to check added relations and their delegators for compatibility with this relationship.
ConnectionField.EventOut	getAddedConnectionOut() Sends a connection after it is created.
RelationField.EventOut	getAddedRelationOut() Sends a relation after it is added to this relationship.
java.util.Map	getRelations() Returns a singleton immutable view of this relationship's delegator (Object) to relation (Relation) map, with delegators and relations being unique.
ConnectionField.EventOut	getRemovingConnectionOut() Sends a connection before it is destroyed.
RelationField.EventOut	getRemovingRelationOut() Sends a relation before it is removed from this relationship.
void	implAddedConnection(Connection connection) Used by relations to fire relation and relationship connection events after adding a connection.
void	implAddRelation(Relation relation) Used by relations to add themselves to this relationship.
protected void	implDispose() Disposes event routes and clears the relations.
void	implRemoveRelation(Relation relation) Used by relations to remove themselves from this relationship.
void	implRemovingConnection(Connection connection) Used by relations to fire relation and relationship connection events before removing a connection.
java.lang.String	toString()

Methods inherited from class gumbo.util.AbstractDisposable

dispose, isDisposed

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Relationship

public Relationship()

Creates an instance.

Method Detail

getRelations

public java.util.Map getRelations()

Returns a singleton immutable view of this relationship's delegator (Object) to relation (Relation) map, with delegators and relations being unique.

Returns:

The view. Never null.

getAddedRelationOut

public final RelationField.EventOut getAddedRelationOut()

Sends a relation after it is added to this relationship. Never null.

getRemovingRelationOut

public final RelationField.EventOut getRemovingRelationOut()

Sends a relation before it is removed from this relationship. Never null.

getAddedConnectionOut

public final ConnectionField.EventOut getAddedConnectionOut()

Sends a connection after it is created. Never null. Will only be sent once even if navigation of the connection is bi-directional.

getRemovingConnectionOut

public final ConnectionField.EventOut getRemovingConnectionOut()

Sends a connection before it is destroyed. Never null. Will only be sent once even if navigation of the connection is bi-directional.

implAddedConnection

public final void implAddedConnection(Connection connection)

Used by relations to fire relation and relationship connection events after adding a connection. Events are fired for all relations in the connection, and then for the relationship. The connection's relationship must match this relationship. Should only be called once by the relation initiating the connection change.

Parameters:

connection - Snapshot of the connection. Never null.

implRemovingConnection

public final void implRemovingConnection(Connection connection)

Used by relations to fire relation and relationship connection events before removing a connection. Events are fired for all relations in the connection, and then for the relationship. The connection's relationship must match this relationship. Should only be called once by the relation initiating the connection change.

Parameters:

connection - Snapshot of the connection. Never null.

implAddRelation

public final void implAddRelation(Relation relation)

Used by relations to add themselves to this relationship. Performs no relation connecton or relationship updating. Must be called after the relation's delegator is initialized, its relationship has been updated, and it has been connected to its neighbors. If successful fires getAddedRelationOut(). Throws an exception if the relation or its delegator are null or already in this relationship, or if the relation is incompatible with this relationship as determined by checkRelation().

Parameters:

relation - Reference to the relation. Never null or duplicate.

implRemoveRelation

public void implRemoveRelation(Relation relation)

Used by relations to remove themselves from this relationship. Performs no relation connecton or relationship updating. Must be called before the relation's relationship has been updated, or it has been disconnected from its neighbors. If successful fires getRemovingRelationOut(). Throws an exception if the relation or its delegator are null or missing from this relationship.

Parameters:

relation - Reference to the relation. Never null or missing.

checkRelation

protected abstract void checkRelation(Relation relation)

Called by the system to check added relations and their delegators for compatibility with this relationship. Typically, all relations in a relationship are the same basic type (such as IntersectionTreeNode). Implementors should throw an exception if the relation or its delegator is incompatible. Implementors can assume that null relation or delegator, duplication of relation or delegator, and the relation's relationship have already been checked.

Parameters:

relation - The relation. Never null.

implDispose

protected void implDispose()

Disposes event routes and clears the relations. Subclasses should disconnect connections and routes first to provide disconnect notification.

Specified by:

implDispose in class AbstractDisposable

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object