Web inventor warns of 'dark' net by Jonathan Fildes

The web should remain neutral and resist attempts to fragment it into different services, web inventor Sir Tim Berners-Lee has said.

Recent attempts in the US to try to charge for different levels of online access web were not "part of the internet model," he said in Edinburgh.

He warned that if the US decided to go ahead with a two-tier internet, the network would enter "a dark period".

Sir Tim was speaking at the start of a conference on the future of the web.

"What's very important from my point of view is that there is one web," he said.

"Anyone that tries to chop it into two will find that their piece looks very boring."

An equal net

The British scientist developed the web in 1989 as an academic tool to allow scientists to share data. Since then it has exploded into every area of life.

"You get this tremendous serendipity where I can search the internet and come across a site that I did not set out to look for"
Tim Berners-Lee

However, as it has grown, there have been increasingly diverse opinions on how it should evolve.

The World Wide Web Consortium, of which Sir Tim is the director, believes in an open model.

This is based on the concept of network neutrality, where everyone has the same level of access to the web and that all data moving around the web is treated equally.

This view is backed by companies like Microsoft and Google, who have called for legislation to be introduced to guarantee net neutrality.

The first steps towards this were taken last week when members of the US House of Representatives introduced a net neutrality bill.

Pay model

But telecoms companies in the US do not agree. They would like to implement a two-tier system, where data from companies or institutions that can pay are given priority over those that cannot.

This has particularly become an issue with the transmission of TV shows over the internet, with some broadband providers wanting to charge content providers to carry the data.

The internet community believes this threatens the open model of the internet as broadband providers will become gatekeepers to the web's content.

Providers that can pay will be able to get a commercial advantage over those that cannot.

There is a fear that institutions like universities and charities would also suffer.

The web community is also worried that any charges would be passed on to the consumer.

Optimism

Sir Tim said this as "not the internet model". The "right" model, as exists at the moment, was that any content provider could pay for a connection to the internet and could then put any content on to the web with no discrimination.

Speaking to reporters in Edinburgh at the WWW2006 conference, he argued this was where the great benefit of the internet lay.

"You get this tremendous serendipity where I can search the internet and come across a site that I did not set out to look for," he said.

A two-tier system would mean that people would only have full access to those portions of the internet that they paid for and that some companies would be given priority over others.

But Sir Tim was optimistic that the internet would resist attempts to fragment.

"I think it is one and will remain as one," he said.

