org.springframework.data.domain

## Interface ExampleMatcher

    public interface ExampleMatcher

Specification for property path matching to use in query by example (QBE). An `ExampleMatcher` can be created for a `object type`. Instances of `ExampleMatcher` can be either `matchingAll()` or `matchingAny()` and settings can be tuned `with...` methods in a fluent style. `with...` methods return a copy of the `ExampleMatcher` instance with the specified setting. Null-handling defaults to `ExampleMatcher.NullHandler.IGNORE` and case-sensitive `ExampleMatcher.StringMatcher.DEFAULT` string matching.

This class is immutable.

Since:
  1.12
Author:
  Christoph Strobl, Mark Paluch, Oliver Gierke, Jens Schauder

### Nested Class Summary

Nested Classes
`static class` `ExampleMatcher.GenericPropertyMatcher` A generic property matcher that specifies `string matching` and case sensitivity.
`static class` `ExampleMatcher.GenericPropertyMatchers` Predefined property matchers to create a `ExampleMatcher.GenericPropertyMatcher`.
`static interface` `ExampleMatcher.MatcherConfigurer<T>` Callback to configure a matcher.
`static class` `ExampleMatcher.MatchMode` The match modes to expose so that clients can find about how to concatenate the predicates.
`static class` `ExampleMatcher.NoOpPropertyValueTransformer`
`static class` `ExampleMatcher.NullHandler` Null handling for creating criterion out of an `Example`.
`static class` `ExampleMatcher.PropertySpecifier` Define specific property handling for a Dot-Path.
`static class` `ExampleMatcher.PropertySpecifiers` Define specific property handling for Dot-Paths.
`static interface` `ExampleMatcher.PropertyValueTransformer` Allows to transform the property value before it is used in the query.
`static class` `ExampleMatcher.StringMatcher` Match modes for treatment of `String` values.

### Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
`ExampleMatcher.StringMatcher` `getDefaultStringMatcher()` Get defined `ExampleMatcher.StringMatcher`.
`Set<String>` `getIgnoredPaths()`
`ExampleMatcher.MatchMode` `getMatchMode()` Get the match mode of the `ExampleMatcher`.
`ExampleMatcher.NullHandler` `getNullHandler()` Get defined null handling.
`ExampleMatcher.PropertySpecifiers` `getPropertySpecifiers()`
`default boolean` `isAllMatching()` Returns whether all of the predicates of the `Example` are supposed to match.
`default boolean` `isAnyMatching()` Returns whether it's sufficient that any of the predicates of the `Example` match.
`boolean` `isIgnoreCaseEnabled()`
`default boolean` `isIgnoredPath(String path)`
`static ExampleMatcher` `matching()` Create a new `ExampleMatcher` including all non-null properties by default matching all predicates derived from the example.
`static ExampleMatcher` `matchingAll()` Create a new `ExampleMatcher` including all non-null properties by default matching all predicates derived from the example.
`static ExampleMatcher` `matchingAny()` Create a new `ExampleMatcher` including all non-null properties by default matching any predicate derived from the example.
`default ExampleMatcher` `withIgnoreCase()` Returns a copy of this `ExampleMatcher` with ignoring case sensitivity by default.
`ExampleMatcher` `withIgnoreCase(boolean defaultIgnoreCase)` Returns a copy of this `ExampleMatcher` with `defaultIgnoreCase`.
`ExampleMatcher` `withIgnoreCase(String... propertyPaths)` Returns a copy of this `ExampleMatcher` with ignore case sensitivity for the `propertyPaths`.
`default ExampleMatcher` `withIgnoreNullValues()` Returns a copy of this `ExampleMatcher` with treatment for null values of `ExampleMatcher.NullHandler.IGNORE`.
`ExampleMatcher` `withIgnorePaths(String... ignoredPaths)` Returns a copy of this `ExampleMatcher` with the specified `propertyPaths`.
`default ExampleMatcher` `withIncludeNullValues()` Returns a copy of this `ExampleMatcher` with treatment for null values of `ExampleMatcher.NullHandler.INCLUDE` .
`ExampleMatcher` `withMatcher(String propertyPath, ExampleMatcher.GenericPropertyMatcher genericPropertyMatcher)` Returns a copy of this `ExampleMatcher` with the specified `GenericPropertyMatcher` for the `propertyPath`.
`default ExampleMatcher` `withMatcher(String propertyPath, ExampleMatcher.MatcherConfigurer<ExampleMatcher.GenericPropertyMatcher> matcherConfigurer)` Returns a copy of this `ExampleMatcher` with the specified `GenericPropertyMatcher` for the `propertyPath`.
`ExampleMatcher` `withNullHandler(ExampleMatcher.NullHandler nullHandler)` Returns a copy of this `ExampleMatcher` with the specified `nullHandler`.
`ExampleMatcher` `withStringMatcher(ExampleMatcher.StringMatcher defaultStringMatcher)` Returns a copy of this `ExampleMatcher` with the specified string matching of `defaultStringMatcher`.
`ExampleMatcher` `withTransformer(String propertyPath, ExampleMatcher.PropertyValueTransformer propertyValueTransformer)` Returns a copy of this `ExampleMatcher` with the specified `PropertyValueTransformer` for the `propertyPath`.

