48 Creating an XML Project

This chapter describes the various components that you must configure in order to create an XML project.

This chapter includes the following sections:

For information on how to create more than one type of TopLink projects, see Chapter 116, "Creating a Project".

48.1 Introduction to XML Project Creation

You can create a project using Oracle JDeveloper, TopLink Workbench, or Java code.

Oracle recommends using either Oracle JDeveloper or TopLink Workbench to create projects and generate deployment XML or Java source versions of the project for use at run time. For more information on how to create a project using TopLink Workbench, see Section 116.1.2, "How to Create a Project Using TopLink Workbench". For information on how to create a project using Java, see Section 116.1.3, "How to Create a Project Using Java".

You can use TopLink to create an XML project, if you have an XML schema (XSD) document, but no object model yet (see Section 48.2, "Creating an XML Project from an XML Schema"). If you have both XSD and object model classes, you can create an XML project using the procedure described in Section 116.1.2, "How to Create a Project Using TopLink Workbench".

For more information, see Chapter 47, "Introduction to XML Projects".

48.2 Creating an XML Project from an XML Schema

If you have an existing data model (XML schema document), but you do not have a corresponding object model (Java classes for domain objects), use this procedure to create your TopLink project and automatically generate the corresponding object model.

Note:

If you have both XSD and object model classes, you can create an XML project using the procedure described in Section 116.1.2, "How to Create a Project Using TopLink Workbench".

Using the TopLink JAXB compiler simplifies JAXB application development with TopLink by automatically generating both the required JAXB files and the TopLink files from your XML schema (XSD) document. Once generated, you can open the Oracle JDeveloper or TopLink Workbench project to fine-tune XML mappings without having to recompile your JAXB object model.

You can use the TopLink JAXB compiler from Oracle JDeveloper TopLink Editor, TopLink Workbench (see Section 48.2.1, "How to Create an XML Project from an XML Schema Using TopLink Workbench"), or from the command line (see Section 48.2.2, "How to Create an XML Project from an XML Schema Using the Command Line").

Note:

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

For more information, see the following:

48.2.1 How to Create an XML Project from an XML Schema Using TopLink Workbench

To create a new, mapped TopLink Workbench project from an XML schema using JAXB, use this procedure:

  1. From TopLink Workbench, select File > New > Project > From XML Schema (JAXB).

    Figure 48-1 Create TopLink Workbench Project using JAXB Dialog Box

    Description of Figure 48-1 follows
    Description of "Figure 48-1 Create TopLink Workbench Project using JAXB Dialog Box"

Use the following information to enter data in each field of this dialog box:

Field Description
From Use these fields to specify your existing JAXB information.
    Schema File Click Browse and select the fully qualified path to your XSD file.
    JAXB Customization File This in an optional setting. It can be used if you have a standard JAXB configuration file that you wish to use to override the default JAXB compiler behavior. The JAXB customization file contains binding declarations for customizing the default binding between an XSD component and its Java representation.
To Use these fields to specify the location and options of the TopLink Workbench project.
    Output Directory Click Browse and select the path to the directory into which generated files are written. All paths used in the project are relative to this directory.
        Output Source Directory Click Browse and select the path to the directory (relative to the Output Directory) into which generated interfaces, implementation classes, and deployment files are written. Default: directory named source in the specified output directory.
        Output Workbench Project Directory Click Browse and select the path to the directory (relative to the Output Directory) into which the TopLink Workbench project files are written. Default: directory named mw in the specified output directory.
    Package Name for Generated Interfaces The optional name of the package to which generated interfaces belong. This defines your context path. If it is not specified, a package name of jaxbderived.<schema name> is used where <schema name> is the name of the schema specified by the Schema File field.
    Package Name for Generated Implementation Classes The optional name of the package to which generated implementation classes belong. This defines your context path. If it is not specified, a package name of jaxbderived.<schema name> is used where <schema name> is the name of the schema specified by the Schema File field.

The TopLink JAXB compiler generates JAXB-specific files (see Section 47.1.1.2, "Working with JAXB-Specific Generated Files") and TopLink-specific files.

48.2.2 How to Create an XML Project from an XML Schema Using the Command Line

To create a new, mapped Oracle TopLink Workbench project from an XML schema using JAXB from the command line, use the tljaxb.cmd or tljaxb.sh file (located in the <TOPLINK_HOME>/bin directory) as follows:

  1. Using a text editor, edit the tljaxb.cmd or tljaxb.sh file to set proxy settings (if required).

    If you are using a schema that imports another schema by URL and you are operating behind a proxy, then you must uncomment the lines shown in Example 48-1 or Example 48-2 and edit them to set your proxy host (name or IP address) and port:

    Example 48-1 Proxy Settings in tljaxb.cmd

    @REM set JVM_ARGS=%JVM_ARGS% -DproxySet=true -Dhttp.proxyHost= -Dhttp.proxyPort=

    Example 48-2 Proxy Settings in tljaxb.sh

    # JVM_ARGS="${JVM_ARGS} -DproxySet=true -Dhttp.proxyHost= -Dhttp.proxyPort="

  2. Execute the tljaxb.cmd or tljaxb.sh file (located in the <TOPLINK_HOME>/bin directory).

    The TopLink JAXB compiler generates JAXB-specific files (see Section 47.1.1.2, "Working with JAXB-Specific Generated Files") and TopLink-specific files.

    Example 48-3 illustrates how to generate an object model from a schema using the Toplink JAXB compiler. Table 48-1 lists the compiler arguments.

    Example 48-3 Generating an Object Model from a Schema with tljaxb.cmd

    tljaxb.cmd -sourceDir ./app/src -generateWorkbench -workbenchDir ./app/mw  -schema purchaseOrder.xsd -targetPkg examples.ox.model.if -implClassPkg examples.ox.model.impl

    Table 48-1 TopLink JAXB Binding Compiler Arguments

    Argument Description Optional?

    -help

    Prints this usage information.

    Yes

    -version

    Prints the release version of the TopLink JAXB compiler.

    Yes

    -sourceDir

    The path to the directory into which generated interfaces, implementation classes, and deployment files are written.

    Default: directory named source in the specified output directory.

    Yes

    -generateWorkbench

    Generate a TopLink Workbench project and necessary project files. If omitted, only runtime information is generated.

    Yes

    -workbenchDir

    The path to the directory into which the TopLink Workbench project files are written. This argument requires the -generateWorkbench argument.

    Default: directory named mw in the specified output directory.

    Yes

    -schema

    The fully qualified path to your XSD file.

    No

    -targetPkg

    The name of the package to which both generated interfaces and classes belong. This defines your context path. To specify a different package for implementation classes, set the -implClassPkg argument.

    Default: a package name of jaxbderived.<schema name> where <schema name> is the name of the schema specified by the -schema argument.

    Yes

    -implClassPkg

    The name of the package to which generated implementation classes belong. If this option is set, interfaces belong to the package specified by the -targetPkg argument. This defines your context path.

    Yes

    -interface

    Generate only interfaces. This argument is optional.

    Default: generate both interfaces and implementation classes.

    Yes

    -verbose

    The interfaces and classes generated. This argument is optional.

    Default: not verbose.

    Yes

    -customize

    The fully qualified path and file name of a standard JAXB customization file that you can use to override default JAXB compiler behavior.

    Yes