Filtering your entities
After the basic CRUD functionalities are implemented for an entity, there is a very common request to create various filters for the attributes of the entity, so the server could be used more effectively. These filters should be sent as the request parameters, so any client - and any browser - could use it easily. Additionally, these filters should follow a sane, and concise pattern, and they must be allowed combining them freely.
How to activate
When generating an entity with
jhipster entity command, select services or service implementation to enable filtering on this entity.
If you want to enable filtering for existing entities, you can modify the entity configuration in your projects
.jhipster directory, by setting
true and then re-generate with
jhipster entity <entity name>.
When using JDL, add a line
filter <entity name> to your JDL file and re-import the definitions with
jhipster import-jdl command.
For each entity, you can enable filtering in the entity generator, and after, you can call your
/api/my-entity GET endpoint with the following parameters :
- For each xyz field
- To list all the entities, where xyz equals to ‘someValue’
- To list all the entities, where xyz equals to ‘someValue’ or ‘otherValue’
- To list all the entities, where xyz is not null, specified.
- To list all the entities, where xyz is null, unspecified.
- If xyz’s type is string:
- To list all the entities, where xyz contains ‘something’.
- If xyz’s is either any of the number types, or the date types.
- To list all the entities, where xyz is greater than ‘someValue’.
- To list all the entities, where xyz is less than ‘someValue’.
- To list all the entities, where xyz is greater than or equal to ‘someValue’.
- To list all the entities, where xyz is less than or equal to ‘someValue’.
Of course, they can be combined freely.
A good way to experience the expressiveness of this filter API is to use it from swagger-ui in the API docs page of your JHipster application.
When this feature is enabled, a new service named as
EntityQueryService and an
EntityCriteria is generated. Spring will convert the request parameters into the fields of the
EntityQueryService, we convert the criteria object into a static, and type safe, JPA query object. For this, it is required that the static metamodel generation is enabled in the build. See the JPA Static Metamodel Generator documentation for details.
To prove that the generated criteria is working, and Spring is well configured, the
EntityResourceIntTest is extended with lots of test cases, one for each individual filter.
Currently only SQL databases (with JPA) is supported, with the separate service or separate service implementation/interface combination.