Header javaperspective.com
JavaPerspective.com  >   Advanced Tutorials  >   4. Miscellaneous Java features  >   4.1. Annotations

4.1. Annotations
Last updated: 2 January 2013.

An annotation is a convenient way to add metadata to Java code. At compile time, annotations are used by the Java compiler to detect certain errors, ignore warnings and also to generate code, documentation or XML resource files. At runtime, annotations can be read but they do not affect the behaviour of the application in which they are used.

You can annotate packages, interfaces, classes, fields, constructors, methods, method parameters and variables. An annotation must be written before the declaration of the annotated element. Furthermore, according to the Java code conventions, it should be on a separate line. The JDK provides 3 predefined annotations: @Override, @Deprecated and @SuppressWarnings. The next sections will show you how to use each predefined annotation.

In fact, the JDK also allows you to define your own annotations but since typical developers never have to define custom annotations, this tutorial only covers the use of predefined annotations.


@Override

The @Override annotation tells the compiler that the annotated method overrides a superclass method or implements an interface method. Here is an example:

@Override
public void doSomething(){
   
// ...
    // ...
}

In case you are overriding a superclass method, if the annotated method does not have the same exact signature than the overridden superclass method, your code will not compile. Although the @Override annotation is optional, it is recommended to use it when you are overriding a superclass method because it allows you to detect errors (for instance, you may have inadvertently mispelled the method name or, you may have omitted a parameter) . As an illustration, suppose that you want to override the method doSomething provided by the superclass SuperClass shown below:

public class SuperClass {

   
public void doSomething(){
         
// ...
          // ...
   
}

}

Naturally, you can override the method doSomething with no @Override annotation as follows:

public final class SubClass extends SuperClass {

   
public void dosomething(){
         
// ...
          // ...
   
}

}

The code above compiles even though you have mispelled the method name (you wrote dosomething instead of doSomething). However, the method dosomething does not override the method doSomething provided by the superclass SuperClass. Later on, you write the code shown below in order to call the supposedly overriding method that you implemented in SubClass (but this time, with the right spelling):

SubClass subClass = new SubClass();
subClass.doSomething
();

You think you have called the overriding method implemented in the class SubClass but in fact, you called the superclass method provided by the class SuperClass. If there is not any noticeable difference between the execution of dosomething and doSomething, you may never detect the error. To prevent such a situation, it is recommended to use the @Override annotation which detects that kind of error at compile time.


@Deprecated

The @Deprecated annotation states that the annotated element is deprecated. A deprecated element is an element that should no longer be used. If you use a deprecated element in your code, a warning will be generated. In the next sample, the method yourDeprecatedMethod is declared as a deprecated method:

@Deprecated
public void yourDeprecatedMethod(){
   
// ...
    // ...
}

The @Deprecated annotation should always be associated with the @deprecated tag in the javadoc documentation of the annotated element. This way, you can use the javadoc to explain why the element was deprecated. Note that the javadoc tag starts with @d whereas the annotation starts with @D:

/**
*
@deprecated
* This method is deprecated because ...
*/
@Deprecated
public void yourDeprecatedMethod(){
   
// ...
    // ...
}


@SuppressWarnings

The @SuppressWarnings annotation allows you to ignore certain warnings at compile time. For instance, the compiler issues a warning if a variable is declared inside a method without being used. If you want the compiler to ignore such warnings, you can use a @SuppressWarnings annotation like this:

@SuppressWarnings("unused")
public void yourMethod(){
   
int yourUnusedVariable = 0;
   
// ...
    // ...
}

Likewise, if you also want to ignore the warnings generated by the use of deprecated elements or unchecked conversions, use the @SuppressWarnings annotation as shown in the next sample:

@SuppressWarnings({"unused", "deprecation", "unchecked"})
public void yourMethod(){
   
int yourUnusedVariable = 0;
   
// ...
    // ...
    // Calls to deprecated methods
    // ...
    // ...
    // Unchecked conversions
    // ...
    // ...
}


You are here :  JavaPerspective.com  >   Advanced Tutorials  >   4. Miscellaneous Java features  >   4.1. Annotations
Next tutorial :  JavaPerspective.com  >   Advanced Tutorials  >   4. Miscellaneous Java features  >   4.2. Comparators

Copyright © 2013. JavaPerspective.com. All rights reserved.  ( Terms | Contact | About ) 
Java is a trademark of Oracle Corporation
Image 1 Image 2 Image 3 Image 4 Image 5 Image 6 Image 7