Before we start with the actual example, lets have a look at the few concepts we should be aware of.

Producer-Consumer Problem

Wikipedia here says that:
The consumer producer problem (also known as the bounded-buffer problem) is a classical example of a multi-process synchronization problem. The problem describes two processes, the producer and the consumer, who share a common, fixed-size buffer used as a queue. The producer’s job is to generate a piece of data, put it into the buffer and start again. At the same time, the consumer is consuming the data (i.e., removing it from the buffer) one piece at a time. The problem is to make sure that the producer won’t try to add data into the buffer if it’s full and that the consumer won’t try to remove data from an empty buffer.

The solution for the producer is to either go to sleep or discard data if the buffer is full. The next time the consumer removes an item from the buffer, it notifies the producer, who starts to fill the buffer again. In the same way, the consumer can go to sleep if it finds the buffer to be empty. The next time the producer puts data into the buffer, it wakes up the sleeping consumer. The solution can be reached by means of inter-process communication, typically using semaphores. An inadequate solution could result in a deadlock where both processes are waiting to be awakened. The problem can also be generalized to have multiple producers and consumers.

There are numerous ways to solve a Producer-Consumer problem and in this post I will show one simple way to solve this problem by using the Data Structures and other constructs provided in the JDK. Java 5 introduced a new set of concurrency related APIs in its java.util.concurrent package. As I said here, not many of the developers are aware of these APIs and very few of the make use of it in their code.

There were quite a few new Collection classes which got introduced in Java 5 and one of them is the BlockingQueue.

BlockingQueue in Java

The JavaDoc says:
BlockingQueue is “A Queue that additionally supports operations that wait for the queue to become non-empty when retrieving an element, and wait for space to become available in the queue when storing an element.” There are multiple methods which are supported to retrieve and add elements to the queue wherein one pair throws an exceptions, one of them waits for some fixed time and one pair which blocks until the queue is full/empty. The methods which blocks the thread are the put(e) and take.

In a typical producer-consumer problem we would want the consumer thread to be blocked until there is something in the queue to be consumed and the producer thread to be blocked until there is some free space in the queue to add some element. With the use of normal collection classes it because quite a bit of work in implementing inter thread communication by waiting and notifying other threads about the status of the queue. The put(e) and take() methods of the BlockingQueue class are the ones which make it very easy to solve producer-consumer like problems.

Lets take a scenario where the producer thread would watch for the files being modified in some directory and add those files to the queue and the consumer thread would print the contents of those files on to the console.

Producer thread

If you are not familiar with implementing the WatchService in Java, you must first read this to get an idea of how it works.

class FileProducer implements Runnable{

  BlockingQueue<Path> filesList;
  Path rootPath;

  public FileProducer(BlockingQueue<Path> filesList, 
                      Path rootPath){
    this.filesList = filesList;
    this.rootPath = rootPath;
  }

  @Override
  public void run() {
    try {
      WatchService service = 
          FileSystems.getDefault().newWatchService();

      rootPath.register(service,
              StandardWatchEventKinds.ENTRY_MODIFY);

      while(true){
        WatchKey key = service.take();

        for (WatchEvent event : key.pollEvents()){

          Path relativePath = (Path)event.context();

          Path absolutePath =
                    Paths.get(rootPath.toString(),
                            relativePath.toString());

          filesList.put(absolutePath);

        }

        //reset is invoked to put the key back to ready
        boolean valid = key.reset();

        //If the key is invalid, just exit.
        if ( !valid){
          break;
        }
      }

    } catch (IOException e) {

      e.printStackTrace();

    } catch (InterruptedException e) {

      e.printStackTrace();

      Thread.currentThread().interrupt();
    }

  }
}

The producer thread above watches a certain directory for file modifications and adds the absolute path of the file into the BlockingQueue collection passed to the producer thread via its constructor.

Consumer Thread

The consumer thread would invoke take() on the BlockingQueue instance and then use the Files API to read the contents. As take() is a blocking call, if the filesList collection is empty then it would just block and wait for the data to be available in the filesList collection.

class FileConsumer implements Runnable{

  BlockingQueue<Path> filesList;
  Path rootPath;

  public FileConsumer(BlockingQueue<Path> filesList, 
                      Path rootPath){
    this.filesList = filesList;
    this.rootPath = rootPath;
  }

  @Override
  public void run(){
    try {
      while(true){

        Path fileToRead = filesList.take();

        List<String> linesInFile = 
            Files.readAllLines(fileToRead, 
                               Charset.defaultCharset());

        System.out.println("reading file: "+fileToRead);

        for ( String line : linesInFile){
          System.out.println(line);
        }

      }
    } catch (InterruptedException e) {

      e.printStackTrace();

      Thread.currentThread().interrupt();
    } catch (IOException e) {

      e.printStackTrace();

    }

  }
}

Note: If you are writing to a file using Vim or some other editors which creates temporary files then you have to make sure you exclude such files being added to the queue.

Invoking the Producer and consumer

public class ProducerConsumerSample {

  public static void main(String[] args) {
 
    BlockingQueue<Path> filesList = 
        new LinkedBlockingQueue<>(10);
 
    Path rootPath = Paths.get("/tmp/nio");
    
    Thread producerThread = 
        new Thread(new FileProducer(filesList, rootPath));
    Thread consumerThread = 
        new Thread(new FileConsumer(filesList, rootPath));
 
    producerThread.start();
    consumerThread.start();
  }

}

Pretty straight forward- create instances of both the threads and then launch them. You can create multiple consumer threads as well! In the above example we make use of the LinkedBlockingQueue which is one of the implementations of the BlockingQueue.

You have to make sure you import corresponding classes in your source code. You can have all the three classes defined in the same file and name the file as ProducerConsumerSample.java and compile and run the code. Once you have the code running, then go to your terminal and type:

/tmp/nio$ touch file1
/tmp/nio$ echo "this is file1" >> file1
/tmp/nio$ touch file2
/tmp/nio$ echo "this is file2" >> file2

and the output you see on the terminal of your java program is:

reading file: /tmp/nio/file1
reading file: /tmp/nio/file1
this is file1
reading file: /tmp/nio/file2
reading file: /tmp/nio/file2
this is file2

Note: This code was compiled and tested on a Linux platform, please find similar ways of creating files on Windows when you run your code.

Download Source Code: Java Agents (399)

Writing the first agent

This section details on writing the first java agent. The purpose of the agent will be get as simple as possible as the aim of this section is just to get a bit introduced to the the usage of java agents. Coding a agent requires writing a java class that has the premain() method. Please refer the below code.

package net.javabeat.articles.javaagent.test;
import java.lang.instrument.Instrumentation;
public class TestJavaAgent {
	public static void premain(String agentArgument,
                   Instrumentation instrumentation){
		System.out.println("Test Java Agent");
	}
}

Note that it is mandatory for agents to have the above method with the exact signature. Note that the above agent does nothing another that printing sample content to the console.

Manifest-Version: 1.0
Premain-Class: net.javabeat.articles.javaagent.
                                test.TestJavaAgent

Agents are packaged as jar files and are made visible to the application using the option ‘javaagent’. Note that it is essential for the jar file to have the Premain-Class attribute that specifies the fully qualified name of the agent class containing the premain method. Now that we have written an agent, we have to make use of the agent. For making use of the agent, let us create a sample java class as follows. Note that nowhere in the code, we are invoking the agent. Instead while running the application, agents are specified as virtual machine arguments.

package net.javabeat.articles.javaagent.test;

public class TestMain {

	public static void main(String[] args) {
		System.out.println("Test Main Class");
	}
}

• Create a jar file called ‘test-agent.jar’ by packaging the class file ‘net.javabeat.articles.javaagent.test.TestJavaAgent’ and the manifest file ‘MANIFEST.MF’
• Make use of the command, to run the agent, java -javaagent:test-agent.jar net.javabeat.articles.javaagent.test.TestMain

The above command will produce the below output,

Test Java Agent
Test Main Class

Note that there are several things to be noted in the above section. First of all, the agent to be run is passed as virtual machine parameter to the application. This is done through the option ‘javaagent’, what follows after that is ‘:’ followed by the path to the jar file. Note that agent classes are invoked first before the above application classes, this can be seen from the output produced by the sample program.

Writing a simple Agent

Now that we have familiarized with the several aspects involved in writing a simple agent, let us start adding some more functionality to the agent in this section. Consider the below code snippet representing the agent,

package net.javabeat.articles.javaagent.simple;
import java.lang.instrument.Instrumentation;
public class SimpleAgent {
	public static void premain(String agentArguments,
                      Instrumentation instrumentation){
		System.out.println("Simple Agent");
		SimpleClassTransformer transformer =
                    new SimpleClassTransformer();
		instrumentation.addTransformer(transformer);
	}
}

Note that the very purpose of having agent is to provide instrumentation capabilities to the application – i.e. the capability to re-define the signature of the class files during run-time. The method premain() is passed with Instrumentation object that serves its very purpose. Using Instrumentation object it is possible to adding transformer objects. Transformer object does the real job of transforming (or re-defining) the content of class files at run-time. The above code defines a transformer object, whose declaration is given below,

package net.javabeat.articles.javaagent.simple;
import java.lang.instrument.ClassFileTransformer;
import java.lang.instrument.IllegalClassFormatException;
import java.security.ProtectionDomain;
public class SimpleClassTransformer implements ClassFileTransformer{
	public byte[] transform(ClassLoader    loader,
            String              className,
            Class            classBeingRedefined,
            ProtectionDomain    protectionDomain,
            byte[]              classfileBuffer)
			throws IllegalClassFormatException {

		System.out.println(className);
		return classfileBuffer;
	}
}

Note that, a transformer object must implement the ClassFileTransformer interface and the abstract method transform needs to be overridden. This method will be called for every class that is loaded as part of the application. Note that the content of the class can be represented as byte array and this method can re-define the class content that returnss a different byte array (as denoted by the method signature). For simplicity, this method returns the original class byte array that is passed to it.

Manifest-Version: 1.0
Premain-Class: net.javabeat.articles.javaagent.simple.SimpleAgent

Given above is the content of the manifest file for the agent. Note that for testing the agent, we need a sample application file which is given below. To illustrate the behavior of class loading, the application creates instances for Test classes.

package net.javabeat.articles.javaagent.simple;
public class SimpleMain {
	public static void main(String[] args) {
		Test1 one = new Test1();
		Test2 two = new Test2();
		System.out.println("Simple Main " + one + two);
	}
}
class Test1{}
class Test2{}

Running the above application along with the agent will produce the following output.

Simple Agent
net/javabeat/articles/javaagent/simple/SimpleMain
net/javabeat/articles/javaagent/simple/Test1
net/javabeat/articles/javaagent/simple/Test2
Simple Main net.javabeat.articles.javaagent.simple.
Test1@61de33net.javabeat.articles.javaagent.simple.Test2@14318bb

Agents for collecting statistical data

In the last section, we have seen how to make use of Instrumentation object. We also saw how to manipulate Instrumentation object by adding Transformer objects. In this final section, we will see the real capability of agents for providing some statistical information about the methods being loaded for a particular class. For the purpose of illustration, let us expand the scope of the sample by provide a business class having empty business methods. Let us also assume that because the methods are for external usage, all the methods have to be public.

