Developing Vert.x modules with Maven

In this guide we'll show you how to develop a Vert.x project using Maven.

Generate the project

Vert.x provides a Maven Archetype that can generate an example Vert.x Maven project for you. You can then edit and adapt that project to develop your Vert.x module.

To generate a project type the following at the command line, in your project's root directory:

mvn archetype:generate -Dfilter=io.vertx:

This will search for any artifacts with group id io.vertx and interactively prompt you as to which one you want.

You'll also be prompted for:

• groupId. This is the groupId for the module that we're going to generate, e.g. com.mycompany.
• artifactId. This the artifactId for the module that we're going to generate, e.g. my-vertx-module.
• version. This is the version for the module that we're going to generate, e.g. 2.0, or 0.1-SNAPSHOT.

If you prefer you can specify these parameters on the command line, for example:

mvn archetype:generate -Dfilter=io.vertx: -DgroupId=com.mycompany -DartifactId=my-module -Dversion=0.1

A directory with a name corresponding to artifactId will be created for you, with the example project in it. Let's go into it:

cd my-vertx-module

It's a functioning Maven project which creates a working Vert.x module. So you can do all the normal Maven stuff, for example, try:

mvn install

This builds, tests and installs the module in your local Maven repository, where it can be picked up by other Vert.x modules or projects.

Outputs

The outputs of the project are:

• The Vert.x module zip file.
• A jar that corresponds to the module. This is useful when you have another project which depends on the classes from your module, as it allows you to add it as a dependency to your other project.

The outputs are created in the target directory as per normal.

Configuring the project

You configure several things as properties in pom.xml including

• module.name determines the name of the module as described in the modules manual

• vertx.pullInDeps determines whether all module dependencies should be packaged into the module as nested modules.

It also contains various properties used to configure versions of various dependencies.

Overriding default Vert.x configuration

If you want to override any Vert.x platform configuration, e.g. langs.properties, cluster.xml or logging configuration, you can add those files to the directory src/main/platform_lib - these will then be added to the Vert.x platform classpath when you run the module with mvn vertx:runMod

Other useful Maven targets

To run the integration tests

mvn integration-test

Setup your IDE

You can use the idea and eclipse goals to create IDE projects from your Maven project, for example

mvn idea:idea

Or

mvn eclipse:eclipse

Once the IDE files have been created you can open the project in your IDE.

• You may have to tell your IDE to use Java source compatibility level of Java 7, as Maven seems to default to Java 5 (!)*

Changing the dependencies of your project

If your project needs a third party jar to build and you want to include it in the lib directory of your module you can add the dependency in the dependencies section of pom.xml with a scope of compile.

If you don't want it to be included in the lib directory you should add it as provided.

Once you've changed your dependencies just run mvn idea:idea or mvn eclipse:eclipse again to update your IDE project files with the new dependencies.

Pushing your module to Maven

Use mvn deploy as normal to push your module to a Maven repository.

Registering your module in the Module Registry

If you've pushed your module to a public Maven or Bintray repository you can register it in the Module Registry so others can search for and discover it.

Next steps

Now you've got the project all set-up and running, it's time to explore the standard project layout itself.