com.webobjects.appserver
Class WODisplayGroup

java.lang.Object
  |
  +--com.webobjects.appserver.WODisplayGroup

All Implemented Interfaces:

EOKeyValueArchiving, EOKeyValueArchiving.Awaking, NSDisposable, NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, Serializable

public class WODisplayGroup

extends Object

implements NSKeyValueCoding, NSKeyValueCoding.ErrorHandling, NSDisposable, EOKeyValueArchiving, EOKeyValueArchiving.Awaking, Serializable

A WODisplayGroup is the basic user interface manager for a WebObjects application that accesses a database. It collects objects from an EODataSource, filters and sorts them, and maintains a selection in the filtered subset. WebObjects dynamic elements are bound to WODisplayGroup attributes and methods to display information from the database on the web page.

A WODisplayGroup manipulates its EODataSource by invoking fetchObjects, insertObject and other methods, and registers itself as an editor and message handler of the EODataSource's EOEditingContext. The EOEditingContext then monitors the WODisplayGroup for changes to objects.

WODisplayGroup interacts mostly with its EODataSource and its EOEditingContext.

The WODisplayGroup delegate offers a number of methods, and WODisplayGroup invokes them as appropriate. Besides displayGroupDisplayArrayForObjects, there are methods that inform the delegate that the WODisplayGroup has fetched, created -- or failed to create -- an object, inserted or deleted an object, changed the selection, or set a value for a property. There are also methods that request permission from the delegate to perform most of these same actions. The delegate can return true to permit the action or false to deny it.

See Also:

EODataSource, EOEditingContext, WODisplayGroup.Delegate, WODisplayGroup.Delegate.displayGroupDisplayArrayForObjects(com.webobjects.appserver.WODisplayGroup, com.webobjects.foundation.NSArray), Serialized Form

Inner Class Summary

static interface

WODisplayGroup.Delegate The WODisplayGroup delegate offers a number of methods, and WODisplayGroup invokes them as appropriate.

Inner classes inherited from class com.webobjects.foundation.NSKeyValueCoding

NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.Null, NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.Utility, NSKeyValueCoding.ValueAccessor

Inner classes inherited from class com.webobjects.eocontrol.EOKeyValueArchiving

EOKeyValueArchiving.Awaking, EOKeyValueArchiving.FinishInitialization, EOKeyValueArchiving.Support

Field Summary

static String

DisplayGroupWillFetchNotification The name for the notification posted during any invocation of WODisplayGroup's fetch method.

Fields inherited from interface com.webobjects.foundation.NSKeyValueCoding

NullValue

Constructor Summary

WODisplayGroup()
Creates and returns a new WODisplayGroup.

Method Summary

NSArray	allObjects() Provides all of the objects collected by the WODisplayGroup.
NSArray	allQualifierOperators() Provides all of the EOQualifier operators plus those that work exclusively on Strings (such as like and contains).
void	awakeFromKeyValueUnarchiver(EOKeyValueUnarchiver unarchiver) Notifies the receiver that the EOKeyValueUnarchiver unarchiver has unarchived all objects from an archive.
int	batchCount() Provides the number of batches to display.
boolean	clearSelection() Clears the selection of any objects from allObjects.
int	currentBatchIndex() Provides the index of the batch currently being displayed.
EODataSource	dataSource() Provides the last EODataSource given to the WODisplayGroup via setDataSource.
static Object	decodeWithKeyValueUnarchiver(EOKeyValueUnarchiver unarchiver)
String	defaultStringMatchFormat() If a key in the queryMatch dictionary does not have an associated value in the queryOperator dictionary, then its value is matched using operator pattern matching, and the format string returned by this method specifies how it will be matched.
String	defaultStringMatchOperator() Provides a default operator for matching strings against string values in the queryMatch dictionary for the objects in the WODisplayGroup.
Object	delegate() Provides the last delegate object given to the WODisplayGroup via setDelegate.
Object	delete() Invokes deleteSelection and displayBatchContainingSelectedObject.
boolean	deleteObjectAtIndex(int anIndex) Deletes the object at anIndex in allObjects.
boolean	deleteSelection() Deletes the selectedObjects from the WODisplayGroup's dataSource.
String	detailKey() For detail display groups, returns the key to the master object that specifies what this detail display group represents.
Object	displayBatchContainingSelectedObject() Displays the batch containing the selection and sets the currentBatchIndex to that batch's index.
NSArray	displayedObjects() Provides the objects to be displayed or otherwise made available to the client (web browser).
Object	displayNextBatch() Increments the current batch index, displays that batch of objects, and clears the selection.
Object	displayPreviousBatch() Decrements the current batch index, displays that batch of objects, and clears the selection.
void	dispose() Invoked when the receiver should prepare itself for destruction.
void	editingContextPresentErrorMessage(EOEditingContext editingContext, String message) Deprecated. Use NSLog instead. No user code should implement or depend upon this.
void	encodeWithCoder(NSCoder coder)
void	encodeWithKeyValueArchiver(EOKeyValueArchiver archiver) Asks the receiver to archive its state into the EOKeyValueArchiver archiver.
boolean	endEditing() Deprecated. No longer important for WebObjects applications. No user code should depend upon this, and any references to this method may be eliminated freely.
Object	fetch() Invokes the fetchObjects method of the dataSource and passes the result to setObjectArray.
boolean	fetchesOnLoad() Indicates whether the WODisplayGroup, whenever it is loaded, should fetch from its dataSource.
protected void	finishInitialization() Invoked from the WODisplayGroup constructor to finish initializing a newly created instance.
static boolean	globalDefaultForValidatesChangesImmediately() Indicates the class default behavior controlling whether submitted changes are immediately validated.
static String	globalDefaultStringMatchFormat() Provides the default string match format for the class.
static String	globalDefaultStringMatchOperator() Provides the default string match operator for the class.
Object	handleQueryWithUnboundKey(String key) Invoked from valueForKey when it finds no property binding for key.
void	handleTakeValueForUnboundKey(Object value, String key) Invoked from takeValueForKey when it finds no property binding for key.
boolean	hasDetailDataSource() If a to-many relationship is dragged from EOModeler to an open component in WebObjects Builder, a display group is created that has an EODetailDataSource.
boolean	hasMultipleBatches() Indicates whether the WODisplayGroup paginates display, using batchCount.
int	indexOfFirstDisplayedObject() Provides the index into displayedObjects of the first object in the current batch.
int	indexOfLastDisplayedObject() Provides the index into displayedObjects of the last object in the current batch.
Object	initWithCoder(NSCoder coder)
boolean	inQueryMode() Deprecated. No longer important for WebObjects applications. No user code should implement or depend upon this, and any implementations or references to this method may be eliminated freely.
Object	insert() Invokes insertNewObjectAtIndex with an index just past the first index in the selection, or at the end if there's no selection.
NSDictionary	insertedObjectDefaultValues() Provides the dictionary of default values added to empty objects that are inserted into the WODisplayGroup's dataSource.
Object	insertNewObjectAtIndex(int newIndex) Invokes the createObject method of the dataSource and inserts the new object into the dataSource (and into allObjects at newIndex) using insertObjectAtIndex.
void	insertObjectAtIndex(Object createObject, int newIndex) Inserts createObject into the WODisplayGroup's dataSource and into allObjects and displayedObjects at newIndex, if possible.
NSArray	localKeys() Provides the additional keys to which WOAssociations may be bound for this WODisplayGroup.
Object	masterObject() Provides the master object for a detail display group (a display group that represents a detail in a master-detail relationship).
int	numberOfObjectsPerBatch() You can set the batch size using setNumberOfObjectsPerBatch or using WebObjects Builder's Display Group Options panel.
void	objectsChangedInEditingContext(NSNotification notification) Redisplays the changed objects in the WODisplayGroup.
void	objectsInvalidatedInEditingContext(NSNotification notification) Refetches all objects from the dataSource of the WODisplayGroup after some or all of them have been invalidated.
EOQualifier	qualifier() Provides the last qualifier given to the WODisplayGroup via setQualifier or qualifyDisplayGroup.
EOQualifier	qualifierFromQueryValues() Builds a qualifier constructed from entries in these query dictionaries: queryMatch, queryMax, queryMin, and queryOperator.
void	qualifyDataSource() Takes the result of qualifierFromQueryValues and applies to the WODisplayGroup's data source.
void	qualifyDisplayGroup() Takes the result of the qualifierFromQueryValues and applies it to the WODisplayGroup using setQualifier.
NSMutableDictionary	queryBindings() You use this method to perform a query stored in the EOModel file.
NSMutableDictionary	queryMatch() The qualifierFromQueryValues method uses this dictionary along with the queryMax and queryMin dictionaries to construct qualifiers.
NSMutableDictionary	queryMax() Provides a dictionary of "less than" query values.
NSMutableDictionary	queryMin() Provides a dictionary of "greater than" query values.
NSMutableDictionary	queryOperator() If a key in the queryMatch dictionary also exists in queryOperator, that operator for that key is used.
void	redisplay() Deprecated. Invoke willChange directly.
NSArray	relationalQualifierOperators() Provides all of the EOQualifier operators excepts that work exclusively on strings (such as like and contains).
Object	selectedObject() Provides the first object from selectedObjects.
NSArray	selectedObjects() Provides the last selection given to the WODisplayGroup via setSelectedObjects.
NSArray	selectionIndexes() Provides the last selection given to the WODisplayGroup via setSelectionIndexes.
Object	selectNext() Attempts to select the object just after the currently selected one.
boolean	selectObject(Object object) Attempts to select the object equal to object in the WODisplayGroup's displayedObjects, returning true if successful and false otherwise.
boolean	selectObjectsIdenticalTo(NSArray objectSelection) Attempts to select the objects in the WODisplayGroup's displayedObjects array whose addresses are equal to those of objects, returning true if successful and false otherwise.
boolean	selectObjectsIdenticalToSelectFirstOnNoMatch(NSArray objectSelection, boolean selectFirstOnNoMatch) Selects the objects in the WODisplayGroup's displayed objectSelection array whose addresses are equal to those of objectSelection, returning true if successful and false otherwise.
Object	selectPrevious() Attempts to select the object just before the presently selected one.
boolean	selectsFirstObjectAfterFetch() Indicates whether the WODisplayGroup should select the first object from its displayedObjects after a fetch when there were no selections before the fetch.
void	setCurrentBatchIndex(int batchIndex) Displays the batchIndex batch of objects.
void	setDataSource(EODataSource ds) Changes the WODisplayGroup's EODataSource to ds.
void	setDefaultStringMatchFormat(String format) Changes how pattern matching will be performed on String values in the queryMatch dictionary.
void	setDefaultStringMatchOperator(String op) Changes the operator used to perform pattern matching for String values in the queryMatch dictionary.
void	setDelegate(Object anObject) Changes the WODisplayGroup's delegate to anObject.
void	setDetailKey(String detailKey) Changes the detail key to detailKey for a detail display group.
void	setFetchesOnLoad(boolean yn) Changes whether the WODisplayGroup automatically fetches its objects after being loaded.
static void	setGlobalDefaultForValidatesChangesImmediately(boolean yn) Changes the class default behavior controlling whether submitted changes are immediately validated.
static void	setGlobalDefaultStringMatchFormat(String format) Changes the default string match format for the class.
static void	setGlobalDefaultStringMatchOperator(String op) Changes the default string match operator for the class.
void	setInQueryMode(boolean yn) Deprecated. No longer important for WebObjects applications. No user code should implement or depend upon this, and any implementations or references to this method may be eliminated freely.
void	setInsertedObjectDefaultValues(NSDictionary defaultValues) Changes the dictionary of default values added to empty objects that are inserted into the WODisplayGroup.
void	setLocalKeys(NSArray newKeySet) Changes the additional keys to which WOAssociations for the objects in this WODisplayGroup may be bound to the Strings in newKeySet.
void	setMasterObject(Object masterObject) Changes the master object to masterObject for detail display groups and then performs a fetch if the display group is set to fetch on load.
void	setNumberOfObjectsPerBatch(int count) Changes the number of objects the WODisplayGroup displays at a time.
void	setObjectArray(NSArray array) Changes the WODisplayGroup's array of allObjects to array, regardless of what its dataSource provides.
void	setQualifier(EOQualifier qualifier) Changes the EOQualifier used by the WODisplayGroup to filter its displayedObjects.
void	setSelectedObject(Object anObject) Changes the WODisplayGroup's selectedObjects to an array containing only anObject.
void	setSelectedObjects(NSArray objects) Changes the WODisplayGroup's selection from displayedObjects to objects.
boolean	setSelectionIndexes(NSArray s) Changes the selection from allObjects.
void	setSelectsFirstObjectAfterFetch(boolean yn) Changes whether the WODisplayGroup should select the first object from its displayedObjects after a fetch when there were no selections before the fetch.
void	setSortOrderings(NSArray keySortOrderArray) Changes the EOQualifier used by the WODisplayGroup to filter its objects.
void	setValidatesChangesImmediately(boolean yn) Changes whether the WODisplayGroup immediately validates submitted changes.
NSArray	sortOrderings() Provides the last array of EOSortOrdering objects given to the WODisplayGroup via setSortOrderings.
NSArray	stringQualifierOperators() Provides an array containing all of the relational operators supported by EOQualifier that work exclusively on Strings: "starts with", "contains", "ends with", "is", and "like".
void	takeValueForKey(Object value, String key) Sets the value for the property identified by key to value.
String	toString()
void	unableToSetNullForKey(String key) Invoked from takeValueForKey when it is given a null value for a scalar property (such as an int or a float).
NSUndoManager	undoManager() Provides the NSUndoManager used by the WODisplayGroup's dataSource's EOEditingContext.
void	updateDisplayedObjects() Recalculates the WODisplayGroup's displayedObjects from allObjects and redisplays them.
boolean	validatesChangesImmediately() Indicates whether the WODisplayGroup immediately validates submitted changes.
Object	valueForKey(String key) Retrieves the value of the property named by key.
void	willChange() Notifies observers that the WODisplayGroup will change.

