owenkellett.com

About a month ago I spent a week in San Francisco for JavaOne 2009. One of the activities that I participated in there was the java.net Community Corner where I recorded a podcast on Project Darkstar. Well, the podcast is now up on the java.net site for download and it turned out really nice! It’s available for download here.

With Project Darkstar‘s new distribution structure (introduced in version 0.9.8 and explained here), people ask from time to time what the best way is to setup a project in Netbeans or Eclipse. I think the typical answer that you see the most fits the acronym “TMTOWTDI” (There’s More Than One Way To Do It). This is true but not necessarily very helpful. In the hopes of eliminating some pain I’m here to offer a way to setup a project in these IDE’s (but this should by no means be considered the way).

First, here is a quick description of the project and the tools that I will be using:

• This will be a purely server side project that will print “Hello Project Darkstar!” when the server is booted.
• I will be using Maven as the build tool for the project.
• The project will leverage the Project Darkstar Maven Plugin to aid in deploying, booting, and shutting down the server according to the new distribution format for the official Project Darkstar server package.
• It should be possible to build, run, and test the raw project outside of an IDE, within Netbeans, and also within Eclipse (with a few tweaks for each respective IDE).

There are three source files that are of interest in this project. The first is the actual Java source file that represents the main class for the server. This class should look something like this:

package my.pkg.hello;
 
import java.io.Serializable;
import java.util.Properties;
import java.util.logging.Level;
import java.util.logging.Logger;
import com.sun.sgs.app.AppListener;
import com.sun.sgs.app.ClientSession;
import com.sun.sgs.app.ClientSessionListener;
 
public class HelloProjectDarkstar implements AppListener, Serializable {
  private static final long serialVersionUID = 1L;
  private static final Logger logger = 
      Logger.getLogger(HelloProjectDarkstar.class.getName());
 
  public void initialize(Properties props) {
    logger.info("Hello Project Darkstar!");
  }
 
  public ClientSessionListener loggedIn(ClientSession session) {
    return null;
  }
}

Second, it is strongly recommended for a Project Darkstar application that you include an app.properties file in the META-INF directory of your resulting JAR file. This file will be used as the base set of configuration properties for the server and is a good place to include default values for application specific configuration properties. In our simple example, we’ll include just two required properties, the name of the server and the listener class:

com.sun.sgs.app.name=HelloProjectDarkstar
com.sun.sgs.app.listener=my.pkg.hello.HelloProjectDarkstar

Third, you need a Maven POM file. If you’re unaware of how Maven works, you can read up on it at the Maven website. Essentially, the POM file is used to declaratively describe your project’s resources and dependencies. Maven then uses this information to correctly build it. Our project has only one dependency (the sgs-server-api) so our POM file should look something like this:

<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
 
  <groupId>my.package.hello</groupId>
  <artifactId>hello-projectdarkstar</artifactId>
  <version>0.1-SNAPSHOT</version>
  <name>Hello Project Darkstar</name>
  <packaging>jar</packaging>
 
  <dependencies>
    <dependency>
      <groupId>com.projectdarkstar.server</groupId>
      <artifactId>sgs-server-api</artifactId>
      <version>${sgs-server.version}</version>
    </dependency>
  </dependencies>
 
  <build>
    <plugins>
      <!-- Use 1.6 for source and target during compile -->
      <plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-compiler-plugin</artifactId>
	<configuration>
	  <source>1.6</source>
	  <target>1.6</target>
	</configuration>
      </plugin>
    </plugins>
  </build>
 
  <properties>
    <sgs-server.version>0.9.9</sgs-server.version>
  </properties>
 
  <repositories>
    <repository>
      <id>java.net</id>
      <name>java.net Maven2 Repository</name>
      <url>http://download.java.net/maven/2/</url>
      <layout>default</layout>
    </repository>
  </repositories>
</project>

These three files should be organized in a directory structure that looks something like this:

- hello-projectdarkstar
  - pom.xml
  - src
    - main
      - java
        - my
          - pkg
            - hello
              - HelloProjectDarkstar.java
    - resources
      - META-INF
        - app.properties

At this point you should be able to build a JAR file that is deployable in a Project Darkstar server. Since this is a Maven project, this should be possible:

• From outside an IDE using the command mvn package
• From within Netbeans (ensure that you have the Maven plugin installed, then try “Open Project” and Netbeans should automatically detect that the root folder is a Maven project)
• Or from within Eclipse (ensure that you have the Maven plugin installed, then choose “Import” from the File menu and import as a “Maven project”).

