Using XMLBeans in the IDE

Workshop includes XMLBeans, an open source technology for binding XML to Java objects. XMLBeans provides multiple ways to access bound XML, but within Workshop the principal means is by generating Java types by compiling WSDL and XSD (schema) files, then binding XML to the generated types.

This topic includes information on:

Compiling Schema for Java Types to Use in Projects

Enabling Automatic Java Type Generation with the XMLBeans Builder

Turning off Automatic Schema Compilation

Generating a JAR File that Contains Java Types Generated from Schema

Locating Generated Java Types

Guiding XMLBeans Type and Package Naming During Compilation

Supporting the Interface Extension Mechanism

Note: XMLBeans is one of the Apache open source technologies. For more information and documentation on XMLBeans, see the Apache XMLBeans web site.

Specifically, in Workshop you might find that XMLBeans are handy for the following:

Compiling Schemas for Java Types to Use in Projects

If you want to use types generated by XMLBeans from schema in your project, you can do so in one of two ways: with automatic schema compilation through the XMLBeans Builder or by creating a JAR file that contains the generated types.

Important: You should not use both of these techniques with the same schemas in the same project. If you do, you will end up with two sets of essentially the same generated types on your project's classpath. If you begin with one technique, be sure to "undo" the other before switching. For example, if you've added the XMLBeans Builder facet, be sure to remove the facet (or remove the schemas from the schema source path) before generating a types JAR. Conversely, you should remove a generated types JAR from your project's classpath before adding the XMLBeans Builder facet.

When you remove the XMLBeans Builder facet, the IDE removes Java types that the builder generated.

XMLBeans Builder

You can have the IDE automatically generate Java types from your WSDL and XSD files by using the XMLBeans Builder. In this way, as you make changes to the WSDL or schema, updated types are generated. (This facet replaces the functionality provided by the Schemas project type in WebLogic Workshop version 8.1.)

