com.webobjects.eointerface
Class EOAssociation

java.lang.Object
  |
  +--com.webobjects.eocontrol.EODelayedObserver
        |
        +--com.webobjects.eointerface.EOAssociation

All Implemented Interfaces:

EOObserving, NSDisposable

Direct Known Subclasses:

EODetailSelectionAssociation, EOMasterAssociation, EOWidgetAssociation

public abstract class EOAssociation

extends EODelayedObserver

implements NSDisposable

An EOAssociation maintains a two-way binding between the properties of a display object, such as a text field or combo box, and the properties of one or more enterprise objects contained in one or more EODisplayGroups. You typically create and configure associations in Interface Builder, using the programmatic interface only when you write your own EOAssociation subclasses.

Principal Attributes:

• A display object (such as a text field or combo box)
• Aspects that control different parameters of the display object (such as value and enabled)
• One or more EODisplayGroups (no more than one per aspect)
• One or more keys (enteprise object properties) (as many as one key per aspect)

EOAssociation defines the mechanism that transfers values between EODisplayGroups and the user interface of an application. An EOAssociation instance is tied to a single display object, a user interface object or other kind of object that manages values intended for display. The EOAssociation takes over certain outlets of the display object and sets its value according to the selection in the EODisplayGroup. An EOAssociation also has various aspects, which define the different parameters of the display object that it controls, such as the value or values displayed and whether the display object is enabled or editable. Each aspect can be bound to an EODisplayGroup with a key denoting a property of the enterprise objects in the EODisplayGroup. The value or values of this property determine the value for the EOAssociation's aspect.

EOAssociation is an abstract class, defining only the general mechanism for binding display objects to EODisplayGroups. You always create instances of its various subclasses, which define behavior specific to different kinds of display objects. For information on the different EOAssociation subclasses you can use, see the following subclass specifications:

com.webobjects.eointerface.cocoa

EOCocoaButtonPlugin	EOCocoaSimpleTextPlugin
EOCocoaCheckBoxPlugin	EOCocoaTableColumnPlugin
EOCocoaComboBoxPlugin	EOCocoaTableViewPlugin
EOCocoaImageViewPlugin	EOCocoaTextFieldPlugin
EOCocoaPopUpButtonPlugin	EOCocoaTextPlugin
EOCocoaRadioMatrixPlugin

com.webobjects.eointerface.swing

EOSwingButtonPlugin	EOSwingQuickTimeViewPlugin
EOSwingCheckBoxPlugin	EOSwingTableColumnPlugin
EOSwingComboBoxPlugin	EOSwingTablePlugin
EOSwingImageViewPlugin	EOSwingTextPlugin

You normally set up EOAssociations using Interface Builder. Each of the class specifications for EOAssociation's subclasses provide an example using Interface Builder to set them up. EOAssociation's programmatic interface is more important when defining custom EOAssociation subclasses.

Constants EOAssociation defines the following String constants to identify the names of association aspects:

ActionAspect	NullAspectSignature
ArgumentAspect	ParentAspect
AttributeAspectSignature	SelectedIndexAspect
AttributeToManyAspectSignature	SelectedObjectAspect
AttributeToOneAspectSignature	SelectedTitleAspect
AttributeToOneToManyAspectSignature	SourceAspect
BackgroundColorAspect	TextColorAspect
BoldAspect	TitlesAspect
DestinationAspect	ToManyAspectSignature
EnabledAspect	ToOneAspectSignature
ItalicAspect	ToOneToManyAspectSignature
MatchKey1Aspect	URLAspect
MatchKey2Aspect	ValueAspect
MatchKey3Aspect

Field Summary

