1) Introduction

JAXB (Java API for XML Binding) technology which was included as part of JWSDP (Java Web Services Developer Pack) before, is now included with the Mustang Distribution. Simply put, it is a Mapping Technology for Java and XML Documents. Using JAXB, one can Generate XML Documents from Java Objects and also they can Construct Java Objects from one or more XML Documents. In JAXB terms, Marshalling refers to the process of converting a Java Object to a XML Document and Un-Marshalling is the reverse of Marshalling which is simply getting a Java Object from one or more XML Documents.

Let us see along with Samples how to work with Marshalling and Un-Marshalling with JAXB.

also read:

• Introduction to Java 6.0 New Features, Part–2
• What is new in Java 8.0?

2) Generating XML Documents from Java Objects

Assume that you want to have a XML Representation of a Java object. Using JAXB Marshalling you can do with much ease and the following Sample Application illustrates the same,

Person.java

package net.javabeat.articles.java6.newfeatures.jaxb;

import java.util.Date;
import javax.xml.bind.annotation.XmlAttribute;
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement()
public class Person {

    private String name;
    private int age;
    private Date dateOfBirth;
    private String type;

    public Person(){
    }

    public Person(String name, int age, Date dateOfBirth, String type) {
        this.name = name;
        this.age = age;
        this.dateOfBirth = dateOfBirth;
        this.setType(type);
    }

    @XmlElement()
    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    @XmlElement()
    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }

    @XmlElement()
    public Date getDateOfBirth() {
         return dateOfBirth;
    }

    public void setDateOfBirth(Date dateOfBirth) {
        this.dateOfBirth = dateOfBirth;
    }

    @XmlAttribute()
    public String getType() {
        return type;
    }

    public void setType(String type) {
        this.type = type;
    }
}

The above Person class has various properties namely ‘name’, ‘age’, ‘dateOfBirth’ and ‘type’ and objects of this Class are the targets we wish to Marshal. The Person class is annotated with @XmlRootElement since we want the name of the Class to be the Root Node. We want ‘name’, ‘age’, and ‘dateOfBirth’ as Child Elements so it has been tagged with @XmlElement. Since we want ‘type’ to appear as an Attribute we had tagged that as @XmlAttribute.

Java2XML.java

package net.javabeat.articles.java6.newfeatures.jaxb;

import java.io.FileWriter;
import java.util.*;
import javax.xml.bind.*;

public class Java2XML {

    public Java2XML() {
    }

    public static void main(String args[]) throws Exception{
        JAXBContext context = JAXBContext.newInstance(Person.class);
        Marshaller marshaller = context.createMarshaller();
        marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);

        Person person = new Person(
            "Anonymous", 32, new Date(1970, 1, 10), "employee");
        marshaller.marshal(person, new FileWriter(".\\src\\Person.xml"));
    }
}

JAXBContext serves as the Entry Point for making use of the JAXB API. It is initiated by the list of Class objects whose objects want to be represented as XML Documents. Then an instance of Marshaller is created by calling JAXBContext.createMarshaller() method. The Java object of type Person is marshalled into the XML Document by calling the Marshaller.marshall() method. Since we want the XML Document to look Well-indented, we have set the property Marshaller.JAXB_FORMATTED_OUTPUT to true.

A file named Person.xml would have got generated and following is the listing of that file,

Person.xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<person type="employee">
    <age>32</age>
    <dateOfBirth>1970-01-10 T00:00:00+05:30</dateOfBirth>
    <name>Anonymous</name>
</person>

3) Representing Java Objects from XML Documents

In the previous section, we saw how to generate an XML Document from a Java Object. Now, let us see the Unmarshalling process here. As mentioned, Unmarshalling is the process of representing Java Objects from a XML Document. The process of Unmarshalling is a bit complicated as so many steps are involved. Let us break the steps one by one in greater detail.

3.1) Creating the XML Schema Definition File

If Java Classes represent the templates wherein objects can be created for a particular type, then in XML World, it is the XML Schema Definition File through which XML Document Instances can be instantiated. The first thing before creating a XML Document is to create a XML Schema and then to attach the Schema to a XML Document Instance. Let us look into a sample XML Schema File called Items, which will contain a list of ‘Item’ Elements along with its ‘Name’ and ‘Price’. Following is the listing of that File.

Items.xsd

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">

<xs:element name="Items">
    <xs:complexType>
        <xs:sequence>
            <xs:element maxOccurs="unbounded" ref="Item"/>
        </xs:sequence>
    </xs:complexType>
</xs:element>

<xs:element name="Item">
    <xs:complexType>
        <xs:sequence>
            <xs:element ref="Name"/>
            <xs:element ref="Price"/>
        </xs:sequence>

        <xs:attribute name="id" use="required" type="xs:NCName"/>
    </xs:complexType>

</xs:element>
    <xs:element name="Name" type="xs:string"/>
    <xs:element name="Price" type="xs:string"/>
</xs:schema>

The above is the XML Schema Definition File which represents a list of Items. Since ‘Items’ element contain a list of Item elements and ‘Item’ element in turn contains both ‘Name’ and ‘Price’ Element, both these elements are Composite Elements and the same is represented by complexType elements.

3.2) Generating Java Files from the Schema Definition Files

Now, its time to generate the Java Source Files from this XML Schema Definition File. Mustang comes with a Utility called xjc (which stands for XML to Java Compiler) which generates Java Source Files when given a XML Schema File. Xjc is nothing but a bat file location in the bin directory of the Java 6 Installation Path. Run the following command to generate the Java Source Files.

xjc –p net.javabeat.articles.java6.newfeatures.jaxb Items.xsd

The only argument to xjc is the name of the XML Schema File which is represented by Items.xsd and the ‘-p’ option specifies the package to which the generated Java Files have to be associated. This results is the generation of the following source files.

Item.java

package net.javabeat.articles.java6.newfeatures.jaxb;

import javax.xml.bind.annotation.*;
import javax.xml.bind.annotation.adapters.*;
import net.javabeat.articles.java6.newfeatures.jaxb.*;

@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "", propOrder = {
    "name",
    "price"
})
@XmlRootElement(name = "Item")
public class Item {

    @XmlElement(name = "Name")
    protected String name;
    @XmlElement(name = "Price")
    protected String price;
    @XmlAttribute(required = true)
    @XmlJavaTypeAdapter(CollapsedStringAdapter.class)
    protected String id;

    public String getName() {
        return name;
    }

    public void setName(String value) {
        this.name = value;
    }

    public String getPrice() {
        return price;
    }

    public void setPrice(String value) {
        this.price = value;
    }

    public String getId() {
        return id;
    }

    public void setId(String value) {
        this.id = value;
    }
}

This file is just a Data file for the corresponding ‘Item’ element which contains getter and setter methods with properly instructed Annotations. Note that the two sub-elements namely ‘name’ and ‘type’ has been tagged with @XmlElement Annotation and the attribute ‘id’ has been tagged with @XmlAttribute Annotation.

Items.java

package net.javabeat.articles.java6.newfeatures.jaxb;

import java.util.*;
import javax.xml.bind.annotation.*;
import net.javabeat.articles.java6.newfeatures.jaxb.*;

@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "", propOrder = {
    "item"
})
@XmlRootElement(name = "Items")
public class Items {

    @XmlElement(name = "Item")
    protected List<Item> item;

    public List<Item> getItem() {
        if (item == null) {
            item = new ArrayList<Item>();
        }
        return this.item;
    }
}

This is the Container Class for the Item element and it just contains a getter for the Item object. Note how the list of ‘Item’ elements in the Schema Document has been mapped to List of Item (List<Item>) elements. This is the Default Mapping given by the Sun’s Reference Implementation for JAXB.

ObjectFactory.java

package net.javabeat.articles.java6.newfeatures.jaxb;

import javax.xml.bind.JAXBElement;
import javax.xml.bind.annotation.XmlElementDecl;
import javax.xml.bind.annotation.XmlRegistry;
import javax.xml.namespace.QName;
import net.javabeat.articles.java6.newfeatures.jaxb.Item;
import net.javabeat.articles.java6.newfeatures.jaxb.Items;
import net.javabeat.articles.java6.newfeatures.jaxb.ObjectFactory;

@XmlRegistry
public class ObjectFactory {

    private final static QName _Price_QNAME = new QName("", "Price");
    private final static QName _Name_QNAME = new QName("", "Name");

    public ObjectFactory() {
    }

    public Item createItem() {
        return new Item();
    }

    public Items createItems() {
        return new Items();
    }

    @XmlElementDecl(namespace = "", name = "Price")
    public JAXBElement<String> createPrice(String value) {
        return new JAXBElement<String>(_Price_QNAME, String.class, null, value);
    }

    @XmlElementDecl(namespace = "", name = "Name")
    public JAXBElement<String> createName(String value) {
        return new JAXBElement<String>(_Name_QNAME, String.class, null, value);
    }

}