package net.javabeat.articles.javaagent.statistics;
public class MyBusinessClass {
	public void bizMethod1(){
		System.out.println("Biz Method 1");
	}
	@SuppressWarnings("unused")
	private void bizMethod2(){
		System.out.println("Biz Method 2");
	}
}

The above code has the definition of the business class. Deliberately, the modifier for the method bizMethod2() is given as private. The agent class is given below. Note that, as illustrated in the last section, this class makes use of Instrumentation object to add transformer objects to it.

package net.javabeat.articles.javaagent.statistics;
import java.lang.instrument.Instrumentation;
public class StatisticsAgent {
	public static void premain(String agentArguments,
                         Instrumentation instrumentation){
		StatisticsClassTransformer transformer =
                   new StatisticsClassTransformer();
		instrumentation.addTransformer(transformer);
	}
}

The flavor of the Transformer class that has the functionality of providing statistical information is given below. At this point, note that by the time when the agent is invoked, the class is not loaded. It is only during the class loading time, the agent is invoked. Hence reflection related APIs cannot be used at this point. For querying the method information for a particular class, the implementation makes use of ASM (byte code analysis library).

package net.javabeat.articles.javaagent.statistics;

import java.io.IOException;
import java.lang.instrument.ClassFileTransformer;
import java.lang.instrument.IllegalClassFormatException;
import java.lang.reflect.Method;
import java.lang.reflect.Modifier;
import java.security.ProtectionDomain;
import java.util.List;

import org.objectweb.asm.ClassReader;
import org.objectweb.asm.tree.ClassNode;
import org.objectweb.asm.tree.MethodNode;

public class StatisticsClassTransformer implements ClassFileTransformer{

	public byte[] transform(ClassLoader    loader,
            String              className,
            Class            classBeingRedefined,
            ProtectionDomain    protectionDomain,
            byte[]              classfileBuffer)
			throws IllegalClassFormatException {

		System.out.println();
		System.out.println("Processing class " + className);

		String normalizedClassName = className.replaceAll("/", ".");

		ClassReader classReader = null;
		try {
			classReader = new ClassReader(normalizedClassName);
		} catch (IOException e1) {
			e1.printStackTrace();
		}

		ClassNode classNode = new ClassNode();
		classReader.accept(classNode, ClassReader.SKIP_DEBUG);

		@SuppressWarnings("unchecked")
		List allMethods = classNode.methods;
		for (MethodNode methodNode : allMethods){
			System.out.println(methodNode.name);
		}
		return classfileBuffer;
	}

	private static void processBizMethods(Class classObject) {
		if (MyBusinessClass.class.equals(classObject)){
			Method[] allMethods = classObject.getDeclaredMethods();
			for (Method aMethod : allMethods){
				System.out.println(aMethod.getName());
				int modifiers = aMethod.getModifiers();
				if (Modifier.isPrivate(modifiers)){
					System.out.println("Method " +
                                        aMethod.getName() + " is private");
				}
			}
		}
	}

	public static void main(String[] args) {
		processBizMethods(MyBusinessClass.class);
	}
}

The content of the manifest file for the above agent is given below.

Manifest-Version: 1.0
Premain-Class: net.javabeat.articles.javaagent.statistics.StatisticsAgent

The content of the application that triggers the agent class is given below.

package net.javabeat.articles.javaagent.statistics;
public class StatisticsMain {
	public static void main(String[] args) {
		MyBusinessClass object = new MyBusinessClass();
		System.out.println("Biz Object " + object);
	}
}

The output of the application is given below,

Processing class net/javabeat/articles/javaagent/statistics/StatisticsMain
<init>
main

Processing class net/javabeat/articles/javaagent/statistics/MyBusinessClass
<init>
bizMethod1
bizMethod2
Biz Object net.javabeat.articles.javaagent.statistics.MyBusinessClass@a59698

Conclusion

Download Source Code: Java Agents (399)

This article provides introductory concepts about Java agents which are introduced from 5.0. It provides a good starter about the usage of agents by providing lot of examples. Hope the readers will be benefited after reading this article.

You can download the POI API from http://poi.apache.org/

Apache POI – Terminology

Before getting in to HSSF, we will see some of the POI-Terminologys

• POIFS (Poor Obfuscation Implementation File System): Java APIs for reading and writing OLE (Object Linking and Embedding) 2 compound document formats.
• HSSF (Horrible Spreadsheet Format): Java API to read Microsoft Excel.
• HDF (Horrible Document Format): Java API to read and write Microsoft Word 97.
• HPSF (Horrible Property Set Format): Java API for reading property sets using (only) Java.

Reading data from Excel format file and displaying to console

Let us assume we have the following excel file (test.xls) with us.

Now let us see how to read through the rows and cells and get the data and display in the console.

Apache POI – Code Sample

The following java program reads a excel file and displays the data to the console.

/*
* POIExcelReader.java
*
* Created on 7 October, 2007, 9:05 PM
*/

package com.ms.util;

//~--- non-JDK imports --------------------------------------------------------

import org.apache.poi.hssf.usermodel.HSSFCell;
import org.apache.poi.hssf.usermodel.HSSFRichTextString;
import org.apache.poi.hssf.usermodel.HSSFRow;
import org.apache.poi.hssf.usermodel.HSSFSheet;
import org.apache.poi.hssf.usermodel.HSSFWorkbook;
import org.apache.poi.poifs.filesystem.POIFSFileSystem;

//~--- JDK imports ------------------------------------------------------------

import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.io.InputStream;

import java.util.Iterator;

/**
* This java program is used to read the data from a Excel file and display them
* on the console output.
*
* @author dhanago
*/
public class POIExcelReader
{

/** Creates a new instance of POIExcelReader */
public POIExcelReader ()
{}

/**
* This method is used to display the Excel content to command line.
*
* @param xlsPath
*/
@SuppressWarnings ("unchecked")
public void displayFromExcel (String xlsPath)
{
InputStream inputStream = null;

try
{
inputStream = new FileInputStream (xlsPath);
}
catch (FileNotFoundException e)
{
System.out.println ("File not found in the specified path.");
e.printStackTrace ();
}

POIFSFileSystem fileSystem = null;

try
{
fileSystem = new POIFSFileSystem (inputStream);

HSSFWorkbook      workBook = new HSSFWorkbook (fileSystem);
HSSFSheet         sheet    = workBook.getSheetAt (0);
Iterator rows     = sheet.rowIterator ();

while (rows.hasNext ())
{
HSSFRow row = rows.next ();

// display row number in the console.
System.out.println ("Row No.: " + row.getRowNum ());

// once get a row its time to iterate through cells.
Iterator cells = row.cellIterator ();

while (cells.hasNext ())
{
HSSFCell cell = cells.next ();

System.out.println ("Cell No.: " + cell.getCellNum ());

/*
 * Now we will get the cell type and display the values
 * accordingly.
 */
switch (cell.getCellType ())
{
	case HSSFCell.CELL_TYPE_NUMERIC :
	{

		// cell type numeric.
		System.out.println ("Numeric value: " + cell.getNumericCellValue ());

		break;
	}

	case HSSFCell.CELL_TYPE_STRING :
	{

		// cell type string.
		HSSFRichTextString richTextString = cell.getRichStringCellValue ();

		System.out.println ("String value: " + richTextString.getString ());

		break;
	}

	default :
	{

		// types other than String and Numeric.
		System.out.println ("Type not supported.");

		break;
	}
}
}
}
}
catch (IOException e)
{
e.printStackTrace ();
}
}

/**
* The main executable method to test displayFromExcel method.
*
* @param args
*/
public static void main (String[] args)
{
POIExcelReader poiExample = new POIExcelReader ();
String         xlsPath    = "c://test//test.xls";

poiExample.displayFromExcel (xlsPath);
}
}

Code walk through

• POIFSFileSystem is the main class for POIFS system. POIFSFileSystem manages the entire life cycle for the file system.
• POIFSFileSystem has a constructor which can take a InputStream as the parameter. Here in the above code we have created a FileInputStream and assigned to the InputStream. This inputStream object is passed to the POIFSFileSystem constructor and POIFSFileSystem object is created.
• After creating POIFSFileSystem object, HSSFWorkbook object has to be created.
• HSSFWorkbook object is a high level representation of a workbook. This is the first object most users will construct whether they are reading or writing a workbook. It is also the top level object for creating new sheets/etc.
• HSSFWorkbook object is created using POIFSFileSystem object. By using the constructor HSSFWorkbook(POIFSFileSystem fs).
• Once we get the HSSFWorkbook object it is very easy to get the Sheet. HSSFWorkbook has a method getSheetAt(int index) Get the HSSFSheet object at the given index.
• Note that index starts at zero. In our code we have used like “workBook.getSheetAt (0)” means we are intrested in first sheet.
• The above method will give us a HSSFSheet object.
• HSSFSheet object has got a method called “rowIterator()”. This will give us all the rows in a Iterator and is of type HSSFRow
• By Iterating this in a while loop we can get each and every for and cells in them.
• HSSFRow has a method called “cellIterator()” This will also return a Iterator consisting of type HSSFCell.
• By Iterating this we will get individual HSSFCell objects.
• By getting the HSSFCell we can get the cell type by using the method “getCellType()”
• By finding the cell type we can use the appropriate method to get the values as shown in the code above. Then it is up to the programmers requirement to use the values got accordingly. Here we have simply displayed it in the console.

Output

Row No.: 0
Cell No.: 0
String value: Name
Cell No.: 1
String value: Age
Cell No.: 2
String value: URL
Row No.: 1
Cell No.: 0
String value: Muthukumar Dhanagopal
Cell No.: 1
Numeric value: 33.0
Cell No.: 2
String value: http://javawave.blogspot.com
Row No.: 2
Cell No.: 0
String value: Krish
Cell No.: 1
Numeric value: 27.0
Cell No.: 2
String value: http://javabeat.net
Row No.: 3
Cell No.: 0
String value: Sri Hariharan Muthukumar
Cell No.: 1
Numeric value: 3.0
Cell No.: 2
String value: http://dhanago.blogspot.com

Other operations you can do with HSSF

• to create a new workbook
• to create a sheet
• to create cells
• to create date cells
• Working with different types of cells
• Aligning cells
• Working with borders
• Fills and color
• Merging cells
• Working with fonts
• Custom colors
• Reading and writing
• Use newlines in cells.
• Create user defined data formats
• Fit Sheet to One Page
• Set print area for a sheet
• Set page numbers on the footer of a sheet
• Shift rows
• Set a sheet as selected
• Set the zoom magnification for a sheet
• Create split and freeze panes
• Repeating rows and columns
• Headers and Footers
• Drawing Shapes
• Styling Shapes
• Shapes and Graphics2d
• Outlining
• Images
• Named Ranges and Named Cells
• How to set cell comments
• How to adjust column width to fit the contents

References

• http://poi.apache.org/hssf/index.html

Summary

Through this article i have just given the much needed push (Even eagles need a push). It is up to the programmers or developers who wanna proceed further to know more about POI and its API. Now a days there are many applications which are there in real time which uses Excel sheets and need to be read from Java and vice verse. POI is a very helpful, fantastic and easy tool helping Java programmers in achieving this.

• Java 5.0 Features
• Book Review: Pro Java 7 NIO.2
• AutoBoxing in Java 5.0

