The Beginners Guide to JAXB

   BEGINNING  JAXB

(Java Architecture for

  XML-BINDING)

---------------------------------------

By  R.S.RAMASWAMY ( [email protected])

--------------------------------------------

(First published in DeveloperIQ..MAY-2005)

-------------------------------------------

  (Page-1)   (Page-2) (Page-3)

    JAX-pack, now being referred to as JWSDP,is a very important development in J2EE.In the previous editions,(July,August,October-2004)  we had covered the basics of JAXP( Java -API for XML Processing), dealing with  DOM,SAX,JDOM,TrAX etc. Part-1 of this tutorial deals with general theory of JAXB and its importance in binding XML to Java classes.

   JAXB  is a component  part of JAX set of API's.  SUN MICRO SYSTEMS is giving a lot of importance to XML WebServices and within a short span, has released a number of revisions of JWSDP ( Java WebService Development pack). It began with JWSDP1.0 and now is running JWSDP1.5. (Version numbers have become very important in modern software field, because, there is so much development taking place almost every month.

This is true in J2EE/OpenSource & DotNet  too. )

It appears that JAXB is available for downloading,  as a part of JWSDP only, and cannot be downloaded as such. So, we should download JWSDP , to gain access to JAXB for experimentation.We are using JWSDP1.4.

   JWSDP is essentially for XML-WebService work. The constituent parts of this package are  JAX-RPC, JAXM(Messaging)& JAXR(Registry).There is also SAAJ ( SOAP with Attachment)not to be confused with JAAS ( Java security). (Hopefully, we will cover these topics , in coming editions).JAXP takes care of DOM,SAX  & XSLT .

  JAXB allows Java developers to access and process XML data without having to know XML or XML processing. For example, there's no need to create or use a SAX parser or write callback methods. It makes use of a  given schema of an XML document and automatically generates the required Java classes, corresponding to that schema.( DeveloperIQ is now providing a detailed workshop on DTD, a form of Schema).Modern trend focuses on XML representation of Data, for ease of exchange in web-service and otherwise. If we have an xml representation of a database, we can use JAXB to create a tree of Java objects  and work with them in Java idiom..This is known as XML-Databinding. .

  Validation is an important part of any XML document. Unlike  HTML, XML tags are user-defined. This is what gives XML its power and utility. But, at the same time, to make it really useful, each such XML document should have a 'schema'....Something like Data Definition in SQL. It should be carefully noted that 'schema' is a general term. In the earlier days of XML, the only schema that was known and used was DTD (Document-type-definition). Even today, DTD is said to be the most prevalent 'schema' in use and best known, among developers.

  However, DTD was found to have a number of limitations.Microsoft is credited with the proposal for an alternative to DTD in the very early days of XML.It was known as 'XML Schema'.The proposal was submitted to the W3C (World-wide Web Consortium), which is the standards body for XML , HTML and related topics and was later adopted by W3C with some modifications.

  'XML-Schema' is considered to be better than DTD, for a number of reasons. First, unlike a DTD, an XML-Schema is itself an XML document. Secondly, it has provision for greater variety of data-types than are available in DTD.It supports Name-space.

********************************************

********************************************  

However, an XML-Schema is of rather large size compared to the corresponding DTD representation .

   Because of this 'limitation' of XML-Schema, another validation scheme , known as Relax-NG , developed by another standards organization, known as OASIS  ,is also prevalent.This schema is comparatively compact. Be it DTD or XML-Schema or Relax-NG, all these topics are heavy reading and belong properly to the study of XML by itself rather than as applied XML in Java.Though , XML webservice is built entirely on XML and SOAP, it is possible for a developer to build an effective webservice application in ASP.net & AXIS, without going into the details of XML.It may be said to be the main merit of ASP.net,that it hides the details of implementation and allows the Application developer to concentrate on the business-logic on hand.So does, Apache's AXIS.But, at some stage, a good understanding  of the inner working details becomes useful, for trouble-shooting and advanced work.But, the danger of 'missing the forest for the trees' , also is there , if we get into implementation details, too deeply.

    The problem in JAXB, is that it originally dealt with DTD and later switched over to XML-Schema (And many books were written about this earliest version of JAXB and are not suitable now).. SUN  promotes  an alternative to the SOAP standard , known  as Eb-XML , being developed under the auspices of UNESCO & OASIS.This is said to be more attuned to the needs of Vericals ( specific industries ). JAXB attempts to incorporate support for Relax-NG also, as it is from OASIS..

