© 2016-2020 The original authors.

1. Introduction

Eclipse Vert.x is a toolkit to build reactive and distributed systems on the top of the JVM. Vert.x applications can be developed in multiple languages such as Java, JavaScript, Groovy, Scala, Kotlin, Ceylon, Ruby…​ As a toolkit, Vert.x is un-opinionated.

The maven-vertx-plugin is a plugin for Apache Maven for packaging and running Vert.x applications. The plugin tries provide an opinionated way to build Vert.x application:

  • applications are packaged as a fat jar (containing your code and all the dependencies including Vert.x)

  • the application is configured with an application.json file or an application.yml file (translated to json).

The last version of the Vert.x Maven Plugin is 1.0.28.

1.1. Using the plugin

The plugin provides a set of goals such as:

  • setup - add the Vert.x Maven Plugin to your pom.xml

  • initialize - manage js dependencies and webjars, also initiates the redeployment

  • package - package your Vert.x application as a fat jar

  • run - run your application

  • start / stop - start your application in background / stop it

Generally, you will use the following configuration:

<project>
  ...
  <build>
    <plugins>
        ...
        <plugin>
            <groupId>io.reactiverse</groupId>
            <artifactId>vertx-maven-plugin</artifactId>
            <version>1.0.28</version>
            <executions>
                <execution>
                    <id>vmp</id>
                    <goals>
                        <goal>initialize</goal>
                        <goal>package</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <redeploy>true</redeploy>
            </configuration>
        </plugin>
        ...
    </plugins>
  </build>
  ...
</project>

1.2. Packaging

This plugin packaged the Vert.x application as a fat or über jar. These jars are executable, and so can be launched using: java -jar <my-app.jar>. The packaging process adds certain MANIFEST.MF entries that control how the application is launched. The plugin takes care of adding the required entries to the MANIFEST.MF with values configured using the Common Configuration

The following are the Manifest entries that will be added based on the configuration elements:

Table 1. Package configuration
Property Manifest Attribute Remarks

vertx.verticle

Main-Verticle

The main verticle, i.e. the entry point of your application. Used when the Main-Class is io.vertx.core.Launcher.

vertx.launcher

Main-Class

The main class used to start the application, defaults to io.vertx.core.Launcher

The package is generated using: mvn clean package

For more information on packaging refer to vertx:package

1.3. Running

The plugin allows running vert.x applications in following ways:

In foreground using vertx:run

The Vert.x application could also be run without building the fat jars, typically during the development mode. The vertx:run goal helps in running the application. The application will be run in as forked process with additional configurations based on the goals.

To run the application vert.x application in foreground, execute the following maven command

mvn clean compile vertx:run

You can enable the redeploy mode rebuilding and restarting the application upon file changes.

For more information on configuration options refer to vertx:run

In background using vertx:start

This allows the application be run using the uber or fat jar as background process. This option also attaches a configurable id or an autogenerated id which could be used to stop the process using vertx:stop

To start the application vert.x application in background, execute the following maven command

mvn clean install vertx:start

For more information on configuration options refer to vertx:start

To stop the application vert.x application running in background, execute the following maven command

mvn vertx:stop

For more information on configuration options refer to vertx:stop

2. Common Configurations

All goals share the following configuration:

Table 2. Package configuration
Element Description Default Property

verticle

Main verticle to start up

vertx.verticle

launcher

Main class to use

io.vertx.core.Launcher

vertx.launcher

skip

Skip the processing executed by this plugin

false

vertx.skip

3. Common Run Configurations

These are the common configuration shared by the run based goals such as run, start and stop.

Table 3. Run configuration
Element Description Property Default

options

the application configuration file path that will be passed to the vertx launcher as -options. If a yaml file is configured then it will be converted to json by the plugin. The converted file will be saved in ${project.outputDir}/conf directory.

vertx.options

src/main/options.json or src/main/options.yaml or src/main/options.yml

