maven, execution tag, id tag missing

Question

I'm looking at the plugin section of a pom I'm inspecting and found this:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-docck-plugin</artifactId>
    <version>1.0</version>
    <executions>
        <execution>
            <phase>pre-site</phase>
            <goals>
                <goal>check</goal>
            </goals>
        </execution>
    </executions>
</plugin>

If you observe the execution section you will notice that it does not have an id tag. My question is how is the id tag used by Maven and how the absence of one influences the observed behavior. I looked into Maven tutorials and could infer that id's of different execution phases must be unique, in a pom not necessarily across the inherited poms, but it did not mention how it is utilized.

Answer 1

For Maven 3.0.x at least, when not specified, the ID for an execution is default-goalName. So for the example you have, the ID would be default-check. The value default-cli may also be used to configure command line executions.

The execution IDs are used when creating the effective POM from the POM itself, any parent POMs (including the Maven super POM), and settings.xml. Maven merges configuration for plugin executions having the same ID across these POMs. Here's an example. Assume this plugin config is in a parent POM (only Maven super POM is higher up in the hierarchy.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-jar-plugin</artifactId>
  <executions>
    <!-- default-jar is the ID assigned to the jar:jar execution 
         included automatically by Maven.  This demonstrates how we 
         can tweak the built-in plugin executions to meet our needs.  
         Note we do not have to specify phase or goals, as those are 
         inherited.  In the example we add a configuration block and
         change the values of the <forceCreation> and <finalName> 
         elements. -->
    <execution>
      <id>default-jar</id>
      <configuration>
        <finalName>firstJar</finalName>
        <forceCreation>true</forceCreation>
      </configuration>
    </execution>

    <!-- Add an execution of the jar plugin to build a jar with the 
         same contents but different name.  We assign an execution ID.
         Because we are not inheriting config for this execution it's our 
         responsibility to specify phase and goals, as well as the config
         we want.  Executions are run in order so this one will run after 
         the default. -->
    <execution>
      <id>another-jar</id>
      <phase>package</phase>
      <goals>
        <goal>jar</goal>
      </goals>
      <configuration>
        <finalName>duplicateJar</finalName>
      </configuration>
    </execution>

    <!-- Configure plugin behavior if we execute the jar:jar goal 
         directly from the command line.  Don't bind this to a phase; 
         we don't want to run this as part of the normal lifecycle. -->
    <execution>
      <id>default-cli</id>
      <configuration>
        <finalName>cmdLineJar</finalName>
      </configuration>
    </execution>
  </executions>
</plugin>

With the above config:

• mvn clean package - builds firstJar.jar and duplicateJar.jar
• mvn jar:jar - builds cmdLineJar.jar (note, no clean lifecycle!)
• mvn clean jar:jar - removes target dir, builds empty (except for manifest) cmdLineJar.jar; because jar:jar does not run the full lifecycle, just one goal
• mvn clean prepare-package jar:jar - runs lifecycle thru prepare-package, then builds a non-empty cmdLineJar.jar

Answer 2

The problem can not be treated with respect to id tag only but notice the different values of it through the examples. This has been tested with maven 3.0.5. Consider the following pom part:

       <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-docck-plugin</artifactId>
            <version>1.0</version>
            <executions>
                <execution>
                    <id>some-other-other-id</id> <!-- No goal for execution is defined -->
                    <phase>pre-site</phase>
                </execution>
                <execution>
                    <phase>pre-site</phase>   <!-- No id for execution is defined -->
                    <goals>
                        <goal>check</goal>
                    </goals>
                </execution>
                <execution>
                    <id>some-id</id>          <!-- No phase for execution is defined -->           
                    <goals>
                        <goal>check</goal>
                    </goals>
                </execution>
                <execution>
                    <id>some-other-id</id>     <!-- Both id and phase defined -->
                    <phase>pre-site</phase>
                    <goals>
                        <goal>check</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>

When run mvn clean site from command line it outputs the following:

[INFO] --- maven-docck-plugin:1.0:check (default) @ MavenJavaApplication ---
[INFO] Skipping unsupported project: MavenJavaApplication
[INFO] No documentation errors were found.
[INFO] 
[INFO] --- maven-docck-plugin:1.0:check (some-other-id) @ MavenJavaApplication ---
[INFO] Skipping unsupported project: MavenJavaApplication
[INFO] No documentation errors were found.

Notice that the execution outputs are always in form of:

<plugin-name>:<plugin-version>:<phase> (<execution-id>)

