XMLBeans FAQ

General Community Questions

What are the different XMLBeans Mailing Lists?

Apache XMLBeans Mailing Lists

Who are the XMLBeans Committers?

Apache XMLBeans Committers

Where do I file a bug for XMLBeans?

XMLBeans uses Jira for bugtracking.

Getting Started

What is the latest version of XMLBeans?

Check the news page for the latest release. The 1.0.4 release is the latest stable maintenance release. You will need JDK 1.4 for the 2.3.0 and 1.0.4 release. For JDK 1.3 users, there is a version of the 1.0.4 release compatible with JDK 1.3. For 2.6.0 release JDK 6 is required.

Where can I download the latest release of XMLBeans?

http://xmlbeans.apache.org/sourceAndBinaries/

How do I get started coding with XMLBeans?

You can find lots of documentation on the XMLBeans' website. The Getting Started guide (http://xmlbeans.apache.org/docs/2.0.0/guide/conGettingStartedwithXMLBeans.html) is a good introduction to XMLBeans. Another excellent place to start is the tutorial.

How can I get the latest XMLBeans source code in svn?

XMLBeans Source Code Information. You will need a Subversion (svn) client.

Is the XMLBeans javadoc available online?

Yes, you can view the XMLBeans [2.5.0 Javadocs], 2.4.0 JavaDocs, 2.2.0 JavaDocs, 2.1.0 JavaDocs, 2.0.0 JavaDocs or the 1.0.4 JavaDocs.

What jars do I need on the classpath to use XMLBeans?

  • The obvious one is xbean.jar, which contains the XMLBeans code. scomp.cmd includes trailing periods after this on v1.0.4, which may cause problems under Windows XP.
  • For XMLBeans V1, this is all you need, but for XMLBeans 2, the JSR173 API jar is also required, since it contains classes that XMLBeans depends on. For XMLBeans 2.0.0, the name of the jar is jsr173_api.jar and for XMLBeans 2.1.0, it's jsr173_1.0_api.jar. In both cases, the jar comes with the XMLBeans binary distribution (for source distributions, the build process will download it and place it in the build/lib directory.
  • For JDK 1.4 users, as of XMLBeans 2.3.0 it has become necessary to also include xmlbeans-qname.jar
  • If XPath/XQuery support is required, the xbean_xpath.jar contains the XPath "glue" code and needs to be included on the classpath. Then, depending on the version of XMLBeans in use, the following are also required: jaxen.jar for XMLBeans V1 (only supports XPath, no XQuery), saxon8.jar for XMLBeans V2.0.0 and V2.1.0 (the only version supported is Saxon 8.1.1), saxon8.jar and saxon8-dom.jar for XMLBeans built from SVN head (this supports Saxon >= 8.6.1).

    XMLBeans version

    Saxon supported version

    v2.4.0

    Saxon-9.0.0.4

    v2.3.0

    Saxon-8.8

    v2.2.0

    SaxonB-8.6.1

    v2.1.0

    SaxonB-8.1.1

    v2.0.0

    SaxonB-8.1.1

    v1.x

    N/A




  • In addition to those, compiling Schemas using the scomp script requires tools.jar from the JDK and resolver.jar from Apache xml-commons (the latter one only in case support for OASIS XML catalogs for resolving external entities is needed).
  • We make another jar available, xmlpublic.jar, which contains the classes in the "org.apache.xmlbeans" package. If your code can be compiled with xmlpublic.jar on the classpath instead of the full xbean.jar, it means that your code uses only "public", supported APIs and will likely not need any modification if you need to upgrade to a newer XMLBeans version.

Running my code that used to work fails with "java.lang.NoClassDefFoundError: javax/xml/namespace/QName" after upgrading to 2.3.0

See What jars do I need on the classpath to use XMLBeans?. You need to add xmlbeans-qname.jar on you classpath.

The scomp program can't find javac and fails with java.io.IOException on Windows!

On Windows, some users have reported that the scomp program fails when trying to run javac on the generated java source. First, be sure you have a JDK installed. The JRE doesn't have the javac program so you won't be able to compile the generated java source. If you have both a JDK and a JRE installed, the JRE's java is being found before the JDK's java. Since scomp uses the 'java.home' property to find the javac program, but javac is only available in the JDK, finding javac will fail.

The solution is to move the JDK higher up on the PATH in the environment. An alternate solution is to set JAVA_HOME and edit the scomp script to run %JAVA_HOME%\bin\java instead of relying on the PATH. The error you would see looks like:

