RowFilter (Java SE 22 & JDK 22)
Description: declaration: module: java.desktop, package: javax.swing, class: RowFilter
Keywords: javax.swing.RowFilter class

Module java.desktop
Package javax.swing

# Class RowFilter<M,I>

java.lang.Object
javax.swing.RowFilter<M,I>

Type Parameters:
  `M` - the type of the model; for example `PersonModel`
  `I` - the type of the identifier; when using `TableRowSorter` this will be `Integer`

public abstract class RowFilter<M,I> extends Object
`RowFilter` is used to filter out entries from the model so that they are not shown in the view. For example, a `RowFilter` associated with a `JTable` might only allow rows that contain a column with a specific string. The meaning of entry depends on the component type. For example, when a filter is associated with a `JTable`, an entry corresponds to a row; when associated with a `JTree`, an entry corresponds to a node.

Subclasses must override the `include` method to indicate whether the entry should be shown in the view. The `Entry` argument can be used to obtain the values in each of the columns in that entry. The following example shows an `include` method that allows only entries containing one or more values starting with the string "a":

     RowFilter<Object,Object> startsWithAFilter = new RowFilter<Object,Object>() {
       public boolean include(Entry<? extends Object, ? extends Object> entry) {
         for (int i = entry.getValueCount() - 1; i >= 0; i--) {
           if (entry.getStringValue(i).startsWith("a")) {
             // The value starts with "a", include it
             return true;
           }
         }
         // None of the columns start with "a"; return false so that this
         // entry is not shown
         return false;
       }
     };

`RowFilter` has two formal type parameters that allow you to create a `RowFilter` for a specific model. For example, the following assumes a specific model that is wrapping objects of type `Person`. Only `Person`s with an age over 20 will be shown:

     RowFilter<PersonModel,Integer> ageFilter = new RowFilter<PersonModel,Integer>() {
       public boolean include(Entry<? extends PersonModel, ? extends Integer> entry) {
         PersonModel personModel = entry.getModel();
         Person person = personModel.getPerson(entry.getIdentifier());
         if (person.getAge() > 20) {
           // Returning true indicates this row should be shown.
           return true;
         }
         // Age is <= 20, don't show it.
         return false;
       }
     };
     PersonModel model = createPersonModel();
     TableRowSorter<PersonModel> sorter = new TableRowSorter<PersonModel>(model);
     sorter.setRowFilter(ageFilter);

Since:
  1.6