(http://news.bbc.co.uk/)

Dealing with InterruptedException by Brian Goetz

You caught it, now what are you going to do with it?

Many Java™ language methods, such as Thread.sleep() and Object.wait(), throw InterruptedException. You can't ignore it because it's a checked exception, but what should you do with it? In this month's Java theory and practice, concurrency expert Brian Goetz explains what InterruptedException means, why it is thrown, and what you should do when you catch one.

This story is probably familiar: You're writing a test program and you need to pause for some amount of time, so you call Thread.sleep(). But then the compiler or IDE balks that you haven't dealt with the checked InterruptedException. What is InterruptedException, and why do you have to deal with it?

The most common response to InterruptedException is to swallow it -- catch it and do nothing (or perhaps log it, which isn't any better) -- as we'll see later in Listing 4. Unfortunately, this approach throws away important information about the fact that an interrupt occurred, which could compromise the application's ability to cancel activities or shut down in a timely manner.

Blocking methods

When a method throws InterruptedException, it is telling you several things in addition to the fact that it can throw a particular checked exception. It is telling you that it is a blocking method and that it will make an attempt to unblock and return early -- if you ask nicely.
A blocking method is different from an ordinary method that just takes a long time to run. The completion of an ordinary method is dependent only on how much work you've asked it to do and whether adequate computing resources (CPU cycles and memory) are available. The completion of a blocking method, on the other hand, is also dependent on some external event, such as timer expiration, I/O completion, or the action of another thread (releasing a lock, setting a flag, or placing a task on a work queue). Ordinary methods complete as soon as their work can be done, but blocking methods are less predictable because they depend on external events. Blocking methods can compromise responsiveness because it can be hard to predict when they will complete.

Because blocking methods can potentially take forever if the event they are waiting for never occurs, it is often useful for blocking operations to be cancelable. (It is often useful for long-running non-blocking methods to be cancelable as well.) A cancelable operation is one that can be externally moved to completion in advance of when it would ordinarily complete on its own. The interruption mechanism provided by Thread and supported by Thread.sleep() and Object.wait() is a cancellation mechanism; it allows one thread to request that another thread stop what it is doing early. When a method throws InterruptedException, it is telling you that if the thread executing the method is interrupted, it will make an attempt to stop what it is doing and return early and indicate its early return by throwing InterruptedException. Well-behaved blocking library methods should be responsive to interruption and throw InterruptedException so they can be used within cancelable activities without compromising responsiveness.

Thread interruption

Every thread has a Boolean property associated with it that represents its interrupted status. The interrupted status is initially false; when a thread is interrupted by some other thread through a call to Thread.interrupt(), one of two things happens. If that thread is executing a low-level interruptible blocking method like Thread.sleep(), Thread.join(), or Object.wait(), it unblocks and throws InterruptedException. Otherwise, interrupt() merely sets the thread's interruption status. Code running in the interrupted thread can later poll the interrupted status to see if it has been requested to stop what it is doing; the interrupted status can be read with Thread.isInterrupted() and can be read and cleared in a single operation with the poorly named Thread.interrupted().

Interruption is a cooperative mechanism. When one thread interrupts another, the interrupted thread does not necessarily stop what it is doing immediately. Instead, interruption is a way of politely asking another thread to stop what it is doing if it wants to, at its convenience. Some methods, like Thread.sleep(), take this request seriously, but methods are not required to pay attention to interruption. Methods that do not block but that still may take a long time to execute can respect requests for interruption by polling the interrupted status and return early if interrupted. You are free to ignore an interruption request, but doing so may compromise responsiveness.

One of the benefits of the cooperative nature of interruption is that it provides more flexibility for safely constructing cancelable activities. We rarely want an activity to stop immediately; program data structures could be left in an inconsistent state if the activity were canceled mid-update. Interruption allows a cancelable activity to clean up any work in progress, restore invariants, notify other activities of the cancellation, and then terminate.

Dealing with InterruptedException

If throwing InterruptedException means that a method is a blocking method, then calling a blocking method means that your method is a blocking method too, and you should have a strategy for dealing with InterruptedException. Often the easiest strategy is to throw InterruptedException yourself, as shown in the putTask() and getTask() methods in Listing 1. Doing so makes your method responsive to interruption as well and often requires nothing more than adding InterruptedException to your throws clause.


Listing 1. Propagating InterruptedException to callers by not catching it

public class TaskQueue {
private static final int MAX_TASKS = 1000;

private BlockingQueue queue
= new LinkedBlockingQueue(MAX_TASKS);

public void putTask(Task r) throws InterruptedException {
queue.put(r);
}

public Task getTask() throws InterruptedException {
return queue.take();
}
}


Sometimes it is necessary to do some amount of cleanup before propagating the exception. In this case, you can catch InterruptedException, perform the cleanup, and then rethrow the exception. Listing 2, a mechanism for matching players in an online game service, illustrates this technique. The matchPlayers() method waits for two players to arrive and then starts a new game. If it is interrupted after one player has arrived but before the second player arrives, it puts that player back on the queue before rethrowing the InterruptedException, so that the player's request to play is not lost.


Listing 2. Performing task-specific cleanup before rethrowing InterruptedException

public class PlayerMatcher {
private PlayerSource players;

public PlayerMatcher(PlayerSource players) {
this.players = players;
}

public void matchPlayers() throws InterruptedException {
try {
Player playerOne, playerTwo;
while (true) {
playerOne = playerTwo = null;
// Wait for two players to arrive and start a new game
playerOne = players.waitForPlayer(); // could throw IE
playerTwo = players.waitForPlayer(); // could throw IE
startNewGame(playerOne, playerTwo);
}
}
catch (InterruptedException e) {
// If we got one player and were interrupted, put that player back
if (playerOne != null)
players.addFirst(playerOne);
// Then propagate the exception
throw e;
}
}
}


Don't swallow interrupts

Sometimes throwing InterruptedException is not an option, such as when a task defined by Runnable calls an interruptible method. In this case, you can't rethrow InterruptedException, but you also do not want to do nothing. When a blocking method detects interruption and throws InterruptedException, it clears the interrupted status. If you catch InterruptedException but cannot rethrow it, you should preserve evidence that the interruption occurred so that code higher up on the call stack can learn of the interruption and respond to it if it wants to. This task is accomplished by calling interrupt() to "reinterrupt" the current thread, as shown in Listing 3. At the very least, whenever you catch InterruptedException and don't rethrow it, reinterrupt the current thread before returning.


Listing 3. Restoring the interrupted status after catching InterruptedException

public class TaskRunner implements Runnable {
private BlockingQueue queue;

public TaskRunner(BlockingQueue queue) {
this.queue = queue;
}

public void run() {
try {
while (true) {
Task task = queue.take(10, TimeUnit.SECONDS);
task.execute();
}
}
catch (InterruptedException e) {
// Restore the interrupted status
Thread.currentThread().interrupt();
}
}
}


The worst thing you can do with InterruptedException is swallow it -- catch it and neither rethrow it nor reassert the thread's interrupted status. The standard approach to dealing with an exception you didn't plan for -- catch it and log it -- also counts as swallowing the interruption because code higher up on the call stack won't be able to find out about it. (Logging InterruptedException is also just silly because by the time a human reads the log, it is too late to do anything about it.) Listing 4 shows the all-too-common pattern of swallowing an interrupt:


Listing 4. Swallowing an interrupt -- don't do this

// Don't do this
public class TaskRunner implements Runnable {
private BlockingQueue queue;

public TaskRunner(BlockingQueue queue) {
this.queue = queue;
}

public void run() {
try {
while (true) {
Task task = queue.take(10, TimeUnit.SECONDS);
task.execute();
}
}
catch (InterruptedException swallowed) {
/* DON'T DO THIS - RESTORE THE INTERRUPTED STATUS INSTEAD */
}
}
}


If you cannot rethrow InterruptedException, whether or not you plan to act on the interrupt request, you still want to reinterrupt the current thread because a single interruption request may have multiple "recipients." The standard thread pool (ThreadPoolExecutor) worker thread implementation is responsive to interruption, so interrupting a task running in a thread pool may have the effect of both canceling the task and notifying the execution thread that the thread pool is shutting down. If the task were to swallow the interrupt request, the worker thread might not learn that an interrupt was requested, which could delay the application or service shutdown.


Back to top


Implementing cancelable tasks

Nothing in the language specification gives interruption any specific semantics, but in larger programs, it is difficult to maintain any semantics for interruption other than cancellation. Depending on the activity, a user could request cancellation through a GUI or through a network mechanism such as JMX or Web Services. It could also be requested by program logic. For example, a Web crawler might automatically shut itself down if it detects that the disk is full, or a parallel algorithm might start multiple threads to search different regions of the solution space and cancel them once one of them finds a solution.

Just because a task is cancelable does not mean it needs to respond to an interrupt request immediately. For tasks that execute code in a loop, it is common to check for interruption only once per loop iteration. Depending on how long the loop takes to execute, it could take some time before the task code notices the thread has been interrupted (either by polling the interrupted status with Thread.isInterrupted() or by calling a blocking method). If the task needs to be more responsive, it can poll the interrupted status more frequently. Blocking methods usually poll the interrupted status immediately on entry, throwing InterruptedException if it is set to improve responsiveness.

The one time it is acceptable to swallow an interrupt is when you know the thread is about to exit. This scenario only occurs when the class calling the interruptible method is part of a Thread, not a Runnable or general-purpose library code, as illustrated in Listing 5. It creates a thread that enumerates prime numbers until it is interrupted and allows the thread to exit upon interruption. The prime-seeking loop checks for interruption in two places: once by polling the isInterrupted() method in the header of the while loop and once when it calls the blocking BlockingQueue.put() method.


Listing 5. Interrupts can be swallowed if you know the thread is about to exit

public class PrimeProducer extends Thread {
private final BlockingQueue queue;

PrimeProducer(BlockingQueue queue) {
this.queue = queue;
}

public void run() {
try {
BigInteger p = BigInteger.ONE;
while (!Thread.currentThread().isInterrupted())
queue.put(p = p.nextProbablePrime());
} catch (InterruptedException consumed) {
/* Allow thread to exit */
}
}

public void cancel() { interrupt(); }
}


Noninterruptible blocking

Not all blocking methods throw InterruptedException. The input and output stream classes may block waiting for an I/O to complete, but they do not throw InterruptedException, and they do not return early if they are interrupted. However, in the case of socket I/O, if a thread closes the socket, blocking I/O operations on that socket in other threads will complete early with a SocketException. The nonblocking I/O classes in java.nio also do not support interruptible I/O, but blocking operations can similarly be canceled by closing the channel or requesting a wakeup on the Selector. Similarly, attempting to acquire an intrinsic lock (enter a synchronized block) cannot be interrupted, but ReentrantLock supports an interruptible acquisition mode.

Noncancelable tasks

Some tasks simply refuse to be interrupted, making them noncancelable. However, even noncancelable tasks should attempt to preserve the interrupted status in case code higher up on the call stack wants to act on the interruption after the noncancelable task completes. Listing 6 shows a method that waits on a blocking queue until an item is available, regardless of whether it is interrupted. To be a good citizen, it restores the interrupted status in a finally block after it is finished, so as not to deprive callers of the interruption request. (It can't restore the interrupted status earlier, as it would cause an infinite loop -- BlockingQueue.take() could poll the interrupted status immediately on entry and throws InterruptedException if it finds the interrupted status set.)


Listing 6. Noncancelable task that restores interrupted status before returning

public Task getNextTask(BlockingQueue queue) {
boolean interrupted = false;
try {
while (true) {
try {
return queue.take();
} catch (InterruptedException e) {
interrupted = true;
// fall through and retry
}
}
} finally {
if (interrupted)
Thread.currentThread().interrupt();
}
}





Back to top


Summary

You can use the cooperative interruption mechanism provided by the Java platform to construct flexible cancellation policies. Activities can decide if they are cancelable or not, how responsive they want to be to interruption, and they can defer interruption to perform task-specific cleanup if returning immediately would compromise application integrity. Even if you want to completely ignore interruption in your code, make sure to restore the interrupted status if you catch InterruptedException and do not rethrow it so that the code that calls it is not deprived of the knowledge that an interrupt occurred.

(http://www-128.ibm.com/developerworks/java/library/j-jtp05236.html?ca=drs)

Declarative Programming in Java by Narayanan Jayaratchagan

Narayanan Jayaratchagan is a Sun Certified J2EE Architect with more than six years of experience with Java and Microsoft Technologies.

What makes EJB components special is the declarative programming model through which we can specify the services such as security, persistence, transaction etc., that the container should provide. An EJB only implements the business logic; the services are associated through a deployment descriptor, which essentially acts as metadata for the EJB. At runtime, the container uses the metadata specified in the deployment descriptor to provide the services. The deployment descriptor is an XML file, not part of the Java classes that make up the EJBs. Is there a standard way to annotate the Java classes that make up the EJBs so that a developer can look at the class definition, together with annotations, and know everything about that class? It would be even better if the remote, home interfaces and the deployment descriptor could be automatically generated by a tool using the annotations. Better yet, can we provide the same kind of declarative services for a simple Java object? If so, how? This article examines how JSR-175: A Metadata Facility for the Java Programming Language will help us in finding answers to these questions and more.

Approaches to Programming

There are two approaches to programming called imperative programming and declarative programming. Imperative programming gives a list of instructions to execute in a particular order -- Java program that counts the number of words in a text file is an example of the imperative approach. Declarative programming describes a set of conditions, and lets the system figure out how to fulfill them. The SQL statement SELECT COUNT(*) FROM XYZ is an example for the declarative approach. In other words, "specifying how" describes imperative programming and "specifying what is to be done, not how" describes declarative programming.

Annotations

The Tiger release of Java (JDK 1.5) adds a new language construct called annotation (proposed by JSR-175). Annotation is a generic mechanism for associating metadata (declarative information) with program elements such as classes, methods, fields, parameters, local variables, and packages. The compiler can store the metadata in the class files. Later, the VM or other programs can look for the metadata to determine how to interact with the program elements or change their behavior.

Declaring an Annotation

Declaring an annotation is very simple -- it takes the form of an interface declaration with an @ preceding it and optionally marked with meta-annotations, as shown below:

package njunit.annotation;

import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD})
public @interface UnitTest {
 String value();
}

The Retention meta-annotation declares that the @UnitTest annotation should be stored in the class file and retained by the VM so it may be read reflectively. The Target meta-annotation declares that the @UnitTest annotation can be used to annotate methods in a Java class. @interface declares the @UnitTest annotation with one member called value, which returns a String.

Using an Annotation

Here is an example that shows how to use the @UnitTest annotation declared in the previous section:

import njunit.annotation.*;

public class Example {

   @UnitTest(value="Test 1. This test will pass.")
   public void pass() {
       assert 10 > 5;
   }

   @UnitTest("Test 2. This test will fail.")
   public void fail() {
       assert 10 < 5;
   }

}

An annotation is applied to the code element by placing an annotation statement (@AnnotationType(...)) before the program element. Annotation values take the form "name=value"; for example, @UnitTest(value="some text"). Single-member annotations with a member named value are treated specially and can use the shorthand @UnitTest("some text"). In the example, the @UnitTest annotation is associated with the pass and fail methods.

Accessing Annotations at Runtime

Once annotations have been associated with program elements, we can use reflection to query their existence and get the values. The main reflection methods to query annotations are in a new interface: java.lang.reflect.AnnotatedElement.

Methods available in the AnnotatedElement interface are:

• boolean isAnnotationPresent(Class annotationType)
  Returns true if an annotation for the specified type is present on this element, else false. This method is designed primarily for convenient access to marker annotations.

• T getAnnotation(Class annotationType)
  Returns this element's annotation for the specified type if such an annotation is present, else null.

• Annotation[] getAnnotations()
  Returns all annotations present on this element. (Returns an array of length zero if this element has no annotations.)

• Annotation[] getDeclaredAnnotations()
  Returns all annotations that are directly present on this element. Unlike the other methods in this interface, this method ignores inherited annotations. (Returns an array of length zero if no annotations are directly present on this element.)

You may notice that the isAnnotationPresent and getAnnotation methods are defined using generics, another new feature available in JDK 1.5.

Here is the list of classes that implement the AnnotatedElement interface:

1. java.lang.reflect.AccessibleObject
2. java.lang.Class
3. java.lang.reflect.Constructor
4. java.lang.reflect.Field
5. java.lang.reflect.Method
6. java.lang.Package

Next, I'll show you an example that illustrates how to access annotations at runtime.

package njunit;

import java.lang.reflect.*;
import njunit.annotation.*;

public class TestRunner {
   static void executeUnitTests(String className) {
       try {
           Object testObject =
               Class.forName(className).newInstance();
           Method [] methods =
               testObject.getClass().getDeclaredMethods();
           for(Method amethod : methods) {
           UnitTest utAnnotation =
               amethod.getAnnotation(UnitTest.class);
           if(utAnnotation!=null) {
               System.out.print(utAnnotation.value() +
                               " : " );
               String result =
                   invoke(amethod, testObject);
               System.out.println(result);
               }
           }
       }catch(Exception x) {
           x.printStackTrace();
       }
   }
  
   static String invoke(Method m, Object o) {
       String result = "passed";
       try{
           m.invoke(o,null);
       } catch(Exception x) {
           result = "failed";
       }
       return result;
   }
  
   public static void main(String [] args) {
       executeUnitTests(args[0]);
   }
}

The TestRunner uses the @UnitTest annotation to determine whether a method is a unit test or not, invoke the method if it is marked with the @UnitTest annotation, and report the success or failure.

Here is how the TestRunner executes the unit test. Given a Java class, the TestRunner first obtains the list of all declared methods using reflection. Then it queries each method using the enhanced for construct and the getAnnotation method available in JDK 1.5 to find out whether it is marked as a @UnitTest. If it is marked, then it invokes the method and reports the success or failure. A test is considered failed if there is any exception when executing the test, and is considered passed otherwise.

In our Example class, the pass method will succeed when invoked, but the fail method will throw an AssertionError, which is propagated to the TestRunner.invoke method as InvocationTargetException.

When run with the command java -ea njunit.TestRunner Example, the output looks like the following:

Test 1. This test will pass. : passed
Test 2. This test will fail. : failed

Meta-Annotations

Java defines several standard meta-annotations (annotation types designed for annotating annotation type declarations).

The new package java.lang.annotation contains the following meta-annotations:

Meta-annotation	Purpose
@Documented	Indicates that annotations with a type are to be documented by javadoc and similar tools by default.
@Inherited	Indicates that an annotation type is automatically inherited.
@Retention	Indicates how long annotations with the annotated type are to be retained. Example: @Retention(RetentionPolicy.RUNTIME) The enumeration RetentionPolicy defines the constants to be used for specifying Retention.
@Target	Indicates the kinds of program element to which an annotation type is applicable. Example: @Target({ElementType.FIELD, ElementType.METHOD}) The enumeration ElementType defines constants that are used with the Target meta-annotation type to specify where it is legal to use an annotation type.

Standard Annotations

There are two standard annotations in the java.lang package.

Annotation	Purpose
@Deprecated	Reincarnation of deprecated javadoc tag as an annotation in JDK 1.5. Compilers warn when a deprecated program element is used or overridden in non-deprecated code.
@Overrides	Indicates that a method declaration is intended to override a method declaration in a super-class. If a method is annotated with this annotation type but does not override a super-class method, compilers are required to generate an error message.

The following example illustrates the use of standard annotations.

public class Parent {
   @Deprecated
   public void foo(int x) {
       System.out.println("Parent.foo(int x) called.");
   }
}

public class Child extends Parent {
   @Overrides
   public void foo() {
       System.out.println("Child.foo() called.");
   }
}

My intention is to extend the Parent class and override the foo(int x) method in Child class. By mistake, the foo method in the child does not override the one in the parent, because of the mismatch in the signature. Obviously, this is a bug. In the past, this kind of bug could be identified only at runtime after hours of debugging. Now, the use of the @Overrides annotation can save hours wasted in debugging. When a method is annotated with @Overrides, the compiler will check whether the method in a child class really overrides a method in the parent. The compiler will report an error when no method is overridden.

javac -source 1.5 Parent.java Child.java
Child.java:3: method does not override
a method from its superclass
@Overrides
^
1 error

Let's correct the error by modifying the foo method signature, and compile the code again.

public class Child extends Parent{
   @Overrides
   public void foo(int x) {
       System.out.println("Child.foo(int x) called.");
   }
}

javac -Xlint:deprecation -source 1.5 Child.java
Child.java:4: warning:
[deprecation] foo(int) in Parent has been
deprecated
public void foo(int x) {
           ^
1 warning

The foo method is marked as deprecated using the @Deprecated annotation, so the compiler reports a warning, as shown above.

A Complex Example

To keep the introduction simple, I used a single valued annotation. Now it's time to look at a complex one.

public @interface Trademark {
 String description();
 String owner();
}

In the code snippet above we have declared an annotation called Trademark with two members: description and owner, both of which return String.

import java.lang.annotation.*;
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.PACKAGE})
public @interface License {
 String name();
 String notice();
 boolean redistributable();
 Trademark[] trademarks();
}

In the code snippet above, we have declared an annotation called License, which has members that return String, boolean, and an array of Trademark annotations. Now we can use the License annotation.

@License(
name = "Apache",
notice = "license notice ........",
redistributable = true,
trademarks =
  {@Trademark(description="abcd",owner="xyz"),
   @Trademark(description="efgh",owner="klmn")}
)
public class Example2 {
   public static void main(String []args) {
   License lic;
   lic=Example2.class.getAnnotation(License.class);
   System.out.println(lic.name());
   System.out.println(lic.notice());
   System.out.println(lic.redistributable());
   Trademark [] tms = lic.trademarks();
   for(Trademark tm : tms) {
       System.out.println(tm.description());
       System.out.println(tm.owner());
       }
   }
}

The above example shows how to use annotations that have multiple members with String, boolean, and array return types. It also illustrates how to define annotations with parameter values that are annotations. The main method in Example2 illustrates how to access the annotations at runtime.

Defaults and Order of name=value Pairs

import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE})
public @interface Help {
 String topic() default "Unknown Topic";
 String url();
}