2) java.util.regex Package

The java.util.regex package provides the necessary classes for using Regular Expressions in a java application. This package has been introduced in Java 1.4. It consists of three main classes namely,

• Pattern
• Matcher
• PatternSyntaxException

3) Pattern Class

A regular expression which is specified as a string, should be first compiled into an instance of Pattern class. The resulting pattern can then be used to create an instance of Matcher class which contains various in-built methods that helps in performing a match against the regular expression. Many Matcher objects can share the same Pattern object.

Let us now discuss about the important methods in Pattern class.

a) compile() method

Before working with, we need a compiled form of regular expression pattern, by calling the Pattern.compile() method which returns a new
Pattern object. Note that compile() is a static method, so we dont an instance of the Pattern class.

There are two forms of compile() method,

• compile(String regex)
• compile(String regex, int flags)

In the first form of compile() method, we pass the regular expression that would be compiled. In the second form of this method, we have an additional parameter which is used to specify the match flags that has to be applied. The flags can be either CASE_INSENSITIVE, MULTILINE, DOTALL, UNICODE_CASE or CANON_EQ based on which matching would be done.

b) matcher() method

The matcher() method is used to create new Matcher object for an input for a given pattern, which can be used to perform matching operations. The syntax is as follows,

matcher(String input)

c) matches() method

The Pattern class provides a matches() method, which is a static method. This method returns true only if the entire input text matches the pattern. This method internally depends on the compile() and matcher() methods of the Pattern object. The syntax for this static matches() method is,

Pattern.matches(pattern, inputSequence);

Let us see a simple example,

RegExpTest.java

import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class RegExpTest {
    public static void main(String[] args) {

        String inputStr = "Computer";
        String pattern = "Computer";
        boolean patternMatched = Pattern.matches(pattern, inputStr);
        System.out.println(patternMatched);

    }
}

The matches() method returns true in this case and hence we get the output as true. If in case, we had given the input string as "ComputerScience", then the matches() method would have returned false.

In the static matches() method, when we specify an input string and a pattern to the Pattern.matches() method, the pattern gets compiled into a Pattern object which is used for matching operation. This is inefficient because every time we specify an input string and pattern, compilation of the pattern is done. Hence, its better to use the non static matches() method in Matcher class. (This matches() method would be discussed when dealing with Matcher class in the forth-coming section).

d) pattern() method

Returns the regular expression as a string from which this pattern was compiled.

e) split() method

This method is used to split the given input text based on the given pattern. It returns a String array.

There are two forms of split() method,

• split(String input)
• split(String input, int limit)

In the second form, we have an argument called limit which is used to specify the limit i.e the number of resultant strings that have to be obtained by split() method.

Let us see a simple example for the split() method,

Pattern pattern = Pattern.compile("ing");
Matcher matcher = pattern.matcher("playingrowinglaughingsleepingweeping");
String[] str = pattern.split(input, 4);
for(String st : str)
{
    System.out.println(st);
}

In the above code, we had specified the limit of number of Strings to be returned as 4. Hence we would get 4 strings as the result.

The output for the above code is,
play
row
laugh
sleepingweeping

f) flag() method

This method returns this pattern’s match flags which would have been specified when the pattern was compiled.

4) Matcher Class

The Matcher class which contains various in-built methods such as matches(), find(), group(), replaceFirst(), replaceAll() etc., that help us to check whether the desired pattern occurs in the given text or search the desired pattern in the text or to replace the occurrence of the pattern in the text with some other set of characters as per the requirement.

Let us now discuss about the important methods in Matcher class.

a) matches() method

The matches() method available in the Matcher class is used to match an input text against a pattern. This method returns true only if the entire input text sequence matches the pattern. Consider the following example,

String input = "Java1.4, Java1.5, Java1.6";
Pattern pattern = Pattern.compile("Java");
Matcher matcher = pattern.matcher(input);
boolean patternMatched = matcher.matches();

In this case the value of patternMatched will be false since the entire input string "Java1.4, Java1.5, Java1.6" does not match the regular expression pattern "Java" and hence matches() method returns false. Let us use the same Pattern object in another Matcher object and see how it works. Consider the following code,

String input = "Java";
Matcher matcher1 = pattern.matcher(input);
boolean patternMatched1 = matcher1.matches();

Here, the matches() method returns true since the entire input sequence matches the pattern "Java". The matches() method finds appropriate use in searching for particular whole words in a given text.

Let us see another example to know about some other methods available in Matcher class,

String input = "Java1.4, Java1.5, Java1.6";

Pattern pattern = Pattern.compile("Java");
Matcher matcher = pattern.matcher(input);

while (matcher.find()){
    System.out.println(matcher.group() + ": " +matcher.start() + ": " + matcher.end());
}

The output of the above code is,

Java: 0: 4
Java: 9: 13
Java: 18: 22

In the above example code, we see the usage of find(), group(), start and end() methods.

Now, let us know about the purpose of those methods.

b) find() method

The find() method in Matcher Class returns true if the pattern occurs anywhere in the input string.
It has two forms,

• find()
• find(int start)

In our example, we used the first form of find() method. It searches for all occurrences of the pattern "Java" in the given input String "Java1.4, Java1.5, Java1.6" and then returns true if a subsequence in the input matches the desired pattern.

In the second form of find() method, we have an argument that is used to specify the start index of find operation.

c) group() method

The group() method in Matcher Class returns the piece of input that has matched the pattern.

d) start() method and end() method

The start() and end() methods in Matcher Class return the start and end indexes respectively, for each occurrence of the subsequences in the input text that has matched the defined regular expression pattern.

5) PatternSyntaxException Class

PatternSyntaxException is an unchecked exception which is thrown when there is any syntax error in a regular expression pattern. It has various methods like getDescription(), getIndex(), getMessage() and getPattern() which enable us to get the details of the error.

We have just seen very simple examples to understand the basics of Regular Expressions in java, and about the purpose of few often used methods. With this basic knowledge, we shall discuss in depth about Regular Expression in the following sections.

6) Matching any single character

The '.' character is used to match any single character. If suppose we use a pattern 'ca.' then this pattern would match string inputs like 'car', ‘cat’, 'cap' etc.. because they start with ca and then followed by another single character. Consider an example to understand this,

Pattern patternObj = Pattern.compile("ca.");
Matcher matcher = patternObj.matcher("cap");
if(matcher.matches()){
    System.out.println("The given input matched the pattern");
}

The output of the above code is,

The given input matched the pattern

7) Matching Special characters

Suppose we need to specify '.' character in our pattern to indicate that the string input should contain the '.' character. But, in Regular Expression '.' has a specific meaning. So we have to specify it to the compiler that we don’t mean the Regular expression '.' by escaping it with a '\' (backslash character) which is a metacharacter. Consider the following example,

Pattern patternObj = Pattern.compile(".est\\.java");
Matcher matcher1 = patternObj.matcher("test.java");
Matcher matcher2 = patternObj.matcher("nest.java");

if(matcher1.matches() && matcher2.matches()){
    System.out.println("Both the inputs matched the pattern");
}

The output of this code is,

Both the inputs matched the pattern

Hence, the use of '.' means to match any character, and the use of ‘\.’ means the normal '.' character. We can use this backslash character wherever we need to specify a special character for some other purpose.
(Note : In Java, the compiler expects a backslash character '\' to be always prefixed with another backslash character '\' when used within a String literal.)

8) Matching particular characters

In a given text, we may need to match specific desired characters. We have already seen that the '.' character will match any single character but now our requirement is to match only 'c' or 's' along with other desired set of characters. In such situations, we can enclose the desired characters in parenthesis [] which is a metacharacter used to indicate a character set from which any one character should be available in the given text. Consider the following piece of code that illustrates the same,

Pattern patternObj = Pattern.compile("[CcSs]at");
Matcher matcher = patternObj.matcher("Sat");
if(matcher.matches()){
    System.out.println("The given input matched the pattern");
}

The output of this code is,

The given input matched the pattern

In the above example, we have used the pattern '[CcSs]at' wherein Cc is used to match C and c, and Ss matches S and s. Hence this would match inputs such as Cat, cat, Sat and sat.

9) Matching range of characters

In Regular expressions, we use the metacharacter '-' i.e a hyphen symbol to specify a range of characters. For example, we can specify the range of lowercase alphabets as '[a-z]' and '[A-Z]' in case of uppercase alphabets.

Consider a situation where we need the input to start with a number from 0 to 3, then followed by any alphabet from a to z and then followed by another number that might range from 7 to 9. The following code can be used to validate the input against such a pattern,

Pattern patternObj = Pattern.compile("[0-3][a-z][7-9]");
Matcher matcher = patternObj.matcher("2a8");
if(matcher.matches()){
    System.out.println("The given input matched the pattern ");
}

10) Matching characters apart from a specific list

We can use the '^' metacharacter to specify one or more characters that we want don’t expect to match. Let us achieve the same requirement in our previous example by using a different pattern that makes use of the metacharacter '^' ,

Pattern patternObj = Pattern.compile("[^3-9][a-z][7-9]");

The use of '^' character inside [] indicates that those characters specified in it are not expected in the input.

This pattern will match the input "2a8" as in our previous example.

11) Use of other Metacharacters in Regular Expression

We have already discussed about the use of '.' and '^' metacharacters. Let us see the purpose of other metacharacters.

\d

This matches a numeric digit. It is the same as using the character set [0-9].

\D

This matches any character which is non-numeric. It is the same as the use of [^0-9].

\s

This matches a single whitespace character.

\S

This matches any character which is not a whitespace character.

\w

This matches a word character. It is equivalent to the character class [A-Za-z0-9_].

\W

This matches a character that is not a word character. It is equivalent to the
negated character class [^A-Za-z0-9_].

[...]

This matches a single character present in between the square paranthesis.

[a-f[s-z]]

This specifies the union of two sets of characters, which is the same as [a-fs-z], i.e it
matches any character that might be either from a to f and from s to z.

[a-m[f-z]]

This specifies the intersection of two sets of characters, which is the same as [f-m], i.e it matches any character from f to m.

[^...]

This matches any single character, except those characters that are specified inside the square parentheses [].

12) POSIX Character Classes

The java.util.regex package provides a set of POSIX character classes, which are indeed shortcuts to be used in regular expressions that make it easier for us to use instead of specifying the entire pattern.

\p{Lower}

It can be used to match any single lowercase alphabetic character. It is the same as using [a-z].

\p{Upper}

It can be used to match any single uppercase alphabet character. It is the same as using [A-Z].

\p{Alpha}

It is used to match any alphabetic character. It serves the same purpose as [A-Za-z].

\p{Digit}

It is used to match any single digit. It serves the same purpose as [0-9].

\p{Punct}

It is the same as using [!"#$%&'()*+,- ./:;?@[\]^_`{|}~].

\p{Graph}

It is the same as using [\p{Alpha}\p{Punct}].

\p{Print}

It is the same as using [\p{Graph}].

\p{ASCII]

It can be used to match any of the ASCII characters. It serves the same purpose as U+0000 through U+007F.

\p{XDigit}

It matches a single hexadecimal digit. It is the same as using [0-9a-fA-F].

\p{Space}

It is used to match a single whitespace character. It is the same as using [ \t\n\x0B\f\r].

\p{Blank}

It matches a single space character or a tab character.

\p{Cntrl}

It matches a control character. It is the same as using [\x00-\x1F\x7F].

13) Conclusion

