50 Shades of TomEE

I don’t know if we’ll get a film after the international success of it but since few months the world is all about microservices.

Whatever your opinion on it is you will surely have to work with it a little bit. One common way to go to production with microservices is to do a shade of your application and simply deploy an executable jar.

Let go through common Microservice solutions which work with TomEE flavors.

TomEE Shades

A shade is a Maven plugin to aggregate project dependencies in a single jar. It can be done with Maven dependency plugin with some hack (basically unpacking all dependencies in target/classes) but Maven shade plugin provides more control over the merge policy thanks to Transformer API.

To do an executable jar using Maven shade plugin you need to know two information:

what is the main class

what files need a specific merging and which policy it needs

All TomEE flavors share the same second point, which we’ll develop just after having tackled the first one.

Specify your Main Class

Depending which flavor of TomEE you use the main will be different but in all cases it will boot your application.

In all cases once you have the main class you will rely on you’ll be able to specify it in Maven shade plugin using the following configuration:

Just write your own main using ApplicationComposers and specify it in shade configuration to boot your application.

TomEE Embedded

TomEE embedded is surely one of the best choices for a TomEE shade since it provides a Main class out of the box. Just specify org.apache.tomee.embedded.Main as the mainClass in the shade ManifestResourceTransformerconfiguration and you are done.

TomEE (remote)

TomEE remote can be controlled using OpenEJB RemoteServer class and this is mainly what does tomee:exec goal. You can also use catalina.sh commands to start/stop your application.

In all cases the fact TomEE remote needs as a plain Tomcat a particular layout – it is not embedded, it makes it a bit harder to shade.
My advice would be to not try to rely on TomEE remote for an executable jar without using tomee:exec (detailed later).

Merging of conflicting resources

When using the maven-shade-plugin and taking the contents of several jars and turning them into one larger jar, it can be common to run into file conflicts that need to be handled.

Some cases, such as META-INF/services/ service providers, are solved smoothly with by shade plugin our of the box with the default configuration. Others require explicit action.

CXF and TomEE need META-INF/cxf/bus-extensions.txt extensions. Here you’ll get conflicts and you need to ensure merging is the same as the one done automatically for service providers. For it you can just rely onAppendingTransformer in your plugin config as shown below:

Recent OpenWebBeans versions need the build-in configuration files to be merged. Specifically, META-INF/openwebbeans/openwebbeans.properties files. Even if TomEE tries to ensure defaults are in place it is better to configure it:

Note: here we use AppendingTransformer to ensure we don’t miss any default key but if you want a full control of it in your application you can also merge it manually and provide the file (put it in META-INF/openwebbeans/openwebbeans.properties in src/main/resources in your project.

Feeling Lazy? Try tomee:exec

If you already used tomee-maven-plugin you are surely use to the tomee:run command but do you know about tomee:exec?

The tomee:exec goal is interesting since it will create an executable jar which will package a tomee distribution already set up with your application and a runner able to unpack it and run it. This works with any Maven war project, no Maven Shade Plugin or special setup required beyond adding the TomEE Maven Plugin to your pom.xml.

Once you packaged your application with a mvn clean install tomee:exec you can run it as easily as:

java -jar target/mytomeeapp.jar

If you want to override or configure the runtime properties passed to TomEE on start, you can use the additionalSystemProperties system property. So if you provided a server.xml setting the http port via my.http.port system property you can run it with:

Overview of MicroProfile Rest Client

One Comment

[…] package your Java EE based web apps as executable jar files. For example Tomitribe recently wrote a really nice summary of various ways of how TomEE can be packaged together with your web application to create an […]