XML Projects

Use an XML project for nontransactional, nonpersistent (in-memory) conversions between Java objects and XML documents using JAXB (see "TopLink Support for Java Architecture for XML Binding (JAXB)" and "JAXB Validation"). TopLink Workbench provides complete support for creating XML projects.

The TopLink runtime performs XML data conversion based on one or more XML schemas. In an XML project, TopLink Workbench directly references schemas in the deployment XML, and exports mappings configured with respect to the schemas you specify. For information on how to use TopLink Workbench with XML schemas, see "Working With XML Schemas". For information on how TopLink supports XML namespaces, see "XML Namespaces".

Table 20-6 describes the components of an XML project.

Table 20-6 XML Project Components

Component	Supported Types
Data Source	None
Descriptors	For more information, see "XML Descriptors".
Mappings	For more information, see the following: Part X, "Mappings" Part XIV, "XML Mappings"

Component

Supported Types

Data Source

None

Descriptors

For more information, see "XML Descriptors".

Mappings

For more information, see the following:

In an XML project, you do not use TopLink queries and expressions.

TopLink Support for Java Architecture for XML Binding (JAXB)

JAXB provides a standard Java object-to-XML API. For more information, see http://java.sun.com/xml/jaxb/index.html.

TopLink provides an extra layer of functions on top of JAXB. It allows for the creation and subsequent manipulation of mappings (in the form of a TopLink Workbench project) from an existing object model, without requiring the recompilation of the JAXB object model.

An essential component of this function is the TopLink JAXB compiler. Using the TopLink JAXB compiler, you can generate both a TopLink XML project and JAXB-compliant object model classes from your XML schema.

The TopLink JAXB compiler simplifies JAXB application development with TopLink by automatically generating (see "Creating an XML Project From an XML Schema") both the required JAXB files (see "Understanding JAXB-Specific Generated Files") and the TopLink files ("Understanding TopLink-Specific Generated Files") from your XML schema (XSD) document.

For more information on using the JAXB and TopLink-specific files that the TopLink JAXB compiler generates, see "Using TopLink JAXB Compiler Generated Files at Run Time".

Understanding JAXB-Specific Generated Files

The TopLink JAXB compiler generates the following JAXB-specific files from your XSD:

Content and Element Interfaces
Implementation Classes
Object Factory Class
JAXB Properties File

The JAXB runtime uses these files as specified by the JAXB specification.

All JAXB-specific files are generated in the output directory you define, and in the subdirectories implied by the target package name you define. For more information about TopLink JAXB binding compiler options, see "Creating an XML Project From an XML Schema".

Before you compile your generated classes, be sure to configure your integrated development environment (IDE) classpath to include <ORACLE_HOME>\lib\xml.jar. For example, see Chapter 4, "Using an Integrated Development Environment".

Content and Element Interfaces

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

Implementation Classes

All implementation classes are named according to the content, element, or implementation name attribute defined in the XSD and a suffix of Impl.

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.

Object Factory Class

The ObjectFactory class provides an instance factory method for each content and element interface. For example, given an element interface ItemsImpl, there would be an instance factory method in the ObjectFactory class with the following signature:

public ItemsImpl createItemsImpl() throws javax.xml.bind.JAXBException

The ObjectFactory class also provides a dynamic instance factory allocator with the following signature:

public static Object newInstance(Class javaContentInterface)
    throws javax.xml.bind.JAXBException

JAXB Properties File

The JAXB properties file is named jaxb.properties and it contains a single entry that defines the javax.xml.bind.context.factory property with a value equal to the fully qualified class name of the TopLink implementation of JAXBContext:

javax.xml.bind.context.factory=oracle.toplink.ox.jaxb.JAXBContextFactory

Understanding TopLink-Specific Generated Files

The TopLink JAXB compiler generates the following TopLink-specific files from your XSD:

TopLink Sessions XML File
TopLink Project XML File
TopLink Workbench Project
Typesafe Enumeration Converter Amendment Method DescriptorAfterLoads Class

You use these files to customize the TopLink metadata that corresponds to the generated JAXB-specific objects.

All TopLink-specific files are generated in a subdirectory, named toplink, of the output directory you specify (see "Creating an XML Project From an XML Schema").

The toplink subdirectory is organized as Figure 20-1 illustrates.

Figure 20-1 JAXB Binding Compiler Generated Files and Directories

Description of "Figure 20-1 JAXB Binding Compiler Generated Files and Directories"

TopLink Sessions XML File

In the generated sessions.xml file, the name element is the name of the context path and the project-xml element is the name of the generated project XML file.

Example 20-1 shows a typical sessions.xml file where the context path is examples.ox.model.

Example 20-1 Typical Generated sessions.xml File

