Jump to: navigation, search

Difference between revisions of "EclipseLink/Examples/MOXy/JAXB"

(Using JAXBContext to Generate an XML Schema)
m
 
(12 intermediate revisions by 4 users not shown)
Line 1: Line 1:
==Overview==
+
== Using EclipseLink MOXy JAXB ==
 +
Java Architecture for XML Binding (JSR 222) is the standard for XML Binding in Java.  JAXB covers 100% of XML Schema concepts.  Learn how to use MOXy as your JAXB provider.:
 +
* [[EclipseLink/Examples/MOXy/JAXB/Compiler | Generating a Java Model from an XML Schema]]
 +
* [[EclipseLink/Examples/MOXy/JAXB/SpecifyRuntime | Specifying the EclipseLink MOXy JAXB Runtime]]
 +
* [[EclipseLink/Examples/MOXy/JAXB/Runtime | Using JAXB to Manipulate XML]]
 +
* [[EclipseLink/Examples/MOXy/JAXB/GenerateSchema | Generating an XML Schema from a Java Model]]
  
The following example will demonstrate how to use EclipseLink's JAXB functionality to:
 
* Generate JAXB-annotated Java classes from an XML Schema using the JAXB Compiler
 
* Unmarshal an XML Document
 
* Modify the XML data using the interfaces generated by the compiler
 
* Marshal the modified data to XML
 
  
==Setup==
+
----
  
# Ensure that you have EclipseLink correctly installed and configured for your environment.  Please see [[EclipseLink/Installing and Configuring EclipseLink]] for more information.
+
See the ''[http://www.eclipse.org/eclipselink/documentation/ Developing JAXB Applications Using EclipseLink MOXy]'' for complete information.
# Ensure that you have ANT correctly installed and configured.
+
# Unzip the Example ZIP file to a new directory.
+
# Edit the <tt>env.properties</tt> file in the root directory of the example and specify the path to your EclipseLink <tt>jlib</tt> directory:
+
<pre>
+
...
+
# Edit eclipselink.jlib to point to your EclipseLink jlib directory
+
eclipselink.jlib=C:/EclipseLink-1.0/eclipselink/jlib
+
...
+
</pre>
+
 
+
You can compile and run the Example at any time by typing <tt>ant</tt> from the Example directory. 
+
 
+
For Eclipse IDE users, a <tt>.project</tt> file is included in the Example directory.  To setup this project in Eclipse:
+
 
+
# From the "File" menu, choose "Import..."
+
# In the Import dialog, choose "General > Existing Projects into Workspace", and click "Next".
+
# Click "Browse" to select a root directory, and point to the folder containing this example.  After selecting the directory, you should see the project name in the "Projects" list.  Click "Finish".
+
 
+
This project is configured to use a classpath variable, <tt>ECLIPSELINK_JLIB</tt>, to point to the required JAR files.  After the project is imported, you should define a variable called <tt>ECLIPSELINK_JLIB</tt> to point to your EclipseLink <tt>jlib</tt> directory.
+
 
+
==Running the JAXB Compiler==
+
 
+
The JAXB compiler can be run to generate JAXB-annotated Java classes from an XML Schema:
+
 
+
<pre>
+
<ECLIPSELINK_HOME>/eclipselink/bin/jaxb-compiler.sh <source-file.xsd> [-options]
+
<ECLIPSELINK_HOME>\eclipselink\bin\jaxb-compiler.cmd <source-file.xsd> [-options]
+
 
+
Options include:
+
  -d <dir>                    Specifies the output directory for generated files
+
  -p <pkg>                    Specifies the target package
+
  -classpath <arg>            Specifies where to find user class files
+
  -verbose                    Enable verbose output
+
  -quiet                      Suppress compiler output
+
  -version                    Display version information
+
 
+
For a complete list of compiler options:
+
  jaxb-compiler.sh -help
+
 
+
Example:
+
  jaxb-compiler.sh -d jaxb-compiler-output config/Customer.xsd
+
</pre>
+
 
+
In this example, the JAXB Compiler is run from the "<tt>run.jaxb.compiler</tt>" task in the ANT build file.
+
 
+
==Creating a JAXBContext using jaxb.properties==
+
 
+
The standard way to specify which JAXB implementation should be used is through a file called <tt>jaxb.properties</tt>, which contains a single property, <tt>javax.xml.bind.context.factory</tt>. This file must be available on the classpath in the corresponding package (in this example, "<tt>org.example.customer_example</tt>").  To specify that the EclipseLink JAXB implementation should be used, your <tt>jaxb.properties</tt> file should have the following content:
+
 
+
<pre>
+
javax.xml.bind.context.factory=org.eclipse.persistence.jaxb.JAXBContextFactory
+
</pre>
+
 
+
In our example, we create the JAXBContext as follows:
+
 
+
<pre>
+
JAXBContext jaxbContext = JAXBContext.newInstance("org.example.customer_example");
+
</pre>
+
 
+
An alternate way to create a new JAXBContext is to supply an array of Class objects.  Again, the <tt>jaxb.properties</tt> file must be available on the classpath in the corresponding package:
+
 
+
<pre>
+
Class[] classes = new Class[4];
+
classes[0] = org.example.customer_example.AddressType.class;
+
classes[1] = org.example.customer_example.ContactInfo.class;
+
classes[2] = org.example.customer_example.CustomerType.class;
+
classes[3] = org.example.customer_example.PhoneNumber.class;
+
JAXBContext jaxbContext = JAXBContext.newInstance(classes);
+
</pre>
+
 
+
==Unmarshalling the XML Document==
+
 
+
With a JAXBContext created, we can now unmarshal an XML document using the statically generated classes:
+
 
+
<pre>
+
File file = new File("Customer-data.xml");
+
Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();
+
StreamSource source = new StreamSource(file);
+
JAXBElement customerElement = unmarshaller.unmarshal(source, CustomerType.class);
+
CustomerType customer = (CustomerType) customerElement.getValue();
+
</pre>
+
 
+
==Modify the Objects==
+
 
+
Below are examples of manipulating the XML data using the JAXB-generated static classes. Note that there are JavaBean-type accessors on the static interfaces.
+
 
+
Modifying the ShippingAddress ZipCode:
+
 
+
<pre>
+
customer.getContactInfo().getShippingAddress().setZipCode("27601");
+
</pre>
+
 
+
Adding a new PhoneNumber:
+
 
+
<pre>
+
PhoneNumber homePhoneNumber  = new ObjectFactory().createPhoneNumber();
+
homePhoneNumber.setType("home");
+
homePhoneNumber.setValue("(613) 555-3333");
+
customer.getContactInfo().getPhoneNumber().add(homePhoneNumber);
+
</pre>
+
 
+
Note the use of the <tt>ObjectFactory</tt> class to create a new <tt>PhoneNumber</tt> object.  In addition to generating the model classes used in this example, the JAXB compiler also generates an <tt>ObjectFactory</tt> class that can be used to create any of the generated types.
+
 
+
Removing all "cell" PhoneNumbers:
+
 
+
<pre>
+
ArrayList phoneNumbersToRemove = new ArrayList();
+
List phoneNumbers = customer.getContactInfo().getPhoneNumber();
+
Iterator it = phoneNumbers.iterator();
+
while (it.hasNext()) {
+
    PhoneNumber phoneNumber = (PhoneNumber) it.next();
+
    if (phoneNumber.getType().equals("cell")) {
+
        phoneNumbersToRemove.add(phoneNumber);
+
    }
+
}
+
phoneNumbers.removeAll(phoneNumbersToRemove);
+
</pre>
+
 
+
==Marshalling the Objects to XML==
+
 
+
The following code segment demonstrates how to marshal Customer objects back to XML. In this example the stream we are saving to is System.out, so the XML text will be printed to the console.
+
 
+
<pre>
+
Marshaller marshaller = jaxbContext.createMarshaller();
+
marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);
+
marshaller.marshal(customerElement, System.out);
+
</pre>
+
 
