Differences between revisions 341 and 342
Revision 341 as of 2012-02-07 17:11:36
Size: 26250
Editor: fx
Comment: remove sp@m
Revision 342 as of 2012-07-18 22:18:55
Size: 26234
Editor: fx
Comment: Added comment for latest release question.
Deletions are marked like this. Additions are marked like this.
Line 4: Line 4:
Line 6: Line 5:
Line 8: Line 6:
  * [[#mailingLists|What are the different XMLBeans Mailing Lists?]]
   * [[#committers|Who are the XMLBeans Committers?]]
   * [[#fileBug|Where do I file a bug for XMLBeans?]]
  * [[#mailingLists|What are the different XMLBeans Mailing Lists?]]
  * [[#committers|Who are the XMLBeans Committers?]]
  * [[#fileBug|Where do I file a bug for XMLBeans?]]
Line 13: Line 11:
  * [[#downloadBinary|Where can I download the latest release of XMLBeans?]]
   * [[#latestVersion|What is the latest version of XMLBeans?]]
   * [[#gettingStartedDoc|How do I get started coding with XMLBeans?]]
   * [[#xmlbeansSource|How can I get the latest XMLBeans source code in svn?]]
   * [[#buildingXMLBeans|How do I build XMLBeans from source?]]
   * [[#viewXMLBeansOnline|Can I view the XMLBeans Source Code online, without having svn on my machine?]]
   * [[#viewJavaDoc|Is the XMLBeans javadoc available online?]]
   * [[#whatJars|What jars do I need on the classpath to use XMLBeans?]] 
  * [[#qname|Running my code that used to work fails with "java.lang.NoClassDefFoundError: javax/xml/namespace/QName" after upgrading to 2.3.0]]
   * [[#scompFindingJavac|The scomp program can't find javac and fails with java.io.IOException on Windows!]]
   * [[#scompOutOfMemory|The scomp program gives OutOfMemoryError when compiling my complex Schema!]]
   * [[#codeTooLarge|The scomp fails with code too large error!]]
  * [[#downloadBinary|Where can I download the latest release of XMLBeans?]]
  * [[#latestVersion|What is the latest version of XMLBeans?]]
  * [[#gettingStartedDoc|How do I get started coding with XMLBeans?]]
  * [[#xmlbeansSource|How can I get the latest XMLBeans source code in svn?]]
  * [[#buildingXMLBeans|How do I build XMLBeans from source?]]
  * [[#viewXMLBeansOnline|Can I view the XMLBeans Source Code online, without having svn on my machine?]]
  * [[#viewJavaDoc|Is the XMLBeans javadoc available online?]]
  * [[#whatJars|What jars do I need on the classpath to use XMLBeans?]]
  * [[#qname|Running my code that used to work fails with "java.lang.NoClassDefFoundError: javax/xml/namespace/QName" after upgrading to 2.3.0]]
  * [[#scompFindingJavac|The scomp program can't find javac and fails with java.io.IOException on Windows!]]
  * [[#scompOutOfMemory|The scomp program gives OutOfMemoryError when compiling my complex Schema!]]
  * [[#codeTooLarge|The scomp fails with code too large error!]]
Line 27: Line 25:
  * [[#PCDATComplexType|How can I write the PCDATA in Element which is complexType?]]
   * [[#javaType4SchemaTypes|What Java types are created for a particular schema type?]]
   * [[#configPackageName|Can I change the default package names for the java classes generated from my schema?]]
  * [[#deepEquals|Is there a way to do a ''deep equals'' between two Xmlobjects?]]
  * [[#suggestedPrefixes|How can I influence the namespace prefix used when saving/printing out my XML?]]
  * [[#xsiSchemaLocation|How can I instruct XMLBeans to add the xsi:schemaLocation attribute to my documents?]]
  * [[#selectPath|Is selectPath(...) on XmlObject and XmlCursor working?]]
   * [[#execQuery|Is execQuery(...) on XmlObject and XmlCursor working?]]
   * [[#xsdConfig|How do I modify the generated interfaces?]]
  * [[#cdataOptions|How do I control CDATA?]]
    
  * [[#PCDATComplexType|How can I write the PCDATA in Element which is complexType?]]
  * [[#javaType4SchemaTypes|What Java types are created for a particular schema type?]]
  * [[#configPackageName|Can I change the default package names for the java classes generated from my schema?]]
  * [[#deepEquals|Is there a way to do a ''deep equals'' between two Xmlobjects?]]
  * [[#suggestedPrefixes|How can I influence the namespace prefix used when saving/printing out my XML?]]
  * [[#xsiSchemaLocation|How can I instruct XMLBeans to add the xsi:schemaLocation attribute to my documents?]]
  * [[#selectPath|Is selectPath(...) on XmlObject and XmlCursor working?]]
  * [[#execQuery|Is execQuery(...) on XmlObject and XmlCursor working?]]
  * [[#xsdConfig|How do I modify the generated interfaces?]]
  * [[#cdataOptions|How do I control CDATA?]]
Line 39: Line 37:
  * [[#introToSTS|Is there an introduction document on the XMLBeans Schema Type System?]]
   * [[#schemaType2Javaname|How do I get the java name for a schema type?]] 
  * [[#schemaAnnotation|How do I get to SchemaAnnotation and SchemaIdentityConstraint on elements?]]
   * [[#schemaPropertySchemaParticle|What is the difference between SchemaProperty and SchemaParticle?]]
   * [[#substGroups|How do I use substitution groups?]]
   * [[#schemaDependencies|How do I compile multiple schema files with dependencies?]]
  * [[#introToSTS|Is there an introduction document on the XMLBeans Schema Type System?]]
  * [[#schemaType2Javaname|How do I get the java name for a schema type?]]
  * [[#schemaAnnotation|How do I get to SchemaAnnotation and SchemaIdentityConstraint on elements?]]
  * [[#schemaPropertySchemaParticle|What is the difference between SchemaProperty and SchemaParticle?]]
  * [[#substGroups|How do I use substitution groups?]]
  * [[#schemaDependencies|How do I compile multiple schema files with dependencies?]]
Line 47: Line 45:
  * [[#navigatingXmlCursor|Is there documentation on navigating with XmlCursor?]]
   * [[#usingBookmarks|How do I use Bookmarks to annotate XML?]]
  * [[#navigatingXmlCursor|Is there documentation on navigating with XmlCursor?]]
  * [[#usingBookmarks|How do I use Bookmarks to annotate XML?]]
Line 52: Line 50:
Line 54: Line 53:
<<Anchor(mailingLists)>>
'''What are the different XMLBeans Mailing Lists?'''
<<Anchor(mailingLists)>> '''What are the different XMLBeans Mailing Lists?'''
Line 60: Line 58:
<<Anchor(committers)>>
'''Who are the XMLBeans Committers?'''
<<Anchor(committers)>> '''Who are the XMLBeans Committers?'''
Line 66: Line 63:
<<Anchor(fileBug)>>
'''Where do I file a bug for XMLBeans?'''

XMLBeans uses Jira for bugtracking.  

 * [[https://issues.apache.org/jira/browse/xmlbeans#selectedTab=com.atlassian.jira.plugin.system.project%3Asummary-panel|Go to XMLBeans JIRA]]
<<Anchor(fileBug)>> '''Where do I file a bug for XMLBeans?'''

XMLBeans uses Jira for bugtracking.

 * [[https://issues.apache.org/jira/browse/xmlbeans#selectedTab=com.atlassian.jira.plugin.system.project:summary-panel|Go to XMLBeans JIRA]]
Line 75: Line 71:
Line 77: Line 74:
<<Anchor(latestVersion)>>
'''What is the latest version of XMLBeans?'''

XMLBeans Version 2.4.0 is the most recent 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.

----
<<Anchor(downloadBinary)>>
'''Where can I download the latest release of XMLBeans?'''
<<Anchor(latestVersion)>> '''What is the latest version of XMLBeans?'''

Check the [[http://xmlbeans.apache.org/news.html|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.

----
<<Anchor(downloadBinary)>> '''Where can I download the latest release of XMLBeans?'''
Line 87: Line 82:
----
<<Anchor(gettingStartedDoc)>>
'''How do I get started coding with XMLBeans?'''

----
<<Anchor(gettingStartedDoc)>> '''How do I get started coding with XMLBeans?'''
Line 94: Line 89:
<<Anchor(xmlbeansSource)>>
'''How can I get the latest XMLBeans source code in svn?'''
<<Anchor(xmlbeansSource)>> '''How can I get the latest XMLBeans source code in svn?'''
Line 98: Line 92:
----
<<Anchor(viewJavaDoc)>>
'''Is the XMLBeans javadoc available online?'''

----
<<Anchor(viewJavaDoc)>> '''Is the XMLBeans javadoc available online?'''
Line 105: Line 99:
<<Anchor(whatJars)>>
'''What jars do I need on the classpath to use XMLBeans?'''
<<Anchor(whatJars)>> '''What jars do I need on the classpath to use XMLBeans?'''
Line 112: Line 105:
  ||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). 
  ||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).
Line 123: Line 117:
----
<<Anchor(qname)>>
'''Running my code that used to work fails with "java.lang.!NoClassDefFoundError: javax/xml/namespace/QName" after upgrading to 2.3.0'''

----
<<Anchor(qname)>> '''Running my code that used to work fails with "java.lang.!NoClassDefFoundError: javax/xml/namespace/QName" after upgrading to 2.3.0'''
Line 128: Line 122:
----
<<Anchor(scompFindingJavac)>>
'''The scomp program can't find javac and fails with java.io.IOException on Windows!'''

----
<<Anchor(scompFindingJavac)>> '''The scomp program can't find javac and fails with java.io.IOException on Windows!'''
Line 155: Line 149:

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. 

----
<<Anchor(scompOutOfMemory)>>
'''The scomp program gives !OutOfMemoryError when compiling my complex Schema!'''
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.

----
<<Anchor(scompOutOfMemory)>> '''The scomp program gives !OutOfMemoryError when compiling my complex Schema!'''
Line 174: Line 166:

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:
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:
Line 181: Line 172:
<<Anchor(codeTooLarge)>>
'''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]]
<<Anchor(codeTooLarge)>> '''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
Line 189: Line 179:
----
<<Anchor(buildingXMLBeans)>>
'''How do I build XMLBeans?'''

----
<<Anchor(buildingXMLBeans)>> '''How do I build XMLBeans?'''
Line 194: Line 184:
----
<<Anchor(viewXMLBeansOnline)>>
'''Can I view the XMLBeans source code online, without having svn on my machine?'''

----
<<Anchor(viewXMLBeansOnline)>> '''Can I view the XMLBeans source code online, without having svn on my machine?'''
Line 202: Line 192:
Line 204: Line 195:
<<Anchor(javaType4SchemaTypes)>>
'''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 ... [[http://xmlbeans.apache.org/docs/2.0.0/guide/conJavaTypesGeneratedFromUserDerived.html|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 ... [[http://xmlbeans.apache.org/docs/2.0.0/guide/conXMLBeansSupportBuiltInSchemaTypes.html|XMLBeans Support for Built-In Schema Types]]

----
<<Anchor(configPackageName)>>
'''Can I change the default package names for the java classes generated from my schema?'''
<<Anchor(javaType4SchemaTypes)>> '''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 ... [[http://xmlbeans.apache.org/docs/2.0.0/guide/conJavaTypesGeneratedFromUserDerived.html|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 ... [[http://xmlbeans.apache.org/docs/2.0.0/guide/conXMLBeansSupportBuiltInSchemaTypes.html|XMLBeans Support for Built-In Schema Types]]

----
<<Anchor(configPackageName)>> '''Can I change the default package names for the java classes generated from my schema?'''
Line 220: Line 203:
{{{
<!-- An xsdconfig file must begin with a "config" element in the 

{{{
<!-- An xsdconfig file must begin with a "config" element in the
Line 225: Line 209:
<xb:config xmlns:pol="http://openuri.org/easypoLocal"  <xb:config xmlns:pol="http://openuri.org/easypoLocal"
Line 236: Line 220:
        XML element name; the javaname attribute's value is the Java type          XML element name; the javaname attribute's value is the Java type
Line 242: Line 226:
Line 246: Line 229:
Line 256: Line 240:
<<Anchor(deepEquals)>>
'''Is there a way to do a ''deep equals'' between two !XmlObjects?'''
<<Anchor(deepEquals)>> '''Is there a way to do a ''deep equals'' between two !XmlObjects?'''
Line 264: Line 247:
<<Anchor(suggestedPrefixes)>>
'''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.  
<<Anchor(suggestedPrefixes)>>  '''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.
Line 270: Line 252:
Line 278: Line 261:

----
<<Anchor(xsiSchemaLocation)>>
'''How can I instruct XMLBeans to add the xsi:schemaLocation attribute to my documents?'''
----
<<Anchor(xsiSchemaLocation)>> '''How can I instruct XMLBeans to add the xsi:schemaLocation attribute to my documents?'''
Line 284: Line 265:
Line 291: Line 273:

----
<<Anchor(selectPath)>>
'''Is selectPath(...) on !XmlObject and !XmlCursor working?'''
----
<<Anchor(selectPath)>> '''Is selectPath(...) on !XmlObject and !XmlCursor working?'''
Line 301: Line 281:
<<Anchor(execQuery)>>
'''Is execQuery(...) on !XmlObject and !XmlCursor working?'''
<<Anchor(execQuery)>> '''Is execQuery(...) on !XmlObject and !XmlCursor working?'''
Line 309: Line 288:
<<Anchor(xsdConfig)>>
'''How do I modify the generated interfaces?'''
<<Anchor(xsdConfig)>> '''How do I modify the generated interfaces?'''
Line 315: Line 293:
<<Anchor(cdataOptions)>>
'''How do I control CDATA?'''
<<Anchor(cdataOptions)>> '''How do I control CDATA?'''
Line 322: Line 299:
Line 324: Line 302:
<<Anchor(introToSTS)>>
'''Is there an introduction document on the XMLBeans Schema Type System?'''
<<Anchor(introToSTS)>> '''Is there an introduction document on the XMLBeans Schema Type System?'''
Line 330: Line 307:
<<Anchor(schemaType2Javaname)>>
'''How do I get the java name for a schema type?'''

   1. Once you've compiled things and got the JAR...

   1. Put the JAR on your classpath

   1. Use {{{com.bea.xml.XmlBeans.getContextTypeLoader()}}} to get the !SchemaTypeLoader corresponding to your thread's context classloader.

   1. you can then use {{{schemaTypeLoader.findType(QNameForType)}}}

   1. and then {{{type.getFullJavaName()}}}

  see this post: http://nagoya.apache.org/eyebrowse/ReadMsg?listName=xmlbeans-user@xml.apache.org&msgNo=7 ''@fixme: seems to be a dead link''

----
<<Anchor(schemaAnnotation)>>
'''How do I get to !SchemaAnnotation and !SchemaIdentityConstraint on elements?'''
<<Anchor(schemaType2Javaname)>> '''How do I get the java name for a schema type?'''

 1. Once you've compiled things and got the JAR...

 1. Put the JAR on your classpath

 1. Use {{{com.bea.xml.XmlBeans.getContextTypeLoader()}}} to get the !SchemaTypeLoader corresponding to your thread's context classloader.

 1. you can then use {{{schemaTypeLoader.findType(QNameForType)}}}

 1. and then {{{type.getFullJavaName()}}}

 1. see this post: http://nagoya.apache.org/eyebrowse/ReadMsg?listName=xmlbeans-user@xml.apache.org&msgNo=7 ''@fixme: seems to be a dead link''

----
<<Anchor(schemaAnnotation)>> '''How do I get to !SchemaAnnotation and !SchemaIdentityConstraint on elements?'''
Line 352: Line 327:
<<Anchor(schemaPropertySchemaParticle)>>
'''What is the difference between !SchemaProperty and !SchemaParticle?'''
<<Anchor(schemaPropertySchemaParticle)>> '''What is the difference between !SchemaProperty and !SchemaParticle?'''
Line 358: Line 332:
  <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: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>
Line 373: Line 347:
{{{    {{{
Line 410: Line 384:
Line 434: Line 409:
Line 444: Line 420:
----
<<Anchor(substGroups)>>
'''How do I use substitution groups?'''

----
<<Anchor(substGroups)>> '''How do I use substitution groups?'''
Line 449: Line 425:
----
<<Anchor(schemaDependencies)>>
'''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:

----
<<Anchor(schemaDependencies)>> '''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:
Line 460: Line 436:
Line 463: Line 438:
Line 465: Line 441:
<<Anchor(navigatingXmlCursor)>>
'''Is there documentation on navigating with !XmlCursor?'''
<<Anchor(navigatingXmlCursor)>> '''Is there documentation on navigating with !XmlCursor?'''
Line 471: Line 446:
<<Anchor(usingBookmarks)>>
'''How do I use Bookmarks to annotate XML?'''
<<Anchor(usingBookmarks)>> '''How do I use Bookmarks to annotate XML?'''

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.

/!\ 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

/!\ 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.


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.


XmlBeansFaq (last edited 2013-08-21 20:05:15 by fx)