Default values for members can be specified in the annotation declaration so that it becomes optional when defining it. In the above example, String topic() default "Unknown Topic"; declares a default value for topic. While defining the Help annotation, the topic is optional and need not be specified. For example, @Help(url=".../help.html") is valid. The url must be specified, otherwise this will result in a compilation error.

In the annotation definition, the name=value pairs can be specified in any order. @Help(topic="Order does not matter", url=".../help.html") and @Help(url=".../help.html", topic="Order does not matter") are considered the same.

Package-Level Annotations

Annotations that can be applied to the package element are referred to as package-level annotations. An annotation with ElementType.PACKAGE as one of its targets is a package-level annotation. Package-level annotations are placed in a package-info.java file. This file should contain only the package statement, preceded by annotations. When the compiler encounters package-info.java file, it will create a synthetic interface, package-name.package-info. The interface is called synthetic because it is introduced by the compiler and does not have a corresponding construct in the source code. This synthetic interface makes it possible to access package-level annotations at runtime. The javadoc utility will use the package-info.java file if it is present, instead of package.html, to generate documentation.

The package-info.java file will look like this:

/**
* documentation comments...
*/
@Annotation1(...)
package sample;

Note: The JDK 1.5 beta release compiler parses the package-info.java file, but does not emit a synthetic interface as stated in the specification.

