Fork me on GitHub

jaxb2:testSchemagen

Full name:

org.codehaus.mojo:jaxb2-maven-plugin:2.2:testSchemagen

Description:

Mojo that creates XML schema(s) from test-scope Java testSources or binaries by invoking the JAXB SchemaGenerator. This implementation is tailored to use the JAXB Reference Implementation from project Kenai.

Note that the TestSchemaGenerationMojo was completely re-implemented for the 2.x versions. Its configuration semantics and parameter set is not 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: test.
  • The goal is thread-safe and supports parallel builds.
  • Binds by default to the lifecycle phase: generate-test-resources.

Required Parameters

Name Type Since Description
outputDirectory File -

The directory where the generated XML Schema file(s) will be placed.


Default value is: ${project.build.directory}/generated-test-resources/schemagen.
testWorkDirectory File -

The directory where the schemagen tool will output XSDs, episode files - and intermediary bytecode files. From this directory the XSDs and the episode file (but not the bytecode files) will be copied to the outputDirectory for further processing.


Default value is: ${project.build.directory}/schemagen-work/test_scope.

Optional Parameters

Name Type Since Description
clearOutputDir boolean 2.0

Removes all files from the output directory before running SchemaGenerator.


Default value is: true.
createJavaDocAnnotations boolean 2.0

If true, Elements or Attributes in the generated XSD files will be annotated with any JavaDoc found for their respective properties. If false, no XML documentation annotations will be generated in post-processing any results from the JAXB SchemaGenerator.


Default value is: true.
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}.
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>
    

generateEpisode boolean 2.0

Corresponding SchemaGen parameter: episode.

Generate an episode file from this XSD generation, 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.
javaDocRenderer JavaDocRenderer 2.0

A renderer used to create XML annotation text from JavaDoc comments found within the source code. Unless another implementation is provided, the standard JavaDocRenderer used is DefaultJavaDocRenderer.


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>
    

testSchemaSourceExcludeFilters List -

Parameter holding a List of Filters, used to match all files under the testSources directories which should not be considered SchemaGenerator testSource files. (The filters identify files to exclude, and hence this parameter is called testSchemaSourceExcludeFilters). If a file under any of the testSource directories matches at least one of the Filters supplied in the testSchemaSourceExcludeFilters, it is not considered an XJC test source file, and therefore excluded from processing.

If not explicitly provided, the Mojo uses the value within STANDARD_TEST_SOURCE_EXCLUDE_FILTERS. The algorithm for finding XJC sources is as follows:

  1. Find all files given in the testSources List. Any Directories provided are searched for files recursively.
  2. Exclude any found files matching any of the supplied testSchemaSourceExcludeFilters List.
  3. The remaining Files are submitted for processing by the XJC tool.

Example: The following configuration would exclude any testSources whose names end with .txt or .foo:

    
       <configuration>
        ...
             <testSchemaSourceExcludeFilters>
                 <filter implementation="org.codehaus.mojo.jaxb2.shared.filters.pattern.PatternFileFilter">
                     <patterns>
                         <pattern>\.txt</pattern>
                         <pattern>\.foo</pattern>
                     </patterns>
                 </filter>
             </testSchemaSourceExcludeFilters>
        </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.


testSources List 2.0

Parameter holding List of paths to files and/or directories which should be recursively searched for Java source files. Only files or directories that actually exist will be included (in the case of files) or recursively searched for source files to include (in the case of directories or JARs). Configure using standard Maven structure for Lists:


 <configuration>
  ...
      <testSources>
         <testSource>/a/full/absolute/path/to/a/SourceFile.java</testSource>
         <testSource>target/some/sourceJar.jar</test>
         <testSource>src/test/java</test>
     </testSources>
  </configuration>

Note: if configured, the sources parameters replace the default value, which is a List containing the paths to the directories defined by getProject().getBuild().getTestSourceDirectory().


transformSchemas List 1.4

A List holding desired schema mappings, each of which binds a schema namespace URI to its desired prefix [optional] and the name of the resulting schema file [optional]. All given elements (uri, prefix, file) must be unique within the configuration; no two elements may have the same values.

The example schema configuration below maps two namespace uris to prefixes and generated file names. This implies that http://some/namespace will be represented by the prefix some within the generated XML Schema files; creating namespace definitions on the form xmlns:some="http://some/namespace", and corresponding uses on the form <xs:element minOccurs="0" ref="some:anOptionalElementInSomeNamespace"/>. Moreover, the file element defines that the http://some/namespace definitions will be written to the file some_schema.xsd, and that all import references will be on the form <xs:import namespace="http://some/namespace" schemaLocation="some_schema.xsd"/>

The example configuration below also performs identical operations for the namespace uri http://another/namespace with the prefix another and the file another_schema.xsd.

    
<transformSchemas>
  <transformSchema>
    <uri>http://some/namespace</uri>
    <toPrefix>some</toPrefix>
    <toFile>some_schema.xsd</toFile>
  <transformSchema>
    <uri>http://another/namespace</uri>
    <toPrefix>another</toPrefix>
    <toFile>another_schema.xsd</toFile>
  </transformSchema>
