Tutoriel sur l'utilisation de la bibliothèque Lombok

François-Xavier Robin

Dans ce billet, je vais présenter la bibliothèque Lombok dont je ne peux plus me passer pour mes développements Java. Cela fait maintenant plus de quatre ans que je l'utilise et tout n'est pas rose. Ce sera donc l'occasion de partager aussi certaines recommandations.

J'en donne une : n'utilisez pas @Data et je vais vous expliquer pourquoi. Un peu de patience.

Pour réagir à cet article, un espace de dialogue vous est proposé sur le forum Commentez .

- Titre : Tutoriel sur l'utilisation de la bibliothèque Lombok

- Auteur : François-Xavier Robin

- Parution : 2 janvier 2019

- Mise à jour : 2 janvier 2019

- Licence : Les sources présentées sur cette page sont libres de droits et vous pouvez les utiliser à votre convenance. Par contre, la page de présentation constitue une œuvre intellectuelle protégée par les droits d'auteur. Copyright ® 2019 François-Xavier Robin. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- I. Lombok, à quoi cela sert-il ?

- II. Démonstration par l'exemple

- II-A. Implémentation sans Lombok

- II-B. Implémentation avec Lombok

- III. Le Pattern « Factory Method » avec Lombok

- IV. Le Pattern « Builder » avec Lombok

- V. Le Pattern « Factory » avec Lombok

- VI. Préconisations (enfin…)

- VII. En guise de conclusion

- VIII. Remerciements

I - Lombok, à quoi cela sert-il ?

À part être visiblement une très belle île d'Indonésie, encore, il s'agit d'une bibliothèque qui va générer pour vous, en respectant de nombreuses bonnes pratiques, ce qu'on appelle du « boiler plate ».

En Java, dans la catégorie « Boiler plate », voici les nominés :

- getters / setters ;

- equals / hashCode ;

- toString ;

- constructeurs ;

- modificateurs d'accès (private, protected, etc.).

And the winner is : égalité entre getter/setters et equals/hashCode. toString n'est vraiment pas loin derrière.

II - Démonstration par l'exemple

Prenez par exemple les classes métiers suivantes :

II-A - Implémentation sans Lombok

Pour montrer ce qu'il faudrait faire en Java « sans Lombok », je vais simplement coder la classe Vehicule afin qu'elle respecte les conventions Java Beans.

Pour l'exemple, l'unicité sera portée par les champs « numeroMoteur, numeroChassis ». Dans la réalité, l'unicité d'un véhicule est bien plus complexe et dans tous les cas ne doit pas reposer sur l'immatriculation.

1. public class Vehicule implements Serializable

