xjc

You use the xjc shell script to compile an XML schema file into fully annotated Java classes.

Synopsis

xjc [-options] schema file/URL/dir/jar ... [-b bindinfo] ...

options

This represents the xjc command-line options. See Options for the xjc Command.

schema file/URL/dir/jar

This represents the location of the XML schema file. If dir is specified, then all schema files in it are compiled. If jar is specified, then the /META-INF/sun-jaxb.episode binding file is compiled.

This specifies one or more schema files to compile. If you specify a directory, then the xjc command scans it for all schema files and compiles them.

-b bindinfo

The location of the binding files.

Note:

If dir is specified, all schema files in it will be compiled. If jar is specified, the /META-INF/sun-jaxb.episode binding file will be compiled.

Description

Start the binding compiler with the appropriate xjc shell script in the bin directory for your platform. There’s also an Ant task to run the binding compiler.

Options for the xjc Command

-nv

This option disables strict schema validation. This doesn’t mean that the binding compiler won’t perform any validation, but means that it will perform a less strict validation.

By default, the xjc binding compiler performs strict validation of the source schema before processing it.

-extension

This option allows vendor extensions to be used. By default, the xjc binding compiler strictly enforces the rules outlined in the Compatibility Rules chapter and Appendix E.2 of the JAXB Specification. Appendix E.2 defines a set of W3C XML Schema features that aren’t completely supported by JAXB v1.0. In some cases, you may be allowed to use them in the -extension mode enabled by this switch. In the default (strict) mode, you’re also limited to using only the binding customization defined in the specification. By using the -extension switch, you’ll be allowed to use the JAXB Vendor Extensions.

-b file/dir

This option specifies one or more external binding files to process. Each binding file must have its own -b switch. The syntax of the external binding files is flexible. You can have a single binding file that contains customization for multiple schemas or you can break the customization into multiple bindings files. For example:

xjc schema1.xsd schema2.xsd schema3.xsd -b bindings123.xjb

xjc schema1.xsd schema2.xsd schema3.xsd -b bindings1.xjb -b bindings2.xjb -b bindings3.xjb.

In addition, the ordering of the schema files and binding files on the command line doesn’t matter.

-d dir

This option specifies an alternate output directory instead of the default. The output directory must already exist. Thexjc binding compiler doesn’t create it for you.

By default, the xjc binding compiler generates the Java content classes in the current directory.

-p pkg

When you specify a target package with this command-line option, it overrides any binding customization for the package name and the default package name algorithm defined in the specification.

-m name

This option generates module-info.java using the specified Java module name.

-httpproxy proxy

This specifies the HTTP or HTTPS proxy in the format [user[:password]@]proxyHost[:proxyPort]. The old -host and -port options are still supported by the RI for backward compatibility, but they are deprecated. The password specified with this option is an argument that’s visible to other users who use the top command. For greater security, use the -httpproxyfile option.

-httpproxyfile file

This option specifies the HTTP or HTTPS proxy with a file. This is same format as the -httpproxy option, but the password specified in the file isn’t visible to other users.

-classpath arg

This option specifies where to find client application class files used by the jxb:javaType and xjc:superClass customization.

-catalog file

This option specifies catalog files to resolve external entity references. It supports the TR9401, XCatalog, and OASIS XML Catalog formats.

-readOnly

This option forces the xjc binding compiler to mark the generated Java sources as read-only.

By default, the xjc binding compiler doesn’t write-protect the Java source files that it generates.

-npa

This option suppresses the generation of package-level annotations into **/package-info.java. Using this switch causes the generated code to internalize those annotations into the other generated classes.

-no-header

This option suppresses the generation of a file header comment that includes some note and time stamp. Using this makes the generated code more compatible with the diff command.

-target [2.0|2.1]

This option generates code in accordance with the specified JAXWS specification version. Defaults to 2.2. The accepted values are 2.0, 2.1, and 2.2.

-encoding encoding

This option specifies character encoding for generated source files.

-enableIntrospection

This option enables the correct generation of Boolean getters and setters to enable Bean Introspection APIs.

-disableXmlSecurity

This option disables XML security features when parsing XML documents.

-contentForWildcard

This option generates content property for types with multiple xs:any derived elements.

-xmlschema

This option treats input schemas as W3C XML Schema (default). If you don’t specify this switch, then your input schemas are treated as though they’re W3C XML Schemas.

-dtd

This option treats input schemas as XML DTD (experimental and unsupported). Support for RELAX NG schemas is provided as a JAXB Vendor Extension.

-wsdl

This option treats input as WSDL and compiles schemas inside it (experimental and unsupported).

-verbose

This option generates extra verbose output, such as printing informational messages or displaying stack traces upon some errors.

-quiet

This option suppresses compiler output, such as progress information and warnings.

-help

This option displays a brief summary of the compiler switches.

-version

This option displays the compiler version information.

-fullversion

This option displays full version information.

Extensions for the xjc Command

-Xpropertyaccessors: This option uses XmlAccessType PROPERTY instead of FIELD for generated classes.
-mark-generated: This option marks the generated code with the annotation @javax.annotation.Generated.
-Xinject-code: This option injects the specified Java code fragments into the generated code.
-episode file: This option generates the specified episode file for separate compilation.
-XLocator: This option causes the generated code to expose Simple API for XML (SAX) Locator information about the source XML in the Java bean instances after unmarshalling.
-Xsync-methods: This option causes all of the generated method signatures to include the synchronized keyword.

Deprecated and Removed Options for the xjc Command

-host and -port: These options are replaced with the -httpproxy option. For backward compatibility, these options are supported, but won’t be documented and might be removed from future releases.
-use-runtime: Because the JAXB 2.0 specification has defined a portable runtime environment, it’s no longer necessary for the JAXB reference implementation to generate **/impl/runtime packages. Therefore, this switch is obsolete and was removed.
-source: The -source compatibility switch was introduced in the first JAXB 2.0 Early Access release. This switch is removed from future releases of JAXB 2.0. If you need to generate 1.0.n code, then use an installation of the 1.0.n codebase.

Compiler Restrictions for the xjc Command

In general, it’s safest to compile all related schemas as a single unit with the same binding compiler switches. Keep the following list of restrictions in mind when running the xjc command. Most of these issues apply only when you compile multiple schemas with multiple invocations of the xjc command.

To compile multiple schemas at the same time, remember the following precedence rules for the target Java package name:

The -p option has the highest precedence.
If there are jaxb:package customizations.
If targetNamespace is declared, then apply the targetNamespace to the Java package name algorithm defined in the specification.
If no targetNamespace is declared, then use a hard coded package named generated.

You can’t have more than one jaxb:schemaBindings per name space, so it’s impossible to have two schemas in the same target name space compiled into different Java packages.

All schemas being compiled into the same Java package must be submitted to the XJC binding compiler at the same time. They can’t be compiled independently and work as expected.

Element substitution groups that are spread across multiple schema files must be compiled at the same time.