static String	ActionAspect String value of the Action aspect
static String	ArgumentAspect String value of the Argument aspect
static String	AttributeAspectSignature String signature of a Attribute aspect.
static String	AttributeToManyAspectSignature String signature of a Attribute To Many aspect.
static String	AttributeToOneAspectSignature String signature of a Attribute To One aspect.
static String	AttributeToOneToManyAspectSignature String signature of a Attribute To One To Many aspect.
static String	BackgroundColorAspect String value of the Background Color aspect
static String	BoldAspect String value of the Bold aspect
static String	ChildrenAspect String value of the Children aspect
static String	DestinationAspect String value of the Destination aspect
static String	EnabledAspect String value of the Enabled aspect
static String	ExpandedIconAspect String value of the ExpandedIconAspect aspect
static String	IconAspect String value of the IconAspect aspect
static int	IgnoreValue Used to indicate that an aspect value has not been set to a usable value.
static String	IsLeafAspect String value of the IsLeaf aspect
static String	ItalicAspect String value of the Italic aspect
static String	MatchKey1Aspect String value of the MatchKey1 aspect
static String	MatchKey2Aspect String value of the MatchKey2 aspect
static String	MatchKey3Aspect String value of the MatchKey3 aspect
static String	NullAspectSignature String signature of a Null aspect.
static String	ParentAspect String value of the Parent aspect
static String	RootAspect String value of the Root aspect
static String	SelectedIndexAspect String value of the Selected Index aspect
static String	SelectedObjectAspect String value of the Selected Object aspect
static String	SelectedTitleAspect String value of the Selected Title aspect
static int	SetValue Used to indicate that an aspect value has been set to a true/enabled value.
static String	SourceAspect String value of the Source aspect
static String	TextColorAspect String value of the Text Color aspect
static String	TitlesAspect String value of the Titles aspect
static String	ToManyAspectSignature String signature of a To Many aspect.
static String	ToOneAspectSignature String signature of a To One aspect.
static String	ToOneToManyAspectSignature String signature of a To One To Many Aspect aspect.
static int	UnsetValue Used to indicate that an aspect value has been set to a false/inactive value.
static String	URLAspect String value of the URL aspect
static String	ValueAspect String value of the Value aspect

Fields inherited from class com.webobjects.eocontrol.EODelayedObserver

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

Constructor Summary

EOAssociation(Object object)
Used by subclasses of EOAssociation to initialize data structures and set aDisplayObject as the display object that the association manages.

Method Summary

NSArray	aspects() Overridden by subclasses to return the names of the receiving class's aspects as an array of string objects.
NSArray	aspectSignatures() Overridden by subclasses to return the signatures of the receiver's aspects, an array of string objects matching its aspects array index for index.
static NSArray	associationClassesForObject(Object object) Finds all EOAssociation subclasses that can be used with the specified display object.
void	bindAspect(String aspect, EODisplayGroup displayGroup, String key) Defines the receiver's link between its display object and an EODisplayGroup.
void	breakConnection() Removes the receiver from its EODisplayGroup and display object.
void	copyMatchingBindingsFromAssociation(EOAssociation source) Binds this association's aspects to the same display group(s) as the source EOAssociation.
EODisplayGroup	displayGroupForAspect(String aspect)
String	displayGroupKeyForAspect(String aspect)
void	dispose() Clears all references this association has to other objects, especially its display object and EODisplayGroup.
boolean	endEditing() Overridden by subclasses to pass the value of the receiver's display object to the EODisplayGroup, by invoking setValueForAspect with the display object's value and the appropriate aspect (typically value).
void	establishConnection() Overridden by subclasses to attach this association to the outlets of its display object and to otherwise configure the display object (such as by setting its action method).
boolean	isConnected() Checks whether or not the association is connected and ready for use.
protected boolean	isEnabled()
protected boolean	isEnabledAtIndex(int index)
boolean	isExplicitlyDisabled()
boolean	isUsableWithObject(Object object) Overridden by subclasses to return whether or not the recieving instance will work with anObject.
Object	object() Returns the receiver's display object.
NSArray	objectKeysTaken() Overridden by subclasses to return the names of display object outlets that instances assume control of.
String	primaryAspect() Overridden by subclasses to return the default aspect, usually one denoting the displayed value, which by convention is named "value".
int	priority() Returns the receiver's change notification priority.
static void	registerAssociationClass(Class associationClass) Registers associationClass with the EOAssociation class map.
void	setExplicitlyDisabled(boolean flag) Sets according to flag whether or not the association is explicitly disabled.
void	setObject(Object object) Sets aDisplayObject to be the display object that the association manages.
boolean	setValueForAspect(Object value, String aspect) Sets value in the selected enterprise object in the EODisplayGroup bound to aspect.
boolean	setValueForAspectAtIndex(Object value, String aspect, int index) Sets a value of the enterprise object at index in the EODisplayGroup bound to aspect.
boolean	shouldEndEditing(String aspect, String invalidInput, String errorDescription) Invoked by subclasses when the display object fails to validate its input, this method informs the EODisplayGroup bound to aspect with an associationFailedToValidateValue message, using the display group's selected object.
boolean	shouldEndEditingAtIndex(String aspect, String invalidInput, String errorDescription, int index) Works in the same manner as shouldEndEditing, but allows you to specify a particular object by index rather than implicitly specifying the selected object.
void	subjectChanged() Overridden by subclasses to update state based on when an EODisplayGroup's selection or contents changes.
Object	valueForAspect(String aspect) Returns a value of the selected enterprise object in the EODisplayGroup bound to aspect.
Object	valueForAspectAtIndex(String aspect, int index) Returns a value of the enterprise object at index in the EODisplayGroup bound to aspect.

