Ajax for Java developers: Java object serialization for Ajax

Five ways to serialize data in Ajax applications

Document options Print this page'); // :script --> E-mail this page'); // :script --> Print this page E-mail this page Discuss Rate this page Help us improve this content

Level: Intermediate

Philip McCarthy (philmccarthy@gmail.com), Software Development Consultant, Independent Consultant

04 Oct 2005

If you're doing Java™ Web development using Asynchronous JavaScript and XML (Ajax), then delivering data from the server to the client is probably your top concern. In this second article in the Ajax for Java developers series, Philip McCarthy walks you through five approaches to Java object serialization and gives you all the information you need to choose the data format and technology best suited to your application.

In the first article in this series, I introduced you to the building blocks of Ajax:

• How to use a JavaScript XMLHttpRequest object to send an asynchronous request to a server from a Web page
• How to handle and respond to that request with a Java servlet returning an XML document to the client
• How to use that response document on the client to update your page view

This time, I'll continue discussing the development fundamentals of Ajax, but I'm focusing on what matters most for many Java Web developers: producing data for the client.

Most Java developers have applied the Model-View-Controller (MVC) pattern to their Web applications. In a traditional Web application, the view component is composed of JSPs, or perhaps another presentation technology such as Velocity templates. These presentation components update the user interface by dynamically producing a whole new page of HTML to replace what the user was previously looking at. In the case of a Java Web application with an Ajax UI, however, the JavaScript client code has ultimate responsibility for updating what the user sees, based on data received in response to an XMLHttpRequest. From the perspective of the server, the view becomes the data representation it sends in response to client requests.

This article focuses on the techniques you can use to generate data-centric views of your Java objects. I'll demonstrate a variety of methods you can use to turn your JavaBeans into XML documents, and you'll learn the pros and cons of each. You'll also see why XML is not always the way to go: transferring plain text can be an expedient choice for simple Ajax requests. Finally, I'll introduce you to JavaScript Object Notation (JSON). JSON allows data to be transmitted in the form of serialized JavaScript object graphs that are extremely easy to work with in client-side code.

About the example

I'll employ one example application and several use cases to illustrate the technology features and techniques discussed here. Figure 1 shows the extremely simple data model that illustrates the example use cases. The model represents a customer's account at an online store. The customer has a collection of previous orders, and each order consists of several items.

Although XMLHttpRequest places no restrictions on the format used to send request data, for most purposes it's appropriate to simply send traditional form parameters, so my discussion concentrates on the server's response. The response can also have any text-based format but, as its name suggests, XMLHttpRequest has built-in capabilities for dealing with XML response data. This makes XML the default choice for Ajax responses, so it's a good place to start.

Back to top

Producing XML from Java classes

There are plenty of reasons to deliver Ajax responses as XML: every Ajax-capable browser has methods for navigating XML documents, and there are many server-side technologies for working with XML data. It's easy to define the contract between your Ajax client and server by producing a schema to describe the types of documents that will be exchanged, and if you take a service-oriented approach to your server-side architecture, using XML allows non-Ajax clients to consume your data feeds as well.

I'll consider three of the ways you can produce XML data from your Java objects and discuss the pros and cons of each.

Back to top

Roll-your-own serialization

First of all, you could generate XML programatically from your object graph. This approach can be as simple as implementing a toXml() method in each of your JavaBean classes. You would then pick a suitable XML API and have each bean emit elements to represent its state and recursively call down the object graph to its members. Clearly, this approach doesn't scale well to a large number of classes because each one needs to have its own XML-generating code specially written. On the upside, it's a simple approach to implement, there's no overhead in terms of extra configuration or a more-complex build process, and any graph composed of your JavaBeans can be turned into an XML document with a couple of calls.

In the example code for the previous article in this series, I implemented toXml() methods by appending strings of XML markup together. As I mentioned at the time, this is a poor approach because it places the burden of ensuring tags are balanced, entities encoded, and so forth on each toXml() method's code. Several XML APIs available on the Java platform do all this work for you, allowing you to concentrate on the XML's content. Listing 1 uses the JDOM API to implement toXml() on the class representing an order in the online store example (see Figure 1).

