Tuesday, November 12, 2013

Running your applications with TomEE plugin for Maven and Maven Profiles

This post shows:
  • an use case for TomEE Maven Plugin;
  • an use case for Maven Profiles;
  • how to start up multiple instances of TomEE with TomEE Maven Plugin;
  • a new sample application [Launcher].

Do you want to see your programmers happy? You don’t need parties, free coffee, snacks and beer. Just give your developers an easy way to build, test and run their code. I have good news: this is possible with Maven, TomEE and TomEE plugin for Maven. Everyone will be happy! Ok, beer also helps. ;)

Let's go straight to our sample of the day. Do you remember our three main projects?
Msglnk [Scala with YUI]
FaceID [Groovy with ExtJS]
PhotoDB [Java with BackboneJS]

PhotoDB, FaceID and MsgLnk are designed to work together as a solution. PhotoDB handles our pictures; FaceID handles our users; MsgLnk handles our communication (email and JMS). Despite being part of a solution, they can also run as standalone applications. In fact, they don't even know about the existence of each other. The app-to-app communication is via JMS.

  • Download PhotoDB here;
  • Download FaceID here;
  • Download MsgLnk here.

In order to run these applications on stand-alone mode, download and extract the source code in a directory of your choice and execute the following command in the project root directory:

 mvn clean install tomee:run  

The command above builds, installs and deploy your project. Once TomEE is online, you should be able to access your application at one of these links:


Note that the previous command starts an application on stand-alone mode. If you start all three applications like that, they won't talk to each other because we would have three instances of the ActiveMQ server. It's very easy to start the applications on "solution" mode though. Just use the "solution" maven profile...

 mvn clean install tomee:run -P solution  

Pictures! Note that we use Java, so these steps are multi-platform.







Repeat the steps above for each application. It will seem like you are downloading the entire Internet. Well, someone else is doing it for you. Maven downloads approximately 250MB of binaries the first time you execute the command. It's a good thing you don't need to worry about that! :)


It looks good, but you may be wondering what the heck does that command mean? It's a combination of three commands with extra parameters. You can do the same thing with...

 mvn clean  
 mvn install 
 mvn tomee:run -P solution  

  • The first command cleans up the target directory of your application.
  • The second one builds and installs the application binaries in your local maven repository.
  • The third one executes the run goal of the tomee plugin with the solution profile.

What does "solution" profile mean? Maven Profiles is a big topic. I advise you to go take a look at this documentation. For short, in our case, this is a way to set variables according to what we want to do.

Our applications have only one real profile: solution. The only way to activate this profile is by passing it along with the -P flag.

Every time we run mvn tomee:run, the plugin starts a new TomEE+ instance. Every TomEE+ server starts its own ActiveMQ server by default. On solution mode, we want to have only one ActiveMQ instance. All our applications should use that single instance as JMS broker. When running on solution mode, PhotoDB and FaceID do not start their instances of the ActiveMQ server. All the applications will use the one started by the MsgLnk.

It's easy to disable the ActiveMQ of a TomEE server...

  <Resource id="MyJmsResourceAdapter" type="ActiveMQResourceAdapter">  
   # Do not start the embedded ActiveMQ broker  
   BrokerXmlConfig =  
   ServerUrl = tcp://localhost:61616  
  </Resource>  
  <Resource id="MyJmsConnectionFactory" type="javax.jms.ConnectionFactory">  
   ResourceAdapter = MyJmsResourceAdapter  
  </Resource>  
  <Container id="MyJmsMdbContainer" ctype="MESSAGE">  
   ResourceAdapter = MyJmsResourceAdapter  
  </Container>  

The TomEE maven plugin is super flexible. Among its many options, there is the config one. It defines the directory that contains TomEE configuration files. Anything you put in this directory will be copied to or will override the files in apache-tomee/conf. Here we see how the Maven profiles can be useful. We can override config values by using it.

  <profiles>  
   <profile>  
    <id>solution</id>  
    <properties>  
     <tomee.config.dir>${project.basedir}/src/main/tomee/network/conf</tomee.config.dir>  
     <tomee.args>-Xmx512m -XX:PermSize=256m -Djava.security.auth.login.config=${project.basedir}/src/main/tomee/network/conf/login.config</tomee.args>  
    </properties>  
   </profile>  
  </profiles>  

See how the plugin configuration would look like.

    <plugin>  
     <groupId>org.apache.openejb.maven</groupId>  
     <artifactId>tomee-maven-plugin</artifactId>  
     <version>${tomee.version}</version>  
     <configuration>  
      <context>photodb</context>  
      <config>${tomee.config.dir}</config>  
      <args>${tomee.args}</args>  
      <tomeeClassifier>plus</tomeeClassifier>  
      <debugPort>5005</debugPort>  
      <tomeeAjpPort>8009</tomeeAjpPort>  
      <tomeeHttpPort>8080</tomeeHttpPort>  
      <tomeeShutdownPort>8005</tomeeShutdownPort>  
      <debug>false</debug>  
     </configuration>  
    </plugin>  

Note that the plugin configuration uses variables set by the profile (tomee.config.dir and tomee.args).

Resources

Wait! There is a third way to start up all three applications: https://github.com/tveronezi/launcher. The Launcher is just a wrapper application. It uses the TomEE plugin to retrieve and start PhotoDB, FaceID and MsgLnk in a single TomEE instance.

Download the source-code here, unzip it, and execute...

 mvn clean install tomee:run  

Once you see...
... you should be able to access http://localhost:8080/.


That's it! Have fun!