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. This document shows you how NetBeans IDE 6.1 and 6.0 provide tooling support for JAXB, principally by means of a wizard that turns various types of XML documents into Java classes. Starting with a given WSDL file, we will generate Java classes and then do something with them.

In this tutorial, you will learn two specific things:

• How to use a wizard in the IDE to bind the schema for an XML document into a set of Java classes that represents the schema.
• How to use a variety of tools provided by the IDE to quickly and efficiently make use of the generated Java classes.

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

• Generating Java Objects from XML Documents
• Examining the JAXB Wizard Output
• Using the Java Objects

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

Software or Resource	Version Required
NetBeans IDE	"All" download bundle 6.0 or 6.1 with the SOA plugin or Java download bundle 6.5
Java Development Kit (JDK)	version 6 or version 5
Java EE-compliant web or application server	Tomcat web server 6.0 and/or GlassFish application server v2
The WSDL file used in this tutorial	CreditReportSimple.wsdl

Both Tomcat and GlassFish can be installed with the Web and Java EE distribution of NetBeans IDE. Alternatively, you can visit the GlassFish 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.

1. Choose File > New Project. Under Categories, select Java. Under Projects, select Java Application and click Next.
2. Under Project Name, enter JseSimpleClientReport and click Finish.

   Creating a project in NetBeans 6.1 includes new options which can be left at the default. For example, the Use Dedicated Folder for Storing Libraries checkbox may be left unselected.

3. 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 types of XML document are supported:
     • XML Schema
     • Relax NG
     • Relax NG Compact
     • XML DTD
     • WSDL
   • 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.
4. Type CreditReport in Binding Name and org.netbeans.j2ee.wsdl.creditreport in Package Name.
5. Next to Select From Local File System, click Browse and browse to the WSDL file that you downloaded at the start of this tutorial.
6. In the Schema Type drop-down, choose WSDL. You should now see the following:

   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.

   
7. 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.

1. 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:
   
2. The Projects window 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.
   

   Also note that the wizard has put the JAXB libraries on the application's classpath for JDK 5. For JDK 6, the JDK itself provides the JAXB libraries, so no new nodes are added to the Libraries node.

3. Assuming you have changed the settings in the wizard, you can regenerate the Java objects, as indicated below:
   
4. Right-click the WSDL file and choose Open. The document opens in an editor with three tabs, "Source", "WSDL", and "Partner". Click WSDL and notice that a visual view opens, allowing you to easily analyze and edit the WSDL file.
   

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.

Using the Java Objects

The goal of this exercise is to do something meaningful with the files and code that the IDE has generated for you. You will set some values in one of the generated Java objects and then marshall it to the IDE's Output window.

1. Open the Main class that the New Java Application wizard generated for you. Add an import statement for org.netbeans.j2ee.wsdl.creditreport.CreditReport.
2. Declare CreditReport, which is one of the generated root JAXB classes, in the constructor:

   public static void main(String[] args) {
        CreditReport cr = new CreditReport();
           }

3. Now just type 'cr.', to start using your declaration, and the IDE gives you relevant code completion for your JAXB artifacts (on some systems you may need to press Ctrl-Space):
   
4. 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));
           

5. Type the letters 'jaxbm' into the editor. 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. A related code template is 'jaxbu', which stands for 'JAXB Unmarshalling'.

6. 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
   }

7. Right-click anywhere in the body of the code and select Fix Imports. The necessary package import statements are added to the code. Any error indicators should disappear.

   You have now used various tools provided by the IDE for working with JAXB in the editor. Your small application is now ready for deployment.

8. If you are using NetBeans IDE 6.5, right-click the project node and select Properties from the context menu. The Project Properties dialog opens. Navigate to Build > Compiling and unselect Compile on Save. Otherwise, you will get Class Not Found exceptions for your generated classes.
   
9. Run the application. The Output window displays the following:
   

See Also

For more information about using NetBeans IDE to develop Java EE applications, see the following resources:

• Getting Started with JAX-WS Web Services
• Developing JAX-WS Web Service Clients
• Getting Started with RESTful Web Services
• Consuming StrikeIron Web Services in Web Applications
• Advanced Web Service Interoperability
• EJB & Web Service Applications Learning Trail

To send comments and suggestions, get support, and keep informed on the latest developments on the NetBeans IDE Java EE development features, join the mailing list.