er.extensions.eof
Class ERXKeyFilter

java.lang.Object
  er.extensions.eof.ERXKeyFilter

public class ERXKeyFilter
extends java.lang.Object

ERXKeyFilter provides a way to specify hierarchical rules for including and excluding ERXKeys. This is useful if you need to perform operations on a set of EO's and optional relationships and attributes within those EO's. As an example, ERXRest uses ERXKeyFilter to programmatically specify which attributes and relationships will be rendered for a particular root EO.

ERXKeyFilter is a hierarchical mapping between ERXKeys (single key, not keypaths), whether an include or exclude rule should be applied for that key, and if it's an include, the next set of filter rules to apply to the destination object.

 ERXKeyFilter companyFilter = ERXKeyFilter.filterWithAttribtues();
 ERXKeyFilter remindersFilter = companyFilter.include(Company.REMINDERS);
 remindersFilter.include(Reminder.SUMMARY);
 ERXKeyFilter reminderAuthorFilter = remindersFilter.include(Reminder.AUTHOR);
 reminderAuthorFilter.includeAll();
 reminderAuthorFilter.exclude(Author.HUGE_RELATIONSHIP);
 

more method comments to come ...

Author:

mschrag

Nested Class Summary

static class	ERXKeyFilter.Base ERXKeyFilter.Base defines the base rule that is applied to a filter.
static interface	ERXKeyFilter.Delegate ERXKeyFilter.Delegate defines an interface for receiving notifications when your filter is applied to an object graph.

Constructor Summary

ERXKeyFilter(ERXKeyFilter.Base base)
Creates a new ERXKeyFilter.

ERXKeyFilter(ERXKeyFilter.Base base, ERXKeyFilter.Base nextBase)
Creates a new ERXKeyFilter.

Method Summary