2. {

3. // champs métier

4. private String numeroMoteur;

5. private String numeroChassis;

6. private String numeroImmatriculation;

7. private LocalDate dateMiseEnCirculation;

9. // champs de relation

10. private List<Intervention> interventions;

12. // constructeurs

13. public Vehicule()

14. {

15. interventions = new ArrayList<>();

16. }

18. public Vehicule(String numeroMoteur,

19. String numeroChassis,

20. String numeroImmatriculation,

21. LocalDate dateMiseEnCirculation)

22. {

23. this();

24. this.numeroMoteur = numeroMoteur;

25. this.numeroChassis = numeroChassis;

26. this.numeroImmatriculation = numeroImmatriculation;

27. this.dateMiseEnCirculation = dateMiseEnCirculation;

28. }

30. // getters/setters : génération par Eclipse

32. public String getNumeroMoteur()

33. {

34. return numeroMoteur;

35. }

37. public void setNumeroMoteur(String numeroMoteur)

38. {

39. this.numeroMoteur = numeroMoteur;

40. }

42. public String getNumeroChassis()

43. {

44. return numeroChassis;

45. }

47. public void setNumeroChassis(String numeroChassis)

48. {

49. this.numeroChassis = numeroChassis;

50. }

52. public String getNumeroImmatriculation()

53. {

54. return numeroImmatriculation;

55. }

57. public void setNumeroImmatriculation(String numeroImmatriculation)

58. {

59. this.numeroImmatriculation = numeroImmatriculation;

60. }

62. public LocalDate getDateMiseEnCirculation() {

63. return dateMiseEnCirculation;

64. }

66. public void setDateMiseEnCirculation(LocalDate dateMiseEnCirculation) {

67. this.dateMiseEnCirculation = dateMiseEnCirculation;

68. }

70. public List<Intervention> getInterventions()

71. {

72. return interventions;

73. }

75. public void setInterventions(List<Intervention> interventions)

76. {

77. this.interventions = interventions;

78. }

80. // equals/hashCode : génération par Eclipse

81. @Override

82. public int hashCode() {

83. final int prime = 31;

84. int result = 1;

85. result = prime * result + ((numeroChassis == null) ? 0 : numeroChassis.hashCode());

86. result = prime * result + ((numeroMoteur == null) ? 0 : numeroMoteur.hashCode());

87. return result;

88. }

90. @Override

91. public boolean equals(Object obj) {

92. if (this == obj)

93. return true;

94. if (obj == null)

95. return false;

96. if (getClass() != obj.getClass())

97. return false;

98. Vehicule other = (Vehicule) obj;

99. if (numeroChassis == null) {

100. if (other.numeroChassis != null)

101. return false;

102. } else if (!numeroChassis.equals(other.numeroChassis))

103. return false;

104. if (numeroMoteur == null) {

105. if (other.numeroMoteur != null)

106. return false;

107. } else if (!numeroMoteur.equals(other.numeroMoteur))

108. return false;

109. return true;

110. }

113. // toString : génération via Eclipse avec "StringBuilder chaining".

114. @Override

115. public String toString() {

116. StringBuilder builder = new StringBuilder();

117. builder.append("Vehicule [numeroMoteur=")

118. .append(numeroMoteur)

119. .append(", numeroChassis=")

120. .append(numeroChassis)

121. .append(", numeroImmatriculation=")

122. .append(numeroImmatriculation)

123. .append(", dateMiseEnCirculation=")

124. .append(dateMiseEnCirculation)

125. .append(", interventions=")

126. .append(interventions)

127. .append("]");

128. return builder.toString();

129. }

130. }

Constat : déjà plus de 100 lignes de code pour une classe pourtant « mini-rikiki » à la base.

Le code généré par Eclipse est convenable. J'ai choisi dans cet exemple l'option « StringBuilder chaining » pour toString mais souvent je préfère la méthode String.format que je trouve plus maintenable au détriment peut-être d'un peu de performance.

Mais cela reste du code source généré : tout code source, même généré doit être maintenable et maintenu !

II-B - Implémentation avec Lombok

Pour utiliser Lombok, il faut déclarer les éléments suivants dans le fichier pom.xml de votre projet MAVEN.

1. <properties>

2. <maven.compiler.source>1.8</maven.compiler.source>

3. <maven.compiler.target>1.8</maven.compiler.target>

4. <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

5. </properties>

7. <dependencies>

8. <dependency>

9. <groupId>org.projectlombok</groupId>

10. <artifactId>lombok</artifactId>

11. <version>1.16.20</version>

12. <scope>provided</scope>

13. </dependency>

14. </dependencies>

Là où Lombok va se différencier d'un générateur de code source, c'est que dans son cas il va générer du ByteCode. Donc rien à maintenir, rien de visible. Cette stratégie est bien différente des assistants de génération de code d'Eclipse ou Netbeans.

D'ailleurs, il faut déclarer l'agent Lombok dans le fichier eclipse.ini, ou alors laisser faire l'installeur intégré au fichier lombok.jar. L'installeur place d'ailleurs lombok.jar dans le répertoire racine d'Eclipse.

1. -javaagent:/opt/eclipse/lombok.jar

Cela fonctionne de la même manière avec NetBeans.

On va pouvoir se concentrer uniquement sur ce qui est important dans notre classe : ses données et leur représentation. Le reste sera généré par Lombok au moyen de ses annotations.

1. @FieldDefaults(level=AccessLevel.PRIVATE)

2. @NoArgsConstructor

3. @AllArgsConstructor

4. @Getter

5. @Setter

6. @EqualsAndHashCode(of= {"numeroMoteur","numeroChassis"})

7. @ToString(of= {"numeroMoteur","numeroChassis","numeroImmatriculation","dateMiseEnCirculation"})

8. public class Vehicule implements Serializable

9. {

10. // champs métier

11. String numeroMoteur;

12. String numeroChassis;

13. String numeroImmatriculation;

14. LocalDate dateMiseEnCirculation;

16. // champs de relation

17. List<Intervention> interventions = new ArrayList<>();

18. }

