You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@avalon.apache.org by do...@apache.org on 2002/09/09 14:28:30 UTC
cvs commit: jakarta-avalon-phoenix/src/xdocs guide-administrator.xml
donaldp 2002/09/09 05:28:30
Modified: src/xdocs Tag: RELEASE_402-branch guide-administrator.xml
Log:
Started writing a proper administrators guide with all that entails. At the moment is begines discussing install, start and stop of Phoenix.
Submitted by: "David W." <da...@optonline.net>
Revision Changes Path
No revision
No revision
1.4.2.1 +227 -6 jakarta-avalon-phoenix/src/xdocs/guide-administrator.xml
Index: guide-administrator.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-phoenix/src/xdocs/guide-administrator.xml,v
retrieving revision 1.4
retrieving revision 1.4.2.1
diff -u -r1.4 -r1.4.2.1
--- guide-administrator.xml 16 Jun 2002 10:21:45 -0000 1.4
+++ guide-administrator.xml 9 Sep 2002 12:28:30 -0000 1.4.2.1
@@ -19,13 +19,234 @@
Phoenix kernel from the point of view of the administrator.
</p>
</subsection>
- <subsection name="Guide non-existent, but features are there">
- <p>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.
- </p>
+ </section>
+ <section name="Starting and Stopping">
+ <subsection name="Using Scripts">
+ <p>
+ You can start Phoenix with the following command:
+
+ <source>
+
+ > bin/run.[bat|sh]
+
+ </source>
+
+ </p>
+ <p>
+ In Windows versions other than NT, you'll need to set
+ the PHOENIX_HOME environment variable first.
+ </p>
+ <p>
+ In UNIX environments, you can use the <code>phoenix.sh</code>
+ script to stop Phoenix.
+ </p>
+
+ <source>
+ > phoenix.sh stop
+ </source>
+
+ <p>
+ phoenix.sh accepts these commands:
+ start, stop, run, restart, check.
+ </p>
+ <p>
+ In Windows, typing CONTROL-C will cause a clean shutdown.
+ </p>
</subsection>
+ <subsection name="Using the Java Service Wrapper">
+ <p>
+ Another option for starting and stopping Phoenix is to build
+ it with support for the
+ <a href="http://wrapper.sourceforge.net/">Java Service Wrapper</a>.
+ </p>
+ <p>
+ 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.
+ </p>
+ <p>
+ 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 <code>ant.properties</code> so that it looks
+ similar to this:
+ </p>
+
+<source>
+# ${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
+</source>
+
+ <p>
+ Then just build as usual.
+ </p>
+ <p>
+ For usage instructions, move to the <code>bin</code> directory and type
+ </p>
+
+ <source>
+
+ > wrapper
+
+ </source>
+
+ <p>
+ The Wrapper configuration file is named <code>conf/wrapper.conf</code>.
+ </p>
+ </subsection>
+ </section>
+ <section name="Using JMX">
+ <subsection name="JMX Overview">
+ <p>
+ Phoenix is tightly integrated with Java Management Extensions (JMX).
+ TODO: say something else
+ </p>
+ </subsection>
+ <subsection name="How to Make Your Block an MBean">
+ <p>
+ It's actually quite simple. Suppose you wanted to expose the
+ interface from the WebServer block
+ <a href="bdg/making-phoenix-compatible-comps.html">described</a> in
+ the Block developer's guide. You only need to do two things.
+ </p>
+ <p>
+ First, create an MBean interface. It will look something like this:
+ </p>
+<source>
+package examplecomp.block;
+
+public interface WebServerMBean {
+ void mountWar(String contextName, URL pathToWar);
+ void unMountWar(String contextName);
+}
+</source>
+ <p>
+ Notice that interface MBean is identical to interface WebServer.
+ In most cases, it should be.
+ </p>
+ <p>
+ Now just make WebServerBlock implement WebServerMBean
+ </p>
+<source>
+package examplecomp.block;
+
+public class WebServerBlock
+ extends AbstractLoggable
+ implements WebServer, WebServerMBean, Startable, Configurable, Initializable {
+
+ // ...
+
+}
+</source>
+ </subsection>
+ <subsection name="Using Http Adaptor">
+ <p>
+ The MX4J Http Adaptor allows access to a running Phoenix server
+ with any web browser.
+ </p>
+ <p>
+ TODO: describe configuration methods when they settle down
+ </p>
+ <p>
+ Then just point your browser to
+ <a href="http://localhost:8082/">http://localhost:8082/</a>.
+ You should see a list of JMX MBeans you can control.
+ </p>
+ <p>
+ 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
+ <code>Phoenix:application=webserver,block=webserver,topic=WebServerMBean</code>.
+ If you click on the name, you'll find a form that allows you
+ to mount and unmount .war files through the web!
+ </p>
+ <p>
+ 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,
+ <code>Phoenix:component=Embeddor,topic=Embeddor</code> 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.
+ </p>
+ </subsection>
+ <subsection name="Using RMI Adaptor">
+ <p>
+ 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
+ <a href="http://mx4j.sourceforge.net/docs/bk01ch03s13.html#d0e1012">
+ documentation</a>. Phoenix uses the JRMP RMI Adaptor.
+ </p>
+ <p>
+ Ensure that the MX4J RMI Adaptor is enabled in kernal.xml
+ </p>
+<source>
+<![CDATA[
+ <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>
+]]>
+</source>
+ <p>
+ 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:
+ </p>
+
+<source>
+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]);
+ }
+}
+</source>
+ <p>
+ Compile and run -- presto! The server stops.
+ </p>
+ </subsection>
+ </section>
+ <section name="Troubleshooting">
+ <p>
+ <b>Phoenix stops immediatly after starting, with no error message</b>
+ </p>
+ <p>
+ 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?
+ </p>
</section>
</body>
</document>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>