Skip to content

Commit

Permalink
Merge pull request #121 from croz-ltd/feature_updateSearchDocumentation
Browse files Browse the repository at this point in the history 
Search page documentation update
  • Loading branch information
@jzrilic
jzrilic authored Sep 7, 2022
2 parents ad8d867 + b6801d4 commit 09a56e0
Show file tree
Hide file tree
Showing 4 changed files with 308 additions and 118 deletions.
6 changes: 3 additions & 3 deletions nrich-search-api/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,6 @@

## Overview

Contains classes that represent the API (configuration classes and data classes) for `nrich-search` module. The interfaces have default implementations provided in
`nrich-search` module but users can provide their own implementations. Unless some overriding is required only classes from this module should be used directly, other configuration should be
provided through property files.
This module contains classes that represent the API (interfaces and data classes) for [`nrich-search`](../nrich-search/README.md) module.
Default implementations are provided in [`nrich-search`](../nrich-search/README.md) module, but users can provide their own implementations.
If no overriding is required, only classes from this module should be used.
5 changes: 3 additions & 2 deletions nrich-search-repository-api/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,5 +4,6 @@

## Overview

Contains classes that represent the repository API (repository interfaces and factories) for `nrich-search` module. The interfaces have default implementations provided in `nrich-search` module but
users can provide their own implementations. Unless some overriding is required only classes from this module should be used directly, other configuration should be provided through property files.
This module contains classes that represent the repository API (repository interfaces and factories) for [`nrich-search`](../nrich-search/README.md) module.
Default implementations are provided in [`nrich-search`](../nrich-search/README.md) module, but users can provide their own implementations.
If no overriding is required, only classes from this module should be used.
97 changes: 57 additions & 40 deletions nrich-search-spring-boot-starter/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,15 @@

## Overview

Spring Boot starter for `nrich-search` module. The purpose of `nrich-search` is to provide easy querying of JPA entities through automatic query creation from passed parameters. It is built on top
of `spring-data-jpa` module and adds custom repository interfaces whose implementation provides searching functionality. Searching is possible with a simple string and a list of searched properties or
by using a separate class whose properties will be used to create a query. Additional configuration of generated query is possible with `SearchConfiguration` configuration class.
Starter module provides a `@Configuration` class (`NrichSearchAutoConfiguration`) with default configuration of `nrich-search` module (while allowing for overriding with conditional annotations),
and a `@ConfigurationProperties` class (`NrichSearchProperties`) with default configured values and does automatic registration through `spring.factories`.
This module is a Spring Boot starter for the [`nrich-search`][nrich-search-url] module.
The purpose of [`nrich-search`][nrich-search-url] is to provide easy querying of JPA entities through automatic query creation from passed parameters.
It's built on top of the Spring Data JPA library and adds custom repository interfaces whose implementation provides searching functionality.
Searching is possible with a simple string and a list of searched properties or by using a separate class whose properties will be used to create a query.
Additional configuration of the generated query is possible with [`SearchConfiguration`][search-configuration-url] configuration class.

Starter module provides a `@Configuration` class ([`NrichSearchAutoConfiguration`][nrich-search-auto-configuration-url]) with default configuration of [`nrich-search`][nrich-search-url] module,
a `@ConfigurationProperties` class([`NrichSearchProperties`][nrich-search-properties-url]) with default configuration values and does automatic bean registration with `spring.factories`.
The Configuration class permits overriding with the help of conditional annotations.

## Usage