also read:

• Java 5.0 Features
• Book Review: Pro Java 7 NIO.2
• AutoBoxing in Java 5.0

This article is just an introduction to Regular expressions. We have seen the basics on how to use regular expressions to perform useful operations such as search, replace and validation for a given input. Regular Expressions can be effectively used to suit our application needs that involve text manipulation.

• Buy : Generics and Collections

2) Java Generics

In this section let us explore the basis of Generics programming. As mentioned in the introductory section, Generics programming enables Classes and Methods to operate on well defined parametric types allowing clients to substitute a suitable Java type at the compile time. This prevents un-necessary casting being done in the Application code and to prevent any wrong data-type being used. To make things clear, consider the following statements.

Map contacts = new HashMap();
contacts.put(new Long(9912345678L), "Jenny");
contacts.put(new Long(9912345679L), "Johny");

Set contactValues = contacts.entrySet();
Iterator contactIterator = contactValues.iterator();

while (contactIterator.hasNext())
{
    Map.Entry anEntry = (Map.Entry)contactIterator.next(); // Line A
    Long number = (Long)anEntry.getKey(); // Line B
    String name = (String)anEntry.getValue(); // Line C
    System.out.println(number + ":" + name);
}

The above code populates a Map, keyed with mobile phone for a person name. The next pieces of code try to iterate over the Map, thereby printing the data within it. Look at the casts down at lines A, B and C. Even though we know that we are going to add phone numbers (which is of type Long) and a person name (probably a String) into the Map, we are doing an explicit cast to get the appropriate data. The other problem we find here is, what if the client put some other data other than the Long data-type for the Key.

contacts.put(new String("9912345678L"), "Jenny");

The above code will definitely raise an exception at the run-time. So, we find two major dis-advantages in the older code (code compiled with java 1.4 compiler or before). One is the need to have absurd cast that is being spread across the code. The other thing is that there is no procedural mechanism through which we can prevent wrong data-type being added to the above Collection.

The solution to the above problems is having Generics in the programming code. Let us see how the above code is re-written using Generics.

Map contacts = new HashMap();
contacts.put(new Long(9912345678L), "Jenny");
contacts.put(new Long(9912345679L), "Johny");

Set<Map.Entry> contactValues = contacts.entrySet();
Iterator<Map.Entry> contactIterator = contactValues.iterator();

while (contactIterator.hasNext())
{
    Map.Entry anEntry = contactIterator.next();
    Long number = anEntry.getKey();
    String name =  anEntry.getValue();
    System.out.println(number + ":" + name);
}

Let us analyze what has happened in the above code. The declaration Map contacts = new HashMap(); has now changed to Map<Long, String> contacts = new HashMap<Long, String>();

The former is called a Raw Map and the latter is an example of a Generic Map. If we look at the declaration of the Map and the HashMap classes, we will find something similar to the following,

public interface Map { ... }

The above declaration can be interpreted as : Map has two parametric types called K (meaning Key) and V (meaning Value). The name of the parametric types can be anything, that doesn’t matter. These changes to Map and all its related collection classes is there right from Java 5.0. So, whenever a clients references a Map interface, it cannot plainly do like the following,

Map mapObject = new HashMap();

The compiler (Java 5.0) as soon as encountering this statement will issue a warning telling that, the declaration of Map is a raw-type and its references should be parameterized. Since the declaration of the Map interface is now parameterized with Keys and Values in the form of <K, V>, the client referencing the Map should provide a suitable type for the parametric types. Going back to our code,

Map contacts = new HashMap();

We want the key for the Map to be of type Long and the value for the corresponding Key to be of type String. We also have parameterized the HashMap class with Long and String, since the class declaration for HashMap has also changed.

public class HashMap implements Map { … }

The usage of parametric types has not only affected Map and HashMap but all the collection related classes and interfaces in the java.util package. In our code, contacts are made to populate in the map object by calling the Map.put() method. Now, the call to Map.entrySet() will return a Set containing entries which is of type Map.Entry. Now let us have a look over the Map.entrySet() method,

Set<Map.Entry> entrySet();

The return type of Map.entrySet() is a Set which is parameterized with Map.Entry. Map.Entry is a class that will store an entry, which is nothing but a combination of Key and value. Note that Map.Entry is again parameterized with K (for Key) and V (for Value). In our case, the key is of type Long and the value is of type String, we have something like the following in the later part of the code,

Set<Map.Entry> contactValues = contacts.entrySet();

The same thing applies for Iterator which is parameterized with Map.Entry which is again parameterized with Long and String. While traversing over the elements within the while loop, we have statements like the following,

...

Map.Entry anEntry = contactIterator.next();
Long number = anEntry.getKey();
String name =  anEntry.getValue();

...

Since we well know that the Iterator is typed with Map.Entry<Long, String>, there is no need for an explicit type-cast. Same is the case for Map.getKey() and Map.getValue(). Since the Map has been parameterized with Long and String, it is not possible to add types other than the defined types. So now the following code will raise a compilation error.

contacts.put(new String(""), new Long(1L));

This ensures type-safe programming and it prevents the client code from adding any wrong data-type to the Collection.

3) Writing Generic Classes

• Java 5.0 Features
• Book Review: Pro Java 7 NIO.2

Let us see how to create our own classes using Generics. Let us keep the purpose of the class as simple as holding some Object, the Object Holder class. This Object Holder class can hold any type of Java object. It provides method for getting and setting the current Object. The following shows the class declaration of the Object Holder class.

ObjectHolder.java

package generics.classes;

public class ObjectHolder
{
    private O anyObject;

    public O getObject()
    {
        return anyObject;
    }

    public void setObject(O anyObject)
    {
        this.anyObject = anyObject;
    }

    public String toString()
    {
        return anyObject.toString();
    }
}

Note the following syntax,

public class ObjectHolder

The above statement essentially says that we wish to make the Object Holder class as a Generic Class. Technically, Object Holder is now a parametric class and O is called a type parameter. O serves as a place-holder for holding any type of Object. Note the usage of the type parameter within the class declaration. Now, the clients can use the above class by substituting any kind of object for the place-holder O. Consider the following Client program that makes use of the Object Holder class.

ObjectHolderClient.java

package generics.classes;

import java.net.URL;

public class ObjectHolderClient
{
    public static void main(String[] args) throws Exception
    {
        ObjectHolder stringHolder =
            new ObjectHolder();
        stringHolder.setObject(new String("String"));
        System.out.println(stringHolder.toString());

        ObjectHolder urlHolder = new ObjectHolder();
        urlHolder.setObject(new URL("http://www.javabeat.net"));
        System.out.println(urlHolder.toString());
    }
}

Note how the Clients instantiates an instance for the Object Holder class.

ObjectHolder stringHolder = new ObjectHolder();

This is called type substitution. For the type parameter O, the type String is substituted. And now the calls to ObjectHolder.setObject(O anyObject) and O ObjectHolder.getObject() can be imagined as ObjectHolder.setObject(String anyObject) and String ObjectHolder.getObject().

Now, let us see another example of Generic classes having two or more parametric types. Assume that we want to represent a class that holds a Composite object along with the elements of the composite object. We can see this kind of Composiste – children relation-ship in a number of places. For example, a Folder containing multiple files or a Window containing a number of UI Components and so on.

Following is the representation of the Container With Elements (ContainerWithElements) class holding a Container object with its children. Note that the class typed parameters have the names Container and Elements respectively for holding the Container object and its child elements.

ContainerWithElements.java

package generics.classes;

import java.util.List;

public class ContainerWithElements
{
    private Container outerObject;
    private List innerObjects;

    public ContainerWithElements(Container outerObject, List innerObjects)
    {
        this.outerObject = outerObject;
        this.innerObjects = innerObjects;
    }

    public Container getOuterObject()
    {
        return outerObject;
    }

    public void setOuterObject(Container outerObject)
    {
        this.outerObject = outerObject;
    }

    public List getInnerObjects()
    {
        return innerObjects;
    }

    public void setInnerObjects(List innerObjects)
    {
        this.innerObjects = innerObjects;
    }

}

The Client program that makes use of the above class is given below. Note the usage of the classes Folder, File, Window and Button are from the generics.classes package and they have nothing to do with the genuine java.* classes.

ContainerWithElementsClient.java

package generics.classes;

import java.util.Arrays;

public class ContainerWithElementsClient
{
    public static void main(String[] args)
    {
        ContainerWithElements folderWithFiles
            = new ContainerWithElements(
                new Folder(), Arrays.asList(new File(), new File()));

        ContainerWithElements windowWithButtons
            = new ContainerWithElements(
                new Window(), Arrays.asList(new Button(), new Button()));
    }
}

For code completeness, the declaration of the classes Folder, File, Window and Button is given below.

class Folder{}
class File{}

class Window{}
class Button{}

4) Writing Generic Methods

In the previous section, we saw how to write Parameterized Classes. Now, let us spend time in exercising Parameterized Methods or Generic methods in this section. A Generic class containing a type parameter affects the entire class, but a generic method containing one or more type parameters affects that particular method only. So it means that a non-generic class can contain a mixture of generic and non-generic methods.

Following code snippet shows how to declare a Generic method.

GenericMethods.java

package generics.methods;

public class GenericMethods
{
    static  void printType(T anyType)
    {
        System.out.println(anyType.getClass().getName());
    }

    public static void main(String[] args)
    {
        GenericMethods.printType(String.class);
        GenericMethods.printType(new String(""));
    }
}

If we look at the way in which a Generic method is declared, we find that the static method printType() has a return type void and it takes a single parameter called T. Here T stands for any parametric type which can be substituted with any of the Java types by the Clients. Since we have introduced a parameter T, it should be defined. But where? It should be defined in the method definition itself just before the return type of the method (<T>).

The moral is whenever we have different type parameters in a method, it should be defined in the method definition. For example, consider the following method that has two type parameters A and B and they are defined before the return type of the method separated by commas.

 void aGgenericMethod(A aType, B bType)
{
    // Something here.
}

But the same type parameter can de used multiple number of times in the parameter list. For example, the type paramter A is defined once but used multiple times in the following code,

 void aGgenericMethod(A aType, A anotherType, B bType)
{
    // Something here.
}

5) Wildcards

The following sections explain the usage of Wild-card character in Generics. For example, consider the following,

strObjects.add(new String("A String"));
strObjects.add(new String("Another String"));

The above line declares an Array List with a type being the String type. The declaration says that the list (strObjects) in this case, can hold objects only of type java.lang.String. No other type is permitted other than java.lang.String. So, the following statements are legal as they are adding objects of type java.lang.String.

List anotherStrObjects = strObjects;

Now, consider the following assignment statement which assigns the object reference strObjects to anotherStrObjects. Now anotherStrObjects is pointing to strObjects reference.

List

The above is a perfectly legal statement as the assignment happens between the same type. Now, consider the following,

LObject someObject = new String("");

The above statement will lead to a compiler error telling that “Cannot convert from List<String> to List<Object”. Though String is a sub-class of the Object class, this type of conversion is not possible in Generics, but the following code compiles well.

List objects = strObjects;