As guessed from its name, this is the Factory Class for creating various elements like ‘Items’, ‘Item’, ‘Name’ and Price’. Appropriate methods are available for creating ‘Items’, ‘Item’, ‘Name’ and ‘Price’ in the form of ObjectFactory.createItems(), ObjectFactory.createItem(), ObjectFactory.createName() and ObjectFactory.createPrice() respectively.

3.3) Creating a Sample XML Document

Now let us create a Sample XML Document against the Schema Definition File Items.xsd. Following is the sample XML file called Items.xml. Note how the XML Document Instance is related with the XML Schema Definition File with the help of ‘xsi:noNamespaceSchemaLocation’ attribute.

Items.xml

<Items xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
  xsi:noNamespaceSchemaLocation='file:C:/Items.xsd'>

    <Item id="LAP001">
        <Name>Laptop</Name>
        <Price>4343$</Price>
    </Item>

    <Item id="TV001">
        <Name>Television</Name>
        <Price>433$</Price>
    </Item>

    <Item id="DVD001">
        <Name>DVD Player</Name>
        <Price>763$</Price>
    </Item>

</Items>
	

3.4) Unmarshalling the XML Document to construct the Java object

The code to Unmarshall the XML Document is given below. The code first represents a JAXBContext object by passing in a Context Path which is usually the package name where the compiled Java Class files are located. Then an Unmarshaller object is created by calling JAXBContext.createUnmarshaller() which does the unmarshalling operation by calling the Unmarshaller.unmarshall() method passing in the XML File. Then the object is iterated over the get the actual data contents from the XML File.

XML2Java.java

package net.javabeat.articles.java6.newfeatures.jaxb;

import java.io.*;
import javax.xml.bind.*;

public class XML2Java {

    public static void main(String args[]) throws Exception{

        JAXBContext context = JAXBContext.newInstance(
            "net.javabeat.articles.java6.newfeatures.jaxb");
        Unmarshaller unmarshaller = context.createUnmarshaller();
        Items items = (Items)unmarshaller.unmarshal(
            new FileReader(".\\src\\Items.xml"));
        List listOfItems = items.getItem();
        for(Item item : listOfItems){
            System.out.println("Name = " + item.getName() +
                ", Price = " + item.getPrice() + ", Id = " + item.getId());
       }
    }
}

Following is the output of the above program

Name = Laptop, Price = 4343$, Id = LAP001
Name = Television, Price = 433$, Id = TV001
Name = DVD Player, Price = 763$, Id = DVD001 

4) Conclusion

This article covered the leftover features of the Part I New features of Java 6. Starting with Pluggable Annotation Processing API, it covered what Annotations are, then guided us how to write Custom Annotations and Custom Annotation Processor. Then it traversed over the Cursor API and the Event Iterator API of StaX such as how to read XML Documents along with well-defined samples. Finally through Java API for XML Binding, it details how to map Java and XML Documents with some sample applications.

Java Database Connectivity allows Application Programs to interact with the Database to access the Relational Data. JDBC provides the Pluggable Architecture wherein any type of Java Compliant Drivers can be plugged-in even during the run-time. The JDBC API provides functionality to establish Connection to the back-end Database session which can execute the Queries to get the Results. The new version of JDBC that comes along with Mustang (Java 6.0) is JDBC 4.0. JDBC 4.0 is one of the areas that were great affected with the new set of features. Let us look into the major features one by one. The specification of the JDBC 4.0 is maintained under JSR 221.

There about twenty features are introduced in the JDBC 4.0. The overall features can be categorize under the following four topics:

1. Driver and connection management
2. Exception handling
3. Data type support
4. API changes

In this article we explore some of the features mostly used by the programmers. If you have any questions, please post it in the comments section.

• Introduction to Java 6.0 New Features, Part–1
• Introduction to Java 6.0 New Features, Part–2
• What is new in Java 8.0?

2) No need for Class.forName(“DriverName”)

Before the advent of JDBC 4.0, Application Programmers have to manually load the Database Driver before making any Database Calls. The following code shows how to load a Database Driver before JDBC 4.0

Class.forName("FullyQualifiedNameOfTheDriverClass");

This has one major dis-advantage. Suppose if the Database Driver Vendor wishes to change the class name of the Driver, then it will result in Code change. But with the help of Service Provider Mechanism (which is available from Java 5), there is no need for the programmers to manually load the Driver. The Driver will be Loaded Automatically by the JVM if the Jar files that correspond to the Driver Class are in the appropriate class path.

Let us explain how the Service Provider Mechanism works. Two entities are of much interest in the Service Provider Mechanism. One is the Service itself which mostly contains a set of interfaces that deals with what the Service is all about and the other one is the Provider who will give a concrete and a well-defined Implementation for the Service. This Mechanism forces the Provider to package the service as a Jar which has to maintain a Directory Structure like this,

\\META-INF\\services\\FullNameOfTheService

Suppose if the JDBC Driver Provider wishes to make his implementation as a Service, then the Vendor should maintain a Directory Structure along with the file name like this,

\\META-INF\\services\\java.sql.Driver

Note that java.sql.Driver is the name of the File, and the file should contain only one entry which is the Name of the Provider Class that implements the Driver. For example, in the case of My SQL, the content of the file will be looking like the following,

File – Java.sql.Driver

com.mysql.jdbc.Driver           # Class name of the Driver

Through this mechanism, the JDBC Drivers will get Automatically Loaded by the Java Program. If there are Multiple Drivers in the Application’s class-path, then the first matching Driver will be taken into consideration and the rest of them will just be ignored.

3) Changes in Connection and Statement Interface

Certain new useful methods are added to the Connection interface. The following sections list down the commonly used methods. To check whether an Connection object is still valid/active or not, then the following method can be used,

int tenSeconds = 10;
Connection.isValid(tenSeconds);

The argument to Connection.isValid(int) is the Timeout value, which specifies the time duration the API should take to find out whether the Connection is valid. If the timeout interval exceeds, then false will be returned. A value of 0 for the time-out interval specifies an Infinite Time-out Duration.

Also there are methods for populating and retrieving the Client Information that a particular Driver supports with the help of Connection.getClientInfo() and Connection.setClientInfo(Properties) methods. Client information can also be set and retrieved individually using Connection.setClientInfo(String,String) and Connection.getClientInfo(String) methods.

The following methods are added into the Statement interface, Statement.isClosed(), Statement.setPoolable(boolean) and Statement.isPoolable(). Statement.isClosed() will return true if the Statement Object is closed by calling the Statement.close() method. By default, only PreparedStatement and CallableStatement are pooled by the Implementation. The call to Statement.setPoolable(true) will only act as a request to the Implementation to pool this Statement Object for better performance. Not all the implementations may support this feature and hence Applications should not depend on this feature always.

4) Enhanced SQL Exception Handling

Exception handling in JDBC has been enhanced a lot in JDBC 4.0. The following are the major areas where the enhancements are done.

• Iterable SQL Exception
• Concreate Sub Classes for specific SQL Exception

4.1) Iterable SQL Exception

The java.sql.SQLException now implements the Iterable<Throwable> interface which means that it can be iterated over to get the Next Set of Exceptions and can also be used in Enhanced For-Loops (available from Java 5.0). Consider the following piece of code,

try{

     // Some Database Access Code

}catch(SQLException exception){

    for(Throwable throwable: exception){
        System.out.println(throwable.getMessage());

    }
}

Before JDBC 4.0, Applications depended on SQLException.getNextException() to get the next Exception and looped over until the returned exception is not null.

try{

     // Some Database Access Code

}catch(SQLException exception){

    System.out.println(exception.getMessage());
    SQLException nextException = exception.getNextException();

    while (nextException != null){
        System.out.println(nextException.getMessage());
        nextException = nextException.getNextException();
    }
}

4.2) Concreate Sub Class for specific SQL Exception

More number of SQL Exception related Sub-Classes are added to the API which encapsulates the State of the SQL Error. In general, these Exceptions fall into 3 categories namely Transient, Recoverable and Non-Transient.

Assume that some kind of SQL Exception has occurred during the Program run-time. If again when a try is made and if there is a possibility such that the program can recover from the Exception without making any application specific change, then it is a kind of Transient Exception. This exception is represented by the java.sql.TransientException class and the following are the identified Transient Exceptions in the JDBC 4.0 API.

• SQLTimeoutException
• SQLTransactionRollbackException
• SQLTransientConnectionException

Minute variation of this Transient Exception is the Recoverable Exception which is represented by java.sql.SQLRecoverableException. Here the exception that has happened can be recovered by performing some Application Specific Recovery.

The last flavour of SQL Exception is the Non-Transient Exception and it is represented by java.sql.TransientException. It tells that an exception can never be recovered even though Infinite Number of Tries is performed by the Application Program. The following are the Exceptions available in this Category,

• SQLDataException
• SQLFeatureNotSupportedException
• SQLIntegrityConstraintViolationException
• SQLInvalidAuthorizationSpecException
• SQLNonTransientConnectionException
• SQLSyntaxErrorException

4.3) Support for SQL RowId

