Rhino: JavaScript for Java

Rhino: JavaScript for Java

Rhino is an open-source implementation of JavaScript written entirely in Java. It is typically embedded into Java applications to provide scripting to end users.

Downloads
How to get source and binaries.
Documentation
Information on Rhino for script writers and embedders.
Help
Some resources if you get stuck.

Generate an XML Document from an Object Model with JAXB 2

Java offers various ways to manipulate XML, including the following:

• Use simple file I/O or javax.xml.stream.XmlStreamWriter.


• Use XML serialization with java.beans.XMLEncoder, which generates an XML representation of a Java Bean in the same way ObjectOutputStream can be used to create binary representation of Serializable objects.


• Use a dedicated library like XStream Play directly with SAX (Simple API for XML) or DOM (Document Object Model) through the JAXP API.

Yet despite XML and Java technology being natural partners in data exchange, mapping a Java object model into XML and vice versa can be a mystery. Consider JAXB as your solution. JAXB (Java Architecture for XML Binding) enables you to perform XML-to-Java data binding and generate Java classes from XML schemas and vice-versa. It's portable, easy to use, and it offers functionalities such as XML validation and customization using annotation and adapters. (Figure 1 illustrates the uses of JAXB.)

Figure 1. JAXB Architecture

The JAXB API, defined in the javax.xml.bind package, is a set of interfaces and classes through which applications communicate with code generated from a schema. The center of the JAXB API is the javax.xml.bind.JAXBContext class. JAXBContext is an abstract class that manages the XML/Java binding. It can be seen as a factory because it provides:

• An Unmarshaller class that deserializes XML into Java and optionally validates the XML (using the setSchema method).


• A Marshaller class that serializes an object graph into XML data and optionally validates it.

First of all, JAXB can define a set of classes into an XML schema by using a schema generator. It also enables the reverse action, allowing you to generate a collection of Java classes from a given XML schema through the schema compiler. The schema compiler takes XML schemas as input and generates a package of Java classes and interfaces that reflect the rules defined in the source schema. These classes are annotated to provide the runtime framework with a customized Java-XML mapping.

JAXB also can generate a Java object hierarchy from an XML schema using a schema generator, or give an object Java hierarchy to describe the corresponding XML schema. The runtime framework provides the corresponding unmarshalling, marshalling, and validation functionalities. That is, it lets you transform an XML document into an object graph (unmarshalling) or transform an object graph into XML format (marshalling).

These capabilities are why JAXB is often associated with web services. Web services use the API to transform objects into messages that they then send through SOAP. This isn't a web services article, however. Using an example address book application for a fictional music company called Watermelon, it focuses on JAXB's XML binding features for round-tripping XML to Java.

What You Need
JAXB (this article uses version 2.1.2 )
JUnit 4.1
Ant 1.7
MySQL 5 and TopLink Essentials as the implementation of JPA

Page 1 of 5

Let's Get Generate Some XML

Watermelon sells and delivers music products such as instruments, amplifiers, scores, books, and so on. In its address book, the company stores two types of customers: individuals and companies. Each has a home address and a set of delivery addresses. Each delivery address can be used on weekends and/or evenings and/or weekdays. I will include this information by adding tags to an address. Figure 2 shows the business model for Watermelon's address book.

Figure 2. Business Model for Watermelon's Address Book

Watermelon wants to send the details of some of its customers to a partner in XML format, so it needs an XML document of its object model for a given customer. With JAXB, this is really easy to do. The following code creates an instance of an Individual and then sets its attributes (first name, last name…), a home address, and two delivery addresses that are tagged. Once the objects are all set, it uses the javax.xml.bind.Marshaller to generate an XML representation of the Individual object, which is then displayed:

Listing 1: Creates an XML Representation of an Individual

// Instantiates Tag objects
Tag tag1 = new Tag("working hours");
Tag tag2 = new Tag("week-ends");
Tag tag3 = new Tag("mind the dog");

// Instantiates an individual object with home address
calendar.set(1940, 7, 7, 0, 0, 0);
Individual individual = new Individual(1L, "Ringo", "Starr", "+187445", "ringo@star.co.uk", calendar.getTime());
individual.setHomeAddress(new Address(2L, "Abbey Road", "London", "SW14", "UK"));

// Instantiates a first delivery address
Address deliveryAddress1 = new Address(3L, "Findsbury Avenue", "London", "CE451", "UK");
deliveryAddress1.addTag(tag1);
deliveryAddress1.addTag(tag3);
individual.addDeliveryAddress(deliveryAddress1);

// Instantiates a second delivery address
Address deliveryAddress2 = new Address(4L, "Camden Street", "Brighton", "NW487", "UK");
deliveryAddress2.addTag(tag1);
deliveryAddress2.addTag(tag2);
individual.addDeliveryAddress(deliveryAddress2);

// Generates XML representation of an individual
StringWriter writer = new StringWriter();
JAXBContext context = JAXBContext.newInstance(Customer.class);
Marshaller m = context.createMarshaller();
m.marshal(individual, writer);