$ scomp -out myeasypo.jar easypo
Time to build schema type system: 1.969 seconds
Time to generate code: 0.313 seconds
'javac' is required on the path.
java.io.IOException: CreateProcess: c:\xmlbeans-1.0.2\schemas\javac @c:\DOCUME~1\alex\LOCALS~1\Temp\javac20992 error=2
null
java.io.IOException: CreateProcess: c:\xmlbeans-1.0.2\schemas\javac @c:\DOCUME~1\alex\LOCALS~1\Temp\javac20992 error=2
        at java.lang.Win32Process.create(Native Method)
        at java.lang.Win32Process.<init>(Unknown Source)
        at java.lang.Runtime.execInternal(Native Method)
        at java.lang.Runtime.exec(Unknown Source)
        at java.lang.Runtime.exec(Unknown Source)
        at java.lang.Runtime.exec(Unknown Source)
        at org.apache.xmlbeans.impl.tool.CodeGenUtil.externalCompile(CodeGenUtil.java:218)
        at org.apache.xmlbeans.impl.tool.SchemaCompiler.compile(SchemaCompiler.java:815)
        at org.apache.xmlbeans.impl.tool.SchemaCompiler.main(SchemaCompiler.java:264)
BUILD FAILED

If that doesn't fix the issue, try specifying relevant paths using Windows 8.3 names. This will get around issues with spaces in folder names.

The scomp program gives OutOfMemoryError when compiling my complex Schema!

The likely problem here is that because of the large number of source files that must be generated sometimes, the javac compilation step fails with insufficient memory. Here's how the problem manifests itself:

@ scomp myBigSchema.xsd
Time to build schema type system: 4.641 seconds
Time to generate code: 8.574 seconds


The system is out of resources.
Consult the following stack trace for details.
java.lang.OutOfMemoryError

If you get this, you need to give javac more memory. But since javac is launched as an external process, tweaking the scomp.bat script and upping the memory that scomp has available will have no effect. The solution is to use the "-mx" parameter to scomp, for example:

$ scomp -mx 1024M myBigSchema.xsd

The scomp fails with code too large error

This issue has been seen when running scomp xsds from www.niem.gov and www.it.ojp.gov/jxdm. When encountered in the schemas above is caused by a limitation of the JVM. It was discovered and noted by a JIRA issue.

http://issues.apache.org/jira/browse/XMLBEANS-307

The scomp tool does not currently have a solution for this.

How do I build XMLBeans?

Building XMLBeans. You will need Ant installed and JDK 1.4.

Can I view the XMLBeans source code online, without having svn on my machine?

Yes you can use the CVS/SVNView to browse or link to the XMLBeans source code. Link to XMLBeans main dev trunk

General XMLBeans Questions

What Java types are created for a particular schema type?

  • User Derived Schema Types When you compile XML schema, the resulting API is made up of two categories of types: built-in types that mirror those in the schema specification and others that are generated from user-derived schema types. This topic provides an overview of the Java types generated for user-derived types, describing the methods the Java types provide ... Java Types Generated from User-Derived Schema Types Built in Types Just as with types in XML schema, the XMLBeans types based on schema are arranged in a hierarchy. In general, the hierarchy of XMLBean types mirrors the hierarchy of the schema types themselves. XML schema types all inherit from xs:anyType (which is at the root of the hierarchy); XMLBeans types inherit from XmlObject ... XMLBeans Support for Built-In Schema Types

Can I change the default package names for the java classes generated from my schema?

You can create a file that ends in .xsdconfig to map targetnamespace to packagename. Put the .xsdconfig file in the same directory as the .xsd that you are compiling. Here is an example .xsdconfig:

<!-- An xsdconfig file must begin with a "config" element in the
        http://www.bea.com/2002/09/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://www.bea.com/2002/09/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>org.openuri.easypo.xsdconfig</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>

Notice that you can also map specific element/attribute names to java names.

(warning) Note: If schema doesn't include targenamespace then use

<xb:namespace uri="##any">
  <xb:package>org.openuri.easypo.xsdconfig</xb:package>
</xb:namespace>

to specify package names

(warning) Note: XMLBeans doesn’t support using two or more sets of java classes (in different packages) mapped to schema types/elements that have the same names and target namespaces, using all in the same class loader. Depending on the direction you are using for the java classes to schema types mapping, some features might not work correctly. This is because even though the package names for the java classes are different, the schema location for the schema metadata (.xsb files) is the same and contains the corresponding implementing java class, so the JVM will always pick up the first on the classpath. This can be avoided if multiple class loaders are used.

Is there a way to do a deep equals between two XmlObjects?

Dmitri.Colebatch posted some code that will do a deep equals. You can find the code attached to this post http://nagoya.apache.org/eyebrowse/ReadMsg?listName=xmlbeans-user@xml.apache.org&msgNo=75

