nicolaken 2002/11/18 06:19:02
Added: src/documentation/content/bdg blockinfo-specification.xml
book.xml creating-a-block.xml doclet-tags.xml
index.xml making-phoenix-compatible-comps.xml
what-is-a-block-listener.xml what-is-a-block.xml
what-is-an-application-listener.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/bdg/blockinfo-specification.xml
Index: blockinfo-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>The BlockInfo Specification</title>
<authors><person name="Peter Donald" email="peter at
apache.org"/></authors></header>
<body>
<section><title>Block Metadata</title>
<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>
<?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.2"/>
</dependency>
<dependency>
<!-- note that role is not specified and defaults
to name of service. The service version is not
specified and it defaults to "1.0" -->
<service name="com.biz.cornerstone.service.RoleMapper"/>
</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>
<section><title>BlockInfo 'block' Section</title>
<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>
</section>
<section><title>BlockInfo 'services' Section</title>
<p>The services section documents the services that this block can
offer other
Blocks. The service instances indicate an interface and optionally a
version
(defaults to version 1.0 if not specified). This section is optional
and a Block
can choose to not offer any services.</p>
</section>
<section><title>BlockInfo 'dependencies' Section</title>
<p>The services section documents the services that this block
requires to operate.
Required services are placed in the Blocks ServiceManager under the
name
specified by the <code>role</code> element of dependency. As is
documented in the
<link
href="http://jakarta.apache.org/avalon/framework/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>
</section>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/bdg/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/bdg/creating-a-block.xml
Index: creating-a-block.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 Block</title>
<authors><person name="Phoenix Documentation Team"
email="avalon-phoenix-dev@jakarta.apache.org"/></authors></header>
<body>
<section><title>Introduction</title>
<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>
</section>
<section><title>Writing the Block component</title>
<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. If a block
implements the
Contextualizable interface it will be passed an instance of
<code>org.apache.avalon.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 interface if it wishes to export a service
to external blocks. It is
also possible to aquire services from other blocks in the
<code>service()</code> method.
</p>
</section>
<section><title>Write the BlockInfo</title>
<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="blockinfo-specification.html">BlockInfo
Specification</link> document.
</p>
</section>
<section><title>Create the jar package</title>
<p>
The final step is packaging up the implementation files, BlockInfos
and other
resources into a jar file.
</p>
</section>
<section><title>Guide Contents</title>
<ol>
<li><link href="what-is-a-block.html">What is a block?</link></li>
<li><link href="what-is-a-block-listener.html">What is a block
listener?</link></li>
<li><link href="what-is-an-application-listener.html">What is an
application listener?</link></li>
<li>How do I create a block?</li>
<li><link href="making-phoenix-compatible-comps.html">How do I make
my components phoenix-compatible?</link></li>
<li><link href="blockinfo-specification.html">BlockInfo
specification</link></li>
</ol>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/bdg/doclet-tags.xml
Index: doclet-tags.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Using Doclet Tags to Generate .xinfo files</title>
<authors><person name="Huw Roberts" email="[EMAIL
PROTECTED]"/></authors></header>
<body>
<section><title>Introduction</title>
<p>
Each block requires a corresponding .xinfo file that is read by the
container at startup. As the developer, you have the option of using
custom java doc tags to generate the .xinfo file. This has a number
of
advantages over generating the file by hand:
</p>
<ul>
<li>
its a lot faster than writing the xinfo file by hand
</li>
<li>
its harder to make mistakes, since much of the data required for
the
xinfo file is parsed out of the source code
</li>
</ul>
<p>
Using this feature requires that you markup the source code with the
appropriate tags and then have the build script include the
<code>MetaGenerateTask</code> task. Both these steps are described
below.
</p>
</section>
<section><title>The Tags</title>
<p>
The following tags are defined:
</p>
<section><title>phoenix:block</title>
<table>
<tr>
<td>Scope</td>
<td>
Applies to any class that is also a block.
</td>
</tr>
<tr>
<td>Purpose</td>
<td>
Marks the class as block and tells the MetaGenerateTask to
generate
an xinfo file for it.
</td>
</tr>
<tr>
<td>Parameters</td>
<td>
None.
</td>
</tr>
<tr>
<td>Notes</td>
<td>
</td>
</tr>
</table>
<p>
Example:
</p>
<source>
/**
* Ftp server starting point. Avalon framework will load this
* from the jar file. This is also the starting point of remote
* admin.
*
* @phoenix:block
* @phoenix:service
name="org.apache.avalon.ftpserver.interfaces.FtpServerInterface"
*
*/
</source>
</section>
<section><title>phoenix:service</title>
<table>
<tr>
<td>Scope</td>
<td>
Applies to classes that are also blocks and export services..
</td>
</tr>
<tr>
<td>Purpose</td>
<td>
Identifies a service that is implemented by the block. A class
can implement more than one service, in which case there will be
multiple phoenix:service tags.
</td>
</tr>
<tr>
<td>Parameters</td>
<td>
Attribute "name" that is the full class name
of the interface that defines the service.
</td>
</tr>
<tr>
<td>Notes</td>
<td>
version tag should also be supported?.
The block must implement the interface for service it declares.
</td>
</tr>
</table>
<p>
Example: see above
</p>
</section>
<section><title>phoenix:mx</title>
<table>
<tr>
<td>Scope</td>
<td>
Classes that are also blocks.
</td>
</tr>
<tr>
<td>Purpose</td>
<td>
Indicates the full name of an interface that defines management
methods for this block.
</td>
</tr>
<tr>
<td>Parameters</td>
<td>
Attribute "name" that is the full class name
of the interface that defines the management methods.
</td>
</tr>
<tr>
<td>Notes</td>
<td>
</td>
</tr>
</table>
<p>
Example:
</p>
<source>
/**
* @phoenix:block
* @phoenix:mx
name="org.apache.avalon.apps.demos.helloworldserver.HelloWorldServerMBean"
*/
</source>
</section>
<section><title>phoenix:dependency</title>
<table>
<tr>
<td>Scope</td>
<td>
Applies to the service() method of the block.
</td>
</tr>
<tr>
<td>Purpose</td>
<td>
Identifies a dependency of this block on an another service.
</td>
</tr>
<tr>
<td>Parameters</td>
<td>
Attribute "name" that is the name of the required service.
</td>
</tr>
<tr>
<td>Notes</td>
<td>
Can also specify a required version number? Optional
dependencies?
</td>
</tr>
</table>
<p>
Example:
</p>
<source>
/*
* @phoenix:dependency
name="org.apache.avalon.cornerstone.services.sockets.SocketManager"
* @phoenix:dependency
name="org.apache.avalon.cornerstone.services.connection.ConnectionManager"
* @phoenix:dependency
name="org.apache.avalon.ftpserver.usermanager.UserManagerInterface"
* @phoenix:dependency
name="org.apache.avalon.ftpserver.ip.IpRestrictorInterface"
*/
public void service(ServiceManager serviceManager) throws
ServiceException {
</source>
</section>
</section>
<section><title>Build Instructions</title>
<p>
To have xinfo files generated as part as your ant build
script, include the MetaGenerateTask like this:
</p>
<source>
<!-- Make .xinfo, .mxinfo and manifest automatically for blocks -->
<target name="metagenerate">
<taskdef name="generatemeta"
classname="org.apache.avalon.phoenix.tools.metagenerate.MetaGenerateTask">
<classpath refid="project.class.path" />
</taskdef>
<generatemeta dest="${build.metagenerate}">
<fileset dir="${java.dir}">
<include name="**/*.java"/>
</fileset>
</generatemeta>
</target>
</source>
<p>
Where build.metagenerate is where the .xinfo files should be placed,
and java.dir
is the location of the source files. Typically the
build.metagenerate directory
is an intermediate build directory. Output from this task are then
copied
to a release image directory and jar'ed as a subsequent step.
</p>
<p>
The qdox jar and phoenix-client.jar need to be in the
project.class.path.
</p>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/bdg/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 Block Developers</title>
<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>
<authors><person name="Berin Loritsch" email="[EMAIL
PROTECTED]"/></authors></header>
<body>
<section><title>Who Should Read This Book?</title>
<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>
</section>
<section><title>Organization</title>
<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>
</section>
<section><title>Contents</title>
<ol>
<li><link href="what-is-a-block.html">What is a block?</link></li>
<li><link href="what-is-a-block-listener.html">What is a block
listener?</link></li>
<li><link href="what-is-an-application-listener.html">What is an
application listener?</link></li>
<li><link href="creating-a-block.html">How do I create a
block?</link></li>
<li><link href="making-phoenix-compatible-comps.html">How do I make
my components phoenix-compatible?</link></li>
<li><link href="blockinfo-specification.html">BlockInfo
specification</link></li>
<li><link href="doclet-tags.html">Using doclet tags to generate
.xinfo files</link></li>
</ol>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/bdg/making-phoenix-compatible-comps.xml
Index: making-phoenix-compatible-comps.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 - Making components that are Phoenix compatible</title>
<authors><person name="Paul Hammant" email="[EMAIL
PROTECTED]"/></authors></header>
<body>
<section><title>Introduction</title>
<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>
</section>
<section><title>Things to remember</title>
<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>
<section><title>Beanification</title>
<p>
</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>
</p>
</section>
<section><title>Inversion of Control Pattern</title>
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.
</section>
<section><title>Sepearation of interface and implementation</title>
<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>
</section>
<section><title>Opening up the API</title>
<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 ...
</p><ol>
<li>Database createDatabase(String name)</li>
<li>Database cloneDatabase(String name)</li>
</ol><p>
.. might be useful. Just because you can only see a ServerSocket
interface does not mean that others do.
</p>
</section>
</section>
<section><title>Example compatible comp</title>
<p>
Below are an interface and implemmentation that are suitably separated,
are beanlike and is in accordance
with the IoC pattern...</p>
<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>
<p>For standalone mode, it might be launched like so:</p>
<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>
<p>When we are trying to run this in phoeinix we might have this
wrapper:</p>
<source>
package examplecomp.block;
public class WebServerBlock
extends AbstractLoggable
implements 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>
<p>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:</p>
<source>
package somebeanserver;
public class EJBBlock
extends AbstractLoggable
implements 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>
</section>
<section><title>Misconceptions</title>
<p>
The following are worth stating:
</p><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>
</p>
</section>
<section><title>Guide Contents</title>
<ol>
<li><link href="what-is-a-block.html">What is a block?</link></li>
<li><link href="what-is-a-block-listener.html">What is a block
listener?</link></li>
<li><link href="what-is-an-application-listener.html">What is an
application listener?</link></li>
<li><link href="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="blockinfo-specification.html">BlockInfo
specification</link></li>
</ol>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/bdg/what-is-a-block-listener.xml
Index: what-is-a-block-listener.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 Block Listener?</title>
<authors><person name="Phoenix Documentation Team"
email="avalon-phoenix-dev@jakarta.apache.org"/></authors></header>
<body>
<section><title>Introduction</title>
<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>
</section>
<section><title>What is a Block Listener?</title>
<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>
</section>
<section><title>How to make a block listener</title>
<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>
</section>
<section><title>Guide Contents</title>
<ol>
<li><link href="what-is-a-block.html">What is a block?</link></li>
<li>What is a block listener?</li>
<li><link href="what-is-an-application-listener.html">What is an
application listener?</link></li>
<li><link href="creating-a-block.html">How do I create a
block?</link></li>
<li><link href="making-phoenix-compatible-comps.html">How do I make
my components phoenix-compatible?</link></li>
<li><link href="blockinfo-specification.html">BlockInfo
specification</link></li>
</ol>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/bdg/what-is-a-block.xml
Index: what-is-a-block.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 Block?</title>
<authors><person name="Phoenix Documentation Team"
email="avalon-phoenix-dev@jakarta.apache.org"/></authors></header>
<body>
<section><title>Introduction</title>
<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>
</section>
<section><title>What is a Block?</title>
<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>
</section>
<section><title>Guide Contents</title>
<ol>
<li>What is a block?</li>
<li><link href="what-is-a-block-listener.html">What is a block
listener?</link></li>
<li><link href="what-is-an-application-listener.html">What is an
application listener?</link></li>
<li><link href="creating-a-block.html">How do I create a
block?</link></li>
<li><link href="making-phoenix-compatible-comps.html">How do I make
my components phoenix-compatible?</link></li>
<li><link href="blockinfo-specification.html">BlockInfo
specification</link></li>
</ol>
</section>
</body>
</document>
1.1
jakarta-avalon-phoenix/src/documentation/content/bdg/what-is-an-application-listener.xml
Index: what-is-an-application-listener.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 an Application Listener?</title>
<authors><person name="Paul Hammant" email="[EMAIL
PROTECTED]"/></authors></header>
<body>
<section><title>Introduction</title>
<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>
</section>
<section><title>Events notified</title>
<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>
</section>
<section><title>How to make a block listener</title>
<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>
</section>
<section><title>Guide Contents</title>
<ol>
<li><link href="what-is-a-block.html">What is a block?</link></li>
<li><link href="what-is-a-block-listener.html">What is a block
listener?</link></li>
<li>What is an application listener?</li>
<li><link href="creating-a-block.html">How do I create a
block?</link></li>
<li><link href="making-phoenix-compatible-comps.html">How do I make
my components phoenix-compatible?</link></li>
<li><link href="blockinfo-specification.html">BlockInfo
specification</link></li>
</ol>
</section>
</body>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
