Full name:
org.codehaus.mojo:jaxb2-maven-plugin:2.4: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:
Name | Type | Since | Description |
---|---|---|---|
<outputDirectory> | File | - |
Corresponding XJC parameter: d. The working directory where the generated Java source files are created. Default value is: ${project.build.directory}/generated-sources/jaxb. |
Name | Type | Since | Description |
---|---|---|---|
<addGeneratedAnnotation> | boolean | 2.0 |
Corresponding XJC parameter: mark-generated. This feature causes all of the generated code to have @Generated annotation. 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: catalog. 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: enableIntrospection. 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: encoding. 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: 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> |
<extension> | boolean | - |
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. Default value is: true. |
<externalEntityProcessing> | boolean | 2.4 |
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> 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 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> |
<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: 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. 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 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> |
<noGeneratedHeaderComments> | boolean | 2.0 |
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. Default value is: false. |
<noPackageLevelAnnotations> | boolean | 2.0 |
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. Default value is: false. |
<packageName> | String | - |
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". |
<quiet> | boolean | - |
Corresponding XJC parameter: quiet. Suppress compiler output, such as progress information and warnings. Default value is: false. |
<readOnly> | boolean | 2.0 |
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. 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: <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> |
<target> | String | 1.3 |
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.) |
<verbose> | boolean | - |
Corresponding XJC parameter: verbose. 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 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. |
<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: <configuration> ... <xjbSources> <xjbSource>bindings/aBindingConfiguration.xjb</xjbSource> <xjbSource>bindings/config/directory</xjbSource> </xjbSources> </configuration> |
<xjcSourceExcludeFilters> | List | - |
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:
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. |
<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 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. |
Corresponding XJC parameter: mark-generated.
This feature causes all of the generated code to have @Generated annotation.
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
Corresponding XJC parameter: catalog.
Specify catalog files to resolve external entity references. Supports TR9401, XCatalog, and OASIS XML Catalog format.
Removes all files from the output directory before running XJC.
Corresponding XJC parameter: enableIntrospection.
Enable correct generation of Boolean getters/setters to enable Bean Introspection APIs.
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):
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>
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.
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>
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>
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).
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.
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>
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.
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.
Corresponding XJC parameter: d.
The working directory where the generated Java source files are created.
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".
Corresponding XJC parameter: quiet.
Suppress compiler output, such as progress information and warnings.
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.
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.
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>
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.)
Corresponding XJC parameter: verbose.
Tells XJC to be extra verbose, such as printing informational messages or displaying stack traces.
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.
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>
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:
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.
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.