47 Introduction to XML Projects

47.1.1.2.1 Implementation Classes

All implementation classes are named according to the content, element, or implementation name attribute defined in the XSD.

The generated implementation classes are simple domain classes, with private attributes for each JAXB property, and public get and set methods that return or set attribute values.

47.1.1.3.1 How to Use TopLink XMLContext

TopLink provides an oracle.toplink.ox.XMLContext class using which you can create instances of TopLink XMLMarshaller, XMLUnmarshaller, XMLBinder (see Section 47.1.1.3.3, "How to Use TopLink XMLBinder"), and XMLValidator.

The XMLContext is thread-safe. For example, if multiple threads accessing the same XMLContext object request an XMLMarshaller, each will receive their own instance of XMLMarshaller, so any state that the XMLMarshaller maintains will be unique to that process. By using the XMLContext, you can use TopLink XML in multithreaded architectures, such as the binding layer for Web services.

Create the XMLContext using its constructor method and by passing in the session name defined in the sessions.xml file, as the following example shows:

XMLContext context = new XMLContext("mysession");

You can also create the XMLContext from multiple sessions using a colon separated list of session names, as the following example shows:

XMLContext context = new XMLContext("session1:session2:session3");

Use the XMLContext to create a TopLink XMLMarshaller, XMLUnmarshaller, XMLBinder, and XMLValidator, as follows:

XMLMarshaller marshaller = context.createMarshaller();
marshaller.marshal(myObject, outputStream);
marshaller.setFormattedOutput(true);

XMLUnmarshaller unmarshaller = context.createUnmarshaller();
Employee emp = (Employee)unmarshaller.unmarshal(new File("employee.xml"));

XMLBinder binder = context.createBinder();
Address add = (Address)binder.unmarshal(myElement);

XMLValidator validator = context.createValidator();
boolean isValid = validator.validate(emp);

Using the XMLContext getDocumentPreservationPolicy method, you can retrieve this context's document preservation policy in a form of the DocumentPreservationPolicy object. This object's API lets you specify the position of newly added to the node elements, as well as disable the addition of new elements.

47.1.1.3.2 How to Use Marshal and Unmarshall Events

You can provide TopLink XMLMarshaller and XMLUnmarshaller with additional functionality at run time by registering them with a listener to handle specific event callbacks. This allows for extra processing on a business object either immediately before, or immediately after an object is written to or read from XML.

There are two types of event callbacks that you can handle in two different ways:

1. To handle listener-based callbacks, set an event handler on an instance of XMLMarshaller or XMLUnmarshaller that implements a required interface, such as XMLMarshalListener or XMLUnmarshalListener. The events are triggered on the marshaller or unmarshaller's listener for any classes being marshalled or unmarshalled.

2. To handle class-specific callbacks, you need to provide the required callback methods on your business objects.

Example 47-1 shows how to create your custom event listeners.

public class EmployeeMarshalListener implements XMLMarshalListener {

    public void beforeMarshal(Object target) {
        // do something
    }

    public void afterMarshal(Object target) {
        // do something
    }
)


public class EmployeeUnmarshalListener implements XMLUnmarshalListener {

    public void beforeUnmarshal(Object target, Object parent) {
        // do something
    }

    public void afterUnmarshal(Object target, Object parent) {
        // do something
    }
)

Example 47-2 and Example 47-3 show how to use the listeners in your application.

...
XMLMarshaller marshaller = context.createMarshaller();
marshaller.setMarshalListener(new EmployeeMarshalListener());
marshaller.marshal(myObject, System.out);
...

...
XMLUnmarshaller unmarshaller = context.createUnmarshaller();
unmarshaller.setUnmarshalListener(new EmployeeUnmarshalListener());
Object myObject = unmarshaller.unmarshal(myFile);
...

47.1.1.3.3 How to Use TopLink XMLBinder

XMLBinder is a run-time class that allows you to preserve a document that you have unmarshalled, as well as to resynchronize that document with the unmarshalled objects at any time.

