Index: build.xml =================================================================== RCS file: /home/cvspublic/jakarta-avalon-phoenix/build.xml,v retrieving revision 1.164 diff -u -r1.164 build.xml --- build.xml 6 Sep 2002 13:56:06 -0000 1.164 +++ build.xml 8 Sep 2002 21:32:38 -0000 @@ -90,7 +90,7 @@ - + Index: src/xdocs/guide-administrator.xml =================================================================== RCS file: /home/cvspublic/jakarta-avalon-phoenix/src/xdocs/guide-administrator.xml,v retrieving revision 1.4 diff -u -r1.4 guide-administrator.xml --- src/xdocs/guide-administrator.xml 16 Jun 2002 10:21:45 -0000 1.4 +++ src/xdocs/guide-administrator.xml 8 Sep 2002 21:32:38 -0000 @@ -19,13 +19,234 @@ Phoenix kernel from the point of view of the administrator.

- -

We currently have no info on this whatsoever. However, this doesn't - mean that Phoenix is not easy to administrate - the contrary is true, - since our tight integration with JMX exposes the entire kernel at - runtime. -

+ +
+ +

+ 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_2.2.3 +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 +

+ + +

+ 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; + +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 kernal.xml +

+ + + true + [other enabled adaptors] + +]]> + +

+ 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? +