PATH Documentation > WebObjects 4.5 > EOInterface Reference

EOAssociation

Inherits from:
(com.apple.client.eointerface) EODelayedObserver (EOControl) : Object
(com.apple.yellow.eointerface) EODelayedObserver (EOControl) : NSObject

Implements:
EOObserving (EODelayedObserver)

(com.apple.client.eointerface only) NSDisposable

Package:
com.apple.client.eointerface

com.apple.yellow.eointerface

Class at a Glance

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)

Class Description

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.apple.client.eointerface Associations
EOActionAssociation	EOActionInsertionAssociation
EOComboBoxAssociation	EOMasterDetailAssociation
EOTableAssociation	EOTableColumnAssociation
EOTableViewAssociation	EOTextAssociation

com.apple.yellow.eointerface Associations
EOActionAssociation	EOActionCellAssociation
EOActionInsertionAssociation	EOColumnAssociation
EOComboBoxAssociation	EOControlAssociation
EODetailSelectionAssociation	EOGenericControlAssociation
EOMasterCopyAssociation	EOMasterDetailAssociation
EOMasterPeerAssociation	EOMatrixAssociation
EOPickTextAssociation	EOPopUpAssociation
EORadioMatrixAssociation	EORecursiveBrowserAssociation
EOTableViewAssociation	EOTextAssociation

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. For more information on EOAssociations, see the sections:

Constants

(com.apple.client.eointerface only) EOAssociation defines the following String constants to identify the names of association aspects:

`ActionAspect`	`EnabledAspect`	`SourceAspect`
`ArgumentAspect`	`ParentAspect`	`TitlesAspect`
`BoldAspect`	`SelectedObjectAspect`	`ValueAspect`
`DestinationAspect`	`SelectedTitleAspect`	`URLAspect`
`ItalicAspect`

(com.apple.client.eointerface only) The class defines additional String constants to identify association signatures (see the method description aspectSignatures for more information):

`AttributeAspectSignature`	`NullAspectSignature`
`AttributeToOneAspectSignature`	`ToOneAspectSignature`
`AttributeToOneToManyAspectSignature`	`ToOneToManyAspectSignature`
`AttributeToManyAspectSignature`	`ToManyAttributeSignature`

Interfaces Implemented

NSDisposable
dispose

Method Types

Declaring capabilities

aspects (com.apple.yellow.eointerface static method)

aspects (com.apple.client.eointerface instance method)

aspectSignatures (com.apple.yellow.eointerface static method)

aspectSignatures (com.apple.client.eointerface instance method)

objectKeysTaken (com.apple.yellow.eointerface)

isUsableWithObject (com.apple.yellow.eointerface static method)

isUsableWithObject (com.apple.client.eointerface instance method)

associationClassesSuperseded (com.apple.yellow.eointerface static method)

associationClassesSuperseded (com.apple.client.eointerface instance method)

displayName (com.apple.yellow.eointerface static method)

displayName (com.apple.client.eointerface instance method)

primaryAspect (com.apple.yellow.eointerface static method)

primaryAspect (com.apple.client.eointerface instance method)

canBindAspect

Getting all possible EOAssociations for a display object

associationClassesForObject:

Getting the display object

object

Examining bindings

displayGroupForAspect

displayGroupKeyForAspect

Updating values

subjectChanged

endEditing

Accessing enterprise object values

setValueForAspect

setValueForAspectAtIndex

valueForAspect

valueForAspectAtIndex

Handling validation errors

shouldEndEditing

shouldEndEditingAtIndex

Constructors

EOAssociation

public EOAssociation(Object aDisplayObject)

Never use this method to create an EOAssociation. EOAssociation is conceptually an abstract class, and you'd never use instances of it. Instead, use subclasses of EOAssociation. Instances of the subclasses can be created programmatically with a constructor of this same form. For more information, see the constructor description for the subclass you want to use. For a list of the subclasses, see the "Class Description".

Static Methods

aspects

public static NSArray aspects()

(com.apple.yellow.eointerface only) 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.

See Also: aspects instance method

aspectSignatures

public static NSArray aspectSignatures()

(com.apple.yellow.eointerface only) Overridden by subclasses to return the signatures of the receiver's aspects, an array of string objects matching its aspects array index for index. Each signature string can contain the following characters:

Signature Character	Meaning
A	The aspect can be bound to attributes.
1 (one)	The aspect can be bound to to-one relationships.
M	The aspect can be bound to to-many relationships.

An aspect signature string of "A1", for example, means the corresponding aspect can be bound to either attributes or to-one relationships. An empty signature indicates that the corresponding aspect can be bound to an EODisplayGroup without a key (that is, the key is irrelevant). Interface Builder uses aspect signatures to enable and disable keys in its Connections inspectors.

