XMLBeans Tools

XMLBeans includes several command-line tools you might find handy as shortcuts for common tasks. You'll find these tools in the bin directory of the XMLBeans installation or source tree.

dumpxsb (XSB File Dumper)

Prints the contents of an XSB file in human-readable form.

inst2xsd (Instance to Schema Tool)

Generates XML schema from XML instance files.

scomp (Schema Compiler)

Compiles a schema into XMLBeans classes and metadata.

scopy (Schema Copier)

Copies the XML schema at the specified URL to the specified file.

sdownload (Schema Downloader)

Maintains "xsdownload.xml," an index of locally downloaded XSD files. URLs that are specified are downloaded if they aren't already cached. If no files or URLs are specified, all indexed files are relevant.

sfactor (Schema Factoring Tool)

Factors redundant definitions out of a set of schemas and uses imports instead.

svalidate (Streaming Instance Validator)

Validates a schema definition and instances within the schema.

validate (Instance Validator)

Validates an instance against a schema.

xpretty (XML Pretty Printer)

Pretty prints the specified XML to the console.

xsd2inst (Schema to Instance Tool)

Prints an XML instance from the specified global element using the specified schema.

xsdtree (Schema Type Hierarchy Printer)

Prints an inheritance hierarchy of the types defined in a schema.

xmlbean Ant task

Compiles a set of XSD and/or WSDL files into XMLBeans types.

Prints the contents of an XSB file in human-readable form. An XSB file contains schema meta information needed to perform tasks such as binding and validation. "XSB" stands for XML Schema Binary.

Syntax

Options

myfile.xsb

The name of an XSB file.

Example

The following command and output example use an XSB file generated by compiling the schema (in EasyPo.xsd) that accompanies the SubstitutionGroup sample.

Output:

Generates XML schema from XML instance files.

Syntax

Options

-design[rd|ss|vb]

The XML schema design type to use for the generated schema.
rd — Use russian doll design; local elements and local types.
ss — Use salami slice design; global elements and local types.
vb(default) — Use venetian blind design; local elements and global complex types.

-simple-content-types [smart | string]

The manner for detecting content types (leaf text)
smart (default) — Use a likely type, such as xs:byte for a value of "123".
string — Use xs:string as the type.

-enumerations [never | number]

Whether to use enumerations.
never — Never use enumerations.
number (default: 10) — Use number as the threshold for enumerations. Specifying "2" will create enumerations for elements with no more than two different values.

-outDir [dir]

The directory for output files.
dir — Directory path. Default is '.' (the current directory).

-outPrefix [file_name_prefix]

The prefix for output file names.
file_name_prefix — Prefix to use. Default is "schema".

-validate

Validate input instances against generated schemas.

-verbose

Print more informational messages.

-license

Print license information.

-help

Print help information.

v

The following example generates schema0.xsd from Purchase-Order.xml, with salami slice schema design, simple content types detected where possible, and enumerations limited to elements with four different values.

Compiles schema into Java XMLBeans classes and metadata. Schema-related work with XMLBeans begins by compiling schema to generated Java types. You can use scomp to compile schema from the command line. XMLBeans also provides an Ant task, xmlbeans, which you can use to compile schemas. For run-time schema compilation that doesn't generate files, see the org.apache.xmlbeans.XmlBeans.compileXsd methods.

For more information about the types resulting from compiling schema, see Java Types Generated from User-Derived Schema Types, XMLBeans Support for Built-In Schema Types, and Methods for Types Generated From Schema.

For more information on getting started with XMLBeans, see Getting Started with XMLBeans.

Syntax

Options

-cp [pathA;pathB;pathC]

Classpath specifying classes to include during compilation.
pathA;pathB;pathC — Class search path of directories and JAR files.

-d [dir]

Target directory for CLASS and XSB files.
dir — The directory path.

-src [dir]

Target directory for generated JAVA files.
dir — The directory path.

-srconly

Do not compile JAVA files or jar the output.
Note that XSB files are needed in order for CLASS files compiled from the sources to be useful as XMLBeans classes. To get only JAVA files, use -src to specify a directory for the JAVA files. To get JAVA and XSB files in the same directory, use -d to specify a directory that will include both. To get JAVA and XSB files in separate directories, use -src for the JAVA file destination and -d for the XSB file destination.

-out [jarFileName]

The name of the output JAR that will contain the result of compilation. The default is "xmltypes.jar".
jarFileName — The name for the JAR containing generated files.

-dl

Permit network downloads for imports and includes (this permission is off by default).

-noupa

Do not enforce the unique particle attribution rule.

-nopvr

Do not enforce the particle valid (restriction) rule.

-noann

Ignore annotations.

-novdoc

Do not validate contents of <documentation> elements.

-compiler

Path to external Java compiler.

-ms

Initial memory for external Java compiler; the default is "8m".

-mx

Maximum memory for external Java compiler; the default is "256m".

-debug

Compile with debug symbols.

-quiet

Print fewer informational messages.

-verbose

Print more informational messages.

-version

Print version information.

-license

Print license information.

-allowmdef "[namespace] [namespace] [namespace]"

Ignore multiple defs in given namespaces. Use ##local to specify the no-namespace in that list.

-catalog [fileName]

Catalog file to use for resolving external entities. With this option, scomp uses org.apache.xml.resolver.tools.CatalogResolver for resolving. Note that to use this option, your classpath must include resolver.jar from https://xml.apache.org/commons/components/resolver/index.html). Copy resolver.jar to the XMLBEANS_HOME/lib directory, so that the script can pick it up from there. You can use the sdownload tool to ensure that required schemas are present for compilation.
fileName —A path to the catalog file.