Case 1: No goal for execution is defined

From Build lifecycle basics:

A plugin goal represents a specific task (finer than a build phase) which contributes to the building and managing of a project. It may be bound to zero or more build phases. A goal not bound to any build phase could be executed outside of the build lifecycle by direct invocation. (...) Moreover, if a goal is bound to one or more build phases, that goal will be called in all those phases.

From Guide to configuring plugins: Configuring build plugins:

But if the goal is not bound to any lifecycle phase then it simply won't be executed during the build lifecycle.

From what is quoted, it may be concluded that the execution with id some-other-other-id can be ran from the command line, but that is not so, it can never be ran - it will be covered in the 5th example.

Case 2: No id for execution is defined

The definition of goal and a phase in the first execution is enough for it to get run so it gets assigned a default execution id of value default and it gets executed.

Case 3: No phase for execution is defined

Since the phase is not defined anywhere this execution does not get executed. It can be verified by the fact that the output does not contain the line with its execution id.

Case 4: Both id and phase defined

This execution defines all three: an id, a phase and a goal so it gets executed.

Case 5: CLI execution

If you run (read the syntax in the docck plugin documentation):

mvn docck:check -Doffline=true

it will output:

[INFO] --- maven-docck-plugin:1.0:check (default-cli) @ MavenJavaApplication ---

From Guide to configuring default mojo executions:

Starting in Maven 2.2.0, each mojo invoked directly from the command line will have an execution Id of default-cli assigned to it, which will allow the configuration of that execution from the POM by using this default execution Id

You can provide the properties for the goal executed from CLI in three different ways:

• in the command line directly
• in the plugin configuration
• in the execution tag with id of value default-cli

Specifically, the above command is equivalent of running

mvn docck:check

with the pom containing:

 <plugin>
     <groupId>org.apache.maven.plugins</groupId>
     <artifactId>maven-docck-plugin</artifactId>
     <version>1.0</version>
     <configuration>
         <offline>true</offline>
     </configuration>
  </plugin>

or:

  <plugin>
     <groupId>org.apache.maven.plugins</groupId>
     <artifactId>maven-docck-plugin</artifactId>
     <version>1.0</version>
     <executions>
         <execution>
             <id>default-cli</id>
             <phase>pre-site</phase>
             <goals>
                 <goal>check</goal>
             </goals>
             <configuration>
                 <offline>true</offline>
             </configuration>
         </execution>
     </executions>
  </plugin>

This last part comes in handy if you want to keep the global configuration for some common properties in different executions, but you want a complete other set of properties for running from CLI.

Case 6: The default execution

Since the maven-docck-plugin has no default binding I'll cover it with the maven-compiler-plugin. Consider an empty pom with jar packaging. If you run:

 mvn clean install

it will trigger the compile phase also and you will see in output:

[INFO] --- maven-compiler-plugin:2.3.1:compile (default-compile) @ MavenJavaApplication ---

To cover the value of the id tag, from Guide to Configuring Default Mojo Executions:

Likewise, each mojo bound to the build lifecycle via the default lifecycle mapping for the specified POM packaging will have an execution Id of default-<goalName> assigned to it, to allow configuration of each default mojo execution independently.

If you run mvn help:effective-pom you will find the default execution definition for compiler plugin in output:

<execution>
    <id>default-compile</id>
    <phase>compile</phase>
    <goals>
        <goal>compile</goal>
     </goals>
 </execution>

It gets inherited from super POM for the jar packaging type:

When no packaging is declared, Maven assumes the artifact is the default: jar. The valid types are Plexus role-hints (read more on Plexus for a explanation of roles and role-hints) of the component role org.apache.maven.lifecycle.mapping.LifecycleMapping. The current core packaging values are: pom, jar, maven-plugin, ejb, war, ear, rar, par. These define the default list of goals which execute to each corresponding build lifecycle stage for a particular package structure.

In other words, the above default execution definition is the consequence of a default lifecycle mapping (documentation, definition ) for the compiler-plugin:

The Compiler Plugin has two goals. Both are already bound to their proper phases within the Maven Lifecycle and are therefore, automatically executed during their respective phases.

• compiler:compile is bound to the compile phase and is used to compile the main source files.

Uniqueness of an execution id tag

From Guide to configuring plugins.html: Using the executions tag:

Note that while execution id's have to be unique among all executions of a single plugin within a POM, they don't have to be unique across an inheritance hierarchy of POMs. Executions of the same id from different POMs are merged. The same applies to executions that are defined by profiles.