<?xml version="1.0" encoding="US-ASCII"?>
<toplink-sessions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="file://xsd/sessions_10_0_3.xsd" version="0">
    <session xsi:type="database-session">
        <name>customer_example</name>
        <primary-project xsi:type="xml">purchaseOrder.xml</primary-project>
        <login xsi:type="xml-login">
            <platform-class>oracle.toplink.ox.platform.SAXPlatform</platform-class>
        </login>
    </session>
</toplink-sessions>

As in any TopLink project, the TopLink session is your primary facade to the TopLink XML API (see "Using TopLink JAXB Compiler Generated Files at Run Time").

TopLink Project XML File

The project XML file is named the same as the XSD, but with a file extension of xml. In Figure 20-1, the name of the generated project XML file is purchaseOrder.xml.

The project XML file contains a descriptor and associated mappings for each content, element, and implementation class.

TopLink Workbench Project

The TopLink Workbench project is written to a subdirectory as Figure 20-1 illustrates. This subdirectory contains a TopLink Workbench project file named with the same name as the XSD, but with a file extension of mwp and the required descriptor and class subdirectories. In Figure 20-1, the TopLink Workbench project is named purchaseOrder.mwp.

Optionally, you can use this TopLink Workbench project to customize the generated descriptors and mappings and reexport the project XML file.

Typesafe Enumeration Converter Amendment Method DescriptorAfterLoads Class

The TopLink JAXB compiler will generate a single class called DescriptorAfterLoads if any implementation class contains a mapping to a type safe enumeration (see "Mappings and JAXB Typesafe Enumerations").

The TopLink JAXB compiler will update this DescriptorAfterLoads class with a descriptor amendment method called amend<ImplementationClassName> for each implementation class that contains a mapping to a typesafe enumeration. The amendment method sets an instance of JAXBTypesafeEnumConverter on each mapping that maps to a typesafe enumeration in that implementation class.

The TopLink Workbench project that the TopLink JAXB compiler creates (see "TopLink Workbench Project") configures the implementation class descriptor with this amendment method. You can open the generated TopLink Workbench project and regenerate deployment XML without losing support for this feature.

Using TopLink JAXB Compiler Generated Files at Run Time

At run time, you can access the TopLink JAXB compiler-generated files:

Using the TopLink XML Context
Using the JAXB Context

Using the TopLink XML Context

TopLink provides an XMLContext class with which you can create instances of TopLink XMLMarshaller, XMLUnmarshaller, 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. The same is true of instances of XMLUnmarshaller and XMLValidator.

By using the XMLContext, you can use TopLink XML in multithreaded architectures, such as the binding layer for Web services.

To use the TopLink XMLContext, do the following:

Configure your application classpath to include your domain object class files (see "Understanding JAXB-Specific Generated Files") and the TopLink runtime.
Acquire the session manager (see "Acquiring the Session Manager").
Use the session manager to acquire your XML session using the sessions.xml file you generated with the TopLink JAXB compiler (see "Acquiring a Session from the Session Manager").
Get the XML project instance from the session:
```
Project myProject = session.getProject();
```
Create a TopLink XML context instance with the project:
```
XMLContext context = new XMLContext(myProject);
```

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

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

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

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

Using the JAXB Context

You can create an instance of JAXBContext using the target package name you selected for your generated files (see "Understanding JAXB-Specific Generated Files") as the context path, as Example 20-2 shows. This example assumes that you configure your application classpath to include your domain object class files.

The JAXBContext is thread-safe.

Example 20-2 Using the Context Path

JAXBContext jaxbContext = JAXBContext.newInstance("examples.ox.model");
Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();
PurchaseOrder purchaseOrder = (PurchaseOrder)
    unmarshaller.unmarshal(new File("purchaseOrder.xml"));

JAXB Validation

TopLink can validate both complete object trees and subtrees against the XML schema that was used to generate the implementation classes. In addition, TopLink will validate both root objects (objects that correspond to the root element of the XML document) and nonroot objects against the schema used to generate the object's implementation class.

When validating an object tree, TopLink performs the following checks (in order):

Check that element appears in the document at the specified location.
If maxOccurs or minOccurs is specified, check number of elements.
If type is specified, check that element value satisfies the type constraints.
If a fixed value is specified, check that the element value matches it.
If restrictions (length, patterns, enumerations, and so on) are specified, check that the element value satisfies it.
If an ID type is specified during a validateRoot operation, check that the ID value is unique in the document.
If an IDREF type is specified during a validateRoot operation, check that the ID referenced exists in the document.

If validation errors are encountered, TopLink stops validating the object tree and creates a ValidationEvent object, according to the JAXB specification. If an error occurs in a subobject, TopLink will not validate further down that object's subtree.

For more information on using TopLink XML to perform validation, see "Using TopLink JAXB Compiler Generated Files at Run Time".

For additional information on JAXB and validation, refer to the JAXB specification at http://java.sun.com/xml/jaxb/.