Methods inherited from class com.webobjects.eocontrol.EODelayedObserver

discardPendingNotification, objectWillChange, observerQueue

Methods inherited from class java.lang.Object

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

Field Detail

ActionAspect

public static final String ActionAspect

String value of the Action aspect

ArgumentAspect

public static final String ArgumentAspect

String value of the Argument aspect

AttributeAspectSignature

public static final String AttributeAspectSignature

String signature of a Attribute aspect.

AttributeToManyAspectSignature

public static final String AttributeToManyAspectSignature

String signature of a Attribute To Many aspect.

AttributeToOneAspectSignature

public static final String AttributeToOneAspectSignature

String signature of a Attribute To One aspect.

AttributeToOneToManyAspectSignature

public static final String AttributeToOneToManyAspectSignature

String signature of a Attribute To One To Many aspect.

BackgroundColorAspect

public static final String BackgroundColorAspect

String value of the Background Color aspect

BoldAspect

public static final String BoldAspect

String value of the Bold aspect

ChildrenAspect

public static final String ChildrenAspect

String value of the Children aspect

DestinationAspect

public static final String DestinationAspect

String value of the Destination aspect

EnabledAspect

public static final String EnabledAspect

String value of the Enabled aspect

ExpandedIconAspect

public static final String ExpandedIconAspect

String value of the ExpandedIconAspect aspect

IconAspect

public static final String IconAspect

String value of the IconAspect aspect

IgnoreValue

public static int IgnoreValue

Used to indicate that an aspect value has not been set to a usable value.

IsLeafAspect

public static final String IsLeafAspect

String value of the IsLeaf aspect

ItalicAspect

public static final String ItalicAspect

String value of the Italic aspect

MatchKey1Aspect

public static final String MatchKey1Aspect

String value of the MatchKey1 aspect

MatchKey2Aspect

public static final String MatchKey2Aspect

String value of the MatchKey2 aspect

MatchKey3Aspect

public static final String MatchKey3Aspect

String value of the MatchKey3 aspect

NullAspectSignature

public static final String NullAspectSignature

String signature of a Null aspect.

ParentAspect

public static final String ParentAspect

String value of the Parent aspect

RootAspect

public static final String RootAspect

String value of the Root aspect

SelectedIndexAspect

public static final String SelectedIndexAspect

String value of the Selected Index aspect

SelectedObjectAspect

public static final String SelectedObjectAspect

String value of the Selected Object aspect

SelectedTitleAspect

public static final String SelectedTitleAspect

String value of the Selected Title aspect

SetValue

public static int SetValue

Used to indicate that an aspect value has been set to a true/enabled value.

