<dependency>
<groupId>io.vertx</groupId>
<artifactId>vertx-launcher-application</artifactId>
<version>5.0.0.CR3</version>
</dependency>
Vert.x Application Launcher
In essence, launching a Vert.x application is not a complex task: write a class with a main
method, create a Vert.x instance and deploy the main verticle.
But, very often, the same problems must be solved, for example:
-
configuring the number of verticle instances
-
deploying the main verticle with a specific
threading model
-
creating a clustered Vert.x instance
-
properly closing Vert.x when the JVM is asked to stop via signals
The Vert.x application launcher is a tool which addresses such concerns, without repeating the same code in every project.
This module, introduced in Vert.x 5, replaces the Vert.x 4 io.vertx.core.Launcher . |
This module has Tech Preview status, this means the API can change between versions. |
Dependencies setup
To use the Vert.x Application Launcher, add the following dependency to the dependencies section of your build descriptor:
-
Maven (in your
pom.xml
):
-
Gradle (in your
build.gradle
file):
dependencies {
compile 'io.vertx:vertx-launcher-application:5.0.0.CR3'
}
Getting started
To start your Vert.x application, use VertxApplication
as the main class.
# Assuming the command is executed on a Unix-like system which has the classpath configured in the CLASSPATH environment variable.
java -cp $CLASSPATH io.vertx.launcher.application.VertxApplication my.app.MainVerticle
If your application is packaged as an executable JAR, having the Main-Class
attribute set to io.vertx.launcher.application.VertxApplication
in the META-INF/MANIFEST.MF
file, the command can be simplified.
java -jar myapp.jar my.app.MainVerticle
Main verticle parameter
The VertxApplication
main class accepts a single parameter, which is the name of the main verticle to deploy.
This parameter is optional if your application is packaged as an executable JAR having, in the META-INF/MANIFEST.MF
file:
-
the
Main-Class
attribute set toio.vertx.launcher.application.VertxApplication
(or a subclass, as explained below), and -
the
Main-Verticle
attribute set to the name of the main verticle.
META-INF/MANIFEST.MF
fileMain-Class: io.vertx.launcher.application.VertxApplication Main-Verticle: my.app.MainVerticle
Options
In addition to the main verticle parameter, the VertxApplication
main class accepts several options.
- -options, --options, -vertx-options, --vertx-options=<vertxOptionsStr>
-
Specifies the Vert.x options.
It should reference either a JSON file which represents the options OR be a JSON string.
- -c, -cluster, --cluster
-
If specified, then the Vert.x instance will form a cluster with any other Vert.x instances on the network.
- -cluster-port, --cluster-port=<clusterPort>
-
Port to use for cluster communication.
By default, a spare random port is chosen.
- -cluster-host, --cluster-host=<clusterHost>
-
Host to bind to for cluster communication.
If this is not specified, Vert.x will attempt to choose one from the available interfaces.
- -cluster-public-port, --cluster-public-port=<clusterPublicPort>
-
Public port to use for cluster communication.
By default, Vert.x uses the same as the cluster port.
- -cluster-public-host, --cluster-public-host=<clusterPublicHost>
-
Public host to bind to for cluster communication.
By default, Vert.x uses the same as the cluster host.
- -deployment-options, --deployment-options=<deploymentOptionsStr>
-
Specifies the main verticle deployment options.
- -w, -worker, --worker
-
If specified, then the main verticle is deployed with the worker threading model.
Takes precedence over the value defined in deployment options.
- -vt, -virtual-thread, --virtual-thread
-
If specified, then the main verticle is deployed with the virtual thread threading model.
Takes precedence over the value defined in deployment options.
- -instances, --instances=<instances>
-
Specifies how many instances of the verticle will be deployed.
Takes precedence over the value defined in deployment options.
- -conf, --conf=<configStr>
-
Specifies configuration that should be provided to the verticle.
It should reference either a JSON file which represents the options OR be a JSON string.
- -h, -help, --help
-
Display a help message.
Extensibility
Hooks
Sometimes, it is useful to change the default behavior depending on the environment, or the configuration. Or, perhaps, you would like to execute some actions after Vert.x has started.
For such cases, you can create a main class and an instance of VertxApplication
using hooks.
main
method implementationVertxApplicationHooks hooks = new VertxApplicationHooks() {
@Override
public void beforeStartingVertx(HookContext context) {
VertxOptions vertxOptions = context.vertxOptions();
// You could customize the metrics/tracer options here
}
@Override
public void afterVerticleDeployed(HookContext context) {
System.out.println("Hooray!");
}
};
VertxApplication app = new VertxApplication(args, hooks);
app.launch();
Please refer to the VertxApplicationHooks
and HookContext
documentation for further details about the hooks.
Subclassing
If you need further control on the Vert.x Application Launcher behavior, consider subclassing it. In this case, you will be able to invoke a special constructor that lets you decide whether, on failure:
-
the application should print usage (help message) to
stdout
, and -
the application should exit the JVM with a specific code.