You can see here how simple it is to create elements, set attributes, and add element content using JDOM. Recursive calls to composited JavaBeans' toXml() methods are made to obtain Element representations of their subgraphs. For instance, the content of the items element is generated here by calling toXml() on each Item object aggregated by the Order.

Once your JavaBeans all implement a toXml() method, it's simple to serialize any arbitrary object graph into an XML document and return it to an Ajax client, as shown in Listing 2.

JDOM again makes life very simple here. You just need to wrap a Document around the XML element returned by the root of the object graph, and then use XMLOutputter to write the document out to the servlet response. Listing 3 shows a sample of the XML produced this way, formatted nicely by initializing the XMLOutputter with JDOM's Format.getPrettyFormat(). In this example, the customer has only made one order, consisting of two items.

Downsides of roll-your-own serialization

Interestingly, the code in Listing 3 shows one of the major drawbacks of having JavaBeans serialize themselves to XML. Suppose this document was used to present an Order History view to the customer. In that case, it's unlikely that you would want to display the full description of every item in every past order, or tell the user his or her name. But if the application has a ProductSearch class that returns its search results as a list of Item beans, it would be helpful to have the descriptions included in the Item's XML representation. Moreover, an additional field on the Item class representing the current stock level would be useful information to display in a Product Search view. However, this field would then be serialized from any object graph involving Item, despite the current stock level's irrelevance to, say, the customer's Order History.

From a design perspective, this is a classic problem of the data model being coupled to view generation. Each bean can only serialize itself in one way, and the one-size-fits-all approach means that Ajax interactions end up exchanging data they don't need to, making the client code work harder to locate information it does require from the document, as well as increasing bandwidth consumption and XML parsing time on the client side. The other consequence of this coupling is that the XML grammar cannot evolve independently of the Java classes. For instance, making a change to the schema of the customer document could impact several Java classes that would then have to be modified and recompiled.

I'll address these concerns later on, but first, let's look at a solution to the scalability issues of the roll-your-own serialization approach: XML binding frameworks.

Back to top

XML binding frameworks

In recent years, several Java APIs have been developed to simplify the process of binding XML documents to Java object graph representations. Most provide both XML marshaling and unmarshaling; that is, they perform two-way conversions between Java object graphs and XML. These frameworks encapsulate all the work of handling XML, meaning that application code only has to deal with plain Java objects. They tend to provide useful ancillary functions as well, such as document validation. Broadly, these frameworks take two different approaches: code generation and object-to-XML mapping. I'll explain both.

The code-generation approach

Binding frameworks that employ code generation include XMLBeans, JAXB, Zeus, and JBind. Castor can also employ this technique. The starting point for any of these frameworks is an XML schema that describes the data types of your documents. Using tools provided by the framework, you then generate Java classes that represent these schema-defined types. Finally, you write your application using these generated classes to represent your model data and serialize them to XML through some convenient mechanism provided by the framework.

The code generation approach is a good one if your application employs a large XML grammar. The scaling problem of writing custom XML-serialization methods across tens of classes vanishes. On the other hand, you no longer get to define your own JavaBeans. The framework-generated Java classes typically follow the XML's structures very closely, which can result in them being rather unwieldy to code against. Also, the generated classes become dumb data containers because you can't generally add behavior to them. Broadly speaking, you need to make compromises in your application code to play nicely with the schema-generated types. Another pitfall is that a change in the schema causes changes to the generated classes, which in turn has a knock-on effect to any code you've written around them.

XML binding frameworks of this type are most useful in data unmarshaling (i.e., consuming XML documents and converting them into Java objects). Unless you have a huge data model and would benefit from having classes generated for you, code-generation-based frameworks are probably overkill for an Ajax application.

The mapping approach