Methods inherited from class java.lang.Object

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

Field Detail

DisplayGroupWillFetchNotification

public static final String DisplayGroupWillFetchNotification

The name for the notification posted during any invocation of WODisplayGroup's fetch method.

See Also:

fetch(), NSNotification

Constructor Detail

WODisplayGroup

public WODisplayGroup()

Creates and returns a new WODisplayGroup. The WODisplayGroup needs to have an EODataSource. If you invoke this method explicitly, you must invoke setDataSource.

See Also:

setDataSource(com.webobjects.eocontrol.EODataSource)

Method Detail

allObjects

public NSArray allObjects()

Provides all of the objects collected by the WODisplayGroup. This collection differs from that provided by displayedObjects. Typically this collection will comprise the results of the last fetch from the WODisplayGroup's dataSource.

However, this collection may be modified via several methods:

• deleteObjectAtIndex
• insertObjectAtIndex
• objectsChangedInEditingContext
• setInQueryMode
• setObjectArray
• updateDisplayedObjects

Returns:

an array of all the objects collected by the WODisplayGroup. Will never be null, though it may be empty.

See Also:

deleteObjectAtIndex(int), displayedObjects(), fetch(), insertObjectAtIndex(java.lang.Object, int), objectsChangedInEditingContext(com.webobjects.foundation.NSNotification), setInQueryMode(boolean), setObjectArray(com.webobjects.foundation.NSArray), updateDisplayedObjects()

allQualifierOperators

public NSArray allQualifierOperators()

Provides all of the EOQualifier operators plus those that work exclusively on Strings (such as like and contains).

Returns:

an array containing all of the relational operators supported by EOQualifier, including ones that work exclusively on Strings

See Also:

queryOperator(), relationalQualifierOperators(), stringQualifierOperators(), EOQualifier

awakeFromKeyValueUnarchiver

public void awakeFromKeyValueUnarchiver(EOKeyValueUnarchiver unarchiver)

Description copied from interface: EOKeyValueArchiving.Awaking

Notifies the receiver that the EOKeyValueUnarchiver unarchiver has unarchived all objects from an archive. Objects receive this method at the end of an unarchiving process of an EOKeyValueUnarchiver, when all objects have been unarchived, but before they are asked to finish initialization through the EOKeyValueArchiving.FinishInitialization interface method finishInitializationWithKeyValueUnarchiver.

Specified by:

awakeFromKeyValueUnarchiver in interface EOKeyValueArchiving.Awaking

Following copied from interface: com.webobjects.eocontrol.EOKeyValueArchiving.Awaking

Parameters:

unarchiver - the EOKeyValueUnarchiver

See Also:

EOKeyValueUnarchiver, EOKeyValueArchiving.FinishInitialization

batchCount

public int batchCount()

Provides the number of batches to display. For example, if displayedObjects().count() == 200 and numberOfObjectsPerBatch() == 10, batchCount() == 20 (twenty batches of ten objects each).

Returns:

the number of batches to display

See Also:

currentBatchIndex(), displayBatchContainingSelectedObject(), displayedObjects(), displayNextBatch(), displayPreviousBatch(), hasMultipleBatches(), numberOfObjectsPerBatch()

clearSelection

public boolean clearSelection()

Clears the selection of any objects from allObjects.

Invokes setSelectionIndexes (passing NSArray.EmptyArray) to do so.

Returns:

true on success and false on failure.

See Also:

allObjects(), setSelectionIndexes(com.webobjects.foundation.NSArray), NSArray.EmptyArray

currentBatchIndex

public int currentBatchIndex()

Provides the index of the batch currently being displayed. The batchCount equals the number of displayedObjects divided by the numberOfObjectsPerBatch. For example, if the WODisplayGroup has one hundred objects to display and the numberOfObjectsPerBatch is twenty, there are five batches. The first batch has a batch index of 1.

Returns:

the index of the batch currently being displayed

See Also:

batchCount(), currentBatchIndex(), displayBatchContainingSelectedObject(), displayedObjects(), displayNextBatch(), displayPreviousBatch(), hasMultipleBatches(), numberOfObjectsPerBatch(), setCurrentBatchIndex(int)

dataSource

public EODataSource dataSource()

Provides the last EODataSource given to the WODisplayGroup via setDataSource. The WODisplayGroup will use this EODataSource to fetch and commit objects.

The EODataSource may represent a detail in a master-detail relationship.

Returns:

the WODisplayGroup's EODataSource

See Also:

fetch(), hasDetailDataSource(), setDataSource(com.webobjects.eocontrol.EODataSource), EODataSource

decodeWithKeyValueUnarchiver

public static Object decodeWithKeyValueUnarchiver(EOKeyValueUnarchiver unarchiver)

defaultStringMatchFormat

public String defaultStringMatchFormat()

If a key in the queryMatch dictionary does not have an associated value in the queryOperator dictionary, then its value is matched using operator pattern matching, and the format string returned by this method specifies how it will be matched.

Returns:

the format string that specifies how pattern matching will be performed on string values in the queryMatch dictionary

See Also:

defaultStringMatchOperator(), setDefaultStringMatchFormat(java.lang.String), globalDefaultStringMatchFormat(), queryMatch()

defaultStringMatchOperator

public String defaultStringMatchOperator()

Provides a default operator for matching strings against string values in the queryMatch dictionary for the objects in the WODisplayGroup. If a key in the queryMatch dictionary does not have an associated operator in the queryOperator dictionary, then the operator is used. Unless this behavior is changed using setDefaultStringMatchOperator, this method returns caseInsensitiveLike.

Returns:

the default operator used to perform pattern matching for string values in the queryMatch dictionary

See Also:

allObjects(), defaultStringMatchFormat(), globalDefaultStringMatchOperator(), queryMatch(), queryOperator(), setDefaultStringMatchOperator(java.lang.String)

delegate

public Object delegate()

Provides the last delegate object given to the WODisplayGroup via setDelegate.

The delegate object may not implement WODisplayGroup.Delegate, because such implementation would require that all delegate methods be implemented. Those methods that might communicate with the delegate will take the appropriate steps to ensure that the delegate implements any method in question before attempting to invoke it.

Returns:

the WODisplayGroup's delegate object

See Also:

setDelegate(java.lang.Object), WODisplayGroup.Delegate

delete

public Object delete()

Invokes deleteSelection and displayBatchContainingSelectedObject. This method is a convenience to be invoked directly from a WOElement's (such as a WOComponent's) action.

Returns:

null to force reloading of the page that contains this WODisplayGroup (see WOElement.invokeAction)

See Also:

deleteObjectAtIndex(int), deleteSelection(), displayBatchContainingSelectedObject(), WOElement.invokeAction(com.webobjects.appserver.WORequest, com.webobjects.appserver.WOContext)

deleteObjectAtIndex

public boolean deleteObjectAtIndex(int anIndex)

Deletes the object at anIndex in allObjects.

Deletion may be prevented by WODisplayGroup.Delegate.displayGroupShouldDeleteObject.

If the deletion is not prevented and succeeds, this method also invokes:

• selectObjectsIdenticalToSelectFirstOnNoMatch
• willChange
• WODisplayGroup.Delegate.displayGroupDidDeleteObject

Parameters:

anIndex - index into allObjects that indicates which object should be deleted

Returns:

true if the object in question was deleted successfully, false otherwise

See Also:

allObjects(), dataSource(), delegate(), delete(), deleteSelection(), selectObjectsIdenticalToSelectFirstOnNoMatch(com.webobjects.foundation.NSArray, boolean), willChange(), WODisplayGroup.Delegate.displayGroupDidDeleteObject(com.webobjects.appserver.WODisplayGroup, java.lang.Object), WODisplayGroup.Delegate.displayGroupShouldDeleteObject(com.webobjects.appserver.WODisplayGroup, java.lang.Object)

deleteSelection

public boolean deleteSelection()

Deletes the selectedObjects from the WODisplayGroup's dataSource.

Deletion may be prevented by WODisplayGroup.Delegate.displayGroupShouldDeleteObject.

If the deletion is not prevented and succeeds, this method also invokes:

• selectObjectsIdenticalToSelectFirstOnNoMatch
• willChange
• WODisplayGroup.Delegate.displayGroupDidDeleteObject

Returns:

true if the selection was deleted successfully, false otherwise

See Also:

dataSource(), delegate(), delete(), deleteObjectAtIndex(int), selectedObjects(), selectObjectsIdenticalToSelectFirstOnNoMatch(com.webobjects.foundation.NSArray, boolean), willChange(), WODisplayGroup.Delegate.displayGroupDidDeleteObject(com.webobjects.appserver.WODisplayGroup, java.lang.Object), WODisplayGroup.Delegate.displayGroupShouldDeleteObject(com.webobjects.appserver.WODisplayGroup, java.lang.Object)

detailKey

public String detailKey()

For detail display groups, returns the key to the master object that specifies what this detail display group represents. That is, if you invoke valueForKey on the object returned by the masterObject method with this key, the objects controlled by this display group are obtained.

This method returns null if the WODisplayGroup is not a detail display group or if the detail key has not yet been set. A detail display group is typically created by dragging a to-many relationship from EOModeler to an open component in WebObjects Builder.

Returns:

the key to the master object

See Also:

hasDetailDataSource(), masterObject(), setDetailKey(java.lang.String), valueForKey(java.lang.String), EODetailDataSource

displayBatchContainingSelectedObject

public Object displayBatchContainingSelectedObject()

Displays the batch containing the selection and sets the currentBatchIndex to that batch's index.

Returns:

null to force the page to reload

See Also:

currentBatchIndex(), displayNextBatch(), displayPreviousBatch(), setCurrentBatchIndex(int)

displayNextBatch

public Object displayNextBatch()

Increments the current batch index, displays that batch of objects, and clears the selection. If the batch currently being displayed is the last batch, this method displays the first batch of objects.

Returns:

null to force the page to reload

See Also:

batchCount(), currentBatchIndex(), displayBatchContainingSelectedObject(), displayedObjects(), displayPreviousBatch(), hasMultipleBatches(), numberOfObjectsPerBatch()

displayPreviousBatch

public Object displayPreviousBatch()

Decrements the current batch index, displays that batch of objects, and clears the selection. If the batch currently being displayed is the first batch, this method displays the last batch of objects.

Returns:

null to force the page to reload

See Also:

batchCount(), currentBatchIndex(), displayBatchContainingSelectedObject(), displayedObjects(), displayNextBatch(), hasMultipleBatches(), numberOfObjectsPerBatch()

displayedObjects

public NSArray displayedObjects()

Provides the objects to be displayed or otherwise made available to the client (web browser). Typically this collection represents a filtered version of allObjects.

If the WODisplayGroup has a delegate that responds to displayGroupDisplayArrayForObjects, the WODisplayGroup uses this method to filter allObjects. Otherwise, the WODisplayGroup filters via a combination of its qualifier and its sortOrderings.

displayedObjects changes each time allObjects changes, as well whenever updateDisplayedObjects is invoked. If display batching is enabled (numberOfObjectsPerBatch() > 0), displayedObjects provides the current batch of objects. Consequently, displayedObjects may be also changed whenever any of the following methods are invoked:

• setNumberOfObjectsPerBatch
• displayNextBatch
• displayPreviousBatch
• displayBatchContainingSelectedObject

Returns:

the objects that should be displayed

See Also:

allObjects(), delegate(), displayNextBatch(), displayPreviousBatch(), displayBatchContainingSelectedObject(), numberOfObjectsPerBatch(), qualifier(), setNumberOfObjectsPerBatch(int), setQualifier(com.webobjects.eocontrol.EOQualifier), setSortOrderings(com.webobjects.foundation.NSArray), sortOrderings(), updateDisplayedObjects(), WODisplayGroup.Delegate.displayGroupDisplayArrayForObjects(com.webobjects.appserver.WODisplayGroup, com.webobjects.foundation.NSArray)

dispose

public void dispose()

Description copied from interface: NSDisposable

Invoked when the receiver should prepare itself for destruction. Implementations of this method should break connections that other objects have to the receiver, including unregistering for notifications, resigning as other objects' delegates, release locks and system resources, close files, and any other clean up operations.

Specified by:

dispose in interface NSDisposable

editingContextPresentErrorMessage

public void editingContextPresentErrorMessage(EOEditingContext editingContext,
                                              String message)

Deprecated. Use NSLog instead. No user code should implement or depend upon this.

Invoked by the supplied EOEditingContext as part of the EOEditingContext.MessageHandler interface, this method uses NSLog to display the supplied String.

Parameters:

editingContext - the supplied EOEditingContext

message - the message to display

See Also:

EOEditingContext.MessageHandler, NSLog

encodeWithCoder

public void encodeWithCoder(NSCoder coder)

encodeWithKeyValueArchiver

