Java pre-processing and annotations talk. How to do it? How it works? Why to do it? Github code: https://github.com/luanpotter/annotation-preprocessing https://github.com/luanpotter/reflection-utils

1. Annotations
Unleashing the power of Java

2. Danilo De Luca
@danilodeluca
danilo.luca@dextra-sw.com
Luan Nico
@luanpotter
luannico27@gmail.com

3. Annotations - O que são?
➔Meta documentação do código

4. Annotations - O que são?
➔Meta documentação do código
@Override
public void toString() { /* ... */ }

5. Annotations - Default Annotations
@Override
@Deprecated
@SupressWarnings({ "unchecked" /* , ... */ })
@SafeVarargs
@FunctionalInterface

6. Annotations - Default Annotations
@Override
@Deprecated
@SupressWarnings({ "unchecked" /* , ... */ })
@SafeVarargs -> stackoverflow.com/questions/14231037
@FunctionalInterface

7. Annotations - Default Annotations
@Override
@Deprecated
@SupressWarnings({ "unchecked" /* , ... */ })
@SafeVarargs -> stackoverflow.com/questions/14231037
@FunctionalInterface -> Java 8 (Consumer, Function, …)

8. Annotations - Creating Annotations!

9. Annotations - Creating Annotations!
public @interface MyShinyAnnotation {
/* ... */
}

10. Annotations - Annotating Annotations

11. Annotations - Annotating Annotations
@Retention ◀
@Target
@Documented
@Inherited

12. Annotations - RetentionPolicy
RetentionPolicy.SOURCE
RetentionPolicy.CLASS
RetentionPolicy.RUNTIME

13. Annotations - RetentionPolicy
RetentionPolicy.SOURCE - @Override
RetentionPolicy.CLASS
RetentionPolicy.RUNTIME

14. Annotations - RetentionPolicy
RetentionPolicy.SOURCE - @Override
RetentionPolicy.CLASS - bytecode libs
RetentionPolicy.RUNTIME

15. Annotations - RetentionPolicy
RetentionPolicy.SOURCE - @Override
RetentionPolicy.CLASS - bytecode libs
RetentionPolicy.RUNTIME - @Deprecated

16. Annotations - Creating Annotations!
@Retention(RetentionPolicy.RUNTIME)
public @interface MyShinyAnnotation {
/* ... */
}

17. Annotations - Annotating Annotations
@Retention
@Target ◀
@Documented
@Inherited

18. Annotations - ElementType
ElementType.ANNOTATION_TYPE
ElementType.CONSTRUCTOR
ElementType.FIELD
ElementType.LOCAL_VARIABLE
ElementType.METHOD
ElementType.PACKAGE
ElementType.PARAMETER
ElementType.TYPE

19. Annotations - ElementType
ElementType.ANNOTATION_TYPE
ElementType.CONSTRUCTOR
ElementType.FIELD
ElementType.LOCAL_VARIABLE
ElementType.METHOD
ElementType.PACKAGE
ElementType.PARAMETER
ElementType.TYPE
ElementType.TYPE_PARAMETER NEW
ElementType.TYPE_USE NEW

20. Annotations - Creating Annotations!
@Target({ TYPE, METHOD, FIELD })
@Retention(RetentionPolicy.RUNTIME)
public @interface MyShinyAnnotation {
/* ... */
}

21. Annotations - Annotating Annotations
@Retention
@Target
@Documented ◀
@Inherited

22. Annotations - Annotating Annotations
@Retention
@Target
@Documented
@Inherited ◀ [class only]

23. Annotations - Annotating Annotations
@Retention
@Target
@Documented
@Inherited
@Repeatable ◀ NEW

24. Annotations - Elements

25. Annotations - Elements
@Target({ TYPE, METHOD, FIELD })
@Retention(RetentionPolicy.RUNTIME)
public @interface MyShinyAnnotation {
String value();
int intValue() default 12;
}

