Les annotations en Java

Transcription

Les annotations en Java
F Mallet
F.
2010/2011
F. Mallet - Miage M1
1
Les annotations
F. Mallet
[email protected]
http://deptinfo.unice.fr/~fmallet/
2011/2012
F. Mallet
2
Les Annotations en Java
Les annotations
Apparues
pp
avec Java2 1.5 ((Tiger)
g )
Annoter des éléments du langage pour
 Documenter le code source
 Favoriser
F
i
l’i
l’introspection
t
ti
 Ajouter des opérations avant la compilation
• Nouvel outil: Annotation Processing Tool
Utili bl à lla compilation
Utilisables
il ti ou à l’l’exécution
é ti
 Différent des tag javadoc @author, @return, …
2010/2011
3
Utilisation
Devant l’élément marqué:
q
@Annotation





Package
Class Interface
Class,
Interface, Enum
Annotation
Constructeur Méthode
Constructeur,
Méthode, Paramètre
Champ, Variable
Exemple
@Annotation
class MaClasse { … }
2010/2011
4
Les annotations standards (1/3)
Déprécié
p
: @Deprecated
p
 Eléments qui ne devraient plus être utilisés:
classes,, méthodes,, constructeur,, champ,
p, …
 Remplace le tag javadoc @deprecated
• Mais sans expliquer
p q
la raison
• Possible d’utiliser conjointement les deux
/**
/
* @deprecated cf. Calendar.getDate
@Deprecated
@
*/
/ep ecated
public Date() { … }
2010/2011
5
Méthode redéfinie : @Override
 Si la méthode ne redéfinit pas effectivement une
méthode, une erreur est levée par le compilateur ou
IDE (Eclipse)
class A {
void m() { … }
}
class B extends A {
@Override
void m() { … }
}
2010/2011
6
IDE (Eclipse)
class A {
void m() { … }
}
class B extends A {
@Override
void M() { … }
}
2010/2011
7
IDE (Eclipse)
class A {
void m() { … }
}
class B extends A {
@Override
void m(int a) { … }
}
2010/2011
8
Cache
Cac e les
es a
avertissements:
e sse e s
@SuppressWarnings
 Par exemple,
exemple si on utilise une classe
générique sans définir le type.
class
l
A {
void m(ArrayList liste) { … }
}
type. References to generic
 ArrayList is a raw type
type ArrayList<E> should be parameterized
2010/2011
9
Cache
Cac e les
es a
avertissements:
e sse e s
@SuppressWarnings
 Par exemple,
exemple si on utilise une classe
générique sans définir le type.
class
l
A {
@SuppressWarnings("unchecked")
void m(ArrayList liste) { … }
}
2010/2011
10
La première annotation (1/2)
L’annotation @interface
Exemple de déclaration
public @interface PremiereAnnotation { }
Exemple d’utilisation
public class Foo {
@PremiereAnnotation
public void method() { … }
}
2010/2011
11
La première annotation (2/2)
L’annotation @interface
Exemple de déclaration
public @interface PremiereAnnotation { }
@PremiereAnnotation
public class Foo {
public void method() { … }
}
2010/2011
12
Annotation @TODO
 Déclaration simple
public @interface TODO { }
 Déclaration avec un paramètre String
public @interface TODO {
String value();
}
 Exemple
E
l d’
d’utilisation
tili ti
@TODO(value="ajouter un constructeur")
public
bli class
l
Foo {
}
2010/2011
13
Annotation @TODO
 Value est optionnel

Si value est le seul paramètre, alors il est optionnel
 Déclaration avec un paramètre String
String value();
}
 Exemple
E
l d’
d’utilisation
tili ti
@TODO("ajouter un constructeur")
public
bli class
l
Foo {
}
2010/2011
14
Annotation @TODO
Déclaration simple
public @interface TODO { }
Déclaration avec un paramètre String
String value();
}
T
Types
de
d retour
t
autorisés
t i é pour value()
l ()
 Type primitif, String, Class, Enum
 java.lang.annotation.Annotation