SourceAspect

public static final String SourceAspect

String value of the Source aspect

TextColorAspect

public static final String TextColorAspect

String value of the Text Color aspect

TitlesAspect

public static final String TitlesAspect

String value of the Titles aspect

ToManyAspectSignature

public static final String ToManyAspectSignature

String signature of a To Many aspect.

ToOneAspectSignature

public static final String ToOneAspectSignature

String signature of a To One aspect.

ToOneToManyAspectSignature

public static final String ToOneToManyAspectSignature

String signature of a To One To Many Aspect aspect.

URLAspect

public static final String URLAspect

String value of the URL aspect

UnsetValue

public static int UnsetValue

Used to indicate that an aspect value has been set to a false/inactive value.

ValueAspect

public static final String ValueAspect

String value of the Value aspect

Constructor Detail

EOAssociation

public EOAssociation(Object object)

Used by subclasses of EOAssociation to initialize data structures and set aDisplayObject as the display object that the association manages.

Parameters:

aDisplayObject - display object for this association. to manage; subclasses should call their super class's constructor and pass in aDisplayObject

Method Detail

aspectSignatures

public NSArray aspectSignatures()

Overridden by subclasses to return the signatures of the receiver's aspects, an array of string objects matching its aspects array index for index. The signature strings can be any of:

Constant	The Aspect Can Be Bound to
AttributeAspectSignature	Attributes
AttributeToOneAspectSignature	Attributes and to-one relationships
AttributeToManyAspectSignature	Attributes and to-many relationships
AttributeToOneToManyAspectSignature	Attributes, to-one relationships, and to-many relationships
ToOneAspectSignature	To-one relationships
ToOneToManyAspectSignature	To-one and to-many relationships
ToManyAspectSignature	To-many relationships
NullAspectSignature	An EODisplayGroup without a key (the key is irrelevant)

Interface Builder uses aspect signatures to enable and disable keys in its Connections inspectors.

Returns:

an array of AttributeToOneToManyAspectSignature strings

aspects

public NSArray aspects()

Overridden by subclasses to return the names of the receiving class's aspects as an array of string objects. Subclasses should include their superclass's aspects and add their own when overriding this method.

Returns:

an NSArray of named aspects as string objects

associationClassesForObject

public static NSArray associationClassesForObject(Object object)

Finds all EOAssociation subclasses that can be used with the specified display object.

Parameters:

anObject - display object to attempt to find a matching EOAssociation for

Returns:

an NSArray of Class objects that can be used as an association for anObject

bindAspect

public void bindAspect(String aspect,
                       EODisplayGroup displayGroup,
                       String key)

Defines the receiver's link between its display object and an EODisplayGroup. Binds aspect to key in displayGroup. Passing a null key unbinds the aspect, and attempting to bind an invalid aspect or one of a connected Association throws an exception. Invoke establishConnection after this method to finish setting up the binding.

Parameters:

aspect - name of the aspect it observes in its display object

displayGroup - EODisplayGroup that will be the target of this binding

key - name of the property it observes in aEODisplayGroup

breakConnection

public void breakConnection()

Removes the receiver from its EODisplayGroup and display object. Subclasses should override this method to remove the receiver from any outlets of the display object and invoke super's implementation at the end.

copyMatchingBindingsFromAssociation

public void copyMatchingBindingsFromAssociation(EOAssociation source)

Binds this association's aspects to the same display group(s) as the source EOAssociation. This method only binds aspects that occur both in this association and in the source association.

Parameters:

source - EOAssociation object to use as the source for bindings to copy; source should not be null

displayGroupForAspect

public EODisplayGroup displayGroupForAspect(String aspect)

Parameters:

aspect - name of aspect of interest

Returns:

the EODisplayGroup bound to the receiver for aspect, or null if there is no such object

See Also:

displayGroupKeyForAspect(java.lang.String)

displayGroupKeyForAspect

public String displayGroupKeyForAspect(String aspect)

Parameters:

aspect - name of aspect of interest