26. Annotations - Elements
@MyShinyAnnotation
@MyShinyAnnotation()
@MyShinyAnnotation(value = "a")
@MyShinyAnnotation("a")
@MyShinyAnnotation(value = "a", intValue = 7)
@MyShinyAnnotation("a", intValue = 7)

27. Annotations - Elements
@MyShinyAnnotation
@MyShinyAnnotation() : todos os elements são obrigatórios (salvo default)
@MyShinyAnnotation(value = "a")
@MyShinyAnnotation("a")
@MyShinyAnnotation(value = "a", intValue = 7)
@MyShinyAnnotation("a", intValue = 7)

28. Annotations - Elements
@MyShinyAnnotation
@MyShinyAnnotation() : todos os elements são obrigatórios (salvo default)
@MyShinyAnnotation(value = "a") : ok
@MyShinyAnnotation("a") : ok
@MyShinyAnnotation(value = "a", intValue = 7)
@MyShinyAnnotation("a", intValue = 7)

29. Annotations - Elements
@MyShinyAnnotation
@MyShinyAnnotation() : todos os elements são obrigatórios (salvo default)
@MyShinyAnnotation(value = "a") : ok
@MyShinyAnnotation("a") : ok
@MyShinyAnnotation(value = "a", intValue = 7) :ok
@MyShinyAnnotation("a", intValue = 7)

30. Annotations - Elements
@MyShinyAnnotation
@MyShinyAnnotation() : todos os elements são obrigatórios (salvo default)
@MyShinyAnnotation(value = "a") : ok
@MyShinyAnnotation("a") : ok
@MyShinyAnnotation(value = "a", intValue = 7) :ok
@MyShinyAnnotation("a", intValue = 7) : nok

31. Annotations - Uses

32. Annotations - Uses
Documentação - Evolução Javadoc
// Author: John Doe
// Date: 3/17/2002
// Current revision: 6
// Last modified: 4/12/2004
// By: Jane Doe
// Reviewers: Alice, Bill, Cindy
public class MyPojo { /* ... */ }

33. Annotations - Uses
Documentação - Evolução Javadoc
// Author: John Doe
// Date: 3/17/2002
// Current revision: 6
// Last modified: 4/12/2004
// By: Jane Doe
// Reviewers: Alice, Bill, Cindy
public class MyPojo { /* ... */ }
@ClassPreamble(
author = "John Doe",
date = "3/17/2002",
currentRevision = 6,
lastModified = "4/12/2004",
lastModifiedBy = "Jane Doe",
reviewers = { "Alice", "Bob", "Cindy" }
)
public class MyPojo { /* ... */ }

34. Annotations - Uses
Documentação - Evolução Javadoc
// Author: John Doe
// Date: 3/17/2002
// Current revision: 6
// Last modified: 4/12/2004
// By: Jane Doe
// Reviewers: Alice, Bill, Cindy
public class MyPojo { /* ... */ }
@ClassPreamble(
author = "John Doe",
date = "3/17/2002",
currentRevision = 6,
lastModified = "4/12/2004",
lastModifiedBy = "Jane Doe",
reviewers = { "Alice", "Bob", "Cindy" }
)
public class MyPojo { /* ... */ }
➔ Easily ‘parseable’!
➔ Standardized!
➔ Type safe!*
*Well, sort of…
➔ Required (compile errors)

35. Annotations - Uses
Solução mais simples...

36. Annotations - Uses
Solução mais simples...
GIT

37. Annotations - Uses
Documentação - Casos Reais

38. Annotations - Uses
Documentação - Casos Reais
@DroolsUsage
@FailingTest

39. Annotations - Uses
Runtime Analysis

40. Annotations - Uses
Runtime Analysis
➔ Hibernate, Spring, Drools, yawp.io

41. Annotations - Uses
Runtime Analysis
➔ Hibernate, Spring, Drools, yawp.io
Annotations over xml hell!

42. Annotations - Uses
Annotation Preprocessing

43. Annotations - Uses
Annotation Preprocessing LATER

