Getting started with new fabric8 Vert.x Maven Plugin

The all new fab­ric8 Vert.x Maven Plu­gin al­lows you to setup, pack­age, run, start, stop and re­de­ploy eas­ily with a very lit­tle con­fig­u­ra­tion re­sult­ing in a less ver­bose pom.xml.

The plug­in is de­vel­oped under the fab­ric8 um­brella.

Tra­di­tion­ally Vert.x ap­pli­ca­tions using Apache Maven need to have one or more of the fol­low­ing plu­g­ins:

  • Maven Shade Plu­gin - aids in pack­ag­ing a uber jar of Vert.x ap­pli­ca­tion with ad­di­tional con­fig­u­ra­tions to per­form SPI com­bin­ing, MAN­I­FEST.MF en­tries etc.,
  • Maven Exec Plu­gin - aids in start­ing the Vert.x ap­pli­ca­tion
  • Maven Ant Plu­gin - aids in stop­ping the run­ning Vert.x ap­pli­ca­tion

Though these are great plu­g­ins and do what is re­quired, but at the end of the day the de­vel­oper is left with a ver­bose pom.xml which might be­come harder to main­tain as the ap­pli­ca­tion or its con­fig­u­ra­tion grows. Even if we de­cide to go this way and use those plu­g­ins, there are some things which can’t done or done eas­ily:

  • run an ap­pli­ca­tion on fore­ground - which is a typ­i­cal way dur­ing de­vel­op­ment where the ap­pli­ca­tion starts in fore­ground of Apache Maven build and killed au­to­mat­i­cally once we hit Ctrl + c(or CMD + c on Mac)
  • redeploy is one of the coolest fea­ture of Vert.x al­low­ing us to per­form hot de­ploy­ments. Still we can man­age to do this with IDE sup­port but not na­tively using Apache Maven - typ­i­cal cases where we dis­able Au­to­matic Builds via IDE
  • setup Vert.x ap­pli­ca­tions with sen­si­ble de­faults and re­quired Vert.x de­pen­den­cies e.g. vertx-​core

In this first blog of fab­ric8 Vert.x Maven Plu­gin se­ries we will help you to get started with this new fab­ric8 Vert.x Maven Plu­gin, high­light­ing how this plug­in helps al­le­vi­at­ing the afore­men­tioned pain points with a less ver­bose pom.xml.

The Apache Maven plug­in source code is avail­able at github with Apache Maven plug­in doc­u­men­ta­tion avail­able at fab­ric8 Vert.x Maven Plu­gin

The source code of the ex­am­ples used in this blog are avail­able at github

Let’s set it up

Its very easy to setup and get started. Let’s say you have a project called vmp-​blog with the fol­low­ing con­tent as part of your pom.xml

...waiting for Gist...

from the project di­rec­tory just run the fol­low­ing com­mand:

mvn io.fabric8:vertx-maven-plugin:1.0.0:setup

On suc­cess­ful ex­e­cu­tion of the above com­mand the project’s pom.xml will be up­dated:

...waiting for Gist...

The com­mand did the fol­low­ing for you on the project:

  • added cou­ple of prop­er­ties
    • fabric8.vertx.plugin.version - the lat­est fab­ric8 vert.x maven plug­in ver­sion
    • vertx.version - the lat­est Vert.x frame­work ver­sion
  • added the Vert.x de­pen­dency BOM and vertx-​core de­pen­dency cor­re­spond­ing to vertx.version
  • added vertx-maven-plugin with a sin­gle ex­e­cu­tion for goals ini­tial­ize and pack­age

The source code cre­ated by this step is avail­able here

Et voilà, you are now all set to go with your Vert.x ap­pli­ca­tion build­ing with Apache Maven!!

Let’s package it

Now that we have set up our project to use vertx-maven-plugin, lets add a sim­ple ver­ti­cle and pack­age the Vert.x ap­pli­ca­tion as typ­i­cal uber jar (in the Vert.x world we call them fat jars). The source code of this sec­tion is avail­able here.

