Fun with Java Annotations Brian McGinnis

Java Annotations Introduced in “Tiger” release (Java 1.5) Introduced in “Tiger” release (Java 1.5) One of most interesting Java extension in a long time One of most interesting Java extension in a long time Ability to declare metadata modifiers for Java language upon: Ability to declare metadata modifiers for Java language upon: Type declarations, Constructors, methods, Members, Parameters, Variables Type declarations, Constructors, methods, Members, Parameters, Variables

Standard Java 1.5 Annotations Tiger has some useful built-in annotations Tiger has some useful built-in annotations Java.lang.Override Java.lang.Override Compiler enforces overriding superclass methods Compiler enforces overriding superclass methods Java.lang.Deprecated Java.lang.Deprecated Warns method, class or member is used Warns method, class or member is used Must use javac “-deprecation” argument to javac or the new - Xlint:deprecated flag to see compiler warnings Must use javac “-deprecation” argument to javac or the new - Xlint:deprecated flag to see compiler warnings Java.lang.SupressWarnings Java.lang.SupressWarnings Useful for Tiger’s many compiler warnings (especially with legacy collection code) Useful for Tiger’s many compiler warnings (especially with legacy collection code) Key: Look for a string enclosed in “[ ]” in compiler warnings from javac (may need to use the command line). Use this string to use for argument. Key: Look for a string enclosed in “[ ]” in compiler warnings from javac (may need to use the command line). Use this string to use for argument. This may work on your compiler yet! This may work on your compiler yet!

@Override Example Code: class Base { public void yes(int i) { } public void yes(int i) { }} class Subclass extends public void yes(int i) { } public void yes(int i) public void no(float x) { } // Compiler error generated here! public void no(float x) { } // Compiler error generated here!}