Restrictions on Annotations

It is important to know that certain restrictions are imposed on annotation declaration:

1. No extends clause is permitted. (Annotation types automatically extend a new marker interface, java.lang.annotation.Annotation.)
2. Methods must not have any parameters.
3. Methods must not have any type parameters (in other words, generic methods are prohibited).
4. Method return types are restricted to primitive types, String, Class, enum types, annotation types, and arrays of the preceding types.
5. No throws clause is permitted.
6. Annotation types must not be parameterized.

Source-Level Annotations

Not all annotations need to be stored in the class files. For example, the deprecated javadoc tag used to mark a program element as obsolete and inform the compiler to emit a warning is now available as the Deprecated annotation, which is a source-level annotation. To declare an annotation to be visible only at source level, use @Retention(RetentionPolicy.SOURCE). The compiler does not store source-level annotations in the class file. Source-level annotations are expected to be used by tools such as documentation generators (javadoc), compilers, and other tools that require/have access to source files.

Accessing Annotations in the Source Files

We can use the Doclet API to access annotations from the source files. The com.sun.javadoc package provides several new interfaces, and methods have been added to existing interfaces to support annotations. I'll walk you through an example that shows you how to access annotations using doclets.

import com.sun.javadoc.*;
public class ListAnnotations {
   public static boolean start(RootDoc root) {
       ClassDoc[] classes = root.classes();
       for (ClassDoc clsDoc : classes) {
           processAClass(clsDoc);
       }
       return true;
   }
   static void processAClass(ClassDoc clsDoc) {
       System.out.println("List of annotations in " +
                           clsDoc.name());
       list(clsDoc.annotations());
   }

   static void list(AnnotationDesc[] annDescs) {
       for (AnnotationDesc ad : annDescs) {
           AnnotationTypeDoc at = ad.annotationType();
           System.out.println("----------");
           System.out.println("Annotation : " + at.name());
           AnnotationDesc.MemberValuePair [] members =
                           ad.memberValues();
           for(AnnotationDesc.MemberValuePair mvp : members) {
               System.out.println("Member = " +
                       mvp.member().name() +
                       ", Value = "+ mvp.value() + "");
           }
       }
   }
}

A Java class with the method public static boolean start(com.sun.javadoc.RootDoc root) is a doclet. The doclet uses the interfaces from the com.sun.javadoc package to gain access to various elements of a class from the source file. To execute a doclet, we have to use the javadoc tool. javadoc will parse the source files and call the start method, which is the entry point for a doclet, similar to the main method in a Java program.

Compiling and Executing the Doclet

javac -source 1.5 -cp c:\jdk15\lib\tools.jar ListAnnotations.java

javadoc -source 1.5 -doclet ListAnnotations -sourcepath . UnitTest.java

Loading source file UnitTest.java...
Constructing Javadoc information...
List of annotations in UnitTest
----------
Annotation : Retention
Member = value, Value = RUNTIME
----------
Annotation : Target
Member = value, Value = METHOD

Class-Level Annotations

We already saw two kinds of annotations: runtime and source. There is yet another kind of annotation: class. This is the default when the Retention meta-annotation is not present or it is present with a value RetentionPolicy.CLASS; the compiler stores annotations in the class files but the VM may not load them at runtime, so they may not be available for reflective access.

Attributes in .NET Vs. Annotations in Java

Microsoft's .NET CLR supports a feature called attributes, which is similar to annotations in Java. Let us see the similarities and differences between attributes and annotations.

.NET Attributes	Java Annotations
Attributes are classes that should extend the System.Attribute class.	Annotations are interfaces that automatically extend the java.lang.annotation.Annotation interface.
Types of an attribute parameter must be primitive types, object, System.Type, enum types, or arrays of the preceding types.	Method return types are restricted to primitive types, String, Class, enum types, annotation types, and arrays of the preceding types.
Attribute parameters can be named or positional. Named ("name=value") parameters can be in any order.	Supports only named ("name=value") parameters and can be in any order. Single member annotations follow the naming convention for the member type as value; can use shorthand.
Attributes can be applied to assembly, class, constructor, delegate, enum, event, field, interface, method, module, parameter, property, return value, and struct.	Annotations can be applied to annotation, class, constructor, enum, field (includes enum constants), interface, local variable, method, parameter, and package.
A declaration can have multiple attributes for the same attribute type.	A declaration cannot have multiple annotations for the same annotation type.
Attributes are always stored in the assembly and available at runtime.	Annotations marked with @Target(RetentionPolicy. SOURCE) meta-annotation (referred to as source-level annotations) are not stored in the class files and will not be available at runtime.
All attributes can be accessed at runtime using reflective APIs.	Annotations marked with @Target(RetentionPolicy.RUNTIME) meta-annotation (referred to as runtime annotations) can be accessed at runtime through reflective APIs.
System.CodeDOM APIs for working with attributes in source files.	Doclet API provides limited support for working with annotations at source files.
.NET provides standard attributes for security, transactions, language interoperability, COM integration, COM+ hosting, marshalling, serialization, components and controls, assemblies and packaging, threading, XML and web services.	Several new JSRs are in progress to define standard annotations for web services and others.
Context attributes provide an interception mechanism that can preprocess and postprocess class instantiation and method calls.	N/A

For developers familiar with .NET attributes, the JDK 1.5 implementation of annotations may appear to be a limitation, but it is not. Java annotations can be used to define design-time information, such as documentation or instructions to the compiler; runtime information, such as tagging a method as a unit test; or behavioral characteristics, such as whether a member is participating in a transaction or not, similar to how attributes are used in .NET applications. Although there is no standard interception mechanism like .NET's context attributes in Java yet, AOP frameworks such as AspectJ and JBossAOP provide call interception mechanisms, and these frameworks may be reimplemented to take advantage of annotations.

Annotations in the Pre-JDK 1.5 World

In older versions of Java, javadoc custom tags are used as annotations. Many popular open source design-time tools, such as XDoclet, EJBGen, and others, generate code based on javadoc tags form the source files. Open source projects like Jakarta Commons Attributes and Attrib4j use javadoc tags to associate custom metadata and make it available at runtime. In both Commons Attributes and Attrib4j, attributes are classes more like .NET attributes, whereas JDK 1.5 treats them as interfaces. For those who can't start using JDK 1.5 as soon as the production release of Tiger is available, it's worthwhile to take a look at Retroweaver. Retroweaver transforms JDK 1.5 classes into classes that can run on older VMs; this way, you can start using JDK 1.5 features with an older version of the JRE.

