ExampleMatcher (Spring Data Core 2.1.5.RELEASE API)

```
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
Modifier and Type	Interface and Description
`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
Modifier and Type	Method and Description
`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

Interface ExampleMatcher

Nested Class Summary

Method Summary

Method Detail

matching

matchingAny

matchingAll

withIgnorePaths

withStringMatcher

withIgnoreCase

withIgnoreCase

withMatcher

withMatcher

withTransformer

withIgnoreCase

withIncludeNullValues

withIgnoreNullValues

withNullHandler

getNullHandler

getDefaultStringMatcher

isIgnoreCaseEnabled

isIgnoredPath

getIgnoredPaths

getPropertySpecifiers

isAllMatching

isAnyMatching

getMatchMode