Frameworks that employ mapping include Castor and Apache Commons Betwixt. Mapping is generally a more flexible and lightweight solution than code generation. First, you code your JavaBeans as you usually would, including any behavior and whatever convenience methods you like. Then, at run time, you call on the framework's introspection-based marshaler, and it produces an XML document based on the types, names, and values of your objects' members. By defining mapping files for your classes, you can override the default binding strategy and advise the marshaler how you'd like your classes to be represented in XML.

This approach is a good compromise between scalability and flexibility. You get to write your Java classes the way you like them, and the marshaler saves you from dealing with XML. However, although the mapping definition files are simple to write and scale reasonably well, the mapping rules can only change the standard binding behavior so much, and some degree of coupling between the structure of your objects and their XML representation will always remain. Ultimately, you may have to compromise either your Java representations or your XML format for the mapping approach to work.

Data binding summary

Dennis Sosnoski has written in depth on the subject of XML data binding APIs of both the code-generation and code-mapping flavors. I'd recommend his excellent articles on Castor and on the code-generation frameworks if you want to investigate this area further (see Resources for links).

On the whole, the code-generation approach trades off too much flexibility and convenience to be useful for the typical Ajax application. On the other hand, the mapping-based frameworks may serve you well, as long as you can tailor their mapping strategies enough to produce the XML you want from your objects.

All of the XML binding APIs share a major drawback with the manual serialization technique: the coupling of model and view. Being limited to a single XML representation of each object type means it is likely that there will always be some redundant data traveling across the network. A more serious problem is that the client code cannot obtain a specialized view when the situation demands it and may have an awkward time trying to deal with the compromised one-size-fits-all view of a given object graph.

In traditional Web application development, page templating systems are used to cleanly separate view generation from controller logic and model data. It's an approach that can help in an Ajax scenario as well.

Back to top

Page templating systems

Any general-purpose page templating technology can be employed to generate XML, allowing Ajax apps to create arbitrary XML response documents from their data models. An added bonus is that templates can be written using simple and expressive markup languages, as opposed to lines and lines of Java code. Listing 4 is a JSP page that takes a Customer bean and renders a custom XML view suitable for client code to create an Order History component.

This concise template outputs only the data needed for an Order History view, and not the irrelevant stuff such as each item's description. It would be just as easy to create custom XML for a Product Search view, which included the full description and stock level for each item.

The trouble with templates

The flipside of the coin is that I now need to create a new JSP for every different view I require, as opposed to just assembling the required object graph and serializing it. From a design perspective, many would argue this is a good thing anyway because it means formally thinking about the types of document the server will produce. Also, because I'm now working with a generic templating environment and not an XML-specific API, it's my responsibility to make sure tags are balanced, element and attribute order is correct, and any XML entities (for instance < or &) are escaped. JSP's core out tag makes this latter task easy, but not all templating technologies provide such a mechanism. Finally, there is no easy way to validate the generated XML document against a schema on the server side, but this isn't something you'd expect to do in a production environment anyway, and you can easily work around it during development.

Back to top

Response data without XML

So far, all the techniques I've covered produce a server response in the form of an XML document. There are a few issues with XML, however. One of these issues is related to latency. Browsers do not parse XML documents and create DOM models instantly, and this can reduce the feeling of "snappiness" needed by some Ajax components, especially when parsing large documents on slower machines. An example is "live search," where search results are fetched from the server and displayed to the users as they type in their search terms. It's important for a live search component to respond quickly to input, but at the same time it needs to parse server responses rapidly and continuously.

Latency is an important consideration, but the biggest reason to avoid XML is the awkward client-side DOM API. Listing 5 shows the hoops you commonly have to jump through to get at a value via the DOM, in a cross-browser-compatible way.

Things become even more complex when there's whitespace between elements, because invariably every element's firstChild will be a whitespace text node. JavaScript libraries are available to make dealing with XML documents less painful. These include Sarissa (see Resources), and Google-ajaXSLT, both of which add XPath capabilities to most browsers.

Nevertheless, it's worth thinking about the alternatives. In addition to responseXML, the XMLHttpRequest object offers a property named responseText, which simply provides the server's response body as a string.