The reason why it is not possible to assign the List containing strings to a List that can hold Objects can be given justification as follows. The main goal of having Generic code in a program is to ensure type-safety. It means that the expected Application types and the types sent by the Clients should match. There should not be any deviation or mis-match in their types. If we go back to the code, on the left-hand side, we have a List that can hold Objects represented by List<Object> objects. This tells to the compiler that this List can hold objects of type java.lang.Object. Now we are making this object List to point to some other list whose parametric type is String. Though String is a concrete sub-class of Object, this assignment is not possible.

Let us see how to get over this problem. Consider the following code,

Object someObject = new String("");

The character '?' is a wild-card character and it stands for any Java type. It can be java.lang.Object type or some other type. It is just a place-holder that tells that it can be assigned with any type. Considering this case, the following are now valid syntaxes.

List anyObjects = null;

List integers = new ArrayList();
anyObjects = integers;

List doubles = new ArrayList();
anyObjects = doubles;

The above code snippet tries to assign a list of integers and a list of doubles to the reference anyObjects. This is perfectly legal. Another strange thing has to be considered is while adding elements into the collection. Since the type parameter for the reference anyObjects is '?', no objects can be added to the collection, not even java.lang.Object. The only exception is that only null can be added to these type of collection.

anyObjects.add(new Integer(1)); // Wont compile
anyObjects.add(new Double(1.0)); // Wont compile

anyObjects.add(null); // This will compile.

6) Bounding the Parameterized Types

Generics won’t be complete if this section is not covered. It is all about bounding parametric types. Till now, we have seen parametric types operate on a single java type like Object or String. Now, let us see how the parametric types can be restricted by applying some constraints over them. For this to be illustrated, let us take a sample application called Animal Actions.

Animal Actions class performs various operations on a given Animal like: making them eat, sleep and run. The first constraint that we see here is that only an Animal object can be passed to the Animal Actions class. Let us represent the Animal class as follows.

Animal.java

package generics.bounds;

public abstract class Animal
{
    // Some common functionalities here.
}

Note that the Animal class is declared as abstract, meaning that some other concrete class is going to extend this Animal class. Another restriction that we see in Animal Actions class is that they will make the Animals to sleep, eat and run. Since these are behaviors and we may give different representations for the same, let them be modeled as interfaces. Following code shows the interface design for the behaviors,

package generics.bounds;

interface Sleepable
{
    public void sleep();
}

interface Runnable
{
    public void run();
}

interface Eatable
{
    public void eat();
}

Let us give implementation of the above behaviors for some animal, say Dog. The following code snippet is for the implementation of Dog which conforms to eating, sleeping and running behavior.

Dog.java

package generics.bounds;

public class Dog extends Animal implements Sleepable, Runnable, Eatable
{
    public void sleep()
    {
        System.out.println("Dog is sleeping");
    }

    public void run()
    {
        System.out.println("Dog is running");
    }

    public void eat()
    {
        System.out.println("Dog is eating");
    }

Now, let us design the Animal Actions class. The restriction we have on Animal Actions class is that, we should operation on any type of object that is an Animal which can eat, sleep and run. Look into the following Animal Actions class,

AnimalActions.java

package generics.bounds;

public class AnimalActions<a> { private A animal; public AnimalActions(A animal) { this.animal = animal; } public A getAnimal() { return animal; } public void setAnimal(A animal) { this.animal = animal; } public void doActions() { animal.sleep(); animal.run(); animal.eat(); } }</a>

The declaration of the parameterized class looks like the following,

public class AnimalActions

Let us break down the pieces in the above declaration. The first trivial stuff that has to be noted is the declaration of the typed parameter A (which is for Animal). The next set of expressions are imposing restrictions on the typed parameter A. The phrase 'A extends Animal' tells that whatever type we pass for the substitution parameter must extend/implement the Animal class/interface. The type that comes after extends can either be an interface or a class. It is illegal to mention something like the following,

public class AnimalActions

Only extends keyword is used for both class as well the interface and not the implements keyword. If we want the parametric type to confirm by more than one classes or interfaces, then every types should be separated by the symbol &. For example, in our case, we want some Animal to eat, sleep and run by implementing the Eatable, Sleepable and Runnable interface. So, we have declared something like AnimalActions<A extends Animal & Sleepable & Runnable & Eatable. To sum up things, the generic class declaration can be interpreted like this; it can be passed with any type that implements/extends Animal, Sleepable, Runnable and Eatable types.

Following code snippet makes use of the above Animal Actions class. In the below code, a new instance of Dog object is created and passed on to the constructor of the Animal Actions class. This is perfectly valid as the Dog class extends the Animal class and it also implements Sleepable, Eatable and Runnable interfaces. It then makes a call to AnimalActions.doActions(), thereby the execution gets directed towards Dog.sleep(), Dog.eat() and Dot.run().

AnimalActionsTest.java

package generics.bounds;

public class AnimalActionsTest
{
    public static void main(String[] args)
    {
        AnimalActions animal = new AnimalActions(new Dog());
        animal.doActions();
    }
}

7) More on parametric bounds and wild-cards

The restriction on parametric types that is applied on class definition is also applicable to method definition. Let us move towards assignment now. Consider the following statement,

List animals = new ArrayList();

The above is a declaration of list that essentially tells to the compiler that it can hold Animal objects. So the following statements is perfectly valid.

animals.add(new Animal()); // Fine.

Assuming that Animal class is not abstract. Not only it is possible to add Animal objects but also any types that extends the Animal class. By having this rule in hand, it is perfectly possible to have the following statements,

animals.add(new Dog()); // This will work too.
animals.add(new Cat()); // This also.

Even though, it is possible to add any type that extends the Animal class, it is not possible to have the following statement.

List dogs = new ArrayList();
dogs.add(new Dog()); dogs.add(new Dog());

animals = dogs; // This wont compile.

The compiler will warn you telling that it is not possible to convert List<Dog> to List<Animal>. Even a type-casting on the above statement doesn’t work.

animals = (List<Animal>)dogs; // This won't work.

Since type-casting from one type to another type is a run-time operation and during run-time there is no such existence of the types List<Animal> or List<Dog> because of erasures. All the typed-parameters won’t be available in the class-file and the above code doesn’t work.

7.1) Upper Bound

The solution to this situation is the usage of wild-cards along with parametric bounding. Have a look over the following declaration.

List animals = new ArrayList();

It tells that a list is being declared with type being anything (?) that is extending the Animal class. Though it looks very similar to the above declaration it has some differences. The first thing is that it is now possible for the animals reference to point to a list that is holding any sub-type of Animal objects.

List dogs = new ArrayList();
dogs.add(new Dog()); dogs.add(new Dog());

animals = dogs;

One important difference is that, it is not possible to add elements to the animals list, though the only exception is adding null elements. This is called the Upper Bound for the animals list.

7.2) Lower Bound

Similar to Upper Bounds, we have Lower Bounds with the following syntax,

List dogs = new ArrayList();

This declaration tells that along with Dog type, all other sub-types of Dog is also allowed. Not any of the super-type of Dog can be added including java.lang.Object. So, if we have classes like GoodDog and BadDog, both extending the Dog class, then the following statements are legal.

dogs.add(new Dog());
dogs.add(new GoodDog());
dogs.add(new BadDog());

8) Conclusion

One of the major language and syntax change in Java 5.0 is Java Generics. Through Generics, it is now possible to have a programming model that operates on some parametric type and the same model can be re-used with different types. It is important to note that there will be only one class file for the whole Generic type, unlike other programming languages (in the name of templates in C++). Generics makes use of the concept of Erasure which erases all the Generic type information during the compilation process.

• Java Threads (Covers J2SE 5. 0)

Java 5.0 comes with a bunch of useful features. In this article, we are going to have an overview of the features like Enhanced for-loop, Variable Arguments, Static Imports and Enumerations. Apart from these features, we have already published other notable features in Java 5.0, auto boxing, generics and annotations. Buy generics book for detailed explanation on the concept. If you are interested in receiving the future Java mails, please subscribe here.

The sections in this article are,

2) Enhanced For loop

We will cover the usage of Enhanced for-loop in this section. This is also referred to as for-each loop. The following code shows how to iterate over the elements in a Collection using the traditional Iterator interface.

ForEachTest.java

package foreach;

import java.util.*;

public class ForEachTest
{
	public static void main(String[] args)
	{
		List numbers = new ArrayList();
		numbers.add(1);numbers.add(2);numbers.add(3);

		Iterator numbersIterator = null;
		for(numbersIterator = numbers.iterator(); numbersIterator.hasNext();)
		{
			System.out.println(numbersIterator.next());;
		}
	}
}

Though the goal of the above program is traversing over the elements in the list collection, we are depending on the Iterator API to achieve this. A replacement to the Iterator is the usage of Enhanced for-loop, through which it is possible to have a short and a neat code like this,

for(Integer number : numbers)
{
	System.out.println(number);
}

Let us see how the above syntax is used to traverse over the collection. The expression before the symbol ':' is a declaration statement which declares an Integer object called number for holding the individual element from the collection. The expression that follows after the symbol must be a Collection type whose elements can be iterated. Precisely, this type must implement an interface called java.util.Iterable which has a single method called iterator(). During compile-time, the compiler translates the above code which looks very similar to the following,

Iterator intIterator = numbers.iterator();

for(;intIterator.hasNext();)
{
	System.out.println(intIterator.next());
}

Even it is possible to apply this new syntax for type Arrays. So, the following code is perfectly legal and it compiles fine.

int [] numbers = {10, 20, 30, 40, 50};

for(int num : numbers)
{
	System.out.println(num);
}

The enhanced for-loop is just a convenience from the programmer’s point of view for iterating over the Collection. But the usage of this loop has some dis-advantages. The first one out of the two is that step-value cannot be incremented. For example, it is not possible to traverse the first element and then the thirth element and so on. And the second dis-advantage is that backward traversal is not possible.

3) Variable Arguments

Among the new features added in Java 5.0, Variable Arguments (var-args) is one of the coolest features. Before getting into this, let us see the reason in action for introducing such a feature like this. The following code snippet shows the addition of two numbers being done in the testAdd() method.

VariableArgumentsTest.java

package varargs;

public class VariableArgumentsTest
{
	static void addTest(String message, int a, int b)
	{
		int result = a + b;
		System.out.println(message + result);

	}

	public static void main(String[] args)
	{
		addTest("Addition Result is ", 10, 20);
	}
}

Consider that we want the addTest() method to add three numbers. Now, we introduce a third parameter called c in the method definition like this,

static void addTest(String message, int a, int b, int c)
{
	int result = a + b + c;
	...
}

Or we can have an overloaded method that is defined with three parameters and have the original implementation there. If the number of parameter values that are going to be passed for the addTest() method goes on increasing, then it requires change in the existing code or possibly the addition of new overloadeded methods. The way to get over this is by using a variable arguments. Internally a variable argument is maintained as an array that can hold zero or one or more arguments of the same type. Following code snippet shows the declaration of variable arguments.

static void addTest(String message, int... numbers)
{
	int result = 0;
	for(int num : numbers)
	{
		result = result + num;
	}
	return result;
}

Note that the type (int) is followed by three dots (often called ellipsis) and then the variable argument name. With such a declaration in hand, it is now possible to invoke the method as shown below.