Kevin Krouse also posted some code that will do a deep equals but had some limitations addressed by Dmitri above. You can find the code attached to this post http://nagoya.apache.org/eyebrowse/ReadMsg?listName=xmlbeans-user@xml.apache.org&msgNo=69.

How can I influence the namespace prefix used when saving/printing out my XML?

XMLBeans does not keep the prefixes when the original XML is loaded into the underlying XML store. If you need/want a specific prefix to be associated with a namespace you can use the setSaveSuggestedPrefixes(...) XmlOption.

Here is a code example from this helpful post, http://nagoya.apache.org/eyebrowse/ReadMsg?listName=xmlbeans-user@xml.apache.org&msgNo=33 :

HashMap suggestedPrefixes = new HashMap();
suggestedPrefixes.put("http://foo.com/", "foo");
XmlOptions opts = new XmlOptions();
opts.setSaveSuggestedPrefixes(suggestedPrefixes);

String output = document.xmlText(opts);

How can I instruct XMLBeans to add the xsi:schemaLocation attribute to my documents?

Here's how to do it. Assume that you have a document represented by the doc XmlObject (obtained via TestDocument.Factory.newInstance() or TestDocument.Factory.parse()) and you need an xsi:schemaLocation attribute on it, with value from the location String.

XmlCursor cursor = doc.newCursor();
if (cursor.toFirstChild())
{
  cursor.setAttributeText(new QName("http://www.w3.org/2001/XMLSchema-instance","schemaLocation"), location);
}

Is selectPath(...) on XmlObject and XmlCursor working?

XMLBeans has a built in engine for very simple XPath expressions. To use more advanced XPath or XQuery expressions in 2.x, you will need Saxon on the classpath. NOTE: See supported versions of Saxon.

To use more advanced XPath expressions in 1.0.4, the Jaxen engine can be used if xbean_xpath.jar is on the classpath. The xbean_xpath.jar is available in build\private\lib by running 'ant xbean_xpath.jar'.

Is execQuery(...) on XmlObject and XmlCursor working?

Yes! XMLBeans 2.1.0 uses Saxon as its XQuery engine so you will need it on your classpath. NOTE: See supported versions of Saxon.

For the 1.0.4 release, there is no open source XQuery integration. However, the XmlBeans included in BEA's Weblogic 8.x executes xqueries using a BEA's proprietary XQuery engine.

How do I modify the generated interfaces?

Use .xsdconfig files. Learn more here - XsdConfigFile.

How do I control CDATA?

Use CDATA options. Learn more here - CdataOptions.

Why am I getting XmlValueDisconnectedException when I try to change an XmlObject?

The cause is that the XmlObject is an orphan; i.e., it has become disassociated from the XML store. This can happen if you get a reference to an object (perhaps by fetching the first item in an array), delete the item from the tree (perhaps by calling the array remove method on element 0), and then try to invoke methods on that reference or any of its child elements. You cannot even invoke the toString() method on an orphaned object! If you need to keep a deleted object, make a copy before you delete it. For example:

       LineItem nl = p.getLineItemArray(0).copy();
       p.removeLineItem(0);

Schema Object Model Questions

Is there an introduction document on the XMLBeans Schema Type System?

This document is a good starting place to learn about programming against the XMLBeans Schema Type System.

How do I get the java name for a schema type?

  1. Once you've compiled things and got the JAR...
  2. Put the JAR on your classpath
  3. Use com.bea.xml.XmlBeans.getContextTypeLoader() to get the SchemaTypeLoader corresponding to your thread's context classloader.
  4. you can then use schemaTypeLoader.findType(QNameForType)
  5. and then type.getFullJavaName()
  6. see this post: http://nagoya.apache.org/eyebrowse/ReadMsg?listName=xmlbeans-user@xml.apache.org&msgNo=7 @fixme: seems to be a dead link

How do I get to SchemaAnnotation and SchemaIdentityConstraint on elements?

See below What is the difference between SchemaProperty and SchemaParticle?

What is the difference between SchemaProperty and SchemaParticle?

In a few words, the difference is that SchemaProperty represents a "flattened", simplified view of the contents of a type, while SchemaParticle represents a "complete" view including all of the model groups, as defined in Schema. To exemplify, consider the following Schema:

<xs:complexType name="T">

 . <xs:sequence>
  . <xs:element name="a" type="xs:string"/> <xs:choice>
   . <xs:element name="a" type="xs:string" maxOccurs="unbounded" tns:ann="annotation_a"/> <xs:element name="b" type="xs:string" maxOccurs="unbounded"/>
  </xs:choice>
 </xs:sequence>

</xs:complexType>