System.out.println(writer);

Author's note: The Marshaller.marshal() method takes an object and marshals it into several supports. The example uses a StringWriter to have a string representation of the XML document, but you could use a FileOutputStream to store the XML into a file, as follows:
            

       File file = new File("customer.xml");
       FileOutputStream outputFile = new FileOutputStream(file);
       m.marshal(individual, outputFile);

The code creates a new instance of JAXBContext by using the static method newInstance, to which it passes the root class that the application needs to manipulate (Customer). From the created Marshaller object, it then calls the marshal method that generates the XML representation of an individual into a StringWriter.

The only thing left to do is add an @XmlRootElement annotation to the Customer class. The @XmlRootElement annotation notifies JAXB that the annotated class is the root element of the XML document. If this annotation is missing, JAXB will throw an exception. If you add it and run the code, you will get the following XML document:

Listing 2: XML Representation of an Individual



   
       London
       UK
       3
       Findsbury Avenue
       
           working hours
       
       
           mind the dog
       
       CE451
   
   
       Brighton
       UK
       4
       Camden Street
       
           working hours
       
       
           week-ends
       
       NW487
   
   ringo@star.co.uk
   
       London
       UK
       2
       Abbey Road
       SW14
   
   1

   +187445
 

With just one annotation (@XmlRootElement), a Marshaller object, and the coding-by-exception approach that guides JAXB (you need to add custom code only when the default is inadequate), you can easily get an XML representation of your object graph. The root element represents the Customer object, and it includes all the attributes (one home address, two delivery addresses, an ID, a phone number, and so on).

Page 2 of 5

Customize the XML Document

Watermelon and its business partner are not completely happy with the structure of the previous XML document (Listing 2). They would like to get rid of some information (address identifiers, tags), format the date of birth, order some attributes, and rename others. Thanks to the annotations of the javax.xml.bind.annotation package, JAXB provides a way to customize and control the XML structure.

First of all, you don't really want to map customers. Rather, you want to map individuals and companies (that means getting rid of the element and instead using or as root elements). To notify JAXB not to take the abstract Customer class into account, you have to get rid of the @XmlRootElement annotation and make the class transient with @XmlTransient. You can use this annotation on a class or an attribute. It informs JAXB not to take it into account when creating the XML representation.

An XML document is made of elements (value) and attributes (). JAXB uses two annotations to differentiate them: @XmlAttribute and @XmlElement. Each annotation has a set of parameters that allows you to rename an attribute, allow null value or not, give it a default value, etc. The following code uses these annotations to turn id into an XML attribute (instead of an element) and to rename the delivery address element (address instead of deliveryAddresses):

@XmlTransient
public abstract class Customer {

 @XmlAttribute
 protected Long id;
 protected String telephone;
 protected String email;
 protected Address homeAddress;
 @XmlElementWrapper(name = "delivery")
 @XmlElement(name = "address")
 protected List
 deliveryAddresses = new ArrayList
();
 // Constructors, getters, setters
}

  

This code uses another interesting annotation, @XmlElementWrapper. It generates a wrapper element around the collections of delivery addresses. If you look back at Listing 2, you'll see two elements. With the code above, you get one element that wraps two

elements.

Talking about addresses, you want to get rid of the identifier and the tags from the XML document. For that, use the @XmlTransient annotation. To rename an element, just use the name property of the @XmlElement annotation. The following code renames the attribute zipcode into a element:

@XmlType(propOrder = {"street", "zipcode", "city", "country"})
@XmlAccessorType(XmlAccessType.FIELD)
public class Address {

 @XmlTransient
 private Long id;
 private String street;
 private String city;
 @XmlElement(name = "zip")
 private String zipcode;
 private String country;
 @XmlTransient
 private List tags = new ArrayList();
 // Constructors, getters, setters
}

  

Notice the @XmlType annotation on the top of the class. It allows JAXB to map a class or an enum to a XML schema type. You can use it to specify a namespace or to order attributes using the propOrder property, which takes a list of names of attributes and generates the XML document following this order.

Author's note: The Address class is annotated with @XmlAccessorType. It controls whether fields or Java bean properties are serialized. XmlAccessType represents the possible values (FIELD, NONE, PROPERTY, PUBLIC_MEMBER). This example uses the FIELD value, which notifies JAXB to use the attributes for the XML mapping (and not getters).

Table 1 below shows three different extracts of XML documents:

1. The default customer XML document that you would get with coding-by-exceptions (with no annotation except @XmlRootElement)


2. The customizations done to the customer class (the identifier becomes an attribute and the delivery addresses are wrapped into a element)


3. Taken into account the annotations of the Address class (no identifier and no tags are displayed; elements are in a certain order)

Default XML Representation	Annotated Customer Class	Annotated Address Class
London UK 3 Findsbury working hours mind the dog CE451 Brighton UK 4 Camden working hours week-ends NW487 (...)	London UK 3 Findsbury working hours mind the dog CE451 Brighton UK 4 Camden working hours week-ends NW487 (...)	Findsbury CE451 London UK Camden NW487 Brighton UK (...)

