You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@avalon.apache.org by ni...@apache.org on 2002/11/18 15:19:02 UTC
cvs commit: jakarta-avalon-phoenix/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
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="huw@apache.org"/></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="bloritsch@apache.org"/></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="hammant@apache.org"/></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="Paul_Hammant@yahoo.com"/></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: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>