public void encodeWithKeyValueArchiver(EOKeyValueArchiver archiver)

Description copied from interface: EOKeyValueArchiving

Asks the receiver to archive its state into the EOKeyValueArchiver archiver.

Specified by:

encodeWithKeyValueArchiver in interface EOKeyValueArchiving

Following copied from interface: com.webobjects.eocontrol.EOKeyValueArchiving

Parameters:

archiver - the EOKeyValueArchiver

See Also:

EOKeyValueArchiver

endEditing

public boolean endEditing()

Deprecated. No longer important for WebObjects applications. No user code should depend upon this, and any references to this method may be eliminated freely.

Indicates whether any further editing should take place.

Returns:

true

fetch

public Object fetch()

Invokes the fetchObjects method of the dataSource and passes the result to setObjectArray.

Fetching may be prevented by WODisplayGroup.Delegate.displayGroupShouldFetch. If not prevented, this method also:

• Posts a WODisplayGroup.DisplayGroupWillFetchNotification just before invoking fetchObjects
• Resets all of the changes memorized by the undoManager (using its removeAllActionsWithTarget method)
• Invokes the delegate method WODisplayGroup.Delegate.displayGroupDidFetchObjects

Invoked by:

• awakeFromKeyValueUnarchiver (if fetchesOnLoad returns true)
• objectsInvalidatedInEditingContext
• qualifyDataSource
• setMasterObject (if fetchesOnLoad returns true)

Returns:

null to force the page to reload

See Also:

dataSource(), delegate(), DisplayGroupWillFetchNotification, fetchesOnLoad(), objectsInvalidatedInEditingContext(com.webobjects.foundation.NSNotification), qualifyDataSource(), setMasterObject(java.lang.Object), setObjectArray(com.webobjects.foundation.NSArray), WODisplayGroup.Delegate.displayGroupShouldFetch(com.webobjects.appserver.WODisplayGroup), WODisplayGroup.Delegate.displayGroupDidFetchObjects(com.webobjects.appserver.WODisplayGroup, com.webobjects.foundation.NSArray)

fetchesOnLoad

public boolean fetchesOnLoad()

Indicates whether the WODisplayGroup, whenever it is loaded, should fetch from its dataSource. A fetch on load typically occurs each time the WOComponent containing the WODisplayGroup is loaded by the client (web browser).

This method is invoked by:

• awakeFromKeyValueUnarchiver
• setMasterObject
• the default WODisplayGroup constructor

Unless explicitly changed via setFetchesOnLoad, returns false.

Returns:

true if the WODisplayGroup fetches automatically after the component that contains it is loaded, false if it must be told explicitly to fetch

See Also:

awakeFromKeyValueUnarchiver(com.webobjects.eocontrol.EOKeyValueUnarchiver), dataSource(), fetch(), setFetchesOnLoad(boolean), setMasterObject(java.lang.Object), WODisplayGroup(), WOComponent

finishInitialization

protected void finishInitialization()

Invoked from the WODisplayGroup constructor to finish initializing a newly created instance. This includes:

• Setting the new instances's EOEditingContext to its dataSource's editing context (if available)
• Registering the new display group for NSNotifications named EOEditingContext.ObjectsChangedInEditingContextNotification and EOObjectStore.InvalidatedAllObjectsInStoreNotification
• Establishing the new instance as an editor for the its editing context
• Establishing the new instance as its editing context's message handler (unless the editing context already has a message handler)

None of your other methods should ever invoke finishInitialization. If you override finishInitialization in a subclass, ensure that you invoke super.finishInitialization().

See Also:

EOEditingContext.ObjectsChangedInEditingContextNotification, EOObjectStore.InvalidatedAllObjectsInStoreNotification, NSNotification

globalDefaultForValidatesChangesImmediately

public static boolean globalDefaultForValidatesChangesImmediately()

Indicates the class default behavior controlling whether submitted changes are immediately validated. This class default behavior acts as the default behavior for new instances of WODisplayGroup.

This behavior can be overridden for each WODisplayGroup instance using setValidatesChangesImmediately.

Unless this behavior is changed using setGlobalDefaultForValidatesChangesImmediately, this method returns false.

Returns:

true if WODisplayGroups should immediately validate changes; false if changes should be passed unvalidated to the WODisplayGroup's EOEditingContext

See Also:

setGlobalDefaultForValidatesChangesImmediately(boolean), validatesChangesImmediately(), EOEditingContext

globalDefaultStringMatchFormat

public static String globalDefaultStringMatchFormat()

Provides the default string match format for the class.

Returns:

the default string match format for the class

See Also:

defaultStringMatchFormat()

globalDefaultStringMatchOperator

public static String globalDefaultStringMatchOperator()

Provides the default string match operator for the class.

Returns:

the default string match operator for the class

See Also:

defaultStringMatchOperator()

handleQueryWithUnboundKey

public Object handleQueryWithUnboundKey(String key)

Description copied from interface: NSKeyValueCoding.ErrorHandling

Invoked from valueForKey when it finds no property binding for key. The default implementation throws an NSKeyValueCoding.UnknownKeyException, with the target object(TargetObjectUserInfoKey) and key(UnknownUserInfokey) in the user info. An NSKeyValueCoding.ErrorHandling class can override this method to handle the query in some other way. The method can return a value, in which case that value is returned by the corresponding valueForKey invocation.

Specified by:

handleQueryWithUnboundKey in interface NSKeyValueCoding.ErrorHandling

Following copied from interface: com.webobjects.foundation.NSKeyValueCoding.ErrorHandling

Parameters:

key - the property name which generated this error

Returns:

any Object or null that the custom implementation desires. The default implementation throws an exception instead.

Throws:

NSKeyValueCoding.UnknownKeyException - when it finds no property binding for key

See Also:

NSKeyValueCoding.valueForKey(java.lang.String), NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.DefaultImplementation

handleTakeValueForUnboundKey

public void handleTakeValueForUnboundKey(Object value,
                                         String key)

Description copied from interface: NSKeyValueCoding.ErrorHandling

Invoked from takeValueForKey when it finds no property binding for key. The default implementation throws an NSKeyValueCoding.UnknownKeyException, with the target object(TargetObjectUserInfoKey) and key(UnknownUserInfoKey) in the user info dictionary of the exception. An NSKeyValueCoding.ErrorHandling class can override this method to handle the error in some other way.

Specified by:

handleTakeValueForUnboundKey in interface NSKeyValueCoding.ErrorHandling

Following copied from interface: com.webobjects.foundation.NSKeyValueCoding.ErrorHandling

Parameters:

value - the new value which could not be set

key - the name of the property which generated this error

Throws:

NSKeyValueCoding.UnknownKeyException - when it finds no property binding for key

See Also:

NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String), NSKeyValueCoding.UnknownKeyException, NSKeyValueCoding.DefaultImplementation

hasDetailDataSource

public boolean hasDetailDataSource()

If a to-many relationship is dragged from EOModeler to an open component in WebObjects Builder, a display group is created that has an EODetailDataSource. This behavior may also be set in WebObjects Builder using the Display Group Options panel.

Returns:

true if the WODisplayGroup's dataSource is an EODetailDataSource, false otherwise

See Also:

dataSource(), detailKey(), masterObject(), EODetailDataSource

hasMultipleBatches

public boolean hasMultipleBatches()

Indicates whether the WODisplayGroup paginates display, using batchCount.

Returns:

true if batchCount is greater than 1, false otherwise

See Also:

batchCount(), currentBatchIndex(), displayBatchContainingSelectedObject(), displayedObjects(), displayNextBatch(), displayPreviousBatch(), numberOfObjectsPerBatch()

inQueryMode

public boolean inQueryMode()

Deprecated. No longer important for WebObjects applications. No user code should implement or depend upon this, and any implementations or references to this method may be eliminated freely.

indexOfFirstDisplayedObject

public int indexOfFirstDisplayedObject()

Provides the index into displayedObjects of the first object in the current batch. As an example, if the current batch is displaying items 11 through 20, this method returns 11.

Returns:

the index of the first object displayed by the current batch

See Also:

currentBatchIndex(), displayedObjects(), indexOfLastDisplayedObject()

indexOfLastDisplayedObject

public int indexOfLastDisplayedObject()

Provides the index into displayedObjects of the last object in the current batch. As an example, if the current batch is displaying items 11 through 20, this method returns 20.

Returns:

the index of the last object displayed by the current batch

See Also:

currentBatchIndex(), displayedObjects(), indexOfFirstDisplayedObject()

initWithCoder

public Object initWithCoder(NSCoder coder)

insert

public Object insert()

Invokes insertNewObjectAtIndex with an index just past the first index in the selection, or at the end if there's no selection.

Returns:

null to force the page to reload

See Also:

insertNewObjectAtIndex(int)

insertNewObjectAtIndex

public Object insertNewObjectAtIndex(int newIndex)

Invokes the createObject method of the dataSource and inserts the new object into the dataSource (and into allObjects at newIndex) using insertObjectAtIndex. If a new object can't be created, this method invokes WODisplayGroup.Delegate.displayGroupCreateObjectFailedForDataSource.