dirs

Directories containing XSD (and possibly XSDCONFIG) files that should be compiled.

schemaFile.xsd

The names of XSD files that should be compiled.

service.wsdl

A WSDL file for which types should be generated.

config.xsdconfig

The name of an XSDCONFIG file. Use an XSDCONFIG file to guide the naming of generated classes and packages. Without an XSDCONFIG file, scomp uses the schema's type names and URI for classes and packages.

Example

In the following example, scomp compiles EasyPO.xsd, guiding type naming with po.xsdconfig. scomp puts generated CLASS and XSB files into a classes directory one level up, and JAVA source files into a src directory one level up. Source files will be compatible with Java version 1.5.

Here, scomp compiles all of the contents of the schemas directory and puts the generated files into poschema.jar one level up.

The following example generates JAVA source and XSB files from the schema in EasyPO.xsd. No CLASS files are generated, and the JAVA and XSB files are put into src and xsb directories, respectively.

When the schema features imports or includes and you want to use a catalog, you can tell scomp to use the default catalog resolver ( org.apache.xml.resolver.tools.CatalogResolver); you specify a catalog file with the -catalog option, as in the example below. (Note that this requires resolver.jar, as noted above for the -catalog option.) In this example, scomp compiles schemaThatUsesRequiredSchema.xsd into myschemas.jar, resolving imports from requiredSchema.xsd through xsdownload.xml. The sdownload tool is executed first — this ensures that requiredSchema.xsd is present for compilation, but does not actually download requiredSchema.xsd unless the URL at which it's found isn't already cached. This is more efficient than using scomp's -dl option, which attempts to download every time.

When a schema features multiple element declarations of the same qname, such as multiple <xs:any> particles, you might want to disable to "unique particle validation" rule, which would ordinarily invalidate the schema. To do this, use the -noupa option, as in the following example.

Copies the XML schema at the specified URL to the specified file.

Syntax

Options

sourceurl

The URL at which the schema is located.

targetfile

The file to which the schema should be copied.

Maintains "xsdownload.xml," an index of locally downloaded XSD files. URLs that are specified are downloaded if they aren't already cached. If no files or URLs are specified, all indexed files are relevant.

You can use this tool when using scomp, in conjunction with scomp's -catalog option, to ensure the presence of schemas that are required for compilation because they're imported or included. This is an alternative to using scomp's -dl option, which would hit the Internet on every invocation of scomp. When you use sdownload with -catalog, the download occurs only if the URL is not already cached. See the scomp section for an example.

Syntax

Options

-dir directory

The directory for the xsdownload.xml file (the default is ".").
directory — The directory path.

-sync

Synchronize the index to any local XSD files in the tree.

-recurse

Recursively download imported and included XSD files.

-refresh

Re-download all indexed XSD files.

Factors redundant definitions out of a set of schemas and uses imports instead.

Syntax

Options

-import

The XSD file to contain redundant definitions for importing.
common.xsd — A path to the file.

-out outputdir

The directory into which to place XSD files resulting from refactoring, plus a commonly imported common.xsd.

inputdir

The directory containing the XSD files with redundant definitions.

-license

Print license information.

Validates the specified instance against the specified schema. Unlike the validate tool, svalidate uses a streaming model through which you can validate much larger instances with less memory (if the schema permits it).

Syntax

Options

-dl

Enable network downloads for imports and includes.

-nopvr

Disable particle valid (restriction) rule.

-noupa

Disable unique particle attribution rule.

-license

Print license information.

schema.xsd

The schema against which to validate.

instance.xml

The instance to validate.

Validates a the specified instance against the specified schema. Compare this tool with the svalidate tool, which is useful for validating very large documents.

Syntax

Options

-dl

Enable network downloads for imports and includes.

-nopvr

Disable particle valid (restriction) rule.

-noupa

Disable unique particle attribution rule.

-license

Print license information.

schema.xsd

The schema against which to validate.

instance.xml

The instance to validate.

Example

The following simple example validates PurchaseOrder.xml against EasyPO.xsd.

In this example, MySchema imports types from another schema and also includes multiple particles defined as <xsd:any> types. The validate command here locates the external schemas for importing (providing there is network access to the schemas) and ignores the validation rule whereby multiple particles of the same qname render the schema invalid.

Pretty prints the specified XML to the console.

Syntax

Options

-indent numberOfSpaces

Indent the specified number of spaces.
numberOfSpaces — The number of spaces to indent.

-license

Print license information.

Prints an XML instance from the specified global element using the specified schema.

Syntax

Options

schemafile.xsd

The schema file defining the element to print.

-name

The name of the global element
globalElementName— The local name of the global element to use as the root of the printed instance.

Example

The following command and output use the schema that accompanies the SubstitutionGroup sample.

Output

Prints inheritance hierarchy of types defined in a schema.

Syntax

Options

-noanon

Don't include anonymous types in the tree.

-nopvr

Disable particle valid (restriction) rule.

-noupa

Disable unique particle attribution rule.

-partial

Print only part of the hierarchy.

-license

Print license information.

schemafile.xsd

The file containing the schema whose hierarchy should be printed.

Example

The following command and output use the schema that accompanies the SubstitutionGroup sample.

Output:

Compiles a set of XSD and/or WSDL files into XMLBeans types. See xmlbean Ant Task for more complete documentation on the task.

Getting Started with XMLBeans