### Method Detail

#### matching

    static ExampleMatcher matching()

Create a new `ExampleMatcher` including all non-null properties by default matching all predicates derived from the example.

Returns:
  new instance of `ExampleMatcher`.
See Also:
  `matchingAll()`

#### matchingAny

    static ExampleMatcher matchingAny()

Create a new `ExampleMatcher` including all non-null properties by default matching any predicate derived from the example.

Returns:
  new instance of `ExampleMatcher`.

#### matchingAll

    static ExampleMatcher matchingAll()

Create a new `ExampleMatcher` including all non-null properties by default matching all predicates derived from the example.

Returns:
  new instance of `ExampleMatcher`.

#### withIgnorePaths

    ExampleMatcher withIgnorePaths(String... ignoredPaths)

Returns a copy of this `ExampleMatcher` with the specified `propertyPaths`. This instance is immutable and unaffected by this method call.

Parameters:
  `ignoredPaths` - must not be null and not empty.
Returns:
  new instance of `ExampleMatcher`.

#### withStringMatcher

    ExampleMatcher withStringMatcher(ExampleMatcher.StringMatcher defaultStringMatcher)

Returns a copy of this `ExampleMatcher` with the specified string matching of `defaultStringMatcher`. This instance is immutable and unaffected by this method call.

Parameters:
  `defaultStringMatcher` - must not be null.
Returns:
  new instance of `ExampleMatcher`.

#### withIgnoreCase

    default ExampleMatcher withIgnoreCase()

Returns a copy of this `ExampleMatcher` with ignoring case sensitivity by default. This instance is immutable and unaffected by this method call.

Returns:
  new instance of `ExampleMatcher`.

#### withIgnoreCase

    ExampleMatcher withIgnoreCase(boolean defaultIgnoreCase)

Returns a copy of this `ExampleMatcher` with `defaultIgnoreCase`. This instance is immutable and unaffected by this method call.

Parameters:
  `defaultIgnoreCase` -
Returns:
  new instance of `ExampleMatcher`.

#### withMatcher

    default ExampleMatcher withMatcher(String propertyPath,
                                       ExampleMatcher.MatcherConfigurer<ExampleMatcher.GenericPropertyMatcher> matcherConfigurer)

Returns a copy of this `ExampleMatcher` with the specified `GenericPropertyMatcher` for the `propertyPath`. This instance is immutable and unaffected by this method call.

Parameters:
  `propertyPath` - must not be null.
  `matcherConfigurer` - callback to configure a `ExampleMatcher.GenericPropertyMatcher`, must not be null.
Returns:
  new instance of `ExampleMatcher`.