</transformSchemas>
    

Parameter Details

clearOutputDir:

Removes all files from the output directory before running SchemaGenerator.

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

createJavaDocAnnotations:

If true, Elements or Attributes in the generated XSD files will be annotated with any JavaDoc found for their respective properties. If false, no XML documentation annotations will be generated in post-processing any results from the JAXB SchemaGenerator.

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

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}

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

generateEpisode:

Corresponding SchemaGen parameter: episode.

Generate an episode file from this XSD generation, 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

javaDocRenderer:

A renderer used to create XML annotation text from JavaDoc comments found within the source code. Unless another implementation is provided, the standard JavaDocRenderer used is DefaultJavaDocRenderer.

  • Type: org.codehaus.mojo.jaxb2.schemageneration.postprocessing.javadoc.JavaDocRenderer
  • Since: 2.0
  • Required: No

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

outputDirectory:

The directory where the generated XML Schema file(s) will be placed.

  • Type: java.io.File
  • Required: Yes
  • Default: ${project.build.directory}/generated-test-resources/schemagen

testSchemaSourceExcludeFilters:

Parameter holding a List of Filters, used to match all files under the testSources directories which should not be considered SchemaGenerator testSource files. (The filters identify files to exclude, and hence this parameter is called testSchemaSourceExcludeFilters). If a file under any of the testSource directories matches at least one of the Filters supplied in the testSchemaSourceExcludeFilters, it is not considered an XJC test source file, and therefore excluded from processing.

If not explicitly provided, the Mojo uses the value within STANDARD_TEST_SOURCE_EXCLUDE_FILTERS. The algorithm for finding XJC sources is as follows:

  1. Find all files given in the testSources List. Any Directories provided are searched for files recursively.
  2. Exclude any found files matching any of the supplied testSchemaSourceExcludeFilters List.
  3. The remaining Files are submitted for processing by the XJC tool.

Example: The following configuration would exclude any testSources whose names end with .txt or .foo:

    
       <configuration>
        ...
             <testSchemaSourceExcludeFilters>
                 <filter implementation="org.codehaus.mojo.jaxb2.shared.filters.pattern.PatternFileFilter">
                     <patterns>
                         <pattern>\.txt</pattern>
                         <pattern>\.foo</pattern>
                     </patterns>
                 </filter>
             </testSchemaSourceExcludeFilters>
        </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

testSources:

Parameter holding List of paths to files and/or directories which should be recursively searched for Java source files. Only files or directories that actually exist will be included (in the case of files) or recursively searched for source files to include (in the case of directories or JARs). Configure using standard Maven structure for Lists:


 <configuration>
  ...
      <testSources>
         <testSource>/a/full/absolute/path/to/a/SourceFile.java</testSource>
         <testSource>target/some/sourceJar.jar</test>
         <testSource>src/test/java</test>
     </testSources>
  </configuration>

Note: if configured, the sources parameters replace the default value, which is a List containing the paths to the directories defined by getProject().getBuild().getTestSourceDirectory().

  • Type: java.util.List
  • Since: 2.0
  • Required: No

testWorkDirectory:

The directory where the schemagen tool will output XSDs, episode files - and intermediary bytecode files. From this directory the XSDs and the episode file (but not the bytecode files) will be copied to the outputDirectory for further processing.

  • Type: java.io.File
  • Required: Yes
  • Default: ${project.build.directory}/schemagen-work/test_scope

transformSchemas:

A List holding desired schema mappings, each of which binds a schema namespace URI to its desired prefix [optional] and the name of the resulting schema file [optional]. All given elements (uri, prefix, file) must be unique within the configuration; no two elements may have the same values.

The example schema configuration below maps two namespace uris to prefixes and generated file names. This implies that http://some/namespace will be represented by the prefix some within the generated XML Schema files; creating namespace definitions on the form xmlns:some="http://some/namespace", and corresponding uses on the form <xs:element minOccurs="0" ref="some:anOptionalElementInSomeNamespace"/>. Moreover, the file element defines that the http://some/namespace definitions will be written to the file some_schema.xsd, and that all import references will be on the form <xs:import namespace="http://some/namespace" schemaLocation="some_schema.xsd"/>

The example configuration below also performs identical operations for the namespace uri http://another/namespace with the prefix another and the file another_schema.xsd.

    
<transformSchemas>
  <transformSchema>
    <uri>http://some/namespace</uri>
    <toPrefix>some</toPrefix>
    <toFile>some_schema.xsd</toFile>
  <transformSchema>
    <uri>http://another/namespace</uri>
    <toPrefix>another</toPrefix>
    <toFile>another_schema.xsd</toFile>
  </transformSchema>
</transformSchemas>
    
  • Type: java.util.List
  • Since: 1.4
  • Required: No