Returns:

the EODisplayGroup key bound to the receiver for aspect, or null if there's no EODisplayGroup

See Also:

displayGroupForAspect(java.lang.String)

dispose

public void dispose()

Clears all references this association has to other objects, especially its display object and EODisplayGroup. Call this method before nulling out a reference to this association to ensure it gets garbage collected properly.

Subclasses should override this method to do any additional cleanup that may be needed and invoke super's implementation at the end.

Specified by:

dispose in interface NSDisposable

See Also:

NSDisposable

endEditing

public boolean endEditing()

Overridden by subclasses to pass the value of the receiver's display object to the EODisplayGroup, by invoking setValueForAspect with the display object's value and the appropriate aspect (typically value). Subclasses whose display objects immediately pass their changes back to the EOAssociation (such as a button or pop-up list) need not override this method. It's only needed when the display object's value is edited rather than simply set.

Returns:

default implementation returns true

establishConnection

public void establishConnection()

Overridden by subclasses to attach this association to the outlets of its display object and to otherwise configure the display object (such as by setting its action method). The default implementation subscribes this association as an observer of its EODisplayGroups. Subclasses should invoke super's implementation after establishing their own connections.

Throws:

IllegalStateException - if the association has no display object

isConnected

public boolean isConnected()

Checks whether or not the association is connected and ready for use.

Returns:

true if connected, false if not

isEnabled

protected boolean isEnabled()

Returns:

false if this association has explicitly disabled its display object or if this association's enabled aspect (if bound) resolves to false; true otherwise

isEnabledAtIndex

protected boolean isEnabledAtIndex(int index)

Parameters:

index - index of object in the EODisplayGroup of the enabled aspect's binding

Returns:

false if this association has explicitly disabled its display object or if this association's enabled aspect (if bound) resolves to false for index; true otherwise.

isExplicitlyDisabled

public boolean isExplicitlyDisabled()

Returns:

true if the receiver has explicitly disabled its display object, false otherwise

isUsableWithObject

public boolean isUsableWithObject(Object object)

Overridden by subclasses to return whether or not the recieving instance will work with anObject. The receiver can examine any relevant characteristic of anObject such as its class, configuration (such as whether an NSMatrix operates in radio mode), and so on.

Parameters:

anObject - object to examine for usability with the association

Returns:

true if the receiver is usable with anObject, false otherwise, default implementation always returns false

object

public Object object()

Returns the receiver's display object.

Returns:

the display object of the association

objectKeysTaken

public NSArray objectKeysTaken()

Overridden by subclasses to return the names of display object outlets that instances assume control of. Interface Builder uses this information to disable connections from these outlets in its Connections Inspector.

Returns:

an empty NSArray

primaryAspect

public String primaryAspect()

Overridden by subclasses to return the default aspect, usually one denoting the displayed value, which by convention is named "value". EOAssociation's implementation returns null.

Returns:

default implementation returns null

priority

public int priority()

Returns the receiver's change notification priority. For more information, see the EODelayedObserver class specification (EOControl).

Overrides:

priority in class EODelayedObserver

Returns:

ObserverPriorityThird.

registerAssociationClass

public static void registerAssociationClass(Class associationClass)

Registers associationClass with the EOAssociation class map. Once an association class is registered, using the correct object argument, it can be found by the associationClassesForObject method.

Parameters:

associationClass - the EOAssociation subclass to register

Throws:

an - IllegalArgumentException if associationClass is null or not a subclass of EOAssociation

setExplicitlyDisabled

public void setExplicitlyDisabled(boolean flag)

Sets according to flag whether or not the association is explicitly disabled. An association is "explicitly disabled" when the display object shouldn't be editable, such as in the case where the display object simply displays the results of a search.

Parameters:

flag - if true, then the association is explicitly disabled should ignore edits from its display object and/or set the display object to be not editable if possible.

setObject

public void setObject(Object object)

Sets aDisplayObject to be the display object that the association manages.

Parameters:

aDisplayObject - the object for the association to manage