Table 1. Customizations of the XML Representation of a Customer

You also can annotate the concrete classes Company and Individual to customize the mapping (see table below). First of all, being the root of the XML document now, both have to use the @XmlRootElement annotation where they can specify the XML namespace http://www.watermelon.example/customer. Like the Address, the example uses the @XmlType.propOrder to order the attributes. Note that in the list of attributes, you can use the ones inherited by the super class Customer, such as id, email, telephone, homeAddress, and so on.

Annotated Company Class

Annotated Individual Class

@XmlRootElement(name = "company", namespace = "http://www.watermelon.example/customer") @XmlType(propOrder = {"id", "name", "contactName", "telephone", "email", "numberOfEmployees", "homeAddress", "deliveryAddresses"}) @XmlAccessorType(XmlAccessType.FIELD) public class Company extends Customer { @XmlAttribute private String name; private String contactName; private Integer numberOfEmployees; // Constructors, getters, setters }

@XmlRootElement(name = "individual", namespace = "http://www.watermelon.example/customer") @XmlType(propOrder = {"id", "lastname", "firstname", "dateOfBirth", "telephone", "email", "homeAddress", "deliveryAddresses"}) @XmlAccessorType(XmlAccessType.FIELD) public class Individual extends Customer { private String firstname; @XmlAttribute private String lastname; @XmlJavaTypeAdapter(DateAdapter.class) private Date dateOfBirth; // Constructors, getters, setters }

There is still one thing that Watermelon is not happy about: the date format. JAXB maps java.util.Date attributes into the default value. For example, the date of birth of an individual will be displayed as follow:

1940-08-07T00:00:00.781+02:00

  

To format this date (e.g., 07/08/1940), you have two choices:

1. Use the datatype javax.xml.datatype.XMLGregorianCalendar instead of java.util.Date. The XMLGregorianCalendar gives a W3C XML representation for date/time datatypes and allows certain manipulations.


2. Use an adapter. As you can see in the code above, the Individual class uses a @XmlJavaTypeAdapter annotation. @XmlJavaTypeAdapter(DateAdapter.class) notifies JAXB to use the custom adapter called DateAdapter when marshalling/unmarshalling the dateOfBirth attribute. Adapters are used when Java types do not map naturally to a XML representation. You can then adapt a bound type to a value type or vice versa.

To format the date, you have to write a class (DateAdpater) that extends XmlAdapter. It has to override the marshal and unmarshal methods, which the JAXB binding framework invokes during marshalling and unmarshalling. This way, you can marshal a date into a formatted string and vice versa. The following code just uses a java.text.SimpleDateFormat object to format the date into a string and vice-versa:

public class DateAdapter extends XmlAdapter {

 DateFormat df = new SimpleDateFormat("dd/MM/yyyy");

 public Date unmarshal(String date) throws Exception {
   return df.parse(date);
 }

 public String marshal(Date date) throws Exception {
   return df.format(date);
 }
}

  

Now if you go back to Listing 1, when you call the Marshaller.marshal() method, the DateAdapter.marshal() is also called (@XmlJavaTypeAdapter(DateAdapter.class)) and the date of birth is then formatted. Here is the XML document you obtain:

Individual XML Document
Ringo 07/08/1940 +187445 ringo@star.co.uk Abbey Road SW14 London UK Findsbury Avenue CE451 London UK Camden Street NW487 Brighton UK
Company XML Document
Mr Father +14519454 contact@sony.com 25000 General Alley 75011 Paris FR St James St SW14 London UK Central Side Park 7845 New York US

Page 3 of 5

Unmarshal and Generate a Schema

As Figure 1 showed, JAXB can also be used to unmarshal, generate, and compile a schema. So let's quickly talk about that. From what you've learned so far, you should understand unmarshalling. The idea is to take the previously obtained XML document and generate an object graph. For that, you get a JAXBContext, from which you create an Unmarshaller object. You then call the unmarshal method, passing an XML document (either from a String or a file), and it returns an instance of an Individual with its attributes:

// xmlString contains the XML document of an individual
StringReader reader = new StringReader(xmlString);
JAXBContext context = JAXBContext.newInstance(Individual.class);
Unmarshaller u = context.createUnmarshaller();
Individual individual = (Individual) u.unmarshal(reader);

System.out.println(individual.getFirstname());

  

An XML schema describes the structure of an XML document and it is written in XML syntax. Even if you don't know much about XML schema, you can generate one using the schemaGen tool provided by Sun's JAXB implementation (command line or Ant task). For example, schemaGen can take all the classes developed for this article and generate the XML schema in Listing 3. In that schema, you can see the Address, Company, Individual, and Tag classes described as complex types (download the code and you will see how schemaGen is invoked from Ant):

 address">
   
     
     
     
     
   
 

 company">
   
     
     
     
     
     
     
       
         
           
         
       
     
   
   
   
 

 individual">
   
     
     
     
     
     
     
       
         
           
         
       
     
   
   
   
 

