https://github.com/biagiot/jpa-search-helper
Helper library for building and running advanced and dynamic queries using JPA in Spring Boot.
https://github.com/biagiot/jpa-search-helper
advanced-search dynamic-queries dynamic-query hibernate hibernate-jpa java jpa persistence-api query query-builder query-engine rdbms repository search search-engine spring springboot sql sql-builder
Last synced: about 2 months ago
JSON representation
Helper library for building and running advanced and dynamic queries using JPA in Spring Boot.
- Host: GitHub
- URL: https://github.com/biagiot/jpa-search-helper
- Owner: biagioT
- License: mpl-2.0
- Created: 2024-01-27T16:08:28.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-16T17:23:07.000Z (about 2 years ago)
- Last Synced: 2024-10-18T12:17:29.408Z (about 2 years ago)
- Topics: advanced-search, dynamic-queries, dynamic-query, hibernate, hibernate-jpa, java, jpa, persistence-api, query, query-builder, query-engine, rdbms, repository, search, search-engine, spring, springboot, sql, sql-builder
- Language: Java
- Homepage:
- Size: 237 KB
- Stars: 36
- Watchers: 1
- Forks: 6
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# JPA Search Helper
Library for building and running advanced and dynamic queries using JPA in Spring Boot.
## Why use JPA Search Helper?
Building dynamic and type-safe queries with JPA can quickly become complex and repetitive.
`JPA Search Helper` simplifies this process by providing a fluent, declarative way to build advanced search filters and projections, with minimal boilerplate.
With this library, you can:
- Dynamically build queries using simple request parameters or structured JSON input.
- Combine filters with logical operators (`AND`, `OR`, `NOT`), without writing custom `Specification` or `CriteriaBuilder` code.
- Reuse your existing JPA entities or domain models through simple annotations.
- Support projections to return only specific fields instead of entire entities.
- Keep full control of the repository layer, without exposing new endpoints.
In short, it helps you build **powerful, flexible search APIs** in Spring Boot, **with zero query code**.
## Status
| Type | Status |
| ---- | ------ |
| Build (CI) | [](https://github.com/biagioT/jpa-search-helper/actions/workflows/ci.yml) |
| CodeQL | [](https://github.com/biagioT/jpa-search-helper/actions/workflows/codeql.yml) |
| Artifact | [](https://mvnrepository.com/artifact/app.tozzi/jpa-search-helper) |
| Javadocs | [](https://javadoc.io/doc/app.tozzi/jpa-search-helper) |
| OpenSSF Score | [](https://securityscorecards.dev/viewer/?uri=github.com/biagioT/jpa-search-helper) |
| OpenSSF Best Practices | [](https://www.bestpractices.dev/projects/11512) |
| Dependabot | [](https://github.com/biagioT/jpa-search-helper/security/dependabot) |
## TL;DR
### Key features
- **Queries**: the library supports two modes for building advanced and dynamic queries:
- *Mode 1*: Via `Map`, to support GET endpoints with query params.
- *Mode 2*: Via an [object](https://github.com/biagioT/jpa-search-helper/blob/main/src/main/java/app/tozzi/model/input/JPASearchInput.java), to support POST endpoints that expect query parameters in the body (from *2.0.0* version)
- **Projection**: for both modes, the library allows you to extract only a subselection of fields from the query (from *3.2.0* version)
### Spoiler
With **jpa-search-helper** your controller* can handle requests like this:
*Mode 1*:
```bash
curl -X GET \
'https://myexampledomain.com/persons?
firstName=Biagio
&lastName_startsWith=Toz
&birthDate_gte=19910101
&country_in=IT,FR,DE
&address_eq=Via Roma 1,Via Milano/,1,20 West/,34th Street
&company.name_in=Microsoft,Apple,Google
&company.employees_between=500,5000'
```
*Mode 2*:
```bash
curl -X POST -H "Content-type: application/json" -d '{
"filter" : {
"operator": "and", // the first filter must contain a root operator: AND, OR or NOT
"filters" : [
{
"operator": "eq",
"key": "firstName",
"value": "Biagio"
},
{
"operator": "or",
"filters": [
{
"operator": "startsWith",
"key": "lastName",
"value": "Toz",
"options": {
"ignoreCase": true
}
},
{
"operator": "endsWith",
"key": "lastName",
"value": "ZZI",
"options": {
"ignoreCase": true,
"trim" : true
}
}
]
},
{
"operator": "in",
"key": "company.name",
"values": ["Microsoft", "Apple", "Google"]
},
{
"operator": "or",
"filters": [
{
"operator": "gte",
"key": "birthDate",
"value": "19910101"
},
{
"operator": "lte",
"key": "birthDate",
"value": "20010101"
}
]
},
{
"operator": "between",
"key" : "company.employees",
"values": [500, 5000],
"options": {
"negate": true
}
}
]
},
"options": {
"pageSize": 10,
"pageOffset": 0,
"sortOptions" : [
{
"key": "birthDate",
"desc": false
}
]
}
}' 'https://myexampledomain.com/persons'
```
..how can you do it? Keep reading this README!
**\*** Please note: the library itself does not expose any controllers or HTTP endpoints, it only provides the repository layer responsible for building and executing the queries.
## Compatibility Matrix
#### Minimum requirements
- Java 17 or later
- Spring Boot 3.2.x or later
| JPA Search Helper | Spring Boot | JDK |
|-------------------|-------------|-----------|
| [v0.0.1 - v2.1.1] | 3.2.x | [17 - 25] |
| [v3.0.0 - v3.2.2] | 3.3.x | [17 - 25] |
| [v3.3.0 - v3.4.5] | 3.4.x | [17 - 25] |
| [v3.5.0 - v3.5.5] | 3.5.x | [17 - 25] |
| [v3.6.0 - v3.6.4] | 4.x.x | [17 - 25] |
| [v4.0.0 - latest] | 4.x.x | [17 - 25] |
## Project dependency
#### Maven
```
app.tozzi
jpa-search-helper
4.1.0
```
#### Gradle
```
implementation 'app.tozzi:jpa-search-helper:4.1.0'
```
## Queries - Usage
### 1. `@Searchable` annotation
Start by applying the `@Searchable` annotation to the fields in your Domain Model, or alternatively your JPA entity, **that you want to make available for search**.
If you have fields that you want to make searchable within other objects then annotate these with `@NestedSearchable`.
```java
@Data
public class Person {
@Searchable
private String firstName;
@Searchable
private String lastName;
@Searchable(entityFieldKey = "dateOfBirth")
private Date birthDate;
@Searchable
private String country;
@Searchable
private String fillerOne;
@Searchable
private String fillerTwo;
@NestedSearchable
private Company company;
@Searchable(targetType = JPASearchType.JSONB, entityFieldKey = "data", jsonPath = "address.street")
private String addressStreet;
@Searchable(targetType = JPASearchType.JSONB, entityFieldKey = "data", jsonPath = "address.city")
private String addressCity;
@Data
public static class Company {
@Searchable(entityFieldKey= "companyEntity.name")
private String name;
@Searchable(entityFieldKey= "companyEntity.employeesCount")
private int employees;
}
}
```
The annotation allows you to specify:
- Core properties:
- `entityFieldKey`:
the name of the field defined on the entity bean (not to be specified if using the annotation on the entity bean). If not specified the key will be the field name.
- `targetType`: the managed object type by entity. If not specified the librariy tries to obtain it based on field type (es. Integer field without target type definition will be `INTEGER`). If there is no type compatible with those managed, it will be managed as a string. Managed types:
- `STRING`, `INTEGER`, `DOUBLE`, `FLOAT`, `LONG`, `BIGDECIMAL`, `BOOLEAN`, `DATE`, `LOCALDATE`, `LOCALDATETIME`, `LOCALTIME`, `OFFSETDATETIME`, `OFFSETTIME`, `ZONEDDATETIME`, `ENUM`, `DATE_SQL`, `TIME_SQL`, `INSTANT`, `TIMESTAMP`, `UUID`, `JSONB`
- Validation properties:
- `datePattern`: only for `DATE`, `LOCALDATE`, `LOCALDATETIME`, `LOCALTIME`, `OFFSETDATETIME`, `OFFSETTIME`, `ZONEDDATETIME`, `TIMESTAMP`, `TIME_SQL`, `DATE_SQL`, `INSTANT` target types. Defines the date pattern to use.
- `maxSize, minSize`: maximum/minimum length of the value (for `STRING` types).
- `maxDigits, minDigits`: only for numeric types. Maximum/minimum number of digits.
- `regexPattern`: regex pattern.
- `decimalFormat`: only for decimal numeric types. Default `#.##`
- Other:
- `sortable`: if false, the field can be used by search but cannot be used for sorting. Default: true.
- `trim`: apply trim.
- `tags`: useful if the Domain Model field can correspond to multiple entity fields (the example is available further down).
- `allowedFilters`: exclusively allowed filters.
- `notAllowedFilters`: not allowed filters.
- `likeFilters`: allowed like filters (_contains_, _startsWith_, _endsWith_). Default: true.
- `ordinalEnum`: only for `ENUM` type; true if search via ordinal
- `jsonPath`: required for `JSONB`; represents the JSON path inside the jsonb column.
- `elementCollection`: set to true when the underlying entity attribute is annotated with `@ElementCollection` (e.g. `List`). `EQ` and `IN` are evaluated with `cb.isMember(...)`; other operators fall back to a LEFT JOIN on the collection table.
Continuing the example, here are our entity classes:
```java
@Entity
@Data
public class PersonEntity {
@Id
private Long id;
@Column(name = "FIRST_NAME")
private String firstName;
@Column(name = "LAST_NAME")
private String lastName;
@Column(name = "BIRTH_DATE")
private Date dateOfBirth;
@Column(name = "COUNTRY")
private String country;
@Column(name = "FIL_ONE")
private String fillerOne;
@Column(name = "FIL_TWO")
private String fillerTwo;
@Type(JsonType.class)
@Column(name = "DATA_ADDRESS", columnDefinition = "jsonb")
private Map data;
@OneToOne
private CompanyEntity companyEntity;
}
@Entity
@Data
public class CompanyEntity {
@Id
private Long id;
@Column(name = "NAME")
private String name;
@Column(name = "COUNT")
private Integer employeesCount;
}
```
### 2. `JPASearchRepository` interface
Your Spring JPA repository must extend `JPASearchRepository`.
```java
@Repository
public interface PersonRepository extends JpaRepository, JPASearchRepository {
}
```
### 3. Search implementation
In your manager, or in your service, or wherever you want to use the repository:
**Mode 1**: define a map __:
```java
// ...
@Autowired
private PersonRepository personRepository;
public List advancedSearch() {
// This is a simple example; in a real use case, these filters would typically be passed directly from the controller.
Map filters = new HashMap<>();
filters.put("firstName_eq", "Biagio");
filters.put("lastName_startsWith#i", "Toz"); // ignore case
filters.put("birthDate_gte", "19910101");
filters.put("country_in", "IT,FR,DE");
filters.put("company.name_eq#n", "Bad Company"); // negation
filters.put("company.employees_between", "500,5000");
filters.put("fillerOne_null#n", "true"); // not null
filters.put("fillerTwo_empty", "true"); // empty
// Without pagination
List fullSearch = personRepository.findAll(filters, Person.class);
filters.put("birthDate_sort", "ASC"); // sorting key and sorting order
filters.put("_limit", "10"); // page size
filters.put("_offset", "0"); // page offset
// With pagination
Page sortedAndPaginatedSearch = personRepository.findAllWithPaginationAndSorting(filters, Person.class);
// ...
}
// ...
```
**Mode 2**: instead of a map, you will need to use [`JPASearchInput`](https://github.com/biagioT/jpa-search-helper/blob/main/src/main/java/app/tozzi/model/input/JPASearchInput.java), shown here, for simplicity, in JSON format.
```json
{
"filter" : {
"operator": "and", // the first filter must contain a root operator: AND, OR or NOT
"filters" : [
{
"operator": "eq",
"key": "firstName",
"value": "Biagio"
},
{
"operator": "or",
"filters": [
{
"operator": "startsWith",
"key": "lastName",
"value": "Toz",
"options": {
"ignoreCase": true
}
},
{
"operator": "endsWith",
"key": "lastName",
"value": "ZZI",
"options": {
"ignoreCase": true,
"trim" : true
}
}
]
},
{
"operator": "in",
"key": "company.name",
"values": ["Microsoft", "Apple", "Google"]
},
{
"operator": "or",
"filters": [
{
"operator": "gte",
"key": "birthDate",
"value": "19910101"
},
{
"operator": "lte",
"key": "birthDate",
"value": "20010101"
}
]
},
{
"operator": "empty",
"key": "fillerOne",
"options": {
"negate": true
}
},
{
"operator": "between",
"key" : "company.employees",
"values": [500, 5000],
"options": {
"negate": true
}
}
]
},
"options": {
"pageSize": 10,
"pageOffset": 0,
"sortOptions" : [
{
"key": "birthDate",
"desc": false
}
]
}
}
```
Through *Mode 2* it is possible to manage complex filters with `AND`, `OR` and `NOT` (see later).
#### Exceptions:
- If a field does not exist, is not searchable or is not sortable, you will receive an `InvalidFieldException`.
- If the value of a field does not meet the requirements you will receive an `InvalidValueException`.
- Other cases: `JPASearchException`
## Queries - Docs
### Managed root operators
| Filter name | Library Key | Supported modes |
|-------------|-------------|-----------------|
| AND | and | 1, 2 |
| OR | or | 2 |
| NOT | not | 2 |
Through *Mode 1*, all filters compose exclusively an `AND` search.
To use the other operators, `OR` and `NOT`, you must use *Mode 2*
### Managed search filter operators
| Filter name | Library Key | SQL | Supported modes | Value required |
|---------------------------|-------------|------------------------------------|-----------------|----------------|
| Equals | eq | sql_col = val | 1,2 | yes |
| Contains | contains | sql_col LIKE '%val%' | 1,2 | yes |
| In | in | sql_col IN (val1, val2, ..., valN) | 1,2 | yes |
| Starts With | startsWith | sql_col LIKE 'val%' | 1,2 | yes |
| Ends With | endsWith | sql_col LIKE '%val' | 1,2 | yes |
| Greater Than | gt | sql_col > val | 1,2 | yes |
| Greater Than or Equal | gte | sql_col >= val | 1,2 | yes |
| Less Than | lt | sql_col < val | 1,2 | yes |
| Less Than or Equal | lte | sql_col <= val | 1,2 | yes |
| Between | between | sql_col BETWEEN val1 AND val2 | 1,2 | yes |
| Null | null | sql_col IS NULL | 1,2 | no |
| Empty | empty | sql_collection_col IS EMPTY | 1,2 | no |
#### Options
**Mode 1**
| Option description | Library Key |
|--------------------|-------------|
| Ignore case | #i |
| Negation | #n |
| Trim | #t |
The option keys must be appended to the filter; e.g. _?firstName_eq#i=Biagio_ or _?firstName_eq#i#n=Biagio_
**Mode 2**
| Option description | Library Key (Java attributes) |
|------------------|-------------------------------|
| Ignore case | ignoreCase |
| Negation | negate |
| Trim | trim |
For each filter it is possible to define `options`
```json
{
// ...
{
"operator": "eq",
"key": "firstName",
"value": "Biagio",
"options": {
"ignoreCase": true,
"trim": false,
"negate": true
}
}
// ...
}
```
Java object:
```java
@Data
public static class JPASearchFilterOptions {
private boolean ignoreCase;
private boolean trim;
private boolean negate;
}
```
### Pagination
| Filter name | Key |
|--|--|
| Limit (page size) | _limit |
| Offset (page number) | _offset |
| Sort | _sort (values: ASC, DESC) |
**Mode 1**: e.g. *?firstName_sort=DESC&_limit=10&_offset=0*
**Mode 2**: value root `options`:
```json
{
"filter" : {
// ...
},
"options" : {
"sortOptions" : [
{
"key": "firstName",
"desc": true
}
],
"pageSize": 10,
"pageOffset": 1
}
}
```
Java object:
```java
@Data
public static class JPASearchOptions {
private List sortOptions;
private Integer pageSize;
private Integer pageOffset;
private List selections;
}
@Data
public static class JPASortOptions {
@NotEmpty
@NotNull
private String key;
private Boolean desc = false;
}
```
### Other (only for Mode 1)
- Separator for array values: `,`: e.g. _?myField_in=test1,test2_ --> values to search for: ["**test1**", "**test2**"]
- To escape separator: prepend `/` to the comma. Example: `?myField_in=test1,test2/,test3` --> values to search for: ["**test1**", "**test2,test3**"]. So `/` is the escape character and `/,` is the escape sequence that represents a literal comma inside a value.
## Projection - Usage
### 1. `@Projectable` annotation
Start by applying the `@Projectable` annotation to the fields in your Domain Model, or alternatively your JPA entity, **that you want to make available for selection**.
If you have fields that you want to make selectable within other objects then annotate these with `@NestedProjectable`.
```java
@Data
public class Person {
@Searchable
private String firstName;
@Projectable
@Searchable
private String lastName;
@Projectable(entityFieldKey = "dateOfBirth")
@Searchable(entityFieldKey = "dateOfBirth")
private Date birthDate;
@Searchable
private String country;
@Searchable
private String fillerOne;
@Searchable
private String fillerTwo;
@NestedProjectable
@NestedSearchable
private Company company;
@Data
public static class Company {
@Searchable(entityFieldKey= "companyEntity.name")
private String name;
@Projectable(entityFieldKey= "companyEntity.employeesCount")
@Searchable(entityFieldKey= "companyEntity.employeesCount")
private int employees;
}
}
```
The annotation allows you to specify:
- Core properties:
- `entityFieldKey`:
the name of the field defined on the entity bean (not to be specified if using the annotation on the entity bean). If not specified the key will be the field name.
### 2. `JPASearchRepository` interface
Your Spring JPA repository must extend `JPAProjectionRepository`.
```java
@Repository
public interface PersonRepository extends JpaRepository, JPASearchRepository, JPAProjectionRepository {
}
```
> **ℹ️ Configuration Note (Spring Boot):**
> Starting from version `4.0.0`, the library ships a Spring Boot auto-configuration that registers `JPAProjectionRepositoryImpl` automatically. No additional `@ComponentScan` / `@EnableJpaRepositories` setup is required for Spring Boot consumers.
>
> If your application **does not** use Spring Boot auto-configuration, or you have customized your component scan, you may still need to add `app.tozzi` to your component scan to ensure the implementation bean is discovered:
```java
@Configuration
// Include your package AND the library package (only needed when NOT using Spring Boot auto-configuration)
@ComponentScan(basePackages = {"com.my-package", "app.tozzi"})
@EnableJpaRepositories(basePackages = {"com.my-package.repository"})
public class ApplicationConfiguration {
// ...
}
```
### 3. Projection implementation
In your manager, or in your service, or wherever you want to use the repository:
**Mode 1**: define (or add to the map used for the Mode 1 search) a map:
- key: *selections*
- value: the only fields that you want to extract separated by commas `,`
```java
// ...
@Autowired
private PersonRepository personRepository;
public List advancedSearch() {
// Pure example, in real use case it is expected that these filters can be passed directly by the controller
Map filters = new HashMap<>();
filters.put("firstName_eq", "Biagio");
filters.put("lastName_startsWith#i", "Toz"); // ignore case
filters.put("birthDate_gte", "19910101");
filters.put("country_in", "IT,FR,DE");
filters.put("company.name_eq#n", "Bad Company"); // negation
filters.put("company.employees_between", "500,5000");
filters.put("fillerOne_null#n", "true"); // not null
filters.put("fillerTwo_empty", "true"); // empty
// Selections
filters.put("selections", "lastName,birthDate,company.employees");
// Without sorting
List> result = personRepository.projection(filters, Person.class, PersonEntity.class);
filters.put("birthDate_sort", "ASC"); // sorting key and sorting order
// With sorting
List> sortedAndPaginatedSearch = personRepository.projectionWithSorting(filters, Person.class, PersonEntity.class);
// ... convert the list of maps into your model
}
// ...
```
**Mode 2**: instead of a map, you will need to use [`JPASearchInput`](https://github.com/biagioT/jpa-search-helper/blob/main/src/main/java/app/tozzi/model/input/JPASearchInput.java), shown here, for simplicity, in JSON format.
```json
{
"filter" : {
"operator": "and", // the first filter must contain a root operator: AND, OR or NOT
"filters" : [
{
"operator": "eq",
"key": "firstName",
"value": "Biagio"
},
{
"operator": "or",
"filters": [
{
"operator": "startsWith",
"key": "lastName",
"value": "Toz",
"options": {
"ignoreCase": true
}
},
{
"operator": "endsWith",
"key": "lastName",
"value": "ZZI",
"options": {
"ignoreCase": true,
"trim" : true
}
}
]
},
{
"operator": "in",
"key": "company.name",
"values": ["Microsoft", "Apple", "Google"]
},
{
"operator": "or",
"filters": [
{
"operator": "gte",
"key": "birthDate",
"value": "19910101"
},
{
"operator": "lte",
"key": "birthDate",
"value": "20010101"
}
]
},
{
"operator": "empty",
"key": "fillerOne",
"options": {
"negate": true
}
},
{
"operator": "between",
"key" : "company.employees",
"values": [500, 5000],
"options": {
"negate": true
}
}
]
},
"options": {
"pageSize": 10,
"pageOffset": 0,
"sortOptions" : [
{
"key": "birthDate",
"desc": false
}
],
"selections" : [
"lastName",
"birthDate",
"company.employees"
]
}
}
```
For both modes, the projection will return a List> result where **the map structure and keys will reflect the entity structure** (to be clear *toJson(entityList) == toJson(mapList)*)
Note 1:
> By default, projection forces all Join relationships to use LEFT JOIN. If you don't want this behavior, choose to use the repository methods (methods with 'Classic' suffix) that allow you to possibly modify only the relations you want to modify
Note 2:
> Projection, regardless of whether you want it or not, will always extract the fields that represent the primary keys of an entity (or related entities)
Note 3:
> Pagination is not supported
#### Exceptions:
- If a field does not exist, is not searchable, is not sortable or is not projectable, you will receive an `InvalidFieldException`.
- Other cases: `JPASearchException`
---
## Advanced Settings
> Starting from version `4.0.0`, the optional parameters (`fetches`, `entityFieldMap`, override join types, ...) are passed via the parameter objects `JPASearchOptions` (search) and `JPAProjectionOptions` (projection), instead of the many overloaded method signatures used in releases up to `3.6.x`. Build them with the fluent `builder()` or use the static `empty()` helper when no extra options are needed.
### Join Fetch
It is possible to force joins with fetch to allow Hibernate (or your JPA framework) to execute a single query for the relationships defined on the entity. **This is only possible without pagination**:
```java
// ...
var options = JPASearchOptions.builder()
.fetches(Map.of("companyEntity", JoinType.LEFT))
.build();
personRepository.findAll(filters, Person.class, options);
// ...
```
### Multiple entities for the same Domain Model
If you have a Domain Model that is the result of the conversion of multiple entities, it is possible to explicitly specify a map (string, string) whose key represents the name of the Domain Model field and the value is the name of the field of the entity to be searched for:
```java
// ...
var options = JPASearchOptions.builder()
.fetches(Map.of("companyEntity", JoinType.LEFT))
.entityFieldMap(Map.of("company", "companyEntity.name"))
.build();
// Without pagination
personRepository.findAll(filters, Person.class, options);
// With pagination
personRepository.findAllWithPaginationAndSorting(filters, Person.class, options);
// ...
```
### Multiple object for the same entity
Another special case could be where an object can be repeated within the Domain Model to represent multiple pieces of the entity. The solution for the search:
```java
@Entity
public class CoupleEntity {
@Id
private Long id;
@Column(name = "p1_fn")
private String p1FirstName;
@Column(name = "p1_ln")
private String p1LastName;
@Column(name = "p2_fn")
private String p2FirstName;
@Column(name = "p2_ln")
private String p2LastName;
}
@Data
public class Couple {
@NestedSearchable
private Person p1;
@NestedSearchable
private Person p2;
@Data
public static class Person {
@Searchable(tags = {
@Tag(fieldKey = "p1.firstName", entityFieldKey = "p1FirstName"),
@Tag(fieldKey = "p2.firstName", entityFieldKey = "p2FirstName"),
})
private String firstName;
@Searchable(tags = {
@Tag(fieldKey = "p1.lastName", entityFieldKey = "p1LastName"),
@Tag(fieldKey = "p2.lastName", entityFieldKey = "p2LastName"),
})
private String lastName;
}
}
```
```bash
curl - request GET
- url 'https://www.myexampledomain.com/couples?
p1.firstName_iEq=Romeo
&p2.firstName_iEq=Giulietta'
```
---
## Spring Boot Project example with HTTP Endpoint
Please note: this library does not expose any endpoints and therefore no controllers.
An example project, exhaustive and complete, is available [here](https://github.com/biagioT/jpa-search-helper-demo).
#### Mode 1
Controller:
```java
@RestController
@RequestMapping("/persons")
public class PersonController {
@Autowired
private PersonManager personManager;
@GetMapping(produces = MediaType.APPLICATION_JSON_VALUE)
public List findPersons(@RequestParam Map requestParams) {
return personManager.find(requestParams);
}
@GetMapping(path="/projection", produces = MediaType.APPLICATION_JSON_VALUE)
public List projection(@RequestParam Map requestParams) {
return personManager.projection(requestParams);
}
}
```
Service/Manager bean:
```java
@Service
public class PersonManager {
@Autowired
private PersonRepository personRepository;
public List find(Map filters) {
return personRepository.findAllWithPaginationAndSorting(filters, Person.class).stream().map(this::toModel).toList();
}
public List projection(Map filters) {
return personRepository.projection(filters, Person.class, PersonEntity.class).stream().map(this::toModel).toList();
}
private static Person toModel(PersonEntity personEntity) {
// ...
}
private static Person toModel(Map entityMap) {
// ...
}
}
```
Curl:
```bash
curl - X GET
'http://localhost:8080/persons?
firstName=Biagio
&lastName_startsWith=Toz
&birthDate_gte=19910101
&country_in=IT,FR,DE
&company.name_in=Microsoft,Apple
&company.employees_between=500,5000'
```
or
```bash
curl - X GET
'http://localhost:8080/persons/projection?
firstName=Biagio
&lastName_startsWith=Toz
&birthDate_gte=19910101
&country_in=IT,FR,DE
&company.name_in=Microsoft,Apple
&company.employees_between=500,5000
&selections=firstName,birthDate'
```
#### Mode 2
Controller:
```java
@RestController
@RequestMapping("/persons")
@Validated
public class PersonController {
@Autowired
private PersonManager personManager;
@PostMapping(produces = MediaType.APPLICATION_JSON_VALUE, consumes = MediaType.APPLICATION_JSON_VALUE)
public List findPersons(@Valid @RequestBody JPASearchInput input) {
return personManager.find(input);
}
@PostMapping(path="/projection", produces = MediaType.APPLICATION_JSON_VALUE, consumes = MediaType.APPLICATION_JSON_VALUE)
public List projection(@Valid @RequestBody JPASearchInput input) {
return personManager.projection(input);
}
}
```
Service/Manager bean:
```java
@Service
public class PersonManager {
@Autowired
private PersonRepository personRepository;
public List find(JPASearchInput input) {
return personRepository.findAllWithPaginationAndSorting(input, Person.class).stream().map(this::toModel).toList();
}
public List projection(JPASearchInput input) {
return personRepository.projection(input, Person.class, PersonEntity.class).stream().map(this::toModel).toList();
}
private static Person toModel(PersonEntity entity) {
// ...
}
private static Person toModel(Map entityMap) {
// ...
}
}
```
Curl:
```bash
curl -X POST -H "Content-type: application/json" -d '{
"filter" : {
"operator": "and", // the first filter must contain a root operator: AND, OR or NOT
"filters" : [
{
"operator": "eq",
"key": "firstName",
"value": "Biagio"
},
{
"operator": "or",
"filters": [
{
"operator": "startsWith",
"key": "lastName",
"value": "Toz",
"options": {
"ignoreCase": true
}
},
{
"operator": "endsWith",
"key": "lastName",
"value": "ZZI",
"options": {
"ignoreCase": true,
"trim" : true
}
}
]
},
{
"operator": "in",
"key": "company.name",
"values": ["Microsoft", "Apple", "Google"]
},
{
"operator": "or",
"filters": [
{
"operator": "gte",
"key": "birthDate",
"value": "19910101"
},
{
"operator": "lte",
"key": "birthDate",
"value": "20010101"
}
]
},
{
"operator": "between",
"key" : "company.employees",
"values": [500, 5000],
"options": {
"negate": true
}
}
]
},
"options": {
"pageSize": 10,
"pageOffset": 0,
"sortOptions" : [
{
"key": "birthDate",
"desc": false
}
]
}
}' 'http://localhost:8080/persons'
```
or
```bash
curl -X POST -H "Content-type: application/json" -d '{
"filter" : {
"operator": "and", // the first filter must contain a root operator: AND, OR or NOT
"filters" : [
{
"operator": "eq",
"key": "firstName",
"value": "Biagio"
},
{
"operator": "or",
"filters": [
{
"operator": "startsWith",
"key": "lastName",
"value": "Toz",
"options": {
"ignoreCase": true
}
},
{
"operator": "endsWith",
"key": "lastName",
"value": "ZZI",
"options": {
"ignoreCase": true,
"trim" : true
}
}
]
},
{
"operator": "in",
"key": "company.name",
"values": ["Microsoft", "Apple", "Google"]
},
{
"operator": "or",
"filters": [
{
"operator": "gte",
"key": "birthDate",
"value": "19910101"
},
{
"operator": "lte",
"key": "birthDate",
"value": "20010101"
}
]
},
{
"operator": "between",
"key" : "company.employees",
"values": [500, 5000],
"options": {
"negate": true
}
}
]
},
"options": {
"sortOptions" : [
{
"key": "birthDate",
"desc": false
}
],
"selections" : [
"birthDate",
"firstName",
"lastName"
]
}
}' 'http://localhost:8080/persons/projection'
```
---
## Links
- Presentation article (version 0.0.1) on [Medium](https://medium.com/@biagio.tozzi/advanced-and-dynamic-searching-with-spring-data-jpa-e322e0f40b4b)