Most of the popular Databases support the concept of a Row Id. A Row Id is an unique Identifier which is used to identify a Row. Support for Retrieving and setting the Row Id for a row is made available from JDBC 4.0 version. For example, consider the following piece of code, which will retrieve the value of the Row Id for a particular Row.

String selectQuery = " select rowid from Employees where id ='123' ";
ResultSet resultSet = statement.executeQuery("selectQuery");
java.sql.Rowid rowId = resultSet.getRowId();

The Row Id is represented by java.sql.RowId class. Before doing any kind of manipulation on the Row Id, it is wise to check whether the under-lying Database implementation provides Support for Row Id(s), as well as the Lifetime of the Row Id objects. The life-time of the Row Id determines how long the Row Id is valid, whether the Row Id exists only for a particluar Session or for a Set of Transactions within a Session or Outside the Database Session etc. This availability can be known with the help of DatabaseMetaData like the following,

RowIdLifeTime rowIdLifeTime = DatabaseMetaData.getRowIdLifetime();

if (rowIdLifeTime != ROWID_UNSUPPORTED){
    // Row Id support is there for this Data source.
}

The returned RowIdLifeTime is an Enum which tells about the Life-Time of the Row Id object. Possible values are ROWID_UNSUPPORTED, ROWID_VALID_FOREVER, ROWID_VALID_OTHER, ROWID_VALID_SESSION, ROWID_VALID_TRANSACTION and ROWID_VALID_FOREVER.

5) Conclusion

The new existing features of JDBC 4.0 like the Automatic Driver Loading, various new methods added to Connection/Statement interface and Enhanced SQL Exception Handling are also explained.

If you are interested in buying a good book for learning JDBC API, database programming with JSDBC and Java is one of the popular book for JDBC, if you need more options, please refer our recommended java books section for the complete list of books. Hope this helps. If you are interested in receiving our future Java articles, please subscribe here.

The first part of this article listed out the major new features of Java 6 (Mustang) related to areas like Common Annotations (JSR 250), Scripting Language for the Java Platform (JSR 223) and JDBC 4.0. This article assumed that Readers have got sufficiently fair bit of knowledge in the various concepts of Java 5.0. First-time Readers of Java 6 are strongly encouraged to read the first part of this article titled “Introduction to Java 6.0 New Features, Part–I”. This article covers the left-over features of Part-I. More specifically, it will cover the Pluggabable Annotation Processing API (JSR 269), Java API for XML Binding (JSR 222) and Streaming API for XML (JSR 173).

2) Pluggable Annotation Processing API

2.1) Introduction to Annotation

Annotations have been there in the Java World from Java 5.0. Java Annotations are a result of the JSR 175 which aimed in providing a Meta-Data Facility to the Java Programming Language. It can be greatly used by the Build-time Tools and Run-time Environments to do a bunch of useful tasks like Code Generation, Validation and other valuable stuffs. Java 6 has introduced a new JSR called JSR 269, which is the Pluggable Annotation Processing API. With this API, now it is possible for the Application Developers to write a Customized Annotation Processor which can be plugged-in to the code to operate on the set of Annotations that appear in a Source File.

Let us see in the subsequent sections how to write a Java File which will make use of Custom Annotations along with a Custom Annotation Processor to process them.

2.2) Writing Custom Annotations

This section provides two Custom Annotations which will be used by a Sample Java File and a Custom Annotation Processor. One is the Class Level Annotation and the other is the Method Level Annotation. Following is the listing for both the Annotation Declarations. See how the Targets for the Annotations ClassLevelAnnotation.java and MethodLevelAnnotation.java are set to ElementType.TYPE and ElementType.METHOD respectively.

ClassLevelAnnotation.java

package net.javabeat.articles.java6.newfeatures.customannotations;

import java.lang.annotation.*;

@Target(value = {ElementType.TYPE})
public @interface ClassLevelAnnotation {
}

MethodLevelAnnotation.java

package net.javabeat.articles.java6.newfeatures.customannotations;

import java.lang.annotation.*;

@Target(value = {ElementType.METHOD})
public @interface MethodLevelAnnotation {
}

AnnotatedJavaFile.java

package net.javabeat.articles.java6.newfeatures.customannotations;

@ClassLevelAnnotation()
public class AnnotatedJavaFile {

    @MethodLevelAnnotation
    public void annotatedMethod(){
    }
}

The above is a Sample Java File that makes use of the Class Level and the Method Level Annotations. Note that @ClassLevelAnnotation is applied at the Class Level and the @MethodLevelAnnotation is applied at the method Level. This is because both the Annotation Types have been defined to be tagged to these respective Elements only with the help of @Target Annotation.

2.3) Writing a Simple Custom Annotation Processor

TestAnnotationProcessor.java

package net.javabeat.articles.java6.newfeatures.customannotations;

import java.util.*;
import javax.annotation.processing.*;
import javax.lang.model.*;
import javax.lang.model.element.*;

@SupportedAnnotationTypes(value= {"*"})
@SupportedSourceVersion(SourceVersion.RELEASE_6)

public class TestAnnotationProcessor extends AbstractProcessor  {

    @Override
    public boolean process(
        Set<?> extends TypeElement> annotations, RoundEnvironment roundEnv){

        for (TypeElement element : annotations){
            System.out.println(element.getQualifiedName());
        }
        return true;
    }
}

Let us discuss the core points in writing a Custom Annotation Processor in Java 6. The first notable thing is that Test Annotation Processor class extends AbstractProcessor class which encapsulates an Abstract Annotation Processor. We have to inform what Annotation Types our Test Annotation Processor Supports. This is manifested through the Class-Level Annotation called @SupportedAnnotationTypes(). A value of “*” indicates that all types of Annotations will be processed by this Annotation Processor. Which version of Source Files this Annotation Processor supports is mentioned through @SupportedSourceVersion Annotation.

The javac compiler of Mustang has an option called ‘-processor’ where we can specify the Name of the Annotation Processor along with a Set of Java Source Files containing the Annotations. For example, in our case, the command syntax would be something like the following,

javac -processor
    net.javabeat.articles.java6.newfeatures.customannotations.TestAnnotationProcessor
        AnnotatedJavaFile.java

The above command tells that the name of the Annotation Processor is net.javabeat.articles.java6.newfeatures.customannotations.TestAnnotationProcessor and it is going to process the AnnotatedJavaFile.java. As soon as this command is issued in the console, the TestAnnotationProcessor.process() method will be called by passing the Set of Annotations that are found in the Source Files along with the Annotation Processing Information as represented by RoundEnvironment. This TestAnnotationProcessor just list the various Annotations present in the Sample Java File (AnnotatedJavaFile.java) by iterating over it.

Following is the output of the above program

net.javabeat.articles.java6.newfeatures.customannotations.ClassLevelAnnotation
net.javabeat.articles.java6.newfeatures.customannotations.MethodLevelAnnotation

3) Streaming API for XML

3.1) Introduction

Streaming API for XML, simply called StaX, is an API for reading and writing XML Documents. Why need another XML Parsing API when we already have SAX (Simple API for XML Parsing) and DOM (Document Object Model)? Both SAX and DOM parsers have their own advantages and disadvantages and StaX provides a solution for the disadvantages that are found in both SAX and DOM. It is not that StaX replaces SAX and DOM.

SAX, which provides an Event-Driven XML Processing, follows the Push-Parsing Model. What this model means is that in SAX, Applications will register Listeners in the form of Handlers to the Parser and will get notified through Call-back methods. Here the SAX Parser takes the control over Application thread by Pushing Events to the Application. So SAX is a Push-Parsing model. Whereas StaX is a Pull-Parsing model meaning that Application can take the control over parsing the XML Documents by pulling (taking) the Events from the Parser.

The disadvantage of DOM Parser is, it will keep the whole XML Document Tree in memory and certainly this would be problematic if the size of the Document is large. StaX doesn’t follow this type of model and it also has options for Skipping a Portion of a large Document during Reading.

The core StaX API falls into two categories and they are listed below. They are

1. Cursor API
2. Event Iterator API

Applications can any of these two API for parsing XML Documents. Let us see what these APIs’ are in detail in the following sections.

3.2) Cursor API

The Cursor API is used to traverse over the XML Document. Think of a Cursor as some kind of Pointer pointing at the start of the XML Document and then Forwarding the Document upon properly instructed. The working model of this Cursor API is very simple. When given a XML Document and asked to parse, the Parser will start reading the XML Document, and if any of the Nodes (like Start Element, Attribute, Text, End Element) are found it will stop and will give information about the Nodes to the Processing Application if requested. This cursor is a Forward only Cursor, it can never go backwards. Both Reading and Writing operations is possible in this cursor API.

3.3) Sample Application

Let us consider a sample Application which will read data from and to the XML Document with the help of the Cursor API. Following is the sample XML Document. The below XML File contains a list of Events for a person in his/her Calendar.

myCalendar.xml

<calendar>

    <event type = "meeting">
        <whom>With my Manager</whom>
        <where>At the Conference Hall</where>
        <date>June 09 2007</date>
        <time>10.30AM</time>
    </event>

    <event type = "birthday">
        <whom>For my Girl Friend</whom>
        <date>01 December</date>
    </event>