EOAssociation's implementation of this method returns an array of "A1M" of the length of its aspects array.

See Also: aspectSignatures instance method

associationClassesForObject:

public static NSArray associationClassesForObject(Object aDisplayObject)

Returns the subclasses of EOAssociation usable with aDisplayObject. Sends isUsableWithObject to every loaded subclass of EOAssociation, adding those that respond true to the array. Subclasses shouldn't override this method; override isUsableWithObject instead.

associationClassesSuperseded

public static NSArray associationClassesSuperseded()

(com.apple.yellow.eointerface only) Overridden by subclasses to return the other EOAssociation classes that the receiver supplants. This allows a subclass to mask its superclasses from the Connection Inspector's pop-up list in Interface Builder, since the subclass always includes the aspects and functionality of its superclasses. For example, EOPopUpAssociation supersedes EOControlAssociation, because EOPopUpAssociation is always more appropriate to use with pop-up buttons.

See Also: associationClassesSuperseded instance method

displayName

public static String displayName()

(com.apple.yellow.eointerface only) Returns the name used by Interface Builder in the Connection Inspector's pop-up list. EOAssociation's implementation simply returns the name of the receiving class.

See Also: displayName instance method

isUsableWithObject

public static boolean isUsableWithObject(Object aDisplayObject)

(com.apple.yellow.eointerface only) Overridden by subclasses to return true if instances of the receiving class are usable with aDisplayObject, false if they aren't. The receiving class can examine any relevant characteristic of aDisplayObject -its class, configuration (such as whether an NSMatrix operates in radio mode), and so on.

See Also: isUsableWithObject instance method

objectKeysTaken

public static NSArray objectKeysTaken()

(com.apple.yellow.eointerface only) Overridden by subclasses to return the names of display object outlets that instances assume control of, such as "target" and "delegate". Interface Builder uses this information to disable connections from these outlets in its Connections Inspector.

See Also: objectKeysTaken instance method

primaryAspect

public static String primaryAspect()

(com.apple.yellow.eointerface only) 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.

See Also: primaryAspect instance method

Instance Methods

aspects

public NSArray aspects()

(com.apple.client.eointerface only) Overridden by subclasses to return the names of the receiving class's aspects, as string objects. Subclasses should include their superclass's aspects and add their own when overriding this method.

See Also: aspects static method

aspectSignatures

public NSArray aspectSignatures()

(com.apple.client.eointerface only) 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
ToManyAttributeSignature	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.

EOAssociation's implementation of this method returns an array of AttributeToOneToManyAspectSignature strings.

See Also: aspectSignatures static method

associationClassesSuperseded

public NSArray associationClassesSuperseded()

(com.apple.client.eointerface only) Overridden by subclasses to return the other EOAssociation classes that the receiver supplants. This allows a subclass to mask its superclasses from the Connection Inspector's pop-up list in Interface Builder, since the subclass always includes the aspects and functionality of its superclasses. For example, EOPopUpAssociation supersedes EOControlAssociation, because EOPopUpAssociation is always more appropriate to use with pop-up buttons.

See Also: associationClassesSuperseded static method

bindAspect

public void bindAspect( String aspectName, EODisplayGroup aDisplayGroup, String key)

Defines the receiver's link between its display object and aDisplayGroup. aspectName is the name of the aspect it observer in its display object, and key is the name of the property it observes in aDisplayGroup. Invoke establishConnection after this method to finish setting up the binding. See "Setting up an EOAssociation Programmatically" in the class description for more information.

See Also: establishConnection

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.

See Also: establishConnection

canBindAspect

public boolean canBindAspect( String aspectName, EODisplayGroup aDisplayGroup, String key)

Overridden by subclasses to return true if the receiver can tie an aspect named aspectName from its display object to the property identified by key in aDisplayGroup, false if it can't. aspectName should name an aspect supported by the receiver's class.

Interface Builder uses this information to disable aspects in its Connections Inspector. Subclasses can override this method to base their answers on other binds already made, or on characteristics of the receiver's display object or of aDisplayGroup. EOAssociation's implementation always returns true.

See Also: localKeys (EODisplayGroup), attributeKeys (EOClassDescription), toOneRelationshipKeys (EOClassDescription), toManyRelationshipKeys (EOClassDescription)

copyMatchingBindingsFromAssociation

public void copyMatchingBindingsFromAssociation(EOAssociation anAssociation)

Duplicates the bindings of anAssociation in the receiver. For each aspect of anAssociation that has an EODisplayGroup, invokes bindAspect with the EODisplayGroup and key for that aspect.

displayGroupForAspect

public EODisplayGroup displayGroupForAspect(String aspectName)

Returns the EODisplayGroup bound to the receiver for aspectName, or null if there's no such object.

See Also: displayGroupKeyForAspect

displayGroupKeyForAspect

