Home About Download Tutorial Papers About the author Documentation Home About Download Tutorial Papers About the author

First case: creating frameworks that allow their users to create domain annotations

The first functionality provided by Daileon is the ability to allow frameworks to allow their users to use domain annotations, instead of the annotations provided by the framework. Metadata-based frameworks often provide annotations as a way to collect metadata and use it at runtime. One common situation is the following:

Listing 1. A method annotated with an annotation.
 public class MyClass {

     @FrameworkAnnotation
     public void method() {
         // do some processing...
     }
 }

In the example shown in Listing 1, a method is annotated with an annotation, provided by a framework. This framework collects the annotation and uses its information to customize its logic at runtime. This can be done via introspection (in the Java language, it is available in the elements located in the java.lang.reflect package). For instance, a framework could consume this annotation in the following way:

Listing 2. Reading the annotation.
  public class AnnotationReader {

     public void read() {
         // The framework somehow gets a reference to the class
         Class<?> clazz = MyClass.class;

         Method method = clazz.getMethod("method");
         if (method.isAnnotationPresent(FrameworkAnnotation.class)) {
             // @FrameworkAnnotation was found on the "method" element
             System.out.println("@FrameworkAnnotation found!");
             FrameworkAnnotation annotation = method.getAnnotation(FrameworkAnnotation.class);
             // Continue processing...
         }
     }
 }

Naturally, the framework is able to verify if a particular annotation is present in an element because it knows the annotation. What if the framework don't know the annotation? As addressed in the About section, a domain annotation is a custom annotation that is defined when the application is being developed. That means that the framework doesn't know it, and thus it isn't able to verify if it annotates a particular element. However, a domain annotation represents annotations that are known by the framework. The first functionality provided by Daileon allows this type of verification.

Suppose that, in a particular domain, the developer defines the following annotation:

Listing 3. Defining a domain annotation.
 package net.sf.daileon.app.domain;

 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;

 import net.sf.daileon.annotation.DomainAnnotation;

 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
 @DomainAnnotation
 @FrameworkAnnotation
 public @interface Repository {}

The @Repository is the domain annotation, and for such, the developer annotates it with @DomainAnnotation and the annotations that are represented by it (@FrameworkAnnotation, in the example above). With the new annotation, the example shown in Listing 1 could be rewritten in the following way:

Listing 4. A method annotated with an annotation.
 public class MyClass {

     @Repository
     public void method() {
         // do some processing...
     }
 }

Now, in order to verify if @FrameworkAnnotation is present in a particular element, instead of using introspection directly (as shown in Listing 2), the framework can use the DomainAnnotationsHelper class, provided by Daileon. For instance, in this case, the framework could verify if @FrameworkAnnotation is present in a particular element in the following way:

Listing 5. Verifying the presence of an annotation with Daileon.
 public class AnnotationReader {

     public void read() {
         // The framework somehow gets a reference to the class
         Class<?> clazz = MyClass.class;

         Method method = clazz.getMethod("method");
         if (DomainAnnotationsHelper.isAnnotationPresent(method, FrameworkAnnotation.class)) {
             // @FrameworkAnnotation was found on the "method" element
             System.out.println("@FrameworkAnnotation found!");
             FrameworkAnnotation annotation = DomainAnnotationsHelper
                     .getAnnotation(method, FrameworkAnnotation.class);
             // Continue processing...
         }
     }
 }

Now, in order to verify if an annotation is present in a particular element , it is possible to do so by calling the DomainAnnotationsHelper.isAnnotationPresent() method. Even though the annotation does not directly annotates the element, this method verifies if it annotates a domain annotation (in the example shown in Listing 3, @FrameworkAnnotation annotates the domain annotation @Repository). It is also possible to get the annotation itself by calling the DomainAnnotationsHelper.getAnnotation() method.

In conclusion, the first functionality offered by Daileon allows frameworks to allow their users to create domain annotations. Even though the framework does not know these annotations (as they are created when the application is created), it is possible to verify if a known annotation annotates indirectly a particular element, since the known annotation annotates the domain annotation. This can be done with the DomainAnnotationsHelper.isAnnotationPresent() method. To get the annotation itself, the DomainAnnotationsHelper.getAnnotation() method may be used.