The responseText property

responseText is especially handy when the server needs to send very simple values to the client, avoiding the bandwidth and processing overheads of XML. For instance, a simple true/false response could be returned by the server as plain text, as could a simple comma-separated list of names or numbers. Generally, though, it's best not to mix and match XML responses and plain-text responses in the same application; sticking to a single data format makes code abstraction and reuse simpler.

responseText can also be useful in conjunction with XML response data. In a scenario where you only need to extract a single value from a response document, it can be more convenient to "cheat," treating the XML as a string of text rather than a structured document. For instance, Listing 6 shows how a regular expression can be used to extract the date of the first order in a customer's Order History. This is really only a hack, though -- generally you shouldn't rely on the lexical representation of an XML document.

Using responseText in this ad-hoc fashion can be convenient in some circumstances. Ideally, however, there would be a way to represent complex, structured data in a format that can be easily navigated in JavaScript, and that doesn't have the processing overheads of XML. As luck would have it, just such a format exists.

Back to top

JavaScript Object Notation

Under the hood, JavaScript objects for the most part are composed of associative arrays, numerically indexed arrays, strings, numbers, or nested combinations of these types. Because all types can be declared literally in JavaScript, it's possible to statically define an object graph in single statement. Listing 7 declares an object using JSON syntax and shows how it can be accessed. Curly braces denote an associative array (that is, an object), with its key-value pairs separated by commas. Square brackets denote a numerically indexed array.

So JSON is an interesting language feature, but what does it have to do with Ajax? The punchline is that you can use JSON to send a JavaScript object graph over the network in an Ajax server's response. This means an escape from XML navigation on the client through the clunky DOM API -- you just need to evaluate the JSON response, and you instantly have an accessible JavaScript object graph. First, however, you need to turn your JavaBeans into JSON.

Producing JSON from Java classes

The same pros and cons that apply to different XML generation techniques also apply to producing JSON. Arguably, there is a case for using presentation templating technologies again. However, using JSON is philosophically closer to passing serialized objects between application tiers than to creating a view of the application state. I'm going to show you how to use the org.json Java API to create toJSONObject() methods on your Java classes. Your JSONObjects can then be simply serialized to JSON. Listing 8 echoes Listing 1 from the XML discussion, showing a toJSONObject() implementation for the Order class.

As you can see, the org.json API is very simple. JSONObject represents a JavaScript object (that is, an associative array) and has various put() methods that take a String key and a value that is a primitive, a String, or another JSON type. JSONArray represents an indexed array, so its put() method takes only a value. Note that in Listing 8, an alternative to creating the jsonItems array and then attaching it to the json object with put() would have been to call json.accumulate("items",iter.next().toJSONObject()); for each item. The accumulate() method is like put() except that it appends its value to an indexed array identified by the key.

Listing 9 shows how to serialize a JSONObject and write it to a servlet's response.

As you can see, there's really nothing to it. The toString() method on JSONObject, called implicitly here, does all the work. Note that the application/x-json content type is a little dubious -- at the time of this writing there's no consensus on what the MIME type of JSON should be. However, application/x-json is a sensible choice for the time being. Listing 10 shows an example response from this servlet code.

Consuming JSON on the client

The final step in the process is turning the JSON data into JavaScript objects on the client. This can be accomplished with a simple call to eval(), a function that interprets strings containing JavaScript expressions on the fly. Listing 11 converts a JSON response into a JavaScript object graph and then performs Listing 5's task of obtaining the name of the first item from the customer's last order.

Comparing Listing 11 with Listing 5 illustrates the advantages to the client of using JSON. If your Ajax project involves navigating lots of complex server responses on the client, JSON may well appeal to you. Putting JSON and XMLHttpRequest together also makes an Ajax interaction start to look more like an RPC call than an SOA request, which may have a bearing on your application design. In the next article, I'll be looking at frameworks explicitly designed to allow JavaScript code to make remote method calls on server-side objects.

Downsides of JSON

