Development Roles

Introduction

Administrator

Deployer

Assembler

Block Developer

Management guide

Introduction

Metadata

Structure

Using Scripts

You can start Loom in the foreground with the following command:

bin/run.[bat|sh]

On Windows versions other than NT, 2000, XP and 2003 Server, you'll need to set the LOOM_HOME environment variable first. To stop Loom running in the foreground simply used CTRL-C, which will cause a clean shutdown. Note that the additional argument -t is always given to Loom in the run.* scripts.

In UNIX environments, you can also use the loom.sh script to start, stop and restart Loom. It accepts the following (mutually exclusive) arguments

loom.sh [start|stop|run|restart|check]

The run arg is equivalent to using the run.sh script.

Using the Java Service Wrapper

Another option for starting and stopping Loom is to build it with support for the Java Service Wrapper.

The main benifit of using the Java Service Wrapper is that it can install Loom as a Linux/Unix deamon or a Windows NT service. It can also detect if the JVM freezes up or crashes and restart the application immediately.

The Loom distribution comes with both Linux and Windows Wrappers. To build Loom with a Wrapper for another Unix platform, simply change the wrapper.nix property in loom/distribution/project.properties to the appropriate platform and rebuild. Loom will cache each new distribution downloaded in the Maven local repository.

For usage instructions

cd bin/
wrapper

The Wrapper configuration file is named conf/wrapper.conf.

Additional arguments

Loom recognizes several arguments. These can be passed to it by the startup scripts or the Java Service Wrapper.

• -d,--debug-init Enable debug initialisation logs.
• -f,--configfile [argument] Use this configuration file.
• -h,--help Display a help message.
• -l,--log-file [argument] The name of Loom's log file.
• -p,--persistent Override the 'temporary' option, if it was given.
• -s,--std-out Log to STDOUT rather than to a file.
• -t,--temporary Shut down when there are no more applications running.

For example, to start Loom with the -p argument you would run

loom.sh start -p

JMX Overview

Loom is tightly integrated with Java Management Extensions (JMX). TODO: say something else. Integrate this section with the other JMX info.

How to Make Your Block an MBean

It's actually quite simple. Suppose you wanted to expose the interface from the WebServer block described in the Block developer's guide. You only need to do two things.

First, create an MBean interface. It will look something like this:

package examplecomp.block;

public interface WebServerMBean
{
    void mountWar( String contextName, URL pathToWar );
    void unMountWar( String contextName );
}

Notice that interface MBean is identical to interface WebServer. In most cases, it should be.

Now just make WebServerBlock implement WebServerMBean

package examplecomp.block;

/**
 * TODO: describe LoomXDoclet setup.
 * @mx.component name="examplecomp.block.WebServerMBean"
 */
public class WebServerBlock
    extends AbstractLoggable
    implements WebServer, WebServerMBean, Startable, Configurable, Initializable
{

    // ...

}

Using Http Adaptor

The MX4J Http Adaptor allows access to a running Loom server with any web browser.

To start the Http Adaptor you must uncomment the <enable-http-adaptor>true</enable-http-adaptor> tag and restart Loom. See kernel.xml for more comments about addresses, ports and optional authentication.

Then just point your browser to http://localhost:8082/. You should see a list of JMX MBeans you can control.

Under the section labled "Domain: Loom" you should see a familier looking name or two. They depend on the .sar file packaging and configuration, but the web server above would have a name similar to Loom:application=webserver,block=webserver,topic=WebServerMBean. If you click on the name, you'll find a form that allows you to mount and unmount .war files through the web!

If your aren't familiar with the guts of Loom, you may want to browse the source to understand what some of the other MBeans listed do. For example, Loom:component=Embeddor,topic=Embeddor allows you to restart and shutdown Loom. It also provides information, such as the server's start time and uptime, home directory, version, and build information.

Using RMI Adaptor

If you would like to write an agent that can administrate Loom programatically, you can use the MX4J RMI Adaptor. This section is basically duplicating information available in the MX4J documentation. Loom uses the JRMP RMI Adaptor.

Ensure that the MX4J RMI Adaptor is enabled in kernel.xml

<component role="org.codehaus.loom.interfaces.SystemManager"
           class="org.codehaus.loom.components.manager.MX4JSystemManager"
           logger="manager">
    <enable-rmi-adaptor>true</enable-rmi-adaptor>
    [other enabled adaptors]
</component>

Place mx4j-jmx.jar, mx4j-tools.jar, and jndi.properties in your classpath. Suppose you wanted to shut down Loom. Create the following class:

import mx4j.connector.rmi.jrmp.JRMPConnector;
import mx4j.connector.RemoteMBeanServer;
import javax.management.ObjectName;

public class JrmpShutdown
{
    public static void main( String[] args ) throws Exception
    {
        // Create a JRMPConnector
        JRMPConnector connector = new JRMPConnector();

        // Pass in the adaptor's JNDI name, no properties
        String jndiName = "jrmp";
        connector.connect( jndiName, null );

        // Get the remote MBeanServer from the connector
        // And use it as if it is an MBeanServer
        RemoteMBeanServer server = connector.getRemoteMBeanServer();

        ObjectName objName = new ObjectName( "Loom:component=Embeddor,topic=Embeddor" );
        server.invoke( objName, "shutdown", new Object[0], new String[0] );
    }
}

Compile and run – presto! The server stops.

Loom stops immediatly after starting

Make sure you have a .sar file in the apps/ directory, or pass the --persistent argument to the startup script if you start with bin/run.[sh|bat]. If you start with bin/run.[sh|bat] and there aren't any services running, Loom quits immediately. In this case you can actually stop the server by undeploying all registered applications through JMX (although that would be a strange way of doing it).