+
==Using JAXBContext to Generate an XML Schema==
+
 
+
First you must create a class that extends javax.xml.bind.SchemaOutputResolver. 
+
 
+
<pre>
+
private class MySchemaOutputResolver extends SchemaOutputResolver {
+
 
+
    public Result createOutput(String namespaceURI, String suggestedFileName) throws IOException {
+
        File file = new File(suggestedFileName);
+
        StreamResult result = new StreamResult(file);
+
        result.setSystemId(file.toURI().toURL().toString());
+
        return result;
+
    }
+
 
+
}
+
</pre>
+
 
+
Then use an instance of this class with JAXBContext to capture the generated XML Schema.
+
 
+
<pre>
+
Class[] classes = new Class[4];
+
classes[0] = org.example.customer_example.AddressType.class;
+
classes[1] = org.example.customer_example.ContactInfo.class;
+
classes[2] = org.example.customer_example.CustomerType.class;
+
classes[3] = org.example.customer_example.PhoneNumber.class;
+
JAXBContext jaxbContext = JAXBContext.newInstance(classes);
+
 
+
SchemaOutputResolver sor = new MySchemaOutputResolver();
+
jaxbContext.generateSchema(sor);
+
</pre>
+
 
+
==Download==
+
 
+
Download the "Examples Zip" from the EclipseLink [http://www.eclipse.org/eclipselink/downloads/ Downloads] page.  Code for this example will be found in the <tt>org.eclipse.persistence.example.jaxb.zip</tt> file.
+

Latest revision as of 17:59, 1 February 2013

Using EclipseLink MOXy JAXB

Java Architecture for XML Binding (JSR 222) is the standard for XML Binding in Java. JAXB covers 100% of XML Schema concepts. Learn how to use MOXy as your JAXB provider.:



See the Developing JAXB Applications Using EclipseLink MOXy for complete information.