44. Annotations - Uses
Documentação
Runtime Analysis
Annotation Preprocessing

45. Annotations - Limitations

46. Annotations - Limitations
★ Valid element types

47. Annotations - Limitations
★ Valid element types
String Primitives
Enums Annotations
Class Arrays of those

48. Annotations - Limitations
★ Valid element types
String Primitives
Enums Annotations
Class Arrays of those
>> Use enum’s or String’s
➔ Date -> String
➔ Comparator -> ComparatorType [could be a Class here too]
>> Use other annotations to group fields
>> But no generic enum nor annotation! [Enum, Annotation]

49. Annotations - Limitations
★ Compile-time constant values

50. Annotations - Limitations
★ Compile-time constant values
@Source(value = "xpto")
public static String randomString() { /* ... */ }
@Source(value = randomString())
public static String readFromFile() { /* ... */ }
@Source(value = readFromFile())
public static String readFromDatabase() { /* ... */ }
@Source(value = readFromDatabase())

51. Annotations - Limitations
★ Compile-time constant values
@Source(value = "xpto") : ok
public static String randomString() { /* ... */ }
@Source(value = randomString()) : nok
public static String readFromFile() { /* ... */ }
@Source(value = readFromFile()) : nok
public static String readFromDatabase() { /* ... */ }
@Source(value = readFromDatabase()) : nok

52. Annotations - Limitations
★ Compile-time constant values
@Source(value = "xpto") : ok
static final String myValue = "xpt";
@Source(value = myValue + "o")
static final String myValue = readFromDatabase();
@Source(value = myValue + "o")
static final String[] myValues = { "xpto" };
@Source(value = myValues[0])

53. Annotations - Limitations
★ Compile-time constant values
@Source(value = "xpto") : ok
static final String myValue = "xpt";
@Source(value = myValue + "o") : ok
static final String myValue = readFromDatabase();
@Source(value = myValue + "o")
static final String[] myValues = { "xpto" };
@Source(value = myValues[0])

54. Annotations - Limitations
★ Compile-time constant values
@Source(value = "xpto") : ok
static final String myValue = "xpt";
@Source(value = myValue + "o") : ok
static final String myValue = readFromDatabase();
@Source(value = myValue + "o") : nok
static final String[] myValues = { "xpto" };
@Source(value = myValues[0])

55. Annotations - Limitations
★ Compile-time constant values
@Source(value = "xpto") : ok
static final String myValue = "xpt";
@Source(value = myValue + "o") : ok
static final String myValue = readFromDatabase();
@Source(value = myValue + "o") : nok
static final String[] myValues = { "xpto" };
@Source(value = myValues[0]) : nok

56. Annotations - Limitations
★ No inheritance
>> Annotate annotations with annotations
@Validator(clazz = Object.class)
public @interface NotNull { /* ... */ }

57. Annotations - Limitations
★ No inheritance
>> Annotate annotations with annotations
@Validator(clazz = Object.class)
public @interface NotNull { /* ... */ }
>> Extract repeated code to other classes
>> Make broad annotations with specializing optional parameters

58. New to Java 8
❖ Repeating Annotations
❖ Type Annotations

59. Repeating Annotations

60. Repeating Annotations
@Allow(Roles.USER)
@Allow(Roles.ADMIN)
public void process(Data data) { /* … */ }

61. Repeating Annotations
@Allow({ Roles.USER, Roles.ADMIN })
public void process(Data data) { /* … */ }

62. Repeating Annotations
@Allow(value = Roles.USER, access = Access.READ_ONLY)
@Allow(value = Roles.ADMIN, access = Access.READ_WRITE)
public void process(Data data) { /* … */ }

63. Repeating Annotations
@Allows({
@Allow(value = Roles.USER, access = Access.READ_ONLY)
@Allow(value = Roles.ADMIN, access = Access.READ_WRITE)
})
public void process(Data data) { /* … */ }

64. Repeating Annotations
@Repeatable(Allows.class)
public @interface Allow {
Role value();
Access access();
}
public @interface Allows {
Allow[] value();
}

