leosimons 02/05/12 12:52:51
Modified: src/xdocs book.xml features.xml getting-started.xml
index.xml install.xml
Added: src/xdocs for-developers-a-future.xml
for-developers-changes.xml
for-developers-project-structure.xml
for-developers-todo.xml guide-administrator.xml
guide-architecture.xml
guide-assemblers-creating-a-server-application.xml
guide-assemblers-what-is-a-server-application.xml
guide-assemblers.xml
guide-block-developers-creating-a-block.xml
guide-block-developers-making-phoenix-compatible-comps.xml
guide-block-developers-what-is-a-block-listener.xml
guide-block-developers-what-is-a-block.xml
guide-block-developers-what-is-an-application-listener.xml
guide-block-developers.xml guide-deployers.xml
guide-example-configuration.xml guide-roles.xml
reference-assembly-xml-specification.xml
reference-blockinfo-specification.xml
reference-config-xml-specification.xml
reference-environment-xml-specification.xml
Removed: src/xdocs administrator-guide.xml afuture.xml
assemblers-guide.xml assembly-xml-specification.xml
block-developers-guide.xml
blockinfo-specification.xml changes.xml
config-xml-specification.xml creating-a-block.xml
creating-a-server-application.xml
deployers-guide.xml
environment-xml-specification.xml
example-configuration.xml
making-phoenix-compatible-comps.xml
what-is-a-block-listener.xml what-is-a-block.xml
what-is-an-application-listener.xml
what-is-a-server-application.xml todo.xml
Log:
overhaul of phoenix documentation organisation as discussed previously.
Brings material in sync with the framework documentation.
Revision Changes Path
1.13 +38 -36 jakarta-avalon-phoenix/src/xdocs/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-phoenix/src/xdocs/book.xml,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- book.xml 2 Apr 2002 18:56:21 -0000 1.12
+++ book.xml 12 May 2002 19:52:49 -0000 1.13
@@ -1,52 +1,54 @@
<?xml version="1.0"?>
-<book software="Phoenix"
- title="Phoenix Documentation"
- copyright="@year@ The Apache Software Foundation">
+<book software="Avalon Phoenix"
+ title="Avalon Phoenix Documentation"
+ copyright="@year@ The Apache Software Foundation"
+ xmlns:xlink="http://www.w3.org/1999/xlink";>
- <project label="Back to Avalon" href="@AVALON_BASE@" />
+ <project label="Jakarta main" href="http://jakarta.apache.org/"; />
+ <project label="Avalon main" href="@AVALON_BASE@" />
- <menu label="About">
+ <menu label="Essentials">
<menu-item label="Overview" href="index.html"/>
<menu-item label="Features" href="features.html"/>
+ <menu-item label="Getting started" href="getting-started.html"/>
<menu-item type="external" id="downloads" label="Download"
href="http://jakarta.apache.org/builds/jakarta-avalon/release/phoenix"/>
- <menu-item label="Getting Started" href="getting-started.html"/>
- <menu-item label="Making compatible components"
href="making-phoenix-compatible-comps.html"/>
- <menu-item label="Installation" href="install.html"/>
- <menu-item label="A Future" href="afuture.html"/>
- <menu-item label="Todo" href="todo.html"/>
- <menu-item label="Changes" href="changes.html"/>
- <menu-item type="external" id="api-docs" label="API Docs"
href="api/index.html"/>
+ <menu-item label="Install" href="install.html"/>
</menu>
- <menu label="Administrators Guide">
- <menu-item label="Overview" href="administrator-guide.html"/>
+ <menu label="Guide">
+ <menu-item label="Architectural Overview"
href="guide-architecture.html"/>
+ <menu-item label="Development Roles" href="guide-roles.html"/>
+ <menu-item label="for Administrators" href="guide-administrator.html"/>
+ <menu-item label="for Deployers" href="guide-deployers.html"/>
+ <menu-item label="for Assemblers" href="guide-assemblers.html"/>
+ <menu-item type="hidden"
href="guide-assemblers-what-is-a-server-application.html"/>
+ <menu-item type="hidden"
href="guide-assemblers-creating-a-server-application.html"/>
+ <menu-item label="for Block Developers"
href="guide-block-developers.html" />
+ <menu-item type="hidden"
href="guide-block-developers-what-is-a-block.html" />
+ <menu-item type="hidden"
href="guide-block-developers-what-is-a-block-listener.html" />
+ <menu-item type="hidden"
href="guide-block-developers-what-is-an-application-listener.html" />
+ <menu-item type="hidden"
href="guide-block-developers-creating-a-block.html" />
+ <menu-item type="hidden"
href="guide-block-developers-making-phoenix-compatible-comps.html"/>
+ <menu-item label="Example configuration"
href="guide-example-configuration.html" />
</menu>
- <menu label="Deployers Guide">
- <menu-item label="Overview" href="deployers-guide.html"/>
+ <menu label="Reference">
+ <menu-item type="external" id="Api Docs" label="API Docs"
href="api/index.html"/>
+ <menu-item label="config.xml Specification"
href="reference-config-xml-specification.html"/>
+ <menu-item label="assembly.xml Specification"
href="reference-assembly-xml-specification.html"/>
+ <menu-item label="environment.xml Specification"
href="reference-environment-xml-specification.html"/>
+ <menu-item label="BlockInfo Specification"
href="reference-blockinfo-specification.html" />
</menu>
- <menu label="Assembler's Guide">
- <menu-item label="Overview" href="assemblers-guide.html"/>
- <menu-item label="What is a Server Application?"
href="what-is-a-server-application.html"/>
- <menu-item label="Creating a Server Application"
href="creating-a-server-application.html"/>
- <menu-item label="config.xml Specification"
href="config-xml-specification.html"/>
- <menu-item label="assembly.xml Specification"
href="assembly-xml-specification.html"/>
- <menu-item label="environment.xml Specification"
href="environment-xml-specification.html"/>
- </menu>
-
- <menu label="Block Developer's Guide">
- <menu-item label="Overview" href="block-developers-guide.html" />
- <menu-item label="What is a Block?" href="what-is-a-block.html" />
- <menu-item label="What is a Block Listener?"
href="what-is-a-block-listener.html" />
- <menu-item label="What is an Application Listener?"
href="what-is-an-application-listener.html" />
- <menu-item label="BlockInfo Specification"
href="blockinfo-specification.html" />
- <menu-item label="Creating a Block" href="creating-a-block.html" />
- </menu>
-
- <menu label="All together">
- <menu-item label="Example configuration"
href="example-configuration.html" />
+ <menu label="For Developers">
+ <menu-item label="Changes" href="for-developers-changes.html"/>
+ <menu-item label="Todo" href="for-developers-todo.html"/>
+ <menu-item type="external" id="coding-standards" label="Coding
standards" href="@AVALON_BASE@/code-standards.html"/>
+ <menu-item label="Project Structure"
href="for-developers-project-structure.html"/>
+ <menu-item type="external" id="cvs" label="CVS"
href="http://jakarta.apache.org/site/cvsindex.html"/>
+ <menu-item type="external" id="mailing-lists" label="Mailing Lists"
href="http://jakarta.apache.org/site/mail.html"/>
+ <menu-item label="A Future" href="for-developers-a-future.html"/>
</menu>
</book>
1.4 +56 -5 jakarta-avalon-phoenix/src/xdocs/features.xml
Index: features.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-phoenix/src/xdocs/features.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- features.xml 2 Apr 2002 18:56:21 -0000 1.3
+++ features.xml 12 May 2002 19:52:49 -0000 1.4
@@ -5,9 +5,9 @@
<document>
<header>
- <title>Phoenix - Features</title>
+ <title>Avalon Phoenix - Features</title>
<authors>
- <person name="Avalon Documentation Team"
email="[email protected]"/>
+ <person name="Leo Simons" email="[EMAIL PROTECTED]"/>
</authors>
</header>
@@ -15,10 +15,61 @@
<s1 title="Introduction">
-<p>
- This document will list the features of Phoenix. It is yet to be
completed ;)
-</p>
+<p>This document is not complete yet...</p>
+</s1>
+
+<s1 title="Extensible architecture">
+ <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>
+</s1>
+
+<s1 title="Flexible environment">
+ <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>
+</s1>
+
+<s1 title="Integrated management">
+ <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>
+</s1>
+
+<s1 title="Ease and speed up application development">
+ <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</li>
+ <li>Resource management</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>
</s1>
</body>
1.4 +42 -42 jakarta-avalon-phoenix/src/xdocs/getting-started.xml
Index: getting-started.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-phoenix/src/xdocs/getting-started.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- getting-started.xml 2 Apr 2002 18:56:21 -0000 1.3
+++ getting-started.xml 12 May 2002 19:52:49 -0000 1.4
@@ -3,7 +3,7 @@
<document>
<header>
- <title>Phoenix - Getting Started</title>
+ <title>Avalon Phoenix - Getting Started</title>
<authors>
<person name="Avalon Documentation Team"
email="[email protected]"/>
<person name="Leo Simons" email="[EMAIL PROTECTED]"/>
@@ -18,14 +18,14 @@
<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="@AVALON_BASE@/framework/index.html">Design</link> document.
+ Avalon Framework (on which Phoenix is based), please refer to the
+ <link href="@AVALON_BASE@/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>
<p>
More detailed instructions will be added to this document in the future.
Feel free
@@ -36,15 +36,15 @@
<s1 title="View Detailed API Documentation">
-<p>
+<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
+ directory of source distribution and run the appropriate build script
for your
platform with the parameter 'javadocs'.
<source><![CDATA[
-
+
> build.[bat|sh] javadocs
-
+
]]></source>
</p>
@@ -53,16 +53,16 @@
<s1 title="Run the HelloWorld example">
<p>
- After you have successfully built Phoenix, you can verify that it
- has compiled correctly by running the HelloWorld demo Service
Application.
+ After you have successfully built Phoenix, you can verify that it
+ has compiled correctly by running the HelloWorld demo Service
Application.
</p>
-<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
+ 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>
+<p>
Then fire up phoenix with the following command:
<source><![CDATA[
@@ -86,34 +86,34 @@
]]></source>
</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>
+ 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
+ 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>
</s1>
<s1 title="The Phoenix Developer Kit - A different example">
<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
+ 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
+ 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:
<ol>
<li>phoenix-demo.sar - the server app in Phoenix form</li>
@@ -123,35 +123,35 @@
</ol>
The Server app in standalone mode after being tested with the client
app(see below):
-
+
<source><![CDATA[
java -jar phoenix-demo-server.jar
PDK Demo listening on port 7654
Ctrl-C to exit
String passed = Hello!!!!!
]]></source>
-
+
The Server app running inside Phoenix and after being tested with the
client app (see below):
-
+
<source><![CDATA[
Phoenix 4.0a4
-Server started on port 1234
+Server started on port 1234
String passed = Hello!!!!!
]]></source>
-
+
The client application being used to poke the server :
-
+
<source><![CDATA[
java -jar phoenix-demo-client.jar localhost 7654 Hello!!!!!
]]></source>
-
+
(Change the port to 1234 from 7654 to poke the in-Phoenix server).
-
-</p>
+
+</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
+ 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>
</s1>
1.7 +44 -60 jakarta-avalon-phoenix/src/xdocs/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-phoenix/src/xdocs/index.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- index.xml 2 Apr 2002 18:56:21 -0000 1.6
+++ index.xml 12 May 2002 19:52:49 -0000 1.7
@@ -4,7 +4,7 @@
<document>
<header>
- <title>Phoenix - Overview</title>
+ <title>Avalon Phoenix - Overview</title>
<authors>
<person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
<person name="Peter Donald" email="[EMAIL PROTECTED]"/>
@@ -18,79 +18,63 @@
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 offer support extra facilities such as central server
management,
- server pools, and other facilities aimed at reducing the time to
market. The API
+ classloading, thread management and security. In the future it will
+ conditionally offer 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 togther server components and
creating a server.
</p>
</s1>
- <s1 title="Multiple Server Application hosting">
+ <s1 title="Documentation is coming">
<p>
- Phoenix hosts one or more server applications at the same time in
the same Virtual machine.
- </p>
- <figure>
- <title>Phoenix layer diagram</title>
- <graphic srccredit="Paul Hammant, 2001"
fileref="images/phoenix-layers.jpg" format="JPEG"/>
- </figure>
- <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.
+ 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>
</s1>
- <s1 title="Packaging of a Server Application">
- <p>
- Phoenix application are distriuted in a single archive.
- </p>
- <s2 title="Packaging in terms of blocks">
- <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>
- <figure>
- <title>Phoenix application in block view</title>
- <graphic srccredit="Paul Hammant, 2001"
fileref="images/phoenix-app-block.jpg" format="JPEG"/>
- </figure>
- </s2>
- <s2 title="Packaging in terms of block jar files">
- <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>
- <title>Phoenix application in block jar view</title>
- <graphic srccredit="Paul Hammant, 2001"
fileref="images/phoenix-app-blockjars.jpg" format="JPEG"/>
- </figure>
- </s2>
- <s2 title="FtpServer as a Phoenix application">
+ <s1 title="Guide to Avalon Phoenix">
<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>
- <figure>
- <title>FtpServer, a real Phoenix application</title>
- <graphic srccredit="Paul Hammant, 2001"
fileref="images/phoenix-app-ftpserver.jpg" format="JPEG"/>
- </figure>
- </s2>
+ 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>
+ <s2 title="Target Audience">
+ <p>
+ This documentation is aimed towards people who:
+ <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>
+ </s2>
+ <s2 title="Contents">
+ <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-administrators.html">Administrator
Guide</link></li>
+ <li><link href="guide-deployers.html">Application Deployer
Guide</link></li>
+ <li><link href="guide-assembler.html">Server Application
Assembler Guide</link></li>
+ <li><link href="guide-block-developers.html">Block Developer
Guide</link></li>
+ <li><link href="guide-example-configuration.html">Example
Configuration.</link></li>
+ </ol>
+ </s2>
+ </s1>
+ <s1 title="Avalon Phoenix Reference Documentation">
<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.
+ Besides the
+ <link href="api/index.html">Javadocs</link>, we have the
+ <link href="guide-architecture.html">Architectural overview</link>
to look at.
</p>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
- $Revision: 1.6 $ $Date: 2002/04/02 18:56:21 $
+ $Revision: 1.7 $ $Date: 2002/05/12 19:52:49 $
</legal>
</footer>
</document>
1.5 +1 -1 jakarta-avalon-phoenix/src/xdocs/install.xml
Index: install.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-phoenix/src/xdocs/install.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- install.xml 18 Apr 2002 20:19:35 -0000 1.4
+++ install.xml 12 May 2002 19:52:49 -0000 1.5
@@ -5,7 +5,7 @@
<document>
<header>
- <title>Phoenix - Installation</title>
+ <title>Avalon Phoenix - Installation</title>
<authors>
<person name="Avalon Documentation Team"
email="[email protected]"/>
</authors>
1.1
jakarta-avalon-phoenix/src/xdocs/for-developers-a-future.xml
Index: for-developers-a-future.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Avalon Phoenix - A future</title>
<authors>
<person name="Paul Hammant" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<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>
</s1>
<s1 title="One step further">
<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>
<title>Sun X1</title>
<graphic srccredit="© Sun Microsystems"
fileref="http://www.sun.com/products-n-solutions/hw/networking/images/prodsplash/x1.jpg";
format="JPEG"/>
</figure>
<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>
</s1>
<s1 title="Is all this possible?">
<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>
</s1>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/xdocs/for-developers-changes.xml
Index: for-developers-changes.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE changes SYSTEM "dtd/changes-v10.dtd">
<changes title="Avalon Phoenix - History of Changes">
<devs>
<person name="Federico Barbieri" email="[EMAIL PROTECTED]" id="FB"/>
<person name="Berin Loritsch" email="[EMAIL PROTECTED]" id="BL"/>
<person name="Peter Donald" email="[EMAIL PROTECTED]" id="PD"/>
<person name="Paul Hammant" email="[EMAIL PROTECTED]" id="PH"/>
<person name="Mircea Toma" email="[EMAIL PROTECTED]" id="MT"/>
</devs>
<release version="4.0a3" date="November 13, 2001">
<action dev="PD" type="change">
Add documentation describing BlockListener.
</action>
<action dev="PD" type="change">
Fixed bug that allowed binary distributions to be built without
copying xerces.jar into correct place.
</action>
</release>
<release version="4.0a2" date="November 12, 2001">
<action dev="PD" type="change">
Update Phoenix to use the new Avalon Framework Logger interface rather
than
directly using LogKits Logger class. This required a backwards
incompatible
change in BlockContext. The getLogger() methods now return the Logger
interface
rather than LogKits Logger class. If a Block implements Loggable then it
will
be passed LogKits Logger, this is required for backwards compatability.
If the
Block implements LogEnabled it will receive the new style Logger.
</action>
<action dev="MT" type="add">
Add support for undeploying and unistalling applications. Add support for
separating
out install phase from deployment phase and persisting information about
application installations.
</action>
<action dev="PD" type="change">
Rework the application deployment format (ie .sar format) to be more in
line
with other specifications. See docs/creating-a-server-application.html in
distribution
for current format description. The old format is deprecated but will
still work.
</action>
<action dev="PH" type="add">
Created the start of a Phoenix Developers Kit (PDK) that will enable
developers to rapidly become accustom to developing Phoenix applications.
</action>
<action dev="PD" type="add">
Started to incorporate the JMX code more fully into Phoenix kernel.
Started
doing this by refactoring the base MBeans and testing using the RIs agent.
</action>
<action dev="PD" type="change">
Separated code that validated assembly of application into separate
classes. The validation is now much stricter and requires that
Blocks conform to established patterns. The validation phase should give
more reasonable explanations for violations. Extra validation checks
include verifying that services offered by a Block are actually
interfaces,
that there is no circular dependencies, that declared Blocks and
BlockListeners
actually implement Block or BlockListener interface, that the names of
Blocks
are valid etc.
</action>
</release>
<release version="4.0a1" date="September 25, 2001">
<action dev="BL" type="change">
Too many things to enumerate here. This is the first public release,
and the code is still considered alpha. In future releases, we will
be much more careful to record the changes to Phoenix.
</action>
</release>
<release version="3.1a2" date="Unreleased">
<action dev="BL" type="add">
Added stylesheet to convert Stylebook markup to DocBook markup.
</action>
<action dev="BL" type="change">
Changed the documentation build process to use Cocoon to build
the site.
</action>
<action dev="PD" type="remove">
Legacy support for nested configuration elements in assembly file
removed.
</action>
<action dev="PD" type="update">
Simplified Loader and made it set ContextClassLoader before executing
Main method. It will also use the System property phoenix.home if set
rather than always trying to dynamically determine home directory.
</action>
<action dev="PD" type="add">
Added SingleAppEmbeddor to launch a kernel to load a single Application.
Patch supplied by "Eung-ju Park" ([EMAIL PROTECTED]). This is useful if
you need to reuse the blocks in other contexts (such as in a Servlet).
</action>
<action dev="PD" type="add">
Made default SystemManager a NoopSystemManager. Patch supplied
by "Eung-ju Park" ([EMAIL PROTECTED]). To re-enable RMI manager a new
command line switch "--remote-manager" was added.
</action>
<action dev="PD" type="update">
Reworked SecurityManager setup. Instead of starting a security
Manager inside the code it has been re-architectured so that the
SecurityManager is set on the command line. This was to avoid a number
of issues related to creating a URLClassLoader in an unprotected context
before setting SecurityManager. ie As AccessControllerContext was null it
is impossible to use ClassLoader.getResource(AsStream)(). This means that
defining phoenix.insecure will no longer disable the SecurityManager. The
replacement method is to set the native OS environment variable
'PHOENIX_SECURE=false'.
</action>
<action dev="PD" type="update">
Separate Parsing of CLI arguements into separate class (CLISetup).
This is to facilitate launching Phoenix as a native daemon using
Tomcats Services API.
</action>
<action dev="PD" type="add">
Started Localizing text strings throughout Phoenix. This is done using
ResourceManager and Resources from Avalon/Excalibur project.
</action>
</release>
</changes>
1.1
jakarta-avalon-phoenix/src/xdocs/for-developers-project-structure.xml
Index: for-developers-project-structure.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Avalon Phoenix - Project Structure</title>
<authors>
<person name="Leo Simons" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<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>
</s1>
<s1 title="Package structure">
<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>
</s1>
<s1 title="CVS Directory structure">
<source>
jakarta-avalon
|
|- console : JMX-based management console
|
|- lib : for third party libraries
|
|- src
| |
| |- compat : deprecated stuff
| |- conf : jar manifest
| |- documentation : cocoon configuration
| |- java : java sources
| |- manifest : jar manifest files
| |- pdk : sources for PDK
| |- proposal : place for ideas to nurture
| |- schema : DTDs for XML files
| |- scratchpad : place for nonsupported, unstable code
| |- 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>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/05/12 19:52:49 $
</legal>
</footer>
</document>
1.1 jakarta-avalon-phoenix/src/xdocs/for-developers-todo.xml
Index: for-developers-todo.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Avalon Phoenix - Todo</title>
<authors>
<person name="Avalon Documentation Team"
email="[email protected]"/>
</authors>
</header>
<body>
<s1 title="Todo">
<p>
This document describes functionality that is either missing or not finished
within Phoenix.
</p>
<p>
Wish List functionality is stuff that we would like to see implemented, but is
not critical for release. This is the area where you can take ownership of a
part of the project and contribute back.
</p>
<p>
Very Important Work to Complete is stuff that we feel is holding up a release
of
Avalon.
</p>
<p>
If you are a new developer to Phoenix or even an existing developer, these are
areas where you can take ownership and help complete. Please do not ask us how
you can help, but rather specific questions about how you think that these
items
should be implemented. It is up to you to take initiative and provide
solutions
to the missing functionality described below. ;-) If your see yourself as more
of a application (rather than infrastructure) writer, then perhaps peruse
Cornerstone's to-do list - it's even more ambitious.
</p>
<p>
Documentation is *always* appreciated in any form. There are two ways to
provide
helpful documentation. The first way is to write up HTML or straight text
documentation and send it to one of the primary authors directly (we are also
willing to give you CVS write access if you wish). The second way is to post
Questions/Answers to the FAQ under the Avalon sections there.
There is a Getting Started document named
"getting-started.html" that could always use additional documentation,
examples
and clarification. You need to take the initiative and just start writing down
your thoughts and concerns and questions and answers and then giving those
back
to us.
</p>
<p>
If you need more detailed help, please join, then send mail to the mailing
list ([email protected]) and ask your specific questions there.
</p>
</s1>
<s1 title="Wish List">
<s2 title="Separate and Antify Validation code">
<p>
Refactor block validation code. Write an Ant taks that uses this
and validates the block jar files and another task that validates the
assembly.xml file.
</p>
</s2>
<s2 title="Log messages">
<p>
Refactor Log messages so that they are structured in a manner more
suitable for administrators rather than developers.
</p>
<p>
update 12/05/02: mostly done.
</p>
</s2>
<s2 title="Generated Configurations">
<p>
Define and implement a smart way to generate Avalon configurations.
Define configuration template containing default configuration,
user configuration file to overwrite or append configurations to
template,
implement code to merge all servers configuration file to a single
Avalon
configuration file.
</p>
</s2>
<s2 title="Time Scheduler changes">
<p>
Rework the DefaultTimeScheduler so that entrys are removed from heap
when
reset. Otherwise it could lead to excessive buildup of invalidated
entries
if many are reset but remain in heap.
</p>
</s2>
<s2 title="Opening some tightly kernel-coupled services">
<p>
Rework kernel so that ConfigurationRepository, Logging and Management
can
be routed through ServerApplications.
</p>
</s2>
<s2 title="Virtual File System / Jars within Jars">
<p>
Implement a simple read-only VFS so that .sar files do not need to be
expanded.
</p>
<p>
update 12/05/02: done.
</p>
</s2>
<s2 title="Thread pooling">
<p>
Rework kernel so that thread boundaries are respected and secure. This
essentially
involves using ThreadPools to execute phases and for management.
</p>
</s2>
<s2 title="JNDI service">
<p>
Determine if we need a naming service. If so provide a simple JNDI
based naming
service possibly built on top of cadastre.
</p>
<p>
update 12/05/02: we've decided not to do so at this time.
</p>
</s2>
<s2 title="Block Management remotely">
<p>
Separate out and specify the way in which different parts of system are
managed.
ie Compare how remote Management of Blocks could occur vs
Deployer/Kernel/Embeddor
management occurs.
</p>
</s2>
<s2 title="Hot deployment">
<p>
A standard system for hot deploying and undeploying. This may require
the building
of FileMonitors that will read a file when it is changed.
</p>
</s2>
<s2 title="Reconfiguration">
<p><strong>This has a few facets:</strong></p>
<p>
A standard reconfiguration system. This may require the building
of FileMonitors that will read a file when it is changed. Any
kind of block or component that extends the Reconfigurable interface
gets sent the new configuration.
</p>
<p>
A mechanism to allow one block to be the master of another's
configuration
programmatically. This would mean that whilst in use, the configuration
could change. It could happen invisibly or as part of human interaction
via some UI. The blocks woyld be granted configuration-update rights in
assembly.xml. Discussed on the list in late Aug, early Sept 2001.
</p>
<p>
Define and implement needed stuff to allow hot and warm reconfiguration
at
runtime.
</p>
</s2>
<s2 title="Proxy Interfaces">
<p>
Currently services are provided via a proxy interface. Rework kernel so
that
the proxy interface can be turned off via a command-line switch.
</p>
</s2>
<s2 title="Management Console">
<p>
Management console/Client interface. CLI version aswell as a GUI
version.
</p>
<p>
update 12/05/02: we have a draft of concept.
</p>
</s2>
<s2 title="Default JNDI Contexts">
<p>
Avalon should provide default JNDI contexts
that Block implementers can extend and use like
Context, EventContext, and DirectoryContext.
</p>
</s2>
<s2 title="Java Messaging Service">
<p>
JMS (Java Messaging Service) for the Connection Manager. It
will provide a standard and flexible connection service and
messaging service. It allows for both point to point messaging
and multicast messaging (subscriber/provider).
</p>
</s2>
<s2 title="Server Pools">
<p>
Support for server pools. Several Phoenix servers should be able
to pool resources and act as one server regardless of VM, or
physical machine they are on.
</p>
</s2>
<s2 title="Block loading remotely">
<p>
Remote loading of Blocks. Phoenix should be able to pull a block
at run time from a remote server, check the signature, and run it
with proper permissions. This would allow for the possibility of
automatically upgrading blocks.
</p>
</s2>
<s2 title="Remote Control">
<p>
Write some code to remotely control Phoenix. (This will most likely be
rolled into JMX support).
</p>
<p>
update 12/05/02: done (through jmx).
</p>
</s2>
<s2 title="Transactions">
<p>
Define and implement some Transaction pattern for the Repository. Maybe
JTA?
</p>
</s2>
</s1>
<s1 title="Ongoing work">
<s2 title="Help needed!">
<p>
We can really use some help here! This is a top priority and all
contributions will be welcomed.
</p>
</s2>
<s2 title="Documentation">
<p>
Write all documentation.
</p>
</s2>
<s2 title="JavaDocs">
<p>
Update JavaDocs for decent developer documentation.
</p>
</s2>
</s1>
<s1 title="Very Important Work to Complete">
<s2 title="Java Management eXtentions">
<p>
JMX (Java Management eXtentions) for central management of
Avalon. If JMX cannot be done due to licensing, we should
make the current beginnings of central management more
robust.
</p>
<p>
update 12/05/02: we're at roughly 80% functionality. We're
using MX4J as our default MBeanServer.
</p>
</s2>
</s1>
</body>
</document>
1.1 jakarta-avalon-phoenix/src/xdocs/guide-administrator.xml
Index: guide-administrator.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Avalon Phoenix - Guide - for Administrators</title>
<authors>
<person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<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>
<s2 title="Target Audience">
<p>
This documentation will describe the care and feeding of the Avalon
Phoenix kernel from the point of view of the administrator.
</p>
</s2>
<s2 title="Guide non-existent, but features are there">
<p>
We currently have no info on this whatsoever. However, this doesn't
mean that Phoenix is not easy to administrate - the contrary is true,
since our tight integration with JMX exposes the entire kernel at
runtime.
</p>
</s2>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/05/12 19:52:49 $
</legal>
</footer>
</document>
1.1 jakarta-avalon-phoenix/src/xdocs/guide-architecture.xml
Index: guide-architecture.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Avalon Phoenix - Guide - Architectural overview</title>
<authors>
<person name="Leo Simons" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
This document briefly describes the Phoenix server architecture.
</p>
</s1>
<s1 title="Multiple Server Application hosting">
<p>
Phoenix hosts one or more server applications at the same time in the
same Virtual machine.
</p>
<figure>
<title>Phoenix layer diagram</title>
<graphic srccredit="Paul Hammant, 2001"
fileref="images/phoenix-layers.jpg" format="JPEG"/>
</figure>
<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>
</s1>
<s1 title="Packaging of a Server Application">
<p>
Phoenix application are distriuted in a single archive.
</p>
<s2 title="Packaging in terms of blocks">
<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>
<figure>
<title>Phoenix application in block view</title>
<graphic srccredit="Paul Hammant, 2001"
fileref="images/phoenix-app-block.jpg" format="JPEG"/>
</figure>
</s2>
<s2 title="Packaging in terms of block jar files">
<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>
<title>Phoenix application in block jar view</title>
<graphic srccredit="Paul Hammant, 2001"
fileref="images/phoenix-app-blockjars.jpg" format="JPEG"/>
</figure>
</s2>
<s2 title="FtpServer as a Phoenix application">
<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>
<figure>
<title>FtpServer, a real Phoenix application</title>
<graphic srccredit="Paul Hammant, 2001"
fileref="images/phoenix-app-ftpserver.jpg" format="JPEG"/>
</figure>
</s2>
<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>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/05/12 19:52:49 $
</legal>
</footer>
</document>
1.1
jakarta-avalon-phoenix/src/xdocs/guide-assemblers-creating-a-server-application.xml
Index: guide-assemblers-creating-a-server-application.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Avalon Phoenix - Guide - Creating a Server Application</title>
<authors>
<person id="PD" name="Peter Donald" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="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>
</s1>
<s1 title="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 Phoenix, contract someone to build the component or download the
Block
from an online repository.
</p>
</s1>
<s1 title="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
<link
href="reference-config-xml-specification.html">specification</link>.
</p>
</s1>
<s1 title="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 <link
href="reference-assembly-xml-specification.html">
specification</link>.
</p>
</s1>
<s1 title="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
<link
href="reference-environment-xml-specification.html">specification</link>.
</p>
</s1>
<s1 title="Create the sar file">
<p>
The sar file format is the standard distribution format of Phoenix
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>
</s1>
<s1 title="Guide Contents">
<ol>
<li><link
href="guide-assemblers-what-is-a-server-application.html">What is a Server
Application?</link></li>
<li>How do I create a Server Application?</li>
<li><link href="reference-config-xml-specification.html">config.xml
specification</link></li>
<li><link href="reference-assembly-xml-specification.html">assembly.xml
specification</link></li>
<li><link
href="reference-environment-xml-specification.html">environment.xml
specification</link></li>
</ol>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/05/12 19:52:49 $
</legal>
</footer>
</document>
1.1
jakarta-avalon-phoenix/src/xdocs/guide-assemblers-what-is-a-server-application.xml
Index: guide-assemblers-what-is-a-server-application.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Avalon Phoenix - Guide - What is a Server Application?</title>
<authors>
<person id="PD" name="Peter Donald" email="[EMAIL PROTECTED]"/>
<person id="BL" name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
In Phoenix, 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>
</s1>
<s1 title="Guide Contents">
<ol>
<li>What is a Server Application?</li>
<li><link
href="guide-assemblers-creating-a-server-application.html">How do I create a
Server Application?</link></li>
<li><link href="reference-config-xml-specification.html">config.xml
specification</link></li>
<li><link href="reference-assembly-xml-specification.html">assembly.xml
specification</link></li>
<li><link
href="reference-environment-xml-specification.html">environment.xml
specification</link></li>
</ol>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/05/12 19:52:49 $
</legal>
</footer>
</document>
1.1 jakarta-avalon-phoenix/src/xdocs/guide-assemblers.xml
Index: guide-assemblers.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Avalon Phoenix - Guide - for Server Assemblers</title>
<authors>
<person name="Avalon Documentation Team"
email="[email protected]"/>
</authors>
</header>
<body>
<s1 title="Who Should Read This Book?">
<p>
The Server Assemblers Guide is written for assemblers who want to
assemble a
Server Application for Phoenix. It is assumed that you are familiar
with
the basic concepts of the Phoenix 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>
</s1>
<s1 title="Organization">
<p>
The information is organized into sections detailing a specifc aspect
of
assembling ServerApplications.
</p>
</s1>
<s1 title="Contents">
<ol>
<li><link
href="guide-assemblers-what-is-a-server-application.html">What is a Server
Application?</link></li>
<li><link
href="guide-assemblers-creating-a-server-application.html">How do I create a
Server Application?</link></li>
<li><link href="reference-config-xml-specification.html">config.xml
specification</link></li>
<li><link href="reference-assembly-xml-specification.html">assembly.xml
specification</link></li>
<li><link
href="reference-environment-xml-specification.html">environment.xml
specification</link></li>
</ol>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/05/12 19:52:49 $
</legal>
</footer>
</document>
1.1
jakarta-avalon-phoenix/src/xdocs/guide-block-developers-creating-a-block.xml
Index: guide-block-developers-creating-a-block.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Avalon Phoenix - Guide - Creating a Block</title>
<authors>
<person id="PD" name="Peter Donald" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
This document will describe the process for creating your first
block. There
are essentially three steps that must be completed before your block
is ready
for assembling.
</p>
<ol>
<li>Write the Block component.</li>
<li>Write the BlockInfo meta-info description file.</li>
<li>Package the component and related resources into a block jar
file.</li>
</ol>
</s1>
<s1 title="Writing the Block component">
<p>
Writing the Block is the main task you will be called to do. It
follows all
the rules of writing a standard Avalon component. Block writers must
also
extend the <code>org.apache.phoenix.Block</code> interface.
</p>
<p>
If a block implements the Composer interface it will be passed an
instance
of <code>org.apache.phoenix.BlockContext</code> which is an extended
version
of <code>org.apache.avalon.Context</code>. Other than this minor
change the
Block's container (the Phoenix Kernel) supports all the Avalon
lifecycle
methods or will in the near future (at the moment suspend/resume is
not yet
supported).
</p>
<p>
The block can implement an instance of
<code>org.apache.phoenix.Service</code>
if it wishes to export a service to external blocks. It is also
possible to
aquire services from other blocks in the <code>compose()</code>
method.
</p>
</s1>
<s1 title="Write the BlockInfo">
<p>
You must create this file to indicate which services this Block
depends upon
and those services which it offers. It is more fully documented in
the
<link href="reference-blockinfo-specification.html">BlockInfo
Specification</link> document.
</p>
</s1>
<s1 title="Create the jar package">
<p>
The final step is packaging up the implementation files, BlockInfos
and other
resources into a jar file. The jar file is a standard jar file with
special manifest
entries. For each Block that is included in the jar, a new manifest
attribute
must be added, namely "Avalon-Block: true". An example
manifest file is
displayed below.
</p>
<source>
Manifest-Version: 1.0
Created-By: Apache Avalon Project
Name: com/biz/cornerstone/blocks/MyBlock.class
Avalon-Block: true
</source>
</s1>
<s1 title="Guide Contents">
<ol>
<li><link href="guide-block-developers-what-is-a-block.html">What is
a block?</link></li>
<li><link
href="guide-block-developers-what-is-a-block-listener.html">What is a block
listener?</link></li>
<li><link
href="guide-block-developers-what-is-an-application-listener.html">What is an
application listener?</link></li>
<li>How do I create a block?</li>
<li><link
href="guide-block-developers-making-phoenix-compatible-comps.html">How do I
make my components phoenix-compatible?</link></li>
<li><link href="reference-blockinfo-specification.html">BlockInfo
specification</link></li>
</ol>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/05/12 19:52:49 $
</legal>
</footer>
</document>
1.1
jakarta-avalon-phoenix/src/xdocs/guide-block-developers-making-phoenix-compatible-comps.xml
Index: guide-block-developers-making-phoenix-compatible-comps.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Avalon Phoenix - Guide - Making components that are Phoenix
compatible</title>
<authors>
<person name="Paul Hammant" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
Quite often reusable components are made elsewhere. Apache has a
number
of places where this activity is going on. While we get it right most
of
the time, some components developer elsewhere are harder to use in
Phoenix
</p>
</s1>
<s1 title="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 Phoenix as block.
</p>
<s2 title="Beanification">
<p>
<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 -
Phoenix 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>
</p>
</s2>
<s2 title="Inversion of Control Pattern">
The IoC pattern is described <link
href="http://jakarta.apache.org/avalon/framework/inversion-of-control.html";>
here</link>. This means for Phoenix avoiding static concepts
including loggers.
</s2>
<s2 title="Sepearation of interface and implementation">
<p>
The separation of interface/impl pattern is described <link
href="http://jakarta.apache.org/avalon/framework/separation-of-interface-and-implementation.html";>here</link>.
For Phoenix is means we can (if done completely) mount the
implementation jar in place where hosted client compoennts (beans, servlets
etc) can use the API, bit 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 impl. Which
pluggable impl is used by Phoenix when it
boots is determined in assembly.xml of course.
</p>
</s2>
<s2 title="Opening up the API">
<p>
Given that you have divided into interface and impl, there are
probably plenty of methods you
can put method 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 Phoenix 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 ...
<ol>
<li>Database createDatabase(String name)</li>
<li>Database cloneDatabase(String name)</li>
</ol>
.. might be useful. Just because you can only see a ServerSocket
interface does not mean that others do.
</p>
</s2>
</s1>
<s1 title="Example compatible comp">
<p>
Below are an interface and implemmentation that are suitably separated,
are beanlike and is in accordance
with the IoC pattern...
<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>
For standalone mode, it might be launched like so:
<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>
When we are trying to run this in phoeinix we might have this wrapper:
<source>
package examplecomp.block;
public class WebServerBlock extends AbstractLoggable implements Block,
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>
This basically shows the impl wrapped and taking its configuration from
the config.xml
that phonix prefers from configuration. The 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 Phoenix block (say an EJB server), it might be
like so:
<source>
package somebeanserver;
public class EJBBlock extends AbstractLoggable implements Block, 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>
</p>
</s1>
<s1 title="Misconceptions">
<p>
The following are worth stating:
<ul>
<li>You do not have to implement any Avalon interfaces to be
reusable (wrap strategy) inside Avalon.</li>
<li>Being Phoenix compatible is just as useful for whole servers as
it is for small components.</li>
<li>Being Phoenix compatible can be for tools that are intended for
client-side as well as server use.</li>
</ul>
</p>
</s1>
<s1 title="Guide Contents">
<ol>
<li><link href="guide-block-developers-what-is-a-block.html">What is
a block?</link></li>
<li><link
href="guide-block-developers-what-is-a-block-listener.html">What is a block
listener?</link></li>
<li><link
href="guide-block-developers-what-is-an-application-listener.html">What is an
application listener?</link></li>
<li><link href="guide-block-developers-creating-a-block.html">How do
I create a block?</link></li>
<li>How do I make my components phoenix-compatible?</li>
<li><link href="reference-blockinfo-specification.html">BlockInfo
specification</link></li>
</ol>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/05/12 19:52:49 $
</legal>
</footer>
</document>
1.1
jakarta-avalon-phoenix/src/xdocs/guide-block-developers-what-is-a-block-listener.xml
Index: guide-block-developers-what-is-a-block-listener.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Avalon Phoenix - Guide - What is a Block Listener?</title>
<authors>
<person id="PD" name="Peter Donald" email="[EMAIL PROTECTED]"/>
<person id="PH" name="Paul Hammant" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
A Phoenix Application consists of Blocks. Blocks can depend on the
services of other Blocks. However there is circumstances in which
relationships between Blocks other than dependency relationships
should exist in an application.
</p>
<p>
For example, you may have a Block that is capable of exporting
other Blocks as SOAP services. The Blocks that wish to be exported
as SOAP services may need to export a service interface that extends
SOAPClient.
</p>
</s1>
<s1 title="What is a Block Listener?">
<p>
A BlockListener is a component that is created before any Blocks are
created in an Application. It receives notification after each Block
is created and setup for Application. The listener also receives
notification when a Block is about to be shutdown.
</p>
<p>
The relationship discussed above (between SOAPServer and SOAPClients)
could be modelled as dependencies but that would mean that each
application
would need to modify the SOAPServer so that it depended on a
particular
number of SOAPClients that was specific to application. A better
approach
to modelling these relationships would be to use a BlockListener to
"wire"
together the SOAPClient services in Blocks to the SOAPServer service.
As
soon as any Block is detected that implements a SOAPClient service it
could
be registered with the SOAPServer.
</p>
</s1>
<s1 title="How to make a block listener">
<p>
Like normal blocks, a block listener can be <em>LogEnabled</em> and
take
configuration via <em>Configurable</em>. The special feature is that
it
must implement <em>BlockListener</em> and the four methods that are a
consequence of that. Those methods illustrate blocks being added and
removed etc and come with a <em>BlockEvent</em> argument. The
following
section in assembly.xml causes instantiation of the block listener:
</p>
<source>
<listener class="pkg.MyBlockListener" name="a-suitable-name" />
</source>
</s1>
<s1 title="Guide Contents">
<ol>
<li><link href="guide-block-developers-what-is-a-block.html">What is
a block?</link></li>
<li>What is a block listener?</li>
<li><link
href="guide-block-developers-what-is-an-application-listener.html">What is an
application listener?</link></li>
<li><link href="guide-block-developers-creating-a-block.html">How do
I create a block?</link></li>
<li><link
href="guide-block-developers-making-phoenix-compatible-comps.html">How do I
make my components phoenix-compatible?</link></li>
<li><link href="reference-blockinfo-specification.html">BlockInfo
specification</link></li>
</ol>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/05/12 19:52:49 $
</legal>
</footer>
</document>
1.1
jakarta-avalon-phoenix/src/xdocs/guide-block-developers-what-is-a-block.xml
Index: guide-block-developers-what-is-a-block.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Avalon Phoenix - Guide - What is a Block?</title>
<authors>
<person id="FB" name="Federico Barbieri" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>In Avalon Phoenix, 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>
</s1>
<s1 title="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>
</s1>
<s1 title="Guide Contents">
<ol>
<li>What is a block?</li>
<li><link
href="guide-block-developers-what-is-a-block-listener.html">What is a block
listener?</link></li>
<li><link
href="guide-block-developers-what-is-an-application-listener.html">What is an
application listener?</link></li>
<li><link href="guide-block-developers-creating-a-block.html">How do
I create a block?</link></li>
<li><link
href="guide-block-developers-making-phoenix-compatible-comps.html">How do I
make my components phoenix-compatible?</link></li>
<li><link href="reference-blockinfo-specification.html">BlockInfo
specification</link></li>
</ol>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/05/12 19:52:49 $
</legal>
</footer>
</document>
1.1
jakarta-avalon-phoenix/src/xdocs/guide-block-developers-what-is-an-application-listener.xml
Index: guide-block-developers-what-is-an-application-listener.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Avalon Phoenix - Guide - What is an Application Listener?</title>
<authors>
<person id="PH" name="Paul Hammant" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
This is very similar to <em>BlockListener</em> in that it is notified
during lifecycle of blocks and application. In Java terms the
<em>ApplicationListener</em> interface extends <em>BlockListener</em>
so it is always informd of both types of events
</p>
</s1>
<s1 title="Events notified">
<p>
ApplicationListener components are created before any Blocks are
created in an Application. They receive notifications before and
after the Applictaion is started and stopped.
</p>
</s1>
<s1 title="How to make a block listener">
<p>
Like normal blocks, an application listener can be <em>LogEnabled</em>
and take configuration via <em>Configurable</em>. The special feature
is that it must implement <em>ApplicationListener</em> and implement
the four methods that are a consequence of that (as well as four from
<em>BlockListener</em>). The following section in assembly.xml causes
instantiation of the application listener. It is exactly the same as
that for <em>BlockListener</em>:
</p>
<source>
<listener class="pkg.MyApplicationListener" name="a-suitable-name"
/>
</source>
</s1>
<s1 title="Guide Contents">
<ol>
<li><link href="guide-block-developers-what-is-a-block.html">What is
a block?</link></li>
<li><link
href="guide-block-developers-what-is-a-block-listener.html">What is a block
listener?</link></li>
<li>What is an application listener?</li>
<li><link href="guide-block-developers-creating-a-block.html">How do
I create a block?</link></li>
<li><link
href="guide-block-developers-making-phoenix-compatible-comps.html">How do I
make my components phoenix-compatible?</link></li>
<li><link href="reference-blockinfo-specification.html">BlockInfo
specification</link></li>
</ol>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/05/12 19:52:49 $
</legal>
</footer>
</document>
1.1
jakarta-avalon-phoenix/src/xdocs/guide-block-developers.xml
Index: guide-block-developers.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Avalon Phoenix - Guide - for Block Developers</title>
<authors>
<person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
</authors>
<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 Phoenix micro-kernel.
</abstract>
</header>
<body>
<s1 title="Who Should Read This Book?">
<p>The BDG is written for developers who want to create
blocks for Phoenix. 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 Phoenix.</p>
<p>While this book concentrates on server fundamentals, it
should not
be construed as a “dummy's” book. 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 (any suggestions?).</p>
</s1>
<s1 title="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>
</s1>
<s1 title="Contents">
<ol>
<li><link href="guide-block-developers-what-is-a-block.html">What is
a block?</link></li>
<li><link
href="guide-block-developers-what-is-a-block-listener.html">What is a block
listener?</link></li>
<li><link
href="guide-block-developers-what-is-an-application-listener.html">What is an
application listener?</link></li>
<li><link href="guide-block-developers-creating-a-block.html">How do
I create a block?</link></li>
<li><link
href="guide-block-developers-making-phoenix-compatible-comps.html">How do I
make my components phoenix-compatible?</link></li>
<li><link href="reference-blockinfo-specification.html">BlockInfo
specification</link></li>
</ol>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/05/12 19:52:50 $
</legal>
</footer>
</document>
1.1 jakarta-avalon-phoenix/src/xdocs/guide-deployers.xml
Index: guide-deployers.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Avalon Phoenix - Guide - for Deployers</title>
<authors>
<person name="Peter Donald" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<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>
<s2 title="Target Audience">
<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>
</s2>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/05/12 19:52:50 $
</legal>
</footer>
</document>
1.1
jakarta-avalon-phoenix/src/xdocs/guide-example-configuration.xml
Index: guide-example-configuration.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Avalon Phoenix - Guide - Example Configuration</title>
<authors>
<person name="Stephen McConnell" email="[EMAIL PROTECTED]"/>
<person name="Gerhard Froehlich" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<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
<a href="http://www.osm.net";>OSM</a></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>
</s1>
<s1 title="The example">
<p>First we start with a manifest file in a jar the contains
a block. The manifest contains the declaration of the path
to the block implementation. This path is also used to
resolve the .xinfo file. In this case the <code>.xinfo</code>
description will be located under
<code>org/apache/acme/hub/gateway/pki/PKIProcessServer.xinfo</code></p>
<source><![CDATA[
Manifest-Version: 1.0
Created-By: ACME Corporation
Name: org/apache/acme/hub/gateway/pki/PKIProcessServer.class
Avalon-Block: true
]]>
</source>
<p>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><![CDATA[
<?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"
version="1.0" />
</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"
version="1.0"/>
</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" version="1.0"/>
</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" version="1.0"/>
</dependency>
<!-- etc. -->
<dependency>
<role>DOMAIN</role>
<service name="org.apache.acme.hub.gateway.DomainService"
version="1.0"/>
</dependency>
<dependency>
<role>RANDOM</role>
<service name="org.apache.acme.hub.gateway.RandomService"
version="1.0"/>
</dependency>
<dependency>
<role>CLOCK</role>
<service name="org.apache.acme.service.time.TimeService"
version="1.0"/>
</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>
The name attribute also serves a the key to lookup a configuration
element in
the application configuration.xml file.
<source><![CDATA[
<?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>
<s1/>
<s1 title="Why this seperation?"/>
<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>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/05/12 19:52:50 $
</legal>
</footer>
</document>
1.1 jakarta-avalon-phoenix/src/xdocs/guide-roles.xml
Index: guide-roles.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Avalon Phoenix - Reference - Development Roles</title>
<authors>
<person name="Leo Simons" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<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>
</s1>
<s1 title="The Administrator">
<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>
</s1>
<s1 title="The Deployer">
<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-deployer.html">Deployer's Guide</link></p>
</s1>
<s1 title="The Assembler">
<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="guide-assemblers.html">Assembler Guide</link></p>
</s1>
<s1 title="The Block Developer">
<p>The block developer creates reusable components (called blocks) that
can be
wired together to form a server applications.</p>
<p><link href="guide-block-developers.html">Block Developers
Guide</link></p>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/05/12 19:52:50 $
</legal>
</footer>
</document>
1.1
jakarta-avalon-phoenix/src/xdocs/reference-assembly-xml-specification.xml
Index: reference-assembly-xml-specification.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Avalon Phoenix - Reference - Specification of assembly.xml </title>
<authors>
<person id="PD" name="Peter Donald" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
The purpose of the <code>assembly.xml</code> file is to define how
the Server
Application is assembled from it's component Blocks. This requires
naming each
block, specifying the implementation class for each block and wiring
together
blocks. The wiring is done via provides elements. Each provide
element maps a
block instance to a role of a dependency specified in the BlockInfo
file. See
below for a sample assembly.xml file.
</p>
<p>
The <code>assembly.xml</code> can also specify
<code>BlockListener</code>
objects that will be created for application. The listeners need a
name and
a classname.
</p>
<p>
In previous versions of Phoenix, configuration data was also stored
in the
assembly file. This is no longer the case (It is now stored in
config.xml).
</p>
</s1>
<s1 title="Sample assembly.xml file">
<source><![CDATA[
<?xml version="1.0"?>
<assembly>
<block-listener name="myListener"
class="com.biz.cornerstone.listeners.MyListener">
</block-listener>
<block name="myAuthorizer"
class="com.biz.cornerstone.blocks.MyAuthorizer">
</block>
<block name="myBlock"
class="com.biz.cornerstone.blocks.MyBlock">
<provide name="myAuthorizer"
role="com.biz.cornerstone.services.Authorizer"/>
</block>
</assembly>]]>
</source>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/05/12 19:52:50 $
</legal>
</footer>
</document>
1.1
jakarta-avalon-phoenix/src/xdocs/reference-blockinfo-specification.xml
Index: reference-blockinfo-specification.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Avalon Phoenix - Reference - The BlockInfo Specification</title>
<version>3.0</version>
<authors>
<person id="PD" name="Peter Donald" email="[EMAIL PROTECTED]"/>
</authors>
<abstract>
Specifies the format of BlockInfo files and the reasons for particular
aspects.
</abstract>
</header>
<body>
<s1 title="Block Metadata">
<p>
The meta-data about each block is stored in a BlockInfo file. The info
includes details on what version the block is, what
<code>Service</code>s
it depends upon and which <code>Service</code>s it can offer to other
Blocks.
In the future the info will also store such data as the schema for
configuring
the block.
</p>
<p>
The BlockInfo file has the same name as the Block except with the
extention
<code>.xinfo</code>. Thus if you were looking up the meta info for a
block named
<code>com.biz.cornerstone.blocks.MyBlock</code> you would look up the
resource
<code>com/biz/cornerstone/blocks/MyBlock.xinfo</code> in the same
block jar file that
the block was packaged in. The BlockInfo file is a simple XML format.
An
example of such a file follows.
</p>
<source>
<![CDATA[
<?xml version="1.0"?>
<blockinfo>
<block>
<version>1.2.3</version>
</block>
<services>
<service name="com.biz.cornerstone.services.MyService"
version="2.1.3" />
</services>
<dependencies>
<dependency>
<role>com.biz.cornerstone.services.Authorizer</role>
<service name="com.biz.cornerstone.service.Authorizer"
version="1.0"/>
</dependency>
<dependency>
<!-- note that role is not specified and defaults
to name of service -->
<service name="com.biz.cornerstone.service.RoleMapper"
version="1.0"/>
</dependency>
</dependencies>
</blockinfo>
]]>
</source>
<p>
You will notice that the information in the BlockInfo file is
separated into
three main sections; <code>block</code>, <code>services</code> and
<code>dependencies</code>.
</p>
<s2 title="BlockInfo 'block' Section">
<p>The block section specifies the version of class. In the future
this
section will also specify the configuration schema if the block is
<code>Configurable</code>.</p>
</s2>
<s2 title="BlockInfo 'services' Section">
<p>The services section documents the services that this block can
offer other
Blocks. The service instances indicate an interface and a version.
The interface
MUST extend <code>org.apache.phoenix.Service</code>. This section is
optional
and a Block can choose to not offer any services.</p>
</s2>
<s2 title="BlockInfo 'dependencies' Section">
<p>The services section documents the services that this block
requires to operate.
Required services are placed in the Blocks ComponentManager under the
name
specified by the <code>role</code> element of dependency. As is
documented in the
<link
href="@FRAMEWORK_BASE@/guide-cop-in-avalon.html">components</link> section, the
concept of Role is more than just a behavioural contract. A
<code>Service</code> is
a behavioural contract and thus the necessity to support the role
element. In most
cases however the role element and the name attribute of the service
will be
identical. In these cases it is sufficient to just specify service
element and role
will default to name of service.</p>
</s2>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/05/12 19:52:50 $
</legal>
</footer>
</document>
1.1
jakarta-avalon-phoenix/src/xdocs/reference-config-xml-specification.xml
Index: reference-config-xml-specification.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Avalon Phoenix - Reference - Specification of config.xml </title>
<authors>
<person id="PD" name="Peter Donald" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
The purpose of the <code>config.xml</code> file is to provide
configuration data
to each of the blocks that require configuration data. The format of
the
configuration data is block-specific, thus refer to documentation of
Block
for relevant details. Each element below the root element has a name
coresponding
to the name of a block specified in assembly.xml file. The contents
of this
element is the configuration data for the block.
</p>
</s1>
<s1 title="Sample config.xml file">
<source><![CDATA[
<?xml version="1.0"?>
<config>
<myAuthorizer>
<!-- ...configuration data here... -->
</myAuthorizer>
<myBlock>
<param1>param1-value</param1>
<an-integer>2</an-integer>
...
</myBlock>
</config>]]>
</source>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/05/12 19:52:50 $
</legal>
</footer>
</document>
1.1
jakarta-avalon-phoenix/src/xdocs/reference-environment-xml-specification.xml
Index: reference-environment-xml-specification.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Avalon Phoenix - Reference - Specification of
environment.xml</title>
<authors>
<person id="PD" name="Peter Donald" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
The purpose of the <code>environment.xml</code> file is to configure
environmental
or Server Application wide settings. Currently this means being able
to set the
security policy and configure logging settings. A sample
<code>environment.xml</code>
follows. Previously thread pool settings were also configured in this
section but this has been deprecated. Note that previously the
information stored in
<code>environment.xml</code> was stored in a file named
<code>server.xml</code>.
</p>
</s1>
<s1 title="Sample environment.xml file">
<source><![CDATA[
<?xml version="1.0"?>
<environment>
<logs>
<category name="" target="default" priority="DEBUG" />
<category name="myAuthorizer" target="myAuthorizer-target"
priority="DEBUG" />
<log-target name="default"
location="/logs/default.log" />
<log-target name="myAuthorizer-target"
location="/logs/authorizer.log" />
</logs>
<policy>
<keystore name="foo-keystore"
location="sar:/conf/keystore"
type="JKS" />
<grant code-base="file:${app.home}${/}some-dir${/}*"
key-store="foo-keystore" >
<permission class="java.io.FilePermission"
target="${/}tmp${/}*"
action="read,write" />
</grant>
<grant signed-by="Bob"
code-base="file:${app.home}${/}SAR-INF${/}lib${/}*"
key-store="foo-keystore" >
<permission class="java.io.FilePermission"
target="${/}tmp${/}*"
action="read,write" />
</grant>
</policy>
</environment>]]>
</source>
<p>
The format of the policy section should be largely self evident if
the assembler
has experience with standard policy files. It should be noted that if
no
policy section is given then the Server Application runs at full
permissions.
The evaluation of properties occurs in a similar manner to standard
policy file property expansion. There are a number of extra
properties that
will be evaluated. These include; <code>app.home</code> and
<code>app.name</code>.
</p>
<p>
One special thing to not is that the user can use URLs of the form,
"sar:/SAR-INF/lib/*". This will apply the permissions to the jars
contained in the .SAR file. Note that these urls must start with
"sar:/" and must use the "/" character as file separator, regardless
of current operating system.
</p>
<p>
The logs section can currently have two types of elements;
<em>log-target</em>s
which represent destinations for logging and <em>category</em>s.
There must be a
log-target with the name "default". Categories are hierarchial in
nature, have a
priority and are associated with one or more log-targets. See the
logging
documentation for a further description of this section.
</p>
<p>
There is another type of log configuration. It is more configurable.
Specify version attribute with logs elements. See javadoc of
org.apache.avalon.excalibur.logger package for detailed description.
Below is example configuration.
<source><![CDATA[
<logger version="1.1">
<factories>
<factory type="file"
class="org.apache.avalon.excalibur.logger.factory.FileTargetFactory"/>
</factories>
<categories>
<category name="" log-level="INFO">
<log-target id-ref="default"/>
</category>
</categories>
<targets>
<file id="default">
<filename>${app.home}/logs/default-</filename>
<append>true</append>
<rotation type="unique" pattern="yyyyMMdd" suffix=".log">
<date>yyyyMMdd</date>
</rotation>
</file>
</targets>
</logger>
]]></source>
</p>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/05/12 19:52:50 $
</legal>
</footer>
</document>
--
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}