If the object is successfully created, this method then sets the default values specified by insertedObjectDefaultValues.

Parameters:

newIndex - where to insert the new object; passed to insertObjectAtIndex

Returns:

the newly created and inserted object, or null if the object couldn't be created or inserted

See Also:

allObjects(), dataSource(), delegate(), insert(), insertObjectAtIndex(java.lang.Object, int), insertedObjectDefaultValues(), WODisplayGroup.Delegate.displayGroupCreateObjectFailedForDataSource(com.webobjects.appserver.WODisplayGroup, com.webobjects.eocontrol.EODataSource)

insertObjectAtIndex

public void insertObjectAtIndex(Object createObject,
                                int newIndex)

Inserts createObject into the WODisplayGroup's dataSource and into allObjects and displayedObjects at newIndex, if possible.

Insertion may be prevented by WODisplayGroup.Delegate.displayGroupShouldInsertObject.

If the deletion is not prevented and succeeds, this method also invokes:

• selectObjectsIdenticalTo with createObject
• willChange
• WODisplayGroup.Delegate.displayGroupDidInsertObject

Parameters:

createObject - object inserted into the WODisplayGroup's dataSource

newIndex - the specified index at which object is displayed

See Also:

allObjects(), delegate(), displayedObjects(), insert(), insertNewObjectAtIndex(int), selectObjectsIdenticalTo(com.webobjects.foundation.NSArray), willChange(), WODisplayGroup.Delegate.displayGroupDidInsertObject(com.webobjects.appserver.WODisplayGroup, java.lang.Object), WODisplayGroup.Delegate.displayGroupShouldInsertObject(com.webobjects.appserver.WODisplayGroup, java.lang.Object, int)

insertedObjectDefaultValues

public NSDictionary insertedObjectDefaultValues()

Provides the dictionary of default values added to empty objects that are inserted into the WODisplayGroup's dataSource. This dictionary's keys represent the properties of the EOEntity that this WODisplayGroup manages.

If this dictionary is empty, insert and insertNewObjectAtIndex add an object that is initially empty. Because the inserted object is empty, the WODisplayGroup has no value to display for that object. This means that the inserted object may not be selected or modified by the client (web browser). Consequently, the dictionary should contain at least a default value for the property or properties displayed by the WODisplayGroup.

Returns:

the default values to be used for newly inserted objects. Will never be null, though it may be empty.

See Also:

dataSource(), insert(), insertNewObjectAtIndex(int), setInsertedObjectDefaultValues(com.webobjects.foundation.NSDictionary), EOEntity

localKeys

public NSArray localKeys()

Provides the additional keys to which WOAssociations may be bound for this WODisplayGroup.

Typically a WODisplayGroup's basic keys are the attributes and relationships of its objects, allObjects. These keys are defined by the EOClassDescription for the objects (derived from an EOEntity in the EOModel associated with the WODisplayGroup's dataSource).

Local keys are used by WebObjects Builder to extend manually the interface of a WODisplayGroup's objects or to provide interface conveniences. Such keys may form associations with key paths, with arbitrary methods of objects or with properties of objects not associated with an EOEntity.

Returns:

an array of additional keys for WOAssociations in this WODisplayGroup. Will never be null, though it may be empty.

See Also:

allObjects(), dataSource(), WOAssociation, EOEntity, EOModel, EOClassDescription

masterObject

public Object masterObject()

Provides the master object for a detail display group (a display group that represents a detail in a master-detail relationship). A detail display group is one that uses an EODetailDataSource (defined in the EOControl framework). A detail display group is created by dragging a to-many relationship from EOModeler to an open component in WebObjects Builder. If the display group is not a detail display group or does not have a master object set, this method returns null.

Returns:

the master object for a detail display group

See Also:

detailKey(), hasDetailDataSource(), setMasterObject(java.lang.Object), EODetailDataSource

numberOfObjectsPerBatch

public int numberOfObjectsPerBatch()

You can set the batch size using setNumberOfObjectsPerBatch or using WebObjects Builder's Display Group Options panel.

Returns:

the number of objects the WODisplayGroup displays at a time

See Also:

batchCount(), currentBatchIndex(), displayBatchContainingSelectedObject(), displayedObjects(), displayNextBatch(), displayPreviousBatch(), hasMultipleBatches(), setNumberOfObjectsPerBatch(int)

objectsChangedInEditingContext

public void objectsChangedInEditingContext(NSNotification notification)

Redisplays the changed objects in the WODisplayGroup. The userInfo of notification may indicate that some objects have been deleted.

Parameters:

notification - indicates whether any objects have been deleted

See Also:

allObjects(), delegate(), NSNotification.userInfo()

objectsInvalidatedInEditingContext

public void objectsInvalidatedInEditingContext(NSNotification notification)

Refetches all objects from the dataSource of the WODisplayGroup after some or all of them have been invalidated. Refetching may be prevented by the WODisplayGroup's delegate method, displayGroupShouldRefetchForInvalidatedAllObjects.

Parameters:

notification - indicates which objects have been invalidated, for use by displayGroupShouldRefetchForInvalidatedAllObjects

See Also:

allObjects(), dataSource(), delegate(), fetch(), NSNotification, WODisplayGroup.Delegate.displayGroupShouldRefetchForInvalidatedAllObjects(com.webobjects.appserver.WODisplayGroup, com.webobjects.foundation.NSNotification)

qualifier

public EOQualifier qualifier()

Provides the last qualifier given to the WODisplayGroup via setQualifier or qualifyDisplayGroup. The WODisplayGroup uses this qualifier, in conjunction with its sortOrderings, to filter allObjects into displayedObjects.

If the WODisplayGroup has a delegate that responds to displayGroupDisplayArrayForObjects, the WODisplayGroup uses this method to filter allObjects instead of using its qualifier and sortOrderings.

Returns:

the WODisplayGroup's qualifier. May be null.

See Also:

allObjects(), delegate(), displayedObjects(), qualifyDisplayGroup(), setQualifier(com.webobjects.eocontrol.EOQualifier), sortOrderings(), updateDisplayedObjects(), WODisplayGroup.Delegate.displayGroupDisplayArrayForObjects(com.webobjects.appserver.WODisplayGroup, com.webobjects.foundation.NSArray)

qualifierFromQueryValues

public EOQualifier qualifierFromQueryValues()

Builds a qualifier constructed from entries in these query dictionaries: queryMatch, queryMax, queryMin, and queryOperator.

Returns:

the qualifier constructed

See Also:

queryMatch(), queryMax(), queryMin(), queryOperator(), qualifyDataSource(), qualifyDisplayGroup()

qualifyDataSource

public void qualifyDataSource()

Takes the result of qualifierFromQueryValues and applies to the WODisplayGroup's data source. The WODisplayGroup then invokes fetch on itself. If the WODisplayGroup is in query mode, query mode is exited. This method differs from qualifyDisplayGroup as follows: whereas qualifyDisplayGroup performs in-memory filtering of already fetched objects, qualifyDataSource triggers a new qualified fetch against the database.

See Also:

queryMatch(), queryMax(), queryMin(), queryOperator(), qualifierFromQueryValues(), fetch(), qualifyDisplayGroup()

qualifyDisplayGroup

public void qualifyDisplayGroup()

Takes the result of the qualifierFromQueryValues and applies it to the WODisplayGroup using setQualifier. The method updateDisplayedObjects is invoked to refresh the display. If the WODisplayGroup is in query mode, query mode is exited.

See Also:

qualifyDataSource(), queryMatch(), queryMax(), queryMin(), queryOperator(), qualifierFromQueryValues(), setQualifier(com.webobjects.eocontrol.EOQualifier), updateDisplayedObjects()

queryBindings

public NSMutableDictionary queryBindings()

You use this method to perform a query stored in the EOModel file. Bind keys in this dictionary to elements on your WOComponent that specify query values, then pass this dictionary to the fetch specification that performs the fetch.

Returns:

a dictionary containing the actual values the user wants to query on

queryMatch

public NSMutableDictionary queryMatch()

The qualifierFromQueryValues method uses this dictionary along with the queryMax and queryMin dictionaries to construct qualifiers.

Use the queryOperator dictionary to specify the type of matching (=, <, >, like, and so on) for each key in the queryMatch dictionary.

If the queryOperator dictionary does not contain a key contained in the queryMatch dictionary, the default is to match the value exactly (=) if the value is a number or a date and to perform pattern matching if the value is a String. In the case of string values, the defaultStringMatchFormat and defaultStringMatchOperator specify exactly how the pattern matching will be performed.

Returns:

a dictionary of query values to match

See Also:

allQualifierOperators(), defaultStringMatchFormat(), defaultStringMatchOperator(), qualifierFromQueryValues(), qualifyDataSource(), qualifyDisplayGroup(), queryMatch(), queryMax(), queryMin(), queryOperator(), relationalQualifierOperators()

queryMax

public NSMutableDictionary queryMax()

