	Terracotta Public Wiki	Log In
	Terracotta Maven Plugin

Added by Orion Letizi, last edited by Eugene Kuleshov on Nov 20, 2007 (view change)

Terracotta Maven Plugin

For the most recent info see Terracotta Forge web site

The following goals are supported:

tc:bootjar - build bootjar
tc:start - start DSO server
tc:stop - stop DSO server
tc:restart - restart DSO server
tc:admin - start DSO administration UI
tc:run - run multiple DSO-enabled processes (it also builds a boot jar, starts the DSO server before running these processes and stops it after they complete)
tc:terminate - stops DSO-enabled web servers started with tc:run (these processes don't finish on their own and need to be brought down)
tc:run-integration - same as tc:run, but don't start DSO server and don't wait for when started processes complete (convenient for the integration tests)
tc:terminate-integration - same as tc:terminate but also stops DSO server (convenient for the integration tests)
tc:test - run surefire/junit tests in multiple DSO-enabled processes (similar to tc:run), it also synchronizes these tests automatically

If you have ideas or suggestions for other goals please don't hesitate to share.

Note for Windows users
Browsing the Repository
Configuration
Launching DSO-enabled processes
Integration with Cargo
Using Cargo integration with integration tests
Choosing Terracotta runtime version
Example projects
Building and installing plugin
Building and installing required jars from the DSO code

Note for Windows users

For the moment our classpath is really long and exceeds limit (8K) imposed by Windows. Normally, Maven2 repo folder locates at C:\Documents and Settings\<username>\.m2

You can get around the long classpath problem by settings the repo to a shorter path. Create settings.xml under C:\Documents and Settings\<username>\.m2

<settings>
  <localRepository>c:/repo</localRepository>
</settings>

Browsing the Repository

The Terracotta maven artifacts are hosted on Amazon's S3 and, therefore, aren't browseable. If you'd like to see the contents of the maven repository, you can use Hung's nifty JavaScript browser:

http://www.terracotta.org/download/reflector/maven2/index.html

Configuration

To enable plugin you need to register it in the plugins section of pom.xml and optionally bind to the build phases. The Following plugin configuration will make run tc:bootjar when "mvn package" or "mvn install" is executed. Commented elements represent defaults that can be overridden:

<project ...
  ...

  <pluginRepositories>
    <pluginRepository>
      <id>terracotta-snapshots</id>
      <url>http://www.terracotta.org/download/reflector/maven2</url>
      <releases>
        <enabled>true</enabled>
      </releases>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
    </pluginRepository>
  </pluginRepositories>

  <build>
    <plugins>
      <plugin>
        <groupId>org.terracotta.maven.plugins</groupId>
        <artifactId>tc-maven-plugin</artifactId>
        <version>0.0.5-SNAPSHOT</version>

        <configuration>
          <!-- used by tc:bootjar -->
          <!-- <verbose>true</verbose> -->
          <!-- <overwriteBootjar>true</overwriteBootjar> -->
          <!-- <bootJar>target/bootjar.jar</bootJar> -->

          <!-- used by tc:start and tc:stop so DSO server could outlive mvn process -->
          <!-- <startServer>true</startServer> -->
          <!-- <spawnServer>true</spawnServer> --> 
          <!-- <config>${basedir}/tc-config.xml</config> -->
          <!-- <jvm>C:\jdk1.6.0\bin\java.exe</jvm> -->
          <!-- <jvmargs>-Xmx20m</jvmargs> -->
          ...
        </configuration>

        <executions>
           <execution>
              <phase>package</phase>
              <goals>
                 <goal>bootjar</goal>
              </goals>
           </execution>
        </executions>
      </plugin>
   ...

Launching DSO-enabled processes

tc:run goal allows to launch several DSO-enabled processes. Processes can be configured using <process> element. For example:

<plugin>
        <groupId>org.terracotta.maven.plugins</groupId>
        <artifactId>tc-maven-plugin</artifactId>
        <version>0.0.5-SNAPSHOT</version>
        ...

        <configuration>
          ...
          <!-- used by tc:run -->
          <!-- <workingDirectory>working directory of the process</workingDirectory> -->
          <!-- <activeNodes>master,sample0,sample1</activeNodes> -->

          <processes>
            <process nodeName="master" count="1" jvmargs="-Xmx20m"
                className="org.terracotta.maven.plugins.tc.test.MasterProcess"/>
            <process nodeName="sample" count="2" jvmargs="-Xmx20m"
                className="org.terracotta.maven.plugins.tc.test.SampleProcess"/>
          </processes>
        </configuration>
      </plugin>
      ...

You can choose which nodes need to be started (i.e. when you need to start them on separate physical boxes):

mvn -DactiveNodes=master,sample0 tc:run
mvn -DactiveNodes=sample1 tc:run

Integration with Cargo

A <processes> element also allow to wrap web application server configuration from Cargo. See <container> element in the example below:

...
  <profiles>
    <!-- Tomcat profile -->
    <profile>
      <id>tomcat5x</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <build>
        <plugins>
          <plugin>
            <groupId>org.terracotta.maven.plugins</groupId>
            <artifactId>tc-maven-plugin</artifactId>
            <version>0.0.5-SNAPSHOT</version>
            <configuration>
              <processes>
                <process nodeName="cargo" count="2">
                  <container>
                    <containerId>tomcat5x</containerId>
                    <zipUrlInstaller>
                      <url>http://www.apache.org/dist/tomcat/tomcat-5/v5.5.25/bin/apache-tomcat-5.5.25.zip</url>
                      <installDir>${user.home}/cargo/tomcat5x</installDir>
                    </zipUrlInstaller>
                  </container>
                </process>
              </processes>
            </configuration>
          </plugin>
        </plugins>
      </build>
    </profile>
    ...

With the above example you could download, install, configure and start two clustered Tomcat containers using single command. With separate profiles for each container you can even chose which server type should be started:

mvn -Ptomcat5x tc:run

or with active node selection:

mvn -Ptomcat5x -DactiveNodes=cargo0 tc:run
mvn -Ptomcat5x -DactiveNodes=cargo1 tc:run

Started servers could be brought down using tc:terminate goal:

mvn -Ptomcat5x tc:terminate

Using Cargo integration with integration tests

Server cluster can be also configured to start before execution of the integration tests and automatically shutdown upon test completion:

<build>
    <plugins>
      <plugin>
        <groupId>org.terracotta.maven.plugins</groupId>
        <artifactId>tc-maven-plugin</artifactId>
        <version>0.0.6-SNAPSHOT</version>
        <executions>
          <execution>
            <id>run-integration</id>
            <phase>pre-integration-test</phase>
            <goals>
              <goal>run-integration</goal>
            </goals>
          </execution>
          <execution>
            <id>terminate-integration</id>
            <phase>post-integration-test</phase>
            <goals>
              <goal>terminate-integration</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      ...

Choosing Terracotta runtime version

By default, plugin is using Terracotta runtime declared in the plugin's pom.xml (2.5.0-SNAPSHOT vot plugin version 0.0.6-SNAPSHOT), but these dependencies can be overwritten in user's pom.xml. For example:

<build>
    <plugins>
      <plugin>
        <groupId>org.terracotta.maven.plugins</groupId>
        <artifactId>tc-maven-plugin</artifactId>
        <version>0.0.6-SNAPSHOT</version>
        ...
        <dependencies>
          <dependency>
            <groupId>org.terracotta</groupId>
            <artifactId>terracotta</artifactId>
            <version>2.5.0-SNAPSHOT</version>
          </dependency>
          <dependency>
            <groupId>org.terracotta</groupId>
            <artifactId>tcconfig</artifactId>
            <version>2.5.0-SNAPSHOT</version>
          </dependency>
        </dependencies>
      </plugin>
      ...

Example projects

There are several example projects under "maven-tc-plugin/examples" folder.

/tc-maven-plugin-sample - can be used to try tc:run goal to run two DSO-enabled JVMs with SampleProcess main class
/tc-maven-sample-surefire - can be used to try tc:test goal to run two DSO-enabled JVMs with SampleTest JUnit test
/tc-maven-webapp - can be used to try tc:run and tc:terminate goals to run two clustered Tomcat instances (after starting you can point web browser to http://localhost:8080/tc-maven-webapp/) and also shows how to start clustered Tomcat instances before running integration test (WebappTest) when running Maven's verify goal.

You can get the source code from svn

svn co http://svn.terracotta.org/svn/forge/projects/maven-tc-plugin/trunk  maven-tc-plugin

and then run the following command from maven-tc-plugin/examples/tc-maven-plugin-sample folder:

mvn tc:run

or if you need to keep DSO server running you could also do something like this:

mvn tc:start
mvn -DstartServer=false tc:run
mvn tc:stop

Building and installing plugin

You can grab maven-tc-plugin from svn:

svn co http://svn.terracotta.org/svn/forge/projects/maven-tc-plugin/trunk  maven-tc-plugin

Then you can install it to your local Maven repository using the following command from the project folder:

mvn install

Building and installing required jars from the DSO code

Required dependencies are automatically downloaded from the Maven repository at http://www.terracotta.org/download/reflector/maven2 but if needed, they can be built from the Terracotta source code. See more details at the Building+Terracotta page.

Get the Terracotta source code from trunk:

svn co https://svn.terracotta.org/repo/tc/dso/trunk

and then build it using using following command from the code/base folder:

tcbuild dist_maven maven.version=2.5-SNAPSHOT

It will install all Terracotta jars and config modules to local Maven repository.

Alternatively you could download the nightly build and manually install the corresponding jars to local Maven repository:

set tc=C:\dev\terr\tc-trunk\code\base\build\dist\terracotta-trunk\lib

call mvn install:install-file -DgeneratePom=true -DgroupId=org.terracotta 
  -DartifactId=terracotta -Dversion=2.4 -Dpackaging=jar -Dfile=%tc%\tc.jar
call mvn install:install-file -DgeneratePom=true -DgroupId=org.terracotta 
  -DartifactId=tcconfig -Dversion=2.4 -Dpackaging=jar -Dfile=%tc%\tcconfig-xmlbeans-generated.jar
call mvn install:install-file -DgeneratePom=true -DgroupId=org.terracotta
  -DartifactId=tcconfig1 -Dversion=1.0 -Dpackaging=jar -Dfile=%tc%\tcconfigV1.jar
call mvn install:install-file -DgeneratePom=true -DgroupId=org.terracotta
  -DartifactId=tcconfig2 -Dversion=2.0 -Dpackaging=jar -Dfile=%tc%\tcconfigV2.jar

I this case you will also need to copy content of the modules/ folder from the Terracotta kit into the root of local Maven repository.

Menu

Quick Links

Community Resources

Architecture, Testing, and Tuning

Integrations Discussions

Misc