This is all a good first step, but in order to boot up our server, we still need to manually take the JAR file that is built by Maven, deploy it into a Project Darkstar server, and then fire up the server. This is tedious, and we’d rather be able to do this using one command (or one click from the IDE). Enter the Project Darkstar Maven plugin. The plugin is pretty well documented on its website, but essentially what it does is automate the process of taking your built JAR file, deploying it into a Project Darkstar container, configuring the container with the appropriate configuration files, and then booting up the server. It also includes the capability to shutdown a running server. Using this, therefore, we can automate the process of running our Project Darkstar application by simply adding a configuration entry for this plugin into our POM in a separate Maven profile:

  <profiles>
    <profile>
      <id>run-server</id>
      <build>
	<plugins>
          <plugin>
            <groupId>com.projectdarkstar.maven.plugin</groupId>
            <artifactId>sgs-maven-plugin</artifactId>
            <version>1.0-alpha-3</version>
            <executions>
              <execution>
                <id>sgs-run</id>
                <phase>pre-integration-test</phase>
                <goals>
                  <goal>install</goal>
                  <goal>configure</goal>
                  <goal>deploy</goal>
                  <goal>boot</goal>
                </goals>
              </execution>
            </executions>
            <configuration>
              <version>${sgs-server.version}</version>
              <sgsHome>
                ${project.build.directory}/sgs-server-dist-${sgs-server.version}
              </sgsHome>
              <sgsBoot>${basedir}/conf/hello.boot</sgsBoot>
              <sgsServer>${basedir}/conf/hello.properties</sgsServer>
              <files>
                <file>${project.artifact.file}</file>
              </files>
            </configuration>
          </plugin>
        </plugins>
      </build>
    </profile>
  </profiles>

This configuration combines the install, configure, deploy, and boot goals of the sgs-maven-plugin into one. Also notice that there are two additional configuration files that are included in your source tree under the conf directory, hello.boot and hello.properties. These files are respectively used to replace the sgs-boot.properties and sgs-server.properties configuration files in the main Project Darkstar distribution. We can keep these files simple for now, but any set of valid configuration properties can be included:

# hello.boot
# =======
JAVA_OPTS = -server -Xmx768M
 
# hello.properties
# =======
com.sun.sgs.app.root=data

So we now have a complete project that looks something like this:

- hello-projectdarkstar
  - conf
    - hello.boot
    - hello.properties
  - pom.xml
  - src
    - main
      - java
        - my
          - pkg
            - hello
              - HelloProjectDarkstar.java
    - resources
      - META-INF
        - app.properties

The project can be built inside or outside of Netbeans or Eclipse using the same mechanisms as described above. However, with this additional configuration, we can also automatically build, deploy, and boot the application in a Project Darkstar container by simply activating the run-server Maven profile. When this is done, Maven will build the project JAR file, download and install the Project Darkstar distribution into the project’s target directory, deploy the built JAR file into the Project Darkstar installation, copy the hello.boot and hello.properties configuration files into the Project Darkstar installation conf directory, and then boot up the server using the sgs-boot.jar from the Project Darkstar installation. This is completely automated and requires doing just the following for each of our respective environments:

• From outside any IDE: just run the command mvn verify -Prun-server. Shutting down the server requires simply a Ctrl-C. Also, in order to clean out the Project Darkstar datastore in between executions, it is necessary to run mvn clean.
• From Netbeans: You should configure the properties of the project by right clicking the project and selecting the “Properties” option. Configure a new Action (or one of the existing actions like the “Run” action) to run the verify goal with the run-server profile activated. Then you should be able to boot up the server by executing that specific action for your project (Right click the project and choose “Run” or whatever action you created under the “Custom” menu). In order to shutdown the server, you should also configure an additional action (i.e. Stop) that runs the sgs:stop goal with the run-server profile activated. Prefer using this action to shutdown the server rather than just killing the process (since multiple JVMs are started when Project Darkstar boots).
• From Eclipse: Similar to Netbeans, you need to configure two “Run Configurations”, one that runs the verify goal with the run-server profile activated, and one that runs the sgs:stop goal with the run-server profile activated. These two configurations should be respectively used to bootup and shutdown the server.

There are a lot more sophisticated ways that you can setup your project with the Project Darkstar Maven plugin that allows you to customize the runtime environment from the command line. You can also tweak it to support booting multi-node configurations by modifying the boot configuration file, or use filterable properties to customize these values at runtime. I won’t get into these here, but I would suggest looking at Project Snowman’s server POM for some ideas. Hopefully, though, this post should give you enough to get the ball rolling in setting up your development environment for a Project Darkstar application.