net.wotonomy.ui
Class EOAssociation

java.lang.Object
  net.wotonomy.control.EODelayedObserver
      net.wotonomy.ui.EOAssociation

All Implemented Interfaces:

java.util.Observer, net.wotonomy.control.EOObserving

Direct Known Subclasses:

GenericAssociation, MasterDetailAssociation

public class EOAssociation
extends net.wotonomy.control.EODelayedObserver

Associations observe DisplayGroups and associate a user interface component with one or more keys on the objects in the display group.

Associations are created with a ui component in the constructor. Then, one or more aspects are bound to display groups and/or property keys with the bindAspect() method. Finally, the association is initialized with the establishConnection() method.

Per the openstep convention, you do not need to retain a reference to the association after it is created; the association will be garbage-collected when the ui component is garbage-collected.

(Because java components don't have delegates like openstep components do, java-based associations will likely need to implement some sort of listener and add itself to the component's list of listeners so that the component will have a strong reference (and the only reference) to the association.)

Version:

$Revision: 904 $

Author:

michael@mpowers.net, $Author: cgruber $

Field Summary

static java.lang.String	ActionAspect
static java.lang.String	ArgumentAspect
protected net.wotonomy.foundation.NSMutableDictionary	aspectToGroup
protected net.wotonomy.foundation.NSMutableDictionary	aspectToKey
static java.lang.String	AttributeAspectSignature
static java.lang.String	AttributeToManyAspectSignature
static java.lang.String	AttributeToOneAspectSignature
static java.lang.String	AttributeToOneToManyAspectSignature
static java.lang.String	BoldAspect
static java.lang.String	ChildrenAspect
protected java.lang.Object	control
static java.lang.String	DestinationAspect
static java.lang.String	EditableAspect
static java.lang.String	EnabledAspect
static java.lang.String	IconAspect
static java.lang.String	IsLeafAspect
static java.lang.String	ItalicAspect
static java.lang.String	LabelAspect
static java.lang.String	NullAspectSignature
static java.lang.String	ObjectsAspect
static java.lang.String	ParentAspect
static java.lang.String	SelectedObjectAspect
static java.lang.String	SelectedTitleAspect
static java.lang.String	SourceAspect
static java.lang.String	TitlesAspect
static java.lang.String	ToManyAspectSignature
static java.lang.String	ToOneAspectSignature
static java.lang.String	ToOneToManyAspectSignature
static java.lang.String	URLAspect
static java.lang.String	ValueAspect
static java.lang.String	VisibleAspect

Fields inherited from class net.wotonomy.control.EODelayedObserver

ObserverNumberOfPriorities, ObserverPriorityFifth, ObserverPriorityFirst, ObserverPriorityFourth, ObserverPriorityImmediate, ObserverPriorityLater, ObserverPrioritySecond, ObserverPrioritySixth, ObserverPriorityThird

Constructor Summary

EOAssociation()
Default constructor.

EOAssociation(java.lang.Object anObject)
Constructor specifying the object to be controlled by this association.

Method Summary

