jaxb2:xjc
Full name:
org.codehaus.mojo:jaxb2-maven-plugin:3.1.0:xjc
Description:
Mojo that creates compile-scope Java source or binaries from XML schema(s) by invoking the JAXB XJC binding compiler. This implementation is tailored to use the JAXB Reference Implementation from project Kenai.
Note that the XjcMojo was completely re-implemented for the 2.x versions. Its configuration semantics and parameter set is not necessarily backwards compatible with the 1.x plugin versions. If you are upgrading from version 1.x of the plugin, read the documentation carefully.
Attributes:
- Requires a Maven project to be executed.
- Requires dependency resolution of artifacts in scope:
compile
. - The goal is thread-safe and supports parallel builds.
- Binds by default to the lifecycle phase:
generate-sources
.
Required Parameters
Name | Type | Since | Description |
---|---|---|---|
<outputDirectory> |
File |
- |
Corresponding XJC parameter: The working directory where the generated Java source files are created. Default value is: ${project.build.directory}/generated-sources/jaxb . |
Optional Parameters
Name | Type | Since | Description |
---|---|---|---|
<addGeneratedAnnotation> |
boolean |
2.0 |
Corresponding XJC parameter: This feature causes all of the generated code to have
Default value is: false . |
<arguments> |
List |
2.0 |
Deprecated. This should be removed in the 2.0+ release, as all arguments should
be handled by other parameters. User property is: xjc.arguments . |
<catalog> |
File |
- |
Corresponding XJC parameter: Specify catalog files to resolve external entity references. Supports TR9401, XCatalog, and OASIS XML Catalog format. |
<clearOutputDir> |
boolean |
- |
Removes all files from the output directory before running XJC. Default value is: true . |
<enableIntrospection> |
boolean |
1.4 |
Corresponding XJC parameter:
Enable correct generation of Boolean getters/setters to enable Bean Introspection APIs. Default value is: false . |
<encoding> |
String |
2.0 |
Defines the encoding used by XJC (for generating Java Source
files) and schemagen (for generating XSDs). The corresponding
argument parameter for XJC and SchemaGen is:
The algorithm for finding the encoding to use is as follows (where the first non-null value found is used for encoding):
Default value is: ${project.build.sourceEncoding} . |
<episodeFileName> |
String |
2.4 |
Corresponding XJC parameter: Generate an episode file with the supplied name from this XJC
compilation, so that other schemas that rely on this schema can be
compiled later and rely on classes that are generated from this
compilation. The generated episode file is simply a JAXB
customization file (but with vendor extensions), normally known as
a binding file with the suffix If the
|
<extension> |
boolean |
- |
Corresponding XJC parameter: By default, the XJC binding compiler strictly enforces the rules outlined in the Compatibility chapter of the JAXB Specification. Appendix E.2 defines a set of W3C XML Schema features that are not 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 are also limited to using only the binding customizations defined in the specification. Default value is: true . |
<externalEntityProcessing> |
boolean |
2.4 |
If set to
Default value is: false . |
<extraFacets> |
List |
2.2 |
Defines a set of extra EnvironmentFacet instances which are used to further configure the ToolExecutionEnvironment used by this plugin to fire XJC or SchemaGen. Example: If you implement the EnvironmentFacet
interface in the class
|
<failOnNoSchemas> |
boolean |
1.3 |
Fails the Mojo execution if no XSDs/schemas are found. Default value is: true . |
<generateEpisode> |
boolean |
2.0 |
Deprecated. No reason given Default value is: true . |
<laxSchemaValidation> |
boolean |
2.0 |
Corresponding XJC parameter: By default, the XJC binding compiler performs strict validation of the source schema before processing it. Use this option to disable strict schema validation. This does not mean that the binding compiler will not perform any validation, it simply means that it will perform less-strict validation. Default value is: false . |
<locale> |
String |
2.2 |
A Locale definition to create and set the system (default) Locale when the XJB or SchemaGen tools executes. The Locale will be reset to its default value after the execution of XJC or SchemaGen is complete. The configuration parameter must be supplied on the form
Example (assigns french locale):
|
<noGeneratedHeaderComments> |
boolean |
2.0 |
Corresponding XJC parameter: Suppress the generation of a file header comment that includes some note and timestamp. Using this makes the generated code more diff-friendly. Default value is: false . |
<noPackageLevelAnnotations> |
boolean |
2.0 |
Corresponding XJC parameter: Suppress the generation of package level annotations into
Default value is: false . |
<packageName> |
String |
- |
Corresponding XJC parameter: The package under which the source files will be generated. Quoting the XJC documentation: "Specifying a target package via this command-line option overrides any binding customization for package name and the default package name algorithm defined in the specification". |
<quiet> |
boolean |
- |
Corresponding XJC parameter: Suppress compiler output, such as progress information and warnings. Default value is: false . |
<readOnly> |
boolean |
2.0 |
Corresponding XJC parameter: By default, the XJC binding compiler does not write-protect the Java source files it generates. Use this option to force the XJC binding compiler to mark the generated Java sources read-only. Default value is: false . |
<skipXjc> |
boolean |
- |
Indicate if the XjcMojo execution should be skipped. Default value is: false .User property is: xjc.skip . |
<sourceType> |
SourceContentType |
2.0 |
Defines the content type of sources for the XJC. To simplify usage of the JAXB2 maven plugin, all source files are assumed to have the same type of content. This parameter replaces the previous multiple-choice boolean configuration options for the jaxb2-maven-plugin (i.e. dtd, xmlschema, relaxng, relaxng-compact, wsdl), and corresponds to setting one of those flags as an XJC argument. Default value is: XmlSchema . |
<sources> |
List |
- |
Parameter holding List of XSD paths to files and/or directories which should be recursively searched for XSD files. Only files or directories that actually exist will be included (in the case of files) or recursively searched for XSD files to include (in the case of directories). Configure using standard Maven structure for Lists:
|
<target> |
String |
1.3 |
Corresponding XJC parameter: Permitted values: |
<verbose> |
boolean |
- |
Corresponding XJC parameter: Tells XJC to be extra verbose, such as printing informational messages or displaying stack traces. Default value is: false .User property is: xjc.verbose . |
<xjbExcludeFilters> |
List |
- |
Parameter holding a List of Filters, used to match all files
under the If not explicitly provided, the Mojo uses the value within
Example: The following configuration would
exclude any XJB files whose names end with
Note that inner workings of the Dependency Injection mechanism used by Maven Plugins (i.e. the DI from the Plexus container) requires that the full class name to the Filter implementation should be supplied for each filter, as is illustrated in the sample above. This is true also if you implement custom Filters. |
<xjbSources> |
List |
- |
Parameter holding List of XJB Files and/or directories which should be recursively searched for XJB files. Only files or directories that actually exist will be included (in the case of files) or recursively searched for XJB files to include (in the case of directories). JAXB binding files are used to configure parts of the Java source generation. Supply the configuration using the standard Maven structure for configuring plugin Lists:
|
<xjcSourceExcludeFilters> |
List |
- |
Parameter holding a List of Filters, used to match all files
under the If not explicitly provided, the Mojo uses the value within
Example: The following configuration would
exclude any sources whose names end with
Note that inner workings of the Dependency Injection mechanism used by Maven Plugins (i.e. the DI from the Plexus container) requires that the full class name to the Filter implementation should be supplied for each filter, as is illustrated in the sample above. This is true also if you implement custom Filters. |
<xsdPathWithinArtifact> |
String |
2.0 |
If provided, this parameter indicates that the XSDs used by XJC
to generate Java code should be copied into the resulting artifact
of this project (the JAR, WAR or whichever artifact type is
generated). The value of the The target directory is created within the artifact if it does
not already exist. If the Example:Adding the sample configuration below would
copy all source XSDs to the given directory within the resulting
JAR (and/or test-JAR). If the directory
Note: This parameter was previously called
|
Parameter Details
<addGeneratedAnnotation>
Corresponding XJC parameter: mark-generated
.
This feature causes all of the generated code to have
@Generated
annotation.
- Type:
boolean
- Since:
2.0
- Required:
No
- Default:
false
<arguments>
List of ordered extra arguments to the XJC command. Each extra argument is interpreted as a word, intended to be copied verbatim to the XJC argument list with spaces in between:
<configuration>
...
<arguments>
<argument>-Xfluent-api</argument>
<argument>somefile</argument>
</arguments>
</configuration>
The arguments configured above yields the following extra
arguments to the XJC command: -Xfluent-api -episode
somefile
- Type:
java.util.List
- Since:
2.0
- Required:
No
- User Property:
xjc.arguments
<catalog>
Corresponding XJC parameter: catalog
.
Specify catalog files to resolve external entity references. Supports TR9401, XCatalog, and OASIS XML Catalog format.
- Type:
java.io.File
- Required:
No
<clearOutputDir>
Removes all files from the output directory before running XJC.
- Type:
boolean
- Required:
No
- Default:
true
<enableIntrospection>
Corresponding XJC parameter:
enableIntrospection
.
Enable correct generation of Boolean getters/setters to enable Bean Introspection APIs.
- Type:
boolean
- Since:
1.4
- Required:
No
- Default:
false
<encoding>
Defines the encoding used by XJC (for generating Java Source
files) and schemagen (for generating XSDs). The corresponding
argument parameter for XJC and SchemaGen is:
encoding
.
The algorithm for finding the encoding to use is as follows (where the first non-null value found is used for encoding):
- If the configuration property is explicitly given within the plugin's configuration, use that value.
- If the Maven property
project.build.sourceEncoding
is defined, use its value. - Otherwise use the value from the system property
file.encoding
.
- Type:
java.lang.String
- Since:
2.0
- Required:
No
- Default:
${project.build.sourceEncoding}
<episodeFileName>
Corresponding XJC parameter: episode
.
Generate an episode file with the supplied name from this XJC
compilation, so that other schemas that rely on this schema can be
compiled later and rely on classes that are generated from this
compilation. The generated episode file is simply a JAXB
customization file (but with vendor extensions), normally known as
a binding file with the suffix .xjb
.
If the episodeFileName
parameter is not given, the
episode file name is synthesized on the form "episode_" +
executionID + ".xjb"
- typically something like
episode_my_xjc.xjb, but it depends on the actual ID given
in the execution element:
<executions>
<execution>
<id>my_xjc</id>
<goals>
<goal>xjc</goal>
</goals>
</execution>
</executions>
- Type:
java.lang.String
- Since:
2.4
- Required:
No
<extension>
Corresponding XJC parameter: extension
.
By default, the XJC binding compiler strictly enforces the rules outlined in the Compatibility chapter of the JAXB Specification. Appendix E.2 defines a set of W3C XML Schema features that are not 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 are also limited to using only the binding customizations defined in the specification.
- Type:
boolean
- Required:
No
- Default:
true
<externalEntityProcessing>
If set to true
, the system property
enableExternalEntityProcessing
is set for the duration
of the Java generation by this plugin, permitting DTD sources to
use external entity URIs such as file://
. Typically,
this is used in conjunction with the sourceType
similar to the configuration snippet below where DTDs are used as
sourceType and read from the src/main/dtd
directory.
This implies a file://
URI.
<configuration>
...
<sourceType>dtd</sourceType>
<sources>
<source>src/main/dtd</source>
</sources>
<externalEntityProcessing>true</externalEntityProcessing>
</configuration>
- Type:
boolean
- Since:
2.4
- Required:
No
- Default:
false
<extraFacets>
Defines a set of extra EnvironmentFacet instances which are used to further configure the ToolExecutionEnvironment used by this plugin to fire XJC or SchemaGen.
Example: If you implement the EnvironmentFacet
interface in the class
org.acme.MyCoolEnvironmentFacetImplementation
, its
setup()
method is called before the XJC or SchemaGen
tools are executed to setup some facet of their Execution
environment. Correspondingly, the restore()
method in
your org.acme.MyCoolEnvironmentFacetImplementation
class is invoked after the XJC or SchemaGen execution
terminates.
<configuration>
...
<extraFacets>
<extraFacet implementation="org.acme.MyCoolEnvironmentFacetImplementation" />
</extraFacets>
...
</configuration>
- Type:
java.util.List
- Since:
2.2
- Required:
No
<failOnNoSchemas>
- Type:
boolean
- Since:
1.3
- Required:
No
- Default:
true
<generateEpisode>
From plugin version 2.4, this parameter will not be used. Instead, episode files are generated by default with all JAXB operations.
Starting with plugin version 2.4, use the parameter
episodeFileName
to provide a custom name of the
generated episode File (or rely on the standard file name
STANDARD_EPISODE_FILENAME
).
- Type:
boolean
- Since:
2.0
- Required:
No
- Default:
true
<laxSchemaValidation>
Corresponding XJC parameter: nv
.
By default, the XJC binding compiler performs strict validation of the source schema before processing it. Use this option to disable strict schema validation. This does not mean that the binding compiler will not perform any validation, it simply means that it will perform less-strict validation.
- Type:
boolean
- Since:
2.0
- Required:
No
- Default:
false
<locale>
A Locale definition to create and set the system (default) Locale when the XJB or SchemaGen tools executes. The Locale will be reset to its default value after the execution of XJC or SchemaGen is complete.
The configuration parameter must be supplied on the form
language[,country[,variant]]
, such as
sv,SE
or fr
. Refer to
org.codehaus.mojo.jaxb2.shared.environment.locale.LocaleFacet.createFor(String,
Log)
for further information.
Example (assigns french locale):
<configuration>
<locale>fr</locale>
</configuration>
- Type:
java.lang.String
- Since:
2.2
- Required:
No
<noGeneratedHeaderComments>
Corresponding XJC parameter: no-header
.
Suppress the generation of a file header comment that includes some note and timestamp. Using this makes the generated code more diff-friendly.
- Type:
boolean
- Since:
2.0
- Required:
No
- Default:
false
<noPackageLevelAnnotations>
Corresponding XJC parameter: npa
.
Suppress 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.
- Type:
boolean
- Since:
2.0
- Required:
No
- Default:
false
<outputDirectory>
Corresponding XJC parameter: d
.
The working directory where the generated Java source files are created.
- Type:
java.io.File
- Required:
Yes
- Default:
${project.build.directory}/generated-sources/jaxb
<packageName>
Corresponding XJC parameter: p
.
The package under which the source files will be generated. Quoting the XJC documentation: "Specifying a target package via this command-line option overrides any binding customization for package name and the default package name algorithm defined in the specification".
- Type:
java.lang.String
- Required:
No
<quiet>
Corresponding XJC parameter: quiet
.
Suppress compiler output, such as progress information and warnings.
- Type:
boolean
- Required:
No
- Default:
false
<readOnly>
Corresponding XJC parameter: readOnly
.
By default, the XJC binding compiler does not write-protect the Java source files it generates. Use this option to force the XJC binding compiler to mark the generated Java sources read-only.
- Type:
boolean
- Since:
2.0
- Required:
No
- Default:
false
<skipXjc>
- Type:
boolean
- Required:
No
- User Property:
xjc.skip
- Default:
false
<sourceType>
Defines the content type of sources for the XJC. To simplify usage of the JAXB2 maven plugin, all source files are assumed to have the same type of content.
This parameter replaces the previous multiple-choice boolean configuration options for the jaxb2-maven-plugin (i.e. dtd, xmlschema, relaxng, relaxng-compact, wsdl), and corresponds to setting one of those flags as an XJC argument.
- Type:
org.codehaus.mojo.jaxb2.javageneration.SourceContentType
- Since:
2.0
- Required:
No
- Default:
XmlSchema
<sources>
Parameter holding List of XSD paths to files and/or directories which should be recursively searched for XSD files. Only files or directories that actually exist will be included (in the case of files) or recursively searched for XSD files to include (in the case of directories). Configure using standard Maven structure for Lists:
<configuration>
...
<sources>
<source>some/explicit/relative/file.xsd</source>
<source>/another/absolute/path/to/a/specification.xsd</source>
<source>a/directory/holding/xsds</source>
</sources>
</configuration>
- Type:
java.util.List
- Required:
No
<target>
Corresponding XJC parameter: target
.
Permitted values: "2.0"
and "2.1"
.
Avoid generating code that relies on JAXB newer than the version
given. This will allow the generated code to run with JAXB 2.0
runtime (such as JavaSE 6.)
- Type:
java.lang.String
- Since:
1.3
- Required:
No
<verbose>
Corresponding XJC parameter: verbose
.
Tells XJC to be extra verbose, such as printing informational messages or displaying stack traces.
- Type:
boolean
- Required:
No
- User Property:
xjc.verbose
- Default:
false
<xjbExcludeFilters>
Parameter holding a List of Filters, used to match all files
under the xjbSources
directories which should
not be considered XJB files. (The filters identify
files to exclude, and hence this parameter is called
xjbExcludeFilters
). If a file matches at least one of
the supplied Filters, it is not considered an XJB file, and
therefore excluded from processing.
If not explicitly provided, the Mojo uses the value within
STANDARD_XJB_EXCLUDE_FILTERS
.
Example: The following configuration would
exclude any XJB files whose names end with xml
or
foo
:
<configuration>
...
<xjbExcludeFilters>
<filter implementation="org.codehaus.mojo.jaxb2.shared.filters.pattern.PatternFileFilter">
<patterns>
<pattern>\.txt</pattern>
<pattern>\.foo</pattern>
</patterns>
</filter>
</xjbExcludeFilters>
...
</configuration>
Note that inner workings of the Dependency Injection mechanism used by Maven Plugins (i.e. the DI from the Plexus container) requires that the full class name to the Filter implementation should be supplied for each filter, as is illustrated in the sample above. This is true also if you implement custom Filters.
- Type:
java.util.List
- Required:
No
<xjbSources>
Parameter holding List of XJB Files and/or directories which should be recursively searched for XJB files. Only files or directories that actually exist will be included (in the case of files) or recursively searched for XJB files to include (in the case of directories). JAXB binding files are used to configure parts of the Java source generation. Supply the configuration using the standard Maven structure for configuring plugin Lists:
<configuration>
...
<xjbSources>
<xjbSource>bindings/aBindingConfiguration.xjb</xjbSource>
<xjbSource>bindings/config/directory</xjbSource>
</xjbSources>
</configuration>
- Type:
java.util.List
- Required:
No
<xjcSourceExcludeFilters>
Parameter holding a List of Filters, used to match all files
under the sources
directories which should
not be considered XJC source files. (The filters
identify files to exclude, and hence this parameter is called
xjcSourceExcludeFilters
). If a file under any of the
source directories matches at least one of the Filters supplied in
the xjcSourceExcludeFilters
, it is not considered an
XJC source file, and therefore excluded from processing.
If not explicitly provided, the Mojo uses the value within
STANDARD_SOURCE_EXCLUDE_FILTERS
. The algorithm for
finding XJC sources is as follows:
- Find all files given in the sources List. Any Directories provided are searched for files recursively.
- Exclude any found files matching any of the supplied
xjcSourceExcludeFilters
List. - The remaining Files are submitted for processing by the XJC tool.
Example: The following configuration would
exclude any sources whose names end with txt
or
foo
:
<configuration>
...
<xjcSourceExcludeFilters>
<filter implementation="org.codehaus.mojo.jaxb2.shared.filters.pattern.PatternFileFilter">
<patterns>
<pattern>\.txt</pattern>
<pattern>\.foo</pattern>
</patterns>
</filter>
</xjcSourceExcludeFilters>
</configuration>
Note that inner workings of the Dependency Injection mechanism used by Maven Plugins (i.e. the DI from the Plexus container) requires that the full class name to the Filter implementation should be supplied for each filter, as is illustrated in the sample above. This is true also if you implement custom Filters.
- Type:
java.util.List
- Required:
No
<xsdPathWithinArtifact>
If provided, this parameter indicates that the XSDs used by XJC
to generate Java code should be copied into the resulting artifact
of this project (the JAR, WAR or whichever artifact type is
generated). The value of the xsdPathWithinArtifact
parameter is the relative path within the artifact where all source
XSDs are copied to (hence the name "XSD Path Within Artifact").
The target directory is created within the artifact if it does
not already exist. If the xsdPathWithinArtifact
parameter is not given, the XSDs used to generate Java code are
not included within the project's artifact.
Example:Adding the sample configuration below would
copy all source XSDs to the given directory within the resulting
JAR (and/or test-JAR). If the directory
META-INF/jaxb/xsd
does not exist, it will be
created.
<configuration>
...
<xsdPathWithinArtifact>META-INF/jaxb/xsd</xsdPathWithinArtifact>
</configuration>
Note: This parameter was previously called
includeSchemasOutputPath
in the 1.x versions of this
plugin, but was renamed and re-documented for improved usability
and clarity.
- Type:
java.lang.String
- Since:
2.0
- Required:
No