public String displayGroupKeyForAspect(String aspectName)

Returns the EODisplayGroup key bound to the receiver for aspectName, or null if there's no EODisplayGroup.

See Also: displayGroupForAspect

displayName

public String displayName()

(com.apple.client.eointerface only) Returns the name used for display purposes. EOAssociation's implementation simply returns the name of the receiver's class.

See Also: displayName static method

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"). Returns true if successful, false if not-specifically if setValueForAspect returns false. The receiver should also send an associationDidEndEditing: message to its EODisplayGroup.

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.

EOAssociation's implementation does nothing but return true.

establishConnection

public void establishConnection()

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

See "Setting up an EOAssociation Programmatically" in the class description for more information.

See Also: breakConnection

isEnabled

protected boolean isEnabled()

(com.apple.client.eointerface only) Returns false if the receiver has explicitly disabled its display object or if the receiver's EnabledAspect (if bound) resolves to false; true otherwise.

isEnabledAtIndex

protected boolean isEnabledAtIndex(int index)

(com.apple.client.eointerface only) Returns false if the receiver has explicitly disabled its display object or if the receiver's EnabledAspect (if bound) resolves to false for index; true otherwise.

isExplicitlyDisabled

public boolean isExplicitlyDisabled()

(com.apple.client.eointerface only) Returns true if the receiver has explicitly disabled its display object, false otherwise.

isUsableWithObject

public boolean isUsableWithObject(Object aDisplayObject)

(com.apple.client.eointerface only) Overridden by subclasses to return true if instances of the receiving class are usable with aDisplayObject, false if they aren't. The receiving class can examine any relevant characteristic of aDisplayObject -its class, configuration, and so on. EOAssociation's implementation returns false.

See Also: isUsableWithObject static method

object

public Object object()

Returns the receiver's display object.

objectKeysTaken

public NSArray objectKeysTaken()

(com.apple.client.eointerface only) 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.

See Also: objectKeysTaken static method

primaryAspect

public String primaryAspect()

(com.apple.client.eointerface only) 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.

See Also: primaryAspect static method

priority

public int priority()

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

setAutoCreated

public void setAutoCreated(boolean aBoolean)

(com.apple.client.eointerface only) This method is provided for internal use and is intentionally undocumented. You should never need to invoke or customize this method.

setExplicitlyDisabled

public void setExplicitlyDisabled(boolean flag)

(com.apple.client.eointerface only) Sets according to flag whether or not the association is explicitly disabled. This method and its counterpart isExplicitlyDisabled are used by objects in the com.apple.client.eoapplication and com.apple.client.eogeneration packages for Direct to Java Client applications. 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.

setValueForAspect

public boolean setValueForAspect( Object value, String aspectName)

Sets a value of the selected enterprise object in the EODisplayGroup bound to aspectName. Retrieves the display group and key bound to aspectName, and sends the display group a setSelectedObjectValue message with value and the key as arguments. Returns true if successful, or if there's no display group bound to aspectName. Returns false if there's an display group and it doesn't accept the new value.

See Also: valueForAspect

setValueForAspectAtIndex

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

Sets a value of the enterprise object at index in the EODisplayGroup bound to aspectName. Retrieves the display group and key bound to aspectName, and sends the display group a setValueForObjectAtIndex message with value, index, and the key as arguments. Returns true if successful, or if there's no display group bound to aspectName. Returns false if there's a display group and it doesn't accept the new value.

See Also: valueForAspectAtIndex

shouldEndEditing

public boolean shouldEndEditing( String aspectName, String inputString, String errorDescription)

Invoked by subclasses when the display object fails to validate its input, this method informs the EODisplayGroup bound to aspectName 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 bound to an NSControl object (Application Kit) receives a controlDidFailToFormatStringErrorDescription delegate message when the control's formatter fails to format the input string. Its implementation of that method invokes shouldEndEditing.

See Also: shouldEndEditingAtIndex

shouldEndEditingAtIndex

public boolean shouldEndEditingAtIndex( String aspectName, String inputString, 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.

subjectChanged

public void subjectChanged()

Overridden by subclasses to update state based 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.

valueForAspect

public Object valueForAspect(String aspectName)

Returns a value of the selected enterprise object in the EODisplayGroup bound to aspectName. Retrieves the display group and key bound to aspectName, and sends the display group a selectedObjectValueForKey message with the key. Returns null if there's no display group or key bound to aspectName.

See Also: setValueForAspect

valueForAspectAtIndex

public Object valueForAspectAtIndex( String aspectName, int index)

Returns a value of the enterprise object at index in the EODisplayGroup bound to aspectName. Retrieves the display group and key bound to aspectName, and sends the display group a valueForObjectAtIndex message with index and the key. Returns null if there's no display group or key bound to aspectName.

See Also: setValueForAspectAtIndex