WebObjects 5.2

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:


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
EOCocoaButtonPluginEOCocoaSimpleTextPlugin
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:
ActionAspectNullAspectSignature
ArgumentAspectParentAspect
AttributeAspectSignatureSelectedIndexAspect
AttributeToManyAspectSignatureSelectedObjectAspect
AttributeToOneAspectSignatureSelectedTitleAspect
AttributeToOneToManyAspectSignatureSourceAspect
BackgroundColorAspectTextColorAspect
BoldAspectTitlesAspect
DestinationAspectToManyAspectSignature
EnabledAspectToOneAspectSignature
ItalicAspectToOneToManyAspectSignature
MatchKey1AspectURLAspect
MatchKey2AspectValueAspect
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)

Last updated Fri Feb 21 13:15:00 PST 2003.

Copyright © 2003 Apple Computer, Inc.