As you can see, this content mandates an <a> element in the instance, followed by either one or more <a>s or one or more <b>s (a (a+|b+)). The majority of applications would only be interested in what are the names and types of elements allowed inside the content for type "T" and would not care whether there are nested sequeces/choices and the like. As such, they can use SchemaType.getProperties() and they will see two entries, one for element "a" (built by collapsing the two occurences of an "a" element in the Schema) and one for element "b".

However, in some cases, more detail is needed about the content of the element. One example would be a Schema validator which needs to know if <a> and <b> are contained by a <choice> or a <sequence>. Another example would be code that is looking for annotations present in the Schema. As it can be seen in this example, there is an annotation on the second occurence of the "a" element, but not the first. Because the SchemaProperty API would collapse the two, it is not suitable for being used in this situation and SchemParticle has to be used instead to isolate each occurence of an "a" element.

This example code illustrate how to get the SchemaProperty'ies and SchemaParticle's on a type:

    SchemaType t = XmlBeans.getContextTypeLoader().findType(new QName("http://test", "T"));
    SchemaProperty[] schemaProperties = t.getProperties();
    for (int i = 0; i < schemaProperties.length; i++)
        printPropertyInfo(schemaProperties[i]);

    System.out.println();

    if (t.getContentType() == SchemaType.ELEMENT_CONTENT ||
            t.getContentType() == SchemaType.MIXED_CONTENT)
    {
        SchemaParticle topParticle = t.getContentModel();
        // topParticle is non-null if we checked the content
        navigateParticle(topParticle);
    }

    public static void navigateParticle(SchemaParticle p)
    {
        switch (p.getParticleType())
        {
        case SchemaParticle.ALL:
        case SchemaParticle.CHOICE:
        case SchemaParticle.SEQUENCE:
            // These are "container" particles, so iterate over their children
            SchemaParticle[] children = p.getParticleChildren();
            for (int i = 0; i < children.length; i++)
                navigateParticle(children[i]);
            break;
        case SchemaParticle.ELEMENT:
            printElementInfo((SchemaLocalElement) p);
            break;
        default:
            // There can also be "wildcards" corresponding to <xs:any> elements in the Schema
        }
    }

With helper methods

    public static void printPropertyInfo(SchemaProperty p)
    {
        System.out.println("Property name=\"" + p.getName() + "\", type=\"" + p.getType().getName()
            + "\", maxOccurs=\"" +
            (p.getMaxOccurs() != null ? p.getMaxOccurs().toString() : "unbounded") + "\"");
    }

    public static void printElementInfo(SchemaLocalElement e)
    {
        System.out.println("Element name=\"" + e.getName() + "\", type=\"" + e.getType().getName()
            + "\", maxOccurs=\"" +
            (e.getMaxOccurs() != null ? e.getMaxOccurs().toString() : "unbounded") + "\"");
        SchemaAnnotation annotation = e.getAnnotation();
        if (annotation != null)
        {
            SchemaAnnotation.Attribute[] att = annotation.getAttributes();
            if (att != null && att.length > 0)
                System.out.println("  Annotation: " + att[0].getName() + "=\"" +
                    att[0].getValue() + "\"");
        }
    }

this is the result of running this code:

Property name="a", type="{http://www.w3.org/2001/XMLSchema}string", maxOccurs="unbounded"
Property name="b", type="{http://www.w3.org/2001/XMLSchema}string", maxOccurs="unbounded"

Element name="a", type="{http://www.w3.org/2001/XMLSchema}string", maxOccurs="1"
Element name="a", type="{http://www.w3.org/2001/XMLSchema}string", maxOccurs="unbounded"
  Annotation: {http://test}ann="annotation_a"
Element name="b", type="{http://www.w3.org/2001/XMLSchema}string", maxOccurs="unbounded"

As you can see, using the SchemaParticle API we get two occurences for the "a" element and an annotation showing up only on the second of these occurences.

How do I use substitution groups?

See the Substitution Groups FAQ: SubstGroupsFaq

How do I compile multiple schema files with dependencies?

Schema files need to be compiled with its compiled dependencies on the classpath. For example, if s4.xsd and s3.xsd depends on s2.xsd which depends on s1.xsd, compile using the following:

scomp -out s1.jar s1.xsd
scomp -cp s1.jar -out s2.jar s2.xsd
scomp -cp s1.jar;s2.jar -out s3.jar s3.xsd s4.xsd

XmlCursor API

Is there documentation on navigating with XmlCursor?

This document, http://xmlbeans.apache.org/docs/2.0.0/guide/conNavigatingXMLwithCursors.html, discusses using XmlCursor to navigate a document.

How do I use Bookmarks to annotate XML?

This document, http://xmlbeans.apache.org/docs/2.0.0/guide/conUsingBookmarksToAnnotateXML.html, discusses using bookmarks to annotate xml.

  • No labels