Conclusion

Every new release of Java has introduced new features, but few warrant a new way of thinking to realize their full potential. Using annotations effectively to simplify programming in Java requires a shift in our thought processes. Even though we use declarative programming languages such as SQL and XSLT most frequently, it may take some time for us to understand how to use declarative and imperative programming together.

Here are a few things you could do with annotations to simplify or empower your programming:

1. Develop code generators using annotations.
2. Develop a new unit-testing framework using annotations, such as NUnit.
3. Think about ways to extend the compiler using custom annotation handlers.
4. Think about annotation's role in defining AOP extensions to Java.

Once JSRs like JSR-181: Web Services Metadata for the Java Platform and others are implemented, we will be able to appreciate the productivity gained by using annotations.

In the near future, we will see a number of existing frameworks being reimplemented using annotations, generics and other new features available in JDK 1.5, codenamed Tiger. So get ready to meet the Tiger.

(http://www.onjava.com/lpt/a/4768)

J2SE 5.0 in a Nutshell by Calvin Austin

Java 2 Platform Standard Edition (J2SE) 5.0 ("Tiger") is the next major revision to the Java platform and language; it is currently slated to contain 15 component JSRs with nearly 100 other significant updates developed through the Java Community Process (JCP).

NOTE: The external version number of this release is 5.0 and its internal version number is 1.5.0, as described at J2SE Naming and Versioning.

With so many exciting changes in this release, you may be wondering where you should start. As in previous releases, the comprehensive list of all changes is available in the Release notes guide. This article, from the J2SE team, will take you through the major changes so that you have a grasp of what J2SE 5.0 has to offer, before diving into the API docs.

The J2SE 5.0 release is focused along certain key themes:

• Ease of Development
• Scalability and Performance
• Monitoring and Manageability
• Desktop Client

There are a small number of features that are just as important but didn't neatly fit in with the themes; they are listed at the end:

• Miscellaneous Features

Ease of Development

You may have already seen reports about some of the new Java Language changes that comprise the Ease of Development theme. The changes include generic types, metadata, autoboxing, an enhanced for loop, enumerated types, static import, C style formatted input/output, variable arguments, concurrency utilities, and simpler RMI interface generation.

JSR-201 contains four of these language changes; enhanced for loop, enumerated types, static import and autoboxing; JSR-175 specifies the new metadata functionality, while JSR-14 details generic types.

The new default language specification implemented by the javac compiler is version 5.0, also known as 1.5, so you do not need to supply the option -source 1.5 (as required in beta1).

Metadata

The metadata feature in J2SE 5.0 provides the ability to associate additional data alongside Java classes, interfaces, methods, and fields. This additional data, or annotation, can be read by the javac compiler or other tools, and depending on configuration can also be stored in the class file and can be discovered at runtime using the Java reflection API.

One of the primary reasons for adding metadata to the Java platform is to enable development and runtime tools to have a common infrastructure and so reduce the effort required for programming and deployment. A tool could use the metadata information to generate additional source code, or to provide additional information when debugging.

In beta2 we are pleased to announce the availability of an annotation processing tool called apt. Apt includes a set of new reflective APIs and supporting infrastructure to process program annotations. The apt reflective APIs provide a build-time, source-based, read-only view of program structure which cleanly models the Java programming language's type system. First, apt runs annotation processors that can produce new source code and other files. Next, apt can cause compilation of both original and generated source files, easing development. For more information on apt refer to the apt guide.

In the following example code you can additionally create an AnnotationFactory processor for apt to generate code or documentation when finding the debug annotation tag.

import java.lang.annotation.*; import java.lang.reflect.*; @Retention(java.lang.annotation.RetentionPolicy.RUNTIME) @interface debug { boolean devbuild() default false; int counter(); } public class MetaTest { final boolean production=true; @debug(devbuild=production,counter=1) public void testMethod() { } public static void main(String[] args) { MetaTest mt = new MetaTest(); try { Annotation[] a = mt.getClass().getMethod("testMethod").getAnnotations(); for (int i=0; i System.out.println("a["+i+"]="+a[i]+" "); } } catch(NoSuchMethodException e) { System.out.println(e); } } }

With a metadata processing tool, many repetitive coding steps could be reduced to a concise metadata tag. For example, the remote interface required when accessing a JAX-RPC service implementation could be implemented as follows:

Before

public interface PingIF extends Remote { public void ping() throws RemoteException; } public class Ping implements PingIF { public void ping() { } }

After

public class Ping { public @remote void ping() { } }

Generic Types

Generic types have been widely anticipated by the Java Community and are now part of J2SE 5.0. One of the first places to see generic types in action is the Collections API. The Collections API provides common functionality like LinkedLists, ArrayLists and HashMaps that can be used by more than one Java type. The next example uses the 1.4.2 libraries and the default javac compile mode.

ArrayList list = new ArrayList(); list.add(0, new Integer(42)); int total = ((Integer)list.get(0)).intValue();

The cast to Integer on the last line is an example of the typecasting issues that generic types aim to prevent. The issue is that the 1.4.2 Collection API uses the Object class to store the Collection objects, which means that it cannot pick up type mismatches at compile time. The first notification of a problem is a ClassCastException at runtime.

The same example with the generified Collections library is written as follows:

ArrayList list = new ArrayList(); list.add(0, new Integer(42)); int total = list.get(0).intValue();

The user of a generified API has to simply declare the type used at compile type using the <> notation. No casts are needed and in this example trying to add a String object to an Integer typed collection would be caught at compile time.

Generic types therefore enable an API designer to provide common functionality that can be used with multiple data types and which also can be checked for type safety at compile time.

Designing your own Generic APIs is a little more complex that simply using them. To get started look at the java.util.Collection source and also the API guide.

Autoboxing and Auto-Unboxing of Primitive Types

Converting between primitive types, like int, boolean, and their equivalent Object-based counterparts like Integer and Boolean, can require unnecessary amounts of extra coding, especially if the conversion is only needed for a method call to the Collections API, for example.

The autoboxing and auto-unboxing of Java primitives produces code that is more concise and easier to follow. In the next example an int is being stored and then retrieved from an ArrayList. The 5.0 version leaves the conversion required to transition to an Integer and back to the compiler.

Before

ArrayList list = new ArrayList(); list.add(0, new Integer(42)); int total = (list.get(0)).intValue();

After

ArrayList list = new ArrayList(); list.add(0, 42); int total = list.get(0);

Enhanced for Loop

The Iterator class is used heavily by the Collections API. It provides the mechanism to navigate sequentially through a Collection. The new enhanced for loop can replace the iterator when simply traversing through a Collection as follows. The compiler generates the looping code necessary and with generic types no additional casting is required.

Before

ArrayList list = new ArrayList(); for (Iterator i = list.iterator(); i.hasNext();) { Integer value=(Integer)i.next(); }

After

ArrayList list = new ArrayList(); for (Integer i : list) { ... }

Enumerated Types

This type provides enumerated type when compared to using static final constants. If you have previously used the identifier enum in your own application, you will need to adjust the source when compiling with javac -source 1.5 (or its synonym -source 5).

public enum StopLight { red, amber, green };

Static Import

The static import feature, implemented as "import static", enables you to refer to static constants from a class without needing to inherit from it. Instead of BorderLayout.CENTER each time we add a component, we can simply refer to CENTER.

import static java.awt.BorderLayout.*; getContentPane().add(new JPanel(), CENTER);

Formatted Output

Developers now have the option of using printf-type functionality to generate formatted output. This will help migrate legacy C applications, as the same text layout can be preserved with little or no change.

Most of the common C printf formatters are available, and in addition some Java classes like Date and BigInteger also have formatting rules. See the java.util.Formatter class for more information. Although the standard UNIX newline '\n' character is accepted, for cross-platform support of newlines the Java %n is recommended.

System.out.printf("name count%n"); System.out.printf("%s %5d%n", user,total);

Formatted Input

The scanner API provides basic input functionality for reading data from the system console or any data stream. The following example reads a String from standard input and expects a following int value.

The Scanner methods like next and nextInt will block if no data is available. If you need to process more complex input, then there are also pattern-matching algorithms, available from the java.util.Formatter class.

Scanner s= new Scanner(System.in); String param= s.next(); int value=s.nextInt(); s.close();

Varargs

The varargs functionality allows multiple arguments to be passed as parameters to methods. It requires the simple ... notation for the method that accepts the argument list and is used to implement the flexible number of arguments required for printf.

void argtest(Object ... args) { for (int i=0;i } } argtest("test", "data");

Concurrency Utilities

The concurrency utility library, led by Doug Lea in JSR-166, is a special release of the popular concurrency package into the J2SE 5.0 platform. It provides powerful, high-level thread constructs, including executors, which are a thread task framework, thread safe queues, Timers, locks (including atomic ones), and other synchronization primitives.

One such lock is the well known semaphore. A semaphore can be used in the same way that wait is used now, to restrict access to a block of code. Semaphores are more flexible and can also allow a number of concurrent threads access, as well as allow you to test a lock before acquiring it. The following example uses just one semaphore, also known as a binary semaphore. See the java.util.concurrent package for more information.

final private Semaphore s= new Semaphore(1, true); s.acquireUninterruptibly(); //for non-blocking version use s.acquire() try { balance=balance+10; //protected value } finally { s.release(); //return semaphore token }

rmic -- The RMI Compiler

You no longer need to use rmic, the rmi compiler tool, to generate most remote interface stubs. The introduction of dynamic proxies means that the information normally provided by the stubs can be discovered at runtime. See the RMI release notes for more information.

Scalability and Performance

The 5.0 release promises improvements in scalability and performance, with a new emphasis on startup time and memory footprint, to make it easier to deploy applications running at top speed.

One of the more significant updates is the introduction of class data sharing in the HotSpot JVM. This technology not only shares read-only data between multiple running JVMs, but also improves startup time, as core JVM classes are pre-packed.

Performance ergonomics are a new feature in J2SE 5.0. This means that if you have been using specialized JVM runtime options in previous releases, it may be worth re-validating your performance with no or minimal options.

Monitoring and Manageability

Monitoring and Manageability is a key component of RAS (Reliability, Availability, Serviceability) in the Java platform.

The J2SE 5.0 release provides comprehensive monitoring and management support: instrumentation to observe the Java virtual machine, Java Management Extensions (JMX) framework, and remote access protocols. All this is ready to be used out-of-the-box. (See the Management and Monitoring release notes for more details.)

The JVM Monitoring & Management API specifies a comprehensive set of instrumentation of JVM internals to allow a running JVM to monitored. This information is accessed through JMX (JSR-003) MBeans and can accessed locally within the Java address space or remotely using the JMX remote interface (JSR-160) and through industry-standard SNMP tools.

One of the most useful features is a low memory detector. JMX MBeans can notify registered listeners when the threshold is crossed, see javax.management and java.lang.management for details.

J2SE 5.0 provides an easy way to enable out-of-the-box remote management of JVM and an application (see Out-of-the-Box for details). For example, to start an application to be monitorable by jconsole in the same local machine, use the following system property:

java -Dcom.sun.management.jmxremote -jar Java2Demo.jar

and to monitor it remotely through JMX without authentication:

java -Dcom.sun.management.jmxremote.port=5001 -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false -jar Java2Demo.jar

For an idea of how easy the new API is to use, the following reports the detailed usage of the memory heaps in the HotSpot JVM.

import java.lang.management.*; import java.util.*; public class MemTest { public static void main(String args[]) { List pools = ManagementFactory.getMemoryPoolMXBeans(); for (MemoryPoolMXBean p: pools) { System.out.println("Memory type="+p.getType()+" Memory usage="+p.getUsage()); } } }

New JVM Profiling API (JSR-163)

The release also contains a more powerful native profiling API called JVMTI. This API has been specified through JSR-163 and was motivated by the need for an improved profiling interface. However, JVMTI is intended to cover the full range of native in-process tools access, which in addition to profiling, includes monitoring, debugging and a potentially wide variety of other code analysis tools.

The implementation includes a mechanism for bytecode instrumentation, Java Programming Language Instrumentation Services (JPLIS). This enables analysis tools to add additional profiling only where it is needed. The advantage of this technique is that it allows more focused analysis and limits the interference of the profiling tools on the running JVM. The instrumentation can even be dynamically generated at runtime, as well as at class loading time, and pre-processed as class files.

The following example creates an instrumentation hook that can load a modified version of the class file from disk. To run this test, start the JRE with java -javaagent:myBCI BCITest

//File myBCI.java import java.lang.instrument.Instrumentation; public class myBCI { private static Instrumentation instCopy; public static void premain(String options, Instrumentation inst) { instCopy = inst; } public static Instrumentation getInstrumentation() { return instCopy; } } //File BCITest.java import java.nio.*; import java.io.*; import java.nio.channels.*; import java.lang.instrument.*; public class BCITest { public static void main (String[] args) { try { OriginalClass mc = new OriginalClass(); mc.message(); FileChannel fc=new FileInputStream( new File("modified"+File.separator+"OriginalClass.class")).getChannel(); ByteBuffer buf = fc.map(FileChannel.MapMode.READ_ONLY, 0, (int)fc.size()); byte[] classBuffer = new byte[buf.capacity()]; buf.get(classBuffer, 0, classBuffer.length); myBCI.getInstrumentation().redefineClasses( new ClassDefinition[] { new ClassDefinition(mc.getClass(), classBuffer)}); mc.message(); }catch (Exception e){} } } //OriginalClass.java //Compile in current directory //Copy source to modified directory,change message and recompile public class OriginalClass { public void message() { System.out.println("OriginalClass"); } }

Improved Diagnostic Ability

Generating Stack traces has been awkward if no console window has been available. Two new APIs, getStackTrace and Thread.getAllStackTraces provide this information programmatically.

StackTraceElement e[]=Thread.currentThread().getStackTrace(); for (int i=0; i System.out.println(e[i]); } System.out.println("\n"+Thread.getAllStackTraces());

The HotSpot JVM includes a fatal error handler that can run a user-supplied script or program if the JVM aborts. A debug tool can also connect to a hung JVM or core file using the HotSpot JVM serviceability agent connector.

-XX:OnError="command" -XX:OnError="pmap %p" -XX:OnError="gdb %p" optional %p used as process id

Desktop Client

The Java Desktop client remains a key component of the Java platform and as such has been the focus of many improvements in J2SE 5.0.

This Beta release contains some of the early improvements in startup time and memory footprint. Not only is the release faster, but the Swing toolkit enjoys a fresh new theme called Ocean. And by building on the updates in J2SE 1.4.2, there are further improvements in the GTK skinnable Look and Feel and the Windows XP Look and Feel.

Linux and Solaris users, and new in beta2, Windows users, who have the latest OpenGL drivers and select graphic cards can get native hardware acceleration from Java2D using the following runtime property:

java -Dsun.java2d.opengl=true -jar Java2D.jar

The Linux release also has the fast X11 toolkit, called XAWT, enabled by default. If you need to compare against the motif version you can use the following system property:

java -Dawt.toolkit=sun.awt.motif.MToolkit -jar Notepad.jar

(the X11 toolkit is called sun.awt.X11.XToolkit)

The X11 Toolkit also uses the XDnD protocol so you can drag-and-drop simple components between Java and other applications like StarOffice or Mozilla.

Miscellaneous Features

Core XML Support

J2SE 5.0 introduces several revisions to the core XML platform, including XML 1.1 with Namespaces, XML Schema, SAX 2.0.2, DOM Level 3 Support and XSLT with a fast XLSTC compiler.

In addition to the core XML support, future versions of the Java Web Services Developer Pack will deliver the latest web services standards: JAX-RPC & SAAJ (WSDL/SOAP), JAXB, XML Encryption, and Digital Signature and JAXR for registries.

Supplementary Character Support

32-bit supplementary character support has been carefully added to the platform as part of the transition to Unicode 4.0 support. Supplementary characters are encoded as a special pair of UTF16 values to generate a different character, or codepoint. A surrogate pair is a combination of a high UTF16 value and a following low UTF16 value. The high and low values are from a special range of UTF16 values.

In general, when using a String or sequence of characters, the core API libraries will transparently handle the new supplementary characters for you. However, as the Java "char" still remains at 16 bits, the very few methods that used char as an argument now have complementary methods that can accept an int value which can represent the new larger values. The Character class in particular has additional methods to retrieve the current character and the following character in order to retrieve the supplementary codepoint value as below:

String u="\uD840\uDC08"; System.out.println(u+"+ "+u.length()); System.out.println(Character.isHighSurrogate(u.charAt(0))); System.out.println((int)u.charAt(1)); System.out.println((int)u.codePointAt(0));

See the Unicode section in Character for more details.

JDBC RowSets

There are five new JDBC RowSet class implementations in this release. Two of the most valuable ones are CachedRowSet and WebRowSet. RowSet objects, unlike ResultSet objects, can operate without always being connected to a database or other data source. Without the expensive overhead of maintaining a connection to a data source, they are much more lightweight than a ResultSet object. The CachedRowSet contains an in-memory collection of rows retrieved from the database that can, if needed, be synchronized at a later point in time. The WebRowSet implementation, in addition, can write and read the RowSet in XML format.

The following code fragment shows how easy it is to create and use a WebRowSet object.

Class.forName("org.postgresql.Driver"); WebRowSetImpl wrs = new WebRowSetImpl(); wrs.setCommand("SELECT COF_NAME,TOTAL FROM COFFEES"); wrs.setUsername("postgres"); wrs.setPassword(""); wrs.setUrl("jdbc:postgresql:test"); wrs.execute(); // executes command and populates webset all coffees wrs.absolute(1); // moves cursor to the first row of wrs wrs.updateInt(2, 10); // reset total field to 10 wrs.updateRow(); // finishes edits to this row wrs.acceptChanges(); // writes new total to the data source wrs.writeXml(System.out); // also exports rowset in XML format wrs.close();

References

New Language Features for Ease of Development in the Java 2 Platform Standard Edition 5.0: http://java.sun.com/features/2003/05/bloch_qa.html

Tiger Component JSRs

003 Java Management Extensions (JMX) Specification http://jcp.org/en/jsr/detail?id=3

013 Decimal Arithmetic Enhancement http://jcp.org/en/jsr/detail?id=13

014 Add Generic Types To The Java Programming Language http://jcp.org/en/jsr/detail?id=14

028 Java SASL Specification http://jcp.org/en/jsr/detail?id=28

114 JDBC Rowset Implementations http://jcp.org/en/jsr/detail?id=114

133 Java Memory Model and Thread Specification Revision http://jcp.org/en/jsr/detail?id=133

160 Java Management Extensions (JMX) Remote API 1.0 http://jcp.org/en/jsr/detail?id=160

163 Java Platform Profiling Architecture http://jcp.org/en/jsr/detail?id=163

166 Concurrency Utilities http://jcp.org/en/jsr/detail?id=166

174 Monitoring and Management Specification for the Java Virtual Machine http://jcp.org/en/jsr/detail?id=174

175 A Metadata Facility for the Java Programming Language http://jcp.org/en/jsr/detail?id=175

200 Network Transfer Format for Java Archives http://jcp.org/en/jsr/detail?id=200

201 Extending the Java Programming Language with Enumerations, Autoboxing, Enhanced for Loops and Static Import http://jcp.org/en/jsr/detail?id=201

204 Unicode Supplementary Character Support http://jcp.org/en/jsr/detail?id=204

206 Java API for XML Processing (JAXP) 1.3 http://jcp.org/en/jsr/detail?id=206

Learn to Use the New Annotation Feature of Java 5.0 by Javid Jamae

The new Java 2 Platform Standard Edition 5.0 (the developer version number is 1.5 and the code name is "Tiger") provides many new features, among them is the ability to annotate Java program elements and to create custom annotation types. Development and deployment tools can then read annotated data (also known as metadata) and process it in some fashion.
Previous versions of Java provided a limited and ad-hoc mechanism for annotating code through JavaDoc comments and keyword modifiers. Tools such as XDoclet provide a slightly more sophisticated, yet non-standard annotation syntax, which piggybacks on top of JavaDoc. But now, with Java 1.5, annotations are a typed part of the Java language and allow for both runtime and compile-time processing of annotation data.

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.

Older versions of Java have rough-and-ready annotation functionality. A good example is the @deprecated JavaDoc tag. The @deprecated tag is used for more than sheer documentation purposes. This tag has no effect on the code it describes, but causes the compiler to produce warnings if any other code references the tagged element. JavaDoc does not seem to be the proper place for this type of metadata, but there was no other annotation facility in previous versions of Java. With Java 1.5, finally, annotations are a typed part of the language and the version even comes with some with pre-built annotations, one of which can be used to mark a class as deprecated (I'll cover this later).

The code below shows how you can declare a method that uses an annotation. It is one of Java 1.5's built-in annotation types:


class Child extends Parent {
@Overrides
public void doWork() {
//do something
}
}

In the code above, note that the annotation starts with an "at" (@) sign. This annotation takes no parameters and is merely used to mark a method for some purpose. It is therefore called a marker annotation. There are also normal annotations and single member annotations (more on these later).
Annotations types are blueprints for annotations, similar to how a class is the blueprint for an object. You can create your own custom annotations by defining annotation types.

The code below shows the declaration of a normal annotation type:


public @interface MyAnnotationType {
int someValue();
String someOtherValue();
}

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.
Author's Note:
For an overview of its new features and a brief guide to downloading and installing Java 5.0, refer to Laurence Moroney's article, "Tiger Stripes: Get Ready to Purr over J2SE 5.0."
The annotations specification was laid out in JSR-175; download it from http://www.jcp.org/en/jsr/detail?id=175.
C# has a similar mechanism for doing annotations called custom attributes. To learn more about C# custom attributes, refer to Pierre Nallet's article, "Get Personal with C# Custom Attributes."



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. Of course, a compiler has to know how to interpret annotation data that is meant to produce compile-time warnings, so again, annotations that do things at compile time will likely be used frequently, but rarely written by average developers.

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. Then at runtime, you could analyze the methods that you're calling and print a particular log message before you begin executing code for that method. One way to achieve this would be through the use of the updated Java 1.5 reflection API. The reflection API now provides access to runtime-accessible annotation data.

< 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.
Category Example
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. @MyNormalAnnotation(mem1="val1", mem2="val2") public void someMethod() { ... }
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. @MySingleMemberAnnotation("a single value") public class SomeClass { ... }
Marker Annotations—These annotations take no parameters. They are used to mark a Java element to be processed in a particular way. @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.

This code below shows an annotated class, constructor, field, and method.


@ClassLevelAnnotation(arg1="val1", arg2={"arg2.val1","arg2.val2"})
public class AnnotationExample {

@FieldLevelAnnotation()
public String field;

@CtorLevelAnnotation()
public AnnotationsTest() {
// code
}

@MethodLevelAnnotationA("val")
@MethodLevelAnnotationB(arg1="val1",arg2="val2")
public void someMethod(String string) {
// code
}
}

As you can see in the ClassLevelAnnotation, annotations may also take arrays of values. When creating an annotation that requires an array you must surround the array of parameters with brackets ( { … } ) and you must comma-separate each array parameter.
Annotation types may define default values for some members. Every member-value pair that does not have a default value must be supplied when you create an annotation.

The annotation-type declaration below uses meta-annotations, which provide information on how the annotation type can be used:


@Retention(RUNTIME)
@Target(METHOD)
public @interface MyAnnotationType {
String value;
}

This code shows how to use meta-annotations when declaring your own annotation type. I will cover the specifics on declaring annotation types and meta-annotation types later, but for now, just know that you can use meta-annotations to annotate other 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. This file should contain only a package declaration, preceded by any annotations that should apply to the package. This java file must not contain an actual class definition (which would be illegal anyways, because package-info is not a legal identifier).







Built-in Annotations
Java 1.5 comes packaged with seven pre-built annotations. I will describe these built-in annotations in this section, borrowing much of the wording directly from the Java 5 documentation.
java.lang.Override


@Target(value=METHOD)
@Retention(value=SOURCE)
public @interface Override

This annotation is used to indicate that a method declaration is intended to override a method declaration in a superclass. If a method is annotated with this annotation type but does not override a superclass method, compilers are required to generate an error message.
This annotation is useful in avoiding the situation where you think you are overriding a method, but you misspell the method name in the child class. The code in the method you are trying to override in the parent class will be used because the name is misspelled in the child class. This is usually a difficult bug to track down because no compiler or runtime error is thrown. But marking a method with the Override annotation would help you realize this type of problem at compile time rather than through arduous debugging.

java.lang.Deprecated


@Documented
@Retention(value=RUNTIME)
public @interface Deprecated

A program element annotated @Deprecated is one that programmers are discouraged from using, typically because it is dangerous or because a better alternative exists. Using this annotation, compilers warn when a deprecated program element is used or overridden in non-deprecated code.
java.lang.SuppressWarning


@Target(value={TYPE,FIELD,METHOD,PARAMETER,CONSTRUCTOR,LOCAL_VARIABLE})
@Retention(value=SOURCE)
public @interface SuppressWarnings

This annotation indicates that the named compiler warnings should be suppressed in the annotated element (and in all program elements contained in the annotated element). Note that the set of warnings suppressed in a given element is a superset of the warnings suppressed in all containing elements. For example, if you annotate a class to suppress one warning and annotate a method to suppress another, both warnings will be suppressed in the method.
java.lang.annotation.Documented


@Documented
@Retention(value=RUNTIME)
@Target(value=ANNOTATION_TYPE)
public @interface Documented

Annotations with a type declaration are to be documented by javadoc and similar tools by default. It should be used to annotate the declarations of types whose annotations affect the use of annotated elements by their clients. If a type declaration is annotated with @Documented, its annotations become part of the public API of the annotated elements.
java.lang.annotation.Inherited


@Documented
@Retention(value=RUNTIME)
@Target(value=ANNOTATION_TYPE)
public @interface Inherited

This indicates that an annotation type is automatically inherited. If an inherited meta-annotation is present on an annotation type declaration, and the user queries the annotation type on a class declaration, and the class declaration has no annotation for this type, then the class's superclass will automatically be queried for the annotation type. This process will be repeated until an annotation for this type is found or the top of the class hierarchy (Object) is reached. If no superclass has an annotation for this type, then the query will indicate that the class in question has no such annotation.
Note that this meta-annotation type has no effect if the annotated type is used for anything other than a class. Also, this meta-annotation causes annotations to be inherited only from superclasses; annotations on implemented interfaces have no effect.

java.lang.annotation.Retention


@Documented
@Retention(value=RUNTIME)
@Target(value=ANNOTATION_TYPE)
public @interface Retention

Retention takes a single value of the enumerated type RetentionPolicy, which informs the compiler of its policy for retaining annotations in memory. There are three RetentionPolicy enumerated values:
SOURCE—Annotations are to be discarded by the compiler.
CLASS—Annotations are to be recorded in the class file by the compiler but need not be retained by the VM at runtime. This is the default behavior.
RUNTIME—Annotations are to be recorded in the class file by the compiler and retained by the VM at runtime, so they may be read reflectively.
If no Retention annotation is present on an annotation type declaration, the retention policy defaults to RetentionPolicy.CLASS. By default, the annotation data is not available in the JVM in order to reduce overhead.

java.lang.annotation.Target


@Documented
@Retention(value=RUNTIME)
@Target(value=ANNOTATION_TYPE)
public @interface Target

@Target indicates the kinds of program element to which an annotation type is applicable. It takes a single enumerated parameter of type ElementType. The enumerated values are as follows:
TYPE (class, interface or enum declaration)
FIELD (includes enum constants)
METHOD
PARAMETER
CONSTRUCTOR
LOCAL_VARIABLE
ANNOTATION_TYPE
PACKAGE
If a @Target meta-annotation is not present on an annotation type declaration, the declared type may be used on any program element. If such a meta-annotation is present, the compiler will enforce the specified usage restriction.






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]";

}

