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.

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

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:

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:

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 ${project.build.directory}, you could now do the fol­low­ing to start and run the Vert.x ap­pli­ca­tion.

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

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

Main-Class                               io.vertx.core.Launcher
Main-Verticle                            io.fabric8.blog.MainVerticle
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:

foo.bar.baz.MyImpl
${combine}

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 foo.bar.baz2.My­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:

foo.bar.baz.MyImpl
foo.bar.baz2.MyImpl2

The po­si­tion of ${combine} con­trols the or­der­ing of the merge, since we added ${combine} below foo.bar.baz.My­Impl all other SPI de­f­i­n­i­tions will be ap­pended below foo.bar.baz.My­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!!