@Deprecated Example Example public class DeprecatedExample { private int x; private public int value; public public void setValue(int aValue) { value = aValue; } public void setValue(int aValue) { value = aValue; }} public class DeprecatedExampleUse { public static void main(String argv[]) public static void main(String argv[]) { DeprecatedExample obj = new DeprecatedExample(); // Compiler WARNINGs generated here DeprecatedExample obj = new DeprecatedExample(); // Compiler WARNINGs generated here obj.value = 10; // Compiler WARNING generated here obj.value = 10; // Compiler WARNING generated here }}

@SuppressWarning Example public class SuppressExample { List wordList = new ArrayList(); // no typing information on the List List wordList = new ArrayList(); // no typing information on the List private void private void generateWarning() generateWarning() { wordList.add("foo"); // Warning generated here. wordList.add("foo"); // Warning generated here. }} javac -Xlint:unchecked SuppressExample.java SuppressExample.java:13: warning: [unchecked] unchecked call to add(E) as a member of the raw type java.util.List wordList.add("foo"); // Warning generated here. wordList.add("foo"); // Warning generated here. ^ 1 warning Get rid of warning by adding this line above the method

Setting Annotation Values Setting Annotation Values Setting Annotation Values Set arguments as key/value pairs Set arguments as key/value pairs Can optionally be an array of key value pairs Can optionally be an array of key value pairs “Marker” annotations “Marker” annotations No arguments No arguments Single value annotations Single value annotations no key is required, just a value no key is required, just a value Multiple value annotations Multiple value annotations separate key/value pairs with commas separate key/value pairs with commas Law”, grade=Grades.Pass) Law”, grade=Grades.Pass)

Java Annotations Metadata from annotations is available at compile-time and at runtime Metadata from annotations is available at compile-time and at runtime What for? What for? compile-time uses: Tools like a code generator or code validator (e.g. java.lang.Override) compile-time uses: Tools like a code generator or code validator (e.g. java.lang.Override) runtime uses: Any framework or application code that can make use of metadata (e.g. J2EE) runtime uses: Any framework or application code that can make use of metadata (e.g. J2EE)

Implementing and using custom annotations

A Sample Annotation Application A simple example to demo custom annotations A simple example to demo custom annotations The demo application is: We want to readily identify design patterns used in our production code The demo application is: We want to readily identify design patterns used in our production code Users put in annotation to identify design patterns in their code Users put in annotation to identify design patterns in their code annotation takes 3 arguments: annotation takes 3 arguments: PatternType = an enum for which design pattern (e.g. singleton, builder, etc.) PatternType = an enum for which design pattern (e.g. singleton, builder, etc.) Role = a string to denote the role played in more complex patterns (e.g. for an MVC pattern, role=“controller”) Role = a string to denote the role played in more complex patterns (e.g. for an MVC pattern, role=“controller”) Msg = a string to further explain pattern usage Msg = a string to further explain pattern usage

Sample usage #1 package samples.myapp; import custom.annotation.Pattern; import custom.annotation.PatternType; /** An example singleton that uses annotation. msg=“Singleton wrapper class”) public class SampleOne { private static SampleOne instance = null; private static SampleOne instance = null; private SampleOne() { } private SampleOne() { } public static SampleOne public static SampleOne get() get() { if (instance == null) if (instance == null) instance = new SampleOne(); instance = new SampleOne(); return(instance); return(instance); }}

Sample Usage #2 package samples.myapp; import custom.annotation.Pattern; import custom.annotation.PatternType; /** An example class that uses annotation. */ public class SampleTwo role="static factory role="static factory method") public static SampleTwo public static SampleTwo create(int aValue) create(int aValue) { SampleTwo instance = new SampleTwo(aValue); SampleTwo instance = new SampleTwo(aValue); return(instance); return(instance); } private int i; private int i; protected SampleTwo(int a) { i = a; } protected SampleTwo(int a) { i = a; } protected SampleTwo() { } protected SampleTwo() { }}

Implementing Annotations 4 standard meta-annotations you need to know about: 4 standard meta-annotations you need to know – specifies which Java elements can use the annotation (e.g. Type, method, constructor, – specifies which Java elements can use the annotation (e.g. Type, method, constructor, – specifies if annotation info is available at compile-time or at – specifies if annotation info is available at compile-time or at – Indicates if annotation should be part of public api. Annotation use shows up in – Indicates if annotation should be part of public api. Annotation use shows up in – Specify inheritance handling of the – Specify inheritance handling of the annotation

Implementing annotations 1. Declare meta-annotations for you custom annotation in the java etc. 2. Declare for your custom annotation in the java file Similar to a regular Java ‘interface’ Similar to a regular Java ‘interface’ Define “properties” of the annotation as methods Define “properties” of the annotation as methods

Annotation Implementation package custom.annotation; Import …. // Specify our meta-annoations ElementType.METHOD, // Tell javadoc to include usage of our custom annotations Pattern { // The design pattern enum value for the annotation instance. // The design pattern enum value for the annotation instance. PatternType type(); PatternType type(); // The "role" played in the design pattern. (value is optional) // The "role" played in the design pattern. (value is optional) String role() default "“; String role() default "“; // Some text to be displayed played in the design pattern. (optional) // Some text to be displayed played in the design pattern. (optional) String msg() default ""; String msg() default "";}

Annotation Implementation package custom.annotation; /** Declare the design patterns known by our annotation. */ public enum PatternType { /** A class which wraps a singleton object instance... blah. */ /** A class which wraps a singleton object instance... blah. */ SINGLETON_CLASS, SINGLETON_CLASS, /** A method used to constructs an object instance... blah. */ /** A method used to constructs an object instance... blah. */ FACTORY_METHOD, FACTORY_METHOD, /** A class which is used to... blah. */ /** A class which is used to... blah. */ BUILDER; BUILDER; public static String public static String getHtmlLink(PatternType pattern, String basePath) { … } getHtmlLink(PatternType pattern, String basePath) { … }}

Tools to use our custom type At runtime, you can get annotation values from java classes At runtime, you can get annotation values from java classes If you defined the annotation If you defined the annotation Use java reflection to pickup annotations from methods, members, etc. Use java reflection to pickup annotations from methods, members, etc. Demo a sample app which prints out all we used in our application code Demo a sample app which prints out all we used in our application code

Pattern Tool Source Code public class PatternTool { /** Processes annotations for a java class. The meat of our tool. */ /** Processes annotations for a java class. The meat of our tool. */ private void processPatternAnnotations(Class javaClass) throws IOException private void processPatternAnnotations(Class javaClass) throws IOException { // Get the declared upon class declaration // Get the declared upon class declaration if (javaClass.isAnnotationPresent(Pattern.class)) { if (javaClass.isAnnotationPresent(Pattern.class)) { Pattern classLevelPattern = (Pattern)javaClass.getAnnotation(Pattern.class); Pattern classLevelPattern = (Pattern)javaClass.getAnnotation(Pattern.class); printClassPattern(classLevelPattern, javaClass.getName()); printClassPattern(classLevelPattern, javaClass.getName()); } // Get all declared upon methods via reflection // Get all declared upon methods via reflection Method[] methods = javaClass.getDeclaredMethods(); Method[] methods = javaClass.getDeclaredMethods(); for (Method method : methods) { for (Method method : methods) { method.setAccessible(true); // make private methods accessible method.setAccessible(true); // make private methods accessible Pattern methodPattern = method.getAnnotation(Pattern.class); Pattern methodPattern = method.getAnnotation(Pattern.class); if (methodPattern != null) { if (methodPattern != null) { printMethodPattern(methodPattern, javaClass.getName(), method.getName()); printMethodPattern(methodPattern, javaClass.getName(), method.getName()); } } …code removed for clarity… …code removed for clarity…}

Sample HTML Output Design Pattern Usage Java Class: samples.myapp.SampleOne samples.myapp.SampleOne Class level design pattern implemented: Singleton Class Design Pattern, Msg: ‘Singleton Wrapper Class’ Singleton Class Design PatternSingleton Class Design Pattern Java Class: samples.myapp.SampleTwo samples.myapp.SampleTwo Method create() implements design pattern: Factory Method Pattern, Role: 'static factory method' create()Factory Method Patterncreate()Factory Method Pattern

Some Ideas on how to apply annotations Things to make you think about how annotations can be used

Replace older technology Replace javadoc-oriented precompilers Replace javadoc-oriented precompilers Provide runtime access to metadata - not just compile-time. Provide runtime access to metadata - not just compile-time. Metadata syntax checked by java compiler Metadata syntax checked by java compiler Replace XML-oriented java tools Replace XML-oriented java tools Put metadata in your java files were it is easy to maintain - not in separate XML files Put metadata in your java files were it is easy to maintain - not in separate XML files Do away with verbose, error-prone XML typing Do away with verbose, error-prone XML typing Typically easier to find and fix errors than fiddling with the XML parsing + Java errors Typically easier to find and fix errors than fiddling with the XML parsing + Java errors Provide built-in type checking for metadata via java compiler Provide built-in type checking for metadata via java compiler Rapidly replacing XML usage in J2EE in many areas Rapidly replacing XML usage in J2EE in many areas

Application Idea: Binding a pojo to user interface resetbutton=false) Public class PersonInfo type=FormField.TEXT, size=25, printf=“%s”) public Sting type=FormField.RADIO, type=FormField.RADIO, isReqd=true) public State type=FormField.TEXT, printf=“%d”) public Integer age; …}

