You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@avalon.apache.org by ni...@apache.org on 2002/11/18 15:18:18 UTC
cvs commit: jakarta-avalon-phoenix/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
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="leosimons@apache.org"/></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="Paul_Hammant@yahoo.com"/></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="hammant@apache.org"/></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="leosimons@apache.org"/></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="leosimons@apache.org"/><person name="Paul Hammant" email="Paul_Hammant@yahoo.com"/></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="daveweit@optonline.net"/></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="leosimons@apache.org"/></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="mcconnell@osm.net"/><person name="Gerhard Froehlich" email="g-froehlich@gmx.de"/></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="huw@apache.org"/></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="leosimons@apache.org"/></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="sshort@postx.com"/></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: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>