Provides a dictionary of "less than" query values. The qualifierFromQueryValues method uses this dictionary along with the queryMatch and queryMin dictionaries to construct qualifiers.

Returns:

a dictionary of "less than" query values

See Also:

qualifierFromQueryValues(), qualifyDataSource(), qualifyDisplayGroup(), queryMatch(), queryMin(), queryOperator()

queryMin

public NSMutableDictionary queryMin()

Provides a dictionary of "greater than" query values. The qualifierFromQueryValues method uses this dictionary along with the queryMatch and queryMin dictionaries to construct qualifiers.

Returns:

a dictionary of "greater than" query values

See Also:

qualifierFromQueryValues(), qualifyDataSource(), queryMatch(), qualifyDisplayGroup(), queryOperator()

queryOperator

public NSMutableDictionary queryOperator()

If a key in the queryMatch dictionary also exists in queryOperator, that operator for that key is used. The allQualifierOperators method returns the operator strings you can use as values in this dictionary.

Returns:

a dictionary of operators to use on items in the queryMatch dictionary

See Also:

allQualifierOperators(), queryMatch(), queryMin(), queryMax(), relationalQualifierOperators(), qualifierFromQueryValues()

redisplay

public void redisplay()

Deprecated. Invoke willChange directly.

Invokes willChange.

See Also:

willChange()

relationalQualifierOperators

public NSArray relationalQualifierOperators()

Provides all of the EOQualifier operators excepts that work exclusively on strings (such as like and contains).

Returns:

an array containing all of the non-String relational operators supported by EOQualifier: =, !=, <, <=, >, and >=

See Also:

allQualifierOperators(), queryOperator(), stringQualifierOperators(), EOQualifier.relationalQualifierOperators()

selectNext

public Object selectNext()

Attempts to select the object just after the currently selected one. The selection is altered in this way:

• If there are no objects, does nothing.
• If there's no selection, selects the object at index zero.
• If the first selected object is the last object in the displayed objects array, selects the first object.
• Otherwise selects the object after the first selected object.

Returns:

null to force the page to reload

See Also:

selectPrevious(), setSelectionIndexes(com.webobjects.foundation.NSArray)

selectObject

public boolean selectObject(Object object)

Attempts to select the object equal to object in the WODisplayGroup's displayedObjects, returning true if successful and false otherwise. object is equal to an object in the displayedObjects array if its address is the same as the object in the array.

Parameters:

object - equal to object in the WODisplayGroup's displayedObjects array

Returns:

true if successful and false otherwise

See Also:

selectPrevious(), selectNext()

selectObjectsIdenticalTo

public boolean selectObjectsIdenticalTo(NSArray objectSelection)

Attempts to select the objects in the WODisplayGroup's displayedObjects array whose addresses are equal to those of objects, returning true if successful and false otherwise.

Parameters:

objectSelection - the objects in the WODisplayGroup's displayedObjects array whose addresses are equal to those of objects

Returns:

true if successful and false otherwise

See Also:

setSelectionIndexes(com.webobjects.foundation.NSArray), selectObjectsIdenticalToSelectFirstOnNoMatch(com.webobjects.foundation.NSArray, boolean)

selectObjectsIdenticalToSelectFirstOnNoMatch

public boolean selectObjectsIdenticalToSelectFirstOnNoMatch(NSArray objectSelection,
                                                            boolean selectFirstOnNoMatch)

Selects the objects in the WODisplayGroup's displayed objectSelection array whose addresses are equal to those of objectSelection, returning true if successful and false otherwise. If no objects in the displayedObjects array match objects and selectFirstOnNoMatch is true, attempts to select the first object in the displayedObjects array.

Parameters:

objectSelection - the objects in the WODisplayGroup's displayed objects array whose addresses are equal to those of objects

selectFirstOnNoMatch - boolean indicating whether the first object in the displayedObjects should be selected if no objects in objectSelection match

Returns:

true if successful and false otherwise

See Also:

setSelectionIndexes(com.webobjects.foundation.NSArray), selectObjectsIdenticalTo(com.webobjects.foundation.NSArray)

selectPrevious

public Object selectPrevious()

Attempts to select the object just before the presently selected one. The selection is altered in this way:

• If there are no objects, does nothing.
• If there's no selection, selects the object at index zero.
• If the first selected object is at index zero, selects the last object.
• Otherwise selects the object before the first selected object.

Returns:

null to force the page to reload

See Also:

redisplay(), selectNext()

selectedObject

public Object selectedObject()

Provides the first object from selectedObjects.

Returns:

the first object in selectedObjects, or null if there's no selection

See Also:

displayedObjects(), selectedObjects(), selectionIndexes()

selectedObjects

public NSArray selectedObjects()

Provides the last selection given to the WODisplayGroup via setSelectedObjects. This selection is represented by an array of objects culled from the WODisplayGroup's displayedObjects.

Returns:

an array of the objects selected from the WODisplayGroup's displayedObjects. Will never be null, though it may be empty.

See Also:

displayedObjects(), selectedObject(), selectionIndexes()

selectionIndexes

public NSArray selectionIndexes()

Provides the last selection given to the WODisplayGroup via setSelectionIndexes. This selection is represented by an array of Integers that indicates the indexes of the selected objects in allObjects.

Returns:

an array of Integers indicating the indexes of the selection. Will never be null, though it may be empty.

See Also:

allObjects(), selectedObject(), selectedObjects(), setSelectionIndexes(com.webobjects.foundation.NSArray)

selectsFirstObjectAfterFetch

public boolean selectsFirstObjectAfterFetch()

Indicates whether the WODisplayGroup should select the first object from its displayedObjects after a fetch when there were no selections before the fetch.

Returns:

true indicates automatically selection of the first displayed object after a fetch if there was no previous selection; false indicates leaving an empty selection as-is

See Also:

displayedObjects(), fetch(), setSelectsFirstObjectAfterFetch(boolean)

setCurrentBatchIndex

public void setCurrentBatchIndex(int batchIndex)

Displays the batchIndex batch of objects. The total batchCount equals the number of displayedObjects divided by the numberOfObjectsPerBatch. For example, if the WODisplayGroup has one hundred objects to display and the numberOfObjectsPerBatch is twenty, there are five batches. The first batch has a batch index of 1. setCurrentBatchIndex(3) would display the third batch of objects (objects 41 to 60 in this example).

If batchIndex is greater than the number of batches, this method displays the first batch.

Parameters:

batchIndex - the proposed batch index of objects

See Also:

currentBatchIndex()

setDataSource

public void setDataSource(EODataSource ds)

Changes the WODisplayGroup's EODataSource to ds. This also causes the WODisplayGroup to:

• Unregister itself, if necessary, as an editor and message handler for the previous EODataSource's EOEditingContext
• Register itself with ds's EOEditingContext, unless that EOEditingContext already has a message handler
• Clear its array of objects, allObjects
• Invoke WODisplayGroup.Delegate.displayGroupDidChangeDataSource

Parameters:

ds - the proposed EODataSource

See Also:

allObjects(), dataSource(), delegate(), EODataSource, EOEditingContext, WODisplayGroup.Delegate.displayGroupDidChangeDataSource(com.webobjects.appserver.WODisplayGroup)

setDefaultStringMatchFormat

public void setDefaultStringMatchFormat(String format)

Changes how pattern matching will be performed on String values in the queryMatch dictionary. This format is used for properties listed in the queryMatch dictionary that have String values and that do not have an associated entry in the queryOperator dictionary. In these cases, the value is matched using pattern matching and format specifies how it will be matched.

The default format string for pattern matching is "%@" which means that the string value in the queryMatch dictionary is used as a prefix (this default can be overridden on a class basis using setGlobalDefaultStringMatchFormat). For example, if the queryMatch dictionary contains a value "Jo" for the key "Name", the query returns all records whose name values begin with "Jo".

Parameters:

format - specifies how pattern will be matched

See Also:

queryMatch(), queryOperator(), setGlobalDefaultStringMatchFormat(java.lang.String), defaultStringMatchFormat(), setDefaultStringMatchOperator(java.lang.String)

setDefaultStringMatchOperator

public void setDefaultStringMatchOperator(String op)

Changes the operator used to perform pattern matching for String values in the queryMatch dictionary. This operator is used for properties listed in the queryMatch dictionary that have String values and that do not have an associated entry in the queryOperator dictionary. In these cases, the operator is used to perform pattern matching.

The default value for the query match operator is caseInsensitiveLike, which means that the query does not consider case when matching letters (this default can be overridden on a class basis using setGlobalDefaultStringMatchOperator). The other possible value for this operator is like, which matches the case of the letters exactly.

Parameters:

op - operator used to perform pattern matching

See Also:

queryMatch(), queryOperator(), allQualifierOperators(), defaultStringMatchOperator(), relationalQualifierOperators(), setDefaultStringMatchFormat(java.lang.String), setGlobalDefaultStringMatchOperator(java.lang.String)

setDelegate

public void setDelegate(Object anObject)

Changes the WODisplayGroup's delegate to anObject.

