Core Java Technologies Tech Tips

Exchanging Data With XML and JAXB, Part 2

2008-09-15T09:57:04-07:00

by Jennie Hall

In Exchanging Data With XML and JAXB, Part 1, we saw how the Java Architecture for XML Binding (JAXB) expedites the exchange of data between systems. With JAXB 2.0's annotation support, generating XML data for a business partner is as easy as annotating your existing object model.

In this tip, you'll learn how JAXB's binding customization features can facilitate XML processing for the recipient of data as well as for the sender. Binding customization offers a level of control over the characteristics of the Java classes generated by the JAXB schema compiler. This allows you to work with an object model that makes sense for your business domain even when processing XML instance documents based on a schema that is not of your own design.

For a brief overview of the Java Architecture for XML Binding (JAXB), see the "What's JAXB?" section of Exchanging Data With XML and JAXB, Part 1.

The Sample Application

Let's continue with our scenario from Part 1.A veterinary office, NiceVet, wants to send upcoming appointment reminders and pet birthday cards to its clients. NiceVet contracts with a service provider, WePrintStuff, to do the printing and mailing. In Part 1, we assembled some data for WePrintStuff by annotating NiceVet's existing object model and then using JAXB to marshal application data from Java objects to an XML instance document. We also used JAXB's schema generator to produce a corresponding schema from the annotated Java classes.

On the receiving end, WePrintStuff will run the JAXB schema compiler against the source schema to generate the schema-derived classes. JAXB will create instances of these classes as it unmarshals NiceVet's data from the XML instance document and binds it into a Java content tree. In some cases, however, the default manner in which JAXB generates the schema-derived classes and binds the data is not exactly what is needed. JAXB's binding customization features provide us with some nice ways to handle many of these cases. We'll take a look at some of them in the next section.

Customizing the Source Schema

We can make some customizations right away to make life easier at WePrintStuff. For example, we would like to work with meaningful package and class names and avoid any naming collisions. To accomplish this, we can add custom binding declarations to the source schema itself -- this is known as inline customization.

Here are the first few lines of the annotated schema:

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema"
				 <!-- JAXB namespace declaration required for inline customization -->
	                         xmlns:jxb="http://java.sun.com/xml/ns/jaxb"
	                         xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
	                         jxb:extensionBindingPrefixes="xjc"
				 <!-- JAXB version number required for inline customization -->
	                         jxb:version="2.0">
	    <xs:annotation>
	        <xs:appinfo>
                    <!-- All collections in this schema will use implementation class java.util.ArrayList. -->
	            <jxb:globalBindings collectionType="java.util.ArrayList"/>
	            <jxb:schemaBindings>
                        <!-- Specify the package for the generated classes; avoid naming collisions. -->
	                <jxb:package name="weprintstuff.generated">
                            <!-- Specify some Javadoc that describes our package and its uses. -->
	                    <jxb:javadoc><![CDATA[<body> The package weprintstuff.generated contains the
                                 schema-derived classes that make up the object model used to process
                                 print client orders.</body>]]>
	                    </jxb:javadoc>
	                </jxb:package>
	            </jxb:schemaBindings>
	        </xs:appinfo>
	    </xs:annotation>

To enable inline customization, we must include a JAXB namespace declaration and the JAXB version number. The JAXB namespace prefix we'll use in our sample application is jxb:. We can override the default JAXB bindings at different scopes. Lower-level, more fine-grained scopes inherit declarations made at higher-level scopes, but binding declarations made at lower-level scopes can override these inherited declarations. The scopes in order from highest to lowest level are global, schema, definition, and component.

In the preceding example, we've made a declaration at global scope that specifies that all collections in this schema will use the implementation class java.util.ArrayList. If our source schema imported another schema, this declaration would apply to the second schema as well. There can be only one <globalBindings> declaration per schema. This declaration is valid in the top-level schema only.

At schema scope, we've specified the package into which the JAXB schema compiler will generate the schema-derived classes. We've also included some package-level Javadoc that describes our package and its uses. Note that we've wrapped our custom binding declarations in <annotation><appinfo> tags.

Now that we have the package we want, let's see if we can get some class names that better reflect Java naming conventions and WePrintStuff's business domain. The default bindings for the original schema would generate classes with names like ClassAType, ClassBType, and so on.This is not how we typically name classes in the Java programming language, so let's fix it:

    <xs:element name="printOrder" type="PrintOrderType"/>
    <xs:complexType name="PrintOrderType">
        <xs:annotation>
            <xs:appinfo>
                <!-- Name the generated class PrintOrder rather than PrintOrderType. -->
                <jxb:class name="PrintOrder">
                    <!-- Provide some Javadoc for PrintOrder. -->
                    <jxb:javadoc><![CDATA[<code>PrintOrder</code> javadoc goes here]]>
                    </jxb:javadoc>
                </jxb:class>
            </xs:appinfo>
        </xs:annotation>
        <xs:sequence>
            <xs:element name="notifications" type="notificationsType" minOccurs="0">
                <xs:annotation>
                    <xs:appinfo>
                        <!-- PrintOrder's notifications property becomes printItems. -->
                        <jxb:property name="printItems"/>
                    </xs:appinfo>
                </xs:annotation>
            </xs:element>
        </xs:sequence>
		...
    </xs:complexType>
    <xs:complexType name="notificationsType">
        <xs:annotation>
            <xs:appinfo>
                <!-- Name the generated class PrintItems rather than NotificationsType. -->
                <jxb:class name="printItems" />
            </xs:appinfo>
        </xs:annotation>
			...
    </xs:complexType>

PrintOrderType becomes PrintOrder, NotificationsType becomes PrintItems, and so on. Dealing with class names is straightforward, but unfortunately we're stuck with a class structure that is less than ideal. There are too many wrappers around the data, which results in a long chain of method calls. Here's what the calls would have looked like with classes derived from the original schema. As you can see, methods with singular method names return collections, which is misleading.

	List<AppointmentType> appointments = printOrder.getNotifications().getAppointments().getAppointment();
	List<BirthdayType> birthdays = printOrder.getNotifications().getBirthdays().getBirthday();

The following improved calls show the new names, which say what they mean and are more relevant to WePrintStuff's business domain.

	List<Appointment> appointments = printOrder.getPrintItems().getAppointmentHolder().getAppointments();
	List<Birthday> birthdays = printOrder.getPrintItem().getBirthdayHolder().getBirthdays();

I tried to solve some of the class structure issues by using the enhanced <jxb:javaType> customization (<xjc:javaType>) and an adapter class derived from XmlAdapter, but JAXB currently does not support this customization for XML complex types. This issue is documented in the JAXB issue tracker as issue number 209. Meanwhile, we'll look at an example of the enhanced <jxb:javaType> customization used with an XML simple type in the upcoming paragraphs.

Moving down the source schema, we see that each print order received will have an ID of type long. We know, however, that WePrintStuff employs a natural key strategy in its persistent store. For print-order records, the key consists of a client name and an order ID. WePrintStuff uses the class PrintOrderKey to encapsulate this key information. We'll apply a binding customization that causes the JAXB schema compiler to use an adapter class, IdAdapter, to replace the original print-order ID with WePrintStuff's PrintOrderKey class. Take a look:

   <xs:element name="printOrder" type="PrintOrderType"/>
    <xs:complexType name="PrintOrderType">
        <xs:sequence>
            <xs:element name="notifications" type="notificationsType" minOccurs="0"/>
        </xs:sequence>
        <xs:attribute name="id" type="xs:long" use="required">
            <xs:annotation>
                <xs:appinfo>
                    <!-- Use an XmlAdapter-based adapter to create WePrintStuff's PrintOrderKey class. -->
                    <!-- Specify the name orderKey for this property. -->
                    <jxb:property name="orderKey">
                        <jxb:baseType>
                            <!-- Specify weprintstuff.print.PrintOrderKey as the type of the orderKey property. -->
                            <!-- Specify the adapter class that will map the schema type to the Java type. -->
                            <xjc:javaType name="weprintstuff.print.PrintOrderKey"
                              adapter="weprintstuff.print.IdAdapter"/>
                        </jxb:baseType>
                    </jxb:property>
                </xs:appinfo>
            </xs:annotation>
        </xs:attribute>
    </xs:complexType>

We've changed the name of the print-order property to orderKey and specified the types of the adapter and the order key. During the unmarshalling process, JAXB calls IdAdapter's unmarshal() method, which receives the value of id and incorporates it into a new PrintOrderKey containing the order ID and client name. Here's the code for IdAdapter:

	public class IdAdapter extends XmlAdapter<String, PrintOrderKey> {

	    // When marshalling a Java content tree to an XML instance document,
	    // move from the type that we work with in Java (PrintOrderKey)
	    // to the type that JAXB understands.
	    public String marshal(PrintOrderKey key) throws Exception {
	        return key.getOrderId().toString();
	    }

	    // When unmarshalling an XML instance document to a Java content tree,
	    // move from the type that JAXB understands (String) to the type
	    // we want to work with in Java technology.
	    public PrintOrderKey unmarshal(String id) throws Exception {
	        // WePrintStuff uses natural keys. Add client name and
	        // convert String ID to required Long.
	        return new PrintOrderKey("NICEVET", new Long(id));
	    }
	}

