Class AbstractXsdGeneratorMojo

  • All Implemented Interfaces:
    org.apache.maven.plugin.ContextEnabled, org.apache.maven.plugin.Mojo
    Direct Known Subclasses:
    SchemaGenerationMojo, TestSchemaGenerationMojo

    public abstract class AbstractXsdGeneratorMojo
    extends AbstractJaxbMojo

    Abstract superclass for Mojos that generate XSD files from annotated Java Sources. This Mojo delegates execution to the schemagen tool to perform the XSD file generation. Moreover, the AbstractXsdGeneratorMojo provides an augmented processing pipeline by optionally letting a set of NodeProcessors improve the 'vanilla' XSD files.

    See Also:
    The JAXB Reference Implementation
    • Field Detail

      • SCHEMAGEN_EMITTED_FILENAME

        public static final java.util.regex.Pattern SCHEMAGEN_EMITTED_FILENAME

        Pattern matching the names of files emitted by the JAXB/JDK SchemaGenerator. According to the JAXB Schema Generator documentation:

        There is no way to control the name of the generated schema files at this time.
      • STANDARD_JAVADOC_RENDERER

        public static final JavaDocRenderer STANDARD_JAVADOC_RENDERER

        The default JavaDocRenderer used unless another JavaDocRenderer should be used.

        Since:
        2.0
        See Also:
        javaDocRenderer
      • STANDARD_BYTECODE_EXCLUDE_FILTERS

        public static final java.util.List<Filter<java.io.File>> STANDARD_BYTECODE_EXCLUDE_FILTERS

        Default exclude file name suffixes for testSources, used unless overridden by an explicit configuration in the testSourceExcludeSuffixes parameter.

             
                 final List<Filter<File>> schemagenTmp = new ArrayList<Filter<File>>();
                 schemagenTmp.addAll(AbstractJaxbMojo.STANDARD_EXCLUDE_FILTERS);
                 schemagenTmp.add(new PatternFileFilter(Arrays.asList("\\.java", "\\.scala", "\\.mdo"), false));
                 STANDARD_BYTECODE_EXCLUDE_FILTERS = Collections.unmodifiableList(schemagenTmp);
             
         
      • CLASS_INCLUDE_FILTERS

        public static final java.util.List<Filter<java.io.File>> CLASS_INCLUDE_FILTERS
        Filter list containing a PatternFileFilter including ".class" files.
      • SYSTEM_TOOLS_CLASSLOADER_PACKAGES

        public static final java.util.List<java.lang.String> SYSTEM_TOOLS_CLASSLOADER_PACKAGES
        Specification for packages which must be loaded using the SystemToolClassLoader (and not in the plugin's ThreadContext ClassLoader). The SystemToolClassLoader is used by SchemaGen to process some stuff from the tools.jar archive, in particular its exception types used to signal JAXB annotation Exceptions.
        See Also:
        ToolProvider.getSystemToolClassLoader()
      • SCHEMAGEN_INCORRECT_OPTIONS

        private static final int SCHEMAGEN_INCORRECT_OPTIONS
        See Also:
        Constant Field Values
      • SCHEMAGEN_COMPLETED_OK

        private static final int SCHEMAGEN_COMPLETED_OK
        See Also:
        Constant Field Values
      • transformSchemas

        @Parameter
        private java.util.List<TransformSchema> 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>
             
         
        Since:
        1.4
      • generateEpisode

        @Deprecated
        @Parameter(defaultValue="true")
        protected boolean generateEpisode
        Deprecated.
        Deprecated - will be removed in a future release

        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 AbstractJaxbMojo.STANDARD_EPISODE_FILENAME).

        Since:
        2.0
      • episodeFileName

        @Parameter
        protected java.lang.String 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>
              
         
        Since:
        2.4
        See Also:
        AbstractJaxbMojo.STANDARD_EPISODE_FILENAME
      • createJavaDocAnnotations

        @Parameter(defaultValue="true")
        protected boolean 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.

        Since:
        2.0
      • javaDocRenderer

        @Parameter
        protected JavaDocRenderer 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.

        Since:
        2.0
        See Also:
        DefaultJavaDocRenderer
      • clearOutputDir

        @Parameter(defaultValue="true")
        protected boolean clearOutputDir

        Removes all files from the output directory before running SchemaGenerator.

        Since:
        2.0
    • Constructor Detail

      • AbstractXsdGeneratorMojo

        public AbstractXsdGeneratorMojo()
    • Method Detail

      • shouldExecutionBeSkipped

        protected boolean shouldExecutionBeSkipped()

        XSD schema files are not generated from POM projects or if no includes have been supplied.

        Implement this method to check if this AbstractJaxbMojo should skip executing altogether.
        Specified by:
        shouldExecutionBeSkipped in class AbstractJaxbMojo
        Returns:
        true to indicate that this AbstractJaxbMojo should bail out of its execute method.
      • isReGenerationRequired

        protected boolean isReGenerationRequired()
        Specified by:
        isReGenerationRequired in class AbstractJaxbMojo
        Returns:
        true to indicate that this AbstractJaxbMojo should be run since its generated files were either stale or not present, and false otherwise.
      • performExecution

        protected boolean performExecution()
                                    throws org.apache.maven.plugin.MojoExecutionException,
                                           org.apache.maven.plugin.MojoFailureException

        Implement this method to perform this Mojo's execution. This method will only be called if !shouldExecutionBeSkipped() && isReGenerationRequired().

        Specified by:
        performExecution in class AbstractJaxbMojo
        Returns:
        true if the timestamp of the stale file should be updated.
        Throws:
        org.apache.maven.plugin.MojoExecutionException - if an unexpected problem occurs. Throwing this exception causes a "BUILD ERROR" message to be displayed.
        org.apache.maven.plugin.MojoFailureException - if an expected problem (such as a compilation failure) occurs. Throwing this exception causes a "BUILD FAILURE" message to be displayed.
      • getWorkDirectory

        protected abstract java.io.File getWorkDirectory()
        Returns:
        The working directory to which the SchemaGenerator should initially copy all its generated files, including bytecode files, compiled from java sources.
      • getCompiledClassNames

        protected abstract java.util.List<java.net.URL> getCompiledClassNames()
        Finds a List containing URLs to compiled bytecode files within this Compilation Unit. Typically this equals the resolved files under the project's build directories, plus any JAR artifacts found on the classpath.
        Returns:
        A non-null List containing URLs to bytecode files within this compilation unit. Typically this equals the resolved files under the project's build directories, plus any JAR artifacts found on the classpath.
      • getSources

        protected abstract java.util.List<java.net.URL> getSources()
        Override this method to acquire a List holding all URLs to the SchemaGen Java sources for which this AbstractXsdGeneratorMojo should generate Xml Schema Descriptor files.
        Specified by:
        getSources in class AbstractJaxbMojo
        Returns:
        A non-null List holding URLs to sources for the XSD generation.
      • getSchemaGenArguments

        private java.lang.String[] getSchemaGenArguments​(java.lang.String classPath,
                                                         java.io.File episodeFile,
                                                         java.util.List<java.net.URL> sources)
                                                  throws org.apache.maven.plugin.MojoExecutionException
        Throws:
        org.apache.maven.plugin.MojoExecutionException
      • getSchemaGeneratorSourceFiles

        private java.util.List<java.lang.String> getSchemaGeneratorSourceFiles​(java.util.List<java.net.URL> sources)
                                                                        throws java.io.IOException,
                                                                               org.apache.maven.plugin.MojoExecutionException

        The SchemaGenerator does not support directories as arguments, implying we must resolve source files in the compilation unit. This fact is shown when supplying a directory argument as source, when the tool emits:

        Caused by: java.lang.IllegalArgumentException: directories not supported

        There seems to be two ways of adding sources to the SchemaGen tool:

        1. Java Source files
        Define the relative paths to source files, calculated from the System.property user.dir (i.e. not the Maven basedir property) on the form src/main/java/se/west/something/SomeClass.java.
        Sample: javac -d . . ./github_jaxb2_plugin/src/it/schemagen-main/src/main/java/se/west/gnat/Foo.java
        2. Bytecode files
        Define the CLASSPATH to point to build output directories (such as target/classes), and then use package notation arguments on the form se.west.something.SomeClass.
        Sample: schemagen -d . -classpath brat se.west.gnat.Foo

        The jaxb2-maven-plugin uses these two methods in the order given

        Parameters:
        sources - The compiled sources (as calculated from the local project's source paths, getSources()).
        Returns:
        A sorted List holding all sources to be used by the SchemaGenerator. According to the SchemaGenerator documentation, the order in which the source arguments are provided is irrelevant. The sources are to be rendered as the final (open-ended) argument to the schemagen execution.
        Throws:
        java.io.IOException
        org.apache.maven.plugin.MojoExecutionException
        See Also:
        getSources()
      • printSchemaGenCommandAndThrowException

        private void printSchemaGenCommandAndThrowException​(java.lang.String projectBasedirPath,
                                                            java.util.List<java.net.URL> sources,
                                                            java.lang.String[] schemaGenArguments,
                                                            int result,
                                                            java.lang.Throwable cause)
                                                     throws org.apache.maven.plugin.MojoExecutionException
        Throws:
        org.apache.maven.plugin.MojoExecutionException