Learn how to use JiBX to convert XML to Java POJOs and vice versa. In this tutorial, you’ll learn about using the new features of JiBX to generate XML schema definitions easily from existing Java code and to. JiBX Binding Tutorial. Companies are moving more and more towards service oriented architecture (SOA) and SOA services communicate with well formatted.
|Published (Last):||23 March 2006|
|PDF File Size:||9.69 Mb|
|ePub File Size:||17.81 Mb|
|Price:||Free* [*Free Regsitration Required]|
Improve schema quality with custom conversion of Java data models to and from XML documents. But the complexity of its binding definitions and its limited support for increasingly widely used XML schema definitions have frustrated users at times. In this tutorial, you’ll learn about using the new features of JiBX 1. Part 2 covers the flip side of starting from XML schema definitions and generating Java code.
You’ll first see how tutorlal start with a simple Java data model and generate a default schema matching that model. From that base, you’ll learn how you tutorlal easily apply a range of customizations to control the actual values used from your Java classes and how they’re accessed, whether they are required or optional, tutogial and namespaces used in the XML, and even the generated schema definition’s structure.
Along the way, you’ll see tutoriao JiBX adds value to your generated schemas by leveraging your investment in Javadocs to document the schema definition automatically.
After reading this tutorial and working through the supplied examples, you will be able to use JiBX to generate tutorixl XML schema definitions from your own Java data-structure classes.
To understand this tutorial, you should have at least a basic knowledge of both Java code and XML. You don’t need a detailed understanding of XML schema definitions, but some familiarity with schema will help you understand the examples better. What sets JiBX apart from the others are performance and flexibility features. JiBX performance consistently measures at the top end of the range, surpassing that of other common tools such as JAXB 2.
Customizing JiBX binding behavior
JiBX is also more flexible than almost all other Java-XML tools, using binding definitions to decouple the Java structure from the XML representation so that each can be changed independently of the other.
You can use tools included in the JiBX release to generate a schema definition matching your Java code or to generate Java code matching your schema definition. Either way, you also get a binding definition that lets you use JiBX to convert between the Java code and XML documents matching the schema definition.
In this tutorial, you’ll see how to apply the first type of generation: You need to install JiBX before proceeding tuotrial this tutorial. Download the latest 1. You’ll end up with a directory named jibx, which contains all the Tutoriap JARs, documentation, examples, and even the source code. Now download the tutorial sample codealso provided as a ZIP file. This should create ttutorial dwcode1 subdirectory in the jibx directory, with the example files including build.
The sample code includes an Apache Ant build file to automate running the JiBX tools and handle the other steps involved in the examples. If you install the sample code elsewhere, you can still use the Ant build. Alternatively, you can edit the build. The tutorial example code uses Java 5 typed collection and enum features, jibs JiBX itself is fully compatible with older Java versions. The standard JiBX runtime works with 1. The BindGen documentation in the JiBX download includes an example showing how customizations can supply BindGen with the jixb of typed collections when you use pre-Java 5 code.
You’ll learn how in this section. As an example, I’ll start with the Java code for a nibx of bean-style private fields, public get and set access methods classes used to represent an order from an online store. The full sample code is in the sample code’s src directory. BindGen tool included in the jibx-tools. You can run the tool directly from the command line or indirectly via a build tool such as Ant. The tutorial download includes an Ant build. To try this out, open a console in the dwcode1 directory of the installed download and type ant compile bindgen.
If you have Ant installed on your system and have installed the download code according to the instructions, you should see output similar to that shown in Figure View image at full size. You can also run BindGen directly from the console.
To do this, you need to include jibx-tools. If you want to duplicate the effect of the supplied Ant bindgen target, you also need to pass the root directory for the source files of your classes in the command line. Finally, you need to list the root class es you want used for generation. Many other options can be passed to BindGen from the command line. You’ll look into those later in the tutorial. Right now, let’s look at the generated schema. Listing 2 shows the generated schema output from BindGen as starter.
The start tag for the schema definition matching each Java class is displayed in bold to emphasize the structure. By default, BindGen generates a schema with nested complexType and simpleType definitions for types that are used only once and separate definitions for types that are used more than once.
In this case, the nested style results in a schema with just three global definitions: The Address class is used in two places within the Order class for billing and shipping addresseswhich is why that class is represented by a separate global definition in the schema. Schema allows you to reuse definitions only if they’re global. The other classes in the Java data structure CustomerItemand Shipping are each referenced at tutofial one point in the Order class, so the corresponding type definitions are embedded directly within the order schema type definition.
One of the nicer BindGen features is that it can generate schema documentation from Javadocs in the input classes. You can see kibx schema documentation in Listing 2 for each field with a Javadoc in Listing 1and for each global type corresponding to a class with a Javadoc.
Not all forms of Javadocs can be matched with schema components by BindGen’s default handling — and some Javadocs, such as those on “get” access methods, may look odd when converted to schema documentation — but the resulting schema documentation can be extremely useful for clarifying jib proper use tuotrial the XML representation. You can even define your own formatter class for Javadocs used as schema documentation, if you want to make some changes to the text in the process of conversion such as stripping “Get the This Javadoc conversion feature works only if you have the source code available for the classes and provide an argument to BindGen telling it the root directory path or paths.
Java code to XML schema
In the command-line samples I provided earlier see Generating the default binding and schemathe source path is supplied as -s src. That binding definition is tutorisl the main output of Tutorual, with the schema generated from the binding. Binding definitions contain full details of the conversions to be done by JiBX, so they’re necessarily complex.
Fortunately, you don’t need to understand the binding definition in order to work with JiBX using BindGen binding and schema generation, so this tutorial doesn’t cover the details. To use the generated binding definition in working with XML documents, you first need to run the JiBX binding compiler tool.
Bind XML message to Java objects using JiBX – JiBX Binding Tutorial
The binding compiler adds bytecode to your compiled class files that actually implements the conversions to and from XML, as specified by the binding definition. You must run the binding compiler each time you recompile your Java classes or modify the binding definition, so it’s generally best to add the binding compiler step as part of your project’s standard build process.
The binding compiler is included in the JiBX distribution as part of jibx-bind. The JiBX documentation provides full details about different ways to run the binding compiler, including how you can run it at run time rather than as part of the build.
Jibx: mapping xml to java
For this tutorial’s purposes, you’ll keep things simple and just run the binding compiler through Ant, using the build. Figure 2 shows the output that you should see when you run this target, assuming you’ve already run the compile and bindgen targets.
You can also run all three targets in sequence by listing them in order on the command line: Listing 3 shows a simple test document matching the generated schema, included in the tutorial’s code download as data. The download package also includes a simple test program, shown here as Listing 4that demonstrates using JiBX for both unmarshalling and marshalling documents.
Marshalling is the process of generating an XML representation for an object in memory, potentially including objects linked from the original object. Unmarshalling is the reverse process of marshalling, building an object and potentially a graph of linked objects in memory from an XML representation. The Ant run target executes this test program, using the Listing 3 document as input and writing the marshalled copy of the document to a file named out.
You can inspect the generated out. Aside from namespace declaration and attribute order and the added total attribute in the output computed and set by the test programthe two documents should be identical. This won’t always be the case! JiBX, like most forms of data binding, works with only the “significant” data in the document, meaning those values being used by your application. Nonsignificant parts of the document such as whitespace within a start or end tag, text between elements, and comments are lost when you unmarshal a document.
Part of the reason the input and output documents are so similar in this case is that the Listing 4 code sets the output format to use indentation of two spaces per element nesting level, matching the input document. Sharp observers will notice one difference between the input and output that seems significant, in the item-list portion of the output document, shown in Listing If you compare the line shown in bold in Listing 5 with the corresponding line in the Listing 3 original document, you can see that the price has changed from 9.
This is not an error, though. The representation used for the price value is a floatand in terms of both Java and XML schema, leading zeros before the decimal point and trailing zeros after the decimal point are not significant for a float.
In this section, you’ll learn how to customize BindGen operation to control the XML representation of data, change the style of names and namespaces, and control some aspects of schema structure.
BindGen supports extensive customizations for all aspects of binding and schema generation. The set of customizations to be applied are passed futorial BindGen as an XML document, with nested elements that mirror the structure of your Java code. Listing 6 gives a simple example:. The nested structure is especially convenient because many customization attributes are inherited through the element nesting, as I’ll discuss later in this section.
A customization file is passed to BindGen as a command-line parameter, using the form -c file-path. Customizations are always optional, and you never need to use a customization file unless you want to change the default BindGen behavior.
BindGen does a reasonable job with its default handling of Java classes, but there are limits on what can be done without user jivx. For example, the default handling is to include every field in the XML representation except for static, transient, or final fields.
This approach works fine for classes that represent simple data objects; however, if your classes include state information or computed values, you might tuttorial up with an XML representation that includes values you’d rather not expose outside the class.
Second, you can choose either to list the values you want to include in the XML representation for a class or to list the values you want to exclude. The Listing 6 customizations demonstrate both these techniques. BindGen also supports generating one-way conversions, which can be more convenient in some cases.
For instance, value object classes are generally immutable and define only final fields and read “get” access methods. This makes value object classes difficult to use for two-way conversions with BindGen. If you instead tell BindGen to generate an output-only conversion, it will happily work with either the thtorial or the properties, whichever you prefer.
This attribute is an example of an inherited tuhorial setting, which applies to everything nested inside the element with the attribute.