WebObjects 5.2.3

com.webobjects.appserver
Class WODisplayGroup

java.lang.Object
  extended bycom.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:

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:

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:

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:

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:

Invoked by:

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:

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:

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:

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:

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:

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:

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

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

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

Copyright © 2004 Apple Computer, Inc.