# 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.

## dumpxsb (XSB File Dumper)

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

    dumpxsb myfile.xsb

#### 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.

    dumpxsb PurchaseOrderDocument.xsb

Output:

    PurchaseOrderDocument.xsb
      Magic cookie: da7ababe
      Major version: 2
      Minor version: 22
      Release number: 0
      Filetype: FILETYPE_SCHEMAPOINTER
      String pool (2):
      1 = "schema.system.s633ECC92E6CC0ACA137B11B7B38CA3A8"
      Type system: schema.system.s633ECC92E6CC0ACA137B11B7B38CA3A8

## inst2xsd (Instance to Schema Tool)

Generates XML schema from XML instance files.

### Syntax

    inst2xsd [options] instance.xml*

#### 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.

### Example

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.

    inst2xsd -design ss -simple-content-types smart -enumerations 4 Purchase-Order.xml

## scomp (Schema Compiler)

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

    scomp [options] [dirs]* [schemaFile.xsd]* [service.wsdl]* [config.xsdconfig]*

#### 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.
-javasource [version]
  Generate Java source compatible for the specified Java version (1.4 or 1.5).
-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 http://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.

    scomp -d ..\classes -src ..\src -javasource 1.5 EasyPO.xsd po.xsdconfig

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

    scomp -out ..\poschema.jar schemas

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.

    scomp -srconly -src ..\src -d ..\xsb EasyPO.xsd

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.

    sdownload "http://some.org/requiredSchema.xsd"
    scomp -out ..\myschemas.jar -catalog xsdownload.xml schemaThatUsesRequiredSchema.xsd

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.

    scomp -out ..\myschemas.jar -noupa schemas

## scopy (Schema Copier)

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

### Syntax

    schemacopy sourceurl [targetfile]

#### Options

sourceurl
  The URL at which the schema is located.
targetfile
  The file to which the schema should be copied.

## 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.

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

    sdownload [-dir directory] [-refresh] [-recurse] [-sync] [url/file]

#### 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.

## sfactor (Schema Factoring Tool)

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

### Syntax

    sfactor [-import common.xsd] [-out outputdir] inputdir [-license]

#### 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.

## svalidate (Streaming Instance Validator)

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

    svalidate [options] schema.xsd instance.xml

#### 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.

## validate (Instance Validator)

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

    validate [options] schema.xsd instance.xml

#### 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.

    validate ..\schemas\EasyPO.xsd PurchaseOrder.xml

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.

    validate -dl -noupa ..\schemas\MySchema.xsd AnInstance.xml

## xpretty (XML Pretty Printer)

Pretty prints the specified XML to the console.

### Syntax

    xpretty [options] file.xml

#### Options

-indent numberOfSpaces
  Indent the specified number of spaces.
  numberOfSpaces — The number of spaces to indent.
-license
  Print license information.

## xsd2inst (Schema to Instance Tool)

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

### Syntax

    xsd2inst schemafile.xsd -name globalElementName

#### 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.

    xsd2inst easypo.xsd -name invoice-header

Output

    <eas:invoice-header xmlns:eas="http://xmlbeans.apache.org/samples/substitutiongroup/easypo">
        <eas:ship-to>
            <eas:name>string</eas:name>
            <eas:address>string</eas:address>
        </eas:ship-to>
        <eas:bill-to>
            <eas:name>string</eas:name>
            <eas:address>string</eas:address>
        </eas:bill-to>
        <!--Optional:-->
        <eas:product id="3"/>
        <!--Optional:-->
        <eas:comment>string</eas:comment>
    </eas:invoice-header>

## xsdtree (Schema Type Hierarchy Printer)

Prints inheritance hierarchy of types defined in a schema.

### Syntax

    xsdtree [-noanon] [-nopvr] [-noupa] [-partial] [-license] schemafile.xsd*

#### 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.

    xsdtree easypo.xsd

Output:

    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:eas="http://xmlbeans.apache.org/samples/substitutiongroup/easypo"
    +-xs:anyType (builtin)
        +-xs:anySimpleType (builtin)
        | +-xs:string (builtin)
        | +-xs:normalizedString (builtin)
        | +-xs:token (builtin)
        | +-type of color element in eas:clothing-type (enumeration)
        +-type of element eas:invoice-header
        +-type of element eas:purchase-order
        +-eas:product-type
        | +-eas:clothing-type
        | +-eas:book-type
        +-eas:name-address

## xmlbean Ant task

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

Related Topics

Getting Started with XMLBeans