CVS: jcontainer/loom/site/xdocs/guide administrator.xml,1.7,1.8 architecture.xml,1.5,1.6 deployers.xml,1.4,1.5 index.xml,1.1,1.2 punit.xml,1.3,1.4 roles.xml,1.3,1.4
Peter Donald <pdonald-yCVjj/[email protected]> Wed, 3 Dec 2003 04:45:22 -0600
| Newsgroups | gmane.comp.java.jcontainer.cvs |
|---|---|
| Message-ID | <[email protected]> |
Update of /cvsroot/jcontainer/jcontainer/loom/site/xdocs/guide
In directory hogshead.codehaus.org:/tmp/cvs-serv21491/site/xdocs/guide
Modified Files:
administrator.xml architecture.xml deployers.xml index.xml
punit.xml roles.xml
Log Message:
Styled codebase
Index: administrator.xml
===================================================================
RCS file: /cvsroot/jcontainer/jcontainer/loom/site/xdocs/guide/administrator.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -d -r1.7 -r1.8
--- administrator.xml 16 Oct 2003 09:23:58 -0000 1.7
+++ administrator.xml 3 Dec 2003 10:44:50 -0000 1.8
@@ -1,9 +1,9 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<document>
<properties>
- <title>Guide - for Administrators</title>
- <author email="[email protected]">David Weit</author>
- </properties>
+ <title>Guide - for Administrators</title>
+ <author email="[email protected]">David Weit</author>
+ </properties>
<body>
<section name="Introduction">
<p>
@@ -23,9 +23,9 @@
<p>
You can start Loom in the foreground with the following command:
-<source>
+ <source>
bin/run.[bat|sh]
-</source>
+ </source>
</p>
<p>
On Windows versions other than NT, you'll need to set
@@ -34,82 +34,87 @@
will cause a clean shutdown.
</p>
<p>
- In UNIX environments, you can also use the <code>loom.sh</code>
+ In UNIX environments, you can also use the
+ <code>loom.sh</code>
script to start, stop and restart Loom. It accepts the following
(mutually exclusive) arguments
</p>
-<source>
+ <source>
loom.sh [start|stop|run|restart|check]
-</source>
+ </source>
<p>
- The <code>run</code> arg is equivalent to using the <code>run.sh</code> script.
+ The
+ <code>run</code> arg is equivalent to using the
+ <code>run.sh</code> script.
</p>
</subsection>
<subsection name="Using the Java Service Wrapper">
- <p>
+ <p>
Another option for starting and stopping Loom is to build
it with support for the
- <a href="http://wrapper.tanukisoftware.org/">Java Service Wrapper</a>.
- </p>
- <p>
+ <a href="http://wrapper.tanukisoftware.org/">Java Service Wrapper</a>.
+ </p>
+ <p>
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.
- </p>
- <p>
+ </p>
+ <p>
Loom distribution comes with both Linux and Windows Wrappers.
To build Loom with a Wrapper for another Unix platform, simply change the
- <code>wrapper.nix</code> property in <code>loom/distribution/project.properties</code>
+ <code>wrapper.nix</code> property in
+ <code>loom/distribution/project.properties</code>
to the appropriate platform and rebuild.
Loom will cache each new distribution downloaded in the Maven local repository.
- </p>
- <p>
+ </p>
+ <p>
For usage instructions
- </p>
-<source>
+ </p>
+ <source>
cd bin/
wrapper
-</source>
- <p>
- The Wrapper configuration file is named <code>conf/wrapper.conf</code>.
- </p>
+ </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>
+ <p>
Loom is tightly integrated with Java Management Extensions (JMX).
TODO: say something else. Integrate this section with the other
- <a href="mx/index.html">JMX info</a>.
- </p>
+ <a href="mx/index.html">JMX info</a>.
+ </p>
</subsection>
<subsection name="How to Make Your Block an MBean">
- <p>
+ <p>
It's actually quite simple. Suppose you wanted to expose the
interface from the WebServer block
- <a href="bdg/making-loom-compatible-comps.html">described</a> in
+ <a href="bdg/making-loom-compatible-comps.html">described</a> in
the Block developer's guide. You only need to do two things.
- </p>
- <p>
+ </p>
+ <p>
First, create an MBean interface. It will look something like this:
- </p>
-<source>
+ </p>
+ <source>
package examplecomp.block;
public interface WebServerMBean {
void mountWar(String contextName, URL pathToWar);
void unMountWar(String contextName);
}
-</source>
- <p>
+ </source>
+ <p>
Notice that interface MBean is identical to interface WebServer.
In most cases, it should be.
- </p>
- <p>
+ </p>
+ <p>
Now just make WebServerBlock implement WebServerMBean
- </p>
-<source>
+ </p>
+ <source>
package examplecomp.block;
/**
@@ -123,66 +128,66 @@
// ...
}
-</source>
+ </source>
</subsection>
<subsection name="Using Http Adaptor">
- <p>
+ <p>
The MX4J Http Adaptor allows access to a running Loom server
with any web browser.
- </p>
- <p>
+ </p>
+ <p>
TODO: describe configuration methods when they settle down
- </p>
- <p>
+ </p>
+ <p>
Then just point your browser to
- <a href="http://localhost:8082/">http://localhost:8082/</a>.
+ <a href="http://localhost:8082/">http://localhost:8082/</a>.
You should see a list of JMX MBeans you can control.
- </p>
- <p>
+ </p>
+ <p>
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
- <code>Loom:application=webserver,block=webserver,topic=WebServerMBean</code>.
+ <code>Loom: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>
+ </p>
+ <p>
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,
- <code>Loom:component=Embeddor,topic=Embeddor</code> allows
+ <code>Loom:component=Embeddor,topic=Embeddor</code> 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.
- </p>
+ </p>
</subsection>
<subsection name="Using RMI Adaptor">
- <p>
+ <p>
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
- <a href="http://mx4j.sourceforge.net/docs/bk01ch03s16.html">
+ <a href="http://mx4j.sourceforge.net/docs/bk01ch03s16.html">
documentation</a>. Loom uses the JRMP RMI Adaptor.
- </p>
- <p>
+ </p>
+ <p>
Ensure that the MX4J RMI Adaptor is enabled in kernel.xml
- </p>
-<source>
-<component role="org.apache.avalon.phoenix.interfaces.SystemManager"
+ </p>
+ <source>
+ <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>
+ <enable-rmi-adaptor>true</enable-rmi-adaptor>
[other enabled adaptors]
-</component>
-</source>
- <p>
+ </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 Loom. Create the
following class:
- </p>
+ </p>
-<source>
+ <source>
import mx4j.connector.rmi.jrmp.JRMPConnector;
import mx4j.connector.RemoteMBeanServer;
import javax.management.ObjectName;
@@ -206,23 +211,23 @@
server.invoke(objName, "shutdown", new Object[0], new String[0]);
}
}
-</source>
- <p>
+ </source>
+ <p>
Compile and run -- presto! The server stops.
- </p>
+ </p>
</subsection>
</section>
<section name="Troubleshooting">
- <p>
- <strong>Loom stops immediatly after starting, with no error message</strong>
- </p>
- <p>
+ <p>
+ <strong>Loom stops immediatly after starting, with no error message</strong>
+ </p>
+ <p>
Make sure you have a .sar file in the app/ directory. If there isn't
a service running, Loom 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>
+ </p>
</section>
</body>
</document>
Index: architecture.xml
===================================================================
RCS file: /cvsroot/jcontainer/jcontainer/loom/site/xdocs/guide/architecture.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- architecture.xml 31 Jul 2003 20:29:40 -0000 1.5
+++ architecture.xml 3 Dec 2003 10:44:50 -0000 1.6
@@ -1,8 +1,8 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<document>
<properties>
- <title>Guide - Architectural overview</title>
- <author email="[email protected]">Leo Simons</author>
+ <title>Guide - Architectural overview</title>
+ <author email="[email protected]">Leo Simons</author>
</properties>
<body>
<section name="Introduction">
@@ -17,7 +17,7 @@
<p>
<strong>Loom layer diagram</strong>
</p>
- <img src="../images/loom-layers.png" alt="Loom Layers"/>
+ <img src="../images/loom-layers.png" alt="Loom Layers"/>
<p>
Shown above are three hosted server applications. A mail server that would implement
multiple listeners for incoming and outgoing services (POP3, SMTP, IMAP etc). Outlook,
@@ -42,7 +42,7 @@
<p>
<strong>Loom application in block view</strong>
</p>
- <img src="../images/loom-app-block.jpg" alt="Loom App Block"/>
+ <img src="../images/loom-app-block.jpg" alt="Loom App Block"/>
</subsection>
<subsection name="Packaging in terms of block jar files">
<p>
@@ -61,7 +61,7 @@
<p>
<strong>FtpServer, a real Loom application</strong>
</p>
- <img src="../images/loom-app-ftpserver.jpg" alt="Loom App FtpServer"/>
+ <img src="../images/loom-app-ftpserver.jpg" alt="Loom App FtpServer"/>
</subsection>
<p>
Notes - Loom does not limit the number of blocks that it allows in a sar file. We have taksdefs for Apache's Ant
Index: deployers.xml
===================================================================
RCS file: /cvsroot/jcontainer/jcontainer/loom/site/xdocs/guide/deployers.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- deployers.xml 31 Jul 2003 20:29:40 -0000 1.4
+++ deployers.xml 3 Dec 2003 10:44:50 -0000 1.5
@@ -1,24 +1,25 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<document>
- <properties>
- <title>Guide - for Deployers</title>
- <author email="jcontainer-interest-yCVjj/[email protected] ">Loom Documentation Team</author>
- </properties>
- <body>
- <section name="Introduction">
- <p>
+ <properties>
+ <title>Guide - for Deployers</title>
+ <author email="jcontainer-interest-yCVjj/[email protected] ">Loom Documentation Team</author>
+ </properties>
+ <body>
+ <section name="Introduction">
+ <p>
Currently deploying a server application under Loom is simply a matter
- of dropping the .sar file into the appropriate directory (<code>apps/</code>)
+ of dropping the .sar file into the appropriate directory (
+ <code>apps/</code>)
and restarting Loom. In the future there will be more advanced methods
of deploying and undeploying Server Applications without restarting Loom.
- </p>
- <subsection name="Target Audience">
- <p>
+ </p>
+ <subsection name="Target Audience">
+ <p>
This documentation describes the methods through which you can deploy
Server Applications under the Loom kernel. It will be expanded as
the system becomes more complete.
- </p>
- </subsection>
- </section>
- </body>
+ </p>
+ </subsection>
+ </section>
+ </body>
</document>
Index: index.xml
===================================================================
RCS file: /cvsroot/jcontainer/jcontainer/loom/site/xdocs/guide/index.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- index.xml 11 Oct 2003 19:34:16 -0000 1.1
+++ index.xml 3 Dec 2003 10:44:50 -0000 1.2
@@ -1,31 +1,31 @@
<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
- <properties>
- <title>Guide to Loom</title>
- </properties>
-
- <body>
- <section name="Introduction">
- <p>
+ <properties>
+ <title>Guide to Loom</title>
+ </properties>
+
+ <body>
+ <section name="Introduction">
+ <p>
This guide starts with an architectural overview of Loom. Then, we identify
the different roles that typically exist in daily use of Loom. For each of
these, we provide a basic guide. We finish with a complete example.
- </p>
- <subsection name="Target Audience">
- <p>
+ </p>
+ <subsection name="Target Audience">
+ <p>
This documentation is aimed towards people who:
- </p>
- <p>
- <ul>
- <li>wish to create applications that run within Loom</li>
- <li>wish to create components (blocks) for use within Loom</li>
- <li>wish to setup and administer Loom</li>
- <li>are interested in the design principles of Loom</li>
- <li>wish to develop code that will be incorporated into Loom</li>
- <li>wish to reuse Loom concepts in their own application</li>
- </ul>
- </p>
- </subsection>
- </section>
- </body>
+ </p>
+ <p>
+ <ul>
+ <li>wish to create applications that run within Loom</li>
+ <li>wish to create components (blocks) for use within Loom</li>
+ <li>wish to setup and administer Loom</li>
+ <li>are interested in the design principles of Loom</li>
+ <li>wish to develop code that will be incorporated into Loom</li>
+ <li>wish to reuse Loom concepts in their own application</li>
+ </ul>
+ </p>
+ </subsection>
+ </section>
+ </body>
</document>
Index: punit.xml
===================================================================
RCS file: /cvsroot/jcontainer/jcontainer/loom/site/xdocs/guide/punit.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- punit.xml 31 Jul 2003 20:29:40 -0000 1.3
+++ punit.xml 3 Dec 2003 10:44:50 -0000 1.4
@@ -1,29 +1,29 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<document>
- <properties>
- <title>Guide - PUnit</title>
- <author email="Paul_Hammant-/[email protected]">Paul Hammant</author>
- </properties>
- <body>
- <section name="Introduction">
- <p>
+ <properties>
+ <title>Guide - PUnit</title>
+ <author email="Paul_Hammant-/[email protected]">Paul Hammant</author>
+ </properties>
+ <body>
+ <section name="Introduction">
+ <p>
Loom has a component/lifecycle aware unit test framework called PUnit. It has no requirements on
external meta information. As such it could be used for unit testing for a wide range of Avalon-Framework
enabled components. Having said that, usage requires some knowledge of multi component applications and
the order of component lifecycling. PUnit builds on JUnit. You should have testing experience of
- <a href="http://www.junit.org">JUnit</a> before using PUnit.
- </p>
- </section>
- <section name="Example Usage">
- <p>
+ <a href="http://www.junit.org">JUnit</a> before using PUnit.
+ </p>
+ </section>
+ <section name="Example Usage">
+ <p>
There is a unit test framework for Loom called PUnit. It is used for pseudo in-container testing of Loom
components. The main class PUnitTestCase should be extended by the developer, some manual setup done, then
normal assertXXX() testing.
- </p>
- <p>
- <strong>Test component (from Loom's own PUnit TestCase)</strong>
- </p>
- <source>
+ </p>
+ <p>
+ <strong>Test component (from Loom's own PUnit TestCase)</strong>
+ </p>
+ <source>
public class TestBlock
implements Serviceable, Configurable, Initializable, Contextualizable, LogEnabled
{
@@ -65,11 +65,11 @@
}
- </source>
- <p>
- <strong>Example TestCase (from Loom's own PUnit TestCase)</strong>
- </p>
- <source>
+ </source>
+ <p>
+ <strong>Example TestCase (from Loom's own PUnit TestCase)</strong>
+ </p>
+ <source>
public class PUnitTestCaseTestCase extends PUnitTestCase
{
@@ -103,8 +103,8 @@
}
}
- </source>
- <p>
+ </source>
+ <p>
What is shown here is a single block being manually instantiated, and registered with PUnit
(addBlock). Configuration rather than being from a file, is handed in from this source
via DefaultConfigurationBuilder (see its other methods for more flexibility). The method
@@ -112,8 +112,8 @@
asserts have been invoked, the shutdown() is appropriate to tidy up in time for the next
test. If you have multiple tests to do, it might be best to do all that is setup and
tearDown methods.
- </p>
- <p>
+ </p>
+ <p>
It is important for developers to know the order of dependancy of their components, and in
fact, the dependency needs of all components used in the test. This is normally the role
of the assembler rather than the developer, but there is no way that unit testing can
@@ -122,59 +122,59 @@
Loom itself spends some effort determining which components are not needed by anything
and cycles them first during startup. The last to be cycled are those that depend on the
others.
- </p>
- </section>
- <section name="To Use">
- <p>
+ </p>
+ </section>
+ <section name="To Use">
+ <p>
When setting up a classpath, excalibur's containerkit and il8n jars are dependencies for Punit...
- </p>
- <source>
- <path id="test.class.path">
- <pathelement location="build/testclasses"/>
- <path refid="compile.classpath"/>
- <pathelement location="lib/phoenix-punit.jar"/>
- <pathelement location="lib/excalibur-containerkit-1.0.jar"/>
- <pathelement location="lib/excalibur-i18n-1.0.jar"/>
- </path>
- </source>
- <p>
+ </p>
+ <source>
+ <path id="test.class.path">
+ <pathelement location="build/testclasses"/>
+ <path refid="compile.classpath"/>
+ <pathelement location="lib/phoenix-punit.jar"/>
+ <pathelement location="lib/excalibur-containerkit-1.0.jar"/>
+ <pathelement location="lib/excalibur-i18n-1.0.jar"/>
+ </path>
+ </source>
+ <p>
As with most testing frameworks, compilation of test classes is required before tests can be invoked...
- </p>
- <source>
- <target name="test" depends="compile" description="compiles and runs unit tests">
+ </p>
+ <source>
+ <target name="test" depends="compile" description="compiles and runs unit tests">
- <mkdir dir="build/testclasses"/>
+ <mkdir dir="build/testclasses"/>
- <javac
+ <javac
destdir="build/testclasses"
debug="${build.debug}"
optimize="${build.optimize}"
deprecation="${build.deprecation}">
- <classpath refid="test.class.path" />
- <src path="src/test" />
- </javac>
+ <classpath refid="test.class.path" />
+ <src path="src/test" />
+ </javac>
- <mkdir dir="build/tests"/>
+ <mkdir dir="build/tests"/>
- <junit fork="true"
+ <junit fork="true"
haltonfailure="${junit.failonerror}"
printsummary="yes"
dir="build/tests">
- <classpath refid="test.class.path"/>
+ <classpath refid="test.class.path"/>
- <formatter type="plain"/>
+ <formatter type="plain"/>
- <batchtest todir="build/tests">
- <fileset dir="build/testclasses">
- <include name="**/*TestCase.class"/>
- <exclude name="**/Abstract*"/>
- </fileset>
- </batchtest>
- </junit>
+ <batchtest todir="build/tests">
+ <fileset dir="build/testclasses">
+ <include name="**/*TestCase.class"/>
+ <exclude name="**/Abstract*"/>
+ </fileset>
+ </batchtest>
+ </junit>
- </target>
- </source>
- </section>
+ </target>
+ </source>
+ </section>
- </body>
+ </body>
</document>
Index: roles.xml
===================================================================
RCS file: /cvsroot/jcontainer/jcontainer/loom/site/xdocs/guide/roles.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- roles.xml 31 Jul 2003 20:29:40 -0000 1.3
+++ roles.xml 3 Dec 2003 10:44:50 -0000 1.4
@@ -1,8 +1,8 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<document>
<properties>
- <title>Development Roles</title>
- <author email="[email protected]">Leo Simons</author>
+ <title>Development Roles</title>
+ <author email="[email protected]">Leo Simons</author>
</properties>
<body>
<section name="Introduction">