addTest("Addition Ressult", 10, 20);     -> addTest("Addition", new int[]{10,20});
addTest("Addition Ressult", 10, 20, 30); -> addTest("Addition", new int[]{10,20, 30});
addTest("Addition Ressult");             -> addTest("Addition", new int[]{});

All the above styles are allowed as they are internally represented as arrays. There are two major constraints in the usage of variable arguments. The first thing is a method is allowed to carry only one variable argument type. The other constraint is that a variable argument type can appear only as the last parameter in a method definition. The following shows the legal and illegal usage of variable argument types.

static void test(int... a, String... b) -> Invalid, more than one variable argument type.
static void test(int... a, int... b)    -> Invalid, more than one variable argument type.
static void test(int... a, int b, int c)-> Invalid, Variable argument type must be the last parameter.
static void test(int a, int... b, int c)-> Invalid, Variable argument type must be the last parameter.
static void test(int a, int... b)       -> This is legal.
static void test(int... a)              -> This is also legal.

4) Static Imports

Static Imports is all about importing all the static Entities – like static classes, static methods and static objects and directly accessing them in code. For example, let us consider that you have a class like this,

StaticTest.java

package staticimport;

public class StaticTest
{
	public static final Object STATIC_OBJECT = new Object();

	public static Object getStaticObbject()
	{
		return STATIC_OBJECT;
	}

	public static class StaticClass
	{

	}
}

The above class is in a package called staticimport and it has a public static object called STATIC_OBJECT, a static method called getStaticObject() and a static inner class called StaticClass. Now let us see how to make use of static imports for accessing these static objects directly. Consider the following client program,

StaticTestClient.java

package staticimport.client;

import static staticimport.StaticTest.StaticClass;
import static staticimport.StaticTest.getStaticObbject;
import static staticimport.StaticTest.STATIC_OBJECT;

public class StaticTestClient {

	public static void main(String[] args) {

		System.out.println("Usage of a static class");
		StaticClass staticClassObject = new StaticClass();

		System.out.println("Usage of a static method");
		Object fromAStaticMethod = getStaticObbject();

		System.out.println("Usage of a static object");
		Object someStaticObject = STATIC_OBJECT;

	}
}

If you note the syntax of static imports, the static keyword follows after the import keyword. Only Static classes, static methods and static objects can be imported in this manner. Suppose, if you try to import a type that is not static, then the compiler will warn you telling that “The import cannot be resolved”, though it should give a descriptive warning telling that the type you are trying to import something which is not static.

Following example makes use of the APIs in the java packages. More specifically it imports all the static objects (members, objects and static classes) defined in System and Math class.

StaticTest.java

package staticimport.client;

import static java.lang.Math.*;
import static java.lang.System.*;

public class StaticTest {

	public static void main(String[] args)
	{
		gc();
		out.println("Testing static object");
		out.println("max of 10 and 20 is " + max(10, 20));
	}
}

5) Enumerations

Let us conclude this article by having a look at Enumerations (or Enums). In Java, Enum is a type, like a class or an interface. If Classes are used to represent objects, interfaces for behavior, then Enumerations are used to define range-based constants. For example, consider the following class that will calculate the population of a country when given the country name.

PopulationCalculator.java

package enums;

public class PopulationCalculator
{
	public static double calculatePopulation(String countryName)
	{
		double population = 0.00;

		if(countryName.equals("India"))
		{
			// Set Indian population here.
		}else if (countryName.equals("Australia"))
		{
			// Set population for Aussies here.
		}else if (countryName.equals("England"))
		{
			//Set population value for England here.
		}
		return population;
	}
}

The problem in the above code is with the input parameter countryName. Since the countryName is represented as a string, care should be taken in the very first line to ascertain the availability of such a country. What if the client passes something like “ABCDEF” or an empty string (“”) or even null for the country name? In all these cases, we end up in some kind of un-expected results at the run-time. We would feel that it would be better if the same error is captured during the compile-time itself. Here comes the concept of Enum which is any other type like Object, String or some other thing.

Following is the declaration of Enum called Country which takes the possible values of India, Australia and England.

Country.java

package enums;

public enum Country
{
	INDIA,

	AUSTRALIA,

	ENGLAND,

}

The keyword enum precedes the name of the Enum, in this case Country. Note that declaration of the various country names like India, Australia and England separated by commas. Internally, an Enum is represented by a class and the objects within it will be treated as public, static and final. So the above Country enum will internally look like this,

Country.java

package enums;

public class Country extends java.lang.Enum
{
	public static final Country INDIA = new Country();

	public static final Country AUSTRALIA = new Country();

	public static final Country ENGLAND = new Country();

}

Note that by default all the Enum classes extends java.lang.Enum class. And the restriction is that they cannot be extended. So Enums are implicitly treated as final classes, even though they can implement Interfaces. Now, let us modify the above Population Calculator class to make use of Country Enum instead of a string. Following is the code for the same.

PopulationCalculator.java

package enums;

public class PopulationCalculator
{
	public static double calculatePopulation(Country country)
	{
		double population = 0.00;

		if(country.equals(Country.INDIA))
		{
			// Set Indian population here.
		}else if (country.equals(Country.AUSTRALIA))
		{
			// Set population for Aussies here.
		}else if (country.equals(Country.ENGLAND))
		{
			//Set population value for England here.
		}
		return population;
	}
}

Now, since the calculatePopulation() method is accepting a type Country which is of type Enum, the client can pass only any of the defined Object in the Enum, thereby ensuring type-safeness. Since all custom Enum classes extend java.lang.Enum class, some of the useful methods like Enum.values() and Enum.ordinal() are automatically available to the Country Enum class. Have a look at the following sample class.

EnumTest.java

package enums;

public class EnumTest {

	public static void main(String[] args) {

		Country[] countries = Country.values();

		for(Country country : countries){
			System.out.println(country.toString() + ":
				Oridinal Value->" + country.ordinal());
		}

}

The call to Country.values() will return an Array of Country values with the values defined within the Country Enum. The method Country.ordinal() will return an index that tells the position of the enum object.

6) Conclusion

This article covered some of the new features available in Java 5.0 like Enhanced For loop, Variable Arguments, Static Imports and Enumerations along with plenty of samples. Each of these new features finds its appropriate usage based on the requirements. Applications can make use of the new features in an optimal way and thereby ensure that the code is simple and efficient.

Javabeat has published many of the good articles related to Java 1.5 version. This list will help you to learn some of the notable features introduced with the version 1.5, please have a look on these articles when time permits. Don’t forget to leave your feedback on the comments section. This helps us to provide better content for you.

• Autoboxing in Java 5.0
• Annotations in Java 5.0
• Generics in Java 5.0
• How to use enum in switch?

The above article would provide the higher level of understanding on each concept. There are many other great features introduced in the Java 1.5 version. If you would like to know all the features in detail, please buy Java Complete Reference, which is the most popular book and released first when this version is announced. Hope this helps you!!

If you would like to receive future mails on Java articles, please subscribe here.

In the latest version of J2SE 5.0 released by Sun, Autoboxing is one of the new feature. Before J2SE 5.0, working with primitive types required the repetitive work of converting the primitive types into wrapper classes and vice – versa. Sometimes the purpose of conversion is just for some API call, after which the results have to be converted into original form which is very frustrating . Auto-boxing and Auto-Unboxing enables the primitive types to be converted into respective wrapper objects and the other way around.This article gives some insight about the importance of this new feature and how it can be used in the real-world programming. The following are some of the popular books available for learning Java 1.5

• Java 1.5 Tiger: A Developer’s Notebook
• Java Cookbook

2)Boxing/Unboxing

Let’s take a small example of incrementing the value of Integer Object for understanding the concept of Boxing/Unboxing.

Before Java 5
int intPrimitive = intObject.intValue();
intPrimitive++;
intObject = new Integer(intPrimitive);

Using Java 5

Integer intObject = new Integer(10);
intObject++;

The output for the above examples will be same. In the first example we are creating an Integer object, unwrapping it to primitive value,
incrementing the primitive value, re-wrapping it to Integer object again.

In the second example when the compiler encounters the line intObject++ compiler unwraps Integer object to primitive type, increments it and rewraps to Integer Object again,So When the compiler got to the line intObject++; it substitues the code which will be something like this:

Integer.valueOf(intObject.intValue()+1);

	or

	int intPrimitive = intObejct.intValue();
	intPrimitive++;
	intObject = new Integer(intPrimitive);

Below example’s show different ways of Boxing/Unboxing.

Boolean isValid = false;		// Boxing

		Short shortObject = 200;	        // Boxing

		if(shortObject list = new ArrayList();
	          for(int i = 0; i < 10; i++){
        	     list.add(i); 		       // Boxing
          	}

3)How Overloading works for Boxing/Unboxing ?

• General Rule: Arguments are implicitly widened to match method parameters.

Lets assume that we are having a function which takes an int as paratmeter.

public void testWidening(int i){
	// Business Logic
	}

	byte b = 25;
	testWidening(b);

Now instead of passing int as an argument if we pass byte or short as arguments then these arguments are implicitly widened to match the testWidening method that takes an int.

Overloading with Boxing

Scenario 1: overloaded functions which take int and Integer as parameters.

void testWidening(int j){
	    	System.out.println("method call for primitive int");
    	    }
   	    void testWidening(Integer k){
		System.out.println("method call for Integer Object");
    	    }

	    int i = 30;
            new Test().testWidening(i);

           O/P: method call for primitive int

Pretty straight forward output, int is passed as an argument and the function which is taking int as parameter has been invoked.

Scenario 2: overloaded functions which take long and Integer as parameters.

void testWidening(long j){
 	    	System.out.println("method call for primitive long");
	    }
	    void testWidening(Integer k){
	    	System.out.println("method call for Integer Object");
	    }

	    O/P: method call for primitive long

Since pre-existing/older versions of code should function the way it used to be, the compiler will always choose the older conversion of widening rather then the new one.Here the function which takes long as a parameter is choosen over the function which takes Integer as a parameter.

Scenario 3: overloaded functions which take Long and Integer as parameters.

void testWidening(Long j){
 	   	System.out.println("method call for Long Object");
	    }
	    void testWidening(Integer k){
	    	System.out.println("method call for Integer Object");
	    }
	    O/P: method call for Integer Object

As expected now the method which is taking Integer object as parameter has been called over the method which is taking Long object as parameter.

Scenario 4: overloaded functions which take int and long as parameters and argument is an Integer object.

void testWidening(int i){
        		System.out.println("in int method");
    		}
    		void testWidening(long j){
        		System.out.println("in long method");
    		}

        	new Test().testWidening(new Integer(10));

		O/P: in int method

The above example shows how Unboxing is done in Java 5. Here we are passing Integer object as an argument and the method which takes int as parameter has been invoked.

Widening Reference Variables

class Shape{
        	//common methods
    	}
	public class Rectangle extends Shape{
    		public void testWidening(Shape s){
	        	System.out.println("Here I am");
    		}
		public static void main(String a[]){
		    Rectangle r = new Rectangle();
		    r.testWidening(r);
    		}
	}
	O/P: Here I am

Here the testWidening method needs Shape object, and Rectangle IS-A Shape. Now let’s look this example.

void testWidening(Long i){
        	System.out.println("method call for Long Object");
    	}
    	public static void main(String a[]){
        	test t = new test();
        	t.testWidening(new Integer(10));
    	}
	O/P: Compile Time Error