config

the application configuration file path that will be passed to the vertx launcher as -conf. If a yaml file is configured then it will be converted to json by the plugin. The converted file will be saved in ${project.outputDir}/conf directory

vertx.config

src/main/config/application.json or src/main/config/application.yml or src/main/config/application.yaml

redeploy

controls whether vertx redeploy is enabled

false

workDirectory

The working directory of the running process of the application

vertx.directory

${project.basedir}

vertxWebEnvironment

The environment the Vert.x Web app is running in.

vertxweb.environment

Default to either the VERTXWEB_ENVIRONMENT environment variable value or, if absent, to dev.

Right now the plugin supports only file based Vert.x configuration

4. Maven Goals

This plugin supports the following goals which are explained in detail in the next sections.

Table 4. Plugin Goals
Goal Description

vertx:setup

Add the vertx-maven-plugin to your pom.xml file

vertx:initialize

Copy js dependencies to webroot, unpack webjars to webroot (optional) and initialize the redeployment mode

vertx:package

Package Vert.x applications

vertx:run

Run a Vert.x application in foreground

vertx:debug

Debug a Vert.x application in foreground

vertx:start

Run a Vert.x application in daemon mode with specific id

vertx:setup

Sets up vert.x maven plugin and basic vert.x dependencies on an existing maven project

[vertx:stop]

Stops the vert.x application running in daemon mode

4.1. vertx:setup

This goal adds the Vert.x Maven Plugin to your pom.xml file. The plugin is configured with a default configuration.

Example
mvn io.reactiverse:vertx-maven-plugin:1.0.28:setup

The setup goal by default uses the plugin property vertx-core-version from the plugin properties file vertx-maven-plugin.properties as the vert.x version of the project, if you wish to override the vertx version, then you can run the same command as above with -DvertxVersion=<your-vertx-version>

e.g.

mvn io.reactiverse:vertx-maven-plugin:1.0.28:setup -DvertxVersion=4.3.1

This will configure the vert.x and its dependencies to 4.3.1 i.e. Maven project property vertx.version set to 4.3.1

You can also generate a project if you don’t have a pom.xml file:

mvn io.reactiverse:vertx-maven-plugin:1.0.28:setup \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=acme-project \
    -DprojectVersion=1.0-SNAPSHOT \ # default to 1.0-SNAPSHOT
    -Dverticle=org.acme.Foo \
    -Ddependencies=web,jmx,mongo

The verticle parameter creates a new verticle class file. The dependencies parameters specifies the Vert.x dependencies you need.

Dependencies are selected from a list of know dependencies matching the one listed on http://vertx.io/docs. In addition, you can configure dependencies using the following syntax: groupId:artifactId:version:classifier such as in:

io.vertx:vertxcodetrans => Inherit version from BOM
commons-io:commons-io:2.5 => Regular dependency
io.vertx:vertx-template-engines:4.3.1:shaded => Dependency with classifier

When creating a project, the java.specification.version system property is used to configure the Maven compiler plugin in the new POM file. To set a different Java version, use the javaVersion property:

mvn io.reactiverse:vertx-maven-plugin:1.0.28:setup -DjavaVersion=11

4.2. vertx:initialize

This goals has several aims:

  • copy js dependencies to the webroot directory

  • unpack webjars dependencies to the webroot directory (optional)

  • initialize the recording of the build used for the redeployment

Configuration

The initialize goal has the following parameters apart from the ones mentioned in Common Configuration

Table 5. Package Configuration
Element Description Property Default

webRoot

The location where js dependencies and webjars are copied.

 

${project.baseDir}/target/classes/webroot

unpackWebJar

Whether or not webjars are unpacked to webRoot. If not unpacked, webjars can be served from the classpath.

 

false

stripWebJarVersion

Whether or not the version is stripped when unpacking webjars

 

true

stripJavaScriptDependencyVersion

