HOME / Docs & Support

Binding WSDL to Java with JAXB

The Java Architecture for XML Binding API (JAXB) makes it easy to access XML documents from applications written in the Java programming language. JAXB is an alternative to using a SAX or DOM parser to access the data in an XML document. When you access an XML document with JAXB, first you bind the schema for the XML document into a set of Java classes that represents the schema. Then you unmarshal the XML document. Unmarshalling a document means creating a tree of content objects that represents the content and organization of the document.

You can also use JAXB to build an XML document. To build an XML document with JAXB, you first bind the schema for the XML document you want to build. Then you create a content tree. Lastly, you marshal the content tree into an XML document.

The following diagram, from Java Architecture for XML Binding API, shows the processes both for accessing and for building XML documents from Java applications.

Diagram showing JAXB process for accessing or creating XML from java

This tutorial shows you NetBeans IDE tooling support for JAXB. In this tutorial, you will learn three specific things:

How to use a wizard in the IDE to bind the schema for an XML document and unmarshal the document into a set of Java classes that represents the schema.
How to use the JAXB-generated class in application code.
How to marshal Java code into an XML Schema document.

For detailed information on the JAXB architecture, as well as on JAXB as a whole, see Chapter 2: Binding between XML Schema and Java Classes and Chapter 3: Using JAXB in The Java Web Services Tutorial.

Contents

Content on this page applies to NetBeans IDE 6.7 and later

Generating Java Objects from XML Documents
Examining the JAXB Wizard Output
Marshalling Java Code Into an XML Schema Document

To follow this tutorial, you need the following software and resources.

Software or Resource	Version Required
NetBeans IDE	Java EE download bundle
Java Development Kit (JDK)	version 7 or version 6 Warning: NetBeans IDE 6.9 requires JDK 6
The WSDL file used in this tutorial	CreditReportSimple.wsdl

Both Tomcat and the GlassFish server can be installed with the Web and Java EE distribution of NetBeans IDE. Alternatively, you can visit the the GlassFish server downloads page or the Apache Tomcat downloads page.

Generating Java Objects from XML Documents

The goal of this exercise is to create a project and generate Java objects from an XML document.

Download CreditReportSimple.wsdl and save it to the location of your choice.
Choose File > New Project. Under Categories, select Java. Under Projects, select Java Application and click Next.
Under Project Name, enter JseSimpleClientReport and click Finish. In the Projects window, the JseSimpleClientReport project appears.
In the Projects window, right-click the JseSimpleClientReport node and choose New > Other > XML > JAXB Binding. Then click Next. The New JAXB Binding wizard appears.

The settings in the wizard above serve the following purposes:
- Binding Name. Specifies the name of the new JAXB binding, which will be used to identify it.
- Project. Displays the name of the current project.
- Schema File. The file that you want to work with can either be available locally or on-line.
- Schema Type. The following XML Schema languages are supported:
  - XML Schema
  - Relax NG - A simple XML Schema language. XML syntax
  - Relax NG Compact - A simple XML Schema language. Non-XML syntax
  - XML DTD - The older alternative to XML Schema
  - WSDL - Web Service Definition Language. The XML Schema language for defining SOAP-based web services.
- Package Name. Specifies the package to which the Java objects will be generated.
- Compiler Options. Many compiler options are available, as described here in the Java EE 5 Tutorial. However, in relation to the JAXB Wizard, only the following are relevant and you can set them using checkboxes in the wizard:
  - nv. Do not perform strict validation of the input schema(s). By default, strict validation of the source schema is performed before processing. Note that this does not mean the binding compiler will not perform any validation; it simply means that it will perform less-strict validation.
  - readOnly. Force the compiler to mark the generated Java sources read-only. By default, the compiler does not write-protect the Java source files it generates.
  - npa. Suppress the generation of package level annotations into **/package-info.java. Using this switch causes the generated code to internalize those annotations into the other generated classes.
  - verbose. Produce maximum compiler output, such as progress information and warnings.
  - quiet. Suppress compiler output, such as progress information and warnings.
