Building Plexus Applications and Runtimes

To be able to build Plexus applications and runtimes you'll need:

  • The Plexus mojo
  • The Plexus application archetype
  • The Plexus runtime archetype

    TODO: Make a link to the maven site that explains what a archetype is.

Introduction

Some stub directories will be created:

/my-component
- Here we'll make a Plexus component
/my-application
- Here we'll make an application
/my-runtime
- Here we'll make a runtime that will host your application. This runtime will contain startup scripts for Unix, Windows and OS X and will be completly standalone.

Creating a Simple Plexus Component

Making the Component Stub

$ mvn archetype:create \
     -DarchetypeGroupId=org.codehaus.plexus \
     -DarchetypeArtifactId=plexus-archetype-component-simple \
     -DarchetypeVersion=1.0-alpha-1-SNAPSHOT \
     -DgroupId=mygroup \
     -DartifactId=my-component \
     -Dversion=1.0-SNAPSHOT \
     -Dpackage=my.component

Building the Plexus Component

To build the component simply type in /my-component:

$ mvn install

You should now have a packaged Plexus component in target/my-component-1.0-SNAPSHOT.jar

Creating a Simple Plexus Application

Making the Application Stub

$ mvn archetype:create \
     -DarchetypeGroupId=org.codehaus.plexus \
     -DarchetypeArtifactId=plexus-archetype-application \
     -DarchetypeVersion=1.0-alpha-1-SNAPSHOT \
     -DgroupId=mygroup \
     -DartifactId=my-application \
     -Dversion=1.0-SNAPSHOT \
     -Dpackage=my.app

Adding the Plexus Component dependency

You need to add the following dependency in /my-application pom:

    <dependency>
      <groupId>mygroup</groupId>
      <artifactId>my-component</artifactId>
      <version>1.0-SNAPSHOT</version>
    </dependency>

and in src/conf/application.xml, add this so the Plexus component will be loaded at startup:

  <load-on-start>
    <component>
      <role>mygroup.HelloWorld</role>
    </component>
  </load-on-start>

Building the Plexus Application

To build the application simply type in /my-application:

$ mvn plexus-appserver:assemble-app

and you should have a application in target/plexus-application. Inside the exploded application there will be two directories: conf and lib. The conf directory contains the configuration file for your application and lib contains all the dependencies the application has.

If you want to do some extra processing on these files or possibly add your own files you can have a plugin with a post goal on plexus:app and it would be invoked before the application was packaged.

If you now run the plexus-appserver:package-app goal:

$ mvn plexus-appserver:package-app

the resulting JAR file will be ready for deployment in a Plexus runtime. Our example application JAR will be target/my-application-1.0-SNAPSHOT.jar.

you can run the above commands in one:

$ mvn install

Creating the Runtime

Making the Runtime Stub

Creating the stub runtime is as easy as creating the application:

$ mvn archetype:create \
     -DarchetypeGroupId=org.codehaus.plexus \
     -DarchetypeArtifactId=plexus-archetype-runtime \
     -DarchetypeVersion=1.0-alpha-1-SNAPSHOT \
     -DgroupId=mygroup \
     -DartifactId=my-runtime \
     -Dversion=1.0-SNAPSHOT \
     -Dpackage=my.runtime

Building the Runtime

$ mvn package

You should now have a usable runtime in target/plexus-runtime and a packaged runtime in target/my-runtime-1.0-SNAPSHOT.jar. Now lets copy over the application:

$ cp ../my-application/target/my-application-1.0-SNAPSHOT.jar \
     target/plexus-app-runtime/apps

You can also add a dependency on my-application in the my-runtime pom, so it won't be necessary to copy the application manually in the runtime.

    <dependency>
      <groupId>mygroup</groupId>
      <artifactId>my-application</artifactId>
      <version>1.0-SNAPSHOT</version>
      <type>plexus-application</type>
    </dependency>

Now you have a working Plexus runtime with your application installed. To start it run:

$ sh target/plexus-app-runtime/bin/plexus.sh

Hopefully you should now have a runtime running with. The message "Starting Hello Component." sended by my-component at startup must appears in logs.

Getting fancy: Adding a Shared Servlet Container

Plexus runtimes can have a set of services thats shared between the applications. One very useful service is a servlet container. This enables several isolated applications to share the same Jetty instance without the need for complicated Apache HTTPD proxy setups. The servlet container service will all the web in a configured directory. The application contains a commented out configuration section for the servlet container which you must uncomment so the service would be enabled.

NOTE: This example assumes that you have the runtime that was created in the last section.

First add the service dependency into the runtime:

    <dependency>
      <groupId>org.codehaus.plexus</groupId>
      <artifactId>plexus-appserver-service-jetty</artifactId>
      <version>2.0-alpha-1</version>
      <type>plexus-service</type>
    </dependency>

Now we need to add a web application to the application. As a simple web application we're using the Jetty JavaDocs. Add this in my-application pom:

    <dependency>
      <groupId>jetty</groupId>
      <artifactId>javadoc</artifactId>
      <version>4.2.23RC0</version>
      <type>war</type>
    </dependency>

Now we need to configure the servlet container service so it knows where to find the web applications. In src/conf/application.xml uncomment the servlet container section. Now bundle the application again:

$ mvn install

We suppose there you added my-application dependency in my-runtime pom. Execute this commands from /my-runtime

$ mvn package

Now when the application server is started again it should

  • Deploy the servlet container.
  • Boot Jetty.
  • Deploy the application.
  • The servlet container will detect that a new application was deployed and deploy the JavaDoc WAR.

    So lets start it:

    $ sh target/plexus-app-runtime/bin/plexus.sh

    And open your browser to http://localhost:8080/