Guide - for Administrators

Avalon is a Server Framework that provides or will provide for central administration, server pooling, and quicker time to market. The framework defines a standard method of piecing together server components and creating a server.

This documentation will describe the care and feeding of the Avalon Phoenix kernel from the point of view of the administrator.

You can start Phoenix with the following command: > bin/run.[bat|sh]

In Windows versions other than NT, you'll need to set the PHOENIX_HOME environment variable first.

In UNIX environments, you can use the phoenix.sh script to stop Phoenix.

                      > phoenix.sh stop
                    

phoenix.sh accepts these commands: start, stop, run, restart, check.

In Windows, typing CONTROL-C will cause a clean shutdown.

Another option for starting and stopping Phoenix 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 Phoenix as an NT service. It can also detect if the JVM freezes up or crashes and restart the application immediately.

To build Phoenix with the Java Service Wrapper, download and extract the latest version. Next, in the root of the source tree, create or modify ant.properties so that it looks similar to this:

# ${base.path} points to the root of the Phoenix source tree
wrapper.home=${base.path}/wrapper_linux_3.0.0
wrapper.jar=${wrapper.home}/lib/wrapper.jar

# If you're using Linux/Solaris:
wrapper.exe=${wrapper.home}/bin/wrapper
wrapper.dll=${wrapper.home}/lib/libwrapper.so

# If you're using Windows:
wrapper.exe=${wrapper.home}/bin/Wrapper.exe
wrapper.dll=${wrapper.home}/lib/Wrapper.dll

Then just build as usual.

For usage instructions, move to the bin directory and type

                      > wrapper

                    

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

Phoenix 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 PhoenixXDoclet setup.
 * @phoenix:mx name="examplecomp.block.WebServerMBean"
 */
public class WebServerBlock
    extends AbstractLoggable
    implements WebServer, WebServerMBean, Startable, Configurable, Initializable {

    // ...

}

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

TODO: describe configuration methods when they settle down

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: Phoenix" 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 Phoenix: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 Phoenix, you may want to browse the source to understand what some of the other MBeans listed do. For example, Phoenix:component=Embeddor,topic=Embeddor allows you to restart and shutdown Phoenix. 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 Phoenix programatically, you can use the MX4J RMI Adaptor. This section is basically duplicating information available in the MX4J documentation. Phoenix uses the JRMP RMI Adaptor.

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

        <component role="org.apache.avalon.phoenix.interfaces.SystemManager"
            class="org.apache.avalon.phoenix.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 (TODO: include it) in your classpath. Suppose you wanted to shut down Phoenix. 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("Phoenix:component=Embeddor,topic=Embeddor");
        server.invoke(objName, "shutdown", new Object[0], new String[0]);
    }
}

Compile and run -- presto! The server stops.

Phoenix stops immediatly after starting, with no error message

Make sure you have a .sar file in the app/ directory. If there isn't a service running, Phoenix quits immediately. You can actually stop the server by undeploying all registered applications through JMX (although that would be a strange way of doing it). TODO: is this behavior a good thing?