January 6, 2009

Project Darkstar 0.9.8

Project Darkstar is, in the simplest description, an application server for games. What J2EE has done for business applications, we want Project Darkstar to do for MMOPGs, virtual worlds, and the like. If you've used a J2EE server such as Glassfish or JBoss, then you know that deployment and maintenance of applications into these containers is simple, and more importantly consistent. However, until just recently, this simplicity and consistency has been sorely lacking with Project Darkstar deployments.

Just before the holidays, we managed to roll a new release, version 0.9.8, of Project Darkstar. Officially announced today, this release features a major packaging improvement that greatly simplifies deployment, startup, and shutdown of Darkstar applications. Let's take a look at how this works.

At the heart of a deployment, is the Project Darkstar container itself. Unlike past releases, installing the server package is as simple as unzipping the distribution zip file. No additional steps are required. The extracted archive will leave a directory structure as follows:

- sgs-server-dist-0.9.8
  - NOTICE.txt
  - bin
  - conf
  - deploy
  - doc
  - lib
  - license
  - src
  - tutorial

The README file has a decent introductory explanation of this structure, but the main directories that you want to concentrate on are bin, conf, deploy, and lib:
  • bin - The bin directory contains two executable JAR files, sgs-boot.jar and sgs-stop.jar which are respectively used to startup and shutdown the container. Executing the command "java -jar /path/to/sgs-server-dist-0.9.8/bin/sgs-boot.jar" will startup the container and initialize the deployed application according to the configuration in the directories below.
  • conf - The conf directory contains three configuration files used for the runtime configuration of the system. The sgs-boot.properties file is used to configure the system environment and JVM configuration, the sgs-server.properties file represents the application configuration file which is fed to the Darkstar Kernel, and the sgs-logging.properties file is used as the java.util.logging.config.file during runtime.
  • deploy - The deploy directory contains all application-specific JAR files. When the container is booted up, these JAR files are automatically included in the JVM's classpath. Additionally, a single one of these JAR files can optionally include an embedded META-INF/app.properties file which is combined with the sgs-server.properties file from the conf directory to make up the set of properties used by the Darkstar Kernel. Out of the box, the deploy directory is empty and so booting up the container will immediately fail since there is no application to run.
  • lib - The lib directory suitably contains all of the JAR files required for any Project Darkstar application. These are automatically included in the JVM's classpath upon bootup of the container.
So we see above that the Project Darkstar container offers a rigid, well-defined structure, while at the same time being customizable and highly flexible. This brings us to the second component of a deployment, the Project Darkstar application. As stated previously, we want simplicity and consistency when developing and deploying an application into a container:
  • An additional feature of the 0.9.8 release of Project Darkstar is the explicit decoupling of the API interfaces from the implementation classes. The only compile-time dependency required when developing an app now is the sgs-server-api JAR file (found in the lib directory as well as the Maven repository). Simple.
  • Application specific Darkstar properties (e.g. com.sun.sgs.app.listener, etc.) can be bundled directly with the application by embedding a META-INF/app.properties Darkstar configuration file directly into your application JAR file. Simple. Consistent.
  • A Project Darkstar application is a JAR file or set of JAR files, one of which optionally contains a META-INF/app.properties Darkstar configuration file. Consistent.
  • A Project Darkstar application can be deployed into any Project Darkstar container by simply dropping the application JAR files into the deploy directory of the container and suitably tweaking the configuration files in the conf directory for your needs. Simple. Consistent.
There are other, subtle details about the flexibility and configuration of the container (including, among many things, how to use native libraries, how to use custom BDB libraries, how to use a different deploy directory, etc.) but I'll leave those for a separate discussion. In a future post, I'm hoping to case-study a real deployment using this new distribution.


  1. It is really very useful

  2. Hi Rick,

    The hands on lab given at JavaOne this year may be of interest to you: http://projectdarkstar.com/handsonlab/
    Also note that the website is currently undergoing some work that should help in the organization of some of the documentation. This should be rolled out pretty soon. Also, I would recommend the Project Darkstar forums as a very good resource for any questions you might have.

    Hope this helps.