Throws:

an - IllegalStateException if the association is already connected when this method is invoked. Throws an IllegalArgumentException if aDisplayObject is not usable with the association (if isUsableWithObject returns false).

setValueForAspect

public boolean setValueForAspect(Object value,
                                 String aspect)

Sets value in the selected enterprise object in the EODisplayGroup bound to aspect. Retrieves the display group and key bound to aspect, and sends the display group a setSelectedObjectValue message with value and the key as arguments.

Parameters:

value - value to set in the selected object of the association's display group

aspect - key for which the association's display group is bound

Returns:

true if successful, or if there's no display group bound to aspect; false if there's an display group and it doesn't accept the new value

See Also:

valueForAspect(java.lang.String)

setValueForAspectAtIndex

public boolean setValueForAspectAtIndex(Object value,
                                        String aspect,
                                        int index)

Sets a value of the enterprise object at index in the EODisplayGroup bound to aspect. Retrieves the display group and key bound to aspect, and sends the display group a setValueForObjectAtIndex message with value, index, and the key as arguments.

Parameters:

value - value to set in the selected object of the association's display group

aspect - key for which the association's display group is bound

index - index of the object in the association's display group to set value on

Returns:

true if successful, or if there's no display group bound to aspect; false if there's an display group and it doesn't accept the new value.

See Also:

valueForAspectAtIndex(java.lang.String, int)

shouldEndEditing

public boolean shouldEndEditing(String aspect,
                                String invalidInput,
                                String errorDescription)

Invoked by subclasses when the display object fails to validate its input, this method informs the EODisplayGroup bound to aspect with an associationFailedToValidateValue message, using the display group's selected object. Returns the result of that message, or true if there's no display group.

For example, an association's plugin bound to an NSControl object (Cocoa) receives a controlDidFailToFormatStringErrorDescription delegate message when the control's formatter fails to format the input string. Its implementation of that method invokes shouldEndEditing.

Parameters:

aspect - key for which the association is bound to its display group

inputString - the String value of the invalid input

errorDescription - description of the validation error

Returns:

the result of displayGroup.associationFailedToValidateValue or true if there is no display group

shouldEndEditingAtIndex

public boolean shouldEndEditingAtIndex(String aspect,
                                       String invalidInput,
                                       String errorDescription,
                                       int index)

Works in the same manner as shouldEndEditing, but allows you to specify a particular object by index rather than implicitly specifying the selected object.

Parameters:

aspect - key for which the association is bound to its display group

inputString - the String value of the invalid input

errorDescription - description of the validation error

index - index of object in the association's display group on which value could not be set

Returns:

the result of displayGroup.associationFailedToValidateValue or true if there is no display group.

subjectChanged

public void subjectChanged()

Overridden by subclasses to update state based on when an EODisplayGroup's selection or contents changes. This method is invoked automatically anytime a display group that's bound to the receiver changes. The receiver can query its display group with selectionChanged and contentsChanged messages to determine how it needs to update.

Overrides:

subjectChanged in class EODelayedObserver

valueForAspect

public Object valueForAspect(String aspect)

Returns a value of the selected enterprise object in the EODisplayGroup bound to aspect. Retrieves the display group and key bound to aspect and sends the display group a selectedObjectValueForKey message with the key.

Parameters:

aspect - key with which the association is bound to its display group

Returns:

null if there is no display group or key bound to aspect

See Also:

setValueForAspect(java.lang.Object, java.lang.String)

valueForAspectAtIndex

public Object valueForAspectAtIndex(String aspect,
                                    int index)

Returns a value of the enterprise object at index in the EODisplayGroup bound to aspect. Retrieves the display group and key bound to aspect, and sends the display group a valueForObjectAtIndex message with index and the key.

Parameters:

index - index of object in the association's display group from which to get a value

aspect - key with which the association is bound to its display group

Returns:

null if there is no display group or key bound to aspect

See Also:

setValueForAspectAtIndex(java.lang.Object, java.lang.String, int)