The new delegate object may not implement WODisplayGroup.Delegate, because such implementation would require that all delegate methods be implemented. Those methods that might communicate with the delegate will take the appropriate steps to ensure that the delegate implements any method in question before attempting to invoke it.

Parameters:

anObject - the proposed delegate object

See Also:

delegate(), WODisplayGroup.Delegate

setDetailKey

public void setDetailKey(String detailKey)

Changes the detail key to detailKey for a detail display group. The detail key is the key that retrieves from the master object the objects that this display group manages. You must set a detail key before you set a master object.

If the WODisplayGroup is not a detail display group, this method has no effect. A display group is a detail display group if its data source is an EODetailDataSource. A detail display group is typically created by dragging a to-many relationship from EOModeler to an open component in WebObjects Builder. Doing so sets the detail key and master object, so you rarely need to use this method.

Parameters:

detailKey - the detail key is set to this for a detail display group

See Also:

detailKey(), hasDetailDataSource(), setMasterObject(java.lang.Object), EODetailDataSource

setFetchesOnLoad

public void setFetchesOnLoad(boolean yn)

Changes whether the WODisplayGroup automatically fetches its objects after being loaded. This behavior may also be set in WebObjects Builder using the Display Group Options panel.

Parameters:

yn - the proposed change. true if the WODisplayGroup, when it is loaded, should automatically fetch from the database; false if the WODisplayGroup should wait until fetch is invoked explicitly

See Also:

fetch(), fetchesOnLoad()

setGlobalDefaultForValidatesChangesImmediately

public static void setGlobalDefaultForValidatesChangesImmediately(boolean yn)

Changes the class default behavior controlling whether submitted changes are immediately validated. This class default behavior acts as the default behavior for new instances of WODisplayGroup.

This behavior can be overridden for each WODisplayGroup instance using setValidatesChangesImmediately.

Parameters:

yn - the proposed behavior. true if WODisplayGroups should immediately validate changes; false if changes should be passed unvalidated to the WODisplayGroup's EOEditingContext

See Also:

globalDefaultForValidatesChangesImmediately(), setValidatesChangesImmediately(boolean), EOEditingContext

setGlobalDefaultStringMatchFormat

public static void setGlobalDefaultStringMatchFormat(String format)

Changes the default string match format for the class.

Parameters:

format - the proposed string match format

See Also:

setDefaultStringMatchFormat(java.lang.String)

setGlobalDefaultStringMatchOperator

public static void setGlobalDefaultStringMatchOperator(String op)

Changes the default string match operator for the class.

Parameters:

op - the proposed default string match operator for the class

See Also:

setDefaultStringMatchOperator(java.lang.String)

setInQueryMode

public void setInQueryMode(boolean yn)

Deprecated. No longer important for WebObjects applications. No user code should implement or depend upon this, and any implementations or references to this method may be eliminated freely.

setInsertedObjectDefaultValues

public void setInsertedObjectDefaultValues(NSDictionary defaultValues)

Changes the dictionary of default values added to empty objects that are inserted into the WODisplayGroup. By default, this dictionary is empty.

Parameters:

defaultValues - the proposed default values to be used for newly inserted, empty objects. Should never be null.

See Also:

insert(), insertedObjectDefaultValues(), insertNewObjectAtIndex(int)

setLocalKeys

public void setLocalKeys(NSArray newKeySet)

Changes the additional keys to which WOAssociations for the objects in this WODisplayGroup may be bound to the Strings in newKeySet.

Parameters:

newKeySet - the proposed local keys

See Also:

localKeys(), WOAssociation

setMasterObject

public void setMasterObject(Object masterObject)

Changes the master object to masterObject for detail display groups and then performs a fetch if the display group is set to fetch on load. The master object owns the objects controlled by this display group.

Before this method is used, you should use the setDetailKey to set the key to this relationship. A detail display group is typically created by dragging a to-Many relationship from EOModeler to an open component in WebObjects Builder. Doing so sets the master object and detail key, so typically you don't have to use this method.

If the WODisplayGroup is not a detail display group, this method has no effect.

Parameters:

masterObject - the master object is set to this

See Also:

setDetailKey(java.lang.String), hasDetailDataSource(), masterObject(), EODetailDataSource

setNumberOfObjectsPerBatch

public void setNumberOfObjectsPerBatch(int count)

Changes the number of objects the WODisplayGroup displays at a time. For example, suppose you are displaying one hundred records. Instead of displaying all of these at once, you can set the batch size so that the page displays a more manageable number (for example, 10). WebObjects Builder allows to set the number of objects per batch on the Display Group Options panel.

Parameters:

count - the proposed number of objects the WODisplayGroup should display at a time

See Also:

numberOfObjectsPerBatch()

setObjectArray

public void setObjectArray(NSArray array)

Changes the WODisplayGroup's array of allObjects to array, regardless of what its dataSource provides. Invoked from fetch to set the array of fetched objects; should almost never need to be invoked explicitly.

Doesn't affect the dataSource's objects at all; specifically, this method results neither in inserts nor deletes of objects in the dataSource. array should contain objects with the same property names or methods as those used by the WODisplayGroup.

After changing to array, this method restores as much of any previous object selection as possible. If unable to restore any previous selection, then the first object is selected if the WODisplayGroup selectsFirstObjectAfterFetch.

Parameters:

array - the object array to be set

See Also:

fetch(), allObjects(), dataSource(), displayedObjects(), selectsFirstObjectAfterFetch()

setQualifier

public void setQualifier(EOQualifier qualifier)

Changes the EOQualifier used by the WODisplayGroup to filter its displayedObjects. Typically invoked in conjunction with setSortOrderings.

Use updateDisplayedObjects to apply a new qualifier to the WODisplayGroup (filter allObjects into displayedObjects).

The WODisplayGroup's qualifier may also be changed via qualifyDisplayGroup or from WebObjects Builder using the Display Group Options panel.

Parameters:

qualifier - the proposed qualifier

See Also:

allObjects(), displayedObjects(), qualifier(), qualifyDisplayGroup(), setSortOrderings(com.webobjects.foundation.NSArray), updateDisplayedObjects(), WODisplayGroup.Delegate.displayGroupDisplayArrayForObjects(com.webobjects.appserver.WODisplayGroup, com.webobjects.foundation.NSArray)

setSelectedObject

public void setSelectedObject(Object anObject)

Changes the WODisplayGroup's selectedObjects to an array containing only anObject. Invokes setSelectedObjects to do so.

If anObject is null, invokes clearSelection.

Parameters:

anObject - the object to become the new selectedObject and sole member of selectedObjects

See Also:

allObjects(), displayedObjects(), selectedObject(), selectedObjects(), selectionIndexes()

setSelectedObjects

public void setSelectedObjects(NSArray objects)

Changes the WODisplayGroup's selection from displayedObjects to objects. Invokes setSelectionIndexes to do so.

Invoked by setSelectedObject.

Parameters:

objects - the proposed selection

See Also:

allObjects(), displayedObjects(), selectedObjects(), setSelectedObject(java.lang.Object), setSelectionIndexes(com.webobjects.foundation.NSArray)

setSelectionIndexes

public boolean setSelectionIndexes(NSArray s)

Changes the selection from allObjects. s contains the indexes (Integers) of some or all of the objects from allObjects.

Invoked by setSelectedObjects.

The selection change may be prevented by the WODisplayGroup's delegate method, displayGroupShouldChangeSelectionToIndexes.

If the selection change is not prevented and succeeds, the WODisplayGroup invokes the delegate method, displayGroupDidChangeSelectedObjects.

NOTE: The selection made here does not necessarily result in a display change in the client (web browser).

Parameters:

s - an array of Integers indicating the indexes of objects to be selected from allObjects. Should never be null.

Returns:

true if the change occurred successfully, false otherwise

See Also:

allObjects(), delegate(), displayedObjects(), setSelectedObjects(com.webobjects.foundation.NSArray), WODisplayGroup.Delegate.displayGroupDidChangeSelectedObjects(com.webobjects.appserver.WODisplayGroup), WODisplayGroup.Delegate.displayGroupShouldChangeSelectionToIndexes(com.webobjects.appserver.WODisplayGroup, com.webobjects.foundation.NSArray)

setSelectsFirstObjectAfterFetch

public void setSelectsFirstObjectAfterFetch(boolean yn)

Changes whether the WODisplayGroup should select the first object from its displayedObjects after a fetch when there were no selections before the fetch.

By default, a WODisplayGroup will select the first object after a fetch when there was no previous selection.

Parameters:

yn - true indicates automatic selection of the first displayed object after a fetch if there was no previous selection, false indicates leaving an empty selection as-is

See Also:

displayedObjects(), fetch(), selectsFirstObjectAfterFetch()

setSortOrderings

public void setSortOrderings(NSArray keySortOrderArray)

Changes the EOQualifier used by the WODisplayGroup to filter its objects. Typically invoked in conjunction with setQualifier.

Use updateDisplayedObjects to apply the new sort orderings to the WODisplayGroup (filter allObjects into displayedObjects).

