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="[EMAIL PROTECTED]"/></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]>