See Also:
  - `TableRowSorter`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `RowFilter.ComparisonType`
  Enumeration of the possible comparison values supported by some of the default `RowFilter`s.
  `static class`
  `RowFilter.Entry<M,I>`
  An `Entry` object is passed to instances of `RowFilter`, allowing the filter to get the value of the entry's data, and thus to determine whether the entry should be shown.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `RowFilter()`
  Constructor for subclasses to call.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <M, I> RowFilter<M,I>`
  `andFilter(Iterable<? extends RowFilter<? super M,? super I>> filters)`
  Returns a `RowFilter` that includes entries if all of the supplied filters include the entry.
  `static <M, I> RowFilter<M,I>`
  `dateFilter(RowFilter.ComparisonType type, Date date, int... indices)`
  Returns a `RowFilter` that includes entries that have at least one `Date` value meeting the specified criteria.
  `abstract boolean`
  `include(RowFilter.Entry<? extends M,? extends I> entry)`
  Returns true if the specified entry should be shown; returns false if the entry should be hidden.
  `static <M, I> RowFilter<M,I>`
  `notFilter(RowFilter<M,I> filter)`
  Returns a `RowFilter` that includes entries if the supplied filter does not include the entry.
  `static <M, I> RowFilter<M,I>`
  `numberFilter(RowFilter.ComparisonType type, Number number, int... indices)`
  Returns a `RowFilter` that includes entries that have at least one `Number` value meeting the specified criteria.
  `static <M, I> RowFilter<M,I>`
  `orFilter(Iterable<? extends RowFilter<? super M,? super I>> filters)`
  Returns a `RowFilter` that includes entries if any of the supplied filters includes the entry.
  `static <M, I> RowFilter<M,I>`
  `regexFilter(String regex, int... indices)`
  Returns a `RowFilter` that uses a regular expression to determine which entries to include.

  ### Methods declared in class java.lang.Object

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

- ## Constructor Details

  - ### RowFilter

    protected RowFilter()
    Constructor for subclasses to call.

- ## Method Details

  - ### regexFilter

    public static <M, I> RowFilter<M,I> regexFilter(String regex, int... indices)
    Returns a `RowFilter` that uses a regular expression to determine which entries to include. Only entries with at least one matching value are included. For example, the following creates a `RowFilter` that includes entries with at least one value starting with "a":

           RowFilter.regexFilter("^a");

    The returned filter uses `Matcher.find()` to test for inclusion. To test for exact matches use the characters '^' and '$' to match the beginning and end of the string respectively. For example, "^foo$" includes only rows whose string is exactly "foo" and not, for example, "food". See `Pattern` for a complete description of the supported regular-expression constructs.

    Type Parameters:
      `M` - the type of the model to which the `RowFilter` applies
      `I` - the type of the identifier passed to the `RowFilter`
    Parameters:
      `regex` - the regular expression to filter on
      `indices` - the indices of the values to check. If not supplied all values are evaluated
    Returns:
      a `RowFilter` implementing the specified criteria
    Throws:
      `NullPointerException` - if `regex` is `null`
      `IllegalArgumentException` - if any of the `indices` are < 0
      `PatternSyntaxException` - if `regex` is not a valid regular expression.
    See Also:
      - `Pattern`

  - ### dateFilter

    public static <M, I> RowFilter<M,I> dateFilter(RowFilter.ComparisonType type, Date date, int... indices)
    Returns a `RowFilter` that includes entries that have at least one `Date` value meeting the specified criteria. For example, the following `RowFilter` includes only entries with at least one date value after the current date:

           RowFilter.dateFilter(ComparisonType.AFTER, new Date());

    Type Parameters:
      `M` - the type of the model to which the `RowFilter` applies
      `I` - the type of the identifier passed to the `RowFilter`
    Parameters:
      `type` - the type of comparison to perform
      `date` - the date to compare against
      `indices` - the indices of the values to check. If not supplied all values are evaluated
    Returns:
      a `RowFilter` implementing the specified criteria
    Throws:
      `NullPointerException` - if `date` is `null`
      `IllegalArgumentException` - if any of the `indices` are < 0 or `type` is `null`
    See Also:
      - `Calendar`
      - `Date`

  - ### numberFilter

    public static <M, I> RowFilter<M,I> numberFilter(RowFilter.ComparisonType type, Number number, int... indices)
    Returns a `RowFilter` that includes entries that have at least one `Number` value meeting the specified criteria. For example, the following filter will only include entries with at least one number value equal to 10:

           RowFilter.numberFilter(ComparisonType.EQUAL, 10);

    Type Parameters:
      `M` - the type of the model to which the `RowFilter` applies
      `I` - the type of the identifier passed to the `RowFilter`
    Parameters:
      `type` - the type of comparison to perform
      `number` - a `Number` value to compare against
      `indices` - the indices of the values to check. If not supplied all values are evaluated
    Returns:
      a `RowFilter` implementing the specified criteria
    Throws:
      `IllegalArgumentException` - if any of the `indices` are < 0, `type` is `null` or `number` is `null`

  - ### orFilter

    public static <M, I> RowFilter<M,I> orFilter(Iterable<? extends RowFilter<? super M,? super I>> filters)
    Returns a `RowFilter` that includes entries if any of the supplied filters includes the entry.

    The following example creates a `RowFilter` that will include any entries containing the string "foo" or the string "bar":

           List<RowFilter<Object,Object>> filters = new ArrayList<RowFilter<Object,Object>>(2);
           filters.add(RowFilter.regexFilter("foo"));
           filters.add(RowFilter.regexFilter("bar"));
           RowFilter<Object,Object> fooBarFilter = RowFilter.orFilter(filters);

    Type Parameters:
      `M` - the type of the model to which the `RowFilter` applies
      `I` - the type of the identifier passed to the `RowFilter`
    Parameters:
      `filters` - the `RowFilter`s to test
    Returns:
      a `RowFilter` implementing the specified criteria
    Throws:
      `IllegalArgumentException` - if any of the filters are `null`
      `NullPointerException` - if `filters` is null
    See Also:
      - `Arrays.asList(T...)`

  - ### andFilter

    public static <M, I> RowFilter<M,I> andFilter(Iterable<? extends RowFilter<? super M,? super I>> filters)
    Returns a `RowFilter` that includes entries if all of the supplied filters include the entry.

    The following example creates a `RowFilter` that will include any entries containing the string "foo" and the string "bar":

           List<RowFilter<Object,Object>> filters = new ArrayList<RowFilter<Object,Object>>(2);
           filters.add(RowFilter.regexFilter("foo"));
           filters.add(RowFilter.regexFilter("bar"));
           RowFilter<Object,Object> fooBarFilter = RowFilter.andFilter(filters);

    Type Parameters:
      `M` - the type of the model the `RowFilter` applies to
      `I` - the type of the identifier passed to the `RowFilter`
    Parameters:
      `filters` - the `RowFilter`s to test
    Returns:
      a `RowFilter` implementing the specified criteria
    Throws:
      `IllegalArgumentException` - if any of the filters are `null`
      `NullPointerException` - if `filters` is null
    See Also:
      - `Arrays.asList(T...)`

  - ### notFilter

    public static <M, I> RowFilter<M,I> notFilter(RowFilter<M,I> filter)
    Returns a `RowFilter` that includes entries if the supplied filter does not include the entry.
    Type Parameters:
      `M` - the type of the model to which the `RowFilter` applies
      `I` - the type of the identifier passed to the `RowFilter`
    Parameters:
      `filter` - the `RowFilter` to negate
    Returns:
      a `RowFilter` implementing the specified criteria
    Throws:
      `IllegalArgumentException` - if `filter` is `null`

  - ### include

    public abstract boolean include(RowFilter.Entry<? extends M,? extends I> entry)
    Returns true if the specified entry should be shown; returns false if the entry should be hidden.

    The `entry` argument is valid only for the duration of the invocation. Using `entry` after the call returns results in undefined behavior.

    Parameters:
      `entry` - a non-`null` object that wraps the underlying object from the model
    Returns:
      true if the entry should be shown