When JAXB work started, it  dealt with  DTD only, because at that time the XML-Schema had not been standardized.Later versions ,are primarily meant to work with XML-schema and DTD support  is  only experimental. Same for Relax-NG,but for an entirely different reason, because work on that is still progressing.  These areas are developing so fast that books and articles become out-dated, very quickly, but they are not withdrawn from the web/market, thus  confusing the readers. Information is getting 'dated', rapidly.With so many acronyms around, it is better  that we try to understand what they mean and their context , before diving in.Hence, the present tutorial attempts to give such an overview.

  (The JWSDP1.4 package has the sub-folders for

JAXP,JAXB,JAXR,JAX-RPC,JSTL,SAAJ,XWS-SECURITY,XMLDSIG-xml digital signature).

------

   The latest release of JWSDP is JWSDP1.5.

( Jan-2005).The following three items can be said to be new or  special improvements  the JWSDP pack.

   a)  Java Streaming XML Parser

   b)  XML Digital Signature

   c)  JAXB(1.04)

--------------------------------------

a)  (SJSXP)(Sun Java Streaming XML Parser ).

------------------------------

The Streaming API for XML (StAX)provides a stream-based API for reading and writing XML documents. The StAX approach is also known as "pull" parsing. This sounds like Microsoft's method of XML processing, in DotNet platform.The DotNet platform has a class known as XmlTextReader which provides a stream API which also is based on 'pull' model.The usual SAX method is known as 'Push' model.The 'pull' model is said to be more efficient in some cases.(Interested readers can refer to page 307-322 of a very valuable book..

'ASP.Net..Tips,Tutorials and Code' by a team of authors led by Scott Mitchell(Techmedia).)

b)The Java-XML- Digital Signature package in the WSDP provides  a standard way for Java developers to access digital signature services. To quote: ***Using the XML Digital Signature APIs found in the WSDP, developers can sign and validate digital content and represent the signatures in an XML format. The signatures provide a standard way to verify that content originated from a known source and was not altered during transmission***.

c) Coming now to JAXB,in the words of Sun Documentation,

***The Java Architecture for XML Binding (JAXB) project  provides a standard API for automating the mapping between XML documents and Java objects. Using JAXB, a developer can compile a schema into Java classes that provide support for marshaling, unmarshaling, accessing, updating, and validating. The main goal of JAXB is to relieve the developer of these tasks so that they can be more productive and be exposed to fewer XML-oriented issues. JAXB 1.0.4 provides support for a subset of XML Schema and experimental support for RelaxNG. RelaxNG is a simplified XML schema system sponsored by the Oasis group. JAXB is currently integrated with JAX-RPC for easily transporting objects across the wire.***.

   There is common agreement in Industry that XML-Schema  is better than DTD.

In a DTD, element content is mostly limited to strings whereas an XML-Schema can set the data type of elements to very specific types such as integers and date. However, with thousands  of DTD based XML documents , being in use today, it is vital that compatibility is maintained. Tools are said  to be available for automating the conversion of DTD into an equivalent Schema.

( readers can see p114 of XML-Unleashed by

Michael Morrison..Techmedia, for details).

   If to create a valid XML document, we begin by creating a DTD.(Document-type-Definition),such DTD creation  is more difficult than creating a well-formed XML document, straight away! If the beginner can first create an XML document and from that generate a DTD automatically, it will be easier job.AlphaWorks of IBM created a Java library, DDbE(Data Descriptors by Example),to make it easier for beginners to create the DTD. The above library fulfils that role.For working properly, DDbE requires XML4j  parser from IBM. ( see p.636 of the above book).Student readers can check up the current status of such automated tools. Though unconventional, this approach, is easier and saves a lot of labour. We get a readymade framework which can then be suitably modified. The recommended method in JAXB is not to begin with DTD but to use an

