Class AbstractGenerateMojo

java.lang.Object
org.apache.maven.plugin.AbstractMojo
io.github.ascopes.protobufmavenplugin.mojo.AbstractGenerateMojo
All Implemented Interfaces:
org.apache.maven.plugin.ContextEnabled, org.apache.maven.plugin.Mojo
Direct Known Subclasses:
MainGenerateMojo, TestGenerateMojo
public abstract class AbstractGenerateMojo extends org.apache.maven.plugin.AbstractMojo
Abstract base for a code generation Mojo that calls protoc.
Author:
Ashley Scopes

  • Field Details

    • DEFAULT_FALSE

      private static final String DEFAULT_FALSE
      See Also:

    • DEFAULT_TRUE

      private static final String DEFAULT_TRUE
      See Also:

    • DEFAULT_TRANSITIVE

      private static final String DEFAULT_TRANSITIVE
      See Also:

    • PROTOBUF_COMPILER_EXCLUDES

      private static final String PROTOBUF_COMPILER_EXCLUDES
      See Also:

    • PROTOBUF_COMPILER_INCLUDES

      private static final String PROTOBUF_COMPILER_INCLUDES
      See Also:

    • PROTOBUF_COMPILER_INCREMENTAL

      private static final String PROTOBUF_COMPILER_INCREMENTAL
      See Also:

    • PROTOBUF_COMPILER_VERSION

      private static final String PROTOBUF_COMPILER_VERSION
      See Also:

    • PROTOBUF_SKIP

      private static final String PROTOBUF_SKIP
      See Also:

    • log

      private static final org.slf4j.Logger log

    • sourceCodeGenerator

      @Inject ProtobufBuildOrchestrator sourceCodeGenerator
      The source code generator.

    • mavenProject

      @Inject org.apache.maven.project.MavenProject mavenProject
      The active Maven project.

    • mavenProjectHelper

      @Inject org.apache.maven.project.MavenProjectHelper mavenProjectHelper
      The active MavenProjectHelper.

    • binaryMavenPlugins

      @Parameter @Nullable List<MavenProtocPluginBean> binaryMavenPlugins
      Binary plugins to use with the protobuf compiler, sourced from a Maven repository.

      Plugin artifacts must be a native executable. By default, the OS and CPU architecture is automatically generated and injected in the classifier if the classifier and type are not provided explicitly.

      For example: 

      
 <binaryMavenPlugins>
   <binaryMavenPlugin>
     <groupId>com.salesforce.servicelibs</groupId>
     <artifactId>reactor-grpc</artifactId>
     <version>1.2.4</version>
   </binaryMavenPlugin>
 </binaryMavenPlugins>

      If you have a Java-based plugin that does not distribute a native executable, or are using a more obscure system architecture, then using a jvmMavenPlugin may be more preferable.

      Objects support the following attributes:

      • groupId - the group ID - required
      • artifactId - the artifact ID - required
      • version - the version - required
      • type - the artifact type - optional
      • classifier - the artifact classifier - optional
      • options - a string of options to pass to the plugin - optional.
      • order - an integer order to run the plugins in. Defaults to 0. Higher numbers run later than lower numbers. The built-in code generators in protoc and descriptor generation has an order of 0.
      • skip - set to true to skip invoking this plugin - useful if you want to control whether the plugin runs via a property - optional.
      Since:
      0.3.0

    • binaryPathPlugins

      @Parameter @Nullable List<PathProtocPluginBean> binaryPathPlugins
      Binary plugins to use with the protobuf compiler, sourced from the system PATH.

      For example: 

      
 <binaryPathPlugins>
   <binaryPathPlugin>
     <name>protoc-gen-grpc-java</name>
   </binaryPathPlugin>
   <binaryPathPlugin>
     <name>protoc-gen-something-else</name>
     <options>foo=bar,baz=bork</options>
   </binaryPathPlugin>
 </binaryPathPlugins>

      Objects support the following attributes:

      • name - the name of the binary to resolve.
      • options - a string of options to pass to the plugin - optional.
      • order - an integer order to run the plugins in. Defaults to 0. Higher numbers run later than lower numbers. The built-in code generators in protoc and descriptor generation has an order of 0.
      • skip - set to true to skip invoking this plugin - useful if you want to control whether the plugin runs via a property - optional.

      On Linux, macOS, and other POSIX-like systems, resolution looks for an executable binary matching the exact name in any directory in the $PATH environment variable.

      On Windows, the case-insensitive %PATH% environment variable is searched for an executable that matches the name, ignoring case and any file extension. The file extension is expected to match any extension in the %PATHEXT% environment variable.

      Since:
      2.0.0

    • binaryUrlPlugins

      @Parameter @Nullable List<UrlProtocPluginBean> binaryUrlPlugins
      Binary plugins to use with the protobuf compiler, specified as a valid URL.

      This includes support for:

      • Local file system objects, specified using file://path/to/file
      • HTTP resources, specified using http://example.website/path/to/file
      • HTTPS resources, specified using https://example.website/path/to/file
      • FTP resources, specified using ftp://example.server/path/to/file

      Additionally, the jar protocol can be used with any of the above to enable extracting a file from a JAR or ZIP and using it directly.

      For example: 

      
 <binaryUrlPlugins>
   <!-- FTP resource -->
   <binaryUrlPlugin>
     <url>ftp://myorganisation.org/protoc/plugins/myplugin.exe</url>
   </binaryUrlPlugin>

   <!-- HTTP resource with custom options-->
   <binaryUrlPlugin>
     <url>https://myorganisation.org/protoc/plugins/myplugin2.exe</url>
     <options>foo=bar,baz=bork</options>
   </binaryUrlPlugin>

   <!-- HTTP resource that is a ZIP holding the binary we want. -->
   <binaryUrlPlugin>
     <url>jar:https://myorganisation.org/protoc/plugins/myplugin3.zip!/protoc-gen-something.exe</url>
   </binaryUrlPlugin>
 </binaryUrlPlugins>

      Objects support the following attributes:

      • url - the URL to resolve.
      • options - a string of options to pass to the plugin - optional.
      • order - an integer order to run the plugins in. Defaults to 0. Higher numbers run later than lower numbers. The built-in code generators in protoc and descriptor generation has an order of 0.
      • skip - set to true to skip invoking this plugin - useful if you want to control whether the plugin runs via a property - optional.
      Since:
      2.0.0

    • cppEnabled

      @Parameter(defaultValue="false") boolean cppEnabled
      Enable generating C++ sources and headers from the protobuf sources.
      Since:
      1.1.0

    • csharpEnabled

      @Parameter(defaultValue="false") boolean csharpEnabled
      Enable generating C# sources from the protobuf sources.
      Since:
      1.1.0

    • dependencyResolutionDepth

      @Parameter(defaultValue="TRANSITIVE") DependencyResolutionDepth dependencyResolutionDepth
      The scope to resolve dependencies with.

      Supported values:

      • TRANSITIVE - resolve all dependencies.
      • DIRECT - only resolve dependencies that were explicitly specified.
      Since:
      1.2.0

    • dependencyScopes

      @Parameter @Nullable Set<String> dependencyScopes
      The dependency scopes to resolve dependencies for.
      Since:
      2.4.0

    • embedSourcesInClassOutputs

      @Parameter(defaultValue="false") boolean embedSourcesInClassOutputs
      Set whether to attach all compiled protobuf sources to the output of this Maven project so that they are included in any generated JAR.

      Note that if you are using dependencies as sources, then those will also be attached, and may have license implications. Therefore, this will default to false.

      Since:
      2.1.0

    • excludes

      @Parameter(property="protobuf.compiler.excludes") @Nullable List<String> excludes
      Source paths to exclude from compilation.

      This can be used to limit what is compiled by protoc.

      Each entry is treated as a glob pattern, and is applied to the path of each discovered compilation candidate file, relative to the sourceDirectory or sourceDependency that provides them.

      See java.nio.file.FileSystem#getPathMatcher for full details of the supported syntax within glob patterns.

      If a file matches any of these patterns, it is automatically excluded.

      If not provided, then the default is to not exclude anything.

      For example, if you wanted to not compile files named user.proto, message.proto, or service.proto, you could use the following configuration. 

      <excludes>
   <exclude>**/user.proto</exclude>
   <exclude>**/message.proto</exclude>
   <exclude>**/service.proto</exclude>
 </excludes>

      Use includes if you wish to instead include files for compilation.

      Since:
      2.2.0

    • failOnInvalidDependencies

      @Parameter(defaultValue="false") boolean failOnInvalidDependencies
      Whether to fail if any invalid direct or transitive dependencies are encountered.

      If true, the build will be aborted with an error if any invalid dependency is encountered.

      If false, then the build will report any invalid dependencies as errors in the logs, before proceeding with the build. Any invalid dependencies will be discarded.

      Prior to v2.4.0, any invalid dependencies would result in an error being raised and the build being aborted. In v2.4.0, this has been relaxed.

      Since:
      2.4.0

    • failOnMissingSources

      @Parameter(defaultValue="true") boolean failOnMissingSources
      Whether to fail on missing sources.

      If no sources are detected, it is usually a sign that this plugin is misconfigured, or that you are including this plugin in a project that does not need it. For this reason, the plugin defaults this setting to being enabled. If you wish to not fail, you can explicitly set this to false instead.

      Since:
      0.5.0

    • failOnMissingTargets

      @Parameter(defaultValue="true") boolean failOnMissingTargets
      Whether to fail if no output languages and no plugins are enabled.

      This defaults to true, but may be set to false if all plugins are optional and no languages are enabled.

      Since:
      2.0.0

    • fatalWarnings

      @Parameter(defaultValue="false") boolean fatalWarnings
      Specify that any warnings emitted by protoc should be treated as errors and fail the build.

      Defaults to false.

      Since:
      0.0.1

    • ignoreProjectDependencies

      @Parameter(defaultValue="false") boolean ignoreProjectDependencies
      Whether to ignore the <dependencies/> blocks in the Maven project when discovering *.proto files to add to the import paths.

      Generally you will want to leave this enabled unless you have a very specific case where you wish to take control of how dependency resolution works.

      Since:
      1.2.0

    • importDependencies

      @Parameter @Nullable List<MavenDependencyBean> importDependencies
      Specify additional dependencies to import protobuf sources from.

      These will not be compiled into Java sources directly.

      Objects support the following attributes:

      • groupId - the group ID - required
      • artifactId - the artifact ID - required
      • version - the version - required
      • type - the artifact type - optional
      • classifier - the artifact classifier - optional
      • dependencyResolutionDepth - the dependency resolution depth to override the project settings with - optional
      • excludes - a set of exclusions to apply to transitive dependencies

      Exclusions are a set of objects, each with the following fields:

      • groupId - the group ID to exclude
      • artifactId - the artifact ID to exclude
      • classifier - optional - the classifier to exclude. If omitted, any classifiers are matched.
      • type - optional - the type of the artifact to exclude. If omitted, any types are matched.
      Since:
      1.2.0

    • importPaths

      @Parameter @Nullable List<File> importPaths
      Specify additional paths to import protobuf sources from on the local file system.

      These will not be compiled into Java sources directly.

      If you wish to depend on a JAR containing protobuf sources, add it as a dependency with the provided or test scope instead, or use importDependencies.

      Since:
      0.1.0

    • includes

      @Parameter(property="protobuf.compiler.includes") @Nullable List<String> includes
      Source paths to include in compilation.

      This can be used to limit what is compiled by protoc.

      Each entry is treated as a glob pattern, and is applied to the path of each discovered compilation candidate file, relative to the sourceDirectory or sourceDependency that provides them

      See java.nio.file.FileSystem#getPathMatcher for full details of the supported syntax within glob patterns.

      If a file matches any of these patterns, it is automatically included.

      If not provided, then the default is to allow any Protobuf source file.

      For example, if you only wanted to compile files named user.proto, message.proto, or service.proto, you could use the following configuration. 

      <includes>
   <include>**/user.proto</include>
   <include>**/message.proto</include>
   <include>**/service.proto</include>
 </includes>

      Use excludes if you wish to instead omit files from compilation.

      Since:
      2.2.0

    • incrementalCompilation

      @Parameter(defaultValue="true", property="protobuf.compiler.incremental") boolean incrementalCompilation
      Whether to enable "incremental" compilation.

      When enabled, this plugin will track changes to sources and importable protobuf dependencies between builds, making a best-effort attempt to only rebuild files when changes have been made since the last build.

      Since:
      2.7.0

    • javaEnabled

      @Parameter(defaultValue="true") boolean javaEnabled
      Enable generating Java sources from the protobuf sources.

      Defaults to true, although some users may wish to disable this if using an alternative plugin that covers generating the code for models instead.

      Since:
      0.1.1

    • jvmMavenPlugins

      @Parameter @Nullable List<MavenProtocPluginBean> jvmMavenPlugins
      Additional pure-Java plugins to use with the protobuf compiler.

      Unlike artifact-based plugins, these are pure Java JAR applications that abide by the protoc compiler API, and will be provided to the compiler via generated scripts.

      For example: 

      
 <jvmMavenPlugins>
   <jvmMavenPlugin>
     <groupId>com.salesforce.servicelibs</groupId>
     <artifactId>reactor-grpc</artifactId>
     <version>1.2.4</version>
   </jvmMavenPlugin>
 </jvmMavenPlugins>

      This mechanism allows plugin vendors to implement their plugins in Java and just distribute platform-independent JAR instead.

      Objects support the following attributes:

      • groupId - the group ID - required
      • artifactId - the artifact ID - required
      • version - the version - required
      • type - the artifact type - optional
      • classifier - the artifact classifier - optional
      • options - a string of options to pass to the plugin. This uses the standard protoc interface for specifying options - optional.
      • order - an integer order to run the plugins in. Defaults to 0. Higher numbers run later than lower numbers. The built-in code generators in protoc and descriptor generation has an order of 0.
      • skip - set to true to skip invoking this plugin - useful if you want to control whether the plugin runs via a property - optional.
      • mainClass - if the plugin is not an assembled JAR at the time the protobuf-maven-plugin is run, then you will need to provide the fully qualified class name of the plugin entrypoint here. This is usually only needed if you are creating the JVM plugin within the same project. If the plugin is an assembled JAR, then this option is optional, the Main-Class manifest entry will be used when present if this is not provided.
      • jvmArgs - a list of commandline arguments to pass to the plugin process - optional.
      • jvmConfigArgs - a list of commandline arguments to configure the JVM itself. This is used to control factors such as JIT compilation, JVM properties, heap size, etc. Users should leave this as the default value (which optimises for short-lived processes) unless they know exactly what they are doing - optional.
      Since:
      0.3.0

    • kotlinEnabled

      @Parameter(defaultValue="false") boolean kotlinEnabled
      Enable generating Kotlin API wrapper code around the generated Java code.

      This may require javaEnabled to also be true, otherwise compilation may fail unless other sources are generated to replace the expected Java ones.

      Since:
      0.1.0

    • liteOnly

      @Parameter(defaultValue="false") boolean liteOnly
      Whether to only generate "lite" messages or not.

      These are bare-bones sources that do not contain most of the metadata that regular Protobuf sources contain, and are designed for low-latency/low-overhead scenarios.

      See the protobuf documentation for the pros and cons of this.

      Since:
      0.0.1

    • objcEnabled

      @Parameter(defaultValue="false") boolean objcEnabled
      Enable generating Objective-C sources from the protobuf sources.
      Since:
      1.1.0

    • outputDescriptorFile

      @Parameter @Nullable File outputDescriptorFile
      Defines the file in which to write the protobin descriptor.

      Leave unspecified to disable. Writes a FileDescriptorSet (a protocol buffer, defined in descriptor.proto) containing all the input files in outputDescriptorFile.

      If this is specified, then incremental compilation will always be disabled to prevent issues with inconsistent build results.

      Since:
      2.9.0

    • outputDescriptorAttached

      @Parameter(defaultValue="false") boolean outputDescriptorAttached
      Whether to attach the generated protobin descriptor as a Maven project artifact.

      This is ignored if outputDescriptorFile is not provided.

      Since:
      2.11.0
      See Also:

    • outputDescriptorAttachmentType

      @Parameter @Nullable String outputDescriptorAttachmentType
      Defines the Maven artifact type for the protobin descriptor when attached to the Maven project.

      This is ignored if outputDescriptorAttached is false.

      Since:
      2.11.0
      See Also:

    • outputDescriptorAttachmentClassifier

      @Parameter @Nullable String outputDescriptorAttachmentClassifier
      Defines the Maven artifact classifier for the protobin descriptor when attached to the Maven project.

      This is ignored if outputDescriptorAttached is false.

      Since:
      2.11.0
      See Also:

    • outputDescriptorIncludeImports

      @Parameter(defaultValue="false") boolean outputDescriptorIncludeImports
      Enable including imports in generated protobin descriptor files.

      This is ignored if outputDescriptorFile is not provided.

      Since:
      2.10.0
      See Also:

    • outputDescriptorIncludeSourceInfo

      @Parameter(defaultValue="false") boolean outputDescriptorIncludeSourceInfo
      Enable including source information in generated protobin descriptor files.

      This is ignored if outputDescriptorFile is not provided.

      Since:
      2.10.0
      See Also:

    • outputDescriptorRetainOptions

      @Parameter(defaultValue="false") boolean outputDescriptorRetainOptions
      Enable retaining option details in generated protobin descriptors.

      This is ignored if outputDescriptorFile is not provided.

      Since:
      2.10.0
      See Also:

    • outputDirectory

      @Parameter @Nullable File outputDirectory
      Override the directory to output generated code to.

      Leave unspecified or explicitly null to use the default for the goal. This defaults to the Maven generated sources directory within target/.

      Since:
      0.1.0

    • phpEnabled

      @Parameter(defaultValue="false") boolean phpEnabled
      Enable generating PHP sources from the protobuf sources.
      Since:
      1.1.0

    • protocVersion

      @Parameter(required=true, property="protobuf.compiler.version") String protocVersion
      Specifies where to find protoc or which version to download.

      This usually should correspond to the version of protobuf-java or similar that is in use.

      If set to "PATH", then protoc is resolved from the system path rather than being downloaded. This is useful if you need to use an unsupported architecture/OS, or a development version of protoc.

      You can also specify a URL that points to:

      • Local file system objects, specified using file://path/to/file
      • HTTP resources, specified using http://example.website/path/to/file
      • HTTPS resources, specified using https://example.website/path/to/file
      • FTP resources, specified using ftp://example.server/path/to/file

      Note that specifying -Dprotobuf.compiler.version in the MAVEN_OPTS or on the command line overrides the version specified in the POM. This enables users to easily override the version of protoc in use if their system is unable to support the version specified in the POM. Termux users in particular will find -Dprotobuf.compiler.version=PATH to be useful, due to platform limitations with libpthread that can result in SIGSYS (Bad System Call) being raised.

      Path resolution on Linux, macOS, and other POSIX-like systems, resolution looks for an executable binary matching the exact name in any directory in the $PATH environment variable.

      Path resolution on Windows, the case-insensitive %PATH% environment variable is searched for an executable that matches the name, ignoring case and any file extension. The file extension is expected to match any extension in the %PATHEXT% environment variable.

      Since:
      0.0.1

    • pythonEnabled

      @Parameter(defaultValue="false") boolean pythonEnabled
      Enable generating Python sources from the protobuf sources.

      If you enable this, you probably will also want to enable Python stubs to enable generating *.pyi files for static type checkers.

      Since:
      1.1.0

    • pythonStubsEnabled

      @Parameter(defaultValue="false") boolean pythonStubsEnabled
      Enable generating Python stubs (*.pyi files) for static typechecking from the protobuf sources.

      If you enable this, you probably will also want to enable Python itself to get actual source code to accompany the stubs.

      Since:
      1.1.0

    • registerAsCompilationRoot

      @Parameter(defaultValue="true") boolean registerAsCompilationRoot
      Whether to register the output directories as compilation roots with Maven.

      Generally, you want to do this, but there may be edge cases where you wish to control this behaviour manually instead. In this case, set this parameter to be false.

      Since:
      0.5.0

    • rubyEnabled

      @Parameter(defaultValue="false") boolean rubyEnabled
      Enable generating Ruby sources from the protobuf sources.
      Since:
      1.1.0

    • rustEnabled

      @Parameter(defaultValue="false") boolean rustEnabled
      Enable generating Rust sources from the protobuf sources.
      Since:
      1.1.0

    • skip

      @Parameter(defaultValue="false", property="protobuf.skip") boolean skip
      Whether to skip the plugin execution entirely.
      Since:
      2.0.0

    • sourceDependencies

      @Parameter @Nullable List<MavenDependencyBean> sourceDependencies
      Additional dependencies to compile, pulled from the Maven repository.

      Note that this will resolve dependencies recursively unless dependencyResolutionDepth is set to DIRECT.

      For example: 

      
 <sourceDependencies>
   <sourceDependency>
     <groupId>com.mycompany</groupId>
     <artifactId>common-protos</artifactId>
     <version>1.2.4</version>
     <type>zip</type>
   </sourceDependency>
 </sourceDependencies>

      Objects support the following attributes:

      • groupId - the group ID - required
      • artifactId - the artifact ID - required
      • version - the version - required
      • type - the artifact type - optional
      • classifier - the artifact classifier - optional
      • dependencyResolutionDepth - the dependency resolution depth to override the project settings with - optional
      • excludes - a set of exclusions to apply to transitive dependencies

      Exclusions are a set of objects, each with the following fields:

      • groupId - the group ID to exclude
      • artifactId - the artifact ID to exclude
      • classifier - optional - the classifier to exclude. If omitted, any classifiers are matched.
      • type - optional - the type of the artifact to exclude. If omitted, any types are matched.
      Since:
      1.2.0

    • sourceDirectories

      @Parameter @Nullable List<File> sourceDirectories
      Override the source directories to compile from.

      Leave unspecified or explicitly null/empty to use the defaults.

      Since:
      0.0.1

  • Constructor Details

    • AbstractGenerateMojo

      public AbstractGenerateMojo()

  • Method Details

    • defaultSourceDirectory

      abstract Path defaultSourceDirectory()
      Provides the default source directory to read protobuf sources from.

      This does not need to point to an existing directory, the plugin will handle this automatically.

      Returns:
      the path to the directory.

    • defaultOutputDirectory

      abstract Path defaultOutputDirectory()
      Provides the default output directory to write generated code to.

      This does not need to point to an existing directory, the plugin will handle this automatically.

      Returns:
      the path to the directory.

    • defaultDependencyScopes

      abstract Set<String> defaultDependencyScopes()
      The default dependency scopes used for resolution.
      Returns:
      the set of dependency scopes used for resolution.

    • outputDescriptorAttachmentRegistrar

      abstract OutputDescriptorAttachmentRegistrar outputDescriptorAttachmentRegistrar()
      Provides the registrar for output descriptor files to attach them to the Maven project as additional artifacts.
      Returns:
      the registrar to use.

    • sourceRootRegistrar

      abstract SourceRootRegistrar sourceRootRegistrar()
      Provides the source root registrar for this Mojo.

      This specifies where to attach generated sources to in order for it to be included as part of the compilation for main or test sources.

      Returns:
      the registrar to use.

    • execute

      public void execute() throws org.apache.maven.plugin.MojoExecutionException, org.apache.maven.plugin.MojoFailureException
      Execute the plugin and generate sources.
      Throws:
      org.apache.maven.plugin.MojoExecutionException - if execution fails.
      org.apache.maven.plugin.MojoFailureException - if an error occurs.

    • dependencyScopes

      private Set<String> dependencyScopes()

    • outputDescriptorFile

      private @Nullable Path outputDescriptorFile()

    • outputDirectory

      private Path outputDirectory()

    • sourceDirectories

      private Collection<Path> sourceDirectories()

    • sourceDirectoryExists

      private boolean sourceDirectoryExists(Path path)

    • importPaths

      private Collection<Path> importPaths()

    • protocVersion

      private String protocVersion()

    • nonNullList

      private <T> List<T> nonNullList(@Nullable List<T> list)