12 removed files
LOOM-67 - move docs migrated to JIRA
loom/site/xdocs/guide/assemblers
diff -N creating-a-server-application.xml
--- creating-a-server-application.xml 1 Apr 2004 04:46:36 -0000 1.5
+++ /dev/null 1 Jan 1970 00:00:00 -0000
<at> <at> -1,71 +0,0 <at> <at>
-<?xml version="1.0" encoding="iso-8859-1"?>
-<document>
- <properties>
- <title>Guide - Creating a Server Application</title>
- </properties>
- <body>
- <section name="Introduction">
- <p>
- This document will describe the process for assembling your first Server
- Application. There is a number of steps in creating a Server Application.
- These are;
- </p>
- <ol>
- <li>Select the blocks you wish to assemble.</li>
- <li>Write the config.xml file.</li>
- <li>Write the assembly.xml file.</li>
- <li>Write the environment.xml file.</li>
- <li>Package the component and related resources into a sar file.</li>
- </ol>
- </section>
- <section name="Select the Blocks to Assemble">
- <p>
- As a assembler it is your responsibility to select the particular Blocks
- required to build your application. You may aquire the Blocks from a number
- of sources depending on your resources. You may use the core Blocks supplied
- with Loom, contract someone to build the component or download the Block
- from an online repository.
- </p>
- </section>
- <section name="Write the config.xml file">
- <p>
- Configuration data for blocks is stored in the config.xml file.
- For more detail on the format of config.xml see the
- <a href="../../reference/config-xml-specification.html">specification</a>.
- </p>
- </section>
- <section name="Write the assembly.xml file">
- <p>
- The next stage is to write the assembly.xml file. The assembly.xml specifies
- the instances of Blocks that are part of the Server Application. Each
- Block has a name. Each block may also have dependencies that need to be
- satisfied and this can be done via the 'provide' sub-elements. The
- provide element maps block instances from the Server Application namespace
- to the Block role namespace specified in BlockInfo files. For more detail
- on the format of assembly.xml see the
- <a href="../../reference/assembly-xml-specification.html">
- specification</a>.
- </p>
- </section>
- <section name="Write the environment.xml file">
- <p>
- The next stage is to write the environment.xml file. The environment.xml is used to
- configure the code-based security policy, log management and thread pooling.
- For more detail on the format of environment.xml see the
- <a href="../../reference/environment-xml-specification.html">specification</a>.
- </p>
- </section>
- <section name="Create the sar file">
- <p>
- The sar file format is the standard distribution format of Loom Server
- Applications. It is a standard Jar file with a specific directory layout.
- The config.xml, environment.xml and assembly.xml file must be stored in
- <code>SAR-INF/</code> directory of the archive. All jar files, including
- both those that contain blocks and those that contain support classes
- should be stored in the
- <code>SAR-INF/lib/</code> directory.
- </p>
- </section>
-
- </body>
-</document>
loom/site/xdocs/guide/assemblers
diff -N index.xml
--- index.xml 1 Apr 2004 04:46:36 -0000 1.6
+++ /dev/null 1 Jan 1970 00:00:00 -0000
<at> <at> -1,27 +0,0 <at> <at>
-<?xml version="1.0" encoding="iso-8859-1"?>
-<document>
- <properties>
- <title>Guide - for Server Assemblers</title>
- </properties>
- <body>
- <section name="Who Should Read This Guide?">
- <p>
- The Server Assemblers Guide is written for assemblers who want to assemble a
- Server Application for Loom. It is assumed that you are familiar with
- the basic concepts of the Loom framework.
- </p>
- <p>
- This book concentrates on assembly, and as such requires no knowledge of
- java programming. It does however assume you are familiar with server
- fundamentals, basic security measures, and performance tuning.
- </p>
- </section>
- <section name="Organization">
- <p>
- The information is organized into sections detailing a specifc aspect of
- assembling Server Applications.
- </p>
- </section>
-
- </body>
-</document>
loom/site/xdocs/guide/assemblers
diff -N what-is-a-server-application.xml
--- what-is-a-server-application.xml 1 Apr 2004 04:46:36 -0000 1.5
+++ /dev/null 1 Jan 1970 00:00:00 -0000
<at> <at> -1,26 +0,0 <at> <at>
-<?xml version="1.0" encoding="iso-8859-1"?>
-<document>
- <properties>
- <title>Guide - What is a Server Application?</title>
- <author email="bloritsch-1oDqGaOF3Lkdnm+yROfE0A@public.gmane.org">Berin Loritsch</author>
- </properties>
- <body>
- <section name="Introduction">
- <p>
- In Loom, a Server Application is a set of Blocks that act in concert
- to provide a unified user service. Example Server Applications include a Mail
- Server, File Server, Web Server etc. The Server Application is a high level
- component that contains a set of Block components.
- </p>
- <p>
- A Server Application requires a number of components other than Blocks to
- be complete. A Server Application requires configuration files to define
- Server Application wide settings (threading, security, logging), to define
- how blocks are wired together, and to define configuration data for the
- Block instances. A Block can also require other resources that are
- application specific.
- </p>
- </section>
-
- </body>
-</document>
loom/site/xdocs/guide/bdg
diff -N creating-a-block.xml
--- creating-a-block.xml 17 Aug 2004 07:37:56 -0000 1.11
+++ /dev/null 1 Jan 1970 00:00:00 -0000
<at> <at> -1,75 +0,0 <at> <at>
-<?xml version="1.0" encoding="iso-8859-1"?>
-<document>
- <properties>
- <title>Guide - Creating a Component</title>
- </properties>
- <body>
- <section name="Introduction">
- <p>
- This document will describe the process for creating your first
- component. The following steps are required before your
- component is ready for assembling.
- </p>
- <ol>
- <li>Write the Component.</li>
- <li>Associate MetaData with the Component.</li>
- <li>Package the component and related resources into a jar file.</li>
- </ol>
- </section>
- <section name="Writing the Component">
- <p>
- Writing the component is the main task you will be called to
- do. It follows all the rules of writing a standard Avalon
- component. If a component implements the Contextualizable interface
- it will be passed an instance of
- <code>org.apache.avalon.phoenix.BlockContext</code> which is
- an extended version of
- <code>org.apache.avalon.Context</code>.
- Other than this minor change the container supports all the
- Avalon lifecycle methods.
- </p>
- </section>
- <section name="Associate MetaData with the Component">
- <p>
- Loom uses the same mechanism as is described in the
- <a href="http://dna.codehaus.org/metadata">DNA MetaData
- documentation</a>. The developer should be aware that the DNA
- documentation describes the metadata associated with DNA
- components. The only difference that must be taken into account
- for Avalon components is the name of the methods that the
- attributes are associated with. For example the dna.dependency
- attribute must be on associated with either Avalons
- Composable.compose(ComponentManager) or
- Serviceable.service(ServiceManager) methods.
- </p>
- <p>
- The only difference is that Loom has an enhanced Ant task to
- generate the MetaData. This enhanced has backward compatible
- support for Phoenix metadata annotations and should be used
- if classes contain historic annotations. See below for a
- sample on how to use the task to generate metadata.
- </p>
- <source>
-<taskdef
- name="generatemeta"
- classname="org.codehaus.loom.info.GenerateLoomDescriptorsTask">
- <classpath refid="maven-sar.class.path" />
- <classpath refid="dna-tools.class.path" />
- <classpath refid="metaclass.class.path" />
- <classpath refid="qdox.class.path" />
-</taskdef>
-
-<generatemeta dest="target/classes">
- <fileset dir="src/java">
- <include name="**/*.java"/>
- </fileset>
-</generatemeta></source>
- </section>
- <section name="Create the jar package">
- <p>
- The final step is packaging up the implementation files,
- MetaClass descriptors and other resources into a jar file.
- </p>
- </section>
- </body>
-</document>
loom/site/xdocs/guide/bdg
diff -N index.xml
--- index.xml 17 Aug 2004 07:18:58 -0000 1.7
+++ /dev/null 1 Jan 1970 00:00:00 -0000
<at> <at> -1,45 +0,0 <at> <at>
-<?xml version="1.0" encoding="iso-8859-1"?>
-<document>
- <properties>
- <title>Guide - for Block Developers</title>
- <author email="bloritsch-1oDqGaOF3Lkdnm+yROfE0A@public.gmane.org">Berin Loritsch</author>
- <abstract>
- The Block Developer's Guide (BDG) is written to bring an overview
- of how to create and deploy a Block. The Block is the component that
- is hosted in the Loom micro-kernel.
- </abstract>
- </properties>
- <body>
- <section name="Who Should Read This Guide?">
- <p>
- The BDG is written for developers who want to create
- blocks for Loom. It is assumed that you are familiar with
- Java, XML, Avalon patterns and server side security issues.
- This book provides an overview of the underlying technology,
- Java classes and interfaces, component model, and
- behavior of server Blocks within Loom.
- </p>
- <p>
- While this guide concentrates on server fundamentals, it
- should not be construed as a "dummy's" guide. Server side
- programming is complex because of the performance and security
- issues you must balance.
- </p>
- <p>
- You should be well versed in the Java language and have some
- practical experience developing server solutions. If you need
- a stronger background on server side programming, I suggest
- finding a good book on the subject.
- </p>
- </section>
- <section name="Organization">
- <p>
- Here is how the information is presented. The first few
- chapters are foundational material, and describe the basic
- concepts you can use in your own blocks. The later chapters
- specify in detail the formal requirements of Block
- implementations.
- </p>
- </section>
- </body>
-</document>
loom/site/xdocs/guide/bdg
diff -N making-loom-compatible-comps.xml
--- making-loom-compatible-comps.xml 17 Aug 2004 08:00:46 -0000 1.6
+++ /dev/null 1 Jan 1970 00:00:00 -0000
<at> <at> -1,203 +0,0 <at> <at>
-<?xml version="1.0" encoding="iso-8859-1"?>
-<document>
- <properties>
- <title>Guide - Making components that are Loom compatible</title>
- <author email="hammant-1oDqGaOF3Lkdnm+yROfE0A@public.gmane.org">Paul Hammant</author>
- </properties>
- <body>
- <section name="Introduction">
- <p>
- Quite often reusable components are made elsewhere. Codehaus and also
- Apache have a number of places where this activity is going on. While we
- get it right most of the time, some components developed elsewhere are harder
- to use in Loom.
- </p>
- </section>
- <section name="Things to remember">
- <p>
- There are a number of common sense things to remember when making or
- adapting a Java component to be reusable in Loom as block.
- </p>
- <subsection name="Beanification">
- <ul>
- <li>Have a public empty constructor for your main class</li>
- <li>Have setters for its configuration.</li>
- <li>Do not assume that the File is where dependancies are - people may reuse this in jars, applets etc.</li>
- <li>Divorce your main method (if appl) from your main class - Loom does not call main methods.</li>
- <li>Consider that the setup and initialization of the bean does not happen in the
- constructor - as a convenience to the user, have an initialize() method</li>
- <li>If the comp has start/stop functinality consider having start() and stop() methods.</li>
- <li>Try to avoid Singleton concepts. There could be multiple blocks in one sar using differnt (by design) instances of your bean</li>
- </ul>
- </subsection>
- <subsection name="Inversion of Control Pattern">
- <p>The IoC pattern is described
- <a href="http://avalon.apache.org/framework/cop/index.html">
- here</a>. This means for Loom avoiding static concepts including loggers.
- </p>
- </subsection>
- <subsection name="Separation of interface and implementation">
- <p>
- The separation of interface/implementation pattern is described
- <a href="http://avalon.apache.org/framework/cop/index.html">here</a>.
- For Loom this means we can (if done completely) mount the implementation jar in
- place where hosted client components (beans, servlets etc) can use the API,
- but not see the implementation. We can also reimplement or wrap bits of the
- implementation. For example we could write a pluggable implementation that could,
- for a certain API journal some methods, but still delegate to the real implementation.
- Which pluggable implementation is used by Loom when it boots is determined in
- assembly.xml of course.
- </p>
- </subsection>
- <subsection name="Opening up the API">
- <p>
- Given that you have divided into interface and implementation, there are probably plenty of methods you
- can put in the interface you never though might be used. For example if you are making JDBC
- compliant relational database, and it is a bean, you could easily think that the only use would be
- clients via JDBC over sockets. Well, given that Loom can now mount the RDBMS block, it might want
- to be reused by other blocks that other people have developed inside the the same SAR file. In that case
- have beanlike methods of ...
- </p>
- <ol>
- <li>Database createDatabase( String name )</li>
- <li>Database cloneDatabase( String name )</li>
- </ol>
- <p>
- .. might be useful. Just because you can only see a ServerSocket interface does not mean that others do.
- </p>
- </subsection>
- </section>
- <section name="Example compatible component">
- <p>
- Below are an interface and implementation that are suitably separated, are beanlike and is in accordance
- with the IoC pattern...</p>
- <source>
-package examplecomp;
-public interface WebServer {
- void mountWar(String contextName, URL pathToWar);
- void unMountWar(String contextName);
-}
-
-package examplecomp.server;
-public class MyWebServer implements WebServer {
-
- public MyWebServer() {
- // whatever.
- }
- public void setPort(int port) {
- // this is one configuration item.
- }
- public void initialize() {
- // whatever.
- }
- public void start() {
- // whatever.
- }
- public void stop() {
- // whatever.
- }
- public void mountWar(String contextName, URL pathToWar) {
- // whatever.
- }
- public void unMountWar(String contextName) {
- // whatever.
- }
-}</source>
- <p>For standalone mode, it might be launched like so:</p>
- <source>
-package examplecomp.main;
-public class WebServerMain {
- public static void main(String[] args) throws Exception {
- MyWebServer ws = new WebServer();
- ws.setPort(Integer.parseInt(args[0]));
- ws.initialize();
- ws.start();
- ws.mountWar(args[1], new File(args[2]).toURL());
- }
-}</source>
- <p>When we are trying to run this in phoenix we might have this wrapper:</p>
- <source>
-package examplecomp.block;
-public class WebServerBlock
- extends AbstractLoggable
- implements WebServer, Startable, Configurable, Initializable {
-
- private int mPort;
- private WebServer mWebServer;
-
- public WebServerBlock() {
- mWebServer = new MyWebServer();
- }
-
- public void configure(final Configuration configuration)
- throws ConfigurationException {
- mPort = configuration.getChild("port").getValueAsInteger( 9001 );
- }
-
- public void initialize() throws Exception {
- mWebServer.setPort(mPort);
- mWebServer.initialize();
- }
-
- public final void start() throws Exception {
- mWebServer.start();
- }
-
- public void stop() throws Exception {
- mWebServer.stop();
- }
-
- public void mountWar(String contextName, String pathToWar) {
- mWebServer.mountWar(contextName, pathToWar);
- }
-
- public void unMountWar(String contextName) {
- mWebServer.unMountWar(contextName);
- }
-}</source>
- <p>This basically shows the implementation wrapped and taking its configuration from the config.xml
- that phoenix prefers from configuration. If the developer wanted they could ignore
- that place of configuration and use their own config files. If the WebServer block were
- being reused by another Loom block (say an EJB server), it might be like so:</p>
- <source>
-package somebeanserver;
-public class EJBBlock
- extends AbstractLoggable
- implements Composable {
-
- private WebServer mWebServer;
-
- public void compose(final ComponentManager compMgr)
- throws ComponentException {
- mWebServer = compMgr.lookup("WebServer");
- }
-
- public void mountEar(String contextName, String pathToEar) {
- String[] warContextNames = getWarContexts(pathToEar);
- URL[] wars = getWarFiles(pathToEar);
- for (int i = 0; i < wars.length; i++) {
- mWebServer.mountWar(warContextNames[i], wars[i]);
- }
- }
-
- public void unMountEar(String contextName) {
- // whatever
- }
-}</source>
- </section>
- <section name="Misconceptions">
- <p>
- The following are worth stating:
- </p>
- <ul>
- <li>You do not have to implement any Avalon interfaces to be
- reusable (wrap strategy) inside Loom.</li>
- <li>Being Loom compatible is just as useful for whole servers as it is for small components.</li>
- <li>Being Loom compatible can be for tools that are intended for client-side as well as server use.</li>
- </ul>
- <p>
- </p>
- </section>
-
- </body>
-</document>
loom/site/xdocs/guide/bdg
diff -N what-is-a-block.xml
--- what-is-a-block.xml 17 Aug 2004 07:21:00 -0000 1.7
+++ /dev/null 1 Jan 1970 00:00:00 -0000
<at> <at> -1,33 +0,0 <at> <at>
-<?xml version="1.0" encoding="iso-8859-1"?>
-<document>
- <properties>
- <title>Guide - What is a Block?</title>
- </properties>
- <body>
- <section name="Introduction">
- <p>In Loom, there are three component layers:</p>
- <ul>
- <li>Blocks</li>
- <li>Components</li>
- <li>Classes</li>
- </ul>
- <p>
- They represent ever narrowing views of a component based architecture.
- The best analogy is that of hardware. In the PC world, a Block would
- be like a PCI card, a Motherboard, a Case, or a Hard Drive. A Component
- would be like the chips on the cards. And classes would be like the
- individual transistors on the chip. Granted, the actual economies
- of scale in this analogy don't hold to software (a component will
- not have millions of classes).
- </p>
- </section>
- <section name="What is a Block?">
- <p>
- A Block is a Component on a larger scale. It is usually the
- implementation of a Service. Examples of Blocks are
- "Persistent Object Store", "Connection Pools", "XML Database",
- "Authenticator" and so on.
- </p>
- </section>
- </body>
-</document>
loom/site/xdocs/guide/bdg
diff -N what-is-an-application-listener.xml
--- what-is-an-application-listener.xml 3 Dec 2003 10:44:51 -0000 1.8
+++ /dev/null 1 Jan 1970 00:00:00 -0000
<at> <at> -1,41 +0,0 <at> <at>
-<?xml version="1.0" encoding="iso-8859-1"?>
-<document>
- <properties>
- <title>Guide - What is an Application Listener?</title>
- <author email="Paul_Hammant-/E1597aS9LQAvxtiuMwx3w@public.gmane.org">Paul Hammant</author>
- </properties>
- <body>
- <section name="Introduction">
- <p>
- An ApplicationListener is a component that is created before
- any other components in the application. It receives
- notifications at the start of Block creation, after each
- Block is created, and when all blocks are created and the
- application is running.
- </p>
- </section>
- <section name="Events notified">
- <p>
- ApplicationListener components are created before any Blocks
- are created in an Application. They receive notifications
- before and after the Application is started and stopped.
- </p>
- </section>
- <section name="How to make an application listener">
- <p>
- Like normal blocks, an application listener can be
- <code>LogEnabled</code> and take configuration via
- <code>Configurable</code>. The special feature
- is that it must implement
- <code>ApplicationListener</code>
- and implement the eight methods that are a consequence of
- that. The following section in assembly.xml causes
- instantiation of the application listener:
- </p>
- <source>
- <listener class="pkg.MyApplicationListener" name="a-suitable-name" />
- </source>
- </section>
-
- </body>
-</document>
loom/site/xdocs/guide/mx
diff -N doclet-tags.xml
--- doclet-tags.xml 19 Apr 2004 21:36:43 -0000 1.7
+++ /dev/null 1 Jan 1970 00:00:00 -0000
<at> <at> -1,299 +0,0 <at> <at>
-<?xml version="1.0" encoding="iso-8859-1"?>
-<document>
- <properties>
- <title>Management Guide - XDoclet Tagging</title>
- <author email="huw-1oDqGaOF3Lkdnm+yROfE0A@public.gmane.org">Huw Roberts</author>
- </properties>
- <body>
- <section name="Introduction">
- <p>
- Doclet tags inserted into source code automatically generate the
- descriptor. There are a number of advantages to doing it this way:
- </p>
- <ul>
- <li>
- its a lot faster than writing MXINFO files by hand
- </li>
- <li>
- its harder to make mistakes, since much of the data required
- for the descriptor is parsed out of the source code
- </li>
- <li>
- useful defaults can be used by reading the standard javadoc.
- </li>
- </ul>
- <p>
- Any class or interface can be used to produce MXINFO files. How they get used is up to
- container and its Management subsystem.
- </p>
- </section>
- <section name="The Tags">
- <p>
- The following tags are defined:
- </p>
- <subsection name="phoenix:mx-topic">
- <table>
- <tr>
- <td>Scope</td>
- <td>
- Applies to classes and interfaces.
- </td>
- </tr>
- <tr>
- <td>Purpose</td>
- <td>
- Marks the class or interface as eligible for management.
- </td>
- </tr>
- <tr>
- <td>Parameters</td>
- <td>
- It takes a single attribute, called name, that will be used
- to uniquely define the Topic for each Target that includes it.
- This name may be presented to the user in the management agent.
- </td>
- </tr>
- <tr>
- <td>Notes</td>
- <td>
-
- </td>
- </tr>
- </table>
- <p>
- Example:
- </p>
- <source>
- /**
- * This is the interface via which you can manager
- * the root container of Applications.
- *
- * <at> phoenix:mx-topic name="Kernel"
- *
- * <at> author
- Peter Donald
- */
- </source>
- </subsection>
- <subsection name="phoenix:mx-attribute">
- <table>
- <tr>
- <td>Scope</td>
- <td>
- Applies to getter and setter methods.
- </td>
- </tr>
- <tr>
- <td>Purpose</td>
- <td>
- Marks the method as being a getter or setter and as eligible for
- management. If the class defines a getter and setter, then just
- getter should be marked up.
- </td>
- </tr>
- <tr>
- <td>Parameters</td>
- <td>
- None
- </td>
- </tr>
- <tr>
- <td>Notes</td>
- <td>
- Often used in conjuntion with the mx-isWriteable tag
- </td>
- </tr>
- </table>
- <p>
- Example:
- </p>
- <source>
- /**
- * Gets the list of applications running in the container
- *
- * <at> phoenix:mx-attribute
- *
- * <at> return applicationNames The array of application names
- */
- String[] getApplicationNames();
- </source>
- </subsection>
- <subsection name="phoenix:mx-operation">
- <table>
- <tr>
- <td>Scope</td>
- <td>
- Applies to methods that are not getters or setters.
- </td>
- </tr>
- <tr>
- <td>Purpose</td>
- <td>
- Marks the method as elible to be a management operation.
- </td>
- </tr>
- <tr>
- <td>Parameters</td>
- <td>
- None
- </td>
- </tr>
- <tr>
- <td>Notes</td>
- <td>
- The standard javadoc is used to generate descriptions for any parameters to the
- method.
- </td>
- </tr>
- </table>
- <p>
- Example:
- </p>
- <source>
- /**
- * Removes the application from the container
- *
- * <at> phoenix:mx-operation
- *
- * <at> param name the name of application to remove
- */
- void removeApplication( String name )
- </source>
- </subsection>
- <subsection name="phoenix:mx-description">
- <table>
- <tr>
- <td>Scope</td>
- <td>
- Applies to manageable attributes and operations (i.e. to methods that also
- have the mx-operation or mx-attribute tag).
- </td>
- </tr>
- <tr>
- <td>Purpose</td>
- <td>
- The text following the tag is a description of the method suitable for presentation
- in the management agent.
- </td>
- </tr>
- <tr>
- <td>Parameters</td>
- <td>
- None
- </td>
- </tr>
- <tr>
- <td>Notes</td>
- <td>
- Optional. If ommitted the javadoc definition is used.
- </td>
- </tr>
- </table>
- <p>
- Example:
- </p>
- <source>
- /**
- * Retrieve a string identifying version of server.
- * Usually looks like "vX.Y.Z".
- *
- * <at> phoenix:mx-attribute
- * <at> phoenix:mx-description Retrieve a string identifying version of server.
- *
- * <at> return version string of server.
- */
- String getVersion();
- </source>
- </subsection>
- <subsection name="phoenix:mx-proxy">
- <table>
- <tr>
- <td>Scope</td>
- <td>
- Applies to classes.
- </td>
- </tr>
- <tr>
- <td>Purpose</td>
- <td>
- The proxy tag is used to indicate that a proxy class should be used
- to manage some aspect(s) of this object. At runtime, the management
- system will instantiate an instance of the proxy class passing in
- a reference to the managed object in the constructor. Management
- calls are then made on the proxy instead of the managed object.
- </td>
- </tr>
- <tr>
- <td>Parameters</td>
- <td>
- Takes a single attribute, "name" that must be the full class name of a class to be used
- as proxy for the management of this class.
- </td>
- </tr>
- <tr>
- <td>Notes</td>
- <td>
- At runtime it is expected the manager will instantiate the proxy class and use
- it in place of the Target object.
- </td>
- </tr>
- </table>
- <p>
- Example:
- </p>
- <source>
-
- /**
- * Ftp server starting point. Avalon framework will load this
- * from the jar file. This is also the starting point of remote
- * admin.
- *
- * <at> phoenix:block
- * <at> phoenix:service name="org.apache.avalon.ftpserver.interfaces.FtpServerInterface"
- *
- * <at> phoenix:mx-proxy class="org.apache.avalon.ftpserver.FtpServerMxProxy"
- *
- * <at> author Rana Bhattacharyya <rana_b-/E1597aS9LQAvxtiuMwx3w@public.gmane.org>
- * <at> author Paul Hammant <Paul_Hammant-/E1597aS9LQAvxtiuMwx3w@public.gmane.org>
- * <at> version 1.0
- */
-
- </source>
- </subsection>
- </section>
- <section name="Build Instructions">
- <p>
- To have mxinfo files generated as part as your ant build
- script, include a task like that this:
- </p>
- <source>
-
- <!-- Make .mxinfo automatically for blocks -->
- <target name="phoenix-qdox" depends="compile">
-
- <mkdir dir="${build.qdox}"/>
-
- <taskdef name="generatemeta"
- classname="org.codehaus.loom.info.GenerateLoomDescriptorsTask">
- <classpath refid="project.class.path" />
- </taskdef>
-
- <generatemeta dest="${build.qdox}">
- <fileset dir="${java.dir}">
- <include name="**/*.java"/>
- </fileset>
- </generatemeta>
-
- </target>
-
- </source>
- <p>
- Where build.qdox is where the .mxinfo files should be placed, and java.dir
- is the location of the source files.
- </p>
- <p>
- The qdox and phoenix-client jars need to be in the project.class.path.
- </p>
- </section>
- </body>
-</document>
loom/site/xdocs/guide/mx
diff -N index.xml
--- index.xml 3 Dec 2003 10:44:51 -0000 1.5
+++ /dev/null 1 Jan 1970 00:00:00 -0000
<at> <at> -1,82 +0,0 <at> <at>
-<?xml version="1.0" encoding="iso-8859-1"?>
-<document>
- <properties>
- <title>Management Guide</title>
- <author email="huw-1oDqGaOF3Lkdnm+yROfE0A@public.gmane.org">Huw Roberts</author>
- </properties>
- <body>
- <section name="Introduction">
- <p>
- Management refers to how a running instance of Loom, along with
- its components, applications and blocks is supervised and manipulated.
- This guide covers the steps required to write management-enabled
- applications using Loom.
- </p>
- </section>
- <section name="Overview">
- <p>
- Management in Loom is divided into two distinct areas. The first
- area is the the management metadata. This is information about which
- applications, blocks and
- components should be managed, the operations and attributes
- to expose, and descriptions for each these to help guide the user.
- Each block and component
- stores this data in an MetaClass descriptor that is distributed along
- with the class files that make up Loom and the Loom-enabled
- applications.
- </p>
- <p>
- The second area is the Loom component that uses the
- MetaClass files to generate a user interface through which Loom
- and its applications are interacted with. It is anticipated
- that a number of such interfaces will be developed. The current
- implementation of the management component uses the descriptors
- to generate ModelMBeans that are then registered and exposed
- through a slightly customized JMX implementation called
- <a href="http://mx4j.sourceforge.net/">MX4J</a>.
- </p>
- <p>
- Note that nothing about the descriptor is dependant on using
- JMX, and the block author does not need to know or care about
- how Loom, the application, and its blocks will be managed.
- His/her responsibility is limited to creating an descriptor file.
- </p>
- <p>
- The guide is broken into a number of sections, each
- covering a particular aspect of the management picture.
- </p>
- </section>
- <section name="Organizing Structure for Management Data">
- <p>
- This section provides a conceptual overview of the elements that
- are used to represent management information within Loom.
- An understanding of these elements and their relationships is
- essential for all users of the management functionality.
- </p>
- <p>
- <a href="structure.html">Structure</a>
- </p>
- </section>
- <section name="Step-By-Step Walk-Through">
- <p>
- This section walks through the steps that are needed to make a
- block manageable. The emphasis is on illuminating the process,
- it does not cover every feature or option.
- </p>
- <p>
- <a href="overview.html">Step-by-Step</a>
- </p>
- </section>
- <section name="Using XDoclet Tags to Generate the Descriptor file">
- <p>
- It is recommended that component and block authors make use
- of custom JavaDoc tags inserted into the source code. These
- tags are parsed using the MetaClass tool to produce the
- descriptor.
- </p>
- <p>
- <a href="doclet-tags.html">Doclet Tags</a>
- </p>
- </section>
- </body>
-</document>
loom/site/xdocs/guide/mx
diff -N overview.xml
--- overview.xml 15 Oct 2003 03:43:09 -0000 1.4
+++ /dev/null 1 Jan 1970 00:00:00 -0000
<at> <at> -1,110 +0,0 <at> <at>
-<?xml version="1.0" encoding="iso-8859-1"?>
-<document>
- <properties>
- <title>Guide - Step by Step Overview</title>
- <author email="huw-1oDqGaOF3Lkdnm+yROfE0A@public.gmane.org">Huw Roberts</author>
- </properties>
- <body>
- <section name="Introduction">
- <p>
- This section gives a quick overview of how to go from a block's source code,
- to a managed object accessible in a management interface. It discusses
- the role of actors at three different points in the
- life cycle of the application:
- during development, at start-up, and while running.
- </p>
-
- <subsection name="In Development">
- <p>
- For a block to be manageable, the developer must provide an
- MetaClass descriptor along with the compiled code. The easiest
- way to do that is to insert a series of Doclet tags into
- the source file. An example of how to use these tags follows.
- </p>
- <p>
- First, at the class level, the block must be tagged as manageable
- with <at> phoenix:mx-topic tag:
- </p>
-
- <source>
- /**
- * Ftp server starting point. Avalon framework will load this
- * from the jar file. This is also the starting point of remote
- * admin.
- *
- * <at> phoenix:block
- * <at> phoenix:mx-topic
- * <at> phoenix:service name="org.apache.avalon.ftpserver...
- */
- public class FtpServerImpl extends AbstractLogEnabled
- ...
- </source>
- <p>
- Then, for each attribute that should be exposed add the
- <at> phoenix:mx-attribute tag:
- </p>
- <source>
- /**
- * <at> phoenix:mx-attribute
- * <at> phoenix:mx-description Returns the top published directory
- */
- public String getDefaultRoot() {
- ...
- </source>
- <p>
- and finally for each operation add the <at> phoenix:mx-operation tag:
- </p>
- <source>
- /**
- * <at> phoenix:mx-operation
- * <at> phoenix:mx-description Returns port that the server listens on
- */
- public String getServerPort(Integer instance) {
- ...
- </source>
- <p>
- When this is compiled the LoomDoclet task extracts this and inserts it
- into an mxinfo file. If a method doesn't have a <at> pheonix:mx-attribute tag it is not exposed for
- management.
- </p>
- </subsection>
- <subsection name="At Startup">
- <p>
- At startup, Loom registers each block to a local SystemManager context. This
- context determines where the block fits into the management hierarchy.
- </p>
- <p>
- The following code snippet shows the code snippet that registers
- the Embeddor component with the 'component' management context. A
- similar process is followed for registering the blocks in
- the application.
- </p>
- <source>
- // get the management context
- final SystemManager componentManager =
- systemManager.getSubContext( null, "component" );
-
- // register the component
- componentManager.register( ManagementRegistration.EMBEDDOR.getName(),
- this,
- ManagementRegistration.EMBEDDOR.getInterfaces() );
- </source>
- <p>
- The system manager uses the mxinfo file in conjunction with introspection to
- generate a ModelMBeanInfo object for each topic. A RequiredModelMBean is then
- created and exposed for management.
- </p>
- </subsection>
- <subsection name="While Running">
- <p>
- In the default configuration, management is provided through MX4J. The administrator can perform various
- tasks such as deploying, starting and stopping applications and changing the configuration of various
- blocks.
- </p>
- <p>
- By default, the server is accessed on port 8082 of the server. eg. http://localhost:8082.
- </p>
- </subsection>
- </section>
- </body>
-</document>
loom/site/xdocs/guide/mx
diff -N structure.xml
--- structure.xml 19 Apr 2004 21:36:43 -0000 1.6
+++ /dev/null 1 Jan 1970 00:00:00 -0000
<at> <at> -1,111 +0,0 <at> <at>
-<?xml version="1.0" encoding="iso-8859-1"?>
-<document>
- <properties>
- <title>Management Guide - Organizing Structure</title>
- <author email="huw-1oDqGaOF3Lkdnm+yROfE0A@public.gmane.org">Huw Roberts</author>
- </properties>
- <body>
- <section name="Introduction">
- <p>
- Loom Management separates the information on what should be managed
- from the implementation of the management agent. In order to maintain
- this separation, yet still allow the management interface to be rich
- and structured enough to be useful, it is necessary to impose an organizing
- strucuture on the management metadata. This structure will be common
- across all management interfaces, although the specifics of how it is
- exposed is up to the implementor.
- </p>
- </section>
- <section name="Elements">
- <p>
- Management information is stored in a structured format that contains both a
- functional definition of the actions (what can be done) and descriptive information
- about the actions (to help guide the user). It is composed of the following elements:
- </p>
- <subsection name="Context">
- <p>
- In Loom, each managed object belongs to a single Context
- The Context contains a list of managed components called Targets. In
- addition to the list of Targets, a Context can also have zero or more
- sub-Contexts.
- </p>
- <p>
- This nested structure of Contexts is the principal
- organizing element for management data, and is the bridge between
- the management code embedded in Loom and the implementation of the
- management component. It is represented by the
- <code>org.codehaus.loom.interfaces.SystemManager</code>
- interface.
- </p>
- </subsection>
- <subsection name="Target">
- <p>
- A target is a manageable object. Examples of Targets in Loom include the
- components, the applications and the blocks. Each target has one or more topics.
- </p>
- </subsection>
- <subsection name="Topic">
- <p>
- A topic is a logical grouping of attributes that can be get and/or set on the Target and a
- group of operations that can be called on it. It is intended that Topics group together
- a particular aspect of Targets manageability.
- </p>
- </subsection>
- </section>
- <section name="Hierarchy">
- <p>
- This diagram illustrates how this might be presented in a management GUI:
- </p>
- <source>
-Loom
- |
- +--Components
- | +-- Kernel
- | +-- Deployer
- | +-- etc.
- |
- +--Applications
- +-- Hello World
- | +-- Blocks
- | +-- Block 1
- | +-- Block 2
- |
- +-- Another App
- +-- Blocks
- +-- Block 1
- +-- Block 2
- </source>
- <p>
- In this example Loom, Components and Blocks are Contexts. Kernel, Deployer, Hello World, Block 1, etc are Targets. Each Target will then have one or more Topics. Topics might be Logging, Lifecycle, Deployer, etc.
- </p>
- <p>
- In a jmx environment each topic would most likely be exported as its own mbean
- (so in the above example the jmx name would be 'Instance=Loom,Application=Hello_World,Block=Block_2,Topic=Logger'.
- </p>
- <p>
- In a swing environment each topic might have its own tab.
- </p>
- <p>
- In a command line environment, the syntax might be:
- </p>
- <source>
-phoenix-mx.set( "Loom/Applications/Hello World/Logging/LogLevel", "DEBUG" );
-phoenix-mx.describe( ""Loom/Applications/Hello World/Logging/LogLevel" );
- </source>
- <p>
- Again, the point behind the 'Organizing Structure' is to keep the management specification
- separated from the management agent, while at the same time providing enough definition
- to keep a shared conceptual view between the two areas.
- </p>
- </section>
- <section name="Management Proxies">
- <p>
- There is one remaining concept to cover, the proxy. It is a class that can be used
- to wrap access to the underlying target. Posible uses include the mapping of data
- types to a more friendly type, (eg. from Date to String and back), cleaning up method names,
- providing backwards compatibility with older versions, and exposing methods
- missing from the target class, but available to it via a reference.
- </p>
- </section>
- </body>
-</document>
CVSspam 0.2.8