</calendar>

ReadingUsingCursorApi.java

package net.javabeat.articles.java6.newfeatures.stax;

import java.io.*;
import javax.xml.stream.*;
import javax.xml.stream.events.*;

public class ReadingUsingCurorApi {

    private XMLInputFactory inputFactory = null;
    private XMLStreamReader xmlReader = null;

    public ReadingUsingCurorApi() {
        inputFactory = XMLInputFactory.newInstance();
    }

    public void read() throws Exception{

        xmlReader = inputFactory.createXMLStreamReader(
            new FileReader(".\\src\\myCalendar.xml"));

        while (xmlReader.hasNext()){

            Integer eventType = xmlReader.next();
            if (eventType.equals(XMLEvent.START_ELEMENT)){
                System.out.print(" " + xmlReader.getName() + " ");
            }else if (eventType.equals(XMLEvent.CHARACTERS)){
                System.out.print(" " + xmlReader.getText() + " ");
            }else if (eventType.equals(XMLEvent.ATTRIBUTE)){
                System.out.print(" " + xmlReader.getName() + " ");
            }else if (eventType.equals(XMLEvent.END_ELEMENT)){
                System.out.print(" " + xmlReader.getName() + " ");
            }
        }
        xmlReader.close();
    }

    public static void main(String args[]){
        try{
            ReadingUsingCurorApi obj = new ReadingUsingCurorApi();
            obj.read();
        }catch(Exception exception){
            exception.printStackTrace();
        }
    }
}

XMLInputFactory is the Factory Class for creating Input Stream objects which is represented by XMLStreamReader. An instance of type XMLStreamReader is created by calling XMLInputFactory.createXMLStreamReader() by passing the XML File to be parsed. At this stage, the Parser is ready to read the XML Contents if a combination call to XMLStreamReader.hasNext() and XMLStreamReader.next() is made. The entire Document is traversed in the while loop and the appropriate node’s value is taken by checking the various Element Types.

3.4) Event Iterator API

The Working Model of this Event Iterator API is no more different from the Cursor API. As the Parser starts traversing over the XML Document and if any of the Nodes are found, it will provide this information to the Application that is processing in the form of XML Events. Applications can loop over the entire Document, by requesting for the Next Event. This Event Iterator API is implemented on top of Cursor API.

3.5) Sample Application

Now let us take over a Sample Application using the Event Iterator API which is parsing on the XML Document myCalendar.xml.

ReadingUsingEventIterator.java

package net.javabeat.articles.java6.newfeatures.stax;

import java.io.*;
import javax.xml.stream.*;
import javax.xml.stream.events.*;

public class ReadingUsingEventIteratorApi {

    private XMLInputFactory inputFactory = null;
    private XMLEventReader xmlEventReader = null;

    public ReadingUsingEventIteratorApi() {
        inputFactory = XMLInputFactory.newInstance();
    }

    public void read() throws Exception{

        xmlEventReader = inputFactory.createXMLEventReader(
            new FileReader(".\\src\\myCalendar.xml"));

        while (xmlEventReader.hasNext()){

            XMLEvent xmlEvent = xmlEventReader.nextEvent();
            if (xmlEvent.isStartElement()){
                System.out.print(" " + xmlEvent.asStartElement().getName() + " ");
            }else if (xmlEvent.isCharacters()){
                System.out.print(" " + xmlEvent.asCharacters().getData() + " ");
            }else if (xmlEvent.isEndElement()){
                System.out.print(" " + xmlEvent.asEndElement().getName() + " ");
            }
        }

        xmlEventReader.close();
    }

    public static void main(String args[]){
        try{
            ReadingUsingEventIteratorApi obj = new ReadingUsingEventIteratorApi();
            obj.read();
        }catch(Exception exception){
            exception.printStackTrace();
        }
    }
}

If XMLStreamReader class represents the Reader for stream reading the XML Contents, then XMLEventReader represents the class for reading the XML Document as XML Events (represented by javax.xml.stream.events.XMLEvent). The rest of the reading logic is the same as that of the ReadingUsingCurorApi.java.

4) Conclusion

This article covered the leftover features of the Part I New features of Java 6. Starting with Pluggable Annotation Processing API, it covered what Annotations are, then guided us how to write Custom Annotations and Custom Annotation Processor. Then it traversed over the Cursor API and the Event Iterator API of StaX such as how to read XML Documents along with well-defined samples. Finally through Java API for XML Binding, it details how to map Java and XML Documents with some sample applications.

This article covers the various new features of Java 6, also known as Mustang. This article assumes that readers have sufficient knowledge over the concepts and terminologies in Java 5.0. For more information on Java 5.0, readers can vist the resources available in javabeat here. Though there is no significant changes at the Language Level, though Mustang comes with a bunch of enhancements in the other areas like Core, XML and Desktop. Most of the features are applicable both to J2SE and J2EE Platforms.

2) Java 6 Features

• Introduction to Java 6.0 New Features, Part–2
• What is new in Java 8.0?

A feature or an enhancement in Java is encapsulated in the form of a JSR. JSR, which stands for Java Specification Request is nothing but a formal proposal which details the need for a specific functionality to be available in the Java Platform that can be used by Applications. These JSR’s will be reviewed and released by a committee called Java Expert Groups (JEG). This article covers the following list of features (or JSRs’) that comes along with the Java 6 Platform.

• Pluggable Annotation Processing API (JSR 269)
• Common Annotations (JSR 250)
• Java API for XML Based Web Services – 2.0 (JSR 224)
• JAXB 2.0 (JSR 222)
• Web Services Metadata (JSR 181)
• Streaming API for XML (JSR 173)
• XML Digital Signature (JSR 105)
• Java Class File Specification Update (JSR 202)
• Java Compiler API (JSR 199)
• JDBC 4.0 (JSR 221)
• Scripting in the Java Platform (JSR 223)

The JSRs’ that are covered in this article are Common Annotations, JDBC 4.0 and Scripting in the Java Platform. Rest of the JSRs’ will be covered in the subsequent article.

3) Common Annotations

The aim of having Common Annotations API in the Java Platform is to avoid applications defining their own Annotations which will result in having larger number of Duplicates. This JSR is targeted to cover Annotations both in the Standard as well the Enterprise Environments. The packages that contain the annotations are javax.annotation and javax.annotation.security . Let us discuss in brief the commonly used Annotations that are available in this JSR in the next subsequent sections.

3.1) @Generated Annotation

Not all the source files or the source code in an application is hand-written by Developers. With the increasing number of Tools and Frameworks, most of the common Boiler-Plate Code is generated by the Tools or the Frameworks itself if they have been properly instructed. Such Tool Generated Code can be marked with @Generated Annotation. Consider the following sample code snippet,

MyClass.java

public class MyClass{

    public void developerCode(){
    }

    @Generated(
        value = "ClassNameThatGeneratedThisCode",
        comments = "This is Tool Generated Code",
        date = "5 June 2007"
    )
    public void toolGeneratedCode(){
    }

}

The value for the @Generated Annotation would be usually the class name that generated this code. Optionally, comments and date can be given to add more clarity to the generated code. Note this @Generated Annotation is not limited to a method definition, it can also be defined for Package Declaration, Class Declaration, Interface Declaration, Local Variable Declaration, Field Declaration, Parameter Declaration etc.

3.2) @Resource and @Resources Annotation

Any Class or Component that provides some useful functionality to an Application can be thought of as a Resource and the same can be marked with @Resource Annotation. This kind of Annotation can be seen normally in J2EE Components such as Servlets, EJB or JMS. For example consider the following code snippet,

@Resource(name = "MyQueue", type = javax.jms.Queue,
    shareable = false,
    authenticationType = Resource.AuthenticationType.CONTAINER,
    description = "A Test Queue"
)
private javax.jms.Queue myQueue;

Queue is a class available as part of JMS API and it serves as a target for Asynchronous Messages being sent by Applications. The various properties to note in @Resource Annotation are: ‘name’ which is the JNDI Name of this resource, ‘type’ which is the type of the resource which usually points to the Fully Qualified Class Name, ‘shareable’ which tells whether this resource can be shared by other components in the Application or not, ‘authenticationType’ which indicates the type of authentication to be performed either by the Container or by the Application and the Possible values are AuthenticationType.CONTAINER and
AuthenticationType.APPLICATION and ‘description’ which is a string that describes the purpose of this resource.

When the Application containing the @Resource Annotations are deployed to a Server, the Container will scan for all the Resource references during the time of Application loading and then will populate the @Resource References by assigning new instances.

@Resources is nothing but a collection of @Resource entries. Following is a sample code that defines @Resources Annotation,

@Resources is nothing but a collection of @Resource entries. Following is a sample code that defines
@Resources Annotation,

@Resources({
    @Resource(name = "myQueue" type = javax.jms.Queue),
    @Resource(name = "myTopic" type = javax.jms.Topic),
})
					

3.3) @PostConstruct and @PreDestroy