#### withMatcher

    ExampleMatcher withMatcher(String propertyPath,
                               ExampleMatcher.GenericPropertyMatcher genericPropertyMatcher)

Returns a copy of this `ExampleMatcher` with the specified `GenericPropertyMatcher` for the `propertyPath`. This instance is immutable and unaffected by this method call.

Parameters:
  `propertyPath` - must not be null.
  `genericPropertyMatcher` - callback to configure a `ExampleMatcher.GenericPropertyMatcher`, must not be null.
Returns:
  new instance of `ExampleMatcher`.

#### withTransformer

    ExampleMatcher withTransformer(String propertyPath,
                                   ExampleMatcher.PropertyValueTransformer propertyValueTransformer)

Returns a copy of this `ExampleMatcher` with the specified `PropertyValueTransformer` for the `propertyPath`.

Parameters:
  `propertyPath` - must not be null.
  `propertyValueTransformer` - must not be null.
Returns:
  new instance of `ExampleMatcher`.

#### withIgnoreCase

    ExampleMatcher withIgnoreCase(String... propertyPaths)

Returns a copy of this `ExampleMatcher` with ignore case sensitivity for the `propertyPaths`. This instance is immutable and unaffected by this method call.

Parameters:
  `propertyPaths` - must not be null and not empty.
Returns:
  new instance of `ExampleMatcher`.

#### withIncludeNullValues

    default ExampleMatcher withIncludeNullValues()

Returns a copy of this `ExampleMatcher` with treatment for null values of `ExampleMatcher.NullHandler.INCLUDE` . This instance is immutable and unaffected by this method call.

Returns:
  new instance of `ExampleMatcher`.

#### withIgnoreNullValues

    default ExampleMatcher withIgnoreNullValues()

Returns a copy of this `ExampleMatcher` with treatment for null values of `ExampleMatcher.NullHandler.IGNORE`. This instance is immutable and unaffected by this method call.

Returns:
  new instance of `ExampleMatcher`.

#### withNullHandler

    ExampleMatcher withNullHandler(ExampleMatcher.NullHandler nullHandler)

Returns a copy of this `ExampleMatcher` with the specified `nullHandler`. This instance is immutable and unaffected by this method call.

Parameters:
  `nullHandler` - must not be null.
Returns:
  new instance of `ExampleMatcher`.

#### getNullHandler

    ExampleMatcher.NullHandler getNullHandler()

Get defined null handling.

Returns:
  never null

#### getDefaultStringMatcher

    ExampleMatcher.StringMatcher getDefaultStringMatcher()

Get defined `ExampleMatcher.StringMatcher`.

Returns:
  never null.

#### isIgnoreCaseEnabled

    boolean isIgnoreCaseEnabled()

Returns:
  true if `String` should be matched with ignore case option.

#### isIgnoredPath

    default boolean isIgnoredPath(String path)

Parameters:
  `path` - must not be null.
Returns:
  return true if path was set to be ignored.

#### getIgnoredPaths

    Set<String> getIgnoredPaths()

Returns:
  unmodifiable `Set` of ignored paths.

#### getPropertySpecifiers

    ExampleMatcher.PropertySpecifiers getPropertySpecifiers()

Returns:
  the `ExampleMatcher.PropertySpecifiers` within the `ExampleMatcher`.

#### isAllMatching

    default boolean isAllMatching()

Returns whether all of the predicates of the `Example` are supposed to match. If false is returned, it's sufficient if any of the predicates derived from the `Example` match.

Returns:
  whether all of the predicates of the `Example` are supposed to match or any of them is sufficient.

#### isAnyMatching

    default boolean isAnyMatching()

Returns whether it's sufficient that any of the predicates of the `Example` match. If false is returned, all predicates derived from the example need to match to produce results.

Returns:
  whether it's sufficient that any of the predicates of the `Example` match or all need to match.

#### getMatchMode

    ExampleMatcher.MatchMode getMatchMode()

Get the match mode of the `ExampleMatcher`.

Returns:
  never null.
Since:
  2.0