How to use an annotation.

Defining an annotation type
To define an annotation type called Meta:

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

@Retention(RetentionPolicy.RUNTIME)
public @interface Meta {
 String data() default "fast";
}

Using an annotation
To use that annotation:

...
 @Meta(data = "slow") 
 public void foo(){
...
 }
...

Using the annotation meta data ("calm down dear, it's only an example").
To print out the meta data that the annotation defines for the example above:

 public static void main(String[] args) {
  for (Method method : MyClass.class.getMethods()) {
   Annotation[] annotations = method.getAnnotations();
   int num = annotations.length;
   if(num==1){
    System.out.println(((Meta)annotations[0]).data());
   }
  }
 }

JAX-RS: The Java API for RESTful Web Services

JAX-RS: The Java API for RESTful Web Services

http://www.developer.com/java/article.php/3843846/JAX-RS-The-Java-API-for-RESTful-Web-Services.htm

Non-Blocking I/O Made Possible in Java

Non-Blocking I/O Made Possible in Java

http://www.developer.com/java/article.php/3837316/Non-Blocking-IO-Made-Possible-in-Java.htm

Learn to Use the New Annotation Feature of Java 5.0

A article for annotation of Java 5 from http://www.devx.com/Java/Article/27235/1954?pf=true

What Are Annotations?
In short, annotations are metadata or data about data. Annotations are said to annotate a Java element. An annotation indicates that the declared element should be processed in some special way by a compiler, development tool, deployment tool, or during runtime.

Annotations can be analyzed statically before and during compile time. Annotations will likely be used before compile time mainly to generate supporting classes or configuration files.For example, a code generator (XDoclet, for example) can use annotation data in an EJB implementation class to generate EJB interfaces and deployment descriptors for you, reducing both your effort and the error rate. The average developer will probably not be writing code-generation tools, so these annotation types are likely to be used out-of-the-box rather than authored anew.

Annotations will also be used for compile-time checking such as to produce warnings and errors for different failure scenarios. An example of an annotation that is used at compile time is the new @Deprecated annotation, which acts the same as the old @deprecated JavaDoc tag.

Annotations can be useful at runtime as well. Using annotations you could mark code to behave in a particular way whenever it is called.For example, you could mark some methods with a @prelog annotation.

Another way to use annotations at runtime is to use Aspect-Oriented Programming (AOP). AOP uses pointcuts—sets of points configured to executed aspects. You could define a pointcut that will execute an aspect for an annotated method. My guess is that developers would be more likely to write their own runtime annotation types than they would annotation types used for code generation and compile-time checking. Still, writing and understanding the code that accesses the annotations (the annotation consumer) at runtime is fairly advanced.

Annotating Code
Annotations fall into three categories: normal annotations, single member annotations, and marker annotations (see Table 1). Normal and single member annotations can take member values as arguments when you annotate your code.

1. Normal Annotations—Annotations that take multiple arguments. The syntax for these annotations provides the ability to pass in data for all the members defined in an annotation type.
Example: @MyNormalAnnotation(mem1="val1", mem2="val2") public void someMethod() { ... }

2. Single Member Annotations—An annotation that only takes a single argument has a more compact syntax. You don't need to provide the member name.
Example: @MySingleMemberAnnotation("a single value") public class SomeClass { ... }

3.Marker Annotations—These annotations take no parameters. They are used to mark a Java element to be processed in a particular way.
Example: @Deprecated public void doWork() { ... }

Any Java declaration can be marked with an annotation. That is, an annotation can be used on a: package, class, interface, field, method, parameter, constructor, enum (newly available in Java 1.5), or local variable. An annotation can even annotate another annotation. Such annotations are called meta-annotations.

Packages annotations are also allowed, but because packages are not explicitly declared in Java, package annotations must be declared in a source file called package-info.java in the directory containing the source files for the package.

Built-in Annotations
Java 1.5 comes packaged with seven pre-built annotations.

java.lang.Override,

java.lang.Deprecated,

java.lang.SuppressWarning,
(The follows are meta-annotation.)

java.lang.annotation.Documented,

java.lang.annotation.Inherited,

java.lang.annotation.Retention,

java.lang.annotation.Target

Declaring Annotation Types
Now that you've learned a little about the annotations that come packaged with Java 1.5, you can move on to declaring your own annotation types.

Here is a sample annotation type:

public @interface MyAnnotationType {
    int someValue();
    String someOtherValue();
    String yesSomeOtherValue() default "[blank]";

}

The annotation consumers are the development tools, the compiler, or a runtime library that accesses the annotation data you created when you annotated your Java code.

An example of how you can access your code during runtime using the reflection API.

// The Annotation Type
import java.lang.annotation.Retention;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

@Retention(RUNTIME) 
public @interface GreetsTheWorld {
     public String value();
}

// The Annotated Class
@GreetsTheWorld("Hello, class!") 
public class HelloWorld {
     
     @GreetsTheWorld("Hello, field!") 
     public String greetingState;

