WODisplayGroup (WebObjects 5.2.3 Reference Documentation)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

WebObjects 5.2.3

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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

Nested Class Summary
`static interface`	`WODisplayGroup.Delegate` The WODisplayGroup delegate offers a number of methods, and WODisplayGroup invokes them as appropriate.

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

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

Nested 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

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

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

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.
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

Parameters:: value - the new value which could not be set; key - the name of the property which generated this error
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.

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:

Searches for a public accessor method of the form setKey, and invokes it if there is one.
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.
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.
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.
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

Parameters:: value - the new value for the property named by key; key - identifies the property to change
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()

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

Parameters:: key - the name of the property which generated this error
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:

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.
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
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.
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

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
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)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Last updated Thu Oct 21 15:04:16 PDT 2004.

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.webobjects.appserver Class WODisplayGroup

DisplayGroupWillFetchNotification

WODisplayGroup

allObjects

allQualifierOperators

awakeFromKeyValueUnarchiver

batchCount

clearSelection

currentBatchIndex

dataSource

decodeWithKeyValueUnarchiver

defaultStringMatchFormat

defaultStringMatchOperator

delegate

delete

deleteObjectAtIndex

deleteSelection

detailKey

displayBatchContainingSelectedObject

displayNextBatch

displayPreviousBatch

displayedObjects

dispose

editingContextPresentErrorMessage

encodeWithCoder

encodeWithKeyValueArchiver

endEditing

fetch

fetchesOnLoad

finishInitialization

globalDefaultForValidatesChangesImmediately

globalDefaultStringMatchFormat

globalDefaultStringMatchOperator

handleQueryWithUnboundKey

handleTakeValueForUnboundKey

hasDetailDataSource

hasMultipleBatches

inQueryMode

indexOfFirstDisplayedObject

indexOfLastDisplayedObject

initWithCoder

insert

insertNewObjectAtIndex

insertObjectAtIndex

insertedObjectDefaultValues

localKeys

masterObject

numberOfObjectsPerBatch

objectsChangedInEditingContext

objectsInvalidatedInEditingContext

qualifier

qualifierFromQueryValues

qualifyDataSource

qualifyDisplayGroup

queryBindings

queryMatch

queryMax

queryMin

queryOperator

redisplay

relationalQualifierOperators

selectNext

selectObject

selectObjectsIdenticalTo

selectObjectsIdenticalToSelectFirstOnNoMatch

selectPrevious

selectedObject

selectedObjects

selectionIndexes

selectsFirstObjectAfterFetch

setCurrentBatchIndex

setDataSource

setDefaultStringMatchFormat

setDefaultStringMatchOperator

setDelegate

setDetailKey

setFetchesOnLoad

setGlobalDefaultForValidatesChangesImmediately

setGlobalDefaultStringMatchFormat

setGlobalDefaultStringMatchOperator

com.webobjects.appserver
Class WODisplayGroup