JHipster Domain Language (JDL) - Options

Summary

In JHipster, you can specify options for your entities such as pagination or DTO. You can do the same with the JDL, either with annotations on the entity, or with the following syntax:

entity A {
  name String required
}
entity B
entity C

dto A, B with mapstruct

paginate A with infinite-scroll
paginate B with pagination
paginate C with pager  // pager is only available in AngularJS

service A with serviceClass
service C with serviceImpl

The complete list of available options is here.

  1. How to
  2. Syntax
  3. Examples
    1. Basic unary example
    2. Basic binary example
    3. all, * example
    4. all, * example with exclusions (unary)
    5. all, * example with exclusions (binary)
    6. Option with custom values
    7. Mixed example
  4. About services
  5. Microservice-related options
  6. Custom annotations
  7. Available options

How to

There are two kinds of options:

  • unary (without option value)
  • binary (with value)

And two way of applying options to entities:

  • using the option name (dto, readOnly, etc.), see examples
  • using annotations

Mixing them is not recommended as it reduces readability.


Syntax

For the regular form:

<option name> <option entity list>

or

<option name> <option entity list> with <option value>

or

<option name> <option entity list> with <option value> except <option excluded entity list>

or 

<option name> <option entity list> except <option excluded entity list>
  • For unary options:
    • the option name and the list is needed
    • the excluded entities are optional with the except keyword (see below for more details)
  • For binary options:
    • the entity list precedes the with keyword and the option value
    • again, the excluded entities are in the end with the except keyword

For annotations:

@<option name>
entity <entity name>

or

@<option name>(<option value>)
  • Similar to Java, annotations may take values in parenthesises
    • depending on the option, values may or may not be optional

Examples

Each example will have two forms:

  • the regular one
  • the annotation-based one

Basic unary example

Regular:

entity A

readOnly A

Annotation-based:

@readOnly
entity A

Basic binary example

Regular:

entity A

dto A with mapstruct

Annotation-based:

@dto(mapstruct)
entity A

all, * example

all and * are aliases.

Regular:

entity A
entity B

dto all with mapstruct

Annotation-based:

@dto(mapstruct)
entity A

@dto(mapstruct)
entity B

all, * example with exclusions (unary)

Regular:

entity A
entity B

skipClient * except A

Annotation-based:

entity A

@skipClient
entity B

all, * example with exclusions (binary)

Regular:

entity A
entity B

dto all with mapstruct except A

Annotation-based:

entity A

@dto(mapstruct)
entity B

Option with custom values

entity A
entity B

microservice all with mySuperMS

Mixed example

Regular:

entity A
entity B
entity C

readOnly B, C
dto * with mapstruct except C
service * with serviceClass except C
search A with elasticsearch

Annotation-based:

@dto(mapstruct)
@search(elastisearch)
@service(serviceClass)
entity A

@readOnly
@dto(mapstruct)
@service(serviceClass)
entity B

@readOnly
entity C

About services

No services specified will create a resource class which will call the repository interface directly. This is the default and simplest option, see A.

service with serviceClass (see B) will make the resource call the service class which will call the repository interface. service with serviceImpl (see C) will make a service interface which will be used by the resource class.

The interface is implemented by a concrete class which will call the repository interface.

Using no service unless sure is the simplest option and good for CRUD. Use service with a Class if you will have a lot of business logic which will use multiple repositories making it ideal for a service class. JHipsters are not fan of unnecessary Interfaces but if you like them go for service with impl.

entity A
entity B
entity C

// no service for A
service B with serviceClass
service C with serviceImpl

As of JHipster v3, microservices can be created. You can specify some options to generate your entities in the JDL: the microservice’s name and the search engine.

Here is how you can specify your microservice’s name (the JHipster app’s name):

entity A
entity B
entity C
microservice * with mysuperjhipsterapp except C
microservice C with myotherjhipsterapp
search * with elasticsearch except C

The first option is used to tell JHipster that you want your microservice to deal with your entities, whereas the second specifies how and if you want your entities searched.


Custom annotations

Custom annotations are possible in the JDL, for instance:

@customAnnotation(customValue)
entity A

The main use case for this is for blueprints: sometimes, you need have custom options for entities, or even fields. For regular options (dto, pagination, etc.), these options will be generated in the JSON like in the CLI. However, for custom options, they will be generated under and options key in the dumped JSON.


Available options

Here are the entity options supported in the JDL:

JDL option name Option type Default value Possible values Comment
skipClient unary false This will make the client code generation to be skipped
skipServer unary false This will make the server code generation to be skipped
noFluentMethod unary false See this note for more information
filter unary false See filtering for more details; if an entity is filtered but doesn't have a service then 'serviceClass' will be used
readOnly unary false Adding this option will make an entity readOnly, see this release note for more details
dto binary no mapstruct, no Whether to create DTOs for your entities, if an entity has a DTO but no service, then 'serviceClass will be used'
service binary no serviceClass, serviceImpl, no
paginate binary no pagination, infinite-scroll, no Pagination is forbidden when the application uses Cassandra
search binary no elasticsearch, no Requires the application to have the searchEngine option enabled
microservice binary custom value Will be automatically added for every entity declared inside a microservice application
angularSuffix binary custom value
clientRootFolder binary custom value