All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface uhr.core.attract.Attractor

public interface Attractor

Attractors describe a desired bond between a client and a host. The host has the service desired. The client uses the service by casting the service to the attractor type and then calling methods. Here's what the abstraction looks like:

We hope most attractor types will be Unifaces, but we allow anything, classes or interfaces, single or multiple methods, for flexibility. After all, one size rarely fits all. Note that a Uniface can pass a Datatron as an argument.

A "Uniface" is a reusable interface with a single method devoid of semantic meaning. For example:

     public interface UF_double_double_int {
         public double get(double arg1, int arg2);
     }        
 

Unifaces and attractors work together to offer these benefits for reusable part collaboration:

1. One line of code to use a uniface versus an average of 4 lines with Messages.

2. Unifaces are much faster than Messages. They approach or equal the speed of normal method calls.

3. A clean Anonymous Collaboration mechanism.

4. Easy automatic hookup in many or most cases.

5. Easy support of hierarchical Service Architecture.

6. Precise, full publishing of a part's input and output.

7. Strong typing.

8. Very fine grained reuse, on a per method level rather than per class.

A probable future feature is to allow attractors to be made immutable after configuration. This would allow safer use and encourage the sharing of attractors between different part instances. This could be done by adding the methods void makeImmutable() and boolean isImmutable(). In an implemenation all mutator methods would call an internal method such as checkImmutable() that would throw an IllegalStateException if immutable. Since this is an optimization feature we are postponing it. After all, as Dijkstra said, "Premature optimization is the root of all evil". :-)

We may add convenience methods to allow easy use of the primitive values like boolean, int, etc, for attributes. All this will occur as needed.

addType(String)

Adds a type for the service.

containsAttribute(Object, Object)

Determine whether the key and value are an attribute in this Attractor.

containsKey(Object)

Determines whether the key is in this attractor's attributes.

containsType(String)

Determines whether the attractor contains the type.

enumerateKeys()

Returns an enumeration of all attribute keys in no particular order.

enumerateTypes()

Returns an enumeration of all types in no particular order.

equals(Object)

Overrides the method in Object for use in matching or to use the atttractor as a unique key.

getAttributeCount()

Returns the number of attributes.

getTypeCount()

Returns the number of types.

getValue(Object)

Returns the attribute value for the key or null if none.

hashCode()

Overrides the method in Object for use as a key.

isAttributeSubset(Attractor)

Determines whether this attractor's attributes are a subset of the argument attractor's attributes.

isTypeSubset(Attractor)

Determines whether this attractor's types are a subset of the argument attractor's types.

putAttribute(Object, Object)

Puts a single Attribute into the Attractor.

toString()

Overrides the method in Object for use in debugging and such.

 public abstract void addType(String type)

Adds a type for the service. This is a Java class name such as "uhr.parts.net.SocketMonitor" or "UF_double_double_int". At least one type must be added.

If Unifaces are used then a service has only one type, and a need for that service also has only one type. However we offer the flexibility of multiple types to avoid overly contraining the designer.

A service has one or more types. This allows a service to evolve and still have backwards compatability with prior needs. For example if a service implements a new interface that extends the old interface, it adds both interfaces as types. A need for the old type will be honored, as well as allowing more currently written needs to use the new type.

A need has one or more types, though usually just one. If it has more than one then upon receiving the service it casts it to the most opportune type.

Parameters:

type - the Java type for the service.

Throws: IllegalArgumentException

if type class is not found.

Throws: IllegalStateException

if already added.

 public abstract boolean containsType(String type)

Determines whether the attractor contains the type.

Parameters:

type - the type in question.

Returns:

true if contained or false if not.

 public abstract int getTypeCount()

Returns the number of types. There should be at least one.

Returns:

the number of types.

 public abstract Enumeration enumerateTypes()

Returns an enumeration of all types in no particular order.

Returns:

the enumeration of types.

 public abstract Object putAttribute(Object key,
                                     Object value)

Puts a single Attribute into the Attractor. Attributes describe what is needed or what a host has. At least one attribute is required. The attribute value can be any object, but we caution developers to limit value to Strings, primitive wrappers, etc at first.

Parameters:

key - the key, which cannot be null.

value - the value, which cannot be null;

Returns:

the previous value or null if none.

 public abstract Object getValue(Object key)

Returns the attribute value for the key or null if none.

Parameters:

key - the key in question.

Returns:

the value for the key or null if none.

 public abstract Enumeration enumerateKeys()

Returns an enumeration of all attribute keys in no particular order.

Returns:

the enumeration of keys.

 public abstract boolean containsKey(Object key)

Determines whether the key is in this attractor's attributes.

Parameters:

attribute - the attribute to test.

 public abstract boolean containsAttribute(Object key,
                                           Object value)

Determine whether the key and value are an attribute in this Attractor.

Parameters:

key - the key in question, which may be null.

value - the value in question, which may be null.

Returns:

true if the attribute described by the key and value is in the Attractor, false if not.

 public abstract int getAttributeCount()

Returns the number of attributes. There should be at least one.

Returns:

the number of attributes.

 public abstract boolean isTypeSubset(Attractor attractor)

Determines whether this attractor's types are a subset of the argument attractor's types. This is true if each of this attractor's types is contained in the other attractor.

Parameters:

attractor - the other attractor to use for comparison.

Returns:

true if a subset, false if not.

 public abstract boolean isAttributeSubset(Attractor attractor)

Determines whether this attractor's attributes are a subset of the argument attractor's attributes. This is true if each of this attractor's attributes is contained in the other attractor.

Parameters:

attractor - the other attractor to use for comparison.

Returns:

true if a subset, false if not.

 public abstract String toString()

Overrides the method in Object for use in debugging and such.

Returns:

the string representation, which is the name and value.

Overrides:

toString in class Object

 public abstract boolean equals(Object object)

Overrides the method in Object for use in matching or to use the atttractor as a unique key.

Parameters:

object - the object to compare to.

Returns:

true if equal or false if not.

Overrides:

equals in class Object

 public abstract int hashCode()

Overrides the method in Object for use as a key.

Returns:

the same int if two attractors are equal, and usually a different int if they're not.

Overrides:

hashCode in class Object

All Packages  Class Hierarchy  This Package  Previous  Next  Index