Whether or not the version is stripped when copying the JavaScript file

 

true

The webroot directory is generally used by the StaticHandler from Vert.x Web.

Redeployment

The initialize goal is used to configure the redeployment used in vertx:run. It starts observing the executed plugins in your build to replay them when a file changes.

4.3. vertx:package

This goal packages a Vert.x application as fat or über jar with its dependencies bundled as part of the jar.

Configuration

The package goal has the following parameters apart from the ones mentioned in Common Configuration

Table 6. Package Configuration
Element Description Property Default

serviceProviderCombination

Whether or not SPI files (META-INF/services) need to be be combined. Accepted valued as combine and none.

 

combine

classifier

The classifier to add to the artifact generated. If given, the artifact will be attached with that classifier and the main artifact will be deployed as the main artifact. If this is not given (default), it will replace the main artifact and only the Vert.x (fat) jar artifact will be deployed (in the Maven sense). Attaching the artifact allows to deploy it alongside to the original one. Attachment is controlled using the attach parameter.

 

 

attach

Whether or not the created archive needs to be attached to the project. If attached, the fat jar is installed and deployed alongside the main artifact (plain jar). Notice that you can’t disable attachment if the classifier is not set (it would mean detaching the main artifact).

 

true

skipScmMetadata

Whether or not the SCM metadata should be retrieved from the SVN or Git repository

 

true

4.4. vertx:run

This goal allows to run the Vert.x application as part of the maven build. The application is always run as a forked process.

The goal has the following exclusive configuration apart from the applicable Common Run Configuration

Element Description Property Default

runArgs

The list of arguments that can be passed as part of run command. You can also pass the required run arguments using the system property. e.g. -Dvertx.runArgs="--worker --instances=2". The system property takes precedence over the plugin configurations

vertx.runArgs

 

options

The configuration file to use to configure Vert.x. This property is passed as the -options option to vertx run.

vertx.options

src/main/config/options.json or src/main/config/options.yml or src/main/config/options.yaml

config

The configuration file to use to configure the application. This property is passed as the -config option to vertx run.

vertx.config

src/main/config/application.json or src/main/config/application.yml or src/main/config/application.yaml

jvmArgs

The Java Options that will be used when starting the application, these are the values that are typically passed to vert.x applications using --java-opts.

vertx.jvmArguments

no arguments

redeploy

Whether or not the redeployment is enabled

 

false

redeployScanPeriod

The file system check period (in milliseconds)

vertx.redeploy.scan.period

1000

redeployGracePeriod

The amount of time (in milliseconds) to wait between 2 re-deployments

vertx.redeploy.grace.period

1000

redeployTerminationPeriod

the amount of time (in milliseconds) to wait after having stopped the application (before launching user command). This is useful on Windows, where the process is not killed immediately.

vertx.redeploy.termination.period

1000 (1 second)

worker

If specified the verticle will be a worker verticle

 

false

When the redeployment is enabled, it replays the plugin configured between the generate-source and process-classes phases.

So to start a Vert.x application just launch:

mvn vertx:run

If the sources are not compiled, the plugin executes mvn compile for you.

vertx:run starts the application in a forked JVM.

4.5. vertx:debug

This goal allows to debug the Vert.x application.The application is started in a JVM with the debugging enabled.In your IDE, you need to create a remote debug configuration to plug the debugger.

The goal does not have any exclusive configuration, Common Run Configuration defines all the applicable configurations for the goal.

Element Description Property Default

options

The configuration file to use to configure Vert.x. This property is passed as the -options option to vertx run.

vertx.options

src/main/config/options.json or src/main/config/options.yml or src/main/config/options.yaml

config

The configuration file to use to configure the application. This property is passed as the -config option to vertx run.

vertx.config

src/main/config/application.json or src/main/config/application.yml or src/main/config/application.yaml

jvmArgs

The Java Options that will be used when starting the application, these are the values that are typically passed to vert.x applications using --java-opts.