The <xjc:javaType> customization we've just discussed is an example of a vendor extension. The JAXB reference implementation (RI) offers additional customizations that are not part of the JAXB specification. To use these extensions, we must include a declaration for the JAXB RI vendor extension namespace and specify a namespace prefix:

	<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema"
	                         xmlns:jxb="http://java.sun.com/xml/ns/jaxb"
                                 <!-- JAXB RI vendor extension namespace declaration is required. -->
	                         xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
                                 <!-- JAXB RI vendor extension namespace prefix is required. -->
                                 jxb:extensionBindingPrefixes="xjc"
	                         jxb:version="2.0">

Finally, vendor extensions require that we run the schema compiler with the -extension switch. For an example of the standard <jxb:javaType> customization, which is not a vendor extension, check out niceVet.xsd and weprintstuff.print.CustomDataTypeConverter. These files are included with the sample code that comes with this tech tip. In our example, we've used the <jxb:javaType> customization to convert XML dateTime types to nicely formatted String dates ready for output.

Things are looking better, but we'd also like to handle the printing of appointment reminders and birthday cards as polymorphically as we can. Take a look at the following:

   <xs:complexType name="AppointmentType">
        <xs:annotation>
            <xs:appinfo>
                <!-- Name has generated class Appointment rather than AppointmentType. -->
                <jxb:class name="Appointment">
                    <jxb:javadoc><![CDATA[<code>Appointment</code> javadoc goes here]]>
                    </jxb:javadoc>
                </jxb:class>
            </xs:appinfo>
        </xs:annotation>
        <xs:complexContent>
            <!-- XML Schema extension element causes AppointmentType to derive from printItemType, a type we've added to the schema. -->
            <xs:extension base="printItemType">
                <xs:sequence>
                   ...
                </xs:sequence>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
        ...
    <!-- Add this complex type to the schema so that Appointment class now derives from PrintItem, a base class that we've implemented. -->
    <xs:complexType name="printItemType">
        <xs:annotation>
            <xs:appinfo>
                <!-- Due to this customization, JAXB will not generate a class for printItemType; it will use the PrintItem class that we've written. -->
                <jxb:class ref="weprintstuff.print.PrintItem"/>
            </xs:appinfo>
        </xs:annotation>
    </xs:complexType>

Fortunately for us, we can modify the structure of the source schema somewhat while retaining the schema's ability to validate the same set of XML instance documents. In this case, we have added a totally new complex type, printItemType, to the schema. Then we modified the complex type AppointmentType with the XML Schema extension element, causing AppointmentType to derive from printItemType.

At this point, we applied a JAXB customization to printItemType that directs the schema compiler to use the specified class that we've written rather than generating one. Because we've implemented PrintItem ourselves, we can include behavior: specifically, a print() method that allows us to handle subclasses, such as Appointment and Birthday, in a more polymorphic manner. Here's the code for PrintItem:

	package weprintstuff.print;

	import java.util.*;

	public abstract class PrintItem {

	    private static final Map<String,Printer> printers;

	    static {
	        printers = new HashMap<String,Printer>();
	        printers.put("weprintstuff.generated.Birthday", new BirthdayPrinter());
	        printers.put("weprintstuff.generated.Appointment", new AppointmentPrinter());
	    }

	    public void print() {
	        Printer p = this.getPrinter();
	        p.print(this);
	    }

	    private Printer getPrinter() {
	        return printers.get(this.getClass().getName());
	    }
	}

The Printer interface has a single method:

    public void print(PrintItem item);

Although we're still hampered by the structure of the schema-derived classes as discussed earlier, the code to print the items in the print order is now pretty clean. Here's an excerpt from our main() method:

	// Unmarshal the data in the XML instance document to a Java content tree
	// made up of instances of the schema-derived classes.
	JAXBElement printOrderElement = (JAXBElement)unmarshaller.unmarshal(new FileInputStream(input));
	PrintOrder printOrder = (PrintOrder)printOrderElement.getValue();

	List<Appointment> appointments = printOrder.getPrintItems().getAppointmentHolder().getAppointments();
	for (Appointment a : appointments) {
		a.print();
	}

	List<Birthday> birthdays = printOrder.getPrintItems().getBirthdayHolder().getBirthdays();
	for (Birthday b : birthdays) {
		b.print();
	}

Another nice customization feature that JAXB provides is the ability to map XML simple types to typesafe enumerations. This is convenient because WePrintStuff currently has printing templates for certain types of appointments only. We'll modify the schema to include the supported appointment types and add a customization that causes the schema compiler to map the elements of ApptType to a Java typesafe enum class. XML instance documents with appointment types that WePrintStuff does not support will be rejected:

    <xs:simpleType name="ApptType">
        <xs:annotation>
            <xs:appinfo>
                <!-- Map the elements of this simple type to a Java typesafe enum class. -->
                <jxb:typesafeEnumClass/>
            </xs:appinfo>
        </xs:annotation>
        <!-- Use XML Schema elements restriction and enumeration to define the supported appointment types. -->
        <xs:restriction base="xs:string">
            <xs:enumeration value="Yearly Checkup"/>
            <xs:enumeration value="Well Mom Exam"/>
            <xs:enumeration value="Teeth Cleaning"/>
            <xs:enumeration value="Vaccination"/>
            <xs:enumeration value="Senior Pet Checkup"/>
        </xs:restriction>
    </xs:simpleType>

Here is the resultant typesafe enum class, ApptType:

	package weprintstuff.generated;

	import javax.xml.bind.annotation.XmlEnum;
	import javax.xml.bind.annotation.XmlEnumValue;
	import javax.xml.bind.annotation.XmlType;

	@XmlType(name = "ApptType")
	@XmlEnum
	public enum ApptType {

	    @XmlEnumValue("Yearly Checkup")
	    YEARLY_CHECKUP("Yearly Checkup"),
	    @XmlEnumValue("Well Mom Exam")
	    WELL_MOM_EXAM("Well Mom Exam"),
	    @XmlEnumValue("Teeth Cleaning")
	    TEETH_CLEANING("Teeth Cleaning"),
	    @XmlEnumValue("Vaccination")
	    VACCINATION("Vaccination"),
	    @XmlEnumValue("Senior Pet Checkup")
	    SENIOR_PET_CHECKUP("Senior Pet Checkup");
	    private final String value;

	    ApptType(String v) {
	        value = v;
	    }

	    public String value() {
	        return value;
	    }

	    public static ApptType fromValue(String v) {
	        for (ApptType c: ApptType.values()) {
	            if (c.value.equals(v)) {
	                return c;
	            }
	        }
	        throw new IllegalArgumentException(v);
	    }

	}

So far we've made what are known as inline binding customizations, but JAXB also accepts customizations in the form of one or more external binding customization files. Inline and external customizations can be used in combination, but they cannot be used together on the same element. External binding files are useful when you cannot modify a given schema or when you want to reuse customizations across schemas. For example, WePrintStuff has its own class for U.S. addresses, DomesticAddress, and WePrintStuff would like to use this class to represent the concept of an address throughout the system.

Here's the external binding file, binding.xjb:

	<!-- XML Schema namespace is required, as are the JAXB namespace and version. -->
	<jxb:bindings version="2.0"
	               xmlns:jxb="http://java.sun.com/xml/ns/jaxb"
	               xmlns:xs="http://www.w3.org/2001/XMLSchema">

	  <!-- Specify the schema name and root schema node. -->
	  <jxb:bindings schemaLocation="niceVet.xsd" node="/xs:schema">

	    <!-- Specify the schema node to which this customization should apply with an XPath expression. -->
	    <jxb:bindings node="//xs:complexType[@name='AddressType']">
                <!-- Direct the schema compiler to use the DomesticAddress class rather than generating a class for complex type AddressType. -->
	        <jxb:class ref="weprintstuff.print.DomesticAddress"/>
	    </jxb:bindings> <!-- node="//xs:complexType[@name='AddressType']" -->

	  </jxb:bindings> <!-- schemaLocation="niceVet.xsd" node="/xs:schema" -->
	</jxb:bindings>

The binding customization file is just an ASCII text file. A valid binding file must specify the schema name and node. We identify nodes using XPath expressions. In the previous listing, we've applied a customization that directs the schema compiler to use WePrintStuff's DomesticAddress class rather than generating a class for the complex type AddressType. This is the same customization illustrated earlier in our PrintItem base class example, although in that situation, we declared the customization inline. The syntax for supplying a binding customization file to the schema compiler is the following:

	xjc -b bindings schema

We can apply multiple binding files to one schema, one binding file to multiple schemas, or multiple binding files to multiple schemas. Each binding file must have its own -b switch.

Generating the Schema-Derived Classes

We generate our schema-derived classes at the command line with the following command to the schema compiler, xjc:

	xjc -d ./src -b binding.xjb -extension niceVet.xsd