Dans cet exemple, pour montrer la puissance de Lombok, j'ai volontairement omis les modificateurs private devant chacun des champs. Les champs sont pourtant bien private grâce à l'annotation @FieldDefaults(level=AccessLevel.PRIVATE). Cela étant, après quatre ans d'usage, je préfère quand même faire figurer les modificateurs d'accès au niveau des champs.

Vous noterez que j'ai reporté l'instanciation de la liste au niveau de la déclaration du champ interventions. Cette instanciation figurait, dans l'exemple précédent, au niveau du constructeur.

Et voilà comment passer de plus de 100 lignes de code à 16 lignes ! C'est quand même bien plus clair et quel temps gagné ! Mais on ne va pas en rester là. Lombok peut nous apporter plus encore.

Avant cela, détaillons un peu les annotations utilisées :

- @FieldDefaults(level=AccessLevel.PRIVATE) : passe tous les champs en private ;

- @NoArgsConstructor : génère le constructeur sans argument et public ;

- @AllArgsConstructor : génère le constructeur avec tous les arguments et public (pour l'exemple) ;

- @Getter : génère tous les getters sur les champs ;

- @Setter : génère tous les setters sur les champs ;

- @EqualsAndHashCode(of=...) : génère equals et hashCode (et d'autres méthodes) sur les champs donnés ;

- @ToString(of=...) : génère toString sur les champs donnés.

C'est quand même bien pratique, mais on peut aller encore plus loin. D'ailleurs, il y a un petit problème avec le @AllArgsConstructor qui permet ainsi de passer une liste qui ira supplanter la liste initiale… Bof bof. On va régler cela bientôt.

III - Le Pattern « Factory Method » avec Lombok

Reprenons l'exemple précédent et avec quelques ajustements nous aurons une classe uniquement instanciable au moyen d'une « factory method » statique.

1. @FieldDefaults(level=AccessLevel.PRIVATE)

2. @RequiredArgsConstructor(staticName="of")

3. @EqualsAndHashCode(of= {"numeroMoteur","numeroChassis"})

4. @ToString(of= {"numeroMoteur","numeroChassis","numeroImmatriculation","dateMiseEnCirculation"})

5. public class Vehicule implements Serializable

6. {

7. @Getter

8. final String numeroMoteur;

10. @Getter

11. final String numeroChassis;

13. @Getter

14. final LocalDate dateMiseEnCirculation;

16. @Getter     @Setter

17. String numeroImmatriculation;

19. // champs de relation

20. @Getter

21. List<Intervention> interventions = new ArrayList<>();

22. }

L'exemple devient un peu plus « sympa ». Je vais détailler ses particularités.

- Le constructeur public par défaut sans argument a disparu. En fait il est bien là, mais il a été passé private par l'annotation @RequiredArgsConstructor. Cela empêche donc l'instanciation sans argument : ce n'est plus un Java Bean, mais ce n'est pas forcément grave. Attention toutefois aux specs comme CDI, JSF, et JPA, qui réclament pourtant ce constructeur.

- une méthode statique « factory method » est générée et est nommée of(...) au moyen de l'annotation @RequiredArgsConstructor(staticName="of"). Ici la convention « of » est utilisée, comme pour les nouvelles API de Java 8, mais j'aurais pu utiliser les vieilles conventions comme newInstance(...). La méthode prendra en argument tous les champs marqués final ou les champs annotés avec @NonNull de Lombok. Attention à ne pas confondre avec @NotNull de Bean Validation ou de Guava.

- equals, hashCode et toString ne changent pas.

- Cette fois-ci, un contrôle plus fin sur les getters/setters est mis en place : seule l'immatriculation peut changer.

Usage de cette classe :

1. Vehicule v = Vehicule.of("AABBCC123", "X06123", LocalDate.of(1989, 01, 18));

2. v.setNumeroImmatriculation("AA-123-BB");

3. System.out.println(v);

Et son résultat dans la console grâce à la méthode toString générée par Lombok :

1. Vehicule(numeroMoteur=AABBCC123, numeroChassis=X06123, dateMiseEnCirculation=1989-01-18, numeroImmatriculation=AA-123-BB)

Ça commence déjà à faire des choses plutôt agréables, mais ce n'est pas fini ! Loin de là…

IV - Le Pattern « Builder » avec Lombok

Dans la catégorie des patterns un peu verbeux à mettre en place de manière traditionnelle, impliquant de la duplication de code (surtout de définitions d'attributs) ce qui est un comble pour des Design Patterns, voici le Builder mis en œuvre avec Lombok.

Avant d'en percevoir sa facilité de mise en œuvre, voici la classe Intervention implémentée avec Lombok et une « factory method » pour son instanciation :

1. @FieldDefaults(level=AccessLevel.PRIVATE)

2. @AllArgsConstructor(staticName="of")

3. @EqualsAndHashCode(of="dateIntervention")

4. @ToString

5. @Getter

6. public class Intervention implements Serializable, Comparable<Intervention>

7. {

8. final LocalDate dateIntervention;

10. final Long kilometrage;

12. @Setter

13. String libelle;

15. @Setter

16. BigDecimal prix;

18. @Override

19. public int compareTo(Intervention o)

20. {

21. return this.dateIntervention.compareTo(o.getDateIntervention());

22. }

23. }

et voici la classe Vehicule ainsi que son Builder sous forme de classe interne que je commenterai par la suite :

1. @FieldDefaults(level=AccessLevel.PRIVATE)

2. @EqualsAndHashCode(of= {"numeroMoteur","numeroChassis"})

3. @ToString(of= {"numeroMoteur","numeroChassis","numeroImmatriculation","dateMiseEnCirculation"})

4. @Builder

5. public class Vehicule implements Serializable

6. {

7. @Getter

8. @NonNull

9. String numeroMoteur;

11. @Getter

12. @NonNull

13. String numeroChassis;

15. @Getter

16. @NonNull

17. LocalDate dateMiseEnCirculation;

19. @Getter    @Setter

20. String numeroImmatriculation;

22. // champs de relation

23. @Getter

24. @Singular

25. List<Intervention> interventions = new ArrayList<>();

26. }

Notez donc l'usage des annotations Lombok suivantes :

- @Builder : génère une classe interne de type « Builder » capable de construire au moyen de « method chaining » une instance de la classe. L'opération terminale sera build() ;

- @AllArgsConstructor(access=AccessLevel.PROTECTED) : le constructeur avec tous les arguments est nécessaire au Builder, mais pour le rendre inaccessible depuis un autre package, mais toujours depuis le Builder, je le place ici en protected ;

- @NonNull : indique au Builder tous les champs obligatoires ;

- @Singular : indique au Builder que l'on pourra ajouter des occurrences à la liste toujours grâce à du method chaining.

Voici un exemple d'usage de ce builder :

1. Vehicule.VehiculeBuilder builder = Vehicule.builder();

3. Vehicule v = builder.numeroChassis("AABBCC123")

4. .numeroMoteur("X06123")

5. .dateMiseEnCirculation(LocalDate.of(1989, 01, 18))

6. .numeroImmatriculation("AA-123-BB")

7. .intervention(Intervention.of(LocalDate.of(2018, 03, 05), 1850000L, "Vidange", new BigDecimal("175.0")))

8. .intervention(Intervention.of(LocalDate.of(2018, 02, 03), 1840000L, "Freins", new BigDecimal("210.0")))

9. .intervention(Intervention.of(LocalDate.of(2018, 01, 15), 1830000L, "Embrayage", new BigDecimal("350.0")))

10. .intervention(Intervention.of(LocalDate.of(2017, 12, 10), 1820000L, "Pneus", new BigDecimal("450.0")))

11. .build();

13. System.out.println(v);

14. v.getInterventions().forEach(System.out::println);

et voici le résultat dans la console :

1. Vehicule(numeroMoteur=X06123, numeroChassis=AABBCC123, dateMiseEnCirculation=1989-01-18, numeroImmatriculation=AA-123-BB)

2. Intervention(dateIntervention=2018-03-05, kilometrage=1850000, libelle=Vidange, prix=175.0)

3. Intervention(dateIntervention=2018-02-03, kilometrage=1840000, libelle=Freins, prix=210.0)

4. Intervention(dateIntervention=2018-01-15, kilometrage=1830000, libelle=Embrayage, prix=350.0)

5. Intervention(dateIntervention=2017-12-10, kilometrage=1820000, libelle=Pneus, prix=450.0)

V - Le Pattern « Factory » avec Lombok

Il est parfois, voire souvent, nécessaire d'avoir un peu plus de contrôle pour la création des instances, notamment dans le Builder, ce qui va nous permettre de mettre en place une solution fondée sur Lombok pour le Design Pattern « Factory ».

Avec Lombok, cela reste assez simple, en utilisant toujours la même annotation @Builder mais cette fois-ci sur des méthodes :

1. @UtilityClass

2. public class VehiculeFactory

3. {

4. @Builder(builderClassName="SmallBuilder", builderMethodName="smallBuilder")

5. public static Vehicule newVehicule(String numeroChassis, String numeroMoteur)

6. {

7. return Vehicule.builder().numeroChassis(numeroChassis)

8. .numeroMoteur(numeroMoteur)

9. .dateMiseEnCirculation(LocalDate.now())

10. .numeroImmatriculation("XX-XXX-XX")

11. .build();

12. }

14. @Builder(builderClassName="FullBuilder", builderMethodName="fullBuilder")

15. public static Vehicule newVehicule(String numeroChassis,

16. String numeroMoteur,

17. LocalDate dateMiseEnCirculation,

18. String numeroImmatriculation)

19. {

20. return Vehicule.builder().numeroChassis(numeroChassis)

21. .numeroMoteur(numeroMoteur)

22. .dateMiseEnCirculation(dateMiseEnCirculation)

23. .numeroImmatriculation(numeroImmatriculation)

24. .build();

25. }

26. }

Quelques explications :

- @UtilityClass : parce que cette factory n'a pas vocation à être instanciée, le constructeur devient privé. De plus, la classe devient aussi final ;

- les méthodes de construction doivent être statiques : rien de choquant ;

- @Builder(builderClassName="...", builderMethodName="...") : déclarer une classe interne de type Builder et qui va se générer en fonction des arguments de la méthode. Il y aura autant de builders internes que d'annotations.

Et voici un petit usage :

1. Vehicule v1 = VehiculeFactory.smallBuilder()

2. .numeroChassis("AAABB123")

3. .numeroMoteur("123ABCD")

4. .build();

6. Vehicule v2 = VehiculeFactory.fullBuilder()

7. .numeroChassis("AAABB578")

8. .numeroMoteur("458AAA")

9. .dateMiseEnCirculation(LocalDate.now())

10. .numeroImmatriculation("789-AAA-987")

11. .build();

13. System.out.println(v1);

14. System.out.println(v2);

Ce qui donne sur la console :

1. Vehicule(numeroMoteur=123ABCD, numeroChassis=AAABB123, dateMiseEnCirculation=2018-03-06, numeroImmatriculation=XX-XXX-XX)

2. Vehicule(numeroMoteur=458AAA, numeroChassis=AAABB578, dateMiseEnCirculation=2018-03-06, numeroImmatriculation=789-AAA-987)

VI - Préconisations (enfin…)

Je les jette en vrac, avec une petite justification quand même.

- Ne pas utiliser @Data : comme annoncé en préambule, cela génère EqualsAndHashCode sur tous les champs, pareil pour ToString, ce qui peut occasionner des exécutions cycliques quand on a des relations bidirectionnelles entre les classes.

- Toujours utiliser @EqualsAndHashCode et @ToString en précisant les champs avec l'attribut of=....

- Spécifier les Getter / Setter sur les champs, et non pas sur la classe (en gros, pas comme dans tous les exemples que je viens de donner).

- Attention au Builder : intégrer un Builder sera possible, mais JPA, JSF ou CDI attendront que le constructeur sans argument soit présent avec le niveau « protected ».

- Attention aux logiciels de revue de code qui n'analysent pas le ByteCode mais que le code source : ils sont perdus…

VII - En guise de conclusion

C'est, vous l'aurez compris, une bibliothèque très puissante dont je ne peux plus me passer, comme annoncé en préambule.

Il y a encore pas mal d'annotations que je n'ai pas couvertes ici, mais qui sont tout aussi utiles :

- @CommonsLog ou @Slf4j ou encore @Log : pour les logs faciles ;

- @Value : pour les objets immuables ;

- @Cleanup : pour la libération de ressources ;

- @Delegate : pour gérer correctement les collections dans les compositions avec un délégué ;

- @Synchronized : pour de la synchronisation ENFIN gérée simplement et correctement.

On va dire que ça fera partie d'un prochain billet…

N'hésitez pas à me faire part de vos usages de Lombok en commentaire, que je reporterai ici le cas échéant.

VIII - Remerciements

Cet article a été publié avec l'aimable autorisation François-Xavier Robin.

Nous tenons à remercier f-leb pour sa relecture orthographique attentive de cet article et Mickael Baron pour la mise au gabarit.