Package gumbo.util

Provides general purpose low-level utilities, with particular emphasis on patterns and services for delegation of data relationships.

See:
Description

Interface Summary

Bimap	A map that functions as an asymetric bi-directional map of non-null keys and values.
Delegatable	A base interface allowing (but not requiring) this object to serve as a delegate for some other delegator.
Disposable	An interface marking this object as being "disposable".
Group	A collection of members backed by any common collection type (Set, List, SetList) as the group store to achieve ordering and/or uniqueness in the group, as well as efficient group mutation.
GroupBimap	A bimap whose values are maintained in groups associated with the keys.
SetList	An interface for a list whose elements are also a set (unique).

Class Summary

AbstractBimap	An abstract implementation of the Bimap interface.
AbstractBimapTest
AbstractDelegatable	A full implementation of the Delegatable interface.
AbstractDelegatable.Serial	Serializable version of AbstractDelegatable.
AbstractDisposable	A full implementation of the Disposable interface that includes detection and blocking of disposal cycles.
AbstractGroup	An abstract implementation of the Group interface.
AbstractGroupBimap	An abstract implementation of the GroupBimap interface.
AbstractGroupBimapTest
AbstractGroupTest
AbstractSetList	A full implementation of the SetList interface that wraps a target list store.
AbstractSetListTest
AllTests
Debug	Utilities for generating "debug" messages to System.err.
Delegatables	Constants and utilities related to Delegatable.
Delegatables.DelegatableImm	A serializable immutable view wrapper for a target Delegatable.
Delegatables.DelegatableWrapper	A serializable wrapper for a target Delegatable.
DelegatableTest
DelegatableTest.DelegatorA
DelegatableTest.DelegatorB
DelegatableTest.DelegatorC
DelegatableTest.DelegatorD
DelegatableTest.TestStaticDelegateHost
Disposables
Disposables.DisposableImm	A serializable immutable view wrapper for a target Disposable.
Disposables.DisposableWrapper	A serializable wrapper for a target Disposable.
EmptyIteratorTest
GumboCollections	Constants and utilities provided by Gumbo that are related to Collections.
GumboCollections.ImmutableCollection	Immutable wrapper for a target collection.
GumboCollectionsTest	Tests those aspects of GumboCollections not addressed in other tests.
TeeReader	Reader wrapper that copies through data to a "tee" writer.
TeeWriter	Writer wrapper that copies through data to a "tee" writer.
TestDelegateHost
Types	Constants and utilities not related to a specific package class.

Package gumbo.util Description

Provides general purpose low-level utilities, with particular emphasis on patterns and services for delegation of data relationships.

Overview

The attributes of this package are...

• General purpose low-level utilities.
• Focus on services and pattern support.
• Implementation via core Java.
• Required by most other packages.

Delegation

A key aspect of the services and patterns provided by this package is the use of delegation for implementation of common services. Such delegation is marked and facilitated by the Delegatable interface, with related utilities available in Delegatables. Concrete implementations of a delegatable interface are typicalled named ???Service.

Delegation, as defined here, is particularly useful in implementing data relationship, such as data networks and trees. Delegation is also useful if a given delegator is involved in more than one type or instance of relationship (e.g. a data object in two different trees or with two event nodes of the same type).

Delegation can be private, with indirect access to the delegated service through public accessors with client class types, such as

public class MyClass {
private TreeNode _service = new TreeNodeService();

public MyClass getParent() {
return Delegatables.delegator(_service.getParent());
}
}

Delegation can also be public, with direct access to the delegated service, via service accessors, such as

public class MyClass {
private TreeNode _serviceA = new MyTreeNodeService();
private TreeNode _serviceB = new MyTreeNodeService();

public TreeNode getTreeServiceA() {return _serviceA}
public TreeNode getTreeServiceB() {return _serviceB}
}

To assure type safety, the services used for public delegation should check the delegator type of all service mutator parameters, such as

public class MyTreeNodeService extends TreeNodeService{
public void setParent(TreeNode parent) {
if(parent!=null && Delegatables.delegator(parent,
MyClass.class)) throw new IllegalArgumentException();
super.setParent(parent);
}
...
}

Relationships

This package contains classes that support data relationships, which are formed from the base class Relation. The RelationListener interface allows monitoring of structural changes throughout a relationship graph. Relationships come in two flavors with correspondingly different graph topologies. An association consists of Associate objects, and can form a non-directed cyclic graph. A tree consist of TreeNode objects, and can form a directed acyclic tree.

Associations are useful for implementing aspect relationships (e.g. propagating the same interaction state to different views of the same data model). Trees are useful for implementing containment relationships (e.g. whole data model contain part data models).

To Do

• Test thread safety.
• Test dispose() for memory leaks.
• Refactor AbstractRelation, AbstractTreeNode, and AbstractAssociate to use LazyGroup as a private delegate.