You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@avalon.apache.org by mc...@apache.org on 2003/10/29 14:42:49 UTC
cvs commit: avalon/fortress/new/xdocs cli.xml design-notes.xml features.xml fortress_logo.gif getting-started.xml index.xml lifecycle-extensions.xml navigation.xml servlet.xml swing.xml using-meta-info.xml
mcconnell 2003/10/29 05:42:49
Added: fortress/new .cvsignore README.TXT maven.xml
project.properties project.xml
fortress/new/etc site.jsl stylesheet.css
fortress/new/xdocs cli.xml design-notes.xml features.xml
fortress_logo.gif getting-started.xml index.xml
lifecycle-extensions.xml navigation.xml servlet.xml
swing.xml using-meta-info.xml
Log:
Build content.
Revision Changes Path
1.1 avalon/fortress/new/.cvsignore
Index: .cvsignore
===================================================================
target
maven.log
velocity.log
1.1 avalon/fortress/new/README.TXT
Index: README.TXT
===================================================================
This directory contains an Anika version of the Fortress docs.
To build the docs you should do the following:
$ cd frotress/new
$ maven avalon:build
$ maven site
1.1 avalon/fortress/new/maven.xml
Index: maven.xml
===================================================================
<project default="site" xmlns:maven="jelly:maven" xmlns:j="jelly:core" xmlns:util="jelly:util" xmlns:ant="jelly:ant">
<property file="${basedir}/build.properties"/>
<property file="${basedir}/project.properties"/>
<goal name="avalon:build">
<maven:reactor
basedir="${basedir}/.."
includes="container/project.xml"
excludes="new/project.xml"
goals="jar:install"
banner="Building:"
ignoreFailures="false"/>
</goal>
<preGoal name="site">
<attainGoal name="license"/>
<attainGoal name="xjavadoc"/>
</preGoal>
<goal name="xjavadoc">
<mkdir dir="${basedir}/target/docs/api" />
<property name="copyright"
value="Copyright &copy; ${year} ${pom.organization.name}. All Rights Reserved." />
<property name="title" value="${pom.name} ${pom.currentVersion} API"/>
<javadoc destdir="${basedir}/target/docs/api"
doctitle="<h1>Avalon Framework</h1>"
noindex="false" author="true" use="true"
windowtitle="${title}"
bottom="${copyright}"
additionalparam="-breakiterator -J-Xmx128m "
packagenames="*,org.*">
<sourcepath path="${basedir}/../container/src/java"/>
<classpath>
<path refid="maven.dependency.classpath"/>
</classpath>
<link href="${sun.j2se.link}" />
</javadoc>
</goal>
</project>
1.1 avalon/fortress/new/project.properties
Index: project.properties
===================================================================
#
# Banner background and foreground colors.
#
maven.ui.banner.background = #fff
maven.ui.banner.foreground = #000
maven.xdoc.jsl = file:/${basedir}/etc/site.jsl
maven.javadoc.stylesheet =${basedir}/etc/stylesheet.css
maven.xdoc.poweredby.image=
#
# Declaration of the remote links to assign on javadoc generation.
# Link declarations can be overriden in the user's build.properties
# file.
#
sun.j2se.link = http://java.sun.com/j2se/1.4/docs/api/
avalon.framework.link = http://avalon.apache.org/framework/api/
maven.javadoc.links = ${sun.j2se.link},${avalon.framework.link}
1.1 avalon/fortress/new/project.xml
Index: project.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<project>
<organization>
<name>Apache Software Foundation</name>
<url>http://avalon.apache.org/</url>
<logo>http://avalon.apache.org/images/apache-avalon-logo.png</logo>
</organization>
<groupId>avalon-fortress</groupId>
<id>avalon-fortress-doc</id>
<name>Avalon-Fortress-Docs</name>
<currentVersion>1.0-dev</currentVersion>
<inceptionYear>2003</inceptionYear>
<shortDescription>Avalon-Fortress-Doc</shortDescription>
<description>
Contains the sources to, and the means to generate, the
Avalon-Fortress website.
</description>
<dependencies>
<dependency>
<id>avalon-framework</id>
<version>4.1.5</version>
<groupId>avalon-framework</groupId>
</dependency>
<dependency>
<id>logkit</id>
<version>1.2.2</version>
</dependency>
<dependency>
<id>commons-collections</id>
<version>2.1</version>
</dependency>
<dependency>
<id>concurrent</id>
<version>1.3.1</version>
</dependency>
<dependency>
<id>excalibur-instrument</id>
<version>1.0</version>
</dependency>
<dependency>
<id>excalibur-instrument-manager</id>
<version>1.0</version>
<groupId>excalibur-instrument-manager</groupId>
</dependency>
<dependency>
<id>excalibur-instrument-manager-interfaces</id>
<version>1.0</version>
<groupId>excalibur-instrument-manager</groupId>
</dependency>
<dependency>
<id>excalibur-event</id>
<version>20030616</version>
</dependency>
<dependency>
<id>bcel</id>
<version>5.1</version>
</dependency>
<dependency>
<id>excalibur-logger</id>
<version>20030616</version>
</dependency>
<dependency>
<id>excalibur-sourceresolve</id>
<version>1.0.1</version>
</dependency>
<dependency>
<id>excalibur-lifecycle</id>
<version>1.0</version>
</dependency>
<dependency>
<id>xml-apis</id>
<version>2.0.2</version>
</dependency>
</dependencies>
</project>
1.1 avalon/fortress/new/etc/site.jsl
Index: site.jsl
===================================================================
<?xml version="1.0"?>
<!-- stylesheet to be used -->
<jsl:stylesheet select="$doc"
xmlns:define="jelly:define"
xmlns:j="jelly:core"
xmlns:jsl="jelly:jsl"
xmlns:log="jelly:log"
xmlns:util="jelly:util"
xmlns:x="jelly:xml"
xmlns:doc="doc"
xmlns="dummy" trim="false">
<jsl:template match="document" trim="false">
<j:useBean var="navbean" class="org.apache.maven.NavBean"/>
<j:set var="location" value="${outFile.substring(destdir.length())}"/>
<util:replace var="location" oldChar="\" newChar="/" value="${location}"/>
<!-- Stores location for publish date / version -->
<j:set var="date">${maven.xdoc.date}</j:set>
<j:setProperties
object="${navbean}"
document="${doc}"
location="${location}"/>
<x:doctype name="html"
publicId="-//W3C//DTD XHTML 1.0 Transitional//EN"
systemId="http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"/>
<html>
<head>
<j:set var="docTitle">
<x:expr select="./properties/title"/>
</j:set>
<x:if select="$nav/title">
<title>
<x:expr select="$nav/title"/> - ${docTitle}
</title>
</x:if>
<x:if select="not($nav/title)">
<title>${pom.name} - ${docTitle}</title>
</x:if>
<style type="text/css"><![CDATA[
@import url("${relativePath}/style/tigris.css");
@import url("${relativePath}/style/maven.css");
]]></style>
<util:file var="projectCssFile" name="${maven.docs.src}/style/project.css"/>
<j:if test="${projectCssFile.exists()}">
<style type="text/css"><![CDATA[
@import url("${relativePath}/style/project.css");
]]></style>
</j:if>
<!-- FIXME: once someone works out how to stop this breaking
<x:element name="script"><x:attribute name="type">text/javascript</x:attribute>
if (document.layers) {
document.writeln(''+
'<link rel="stylesheet" type="text/css" href="${relativePath}/style/ns4_only.css" media="screen" /><link rel="stylesheet" type="text/css" href="${relativePath}/style/maven_ns4_only.css" media="screen"/>');
}
</x:element>
-->
<link rel="stylesheet" type="text/css" href="${relativePath}/style/print.css" media="print"/>
<meta http-equiv="Content-Type" content="text/html; charset=${outputencoding}"></meta>
<x:forEach var="author" select="./properties/author">
<meta name="author" content="${author.text}"/>
<meta name="email" content="${author.attribute('email').value}"/>
</x:forEach>
<jsl:applyTemplates select="$doc/document/head/*"/>
</head>
<x:element name="body"><j:whitespace trim="true">
<x:attribute name="class">composite</x:attribute>
<x:forEach var="attr" select="$doc/document/body/@*">
<x:attribute name="${attr.name}">${attr.value}</x:attribute>
</x:forEach>
</j:whitespace>
<div id="banner">
<table border="0" cellspacing="0" cellpadding="8" width="100%" height="103">
<tr>
<!-- organization logo -->
<td>
<j:set var="logo" value="${pom.organization.logo}"/>
<j:if test="${!empty(logo)}">
<!-- set url to org or project url -->
<j:set var="url" value="${pom.organization.url}"/>
<j:if test="${!empty(url)}">
<j:set var="home" value="${pom.organization.url}"/>
</j:if>
<j:if test="${empty(url)}">
<j:set var="home" value="${pom.url}"/>
</j:if>
<!-- set image to relative or complete -->
<j:set var="image" value="${pom.organization.logo}"/>
<j:if test="${!image.startsWith('http://')}">
<j:set var="image" value="${relativePath}${image}"/>
</j:if>
<a href="${home}">
<img src="${image}" align="left" alt="${pom.organization.name}" border="0"/>
</a>
</j:if>
</td>
<!-- project logo and link -->
<td>
<div align="right" id="login">
<a href='http://apachecon.com/2003/US/index.html'>
<img border='0'
src='http://www.apache.org/~ceki/ac2003/ac2003-150.gif'/>
</a>
</div>
</td>
<!--
<td>
<div align="right" id="login">
<j:set var="logo" value="${pom.logo}"/>
<j:if test="${logo != null and logo != ''}">
<j:set var="image" value="${pom.logo}"/>
<j:if test="${!image.startsWith('http://')}">
<j:set var="image" value="${relativePath}${image}"/>
</j:if>
<a href="${pom.url}">
<img src="${image}" align="right" alt="${pom.name}" border="0"/>
</a>
</j:if>
</div>
</td>
-->
</tr>
</table>
</div>
<div id="breadcrumbs">
<table border="0" cellspacing="0" cellpadding="4" width="100%">
<tr>
<j:if test="${date == 'left'}">
<j:set var="version" value="${maven.xdoc.version}"/>
<td>Last published: ${build.date}
<j:if test="${!empty(version)}">| Doc for ${version}</j:if>
</td>
</j:if>
<td>
<div align="right">
<j:if test="${date == 'right'}">
Last published: ${build.date}
<x:if select="$nav/body/links">|</x:if>
</j:if>
<!-- render links -->
<x:if select="$nav/body/links">
<jsl:applyTemplates select="$nav/body/links"/>
</x:if>
<x:if select="not($nav/body/links)">
<!-- FIXME -->
</x:if>
</div>
</td>
</tr>
</table>
</div>
<!-- Body of the page -->
<table border="0" cellspacing="0" cellpadding="8" width="100%"> <!--id="main" -->
<tr valign="top">
<td id="leftcol" width="20%">
<div id="navcolumn">
<j:if test="${date == 'navigation-top'}">
<div>
<small>Last published: ${build.date}</small>
</div>
</j:if>
<x:if select="$nav">
<jsl:applyTemplates select="$nav/body/menu[not(@type) | @type='header'] | $nav/body/search"/>
</x:if>
<!-- Standard Maven Navigation -->
<j:set var="fileName">${file}</j:set>
<!--
! Check to see if the user wishes to include the
! maven-generated docs on their site.
!-->
<j:if test="${includeProjectDocumentation.equals('yes')}">
<div>
<strong>Project Documentation</strong>
<div>
<small>
<a href="${relativePath}/index.html">About ${pom.name}</a>
</small>
</div>
<div>
<small>
<a href="${relativePath}/project-info.html">Project Info</a>
</small>
<util:tokenize var="projectInfoFiles" delim=",">${maven.xdoc.projectInfo}</util:tokenize>
<j:forEach var="infoFile" items="${projectInfoFiles}">
<j:if test="${relativePath == '.' and fileName.endsWith(infoFile)}">
<div>
<small>
<a href="${relativePath}/mail-lists.html">Mailing Lists</a>
</small>
</div>
<div>
<small>
<a href="${relativePath}/team-list.html">Project Team</a>
</small>
</div>
<div>
<small>
<a href="${relativePath}/dependencies.html">Dependencies</a>
</small>
</div>
<j:if test="${!empty(pom.repository.url)}">
<div>
<small>
<a href="${relativePath}/cvs-usage.html">Source Repository</a>
</small>
</div>
</j:if>
<j:if test="${!empty(pom.issueTrackingUrl)}">
<div>
<small>
<a href="${relativePath}/issue-tracking.html">Issue Tracking</a>
</small>
</div>
</j:if>
</j:if>
</j:forEach>
</div>
<div>
<small>
<a href="${relativePath}/maven-reports.html">Project Reports</a>
</small>
<!--
| Check to see if we need to include the report
| links in this document. The only time we
| need to do this is when the current document
| either the maven-reports.xml doc (the page
| is displayed when clicking on Project
| Reports) or when the current document is one
| of the actual reports (in which case we want
| to leave the project report links expanded.
|-->
<j:set var="includeReportLinks" value="false"/>
<j:forEach var="report" items="${reports}">
<j:set var="linkWithXmlExt" value="${report.link}.xml"/>
<j:if test="${relativePath == '.' and (fileName.endsWith('maven-reports.xml') or fileName.endsWith(linkWithXmlExt))}">
<j:set var="includeReportLinks" value="true"/>
</j:if>
</j:forEach>
<!--
| If we need to include the report links, then
| do so. This is determined by the above
| block.
|-->
<j:if test="${includeReportLinks == 'true'}">
<j:forEach var="report" items="${reports}">
<div>
<small>
<a href="${relativePath}/${report.link}.html">
${report.name}
</a>
</small>
</div>
</j:forEach>
</j:if>
</div>
<j:if test="${pom.reports.isEmpty()}">
<j:if test="${sourcesPresent}">
<div>
<small>
<a href="${relativePath}/apidocs/index.html">JavaDocs</a>
</small>
</div>
<div>
<small>
<a href="${relativePath}/xref/index.html">Source XReference</a>
</small>
</div>
<j:if test="${unitTestSourcesPresent == 'true'}">
<div>
<small>
<a href="${relativePath}/xref-test/index.html">Test XReference</a>
</small>
</div>
</j:if>
</j:if>
</j:if>
<j:set var="devProcess" value="false"/>
<util:available file="${maven.docs.src}/development-process.xml">
<j:set var="devProcess" value="true"/>
</util:available>
<j:if test="${devProcess}">
<div>
<small>
<a href="${relativePath}/development-process.html">Development Process</a>
</small>
</div>
</j:if>
<j:if test="${!devProcess}">
<div>
<small>
<j:set var="devProcess">${maven.xdoc.developmentProcessUrl}</j:set>
<a href="${devProcess}">Development Process</a>
</small>
</div>
</j:if>
</div>
</j:if>
<j:set var="poweredbyimage">${maven.xdoc.poweredby.image}</j:set>
<j:set var="poweredbytitle">${maven.xdoc.poweredby.title}</j:set>
<j:set var="poweredbyurl">${maven.xdoc.poweredby.url}</j:set>
<j:if test="${!empty(poweredbyimage)}">
<div style="margin-top: 20px; width: 100%; text-align: center;">
<a href="${poweredbyurl}" title="${poweredbytitle}"><img alt="${maven.xdoc.poweredby.title}" style="border: 1px solid black" src="${relativePath}/images/logos/${poweredbyimage}"/></a>
</div>
</j:if>
<j:if test="${date == 'navigation-bottom'}">
<div>
<small>Last published: ${build.date}</small>
</div>
</j:if>
</div>
</td>
<td rowspan="2">
<div id="bodycol">
<!-- Insert MAIN body here -->
<div class="app">
<!-- FIXME really shouldn't use $doc, but jelly loses it's context again -->
<jsl:applyTemplates select="$doc/document/body/section"/>
<jsl:applyTemplates select="$doc/document/body/glossary" />
<jsl:applyTemplates select="$doc/document/body/release" />
<jsl:applyTemplates select="$doc/document/body/changelog" />
<jsl:applyTemplates select="$doc/document/body/taskList" />
<jsl:applyTemplates select="$doc/document/body/goals" />
</div>
</div>
</td>
</tr>
</table>
<div id="footer">
<table style='width:100%' border="0" cellspacing="0" cellpadding="4">
<jsl:applyTemplates select="$nav/body/footer"/>
<tr>
<td>
<j:if test="${!empty(pom.organization.name)}">
<j:if test="${!empty(pom.inceptionYear)}">
<j:if test="${pom.inceptionYear == mavenCurrentYear}">
© ${mavenCurrentYear}, ${pom.organization.name}
</j:if>
<j:if test="${pom.inceptionYear != mavenCurrentYear}">
© ${pom.inceptionYear}-${mavenCurrentYear}, ${pom.organization.name}
</j:if>
</j:if>
<j:if test="${empty(pom.inceptionYear)}">
© ${mavenCurrentYear}, ${pom.organization.name}
</j:if>
</j:if>
<j:if test="${date == 'bottom'}">
- Last published: ${build.date}
</j:if>
</td>
<j:if test="${date == 'bottom-right'}">
<td style='width: auto; text-align:right'>Last published: ${build.date}</td>
</j:if>
</tr>
</table>
</div>
</x:element>
</html>
</jsl:template>
<!-- process the properties of the doc -->
<jsl:template match="properties" trim="false">
<!-- stick head block here later -->
</jsl:template>
<!-- Process a menu for the navigation bar -->
<jsl:template match="menu" trim="false">
<div>
<strong><x:expr select="@name"/></strong>
<jsl:applyTemplates select="item"/>
</div>
</jsl:template>
<jsl:template match="item" trim="false">
<x:set var="item" select="."/>
<x:set var="_name" select="string(@name)"/>
<x:set var="_link" select="string(@href)"/>
<x:set var="_img" select="string(@img)"/>
<div>
<small>
<j:if test="${navbean.isSelected(item.get(0))}">
<b><doc:itemLink name="${_name}" link="${_link}" img="${_img}"/></b>
</j:if>
<j:if test="${!navbean.isSelected(item.get(0))}">
<doc:itemLink name="${_name}" link="${_link}" img="${_img}"/>
</j:if>
</small>
<j:if test="${!navbean.isCollapsed(item.get(0))}">
<jsl:applyTemplates select="item"/>
</j:if>
</div>
</jsl:template>
<!-- Process the breadcrumb navbar -->
<jsl:template match="links" trim="false">
<j:set var="linkCount" value="1"/>
<x:forEach var="link" select="item">
<j:if test="${linkCount != 1}">|</j:if>
<j:set var="_name"><x:expr select="@name"/></j:set>
<j:set var="_link"><x:expr select="@href"/></j:set>
<doc:itemLink name="${_name}" link="${_link}"/>
<j:set var="linkCount" value="${1+linkCount}"/>
</x:forEach>
</jsl:template>
<!-- Google site search -->
<jsl:template match="search" trim="false">
<!-- Search code: http://www.google.com/searchcode.html -->
<!-- Google logos: http://www.google.com/stickers.html -->
<!-- Terms: http://www.google.com./services/terms_free.html -->
<div>
<strong>Search ${pom.name}</strong>
<form method="get" action="http://www.google.com/search">
<a class="navlink" href="http://www.google.com">
<img src="http://www.google.com/logos/Logo_25wht.gif"
alt="Google" border="0" />
</a><p/>
<j:set var="siteURL" value="${pom.url}"/>
<!-- google fails on urls that end with / -->
<j:if test="${siteURL.endsWith('/')}">
<j:set var="URLLength" value="${siteURL.length() - 1}"/>
<j:set var="siteURL" value="${siteURL.substring(0, URLLength.intValue())}"/>
</j:if>
<input type="text" size="15" name="q" maxlength="255" value=""/>
<input type="submit" value="Go" name="btnG"/>
<input type="hidden" name="domains" value="${siteURL}"/>
<input type="hidden" id="search" name="sitesearch" value="${siteURL}"/>
</form>
</div>
</jsl:template>
<!-- process a documentation section -->
<jsl:template match="section" trim="false">
<div class="h3">
<j:set var="_sectionName"><x:expr select="@name"/></j:set>
<j:if test="${!empty(_sectionName)}">
<h3>
<a name="${_sectionName}">${_sectionName}</a>
</h3>
</j:if>
<jsl:applyTemplates select="*"/>
</div>
</jsl:template>
<jsl:template match="subsection" trim="false">
<div class="h4">
<j:set var="_sectionName"><x:expr select="@name"/></j:set>
<j:if test="${!empty(_sectionName)}">
<h4>
<a name="${_sectionName}">${_sectionName}</a>
</h4>
</j:if>
<jsl:applyTemplates select="*"/>
</div>
</jsl:template>
<jsl:template match="source" trim="false">
<div id="source">
<pre><x:expr select="."/></pre>
</div>
</jsl:template>
<jsl:template match="footer" trim="false">
<tr>
<td>
<jsl:applyTemplates select="*"/>
</td>
</tr>
</jsl:template>
<jsl:template match="table" trim="false">
<j:set var="rowcount" value="0"/>
<table cellpadding="3" cellspacing="2" border="1" width="100%">
<jsl:applyTemplates select="*"/>
</table>
</jsl:template>
<jsl:template match="tr" trim="false">
<j:choose>
<j:when test="${rowMode == 'a'}">
<j:set var="rowMode" value="b"/>
</j:when>
<j:otherwise>
<j:set var="rowMode" value="a"/>
</j:otherwise>
</j:choose>
<!-- copy attributes FIXME: Shouldn't this only be colspan|rowspan? -->
<x:element name="tr"><j:whitespace trim="true">
<x:attribute name="class">${rowMode}</x:attribute>
<x:forEach var="attr" select="@*">
<x:attribute name="${attr.name}">${attr.value}</x:attribute>
</x:forEach>
<jsl:applyTemplates select="*"/>
</j:whitespace></x:element>
</jsl:template>
<!--************************-->
<!-- glossary documentation -->
<!--************************-->
<jsl:template match="glossary" trim="false">
<jsl:applyTemplates select="glossary-entries/glossary-entry" />
</jsl:template>
<jsl:template match="glossary-entry" trim="false">
<strong><x:expr select="name" /></strong>
<br/>
<x:expr select="definition" />
<p/>
</jsl:template>
<!--************************-->
<!-- goals documentation -->
<!--************************-->
<jsl:template match="goals" trim="false">
<!-- reset row alternation -->
<j:set var="rowMode" value="" />
<div class="h3">
<h3><a name="Goals">Goals</a></h3>
<table>
<tr width='100%'><th>Goal</th><th>Description</th></tr>
<jsl:applyTemplates select="goal"/>
</table>
</div>
</jsl:template>
<!-- a goal -->
<!-- FIXME: this is copied from tr - there must be a way of
calling templates in jsl? -->
<jsl:template match="goal" trim="false">
<j:choose>
<j:when test="${rowMode == 'a'}">
<j:set var="rowMode" value="b"/>
</j:when>
<j:otherwise>
<j:set var="rowMode" value="a"/>
</j:otherwise>
</j:choose>
<x:element name="tr"><j:whitespace trim="true">
<x:attribute name="class">${rowMode}</x:attribute>
<j:set var="_goalName"><x:expr select="./name" /></j:set>
<td width='20%'><a name="${_goalName}">${_goalName}</a></td>
<td width='80%'><jsl:applyTemplates select="description" /></td>
</j:whitespace></x:element>
</jsl:template>
<jsl:template match="description">
<jsl:copy trim="false">
<jsl:applyTemplates trim="false"/>
</jsl:copy>
</jsl:template>
<!--************************-->
<!-- changelog documentation-->
<!--************************-->
<jsl:template match="changelog" trim="false">
<j:set var="rowMode" value="" />
<table width="100%">
<tr>
<th>Date</th><th>Author</th><th>Files/Message</th>
</tr>
<jsl:applyTemplates select="changelog-entry" />
</table>
</jsl:template>
<!-- transform a changelog entry -->
<!-- FIXME: tr code copied from above -->
<jsl:template match="changelog-entry" trim="false">
<j:choose>
<j:when test="${rowMode == 'a'}">
<j:set var="rowMode" value="b"/>
</j:when>
<j:otherwise>
<j:set var="rowMode" value="a"/>
</j:otherwise>
</j:choose>
<x:element name="tr"><j:whitespace trim="true">
<x:attribute name="class">${rowMode}</x:attribute>
<td><x:expr select="date" /> <x:expr select="time" /></td>
<td><x:expr select="author"/></td>
<td><jsl:applyTemplates select="*" />
<pre><x:expr select="msg"/></pre>
</td>
</j:whitespace></x:element>
</jsl:template>
<jsl:template match="file">
<j:set var="url">${pom.repository.url}<x:expr select="name"/></j:set>
<j:set var="revUrl">${url}?<x:expr select="revision"/>&content-type=text/vnd.viewcvs-markup</j:set>
<a href="${url}"><x:expr select="name"/></a> -
<a href="${revUrl}">v<x:expr select="revision"/></a>
<br/>
</jsl:template>
<!-- remove the space at the end of parsed "a" anchors -->
<jsl:template match="a" trim="false">
<jsl:copy trim="true">
<jsl:applyTemplates trim="true"/>
</jsl:copy>
</jsl:template>
<!-- copy any other elements through -->
<jsl:template match="*" trim="false">
<jsl:copy trim="false">
<jsl:applyTemplates trim="false"/>
</jsl:copy>
</jsl:template>
<!-- element values don't pass through as text -->
<jsl:template match="@*"/>
</jsl:stylesheet>
1.1 avalon/fortress/new/etc/stylesheet.css
Index: stylesheet.css
===================================================================
/* Javadoc style sheet */
/* Define colors, fonts and other style attributes here to override the defaults */
/* Page background color */
body { background-color: #FFFFFF }
/* Table colors */
.TableHeadingColor { background: #CCCCFF } /* Dark mauve */
.TableSubHeadingColor { background: #EEEEFF } /* Light mauve */
.TableRowColor { background: #FFFFFF } /* White */
/* Font used in left-hand frame lists */
.FrameTitleFont { font-size: 10pts; font-family: Helvetica, Arial, san-serif }
.FrameHeadingFont { font-size: 10pts; font-family: Helvetica, Arial, san-serif }
.FrameItemFont { font-size: 10pts; font-family: Helvetica, Arial, san-serif }
/* Example of smaller, sans-serif font in frames */
/* .FrameItemFont { font-size: 10pt; font-family: Helvetica, Arial, sans-serif } */
/* Navigation bar fonts and colors */
.NavBarCell1 { background-color:#EEEEFF;}/* Light mauve */
.NavBarCell1Rev { background-color:#00008B;}/* Dark Blue */
.NavBarFont1 { font-family: Arial, Helvetica, sans-serif; color:#000000;}
.NavBarFont1Rev { font-family: Arial, Helvetica, sans-serif; color:#FFFFFF;}
.NavBarCell2 { font-family: Arial, Helvetica, sans-serif; background-color:#FFFFFF;}
.NavBarCell3 { font-family: Arial, Helvetica, sans-serif; background-color:#FFFFFF;}
1.1 avalon/fortress/new/xdocs/cli.xml
Index: cli.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<document>
<properties>
<title>Avalon Fortress - Overview</title>
<author email="dev@avalon.apache.org">Avalon Documentation Team</author>
</properties>
<body>
<section name="Command Line Tools">
<p>
Command Line Tools are the class of tools or applications that are
run from a command shell. Typical examples are the ANT build tool,
Turbine Maven, Apache Forrest, etc. They have a definite begining
and a definite end. As a result, we don't have to do any trickery
with threads or synchronizing the startup and shutdown of the
container.
</p>
<p>
A typical example of creating a Fortress CLI application will follow
the pattern outlined below:
</p>
<!-- <source>
<![CDATA[
public int main(String [] args)
{
// You would have to implement the referenced method here...
FortressConfig config = configWithArgs( args );
ContainerManager cm = new DefaultContainerManager( config.getContext() );
ContainerUtil.initialize( cm );
// Get the root container and use it
MyCLIContainer container = (MyCLIContainer) cm.getContainer();
container.performAction(args);
// Clean up after ourselves
ContainerUtil.dispose( cm );
}
]]>
</source>-->
<p>
As you can see, there are three major portions of working with
Fortress: startup, useage, and shutdown; The Startup and shutdown
portions are not likely to change at all. What will change is how
you plan on interacting with your container.
</p>
</section>
</body>
</document>
1.1 avalon/fortress/new/xdocs/design-notes.xml
Index: design-notes.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<document>
<properties>
<title>Avalon Fortress - Design Notes</title>
<author email="dev@avalon.apache.org">Avalon Documentation Team</author>
</properties>
<body>
<section name="Fortress Design Notes">
<p>
Fortress has two design goals: facilitate heirarchical containers and
take management functions outside of the critical path. The critical
path is the code execution path that is required to find and use a
component. Fortress assumes that the developer has explicit knowledge of
his domain--which Fortress itself would never have any knowledge of. It
also assumes that there is one root container, although it does not
force that upon the developer.
</p>
<subsection name="Asynchronous Management">
<p>
Due to the long startup times of certain components like the
DataSourceComponent ECM based code suffered from slowness. The problem
was also made worse by the delayed loading and running of components.
Components would only be instantiated when they were first looked
up--which made problems for components that needed to be started
immediately.
</p>
<p>
Fortress makes use of the Event package's CommandManager so that all
components can be started up immediately, but it is done in the
background. That means that components are still starting while
Fortress is ready to work. If a component hasn't been started yet
before it is needed, then Fortress will make sure it starts before it
turns over the requested component. It will also make sure no
component gets started twice.
</p>
<p>
All component pool sizing and management is done by background threads
so that as Fortress responds to requests for components, it manages
resources without adding that cost to the client code. That means the
critical path (the code that actually does the work of the system) is
not delayed unnecessarily.
</p>
</subsection>
<subsection name="Hierarchical Containers">
<p>
Part of the design concept for Fortress heirarchical containers is to
use a ContainerManager to make sure all the necessary services are set
up and running. For example, the Fortress container needs a
CommandManager--so the ContainerManager checks to see if it is already
set up and uses it. That way we can have one Container that has one or
more ContainerManagers that all use the kernel level services of the
parent container.
</p>
<p>
The kernel level services are: CommandManager, InstrumentManager,
LoggerManager and ThreadManager. The actual setup and configuration of
these services are done using a Context. The choice for the Context
object was a conscious decision because we didn't want to extend the
objects in a proprietary manner (LoggerManageable, etc.) like the ECM
did. By passing the kernel services in the context, the kernel
services can be forwarded to any child containers.
</p>
<p>
To assist in the setup of the Context, Fortress uses a ContextManager.
The ContextManager will either set up the context based on a Context
passed in, or from a default context. Once the ContextManager assists
the ContainerManager to set up any missing kernel services, you can
get the Container from the ContainerManager and start using it.
</p>
</subsection>
</section>
<section name="Why Not Set Up a Standard Container Interface?">
<p>
Each domain has its own needs. For instance, Cocoon is based on a
request/response processing model. Component based tools are based
on a useage model. Swing based Apps are based on other models. There
is no one size fits all solution, and Fortress can be used in all of
these solutions. As an interim solution, the DefaultContainer does
have one public method exposed: <code>getServiceManager()</code>.
</p>
</section>
<section name="Why Not Use a Central Kernel?">
<p>
This was actually planned in a future release. There are some issues
to work out with a central kernel though. Those issues include how
to detect and set up sub-containers, how to make sure the container
instance you want is set up instead of the default version, etc. In
essence, what is needed is <em>meta information</em>. Meta
information is information about the container heirarchy and the
components involved. In the future Avalon Container: Merlin ,
has a proper meta model.
</p>
</section>
<section name="Smooth Migration for Component Lookup">
<p>
Due to the fact there are many ways of implementing the "preferred
practices" for role naming, different components make assumptions
about their environment. The chief problem with these assumptions
is that it reduces the availability for which components can work
with each other. Some components expect only one component to be
mapped, while another component may expect to lookup choices in
a ServiceSelector, while yet another may expect to find it via a
stylized entry. To recap, the supported lookup styles are:
</p>
<ul>
<li>lookup(MyComponent.ROLE)</li>
<li>lookup(MyComponent.ROLE + "Selector").select(hint)</li>
<li>lookup(MyComponent.ROLE + "/" + hint)</li>
</ul>
<p>
In the first case, the component that requires an external component
asks for the mapped component via the role name. It expects only
one component to be mapped. If Fortress has multiple components
available, it will only return the default version. The default
version is the first entry in the configuration file, unless you
add the magic attribute "default" with the value "true". The last
component for the role with that attribute is the default value.
</p>
<p>
In the second case, the component expects to be able to select the
component from a ServiceSelector, mapped to the ROLE + "Selector"
entry. Fortress will manufacture a ServiceSelector for you, and
all will be as expected.
</p>
<p>
In the last case, the component expects to be able to look up the
component based on the ROLE and the hint combined. The magic
separator is the "/" character. Fortress will be able to interpret
that and skip the ServiceSelector step.
</p>
</section>
</body>
</document>
1.1 avalon/fortress/new/xdocs/features.xml
Index: features.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<document>
<properties>
<title>Avalon Fortress - Features</title>
<author email="dev@avalon.apache.org">Avalon Documentation Team</author>
</properties>
<body>
<section name="Features">
<p>
Fortress provides a framework for you to easily create your
own application specific containers. We strive to make it
easy for you to do without sacrificing any power. Fortress
allows you to focus on the core issues in your system, without
worrying about the component management getting in your way.
</p>
<subsection name="Asynchronous Component Management">
<p>
Most component management functions don't take that long to
perform, but the time they do take can directly affect how
many requests your system can process at the same time. For
that reason, we use the CommandManager from the Event package
to manage our components. By moving all the management
functions to a limited number of background threads, we are
able to save you time in the critical processing path.
</p>
<p>
The CommandManager can be extended to your components as well.
That way, your components can perform management tasks in the
background as well. Fortress will likely be your choice of
containers if you have strict performance constraints.
</p>
</subsection>
<subsection name="Extensible Lifecycle">
<p>
Fortress has support for an experimental feature that allows
you to extend your component lifecycle in an application
specific manner. If it proves to be a truly useful feature,
other Avalon containers will adopt it.
</p>
</subsection>
<subsection name="Instrumentation">
<p>
Fortress is integrated with the Instrumentation package so
you can get a graphical view of the health of your system
at runtime. We integrate sampling points for each of the
component handlers so that you can see how many component
instances each handler is responsible for. Using that
information, you can tune your container more intelligently.
</p>
</subsection>
<subsection name="Attribute Enabled Meta Information">
<p>
Instead of using a "roles" file to keep track of the component
configuration name, and what kind of lifestyle the component
has, Fortress provides some tools so that you can keep track
of that information with your java source code. You have to
use the ANT tasks that are defined in the Fortress tools jar.
It collects all the attributes defined as JavaDoc doc tags
and generates the meta info files which are then read at
runtime. It makes it a whole lot easier to manage critical
aspects like lifestyle and which classes represent components.
<a href="using-meta-info.html">You can find out more about it
here.</a>
</p>
</subsection>
</section>
</body>
</document>
1.1 avalon/fortress/new/xdocs/fortress_logo.gif
<<Binary file>>
1.1 avalon/fortress/new/xdocs/getting-started.xml
Index: getting-started.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<document>
<properties>
<title>Fortress Getting Started</title>
<author email="dev@avalon.apache.org">Avalon Documentation Team</author>
</properties>
<body>
<section name="Getting Started">
<p>
This is a brief guide to getting you up and running with fortress.
For complex topics like how to decompose a system into individual
components, Seperation of Concerns, etc, refer to other documentation.
</p>
<subsection name="Getting your stuff together">
<ul>
<li>If you haven't already, download and install the latest version
of <link href="http://ant.apache.org/">Apache Ant</link>.</li>
<li>Get and install a CVS client (see
<link href="http://jakarta.apache.org/site/cvsindex.html">here</link>
for information on CVS).</li>
<li>Check out the modules avalon, avalon-excalibur,
avalon-logkit and jakarta-site</li>
<li>Use ant to build the various projects: avalon, logkit, excalibur fortress.
If something goes wrong, run ant in verbose mode using the -v option and
send the output to the avalon-user mailing list. Someone'll help you out.
</li>
</ul>
<p>Or, if you hate CVS, get a nightly build.</p>
</subsection>
<subsection name="Hello, world!">
<p>You just built fortress, its dependencies, and its examples from cvs in
the previous step. This enables you to (finally!) run a HelloWorld demo.
change into the bin directory for the examples and run the
scripts there (runswing.sh is a nice one).</p>
</subsection>
<subsection name="Well, duh! So now what?">
<p><b>Play with the examples</b></p>
<p>After looking at the sources to the examples provided and figuring out
what goes on (if you're an IDE person, run the examples in your IDE
debugger! If you develop servlets, be sure to try to get the servlet
example to run), the real cool but also the hard part begins.</p>
</subsection>
<subsection name="Converting from ECM">
<p>If you're looking at converting an existing avalonized application that
uses ECM, well, we want to write a tool that does this all but automatically
for you. Not there yet though.</p>
</subsection>
<subsection name="Convert a non-avalon application">
<p>The first thing you want to do is to create a fortress instance inside
your applications main loop or bootstrap class. The second thing you want
to do is identify the building blocks of your application, and transform
them into avalon components (by making them passive, and extending the
avalon framework lifecycle interfaces).
Then, create the fortress configuration files to tell it about those new
components, and transfer control over those components from your bootstrap
code to fortress. Done!</p>
<p>Okay, so it may not be so simple as it sounds, but that is the general
idea. Just get started, and come and talk to us on the mailing list when
you get lost.</p>
</subsection>
<subsection name="Creating a new application">
<p>Start with the example that fits your enviroment (console, GUI
or embedded), and simply start hacking from there. You'll want to think
about the various tasks your app serves, and how to decompose your app
into components that fit those tasks. The
<link href="http://avalon.apache.org/developing">Developing with Avalon</link>
paper talks you through this.</p>
</subsection>
<subsection name="Mastering Fortress">
<p>
The best way to learn about avalon and its concepts is to build your own
container. Try and plug in your own implementations of the different parts
of fortress, like a different ComponentHandler. Once you get a hang of it,
come and join the avalon folks in their quest for the holy grail of
software architecture!
</p>
</subsection>
</section>
</body>
</document>
1.1 avalon/fortress/new/xdocs/index.xml
Index: index.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<document>
<properties>
<title>Avalon Fortress - Overview</title>
<author email="dev@avalon.apache.org">Avalon Documentation Team</author>
</properties>
<body>
<section name="Introduction">
<p>
Fortress contains a framework to help you create your own
avalon containers. It boasts asynchronous management of your
component instances, high scalability, easier maintenance of
your code, and easy embedding into various environments like
servlet engines.
</p>
</section>
<section name="Available Documentation">
<ul>
<li>There is some material relating to fortress in the experimental
<a href="http://nagoya.apache.org/wiki/">ApacheWiki</a>, right
<a href="http://nagoya.apache.org/wiki/apachewiki.cgi?AvalonFortress">here</a>.
One of the things you can find there is the
<a href="http://nagoya.apache.org/wiki/apachewiki.cgi?AvalonFortressFAQ">FAQ</a>.</li>
<li>You will probably want to check out the examples that come with fortress;
they're located in the examples/ dir in cvs, and nightly builds are also
made available.</li>
<li>For general information about the avalon project, you will want to read the
<a href="http://avalon.apache.org/framework/">Avalon Framework Documentation</a>.
<a href="http://avalon.apache.org/developing/">Developing with Avalon</a> is a
terribly useful resource as well.</li>
</ul>
</section>
</body>
</document>
1.1 avalon/fortress/new/xdocs/lifecycle-extensions.xml
Index: lifecycle-extensions.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<document>
<properties>
<title>Fortress Getting Started</title>
<author email="dev@avalon.apache.org">Avalon Documentation Team</author>
</properties>
<body>
<section name="What are lifecycle extensions ?">
<p>
Lifecycle extensions are additional stages a component can traverse through during
it's lifetime. Lifecycle extensions allow a Container to provide extra functionality
to Components in addition to the standard stages defined by Avalon Framework.
</p>
<p>
Avalon Framework defines a set of standard interfaces often termed as Lifecycle
metainfo which tells the ComponentManager how a particular Component should be treated
during it's life.
</p>
<p>
This metainfo allows the developer to separate the various concerns involved when
writing a Component, often termed SoC and IoC (Separation of Concerns and Inversion of
Control) and is one of primary advantages of using Avalon.
</p>
<p>
Sometimes it's useful to extend this development paradigm from the framework level
into the application domain, to create customized lifecycle extensions that are called
upon in addition to the standard set defined by the Avalon Framework.
</p>
<p>
Such custom lifecycle stages can further enable domain specific logic across many,
perhaps even unrelated components, can reduce code duplication, and allows the developer
to reuse the same development and thinking paradigm as the standard lifecycle stages.
</p>
<p>
For example, you might want to pass a specialized SecurityManager to some of your
components before they are initialized, or have their internal state persistently cached
during system shutdown and restored at during startup. You might want to pass user
dependent decryption keys to your component, or give components the opportunity to
recycle themselves before being disposed or returned to a pooled component handler.
</p>
<p>
The possibilities and number of extensions are only limited by the requirements of your
particular application domain.
</p>
<p>
This document describes how to add new lifecycle extensions using <strong>Fortress</strong>.
This document assumes a knowledge of what an Avalon lifecycle is, and a basic understanding
of the standard lifecycle interfaces Avalon Framework defines. References in this document to
Component and ComponentManager can also be freely interpreted as Service and ServiceManager
by the reader.
</p>
<note>As at the time of writing, Fortress is the only Avalon container that
supports lifecycle extensions, which means Components that use this feature will most likely
only work as expected with Fortress, and not with the other Avalon containers
(ExcaliburComponentManager, Phoenix, Merlin, Tweety, etc)</note>
<p>
Support for lifecycle extensions in the other Avalon containers is technically possible but
has not yet been discussed. Please check with the Avalon developer mailing list if you use
one of these containers and would like to use lifecycle extensions.
</p>
</section>
<section name="How do I extend a Component's lifecycle ?">
<p>
Extending a Component's lifecycle is straightforward. An overview of the process
follows:
</p>
<ol>
<li>Define the new component interface<br/>
Create the new interface defining the operations that should be called upon components
that implement this interface. Using the previously mentioned examples, this would be
your <code>SecurityManageable</code>, <code>Cacheable</code>, <code>Decryptable</code>,
<code>Recycleable</code> interfaces.
</li>
<li>Define an extension object that calls upon the methods defined in the new interface,
during one or more of the pre-defined phases of component's lifecycle<br/>
Create a class that implements <code>LifecycleExtension</code>, that tests any given
component for the above defined interface (and others if applicable), invoking methods
defined in that interface.
</li>
<li>Register the extension object with Fortress' <code>LifecycleExtensionManager</code><br/>
Create an instance of the class defined in the previous step, and register it with a
<code>LifecycleExtensionManager</code>, using either the default manager available inside
of your container, or an externally created manager that is later given to the container
to use.
</li>
<li>Implement the new component interface on your component<br/>
Add the new <code>implements</code> clause to your Component, or Component implementation,
and write any methods defined in the implemented interface.
</li>
<li><code>lookup()/select()/release()</code> components as normal<br/>
Proceed as normal. Checking for extensions is done implicitly within Fortress. Once
lifecycle extensions are registered they will be invoked on any implementing components
during the 4 phases defined later in this document.
</li>
</ol>
</section>
<section name="When can a Component's lifecycle be extended ?">
<p>
The life of any component can be broken down to the following phases:
</p>
<ol>
<li>Creation<br/>
When the Component is actually instantiated.
</li>
<li>Access<br/>
When the Component is accessed via a ComponentManager/Selector
(<code>lookup()/select()</code>).
</li>
<li>Release<br/>
When the Component is released via a ComponentManager/Selector (<code>release()</code>).
</li>
<li>Destruction<br/>
When the Component is decommissioned, ready for garbage collection.
</li>
</ol>
<p>A Component will go through it's Creation and Destruction phase only once. Since
<code>ComponentHandler</code> classes can implement different handling strategies
(Poolable, ThreadSafe, etc), the access and release phases of a component can be
done multiple times.</p>
<p>
Lifecycle extensions can be added to any of the above defined phases. This allows
you to choose when your particular extension will be executed.
</p>
<p>
For example, thread or user dependent extensions would be added at the access and release
levels (ie. when the component is retrieved and returned to the ComponentManager) as they
depend on runtime data not available until they are actually used.
</p>
<p>
More static, or global extensions would be added at the creation or destruction level, since
they do not depend on any external data that change during runtime, nor are they particular
to any one context of use.
</p>
</section>
<section name="Which interfaces and classes do I need to use ?">
<p>
Support for lifecycle extensions in Fortress is done using the following classes/interfaces.
</p>
<subsection name="The Component Extension Interface">
<p>
This interface specifies the business particular extension components will be tested for.
It defines the new interface that components will implement to receive additional
functionality.
</p>
<p>
There is no particular base interface the developer needs to extend, and the interface
can be kept separate from the Container itself.
</p>
</subsection>
<subsection name="The LifecycleExtension Interface">
<p>
Component extensions are invoked via a Lifecycle extension object. Lifecycle extension
objects are managed via a <code>LifecycleExtensionManager</code> class and essentially
test for a particular Component extension interface, and appropriately call methods defined
in that interface.
</p>
<p>
All Lifecycle extension objects must implement the <code>LifecycleExtension</code> interface.
The <code>LifecycleExtension</code> interface defines 4 methods that are called upon to allow
an implementor to extend a component's lifecycle.
</p>
<p>
The 4 methods (<code>create</code>, <code>destroy</code>, <code>access</code> and
<code>release</code>) are invoked by a manager class from inside Fortress. Each method
accepts 2 parameters, the particular Component instance being extended, and the container
<code>Context</code>.
</p>
<p>
The container <code>Context</code> is passed as a parameter to provide access to any
miscellaneous objects that might be needed during extension code (to make use of this feature
the container Context will need to be initialized with references and passed to the
<code>FortressConfig</code> during Fortress' startup sequence).
</p>
<p>
Each method may throw an exception to indicate an error, which will be logged, but will
not terminate other extensions from being executed on that Component.
</p>
<source>
/**
* LifecycleExtension interface. This interface defines the methods that
* a LifecycleExtensionManager can call on a particular concrete
* LifecycleExtensionMarker class.
*/
public interface LifecycleExtension
{
/**
* Create, called when the given component is being
* instantiated.
*
* @param component a Component instance
* @param context a Context instance
* @exception Exception if an error occurs
*/
void create( Object component, Context context )
throws Exception;
/**
* Destroy, called when the given component is being
* decommissioned.
*
* @param component a Component instance
* @param context a Context instance
* @exception Exception if an error occurs
*/
void destroy( Object component, Context context )
throws Exception;
/**
* Access, called when the given component is being
* accessed (ie. via lookup() or select()).
*
* @param component a Component instance
* @param context a Context instance
* @exception Exception if an error occurs
*/
void access( Object component, Context context )
throws Exception;
/**
* Release, called when the given component is being
* released (ie. by a CM or CS).
*
* @param component a Component instance
* @param context a Context instance
* @exception Exception if an error occurs
*/
void release( Object component, Context context )
throws Exception;
}
</source>
<p>
Many extensions will not require implementation of every method defined in the
above interface, for that reason, there's a <code>AbstractLifecycleExtension</code>
convenience class available which provides default (empty) implementations of each
method which you can extend from. This allows you to implement only the methods
necessary for your particular extension.
</p>
</subsection>
<subsection name="The LifecycleExtensionManager class">
<p>
The <code>LifecycleExtensionManager</code> class provides default management of
extension implementations and an API which ComponentManager/Selector's can call
upon to execute them.
</p>
<p>
The LifecycleExtensionManager class API is too big to list here, instead please look at
the following <link href="http://avalon.apache.org/excalibur/fortress/api/org/apache/excalibur/fortress/lifecycle/LifecycleExtensionManager.html">link</link>. It essentially defines
4 methods for executing extension objects at the various phases of a component's lifecycle,
and several methods for registering extension objects with the manager.
</p>
<p>
The <code>LifecycleExtensionManager</code> class will operate safely in multithreaded
environments, and allows you to add/remove extensions to a running system.
</p>
<p>
By default, all Fortress based containers will be initialized with a default
<code>LifecycleExtensionManager</code> that contains no extensions. You can alternatively
provide a pre-configured LifecycleExtensionManager to your Container via the
FortressConfig class (<code>ContainerConstants.EXTENSION_MANAGER</code> key) if you like.
</p>
<p>
To add a new lifecycle extension object to the manager simply call the method
<code>LifecycleExtensionManager.addExtension()</code>. Methods also exist for removing
and iterating through the currently available extensions.
</p>
</subsection>
<subsection name="FortressComponentManager/FortressComponentSelector">
<p>
Fortress' inbuilt Component Manager/Selector/Factory code will automatically call
upon the LifecycleExtensionManager class at each phase in a Component's life at the
following predefined times:
</p>
<ol>
<li>Access<br/>
Called inside the ComponentManager, after the component has been retrieved
from it's handler, but before it's returned to the invoker of
<code>lookup()/select()</code>.
</li>
<li>Release<br/>
Called inside the ComponentManager, before the component is passed back to
it's handler to be disposed/pooled/etc.
</li>
<li>Creation<br/>
Called inside the ComponentFactory, before <code>initialize()</code>.
</li>
<li>Destruction<br/>
Called inside the ComponentFactory, after <code>dispose()</code>.
</li>
</ol>
<note>, components created via Fortress' ComponentHandler classes directly
will bypass the logic for <code>access</code> and <code>release</code> extensions. This is
because the code performing this logic is located in the ComponentManager/Selector classes
(independent from all handlers).</note>
</subsection>
</section>
<section name="An Example">
<p>
Let's look at a simple example. The following is also available as a working sample
in Fortress' examples directory.
</p>
<p>
Our example implements a Lifecycle extension for passing a <code>SecurityManager</code> to
Components. We'll call it the <code>SecurityManageable</code> interface.
</p>
<subsection name="Define the component extension interface">
<p>
First we define the new Component extension interface.
</p>
<source>
/**
* Simple custom lifecycle extension interface for supplying a component
* with a security manager.
*/
public interface SecurityManageable
{
/**
* Pass a SecurityManager object to the component
*
* @param manager a SecurityManager value
*/
void secure( SecurityManager manager )
throws SecurityException;
}
</source>
</subsection>
<subsection name="Create the lifecycle extensions class">
<p>
Next we define the actual extension implementation which invokes the <code>secure()</code>
method. We extend from <code>AbstractLifecycleExtension</code> since we only want
<code>secure()</code> to be invoked upon each access (ie. lookup()) to the component, and
don't need to implement the other 3 LifecycleExtension methods (create, release, and
destroy).
</p>
<source>
/**
* Some custom extensions for this container's components.
*/
public class Extensions
extends AbstractLifecycleExtension
{
/**
* Access, called when the given component is being
* accessed (ie. via lookup() or select()).
*
* @param component a Component instance
* @param context a Context instance
* @exception Exception if an error occurs
*/
public void access( Object component, Context context )
throws Exception
{
if ( component instanceof SecurityManageable )
{
// pass in a simple security manager, a real system might want to pass
// in specialized/custom security managers
( ( SecurityManageable ) component ).secure( new SecurityManager() );
}
}
}
</source>
</subsection>
<p>An extension class may run components through any given number of
extensions, and are not limited to just one.</p>
</section>
<section name="Register the lifecycle extensions class">
<p>
We then inform our container about the extension. This could be done in several different
ways, for simplicity we'll extend <code>initialize()</code> and add it to the
<code>LifecycleExtensionManager</code> there.
</p>
<p>
(an alternative might be to initialize a LifecycleExtensionManager before creating the
container and pass it in via the <code>FortressConfig.setExtensionManager()</code> method,
or to create a LifecycleExtensionManager subclass that includes the extension preset)
</p>
<source>
/**
* Simple container that includes custom lifecycle extensions.
*/
public final class ExtendedContainer
extends AbstractContainer
{
public void initialize()
throws Exception
{
super.initialize();
m_extManager.addExtension( new Extensions() );
}
}
</source>
</section>
<section name="Use the new component interface">
<p>
To use the new SecurityManageable lifecycle extension, we simply implement
SecurityManageable just as we do with any other Avalon lifecycle interfaces
(assuming a predefined Component interface <code>ExtendedComponent</code>).
</p>
<source>
/**
* ExtendedComponentImpl, demonstrating the use of a custom
* lifecycle stage SecurityManageable. This code does
* a simple access check for several files on the file system and logs
* the results accordingly.
*/
public class ExtendedComponentImpl
extends AbstractLogEnabled
implements ExtendedComponent, SecurityManageable
{
/**
* Pass a SecurityManager object to the component
*
* @param manager a SecurityManager value
*/
public void secure( final SecurityManager manager )
throws SecurityException
{
getLogger().info( "Received SecurityManager instance: " + manager );
final String[] files = { "/tmp", "/vmlinuz", "/usr/lib/libc.a" };
for ( int i = 0; i < files.length; ++i )
{
try
{
manager.checkRead( files[ i ] );
getLogger().info( "Thread can read " + files[ i ] );
}
catch ( SecurityException e )
{
getLogger().info( "Thread can not read " + files[ i ] );
}
}
}
}
</source>
</section>
<section name="Need more information?">
<p>
If you have any particular questions, comments, etc, please send an email to the Avalon
developer mailing <link href="mailto:dev@avalon.apache.org">list</link>.
</p>
</section>
</body>
</document>
1.1 avalon/fortress/new/xdocs/navigation.xml
Index: navigation.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<project href="http://avalon.apache.org/fortress"
name="Avalon Fortress">
<title>Avalon Fortress</title>
<body>
<links>
<item name="Apache" href="http://apache.org/"/>
<item name="Avalon" href="http://avalon.apache.org/"/>
<item name="Framework" href="http://avalon.apache.org/product/framework/"/>
<item name="Containers" href="http://avalon.apache.org/product/containers/"/>
<item name="Components" href="http://avalon.apache.org/product/components/"/>
</links>
<menu name="About Fortress">
<item name="Overview" href="/index.html"/>
<item name="Features Oriented" href="/features.html"/>
<item name="Getting Started" href="/getting-started.html"/>
<item name="Using Meta Info" href="/using-meta-info.html"/>
<item name="Download" href="http://avalon.apache.org/download.cgi"/>
</menu>
<menu name="Environment">
<item name="CLI" href="/cli.html"/>
<item name="Swing" href="/swing.html"/>
<item name="Servlet" href="/servlet.html"/>
</menu>
<menu name="Resources">
<item name="API" href="/api/index.html"/>
<item name="Lifecycle Extensions" href="/lifecycle-extensions.html"/>
<item name="Design Notes" href="/design-notes.html"/>
</menu>
</body>
</project>
1.1 avalon/fortress/new/xdocs/servlet.xml
Index: servlet.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<document>
<properties>
<title>Fortress Getting Started</title>
<author email="dev@avalon.apache.org">Avalon Documentation Team</author>
</properties>
<body>
<section name="Servlet Based Applications">
<p>
Servlet based applications are viewed on the web. Examples of these
types of Java projects are Jakarta Turbine, and Apache Cocoon.
Servlets have their own lifecycle, so it is rather easy to tie the
life of a container to the life of a servlet.
</p>
<p>
Servlet based applications can either tie the Avalon container to
a Servlet or bind it to JNDI. The advantage of binding it to JNDI is
better resource management because the container is not being torn
down and rebuilt periodically. The disadvantage is that there is no
standard way of doing it in your Servlet container. Most of the time
we bind the container to a Servlet like the following code:
</p>
<source>
<![CDATA[
public class MyAvalonServlet implements HttpServlet
{
private static final String ROOT =
"resource://org/apache/excalibur/fortress/examples/servlet/";
private static final String XCONF =
ROOT + ServletContainer.xconf";
private static final String XLOG =
ROOT + ServletContainer.xlog";
private static final String ROLES =
ROOT + ServletContainer.roles";
private MyServletContainer m_container;
private ContainerManager m_containerManager;
/**
* Initializes Servlet and creates a <code>ServletContainer</code> instance
*
* NOTE: this is the servlet init code.
*
* @exception ServletException if an error occurs
*/
public void init()
throws ServletException
{
super.init();
try
{
final FortressConfig config = new FortressConfig();
config.setContainerClass(
"org.apache.avalon.fortress.examples.servlet.ServletContainer" );
config.setContextDirectory( "./" );
config.setWorkDirectory( "./" );
config.setContainerConfiguration( XCONF );
config.setLoggerManagerConfiguration( XLOG );
config.setRoleManagerConfiguration( ROLES );
m_containerManager =
new DefaultContainerManager( config.getContext() );
ContainerUtil.initialize(m_containerManager);
m_container =
(ServletContainer)m_containerManager.getContainer();
}
catch( Exception e )
{
throw new ServletException( "Error during initialization", e );
}
}
/**
* Pass all servlet requests through to container to be handled. In a more
* complex system, there could be multiple containers that handle different
* requests, or a main controlling container with subcontainers for different
* requests.
*
* @param request a <code>ServletRequest</code> instance
* @param response a <code>ServletResponse</code> instance
* @exception IOException if an IO error occurs
* @exception ServletException if a servlet error occurs
*/
public void service( ServletRequest request, ServletResponse response )
throws IOException, ServletException
{
m_container.handleRequest( request, response );
}
/**
* Disposes of container manager and container instance.
*
* NOTE: This is the Servlet destruction callback
*/
public void destroy()
{
ContainerUtil.dispose(m_containerManager);
}
}
]]>
</source>
</section>
</body>
</document>
1.1 avalon/fortress/new/xdocs/swing.xml
Index: swing.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<document>
<properties>
<title>Fortress Getting Started</title>
<author email="dev@avalon.apache.org">Avalon Documentation Team</author>
</properties>
<body>
<section name="Swing Based Applications">
<p>
Swing applications are those applications that have a lovely graphical
interface for you to interact with. When you are done with the
application, you close it and are done with it. Some examples of a
Swing based application include Apache JMeter, JEdit, and Avalon
Instrument Client.
</p>
<p>
Swing applications are very similar to CLI based applications in the
way they are set up and torn down. What differs is that the GUI runs
in a different set of threads, so the main routine has to wait until
the GUI is done. There are two strategies to do that. The first is
to extend the DefaultContainer and use that to enclose your Swing
based JFrame and implement the Runnable interface. The second is to
manage the Swing GUI separately, but give your container or its
ServiceManager to the Swing code to interact with.
</p>
<subsection name="Extending DefaultContainer">
<p>
If we extend the DefaultContainer, our main method will look pretty
much the same:
</p>
<source>
<![CDATA[
public int main(String [] args)
{
// You would have to implement the referenced method here...
FortressConfig config = configWithArgs( args );
ContainerManager cm = new DefaultContainerManager( config.getContext() );
ContainerUtil.initialize( cm );
// Get the root container and use it
((MySwingContainer) cm.getContainer()).run();
// Clean up after ourselves
ContainerUtil.dispose( cm );
}
]]>
</source>
<p>
The extensions to DefaultContainer that you do are different for
each application. However, they will have some common elements.
Here is an excerpt from both the Swing example and the Viewer
example included in CVS.
</p>
<source>
<![CDATA[
public class MySwingContainer extends DefaultContainer implements Runnable
{
JFrame m_frame = new JFrame();
// skipping non relevant parts
public void run()
{
while ( m_frame.isVisible() )
{
try
{
Thread.sleep(1000);
}
catch (InterruptedException ie)
{
// you can either ignore the exception or you can
// close the application. Remove the next line
// if you don't want to end the application:
m_frame.setVisible( false );
}
}
}
}
]]>
</source>
</subsection>
</section>
</body>
</document>
1.1 avalon/fortress/new/xdocs/using-meta-info.xml
Index: using-meta-info.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<document>
<properties>
<title>Excalibur Fortress - Using Meta Info</title>
<author email="dev@avalon.apache.org">Avalon Documentation Team</author>
</properties>
<body>
<section name="What is Meta Information?">
<p>
Meta Information is information about your components. The information that
Fortress needs to properly manage your components is fairly small. It needs to
know which classes are components, which services that component implements, what
its dependencies are, and what type of lifestyle the component was designed for.
Using this information, Fortress can determine if there are some circular
dependencies as well as manage other aspects of your component.
</p>
<p>
Your container has to find the meta information in some way. If you are used
to the Excalibur Component Manager (ECM), then you supplied the meta information
based on a "roles" file and certain marker interfaces that your component
implemented. There are several drawbacks to this approach, some of which include
inheritance of conflicting meta information and having to manage your information
in separate files.
</p>
<p>
Fortress has adopted a practice that is available in both Phoenix and Merlin to
make managing meta information a breeze. It is the use of JavaDoc tags to mark the
meta information right with the source code itself. This scheme works much better,
and unlocks some features to you. One of them is for Fortress to tell you that you
have a circular dependency (some components that require each other to work) at
initialization time instead of at run time.
</p>
</section>
<section name="How does the Meta Info Tags Look?">
<p>
The best way to demonstrate how these tags look and behave is to show some sample
code. Fortress follows the AMTAGS proposal on the WIKI, and also supports a couple
extra tags. Specifically, the set of tags that Fortress supports are
"avalon.dependency", "avalon.service", "x-avalon.info", "x-avalon.lifestyle",
"avalon.component", "fortress.name", "fortress.handler". The two Fortress specific
tags are recognized, but are not encouraged for routine use.
</p>
<p>
Everything except for the "avalon.dependency" must be specified in the component's
class JavaDoc. Below is a snippet:
</p>
<source>
<![CDATA[
/**
* My component implementation.
*
* @avalon.component
* @avalon.service type="RoleInterface"
* @x-avalon.info name="my-component"
* @x-avalon.lifestyle type="pooled"
*/
public class MyComponent implements RoleInterface
{
// ....
}
]]>
</source>
<p>
The "avalon.component" is a marker tag, and it is required to mark a class as a
component. You must have one or more "avalon.service" tags (one per interface
type). The value in the "type" attribute must be a resolvable class name. If the
type of "RoleInterface" is in the same package, or in one of the imports, then all
is well. The "x-avalon.info" tag is used to provide a configuration name for the
component. In this case, the configuration name is "my-component". If you do not
supply this tag, Fortress will create one for you based on the class name of the
component. It is best if you supply your own. The "x-avalon.lifestyle" tag is
used to choose how this component is managed.
</p>
<p>
Dependencies are declared in the <code>service()</code> method for the component.
The component needs to implement the Serviceable interface. Fortress knows how
to look at the code hierarchy to collect all the dependencies as long as you have
all your source code available. The dependency declarations look like this:
</p>
<source>
<![CDATA[
/**
* Get all the dependencies.
*
* @avalon.dependency type="OtherService"
* @avalon.dependency type="Foo"
*/
public void service( ServiceManager manager )
{
// ...
}
]]>
</source>
<p>
All the "avalon.dependency" entries are collected by the same rules as the
"avalon.service" entries. In other words, the "type" attribute is evaluated
based on the same rules as your Java compiler evaluates them. Fortress will
take care of resolving them properly.
</p>
</section>
<section name="Collecting the Meta Information">
<p>
Fortress provides an ANT task to collect all your meta information and generate
the extra files that your JAR files need to have for Fortress to use the meta
information at run time. You include the ANT task in your build.xml file like
this:
</p>
<source>
<![CDATA[
<project>
<!-- ... -->
<taskdef name="collect-metainfo"
classname="org.apache.avalon.fortress.tools.ComponentMetaInfoCollector">
<classpath refid="tools.class.path"/>
</taskdef>
<target name="compile" depends="jar-tools" description="Compiles the source code">
<mkdir dir="${build.classes}"/>
<!-- Compile all classes excluding the tests. -->
<javac srcdir="${java.dir}"
destdir="${build.classes}">
<classpath>
<path refid="tools.class.path"/>
<pathelement location="${loader.classes}"/>
</classpath>
<include name="**/*.java"/>
</javac>
<collect-metainfo destdir="${build.classes}">
<fileset dir="${java.dir}"/>
</collect-metainfo>
</target>
<!-- ... -->
</project>
]]>
</source>
<p>
Once you include all the generated files in your JAR for the components, you
don't have to do anything more than include the JAR in your classpath for Fortress.
Everything else is taken care of.
</p>
</section>
<section name="The x-avalon.lifestyle Tag">
<p>
The "x-avalon.lifestyle" tag needs a little further explanation. It can have one
of four values in the "type" attribute:
</p>
<ul>
<li><strong>singleton</strong> One instance of the component shared with all clients.</li>
<li><strong>thread</strong> One instance of the component per thread of execution.</li>
<li><strong>pooled</strong> One instance of the component per request, with instances reused from a pool.</li>
<li><strong>transient</strong> One instance of the component per request, with instances destroyed on release.</li>
</ul>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: cvs-unsubscribe@avalon.apache.org
For additional commands, e-mail: cvs-help@avalon.apache.org