 tag">
   
     
     
   
 

 dateAdapter">
   
     
       
     
   
 

 
   
 


  

When you download JAXB, another tool comes along with it: the schema compiler (xjc). schemaGen allows to generate an XML schema from Java classes, and xjc does the opposite: from an XML schema, it creates annotated Java files. You can use it as a command line or as an Ant task. Take Listing 3, run xjc, and that will generate the class hierarchy (not the objects, the classes) that describes the Watermelon business model.

Page 4 of 5

Annotations for Persistence

Some of you might already know of the fictional music company called Watermelon. I've used it in two previous articles about JPA ("Master the New Persistence Paradigm with JPA" and "Persistence Pays Offs: Advanced Mapping with JPA"). If you think of JAXB as a way to persist data into XML, JPA is its counterpart in terms of relational databases. In fact, both technologies rely heavily on annotations. That means that the same class can be annotated by JPA and JAXB annotations and, in this way, can give an XML representation as well as be persisted in a database.

For those of you interested in this double use of annotations, you will find an example in the code download. But just to give you a taste, here is what the Address class would look like:

@Entity
@Table(name = "t_address")
@XmlType(propOrder = {"street", "zipcode", "city", "country"})
@XmlAccessorType(XmlAccessType.FIELD)
public class Address {

 @XmlTransient
 @Id @GeneratedValue
 private Long id;

 private String street;

 @Column(length = 100)
 private String city;

 @Column(name = "zip_code", length = 10)
 @XmlElement(name = "zip")
 private String zipcode;

 @Column(length = 50)
 private String country;

 @XmlTransient
 @ManyToMany(cascade = CascadeType.PERSIST)
 @JoinTable(name = "t_address_tag",
   joinColumns = {@JoinColumn(name = "address_fk")},
   inverseJoinColumns = {@JoinColumn(name = "tag_fk")})
 private List tags = new ArrayList();