The schema compiler informs us that it has generated our classes with the following output:

	parsing a schema...
	compiling a schema...
	weprintstuff\generated\Adapter1.java
	weprintstuff\generated\Adapter2.java
	weprintstuff\generated\Appointment.java
	weprintstuff\generated\ApptType.java
	weprintstuff\generated\Birthday.java
	weprintstuff\generated\ObjectFactory.java
	weprintstuff\generated\Owner.java
	weprintstuff\generated\Pet.java
	weprintstuff\generated\PrintItems.java
	weprintstuff\generated\PrintOrder.java
	weprintstuff\generated\package.html

The JAXB schema compiler has a number of options. For example, it will mark generated classes as read only in response to the -readOnly switch. Invoke xjc with no options or with the -help switch for more information.

The Payoff

We've modified our source schema, made our customizations, and generated our schema-derived classes. All that's left to do is run our printing program, let JAXB bind the XML data supplied by NiceVet, and print out the appointment reminders and birthday cards. We'll take a look at our XML instance document:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<printOrder id="1219271208522">
    <notifications>
        <appointments>
            <appointment>
                <apptType>Yearly Checkup</apptType>
                <apptDate>2008-09-15T00:00:00-07:00</apptDate>
                <owner>
                    <firstName>Joe</firstName>
                    <lastName>Outdoors</lastName>
                    <address>
                        <addressLine1>123 Whitewater Street</addressLine1>
                        <city>OurTown</city>
                        <state>CA</state>
                        <zip>90347</zip>
                        <zipExt>1234</zipExt>
                    </address>
                </owner>
                <pet>
                    <name>Honcho</name>
                    <species>Dog</species>
                </pet>
            </appointment>
            <appointment>
                <apptType>Well Mom Exam</apptType>
                <apptDate>2008-09-12T00:00:00-07:00</apptDate>
                <owner>
                    <firstName>Missy</firstName>
                    <lastName>Fairchild</lastName>
                    <address>
                        <addressLine1>456 Scenic Drive</addressLine1>
                        <city>West OurTown</city>
                        <state>CA</state>
                        <zip>90349</zip>
                        <zipExt>6789</zipExt>
                    </address>
                </owner>
                <pet>
                    <name>Miss Kitty</name>
                    <species>Cat</species>
                </pet>
            </appointment>
        </appointments>
        <birthdays>
            <birthday>
                <age>7</age>
                <birthday>2000-09-07T00:00:00-07:00</birthday>
                <owner>
                    <firstName>Violet</firstName>
                    <lastName>Flowers</lastName>
                    <address>
                        <addressLine1>22375 Willow Court</addressLine1>
                        <city>West OurTown</city>
                        <state>CA</state>
                        <zip>90349</zip>
                        <zipExt>6789</zipExt>
                    </address>
                </owner>
                <pet>
                    <name>Tom</name>
                    <species>Cat</species>
                </pet>
            </birthday>
        </birthdays>
    </notifications>
</printOrder>

And here's another look at the main() method:

	// The XML instance document received from NiceVet contains NiceVet's print order.
	File input = new File("niceVet.xml");

	// Create a JAXBContext for the weprintstuff.generated package.
	JAXBContext ctx = JAXBContext.newInstance("weprintstuff.generated");

	// Create an unmarshaller.
	Unmarshaller unmarshaller = ctx.createUnmarshaller();

	// Unmarshal the data in the XML instance document to a Java content tree made up of instances of the schema-derived classes.

	JAXBElement printOrderElement = (JAXBElement)unmarshaller.unmarshal(new FileInputStream(input));
	PrintOrder printOrder = (PrintOrder)printOrderElement.getValue();

	// Print out the print items.	
        List<Appointment> appointments = printOrder.getPrintItems().getAppointmentHolder().getAppointments();
	for (Appointment a : appointments) {
		a.print();
	}

	List<Birthday> birthdays = printOrder.getPrintItems().getBirthdayHolder().getBirthdays();
	for (Birthday b : birthdays) {
		b.print();
	}

Check out our results: No one will ever miss an appointment or a birthday again.

	Hi Joe!
	Our records show that your dog Honcho has a Yearly Checkup appointment scheduled on 09/15/2008.
	Please call us 24 hours prior to your appointment if you need to reschedule.
	Sincerely, NiceVet

	Hi Missy! Our records show that your cat Miss Kitty has a Well Mom Exam appointment scheduled on 09/12/2008.
	Please call us 24 hours prior to your appointment if you need to reschedule.
	Sincerely, NiceVet

	Hi Violet!
	Our records show that your cat Tom will turn 7 years old on 09/07.
	Happy Birthday, Tom, from all of us at NiceVet!

Running the Sample Application

To run the sample application, download the sample code and unzip it. Navigate to the directory <sample-install-dir>/schema-to-java and generate the schema-derived classes as described in the section "Generating the Schema-Derived Classes."

Launch the NetBeans IDE and select File > Open Project. In the Open Project dialog box, navigate to the directory where you unzipped the sample code and select the folder schema-to-java. Select the Open as Main Project check box. Click Open Project Folder. Right-click the schema-to-java project and select Run Project.

Conclusion

In Exchanging Data With XML and JAXB, Parts 1 and 2, we've learned how JAXB can facilitate the flow of data between business partners. With features that expedite XML processing on both ends of the exchange, JAXB can enable simpler, more productive integration between systems.

References and Resources

Sample code for this tip
Java EE 5 Tutorial
Kohsuke Kawaguchi's Blog - Kohsuke Kawaguchi is a staff engineer at Sun Microsystems, where he works on JAXB, among other projects.
JSR 222: JAXB Specification

About the Author

Jennie Hall is a lead developer working in the financial sector.

Exchanging Data with XML and JAXB, Part 1

2008-08-12T16:35:28-07:00

by Jennie Hall

In this tip, you'll learn how to to use the Java Architecture for XML Binding (JAXB) in Java SE 6 to exchange XML data between systems without having to delve into the specifics of XML processing. Among other key improvements, JAXB 2.0 offers support for binding Java objects to XML via the use of annotations. This feature allows you to generate XML data from your application simply by annotating your existing object model.

What's JAXB?

JAXB simplifies the use of XML data in Java applications by shielding you and your code from the low-level details of working with XML. Essentially, JAXB allows you to move easily back-and-forth between XML and Java. A JAXB implementation supplies a schema compiler, which takes in an XML schema and generates Java classes which map to that schema. Data from XML documents which are instances of the schema can be bound automatically to the generated classes by JAXB's binding runtime framework. This is called unmarshalling. Once unmarshalled, content can be manipulated or modified in Java as needed. JAXB can also write (marshal) data from Java objects to an XML instance document. JAXB optionally performs validation of content as part of these operations.

In addition to the schema compiler, a JAXB implementation also provides a schema generator, which looks at annotations on Java classes and generates a corresponding XML schema. This feature is new to JAXB 2.0.

The Sample Application

A veterinary office wants to send notices to its clients reminding them of their pets' upcoming appointments. Because they are nice folks, they also like to send a birthday card to an owner on the pet's birthday. The veterinary office, NiceVet, contracts with a service provider, WePrintStuff, to do their printing and mailing for them.

NiceVet already has an application which maintains information about the animals under NiceVet's care and their owners. Here's a diagram of NiceVet's existing object model:

NiceVet needs a way to get the necessary notification data to WePrintStuff for processing without spending a lot of time and money modifying their current application.

Generating the XML

