jaxb2:xjc

Full name:

org.codehaus.mojo:jaxb2-maven-plugin:2.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.

Attributes:

  • Requires a Maven project to be executed.
  • Requires dependency resolution of artifacts in scope: compile.
  • Since version: 2.0.
  • Binds by default to the lifecycle phase: generate-sources.

Required Parameters

Name Type Since Description
outputDirectory File 2.0

Corresponding XJC parameter: d.

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: 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 2.0

Corresponding XJC parameter: catalog.

Specify catalog files to resolve external entity references. Supports TR9401, XCatalog, and OASIS XML Catalog format.


clearOutputDir boolean 2.0

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):

  1. If the configuration property is explicitly given within the plugin's configuration, use that value.
  2. If the Maven property project.build.sourceEncoding is defined, use its value.
  3. Otherwise use the value from the system property file.encoding.



Default value is: ${project.build.sourceEncoding}.
extension boolean 2.0

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: false.
failOnNoSchemas boolean 1.3 Fails the Mojo execution if no XSDs/schemas are found.
Default value is: true.
generateEpisode boolean 2.0

Corresponding XJC parameter: episode.

Generate an episode file from this 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 really just a JAXB customization file (but with vendor extensions.)

If this parameter is true, the episode file generated is called META-INF/sun-jaxb.episode, and included in the artifact.


Default value is: true.
httpproxy String 2.0

Corresponding XJC parameter: httpproxy.

Set HTTP/HTTPS proxy to be used by the XJC, on the format [user[:password]@]proxyHost[:proxyPort].


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

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 2.0

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 2.0 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 2.0

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 2.0

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 2.0

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 2.0

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 2.0

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:

  1. Find all files given in the sources List. Any Directories provided are searched for files recursively.
  2. Exclude any found files matching any of the supplied xjcSourceExcludeFilters List.
  3. 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.


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.


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:

Deprecated. This should be removed in the 2.0+ release, as all arguments should be handled by other parameters.

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
  • Since: 2.0
  • Required: No

clearOutputDir:

Removes all files from the output directory before running XJC.

  • Type: boolean
  • Since: 2.0
  • 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):

  1. If the configuration property is explicitly given within the plugin's configuration, use that value.
  2. If the Maven property project.build.sourceEncoding is defined, use its value.
  3. Otherwise use the value from the system property file.encoding.


  • Type: java.lang.String
  • Since: 2.0
  • Required: No
  • Default: ${project.build.sourceEncoding}

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
  • Since: 2.0
  • Required: No
  • Default: false

failOnNoSchemas:

Fails the Mojo execution if no XSDs/schemas are found.
  • Type: boolean
  • Since: 1.3
  • Required: No
  • Default: true

generateEpisode:

Corresponding XJC parameter: episode.

Generate an episode file from this 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 really just a JAXB customization file (but with vendor extensions.)

If this parameter is true, the episode file generated is called META-INF/sun-jaxb.episode, and included in the artifact.

  • Type: boolean
  • Since: 2.0
  • Required: No
  • Default: true

httpproxy:

Corresponding XJC parameter: httpproxy.

Set HTTP/HTTPS proxy to be used by the XJC, on the format [user[:password]@]proxyHost[:proxyPort].

  • Type: java.lang.String
  • Since: 2.0
  • Required: No

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

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
  • Since: 2.0
  • 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
  • Since: 2.0
  • Required: No

quiet:

Corresponding XJC parameter: quiet.

Suppress compiler output, such as progress information and warnings.

  • Type: boolean
  • Since: 2.0
  • 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:

Indicate if the XjcMojo execution should be skipped.
  • Type: boolean
  • Since: 2.0
  • 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
  • Since: 2.0
  • 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
  • Since: 2.0
  • 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
  • Since: 2.0
  • 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
  • Since: 2.0
  • 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:

  1. Find all files given in the sources List. Any Directories provided are searched for files recursively.
  2. Exclude any found files matching any of the supplied xjcSourceExcludeFilters List.
  3. 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
  • Since: 2.0
  • 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