As you can see, annotation types are declared similarly to interfaces. In fact they use the interface keyword prepended with an @ sign. Just like an interface, annotations have method declarations, each of which defines a member of the annotation. These methods may not have any parameters. As shown in the example, default values are specified after the parenthesis on a method declaration.
At first, it seems a little odd to specify the members of an annotation using method syntax, because when you declare a Java element and annotate it (e.g. when you annotate a class), you may pass values into the annotation. But you are not the consumer of the annotation at this point; you are merely constructing an instance of the annotation. Think of it as calling a constructor on an implicit Java class that you didn't have to write.

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. After you've created the annotation, annotation consumers may call the methods on the annotation interface in order to get the annotation values. The return types of the methods represent the type of data that a consumer of the annotation would get back.

There are a few restrictions when defining annotation types.

Annotations cannot extend other annotations, except for the java.lang.annotation.Annotation marker interface they inherently extend.
Method return types must be: primitive types, String, Class, enum types, annotation types, or arrays of the preceding types.
Annotations can't have a throws clause.
Self reference is not allowed (e.g. AnnotationA contains a member of type AnnotationA), nor circular reference (e.g. AnnotationA contains a member of type AnnotationB and vice versa).
Single member annotations must define only a single method called value in the annotation type. So long as you follow this construct, you can use the condensed single-member syntax when creating an annotation of this type.