The builder is a project facet that:

  • Examines specified directories for WSDLs and schemas.
  • Generates Java types by compiling schema types described in the files.
  • Puts the generated types on your project classpath. For information about where the generated types go, see Locating Generated Java Types.
  • Note that you can create a JAR file from automatically generated types.

    Types JAR

    You can create a JAR file with the generated types, then put the JAR file on your project's classpath. You might prefer this option if you don't anticipate any changes to the WSDL or schema from which types are generated. By using a types JAR rather than the XMLBeans Builder, you can also avoid the overhead present when the IDE compiles schemas at build time. Note that if your WSDL or schema files change, you'll need to manually recreate the JAR file.

    Enabling Automatic Java Type Generation with the XMLBeans Builder

    You get automatic schema compilation by using the XMLBeans builder, a facet you can add to your project. The XMLBeans builder is an Eclipse incremental project builder (similar to the Java builder) that can be enabled on either WTP faceted projects (via the XMLBeans Builder facet) or on plain Java projects (by selecting the Enable XMLBeans Builder check box in the XMLBeans page of the project's properties.

    When you enable the XMLBeans Builder facet, the IDE creates a "schemas" directory in your project (you can rename the directory, add additional directories or specify inclusion/exclusion filters later) and adds this directory to a schema source compilation path. WSDL and XSD files you put into this directory will be automatically compiled (when your project is built) into Java types that the IDE puts on your project's classpath. You can change the schema compilation path as described in Setting the Schema Compilation Source Path. (See the note above for important information about the XMLBeans Builder.)

    For WTP faceted projects (WebLogic EJB, Dynamic Web and Utility), you can add the XMLBeans Builder in one of two ways:

    In either case, the user interface through which you add the facet is pretty much the same. The steps include:

    1. Adding the XMLBeans Builder facet.
    2. Setting generated file locations.
    3. Setting XMLBeans options.
    4. Setting the schema compilation source path.

    For plain Java projects, you can enable the XMLBeans builder via the XMLBeans page in the project properties dialog.

    Adding the XMLBeans Builder Facet

    Under Select Project Facets, you select the XMLBeans Builder facet by expanding the XMLBeans node, then selecting the XMLBeans Builder check box. (The following user interface is also used when you add the facet to an existing project.)

    For an introduction to project facets, see Setting Project Facets.

    The options include:

    XMLBeans Library (selected by default for all project types except EAR projects)

    XMLBeans Builder

    After you've selected the XMLBeans Builder facet, click Next.

    Selecting Builder Options

    Once you've selected the XMLBeans Builder facet and clicked Next, you'll find two tabs through which you can set properties related to Java type generation. These include user interface for setting the locations for source and binary files generated during schema compilation and for setting XMLBeans schema compilation options.

    Setting Generated File Locations

    The Generated File Locations tab provides a way for you to set the locations of JAVA and CLASS files generated from your WSDL or XSD files. (XMLBeans also generates other kinds of files, including XSB files, that it uses internally.) Typically, you'll want to leave these paths unchanged. (This user interface is also used when you add the facet to an existing project as well as in project properties for XMLBeans.)

    The generated src file root box contains the name of the directory that will contain Java source files generated by XMLBeans. These generated source files are compiled into the standard Java output folder for you project (such as build/classes) along with the other compiled results of your project. The default is ".xbean_src".

    The generated binary file root box contains the name of the directory that will contain other files generated by XMLBeans. This directory is added to the project classpath and is exported to dependent projects. The default for the binary file root directory is ".xbean_bin".

    Click the XMLBeans Options tab to set schema compilation options.

    Setting XMLBeans Options

    The XMLBeans Options tab provides a way for you to set options specific to schema compilation. Most of the options listed here are exposed by the open source XMLBeans schema compiler that the IDE uses, so you'll find them also documented in connection with the xmlbean Ant task at the Apache XMLBeans web site.

    After you add the builder, you can change these and other settings through the project properties dialog. The XMLBeans category of project properties includes tabs for setting the generated file locations and XMLBeans options you set when adding the builder. (This user interface is also used when you add the facet to an existing project as well as in project properties for XMLBeans.)

    These options are described in the following table. (Note that the semantics for some of the Ant task attributes differs slightly from the options in the IDE user interface.)

    XMLBeans Option Description Ant Task Attribute Counterpart
    Schema type system name Name of the schema type system (defaults to <projectname>TypeSystem) typesystemname
    Validate Schemas Select this to have your schemas validated during compilation.

    novdoc
    URI resolution Determines resolution of include/import declarations. None.
    Default XMLBeans resolution
    An EntityResolver is not provided and network URL downloading is disabled. Similar to "false" for the "download" attribute.
    Default XMLBeans resolution with network URL downloading
    Default XMLBeans resolution (in other words, no EntityResolver) but the network URL downloading flag is enabled. Similar to "true" for the "download" attribute.
    WTP resolution
    EntityResolver is provided that delegates to the WTP URIResolver (searches the XML Catalog and Internet cache). Similar to "false" for the "download" attribute.
    Java version for generated source Determines version compatibility of the generated Java source. javasource
    Enforce unique particle attribution rule Determines if the unique particle attribution rule is enforced (in other words, no overlapping particles both in choice/all or validating adjacent items). noupa
    Enforce particle valid restriction rule Determines if the particle valid restriction rule is enforced (in other words, whether one particle is an allowed restriction of another particle). nopvr
    Skip annotations Determines if schema "<annotation>" elements should be skipped. noann
    Include project classpath entries in classpath for XMLBeans compilation If true, compilation and xsdconfig processing will be performed with a classpath that includes the entries from the project classpath. This means that pre-compiled schema types on the classpath will be visible during compilation and Java classes on the classpath will be visible for interface extension processing. No direct counterpart.
    Namspaces in which duplicate schema types will be ignored List of one or more namespaces in which duplicate definitions are to be ignored. ignoreDuplicatesInNamespaces

    Setting the Schema Compilation Source Path

    When compiling WSDL and XSD files into Java types, the IDE looks at directories on the schema source path for files to compile. This path is automatically set when you add the XMLBeans Builder facet, but you can make changes to it with the Source Paths tab, as shown in the following illustration. This is similar to a source path for JAVA file compilation. In fact, you can specify that those JAVA source paths themselves be used for locating WSDL and XSD files to compile.

    Turning off Automatic Schema Compilation

    If you don't want automatic schema compilation, you can disable the XMLBean Builder facet. This procedure for doing so differs between WTP faceted project and Java projects.

     

    Generating a JAR File that Contains Java Types Generated from Schema

    If you want a JAR file that contains Java types generated from your schema, you can get it in one of two ways, as described below. Note that these produce slightly different results, so you should keep in mind what you'll be using the JAR file for.

    Creating a JAR File from Manually Generated Java Types

    You can use an IDE menu command to generate a JAR file that contains the types when you want it. This is known as generating a types JAR. You might find this useful if you aren't using automatic compilation of Java types from schema. (Contrast this with the procedure for getting a JAR file from types that were generating through automatic schema compilation.)

    Note: Be sure to see the note above for important information about types JARs.

    1. In the Project Explorer, right-click the WSDL or XSD file whose generated Java types you want packaged into a JAR file, then click Web Services > Generate Types JAR File.
    2. In the Types JAR File Generation Wizard dialog, in the Type Family box, ensure that Apache XmlBeans is selected, then click Next.
    3. Select the parent folder for the JAR file you are creating, enter the JAR file's name in the File name box, then click Finish.

    Creating a JAR from Automatically Generated Types

    By using the following steps you can create a JAR file that includes generated Java types as well as the other XMLBeans-related artifacts you might need, including XSDCONFIG files. A JAR file created this way gets you the output of the XMLBeans Builder.

    1. Right-click the project and select Export.
    2. In the Export dialog, under Select an export destination, click JAR file, then click Next.
    3. In the JAR Export dialog, under Select the resources to export, clear all but the .xbean_bin and build directories (make certain to deselect the various Eclipse metadata files under the project root). Note that these are the files that are used to build JARs for deployment.
    4. Ensure that Export generated class files and resources is not selected.
    5. Ensure that Export all output folders for checked projects and Export .java source files and resources are selected.
    6. Click the Browse button to pick the name and location for your generated JAR.
    7. Select Add directory entries (to be consistent with the JAR files created by the xmlbeans Ant task).
    8. Click Finish.

    Locating Generated Java Types

    Depending on how your project is set up to compile schema, the resulting Java types might not be easily discoverable in the IDE. For example, if you use the XMLBeans Builder facet to enable automatic compilation, the generated Java types are put into the generated file locations — which, by default, aren't visible in the Package Explorer or Project Explorer views.

    XMLBeans Builder output — Use the IDE's Navigator view to locate Java source and binary files generated during schema compilation. The following illustration shows the default generated file paths as displayed in the Navigator view. Note, too, that compiled CLASS files are put into the build/classes directory with other classes resulting from your project's code.

    Types JAR output — Use the Package Explorer or Project Explorer views to browse the JAR's contents, just as you would with another JAR file. The following illustration shows how this might look.

    Guiding XMLBeans Type and Package Naming During Compilation

    When compiling a WSDL or schema into Java types, the XMLBeans builder will by default try to use your schema type names and URIs when naming generated Java types and Java packages, respectively. You can customize the names of resulting Java types and packages by using an XSDCONFIG file that maps a schema type name or namespace URI to a Java type name or package name that you specify. You put this file in the directory that holds the WSDL and XSD files you're compiling.

    Coercing type naming in this way does not change the names for the underlying schema types — it merely determines the names for corresponding generated Java types. Selecting your own names for compiled types can be useful when you want to control type name length, locale, capitalization, and so on.

    Note: Due to a Windows operating system limitation on file path lengths (256 characters), you might have trouble compiling schemas in which the generated types are nested in a very deep package hierarchy. This may result in an error message stating that a particular class couldn't be found. To work around this limiitation, try using your XSDCONFIG file to guide the naming of generated packages so that the hierarchy is less deep, package names are shorter, and so on.

    To Guide Type Naming During Compilation

    1. Determine the names you want for each of the named types in your schema, including elements and attributes.

      For example, you might decide that a PURCH_ORDER schema element and CUST schema type should be called PurchaseOrder and Customer as Java types.

    2. Add a new XSDCONFIG file to your project.
      1. Right-click the directory that contains the WSDL and XSD files that will be compiled to generated Java types, then click New > File.

        This should be a directory that is on the schema compilation source path — by default, the "schemas" directory.

      2. In the New File dialog, in the File name box, enter the name of your XSDCONFIG file, giving the file a name with an XSDCONFIG extension, then click Finish.
      3. In the empty window that is displayed, enter the content of your XSDCONFIG file. For example, you might start with the following example, replacing the <namespace>, <package>, and <qname> elements with values that make sense for your needs.
        <!-- An XSDCONFIG file must have a root "config" element in the
            http://xml.apache.org/xmlbeans/2004/02/xbean/config namespace. Also, be sure
            to declare any namespaces used to qualify types in your schema (here,
            the namespace corresponding to the pol prefix). -->
        <xb:config xmlns:pol="http://openuri.org/easypoLocal"
            xmlns:xb="http://xml.apache.org/xmlbeans/2004/02/xbean/config">
         
            <!-- Use the "namespace" element to map a namespace to the Java package
                name that should be generated. -->
            <xb:namespace uri="http://openuri.org/easypoLocal">
                <xb:package>com.myco.potracker</xb:package>
            </xb:namespace>
         
            <!-- Use the "qname" element to map schema type names to generated
                Java type names. In these examples, the name attribute's value is the
                XML element name; the javaname attribute's value is the Java type
                that should be generated. -->
            <xb:qname name="pol:CUST" javaname="Customer"/>
            <xb:qname name="pol:PURCH_ORDER" javaname="PurchaseOrder"/>
        </xb:config>

    When you build the schema project, the compiler will use the XSDCONFIG file to define names for generated Java types.

    Supporting the Interface Extension Mechanism

    XMLBeans provides a mechanism through which interfaces generated during schema compilation will extend interfaces in your project. Likewise, generated implementation classes will implement extended interface methods via handler classes. You specify the interfaces to extend and the handler classes to use through an XSDCONFIG file. For more information on the interface extension mechanism, see the XMLBeans wiki.

    If you're using the interface extension mechanism, the IDE must of course know where your interaces and handlers classes are. You can take one of the following approaches:


    Still need help? Post a question on the Workshop newsgroup.