nicolaken 2002/11/18 06:18:18
Added: src/documentation/content book.xml features.xml
for-developers-a-future.xml
for-developers-alternate-kernel.xml
for-developers-project-structure.xml
getting-started.xml guide-administrator.xml
guide-architecture.xml guide-deployers.xml
guide-example-configuration.xml
guide-management.xml guide-roles.xml index.xml
install.xml jboss-setup.xml tabs.xml
Log:
First step of migration of documentation to Forrest.
New docs dir:
jakarta-avalon-phoenix/src/documentation
New content dir:
jakarta-avalon-phoenix/src/documentation/content
New resources and images dir:
jakarta-avalon-phoenix/src/documentation/resources
To build the documentation download Forrest from CVS
http://xml.apache.org/forrest/your-project.html#N10022
install it as described here
http://xml.apache.org/forrest/your-project.html#N10036
cd in the jakarta-avalon-phoenix dir and run "forrest"
To see the site real-time from a local embedded webserver run "forrest run"
and point the browser to http://localhost:8888/
The sources to change are in ./build/webapp, you will need to synch them with
the actual docs manually.
Or run the Phoenix build.xml with target "site".
Revision Changes Path
1.1 jakarta-avalon-phoenix/src/documentation/content/book.xml
Index: book.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN"
"book-cocoon-v10.dtd">
<book title="Avalon Phoenix" copyright="Avalon Phoenix" software="Avalon
Phoenix">
<menu label="Essentials">
<menu-item href="index.html" label="Overview"/>
<menu-item href="features.html" label="Features"/>
<menu-item href="getting-started.html" label="Getting started"/>
<menu-item href="http://jakarta.apache.org/builds/jakarta-avalon-phoenix";
label="Download"/>
<menu-item href="install.html" label="Install"/>
</menu>
<menu label="Guide">
<menu-item href="guide-architecture.html" label="Architectural Overview"/>
<menu-item href="guide-roles.html" label="Development Roles"/>
<menu-item href="guide-administrator.html" label="for Administrators"/>
<menu-item href="guide-deployers.html" label="for Deployers"/>
<menu-item href="assemblers/index.html" label="for Assemblers"/>
<menu-item href="bdg/index.html" label="for Block Developers"/>
<menu-item href="mx/index.html" label="Management Guide"/>
<menu-item href="guide-example-configuration.html" label="Example
configuration"/>
</menu>
<menu label="Reference">
<menu-item href="api/index.html" label="API Docs"/>
<menu-item href="assemblers/config-xml-specification.html" label="config.xml
Specification"/>
<menu-item href="assemblers/assembly-xml-specification.html"
label="assembly.xml Specification"/>
<menu-item href="assemblers/environment-xml-specification.html"
label="environment.xml Specification"/>
<menu-item href="bdg/blockinfo-specification.html" label="BlockInfo
Specification"/>
</menu>
<menu label="For Developers">
<menu-item href="changes.html" label="Changes"/>
<menu-item href="http://jakarta.apache.org/avalon/code-standards.html";
label="Coding standards"/>
<menu-item href="for-developers-project-structure.html" label="Project
Structure"/>
<menu-item href="http://jakarta.apache.org/site/cvsindex.html"; label="CVS
Repositories"/>
<menu-item href="http://jakarta.apache.org/site/mail.html"; label="Mailing
Lists"/>
<menu-item
href="http://nagoya.apache.org/bugzilla/buglist.cgi?bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=RESOLVED&product=Avalon&component=Phoenix";
label="TODO"/>
<menu-item
href="http://nagoya.apache.org/bugzilla/enter_bug.cgi?product=Avalon&component=Phoenix";
label="Bug Database"/>
<menu-item
href="http://nagoya.apache.org/bugzilla/enter_bug.cgi?product=Avalon&component=Phoenix&bug_severity=Enhancement";
label="Enhancement Requests"/>
<menu-item href="for-developers-alternate-kernel.html" label="Alternate
Kernels"/>
</menu>
</book>
1.1
jakarta-avalon-phoenix/src/documentation/content/features.xml
Index: features.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Features</title>
<authors><person name="Leo Simons" email="[EMAIL
PROTECTED]"/></authors></header>
<body>
<section><title>Introduction</title>
<p>This document is not complete yet...</p>
</section>
<section><title>Extensible architecture</title>
<p>Phoenix is written as an extensible micro-kernel. This allows you
to:</p>
<ul>
<li>Customise behaviour quickly</li>
<li>Plug in extra functionality effortlessly</li>
<li>remove unneeded functionality for a small footprint</li>
</ul>
</section>
<section><title>Flexible environment</title>
<p>Phoenix has native support for use in the following environments:</p>
<ul>
<li>command-line stand-alone program</li>
<li>Unix daemon</li>
<li>Embedded in other programs (including servlet engines)</li>
</ul>
</section>
<section><title>Integrated management</title>
<p>Phoenix enables JMX management of your software:</p>
<ul>
<li>All aspects of phoenix itself are manageable, including
startup/shutdown, deployment, management and logging.</li>
<li>Applications running in phoenix are manageable, exposing
their lifecycle (configuration, startup/shutdown, etc) and
everything else you mark as manageable.</li>
</ul>
</section>
<section><title>Ease and speed up application development</title>
<p>Phoenix is a container for (server) applications. It can host
multiple applications within the same JVM, while keeping them securely
isolated from each other.</p>
<p>Phoenix provides simple XML configuration files that allow you to
rapidly assemble a customised server applications from readily available
components (called blocks).</p>
<p>Phoenix provides the following services to hosted applications:</p>
<ul>
<li>Lifecycle management</li>
<li>Configuration management and persistence</li>
<li>Resource management and sharing</li>
<li>Management exposure through JMX</li>
<li>Automatic (re)deployment</li>
<li>An isolated environment</li>
</ul>
<p>Phoenix leverages the Avalon Framework, making it compatible with other
Avalon-based projects like Excalibur and Cornerstone, enabling you to
easily reuse their functionality.</p>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/for-developers-a-future.xml
Index: for-developers-a-future.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>A future</title>
<authors><person name="Paul Hammant" email="[EMAIL
PROTECTED]"/></authors></header>
<body>
<section><title>Introduction</title>
<p>
A long term aim of Phoenix is to provide a platform that hosts
multiple third party applications written only in Java within a single virtual
machine. The Phoenix platform is currently hosted on an Operating System such
as Unix, Windows or Mac. It could function directly on top of a Java Operating
System. A CPU combined with a suitable amount of memory, a basic BIOS, a
Kernal, a suitable JVM and runtime library, could mount Phoenix and hosted
server applications.
</p>
</section>
<section><title>One step further</title>
<p>
Imagine Sun making such a box under their own name or as Cobalt,
using low power chips from their own stable or perhaps a StrongARM. That
machine could be rack mounted like their current X1:
</p>
<figure
src="http://www.sun.com/products-n-solutions/hw/networking/images/prodsplash/x1.jpg";
alt="Sun X1"/>
<p>
If that rackable server had 32 such CPUs, each with 128Mb of memory
all
booting Phoenix. And if the CPUs shared a single hard drive, we might
have
a machine that was tuned to CPU intensive activities. Cocoon/Tomcat,
EJB
clusters, might be load balanced by one of the CPUs running a Phoenix
load
balancer. Alternate scenarios are for virtual site hosting. It
could be
a "1U" render or bean farm with each internal CPU having its own
TCP/IP
address.
</p>
</section>
<section><title>Is all this possible?</title>
<p>
Well there are already romable J2SE implementations that are
available for
StrongARM chips on Compaq's handheld iPAQ. We are there already, but
for
the client side rather than the server side.
</p>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/for-developers-alternate-kernel.xml
Index: for-developers-alternate-kernel.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Alternate Kernels</title>
<authors><person name="Paul Hammant" email="[EMAIL
PROTECTED]"/></authors></header>
<body>
<section><title>Introduction</title>
<p>
Phoenix can launch with alternate kernels. Apart from the default
kernel which is suitable for deploying in live scenarios, we
supply a kernel which loads beanshell during startup.
</p>
</section>
<section><title>Beanshell enabled kernel</title>
<p>
This allows pretty much any anything to be done to applications
and blocks once started. As such it is not suitable for live
deployment as it could be considered a bit of a hackers tool.
</p>
<p>
The supplied commands are getblock, prtapps, prtblocks, resumeapp,
rmvapp, startapp, stopapp and suspendapp. With getapp, you can
invoke any of the public methods on the implementation, including
interacting with the block's methods from its service.
</p>
<p>
To create a beanshell capable kernel, place the bsh-1.2b6.jar from
<link href="http://www.beanshell.org/download.html";>here</link> in
the
lib directory of phoenix before building it. You will need to edit
the
'beanshell.jars' and 'kernel.impl.class' parts of the ant.properties
file.
You may also want to add your own convenience bsh scripts to the
src/bsh/ directory.
</p>
</section>
<section><title>Beanshell enabled, remotely accessible kernel</title>
<p>
This is to-do.
</p>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/for-developers-project-structure.xml
Index: for-developers-project-structure.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Project Structure</title>
<authors><person name="Leo Simons" email="[EMAIL
PROTECTED]"/></authors></header>
<body>
<section><title>Introduction</title>
<p>Avalon Phoenix has seen lots of refactoring to create an intuitive
code layout. It is usually quite easy to find what you need. This document
provides an overview of the project structure. It is still under
construction.</p>
</section>
<section><title>Package structure</title>
<source>
org.apache.avalon.phoenix
|
|- components
| |- application
| |- classloader
| |- configuration
| |- deployer
| |- installer
| |- embeddor
| |- extensions
| |- kernel
| |- logger
| |- manager
| |- rmiadaptor
|- frontends
|- interfaces
|- launcher
|- metadata
|- metainfo
|- tools
|- assembler
|- configuration
|- infobuilder
|- tasks
|- verifier
|- xdoclet
</source>
</section>
<section><title>CVS Directory structure</title>
<source>
jakarta-avalon-phoenix
|
|- lib : for third party libraries
|
|- src
| |
| |- conf : jar manifest
| |- java : java sources
| |- manifest : jar manifest files
| |- pdk : sources for PDK
| |- schema : DTDs for XML files
| |- script : shell scripts for usage in a standalone setup
| |- test : unit tests
| |- xdocs : site documentation in xml format
|
|- build.xml
|- docs.xml
|
|- BUILDING.txt
|- LICENSE.txt
|- README.txt
|- WARNING.txt
</source>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/getting-started.xml
Index: getting-started.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Getting Started</title>
<authors><person name="Phoenix Documentation Team"
email="avalon-phoenix-dev@jakarta.apache.org"/><person name="Leo Simons"
email="[EMAIL PROTECTED]"/><person name="Paul Hammant" email="[EMAIL
PROTECTED]"/></authors></header>
<body>
<section><title>Introduction</title>
<p>
This document provides developers with simple documentation for getting
started with Phoenix. For information about the overall structure of
Avalon Framework (on which Phoenix is based), please refer to the
<link
href="http://jakarta.apache.org/avalon/framework/index.html";>Framework
documentation</link>.
</p>
<p>
Instructions for downloading and installing Phoenix can be found on the
<link href="install.html">Install</link> document.
</p>
<p>
More detailed instructions will be added to this document in the future.
Feel free
to send in patches ;)
</p>
</section>
<section><title>View Detailed API Documentation</title>
<p>
To generate a full set of detailed API documentation for Avalon, go to
the base
directory of source distribution and run the appropriate build script for
your
platform with the parameter 'javadocs'.
<code>
> build.[bat|sh] javadocs
</code>
</p>
</section>
<section><title>Run the HelloWorld example</title>
<p>
After you have successfully built Phoenix, you can verify that it
has compiled correctly by running the HelloWorld demo Service Application.
</p>
<p>
Firstly you will need to get the demo-helloword.sar file and drop it into
the apps directory of Phoenix. Get it from <link href="TODO">TODO</link>
or build
it from its CVS - <link
href="http://cvs.apache.org/viewcvs/jakarta-avalon-apps/demo/";>
http://cvs.apache.org/viewcvs/jakarta-avalon-apps/demo/</link>.
</p>
<p>
Then fire up phoenix with the following command:
<code>
> bin/run.[bat|sh]
</code>
</p>
<p>
Next, fire up your favorite webbrowser and point it to
http://localhost:8999/,
where localhost is the network name of your machine ("localhost") should
work on all windows platforms.<br/>
If all goes well, you will see something like the following:
<code>
Hello World!
Requests so far = 1
you are 127.0.0.1 at 127.0.0.1
</code>
</p>
<p>
This shows that Phoenix has unpacked and launched the server application
contained
within the demo-helloworld.sar file. If you close and relaunch Phoenix,
it should
restart the application.
</p>
<p>
As examples go this is a fairly simple one. You should ignore the
altrmihelloworldserver,
rmihelloworldserver and soaphelloworldserver packages as they are
retrofitting the
helloworld demo with remote capability using three technologies.
HelloWorld uses
connection management from the Avalon-Cornerstone project, which is good
as it allows us to
share connection pooling across multiple servers.
</p>
</section>
<section><title>The Phoenix Developer Kit - A different example</title>
<p>
This self contained kit could be considered a starter project for someone
wanting to make a
Phoenix compatible application. The idea is that you start with this
skeleton including
Ant build script and then add in more and more as your se code to copy
from elsewhere.
</p>
<p>
This also demonstrates that it is possible to make a server application
that is dual mode.
Dual mode to us is the ability for the server application to run inside
Phoenix and to
stand-alone from the command line. It is a little bit of a sleight of
hand as the codebase
would be zipped into two forms - the sar file for phoenix and a jar file
for standalone.
</p>
<p>
The Phoenix development kit originates in Phoenix's CVS, but for
convenience is downloadable
from <link href="TODO">TODO</link>. When you have that file, unzip it
and immediately launch
ant to make the jars and sars. There are four:
</p><ol>
<li>phoenix-demo.sar - the server app in Phoenix form</li>
<li>phoenix-demo-block.sar - used inside the sar</li>
<li>phoenix-demo-client.sar - a client app to test the server</li>
<li>phoenix-demo-server.sar - the server app in standalone form</li>
</ol><p>
The Server app in standalone mode after being tested with the client
app(see below):
<code>
java -jar phoenix-demo-server.jar
PDK Demo listening on port 7654
Ctrl-C to exit
String passed = Hello!!!!!
</code>
The Server app running inside Phoenix and after being tested with the
client app (see below):
<code>
Phoenix 4.0a4
Server started on port 1234
String passed = Hello!!!!!
</code>
The client application being used to poke the server :
<code>
java -jar phoenix-demo-client.jar localhost 7654 Hello!!!!!
</code>
(Change the port to 1234 from 7654 to poke the in-Phoenix server).
</p>
<p>
Note - because of the need to make this dual mode, the PDK does not use
Cornerstone
components. We normally recommend that people should reuse components
from cornerstone as
the potential for sharing will be much higher.
</p>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/guide-administrator.xml
Index: guide-administrator.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Guide - for Administrators</title>
<authors><person name="David W." email="[EMAIL
PROTECTED]"/></authors></header>
<body>
<section><title>Introduction</title>
<p>
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.
</p>
<section><title>Target Audience</title>
<p>
This documentation will describe the care and feeding of
the Avalon
Phoenix kernel from the point of view of the administrator.
</p>
</section>
</section>
<section><title>Starting and Stopping</title>
<section><title>Using Scripts</title>
<p>
You can start Phoenix with the following command:
<code>
> bin/run.[bat|sh]
</code>
</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>
</section>
<section><title>Using the Java Service Wrapper</title>
<p>
Another option for starting and stopping Phoenix is to build
it with support for the
<link href="http://wrapper.sourceforge.net/";>Java Service
Wrapper</link>.
</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>
</section>
</section>
<section><title>Using JMX</title>
<section><title>JMX Overview</title>
<p>
Phoenix is tightly integrated with Java Management Extensions
(JMX).
TODO: say something else. Integrate this section with the
other
<link href="mx/index.html">JMX info</link>.
</p>
</section>
<section><title>How to Make Your Block an MBean</title>
<p>
It's actually quite simple. Suppose you wanted to expose the
interface from the WebServer block
<link
href="bdg/making-phoenix-compatible-comps.html">described</link> 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;
/**
* TODO: describe PhoenixXDoclet setup.
* @phoenix:mx name="examplecomp.block.WebServerMBean"
*/
public class WebServerBlock
extends AbstractLoggable
implements WebServer, WebServerMBean, Startable, Configurable,
Initializable {
// ...
}
</source>
</section>
<section><title>Using Http Adaptor</title>
<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
<link
href="http://localhost:8082/";>http://localhost:8082/</link>.
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>
</section>
<section><title>Using RMI Adaptor</title>
<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
<link
href="http://mx4j.sourceforge.net/docs/bk01ch03s13.html#d0e1012";>
documentation</link>. Phoenix uses the JRMP RMI Adaptor.
</p>
<p>
Ensure that the MX4J RMI Adaptor is enabled in kernal.xml
</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>
[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>
</section>
</section>
<section><title>Troubleshooting</title>
<p>
<strong>Phoenix 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, 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>
1.1
jakarta-avalon-phoenix/src/documentation/content/guide-architecture.xml
Index: guide-architecture.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Guide - Architectural overview</title>
<authors><person name="Leo Simons" email="[EMAIL
PROTECTED]"/></authors></header>
<body>
<section><title>Introduction</title>
<p>
This document briefly describes the Phoenix server architecture.
</p>
</section>
<section><title>Multiple Server Application hosting</title>
<p>
Phoenix hosts one or more server applications at the same time
in the same Virtual machine.
</p>
<p>
<strong>Phoenix layer diagram</strong>
</p>
<figure src="images/phoenix-layers.jpg" alt="Phoenix 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,
Eudora and other mail clients would be able to connect to the
server. As it happens,
Apache has a project in progress called "James" that provides
these services and Newsgroups.
Also shown is a Web server. That would respond to HTTP/HTTPS
requests from similar standards
based clients and be able to host it's own applications
(web-apps and virtual websites). Lastly,
and non-existant currently at Apache is an EJB Server. This
would be able to host it's own
bean applications and might use the web server for it's HTTP
needs.
</p>
</section>
<section><title>Packaging of a Server Application</title>
<p>
Phoenix application are distributed in a single archive.
</p>
<section><title>Packaging in terms of blocks</title>
<p>
Phoenix hosts server applications made up of blocks. The
blocks may depend on libraries
to function correctly. The blocks are tied together with
Assembly instructions and Configured
externally.
</p>
<p>
<strong>Phoenix application in block view</strong>
</p>
<figure src="images/phoenix-app-block.jpg" alt="Phoenix
App Block"/>
</section>
<section><title>Packaging in terms of block jar files</title>
<p>
The server application is entirely contained withing one
"sar" file. Sar is "Server ARchive".
Each block is a jar file. The dependant libraries are
regular jars (placed
within a directory "lib" insde the sar file). The Assembly
and configuration instructions
are in xml form and contained within a "conf" directory
inside the sar file.
</p>
<figure src="images/phoenix-app-blockjars.jpg" alt="Phoenix
application in block jar view"/>
</section>
<section><title>FtpServer as a Phoenix application</title>
<p>
FtpServer (part of the Avalon/Cornerstone project) is
distributed in sar form. Here is a
view of it's blocks. It has no third party jars that it
depends on.
</p>
<p>
<strong>FtpServer, a real Phoenix application</strong>
</p>
<figure src="images/phoenix-app-ftpserver.jpg"
alt="Phoenix App FtpServer"/>
</section>
<p>
Notes - Phoenix does not limit the number of blocks that it
allows in a sar file. We have taksdefs for Apache's Ant
tool for making sar files. See the "Block Developers Guide"
(left
margin of this page) for more what/how/why.
</p>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/guide-deployers.xml
Index: guide-deployers.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Guide - for Deployers</title>
<authors><person name="Phoenix Documentation Team"
email="avalon-phoenix-dev@jakarta.apache.org"/></authors></header>
<body>
<section><title>Introduction</title>
<p>
Currently deploying a server application under Phoenix is simply a
matter
of dropping the .sar file into the appropriate directory
(<code>apps/</code>)
and restarting Phoenix. In the future there will be more advanced
methods
of deploying and undeploying Server Applications without restarting
Phoenix.
</p>
<section><title>Target Audience</title>
<p>
This documentation describes the methods through which you can
deploy
Server Applications under the Phoenix kernel. It will be expanded as
the system becomes more complete.
</p>
</section>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/guide-example-configuration.xml
Index: guide-example-configuration.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Guide - Example Configuration</title>
<authors><person name="Stephen McConnell" email="[EMAIL
PROTECTED]"/><person name="Gerhard Froehlich" email="[EMAIL
PROTECTED]"/></authors></header>
<body>
<section><title>Introduction</title>
<p>This page contains a real production example of a block
assembly and block .xinfo description based an extract from
a B2B Enterprise Integration and Collaboration Platform developed by
<link href="http://www.osm.net";>OSM</link>.</p>
<p>This example was originally a Mailing List response to a
some user questions!</p>
<p>The orginal post was written by Stephen McConnell from OSM.</p>
</section>
<section><title>The example</title>
<p>Each Block has an associated xinfo file and the xinfo file
is stored alongside the block in a jar file. The <code>.xinfo</code>
file contains a description of a reasonably simple block that serves
as a factory for business processes that handle PKI certification
requests:</p>
<source>
<?xml version="1.0"?>
<blockinfo>
<block>
<version>1.0</version>
</block>
<services>
<!--
This block could be declaring several services that it supports.
Unlike a Java interface, the service includes a version tag. So
it's possible for a block to have several services with possibly
different versions. If there are multiple services then just
declare them with multiple service entries here. Phoenix will make
sure that the class with the same name as the .xinfo file
implements these interfaces (if it doesn't then Phoenix will
terminate).
-->
<service name="org.apache.acme.hub.gateway.FactoryService"/>
</services>
<!--
So far, we have the definition of a class that supports possibly
multiple version interfaces. But things get much more interesting, when
we think about the services that this block requires in order to function
properly. That's partly handled by the dependencies element and partly by
the assembly.xml file (which I'll explain later). In the following
dependency example there are seven "service" dependencies (i.e. 7 versioned
interface dependencies that must be fulfilled for this block to function.
-->
<dependencies>
<!--
Each dependency contains a declaration of a role name and a service
interface and a version that can fulfil that role. The dependency
does not say anything about where that service implementation should
come from (that's the job the assembly.xml file). The role element
is simply the label used in the implementation of your block configure
method that distinguishes a particular instance of the service.
-->
<dependency>
<role>GATEWAY</role>
<service name="org.apache.acme.hub.gateway.GatewayContext"/>
</dependency>
<!--
This dependency declaration simply states that in order to function,
this block requires a <service/> (in this case a wrapper to a
CORBA
ORB version 2.4) and that the block implementation will lookup this
service using the "ORB" keyword.
-->
<dependency>
<role>ORB</role>
<service name="org.apache.acme.hub.gateway.ORBService"
version="2.4"/>
</dependency>
<!--
This dependency declares a requirement for a PSS (Persistent State
Service) Storage Home.
-->
<dependency>
<role>PSS</role>
<service
name="org.apache.acme.hub.gateway.ProcessorStorageHomeService"/>
</dependency>
<!--
This dependency enables the block to establish a call-back to the
block supplying the service. This block uses the Registry interface
to publish a business process description to a higher level manager.
-->
<dependency>
<role>REGISTRY</role>
<service name="org.apache.acme.hub.gateway.Registry"/>
</dependency>
<!-- etc. -->
<dependency>
<role>DOMAIN</role>
<service name="org.apache.acme.hub.gateway.DomainService"/>
</dependency>
<dependency>
<role>RANDOM</role>
<service name="org.apache.acme.hub.gateway.RandomService"/>
</dependency>
<dependency>
<role>CLOCK</role>
<service name="org.apache.acme.service.time.TimeService"/>
</dependency>
</dependencies>
</blockinfo>
</source>
<p>Next is the block declaration (an extract from an
<code>assembly.xml</code>
file). This enables the declaration of WHERE the services are coming
from.
I.e. you may have a system with many blocks and even the potential for
matching
services available from more that one block. The class attribute
provides the
link to the <code>.xinfo</code> file and the implementation class. The
name
is used a key within the <code>assembly.xml</code> file when wiring
things together.
E.g. the provide element references a block by its name - and declares
that the
named block will serve as the provider of the service. The role
attribute matches
the role element in the <code>.xinfo</code> dependency declaration.</p>
<p>The name attribute also serves a the key to lookup a configuration
element in
the application configuration.xml file.</p>
<source>
<?xml version="1.0"?>
<assembly>
<!-- other assembly information here -->
<!-- Certification Request Processor Factory -->
<block class="org.apache.acme.pki.process.CertificationRequestServer"
name="certification" >
<provide name="gateway" role="GATEWAY"/>
<provide name="gateway" role="ORB"/>
<provide name="gateway" role="PSS"/>
<provide name="gateway" role="DOMAIN"/>
<provide name="gateway" role="RANDOM"/>
<provide name="pki" role="REGISTRY"/>
<provide name="time" role="CLOCK"/>
</block>
<!-- more assembly information here -->
</assembly>
</source>
<section><title/></section>
<section><title>Why this seperation?</title></section>
<ul>
<li>It forces structure and separation</li>
<li>It provides a way of managing possibly multiple versions of the
same interface in a single environment</li>
<li>It enables explicit declaration of the source of service
provision</li>
</ul>
<p>For example you can have multiple blocks providing a TimeService.
One of those blocks uses an external time reference while the others
use a local time reference. The local time block
declare dependencies on the external source time block and is periodically
synchronised. In this example all of the TimeService services are exposing
the same interface, same version (i.e. same service), but the decision as
to
which service is the provider to another can be explicitly controlled.
While the time example is perhaps trivial, there are significant policy
security implications related to service provider selection.</p>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/guide-management.xml
Index: guide-management.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Guide - JMX Management</title>
<authors><person name="Huw Roberts" email="[EMAIL
PROTECTED]"/></authors></header>
<body>
<section><title>Table of Contents</title>
<table>
<tr>
<td>Section</td>
<td>Title</td>
<td>Intended Audience</td>
</tr>
<tr>
<td>
1.
</td>
<td>
<link href="guide-mx-structure.html">Organizing Structure for
Management Data</link>
</td>
<td>
Everyone
</td>
</tr>
<tr>
<td>
2.
</td>
<td>
<link href="guide-mx-overview.html">Step by Step Overview</link>
</td>
<td>
Everyone
</td>
</tr>
<tr>
<td>
3.
</td>
<td>
<link href="guide-mx-mxinfo.html">MXINFO files</link>
</td>
<td>
Component Authors
</td>
</tr>
<tr>
<td>
4.
</td>
<td>
<link href="guide-mx-xdoctags.html">XDoclet Tagging</link>
</td>
<td>
Component Authors
</td>
</tr>
<tr>
<td>
5.
</td>
<td>
[TODO] Container Responsibilities to Support Management
</td>
<td>
Container Authors
</td>
</tr>
<tr>
<td>
6.
</td>
<td>
Link to javadocs
</td>
<td>
Reference
</td>
</tr>
</table>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/guide-roles.xml
Index: guide-roles.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Development Roles</title>
<authors><person name="Leo Simons" email="[EMAIL
PROTECTED]"/></authors></header>
<body>
<section><title>Introduction</title>
<p>
In phoenix-based development, we identify several roles. Each
of these has its own
guide. If you plan to aid in the development of phoenix itself, or if
you are
responsible for all these aspects, you should read all the guides.
Otherwise, you
should be able to learn everything you need to know from the guide
that fits your
role.
</p>
</section>
<section><title>The Administrator</title>
<p>The administrator is responsible for getting phoenix to run
and for keeping it
running. He typically controls the startup and shutdown of the
standalone server
or daemon, and uses a management console to keep the server in
top condition.</p>
<p>
<link href="guide-administrator.html">Administrator's
Guide</link>
</p>
</section>
<section><title>The Deployer</title>
<p>The deployer manages (un/re)deployment of the applications
hosted withing phoenix,
typically through a management console. In real life, this is
often the same person
as the adminstrator.</p>
<p>
<link href="guide-deployers.html">Deployer's Guide</link>
</p>
</section>
<section><title>The Assembler</title>
<p>The assembler takes pre-written blocks and glues these
together to create a
server application. Assemblers usually work closely with block
developers.</p>
<p>
<link href="assemblers/index.html">Assembler Guide</link>
</p>
</section>
<section><title>The Block Developer</title>
<p>The block developer creates reusable components (called
blocks) that can be
wired together to form a server applications.</p>
<p>
<link href="bdg/index.html">Block Developers Guide</link>
</p>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/index.xml
Index: index.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Overview</title>
<authors><person name="Phoenix Documentation Team"
email="avalon-phoenix-dev@jakarta.apache.org"/></authors></header>
<body>
<section><title>Introduction</title>
<p>
Phoenix is a micro-kernel designed and implemented on top of the
Avalon
framework. It is both an API to program to and a reference
implementation.
The reference implementation provides a number of facilities to
manage the
environment of Server Applications. Such facilities include log
management,
classloading, thread management and security. In the future it will
conditionally support extra facilities such as central server
management,
server pools, and other facilities aimed at reducing the time to
market. The API
defines a standard method of piecing together server components and
creating a server.
</p>
</section>
<section><title>Documentation is coming</title>
<p>
Some of the information on this site is currently a bit out of date.
We are
working hard to fix this. If you come across any incosistencies or have a
problem, please don't hesitate to contact us through the mailing list.
Thank
you.
</p>
</section>
<section><title>Guide to Avalon Phoenix</title>
<p>
This guide starts with an architectural overview of Phoenix. Then, we
identify
the different roles that typically exist in daily use of phoenix. For
each of
these, we provide a basic guide. We finish with a complete example.
</p>
<section><title>Target Audience</title>
<p>
This documentation is aimed towards people who:
</p><ul>
<li>wish to create applications that run within phoenix</li>
<li>wish to create components (blocks) for use within phoenix</li>
<li>wish to setup and administer phoenix</li>
<li>are interested in the design principles of Avalon
Phoenix</li>
<li>wish to develop code that will be incorporated into Avalon
Phoenix</li>
<li>wish to reuse Avalon Phoenix concepts in their own
application</li>
</ul><p>
</p>
</section>
<section><title>Contents</title>
<ol>
<li><link href="guide-architecture.html">Architectural
overview</link></li>
<li><link href="guide-roles.html">Development roles</link></li>
<li><link href="guide-administrator.html">Administrator
Guide</link></li>
<li><link href="guide-deployers.html">Application Deployer
Guide</link></li>
<li><link href="mx/index.html">JMX Management Guide</link></li>
<li><link href="assemblers/index.html">Server Application
Assembler Guide</link></li>
<li><link href="bdg/index.html">Block Developer Guide</link></li>
<li><link href="guide-example-configuration.html">Example
Configuration.</link></li>
</ol>
</section>
</section>
<section><title>Avalon Phoenix Reference Documentation</title>
<p>
Besides the
<link href="api/index.html">Javadocs</link>, we have the
<link href="guide-architecture.html">Architectural overview</link>
to look at.
</p>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/install.xml
Index: install.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Installation</title>
<authors><person name="Phoenix Documentation Team"
email="avalon-phoenix-dev@jakarta.apache.org"/></authors></header>
<body>
<section><title>Installation</title>
<p>
Phoenix runs on a variety of platforms that have installed the Java 2
Virtual Machine.
</p>
<p>
Everything required to run Phoenix and develope Phoenix based products
comes with the
<link
href="http://jakarta.apache.org/builds/avalon/release";>distribution</link>. If
you wish to help develop Avalon/Phoenix then it is recomended that you
obtain the full
source tree from <link
href="http://jakarta.apache.org/getinvolved/cvsindex.html";>CVS</link>
or from the <link
href="http://jakarta.apache.org/builds/avalon/nightly/";>nightly
builds</link>.
</p>
</section>
<section><title>Compiling</title>
<p>
Execute the relevant platform specific script (build.[sh|bat]) in the
base phoenix
directory.
</p>
<p>
Executing this script will create a <em>dist</em> directory within the
Phoenix
directory. The <em>dist</em> directory will contain the
compiled class files packaged into jars.
</p>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/jboss-setup.xml
Index: jboss-setup.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Introduction</title>
<authors><person name="Steve Short" email="[EMAIL
PROTECTED]"/></authors></header>
<body>
<section><title>Introduction</title>
<p>
This document describes the process for launching Phoenix in the
JBoss application server.
</p>
</section>
<section><title>Procedure</title>
<p>
Setup instructions (Windows based, but *nix equivalent is obvious):
</p>
<p>Copy phoenix distribution to Jboss directory:</p>
<source>copy %PHOENIX_HOME%\* %JBOSS_HOME%\phoenix</source>
<p>Copy phoenix loader to Jboss deployment dir (using Jboss
'default' server as example):</p>
<source>copy %PHOENIX_HOME%\bin\phoenix-loader.jar
%JBOSS_HOME%\server\defaultdeploy</source>
<p>Copy phoenix loader config file to Jboss deployment dir
(using Jboss 'default' server as example):</p>
<source>copy %PHOENIX_HOME%\conf\phoenix-service.xml
%JBOSS_HOME%\server\defaultdeploy</source>
<p>And don't forget to copy your app to the apps directory.
I think that's everything - if I've forgotten anything just
holler.</p>
</section>
</body>
</document>
1.1 jakarta-avalon-phoenix/src/documentation/content/tabs.xml
Index: tabs.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tabs PUBLIC "-//APACHE//DTD Cocoon Documentation Tab
V1.0//EN" "tab-cocoon-v10.dtd">
<tabs software="MyProj"
title="MyProj"
copyright="Foo"
xmlns:xlink="http://www.w3.org/1999/xlink";>
<tab label="Home" dir=""/>
<!-- Add new tabs here, eg:
<tab label="How-Tos" dir="community/howto/"/>
<tab label="XML Site" dir="xml-site/"/>
-->
</tabs>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
![http://www.sun.com/products-n-solutions/hw/networking/images/prodsplash/x1.jpg"](http://www.sun.com/products-n-solutions/hw/networking/images/prodsplash/x1.jpg"){kind=link}