TomEE Embedded And Gradle

TomEE 7.0.0 was just released and brings in its new features a surprising and interesting one: a better Gradle integration. This means a better support of gradle build layout for embedded tests but also a new official TomEE embedded Gradle plugin.

TomEE already got several non-official gradle plugins but they all got some known issues like:

• Disappearing from github/repositories
• Bringing back TomEE in the build classpath (which means potentially having lots of conflicts with other plugins)
• Not supporting TomEE embedded classpath deployment

The new TomEE embedded Gradle plugin design is centered on the flat classpath case and aims to make web development easier.

Gradle + TomEE: get started

To get started, you just need to reference the TomEE embedded plugin. The plugin is on central so you need mavenCentral() if not already used :

buildscript {
   repositories {
       mavenCentral()
   }

   dependencies {
       classpath 'org.apache.tomee.gradle:tomee-embedded:7.0.0'
   }
}

apply plugin: 'org.apache.tomee.tomee-embedded'

So a hello world gradle.build file would look like:

buildscript {
   repositories {
       mavenCentral()
   }

   dependencies {
       classpath 'org.apache.tomee.gradle:tomee-embedded:7.0.0'
   }
}

apply plugin: 'org.apache.tomee.tomee-embedded'

group 'test'
version '1.0-SNAPSHOT'

apply plugin: 'groovy'
apply plugin: 'war'

sourceCompatibility = 1.8

repositories {
   mavenCentral()
}

dependencies {
   providedCompile 'org.apache.tomee:javaee-api:7.0'
}

Once all is setup and your classes are built (you don’t need to package them) you can run:

gradle tomee-embedded

By doing that, you will likely think the server is hanging because, by default, Gradle is not logging much.
To solve it and to see TomEE startup, just add the Gradle option -i :

gradle tomee-embedded -i

TomEE Gradle plugin configuration

You can configure the plugin using the extension tomee-embedded and set the TomEE version you want there (default is the same as the plugin) :

extensions.getByName('tomee-embedded').tomeeVersion = 'other version'

You can also require to skip the default repository used to find tomee (i.e. maven central) :

extensions.getByName('tomee-embedded').skipDefaultRepository = true

Which means tomee will fetch from the repositories you declared and maven central will not be automatically added.

Once this configuration is done, the plugin creates a configuration (“classpath” in gradle world) named tomee-embedded (which means you can update it as well programmatically in gradle.build) and add this org.apache.tomee:tomee-embedded dependency. If you need more “container libraries”, just add the dependencies you need to this configuration.

Thanks to this configuration the plugin itself doesn’t depend on tomee and doesn’t bring back all tomee dependencies to the build script classpath, which should already avoid several issues and allow to customize it easily.

Finally, as seen in previous samples, the plugin registers a task called tomee-embedded. This is a highly customizable task which is pretty close to its maven friend allowing you to:

• Configure container properties
• Configure container ports/connectors
• Configure deployment context and docBase
• Configure container classpath (you can replace their previous configuration if you desire)
• Modules/libraries to deploy and dependency scopes to take into account
• Etc ...

Tip: with such a configuration, you can easily start multiple TomEE instances and applications by overriding their configurations (to create gradle tomee1 -i and gradle tomee2 -i to test clustering or a distributed security infrastructure with an identity provider for instance).

Conclusion

This is a first step in Gradle world for TomEE. The obvious goal is to ensure that TomEE experience is as smooth as jetty was, but with a stack you are used to.

There are still a lot of potential improvements and directions:

• Should the task configuration be copied in the extension/global configuration? This has pros and cons but could simply default configuration.
• Should we rename configuration and extension tomeeEmbedded or something else to let Gradle support it without requiring getByName() usage?
• Should we also create a tomee-remote plugin like the one we have for Maven? (this doesn’t make much sense just to start TomEE since it is 1 line, but can provide a better “API” and some advanced features like tomee:build or tomee:exec)?

As a TomEE developer I have to admit we have not enough feedback from Gradle users. Thus, I’m not sure it is not used, but maybe they have different habits from Maven users. If you use TomEE (from tests to deployment without forgetting web development) don’t hesitate to send us a mail on tomee mailing list (dev@tomee.apache.org) to give us some feedback or even help us improve Gradle users experience!