loom - HelloWorld Demo

HelloWorld Demo

Introduction

The 'Hello World' demo is a server component that manages a greeting message. It has a socket listener that replies with the greeting to client applications that open the port.

The reply is in HTML form so it can be viewed by a Browser. The HTTP headers are missing, but it still works. It is also possible to view the message vith a telnet client.

Architecture

The application consists of three separate blocks, helloworldserver, connections and sockets.

The connections and sockets blocks are part of Spice Netserve. Netserve is a set of tools for people wrinting network servers.

Source modules

The HelloWorld demo comprises of the following modules, all contained within the src/ directory:

org.codehaus.loom.demos.helloworld Contains the Java source for 'Hello World'.

conf/assembly.xml Contains the assembly instructions for the resulting server archive (SAR) file.

conf/config.xml Contains the configuration for the resulting server archive (SAR) file.

conf/environment.xml Contains instructions about the environment, here only logging.

Java Source

HelloWorldServer.java

The interface that's the contract for the Server block. It defines methods for getting and setting the greeting message.

HelloWorldServerImpl.java

This like all impl classes implements an interface. Which interface is rather obvious in this case. It's a standard pattern that uses other blocks (Sockets and Connections) to do the hard work of listening on a port, pooling threads and connections and organizing socket invokations in a queue.

HelloWorldHandler.java

Instantiated and registered to serve as a request handler for the connections block by HelloWorldServerImpl. HelloWorldHandler has a reference back to the server implementation, so it can fetch the greeting message when serving requests.

Configuration

assembly.xml

The bulk of the contents of the file pertain to other blocks including ones that HelloWorld is dependant upon. Here's the section that's for HelloWorld:

<block class="org.codehaus.loom.demos.helloworld.HelloWorldServerImpl"
  name="helloworldserver">
    <provide name="sockets"
      role="org.codehaus.spice.netserve.sockets.ServerSocketFactory"/>
    <provide name="connections"
      role="org.codehaus.spice.netserve.connection.SocketAcceptorManager"/>
</block>

Of the block element, listed attributes are the instatiatable class implementing the HelloWorld interface (not mentioned itself in this assembly.xml), the display name of the block, and two services that HelloWorld needs.

assembly.xml reference documentation

config.xml

Again here is the pertinent section:

<helloworldserver>
    <port>8999</port>
    <bind>127.0.0.1</bind>
</helloworldserver>

The configuration element named <helloworldserver> is used as it's name suggests and is passed the blocks being used for the app. Elements port and bind are used to get a server socket from the socket manager (sockets block).

If you had configuration for an app, you'd specify it here in with element and attribute names that are invented for the application.

config.xml reference documentation

environment.xml

Helloworld's environment configuration is very simple. What it basically defines is one log category for all components and a log file as target for it.

<logs>
    <category name="" target="default" priority="INFO"/>
    <log-target name="default" location="/logs/demo.log"/>
</logs>

To see more logs set the priority to DEBUG.

environment.xml reference documentation

Unpacking of SAR files

Loom unpacks everything but the SAR-INF/lib/ directory from a SAR. Once the SAR has been unpacked to the apps/demo-helloworld/ directory Loom will not attempt to unpack it again. So if you replace the demo-helloworld.sar file with a new version, you must remove the apps/demo-helloworld/ directory, or individual files in it, for configuration changes to take effect. Without this behavior important information could be overwritten when updating packages.

Management

Perhaps you noticed the mx. tags in HelloWorldServerImpl's Javadoc headers. These tell Loom how the application can be managed.

To enable management via HTTP you need to uncomment the  in conf/kernel.xml. When you have done this and restarted Loom, point your web browser to http://localhost:8082 and you will se a management GUI in HTML.

Now scroll dowm to the section "Domain: Loom Engine". Here you can see a subsection "Loom Engine:application=demo-helloworld,block=helloworldserver". Click on this one to see the operations HelloWorld exports. Try "setGreeting" and see what it does. If everything went well you should see the changes from HelloWorlds response handler.

For more information about management in Loom read the Management guide

Hot Deployment

Loom can deploy, undeploy and redeploy application on the fly. In UNIX you can test this by simply touching a SAR file.

First in one shell:

tail -f ./apps/demo-helloworld/logs/demo.log

Then in anoter shell:

touch ./apps/demo-helloworld.sar

Now you should see HelloWorldServerImpl's output saying that it is shutting down, and starting again.

For a more advanced test, recompile HelloWorld with a different initial message (m_greeting) and copy the new demo-helloworld.sar over the old one while loom is running. Remember that Loom will not overwrite configuration files if they already exist.

If you remove a SAR or rename its extension to something else than .sar the application will be removed from the kernel. Copying the file back, or remaning it to its original name will load the application again.

Starting your own project

Familiarity with Maven and its build system would be a good place to start. Simply.

cd demos/helloworld
maven

Documentation example

HelloWorld has an example of documentation building. When you have build Loom, goto HelloWorld's directory and run:

maven docs

This will generate a site in the target/docs directory. See the generated docs for more info and an example of some possible documentation tags.

To understand maven in more detail it is necessary to study its own documentation. The plugin documentation is also important.

Overview

Users guide

Development Roles

Management guide

Reference

Applcations

Project Info

Misc

Feeds