It’s not legal to widen from one wrapper class to another, The reason is all the wrapper classes like BigDecimal, BigInteger, Byte, Double, Float,Integer, Long, Short extend Number class and its not valid to say Integer IS-A Long.

3)How ==, !=, <=, >= works for Boxing/Unboxing ?

Let’s look at the below example’s.

• Example for ==

Integer intObject1 = 100;
        Integer intObject2 = 100;
        Integer intObject3 = 128;
        Integer intObject4 = 128;

        if(intObject1 == intObject2)
            System.out.println("intObject1 and intObject2 are equal");
        else
            System.out.println("intObject1 and intObject2 are not equal");

         if(intObject3 == intObject4)
            System.out.println("intObject3 and intObject4 are equal");
        else
            System.out.println("intObject3 and intObject4 are not equal");

	O/P: intObject1 and intObject2 are equal
	     intObject3 and intObject4 are not equal

General guess would be false in both cases.

Here there is a difference in the output’s of two if statements because in order to save memory when primitive types are boxed into the wrapper types, the JVM allocates memory and creates a new object. But for some special cases, the JVM reuses the same object, two instances of the following wrapper objects will always be == when their primitive values are the same.

• Boolean
• Byte
• Character from \u0000 to \u007f (7f is 127 in decimal)
• Short and Integer from -128 to 127

• Example for !=

if(intObject1 != intObject2)
            System.out.println("intObject1 and intObject2 are not equal");
        else
            System.out.println("intObject1 and intObject2 are equal");
        if(intObject3 != intObject4)
            System.out.println("intObject3 and intObject4 are not equal");
        else
            System.out.println("intObject3 and intObject4 are equal");
	O/P:
	intObject1 and intObject2 are equal
	intObject3 and intObject4 are not equal

The ouput is as expected, Since the values of intObject1 and intObject 2 are below 128, they are considered as equal and intObject3 and intObject4 are considered as not equal.

• Example for <= and >=

Integer intObject1 = 100;
        Integer intObject2 = 101;
        Integer intObject3 = 128;
        Integer intObject4 = 129;

        if(intObject1  intObject2");
        if(intObject4 >= intObject3)
            System.out.println("intObject4 is >= intObject3");
        else
            System.out.println("intObject4 is < intObject3");
	O/P:
	intObject1 is = intObject3

This time we have changed 2nd and 4th declarations from Integer to Int still the output is the same.

Integer intObject1 = 100;
        int 	intObject2 = 101;
        Integer intObject3 = 128;
        int 	intObject4 = 129;

        if(intObject1  intObject2");
        if(intObject4 >= intObject3)
            System.out.println("intObject4 is >= intObject3");
        else
            System.out.println("intObject4 is < intObject3");
	O/P:
	intObject1 is = intObject3

Conclusion

This new feature in J2SE 5.0 has both advantages and disadvantages, it all depends on where and how are we using the feature. It is recommended by SUN to use them only when there is an “impedance mismatch” between reference types and primitives, for example, when you have to put numerical values into a collection. It is not appropriate to use autoboxing and unboxing for scientific computing, or other performance-sensitive numerical code. An Integer is not a substitute for an int; autoboxing and unboxing blur the distinction between primitive types and reference types, but they do not eliminate it.

Javabeat has published many of the good articles related to Java 1.5 version. This list will help you to learn some of the notable features introduced with the version 1.5, please have a look on these articles when time permits. Don’t forget to leave your feedback on the comments section. This helps us to provide better content for you.

• New features in Java 5.0
• Annotations in Java 5.0
• Generics in Java 5.0
• How to use enum in switch?

The above article would provide the higher level of understanding on each concept. There are many other great features introduced in the Java 1.5 version. If you would like to know all the features in detail, please buy Java 1.5 Tiger: A Developer’s Notebook, which is the most popular book and released first when this version is announced. Hope this helps you!!

If you would like to receive future mails on Java articles, please subscribe here.

Buy Java Generics from FlipKart.com (Java Generics and Collections covers everything from the most basic uses of generics to the strangest corner cases. It teaches you everything you need to know about the collections libraries, so you’ll always know how and when to use each collection for any given task.)

2) Java Annotations

2.1) Introduction

Java, being a wonderful object-oriented language provided support for Annotations starting from 5.0. This feature was added to Java 5.0 as a result of the JSR 175 namely “A Metadata Facility for the JavaTM Programming Language”. Annotations in Java can be seen elsewhere in a program. It can be seen in class declaration, method declaration, field declaration etc. The added Annotation to Java Elements have proven themselves to be considerably useful in many instances. Consider the following class definition,

Employee.java

final class Employee
	{
		private String name;
		private String id;

		// Getters and setters for Employee class.
	}

The above is a definition of a class, Employee. It can be noted that the class declaration is preceded with the final keyword which tells that this class cannot be sub-classed. So, the introduction of the final keyword adds some additional information (or adds some constraints) over the class definition telling that no other class in the word can extend the Employee class. Therefore, the final keyword forms a part in providing meta-data information in the class definition. So, this is one variation of Annotation. Annotations are generally a way to add meta-data information to an element (an element can be a class, method, field, or anything) and these meta-data are processed by the tools (compilers, javadoc, etc.). Annotations are differentiated from other elements like class, interface etc., by preceding an '@' symbol before it.

An annotation definition looks like the following,

TestAnnotation.java

public @interface TestAnnotation
	{
		// Property Definition here.
	}

Don’t get confused with the interface keyword. It has nothing to do with annotations. '@' along with interface is the start of the annotation definition and TestAnnotation in the above case is the name of the Annotation. Whether annotations can be applied to class (a class-level annotation), or a method (method-level annotation) or a field (field-level annotation) is specified in the declaration of the annotation itself. This is referred to as Annotating an Annotation itself.

The Meta-Annotations that would be covered in the forthcoming sections are,

• Target Annotation
• Retention Annotation

2.2) Target Annotation

For example, if the case is that @TestAnnotation annotation can only be applied to methods, then there is a Meta-Annotation (meta-data about meta-data) which tells for which element type this annotation is applicable. For example, the following is the declaration of the @TestAnnotation annotation along with some meta-data that states the elements that this annotation can be applied to.

TestAnnotation.java

@Target(ElementType.METHOD)
	public @interface TestAnnotation
	{
		// Property Definitions here.
	}

From the above, we can see that the Annotation @TestAnnotation is annotated with @Target. This kind of Annotation Chaining is always possible. The target element tells that the @TestAnnotation annotation can be applied only to methods and not to any other element types. The argument to @Target Annotation can be one from the possible set of values of any Java Element, which is defined in a well-defined Enum called ElementType. Here are the possible values taken by this Enum,

• TYPE – Applied only to Type. A Type can be a Java class or interface or an Enum or even an Annotation.
• FIELD – Applied only to Java Fields (Objects, Instance or Static, declared at class level).
• METHOD – Applied only to methods.
• PARAMETER – Applied only to method parameters in a method definition.
• CONSTRUCTOR – Can be applicable only to a constructor of a class.
• LOCAL_VARIABLE – Can be applicable only to Local variables. (Variables that are declared within a method or a block of code).
• ANNOTATION_TYPE – Applied only to Annotation Types.
• PACKAGE – Applicable only to a Package.

2.3) Retention Annotation

Another commonly used Meta-data for an Annotation is the Retention Policy. Assume that we have some Annotations defined in the source code. We have a mechanism through which we can say that to what extent the Annotations should be retained. The three possible ways of telling this are,

• Retain the Annotation in the Source Code only
• Retain the Annotation in the Class file also.
• Retain the Annotation Definition during the Run-time so that JVM can make use of it.

The Annotation that is used to achieve this is @Retention and it takes a possible values of SOURCE, CLASS and RUNTIME defined in RetentionPolicy Enumeration. For example, if we want to retain the @TestAnnotation information till the class file, we can define something like this,

TestAnnotation.java

@Target(ElementType.METHOD)
	@Retention(RetentionPolicy.CLASS)
	public @interface TestAnnotation
	{
		// Property Definitions here.
	}

3) Built-in Annotations in Java

There are some pre-defined annotations available in the Java Programming language. They are,

• Override
• Deprecated
• SuppressWarnings

3.1) The @Override Annotation

The syntax of the @Override annotation is as follows,

Override.java

@Retention(RetentionPolicy.CLASS)
	@Target(ElementType.RUNTIME)
	public @interface Override
	{
	}

@Override annotation essentially tells to the compiler that, whenever such an annotation is defined in a method of some class, then that method must be an overridden method. If not, then the compilers can report them as errors. Consider the following sample which explains this,

Employee.java

public class Employee
	{
		protected void startWork()
		{
			// Code that will start to do some work.
		}

		protected void endWork()
		{
			// Code to end the work.
		}
	}

Manager.java

public class Manager extends Employee
	{

		@Override
		protected void startWork()
		{
			// Code that will start to do some work.
		}

		@Override
		protected void endWork()
		{
			// Code to end the work.
		}
	}

In the above sample code, we have a class called Employee with two methods namely startWork() and endWork(). These methods have been marked as protected so that sub-classses can override them by providing their own functionality. A class, Manager is created and the methods are overriden in the sub-class. At this point, we have to note one key issue. The methods startWork() and endWork() has been annotated with @Override annotation. This tells to the compiler that the method that is annotated with @Override is an overridden method. So, the compiler immediately climbs up to the base class to find the existence of such a method. If no such method is found in the base class, then the compiler can report an error message.

The major aim of introducing this annotation @Override is to catch the errors that programmers might make when overriding a method in the sub-class. For example, consider the following sample code,

DefaultTableCellEditor.java

public class DefaultTableCellEditor implements TableCellEditor
	{
		public Component getTableCellEditorComponent (JTable table,
                                             Object value,
                                             boolean isSelected,
                                             int row,
                                             int column)
		{
			// Default functionality goes here.
		}
	}

If the functionality of the getTableCellEditorComponent() has to be overriden, then a new class has to be created by extending the DefaultTableCellEditor as shown below,

MyCustomizedTableCellEditor.java

public class MyCustomizedTableCellEditor extends DefaultTableCellEditor
	{
		public Component getTableCellEditorComponet(JTable table,
                                             Object value,
                                             boolean isSelected,
                                             int row,
                                             int column){

			// My customized functionality goes here.
		}
	}

The above code compiles and run fine, but not with the expected behavior because of the fact that when re-defining the method in the sub-class the method name has been wrongly spelled (getTableCellEditorComponet() instead of getTableCellEditorComponent()). Developers would have wasted their energy and time in debugging what was wrong with the code and why the expected behavior wasn’t the customized functionality. These kind of errors can be found at the compile-time rather than at the run-time, if the annotation @Override is applied on the re-defined method in the sub-class. If the method is annotated with @Override and if there is an mismatch in the method name or in the argument list, then the compiler will immediately report an error message like,

“The method getTableCellEditorComponet of type ‘MyCustomizedTableCellEditor’ must override a super-class method”.

3.2) The @SuppressWarnings Annotation

With the concept of Generics starting from Java 5.0, references to any of the Collection types should be parameterized. Else the compiler will issue a warning message. For example, consider the following legacy code which makes use of a raw List type,

LegacyCode.java