static net.wotonomy.foundation.NSArray	aspects() Returns a List that describes the aspects supported by this class.
static net.wotonomy.foundation.NSArray	aspectSignatures() Returns a List of aspect signatures whose contents correspond with the aspects list.
static net.wotonomy.foundation.NSArray	associationClassesForObject(java.lang.Object anObject) Returns all registered subclasses of EOAssociation for which usableWithObject with the specified object returns true.
static net.wotonomy.foundation.NSArray	associationClassesSuperseded() Returns a List of EOAssociation subclasses that, for the objects that are usable for this association, are less suitable than this association.
void	bindAspect(java.lang.String anAspect, EODisplayGroup aDisplayGroup, java.lang.String aKey) Binds the specified aspect of this association to the specified key on the specified display group.
void	breakConnection() Breaks the connection between this association and its object.
boolean	canBindAspect(java.lang.String anAspect, EODisplayGroup aDisplayGroup, java.lang.String aKey) Returns whether this association can bind to the specified display group on the specified key for the specified aspect.
void	copyMatchingBindingsFromAssociation(EOAssociation anAssociation) Copies the binding for each aspect in this association that has a matching aspect in the specified association.
EODisplayGroup	displayGroupForAspect(java.lang.String anAspect) Returns the display group that is bound the specified aspect, or null if no display group is currently bound to that aspect.
java.lang.String	displayGroupKeyForAspect(java.lang.String anAspect) Returns the key for the display group bound to the specified aspect, or null if no display group is currently bound to that aspect.
java.lang.String	displayName() The human-readable descriptive name for this association.
boolean	endEditing() Forces this association to cause the object to stop editing and validate the user's input.
void	establishConnection() Establishes a connection between this association and the controlled object.
static boolean	isUsableWithObject(java.lang.Object anObject) Returns whether this class can control the specified object.
java.lang.Object	object() Returns the object that is currently controlled by this association, or null if no object is currently controlled.
static net.wotonomy.foundation.NSArray	objectKeysTaken() Returns a List of properties of the controlled object that are controlled by this class.
static java.lang.String	primaryAspect() Returns the aspect that is considered primary or default.
boolean	setValueForAspect(java.lang.Object aValue, java.lang.String anAspect) Writes the specified value for the display group and key currently bound to the specified aspect.
boolean	setValueForAspectAtIndex(java.lang.Object aValue, java.lang.String anAspect, int anIndex) Writes the specified value for the display group and key currently bound to the specified aspect, at the specified index (assuming it's an indexed property).
boolean	shouldEndEditing(java.lang.String anAspect, java.lang.String anInvalidInput, java.lang.String anErrorDescription) Called by subclasses to notify that the user's input failed validation.
boolean	shouldEndEditingAtIndex(java.lang.String anAspect, java.lang.String anInvalidInput, java.lang.String anErrorDescription, int anIndex) Called by subclasses to notify that the user's input failed validation.
void	subjectChanged() Called when either the selection or the contents of an associated display group have changed.
java.lang.Object	valueForAspect(java.lang.String anAspect) Returns the current value for the display group and key associated with the specified aspect.
java.lang.Object	valueForAspectAtIndex(java.lang.String anAspect, int anIndex) Returns the current value for the display group and key associated with the specified aspect, and the specified index (assuming multiple values).

Methods inherited from class net.wotonomy.control.EODelayedObserver

discardPendingNotification, objectWillChange, observerQueue, priority, update

Methods inherited from class java.lang.Object

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

Field Detail

ActionAspect

public static final java.lang.String ActionAspect

See Also:

Constant Field Values

EnabledAspect

public static final java.lang.String EnabledAspect

See Also:

Constant Field Values

SourceAspect

public static final java.lang.String SourceAspect

See Also:

Constant Field Values

ArgumentAspect

public static final java.lang.String ArgumentAspect

See Also:

Constant Field Values

ParentAspect

public static final java.lang.String ParentAspect

See Also:

Constant Field Values

TitlesAspect

public static final java.lang.String TitlesAspect

See Also:

Constant Field Values

BoldAspect

public static final java.lang.String BoldAspect

See Also:

Constant Field Values

SelectedObjectAspect

public static final java.lang.String SelectedObjectAspect

See Also:

Constant Field Values

ValueAspect

public static final java.lang.String ValueAspect

See Also:

Constant Field Values

DestinationAspect

public static final java.lang.String DestinationAspect

See Also:

Constant Field Values

SelectedTitleAspect

public static final java.lang.String SelectedTitleAspect

See Also:

Constant Field Values

URLAspect

public static final java.lang.String URLAspect

See Also:

Constant Field Values

ItalicAspect

public static final java.lang.String ItalicAspect

See Also:

Constant Field Values

ChildrenAspect

public static final java.lang.String ChildrenAspect

See Also:

Constant Field Values

IsLeafAspect

public static final java.lang.String IsLeafAspect

See Also:

Constant Field Values

EditableAspect

public static final java.lang.String EditableAspect

See Also:

Constant Field Values

VisibleAspect

public static final java.lang.String VisibleAspect

See Also:

Constant Field Values

ObjectsAspect

public static final java.lang.String ObjectsAspect

See Also:

Constant Field Values

LabelAspect

public static final java.lang.String LabelAspect

See Also:

Constant Field Values

IconAspect

public static final java.lang.String IconAspect

See Also:

Constant Field Values

AttributeAspectSignature

public static final java.lang.String AttributeAspectSignature

See Also:

Constant Field Values

NullAspectSignature

public static final java.lang.String NullAspectSignature

See Also:

Constant Field Values

AttributeToOneAspectSignature

public static final java.lang.String AttributeToOneAspectSignature

See Also:

Constant Field Values

ToOneAspectSignature

public static final java.lang.String ToOneAspectSignature

See Also:

Constant Field Values

AttributeToOneToManyAspectSignature

public static final java.lang.String AttributeToOneToManyAspectSignature

See Also:

Constant Field Values

ToOneToManyAspectSignature

public static final java.lang.String ToOneToManyAspectSignature

See Also:

Constant Field Values

AttributeToManyAspectSignature

public static final java.lang.String AttributeToManyAspectSignature

See Also:

Constant Field Values

ToManyAspectSignature

public static final java.lang.String ToManyAspectSignature

See Also:

Constant Field Values

control

protected java.lang.Object control

aspectToGroup

protected net.wotonomy.foundation.NSMutableDictionary aspectToGroup

aspectToKey

protected net.wotonomy.foundation.NSMutableDictionary aspectToKey

Constructor Detail

EOAssociation

public EOAssociation()

Default constructor.

EOAssociation

public EOAssociation(java.lang.Object anObject)

Constructor specifying the object to be controlled by this association. Does not establish connection.

Method Detail

aspectSignatures

public static net.wotonomy.foundation.NSArray aspectSignatures()

Returns a List of aspect signatures whose contents correspond with the aspects list. Each element is a string whose characters represent a capability of the corresponding aspect.

• "A" attribute: the aspect can be bound to an attribute.
• "1" to-one: the aspect can be bound to a property that returns a single object.
• "M" to-one: the aspect can be bound to a property that returns multiple objects.

An empty signature "" means that the aspect can bind without needing a key. This implementation returns "A1M" for each element in the aspects array.

aspects

public static net.wotonomy.foundation.NSArray aspects()

Returns a List that describes the aspects supported by this class. Each element in the list is the string name of the aspect. This implementation returns an empty list. TODO: Is this static in the WebObjects published API? If not, fix.

associationClassesForObject

public static net.wotonomy.foundation.NSArray associationClassesForObject(java.lang.Object anObject)

Returns all registered subclasses of EOAssociation for which usableWithObject with the specified object returns true. You should only call this method on the EOAssociation class.

associationClassesSuperseded

public static net.wotonomy.foundation.NSArray associationClassesSuperseded()

Returns a List of EOAssociation subclasses that, for the objects that are usable for this association, are less suitable than this association. This implementation returns an empty list.

bindAspect

public void bindAspect(java.lang.String anAspect,
                       EODisplayGroup aDisplayGroup,
                       java.lang.String aKey)

Binds the specified aspect of this association to the specified key on the specified display group.

breakConnection

public void breakConnection()

Breaks the connection between this association and its object. Override to stop listening for events from the object, but remember to call this method. This implementation unregisters this association from observing each bound display group.

canBindAspect

public boolean canBindAspect(java.lang.String anAspect,
                             EODisplayGroup aDisplayGroup,
                             java.lang.String aKey)

Returns whether this association can bind to the specified display group on the specified key for the specified aspect. This implementation returns false.

copyMatchingBindingsFromAssociation

public void copyMatchingBindingsFromAssociation(EOAssociation anAssociation)

Copies the binding for each aspect in this association that has a matching aspect in the specified association.

displayGroupForAspect

public EODisplayGroup displayGroupForAspect(java.lang.String anAspect)

Returns the display group that is bound the specified aspect, or null if no display group is currently bound to that aspect.

displayGroupKeyForAspect

public java.lang.String displayGroupKeyForAspect(java.lang.String anAspect)

Returns the key for the display group bound to the specified aspect, or null if no display group is currently bound to that aspect.

displayName

public java.lang.String displayName()

The human-readable descriptive name for this association. This implementation returns the class name.

endEditing

public boolean endEditing()

Forces this association to cause the object to stop editing and validate the user's input. This implementation returns true.

Returns:

false if there were problems validating, or true to continue.

establishConnection

public void establishConnection()

Establishes a connection between this association and the controlled object. Subclasses should populate their controlled object from the display group and begin listening for events from their controlled object here, but remember to call this method. Any existing value in the controlled object will be overwritten. This implementation registers this assocation to observer changes to each of the bound display groups.

isUsableWithObject

public static boolean isUsableWithObject(java.lang.Object anObject)

Returns whether this class can control the specified object. This implementation returns false.

object

public java.lang.Object object()

Returns the object that is currently controlled by this association, or null if no object is currently controlled.

objectKeysTaken

public static net.wotonomy.foundation.NSArray objectKeysTaken()

Returns a List of properties of the controlled object that are controlled by this class. For example, "stringValue", or "selected". This implementation returns an empty list.

primaryAspect

public static java.lang.String primaryAspect()

Returns the aspect that is considered primary or default. This is typically "value" or somesuch. This implementation returns null.

setValueForAspect

public boolean setValueForAspect(java.lang.Object aValue,
                                 java.lang.String anAspect)

Writes the specified value for the display group and key currently bound to the specified aspect. This implementation calls EODisplayGroup.setSelectedObjectValue().

Returns:

True if the value was successfully set, otherwise false.

setValueForAspectAtIndex

public boolean setValueForAspectAtIndex(java.lang.Object aValue,
                                        java.lang.String anAspect,
                                        int anIndex)

Writes the specified value for the display group and key currently bound to the specified aspect, at the specified index (assuming it's an indexed property). This implementation calls EODisplayGroup.setValueForObjectAtIndex().

Returns:

True if the value was successfully set, otherwise false.

shouldEndEditing

public boolean shouldEndEditing(java.lang.String anAspect,
                                java.lang.String anInvalidInput,
                                java.lang.String anErrorDescription)

Called by subclasses to notify that the user's input failed validation. Notifies the display group for the aspect, returning the result. This implementation calls EODisplayGroup.associationFailedToValidateValue() with the display group's selected object.

Returns:

True if the user should be allowed to continue, meaning that the display group with handle user notification, otherwise false meaning the caller should notify the user.

shouldEndEditingAtIndex

public boolean shouldEndEditingAtIndex(java.lang.String anAspect,
                                       java.lang.String anInvalidInput,
                                       java.lang.String anErrorDescription,
                                       int anIndex)

Called by subclasses to notify that the user's input failed validation. Notifies the display group for the aspect, returning the result. This implementation calls EODisplayGroup.associationFailedToValidateValue() with the object in the display group's displayed objects array at the specified index.

Returns:

True if the user should be allowed to continue, meaning that the display group with handle user notification, otherwise false meaning the caller should notify the user.

subjectChanged

public void subjectChanged()

Called when either the selection or the contents of an associated display group have changed. This implementation does nothing.

Specified by:

subjectChanged in class net.wotonomy.control.EODelayedObserver

valueForAspect

public java.lang.Object valueForAspect(java.lang.String anAspect)

Returns the current value for the display group and key associated with the specified aspect.

valueForAspectAtIndex

public java.lang.Object valueForAspectAtIndex(java.lang.String anAspect,
                                              int anIndex)

Returns the current value for the display group and key associated with the specified aspect, and the specified index (assuming multiple values).