J2EE Components are usually created by the Container or the Framework on which they are deployed. Container creates new components by calling the Default or the No Argument Constructor. It is a very common need that a component needs to get initialized with some default values after it has been created. @PostConstruct Annotation serves that purpose. It is a Method-Level Annotation, meaning that this Annotation can be applied only to a Method and it will be fired immediately as soon the Component is created by invoking the Constructor.

Consider the following set of code,

MyDbConnectionComponent.java

public class MyDbConnectionComponent{

    public MyDbConnectionComponent(){
    }

    @PostConstruct()
    public void loadDefaults(){

        // Load the Driver Class.
        // Get the Connection and Do other stuffs.

    }
}

We can see that @PostConstruct Annotation is normally used to Initialize the Resources that are Context specific. The loadDefaults() method which is marked with @PostConstruct Annotation will be called immediately by the Container as soon as an instance of MyDbConnectionComponent is created. There are certain guidelines to be followed while defining the PostConstruct method such as: the method should not be marked as static, return type should be void, it cannot throw any CheckedExceptions etc.

The counterpart to @PostConstruct Annotation is the @PreDestroy Annotation. From the name of the Annotation itself, we can infer that the method that is marked with this Annotation will be called before an object is about to be removed or destroyed by the Container. Like the @PostConstruct Annotation, this is also a Method-Level Annotation and the following code snippet proves this,

MyDbConnectionComponent.java

public class MyDbConnectionComponent{

    public MyDbConnectionComponent(){
    }

    @PreDestroy()
    public void releaseResources(){

        // Close the Connection.
        // Unload the Class Driver from the System

    }
}

The method releaseResources() will be called by the Container before the object is about to be Destroyed. Resource releasing code are ideal candidates to be placed in the @PreDestroy Annotation method.

3.4) Role Based Annotations

The following sections discuss the various Role-based Annotations that are very common in Applications that are very concerned about Security. A Typical Application is accessed by a wide range of Users and Users themselves fall into Several Roles. Considering an IT Organization, all Employees fall into the General Category of Roles namely Admin, Director, Manager, Engineer, Programmer etc. It is very common to see Applications following Role-Based Security Model. The Annotations @DeclareRoles, @RolesAllowed, @PermitAll, @DenyAll and @RunAs are Role-Based Annotations and are covered here.

3.4.1) @DeclareRoles Annotations

This is a Class-Level Annotation meaning that this Annotation is applicable only to a Class Declaration. If applied to a Class or a Component, it essentially declares the valid Set of Roles that are available for this Component. Consider the following code which will clarify this,

LeaveService.java

@DeclareRoles(value = {"Director", "Manager", "Others" })
public class LeaveService{

    @Resource
    private Context context;

    public void applyLeave(){

        // Any employee can apply for leave. So no need for any
        // conditional check.
    }

    public void grantLeave(){
        if(checkUserInRole()){
            // Grant Leave.
        }
    }

    public void cancelLeave(){
        if(checkUserInRole()){
            // Cancel Leave.
        }
    }

    private boolean checkUserInRole(){
        if( (context.isCallerInRole("Director") )
            || (context.isCallerinRole("Manager")) ){
            return true;
        }

        return false;
    }
}

In the above example, the component LeaveService has been marked with @DeclareRoles Annotations with Role Name values namely Director and Manager. It has three services namely: applying for leave (applyLeave()), granting for leave (grantLeave()) and cancellation of leave (cancelLeave()). It is acceptable that only Employees in the Superior Role (Director or Manager) can grant or deny leaves to their sub-ordinates. So additional conditional checks are done to ensure that whether the User who is accessing the grantLeave() or the cancelLeave() service belongs to either of the defined Roles(Director or Manager). Since any employee in a company can apply for a leave, (whose Role Name is given as Others), no conditional checks are done in applyLeave() method.

3.4.2) @RolesAllowed Annotation

This is a Class/Method Level Annotation which is used to grant access to some Service(s) to the defined set of Users who are mentioned by their Role Names in the Annotation. Let us get into the following example straightaway,

LeaveService.java

@DeclareRoles("A", "B", "C", "X", "Y", "Z")
@RolesAllowed("A", "B", "C")
public class MyServiceComponent{

    @RolesAllowed(value = {"A", "X", "Y"} )
    public void myService1(){
    }

    @RolesAllowed(value = {"B", "Y", "Z"} )
    public void myService2(){
    }

    @RolesAllowed(value = {"X", "Y", "Z"} )
    public void myService3(){
    }

    public void myService4(){
    }
}

The above code declares various roles namely “A”, “B”, “C”, “X”, “Y” and “Z” for the component MyServiceComponent. The @RolesAllowed Annotation when applied to a method grant Access to Users who are in that Roles only. For example, only Users with Roles “A” or “X” or “Y” are allowed to access the method myService1(). In the case of myService2(), “B”, “Y” or “Z” role Users are allowed to access it and so on.

What happens in the case of myService4()??

No @RolesAllowed is specified for this method. The fact is that, if a method doesn’t have @RolesAllowed Annotation attached to it, then it will inherit this property from the class where it has been defined. So, in our case, Users in the Role “A”, “B” or “C” can access the method myService4() becuase these set of Roles have been defined at the Class Level. What if the Class Declaration itself doesn’t have the @RolesAllowed Annotation declared? The answer is simple: it will take all the Roles that are defined in @DeclareRoles.

3.4.3) @PermitAll and @DenyAll Annotation

These are Class/Method Level Annotations and if applied to a Class Declaration will affect all the methods in the class, and when applied to a method will affect that method only.

Consider the following sample,

MyClass.java

@DeclareRoles(value = {"A", "B", "C"} )
class MyClass{

    @PermitAll()
    public void commonService(){
    }

    @DenyAll
    public void confidentialService(){
    }
}

From the above code, it is inferred that commonService() method can be accessible by all Users irrespective of their Roles as it is marked with @PermitAll() annotation and no one can access the confidentialService() because it has been marked with @DenyAll() annotation.

4) Scripting Language for the Java Platform

4.1) Introduction

Java 6 provides the Common Scripting Language Framework for integrating various Scripting Languages into the Java Platform. Most of the popular Scripting Languages like Java Script, PHP Script, Bean Shell Script and PNuts Script etc., can be seamlessly integrated with the Java Platform. Support for Intercommunication between Scripting Languages and Java Programs is possible now because of this. It means that Scripting Language Code can access the Set of Java Libraries and Java Programs can directly embed Scripting Code. Java Applications can also have options for Compiling and Executing Scripts which will lead to good performance, provided the Scripting Engine supports this feature. Let us have a high-level overview of this JSR before going in detail.

Following sections provide the two core components of the Scripting engine namely,

• Language Bindings
• The Scripting API

4.2) Language Bindings

The Language Bindings provides mechanisms for establishing communications between the Java Code and the Script Code. More specifically, it deals with how actually a Java Object creating by a Script Code is stored and maintained by the Scripting Engine, how the Script Arguments are converted back and forth, how the Calls that are made to the Java Methods from within the Scripting Code got translated and how the return values from the Java Code are made available to the Scripting code. To illustrate on this further, consider the JavaScript Code,

var aJavaString = new String("A Test String");

This piece of code essentially creates a new Java String object and assigns it to a JavaScript object called aJavaString which is of var type. As soon as the Rhino Script Engine (which is the Scripting Engine name for JavaScript) parses this Script Code, it has to create a new instance of String object and should store it somewhere. The place where Java Objects and Script objects are stored are referred to as Bindings in Java Scripting Terminology. Here, aJavaString acts as a Proxy Object for the real java.lang.String object.

Again consider the following code,

var aJavaString = new java.lang.String('A Test String');
var length = aJavaString.substring(7, 13);

So many Micro-Level Tasks are involved if we analyse the above piece of code carefully. They are listed as follows,

1. Script Arguments are Converted to Java Arguments
2. Java Method to be invoked is identified
3. Logic is performed on the invoked Java Method
4. Return Values, if any, are sent back to the Scripting Code

The first line indicates that a new instance of java.lang.String object is created and it is stored in a Java Script object called aJavaString. Here aJavaString acts as a Proxy Object for the original java.lang.String object. After that we can see that the arguments 7 and 13 are passed from the Script Code to the method String.substring(int,int). The Engine will now convert the arguments that are to be sent to the Java method by using the Default Script-Java Mappings which is very specific to every Script Engine. After that, the Scripting Engine must ensure the availability of the method String.substring(int,int) at the run-time by abundantly depending on the Java Reflection API. Now the method is invoked and the logic gets executed. The return values are then converted using the Java-Script Mappings as defined by the Script Engine and will get populated in the length JavaScript object.

4.3) Scripting API

This API allows Java Programs to take the full advantage of Directing Embedding Scripting Code into the Applications. It also provides a framework wherein New Scripting Engines can be easily plugged-in. The entire API is available in the javax.script package.

ScriptEngineManager class provides mechanisms for Searching and Adding Scripting Engines into the Java Platform. Convenient methods are available for Discovering Existing Scripting Engines. For example, the following code will iterate and will list down all the Script Engines that are available in the Java 6 Distribution.