vertx.jvmArguments

no arguments

debugPort

The debugger port

debug.port

5005

debugSuspend

Whether or not the application must wait until a debugger is attached to start

debug.suspend

false

the redeploy mode and debug cannot be used together. When vertx:debug is launched, the redeployment mode is disabled.

4.6. vertx:start

This goal allows to start the Vert.x application as a background process from maven build. This goal triggers the vert.x start command, passing the configuration values as mentioned below.

Table 7. Run configuration
Element Description Property Default

startMode

The property to decide how the vert.x application will be started in background. The application can be started in jar mode in which the application will be packaged as fat jar and started, or can be run in exploded mode where the application will be launched with exploded classesDirectory and maven dependencies to the classpath

vertx.start.mode

jar

appId

The application id that will added as -id option to the vert.x start command

vertx.app.id

If this is not passed a default uuid will be generated and set as appId

jvmArgs

The Java Options that will be used when starting the application, these are the values that are typically passed to vert.x applications using --java-opts

vertx.jvmArguments

Apart from the above list of exclusive start configuration, the goal shares the common Common Run Configuration with the following configuration ignored by the goal,

  • redeploy === vertx:stop This goal allows to stop the vert.x application running as background process from maven build. This goal triggers the vert.x stop command, passing the configuration values as mentioned below.

Table 8. Run configuration
Element Description Property Default

appIds

The application id’s that will stopped using the vert.x stop command

If this is not passed, the vertx-start-proc.id file present workingDirectory will be read for the application id

Apart from the above list of exclusive start configuration, the goal shares the common Common Run Configuration with the following configuration ignored by the goal,

  • redeploy === vertx:setup

This goal adds the Vert.x Maven Plugin to your pom.xml file. The plugin is configured with a default configuration.

Example
mvn io.reactiverse:vertx-maven-plugin:1.0.28:setup

The setup goal by default uses the plugin property vertx-core-version from the plugin properties file vertx-maven-plugin.properties as the vert.x version of the project, if you wish to override the vertx version, then you can run the same command as above with -DvertxVersion=<your-vertx-version>

e.g.

mvn io.reactiverse:vertx-maven-plugin:1.0.28:setup -DvertxVersion=4.3.1

This will configure the vert.x and its dependencies to 4.3.1 i.e. Maven project property vertx.version set to 4.3.1

You can also generate a project if you don’t have a pom.xml file:

mvn io.reactiverse:vertx-maven-plugin:1.0.28:setup \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=acme-project \
    -DprojectVersion=1.0-SNAPSHOT \ # default to 1.0-SNAPSHOT
    -Dverticle=org.acme.Foo \
    -Ddependencies=web,jmx,mongo

The verticle parameter creates a new verticle class file. The dependencies parameters specifies the Vert.x dependencies you need.

Dependencies are selected from a list of know dependencies matching the one listed on http://vertx.io/docs. In addition, you can configure dependencies using the following syntax: groupId:artifactId:version:classifier such as in:

io.vertx:vertxcodetrans => Inherit version from BOM
commons-io:commons-io:2.5 => Regular dependency
io.vertx:vertx-template-engines:4.3.1:shaded => Dependency with classifier

When creating a project, the java.specification.version system property is used to configure the Maven compiler plugin in the new POM file. To set a different Java version, use the javaVersion property:

mvn io.reactiverse:vertx-maven-plugin:1.0.28:setup -DjavaVersion=11

5. Archive configuration

The Vert.x Maven Plugin lets you configure the content of the created archive. Typically you can decide:

  • which dependency needs to be embedded

  • which files need to be included

  • which resources need to be combined

Besides, you can customize the manifest.