To make package work cor­rectly we need to add prop­erty called vertx.verticle, which will be used by the vertx-​maven-plugin to set the Main-Verticle: at­tribute of the MANIFEST.MF. Please refer to the doc­u­men­ta­tion of pack­age for other pos­si­ble con­fig­u­ra­tions. There is also a ex­am­ples sec­tion of the vertx-​maven-plugin which pro­vides var­i­ous sam­ples snip­pets.

The up­dated pom.xml with the added prop­erty vertx-maven-plugin is shown below:

Only up­dated sec­tion is shown below, rest of the pom.xml is same as above

...waiting for Gist...

To pack­age the Vert.x ap­pli­ca­tion, run the fol­low­ing Apache Maven com­mand from the project di­rec­tory:

mvn clean package

On suc­cess­ful run of the above com­mand you should see the file with name ${project.finalName}.jar cre­ated in the ${}, you could now do the fol­low­ing to start and run the Vert.x ap­pli­ca­tion.

java -jar ${}/${project.finalName}.jar

The gen­er­ated MANIFEST.MF file is as shown below:

Main-Class                               io.vertx.core.Launcher
Manifest-Version                         1.0

The source code up to now is avail­able in here

SPI Combination

The package goal by de­fault does a SPI com­bi­na­tion, lets say you have a ser­vice file called com.fasterxml.jackson.core.JsonFactory in ${project.basedir}/src/main/resources/META-INF/services with con­tents:

Dur­ing pack­ag­ing, if the fab­ric8 Vert.x Maven Plu­gin finds an­other com.fasterxml.jackson.core.JsonFactory ser­vice de­f­i­n­i­tion file within the project de­pen­den­cies with con­tent­Impl2, then it merges the con­tent into com.fasterxml.jackson.core.JsonFactory of ${project.basedir}/src/main/resources/META-INF/services, re­sult­ing in the fol­low­ing con­tent:

The po­si­tion of ${combine} con­trols the or­der­ing of the merge, since we added ${combine} below­Impl all other SPI de­f­i­n­i­tions will be ap­pended below­Impl

What’s next ?

It’s good to have the jar pack­aged and run using java -jar uber-jar, but when doing typ­i­cal de­vel­op­ment you don’t want to do fre­quent Apache Maven pack­ag­ing and wish to see your changes au­to­mat­i­cally re­de­ployed.

Don’t worry!!! As part of fab­ric8 Vert.x Maven Plu­gin we have added the in­cre­men­tal builder to Apache Maven build, which will watch for your source and re­source changes to per­form au­to­matic re-​build and del­e­gate the re­de­ploy­ment to Vert.x.

Run, re­de­ploy and other fea­tures of the fab­ric8 Vert.x Maven Plu­gin will be ex­plored in de­tail in the next part of this se­ries, until then have fun with fab­ric8 Vert.x Maven Plu­gin!!

Next post

Internet of Things - Reactive and Asynchronous with Vert.x

I have to admit … before joining Red Hat I didn’t know about the Eclipse Vert.x project but it took me few days to fall in love with it!

Read more
Previous post

OAuth2 got easy

Oauth2 support exists in Eclipse Vert.x since version 3.2.0. The implementation follows the principles that rule the whole vert.x ecosystem.

Read more
Related posts

My first Vert.x 3 Application

Let's say, you heard someone saying that Vert.x is awesome. Ok great, but you may want to try it by yourself. Well, the next natural question is “where do I start ?”

Read more

Unit and Integration Tests

Let’s refresh our mind about what we developed so far in the introduction to vert.x series. We forgot an important task. We didn’t test the API.

Read more

TCP Client using Eclipse Vert.x, Kotlin and Gradle build

In this blog post, I demonstrate how to write a very simple TCP client that keeps a connection open to a custom-written server in cloud.

Read more