- Use Extension. By default, the compiler strictly enforces the rules outlined in the Compatibility chapter of the JAXB Specification. In the default (strict) mode, you are also limited to using only the binding customizations defined in the specification. By using this option, you will be allowed to use the JAXB Vendor Extensions.
- Use Binding File. Lets you import and edit one or more JAXB binding customization files.
- Use Catalog File. Lets you import and edit OASIS catalog files.
Type CreditReport in Binding Name.
Under Schema File, select Select From Local File System. Click Browse and browse to the WSDL file that you downloaded at the start of this tutorial.
In the Schema Type drop-down, choose WSDL (unless the IDE chose this automatically).
Note: A warning might appear saying that WSDL Schema support is only experimental and you need to use the -wsdl option to activate it. Ignore this warning.
In Package Name type org.netbeans.j2ee.wsdl.creditreport. You should now see the following:
Click Finish.

The IDE generates the Java objects from the given XML document. In the next section, we examine the Java objects in the IDE.

Examining the JAXB Wizard Output

The goal of this exercise is to familiarize ourselves with the tools in NetBeans IDE for working with the JAXB wizard's output.

As with other artifacts that the IDE regenerates whenever a project is built, the Java objects are generated in the build folder. Open the Files window and then you can browse to the location of the generated Java objects. These Java objects are also displayed in the Projects window, under the Generated Sources node.
The Projects window also displays a new node that contains the WSDL file, as shown below. Note that you can right-click the CreditReport node and then the wizard reopens and you can change the settings you specified earlier.
Assuming you have changed the settings in the wizard, you can regenerate the Java objects, as indicated below:
Right-click the WSDL file and choose Open. The document opens in the editor.

Now that you know what the IDE has generated for your XML document, we will use some of the tools we have looked at to do something meaningful with our generated Java objects.

Marshalling Java Code Into an XML Schema

The goal of this exercise is to do something meaningful with the files and code that the IDE has generated for you. You set some values in one of the generated Java objects and then marshal the object into an XML Schema document that appears in the IDE's Output window.

Open the main class that the New Java Application wizard generated for you. By default this class is named after the project, JseSimpleClientReport.java. Declare CreditReport, which is one of the generated root JAXB classes, in the main method body:
```
public static void main(String[] args) {
     CreditReport cr = new CreditReport(); 
}
```
A warning icon appears. Hover over it, and a tooltip opens telling you that the IDE cannot find the class CreditReport. Left-click the warning icon and select the option for the IDE to add the import statement.
In the main method body, type 'cr.' The IDE gives you relevant code completion for your JAXB artifacts (on some systems you may need to press Ctrl-Space):

Set some values for the JAXB class, such as the following (Add an import statement for java.math.BigInteger):

    cr.setFirstName("Butros Butros");
    cr.setLastName("Gali");
    cr.setDob("1930/05/30");
    cr.setScore("900");
    cr.setSsn("123-45-6789");

    cr.setLatestAddress1("2500 Some Ave");
    cr.setLatestAddress2("Suite 5000");
    cr.setCity("New York");
    cr.setState("New York");
    cr.setCountry("USA");
    cr.setPostalCode("NY 12345-6789");

    cr.setCurrency("USD");
    cr.setLiability(BigInteger.valueOf(2000000));
    cr.setLiquidAssests(BigInteger.valueOf(3000000));
    cr.setImmovableAssests(BigInteger.valueOf(5000000));

In the main method body, below the values you inserted, type the letters 'jaxbm'. These letters stand for 'JAXB Marshalling'. You should now see the following:

A red underline appears, because the characters you typed do not form a word that is part of the Java programming language. Instead, these letters form a NetBeans code template, which we will use in the next step.

NetBeans also provides a code template for JAXB unmarshalling. Its abbreviation is 'jaxbu'.

Press the 'Tab' key.

The 'jaxbm' characters expand and a code snippet appears:

try {
    javax.xml.bind.JAXBContext jaxbCtx = javax.xml.bind.JAXBContext.newInstance(cr.getClass().getPackage().getName());
    javax.xml.bind.Marshaller marshaller = jaxbCtx.createMarshaller();
    marshaller.setProperty(javax.xml.bind.Marshaller.JAXB_ENCODING, "UTF-8"); //NOI18N
    marshaller.setProperty(javax.xml.bind.Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);
    marshaller.marshal(cr, System.out);
} catch (javax.xml.bind.JAXBException ex) {
    // XXXTODO Handle exception
    java.util.logging.Logger.getLogger("global").log(java.util.logging.Level.SEVERE, null, ex); //NOI18N
}

Warning: Code template expansion is very sensitive. You cannot add a space and then hit tab, or mistype the phrase, correct it, and then hit tab, etc. You must only type the phrase, correctly, and then hit tab. If you make a typing error, delete the phrase you started to type and type in the entire phrase.