JSON does have its drawbacks. Using the JSON approach illustrated here, there's no way to tailor objects' serialization on a per-request basis, so unneeded fields may often be sent across the network. Additionally, adding toJSONObject() methods to each JavaBean does not scale well, although it would be fairly straightforward to write a generic JavaBean to a JSON serializer using introspection and annotations. Finally, if your server-side code is service oriented and not tailored solely to handling requests from an Ajax client, XML is a better choice because of its ubiquitous support.

Back to top

Comparing serialization techniques

You've now seen five different techniques for transferring server-side Java state to an Ajax client. I've discussed roll-your-own hand-coded XML serialization, XML binding via code generation, XML binding via a mapping mechanism, template-based XML generation, and finally hand-coded serialization to JSON. Each has its own advantages and disadvantages and is best suited to different application architectures.

In an attempt to summarize the benefits and drawbacks of each approach, Table 1 assigns rough scores in six categories:

Scalability

Describes how well the approach adapts to a large number of data types. Will your coding and configuration workload increase with each additional type?

Ease of integration

Assesses how simple it is to integrate the technology into your project. Does it necessitate a more convoluted build process? Does it increase deployment complexity?

Java class API

Describes how easy it is to work with the server-side Java objects employed in the approach. Do you get to write regular beans or will you have to work with awkward document representations?

Control over output

Describes how precisely you can control the serialized representation of your classes.

View flexibility

Assesses whether different, customized data serializations can be created from the same set of objects.

Client data access

Describes how easy it is for JavaScript code to work with the server's response data.

Back to top

In conclusion

The data compiled in Table 1 isn't intended to imply that any of the serialization technologies is better than the others. After all, the relative importance of each of the six categories depends on the specifics of your project. For instance, if you'll be working with hundreds of data types, you want scalability, so code generation is probably your best bet. If you need to generate several different views of the same data model, page templating is the way to go. If you're working on a small-scale project and want to reduce the quantity of JavaScript code you'll have to write, consider JSON.

Hopefully this article has given you the information you need to choose a serialization technology that is suited to your application. See the Resources section to learn more about the technologies discussed here. You should also keep an eye out for the next article in this series, where I'll show you how to write a Java Ajax application using Direct Web Remoting (DWR). The DWR framework allows you to call methods on your Java classes directly from JavaScript code. In other words, it takes care of the work of data serialization for you so that you can use Ajax at an even higher level of abstraction.

Back to top

Resources

• "Ajax for Java developers: Build dynamic Java applications" (Philip McCarthy, developerWorks, September 2005): First steps with Ajax.
  
  
• "Ajax for Java developers: Ajax with Direct Web Remoting" (Philip McCarthy, developerWorks, November 2005): Learn how to use Direct Web Remoting (DWR).
  
  
• "Data binding, Part 1: Code generation approaches -- JAXB and more" (Dennis Sosnoski, developerWorks, January 2003): An in-depth look at XML data binding technologies.
  
  
• "Data binding with Castor" (Dennis Sosnoski, developerWorks, April 2002): A primer on using Castor's mapping approach.
  
  
• "AJAX and scripting Web services with E4X" (Paul Fremantle and Anthony Elder, developerWorks, April 2005): An introduction to Ajax that features E4X, an extension to JavaScript that simplifies XML scripting.
  
  
• Ajax In Action (Dave Crane, Eric Pascarello, Darren James; Manning, November 2005): In-depth coverage of the MVC approach to Ajax that also covers JSON.
  
  
• developerWorks open source project news: A current listing of open source projects such as PAJAJ (PHP Asynchronous Javascript and JSON).
  
  
• The Java technology zone: Hundreds of articles about every aspect of Java programming.
  
  

• Sarissa: A cross-browser JavaScript library with support for XPath.
  
  
• Jakarta Commons Betwixt: A flexible mapping-based XML binding library.
  
  
• JSON: JavaScript Object Notation APIs for the Java language and others.
  
  

• Participate in the discussion forum.
  
  
• developerWorks blogs: Get involved in the developerWorks community.