List allFactories = ScriptEngineManager.getEngineFactories();

for(ScriptEngineFactory engineFactory : allFactories){
    System.out.println("Engine Name" + engineFactory.getEngineName());
}

The ScriptEngineFactory is the Factory Class for creating ScriptEngine objects. As such, two different ways are there to get instances of ScriptEngine classes. One way is to call the method ScriptEngineFactory.getScriptEngine(). The other direct way is to depend on the ScriptEngineManager itself to call getEngineByName().

// First Way
ScriptEngineFactory rhinoFactory = getScriptEngineFactory();
ScriptEngine rhinoEngine = rhinoFactory.getScriptEngine();

// Second Way
String name  = "javascript";
ScriptEngine rhinoEngine = ScriptEngineManager.getEngineByName(engineName);
					

Execution of scripts can be done by calling the ScriptEngine.eval(String) method.

Bindings as represented by javax.script.Bindings, provide key/name information to ScriptEngines. Two types of Binding Scopes are available, one is the Global Scope and the other is the Engine Scope. By default, the ScriptEngineManager manages some set of Default bindings, which can be obtained by making a call to ScriptManager.getBindings(). The Bindings that are obtained in this manner (i.e from ScriptEngineManager) are called Global Bindings. Following is the code to get a reference to the Global-Bindings object and to populate it with application-specific values.

Bindings globalBindings = scriptEngineManager.getBindings();
globalBindings.put("key1", "value1");
globalBindings.put("key2", "value2");

It is also possible to customize the Binding information on Engine-by-Engine basis. For example, to obtain Bindings that is very specific to a particular Engine, a call to ScriptEngine.getBindings() can be made. These Bindings that are obtained in this way are called Engine Bindings.

4.4) Sample Code

This following Sample Application demonstrates how to directly embed Scripting Code in Java Applications. Argument passing between the Java Code and the Script Code are illustrated in this Sample.

package test;

import javax.script.*;

public class ScriptTest{

    public static void main(String[] args){

        try{
            // Create an instance of the Scripting manager.
            ScriptEngineManager manager = new ScriptEngineManager();

            // Get the reference to the rhino scripting engine.
            ScriptEngine rhinoEngine = manager.getEngineByName("javascript");

            // Get the Binding object for this Engine.
            Bindings bindings =	rhinoEngine.getBindings(ScriptContext.ENGINE_SCOPE);

            // Put the input value to the Binding.
            bindings.put("strValue", "A Test String");

            // Populate the script code to be executed.
            StringBuilder scriptCode = new StringBuilder();
            scriptCode.append("var javaString = new java.lang.String(strValue);");
            scriptCode.append("var result = javaString.length();");

            // Evaluate the Script code.
            rhinoEngine.eval(scriptCode.toString());

            // Take the output value from the script, i.e from the Bindings.
            int strLength = (Integer)bindings.get("result");

            System.out.println("Length is " + strLength);
        }catch(Exception exception){
            exception.printStackTrace();
        }
    }
}

In the above code, a new instance of ScriptEngineManager is created in the very first line. Then, the Scripting Engine
that comes shipped with the Mustang, (i.e, Rhino Java Script Engine) is obtained by calling ScriptEngineManager.getEngineByName(“javascript”). Arguments are passed from and to the Java Code with the help of Bindings. The input string to be processed is added to the Bindings with the call to Bindings.put(“strValue”, “A Test String”). Notice how the input string is populated within the script code at run-time, var javaString = new java.lang.String(strValue). It means that at run-time the Script code becomes var javaString = new java.lang.String(‘A Test String’). Then the script is executed by calling the ScriptEngine.eval(String) method. The output which is the length of the input string is now in the Script variable called result. And as mentioned previously, since all the Script and the Java Objects will be maintained and controlled by the Bindings, it is possible to get the value of the Script object result directly by calling Bindings.get(“result”).

6) Conclusion

This article covered some of the new features available in Java 6. It started off with the JSR that aimed in defining the Common Set of Annotations that can be used by Application Programs. Each and every Annotation in this package is briefly explained and examples were given to make it more understandable. Then, the Common Scripting Language Framework for the Java Platform is given in depth discussion along with the concept of Bindings, Scripting API and with a Sample Program.

also read:

• New Features in Java 6.0 – Part 1
• New Features in Java 6.0 – Part 2
• New Features in JDBC API (Java 6.0)
• What is New in Java 8.0

Instead of looking into all the classes and interfaces that are available in the javax.tools package, it makes more sense to go through some sample programs, then examining what the classes and the methods are doing.

Compiling a java source file from another Java source

Following is the small sample program that will demonstrate how to compile a Java source file from another java file on the fly.

[All the examples given here are written and tested with Mustang build 1.6.0-b105, and it seems that more API changes and restructuring of classes and methods are occurring in the newer builds].

MyClass.java:

package test;
public class MyClass {
	public void myMethod(){
		System.out.println("My Method Called");
	}
}

Listing for SimpleCompileTest.java that compiles the MyClass.java file.

SimpleCompileTest.java:

package test;
import javax.tools.*;
public class SimpleCompileTest {
	public static void main(String[] args) {
String fileToCompile = "test" + java.io.File.separator +"MyClass.java";
JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
int compilationResult =	compiler.run(null, null, null, fileToCompile);
		if(compilationResult == 0){
			System.out.println("Compilation is successful");
		}else{
			System.out.println("Compilation Failed");
		}
	}
}

The entry point for getting a compiler instance is to depend on the ToolProvider class. This class provides methods for locating a Tool object. (Remember a Tool can be anything like javac, javadoc, rmic, javah etc…) Though the only Tool available in Mustang build (1.6.0-b105) is the JavaCompiler as of now, it is expected that many more tools are to be added in the future.

The getSystemJavaCompiler() method in the ToolProvider class returns an object of some class that implements JavaCompiler (JavaCompiler is an interface that extends Tool interface and not a class). To be more specific, the method returns a JavaCompiler implementation that is shipped along with the Mustang Distribution. The implementation of the Java Compiler is available in the tools.jar file (which is usually available in the <JDK60_INSTALLATION_DIR>\lib\tools.jar).

After getting an instance of the JavaCompiler, compilation on a set of files (also known as compilation units) can be done by invoking the run(InputStream inputStream, OutputStream outputStream, OutputStream errorStream, String … arguments) method. To use the defaults, null can be passed for the first three parameters (which correspond to System.in, System.out and System.err), the fourth parameter which cannot be null is a variable argument that refers to the command-line arguments we usually pass to the javac compiler.

The file that we are going to compile is MyClass.java which is the same test package as of the SimpleCompileTest. The complete file name (along with the directory ‘test’) is passed as 4th argument to the run method. If there are no errors in the source file (MyClass.java, in this case), the method will return 0 which means that the source file was compiled successfully.

After compiling and running the SimpleCompileTest.java, one can see the following output message in the console.

‘Compilation is successful’

Let us modify the source code by introducing a small error by removing the semi-colon after the end of the println() statement and see what happens to the output.

MyClass.java:
package test;

public class MyClass {
	public void myMethod(){
System.out.println("My Method Called")
// Semi-colon removed here purposefully.
	}
}
Now, running the SimpleCompileTest.java leads to the following output,

test\MyClass.java:5: ';' expected
		System.out.println("My Method Called")
		                                      ^
1 error
Compilation Failed

This is the error message one normally sees when compiling a java file using javac.exe in the command prompt. The above represents the error message(s) and since we have made the error output stream point to null (which defaults to System.err, which is the console) we are getting the output error messages in the console. If instead we have pointed the errorStream to something like this,

FileOutputStream errorStream = new FileOutputStream("Errors.txt");
int compilationResult = compiler.run(null, null, errorStream, fileToCompile);

a new file called Errors.txt will be created in the current directory and the file would be populated with the error messages that we saw before.

Compiling multiple files

One might be tempted to think that the following code will work for compiling multiple java files (assuming that the two files that are to be compiled are One.java and Two.java).

String filesToCompile = new String("One.java Two.java") ;

But surprisingly, when you try this, you will get a ‘Compilation Failed’ error message in the console.

The answer is JavaCompiler needs to extract individual options and arguments and these options and arguments should not be separated by spaces, but should be given as individual strings.

So, this won’t work at all.

compiler.run(null, null, null, “One.java Two.java”);

But, the below code will work nicely.

compiler.run(null, null, null, “One.java”, “Two.java”);

One reason for forcing this kind of restriction is that sometimes the complete java file names (which includes directory path as well) itself can have white-spaces , in such a case it would be difficult for the parser to parse all the tokens correctly into options and arguments.

Following is a sample code that compiles multiple java files.

MyClass.java:
package test;

public class MyClass {
}

MyAnotherClass.java:
package test;

public class MyAnotherClass {
}

MultipleFilesCompileTest.java:
package test;
import javax.tools.*;

