| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> | |
| <html><head> | |
| <link rel="stylesheet" href="../../../print.css" type="text/css" media="print"><title>Binding WSDL to Java with JAXB - NetBeans IDE</title> | |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> | |
| <meta name="KEYWORDS" content="NETBEANS, TUTORIAL, GUIDE, USER, DOCUMENTATION, WEB SERVICE, WEB SERVICES, SOAP, METRO, WSDL, JAVA, JAXB, JAX-WS"> | |
| <meta name="description" content="This tutorial shows how to use NetBeans IDE 7.0-7.4 | |
| to work with Java Architecture for XML Binding (JAXB) to generate Java classes based on XML documents."> | |
| <link rel="stylesheet" href="../../../netbeans.css"></head><body> | |
| <h1>Binding WSDL to Java with JAXB</h1> | |
| <p>The <a href="http://www.oracle.com/technetwork/articles/javase/index-140168.html" target="_blank">Java Architecture for XML Binding API</a> | |
| (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 | |
| <a href="http://www.oracle.com/technetwork/articles/javase/index-140168.html#binsch" target="_blank"> | |
| <em>bind</em> the schema</a> for the XML document into a set of Java classes | |
| that represents the schema. Then you | |
| <a href="http://www.oracle.com/technetwork/articles/javase/index-140168.html#unmars" target="_blank"> | |
| <em>unmarshal</em> the XML document</a>. | |
| Unmarshalling a document means creating a tree of content objects that | |
| represents the content and organization of the document.</p> | |
| <p>You can also use JAXB to build an XML document. To build an XML document with | |
| JAXB, you first <a href="http://www.oracle.com/technetwork/articles/javase/index-140168.html#binsch2" target="_blank"> | |
| bind the schema</a> for the XML document you want to build. Then you | |
| <a href="http://www.oracle.com/technetwork/articles/javase/index-140168.html#crtree" target="_blank"> | |
| create a content tree</a>. Lastly, you | |
| <a href="http://www.oracle.com/technetwork/articles/javase/index-140168.html#mars"> | |
| <em>marshal</em> the content tree</a> into an XML document.</p> | |
| <p>The following diagram, from | |
| <a href="http://www.oracle.com/technetwork/articles/javase/index-140168.html" target="_blank"> | |
| Java Architecture for XML Binding API</a>, shows the processes | |
| both for accessing and for building XML documents from Java applications.</p> | |
| <p><img style="width: 450px; height: 300px;" alt="Diagram showing JAXB process for accessing or creating XML from java" src="../../../images_www/articles/72/websvc/jaxb/xml_schema_fig1.PNG"><br> | |
| </p> | |
| <p>This tutorial shows you NetBeans IDE | |
| tooling support for JAXB. In this tutorial, you will learn three specific things: </p> | |
| <ul> | |
| <li>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. </li> | |
| <li>How to use the JAXB-generated class in application code.</li> | |
| <li>How to marshal Java code into an XML Schema document. </li> | |
| </ul> | |
| <p>For detailed information on the JAXB architecture, as well as on | |
| JAXB as a whole, see <a href="http://download.oracle.com/docs/cd/E17802_01/webservices/webservices/docs/2.0/tutorial/doc/JAXBWorks.html#wp100322" target="_blank">Chapter 2: Binding between XML Schema and Java Classes</a> | |
| and <a href="http://download.oracle.com/docs/cd/E17802_01/webservices/webservices/docs/2.0/tutorial/doc/JAXBUsing.html#wp78319" target="_blank">Chapter 3: Using JAXB</a> in <a href="http://java.sun.com/webservices/docs/2.0/tutorial/doc/" target="_blank">The Java Web Services Tutorial</a>. </p> | |
| <p><b>Contents</b></p> | |
| <img src="../../../images_www/articles/72/netbeans-stamp-74-73-72.png" class="stamp" alt="Content on this page applies to NetBeans IDE 7.2, 7.3 and 7.4" title="Content on this page applies to the NetBeans IDE 7.2, 7.3 and 7.4" > | |
| <ul> | |
| <li><a href="#Exercise_1"> Generating Java Objects from XML Documents</a></li> | |
| <li><a href="#Exercise_2"> Examining the JAXB Wizard Output</a></li> | |
| <li><a href="#Exercise_3">Marshalling Java Code Into an XML Schema Document </a></li> | |
| </ul> | |
| <p><b>To follow this tutorial, you need the following software and | |
| resources.</b></p> | |
| <table> | |
| <tbody> | |
| <tr> | |
| <th class="tblheader" scope="col">Software or Resource</th> | |
| <th class="tblheader" scope="col">Version Required</th> | |
| </tr> | |
| <tr> | |
| <td class="tbltd1"><a href="http://www.netbeans.org/downloads/index.html">NetBeans IDE</a></td> | |
| <td class="tbltd1"> Java EE download bundle </td> | |
| </tr> | |
| <tr> | |
| <td class="tbltd1"><a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Java Development | |
| Kit (JDK)</a> </td> | |
| <td class="tbltd1">version 7 or version 6</td> | |
| </tr> | |
| <tr> | |
| <td class="tbltd1">The WSDL file used in this tutorial</td> | |
| <td><a href="http://www.netbeans.org/files/documents/4/2518/CreditReportSimple.wsdl">CreditReportSimple.wsdl</a></td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <p class="notes">Both | |
| Tomcat and the GlassFish server can be installed with the Web and Java | |
| EE distribution of NetBeans IDE. | |
| Alternatively, you can visit the <a href="https://glassfish.java.net/download.html">the | |
| GlassFish server downloads page</a> or the <a href="http://tomcat.apache.org/download-60.cgi">Apache Tomcat | |
| downloads page</a>.</p> | |
| <!-- ===================================================================================== --> | |
| <h2><a name="Exercise_1"></a><!--Exercise 1: --> Generating Java | |
| Objects from XML Documents</h2> | |
| <p>The goal of this exercise is to create a project and generate Java | |
| objects from an XML document.</p> | |
| <ol> | |
| <li>Download <a href="http://www.netbeans.org/files/documents/4/2518/CreditReportSimple.wsdl" target="_blank">CreditReportSimple.wsdl</a> and save it to the | |
| location of your choice.<br> | |
| </li> | |
| <li>Choose File > New Project. Under Categories, select Java. | |
| Under Projects, select Java Application and click Next.</li> | |
| <li>Under Project Name, enter <tt>JseSimpleClientReport</tt> and | |
| click Finish. In the Projects window, the JseSimpleClientReport project | |
| appears.</li> | |
| <li>In the Projects window, right-click the <tt>JseSimpleClientReport</tt> | |
| node and choose New > Other > XML > JAXB Binding. Then click | |
| Next. The New JAXB Binding wizard appears. <br> | |
| <img src="../../../images_www/articles/72/websvc/jaxb/jaxb-wiz-1.png" alt="JAXB Wizard" class="margin-around" border="1" height="519" width="600"> | |
| <p>The settings in the wizard above serve the following purposes:</p> | |
| <ul> | |
| <li><b>Binding Name.</b> Specifies the name of the new JAXB | |
| binding, which will be used to identify it.</li> | |
| <li><b>Project.</b> Displays the name of the current project.</li> | |
| <li><b>Schema File.</b> The file that you want to work with can | |
| either be available locally or on-line.</li> | |
| <li><b>Schema Type.</b> The following XML Schema languages are | |
| supported: | |
| <ul> | |
| <li><a href="http://www.w3.org/XML/Schema" target="_blank"><b>XML Schema</b></a></li> | |
| <li><a href="http://relaxng.org/" target="_blank"><b>Relax NG</b></a> - A simple XML Schema language. XML syntax </li> | |
| <li><a href="http://relaxng.org/" target="_blank"><b>Relax NG | |
| Compact</b></a> - A simple XML Schema language. Non-XML syntax</li> | |
| <li><b>XML DTD - </b>The older alternative to XML Schema<br></li> | |
| <li><b><a style="font-weight: bold;" href="http://www.w3.org/TR/wsdl">WSDL</a> - </b>Web Service Definition Language. The XML Schema language for defining SOAP-based web services.<br> | |
| </li> | |
| </ul> | |
| </li> | |
| <li><b>Package Name.</b> Specifies the package to which the Java | |
| objects will be generated.</li> | |
| <li><b>Compiler Options.</b> Many compiler options are available, | |
| as described <a href="http://docs.oracle.com/javaee/7/tutorial/doc/">here</a> | |
| in the Java EE 7 Tutorial. However, in relation to the JAXB Wizard, | |
| only the following are relevant and you can set them using checkboxes | |
| in the wizard: | |
| <ul> | |
| <li><b>nv.</b> 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 <i>any</i> validation; it simply means that | |
| it will perform less-strict validation.</li> | |
| <li><b>readOnly.</b> 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.</li> | |
| <li><b>npa.</b> Suppress the generation of package level | |
| annotations into <tt>**/package-info.java</tt>. Using this switch | |
| causes the generated code to internalize those annotations into the | |
| other generated classes.</li> | |
| <li><b>verbose.</b> Produce maximum compiler output, such as | |
| progress information and warnings.</li> | |
| <li><b>quiet.</b> Suppress compiler output, such as progress | |
| information and warnings.</li> | |
| </ul> | |
| </li> | |
| <li><b>Use Extension.</b> 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.</li> | |
| <li><b>Use Binding File.</b> Lets you import and edit one or more | |
| JAXB binding customization files.</li> | |
| <li><b>Use Catalog File.</b> Lets you import and edit OASIS | |
| catalog files.</li> | |
| </ul> | |
| </li> | |
| <li>Type <tt>CreditReport</tt> in Binding Name.</li> | |
| <li>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.</li> | |
| <li>In the Schema Type drop-down, choose WSDL (unless the IDE chose | |
| this automatically). | |
| <p class="alert"><strong>Note: </strong>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.</p></li> | |
| <li>In Package Name type <tt>org.netbeans.j2ee.wsdl.creditreport</tt>. You should now see the following: | |
| <img src="../../../images_www/articles/72/websvc/jaxb/jaxb-wiz-2.png" alt="Filled-out JAXB Wizard" class="margin-around" title="Filled-out JAXB Wizard" border="1" height="531" width="600"></li> | |
| <li>Click Finish.</li> | |
| </ol> | |
| <p>The IDE generates the Java objects from the given XML document. In | |
| the next section, we examine the Java objects in the IDE. </p> | |
| <h2><a name="Exercise_2"></a> Examining the JAXB Wizard Output</h2> | |
| <p>The goal of this exercise is to familiarize ourselves with the tools | |
| in NetBeans IDE for working with the JAXB wizard's output.</p> | |
| <ol> | |
| <li>As with other artifacts that the IDE regenerates whenever a | |
| project is built, the Java objects are generated in the <tt>build</tt> | |
| 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.<br> | |
| <img src="../../../images_www/articles/72/websvc/jaxb/gen-src.png" alt="Projects and Files views showing generated Java objects" class="margin-around" title="Projects view showing generated Java objects" border="1" height="552" width="328"></li> | |
| <li>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. <br> | |
| <img src="../../../images_www/articles/72/websvc/jaxb/change-jaxb-options.png" alt="Credit report context menu showing Change JAXB Options option" class="margin-around" title="Credit report context menu showing Change JAXB Options option" width="325" height="209"> | |
| </li> | |
| <li> | |
| <p>Assuming you have changed the settings in the wizard, you can | |
| regenerate the Java objects, as indicated below: <br> | |
| <img src="../../../images_www/articles/72/websvc/jaxb/regen-code.png" alt="JAXB Binding context menu showing Regenerate Java Code option" class="margin-around" title="JAXB Binding context menu showing Regenerate Java Code option" height="209" width="325"></p> | |
| </li> | |
| <li>Right-click the WSDL file and choose Open. The document opens in | |
| the editor. <br> | |
| </li> | |
| </ol> | |
| <p>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.<!-- ===================================================================================== --> | |
| </p> | |
| <h2><a name="Exercise_1"></a><!--Exercise 2: --> Marshalling Java Code Into an XML Schema </h2> | |
| <p>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.</p> | |
| <ol> | |
| <li>Open the main class that the New Java Application | |
| wizard generated for you. By default this class is named after the project, <tt>JseSimpleClientReport.java</tt>. Declare <tt>CreditReport</tt>, which is one | |
| of the generated root JAXB classes, in the <tt>main</tt> method body: | |
| <pre class="examplecode">public static void main(String[] args) {<br> CreditReport cr = new CreditReport(); <br>}</pre> | |
| </li> | |
| <li>A warning icon appears. Hover over it, and a tooltip opens | |
| telling you that the IDE cannot find the class <tt>CreditReport</tt>. | |
| Left-click the warning icon and select the option for the IDE to add | |
| the import statement.</li> | |
| <li>In the <tt>main</tt> 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): <br> | |
| <img src="../../../images_www/articles/72/websvc/jaxb/jaxb-codecompletion.png" alt="Code completion options" class="margin-around" title="Code completion options" border="1" height="332" width="447"></li> | |
| <li>Set some values for the JAXB class, such as the following (Add an | |
| import statement for <tt>java.math.BigInteger</tt>): | |
| <pre class="examplecode"> cr.setFirstName("Butros Butros");<br> cr.setLastName("Gali");<br> cr.setDob("1930/05/30");<br> cr.setScore("900");<br> cr.setSsn("123-45-6789");<br><br> cr.setLatestAddress1("2500 Some Ave");<br> cr.setLatestAddress2("Suite 5000");<br> cr.setCity("New York");<br> cr.setState("New York");<br> cr.setCountry("USA");<br> cr.setPostalCode("NY 12345-6789");<br><br> cr.setCurrency("USD");<br> cr.setLiability(BigInteger.valueOf(2000000));<br> cr.setLiquidAssests(BigInteger.valueOf(3000000));<br> cr.setImmovableAssests(BigInteger.valueOf(5000000));<br> </pre> | |
| </li> | |
| <li>In the <tt>main</tt> method body, below the values you inserted, | |
| type the letters 'jaxbm'. These letters stand for '<a href="http://www.oracle.com/technetwork/articles/javase/index-140168.html#mars" target="_blank">JAXB Marshalling</a>'. | |
| You should now see the following: <br> | |
| <img src="../../../images_www/articles/72/websvc/jaxb/jaxb-template.png" alt="Snippet in editor showing red underlined jaxbm" class="margin-around" title="Snippet in editor showing red underlined jaxbm" border="1" height="171" width="546"> | |
| <p>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.</p> <p class="notes">NetBeans also provides a code template for JAXB unmarshalling. Its abbreviation is 'jaxbu'.</p> | |
| </li> | |
| <li>Press the 'Tab' key. | |
| <p>The 'jaxbm' characters expand and a code snippet appears:</p> | |
| <pre class="examplecode">try {<br> javax.xml.bind.JAXBContext jaxbCtx = javax.xml.bind.JAXBContext.newInstance(cr.getClass().getPackage().getName());<br> javax.xml.bind.Marshaller marshaller = jaxbCtx.createMarshaller();<br> marshaller.setProperty(javax.xml.bind.Marshaller.JAXB_ENCODING, "UTF-8"); //NOI18N<br> marshaller.setProperty(javax.xml.bind.Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);<br> marshaller.marshal(cr, System.out);<br>} catch (javax.xml.bind.JAXBException ex) {<br> // XXXTODO Handle exception<br> java.util.logging.Logger.getLogger("global").log(java.util.logging.Level.SEVERE, null, ex); //NOI18N<br>}</pre> | |
| <p class="alert"><b>Warning:</b> 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. </p> | |
| </li> | |
| <li>Run the application (Right-click the project node and select | |
| Run). The Output window displays the following: <br> | |
| <img src="../../../images_www/articles/72/websvc/jaxb/jaxb-output.png" alt="Client report output" class="margin-around" title="Client report output" border="1" height="321" width="577"></li> | |
| </ol> | |
| <br> | |
| <div class="feedback-box"><a href="/about/contact_form.html?to=3&subject=Feedback:%20JAXB%20Wizard%20in%20NetBeans%20IDE">Send | |
| Us Your Feedback</a></div> | |
| <br style="clear: both;"> | |
| <!-- ======================================================================================= --> | |
| <h2><a name="seealso"></a>See Also</h2> | |
| <p>For more information about using NetBeans IDE to develop Java EE | |
| applications, see the following resources: </p> | |
| <ul> | |
| <li><a href="../../docs/websvc/jax-ws.html">Getting Started with JAX-WS Web Services</a></li> | |
| <li><a href="../../docs/websvc/client.html">Developing JAX-WS Web Service Clients</a></li> | |
| <li><a href="../../docs/websvc/rest.html">Getting Started with RESTful Web Services</a></li> | |
| <li><a href="../../docs/websvc/wsit.html">Advanced Web Service Interoperability</a></li> | |
| <li><a href="../../trails/web.html">Web Services Learning Trail</a></li> | |
| </ul> | |
| <p>To send comments and suggestions, get support, and keep informed on | |
| the latest developments on the NetBeans IDE Java EE development | |
| features, <a href="../../../community/lists/top.html">join the | |
| nbj2ee@netbeans.org mailing list</a>.</p> | |
| </body></html> |