XML-Schema.

--------------------------------------------

   Let us now try to get familiar with the technical terms in JAXB environment.

   We begin from an XML-Schema , first. An XML schema uses XML syntax to describe the relationships among elements, attributes and entities in an XML document. The purpose of an XML schema is to define a class of XML documents that must adhere to a particular set of structural rules and data constraints. 

There is a  command  in JAXB/bin known as xjc .(Actually, it is a batch file which uses jaxb binding compiler.). We can invoke this batch file from the command line (after setting the required path & classpath, to be defined soon).The command is like :

 >xjc  books.xsd , where books.xsd is the XML-Schema file being used.The command has a few optional arguments, to specify the name of target directory, package name etc. Sometimes, we may prefer to use an existing DTD as reference and in such cases, we can give -dtd  as option and then specify the DTD file).

 When we run this command,it generates a number of Java source files in layered packages.There is a default binding rule and it is generally sufficient. In case, we need more fine-tuned behaviour, we can supply such a binding schema also as an argument.

    These source files are then compiled.

Using these classes, we can convert an XML document which is based on the specified schema into corresponding java objects in a tree, different from the usual DOM tree and more efficient. This process of converting an XML document into Java objects is called Unmarshalling.

In the context of JAXB, a Java application is a client application that uses the JAXB binding framework to unmarshal XML data, validate and modify Java content objects, and marshal Java content back to XML data.

---

To paraphrase from Sun's Documentation,

*** 

The general steps in the JAXB data binding process are:

1.  Generate classes. An XML schema is used as input to the JAXB binding compiler to generate JAXB classes based on that schema.

2.   Compile classes. All of the generated classes, source files, and application code must be compiled.

3.  Unmarshal. XML documents written according to the constraints in the source schema are unmarshalled by the JAXB binding framework.

4.  Generate content tree. The unmarshalling process generates a content tree of data objects instantiated from the generated JAXB classes; this content tree represents the structure and content of the source XML documents.

5.   Validate (optional). The unmarshalling process optionally involves validation of the source XML documents before generating the content tree.

6.   Process  the content. The client application can modify the XML data represented by the Java content tree by means of interfaces generated by the binding compiler.

7.  Marshal. The processed content tree is marshalled out to one or more XML output documents. The content may be validated before marshalling.

---------------------------------------------------------------------------------------------------------------------

The following code-snippet  illustrates the process of unmarshalling.

( we are assuming an xml document named 'library'.)."<package-name>" refers to the package in which the auto-genrated class files due to xjc command are available.

 ------------------------------------------- 

JAXBContext  context =

JAXBContext.newInstance("<package-name>") ;

Unmarshaller   unmarshaller =

   context.createUnmarshaller() ;

Library   library =

  (Library)unmarshaller.unmarshal

  (new   FileInputStream("library.xml")) ;

-------------------------------------------------------

library.xml is an example XML document that conforms to the schema file from which the JAXB-generated Java classes and interfaces are created, and Library is the root object in the XML document. Hereafter, we can use java  idiom to manipulate the objects in the library.

-------------------------------------------

An application can directly create java objects by using the ObjectFactory created by the xjc process.First, we get an instance of ObjectFactory.This factory instance is then used to create a library object. 

We create objects in that library tree, set attributes for such objects& add the objects to the root.Finally, an instance of Marshaller class, is created and used to send the object to xml file.

---------------------------------------

ObjectFactory   factory=

  new ObjectFactory();

Library  library = factory.createLibrary();

Book  book1 = factory.createBook();

book1.setTitle("java today");

book1.setPrice("200Rs");

library.add(book1);

Marshaller   marshaller =   context.createMarshaller();

marshaller.marshal(library, new FileOutputStream("library.xml")) ;

============================================

   Thus, the process of converting a java-object tree to xml is known as Marshalling.

To, recapitulate,

Unmarshalling means creating a java object tree  for an XML document.

Marshalling means  converting a javaobject tree into equivalent XML.

==========================================

With these introductory ideas, we take up a simple example in the next part of this tutorial.

*******************************************  

  (Page-1)   (Page-2) (Page-3)