ERXKeyFilter	_filterForKey(ERXKey key) Returns the filter for the given key, or creates a "nextBase" filter if there isn't one.
void	addMap(ERXKey fromKey, ERXKey toKey) Adds a key mapping to this filter.
ERXKeyFilter.Base	base() Returns the base rule for this filter.
ERXKeyFilter.Delegate	delegate() Returns the filter delegate for this filter.
void	exclude(ERXKey... keys) Excludes the given keys from this filter.
com.webobjects.foundation.NSSet<ERXKey>	excludes() Returns the set of keys that are explicitly excluded.
boolean	excludes(ERXKey key) Returns whether or not the given key is excluded.
static ERXKeyFilter	filterWithAll() Shortcut to return a new ERXKeyFilter(All)
static ERXKeyFilter	filterWithAllRecursive() Shortcut to return a new ERXKeyFilter(All, All)
static ERXKeyFilter	filterWithAttributes() Shortcut to return a new ERXKeyFilter(Attributes)
static ERXKeyFilter	filterWithAttributesAndToOneRelationships() Shortcut to return a new ERXKeyFilter(AttributesAndToOneRelationships)
static ERXKeyFilter	filterWithKeys(ERXKey<?>... keys) Shortcut to return a new ERXKeyFilter()
static ERXKeyFilter	filterWithNone() Shortcut to return a new ERXKeyFilter(None)
void	include(ERXKey... keys) Includes the given set of keys in this filter.
ERXKeyFilter	include(ERXKey key) Includes the given key in this filter.
void	includeAll() Sets the base rule to All.
void	includeAttributes() Sets the base rule to Attributes.
void	includeAttributesAndToOneRelationships() Sets the base rule to AttribtuesAndToOneRelationships.
void	includeNone() Sets the base rule to None.
com.webobjects.foundation.NSDictionary<ERXKey,ERXKeyFilter>	includes() Returns the included keys and the next filters they map to.
boolean	includes(ERXKey key) Returns whether or not the given key is included in this filter.
<T> ERXKey<T>	keyMap(ERXKey<T> fromKey) Returns the key that is mapped to from the given input key.
boolean	lockedRelationship(ERXKey key) Returns whether or not the given relationship is locked (i.e.
com.webobjects.foundation.NSSet<ERXKey>	lockedRelationships() Returns the set of relationships that are locked (i.e.
void	lockRelationship(ERXKey... keys) Locks the given relationship on this filter.
boolean	matches(ERXKey key, ERXKey.Type type) Returns whether or not the given key (of the given type, if known) is included in this filter.
ERXKeyFilter.Base	nextBase() Returns the base that is used for subkeys of this key by default.
void	only(ERXKey... keys) Restricts this filter to only allow the given keys.
ERXKeyFilter	only(ERXKey key) Restricts this filter to only allow the given key.
void	setBase(ERXKeyFilter.Base base) Sets the base rule.
void	setDelegate(ERXKeyFilter.Delegate delegate) Associate a filter delegate with this filter.
ERXKeyFilter	setNextBase(ERXKeyFilter.Base nextBase) Sets the base that is used for subkeys of this key by default.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

ERXKeyFilter

public ERXKeyFilter(ERXKeyFilter.Base base)

Creates a new ERXKeyFilter.

Parameters:

base - the base rule to apply

ERXKeyFilter

public ERXKeyFilter(ERXKeyFilter.Base base,
                    ERXKeyFilter.Base nextBase)

Creates a new ERXKeyFilter.

Parameters:

base - the base rule to apply

nextBase - the next base rule to apply

Method Detail

setDelegate

public void setDelegate(ERXKeyFilter.Delegate delegate)

Associate a filter delegate with this filter.

Parameters:

delegate - the delegate to associate

delegate

public ERXKeyFilter.Delegate delegate()

Returns the filter delegate for this filter.

Returns:

the delegate

addMap

public void addMap(ERXKey fromKey,
                   ERXKey toKey)

Adds a key mapping to this filter.

Parameters:

fromKey - the key to map from

toKey - the key to map to

keyMap

public <T> ERXKey<T> keyMap(ERXKey<T> fromKey)

Returns the key that is mapped to from the given input key.

Type Parameters:

T - the type of the key (which doesn't change)

Parameters:

fromKey - the key to map from

Returns:

the key that maps to the given key

filterWithNone

public static ERXKeyFilter filterWithNone()

Shortcut to return a new ERXKeyFilter(None)

Returns:

a new ERXKeyFilter(None)

filterWithAttributes

public static ERXKeyFilter filterWithAttributes()

Shortcut to return a new ERXKeyFilter(Attributes)

Returns:

a new ERXKeyFilter(Attributes)

filterWithKeys

public static ERXKeyFilter filterWithKeys(ERXKey<?>... keys)

Shortcut to return a new ERXKeyFilter()

Parameters:

keys - the keys to include

Returns:

a new ERXKeyFilter(None) with the included keys

filterWithAttributesAndToOneRelationships

public static ERXKeyFilter filterWithAttributesAndToOneRelationships()

Shortcut to return a new ERXKeyFilter(AttributesAndToOneRelationships)

Returns:

a new ERXKeyFilter(AttributesAndToOneRelationships)

filterWithAll

public static ERXKeyFilter filterWithAll()

Shortcut to return a new ERXKeyFilter(All)

Returns:

a new ERXKeyFilter(All)

filterWithAllRecursive

public static ERXKeyFilter filterWithAllRecursive()

Shortcut to return a new ERXKeyFilter(All, All)

Returns:

a new ERXKeyFilter(All, All)

base

public ERXKeyFilter.Base base()

Returns the base rule for this filter.

Returns:

the base rule for this filter

includeAll

public void includeAll()

Sets the base rule to All.

includeAttributes

public void includeAttributes()

Sets the base rule to Attributes.

includeAttributesAndToOneRelationships

public void includeAttributesAndToOneRelationships()

Sets the base rule to AttribtuesAndToOneRelationships.

includeNone

public void includeNone()

Sets the base rule to None.

setBase

public void setBase(ERXKeyFilter.Base base)

Sets the base rule.

Parameters:

base - the base rule

nextBase

public ERXKeyFilter.Base nextBase()

Returns the base that is used for subkeys of this key by default.

Returns:

the base that is used for subkeys of this key by default

setNextBase

public ERXKeyFilter setNextBase(ERXKeyFilter.Base nextBase)

Sets the base that is used for subkeys of this key by default.

Parameters:

nextBase - the base that is used for subkeys of this key by default

Returns:

this (for chaining)

_filterForKey

public ERXKeyFilter _filterForKey(ERXKey key)

Returns the filter for the given key, or creates a "nextBase" filter if there isn't one. This should usually only be called when you know exactly what you're doing, as this doesn't fully interpret include/exclude rules.

Parameters:

key - the key to lookup

Returns:

the key filter

includes

public com.webobjects.foundation.NSDictionary<ERXKey,ERXKeyFilter> includes()

Returns the included keys and the next filters they map to.

Returns:

the included keys and the next filters they map to

excludes

public com.webobjects.foundation.NSSet<ERXKey> excludes()

Returns the set of keys that are explicitly excluded.

Returns:

the set of keys that are explicitly excluded

lockedRelationships

public com.webobjects.foundation.NSSet<ERXKey> lockedRelationships()

Returns the set of relationships that are locked (i.e. cannot be replaced).

Returns:

the set of relationships that are locked (i.e. cannot be replaced)

include

public void include(ERXKey... keys)

Includes the given set of keys in this filter.

Parameters:

keys - the keys to include

includes

public boolean includes(ERXKey key)

Returns whether or not the given key is included in this filter.

Parameters:

key - the key to lookup

Returns:

whether or not the given key is included in this filter

include

public ERXKeyFilter include(ERXKey key)

Includes the given key in this filter.

Parameters:

key - the key to include

Returns:

the next filter

excludes

public boolean excludes(ERXKey key)

Returns whether or not the given key is excluded.

Parameters:

key - the key to lookup

Returns:

whether or not the given key is excluded

lockedRelationship

public boolean lockedRelationship(ERXKey key)

Returns whether or not the given relationship is locked (i.e. value's attributes can be updated but not the relationship cannot be changed).

Parameters:

key - the key to lookup

Returns:

whether or not the given relationship is locked

lockRelationship

public void lockRelationship(ERXKey... keys)

Locks the given relationship on this filter.

Parameters:

keys - the relationships to lock

exclude

public void exclude(ERXKey... keys)

Excludes the given keys from this filter.

Parameters:

keys - the keys to exclude

only

public void only(ERXKey... keys)

Restricts this filter to only allow the given keys.

Parameters:

keys - the keys to restrict to

only

public ERXKeyFilter only(ERXKey key)

Restricts this filter to only allow the given key.

Parameters:

key - the only key to allow

Returns:

the next filter

matches

public boolean matches(ERXKey key,
                       ERXKey.Type type)

Returns whether or not the given key (of the given type, if known) is included in this filter.

Parameters:

key - the key to lookup

type - the type of the key (if known)

Returns:

whether or not this filter matches the key

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object