65. Repeating Annotations
@Allow(value = Roles.USER, access = Access.READ_ONLY)
@Allow(value = Roles.ADMIN, access = Access.READ_WRITE)
public void process(Data data) { /* … */ }

66. Type Annotations

67. Type Annotations
★ ElementType.TYPE_PARAMETER : tipos usados como generics
★ ElementType.TYPE_USE : qualquer menção a um tipo

68. Type Annotations
★ List<@Numeric String> phones;
★ Map<@NonEmpty String, @Adult Person> peopleByName;
public void test() {
@NotNull String a = "Hi!";
// ….
}

69. Type Annotations
★ This can be used for several things:
○ Checkers
○ Static code validation
○ Model Validation

70. Type Annotations
Example!
<dependency>
<groupId>xyz.luan</groupId>
<artifactId>reflection-utils</artifactId>
<version>0.7.1</version>
</dependency>

71. Annotation Preprocessing

72. Annotation Preprocessing
➔Etapas adicionais de compilação
controladas via Annotations
➔Exemplo:
◆ projectlombok.org / github.com/rzwitserloot/lombok
◆ FragmentArgs / ButterKnife [android]

73. Annotation Preprocessor
➔Project Lombok
public class MyBoringModel {
private String field;
public String getField() {
return this.field;
}
}

74. Annotation Preprocessor
➔Project Lombok
public class MyBoringModel {
@Getter private String field;
}
➔ @Getter, @Setter, @ToString, @EqualsAndHashCode → @Data
➔ @SneakyThrows, @UtilityClass, @Cleanup
➔Muito mais!
➔projectlombok.org/features

75. Annotation Preprocessing
➔Como funciona?
◆ Preprocessors extend AbstractProcessor
◆ Implementam os métodos usando uma API análoga
a de Reflection
◆ Registram-se no META-INF
◆ javac sobe uma vm e roda os processadores
registrados em turnos

76. Annotation Preprocessing
➔Na prática
◆ Baixe o jar da biblioteca e coloque no classpath do
javac

77. Annotation Preprocessing
➔Na prática
◆ ✓ Baixe o jar da biblioteca e coloque no classpath
do javac

78. Annotation Preprocessing
➔Na prática
◆ ✓ Baixe o jar da biblioteca e coloque no classpath
do javac
◆ Adicione a dependência no maven/gradle/etc

79. Annotation Preprocessing
➔Na prática
◆ ✓ Baixe o jar da biblioteca e coloque no classpath
do javac
◆ ✓ Adicione a dependência no maven/gradle/etc

80. Annotation Preprocessing
➔Na prática
◆ ✓ Baixe o jar da biblioteca e coloque no classpath
do javac
◆ ✓ Adicione a dependência no maven/gradle/etc
➔Precisa ser uma lib separada [META-INF]
➔Precisa habilitar annotation preprocessing
em algumas IDEs (javac faz por padrão)

81. Annotation Preprocessor
➔Possibilidades
◆ Análise de código (dar erros e warnings...)
◆ Gerar métodos, campos, classes, qualquer coisa
➔Limitações
◆ Triggerado por annotations [processamento em
rodadas]
➔“Problemas”
◆ Excessivamente poderoso

82. Annotation Preprocessor
➔Como fazer?
◆ Exemplo Codigo

83. Annotation Preprocessing
<dependencies>
<dependency>
<groupId>com.google.auto.service</groupId>
<artifactId>auto-service</artifactId>
<version>1.0-rc4</version>
</dependency>
</dependencies>

84. Annotation Preprocessing
➔Extremamente poderoso!
◆ With great power comes great responsibility
➔API razoavelmente feia
➔Podemos juntar com Reflection
◆ Preprocess in compile-time
◆ Reflection in run-time
➔Possibilidades são infinitas

85. Dúvidas?

86. Danilo De Luca
@danilodeluca
danilo.luca@dextra-sw.com
Luan Nico
@luanpotter
luannico27@gmail.com