Loom is a server application that provides or will provide central administration, server pooling, and quicker time to market. It defines a standard method of piecing together server components and creating a server.
This documentation will describe the care and feeding of the Loom kernel from the point of view of the administrator.
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.
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.
Loom recognizes several arguments. These can be passed to it by the startup scripts or the Java Service Wrapper.
For example, to start Loom with the -p argument you would run
loom.sh start -p |
Loom is tightly integrated with Java Management Extensions (JMX). TODO: say something else. Integrate this section with the other JMX info.
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
{
// ...
}
|
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.
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.
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).