Application ideas: User Input public class PersonPojo max=115) public int public Integer numberOfDependents; …}

Application: com.acme.Metrics.class, com.acme.CustomSecurity.class}) public class AccountManagementBean implements AccountManagement { public void createAccount(int accountNumber, AccountDetails details) {... }...} public class Metrics public Object profile(InvocationContext inv) throws Exception { long time = System.currentTimeMillis(); try { return inv.proceed(); } finally { long endTime = time - System.currentTimeMillis(); System.out.println(inv.getMethod() + " took " + endTime + “ milliseconds."); }}} public class AccountAudit public Object auditAccountOperation(InvocationContext inv) throws Exception { try { Object result = inv.proceed(); Auditor.audit(inv.getMethod().getName(), inv.getParameters[0]); return result; } catch (Exception ex) { Auditor.auditFailure(ex); throw ex; } }} public class CustomSecurity public Object customSecurity(InvocationContext inv) throws Exception….

Application: EJB public class Maintainence { public void importCompanyData () {...} public void restart () public class HRActivity public void addToPayroll () “Manager”}) public void postJobOpening() {...}...}

Application Idea: Code Maintentance Annotations Public class MyAppClass { // Tags to generate documentation of SQL used in your application so it’s easier to // figure out implications of dbms schema changes and dbms protected static final String sql = “select id, version from astro_entity where type = ?”; public ArrayList getSuperNova(String snType) { ….} // Tags to generate documentation on hacks and things todo for future linear sort algorithm”, fix=“Use tree sorting to separate class”) public void sortSuperNova(ArrayList sn) {…}