By default, the plugin:

  • embeds all compile dependencies

  • includes all files from target/classes (compiled classes from src/main/resources, processed resources from `src/main/resources)

  • combines resources from META-INF/services, META-INF/spring.* and META-INF/org/apache/logging/log4j/core/config/plugins/Log4j2Plugins.dat.

5.1. Using archive configuration

In you plugin configuration add the archive item:

<project>
  ...
  <build>
    <plugins>
        ...
        <plugin>
            <groupId>io.reactiverse</groupId>
            <artifactId>vertx-maven-plugin</artifactId>
            <version>${version}</version>
            <executions>
                <execution>
                    <id>vmp</id>
                    <goals>
                        <goal>initialize</goal>
                        <goal>package</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <archive>
                    <!-- archive configuration goes here -->
                </archive>
            </configuration>
        </plugin>
        ...
    </plugins>
  </build>
  ...
</project>

5.2. Configuring embedded dependencies

In the archive configuration, you can declare dependency sets which indicate which dependencies must be included and excluded. Also for each configure set, you can decide the file to include and exclude.

Here is an example:

<configuration>
   <archive>
       <dependencySets>
           <set>
              <excludes>
                  <exclude>*:commons-lang3</exclude>
              </excludes>
              <includes>
                  <include>*:log4j-core</include>
                  <include>*:vertx-core</include>
              </includes>
              <options>
                  <excludes>
                      <exclude>*.dtd</exclude>
                  </excludes>
              </options>
           </set>
       </dependencySets>
    </archive>
</configuration>

Notice that when a dependency set is configured, no other dependency is embedded, disabling the default. When you configure the archive without a dependency set, the default behavior (embedding all compile dependencies) is used.

On a dependency set you can configure:

  • includes: the set of dependencies to specifically include, if not set, include all dependencies not explicitly excluded

  • excludes: the set of dependencies to exclude

  • scope: the scope of the dependency to include, default to runtime

  • useTransitiveDependencies: a boolean indicating if transitive dependencies from included dependencies must be also included in the jar

  • option: configure the files to include / exclude from this dependency set

The option attribute enable fine-grain tuning of the file to embed. In the example above, the dtd files are excluded.

5.3. Embedding specific file

The archive can be configured with a set of external file to include. For instance:

<configuration>
   <archive>
       <files>
          <file>
              <source>src/ext/hello.txt</source>
              <outputDirectory>misc</outputDirectory>
              <destName>lorem-ipsum.txt</destName>
          </file>
       </files>
    </archive>
</configuration>

Each file contains:

  • the source - the location of the file

  • the outputDirectory - indicating where would be the file in the archive

  • the destName - indicating the final name

For instance, in the previous example, the file src/ext/hello.txt is embedded in the archive as misc/lorem-ipsum.txt.

5.4. Embedding file sets

While files allow embedding files individually, fileSets declare set of files:

<archive>
    <fileSets>
       <fileSet>
           <directory>src/ext</directory>
           <outputDirectory>misc</outputDirectory>
           <excludes>
               <exclude>h*.txt</exclude>
           </excludes>
       </fileSet>
    </fileSets>
</archive>

In a fileSet, you can configure:

  • the directory - the directory containing the files

  • the outputDirectory - indicating where would be the file in the archive

  • includes and excludes pattern to choose which files you want to embed in the archive.

  • useDefaultExcludes - indicating if you want to use the default exclusion list (enabled by default)

5.5. Customizing the manifest

You can also add entries into the MANIFEST.MF of the created archive using the manifest entry:

<executions>
    <execution>
        <goals>
            <goal>package</goal>
        </goals>
        <configuration>
            <archive>
               <manifest>
                   <key>value</key>
                   <name>${project.artifactId}</name>
               </manifest>
            </archive>
        </configuration>
    </execution>
</executions>

5.6. Resource combination

Resource combination is the process of merging the content of some files into a single file. It is particularly useful when building an archive embedding dependencies which contain the same files.

The files matching these patterns are combined by default:

  • META-INF/services/*

  • META-INF/spring*

  • META-INF/org/apache/logging/log4j/core/config/plugins/Log4j2Plugins.dat.

The fileCombinationPatterns attribute allows configuring which files need to be combined:

<archive>
    <fileCombinationPatterns>
        <pattern>misc/extension.*</pattern>
        <pattern>META-INF/services/*</pattern>
        <pattern>META-INF/org/apache/logging/log4j/core/config/plugins/Log4j2Plugins.dat</pattern>
    </fileCombinationPatterns>
</archive>
If you set the fileCombinationPatterns attribute, the defaults are ignored.

6. Example Configurations

The following sections shows example plugin snippets for the goals provided by the plugin.

please update the plugin version as needed (latest is 1.0.28).

Also check the samples directory to see other examples:

6.1. vert.x:package Examples

This is the default configuration. It builds the fat jar in the package phase, and support .js and webjars dependencies. mvn compile vertx:run enables the redeployment.

<plugin>
    <groupId>io.reactiverse</groupId>
    <artifactId>vertx-maven-plugin</artifactId>
    <version>${version}</version>
    <executions>
        <execution>
            <id>vmp</id>
            <goals>
                <goal>initialize</goal>
                <goal>package</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <redeploy>true</redeploy>
    </configuration>
</plugin>
Webjars and Javascript dependencies

When the js dependencies and the webjars are handled, it stripped the version by default. Let’s illustrate this with the following dependencies:

<dependency>
    <groupId>io.vertx</groupId>
    <artifactId>vertx-web</artifactId>
    <version>3.9.5</version>
    <classifier>client</classifier>
    <type>js</type>
</dependency>
<dependency>
    <groupId>org.webjars</groupId>
    <artifactId>jquery</artifactId>
    <version>3.1.1</version>
</dependency>

The first dependency is a js dependency (<type>js</type>). The plugins resolves the dependency and copy the file to the webroot directory (the default is ${project.baseDir}/target/classes/webroot). The output file name is: vertx-web-client.js.

The second dependency is a webjar. A webjar is a jar file containing web resources. By default, the plugin extracts the web resource to the webroot directory. In this example, it creates: ${project.baseDir}/target/classes/webroot/jquery/jquery.js (and other included resources).

Using full names for Webjars and Javascript dependencies

By default the plugin stripped the version. However this behavior can be disabled using:

<plugin>
    <groupId>io.reactiverse</groupId>
    <artifactId>vertx-maven-plugin</artifactId>
    <version>${version}</version>
    <executions>
        <execution>
            <id>vmp</id>
            <goals>
                <goal>initialize</goal>
                <goal>package</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <redeploy>true</redeploy>
        <stripWebJarVersion>false</stripWebJarVersion>
        <stripJavaScriptDependencyVersion>false</stripJavaScriptDependencyVersion>
    </configuration>
</plugin>

In this case, the vertx-web-client.js output file is: vertx-web-3.9.5-client.js, while for jquery, resources are unpacked in ${project.baseDir}/target/classes/webroot/jquery/3.1.1. You can always look into the target/classes/webroot directory to check the output files.

Finally, you can also configure the webRoot dir:

<plugin>
    <groupId>io.reactiverse</groupId>
    <artifactId>vertx-maven-plugin</artifactId>
    <version>${version}</version>
    <executions>
        <execution>
            <id>vmp</id>
            <goals>
                <goal>initialize</goal>
                <goal>package</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <webRoot>target/classes/assets</webRoot>
        <redeploy>true</redeploy>
    </configuration>
</plugin>

Notice that the webRoot directory is relative to the project directory.

6.2. vert.x:start Examples

You can start your application in background using: mvn clean package vertx:start. The application is started in background. An id is automatically associated with the process. This id can be specified:

mvn clean package vertx:start -Dvertx.app.id=my-vertx-app

This id is useful to stop the application:

mvn vertx:stop -Dvertx.app.id=my-vertx-app

The application id can be set in the pom.xml file:

<plugin>
    <groupId>io.reactiverse</groupId>
    <artifactId>vertx-maven-plugin</artifactId>
    <version>${version}</version>
    <executions>
        <execution>
          <phase>initialize</phase>
          <phase>package</phase>
        </execution>
    </executions>
    <configuration>
        <appId>my-app-id</appId>
    </configuration>
</plugin>
Start goal with custom Java options

Because it’s a forked process, passing Java options needs to be done explicitly using a specific property:

<plugin>
    <groupId>io.reactiverse</groupId>
    <artifactId>vertx-maven-plugin</artifactId>
    <version>${version}</version>
    <executions>
      <execution>
          <phase>initialize</phase>
          <phase>package</phase>
      </execution>
    </executions>
    <configuration>
       <jvmArgs> (1)
          <jvmArg>-Xms512m</jvmArg>
          <jvmArg>-Xmx1024m</jvmArg>
       </jvmArgs>
    </configuration>
</plugin>
1 The jvm arguments that gets passed as --java-opts to the vert.x application

You can also pass these parameters in the command line:

mvn clean package vertx:start -Dvertx.jvmArguments=-Xms512m -D-Dfoo=far
Stopping one or more applications

When you have configured to [start-with-app-id] or know the application ids, then you can add list of application ids as shown below to trigger stop of the those applications

<plugin>
    <groupId>io.reactiverse</groupId>
    <artifactId>vertx-maven-plugin</artifactId>
    <version>${version}</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>start</goal>
            </goals>
            <configuration>
              <appIds> (1)
                 <appId>my-app-id-1</appId>
                 <appId>my-app-id-2</appId>
              </appIds>
            </configuration>
        </execution>
    </executions>
</plugin>
1 List of custom unique application ids
Adding some extra options to run command
 <plugin>
    <groupId>io.reactiverse</groupId>
    <artifactId>vertx-maven-plugin</artifactId>
    <version>${version}</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>run</goal>
            </goals>
            <configuration>
                <runArgs>
                    <runArg>--cluster</runArg>
                </runArgs>
            </configuration>
        </execution>
    </executions>
</plugin>

7. Miscellaneous

7.1. How does the redeploy work

During the initialize phase, the plugin starts observing the mojos (Maven plugins) that are executed. When the Vert.x application is launched, it watches for changes in src/main. When a file is changed (created, updated or deleted), it replays the executed mojos. It executes all the mojos from the generate-sources to the process-classes phases, using the same configuration as the initial (observed) one.

When these mojos are executed, they may update files in target/classes. The Vert.x application has been launched to observe changed files from this location and restart when changes happen. The application is restarted completely, i.e. stopped and restarted.

Such mechanism lets you use any Maven plugin (executed in the right set of phase). The plugin is re-executed and then the Vert.x application is restarted.

7.2. Windows: command line is too long

The Vert.x Maven Plugin runs your Vert.x application in a forked process. This process command line can grow quickly depending on:

  1. the number of dependencies in the project,

  2. the length of the path to JVM,

  3. the length of the path to the Maven repository.

On Windows, there is a maximum length for command lines. When this maximum is reached the Vert.x application fails to start. You will see an error such as:

Command line is too long

As a workaround, you can either:

  • move the JVM and Maven repository paths closer to the root of the Windows drive, or

  • use subst to associate the JVM and Maven repository paths with a drive letter.

For example, you could associate the letter X with the JVM path and Y with the Maven repository path:

subst X: "C:\Program Files\AdoptOpenJDK\jdk-11.0.8.10-hotspot"
subst Y: "C:\Users\User\.m2\repository"
Virtual drives created with subst do not survive reboots. To make the setup somewhat persistent, put the subst commands in a batch file and add it to the startup folder.

Then:

  1. set the JAVA_HOME environment variable to X:

  2. open the Maven settings file and change the localRepository element value to Y:

Don’t forget to open a new terminal so that the environment variable change is visible.

8. References