It's time to annotate our object model so we can generate some XML data for the printing and mailing service. Looking at NiceVet's object model, we see that the PrintOrder class holds the information about upcoming events, and thus makes sense as the root element of the data we want to send. Let's add the @XmlRootElement annotation to the PrintOrder class. This will establish printOrder as the root element of our generated XML.

	import javax.xml.bind.annotation.XmlRootElement;

	// the root element of our generated XML
	@XmlRootElement(name = "printOrder")
	public class PrintOrder {

	    private long id;
	    private List<Event> events;

Let's add some more annotations:

	import javax.xml.bind.annotation.XmlRootElement;
	import javax.xml.bind.annotation.XmlType;
	import javax.xml.bind.annotation.XmlAccessorType;
	import javax.xml.bind.annotation.XmlAccessType;
	import javax.xml.bind.annotation.XmlAttribute;
	import javax.xml.bind.annotation.XmlElement;
	import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;

	// the root element of our generated XML
	@XmlRootElement(name = "printOrder")
	// maps this class to a generated schema type
	@XmlType(name = "PrintOrderType", propOrder = {"events"})
	// bind all non-static, non-transient fields
	// to XML unless annotated with @XmlTransient
	@XmlAccessorType(XmlAccessType.FIELD)
	public class PrintOrder {

	    // maps this field to an XML attribute
	    @XmlAttribute(required = true)
	    private long id;
	    // custom adapter maps this field to a type,

	    // NotificationsType, which makes it easy to
	    // generate the desired XML
	    @XmlJavaTypeAdapter(value=EventAdapter.class)   
	    @XmlElement(name = "notifications")
	    private List<Event> events;

@XmlType maps the PrintOrder class to a generated schema type named PrintOrderType. The @XmlAccessorType(XmlAccessType.FIELD) annotation tells JAXB to bind all non-static, non-transient fields to XML unless annotated with @XmlTransient, which prevents the mapping of a field or property. With the XmlAccessType.FIELD setting, getter/setter pairs are not bound to XML unless explicitly annotated. The default setting is XmlAccessType.PUBLIC_MEMBER (all public fields and getter/setter pairs are bound unless otherwise annotated); other settings are XmlAccessType.PROPERTY and XmlAccessType.NONE.

Moving down the code listing, we see that the field id maps to an XML attribute on the PrintOrderType element. Some kind of identifier on the print order is required, and we've annotated the id field accordingly.

The PrintOrder class has a list of events which contains both appointments and birthdays. The annotation @XmlJavaTypeAdapter tells JAXB that we are going to use a custom adapter, EventAdapter, to help us map this Java construct to XML. To support this annotation, we need to write an adapter class which extends XmlAdapter and overrides its abstract marshal and unmarshal methods.

	public class EventAdapter extends XmlAdapter<NotificationsType, List<Event>> {

	    // adapt original Java construct to a type, NotificationsType,
	    // which we can easily map to the XML output we want
	    public NotificationsType marshal(List<Event> events) throws Exception {
	        List<Appointment> appointments = new ArrayList<Appointment>();
	        List<Birthday> birthdays = new ArrayList<Birthday>();
	        
	        for (Event e : events) {
	            if (e instanceof Appointment) {
	                appointments.add((Appointment)e);
	            } else {
	                birthdays.add((Birthday)e);              
	            }
	        }        
	        return new NotificationsType(appointments, birthdays);
	    }

	    // reverse operation: map XML type to Java
	    public List<Event> unmarshal(NotificationsType notifications) throws Exception { ... }

EventAdapter's marshal method takes the original Java construct, List<Event> events, and converts it to a type which maps more easily to the XML output we want. Let's take a look at NotificationsType:

	import javax.xml.bind.annotation.XmlElementWrapper;
	import javax.xml.bind.annotation.XmlElement;
	import java.util.List;

	public class NotificationsType {
	    
	    // produce a wrapper XML element around this collection
	    @XmlElementWrapper(name = "appointments")
	    // maps each member of this list to an XML element named appointment
	    @XmlElement(name = "appointment")
	    //private List<Appointment> appointments;
	    private List<Appointment> appointments;
	    // produce a wrapper XML element around this collection
	    @XmlElementWrapper(name = "birthdays")
	    // maps each member of this list to an XML element named birthday
	    @XmlElement(name = "birthday")
	    //private List<Birthday> birthdays;
	    private List<Birthday> birthdays;
	    
	    public NotificationsType() {}
	    
	    public NotificationsType(List<Appointment> appointments, List<Birthday> birthdays) {
	        this.appointments = appointments;
	        this.birthdays = birthdays;
	    }

The @XmlElementWrapper annotation creates a wrapper XML element around each collection, and the @XmlElement annotation maps each member of the collection to an XML element of the appropriate type. Combined with the @XmlElement(name = "notifications") annotation on PrintOrder.events, what we end up with will look something like this:

	<printOrder>
		<notifications>
			<appointments>
				<appointment>
					...
				</appointment>
			</appointments>
			<birthdays>
				<birthday>
					...
				</birthday>
			</birthdays>
		</notifications>
	</printOrder>

Another annotation worth mentioning lies in the abstract base class Event (listing below), from which subclasses Appointment and Birthday inherit. This inheritance hierarchy won't hold much meaning for our service provider, WePrintStuff, so we'll eliminate it with the @XmlTransient annotation on Event. We still need fields owner and pet, however, so we annotate them with @XmlElement(required = true).

	import javax.xml.bind.annotation.XmlElement;
	import javax.xml.bind.annotation.XmlTransient;

	// no need to capture this inheritance hierarchy in XML
	@XmlTransient
	public abstract class Event {

	    @XmlElement(required = true)
	    private Owner owner;
	    @XmlElement(required = true)
	    private Pet pet;

	    public Event() {}
	            
	    public Event(Owner owner, Pet pet) {
	       this.owner = owner;
	       this.pet = pet;
	    }

When objects of type Birthday and Appointment are marshalled to XML, they will include all the relevant data from their supertype, Event. Take a look at the listing below for the Birthday class:

	@XmlType(name = "BirthdayType", propOrder = {"age", "birthday", "owner", "pet"})
	@XmlAccessorType(XmlAccessType.FIELD)
	public class Birthday extends Event {

	    @XmlElement(required = true)
	    private int age;
	    
	    public Birthday() {}
	    
	    public Birthday(Owner owner, Pet pet) {
	        super(owner, pet);
	        this.age = this.calculateAge();
	    }

	    @XmlElement(name = "birthday", required = true)
	    public Date getBirthday() {
	        return this.getPet().getDateOfBirth();
	    }

@XmlType.propOrder specifies the order in which content is marshalled and unmarshalled. This order would otherwise be unspecified due to the nature of Java reflection. Alternatively, you can impose an order with the @XmlAccessorOrder annotation. As mentioned in the Java Tutorial, imposing an order improves application portability across JAXB implementations.

Although the field dateOfBirth is actually on the Pet class, it makes more sense in terms of our XML representation if this data is organized as an element under the birthday element. We can achieve this without a dateOfBirth field on the Birthday class by annotating the getBirthday() method, which delegates to Pet.

On a related note, WePrintStuff doesn't need to do any additional processing with the dates NiceVet sends them; they just need to locate the correct notification template and print the information out. As we saw earlier with the events list on the PrintOrder class, we can supply a custom adapter to get the desired XML output. This time, however, we'll specify the adapter through a package-level annotation. The adapter will take in all java.util.Date instances and output nicely formatted Strings. The package-level annotation goes in the package-info.java file (located in the vet package):

	// every java.util.Date class in the vet package should be
	// processed by DateAdapter
	@XmlJavaTypeAdapter(value=DateAdapter.class, type=Date.class)
	package vet;

	import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
	import java.util.Date;

Although JAXB can handle marshalling java.util.Date to XML in a default manner on its own, we're telling JAXB to use an alternative, customized mapping which better suits our purposes. We implement the adapter in much the same way as above:

	import java.util.Date;
	import java.text.SimpleDateFormat;
	import javax.xml.bind.annotation.adapters.XmlAdapter;

	public class DateAdapter extends XmlAdapter<String, Date> {

		// the desired format
	    private String pattern = "MM/dd/yyyy";
	    
	    public String marshal(Date date) throws Exception {
	        return new SimpleDateFormat(pattern).format(date);
	    }
	    
	    public Date unmarshal(String dateString) throws Exception {
	        return new SimpleDateFormat(pattern).parse(dateString);
	    }

The annotations on the other classes in the object model are similar to what we've seen so far; take a peek at the sample code included with this tip to see exactly what's going on in the other classes.

We've finished annotating NiceVet's object model and we're ready to generate some XML. If we run the sample application, we should see an XML instance document something like the following listing. The document, niceVet.xml, is located in the root directory of the java-to-schema project.

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<printOrder id="1218226109781">
	    <notifications>
	        <appointments>
	            <appointment>
	                <apptType>Yearly Checkup</apptType>
	                <apptDate>09/15/2008</apptDate>
	                <owner>
	                    <firstName>Joe</firstName>
	                    <lastName>Outdoors</lastName>
	                    <address>
	                        <addressLine1>123 Whitewater Street</addressLine1>
	                        <city>OurTown</city>
	                        <state>CA</state>
	                        <zip>90347</zip>
	                        <zipExt>1234</zipExt>
	                    </address>
	                </owner>
	                <pet>
	                    <name>Honcho</name>
	                    <species>Dog</species>
	                </pet>
	            </appointment>
	            <appointment>
	                <apptType>Well Mom Exam</apptType>
	                <apptDate>09/12/2008</apptDate>
	                <owner>
	                    <firstName>Missy</firstName>
	                    <lastName>Fairchild</lastName>
	                    <address>
	                        <addressLine1>456 Scenic Drive</addressLine1>
	                        <city>West OurTown</city>
	                        <state>CA</state>
	                        <zip>90349</zip>
	                        <zipExt>6789</zipExt>
	                    </address>
	                </owner>
	                <pet>
	                    <name>Miss Kitty</name>
	                    <species>Cat</species>
	                </pet>
	            </appointment>
	        </appointments>
	        <birthdays>
	            <birthday>
	                <age>7</age>
	                <birthday>09/07/2000</birthday>
	                <owner>
	                    <firstName>Violet</firstName>
	                    <lastName>Flowers</lastName>
	                    <address>
	                        <addressLine1>22375 Willow Court</addressLine1>
	                        <city>West OurTown</city>
	                        <state>CA</state>
	                        <zip>90349</zip>
	                        <zipExt>6789</zipExt>
	                    </address>
	                </owner>
	                <pet>
	                    <name>Tom</name>
	                    <species>Cat</species>
	                </pet>
	            </birthday>
	        </birthdays>
	    </notifications>
	</printOrder>

The generated schema for the XML instance document above is named schema1.xsd, and it lives in /generated/schema under the root directory of the java-to-schema project. It looks like this:

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

	  <xs:element name="printOrder" type="PrintOrderType"/>

	  <xs:complexType name="PrintOrderType">
	    <xs:sequence>
	      <xs:element name="notifications" type="notificationsType" minOccurs="0"/>
	    </xs:sequence>
	    <xs:attribute name="id" type="xs:long" use="required"/>
	  </xs:complexType>

	  <xs:complexType name="notificationsType">
	    <xs:sequence>
	      <xs:element name="appointments" minOccurs="0">
	        <xs:complexType>
	          <xs:sequence>
	            <xs:element name="appointment" type="AppointmentType" minOccurs="0" maxOccurs="unbounded"/>
	          </xs:sequence>
	        </xs:complexType>
	      </xs:element>
	      <xs:element name="birthdays" minOccurs="0">
	        <xs:complexType>
	          <xs:sequence>
	            <xs:element name="birthday" type="BirthdayType" minOccurs="0" maxOccurs="unbounded"/>
	          </xs:sequence>
	        </xs:complexType>
	      </xs:element>
	    </xs:sequence>
	  </xs:complexType>

	  <xs:complexType name="AppointmentType">
	    <xs:sequence>
	      <xs:element name="apptType" type="xs:string"/>
	      <xs:element name="apptDate" type="xs:string"/>
	      <xs:element name="owner" type="OwnerType"/>
	      <xs:element name="pet" type="PetType"/>
	    </xs:sequence>
	  </xs:complexType>

	  <xs:complexType name="OwnerType">
	    <xs:sequence>
	      <xs:element name="firstName" type="xs:string"/>
	      <xs:element name="lastName" type="xs:string"/>
	      <xs:element name="address" type="AddressType"/>
	    </xs:sequence>
	  </xs:complexType>

	  <xs:complexType name="AddressType">
	    <xs:sequence>
	      <xs:element name="addressLine1" type="xs:string"/>
	      <xs:element name="addressLine2" type="xs:string" minOccurs="0"/>
	      <xs:element name="city" type="xs:string"/>
	      <xs:element name="state" type="xs:string"/>
	      <xs:element name="zip" type="xs:string"/>
	      <xs:element name="zipExt" type="xs:string" minOccurs="0"/>
	    </xs:sequence>
	  </xs:complexType>

	  <xs:complexType name="PetType">
	    <xs:sequence>
	      <xs:element name="name" type="xs:string"/>
	      <xs:element name="species" type="xs:string" minOccurs="0"/>
	    </xs:sequence>
	  </xs:complexType>

	  <xs:complexType name="BirthdayType">
	    <xs:sequence>
	      <xs:element name="age" type="xs:int"/>
	      <xs:element name="birthday" type="xs:string"/>
	      <xs:element name="owner" type="OwnerType"/>
	      <xs:element name="pet" type="PetType"/>
	    </xs:sequence>
	  </xs:complexType>
	</xs:schema>

If we take a quick peek at the main() method, we can see that we are generating the schema as follows:

	// specify where the generated XML schema will be created
	final File dir = new File("generated" + File.separator + "schema");
	// specify a name for the generated XML instance document
	OutputStream os = new FileOutputStream("niceVet.xml");

	// create a JAXBContext for the PrintOrder class
	JAXBContext ctx = JAXBContext.newInstance(PrintOrder.class);
	// generate an XML schema from the annotated object model; create it
	// in the dir specified earlier under the default name, schema1.xsd
	ctx.generateSchema(new SchemaOutputResolver() {
		   @Override
		   public Result createOutput(String namespaceUri, String schemaName) throws IOException {
				return new StreamResult(new File(dir, schemaName));
		   }
	   });

To get the XML instance document, we first create some data, then we obtain a Marshaller from the JAXBContext and marshal the Java content tree to XML:

	// create some data
	PrintOrder order = new PrintOrder(EventUtil.getEvents());

		...
		
	// create a marshaller   
	Marshaller marshaller = ctx.createMarshaller();
	// the property JAXB_FORMATTED_OUTPUT specifies whether or not the
	// marshalled XML data is formatted with linefeeds and indentation
	marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
	// marshal the data in the Java content tree 
	// to the XML instance document niceVet.xml
	marshaller.marshal(order, os);

Running the Sample Application

To run the sample application, download the sample code and unzip it. Launch NetBeans and select File -> Open Project. In the Open Project dialog box, navigate to the directory where you unzipped the sample code and select the folder java-to-schema. Select the Open as Main Project check box. Click Open Project Folder. Right-click the java-to-schema project and select Run Project.

Conclusion

In this tip, you've seen how JAXB makes it easy to generate XML data to exchange with a business partner. The XML data your partner receives, however, may need a little tweaking in order to mesh with their system. In a future tip, you'll learn how to apply customizations to a supplied schema to get the Java object model - and content tree - you want.

References and Resources

Sample code for this tip

The Java Tutorial.

Kohsuke Kawaguchi's Blog. Kohsuke Kawaguchi is a staff engineer at Sun Microsystems, where among other projects he works on JAXB.

Jennie Hall is a lead developer working in the financial sector.

Where's the State?

2008-08-08T09:52:57-07:00

from Tim Boudreau's Blog

Where's the state? This is a small but useful question when deciding how a problem domain gets carved up into objects: What things have state? What things have values that can change? When and how can they change? Can the changes be observed? Who needs to observe changes in state?

These questions make a good start for figuring out how to carve up a problem domain into objects, if you observe the principle keep all related state in one place. I would go so far as to say that the majority of the appeal of Model-View-Controller (MVC) architecture is that it encourages you to keep state in one place.

One big reason why statefulness matters is threading. In practice, it is common to see designs where threading was an afterthought. This is to be expected. Concurrency is a not natural way for human beings to think. So commonly a library is designed with no thought about threading; then a problem shows up which multi-threading can solve. Threading ends up being introduced into a codebase that was never designed for it. Retrofitting a threading model on something designed without one is very painful and sometimes impossible.

Some threading models can be simple. For example, any time you are writing a Swing application, and you have a method that can do long running I/O, the first line of that method should be

assert !EventQueue.isDispatchThread();

under all circumstances.

But keeping I/O off the event thread is the trivial case. Managing mutations to a model inside an application is a more complicated, less obvious problem.

Any time you find yourself writing a setter (or more generally, mutator) method, it is worth asking yourself Who does this piece of state really belong to? Am I putting state in the right place? Blindly following the beans pattern (add a getter/setter to whatever type you happen to be editing) can result in state being distributed all over objects in an application. The result will be harder to maintain, and if it has any lifespan, less and less maintainable over time. Like entropy, or the no broken windows theory, the more state is distributed all over the place, the more that will masquerade as design and make it okay for a programmer to further diffuse state throughout objects in the application. Human beings can only hold so many things in their minds at a time. The more state is diffused, the more things someone must pay attention to simultaneously to solve a problem in that code.

Read the rest of this blog . . .

Distributing a Java Web Start Application via CD-ROM

2008-07-21T09:49:36-07:00

by Luan O'Carroll

Isn't Java Web Start (JWS) supposed to allow web-based distribution of applications? So why would one want to distribute a Java Web Start (JWS) application via CD-ROM? Well, for a number of reasons. For larger applications, a complete installation can still be a major download even with high-speed broadband. Secondly, not all desktops are online, and not all can access the internet (for corporate security reasons, for example). And, lastly, some people just like CDs.

A client company required that their application be distributed worldwide, including to places where broadband coverage is sparse. The application contains information about a large number of products, including detailed drawings and diagrams. All this information constituted a major part of the application, and a complete installation including the JVM amounts to over 40 MB. In addition to this, the company wanted to be able to distribute the application on CDs at trade fairs and with promotional materials; therefore, a CD-based distribution was required. Normally a CD install is possible using either commercial or open source installers, of which there are many. However, when an application is to run with Java Web Start, it needs to be installed in a specific location and not at the user's discretion, as is the norm for installers.

This article describes the steps involved in installing an application that installs both from CD and the internet. The installation process requires that:

The installed application must check for updates and integrate with the JWS cache.
The installation should work on a machine without an existing or up-to-date version of Java.
The installed application should not require an internet connection.
A installation must be easy to use and must provide a simple user interface.

Application installation is normally carried out with a generic installer application, but a traditional install process would effectively create a separate application that is unaware of JWS. Each time an update is released, the user would have to download and install the new version, whereas a JWS application only downloads those components that have been updated, making the process far more efficient and reliable. The article therefore also describes a JWS application installer.

JWS Primer

Java Web Start allows Java applications to be launched via a link to a JNLP file. The JNLP file describes the main method or entry point into the application and it references the resources used by the application.

When a JWS application is launched, the JVM tries to access the required resources, updating them if necessary, and copies the file to its cache. On subsequent attempts to launch the application, JWS can check this cache and skip download of the resources. If the client machine is offline or if the server cannot be contacted, then JWS can run the application in an offline mode.

If the JWS launch file (the JNLP) were placed on CD, JWS would attempt to contact the server and download any new files. Obviously this would defeat the purpose of distributing the files via CD if the client machine is online. Instead, we need some way to update the JWS cache as though the application had been previously loaded by JWS.

Updating the JWS Cache

The Java 5 version of JWS includes a little known -import option that imports a JWS application into the cache from a specified location.

The CD image at this location is just a copy of what you would normally place on the web server: the JNLP file, plus the .jars and resources referred to by that JNLP file. If you use a servlet to serve up the JNLP, then the CD image will need a self-contained snapshot of the generated JNLP file.

The CD image can thus be installed into the JWS cache by calling:

<JAVA_HOME>/jre/bin/javaws -codebase <CACHE_IMAGE> -import <CACHE_IMAGE>/<XXXX>.jnlp

where <JAVA_HOME> is the root of the (possible new) JVM, <CACHE_IMAGE> is location of the JWS application on the CD, and <XXXX> is the name of the application JNLP file. Later, we will see how this command is automated and wrapped in a simple GUI.

In installing the cached application, JWS conveniently prompts the user to install desktop and menu shortcuts for starting the application. Once the JWS install has been completed, we can again call JWS to start the newly installed application.

<JAVA_HOME>/jre/bin/javaws -import <CACHE_IMAGE>/<XXXX>.jnlp

Again the CD is used, but this time JWS will use the installation referred to by the JNLP file. If the machine is connected to the internet, it will check for updates in the normal way, as part of the process, and then start the application. If there is no network connection, the application will launch as delivered on CD.

The next time the user starts the application they can use the menu or desktop shortcuts and the CD will no longer be needed. Alternatively, the user can start the application from a link on a web page that points to the same URL/JNLP file combination; i.e., the original version from the website.

JVM Complications

One gotcha in all of this is that the above commands require the presence of a JVM, and in some rare cases this may not be installed or may not be available by default on the system path and therefore some extra measures are needed to locate a usable JVM. Furthermore, when a user inserts the CD, the installation should begin, and the installation should check for the presence of an existing JVM. The process of checking for a JVM is then as follows:

Check for a JVM (for the installer).
Install the JVM if not present.
Launch the installer, showing the usual license information.
Install the target JVM (if required by the application and different from 1 above).
Import the JWS cache.
Start the JWS application.

Some further complications arise from the fact that the minimum JVM for the JWS -import option is Java 5, so even if a JVM is present and usable for the application, this import option will still require a fairly recent JVM. Secondly, the import process takes some time and must complete before the application is launched, and this sort of delayed execution is difficult to achieve with many of the normal installers.

Given these complications, it was necessary to build a custom launch application that could perform these steps.

Read the rest of the article.

Launch Java Applications from Assembly Language Programs

2008-07-02T15:21:27-07:00

by Biswajit Sarkar

Java Native Interface (JNI) is a mechanism that can be used to establish communication between native language programs and the Java virtual machine. The documentation for JNI and the technical literature on JNI deal extensively with interactions between the JVM and C/C++ code. The Java SDK even provides a utility to generate a header file to facilitate calling C/C++ programs from Java code. However, there is hardly any mention of Java and assembly language code working together. In an earlier article I showed how assembly language programs can be called from Java applications. Here I deal with the technique for invoking Java programs from an ASM process through a demo application that calls a Java method from assembly language code. The Java method brings up a Swing JDialog to show that it has, indeed, been launched.

Why Java with ASM?

JNI is essential to the implementation of Java, since the JVM needs to interact with the native platform to implement some of its functionality. Apart from that, however, use of Java classes can often be an attractive supplement to applications written in other languages, as Java offers a wide selection of APIs that makes implementation of advanced functions very simple.

Some time ago, I was associated with an application to collect real-time data from a number of sources and save them in circular buffers so that new data would overwrite old data once the buffer got filled up. If a designated trigger event was sensed through a digital input, a fixed number of data samples would be saved in the buffers so that a snapshot of pre- and post-trigger data would be available. The original application was written in assembly language. After the application was used for a few months, it was felt that it would be very useful to have the application mail the snapshots to authorized supervisors whenever the trigger event occurred. Of course, it would have been possible to write this extension in assembly, but the team felt that in that particular instance it was easier to write that extension in Java and hook it up with the ASM program. As I had earlier worked with ASM-oriented JNI, I knew this could be done and, indeed, the project was implemented quickly and successfully.

I am sure there are many legacy applications written in assembly language that could benefit from such add-ons. However, it is not only for old applications in need of renovation that JNI can prove useful. Although it may seem unlikely to some of us, assembly language is still used for writing selected portions of new programs. In an article published not very long ago, the author says, "I have found that many of Sun's partners still use assembly language in their products to ensure that hot code paths are as efficient as possible. While compilers are able to generate much more efficient code today, the resulting code still doesn't always compete with hand-coded assembly written by an engineer that knows how to squeeze performance out of each microprocessor instruction. Assembly language remains a powerful tool for optimization, granting the programmer greater control, and with judicious use can enhance performance." Clearly, in such "mixed language" applications the ability to use Java with ASM can be useful.

Note that the technique shown here can also be used to call Java code from languages other than ASM. If JInvoke is rewritten as a .dll, code written in FORTRAN, for instance, can link to it and call a Java method.

I have used JNI with legacy ASM code in two ways:

Functional enhancement: Mail-enabling an existing ASM application, as mentioned earlier.
Interface enhancement: Adding interactive user interface (mostly AWT, but some Swing as well).

These enhanced applications have run on Windows 2000 and XP. The Java versions used were 1.3, 1.4, and 1.6. In all cases the applications worked smoothly.

Read the rest of this article . . .

Add Logging at Class Load Time with Java Instrumentation

2008-06-16T08:17:05-07:00

by Thorbjørn Ravn Andersen

When you're trying to analyze why a program failed, a very valuable piece of information is what the program was actually doing when it failed. In many cases, this can be determined with a stack trace, but frequently that information is not available, or perhaps what you need is information about the data that was being processed at the time of failure.

Traditionally this means using a logging framework like log4j or the Java Logging API, and then writing and maintaining all necessary log statements manually. This is very tedious and error-prone, and well-suited for automation. Java 5 added the Java Instrumentation mechanism, which allows you to provide "Java agents" that can inspect and modify the byte code of the classes as they are loaded.

This article will show how to implement such a Java agent, which transparently will add entry and exit logging to all methods in all your classes with the standard Java Logging API. The example used is Hello World:

public class HelloWorld {
    public static void main(String args[]) {
        System.out.println("Hello World");
    }
}

And here is the same program with entry and exit log statements added:

import java.util.Arrays;
import java.util.logging.Level;
import java.util.logging.Logger;

public class LoggingHelloWorld {
    final static Logger _log = Logger.getLogger(LoggingHelloWorld.class.getName());

    public static void main(String args[]) {
        if (_log.isLoggable(Level.INFO)) {
            _log.info("> main(args=" + Arrays.asList(args) + ")");
        }
        System.out.println("Hello World");
        if (_log.isLoggable(Level.INFO)) {
            _log.info("< main()");
        }
    }
}

The default logger format generates output similar to:

2007-12-22 22:08:52 LoggingHelloWorld main
INFO: > main(args=[])
Hello World
2007-12-22 22:08:52 LoggingHelloWorld main
INFO: < main()

Note that each log statement is printed on two lines. First, a line with a time stamp, the provided log name, and the method in which the call was made, and then a line with the provided log text.

The rest of the article will demonstrate how to make the original Hello World program behave like the logging Hello World by manipulating the byte code when it is loaded. The manipulation mechanism is the Java Instrumentation API added in Java 5.

Read the rest of this article.

Source Code Analysis Using Java 6 APIs

2008-05-20T12:06:52-07:00

by Seema Richard, Deepa Sobhana

Have you ever thought of how tools like Checkstyle or FindBugs perform a static code analysis, or how Integrated Development Environments (IDEs) like NetBeans or Eclipse execute quick code fixes or find the exact references of a field declared in your code? In many cases, IDEs have their own APIs to parse the source code and generate a standard tree structure, called an Abstract Syntax Tree (AST) or "parse tree," which can be used for deeper analysis of the source elements. The good news is that it is now possible to accomplish the said tasks plus a lot more with the help of three new APIs introduced in Java as part of the Java Standard Edition 6 release. The APIs that might be of interest to developers of Java applications that need to perform source code analysis are the Java Compiler API (JSR 199), the Pluggable Annotation Processing API (JSR 269), and the Compiler Tree API.

In this article, we explore the features of each of these APIs and go on to develop a simple demo application that verifies certain Java coding rules on a set of source code files supplied as input. This utility also shows the coding violation messages as well as the location of violated source code as output. Consider a simple Java class that overrides the equals() method of the Object class. The coding rule to be verified is that every class that implements the equals() method should also override the hashcode() method with the proper signature. You can see that the TestClass class below does not define the hashcode() method, even though it has the equals() method.

public class TestClass implements Serializable {
 int num;

 @Override
  public boolean equals(Object obj) {
        if (this == obj)
                return true;
        if ((obj == null) || (obj.getClass() != this.getClass()))
                return false;
        TestClass test = (TestClass) obj;
        return num == test.num;
  }
}

Let us go on and analyze this class as part of the build process with the help of these three APIs.

Invoking the Compiler from Code: The Java Compiler API

We all use the javac command-line tool for compiling Java source files to class files. Then why do we need an API to compile Java files? Well, the answer is quite simple: as the name describes, this new standard API lets us invoke the compiler from our own Java applications; i.e., you can programmatically interact with the compiler and thereby make compilation part of application-level services. Some typical uses of this API are listed below.

The compiler API helps application servers to minimize the time taken to deploy applications, for example, by avoiding the overhead of using an external compiler for compiling the servlet sources generated from the JSP pages.
Developer tools like IDEs and code analyzers can invoke the compiler from within the editor or build tools that significantly reduce the compile time.

The Java compiler classes are packaged under the javax.tools package. The ToolProvider class of this package provides a method called getSystemJavaCompiler() that returns an instance of some class that implements the JavaCompiler interface. This compiler instance can be used to create a compilation task that will perform the actual compilation. The Java source files to be compiled will be then passed to the compilation task. For this, the compiler API provides a file manager abstraction called JavaFileManager, which allows Java files to be retrieved from various sources, such as the file system, databases, memory, and so on. In this sample, we use StandardFileManager, a file manager based on java.io.File. The standard file manager can be acquired by calling the getStandardFileManager() method of the JavaCompiler instance. The code snippet for the above-mentioned steps is shown below:

//Get an instance of java compiler
JavaCompiler compiler = ToolProvider.getSystemJavaCompiler();

//Get a new instance of the standard file manager implementation
StandardJavaFileManager fileManager = compiler.
        getStandardFileManager(null, null, null);
        
// Get the list of java file objects, in this case we have only 
// one file, TestClass.java
Iterable compilationUnits1 = 
        fileManager.getJavaFileObjectsFromFiles("TestClass.java");

A diagnostic listener can be optionally passed to the getStandardFileManager() method to produce diagnostic reports of any non-fatal problems. In this code snippet, we pass null values, since we are not collecting the diagnostics from the tool. For details of the other parameters passed to these methods, please refer to the Java 6 API. The getJavaFileObjectsfromFiles() method of the StandardJavaFileManager returns all the JavaFileObject instances that correspond to the supplied Java source files.

Read the rest of this article

Nimbus Look and Feel in Java SE 6 Update 10 Beta

2008-04-24T09:41:41-07:00

By Ethan Nicholas

When the venerable Metal look and feel for Swing first debuted, its main aesthetic competition was the Windows 95 interface. Given the state of graphical user interfaces a decade ago, Metal was an attractive and elegant alternative to the other common interfaces of the time.

The updated Ocean theme in Java SE 5 helped to keep Metal a viable choice up to the present day, but it's time for Swing's cross-platform look and feel to get an overhaul.

Enter the Nimbus Look and Feel. A brand new, modern look and feel based on Synth, Nimbus provides a polished look to applications which choose to use it. And because Nimbus is drawn entirely using Java 2D vector graphics, rather than static bitmaps, it's tiny (only 56KB!) and can be rendered at arbitrary resolutions.

Figure 3: SwingSet3 in Metal

Figure 4: SwingSet3 in Nimbus

For compatibility reasons, Metal is still the default Swing look and feel, but updating applications to use Nimbus couldn't be simpler. It only takes a single line of code:

UIManager.setLookAndFeel("com.sun.java.swing.plaf.nimbus.NimbusLookAndFeel");

You can also force Nimbus to be the default look and feel by specifying -Dswing.defaultlaf=com.sun.java.swing.plaf.nimbus.NimbusLookAndFeel. on the command line. A more permanent way to set the property is to add

swing.defaultlaf=com.sun.java.swing.plaf.nimbus.NimbusLookAndFeel

to the file <JAVA_HOME>/lib/swing.properties. You will have to create the swing.properties file if it does not already exist.

For further reading about Nimbus, take a look at the Nimbus early access page.

JSlider Appearance Improvements

2008-04-04T13:34:02-07:00

by John Zukowsi

The JSlider component is a popular component for selecting a value from a numerical range. While some people might think of a JScrollBar for numerical input, that really serves the purpose of scrolling around a viewport, not data input. By default, the input range of a JSlider is 0 to 100, with an initial value of 50. You can change any of the three defaults, the direction of the scrollbar, and whether tick marks should appear and what to show next to them. You'll look at all of these possible features.

First off is the basic JSlider, just creating it and adding it to a screen, preserving all the defaults. Nothing fancy here, but builds the basics for what to build on for the remaining examples. The SliderSample program actually has four sliders; two horizontal and two vertical.

import javax.swing.*;
import java.awt.*;

public class SliderSample {
  public static void main(final String args[]) {
    Runnable runner = new Runnable() {
      public void run() {
        JFrame frame = new JFrame("Sample Sliders");
        frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
        JSlider js1 = new JSlider();
        JSlider js2 = new JSlider();
        js2.setInverted(true);
        JSlider js3 = new JSlider(JSlider.VERTICAL);
        js3.setPaintLabels(true);
        JSlider js4 = new JSlider(JSlider.VERTICAL);
        js4.setInverted(true);
        frame.add(js1, BorderLayout.NORTH);
        frame.add(js2, BorderLayout.SOUTH);
        frame.add(js3, BorderLayout.WEST);
        frame.add(js4, BorderLayout.EAST);
        frame.setSize(300, 200);
        frame.setVisible(true);
      }
    };
    EventQueue.invokeLater(runner);
  }
}

Compiling and running the program shows a screen with four sliders on it. While you cannot tell from the screen, the ones in the EAST and SOUTH regions of the BorderLayout are actually inverted. So, for the horizontal sliders, 0 is on the left for the top one and 100 is on the left for the inverted bottom one. For the vertical sliders, 0 is on the bottom for the left one and on the top for the inverted right one.

By default, there is no indicator on the slider for what its value is. Instead, you would just ask the slider its value at some later time, or attach a listener to the control to be told the value upon movement. Ignoring the import lines, here is a listener that reports the value when the user stops dragging the slider knob. The getValueIsAdjusting() method reports true while the user still has the knob selected with the mouse.

 public class SliderChangeListener implements ChangeListener {
    public void stateChanged(ChangeEvent changeEvent) { 
      Object source = changeEvent.getSource();
      JSlider theJSlider = (JSlider)source;
      if (!theJSlider.getValueIsAdjusting()) { 
        System.out.println ("Slider changed: " + theJSlider.getValue());
      } 
    } 
  }

Not showing a value on the slider makes it somewhat useless, though you can certainly work with it where the exact value doesn't matter and the user can see results based upon relative position. To help in making the slider more useful, you can show tick marks with labels. There are two classes of tick marks, major and minor ones. Major and minor are just classifications for the length and positioning of the lines drawn for the tick mark, where major tick marks are longer than minor ones. To enable tick marks, you have to call setPaintTicks(true), and, say how far apart the tick marks should appear. By default, the spacing is zero, resulting in no tick marks drawn, even when paint ticks is true. Adding the appropriate lines to the earlier program will show tick marks on the top and left sliders, with major ticks every 10 and minor ones at the midpoint between them.

  
  js1.setPaintTicks(true);
  js1.setMajorTickSpacing(10);
  js1.setMinorTickSpacing(5);

  js3.setPaintTicks(true);
  js3.setMajorTickSpacing(10);
  js3.setMinorTickSpacing(5);

Showing tick marks certainly helps, but showing labels makes things most useful. Adding setPaintLabels(true) calls will show labels at the major tick marks. By default, the labels are their respective cardinal numbers, so with a major tick mark at value 0, the associated label is string "0," and so on for "10,", "20,", all the way to "100."

Instead of showing the cardinal numbers, you can provide a label table: setLabelTable(Dictionary labels). In the table, you would map integer values to different components to show as the label. In generic-speak, that would be Dictionary<Integer, JComponent>, though the method isn't explicitly defined to require the key-value pair to be such. Typically, the mapping is Integer object to JLabel. As the Swing component set predates the Collections framework, the method takes a Dictionary, not a Map, so remember to use a Hashtable for the label table. Here's one label table setup that shows text roughly every eleven positions. At the ends are colored diamond icons, instead of text, to help show that that are labels not text strings that can go at each position.

   Hashtable<Integer, JComponent> table =
      new Hashtable<Integer, JComponent>();
    table.put(new Integer(0), new JLabel(
      new DiamondIcon(Color.RED)));
    table.put(new Integer(11), new JLabel("Eleven"));
    table.put(new Integer(22), new JLabel("Twenty-Two"));
    table.put(new Integer(33), new JLabel("Thirty-Three"));
    table.put(new Integer(44), new JLabel("Fourty-Four"));
    table.put(new Integer(55), new JLabel("Fifty-Five"));
    table.put(new Integer(66), new JLabel("Sixty-Six"));
    table.put(new Integer(77), new JLabel("Seventy-Seven"));
    table.put(new Integer(88), new JLabel("Eighty-Eight"));
    table.put(new Integer(100), new JLabel(
      new DiamondIcon(Color.BLACK)));
     js4.setLabelTable(table);
     js4.setPaintLabels(true);

The definition for the DiamondIcon will be shown at end with the full class definition.

Notice that the slider in the eastern area of the screen was used for the label table. Had the southern slider been used instead, the label text would overlap. Keep that in mind when you work with slider labels.

One last thing you can do to affect the display. You can hide the track that the knob slides on. Just call the setPaintTrack() method, with a setting of false. Here, the bottom slider has its track hidden.

There isn't that much more you can do to customize the look of the JSlider, but as you've seen there is certainly quite a bit you can do. From adding tick marks and labels to hiding the track, you've seen the most significant features. If you want to get really fancy, consider creating a custom UI for the component and show it as a dial instead of a line. Sounds like an idea for a future tip.

Here's the final and complete source used to generate the samples. You will need to work backwards to remove code sections to return back to the first screen shot.

import javax.swing.*;
import javax.swing.event.*;
import java.awt.*;
import java.util.Hashtable;

public class SliderSample {
  public static void main(final String args[]) {
    Runnable runner = new Runnable() {
      public void run() {
        JFrame frame = new JFrame("Sample Sliders");
        frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
        ChangeListener listener = new SliderChangeListener();
        JSlider js1 = new JSlider();
        js1.setPaintLabels(true);
        js1.setPaintTicks(true);
        js1.setMajorTickSpacing(10);
        js1.setMinorTickSpacing(5);
        js1.addChangeListener(listener);
        JSlider js2 = new JSlider();
        js2.setInverted(true);
	js2.setPaintTrack(false);
        js2.addChangeListener(listener);
        JSlider js3 = new JSlider(JSlider.VERTICAL);
        js3.setPaintLabels(true);
        js3.setPaintTicks(true);
        js3.setMajorTickSpacing(10);
        js3.setMinorTickSpacing(5);
        js3.addChangeListener(listener);
        JSlider js4 = new JSlider(JSlider.VERTICAL);
        js4.setInverted(true);
        Hashtable<Integer, JComponent> table =
          new Hashtable<Integer, JComponent>();
        table.put(new Integer(0), new JLabel(
          new DiamondIcon(Color.RED)));
        table.put(new Integer(11), new JLabel("Eleven"));
        table.put(new Integer(22), new JLabel("Twenty-Two"));
        table.put(new Integer(33), new JLabel("Thirty-Three"));
        table.put(new Integer(44), new JLabel("Fourty-Four"));
        table.put(new Integer(55), new JLabel("Fifty-Five"));
        table.put(new Integer(66), new JLabel("Sixty-Six"));
        table.put(new Integer(77), new JLabel("Seventy-Seven"));
        table.put(new Integer(88), new JLabel("Eighty-Eight"));
        table.put(new Integer(100), new JLabel(
          new DiamondIcon(Color.BLACK)));
        js4.setLabelTable(table);
        js4.setPaintLabels(true);
        js4.addChangeListener(listener);
        frame.add(js1, BorderLayout.NORTH);
        frame.add(js2, BorderLayout.SOUTH);
        frame.add(js3, BorderLayout.WEST);
        frame.add(js4, BorderLayout.EAST);
        frame.setSize(400, 300);
        frame.setVisible(true);
      }
    };
    EventQueue.invokeLater(runner);
  }
  public static class SliderChangeListener implements ChangeListener {
    public void stateChanged(ChangeEvent changeEvent) { 
      Object source = changeEvent.getSource();
      JSlider theJSlider = (JSlider)source;
      if (!theJSlider.getValueIsAdjusting()) { 
        System.out.println ("Slider changed: " + theJSlider.getValue());
      } 
    } 
  }
  public static class DiamondIcon implements Icon {
    private Color color;
    private boolean selected;
    private int width;
    private int height;
    private Polygon poly;
    private static final int DEFAULT_WIDTH = 10;
    private static final int DEFAULT_HEIGHT = 10;

    public DiamondIcon(Color color) {
      this(color, true, DEFAULT_WIDTH, DEFAULT_HEIGHT);
    }

    public DiamondIcon(Color color, boolean selected) {
      this(color, selected, DEFAULT_WIDTH, DEFAULT_HEIGHT);
    }

    public DiamondIcon(Color color, boolean selected,
        int width, int height) {
      this.color = color;
      this.selected = selected;
      this.width = width;
      this.height = height;
      initPolygon();
    }

    private void initPolygon() {
      poly = new Polygon();
      int halfWidth = width / 2;
      int halfHeight = height / 2;
      poly.addPoint(0, halfHeight);
      poly.addPoint(halfWidth, 0);
      poly.addPoint(width, halfHeight);
      poly.addPoint(halfWidth, height);
    }

    public int getIconHeight() {
      return height;
    }

    public int getIconWidth() {
      return width;
    }

    public void paintIcon(Component c, Graphics g, int x, int y) {
      g.setColor(color);
      g.translate(x, y);
      if (selected) {
        g.fillPolygon(poly);
      } else {
        g.drawPolygon(poly);
      }
      g.translate(-x, -y);
    }
  }
}

Using Generics With Wildcards and Extends

2008-03-10T16:56:23-07:00

By John Zukowski

Java 2 Platform, Standard Edition 5.0 (J2SE 5.0) introduced generics to the Java programming language and platform. In the simplest case and typical usage, generics allow for the identification of what you want to store in a collection. So instead of saying that your program has a List of Objects, you can now specify that you have a List of String objects or some other class type. Then, if you accidentally try to add something to the List that is of the wrong type, the compiler notifies you of the error and it can be fixed at compile time, rather than having to wait until you run the program and the program reaches the point in code where the fetch operation produces a runtime casting exception.

This brings up a second benefit of generics. Iterators now become typesafe. The next() method of the Iterator interface returns the typesafe version of the next element of the collection.

But this is not a tip about the use of generics, which a 2005 Core Java Technologies Tip explained. Most people don't fully understand the use of the extends keyword when using generics. A typical example shown to explain the use of extends has to do with drawing shapes. Instead, this tech tip will use an example that uses Swing components so that you do not have to create extra new classes. In a very limited case, the class hierarchy for Swing button components is shown here, with Object as the real root:

Component
|- Container
   |- JComponent
      |- AbstractButton
         |- JButton
         |- JMenuItem
            |- JCheckBoxMenuItem
            |- JMenu
            |- JRadioButtonMenuItem
         |- JToggleButton
            |- JCheckBox
            |- JRadioButton

One thing that all AbstractButton subclasses share in common is a getText() method. So in the spirit of generics, you can define a method that takes a List of AbstractButton items and return a List of the String labels of those buttons. Here's the first version of such a method:

  public static List<String> getLabels(List<AbstractButton> list) {
    List<String> labelList = new ArrayList<String>(list.size());
    for (AbstractButton button: list) {
      labelList.add(button.getText());
    }
    return labelList;
  }

And here is how you might use the method. First, define a List of AbstractButton types, fill it up, and call the method:

  List<AbstractButton> buttonList =
      new ArrayList<AbstractButton>();
  buttonList.add(new JButton("Hello"));
  buttonList.add(new JCheckBox("World"));
  buttonList.add(new JRadioButton("Hola"));
  buttonList.add(new JMenuItem("Mundo"));

  List labels = getLabels(buttonList);
  System.out.println(labels);

"Hola, Mundo" is the Spanish translation of "Hello, World," according to Google. The results of the println() call is as follows:

[Hello, World, Hola, Mundo]

With a List of AbstractButtons, everything functions fine, but this breaks down when the List is of something else, specifically a subclass. One would logically think that with a List of JButton items, everything would work fine, because JButton is a subclass of AbstractButton. Shouldn't you be able to call getLabels(List<AbstractButton>) with a List of a subclass of AbstractButton?

  List<JButton> buttonList = ...
  // ... Fill list ...
  List<String> labels = getLabels(buttonList);

Well, that isn't the case. Because this is a compile-time check, and because the definition of getLabels() is defined to accept only an AbstractButton List, you cannot pass anything else to it. The compilation-time error message follows:

GetList.java:13: getLabels(java.util.List<javax.swing.AbstractButton>)
  in GetList cannot be applied to (java.util.List<javax.swing.JButton>)

    List<String> labels = getLabels(buttonList);
                          ^
1 error

And this is where the extends keyword comes in handy. Instead of defining the getLabels() method to accept only an AbstractButton list, define it to accept any List of AbstractButton subclasses:

    public static List<String> getLabels(
      List<? extends AbstractButton> list) {

The wildcard ? here says that the method doesn't care what the exact class type is, as long as it is a subclass of AbstractButton. Here's a complete example that puts all the pieces together:

import java.util.*;
import javax.swing.*;

public class GetList {
  public static void main(String args[]) {
    List<JButton> buttonList =
      new ArrayList<JButton>();
    buttonList.add(new JButton("Hello"));
    buttonList.add(new JButton("World"));
    buttonList.add(new JButton("Hola"));
    buttonList.add(new JButton("Mundo"));

    List labels = getLabels(buttonList);
    System.out.println(labels);

  }

  public static List<String> getLabels(
        List<? extends AbstractButton> list) {
    List<String> labelList = new ArrayList<String>(list.size());
    for (AbstractButton button: list) {
      labelList.add(button.getText());
    }
    return labelList;
  }
}

Now, when you are defining your own classes and methods with generics and are thinking of accepting an abstract class as the generic argument, or any superclass, remember to use wildcards so that the same method works best with subclasses too.

For more information on generics, see two earlier tutorials by Gilad Bracha: a 2004 tutorial (PDF) and the generics lesson in the online Java Tutorial.