package builtin.suppress;

	import java.util.*;

	public class LegacyCode
	{
		public static List toList(Object[] array)
		{
			return Arrays.asList(array);
		}
	}

If the code gets compiled by using a Java 5 Compiler, then we would probably see a message something very similar to this.

“List is a raw type. References to generic type List<E> should be parameterized”.

The compiler suggests not to use raw type for Collection without being parameterized with some type. For getting rid of this warning message, one can define the return type like List<Object> thereby making the compiler happy. Assume the case of legacy projects when its get compiled by a Java 5.0 compiler. We can see numerous of warning like this. It is highly impossible to go and fix everywhere. Consider the case where a project is depending on a third-party library, in which case the dependant source code cannot be changed. The solution for this problem is to make use of @SuppressWarnings Annotation. The following shows the definition of a Suppress Warning Annotation,

SuppressWarnings.java

@Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE})
	@Retention(RetentionPolicy.SOURCE)
	public @interface SuppressWarnings
	{
		String[] value();
	}

Note that Suppress Warnings can be used on various Java elements like Class/Interface, Method, Constructor etc. When applied on any of the Java Elements along with a value, it provides a hint to the Compiler to turn-off the warnings. Consider the following code,

@SuppressWarnings("unchecked")
	public static List toList(Object[] array)
	{
		return Arrays.asList(array);
	}

The above code provides a hint to the compiler to suppress the unchecked warnings. Following is another example of Suppress Warnings. We know that it is a good practice to provide a Serial Version Identifier for a class that implements the Serializable interface. Consider the following code,

LegacyCode.java

package builtin.suppress;

	import java.io.Serializable;
	import java.util.*;

	public class LegacyCode implements Serializable
	{
		@SuppressWarnings("unchecked")
		public static List toList(Object[] array)
		{
			return Arrays.asList(array);
		}
	}

The compiler will warn saying that for a Serializable class, there should be a definition of Serial Version Identifier like this :”The serializable class LegacyCode does not declare a static final serialVersionUID field of type long”. This can be suppressed (although its not a good practice) by using the following Annotation.

LegacyCode.java

@SuppressWarnings("serial")
	public class LegacyCode implements Serializable
	{

	}

Note that in the above case the Annotation is applied in the class-level.

3.3) The @Deprecated Annotation

The Interfaces and the Classes in an Application get updated every now and then. Interfaces used by the Clients may undergo so many revisions in the form of new methods being added and existing methods being removed or updated. Imagine the case where a method defined in a class or an interface has now become obsolete and we should warn the Client Applications not to make use of them. One dangerous way is to remove the method itself from the Interface. But this solution has a huge impact on the code that is dependant on this interface. Another elegant way is to mark the old method as deprecated which informs the client not to use this method anymore because in the future versions this old method may not be supported. Clients may prepare themselves not to depend on the old method anymore.

For example, consider the following code,

MyOldClass.java

package builtin.deprecated;

	public class MyOldClass
	{
		/**
		* This method has become obsolete. Client Applications now can
		* depend on
		* {@link #myAlternativeMethod()} to achieve the same affect.
		*/
		@Deprecated
		public void myDeprecatedMethod()
		{
			// Obsolete code here.
		}

		public void myAlternativeMethod()
		{
			// Revised code here.
		}
	}

The class MyOldClass has a method myDeprecatedMethod() which is tagged as Deprecated. Now if any of the Client code tries to access this method, then the following warning message is issued by the compiler.

“The method myDeprecatedMethod() from the type MyOldClass is deprecated”.

It is always nice to mention the alternate ways in the JavaDoc itself. For example, the JavaDoc for myDeprecatedMethod() method suggests to use the method myAlternativeMethod() as an alternative.

4) User-defined Annotations

In this section, we shall see how to annotate objects that we may come across in day-to-day life. Imagine that we want to persistent object information to a file. An Annotation called Persistable can be used for this purpose. An important thing is that we want to mention the file in which the information will get stored. We can have a property called fileName within the declaration of Annotation itself. The definition of the Persistable Annotation is given below,

Persistable.java

@Target({ElementType.FIELD, ElementType.LOCAL_VARIABLE})
	public @interface Persistable
	{
		String fileName();
	}

Note that we have specified the target for this Annotation as Field and Local variable meaning that this Annotation can be applicable only to Java Fields and Local variables. Also note how the property fileName for this Annotation is defined. The type (String, in this case) followed by the property name which looks like a method definition fashion.

Having defined this Annotation, let us see how to apply this Annotation on Java Elements. Consider the following code snippet,

@Persistable(fileName = "movies.txt") Movie movie;

The above code tells to save all the information about the Movie object to the file called movies.txt. But who will do this operation? We haven’t defined any code that will do this operation. Generally Annotations are interpreted by Tools and once Tools read these Annotation informations, they will perform the required operation. If we want to give default values to a property, then we should follow the strange syntax.

Persistable.java

@Target({ElementType.FIELD, ElementType.LOCAL_VARIABLE})
	public @interface Persistable
	{
		String fileName() default "defaultMovies.txt";
	}

In this case, if the clients didn’t supply a value to the fileName property, then the default value defaultMovies.txt is taken. Now let us see the syntax of specifying multiple values to a property. Let us assume that we want to save the status of the object in multiple files in which case we should have declared an array to hold the filenames.

Persistable.java

@Target({ElementType.FIELD, ElementType.LOCAL_VARIABLE})
	public @interface Persistable
	{
		String[] fileNames();
	}

And now Clients can given multiple file entries using the traditional array syntax like this,

@Persistable(
		fileNames = {
			"movie1.txt", "movie2.txt", "movie3.txt"} )
	Movie movie;

5) Reflecting the Annotation Information

5.1) Introduction

In this section, let us see how to query for information related to Annotation types using Reflection. As we all know, Java Reflection API is used to dynamically discover information (meta-data information too) for any type of Java Element like Class, Interface, Field, Method, Constructor etc. From Java 5.0 onwards, the Reflection API has been extended to add support for Annotation types too.

A new interface called Annotated Element (AnnotationElement) has been added to the java.lang.annotation package. This interface is primarily used to tell that the element in consideration is an Annotation Element which means that all the existing classes/interfaces like java.lang.Package, java.lang.Class, java.lang.reflect.Constructor, java.lang.reflect.Field and java.lang.reflect.Method implement the AnnotationElement interface. Following are the useful methods available in the AnnotationElement interface,

• Boolean isAnnotationPresent(Class) – This method will return true if the annotation type (which is passed as an argument) is present in the calling element object.
• Annotation getAnnotation(Class) – When given an Annotation class on the calling element, gives the corresponding Annotation object.
• Annotation[] getAnnotations() – Returns an array of Annotations that are present on the calling object.

5.2) Example Program

Let us look into a simple example program that makes use of the new interfaces and the methods to query for Annotation information at run-time. For this example, let us define two Annotation types as follows. One is the Author Annotation and the other is the Version Annotation. This is a very common piece of meta-information that can be given to any Java file (or any other type of file).

Author.java

package reflections;

	import java.lang.annotation.*;

	@Target(value = {ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.TYPE})
	@Retention(RetentionPolicy.RUNTIME)
	public @interface Author
	{
		String name() default "unknown";
	}

Note the definition of the Author annotation. This is a single-valued Annotation meaning that this Annotation has a single property called name. Also make a note of the Target Annotation. The presence of Target Annotation tells that Author Annotation can only be applied to Java elements like Constructor, Method and Type (Class/Interface). Another important thing to note is the Retention for this Annotation is set to Run-time because we want this Annotation information to be available to the JVM while the program is running. The name property is also given a default value unknown if the consuming Application fail to provide an explicit value.

Following is the definition of the Version Annotation. It looks exactly the same as Author Annotation except the fact that it has a property called number (which is of type double) to hold the version value.

Version.java

package reflections;

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

	@Target(value = {ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.TYPE})
	@Retention(RetentionPolicy.RUNTIME)
	public @interface Version
	{
		double number();
	}

Let us have a look at the following class definition that makes use of the above declared Annotations. The Annotations are applied at the class-level as well as in the method-level.

AnnotatedClass.java

package reflections;

	@Author(name = "Johny")
	@Version(number = 1.0)
	public class AnnotatedClass
	{
		@Author(name = "Author1")
		@Version(number = 2.0f)
		public void annotatedMethod1()
		{
		}

		@Author(name = "Author2")
		@Version(number = 4.0)
		public void annotatedMethod2()
		{
		}
	}

This program makes use of the new API to read the Annotation related information that are applied on various Java Elements. The utility method readAnnotation() takes a parameter of type AnnotationElement which can represent a Class, method or Constructor. Then it queries for a list of Annotations of that particular element by calling the getAnnotations() method. Then the array is iterated to get the individual element, then made a downcast to extract the exact information – Author.name() and Version.number().

AnnotationReader.java

package reflections;

	import java.lang.annotation.Annotation;
	import java.lang.reflect.AnnotatedElement;
	import java.lang.reflect.Method;

	public class AnnotationReader
	{
		public static void main(String args[]) throws Exception
		{
			Class<AnnotatedClass> classObject = AnnotatedClass.class;
			readAnnotation(classObject);
			Method method1 = classObject.getMethod("annotatedMethod1", new Class[]{});
			readAnnotation(method1);
			Method method2 = classObject.getMethod("annotatedMethod2", new Class[]{});
			readAnnotation(method2);
		}

		static void readAnnotation(AnnotatedElement element)
		{
			try
			{
				System.out.println("\nFinding annotations on " + element.getClass().getName());
				Annotation[] classAnnotations = element.getAnnotations();

				for(Annotation annotation : classAnnotations)
				{
					if (annotation instanceof Author)
					{
						Author author = (Author)annotation;
						System.out.println("Author name:" + author.name());
					}
					else if (annotation instanceof Version)
					{
						Version version = (Version)annotation;
						System.out.println("Version number:" + version.number());
					}
				}
			}
			catch (Exception exception)
			{
				exception.printStackTrace();
			}
		}
	}

The output for the above program is as follows,

Output

Finding annotations on java.lang.Class
	Version number:1.0
	Author name:Johny

	Finding annotations on java.lang.reflect.Method
	Author name:Author1
	Version number:2.0

	Finding annotations on java.lang.reflect.Method
	Author name:Author2
	Version number:4.0

6) Conclusion

Before the advent of Annotations, Applications had to define their meta-data in some configuration files and usually these meta-data were externalized from the Application. Now, they can directly define this meta-data information in the source code. The concept of Annotating elements in Java is gaining much popurality because of its robustness and simplicity of usage. When effectively applied on Java elements, Annotations can be of great use.

7) Reference Books

Buy from FlipKart.com or Amazon.com

The foreword to this new O’Reilly series explains that a “Developer’s Notebook” is the raw scribbling of an “Alpha Geek” as he or she examines some exciting new technology. That pretty much describes “Java 1.5 Tiger.” It’s raw, it’s scribbling, and it’s exciting nonetheless.

Buy from FlipKart.com or Amazon.com

Concurrency, in the form of threads, has been present in the Java language from its beginning, and this book is all about concurrency in the current and future versions of Java with an emphasis on writing practical code. This book does for concurrent programming in Java what Geary’s series of books did for graphical Java – it moves concurrent Java programming out of the realm of applets containing bouncing balls and into that of providing real solutions for professional programmers. (read our review)