jaxb2:schemagen
Full name:
org.codehaus.mojo:jaxb2-maven-plugin:3.1.0:schemagen
Description:
Mojo that creates XML schema(s) from compile-scope Java sources or binaries by invoking the JAXB SchemaGenerator. This implementation is tailored to use the JAXB Reference Implementation from project Kenai.
Note that the SchemaGenerationMojo 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-resources
.
Required Parameters
Name | Type | Since | Description |
---|---|---|---|
<outputDirectory> |
File |
- |
The directory where the generated XML Schema file(s) will be placed, after all transformations are done. Default value is: ${project.build.directory}/generated-resources/schemagen . |
<workDirectory> |
File |
- |
The directory where the Default value is: ${project.build.directory}/schemagen-work/compile_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 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:
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 SchemaGen parameter: Generate an episode file with the supplied name 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 simply a JAXB
customization file (but with vendor extensions), normally known as
a binding file with the suffix If the
|
<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
|
<generateEpisode> |
boolean |
2.0 |
Deprecated. No reason given 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
Example (assigns french locale):
|
<schemaSourceExcludeFilters> |
List |
2.0 |
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. |
<sources> |
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:
Note: if configured, the sources parameters
replace the default value, which is a List containing the paths to
the directories defined by
|
<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
The example configuration below also performs identical
operations for the namespace uri
|
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):
- 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 SchemaGen parameter: episode
.
Generate an episode file with the supplied name 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 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_schemagen.xjb, but it depends on the actual ID
given in the execution element:
<executions>
<execution>
<id>schemagen</id>
<goals>
<goal>schemagen</goal>
</goals>
</execution>
</executions>
- Type:
java.lang.String
- Since:
2.4
- Required:
No
<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>
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
<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, after all transformations are done.
- Type:
java.io.File
- Required:
Yes
- Default:
${project.build.directory}/generated-resources/schemagen
<schemaSourceExcludeFilters>
Parameter holding a List of Filters, used to match all files
under the sources
directories which should
not be considered SchemaGenerator source files.
(The filters identify files to exclude, and hence this parameter is
called schemaSourceExcludeFilters
). If a file under
any of the source directories matches at least one of the Filters
supplied in the schemaSourceExcludeFilters
, 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
schemaSourceExcludeFilters
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>
...
<schemaSourceExcludeFilters>
<filter implementation="org.codehaus.mojo.jaxb2.shared.filters.pattern.PatternFileFilter">
<patterns>
<pattern>\.txt</pattern>
<pattern>\.foo</pattern>
</patterns>
</filter>
</schemaSourceExcludeFilters>
</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
<sources>
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>
...
<sources>
<source>/a/full/absolute/path/to/a/SourceFile.java</source>
<source>target/some/sourceJar.jar</source>
<source>src/main/java</source>
</sources>
</configuration>
Note: if configured, the sources parameters
replace the default value, which is a List containing the paths to
the directories defined by
getProject().getCompileSourceRoots()
.
- Type:
java.util.List
- Since:
2.0
- Required:
No
<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
<workDirectory>
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/compile_scope