When the XMLBinder unmarshalls XML nodes into mapping objects, and then performs an update operation, it preserves not only the order of elements, but also the comments from an original XML document using the cached value. This way, both the returned node and the cached node are identical and reflect the preserved document. When adding new elements, TopLink XMLBinder places them at the correct location (relative to other mapped content) in the node.

When unmarshalling a document that contains only unmapped content, setting some values and then marshalling, the XMLBinder adds new elements before existing unmapped data, such as comments and processing instructions.

Example 47-4 demonstrates how you can unmarshall a document using an instance of an XMLBinder.

XMLContext conext = new XMLContext(myProject);
XMLBinder binder = context.createBinder();
Employee emp = (Employee) binder.unmarshal(myDocument);

In the preceding example, emp is the root object that was unmarshalled from the provided document. The binder maintains references to the original XML document as well as objects generated during the unmarshall operation.

Example 47-5 demonstrates how you can make changes to the object (Employee) and update the XML document using an instance of an XMLBinder.

...
emp.setPhoneNumber("123-4567");
binder.updateXML(emp);

In the preceding example, the updateXML method will update the cached node in the binder. Note that the cached node preserves the document, including comments, as the following example shows:

<employee>
   <!--comment1 -->
      <name>John Smith </name>
      <phone-number>123-4567</phone-number>
   <!--comment2 -->
</employee>

Example 47-6 demonstrates how you can obtain an associated node for a subobject (Address) of the Employee using an instance of an XMLBinder.

...
Address addr = emp.getAddress();
Node addressNode = binder.getXMLNode(addr);

In the preceding example, the returned node (addressNode) is the XML node in the original XML document that was used to build this employee's Address object.

Example 47-7 demonstrates how you can make changes to an XML node and update objects (Address) of the Employee using an instance of an XMLBinder.

...
addressNode.setAttribute("apt-no", "1527");
Address updatedAddressNode = binder.updateObject(addressNode);

In the preceding example, the address returned from the binder operation is the original Address object created during the unmarshall operation, but now it contains the updated apartment number information from the XML document.

47.1.1.3.4 How to Use JAXBContext

You can create an instance of JAXBContext from a collection of classes that are to be bound to XML. This will generate a TopLink project from the classes dynamically at run time.

Using the instance of JAXBContext you can obtain Marshaller and Unmarshaller instances to operate on those classes, as Example 47-8 demonstrates. Note that this example assumes that you configure your application classpath to include your domain object class files.

Class[] classes = {Employee.class, Address.class, Department.class};
JAXBContext jaxbContext = JAXBContext.newInstance(classes);
Marshaller marshaller = jaxbContext.createMarshaller();
marshaller.marshal(myEmployee, myOutput);

47.1.1.3.5 How to Use JAXBElement

TopLink lets you marshal to and unmarshall from JAXBElement types. The javax.xml.bind.JAXBElement class provides access to the following basic properties of an XML element:

• its qualified name, which is composed of {target namespace} and {name}

• its value, which is an instance of the Java class binding of its {type definition}

• whether or not the element's content is {nillable}

TopLink supports the following JAXB element marshal API defined in the Marshaller:

• marshal(java.lang.Object jaxbElement, java.io.Writer writer)

• marshal(java.lang.Object jaxbElement,

                      java.io.OutputStream os)

• marshal(java.lang.Object jaxbElement,

                       org.xml.sax.ContentHandler)

• marshal(java.lang.Object jaxbElement,

                       javax.xml.transform.Result)

• marshal(java.lang.Object jaxbElement, org.w3c.dom.Node)

• marshal(java.lang.Object jaxbElement,

                       javax.xml.stream.XMLStreamWriter writer)

TopLink provides implementation of the following JAXB element unmarshall API defined in the Unarshaller:

• <T> JAXBElement<T> unmarshal(

             org.w3c.dom.Node node, Class<T> declaredType)

• <T> JAXBElement<T> unmarshal(

             javax.xml.transform.Source source,

             Class<T> declaredType)

• <T> JAXBElement<T> unmarshal(

             javax.xml.stream.XMLStreamReader streamReader,

             Class<T> declaredType)

• <T> JAXBElement<T> unmarshal(

             javax.xml.stream.XMLEventReader eventReader,

             Class<T> declaredType)