nicolaken 2002/11/18 06:18:50
Added: src/documentation/content/assemblers
assembly-xml-specification.xml book.xml
config-xml-specification.xml
creating-a-server-application.xml
environment-xml-specification.xml index.xml
what-is-a-server-application.xml
Log:
First step of migration of documentation to Forrest.
New docs dir:
jakarta-avalon-phoenix/src/documentation
New content dir:
jakarta-avalon-phoenix/src/documentation/content
New resources and images dir:
jakarta-avalon-phoenix/src/documentation/resources
To build the documentation download Forrest from CVS
http://xml.apache.org/forrest/your-project.html#N10022
install it as described here
http://xml.apache.org/forrest/your-project.html#N10036
cd in the jakarta-avalon-phoenix dir and run "forrest"
To see the site real-time from a local embedded webserver run "forrest run"
and point the browser to http://localhost:8888/
The sources to change are in ./build/webapp, you will need to synch them with
the actual docs manually.
Or run the Phoenix build.xml with target "site".
Revision Changes Path
1.1
jakarta-avalon-phoenix/src/documentation/content/assemblers/assembly-xml-specification.xml
Index: assembly-xml-specification.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Specification of assembly.xml </title>
<authors><person name="Peter Donald" email="peter at
apache.org"/></authors></header>
<body>
<section><title>Introduction</title>
<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>ApplicationListener</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>
</section>
<section><title>Sample assembly.xml file</title>
<source>
<?xml version="1.0"?>
<assembly>
<listener name="myListener"
class="com.biz.cornerstone.listeners.MyListener">
</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>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/assemblers/book.xml
Index: book.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN"
"book-cocoon-v10.dtd">
<book title="Avalon Phoenix" copyright="Avalon Phoenix" software="Avalon
Phoenix">
<menu label="Essentials">
<menu-item href="../index.html" label="Overview"/>
<menu-item href="../features.html" label="Features"/>
<menu-item href="../getting-started.html" label="Getting started"/>
<menu-item href="../http://jakarta.apache.org/builds/jakarta-avalon-phoenix";
label="Download"/>
<menu-item href="../install.html" label="Install"/>
</menu>
<menu label="Guide">
<menu-item href="../guide-architecture.html" label="Architectural Overview"/>
<menu-item href="../guide-roles.html" label="Development Roles"/>
<menu-item href="../guide-administrator.html" label="for Administrators"/>
<menu-item href="../guide-deployers.html" label="for Deployers"/>
<menu-item href="../assemblers/index.html" label="for Assemblers"/>
<menu-item href="../bdg/index.html" label="for Block Developers"/>
<menu-item href="../mx/index.html" label="Management Guide"/>
<menu-item href="../guide-example-configuration.html" label="Example
configuration"/>
</menu>
<menu label="Reference">
<menu-item href="../api/index.html" label="API Docs"/>
<menu-item href="../assemblers/config-xml-specification.html"
label="config.xml Specification"/>
<menu-item href="../assemblers/assembly-xml-specification.html"
label="assembly.xml Specification"/>
<menu-item href="../assemblers/environment-xml-specification.html"
label="environment.xml Specification"/>
<menu-item href="../bdg/blockinfo-specification.html" label="BlockInfo
Specification"/>
</menu>
<menu label="For Developers">
<menu-item href="../changes.html" label="Changes"/>
<menu-item href="../http://jakarta.apache.org/avalon/code-standards.html";
label="Coding standards"/>
<menu-item href="../for-developers-project-structure.html" label="Project
Structure"/>
<menu-item href="../http://jakarta.apache.org/site/cvsindex.html"; label="CVS
Repositories"/>
<menu-item href="../http://jakarta.apache.org/site/mail.html"; label="Mailing
Lists"/>
<menu-item
href="../http://nagoya.apache.org/bugzilla/buglist.cgi?bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=RESOLVED&product=Avalon&component=Phoenix";
label="TODO"/>
<menu-item
href="../http://nagoya.apache.org/bugzilla/enter_bug.cgi?product=Avalon&component=Phoenix";
label="Bug Database"/>
<menu-item
href="../http://nagoya.apache.org/bugzilla/enter_bug.cgi?product=Avalon&component=Phoenix&bug_severity=Enhancement";
label="Enhancement Requests"/>
<menu-item href="../for-developers-alternate-kernel.html" label="Alternate
Kernels"/>
</menu>
</book>
1.1
jakarta-avalon-phoenix/src/documentation/content/assemblers/config-xml-specification.xml
Index: config-xml-specification.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Specification of config.xml </title>
<authors><person name="Peter Donald" email="peter at
apache.org"/></authors></header>
<body>
<section><title>Introduction</title>
<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>
</section>
<section><title>Sample config.xml file</title>
<source>
<?xml version="1.0"?>
<config>
<myAuthorizer>
<!-- ...configuration data here... -->
</myAuthorizer>
<myBlock>
<param1>param1-value</param1>
<an-integer>2</an-integer>
...
</myBlock>
</config>
</source>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/assemblers/creating-a-server-application.xml
Index: creating-a-server-application.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Guide - Creating a Server Application</title>
<authors><person name="Peter Donald" email="peter at
apache.org"/></authors></header>
<body>
<section><title>Introduction</title>
<p>
This document will describe the process for assembling your first
Server
Application. There is a number of steps in creating a Server
Application.
These are;
</p>
<ol>
<li>Select the blocks you wish to assemble.</li>
<li>Write the config.xml file.</li>
<li>Write the assembly.xml file.</li>
<li>Write the environment.xml file.</li>
<li>Package the component and related resources into a sar file.</li>
</ol>
</section>
<section><title>Select the Blocks to Assemble</title>
<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>
</section>
<section><title>Write the config.xml file</title>
<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="config-xml-specification.html">specification</link>.
</p>
</section>
<section><title>Write the assembly.xml file</title>
<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="assembly-xml-specification.html">
specification</link>.
</p>
</section>
<section><title>Write the environment.xml file</title>
<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="environment-xml-specification.html">specification</link>.
</p>
</section>
<section><title>Create the sar file</title>
<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>
</section>
<section><title>Guide Contents</title>
<ol>
<li><link href="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="config-xml-specification.html">config.xml
specification</link></li>
<li><link href="assembly-xml-specification.html">assembly.xml
specification</link></li>
<li><link href="environment-xml-specification.html">environment.xml
specification</link></li>
</ol>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/assemblers/environment-xml-specification.xml
Index: environment-xml-specification.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Specification of environment.xml</title>
<authors><person name="Peter Donald" email="peter at
apache.org"/></authors></header>
<body>
<section><title>Introduction</title>
<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>
</section>
<section><title>Sample environment.xml file</title>
<source>
<?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="sar:/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.
</p>
<source>
<?xml version="1.0"?>
<environment>
<logs 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>
</logs>
</environment>
</source>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/assemblers/index.xml
Index: index.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Guide - for Server Assemblers</title>
<authors><person name="Avalon Documentation Team"
email="avalon-dev@jakarta.apache.org"/></authors></header>
<body>
<section><title>Who Should Read This Book?</title>
<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>
</section>
<section><title>Organization</title>
<p>
The information is organized into sections detailing a specifc
aspect of
assembling ServerApplications.
</p>
</section>
<section><title>Contents</title>
<ol>
<li>
<link href="what-is-a-server-application.html">What is a
Server Application?</link>
</li>
<li>
<link href="creating-a-server-application.html">How do I
create a Server Application?</link>
</li>
<li>
<link href="config-xml-specification.html">config.xml
specification</link>
</li>
<li>
<link href="assembly-xml-specification.html">assembly.xml
specification</link>
</li>
<li>
<link
href="environment-xml-specification.html">environment.xml specification</link>
</li>
</ol>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/assemblers/what-is-a-server-application.xml
Index: what-is-a-server-application.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Guide - What is a Server Application?</title>
<authors><person name="Peter Donald" email="peter at apache.org"/><person
name="Berin Loritsch" email="[EMAIL PROTECTED]"/></authors></header>
<body>
<section><title>Introduction</title>
<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>
</section>
<section><title>Guide Contents</title>
<ol>
<li>What is a Server Application?</li>
<li><link href="creating-a-server-application.html">How do I create a
Server Application?</link></li>
<li><link href="config-xml-specification.html">config.xml
specification</link></li>
<li><link href="assembly-xml-specification.html">assembly.xml
specification</link></li>
<li><link href="environment-xml-specification.html">environment.xml
specification</link></li>
</ol>
</section>
</body>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