The WODisplayGroup's sortOrderings may also be changed from WebObjects Builder using the Display Group Options panel.

Parameters:

keySortOrderArray - the proposed EOSortOrdering objects

See Also:

allObjects(), displayedObjects(), qualifyDisplayGroup(), setQualifier(com.webobjects.eocontrol.EOQualifier), updateDisplayedObjects(), sortOrderings(), EOSortOrdering

setValidatesChangesImmediately

public void setValidatesChangesImmediately(boolean yn)

Changes whether the WODisplayGroup immediately validates submitted changes.

This behavior can be overridden class-wide (affecting WODisplayGroup instances created after the class change) using setGlobalDefaultForValidatesChangesImmediately.

Parameters:

yn - the proposed behavior. true if the WODisplayGroup should immediately validate changes; false if changes should be passed unvalidated to the WODisplayGroup's EOEditingContext

See Also:

setGlobalDefaultForValidatesChangesImmediately(boolean), validatesChangesImmediately(), EOEditingContext.saveChanges(), EOEditingContext.tryToSaveChanges()

sortOrderings

public NSArray sortOrderings()

Provides the last array of EOSortOrdering objects given to the WODisplayGroup via setSortOrderings. The WODisplayGroup uses these sort orderings, in conjunction with its qualifier, to filter allObjects into displayedObjects.

If the WODisplayGroup has a delegate that responds to displayGroupDisplayArrayForObjects, the WODisplayGroup uses this method to filter allObjects instead of using its qualifier and sortOrderings.

Returns:

an array of EOSortOrdering objects. May be null.

See Also:

allObjects(), delegate(), displayedObjects(), qualifier(), qualifyDisplayGroup(), setSortOrderings(com.webobjects.foundation.NSArray), updateDisplayedObjects(), EOSortOrdering, WODisplayGroup.Delegate.displayGroupDisplayArrayForObjects(com.webobjects.appserver.WODisplayGroup, com.webobjects.foundation.NSArray)

stringQualifierOperators

public NSArray stringQualifierOperators()

Provides an array containing all of the relational operators supported by EOQualifier that work exclusively on Strings: "starts with", "contains", "ends with", "is", and "like".

Returns:

an array containing all of the relational operators

See Also:

allQualifierOperators(), relationalQualifierOperators(), EOQualifier

takeValueForKey

public void takeValueForKey(Object value,
                            String key)

Description copied from interface: NSKeyValueCoding

Sets the value for the property identified by key to value.

The default implementation provided by NSKeyValueCoding.DefaultImplementation works as follows:

1. Searches for a public accessor method of the form setKey, and invokes it if there is one.
2. If a public accessor method is not found, searches for a private accessor method of the form _setKey, and invokes it if there is one.
3. If an accessor method is not found and the static method canAccessFieldsDirectly returns true, searches for a field based on key and sets its value directly. For the key "lastName", this would be _lastName, _isLastName, lastName, or isLastName.
4. If the type of the value argument is not compatible with the underlying field or method parameter, the default implementation will make an effort to convert between different Java numeric types (Integer, Double, BigDecimal, etc) as well as between Boolean and Number (true = 1, false = 0). If any other conversion would be necessary, an exception is thrown.
5. If neither an accessor method nor a field is found, it is an error condition. It invokes handleTakeValueForUnboundKey if the object implements NSKeyValueCoding.ErrorHandling or throws NSKeyValueCoding.UnknownKeyException if the object does not.

Note: : The default implementations have significant performance optimizations. To benefit from them, implement NSKeyValueCoding on a custom class as shown above by using the methods in NSKeyValueCoding. DefaultImplementation, or if your class inherits from an WebObjects class that implements NSKeyValueCoding, do not override the inherited implementation. Using a custom implementation incurs significant performance penalties.

Specified by:

takeValueForKey in interface NSKeyValueCoding

Following copied from interface: com.webobjects.foundation.NSKeyValueCoding

Parameters:

value - the new value for the property named by key

key - identifies the property to change

Throws:

NSKeyValueCoding.UnknownKeyException - if key cannot be found on the object this method was invoked upon.

See Also:

NSKeyValueCoding.NullValue, NSKeyValueCoding.valueForKey(java.lang.String), NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.ErrorHandling.handleTakeValueForUnboundKey(java.lang.Object, java.lang.String)

toString

public String toString()

Overrides:

toString in class Object

unableToSetNullForKey

public void unableToSetNullForKey(String key)

Description copied from interface: NSKeyValueCoding.ErrorHandling

Invoked from takeValueForKey when it is given a null value for a scalar property (such as an int or a float). The default implementation throws an IllegalArgumentException. You might want to implement the method (or override the inherited implementation) to handle the request in some other way, such as by substituting new Integer(0) or a sentinel value and invoking takeValueForKey again.

Specified by:

unableToSetNullForKey in interface NSKeyValueCoding.ErrorHandling

Following copied from interface: com.webobjects.foundation.NSKeyValueCoding.ErrorHandling

Parameters:

key - the name of the property which generated this error

Throws:

IllegalArgumentException - when it is given a null value for a scalar property

See Also:

NSKeyValueCoding.takeValueForKey(Object value, String key), NSKeyValueCoding.DefaultImplementation

undoManager

public NSUndoManager undoManager()

Provides the NSUndoManager used by the WODisplayGroup's dataSource's EOEditingContext.

Returns:

the undo manager that the WODisplayGroup will use to revert changes to its objects

See Also:

allObjects(), dataSource(), EOEditingContext, NSUndoManager

updateDisplayedObjects

public void updateDisplayedObjects()

Recalculates the WODisplayGroup's displayedObjects from allObjects and redisplays them. Invoked by qualifyDisplayGroup and setObjectArray.

If the WODisplayGroup has a delegate that responds to displayGroupDisplayArrayForObjects, the WODisplayGroup uses this method to filter allObjects into displayedObjects. Otherwise, the WODisplayGroup uses its qualifier and sortOrderings to do so. In either case, any objects that were previously selected remain selected in the new array of displayedObjects.

See Also:

allObjects(), delegate(), displayedObjects(), qualifier(), qualifyDisplayGroup(), redisplay(), selectedObjects(), setObjectArray(com.webobjects.foundation.NSArray), sortOrderings(), WODisplayGroup.Delegate.displayGroupDisplayArrayForObjects(com.webobjects.appserver.WODisplayGroup, com.webobjects.foundation.NSArray)

validatesChangesImmediately

public boolean validatesChangesImmediately()

Indicates whether the WODisplayGroup immediately validates submitted changes.

Unless this behavior is overridden for this WODisplayGroup instance using setValidatesChangesImmediately, the value returned is the same as that currently returned by globalDefaultForValidatesChangesImmediately.

Returns:

true if the WODisplayGroup should immediately validate changes; false if changes should be passed unvalidated to the WODisplayGroup's EOEditingContext

See Also:

globalDefaultForValidatesChangesImmediately(), setValidatesChangesImmediately(boolean)

valueForKey

public Object valueForKey(String key)

Description copied from interface: NSKeyValueCoding

Retrieves the value of the property named by key.

The default implementation provided by NSKeyValueCoding.DefaultImplementation works as follows:

1. Searches for a public accessor method based on key. For example, with a key of "lastName", the method looks for a method named getLastName, lastName, or isLastName.
2. If a public accessor method is not found, searches for a private accessor method based on key (a method preceded by an underbar). For example, with a key of "lastName", the method looks for a method named _getLastName, _lastName, or _isLastName
3. If an accessor method is not found and the static method canAccessFieldsDirectly returns true, the method searches for a field based on key and returns its value directly. For the key "lastName", this would be _lastName, _isLastName, lastName, or isLastName.
4. If neither an accessor method nor a field is found, the method invokes handleQueryWithUnboundKey (defined in NSKeyValueCoding.ErrorHandling).

Note: The default implementations have significant performance optimizations. To benefit from them, implement NSKeyValueCoding on a custom class as shown above by using the methods in NSKeyValueCoding.DefaultImplementation, or if your class inherits from an WebObjects class that implements NSKeyValueCoding, do not override the inherited implementation. Using a custom implementation incurs significant performance penalties.

Specified by:

valueForKey in interface NSKeyValueCoding

Following copied from interface: com.webobjects.foundation.NSKeyValueCoding

Parameters:

key - identifies the property to retrieve

Returns:

the value of the property identified by key. Depending on the object you invoke this method upon, null may be replaced with NullValue

Throws:

NSKeyValueCoding.UnknownKeyException - if key cannot be found on the object this method was invoked upon.

See Also:

NSKeyValueCoding.NullValue, NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String), NSKeyValueCoding.DefaultImplementation, NSKeyValueCoding.ErrorHandling, NSKeyValueCoding.ErrorHandling.handleQueryWithUnboundKey(java.lang.String)

willChange

public void willChange()

Notifies observers that the WODisplayGroup will change.

See Also:

EOObserverCenter.notifyObserversObjectWillChange(java.lang.Object)