public class MultipleFilesCompileTest {
	public static void main(String[] args) throws Exception{
String file1ToCompile = "test" + java.io.File.separator + "MyClass.java";
String file2ToCompile = "test" + java.io.File.separator + "MyAnotherClass.java";
		JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
int compilationResult =	compiler.run(null, null, null, file1ToCompile, file2ToCompile);
		if(compilationResult == 0){
			System.out.println("Compilation is successful");
		}else{
			System.out.println("Compilation Failed");
		}
	}
}

The above program compiles fine with the output message ‘Compilation is successful’.

Do remember, that the final argument is a variable argument and it can accept any number of arguments.

[Starting with Java 5.0, variable argument is a new feature where the callers (the calling method) can pass any number of arguments. To illustrate this concept, look at the sample code.

public int addNumbers(int …numbers){

int total = 0;
For(int temp : numbers){
	Total = total + temp;
}
return total;
}

A variable argument is represented by ellipsis (…) preceding the variable name like this
int … numbers. And , one can call the above method in different styles, like the below

addNumbers(10, 10, 30,40); // This will work.
addNumbers(10,10) // This also will work.

type must be the last one. Variable arguments are internally treated as arrays. So, this is also possible now.

addNumbers(new int[]{10, 34, 54});

So, great care should be exercised when passing multiple options along with values to the run method. As an example, the ideal way to pass options along with its option values might me,

compiler.run(null, null, null, ”-classpath”, ”PathToClasses”, ”-sourcepath”, ”PathToSources”, ”One.java”, ”Two.java”);

Ass one can see, even the option and its option values must be treated as a separate string.

As you are aware of the fact, when invoking the java compiler with the ‘verbose’ option specified, the javac will output messages that will occur during the compilation life-cycle (like parsing the input, validating them, scanning for the paths for both source and class files, loading all the necessary class files, then finally creating the class files in the specified destination directory). Let us achieve the same effect through the following sample code.

SimpleCompileTestWithVerboseOption.java
package test;
import java.io.FileOutputStream;
import javax.tools.*;
public class SimpleCompileTestWithVerboseOption {
	public static void main(String[] args) throws Exception{
String fileToCompile = "test" + java.io.File.separator + "MyClass.java";
		JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
		FileOutputStream errorStream = new FileOutputStream("Errors.txt");
		int compilationResult =	compiler.run(
				null, null, errorStream, "-verbose", fileToCompile);
		if(compilationResult == 0){
			System.out.println("Compilation is successful");
		}else{
			System.out.println("Compilation Failed");
		}
	}
}

May be a bug in Mustang

One might see that the errorStream (3rd argument) has been pointed out to a file to collect the output messages instead of the outputStream (2nd argument).

The following code was tried for capturing the verbose output, but this code failed, in the sense, the output was still written to the standard console, though the code seems to re-direct the output to a file.

FileOutputStream outputStream = new FileOutputStream("Output.txt");
int compilationResult =	compiler.run(
null, outputStream, null, "-verbose", fileToCompile);

The Java Compiler API is treating the output messages (in this case, the output messages obtained by specifying the ‘verbose’ option) as error messages, and so even though the output is pointing to the file (‘Output.txt’), it is spitting all the output messages to the console.

Also, the documentation for the run method is unclear; it tells that any diagnostics (errors, warnings or information) may be written either to the output stream or the error messages.

Advanced Compilation

In the above section, we saw how to compile files using the JavaCompiler tool. For advanced compilation related stuffs, the JavaCompiler depends on two more services namely the file manager services and the diagnostics services. These services are provided by the JavaFileManager and the DiagnosticListener classes respectively.

JavaFileManager

The JavaFileManager (being given implementation as StandardJavaFileManager) manages all the file objects that are usually associated with tools. This JavaFileManager is not only to JavaCompiler, but instead it can work with any kinds of objects that conform to the standard Tool interface. To understand why JavaFileManager is so important, let us understand what could be the things that may happen during compilation process.

javac MyClass.java

When we issue this command in the command prompt, so many things will happen. The very first thing is that the compiler will parse all the options that are specified by the user, have to validate them, and them have to scan the source and class path for java source files and the jar files. It then has to deal with the input files (in this case it is MyClass.java) and output files (MyClass.class).

So, JavaFileManager which is associated with any kind of tool (normally all tools have some kind of input and the output files for processing), deals with managing all the input files and output files. By managing, we mean that JavaFileManager is responsible for creating output files, scanning for the input files, caching them for better performance. One such implementation given to the JavaFileManager is the StandardJavaFileManager.

A file being managed by JavaFileManager doesn’t mean the file is necessarily a file in the hard-disk. The contents of the file managed may come from a physical file in a hard-disk, may come from in-memory or can even come from a remote socket. That’s why JavaFileManager doesn’t deal with java.io.File objects (which usually refer to the physical files in the operating system File System). Rather, JavaFileManager manages all the files and their contents in the form of FileObject and JavaFileObject which represents the abstract representation for any kind of files by managed by the JavaFileManager.

FileObject and JavaFileObject refer to the abstract file representation that are being managed by the JavaFileManager and also have support related to reading and writing the contents to the right destination. The only difference between a FileObject and a JavaFileObject is that a FileObject can represent any kind of FileObject (like text file, properties file, image file etc), whereas a JavaFileObject can represent only java source file (.java) or a class file (.class). If a FileObject represents a java source file or a class file, then implementations should take care to return a JavaFileObject instead.

Diagnostics

The second dependent service by the JavaCompiler is the Diagnostic Service. Diagnostic usually refers to errors, warnings or informative messages that may appear in a program. For getting diagnostics messages during the compilation process, we can attach a listener to the compiler object. The listener is a DiagnosticListener object and its report() method will be called with a diagnostic method which contains many a more information like the kind of diagnostics (error, warning, information or other), the source for this diagnostics, the line number in the source code, a descriptive message etc.

CompilationTask

Before going into the sample code to clarify things like JavaFileManager, Diagnostic,and the DiagnosticListener classes, let us have a quick review on the class CompilationTask. From its name, obviously one can tell that it represents an object that encapsulates the actual compilation operation. We can initiate the compilation operation by calling the call() method in the CompilationTask object.

But how to get the CompilationTask object?

Since, CompilationTask is closely associated to a JavaCompiler object, one can easily say JavaCompiler.getCompilationTask( arguments ) to get the CompilationTask object. Let we now see the parameters that are needed to pass to the getCompilationTask(…) method.

Almost all the arguments can be null (with their defaults, which is discussed later), but the final argument represents the list of java objects to be compiled (or the compilation units) which cannot be null. The last argument is Iterable<? Extends JavaFileObject> javaObjects.

So, how can one populate this argument?

[Iterable is a new interface that was added with jdk 5.0 which is use to iterate (or traverse over a collection of objects. It has one method called iterator() which returns an Iterator object, and using it one can traverse over the collection by using the combinational hasNext() and the next() methods.

Considering type safety which started from Java 5.0, it is the role of the developer to specify what exactly is the type of object to be iterated. Iterable<? Extends JavaFileObject> means that this argument is an iterable that is acting on any class that implement the JavaFileObject interface].

JavaFileManager has 4 convenience methods like getJavaFileObject(File … files) , getJavaFileObjects(String … filenames), getJavaFileObjectsFromFiles(Iterable(? extends JavaFileObject) and getJavaFileObjectFromString(Iterable<? extends String> filenames) that returns javaObjects in the form of Iterable<? Extends JavaFileObject> type.

So, we can construct the 4th arguments using any of the convenience methods.

With more bits of theory in the last few sections, let us see a sample program that incorporates all the classes and the methods that we saw listed.

Purposefully we create a java file called MoreErrors.java that has some error code in it. The listing for MoreErrors.java is shown below.

MoreErrors.java:
package test;
public class MoreErrors {
	public void errorOne ()
		// No open braces here.  Line a
	}
	public void errorTwo(){
		System.out.println("No semicolon") // Line b
		// No semicolon at the end of the statement.
	}
	public void errorThree(){
		System.out.prntln("No method name called prntln()"); // Line c
	}
}

As one can see, the statement above line a, line b and line c has errors.

Let us look into the AdvancedCompilationTest.java that uses all the classes and the methods that we discussed above.

AdvancedCompilationTest.java:
package test;
import java.io.*;
import java.util.*;
import javax.tools.*;
import javax.tools.JavaCompiler.*;
public class AdvancedCompilationTest {
	public static void main(String[] args) throws Exception {
		JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
// Line 1.
		MyDiagnosticListener listener = new MyDiagnosticListener(); // Line 2.
		StandardJavaFileManager fileManager  =
		compiler.getStandardFileManager(listener, null, null); // Line 3.
String fileToCompile = "test" + File.separator + "ManyErrors.java";
// Line 4
		Iterable fileObjects =						fileManager.getJavaFileObjectsFromStrings(
Arrays.asList(fileToCompile));  // Line 5
CompilationTask task = compiler.getTask(null, fileManager, listener, null, null, fileObjects); // Line 6
		Boolean result = task.call(); // Line 7
		if(result == true){
			System.out.println("Compilation has succeeded");
		}
	}
}
class MyDiagnosticListener implements DiagnosticListener{
	public void report(Diagnostic diagnostic) {
		System.out.println("Code->" +  diagnostic.getCode());
		System.out.println("Column Number->" + diagnostic.getColumnNumber());
		System.out.println("End Position->" + diagnostic.getEndPosition());
		System.out.println("Kind->" + diagnostic.getKind());
		System.out.println("Line Number->" + diagnostic.getLineNumber());
		System.out.println("Message->"+ diagnostic.getMessage(Locale.ENGLISH));
		System.out.println("Position->" + diagnostic.getPosition());
		System.out.println("Source" + diagnostic.getSource());
		System.out.println("Start Position->" + diagnostic.getStartPosition());
		System.out.println("\n");
	}
}

Let us explore the above code in greater detail.

Line 1 is essentially creating an object of type JavaCompiler using the ToolProvider class. This is the entry point.

JavaCompiler compiler = ToolProvider.getSystemJavaCompiler()

Line 2 and Line 3 is making the compiler to make use of the FileManager and the Diagnostic’s Services. To rewind the theory a bit, JavaFileManager object is used to manage the input and the output files that a tool normally deals with. And Diagnostic’s objects refer the diagnostics (errors, warnings or information) that may occur during the compilation process within a program.

MyDiagnosticListener listener = new MyDiagnosticListener();

Line 2 creates an object of Type DiagnosticListener, since we want to monitor the diagnostics that may happen during the process of compilation (diagnostics, in the form of error messages will always happen in our case, as we have purposefully done some errors in the java code). We have overridden the report(Diagnostic) method and have extracted all the possible information. Since diagnostics can happen in any kind of file object, how can we specifically tell that this Diagnostics is for a java file object?

The answer has become easy because of Java 5.0 generics. One can notice that MyDiagnosticListener is a typed class (having some typed parameter) meaning that it can act on any kind of object that has diagnostics properties; here we are explicitly telling that the diagnostics is for JavaFileObject and not for any other file object by mentioning the JavaFileObject in the class declaration and the method declaration (shown in bold).

class MyDiagnosticListener implements DiagnosticListener{
	public void report(Diagnostic diagnostic) {
		System.out.println("Code->" +  diagnostic.getCode());
		System.out.println("Column Number->" + diagnostic.getColumnNumber());
		….
		….
	}
}

In Line 3, we are associating the Diagnostics listener object to the compiler object through the standard java file manager by making this method call.

StandardJavaFileManager fileManager  =
			compiler.getStandardFileManager(listener, null, null);

This method tells to attach the diagnostics listener object to this compiler object, so whenever this compiler object executes a compilation operation, and if any diagnostics related errors or warnings have occurred in a program, then the diagnostics being encapsulated by the Diagnostic object will be passed back to the report() method of the DiagnosticListener interface.

The last 2 arguments refer the locale and charset arguments for formatting the diagnostic messages in a particular locale and by using the specified charset which can be null.

Line 4 and Line 5 populates the file objects to be compiled by using the convenience objects in the StandardJavaFileManager class.

String fileToCompile = "test" + File.separator + "ManyErrors.java";
Iterable fileObjects =						fileManager.getJavaFileObjectsFromStrings(
Arrays.asList(fileToCompile));

Line 6 gets an instance of the CompilationTask object by calling the getCompilationTask() method and by passing the fileManager, listener and the fileObjects objects. The null arguments refer to the Writer object (for getting the output from the compiler), list of options (the options that we pass to javac like –classpath classes, -sourcepath Sources…) and classes (for processing the custom annotations that are found in the source code).

Finally, the actual compilation operation is done by calling the call() method which returns true if all the files (compilationUnits) succeed compilation. If any of the files have errors in it , then the call() method will return false. Anyway, in our case, we have some error code in the MoreErrors.java file, so the report method will be called printing all the diagnostics information.

DiagnosticCollector

In the previous program, we saw that we have a customized class called MyDiagnosticListener. Its sole purpose it to collect and print all the diagnostic messages to the console. This class can be completely eliminated since Mustang already has a class called DiagnosticCollection<SourceObject> that does the same thing. It has a method called getDiagnostics() which returns a list , through which we can iterate and can output the diagnostic messages to the console.

The following code achieves the same using DiagosticCollector class.

AdvancedCompilationTest2.java:
package test;
import java.io.*;
import java.util.*;
import javax.tools.*;
import javax.tools.JavaCompiler.*;
public class AdvancedCompilationTest2 {
	public static void main(String[] args) throws Exception {
JavaCompiler compiler = ToolProvider.getSystemJavaCompiler(); // Line 1.
		DiagnosticCollector diagnosticsCollector =
		new DiagnosticCollector();
		StandardJavaFileManager fileManager  =
compiler.getStandardFileManager(diagnosticsCollector, null, null); // Line 3.
String fileToCompile = "test" + File.separator + "ManyErrors.java"; // Line 4
Iterable fileObjects = fileManager.getJavaFileObjectsFromStrings(Arrays.asList(fileToCompile)); // Line 5
CompilationTask task = compiler.getTask(null, fileManager, diagnosticsCollector, null, null, fileObjects); // Line 6
		Boolean result = task.call(); // Line 7
List> diagnostics = diagnosticsCollector.getDiagnostics();
		for(Diagnostic d : diagnostics){
			// Print all the information here.
		}
		if(result == true){
			System.out.println("Compilation has succeeded");
		}else{
			System.out.println("Compilation fails.");
		}
}
}

Compilation of Java Source from a String object

Having discussed about the various ways of compiling java file sources, it’s now time to look at how to compile a java source that is encapsulated in a string object. As previously mentioned, it is not mandatory that the contents of a java source must reside in hard-disk, it can even reside in memory. By saying that compiling a java source from a string object, we are implicitly saying that the java source is residing in memory, more specifically, the contents are residing in RAM.

For this to happen, we have to encapsulate a class the represents the java source from a string. We can extend this class from the SimpleJavaFileObject (a convenient class that overrides all the methods in the JavaFileObject with some default implementation). The only method to override is the getCharContent() that will be called internally by the Java compiler to get the java source contents.

JavaObjectFromString.java:
package test;
import java.net.URI;
class JavaObjectFromString extends SimpleJavaFileObject{
    private String contents = null;
public JavaObjectFromString(String className, String contents) throws Exception{
    		super(new URI(className), Kind.SOURCE);
this.contents = contents;
    }
public CharSequence getCharContent(boolean ignoreEncodingErrors) throws IOException {
    		return contents;
    }
}

Since the SimpleJavaFileObject has a protected two argument constructor that accepts an URI (the URI representation of the file object) and a Kind object (a special type that tells what kind is this object, the Kind may be a Kind.SOURCE, Kind.CLASS, Kind.HTML, Kind.OTHER, in our case, it is Kind.SOURCE, since we are inferring a Java source object), we have defined a two argument constructor in JavaObjectFromString class and delegates the control back the base class. The getCharContent() method has to be overridden (since this is the method that will be called by the JavaCompiler to get the actual java source contents) to return the string (remember, String implements CharSequence) that represents the entire java source (which was previously saved in the constructor).

The code that uses this JavaObjectFromString object looks like this.

AdvancedCompilationTest3.java:
package test;
import java.io.*;
import java.util.*;
import javax.tools.*;
import javax.tools.JavaCompiler.*;
public class AdvancedCompilationTest3 {
	public static void main(String[] args) throws Exception {
JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();
		DiagnosticCollector diagnosticsCollector =
			new DiagnosticCollector();
		StandardJavaFileManager fileManager  =
compiler.getStandardFileManager(diagnosticsCollector, null, null);
JavaFileObject javaObjectFromString = getJavaFileContentsAsString();
Iterable fileObjects = Arrays.asList(javaObjectFromString);
CompilationTask task = compiler.getTask(null, fileManager, diagnosticsCollector, null, null, fileObjects);
		Boolean result = task.call();
List> diagnostics = diagnosticsCollector.getDiagnostics();
		for(Diagnostic d : diagnostics){
			// Print all the information here.
		}
		if(result == true){
			System.out.println("Compilation has succeeded");
		}else{
			System.out.println("Compilation fails.");
		}
	}
	static SimpleJavaFileObject getJavaFileContentsAsString(){
		StringBuilder javaFileContents = new StringBuilder("" +
				"class TestClass{" +
				"	public void testMethod(){" +
	"		System.out.println(" + "\"test\"" +           ");" +
				"}" +
				"}");
		JavaObjectFromString javaFileObject = null;
		try{
javaFileObject = new JavaObjectFromString("TestClass", javaFileContents.toString());
		}catch(Exception exception){
			exception.printStackTrace();
		}
		return javaFileObject;
	}
}

Conclusion

Before the release of Mustang, the compiler API related interfaces and classes were maintained in some non-standard packages (i.e inside com.sun.javac.tools.javac). But with Java 6.0, the designers of java have given great heights to compilation API by generalizing them in the javax.tools package. As already mentioned, this API is not for everyone. Web and Application servers can depend on this API exhaustively to provide compilation activities of the dynamically created Java source files. Although it is heard that more and more bugs related to Compiler API are there, they are expected to be fixed soon in the future builds.