     @GreetsTheWorld("Hello, constructor!") 
     public HelloWorld() {
     }

     @GreetsTheWorld("Hello, method!") 
     public void sayHi() {
     }
}

// The Annotation Consumer
import java.lang.reflect.Constructor;
import java.lang.reflect.Field;
import java.lang.reflect.Method;

public class HelloWorldAnnotationTest
{
  public static void main( String[] args ) throws Exception
  {
    //access the class annotation
    Class clazz = HelloWorld.class;
    System.out.println( clazz.getAnnotation( GreetsTheWorld.class ) );

    //access the constructor annotation
    Constructor constructor =
            clazz.getConstructor((Class[]) null);
    System.out.println(
            constructor.getAnnotation(GreetsTheWorld.class));

    //access the method annotation
    Method method = clazz.getMethod( "sayHi" );
    System.out.println(method.getAnnotation(GreetsTheWorld.class));

    //access the field annotation
    Field field = clazz.getField("greetingState");
    System.out.println(field.getAnnotation(GreetsTheWorld.class));
  }
}

Why did Hibernate update my database?

From http://blog.xebia.com/2009/04/06/why-did-hibernate-update-my-database/

Hibernate is a sophisticated ORM framework, that will manage the state of your persistent data for you. Handing over the important but difficult task of managing persistent state of your application to a framework has numerous advantages, but one of the disadvantages is that you sort of lose control over what happens where and when. One example of this is the dirty checking feature that Hibernate provides. By doing dirty checking, Hibernate determines what data needs to be updated in your database. In many cases, this feature is quite useful and will work without any issues, but sometimes you might find that Hibernate decides to update something that you did not expect. Finding out why his happened can be a rather difficult task.

I was asked to look into some issue with a StaleObjectState exception the other day. StaleObjectState exceptions are used by hibernate to signal an optimistic locking conflict: While some user (or process) tries to save a data item, the same data item has already been changed in the underlying database since it was last read. Now the problem was that the process that was throwing the exception was the only process that was supposed to change that data. From a functional point of view there could not have been any other user or process that changed the data in the meantime. So what was going on?

Digging around in the log for some time, we found that the data was updated by some other process that was supposed to only read that data. Somehow Hibernate decided that the data read by that process had become dirty and should be saved. So now he had to find out why Hibernate thought that data was dirty.

Hibernate can perform dirty checking in several places in an application:

1. When a transaction is being committed or a session is being flushed, obviously, because at that time changes made in the transaction or session should be persisted to the database
2. When a query is being executed. To prevent missing changes that still reside in memory, Hibernate will flush data that might be queried to the database just before executing the query. It tries to be picky about this and not flush everything all the time, but only the data that might be queried.
It is quite difficult to check all these places to find out where the data is being find dirty, especially when the process executes several queries.

To find out why Hibernate deems the data to be dirty, we have to dig into the Hibernate internals and start debugging the framework code. The Hibernate architecture is quite complex. There are a number of classes that are involved in dirty checking and updating entities:

The DefaultFlushEntityEventListener determines what fields are dirty. The internals of this class work on the list of properties of an entity and two lists of values: the values as loaded from the database and the values as currently known to the session. It delegates finding out the ''dirty-ness' of a field to the registered Interceptor and to the types of the properties.
The EntityUpdateAction is responsible for doing the update itself. An object of this type will be added to a ActionQueue to be executed when a session is flushed.
These classes show some of the patterns used in the internals of Hibernate: eventing and action queuing. These patterns make the architecture of the framework very clear, but they also make following what is going on sometimes very hard...

As previously explained, flushing happens quite often and setting a breakpoint in the DefaultFlushEntityEventListener is not usually a good idea, because it will get hit very often. An EntityUpdateAction, however, will only get created when an update will be issued to the underlying database. So to find out what the problem was, I set a breakpoint in the constructor and backtracked from there. It turned out Hibernate could not determine the dirty state of the object and therefor decided to update the entity just to be save.

As mentioned eralier, Hibernate uses the "loaded state" to determine whether an object is dirty. This is the state of the object (the values of its properties) when loaded form the database. Hibernate stores this information in its persistence context. When dirty checking, Hibernate compares these values to the current values. When the "loaded state" is not available, Hibernate effectively cannot do dirty checking and deems the object dirty. The only scenario, however, in which the loaded state is unavailable is when the object has been re-attached to the session and thus not loaded from the database. The process I was looking into, however did not work with detached data.

There is one other scenario in which Hibernate will lose the "loaded state" of the data: When the session is being cleared. This operation will discard all state in the persistence context completely. It is quite a dangerous operation to use in your application code and it should only be invoked if you are very sure of what you're doing. In our situation, the session was being flushed and cleared at some point, leading to the unwanted updates and eventually the StaleObjectStateExceptions. An unwanted situation indeed. After removing the clear, the updates where gone and the bug was fixed.

Using Hibernate can save a developer a lot of time, when things are running smoothly. When a problem is encountered, a lot of specialized Hibernate knowledge and a considerable amount of time is often needed to diagnose and solve it.