A single member annotation can be defined as follows:

public @interface Copyright {
String value();
}

You can also create meta-annotations, as we have already seen. A meta-annotation is any annotation that can be used to annotate other annotations. For example, all of the build-in annotations utilize meta-annotations and some of them are meta-annotations themselves.
Here is the declaration for the @ Inherited meta-annotation type:


@Documented
@Retention(value=RUNTIME)
@Target(value=ANNOTATION_TYPE)
public @interface Inherited

The @Inherited annotation uses three other meta-annotations and is a meta-annotation itself. What makes it a meta-annotation? Any annotation whose @Target annotation member includes ANNOTATION_TYPE can be used as a meta-annotation.
Reading Annotations
Now that you know how to declare your own annotation types and annotate Java elements, you need to know how to access the annotation data you specified. Annotation consumers are software that read annotation data and do something useful with it. Annotation consumers fall into three groups:

General tools are programs that can analyze source code and do something useful with it. For example compilers and documentation generators are both considered general tools. General tools do not load annotated classes or annotation interfaces into the virtual machine.

Specific tools are also programs that can analyze source code without loading annotated classes, but they need to load annotation interfaces into the virtual machine. An example of this is a Stub generator.

Introspectors are programs that can query their own annotations (the ones with a RUNTIME retention policy). Introspectors will load both annotated classes and annotation interfaces into the virtual machine.

Listing 1 is an example of how you can access your code during runtime using the reflection API.

As I mentioned previously, I think that most developers will be users of annotations, but few will have to write code that consumes annotations.

If you are a general or specific tools developer, you may want to look into a few APIs that will help you read annotations from source files in order to use them for some type of static preprocessing. The new Doclet API (com.sun.javadoc) has support for reading annotations. It doesn’t currently support all of the features of annotations, but it may suffice as a library for writing your tool. Another thing to keep an eye on is the newly submitted JSR-269 (Pluggable Annotation Processing API), which will provide a generic API that allows developers to read annotation data using general and specific tools.

If you are developing an introspector, you can use the new reflection API to access your annotations, though I would suggest looking into AOP as a means to interface with annotated methods. I think there is a lot of room for exploration here. The combinations of aspects and annotations can yield a very powerful introspection tool.



Javid Jamae consults for Valtech, a global consulting group specializing in delivering advanced technology solutions. Valtech endeavors to help its customers through its global delivery model to create and/or maintain an affordable competitive advantage.

(http://www.devx.com/Java/Article/27235/1954?pf=true)