Expand All @@ -19,88 +23,84 @@ The artifact is published on [Maven Central Repository](https://search.maven.org
With Maven:

```xml

<dependency>
<groupId>net.croz.nrich</groupId>
<artifactId>nrich-search-spring-boot-starter</artifactId>
<version>${nrich.version}</version>
</dependency>

```

With Gradle:

```groovy
implementation "net.croz.nrich:nrich-search-spring-boot-starter:${nrich.version}"
```

Note if using `nrich-bom` dependency versions should be omitted.
Note if using [`nrich-bom`][nrich-bom-url] dependency versions should be omitted.

### Configuration

Configuration is done through a property file, available properties and descriptions are given bellow (all properties are prefixed with nrich.search which is omitted for readability):
The configuration is done through a property file. Available properties and descriptions are given bellow (all properties are prefixed with **nrich.search** which is omitted for readability):

| property | description | default value |
|-------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|
| default-converter-enabled | Whether default string to type converter used for converting strings to property values when searching registry is enabled | true |
| string-search.date-format-list | List of date formats used to convert string to date value | dd.MM.yyyy., dd.MM.yyyy.'T'HH:mm, dd.MM.yyyy.'T'HH:mm'Z' |
| string-search.decimal-number-format-list | List of decimal formats used to convert string to decimal value | #0.00, #0,00 |
| string-search.boolean-true-regex-pattern | Regexp pattern that is used to match boolean true values | ^(?i)\s*(true&#124;yes&#124;da)\s*$ |
| string-search.boolean-false-regex-pattern | Regexp pattern that is used to match boolean false values | ^(?i)\s*(false&#124;no&#124;ne)\s*$ |
| default-converter-enabled | whether default string to type converter used for converting strings to property values when searching registry is enabled | true |
| string-search.date-format-list | list of date formats used to convert string to date value | dd.MM.yyyy., dd.MM.yyyy.'T'HH:mm, dd.MM.yyyy.'T'HH:mm'Z' |
| string-search.decimal-number-format-list | list of decimal formats used to convert string to decimal value | #0.00, #0,00 |
| string-search.boolean-true-regex-pattern | regular expression that is used to match boolean true values | ^(?i)\s*(true&#124;yes&#124;da)\s*$ |
| string-search.boolean-false-regex-pattern | regular expression that is used to match boolean false values | ^(?i)\s*(false&#124;no&#124;ne)\s*$ |

The properties under string-search are used when converting string received from client to property values that will be used to search entity. For example if a string is sent and the property
searched by is of type Date, nrich will try to parse string to Date and if parsing succeeds restriction will be added to query and if parsing fails the property will be skipped (no exception is thrown
or logged).
The properties under string-search are used when converting string received from client to property values that will be used to search entity.
For example, if a string is sent and the property searched by is of type Date, nrich will try to parse string to Date and if parsing succeeds
restriction will be added to query and if parsing fails the property will be skipped (no exception is thrown or logged).

The default configuration values in yaml format for easier modification are given bellow:
The default configuration values are given bellow in a yaml format for easier modification:

```yaml

nrich.search:
default-read-only-property-list:
default-converter-enabled: true
string-search:
date-format-list: dd.MM.yyyy., dd.MM.yyyy.'T'HH:mm, dd.MM.yyyy.'T'HH:mm'Z'
decimal-number-format-list: #0.00, #0,00
boolean-true-regex-pattern: ^(?i)\s*(true|yes|da)\s*$
boolean-false-regex-pattern: ^(?i)\s*(false|no|ne)\s*$

default-read-only-property-list:
default-converter-enabled: true
string-search:
date-format-list: dd.MM.yyyy., dd.MM.yyyy.'T'HH:mm, dd.MM.yyyy.'T'HH:mm'Z'
decimal-number-format-list: #0.00, #0,00
boolean-true-regex-pattern: ^(?i)\s*(true|yes|da)\s*$
boolean-false-regex-pattern: ^(?i)\s*(false|no|ne)\s*$
```
### Using the module
Module provides `SearchExecutor<T>` interface that enables searching by properties defined in a class and `StringSearchExecutor<T>` interface that enables searching by a string and provided list of
properties to search. WHen using Hibernate as JPA implementation `NaturalIdSearchExecutor` is also available that enables searching by `@NaturalId` annotated properties.
[`nrich-search`][nrich-search-url] module provides three interfaces:

To use the module users should first enable custom repository factory:
- [`SearchExecutor`][search-executor-url]
- [`StringSearchExecutor`][string-search-executor-url]
- [`NaturalIdSearchExecutor`][natural-id-search-executor-url]

```java
[`SearchExecutor`][search-executor-url] interface enables searching by properties defined in a class and [`StringSearchExecutor`][string-search-executor-url] interface enables searching by
a string and a provided list of properties. [`NaturalIdSearchExecutor`][natural-id-search-executor-url] interface enables searching by `@NaturalId` annotated properties, but is only available when
Hibernate is used as JPA implementation.

To use the module users should first enable custom repository factory bean:

```java
@EnableJpaRepositories(repositoryFactoryBeanClass = SearchExecutorJpaRepositoryFactoryBean.class)
@Configuration(proxyBeanMethods = false)
public class ApplicationConfiguration {
}

```

After that implement one or both interfaces in a spring-data repository:
After that, users need to implement one or both interfaces in a spring-data repository:

```java

@Repository
public interface UserSearchRepository extends JpaRepository<User, Long>, SearchExecutor<User>, StringSearchExecutor<User>, NaturalIdSearchExecutor<User> {
}

```

As a result, new repository method becomes available for searching:
As a result, new repository search method becomes available for searching:

```java

@RequiredArgsConstructor
@Service
public class UserService {
Expand All @@ -111,7 +111,24 @@ public class UserService {
public List<User> findByRequest(UserSearchRequest request) {
return testEntitySearchRepository.findAll(request, SearchConfiguration.emptyConfiguration());
}
}
```

[//]: # (Reference links for readability)

```
[nrich-search-url]: ../nrich-search/README.md

[search-configuration-url]: ../nrich-search-api/src/main/java/net/croz/nrich/search/api/model/SearchConfiguration.java

[nrich-search-auto-configuration-url]: src/main/java/net/croz/nrich/search/starter/configuration/NrichSearchAutoConfiguration.java

[nrich-search-properties-url]: ../nrich-search-spring-boot-starter/src/main/java/net/croz/nrich/search/starter/properties/NrichSearchProperties.java

[nrich-bom-url]: ../nrich-bom/README.md

[search-executor-url]: ../nrich-search-repository-api/src/main/java/net/croz/nrich/search/api/repository/SearchExecutor.java

[string-search-executor-url]: ../nrich-search-repository-api/src/main/java/net/croz/nrich/search/api/repository/StringSearchExecutor.java

[natural-id-search-executor-url]: ../nrich-search-repository-api/src/main/java/net/croz/nrich/search/api/repository/NaturalIdSearchExecutor.java
Loading

0 comments on commit 09a56e0

Please sign in to comment.