j
l
t ti A
t ti
 Tableau d’un type autorisé
2010/2011
15
Annotation @TODO
Déclaration avec plusieurs champs
String value();
Level level();
static enum Level {MINOR,NORMAL,URGENT};
{
,
,
};
}
d utilisation
@TODO(value="à modifier", level=TODO.Level.NORMAL)
void bar() { … }
2010/2011
16
Annotation @TODO
Déclaration avec plusieurs champs
String value();
Level level();
static enum Level {MINOR,NORMAL,URGENT};
{
,
,
};
}
d utilisation
import static TODO.Level.NORMAL;
…
@TODO(value="à modifier", level=NORMAL)
void bar() {… }
2010/2011
17
Annotation @TODO
Déclaration avec p
plusieurs champs
p
String value();
String[] responsables();
}
d utilisation de tableaux
@TODO(value="à modifier",
responsables={"Michel","Philippe"})
p
{
,
pp })
void bar() {… }
2010/2011
18
Annotation @TODO
Déclaration avec p
plusieurs champs
p
String value();
String[] responsables();
}
d utilisation de tableaux
@TODO(value="à modifier",
responsables="Michel")
p
)
void bar() {… }
2010/2011
19
Annotation @TODO
String value();
}
Interdit d’appliquer
d appliquer plusieurs fois la même
annotation
@TODO("à modifier")
difi ")
@TODO("changer le nom")
void bar() {… }
2010/2011
20
Annotation @TODOs
@interface TODO { String value(); }
@interface TODOs { TODO[] value(); }
Mais on peut faire un tableau d’annotations
@TODOs({
@TODO
({
@TODO("changer le nom"),
@TODO("à modifier")
})
void bar() {… }
2010/2011
21
Annotation @TODOs
@interface TODO { String value(); }
@interface TODOs { TODO[] value(); }
Mais on peut faire un tableau d’annotations
@TODOs(value
@TODO
( l
= {
@TODO(value = "changer le nom"),
@TODO(value = "à modifier")
})
void bar() {… }
2010/2011
22
Les méta-annotations
méta annotations
Paquetage
q
g j
java.lang.annotation
g
 @Documented
• Indique
q q
que l’annotation doit être documentée p
par
javadoc et les outils compatibles
 @Inherited
• L’annotation est hérité par l’élément qui hérite de
l’élément annoté
 @Retention
@
• Où l’annotation doit être maintenue (source, .class, JVM)
 @Target
• Limite le type des éléments sur lequel l’annotation peut
s’appliquer
2010/2011
23
Annotation @Documented
@Documented
@Retention(value=RUNTIME)
@Target(value=ANNOTATION_TYPE)
public @interface Documented {
}
Usage
@Documented
@interface Foo { }
2010/2011
24
Annotation @Inherited
@Documented
public @interface Inherited {
}
Application
@Inherited
@interface Foo { }
2010/2011
25
Annotation @Inherited
Application
pp
@Inherited
@interface Foo { }
Usage
g
 Si une classe A est annotée
@Foo
@
class A { … }
 Alors, les sous
sous-classes
classes de A héritent
automatiquement de l’annotation
class B extends A { … }
2010/2011
26
Annotation @Retention
@Documented
public
bli @i
@interface
f
Retention
i
{
RetentionPolicy[] value();
}
public enum
SOURCE,
CLASS,
RUNTIME
}
2010/2011
RetentionPolicy {
// pas incluse dans le .class
// dans le .class, mais pas JVM
// disponible par introspection
27
Annotation @Target
@Documented
public
bli @i
@interface
f
Target {
ElementType[] value();
}
public enum ElementType {
ANNOTATION_TYPE, CONSTRUCTOR, FIELD,
LOCAL VARIABLE, METHOD, PACKAGE,
LOCAL_VARIABLE,
PARAMETER, TYPE
}
2010/2011
28
Annotation @Target
@Target(ElementType.ANNOTATION_TYPE)
public @interface Target {
ElementType[] value();
}
@Target({FIELD, METHOD})
public @interface Foo {
String value();
}
2010/2011
29
Annotation et introspection
Méthodes de la classe Class
 <A extends Annotation>
getAnnotation(Class<A> annotation);
 Annotation[] getAnnotations();
 Annotation[] getDeclaredAnnotations();
();
 boolean isAnnotation();
 boolean
isAnnotationPresent(Class<?? extends
t d A
Annotation>
t ti
c);
2010/2011
30
Exemple
p
@
@TODO(value=A
(
Modifier))
@java.lang.Deprecated()
@Deprecated
@TODO{"A
@TODO{
A Modifier"}
Modifier }
class A { … }
Introspection
class<A> c = A.class;
Annotation[] as =
c.getAnnotations();
for(Annotation a : as)
System.out.println(a);
y
p
2010/2011
31
Exemple
e pe
A Modifier
@Deprecated
@TODO{"A Modifier"}
class A { … }
Introspection
class<A> c = A.class;
TODO todo =
c.getAnnotation(TODO.class);
tA
t ti (TODO l
)
System.out.println(todo.value());
2010/2011
32
ANNOTATION PROCESSING
TOOL
2010/2011
33
Annotation Processing Tool
Lors
o s de la
a co
compilation
p a o ou à la
a volée
o ée !
Deux utilisations complémentaires
 Aide
Aid à l’édition/compilation
l’éditi /
il ti
• Règles de développement (commentaires…)
• Affiche des messages (Warning, Error) à partir du
source Java
 Génération de code
• Ne peut PAS modifier le code source
• Peut générer des classes pour compléter le code
initial (Adaptateur…)
2010/2011
34
Exemple: @Override
IDE (Eclipse)
class A {
void m() { … }
}
class B extends A {
@Override
void M() { … }
}
2010/2011
35
AnnotationProcessor
com sun mirror apt
com.sun.mirror.apt.
 Documentation
 http://download.oracle.com/javase/1.5.0/docs/guide/apt/ (JSR 175)
 Compilation
Co p at o
 Implémentation livrée avec le JDK mais pas dans le
CLASSPATH par défaut
 $JAVA_HOME/lib/tools.jar
$
 IDE-specific: plugin org.eclipse.jdt.apt.core
 API
 Interface avec une seule méthode (à redéfinir)
 void
id process()
()
 Quel processeur pour quelle annotation ?
2010/2011
36
AnnotationProcessorFactory
com sun mirror apt
com.sun.mirror.apt.
 Déclare les annotations supportées
public Collection<String> supportedAnnotationTypes() {
return Collections.singleton("miage.m1.MyAnnotation");
}
 Déclare les options supportées
public Collection<String> supportedOptions() { return null;}
 Créé un AnnotationProcessor adapté en fonction de
ll’annotation
annotation rencontrée
public AnnotationProcessor getProcessorFor(
Set<AnnotationTypeDeclaration> atDecls,
AnnotationProcessorEnvironment env) {
return miage.m1.MyAnnotation(env);
}
2010/2011
37
Exemple d
d’AnnotationProcessor
AnnotationProcessor
class MyAnnotationProcessor implements AnnotationProcessor {
private AnnotationProcessorEnvironment _env;
env;
MyAnnotationProcessor(AnnotationProcessorEnvironment env) {
s per()
super();
_env = env;
}
@Override
public void process() {
// traite l’annotation
}
}
2010/2011
38
Exemple d
d’AnnotationProcessor
AnnotationProcessor
// constructeur,
constructeur champs,
champs …
@Override
A
AnnotationTypeDeclaration
t ti T
D l
ti
annotDecl
tD l =
(AnnotationTypeDeclaration)_env.getTypeDeclaration(
"miage.m1.MyAnnotation");
if (annotDecl==null)
(
tD l
ll) return;
t
Collection<Declaration> decls =
_env.getDeclarationsAnnotatedWith(annotDecl);
if (decls == null) return;
for(Declaration declaration : decls) {
// traite la déclaration annotée
}
}
2010/2011
39
Declaration vs
vs. Type
2010/2011
40
com sun mirror util
com.sun.mirror.util.
DeclarationVisitor
Tout
ou visiteur
s eu do
doit implémenter
p é e e l’interface
e ace
interface DeclarationVisitor {
visitDeclaration(Declaration);
visitMemberDeclaration(MemberDeclaration);
visitTypeDeclaration(TypeDeclaration);
visitClassDeclaration(ClassDeclaration);
i itCl
D l
ti (Cl
D l
ti )
visitFieldDeclaration(FieldDeclaration);
…
}
Adaptateur standard vide

2010/2011
com.sun.mirror.util.SimpleDeclarationVisitor
41
Pour afficher des messages
// constructeur,
champs …
@Override
A
t ti T
D l
ti
annotDecl
tD l =
(
tD l
ll) return;
t
declaration.accept(new MyVisitor(_env.getMessenger()));
}
}
2010/2011
42
Exemples de Visiteur
Affiche simplement
p
le nom des déclarations
class MyVisitor extends SimpleDeclarationVisitor{
public void visitDeclaration(Declaration d) {
System out println("Decl:" + d.getSimpleName());
System.out.println("Decl:"
d getSimpleName());
}
}
2010/2011
43
Exemples de Visiteur
Affiche un warning
g si le nom d’une classe
commence par une minuscule
import com.sun.mirror.apt.Messager;
class MyVisitor extends SimpleDeclarationVisitor{
Messager messager;
MyVisitor(Messager
y
(
g
messager)
g ) {
this.messager = messager;
}
public
bli void
id visitClassDeclaration(ClassDeclaration
i itCl
D l
ti (Cl
D l
ti
d) {
if (Character.isLowerCase(d.getSimpleName().getChar(0)))
messager.printWarning(d.getPosition(),
"Class names should start with a capital letter");
}
}
2010/2011
44
Pour générer du code
// constructeur,
champs …
@Override
A
t ti T
D l
ti
annotDecl
tD l =
(
tD l
ll) return;
t
generate(_env.getFiler()));
}
}
2010/2011
45
Pour générer du code
// …
private void generate(Filer filer) {
PrintWriter pw = filer.createSourceFile("Essai.java");
pw.println("class
println(" l
E
Essai
i {")
{");
pw.println(" static public void main(String[] args) {");
pw.println("
System.out.println(\"Fichier généré.\");");
pw.println("
i tl (" }")
}");
pw.println("}");
pw.close();
}
}
Le code généré
 Est généré dans le bon dossier (package)
 Est compilé et peut contenir des annotations
2010/2011
46
Utilisation des annotations
Outil
Ou ap
apt (d
(disponible
spo b e a
avec
ec JJDK))
 apt -factorypath { où se trouve MyFactory.class }

-factory miage.m1.MyFactory

-s {répertoire où générer les .java}

-d {répertoire où générer les .class}

-cp {chemin
{ h i pour l
la compilation}
il ti }

{fichiers Java à compiler avec processeur}
2010/2011
47
Sources
Tutoriels
u o e s de Su
Sun:
 http://download.oracle.com/docs/books/tutorial/java/javaOO/annotations.html
 http://download.oracle.com/javase/1.5.0/docs/guide/language/annotations.html
 http://download.oracle.com/javase/1.5.0/docs/guide/apt/
http://download oracle com/javase/1 5 0/docs/guide/apt/
2010/2011
48

Les annotations en Java

Transcription

Documents pareils

Mardi 17 Janvier 19h00 Exia / Cesi de Mont Saint Aignan Des

catholic charities usa

DE TODO CORAZÓN

Diplomatic-Cover - Top Interactive Agencies

Procédure d`installation et d`activation de licence : Télécharger la

Programmation JAVA JSE

PSY-Formation int2015:PSY-Int-Form-06

Descriptif mission en alternance : Caterpillar Grenoble Equipe

Voir mon CV - Master 2 IMT