ERXKeyFilter (Project Wonder Reference Documentation)

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

```
public class ERXKeyFilter
extends 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);
 
```
For keys representing to-many relationships you can set a distinct flag if you want to filter that relationship to return only distinct objects. For this you can either pass in a key with the unique operator of ERXArrayUtilities or explicitly set the flag:
```
 ERXKeyFilter companyFilter = ERXKeyFilter.filterWithAttribtues();
 companyFilter.include(ERXKey.unique(Company.EMPLOYEES));
 companyFilter.include(Company.CLIENTS).setDistinct(true);
 
```
more method comments to come ...
Author:

mschrag

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`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

Constructors
Constructor and Description
`ERXKeyFilter(ERXKeyFilter.Base base)` Creates a new ERXKeyFilter.
`ERXKeyFilter(ERXKeyFilter.Base base, ERXKeyFilter.Base nextBase)` Creates a new ERXKeyFilter.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`ERXKeyFilter`	`_filterForKey(ERXKey key)` Returns the filter for the given key, or creates a "nextBase" filter if there isn't one.
`ERXKeyFilter`	`_filterForKey(String 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.
`void`	`addMap(String fromKey, String toKey)` Adds a key mapping to this filter.
`ERXKeyFilter.Base`	`base()` Returns the base rule for this filter.
`protected ERXKeyFilter`	`createFilter(ERXKeyFilter.Base base)`
`protected ERXKeyFilter`	`createNextFilter()`
`ERXKeyFilter.Delegate`	`delegate()` Returns the filter delegate for this filter.
`void`	`exclude(ERXKey... keys)` Excludes the given keys from this filter.
`void`	`exclude(String... keys)` Excludes the given keys from this filter.
`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.
`boolean`	`excludes(String 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`	`filterWithKeys(String... 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.
`ERXKeyFilter`	`include(ERXKey key, ERXKeyFilter existingFilter)` Includes the given key in this filter.
`void`	`include(String... keyNames)` Includes the given set of keys in this filter, wrapping them in ERXKey objects for you.
`ERXKeyFilter`	`include(String key)` Includes the given key in this filter.
`ERXKeyFilter`	`include(String keyName, ERXKeyFilter existingFilter)` Includes the given key in this filter, wrapping it in an ERXKey object for you.
`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.
`Map<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.
`boolean`	`includes(String key)` Returns whether or not the given key is included in this filter.
`boolean`	`isAnonymousUpdateEnabled()` Returns whether or not nodes without ids will result in an anonymous update or an object creation.
`boolean`	`isDeduplicationEnabled()` Returns whether or not duplicate objects are collapsed to just an id.
`boolean`	`isDistinct()` Returns whether or not a to-many relationship should return only distinct objects.
`boolean`	`isUnknownKeyIgnored()` Returns whether or not unknown keys are ignored rather than throwing an unknown key exception.
`<T> ERXKey<T>`	`keyMap(ERXKey<T> fromKey)` Returns the key that is mapped to from the given input key.
`String`	`keyMap(String 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.
`boolean`	`lockedRelationship(String key)` Returns whether or not the given relationship is locked (i.e.
`NSSet<ERXKey>`	`lockedRelationships()` Returns the set of relationships that are locked (i.e.
`void`	`lockRelationship(ERXKey... keys)` Locks the given relationship on this filter.
`void`	`lockRelationship(String... 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.
`boolean`	`matches(String 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`	`only(String... keys)` Restricts this filter to only allow the given keys.
`ERXKeyFilter`	`only(String key)` Restricts this filter to only allow the given key.
`void`	`setAnonymousUpdateEnabled(boolean anonymousUpdateEnabled)` Sets whether nodes without ids will result in an anonymous update or an object creation.
`void`	`setBase(ERXKeyFilter.Base base)` Sets the base rule.
`void`	`setDeduplicationEnabled(boolean deduplicationEnabled)` Sets whether or not duplicate objects are collapsed to just an id in the filtered graph.
`void`	`setDelegate(ERXKeyFilter.Delegate delegate)` Associate a filter delegate with this filter.
`ERXKeyFilter`	`setDistinct(boolean distinct)` Sets whether or not a to-many relationship should return only distinct objects.
`ERXKeyFilter`	`setNextBase(ERXKeyFilter.Base nextBase)` Sets the base that is used for subkeys of this key by default.
`void`	`setSortOrderings(NSArray<EOSortOrdering> sortOrderings)` Sets the sort orderings that will be applied by this key filter.
`void`	`setUnknownKeyIgnored(boolean unknownKeyIgnored)` Sets whether or not unknown keys are ignored rather than throwing an unknown key exception.
`NSArray<EOSortOrdering>`	`sortOrderings()` Returns the sort orderings that will be applied by this key filter.
`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
  - addMap
```
public void addMap(String fromKey,
                   String 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
  - keyMap
```
public String keyMap(String fromKey)
```
    Returns the key that is mapped to from the given input key.
    
    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
  - filterWithKeys
```
public static ERXKeyFilter filterWithKeys(String... 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
  - createFilter
```
protected ERXKeyFilter createFilter(ERXKeyFilter.Base base)
```
  - createNextFilter
```
protected ERXKeyFilter createNextFilter()
```
  - 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)
  - setAnonymousUpdateEnabled
```
public void setAnonymousUpdateEnabled(boolean anonymousUpdateEnabled)
```
    Sets whether nodes without ids will result in an anonymous update or an object creation. An anonymous update means that whatever object currently exists will remain, and the nested object graph will be applied as a recursive update.
    
    Parameters:
    
    anonymousUpdateEnabled - whether nodes without ids will result in an anonymous update or an object creation
  - isAnonymousUpdateEnabled
```
public boolean isAnonymousUpdateEnabled()
```
    Returns whether or not nodes without ids will result in an anonymous update or an object creation.
    
    Returns:
    
    whether or not nodes without ids will result in an anonymous update or an object creation
  - setDeduplicationEnabled
```
public void setDeduplicationEnabled(boolean deduplicationEnabled)
```
    Sets whether or not duplicate objects are collapsed to just an id in the filtered graph. This only applies to filters used to render object graphs.
    
    Parameters:
    
    deduplicationEnabled - if true, duplicate objects are collapsed into ids
  - isDeduplicationEnabled
```
public boolean isDeduplicationEnabled()
```
    Returns whether or not duplicate objects are collapsed to just an id.
    
    Returns:
    
    whether or not duplicate objects are collapsed to just an id
  - _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
  - _filterForKey
```
public ERXKeyFilter _filterForKey(String 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 Map<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 NSSet<ERXKey> excludes()
```
    Returns the set of keys that are explicitly excluded.
    
    Returns:
    
    the set of keys that are explicitly excluded
  - lockedRelationships
```
public 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(String... keyNames)
```
    Includes the given set of keys in this filter, wrapping them in ERXKey objects for you.
    
    Parameters:
    
    keyNames - the names of the keys to include
  - include
```
public ERXKeyFilter include(String keyName,
                            ERXKeyFilter existingFilter)
```
    Includes the given key in this filter, wrapping it in an ERXKey object for you.
    
    Parameters:
    
    keyName - the key to include
    
    existingFilter - the existing filter to use for this key
    
    Returns:
    
    the next filter
  - 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
  - includes
```
public boolean includes(String 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
  - include
```
public ERXKeyFilter include(String key)
```
    Includes the given key in this filter.
    
    Parameters:
    
    key - the key to include
    
    Returns:
    
    the next filter
  - include
```
public ERXKeyFilter include(ERXKey key,
                            ERXKeyFilter existingFilter)
```
    Includes the given key in this filter.
    
    Parameters:
    
    key - the key to include
    
    existingFilter - the existing filter to use for this key
    
    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
  - excludes
```
public boolean excludes(String 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
  - lockedRelationship
```
public boolean lockedRelationship(String 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
  - lockRelationship
```
public void lockRelationship(String... 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
  - exclude
```
public void exclude(String... 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 void only(String... 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
  - only
```
public ERXKeyFilter only(String key)
```
    Restricts this filter to only allow the given key.
    
    Parameters:
    
    key - the only key to allow
    
    Returns:
    
    the next filter
  - setSortOrderings
```
public void setSortOrderings(NSArray<EOSortOrdering> sortOrderings)
```
    Sets the sort orderings that will be applied by this key filter. The actual meaning of this is up to the code that applies this key filter to an object graph. A common example would be if you want to selectively sort the results of a to-many relationship that this filter is applied to.
    
    Parameters:
    
    sortOrderings - the sort orderings that will be applied by this key filter
  - sortOrderings
```
public NSArray<EOSortOrdering> sortOrderings()
```
    Returns the sort orderings that will be applied by this key filter.
    
    Returns:
    
    the sort orderings that will be applied by this key filter
  - setUnknownKeyIgnored
```
public void setUnknownKeyIgnored(boolean unknownKeyIgnored)
```
    Sets whether or not unknown keys are ignored rather than throwing an unknown key exception.
    
    Parameters:
    
    unknownKeyIgnored - if true, unknown keys are ignored
  - isUnknownKeyIgnored
```
public boolean isUnknownKeyIgnored()
```
    Returns whether or not unknown keys are ignored rather than throwing an unknown key exception.
    
    Returns:
    
    whether or not unknown keys are ignored rather than throwing an unknown key exception
  - setDistinct
```
public ERXKeyFilter setDistinct(boolean distinct)
```
    Sets whether or not a to-many relationship should return only distinct objects.
    
    Parameters:
    
    distinct - if true and the key represents a to-many only distinct objects will be returned
    
    Returns:
    
    this filter
  - isDistinct
```
public boolean isDistinct()
```
    Returns whether or not a to-many relationship should return only distinct objects.
    
    Returns:
    
    whether or not a to-many relationship should return only distinct objects.
  - 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
  - matches
```
public boolean matches(String 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 String toString()
```
    Overrides:
    
    toString in class Object

Class ERXKeyFilter

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ERXKeyFilter

ERXKeyFilter

Method Detail

setDelegate

delegate

addMap

addMap

keyMap

keyMap

filterWithNone

filterWithAttributes

filterWithKeys

filterWithKeys

filterWithAttributesAndToOneRelationships

filterWithAll

filterWithAllRecursive

base

includeAll

includeAttributes

includeAttributesAndToOneRelationships

includeNone

setBase

nextBase

createFilter

createNextFilter

setNextBase

setAnonymousUpdateEnabled

isAnonymousUpdateEnabled

setDeduplicationEnabled

isDeduplicationEnabled

_filterForKey

_filterForKey

includes

excludes

lockedRelationships

include

include

include

includes

includes

include

include

include

excludes

excludes

lockedRelationship

lockedRelationship

lockRelationship

lockRelationship

exclude

exclude

only

only

only

only

setSortOrderings

sortOrderings

setUnknownKeyIgnored

isUnknownKeyIgnored

setDistinct

isDistinct

matches

matches

toString