 // Constructors, getters, setters
}

  

Page 5 of 5

Joda Time

Joda Time es una popular librería distribuida bajo licencia Apache que pretende ser una alternativa a las clases que el JDK proporciona para la gestión de fechas, como Date, Calendar o Time. Esta librería sin duda simplifica el manejo de fechas y permite realizar operaciones de un modo sencillo que con el API estándar resultan bastante tediosas.

Si algo negativo se podía decir de ella es que al no ser estándar era un jar más a incluir en el proyecto. Ahora sus creadores la han llevado a Java Community Process y han creado el JSR 310 para intentar convertirla en parte estándar de la plataforma. Ahora mismo el JSR se encuentra en su primera fase; aún no ha sido aceptado. El 12 de febrero habrá una votación para decidir si se acepta o no. Esperemos que así sea y que esta útil librería se convierta en una parte estándar de la plataforma.

Para los que no la conocéis, aquí va un ejemplo de su uso:

DateTime dt = new DateTime();
int year = dt.getYear();
String monthText = dt.monthOfYear().getAsText(Locale.ENGLISH);
String monthInFrench = dt.monthOfYear().getAsText(Locale.FRENCH);
String dateAsISO8601Format = dt.toString();

Jasypt

Jasypt is a java library which allows the developer to add basic encryption capabilities to his/her projects with minimum effort, and without the need of having deep knowledge on how cryptography works.

• Sigue los estándares y normas marcados por RSA tanto para message digesting como para cifrado basado en clave.


• Es completamente thread-safe.


• Puede usarse "a lo fácil", con dificultad casi cero, o "a lo power-user", de manera que se puede configurar mucho.


• Tiene un módulo de integración transparente con Hibernate: Se le dice en un mapping que tal o cual campos de una entidad son cifrados y cómo se cifran y listo, para nuestra aplicación es transparente y en la base de datos se guardan los datos cifrados (muy útil para datos de caracter personal, o para bases de datos con muchos usuarios de sólo lectura...).


• Se puede usar perfectamente en Spring. Todas las herramietnas de cifrado están pensadas de manera que sea sencillo usarlas desde un contenedor IoC. Además, el hecho de que sea thread-safe evita problemas en aplicaciones web debido al uso intensivo de singletons.


• Es muy configurable: se pueden hacer incluso cosas como que un "encryptor" al inicializarse le pida su clave por HTTPS (por ejemplo) a algún servidor remoto, para evitar tenerla en el código fuente.

Uso correcto de las excepciones

Se trata de un artículo que pretende explicar al lector cómo emplear adecuadamente las excepciones en Java, sobre todo cuándo hacerlas "cheked" y "uncheked". Las excepciones que se correspondan con casos de uso excepcionales pero esperados (por ejemplo, el nombre que indica un usuario que se quiere registrar en nuestra aplicación web ya existe) deberían ser cheked ya que el código cliente que llama al código que lanza la excepción debe y puede gestionarla.

Cuando las excepciones se corresponden a bugs o fallos de infraestructura (disco duro lleno, no hay red, la base de datos lanza una excepción...) las excepciones deberían ser uncheked porque el código cliente no va a poder hacer nada para gestionar la excepción. Si no hay red, por ejemplo, no hay nada que hacer. Estas excepciones deberían capturarse muy cerca de la interfaz de usuario, probablemente en algún tipo de bucle que gestione todos los eventos. El resto del código no debería ocuparse de ellas, ni capturarlas ni lanzarlas. Capturar o lazar este tipo de excepciones lo único que consigue es escribir un montón de código inútil.

Según el autor del artículo, las excepciones en Java sí están bien pensadas (cosa en la que no está de acuerdo todo el mundo) pero algunas partes de la librería estándar hacen un uso incorrectas de ellas lo cual lleva a pensar que hay algún problema con las excepciones, cuando el problema está en la librería.

Abstract

One of the most important architectural decisions a Java developer can make is how to use the Java exception model. Java exceptions have been the subject of considerable debate in the community. Some have argued that checked exceptions in the Java language are an experiment that failed. This article argues that the fault does not lie with the Java model, but with Java library designers who failed to acknowledge the two basic causes of method failure. It advocates a way of thinking about the nature of exceptional conditions and describes design patterns that will help your design. Finally, it discusses exception handling as a crosscutting concern in the Aspect Oriented Programming model. Java exceptions are a great benefit when they are used correctly. This article will help you do that.

Why Exceptions Matter

Exception handling in a Java application tells you a lot about the strength of the architecture used to build it. Architecture is about decisions made and followed consistently at all levels of an application. One of the most important decisions to make is the way that the classes, subsystems, or tiers within your application will communicate with each other. Java exceptions are the means by which methods communicate alternative outcomes for an operation and therefore deserve special attention in your application architecture.

A good way to measure the skill of a Java architect and the development team's discipline is to look at exception handling code inside their application. The first thing to observe is how much code is devoted to catching exceptions, logging them, trying to determine what happened, and translating one exception to another. Clean, compact, and coherent exception handling is a sign that the team has a consistent approach to using Java exceptions. When the amount of exception handling code threatens to outweigh everything else, you can tell that communication between team members has broken down (or was never there in the first place), and everyone is treating exceptions "their own way."

The results of ad hoc exception handling are very predictable. If you ask team members why they threw, caught, or ignored an exception at a particular point in their code, the response is usually, "I didn't know what else to do." If you ask them what would happen if an exception they are coding for actually occurred, a frown follows, and you get a statement similar to, "I don't know. We never tested that."

You can tell if a Java component has made effective use of Java exceptions by looking at the code of its clients. If they contain reams of logic to figure out when an operation failed, why it failed, and if there's anything to do about it, the reason is almost always because of the component's error reporting design. Flawed reporting produces lots of "log and forget" code in clients and rarely anything useful. Worst of all are the twisted logic paths, nested try/catch/finally blocks, and other confusion that results in a fragile and unmanageable application.

Addressing exceptions as an afterthought (or not addressing them at all) is a major cause of confusion and delay in software projects. Exception handling is a concern that cuts across all parts of a design. Establishing architectural conventions for exceptions should be among the first decisions made in your project. Using the Java exception model properly will go a long way toward keeping your application simple, maintainable, and correct.

Challenging the Exception Canon

What constitutes "proper use" of Java's exception model has been the subject of considerable debate. Java was not the first language to support exception-like semantics; however, it was the first language in which the compiler enforced rules governing how certain exceptions were declared and treated. Compile-time exception checking was seen by many as an aid to precise software design that harmonized nicely with other language features. Figure 1 shows the Java exception hierarchy.

In general, the Java compiler forces a method that throws an exception based on java.lang.Throwable including that exception in the "throws" clause in its declaration. Also, the compiler verifies that clients of the method either catch the declared exception type or specify that they throw that exception type themselves. These simple rules have had far-reaching consequences for Java developers world-wide.

The compiler relaxes its exception checking behavior for two branches of the Throwable inheritance tree. Subclasses of java.lang.Error and java.lang.RuntimeException are exempt from compile-time checking. Of the two, runtime exceptions are usually of greater interest to software designers. The term "unchecked" exception is applied to this group to distinguish it from all other "checked" exceptions.

Figure 1. Java exception hierarchy

I imagine that checked exceptions were embraced by those who also valued strong typing in Java. After all, compiler-imposed constraints on data types encouraged rigorous coding and precise thinking. Compile-time type checking helped prevent nasty surprises at run-time. Compile-time exception checking would work similarly, reminding developers that a method had potential alternate outcomes that needed to be addressed.

Early on, the recommendation was to use checked exceptions wherever possible to take maximum advantage of the help provided by the compiler to produce error-free software. The designers of the Java library API evidently subscribed to the checked exception canon, using these exceptions extensively to model almost any contingency that could occur in a library method. Checked exception types still outnumber unchecked types by more than two to one in the J2SE 5.1 API Specification.

To programmers, it seemed like most of the common methods in Java library classes declared checked exceptions for every possible failure. For example, the java.io package relies heavily on the checked exception IOException. At least 63 Java library packages issue this exception, either directly or through one of its dozens of subclasses.

An I/O failure is a serious but extremely rare event. On top of that, there is usually nothing your code can do to recover from one. Java programmers found themselves forced to provide for IOException and similar unrecoverable events that could possibly occur in a simple Java library method call. Catching these exceptions added clutter to what should be simple code because there was very little that could be done in a catch block to help the situation. Not catching them was probably worse since the compiler required that you add them to the list of exceptions your method throws. This exposes implementation details that good object-oriented design would naturally want to hide.

This no-win situation resulted in most of the notorious exception handling anti-patterns we are warned about today. It also spawned lots of advice on the right ways and the wrong ways to build workarounds.

Some Java luminaries started to question whether Java's checked exception model was a failed experiment. Something failed for sure, but it had nothing to do with including exception checking in the Java language. The failure was in the thinking by the Java API designers that most failure conditions were the same and could be communicated by the same kind of exception.

Faults and Contingencies

Consider a CheckingAccount class within an imaginary banking application. A CheckingAccount belongs to a customer, maintains a current balance, and is able to accept deposits, accept stop payment orders on checks, and process incoming checks. A CheckingAccount object must coordinate accesses by concurrent threads, any of which may alter its state. CheckingAccount's processCheck() method accepts a Check object as an argument and normally deducts the check amount from the account balance. But a check-clearing client that calls processCheck() must be ready for two contingencies. First, the CheckingAccount may have a stop payment order registered for the check. Second, the account may not have sufficient funds to cover the check amount.

So, the processCheck() method can respond to its caller in three possible ways. The nominal response is that the check gets processed and the result declared in the method signature is returned to the invoking service. The two contingency responses represent very real situations in the banking domain that need to be communicated to the check-clearing client. All three processCheck() responses were designed intentionally to model the behavior of a typical checking account.

The natural way to represent the contingency responses in Java is to define two exceptions, say StopPaymentException and InsufficientFundsException. It wouldn't be right for a client to ignore these, since they are sure to be thrown in the normal operation of the application. They help express the full behavior of the method just as importantly as the method signature.

Clients can easily handle both kinds of exception. If payment on a check is stopped, the client can route the check for special handling. If there are insufficient funds, the client can transfer funds from the customer's savings account to cover the check and try again.

The contingencies are expected and natural consequences of using the CheckingAccount API. They do not represent a failure of the software or of the execution environment. Contrast these with actual failures that could arise due to problems related to the internal implementation details of the CheckingAccount class.

Imagine that CheckingAccount maintains its persistent state in a database and uses the JDBC API to access it. Almost every database access method in that API has the potential to fail for reasons unrelated to the implementation of CheckingAccount. For example, someone may have forgotten to turn on the database server, unplugged a network cable, or changed the password needed to access the database.

JDBC relies on a single checked exception, SQLException, to report everything that could possibly go wrong. Most of what could go wrong has to do with configuring the database, the connectivity to it, and the hardware it resides on. There's nothing that the processCheck() method could do to deal with these situations in a meaningful way. That's a shame, because processCheck() at least knows about its own implementation. Upstream methods in the call stack have an even smaller chance of being able to address problems.

The CheckingAccount example illustrates the two basic reasons that a method execution can fail to return its intended result. They are worthy of some descriptive terms:

Contingency

An expected condition demanding an alternative response from a method that can be expressed in terms of the method's intended purpose. The caller of the method expects these kinds of conditions and has a strategy for coping with them.

Fault

An unplanned condition that prevents a method from achieving its intended purpose that cannot be described without reference to the method's internal implementation.

Using this terminology, a stop payment order and an overdraft are the two possible contingencies for the processCheck() method. The SQL problem represents a possible fault condition. The caller of processCheck() ought to have a way of providing for the contingencies, but could not be reasonably expected to handle the fault, should it occur.

Mapping Java Exceptions

Thinking about "what could go wrong" in terms of contingencies and faults will go a long way toward establishing conventions for Java exceptions in your application architecture.

Condition	Contingency	Fault
Is considered to be	A part of the design	A nasty surprise
Is expected to happen	Regularly but rarely	Never
Who cares about it	The upstream code that invokes the method	The people who need to fix the problem
Examples	Alternative return modes	Programming bugs, hardware malfunctions, configuration mistakes, missing files, unavailable servers
Best Mapping	A checked exception	An unchecked exception

Contingency conditions map admirably well to Java checked exceptions. Since they are an integral part of a method's semantic contract, it makes sense to enlist the compiler's help to ensure that they are addressed. If you find that the compiler is "getting in the way" by insisting that contingency exceptions be handled or declared when it is inconvenient, it's a sure bet that your design could use some refactoring. That's actually a good thing.

Fault conditions are interesting to people but not to software logic. Those acting in the role of "software proctologist" need information about faults to diagnose and fix whatever caused them to happen. Therefore, unchecked Java exceptions are the perfect way to represent faults. They allow fault notifications to percolate untouched through all methods on the call stack to a level specifically designed to catch them, capture the diagnostic information they contain, and provide a controlled and graceful conclusion to the activity. The fault-generating method is not required to declare them, upstream methods are not required to catch them, and the method's implementation stays properly hidden—all with a minimum of code clutter.

Newer Java APIs such as the Spring Framework and the Java Data Objects library have little or no reliance on checked exceptions. The Hibernate ORM framework redefined key facilities as of release 3.0 to eliminate the use of checked exceptions. This reflects the realization that the great majority of the exception conditions that these frameworks report are unrecoverable, stemming from incorrect coding of a method call, or a failure of some underlying component such as a database server. Practically speaking, there is almost no benefit to be gained by forcing a caller to catch or declare such exceptions.

Fault handling in your architecture

The first step toward handling faults effectively in your architecture is to admit that you need to do it. Coming to this acceptance is difficult for engineers who take pride in their ability to create impeccable software. Here is some reasoning that will help. First, your application will be spending a great deal of time in development where mistakes are commonplace. Providing for programmer-generated faults will make it easier for your team to diagnose and fix them. Second, the (over)use of checked exceptions in the Java library for fault conditions will force your code to deal with them, even if your calling sequences are completely correct. If there's no fault handling framework in place, the resulting makeshift exception handling will inject entropy into your application.

A successful fault handling framework has to accomplish four goals:

• Minimize code clutter


• Capture and preserve diagnostics


• Alert the right person


• Exit the activity gracefully

Faults are a distraction from your application's real purpose. Therefore, the amount of code devoted to processing them should be minimal and, ideally, isolated from the semantic parts of the application. Fault processing must serve the needs of the people responsible for correcting them. They need to know that a fault happened and get the information that will help them figure out why. Even though a fault, by definition, is not recoverable, good fault handling will attempt to terminate the activity that encountered the fault in a graceful way.

Use unchecked exceptions for fault conditions

There are lots of reasons to make the architectural decision to represent fault conditions with unchecked exceptions. The Java runtime rewards programming mistakes by throwing RuntimeException subclasses such as ArithmeticException and ClassCastException, setting a precedent for your architecture. Unchecked exceptions minimize clutter by freeing upstream methods from the requirement to include code for conditions that are irrelevant to their purpose.

Your fault handling strategy should recognize that methods in the Java library and other APIs may use checked exceptions to represent what could only be fault conditions in the context of your application. In this case, adopt the architectural convention to catch the API exception where it happens, treat it as a fault, and throw an unchecked exception to signal the fault condition and capture diagnostic information.

The specific exception type to throw in this situation should be defined by your architecture. Don't forget that the primary purpose of a fault exception is to convey diagnostic information that will be recorded to help people figure out what went wrong. Using multiple fault exception types is probably overkill, since your architecture will treat them all identically. A good, descriptive message embedded inside a single fault exception type will do the job in most cases. It's easy to defend using Java's generic RuntimeException to represent your fault conditions. As of Java 1.4, RuntimeException, like all throwables, supports exception chaining, allowing you to capture and report a fault-inducing checked exception.

You may choose to define your own unchecked exception for the purpose of fault reporting. This would be necessary if you need to use Java 1.3 or earlier versions that do not support exception chaining. It is simple to implement a similar chaining capability to capture and translate checked exceptions that constitute faults in your application. Your application may have a need for special behavior in a fault reporting exception. That would be another reason to create a subclass of RuntimeException for your architecture.

Establish a fault barrier

Deciding which exception to throw and when to throw it are important decisions for your fault-handling framework. Just as important are the questions of when to catch a fault exception and what to do afterward. The goal here is to free the functional portions of your application from the responsibility of processing faults. Separation of concerns is generally a good thing, and a central facility responsible for dealing with faults will pay benefits down the road.

In the fault barrier pattern, any application component can throw a fault exception, but only the component acting as the "fault barrier" catches them. Adopting this pattern eliminates much of the intricate code that developers insert locally to deal with faults. The fault barrier resides logically toward the top of the call stack where it stops the upward propagation of an exception before default action is triggered. Default action means different things depending on the application type. For a stand-alone Java application, it means that the active thread is terminated. For a Web application hosted by an application server, it means that the application server sends an unfriendly (and embarrassing) response to the browser.

The first responsibility of a fault barrier component is to record the information contained in the fault exception for future action. An application log is by far the best place to do this. The exception's chained messages, stack traces, and so on, are all valuable pieces of information for diagnosticians. The worst place to send fault information is across the user interface. Involving the client of your application in your debugging process is hardly ever good for you or your client. If you are really tempted to paint the user interface with diagnostic information, it probably means that your logging strategy needs improvement.

The next responsibility of a fault barrier is to close out the operation in a controlled manner. What that means is up to your application design but usually involves generating a generic response to a client that may be waiting for one. If your application is a Web service, it means building a SOAP <fault> element into the response with a <faultcode> of soap:Server and a generic <faultstring> failure message. If your application communicates with a Web browser, the barrier would arrange to send a generic HTML response indicating that the request could not be processed.

In a Struts application, your fault barrier can take the form of a global exception handler configured to process any subclass of RuntimeException. Your fault barrier class will extendorg.apache.struts.action.ExceptionHandler, overriding methods as needed to implement the custom processing you need. This will take care of inadvertently generated fault conditions and fault conditions explicitly discovered during the processing of a Struts action. Figure 2 shows contingency and fault exceptions.

Figure 2. Contingency and fault exceptions

If you are using the Spring MVC framework, your fault barrier can easily be built by extending SimpleMappingExceptionResolver and configuring it to handle RuntimeException and its subclasses. By overriding the resolveException() method, you can add any custom handling you need before using the superclass method to route the request to a view component that sends a generic error display.

When your architecture includes a fault barrier and developers are made aware of it, the temptation to write one-off fault exception handling code decreases dramatically. The result is cleaner and more maintainable code throughout your application.

Contingency Handling in Your Architecture

With fault processing relegated to the barrier, contingency communication between primary components becomes much simpler. A contingency represents an alternative method result that is just as important as the principal return result. Therefore, checked exception type is a good vehicle to convey the existence of a contingency condition and supply the information needed to contend with it. This practice enlists the help of the Java compiler to remind developers of all aspects of the API they are using and the need to provide for the full range of method outcomes.

It is possible to convey simple contingencies by using a method's return type alone. For example, returning a null reference instead of an actual object can signify that the object could not be created for a defined reason. Java I/O methods typically return an integer value of -1 instead of a byte value or byte count to indicate an end-of-file condition. If your method's semantics are simple enough to allow it, alternative return values may be the way to go, since they eliminate the overhead that comes with exceptions. The downside is that the method caller is responsible for testing the return value to see if it is a primary result or a contingency result. The compiler will not insist that the method caller makes that test, however.

If a method has a void return type, an exception is the only way to indicate that a contingency occurred. If a method is returns an object reference, the vocabulary that the return value can express is limited to two values (null and non-null). If a method returns an integral value, it may be possible to express several contingency conditions by choosing values that are guaranteed not to conflict with the primary return values. But now we have entered the world of error code checking, something the Java exception model was developed to avoid.

Supply something useful

It made little sense to define different fault reporting exception types, since the fault barrier treats them all the same. Contingency exceptions are quite different, because they are meant to convey diverse conditions to method callers. Your architecture would probably specify that these exceptions should all extend java.lang.Exception or a designated base class that does.

Do not forget your exceptions are complete Java types that can accommodate specialized fields, methods, and even constructors that can be shaped for your unique purposes. For example, the InsufficientFundsException type thrown by the imaginary CheckingAccount processCheck() method could include an OverdraftProtection object that is able to transfer funds needed to cover the shortfall from another account whose identity depends on how the checking account is set up.

To log or not to log

Logging fault exceptions makes sense because their purpose is to draw the attention of people to situations that need to be corrected. The same cannot be said for contingency exceptions. They may represent relatively rare events, but every one of them is expected to happen during the life of your application. If anything, they signify that the application is working the way it was designed to work. Routinely adding logging code to contingency catch blocks adds clutter to your code with no actual benefit. If a contingency represents a significant event, it is probably better for a method to generate a log entry recording the event before throwing a contingency exception to alert its caller.

Exception Aspects

In Aspect Oriented Programming (AOP) terms, fault and contingency handling are crosscutting concerns. To implement the fault barrier pattern, for example, all the participating classes must follow common conventions:

• The fault barrier method must reside at the head of a graph of method calls that traverses the participating classes.


• They must all use unchecked exceptions to signify fault conditions.


• They must all use the specific unchecked exception types that the fault barrier is expecting to receive.


• They all must catch and translate checked exceptions from lower methods that are deemed to be faults in their execution context.


• They must not interfere with the propagation of fault exceptions on their way to the barrier.

These concerns cut across the boundaries of otherwise unrelated classes. The result is minor bits of scattered fault handling code and implicit coupling between the barrier class and the participants (although still a great improvement over not using a pattern at all!). AOP allows the fault handling concern to be encapsulated in a common Aspect applied to the participating classes. Java AOP frameworks such as AspectJ and Spring AOP recognize exception handling as a join point to which fault handling behavior (or advice) can be attached. In this way, the conventions that bind participants in the fault barrier pattern can be relaxed. Fault processing can now reside within an independent, out-of-line aspect, eliminating the need for a "barrier" method to be placed at the head of a method invocation sequence.

If you are exploiting AOP in your architecture, fault and contingency handling are ideal candidates for aspects that apply throughout an application. A full exploration of how fault and contingency handling could work in the AOP world would make an interesting topic for a future article.

Conclusion

Although the Java exception model has generated spirited discussion during its lifetime, it provides excellent value when it is applied correctly. As an architect, it is up to you to establish conventions that get the most from the model. Thinking of exceptions in terms of faults and contingencies can help you make the right choices. Using the Java exception model properly will keep your application simple, maintainable, and correct. Aspect Oriented Programming techniques may offer some definite advantages for your architecture by recognizing fault and contingency handling as crosscutting concerns.