Examples of KeyFilter

• com.persistit.KeyFilter

  Specifies a subset of all possible keys values. A KeyFilter can be used with the {@link Exchange#traverse(Key.Direction,KeyFilter,int)}method to restrict the set of key values within a Persistit Tree that will actually be traversed.

  A KeyFilter provides two primary methods:

  • {@link #selected(Key)} indicates whether the value of the specifiedKey is a member of the subset specified by this filter, and
  • {@link #next(Key,Key.Direction)} modifies the Key to the nextlarger or smaller key value that lies within the range specified by this filter.

  These methods permit efficient traversal of a filtered subset of keys within a Tree.

  KeyFilter Terms

  A KeyFilter consists of an array of one or more terms. Each term corresponds to one segment in a key value that will be selected or excluded by this KeyFilter. The Kth term in the list applies to the Kth segment of a key.

  There are three kinds of term:

  SimpleTerm

  Represents a single segment value. To match a SimpleTerm, the value of the key segment in the corresponding position must exactly match the SimpleTerm's value.

  RangeTerm

  Represents a range of values. To match a RangeTerm, the value of the key segment in the corresponding position must fall between the end points of the range according to the key ordering specification. RangeTerms can be defined to include or exclude either end point.

  OrTerm

  Represents alternatives. Each alternative is itself a SimpleTerm or a RangeTerm. To match an OrTerm, the value of the key segment in the corresponding position must match one of the alternative terms associated with the OrTerm.

  The static methods {@link #simpleTerm(Object)}, {@link #rangeTerm(Object,Object)}, {@link #rangeTerm(Object,Object,CoderContext)}, {@link #rangeTerm(Object,Object,boolean,boolean)}, {@link #rangeTerm(Object,Object,boolean,boolean,CoderContext)}, and {@link #orTerm} produce these various kinds of Terms

  For example, consider a key consisting of three segments: a last name, a first name and a person ID number for a person. Such a key value might be constructed with code such as this:

   key.clear().append("McDonald").append("Bob").append(12345); 

  Suppose we now want to enumerate all members of a tree having keys of this form with last names falling between "M" and "Q", and first names equal to either "Alice" or "Bob". The following code constructs a KeyFilter for this purpose:

   KeyFilter keyFilter = new KeyFilter(); keyFilter = keyFilter.append(KeyFilter.rangeTerm("M", "Q")); keyFilter = keyFilter.append(KeyFilter.orTerm(new KeyFilter.Term[]{ KeyFilter.simpleTerm("Alice"), KeyFilter.simpleTerm("Bob"))}); 

  The first term specifies a range that includes any last name that sorts alphabetically between "M" and "Q" (inclusively). The second term is an OrTerm that selects the first names "Alice" or "Bob".

  A RangeTerm optionally specifies whether the end-points are inclusive. For example, the term

   KeyFilter.rangeTerm("Jones", "Smith", true, false) 

  includes the name "Jones" and all names that follow up to, but not including, "Smith". If unspecified, the end-points of the range are included.

  Minimum and Maximum Depth

  A KeyFilter may also specify minimum depth, maximum depth, or both. These values control the number of segments that must be present in key value in order for it to be selected. A KeyFilter will select a key only if the number of segments in the key lies between the minimum depth and the maximum depth, inclusive.

  String Representation

  The {@link #toString()} method returns a canonical String representation ofthe current terms for this KeyFilter. For example, the string representation of the filter constructed in above is

   {"M":"Q",{"Alice","Bob"}} 

  You can construct a KeyFilter from its string representation with the {@link KeyParser#parseKeyFilter} method. For example, the followingcode generates an equivalent KeyFilter:

   KeyParser parser = new KeyParser("{\"M\":\"Q\",{\"Alice\",\"Bob\"}}; KeyFilter filter = parser.parseKeyFilter(); 

  As a convenience, the constructor {@link #KeyFilter(String)} automaticallycreates and invokes a KeyParser to create a KeyFilter from its string representation.

  Following is an informal grammar for the string representation of a key filter. See string representation in {@link Key} for information on how to specify a keysegment value.

   keyFilter ::= '{' termElement [',' termElement]... '}' termElement ::= [ '>' ] term [ '<' ] term ::= segment | range | qualifiedRange | orTerm segment ::= see segment range ::= segment ':' segment | ':' segment | segment ':' qualifiedRange = ('(' | '[') range (')' | ']') orTerm ::= '{' term [',' term ]...'}' 

  A range may omit either the starting segment value or the ending segment value. When the starting segment value is omitted, the range starts before the first possible key value, and when the ending segment value is omitted, the range ends after the last possible key value. Thus the range specification

   {"Smith":} 

  include every key with a first segment value of "Smith" or above. Similarly,

   {:"Smith"} 

  includes all keys up to and including "Smith".

  A qualifiedRange allows you to specify whether the end-points of a range are included or excluded from the selected subset. A square bracket indicates that the end-point is included, while a parenthesis indicates that it is excluded. For example

   {("Jones":"Smith"]} 

  does not include "Jones" but does include "Smith". An unqualified range specification such as

   {"Jones":"Smith"} 

  includes both end-points. It is equivelent to

   {["Jones":"Smith"]} 

  Within the string representation of a KeyFilter at most one term element may specify the prefix ">" (greater-than sign), and at most one term element may specify the suffix "<" (less-than sign). These denote the minimum and maximum depths of the KeyFilter, respectively. The minimum depth is the count of term elements up to and including the term marked with a ">" and the maximum depth is the count of terms up to and including the term marked with a ">". For example, in the KeyFilter represented by the string

   {*,>100:200,*<} 

  the minimum depth is 2 and the maximum depth is 3.

  Building KeyFilters by Appending Terms

  A KeyFilter is immutable. The methods {@link #append(KeyFilter)}, {@link #append(KeyFilter.Term)}, {@link #append(KeyFilter.Term[])}, create new KeyFilters with additional terms supplied by the supplied KeyFilter, Term or array of Terms. The {@link #limit} method creates a new KeyFilter with modifiedminimum and maximum depth values. Each of these methods returns a new KeyFilter which results from combining the original KeyFilter with the supplied information.

  Formal Specification of the {@link #next(Key,Key.Direction)} Method

  A KeyFilter defines a subset of the the set of all Key values: the {@link Exchange#traverse(Key.Direction,KeyFilter,int)} method returns onlyvalues in this subset. The following definitions are used in describing the behavior of the {@link #next(Key,Key.Direction)} method.

  Range

  Let S be the ordered set of all possible key values. (Though large, this set is finite because a Keys have finite length.) The range R is the subset of keys in S selected by this KeyFilter.

  Adjacent

  Two keys K1 and K2 in this set are adjacent if K1 != K2 and there exists no other key value K such that K1 < K < K2. The terms left-adjacent and right-adjacent describe the precedence: K1 is left-adjacent to K2; K2 is right-adjacent to K1

  Contiguous

  Let C be a subset of R. Let Kmin and Kmax be the smallest and largest keys in C, respectively. Then C is contiguous if there is no key K not in R where Kmin < K < Kmax.

  Direction

  The {@link Key.Direction} is supplied to the{@link Exchange#traverse(Key.Direction,KeyFilter,int)} method to controlnavigation. There are five possible values:

  • LT: the result key must be strictly less than the supplied key.
  • LTEQ: the result key must be less than or equal to the supplied key.
  • EQ: the result key must be equal to the supplied key.
  • GTEQ: the result key must be greater than or equal to the supplied key.
  • GT: the result key must be strictly greater than the supplied key.

  LT and GT are called exclusive because the result of traverse excludes the supplied key. LTEQ and GTEQ are inclusive.

  A KeyFilter defines the range R as zero or more contiguous subsets of S. The next method is used to assist the traverse method by skipping efficiently over keys that are not in contained in R. Given a {@link Key} K and a {@link Key.Direction} D, the method behaves as follows:

  1. If K is in R (i.e., is selected) and either D is inclusive, or there exists a key value K' in R that is adjacent to K (where K' is larger than K if D is GT, or smaller than K if D is LT), then return true without modifying the K.
  2. Otherwise attempt to modify K to a new value K' which is either adjacent to or in the next contiguous subset of R, and return true to indicate that more keys exist in the range. Specifically, for each Direction D, K' is defined as follows:
     • LT: find the largest key J in R where J < K. Then K' is the key right-adjacent to J.
     • LTEQ: find the largest key J in R where J < K. Then K' is J.
     • EQ: there is no K'
     • GTEQ: find the smallest key J in R where J > K. Then K' is J.
     • GT: find the smallest key J in R where J < K. Then K' is the key left-adjacent to J.
  3. Otherwise, if there is no key K' that satisfies the requirements of #2, return false to indicate that the range has been exhausted.

  @version 1.0

• org.infinispan.filter.KeyFilter
  A filter for keys. This class is complemented by the {@link org.infinispan.filter.KeyValueFilter} class. Thisclass is useful for cases when it may be more beneficial to not have the values available. This would include cache loaders since many implementations it may incur additional performance costs just to resurrect the values in addition to any keys. @author Manik Surtani @since 6.0
• org.infinispan.notifications.KeyFilter
  A filter for keys. @author Manik Surtani @since 6.0

Examples of org.infinispan.notifications.KeyFilter