Return-Path: Delivered-To: apmail-incubator-directory-cvs-archive@www.apache.org Received: (qmail 569 invoked from network); 27 Jan 2004 04:49:08 -0000 Received: from daedalus.apache.org (HELO mail.apache.org) (208.185.179.12) by minotaur-2.apache.org with SMTP; 27 Jan 2004 04:49:08 -0000 Received: (qmail 68445 invoked by uid 500); 27 Jan 2004 04:47:48 -0000 Delivered-To: apmail-incubator-directory-cvs-archive@incubator.apache.org Received: (qmail 61515 invoked by uid 500); 27 Jan 2004 04:46:21 -0000 Mailing-List: contact directory-cvs-help@incubator.apache.org; run by ezmlm Precedence: bulk Reply-To: directory-dev@incubator.apache.org list-help: list-unsubscribe: list-post: Delivered-To: mailing list directory-cvs@incubator.apache.org Received: (qmail 55091 invoked from network); 27 Jan 2004 04:44:55 -0000 Received: from unknown (HELO minotaur.apache.org) (209.237.227.194) by daedalus.apache.org with SMTP; 27 Jan 2004 04:44:55 -0000 Received: (qmail 56819 invoked by uid 65534); 27 Jan 2004 04:20:52 -0000 Date: 27 Jan 2004 04:20:52 -0000 Message-ID: <20040127042052.56817.qmail@minotaur.apache.org> From: akarasulu@apache.org To: directory-cvs@incubator.apache.org Subject: svn commit: rev 6313 - in incubator/directory/sitedocs/trunk/sitedocs: . src src/etc xdocs xdocs/community xdocs/community/history xdocs/community/process xdocs/community/who xdocs/developing xdocs/doc xdocs/images xdocs/product xdocs/product/components xdocs/product/containers xdocs/product/framework xdocs/related xdocs/sandbox X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N Author: akarasulu Date: Mon Jan 26 20:20:51 2004 New Revision: 6313 Added: incubator/directory/sitedocs/trunk/sitedocs/ incubator/directory/sitedocs/trunk/sitedocs/maven.xml incubator/directory/sitedocs/trunk/sitedocs/project.properties incubator/directory/sitedocs/trunk/sitedocs/project.xml incubator/directory/sitedocs/trunk/sitedocs/src/ incubator/directory/sitedocs/trunk/sitedocs/src/etc/ incubator/directory/sitedocs/trunk/sitedocs/src/etc/site.jsl incubator/directory/sitedocs/trunk/sitedocs/xdocs/ incubator/directory/sitedocs/trunk/sitedocs/xdocs/.htaccess incubator/directory/sitedocs/trunk/sitedocs/xdocs/.navigation.xml.swp (contents, props changed) incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/ incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/history/ incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/history/changes.txt incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/history/index.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/history/navigation.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/index.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/navigation.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/ incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/code-standards.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/development.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/index.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/mission.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/navigation.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/patches.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/pmc-votes.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/pmc.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/release.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/who/ incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/who/akarasulu.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/who/index.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/who/mcconnell.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/who/navigation.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/cvs.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/ incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/authors.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/compatiblity.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/conclusion.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/decomposing.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/framework.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/implementing.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/index.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/introduction.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/navigation.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/strategies.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/doc/ incubator/directory/sitedocs/trunk/sitedocs/xdocs/doc/articles.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/doc/index.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/doc/navigation.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/doc/wiki.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/download.cgi incubator/directory/sitedocs/trunk/sitedocs/xdocs/download.html incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/ incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/apache-avalon-logo.png (contents, props changed) incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/avalon-logo.svg incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/avalon-power.png (contents, props changed) incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/deployment.gif (contents, props changed) incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/group-logo.gif (contents, props changed) incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/icon.png (contents, props changed) incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/merlin.gif (contents, props changed) incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/project-logo.gif (contents, props changed) incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/server-01.gif (contents, props changed) incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/server-02.gif (contents, props changed) incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/server-03.gif (contents, props changed) incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/server-04.gif (contents, props changed) incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/tortoise-cvs-screenshot.gif (contents, props changed) incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/tortoisecvs-checkout.jpg (contents, props changed) incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/tortoisecvs-settings.jpg (contents, props changed) incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/wincvs-checkout.jpg (contents, props changed) incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/wincvs-preferences.jpg (contents, props changed) incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/wincvs-settings.jpg (contents, props changed) incubator/directory/sitedocs/trunk/sitedocs/xdocs/index.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/license.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/mailing-lists.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/navigation.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/news.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/ incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/components/ incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/components/index.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/components/navigation.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/containers/ incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/containers/index.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/containers/navigation.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/framework/ incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/framework/index.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/framework/navigation.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/index.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/navigation.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/related/ incubator/directory/sitedocs/trunk/sitedocs/xdocs/related/apache.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/related/external.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/related/index.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/related/navigation.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/related/powered.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/sandbox/ incubator/directory/sitedocs/trunk/sitedocs/xdocs/sandbox/index.xml incubator/directory/sitedocs/trunk/sitedocs/xdocs/sandbox/navigation.xml Log: mainly this is a copy of the Avalon site - I'll change it gradually Added: incubator/directory/sitedocs/trunk/sitedocs/maven.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/maven.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,54 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Added: incubator/directory/sitedocs/trunk/sitedocs/project.properties ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/project.properties Mon Jan 26 20:20:51 2004 @@ -0,0 +1,5 @@ +maven.xdoc.date=left +maven.ui.banner.background=#FFFFFF +maven.xdoc.includeProjectDocumentation=no +maven.xdoc.poweredby.image= +maven.xdoc.jsl = file:/${basedir}/src/etc/site.jsl Added: incubator/directory/sitedocs/trunk/sitedocs/project.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/project.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,61 @@ + + + 3 + directory + directory-sitedocs + Apache Directory + + + The Apache Directory Project + http://www.apache.org/~akarasulu/directory + /images/apache-avalon-logo.png + + + 2003 + org.apache.directory.sitedocs + http://www.apache.org/~akarasulu/directory + + + http://nagoya.apache.org/jira/secure/BrowseProject.jspa?id=10400 + + cvs.apache.org + /home/akarasulu/public_html/directory + + /home/akarasulu/public_html/directory/dist + + + Apache Directory Project + + + Long Directory Project description from inside POM. + + + + + Directory Developer List + + directory-dev-subscribe@incubator.apache.org + + + directory-dev-unsubscribe@incubator.apache.org + + + http://nagoya.apache.org/eyebrowse/SummarizeList?listId=181 + + + + + + + + + Apache 1.1 License + +http://cvs.apache.org/viewcvs.cgi/incubator/directory/LICENSE.txt?rev=1369&root=Apache-SVN&view=markup + + repo + + + + + Added: incubator/directory/sitedocs/trunk/sitedocs/src/etc/site.jsl ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/src/etc/site.jsl Mon Jan 26 20:20:51 2004 @@ -0,0 +1,631 @@ + + + + + + + + + + ${maven.xdoc.date} + + + + + + + + + + + + + <x:expr select="$nav/title"/> - ${docTitle} + + + + ${pom.name} - ${docTitle} + + + + + + + + + + + + + + + + + + + + + + + composite + + ${attr.value} + + + + + + + + + + + +
+ + +
+ +
+ + + + + + + +
+
+
+ + + + + + + + + + + + +
+ + +
+ + + + + + + + +
+ + + + + + + + + + + +
+ + + + + + + | + + + + + + + + + + + + +
+ Search ${pom.name} +
+ + Google +

+ + + + + + + + + + + +

+ + + + +
+ + +

+ ${_sectionName} +

+ + +
+ + + +
+ + +

+ ${_sectionName} +

+ + +
+ + + +
+
+
+ + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + + ${rowMode} + + ${attr.value} + + + + + + + + + + + + + + +
+ +

+ + + + + + + + +

+

Goals

+ + + +
GoalDescription
+
+ + + + + + + + + + + + + + + + ${rowMode} + + ${_goalName} + + + + + + + + + + + + + + + + + + + + +
DateAuthorFiles/Message
+ + + + + + + + + + + + + + + + ${rowMode} + + + + +
+ + + + + + ${pom.repository.url} + ${url}?&content-type=text/vnd.viewcvs-markup + - + v +
+ + + + + + + + + + + + + + + + + + + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/.htaccess ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/.htaccess Mon Jan 26 20:20:51 2004 @@ -0,0 +1,7 @@ +RedirectMatch ^/apps(.*) http://avalon.apache.org/phoenix/applications.html +RedirectMatch ^/sandbox/meta(.*) http://avalon.apache.org/meta +RedirectMatch ^/sandbox/merlin(.*) http://avalon.apache.org/merlin +RedirectMatch ^/sandbox/api(.*) http://avalon.apache.org/merlin/api +RedirectMatch ^/cornerstone(.*) http://avalon.apache.org/components +RedirectMatch ^/merlin/starting/installation/3.0(.*) http://avalon.apache.org/merlin/starting/installation +RedirectMatch ^/merlin/starting/installation/3.2(.*) http://avalon.apache.org/merlin/starting/installation Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/.navigation.xml.swp ============================================================================== Binary file. No diff available. Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/history/changes.txt ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/history/changes.txt Mon Jan 26 20:20:51 2004 @@ -0,0 +1,202 @@ + + + + Avalon History of Changes + + + + + + + + Added in DataSource implementation for use with J2EE style apps. + + + Added the notion of ServerApplication to replace the concept of .bar as a server. + A ServerApplication is a isolated environment that manages it's own threads, + security, logging, classloading etc. It has a specific layout as documented + in Assembly guide. The kernel was refactored to contain ServerApplications + rather than Blocks and a lot of support was refactored to support safe separation + of ServerApplications. The archives are in .sar format and are similar in many + aspects to .war of servlet fame. + + + Refactored thread management so specific thread pools can assigned to specific + threads/thread groups in a manner similar to how ContextClassLoader is associated + with threads. Thread management was also moved to a new package + (org.apache.avalon.util.threads). + + + Modify the packaging of all kernel related files into org.apache.phoenix. + + + Modify the packaging of all blocks/services/demos into package hierarchy + org.apache.cornerstone. + + + Added two new services/blocks by refactoring code from tomcat and old SocketServer. + There is now a SocketManager and a ConnectionManager. The TLS code is now much improved + and there is the beginning of client socket factory. This provides for future client + socket code factories for SSL/TLS or SSH1/2 etc. Also adapted SimpleServer to use + these methods. + + + Changed config file from per .bar to per .sar and changed name from BAR-INF/< + barname>.conf.xml to conf/assembly.xml. It still contains configuration data as + well as assembly data but this will be removed in a future revision. + + + Added an extra config file to .sar (conf/server.xml) that is responsible for + configuring .sar wide variables. Some examples include security, logging and thread loading. + + + Refactored most of the code to use AbstractLoggable and the corresponding getLogger() + method. Also removed the remaining static access to LogKit. + + + Continued to refine the Camelot API. + + + Removed blockdefs.properties in favour of adding attributes to manifest entries of jars. + This should enable future GUI tools to easily assemble blocks. + + + Re-Added the sub-classed context BlockContext to allow blocks full access to important + environmental information. + + + Many of the lifecycle methods now have a chance to fail by throwing an exception. + + + Removed all notion of kernel configurability. + + + Enabled securityManager by default and now ServerApplications have to specify a security + policy. + + + Removed classloader hack in ObjectStorageRepository as it is no longer required with + new .sar format. + + + Homogenized the remaining code to follow one style. + + + Configuration temporarily will create new Configuration objects on getChild() if they + don't exist until Berin's work is finalized. + + + Altered Compose so that it threw ComponentManagerException of which the previous two + exceptions thrown are now subclasses. + + + Made loading of jars relative to avalon-loader.jar rather than via current working + directory so that some tools (ie VAJava) would not complain. + + + Separated out tools directory/jars from main jars that avalon uses. + + + A number of bug fixes and more descriptive exceptions for Configuration and Parameters + objects. + + + + + + Made SocketManager accept arbitrary SocketServer.Listener objects. + + + Updated all blocks to use new system level logging. + + + Changed Threads so that it is now a system level service. + + + Added new LogManager that manages arbitrary log categories. + + + Added the BlockInfo requirement. Thus blocks need to have an XML file that describe the + services it offers, the services it depends upon and other meta information. + + + Added support for Blocks to implement BlockContextualizable. If they do this the kernel + will pass them Context information. Currently the context information is limited to + a handle to kernel instance and the name they were configured under. + + + Changed SimpleContext and SimpleComponentManager to DefaultComponent and + DefaultComponentManager to match better with other Avalon design patterns. + + + Added functionality that allowed you to listen to BlockEvents generated by kernel. + Events indicate when a Block is being created, initialized, composed, destroyed, ran and + stopped. + + + Updated Logger interface so arbitrary integer levels are not allowed to be passed. The user + is forced to use defined enumerants. This was done to increase safety. + + + Updated kernel so that is now delegates to AvalonKernelConfigurator to configure itself. + + + Updated kernel so that it is now pluggable. Any kernel can be loaded via the code in main. + Kernel configuration files are loaded from default configuration directory in a file + with same name as class with a .conf.xml appended. + + + Removed getDescription method from Block as it is to become part of BlockInfo + + + Change methods in Configure/Reconfigure to throw ConfigurationExceptions. + + + Change methods in Configure/Reconfigure to match Java standards. + + + Add to the Logger log level support. + + + JNDI for the lookup of blocks and components. Still keep the + Composer interface for those lightweight blocks that don't + need the extra features of the Context. JNDI should be the + ComponentManager of choice. + + + Synchronized Avalon with Cocoon 2 enhancements. Uses SAX 2 for + configuration, incorporated abstract and base classes for fundamental + types, and incorporated the NamedComponent interface. + + + Upgraded Loader architecture and the AvalonClassLoader to provide + better detail, as well as new ways of configuring the loader at the + beginning. It does not require any extra libraries to load. + + + + + + Changed the Acceptor pattern to a more flexible event provider. + + + Added a TimeServer to easily manage time events. + + + Make Store implementation more pluggable. + + + + + + Updated Context pattern to Configurable-Composer pattern. + + + + + + First Avalon implementation. + + + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/history/index.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/history/index.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,28 @@ + + + + Alex Karasulu + Apache Directory Project: Community History + + + + +
+ +

+ This document tracks the history of the Directory project. The + Directory project was originally started with the need for a + Java LDAP Server. Explain more history. +

+ +

+ Over time the Java ... +

+

+ Project changes are documented here. +

+ +
+ + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/history/navigation.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/history/navigation.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,54 @@ + + + + + Apache Avalon + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/index.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/index.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,47 @@ + + + + Alex Karasulu + Apache Directory: Community + + + +
+ + + + + + + + + + + + + + + +
TopicDescription
Who We Are +

+ These pages list many of the contributors to directory. They + have worked and are working long and hard to make quality + software for the rest of the world to use. Contributors to the + Directory Project should be extremely proud of themselves! If you + would like to become a contributor, please see the Get Involved + document to figure out how. If you are a contributor but are not + listed, submit a patch! +

+
Process +

+ The Apache Directory Project, like all other projects at Apache, is a + meritocracy and follows the Apache Way of + community and project management. This page contains a bunch of + references to the structure, operation and process aspects that + help us maintain project oversight. +

+
Historical

Background content - how Apache Directory came to be.

+ +
+ + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/navigation.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/navigation.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,50 @@ + + + + + Apache Avalon + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/code-standards.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/code-standards.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,195 @@ + + + + Alex Karasulu + Apache Directory Project: Coding Standards + + +
+

This document describes a list of coding conventions that are required + for code submissions to the project. By default, the coding conventions + for most Open Source projects should follow the existing coding conventions + in the code that you are working on. For example, if the bracket is on + the same line as the if statement, then you should write all your code + to follow that convention.

+ +

Please follow these conventions closely. It makes life so much +easier.

+ +

Brackets should begin and end on a new line. Examples:

+ + +if( foo ) +{ + // code here +} + +try +{ + // code here +} +catch( final Exception bar ) +{ + // code here +} +finally +{ + // code here +} + +while( true ) +{ + // code here +} + + + +

The preference is to include extra spaces between parenthesis and expression. +For example; +

+ + +if( foo ) + + +

4 spaces. NO tabs. Period. We understand that a lot of you like +to use tabs, but the fact of the matter is that in a distributed development +environment, when the cvs commit messages get sent to a mailing list, they +are almost impossible to read if you use tabs.

+ +

In Emacs-speak, this translates to the following command:

+ +(setq-default tab-width 4 indent-tabs-mode nil) + +

In vim, having the following in your .vimrc will help:

+ +set tabstop=4 +set expandtab +set list +set listchars=tab:>. + + +

Unix linefeeds for all .java source code files. Other platform specific +files should have the platform specific linefeeds.

+ +

Javadoc SHOULD exist on all your methods. Also, if you are working +on existing code and there currently isn't a javadoc for that method/class/variable +or whatever, then you should contribute and add it. This will improve the +project as a whole.

+ +

The Jakarta Apache/Avalon License MUST be placed at the top +of each and every file.

+ +

If you contribute to a file (code or documentation), add yourself to the +top of the file. For .java files the preferred Javadoc format is:

+ + +@author <a href="mailto:user@domain.com">John Doe</a> + + +

Indent comments on an 80 column basis and the code on a + 100 column basis, using two more indents when a line must be wrapped.

+ +

We focus on readability over performance, at least initially. Source code +optimization is the last thing to be done to increase performance. +If the code is not performing then it is better to re-engineer it rather +than to expand loops, take out variable declarations etc. When the code +is stable and has a well defined purpose and interface it may be appropriate +to do source code optimization.

+ +

Try to javadoc all methods and variables, especially public, protected +and default access methods and member variables. Also add code comments +when you think it's necessary (like assumptions).

+ +

Variables are declared in the inner scope.

+ + +while( myListIterator.hasNext() ) +{ + final String myString = (String)myListIterator.next(); +} + + +

Variables should be descriptive and ideally English words. The exceptions +being loop counters (usually use i, j and k), exceptions (use concatenation +of word separating characters - i.e. SocketException is abbreviated as se) and +other commonly used abbreviations (i.e. sb for StringBuffer).

+ +try +{ + for( int i = 0; i < 10; i++ ) + { + // some stuff + } +} +catch( final FileNotFoundException fnfe ) +{ + // some stuff +} +catch( final IndexOutOfBoundsException ioobe ) +{ + // some stuff +} + +

+Use String concatenation except in extremely performance sensitive +sections. This leaves StringBuffer optimization to the compiler. +So use:

+ +final String myString = "test " + "for " + "performances"; + +

Try not to declare a method as 'synchronized'. If a method accesses +a shared resource then surround accesses to that resource with +a synchronized block. Ideally the synchronized block should surround +the smallest possible area. For example:

+ +public void sharedMethod() +{ + String display = null; + + synchronized( this ) + { + display = mySharedObject.getHelloWorld(); + } + + System.out.println( display ); +} + +

If you are within a static method, then you may have to create +a static object whose sole purpose in life is to provide the +lock you need. Alternatively you could use the Class object for +the class you are in. That is, if you're in class MyClass, use +"MyClass.class".

+

Have the names of all member instance fields start with the prefix "m_". +Example:

+ + +class MyClass +{ + Class m_class = MyClass.class; + int m_users; +} + + +

Don't chain method calls. The below:

+ +Thing thing = (MyThing)myObject.doSomething().doSomethingElse().getMyThing(); + +

is considered bad practice because it hides problems relating to +synchronization, resource management, etc. The example above might +become:

+ +final MySomething something = myObject.doSomething(); +final MyElse somethingElse = something.doSomethingElse(); +Thing thing = somethingElse.getMyThing(); + +

The extra typing will help keep the code bug-free.

+ +

Thanks for your cooperation.

+ +

-The Avalon Team

+ +
+ + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/development.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/development.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,22 @@ + + + + Alex Karasulu + Apache Directory Project + + + +
+

+ The following documents describe the development practices in + use by the Directory community. When contributing to the project, + please follow these guidelines. +

+ +
+ + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/index.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/index.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,62 @@ + + + + Alex Karasulu + Apache Directory Project: Process + + + +
+

+ Welcome to the Directory community! +

+

+ The Apache Directory Project, like all other projects at Apache, + is a meritocracy and follows the Apache Way of + community and project management. The following documents + help define these terms and form the guidelines by which the + Directory Project operates. +

+ +
+
+

+ The Directory Project continually looks at ways to cooperate + better with other projects, especially here at Apache. + Code reuse by us and others using our APIs is one of our + primary goals. +

+

+ If you are from another Apache project, and would like all the + committers from your project to have access to the Directory + Repositories, all you need to do is ask the Directory PMC +

+

+ The PMC will let you know if your request is accepted or + not. If you are interested in commit privileges, but are not + part of one of the Apache projects, then you have to do it + the old fashioned way and participate on the mailing lists + and post patches, etc. We are taking advantage of the Apache + infrastructure to make this happen. +

+
+ + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/mission.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/mission.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,223 @@ + + + + Alex Karasulu + Apache Directory Project: Mission + + + +
+ +Apache Directory is a collaborative software development project dedicated +to providing a high-quality freely available set of directory servers and +APIs used for accessing naming and directory systems via JNDI +according to the principles of the Apache Software Foundation [ASF]. + +This charter briefly describes the mission, history, organization, and +processes of the Apache Directory project. + +MISSION +======= + +[here's what Avalon's Mission is: we need our own] + +Apache Directory exists to promote and facilitate Component Based Design. +Component Based Design is a proven practice that helps create systems +that are loosely coupled and easy to maintain. Component Based Design +requires a rigid software framework to function properly. + +Apache Avalon provides a specification for such a framework, an +implementation of that specification and a compliance testing suite, +and tools and components to facilate development using that framework. + +The software developed by the Apache Avalon project must be high +performance, reliable, secure, and easy to use. The individual software +components must be part of an underlying architectural orchestration +that will allow them to work together without major negotiations or +breakage. + +The process followed for the development of Apache Avalon software is +the same as the process followed by other ASF projects: individuals and +corporations collaborate on the best possible infrastructure, APIs, +code, testing, and release cycles. + +In order to achieve a coherent architecture between Apache Avalon +components and other components and applications, standards (formal or +de facto) will be used as much as possible for both protocols and APIs. +We will also allow the innovation of new protocols, APIs, and components +in order to seed new concepts not yet defined by standards. + +HISTORY +======= + +[here's what Avalon's is: we need our own] + +This project was established under the direction of the Apache Software +Foundation in November 2002 to facilitate joint open-source development. + +Prior to November 2002, Apache Avalon has been a part of the Apache Java +project and the Apache Jakarta project. + +THE PROJECT MANAGEMENT COMMITTEE +================================ + +[here's what Avalon's is: we need our own] + +The Apache Avalon project is managed by a small, core group of +contributors known as the Project Management Committee [PMC]. The PMC +must have at least one ASF Officer, who will also be the PMC Chairperson +and who will report to the ASF Board. See +http://www.apache.org/foundation/bylaws.html for reference. + +The PMC has the following responsibilities: + +o Facilitating code or other donations by individuals or companies. +o Resolving license issues and other legal issues. +o Approving new committers. +o Ensuring that administrative and infrastructure work is completed. +o Overseeing Apache Avalon to ensure that the mission defined in + this document is being fulfilled. +o Resolving conflicts within the project. + +To become a member of the PMC, an individual must be nominated by a +contributor, unanimously approved by all PMC members, and approved by a +two-thirds majority of committers. In most cases, developers will have +actively contributed to development for at least six months before being +considered for membership on the PMC. + +The PMC is responsible for maintaining and updating this charter. +Development must follow the process outlined in this charter, so any +change to the development process necessitates a change to the charter. +Changes must be unanimously approved by all members of the PMC. A +contributor may challenge a change to the charter at any time and ask +for a vote of all committers, in which case a two-thirds majority must +approve the change. + +COMMITTERS +========== + +[here's what Avalon's is: we need our own] + +Committers are developers who have read/write access priviledges to the +source code repository. New committers are added when a developer is +nominated by a committer and approved by at least 50 percent of the +existing committers with no opposing votes. In most cases, new +committers will already be participating in the development process by +submitting suggestions and/or fixes via the bug report page or mailing +lists. + +CONTRIBUTORS +============ + +[here's what Avalon's is: we need our own] + +Anyone is allowed and encouraged to participate in the development of +the Apache Avalon software products. Occasional contributors will be +able to report bugs, participate in the mailing lists, and submit +patches. + +Specific changes to a product proposed for discussion or voting on the +appropriate development mailing list should be presented in the form of +patches. When sent to the mailing list, the message should contain a +subject beginning with [PATCH] and include a clear summary that +describes the effect of that patch. + +Like all Apache projects, the Avalon project is a meritocracy -- the +more work you do, the more you are allowed to do. Developers who make +regular and substantial contributions may become committers as described +above. + +LICENSING +========= + +[here's what Avalon's is: we need our own] + +All contributions to the Apache Avalon project adhere to the "ASF Source +Code License." All contributions must be made under those terms. All +contributions must contain the following copyright notice and license: + + ============================================================================ + The Apache Software License, Version 1.1 + ============================================================================ + + Copyright (C) 1997-2003 The Apache Software Foundation. + All rights reserved. + + Redistribution and use in source and binary forms, with or without modifica- + tion, are permitted provided that the following conditions are met: + + 1. Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + + 2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + + 3. The end-user documentation included with the redistribution, if any, must + include the following acknowledgment: "This product includes software + developed by the Apache Software Foundation (http://www.apache.org/)." + Alternately, this acknowledgment may appear in the software itself, if + and wherever such third-party acknowledgments normally appear. + + 4. The names "Apache", "Avalon", "Excalibur", "Fortress", "Phoenix", + "Merlin" and "Apache Software Foundation" must not be used to endorse or + promote products derived from this software without prior written + permission. For written permission, please contact apache@apache.org. + + 5. Products derived from this software may not be called "Apache", nor may + "Apache" appear in their name, without prior written permission of the + Apache Software Foundation. + + THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, + INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE + APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLU- + DING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS + OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON + ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF + THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + This software consists of voluntary contributions made by many individuals + on behalf of the Apache Software Foundation. For more information on the + Apache Software Foundation, please see http://www.apache.org/. + +THE DEVELOPMENT PROCESS +======================= + +[here's what Avalon's is: we need our own] + +The development process is intentionally lightweight and follows the +same guidelines as other ASF projects. The project committers decide +which changes may be committed to the repository. Three +1 ('yes' votes) +with no -1 ('no' votes or vetoes) are needed to approve a code change. +For efficiency, some code changes from some contributors (e.g. feature +additions, bug fixes) may be approved in advance, in which case they may +be committed first and changed as needed, with conflicts resolved by +majority vote of the committers. + +PRODUCT REQUIREMENTS +==================== + +[here's what Avalon's is: we need our own] + +All software products developed by Apache Avalon must have a set of +requirments as well as an up-to-date release plan and architecture +design. All software products developed by Apache Avalon must have a +test system to verify their correct functioning and are ideally subject +to continous integration testing, regression testing and unit testing. + +RELATIONSHIP TO OTHER APACHE PROJECTS +===================================== + +[here's what Avalon's is: we need our own] + +The Apache Avalon project should work closely with other Apache +projects, such as Jakarta and Apache HTTP Server, to avoid redundancy +and achieve a coherent architecture among Apache Avalon and these +projects. + +
+ + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/navigation.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/navigation.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,57 @@ + + + + + Apache Avalon + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/patches.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/patches.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,41 @@ + + + + Alex Karasulu + Apache Directory Project: Patches + + +
+

It's the issue tracking system we use, and + we ask that you do, too.
+
+ Enter a bug
+
+ but please make sure the bug you're reporting doesn't exist yet, you include + all relevant information, etc. See + this page + for more on how to submit bug reports, or try Google.

+
+
+

Generate patches using cvs diff -u, or diff -u. + Please create your patches relative to the root of the cvs module the patch + should be applied to. Please compile changes to multiple files + in a single patch file. Make sure the patch adheres to the coding standards, + and includes appropriate javadoc.

+ +

When you've built the patch, file a new bug report in JIRA if one + does not exist yet, explain the reason behind the patch, how the patch fixes + the issues, and add the patch as an attachment.

+ +

If your patch is not getting applied or there is no response, start nagging + the developers (politely, please :D) on the developers mailing list.

+ +
+

Please submit documentation patches against the xml sourcefiles used + for generating the documentation, and not against the documentation + itself.

+
+
+ + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/pmc-votes.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/pmc-votes.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,174 @@ + + + + Alex Karasulu + Apache Directory Project: PMC Voting + + + + +
+ +

This document details how the Avalon PMC has agreed to handle voting.

+ + + + + +

+ The proposer is the one who comes up with the + discussion that needs to be addressed. Any + member of the Directory community may start the + discussion. The proposer must follow the + procedures listed under the heading "Prior to + the Vote".

+ + + + + +

The vote administrator is the person who + tallies the votes and reports the results. + The person who actually puts a proposal up for + vote is usually the vote administrator, + although this task can be taken on by someone + else.

+ + + + + +

A voter is someone who expresses support, + opposition or abstention for the subject being + voted on. A voter must be a Directory PMC + member. Input is appreciated from committers + and all other members of the community, but + only votes from PMC members are counted.

+ + + + + + +

Before any vote can take place, the subject must be + discussed. All such discussions take place on the + Directory developer or PMC mailing list, and have the + text "[PROPOSAL]" in the subject line. That + practice alerts members to the fact that you + eventually intend to call a vote on the + subject.

+ + + + +

When the proposal is ready to be adopted by the + community, the Proposer will call for a vote on + the Directory developers or PMC mailing list. The + call for vote must have the text "[PMC:VOTE]" in + the subject line. That practice alerts the + members to the fact that the prior proposal is now + ready to vote on, and discussion should stop for + the proposal.

+ + + +

The voter responds to the call for vote with an + expression of support, opposition, or + abstention. The exact way to express the + voter's position is listed below:

+ +
    +
  • +1 a vote supporting the subject
    • +
  • +0 a vote abstaining from the subject (but showing some support).
    • +
  • 0 a vote abstaining from the subject.
    • +
  • -0 a vote abstaining from the subject (but showing disapproval).
    • +
  • -1 a vote opposing the subject
    • +
+ + + + +

The vote administrator will count only the last + vote from each voter. That means a voter may + change their vote at any time during the + duration of the vote. All votes (+1, -1, +0, + -0 and 0) count toward quorum, but +0, -0 and + 0 do not count when determining majority.

+ + + + +

There are two classes of votes: a Qualified + Majority Vote and a Normal Majority Vote. In + both types of votes, only +1 and -1 votes + count toward majority.

+ + + +

Any vote that affects the texts "Directory PMC + Charter" or "Directory PMC Policies and + Procedures" is a Qualified Majority + Vote. For this type of vote to pass, it + requires that there are more than twice as + many +1 votes as -1 votes.

 + + + +

All votes that do not fall under the + heading of Qualified Majority Vote are + handled as a Normal Majority Vote. If + there are more +1 votes than -1 votes, + then the vote has passed.

 + + + + +

In order for any vote to be considered binding + it must have quorum, and be held for the + proper amount of time.

+ + + + + +

For all votes, there must be at least three (3) + voters and half (1/2) of the PMC must cast a + vote. When determining quorum, all votes (+1, + -1, +0, -0 and 0) count.

 + + + +

All votes will be open for an initial period of + one week. The Vote Administrator may close + the vote at any time after that period if + quorum has been achieved. If quorum could not + be reached within the initial one-week period, + the vote will remain open for one additional + week. If the vote still has not achieved + quorum, then it is considered failed. The + proposer can choose to bring it up later when + quorum can be reached.

 + + + + +

When the vote is closed, the results of the vote + are summarized by the Vote Administrator. The + vote administrator will send an email to the + Directory developers or PMC list with the text + "[PMC:VOTE-RESULT]" in the subject that has the + summary. The summary will include the count of + all +1, +0, 0, -0, and -1 responses, and the final + verdict of whether the subject passed.

+ + + + +

Disagreements concerning voting may be directed to + the Chair. The Chair's opinion shall be final and + binding upon the PMC.

+ + +
+ + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/pmc.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/pmc.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,56 @@ + + + + Alex Karasulu + Apache Directory Project: PMC + + + +
+

These pages exist only to provide some down-to-earth insight + in how things work at the ASF. They're informative only, not + normative. They may contain errors or inadequacies. IANAL.

+
+
+

Apache is a legal entity, i.e. a real non-profit organisation, + with a charter, members, a board, a president, etc. You can + read all about that + here

+ +

A PMC, Project Management Committee, is a group of people + appointed with the task of managing something that fits with the + Apache Software Foundation goals. The Avalon PMC, for example, + is tasked with managing the Apache Directory Project.

+
+
+

We're all programmers, and that is what we want to occupy us + with. We like to share and work on our software together, which + is why we make it free software. However, there is always some + stuff which still requires management.

+ +

For example, in order to protect ourselves and our users, all + software hosted at Apache must be properly copyrighted to the ASF, + and licensed under the ASF license. This is something the PMC is + responsible for.

+ +

Also, remember that the PMC consists of the same people that do + the development work. There's no "bossing around" here. The PMC + exists only to facilitate free software developers in "doing their + thing", just like the ASF exists "to provide organizational, legal, + and financial support for the Apache Open Source software + projects".

+
+
+

The position of Avalon PMC chair is an important one; the PMC + chair has special responsibilities and privileges as detailed in + the ASF bylaws.

+
+
+

The following people form the current Avalon PMC:

+ +
+ + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/release.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/process/release.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,52 @@ + + + + Alex Karasulu + Apache Directory Project: Release Management + + +
+

We haven't got our release process written down yet.

+
+
+ +
+
+

Noel J. Bergman wrote to avalon-dev:

+ +[snip] +Here are a few items to consider for the Release Plan: + + 1) Identify bugs and incompatibilities. + 2) Decide which ones will be fixed. + 3) Decide what other changes are necessary, e.g., packaging. + 4) Make the code changes. + 5) Test + 6) Update the documentation and web site. + +[snip] +Here are a few useful links: + + Jakarta: http://jakarta.apache.org/site/decisions.html + Apache HTTPD release policies: http://httpd.apache.org/dev/release.html + Avalon bug summary: +http://nagoya.apache.org/bugzilla/reports.cgi?product=Avalon&output=most_doo +med&links=1&banner=1&quip=0 + Mirroring: http://cvs.apache.org/~bodewig/mirror.html + +[snip] + --- Noel + +
+ + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/who/akarasulu.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/who/akarasulu.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,16 @@ + + + + Alex Karasulu + Apache Directory Project: Contributors + + +
+

(akarasulu at apache dot org)

+

+ Talk about Alex here. +

+
+ + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/who/index.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/who/index.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,36 @@ + + + + Alex Karasulu + Apache Directory Project: Who we are + + +
+

+ The current Directory committers are: akarasulu, jmachols, wesmckean, + rpenoyer, nburgman, smcconnell, hyandell, psteitz +

+
+
+

+ The current inactive avalon committers (an inactive committer is + someone who hasn't done a cvs commit in three months, or hasn't + bothered to move himself from this list to the one above) are: + none yet. +

+
+
+

+ The current emeritus committers (an emeritus committer is + someone who is not active within the avalon project anymore) + are: none yet. +

+
+
+

+ Fill this in with time. +

+
+ + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/who/mcconnell.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/who/mcconnell.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,16 @@ + + + + Alex Karasulu + Apache Directory Project: Contributors + + +
+

(mcconnell at apache dot org)

+

+ Steve talk about yerself here. +

+
+ + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/who/navigation.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/community/who/navigation.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,54 @@ + + + + + Apache Avalon + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/cvs.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/cvs.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,196 @@ + + + + Avalon Documentation Team + CVS + + + + + +
+

If you are looking to download the source code for stable versions of the Avalon + projects, you're in the wrong place. You should download a source release from + the source download page.

+
+
+

CVS, the Concurrent Versions System is a revision control system useful for + management of source code, and is the predominant version control system used at + Apache. See The CVS Homepage for + more about CVS.

+
+
+

If you know what you're doing, all you need to know:

+

viewcvs: http://cvs.apache.org/viewcvs.cgi/

+ +anonymous CVSROOT: :pserver:anoncvs@cvs.apache.org:/home/cvspublic +modules: + avalon # framework, containers and documentation + avalon-components # component repository + avalon-excalibur # utility repository + avalon-logkit # cool logging toolkit + avalon-phoenix # the phoenix container and related libraries + avalon-sandbox # alpha & pre-alpha code + avalon-site # this website + +
+
+

There's a few options for you:

+ + + +

Cygwin is a free software suite + of ports of popular Linux tools and utilities to run natively under windows. + Among it is a port of the cvs application. If you use cygwin, follow the Linux + instructions.

+ + + +

The CVS utilities are available as native Windows binaries. Get them from + the CVS homepage. To use these + tools, open a command window (click Start > Run..., then type 'cmd'), then + enter the following commands:

+ + +rem you can use any directory in place of C:\cvs +rem replace $CVSUTILS with where you installed the cvs binary, or with +rem nothing if you added the utility to your PATH +mkdir C:\cvs +cd C:\cvs +$CVSUTILS\cvs.exe -d :pserver:anoncvs@cvs.apache.org login +rem enter anoncvs when prompted for a password, then hit enter +rem the below command should be on one line +$CVSUTILS\cvs.exe -z3 -d ^ + :pserver:anoncvs@cvs.apache.org:/home/cvspublic checkout ^ + avalon avalon-excalibur avalon-components ^ + avalon-phoenix avalon-logkit avalon-site ^ + avalon-sandbox xml-forrest ^ + + +

This will take a while, depending on your connection. Go ahead and grab + yourself a coffee or ten. When done, you should have checked out all Avalon + sources and the most important utility libraries you need to build it (save + for Apache Maven, which you should + go install right now if you haven't already). For further building instructions + run:

+ +maven avalon:info + + + + +

TortoiseCVS is a neat extension + for the Windows Explorer which integrates CVS. Using it is real simple:

+ +

After you've created a folder where you want to check out the sources to, + right-click and select CVS Checkout...:
+ screenshot of CVS settings

+ +

Then, fill out the settings like in the screenshot below, and then click ok.
+ screenshot of CVS settings

+ +

This checks out the avalon CVS module. Repeat this procedure for all + the modules you wish to check out. See above under "CVS data" for the list of Avalon modules, or use the + ViewCVS Webpage for a full + list of ASF-hosted CVS modules.

+ + + +

WinCVS is a standalone windows + application for working with CVS. It has more features than TortoiseCVS, and + hence more buttons a novice is not likely to use.

+ +

After you've created a folder where you want to check out the sources to, + select the Checkout module... option from the Create menu:
+ screenshot of CVS settings

+ +

Then, select the "general tab" and fill out the settings like in the + screenshot below:
+ screenshot of CVS settings.

+ +

Now, switch back to the first tab and fill out the settings like in the + screenshot below, and then click ok.
+ screenshot of CVS settings.

+ +

This checks out the avalon CVS module. Repeat this procedure for all + the modules you wish to check out. See above under "CVS data" for the list of Avalon modules, or use the + ViewCVS webpage for a full + list of ASF-hosted CVS modules.

+ +
+
+ + + +

The CVS utilities are available as native linux binaries. Chances are + you already have them installed. Try it by opening a console and typing 'cvs'. + If you get an error along the lines of "bash: cvs: command not found", then + you need to install them first. Under Debian, you can do so by opening a console + window and entering the commands:

+ + +su - +# enter the root password when prompted +apt-get update +apt-get install cvs +exit + + +

Under Red Hat, the commands are a little different:

+ + +su - +# enter the root password when prompted +rpm -i ftp://ftp.redhat.com/pub/redhat/linux/8.0/en/os/i386/RedHat/RPMS/cvs-1.11.2-5.i386.rpm +exit + + +

The procedure is similar for other Linux distributions. Once you have + these tools installed, open a command window, then enter the following + commands:

+ + +# you can use any directory in place of ~/cvs +mkdir ~/cvs +cd ~/cvs +cvs -d :pserver:anoncvs@cvs.apache.org login +# enter anoncvs when prompted for a password, then hit enter +cvs -z3 -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic \ + checkout avalon \ + avalon-excalibur avalon-cornerstone \ + avalon-phoenix avalon-logkit avalon-site \ + avalon-sandbox jakarta-site xml-forrest + + +

This will take a while, depending on your connection. Go ahead and grab + yourself a coffee or ten. When done, you should have checked out all avalon + sources and the most important utility libraries you need to build it (save + for Apache Ant, which you should + go install right now if you haven't already).

+ + + + +

KDE's Konqueror browser has CVS support built-in. I've never used it so I + can't comment on it. See + the Cervisia website for + more information.

+ +
+
+ +

jCVS is a 100% java CVS package that I've + never used.

+
+
+ +

Most decent IDEs these days provide CVS integration. Apache's Jakarta Project has + an excellent section on how to configure your IDE: + IDE Developer's Guide + . It applies equally well to Avalon. +

+
+ + + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/authors.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/authors.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,48 @@ + + + + + Paul Hammant + Berin Loritsch + Developing With Apache Avalon Authors + + + +
+ +

+ Berin has helped define and document the Avalon projects since 2000. + He has been involved in Apache Avalon and Apache Cocoon. He is the + author of the current thread-safe pool implementations as well as + the DataSourceComponent. Berin and Giacomo Pati were the architects + of Excalibur's Component Management infrastructure. +

+

+ Outside of the public view of the Apache Software Foundation, Berin + has developed workflow based web applications as well as data + manipulation services. He has nine years of experience developing + database backed applications, and eight years experience with + technical writing. Berin has only been developing Java since 1999, + but his background in other Object Oriented Languages and architectures + like C++ and CORBA helped him get a jump start. +

+ + +

+ Paul is most interested in applications that run on top of Phoenix. As such he constantly + trawls the internet look for suitable server applications for Phoenix. He tries to persuade + the authors to rebase to Phoenix or make their apps phoenix compatible. +

+

+ Paul wrote some of blocks for Cornerstone and some of the apps in Avalon apps. + He also started AvalonDB, + Jesktop, + AltRMI, + Enterprise Object Broker, and + Picocontainer. +

+ +
+ + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/compatiblity.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/compatiblity.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,99 @@ + + + + + Paul Hammant + Berin Loritsch + Compatibility with Avalon Project Containers + + + +
+

+ There are many applications, utility or tools written in Java that you + wish you could use in an Avalon container. It may be that you are + writing such an app/utility/tool that you intend to additionally be + usable by Avalon components in Avalon containers. This document + gives some advice on the subject. We will refer to applications, + utilities and tools as just 'tools' from her on in. We'll assume + the classes for which are in a single Jar. +

+

+ This advise is applicable to all + + reference containers +

+
+
+

+ The tool's Jar should only contain the classes in question and + directly associated resources. It should not contain the classes + or resources from other projects. For example it is a bad habit + to include the org.apache.xerces.* jars in another jar. It would + be correct for the notes accompanying the tools to list xerces.jar + as a dependency. +

+

+ It is best that packages for the tool are well defined. Sun + recommend a package structure that honors the internet domain of + the hosted proejct. For example org.apache prefixes all the packages + of projects hosted at Apache. Sometimes a project thinks it is + significant enough to avoid the domain name based naming, but still + have a package. JUnit is an example of this, as it uses junit as its + top level package. Tools that have no package or a package name + that a non unique word are not good design. +

+
+
+

+ There are many tools written in Java as beans that you wish you could + use in an Avalon container as a component. If they are not + dependent on Avalon packages and classes already it is likely that + some wrapper concept is appropriate. The normal form is to have + a separate package with a class that is dependent on Avalon Framework + methods. That wrapper class would be Configurable, Initializable etc, + and would map its configuration to setZYZ() methods in the original bean. +

+

+ It is also a good idea to understand the + + separation of interface and implementation when designing components. +

+
+
+

+ Many Java tools internally use + Class.forName(String).newInstance() + to instantiate some part of its internal functionality. This + works if the class's Jar is mounted at the top-level system + classloader. In the case of many Avalon containers, the Jar in + question will actually be mounted in a classloader at some other point + in a tree of classloaders. Thus Class.forName() + will fail with ClassNotFoundException if running in a container. +

+

+ A better thing to do would be to use + this.getClass().getClassLoader().loadClass(String). + This means that the class will always be loaded from classloader + that hosts the rest of the classes for the tool. It can run at any + point in a tree of classloaders without problem. +

+
+
+

+ It is common amongst novice developers to use much static + functionality. This could be methods or class variables. Given + that Avalon's containers may mount multiple instances of a component + potentially in multiple classloaders, the use of static may lead to + unpredicted behavior. If the static var or method is mounted in a + classloader that is visible to multiple components, then it will + behave as expected. For this reason, static should be used with care + - you cannot guarantee where someone might try to run your tool. +

+

+ Static also makes Unit Testing quite difficult. If you can at all + avoid it, please do so. +

+
+ + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/conclusion.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/conclusion.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,113 @@ + + + + + Paul Hammant + Berin Loritsch + Conclusion + + + +
+

+ Maybe you are already convinced, but need some help convincing + your colleagues that Avalon is right for you. Maybe you need + some convincing yourself. Either way, this chapter will help + wrap everything up, and provide you with some convincing arguments. + We all need to fight Fear, Uncertainty, and Doubt (FUD) with the + Open Source model. For arguments on the validity of Open Source, + I will direct you to Eric S. Raymond's excellent treaties on the subject. + Regardless of your opinions on his politics, the + papers he wrote and compiled into the book + + The Cathedral and the Bazaar will give you the information you need to + be convinced about the open source model as a whole. +

+
+
+

+ The bottom line is that Avalon accomplishes the goal it was + originally designed to fulfill. Avalon does not introduce new + concepts and ideas, but rather uses and formalizes several concepts + that have stood the test of time. The newest concept that influenced + the design of Avalon is the Separation of Concerns pattern introduced + sometime around 1995. Even then, Separation of Concerns is a + formalization of System Analysis techniques. +

+

+ Avalon's user base is measured in the hundreds. Several projects + like Apache Cocoon, Apache JAMES, and Jesktop are all built on Avalon. + Developers for those projects are users of Avalon Framework. Because of + the number of users Avalon has, it is very well tested. +

+ 3 +

+ The authors of Avalon recognize that we are not the sole experts + on server side programming. We use concepts and ideas from other + people's research. We respond to feedback from our users. Avalon + is not just designed by the five developers mentioned in the + introduction -- the people who came up with the concepts of Inversion + of Control, Separation of Concerns, and Component Oriented + Programming designed it. +

+

+ The beauty of Open Source projects is that the result is an + amalgamation of the best ideas and the best code. Avalon has gone + through periods of testing ideas and rejecting them because there + was a better solution. You can take the knowledge gained by the + Avalon team and use it in your own systems. You can take the + predefined components in Excalibur and use them in your own + projects -- they have been tested to work under heavy load without + errors. +

+ + +

+ The Apache Software License (ASL) is compatible + with just about every other license known. The biggest known + exceptions are the GNU Public License (GPL) + and the Lesser GNU Public License (LGPL). The + important thing is that the ASL is friendly to corporate development, + and does not force you to release your source code if you don't want + to. It is the same license used for the Apache Software Foundation's + venerable HTTP server. +

+ + +

+ Most of Avalon's users contribute back to the project in some way. + This spreads the cost of developing, debugging, and documenting the + framework across several users. It also means that Avalon's code + has gone through a more extensive peer review than would ever be + possible in one company. In addition, users of Avalon support + Avalon. While it is true open source projects do not typically have + a help desk or telephone support line, we do have a mailing list. + Many times your questions can be answered in less time on the list + than it would take on some support lines. +

+ + +

+ Developing on Avalon helps the developer to get into a mindset. + That mindset focuses the efforts on how to discover Components and + Services. Since many of the details regarding the life of the + Components and Services in the system are already analyzed and + designed, the developer only has to choose which ones they need. +

+

+ It is important to state that Avalon development does not replace + traditional Object Oriented Analysis and Design, but enhances it. + You are still using the same techniques you did before, only now + you have a tool set you can use to achieve your design faster. +

+ +
+
+

+ Avalon Framework, Avalon Excalibur, Avalon Phoenix and Avalon LogKit + are ready for you to use now. They are mature, powerful products and + they are only getting better! +

+
+ + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/decomposing.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/decomposing.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,398 @@ + + + + + Paul Hammant + Berin Loritsch + Decomposing A System + + + +
+

+ We will use a hypothetical business server to demonstrate + how to identify services and Components. After we define some + services that are used in the system, we will take one of those + services and define the different components needed by the + service. My goal is to pass on some concepts that will help + you define your system in manageable pieces. +

+
+
+

+ While it is beyond the scope of this presentation to provide + a full-blown methodology, I do want to provide some pointers. + We will start with the implementation oriented definition of + Components and Services, and then provide a practical definition. +

+ + + +
Component
+ A Component is the combination of a work interface, and the + implementation of that interface. Its use provides a looser + coupling between objects, allowing the implementation to + change independently of its clients. +
+ + + +
Service
+ A Service is a group of one or more Components that provide + a complete solution. Examples of a Service are protocol + handlers, job schedulers, and authentication and authorization + services. +
+

+ While these definitions provide a starting place, they don't + give the whole picture. In order to decompose a system (defined + as a group of facilities that comprise a project) into the + necessary parts, I advocate a top-down approach. That way you + will avoid being bogged down in details before you know what the + different facilities are. +

+ +

+ You always have to start out with a general idea of what your + project is supposed to accomplish. In the commercial world, the + initial statement of work accomplishes this. In the open source + world, this is usually accomplished by an idea or brainstorming + session. I can't stress enough the importance of having a high + level view of the project. +

+

+ Obviously, a large project will be comprised of many different + services, and a small project will only have one or two. If you + start to feel a bit overwhelmed, just remind yourself that a large + project is really an umbrella for a bunch of smaller projects. + Eventually, you will get to the point where you will be able to + comprehend the big picture. +

+ +
+
+

+ The Business Server is a hypothetical project. For the purpose + of our discussion, its function is to handle sales orders, + automatically bill customers, and manage the inventory control. + Sales orders have to be processed as they come in, using some + kind of transaction system. The server automatically bills the + customers 30 days after the sales order is filled. The inventory + is managed by both the server and by the current inventory counted + at the factory or warehouse. The business server will be a + distributed system, and each server will communicate with others + via a messaging service. +

+
+
+

+ We will use the Business Server Project to discover the services. + Considering the overly broad statement of work, we can immediately + begin to see some services defined in the description of the + project. The list of services will be split into explicit ones + (services that can immediately be derived from the statement of + work) and implicit ones (services that are discovered due to similar + work or as supporting the explicit services). Please note that the + implementing company will develop not all of the services-some will + be purchased as commercial solutions. In those cases, we will + probably put a wrapper so that we still have a specific way of + interacting with the commercial product. The implementing company + will build the majority of the services. +

+ +

+ We can quickly derive a number of services from the statement + of work. Our work is not done after this initial analysis, + because the definition of some services requires the existence + of other services. +

+ +

+ The statement of work specifies that "Sales orders have to be + processed as they come in". This means we need to have a + mechanism of receiving sales requests and automatically process + them. This is similar to the way web servers work. They + receive a request for a resource, process it, and return a + result (e.g. the HTML page). This is known as Transaction + Processing. +

+

+ To be fair, there are different types of transactions. The + generic transaction service will most likely have to be broken + down into something more specific like a "Sales Order Processor". + The approach has to do with how generic you make your service. + There is a balance between usability and reusability. The more + generic a service is, the more reusable it is. Usually it is + also more difficult to comprehend. +

+ + +

+ There are a couple of instances where an event must be scheduled + for a specified amount of time after a transaction. In addition, + the inventory control processes need to kick off supply orders on + a periodic basis. Because the statement of work states "server + automatically bills the customers 30 days after the sales order + is filled" we need a scheduling service. The good news is that + Avalon Cornerstone provides one for us so we don't have to create + our own. +

+ + +

+ The statement of work specifies that "each server will + communicate via a messaging service" in our distributed system. + Let's face it, sometimes customers want a specific product or + method they want to use. The messaging service is a prime + example of using another company's product. Most likely, we + would use Java Messaging Service (JMS) to interface with the + Messaging Service. Since JMS is a standard, it is unlikely + that the interface will change any time soon. +

+

+ In practical experience, a well-designed message oriented system + will scale better than object oriented systems (like EJB). One + reason for better scalability is that messaging tends to have + lower concurrent overhead memory. Another reason for this is that + it is easier to spread the load of message processing across all + servers instead of concentrating all the processing in a small + cluster of servers (or even just one server). +

+ + +

+ While this is not a classic server piece in textbooks, it is a + requirement of this system. The inventory control service + routinely monitors the records for what the factory or warehouse + has in stock, and triggers events when stock starts running out. +

+ + + +

+ Using experience with past systems, and further breaking down + other services will yield a number of services that the system + needs that wasn't specified. Due to space limitations, we will + avoid doing a full decomposition. +

+ +

+ The authentication and authorization service is not necessarily + specified in the statement of work -- but all business systems + must take security seriously. That means all clients of the system + must be authenticated, and every action of the user must be + authorized. +

+ + +

+ Workflow automation is a hot development area in enterprise + systems. If you don't use a third party workflow management + server, you will have to invent your own. Workflow automation + is generally the act of using a software system to route tasks + through a Company's business process. For more information, + view the Workflow Management Council's web page at + http://www.wfmc.org. +

+ + +

+ This definition of a "document repository" is very loosely + defined as the current state of information in a task. In + other words, when the company receives a purchase order, our + system needs to store and recall the purchase order information. + The same goes for billing and any other process in the system + from inventory to new customer requests. +

+ + + +

+ I hope that the examples of services for the Business Server + project will help you discover more. You will find that as you + go from higher levels of abstraction down to lower levels, you + will find more types of services required like Connection Management + to handle requests on open ports. Some of the services we defined + will be implemented by third party systems such as the Messaging + Service and the Workflow Management Service. It is in your best + interest to use a standard interface for these services so that + you can change vendors later. Some services are actually multiple + services acting as one larger service. Some are already available + within Avalon Excalibur or Avalon Cornerstone. +

+

+ One thing to keep in mind while discovering the services in a + system is that a service should be a high level sub-system. This + will help you define components using teams of analysts. Because + we have already identified the main services, you can have more + than one person (or team) decompose each of the services in parallel. + The boundaries are well defined, so there is little chance for + overlap. If you decide to do the parallel analysis, you should + come back together to identify common Components so that you can + reuse as much code as possible. +

+ + +
+
+

+ We will use the Document Repository Service mentioned already for the + process of identifying the proper Components. For the sake of our + conversation, we will now state the requirements of the Document + Repository Service. The repository will use a database for persistent + storage, identify and authorize clients, and cache documents in memory. +

+ +

+ When we talk about components, you have to think in terms of "What + facilities does my service need to operate?" Avalon was conceived + with the concept of casting your system. The + developer of the system would come up with a list of responsibilities + for the Component known as its role. +

+ +

+ The concept of roles comes from the theater. A play, musical, or + movie will have a certain number of roles that actors play. Although + there never seems to be a shortage of actors, there are a finite + number of roles. Its script defines the + function or action of a role. Just like the theatrical version, the + script determines how you interact with the Component. Think of the + different roles in your system, and you will have your + cast of Components so to speak. +

+

+ A role is the contract for a type of component. For example, our + Document Repository Service needs to interact with a database. + Avalon Excalibur defines a Component that satisfies the role "Data + Source". Excalibur includes two different Components that satisfy + that role, depending on the setting our Service will be living in; + however, they both satisfy the same contracts. The majority of + Avalon based systems will only use one active Component for each + role. The script is the work interface: the interface with which + other components interact. +

+

+ There are specific contracts that you must define and keep in mind + when you specify interfaces for your Components. The contracts + specify what users of the Component must provide, and what the + Component produces. Sometimes you must include usage semantics in + the contract. An example is the difference between a temporary + storage Component and a permanent storage Component. When the + interface and contract are defined, you can work on your + implementation. +

+ + + +

+ We have already identified four possibilities for Components within + our Document Repository Service: DataSourceComponent (from Excalibur), + Cache, Repository, and Guardian. You should look for roles with a high + likelihood of multiple implementations that need to inter-operate + seamlessly. +

+

+ Using that example, you will discover several instances where you need + replaceable facilities. Most of the time, you will only be using one + implementation of the facility, but you need the ability to upgrade it + independently of the rest of the system. Other times, you will need + alternate implementations due to environmental issues. For example, + the "Data Source" that Excalibur defined will usually handle all the + JDBC Connection pooling itself-but sometimes you want to take advantage + of that facility built into a Java 2 Enterprise Edition (J2EE) server. + Excalibur solves this by having a "Data Source" that directly pools and + manages the JDBC connections, and one that uses Java's Naming and + Directory Interface (JNDI) to get the specified connection. +

+ + +

+ People who are used to JavaBeans tend to implement everything as a + JavaBean. This means everything from data modeling to transaction + processing. If you used this approach with Components, you might end + up with an overly complex system. Think of Components as modeling a + service or facility, and not data. You could have a Component that + pulls data from another resource, but the data should remain distinct + as data. An example of this philosophy in Avalon Excalibur is the + fact that the Connection is not a Component. +

+

+ Another example could be the Guardian Component we specified earlier. + It could be argued that the logic involved in the Guardian is so + specific to the Document Repository Service that it could not be used + again for a completely different service. While there are ways of + managing the complexity, and ways of making it flexible-sometimes the + extra work is not worth it. You have to weigh your decisions in such + cases carefully. If the logic performed in a potential Component is + going to be applied consistently then it might make sense to keep it a + Component. There is room to have multiple instances of a Component in + a system, and they would be selected at run time. If the logic for a + potential Component is specific to only one other Component, it might + be worth it to absorb the logic into the other Component. Using the + example of the Guardian Component and the Repository Component, we + could argue that our Guardian is so specific to the Repository, that it + is not implemented as a Component. +

+ + +

+ We will list the Components that we are going to implement with a + description of their roles, the rationale, and their origination (if + the component already exists). +

+ +

+ The DocumentRepository is the parent Component of the whole service. + In Avalon, services are implemented as Blocks, which are a specific + kind of Component. The Block must have a work interface that extends + the Service marker interface. The Block interface also extends + Avalon's Component interface. Please note that Block and Service are + interfaces that are part of Avalon Phoenix. In the end, a Service is + still technically just a specific type of Component. +

+

+ The DocumentRepository is our method of getting Document objects from + persistent storage. It interacts with the other Components in the + service to provide security, functionality, and speed. This + particular DocumentRepository will connect to a database and employ + the logic to build the Document objects internally. +

+ + +

+ The DataSourceComponent is supplied by Avalon Excalibur. It is our + method of retrieving valid JDBC Connection objects for our use. +

+ + +

+ The Cache is a short-term memory-based storage facility. The + DocumentRepository will use it to store Document objects referenced + by a hash algorithm. In order to promote the reusability of the + Cache Component, the stored object must implement a Cacheable + interface. +

+ + +

+ The Guardian Component is used to manage permissions based on the + Principal. The Guardian will load its permission sets from a + database. The Guardian will use the standard Java security model to + enforce access to the specific Document objects. +

+ + + +

+ At this point, you should have an idea of what makes a good Component. + The examples describe all the Components that will be in the Document + Repository Service, with a brief summary of what they will do. A quick + glance through the list supports the approach of only implementing + facilities as Components -- not data. At this point, you should be able + to determine what components your services need to operate. +

+ +
+ + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/framework.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/framework.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,785 @@ + + + + + Paul Hammant + Berin Loritsch + Framework and Foundations + + + +
+

+ Avalon Framework is the central piece to the entire Avalon project. If you + understand the contracts and constructs defined in the framework, you can + understand anything that uses it. Remember the principles and patterns we + have already discussed so far. In this section, we will expound on how the + Role concept works practically, the lifecycle of Components, and how the + interfaces work. +

+
+
+

+ In Avalon, all Components have a role. The reason is that you retrieve + your Components by role. At this stage, the only concern area we are + using is the signature of the role. If you recall in the second section, + we defined a Component as "the combination of a work interface and the + implementation of the interface". That work interface is your role. +

+ +

+ Below you will find an example interface, followed by some best + practices along with their reasoning. +

+ + + + +
    +
  1. +

    + Include a String called "ROLE" that has the role's official name. + That name is the same as the fully qualified name for the work + interface. This helps later on when we need to get an instance + of the Component later. +

    +
    2. +
  2. +

    + Do extend the Component interface if possible. This makes it easier + on you when it is time to release your Component. If you are not + in control of the work interface, then you do not have this option. + It is not the end of the world, as you can recast the instance to + Component when it is time to release it. +

    +
    3. +
  3. +

    + Do one thing and do it well. A Component should have the simplest + interface possible, When your work interface extends several other + interfaces, you muddy the contract for this Component. An old + American acronym helps define this pattern: Keep It Simple, Stupid + (KISS). It's not hard to outsmart yourself -- I've done it + a number of times myself. +

    +
    4. +
  4. +

    + Only specify the methods you need. The client should have no + knowledge of implementation details, and too many alternative + methods only introduce unneeded complexity. In other words pick + an approach and stick with it. +

    +
    5. +
  5. +

    + Don't let your Role's interface extend any lifecycle or lifestyle + interfaces. By implementing any of those classes of interfaces, you + are tying an implementation to the specification. This is a + bad pattern and this will only lead to debugging and implementation + problems later. +

    +
    6. +
+ + +

+ In Avalon, every Role has a name. It is how you get references to + other Components in the system. The Avalon team has outlined some + idioms to follow for the naming of your role. +

+ +
    +
  1. +

    + The fully qualified name of the work interface is usually the + role name. The exceptions are listed after this general rule. + Using this example, our theoretical Component's name would be + "org.apache.bizserver.docs.DocumentRepository". This is the + name that would be included in your interface's "ROLE" + property. +

    +
    2. +
  2. +

    + If we obtain the reference to this Component through a + Component Selector, we usually take the role name derived from + the first rule and append the word "Selector" to the end. The + result of this naming rule would be + "org.apache.bizserver.docs.DocumentRepositorySelector". You + can use the shorthand + DocumentRepository.ROLE + "Selector". +

    +
    3. +
  3. +

    + If we have multiple Components that implement the same work + interface, but are used for different purposes, we have + separate roles. A Role is the Component's purpose in the + system. Each role name will start with the original role + name, but the purpose name of the role will be appended + with a /${purpose}. By example + we could have the following purposes for our + DocumentRepository: PurchaseOrder and Bill. Our two roles + would be expressed as + DocumentRepository.ROLE + "/PurchaseOrder" + and DocuementRepository.ROLE + "/Bill", + respectively. +

    +
    4. +
+ + + +
+
+

+ The entire Avalon Framework can be divided into seven main categories (as + is the API): Activity, Service, Configuration, Context, Logger, + Parameters, Thread, and Miscellany. Each of those categories (except + Miscellany) represents a unique concern area. It is common for a + Component to implement several interfaces to identify all the concern + areas that the Component is worried about. This will allow the + Component's container to manage each Component in a consistent manner. +

+ +

+ When a framework implements several interfaces to separate the concerns + of the Component, there is potential for confusion over the order of + method calls. Avalon Framework realizes this, and so we developed the + contract for lifecycle ordering of events. If your Component does not + implement the associated Interface, then simply skip to the next event + that will be called. Because there is a correct way to create and + prepare Components, you can set up your Components as you receive + events. +

+

+ The Lifecycle of a Component is split into three phases: + Initialization, Active Service, and Destruction. Because these phases + are sequential, we will discuss the events in order. In addition, the + act of Construction and Finalization is implicit due to the Java + language, so they will be skipped. The steps will list the method + name, and the required interface. Within each phase, there will be a + number of stages identified by method names. Those stages are executed + if your Component extends the associated interface specified in + parenthesis. +

+ +

+ This list of stages occurs in this specific order, and occurs only + once during the life of the Component. +

+
    +
  • +

    + enableLogging + [LogEnabled] +

    +
    • +
  • +

    + contextualize + [Contextualizable] +

    +
    • +
  • +

    + compose + [Composeable] +

    +
    • +
  • +

    + service + [Serviceable] +

    +
    • +
  • +

    + configure + [Configurable] + or + parameterize + [Parameterizable] +

    +
    • +
  • +

    + initialize + [Initializable] +

    +
    • +
  • +

    + start + [Startable] +

    +
    • +
+ + +

+ This list of stages occurs in this specific order, but may occur + multiple times during the life of the Component. Please note that + should you choose to not implement the Suspendable interface, it is + up to your Component to ensure proper functionality while executing + any of the Re* stages. +

+
    +
  • +

    + suspend + [Suspendable] +

    +
    • +
  • +

    + recontextualize + [Recontextualizable] +

    +
    • +
  • +

    + recompose + [Recomposable] +

    +
    • +
  • +

    + reconfigure + [Reconfigurable] +

    +
    • +
  • +

    + resume + [Suspendable] +

    +
    • +
+ + +

+ This list of stages occurs in the order specified, and occurs only + once during the life of the Component. +

+
    +
  • +

    + stop + [Startable] +

    +
    • +
  • +

    + dispose + [Disposable] +

    +
    • +
+ + + +

+ In this section, we will cover all the sections alphabetically with + the exception of the most important concern area: Component. +

+ + + +
A Word About Containers
+ When I use the word "container" or "contains" when describing + Components, I have a very specific meaning. I am referring to child + Components that the parent Component has instantiated and controls. + I am not referring to Components obtained through a ServiceManager or + ServiceSelector. Furthermore, some Avalon stages + received by a + container must be propagated to all of its children implementing the + appropriate interface. The specific interfaces in question are + Initializable, Startable, Suspendable, and Disposable. The reasoning + for this contract is that these particular interfaces have specific + execution contracts. +
+ +

+ This is the core of Avalon Framework. Any interface defined in this concern + area will throw ServiceException. +

+ + Serviceable +

+ A Component that uses other Components needs to implement either this + interface or the old Composable interface. The new interface is the + preferred way of doing things. The interface has only one method + service with a + ServiceManager passed in as the only + parameter. +

+

+ The contract surrounding this interface is that the + service is called once and only once during + the lifetime of this Component. +

+

+ This interface along with any other interface that has methods + specified uses the Inversion of Control pattern. It is called by + the Component's container, and only the Components that this + Component needs should be present in the + ServiceManager. +

+ + +

+ The Recomposable interface has no replacement in the Serviceable + package. Use of Recomposable has been extremely rare, and many + applications that use avalon do not provide support for it. +

+ + + + +

+ This group of interfaces refers to contracts for the life cycle of + the Component. If there is an error during any method call with this + group of interfaces, then you can throw a generic Exception. +

+ +

+ The Disposable interface is used by any + Component that wants a structured way of knowing it is no longer + needed. Once a Component is disposed of, it can no longer be used. + In fact, it should be awaiting garbage collection. The interface + only has one method dispose that has no + parameters. +

+

+ The contract surrounding this interface is that the + dispose method is called once and the method + is the last one called during the life of the Component. Further + implications include that the Component will no longer be used, + and all resources held by this Component must be released. +

+ + +

+ The Initializable interface is used by any + Component that needs to create Components or perform + initializations that take information from other initialization + steps. The interface only has one method + initialize that has no parameters. +

+

+ The contract surrounding this interface is that the + initialize method is called once and the + method is the last one called during the initialization sequence. + Further implications include that the Component is now live, and it + can be used by other Components in the system. +

+ + +

+ The Startable interface is used by any + Component that is constantly running for the duration of its life. + The interface defines two methods: start and + stop. Neither method has any parameters. +

+

+ The contract surrounding this interface is that the + start method is called once after the + Component is fully initialized, and the stop + method is called once before the Component is disposed of. Neither + method will be called more than once, and start + will always be called before stop. + Implications of using this interface require that the + start and stop methods be + conducted safely (unlike the Thread.stop + method) and not render the system unstable. +

+ + +

+ The Suspendable interface is used by any + Component that is running for the duration of its life that permits + itself to be suspended. While it is most commonly used in + conjunction with the Startable interface, it + is not required to do so. The interface defines two methods: + suspend and resume. + Neither method has any parameters. +

+

+ The contract surrounding this interface is that + suspend and resume may be + called any number of times, but never before the Component is + initialized and started or after the Component is stopped and + disposed. Calls to suspend when the system is + already suspended should have no effect as well as calls to + resume when the system is already running. +

+ + + +

+ This group of interfaces describes the concern area of configuration. + If there are any problems, such as required + Configuration elements that are missing, then + you may throw a ConfigurationException. +

+ +

+ Components that modify their exact behavior based on configurations + must implement this interface to obtain an instance of the + Configuration object. There is one method + associated with this interface: configure with + a Configuration object as the only + parameter. +

+

+ The contract surrounding this interface is that the + configure method is called once during the + life of the Component. The Configuration + object passed in must not be null. +

+ + +

+ The Configuration object is a representation + of a tree of configuration elements that have attributes. In a + way, you can view the configuration object as an overly simplified + DOM. There are too many methods to cover in this document, so + please review the JavaDocs. You can get the + Configuration object's value as a + String, int, + long, float, or + boolean -- all with default values. You + can do the same for attribute values. You may also get child + Configuration objects. +

+

+ There is a contract that says that if a + Configuration object has a value that it + should not have any children, and the corollary is also + true -- if there are any children, there should be no value. +

+

+ You will notice that you may not get parent + Configuration objects. This is by design. + To reduce the complexity of the Configuration + system, containers will most likely pass child configuration + objects to child Components. The child Components should not have + any access to parent configuration values. This approach might + provide a little inconvenience, but the Avalon team opted for + security by design in every instance where there was a tradeoff. +

+ + +

+ Components that implement this interface behave very similar to + Recomposable Components. It's only method + is named reconfigure. This design decision is + used to minimize the learning curve of the Re* interfaces. + Reconfigurable is to + Configurable as + Recomposable is to + Composable. +

+ + + +

+ The concept of the Context in Avalon arose + from the need to provide a mechanism to pass simple objects from a + container to a Component. The exact protocol and binding names are + purposely left undefined to provide the greatest flexibility to + developers. The contracts surrounding the use of the + Context object are left for you to define in + your system, however the mechanism is the same. +

+ +

+ The Context interface defines only the + method get. It has an + Object for a parameter, and it returns an + object based on that key. The Context is + populated by the container, and passed to the child Component who + only has access to read the + Context. +

+

+ There is no set contract with the Context + other than it should always be read-only by + the child Component. If you extend Avalon's + Context, please respect that contract. It + is part of the Inversion of Control pattern as well as security by + design. In addition, it is a bad idea to pass a reference to the + container in the Context for the same reason that the Context + should be read-only. +

+ + +

+ A Component that wishes to receive the container's + Context will implement this interface. It + has one method named contextualize with the + parameter being the container's Context + object. +

+

+ The contract surrounding this interface is that the + contextualize method is called once during the + life of a Component, after LogEnabled but + before any other initialization method. +

+ + +

+ Components that implement this interface behave very similar to + Recomposable Components. It's only method + is named recontextualize. This design + decision is used to minimize the learning curve of the Re* + interfaces. Recontextualizable is to + Contextualizable as + Recomposable is to + Composable. +

+ + +

+ The Resolvable interface is used to mark objects that need to be + resolved in some particular context. An example might be an object + that is shared by multiple Context objects, + and modifies its behavior based on a particular + Context. The resolve + method is called by the Context before the + object is returned. +

+ + + +

+ Every system needs the ability to log events. Avalon uses its + LogKit project internally. While LogKit does have ways of accessing + a Logger instance statically, the Framework wishes to use the + Inversion of Control pattern. +

+ +

+ Every Component that needs a Logger instance implements this + interface. The interface has one method named + enableLogging and passes Avalon Framework's + Logger instance to the Component. +

+

+ The contract surrounding this method is that it is called only + once during the Component's lifecycle before any other + initialization step. +

+ + +

+ The Logger interface is used to abstract + away the differences in logging libraries. It provides only a + client API. Avalon Framework provides three wrapper classes that + implement this interface: LogKitLogger for + LogKit, Log4jLogger for Log4J, and + Jdk14Logger for JDK 1.4 logging. +

+ + + +

+ Avalon realizes that the Configuration object hierarchy can be + heavy in many circumstances. Therefore, we came up with a + Parameters object that captures the + convenience of Configuration objects with a + simple name and value pair. +

+ +

+ Any Component that wants to use Parameters + instead of Configuration objects will + implement this interface. Parameterizable + has one method named parameterize with the + parameter being the Parameters object. +

+

+ The contract is that this is called once during the lifecycle of + the Component. This interface is not compatible with the + Configurable interface. +

+ + +

+ The Parameters object provides a mechanism + to obtain a value based on a String name. + There are convenience methods that allow you to use defaults if the + value does not exist, as well as obtain the value in any of the + same formats that are in the Configurable + interface. +

+

+ While there are similarities between the + Parameters object and the + java.util.Property object, there are some + important semantic differences. First, + Parameters are + read-only. Second, + Parameters are easily derived from + Configuration objects. Lastly, the + Parameters object is derived from XML + fragments that look like this: +

+ + +]]> + + + + +

+ This used to be the core of Avalon Framework. The Component interface + and it friends have been deprecated in favor of the Service package, + which is exactly the same, except that the service package uses + java.lang.Object in place of the Component interface. + Any interface defined in this + concern area will throw ComponentException. +

+ +

+ Before the service package was put in place, every Avalon Component + had to implement the Component interface. We have removed this restriction + in the service package. + The Component Manager and Component Selector only handle Components. + There are no methods associated with this interface. It is only used as + a marker interface. +

+

+ For maximum backward compatibility with existing applications, it can still + be useful to implement the Component interface as older applications may + depend on it being available. +

+

+ Any Component must use default no parameter constructors. All + configurations are done with the + Configurable or + Parameterizable interfaces. +

+ + +

+ A Component that uses other Components needs to implement either this + interface or the new Serviceable interface. The new interface is the + preferred way of doing things. The interface has only one method + compose with a + ComponentManager passed in as the only + parameter. +

+

+ The contract surrounding this interface is that the + compose is called once and only once during + the lifetime of this Component. +

+

+ This interface along with any other interface that has methods + specified uses the Inversion of Control pattern. It is called by + the Component's container, and only the Components that this + Component needs should be present in the + ComponentManager. +

+ + +

+ On rare occasions, a Component will need a new + ComponentManager with new Component role + mappings. For those occasions, implement the recomposable + interface. It has a separate method from Composable called + recompose. +

+

+ The contract surrounding the interface states that the + recompose method can be called any number of + times, but never before the Component is fully initialized. When + this method is called, the Component must update itself in a safe + and consistent manner. Usually this means all processing that the + Component is performing must stop before the update and resume + after the update. +

+ + + +

+ The thread marker interfaces are used to signal to the container + essential semantic information regarding the Component use. They + mark a component implementation in regards to thread safety. It is + a best practice to delay implementing these interfaces until the + final Component implementation class. This avoids complications + when an implementation is marked ThreadSafe, + but a component that extends that implementation is not. The + interfaces defined in this package comprise part of what I call + the LifeStyle interfaces. There is one more + LifeStyle interface that is part of the + Excalibur package -- so it is an extension to this core + set -- Poolable that is defined in + Excalibur's pool implementations. +

+ +

+ is that the interface or the implementation precludes this + Component being accessed by several threads simultaneously. Each + thread needs its own instance of the Component. Alternatively, you + may use Component pooling instead of creating a new instance for + every request for the Component. In order to use pooling, you will + need to implement Avalon Excalibur's Poolable + interface instead of this one. +

+ + +

+ The contract with ThreadSafe Components is + that both their interface and their implementation function + correctly no matter how many threads access the Component + simultaneously. While this is generally a lofty design goal, + sometimes it is simply not possible due to the technologies you are + using. A Component that implements this interface will generally + only have one instance available in the system, and other + Components will use that one instance. +

+ + + +

+ The classes and interfaces in the root package for Avalon Framework + incorporates Cascading Exceptions, and a couple of generic utilities. + However, one class deserves mention beyond the others. +

+ +

+ Java versioning techniques are entries in + the manifest file in a jar. The problem is, when the jar is + unpacked you lose the versioning information, and the versioning + is in an easily modified text file. When you couple this with a + higher learning curve, detecting Component or Interface versions + is difficult. +

+

+ The Avalon team came up with the Version object to allow you to + have easily determined versions, and to compare versions. You may + implement the Version object in your + Components and your tests for the proper Component or minimum + version level will be much easier. +

+ + + +
+ + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/implementing.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/implementing.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,1090 @@ + + + + + Paul Hammant + Berin Loritsch + Using Avalon Frameowork + + + +
+

+ After your analysis is complete, you need to create the Components and + Services that make up your system. Avalon would be of little use if it + only described some idioms for you to use. Even then, the use of those + idioms and patterns would still help in understanding the overall system. + Avalon Excalibur provides some useful Components and utilities that you can + incorporate into your own system that will make your life much easier. For + our demonstration, we will go through the process of defining a Component + that retrieves a document instance from a repository. If you recall our + discussion about the theoretical Business Server, we identified this + Component as a Service. In practical situations, a Service is a Component + that has a larger scope. +

+
+
+

+ At this point, we define how to implement our Component. We will go + through the process of implementing the DocumentRepository Component + previously mentioned. The first things we need to figure out are the + concern areas for our Component. Then we have to figure out how our + Component will be created and managed. +

+
+

+ We have already defined the Role and the Interface for our + DocumentRepository Component in the last chapter, we are ready to + create the implementation. Because the interface for the + DocumentRepository only defines one method, we have an opportunity to + create a thread-safe Component. This is the most desired type of + component because it allows for the least amount of resource + utilization. In order for our implementation to be thread-safe, we do + need to be careful about how we implement the Component. Since all of + our documents are stored in a database, and we desire to use an + external Guardian Component, we will need access to other Components. + As responsible developers, we will want to log messages that will help + us debug our component, and track down what is going on internally. + The beauty of the Avalon Framework is that you only implement the + interfaces you need, and ignore the ones you don't. This is where + Separation of Concerns pays off. As you find you need a new concern + area addressed, you merely implement the associated interface, and + incorporate the new functionality. To the client of your Component, + there is no difference. +

+

+ Since it is a design goal to be thread-safe, we already know that we + need to implement the ThreadSafe interface. The DocumentRepository + interface only has one method, so the use of the Component's work + interface is compatible with that requirement. Furthermore, we know + that a Component will not be used before it is fully initialized, nor + will it be used once it is destroyed. +

+

+ There are a couple of implicit interfaces that we need to implement to + accomplish the design. We want our solution to be as secure as + possible and explicitly track whether the Component is fully + initialized or not. To accomplish this goal, we will implement the + Initializable and Disposable interfaces. Since specific information + about our environment may change, or may need to be customized, we need + to make our DocumentRepository Configurable. Our Component makes use + of other Components, and the method that Avalon provides to get + instances of the required Component is by using a ServiceManager. We + will need to implement the Serviceable interface to get an instance of + the ServiceManager. +

+

+ Because the DocumentRepository accesses the documents in the database, + we need to make a decision. Do we want to take advantage of the Avalon + Excalibur DataSourceComponent, or do we want to implement our own + Connection management code. For the sake of this paper, we will use + the DataSourceComponent. +

+

+ At this point, our skeleton class looks like this: +

+ + + +

+ You will notice some constructs in the above code. When you are + designing with security in mind, you should explicitly enforce every + contract on your Component. Security is only as strong as the weakest + link. You should only use a Component when you are certain it is fully + initialized, and never use it when it is disposed of. I placed the + logic that you would need in this skeleton class because that way you + can adopt the same practices in classes that you write. +

+
+
+

+ In order for you to understand how the Container/Component relationship + works, we will first discuss the manual method of managing Components. + Next, we will discuss how Avalon's Excalibur Component infrastructure + hides the complexity from you. You will still find times when you + would rather manage components yourself. Most of the time the power + and flexibility of Excalibur is just what you need. +

+
+

+ All of Avalon's Components are created somewhere. The code that + creates the Component is that Component's Container. The Container + is responsible for managing the Component's lifecycle from + construction through destruction. A Container can be the static + "main" method called from a command line, or it can be another + Component. Remember the Inversion of Control pattern when you + design your Containers. Information and method calls should only + flow from the Container to the Component. +

+ + Subversion of Control +

+ Subversion of Control is the anti-pattern to Inversion of Control. + Subversion of control is done when you pass a reference to a + Component's Container to the Component. It is also done when you + have a Component manage it's own lifecycle. Code that operates in + this manner should be considered defective. The interactions that + happen when you confuse the Container/Component relationship make + the system harder to debug and security harder to audit. +

+ +

+ In order to manage the child Components, you need to keep a reference + to them for their entire lifetime. Before the Container or any other + Component can use the child Component, it must go through the + initialization phase of its lifecycle. For our DocumentRepository, + the code will look something like the following: +

+ + + +

+ For the sake of brevity, I removed all the explicit checking from the + above code. You can see that manually creating and managing + Components is very detailed. If you forget to do one step in the + life of a Component, you will see bugs. This also requires intimate + knowledge of the Components you are instantiating. An alternate + approach would be to add a couple methods to the above + ContainerComponent that handles the + initialization of the components dynamically. +

+
+
+

+ Developer's are naturally lazy, so they would spend the time to write + a specialized ComponentManager that became the Container for all of + their Components in the system. That way they would not have to be + bothered with intimately knowing the interfaces of all the Components + in a system. That can be a daunting task. The Avalon developers + have created just such a beast. Avalon Excalibur's Component + architecture includes a ComponentManager that is controlled by + configuration files written in XML. +

+

+ There is a tradeoff when you relinquish the responsibility of + managing a Component to Excalibur's ComponentManager. You relinquish + the fine control over what Components are included in the + ComponentManager. However, if you have a large system, you will find + that manual control is a daunting task. In that case, it is better + for the stability of the system for one entity to centrally manage + all the Components in a system. +

+

+ Since there are varying levels of integration you want to achieve + with Excalibur's Component Architecture, we will start with the + lowest level. Excalibur has a group of ComponentHandler objects that + act as individual Containers for one type of Component. They manage + the complete life of your Component. Let me introduce the concept of + lifestyle interfaces. A lifestyle interface describes how the system + treats a Component. Since the lifestyle of a component has impact on + the running of a system, we need to discuss the implications of the + current lifestyle interfaces: +

+
    +
  1. +

    org.apache.avalon.framework.thread.SingleThreaded

    +
      +
    1. +

      + Not thread-safe or reusable. +

      +
      2. +
    2. +

      + When no lifestyle interface is supplied, this is assumed. +

      +
      3. +
    3. +

      + A brand new instance is created every time the Component is + requested. +

      +
      4. +
    4. +

      + Creation and initialization is delayed until you request the + Component. +

      +
      5. +
    +
    2. +
  2. +

    org.apache.avalon.framework.thread.Threadsafe

    +
      +
    1. +

      + Component is fully reentrant, and complies with all + principles of thread safety. +

      +
      2. +
    2. +

      + One instance is created and shared with all Composables that + request it. +

      +
      3. +
    3. +

      + Creation and initialization is done when ComponentHandler is + created. +

      +
      4. +
    +
    3. +
  3. +

    org.apache.avalon.excalibur.pool.Poolable

    +
      +
    1. +

      + Not thread-safe, but is fully reusable. +

      +
      2. +
    2. +

      + A pool of instances is created and the free instances are + returned to Composables that request it. +

      +
      3. +
    3. +

      + Creation and initialization is done when ComponentHandler is + created. +

      +
      4. +
    +
    4. +
+

+ The ComponentHandler interface is very simple to deal with. You + initialize the Constructor with the Java class, the Configuration + object, the ComponentManager, a Context object, and a RoleManager. + If you know that your Component will not need any of the + aforementioned items, you can pass a null in its place. After + that, when you need a reference to the Component, you call the "get" + method. After you are done with it, you call the "put" method and + pass the Component back to the ComponentHandler. The following code + will make it easier to understand. +

+ + + +

+ At this point, we only saved ourselves a few lines of code. We still + manually created our Configuration object, we still had to set the + Logger, and we still had to initialize and dispose of the + ComponentHandler objects. What we did at this point is simply protect + ourselves from changing interfaces. You may find it better for your + code to use this approach. Excalibur went further though. Most + complex systems have configuration files, and they allow an + administrator to alter vital Configuration information. Excalibur + can read a configuration file in the following format, and build the + Components in a system from it. +

+ + + + + + false + org.gjt.mm.mysql.Driver + jdbc:mysql:localhost/mydb + test + test + + + + false + org.gjt.mm.mysql.Driver + jdbc:mysql:localhost/myotherdb + test + test + + + + documents + + + security + + + +]]> + +

+ The root element can be anything you want. You will notice that we + now have several Components defined. We have our familiar + DocumentRepository class and GuardianComponent class, as well as a + couple of Excalibur DataSourceComponent classes. In addition, now we + have some specific configuration information for our Guardian + Component. In order to read that information into your system, + Avalon Framework provides some conveniences for you: +

+ + + +

+ This does simplify all the code we had for hand-building the + Configuration element earlier, and it limits the amount of + information we need to explicitly know right away. We will take one + last look at our Container class and see if we really have some + savings. Keep in mind that we have five components specified (a + ComponentSelector counts as a Component), and configurations for + each of them. +

+ + + +

+ Isn't this amazing? We have more than twice the number Components + initialized and ready for use with less than half the code (six lines + of code instead of thirteen lines of code). There is the drawback of + the Configuration file looking somewhat crazy, but it minimizes the + amount of code you have to write. +

+

+ There is a lot of activity happening under the hood of the + ExcaliburComponentManager. For each "component" element in the + configuration file, Excalibur creates a ComponentHandler for each + class entry and maps it to the role entry. The "component" element + and all it's child elements are used for the Configuration of the + Component. When the Component is an ExcaliburComponentSelector, the + Excalibur reads each "component-instance" element and performs the + same type of operation as before-this time mapping to the hint entry. +

+
+ Making the Configuration Pretty +

+ We can manage the configuration file's appearance with the use of + aliases. Excalibur uses a RoleManager to provide aliases for the + configuration system. A RoleManager can either be a dedicated + class that you create, or you can use the DefaultRoleManager and + pass in a Configuration object. If I use the DefaultRoleManager, I + will hide the role configuration file inside the jar with the rest + of the system. This is because the role configuration file is only + going to be altered by developers. Below is the interface for the + RoleManager: +

+ + + +

+ Let's take a look at how Excalibur uses the RoleManager in our + scheme. First, Excalibur will cycle through all the elements that + are direct children of the root element. This includes all + "component" elements like before, but this time when Excalibur + doesn't recognize an element name, it asks the RoleManager which + role we should use for this Component. If the RoleManager returns + null, the element and all it's child elements are ignored. Next, + Excalibur derives the class name from the role name. The last + method is to dynamically map a class name to a ComponentSelector's + child type. +

+

+ Excalibur provides a default implementation of the RoleManager that + is configured with an XML configuration file. The markup is very + simple, and it hides all the extra information you don't want your + administrator to see. +

+ + + + + + + + + +]]> + +

+ In order to use the RoleManager, you do need to alter the + "initialize" method of our Container class. You are using the + configuration builder to build a Configuration tree from this + file. Please remember, if you are going to use a RoleManager, you + must call the "setRoleManager" method before + the "configure" method. To demonstrate how you would retrieve this + XML file from the class loader, I will demonstrate the technique + below: +

+ + + +

+ Since we added six more lines of code, we need to see what it + bought us. Our final configuration file can be written like this: +

+ + + + + + false + org.gjt.mm.mysql.Driver + jdbc:mysql:localhost/mydb + test + test + + + + false + org.gjt.mm.mysql.Driver + jdbc:mysql:localhost/myotherdb + test + test + + + + documents + + + security + + + +]]> + +

+ As you can see, this is much more readable than how we started. + Now we can add any number of components to our system, and we won't + have to write any more code to support them. +

+
+
+
+
+
+

+ Now that we have created our Components, we will want to use them. You + access Components the same way regardless of how they were instantiated + or managed. You must implement the Composable interface to get a + reference to the ComponentManager. The ComponentManager holds all the + references to the Components you need. For the sake of our discussion, + we will assume that the ComponentManager given to us is configured in the + same manner as the final Configuration file in the last section. This + means that we have a Repository, a Guardian, and two DataSources. +

+
+

+ The Component management infrastructure requires that you release any + Component for which you have obtained a reference. The reason for this + restriction is so that the Component's resources can be properly + managed. A ComponentManager is designed for cases when you have + multiple types of Components with distinct roles. A ComponentSelector + is designed for cases when you have multiple types of Components + with the same role. Another unique aspect of the ComponentSelector is + that it is a Component by design. This enables us to get a + ComponentSelector from a ComponentManager. +

+

+ There are two valid approaches for handling references to external + Components. You can obtain your references during initialization, and + release them during disposal. You may also encapsulate the Component + handling in a try/catch/finally block. Each has its advantages and + disadvantages. +

+
+ + + +

+ As you can see by the sample code, this is easy to follow. The + object gets a reference to a Guardian Component when it first + receives the ComponentManager. If you could be guaranteed that the + Guardian Component was ThreadSafe, then this is all that is + necessary. Unfortunately, you cannot guarantee this for the long + term. To properly manage resources, we must release the Component + when we are done with it. That's why we kept a reference to the + ComponentManager. +

+

+ The main disadvantage of this approach comes into play when you are + dealing with pooled Components. The reference of the Component is + kept for the life of this object. It might not be a problem if the + object had a short life span, but if it was a Component managed by + the Excalibur component management architecture, its life span is as + long as the Component whose reference it has. What this means is + that we are essentially turning the Component's pool into a Factory. +

+

+ The main advantage of this approach is that the code is very clear on + how a Component is obtained and released. You don't have to have any + understanding of exception handling. +

+

+ One other nuance is that you are tying the existence of the Guardian + to the ability to initialize this object. Once an Exception is + thrown during the initialization phase of an object, you must assume + that the object is not valid. Sometimes you want to fail if a + required Component does not exist so this is not a problem. You do + need to be aware of this implication when you are designing your + Components though. +

+
+
+ + + +

+ As you can see, the code is a bit more complex. In order to + understand it, you have to understand Exception handling. This is + not necessarily a problem, because most Java developers know how to + handle them. You don't have to worry so much about the Component + life style with this approach, because we are releasing it as soon + as we no longer need it. +

+

+ The main disadvantage of this approach is the added complexity of the + exception handling code. In order to minimize the complexity and + make the code more maintainable, we extracted the working code into + another method. Keep in mind that we can get the reference to as + many Components as we possibly want inside the try block. +

+

+ The main advantage of this approach is that you are managing your + Component references more efficiently. Again, there is no real + difference if you are using ThreadSafe Components, but it makes a + real difference when you have pooled Components. There is a slight + overhead dealing with getting a new reference every time you use a + Component, but the likelihood of being forced to create a new + instance of the Component is minimized. +

+

+ Just like the Initialization and Disposal Approach, you have to + understand a subtle nuance. The Exception Handling Approach does not + fail on initialization if the Component is missing from the manager. + As mentioned before, this is not entirely bad. Many times, you want + an object to exist, but it is not a failure if a desired Component + is missing. +

+
+
+
+

+ For most operations, you will only need the ServiceManager. Since we + decided that we needed multiple instances of the DataSourceComponent, + we need to know how to get the instance we want. ServiceSelectors + are a little trickier than ServiceManagers because we are dealing + with hints to get the reference we need. A Component has a specific + Role, and this contract is well documented. However, sometimes we need + to select one of many Components for a Role. A ServiceSelector uses + an arbitrary object for the hint. Most of the time, the object is a + String, although you might want to use a Locale object to get a proper + internationalization Component. +

+

+ In our system we have set up, we chose to use Strings to select the + correct instance of the DataSourceComponent. We even gave ourselves a + Configuration element that references the exact string we need to get + the right Component. This is a good practice to follow, as it makes it + easier on administrators of a system. It is easier for an + administrator to see a reference to another Component than it is for + them to remember magic values for the configuration. +

+

+ Conceptually, getting a Component from a ServiceSelector is no + different than getting a Component from a ServiceManager. You just + have one more step. Remember that a ServiceSelector is a Component. + The ServiceManager will be set up to return the ServiceSelector + when you lookup its role. You then need to select the component from + the selector. To demonstrate, I will extend the code from the + Exception Handling Approach discussed previously. +

+ + + +

+ As you can see, we got the reference to the ServiceSelector using the + Role specified for the Component. We followed the Role naming + guidelines outlined in a previous chapter by adding the "Selector" + suffix to the Role name. It is also perfectly acceptable to use a + static interface for all the Role names in your system to minimize the + number of String concatenation in your code. +

+

+ Next, we obtained the reference to the DataSourceComponent from the + ServiceSelector. Our sample code assumed that we had already pulled + the required information from the Configuration object and placed it in + a class variable named "useDb". +

+
+
+
+

+ This last section is included to give you an idea of the types of + Components and utilities that are included with Apache Avalon Excalibur. + These utilities are robust, and fully usable in production systems. We + do have an unofficial staging project called "Scratchpad" where we iron + out implementation details for potential new utilities. Scratchpad + utilities are of varying quality, and their use is not guaranteed to + remain the same -- although you may have good experience with them. +

+
+

+ The CLI utilities are used by a number of projects including Avalon + Phoenix and Apache Cocoon to process command line arguments. It + provides facilities to print help responses, and to process options by + either a short name or a long name. +

+
+
+

+ The collection utilities provide some enhancements to the + Java Collections API. Among them is the ability + to find the intersections between two lists and a + PriorityQueue that is an enhancement to + Stack to allow the priority of objects override + the simple first in/last out Stack + implementation. +

+
+
+

+ We already discussed the use of this in the previous section. This is + Excalibur's most complex beast, but it provides a lot of functionality + in just a few classes. It will make one distinction more than simple + SingleThreaded or + ThreadSafe for managing a component type: + Poolable. If a Component implements Excalibur's + Poolable interface instead of the + SingleThreaded interface, it will maintain a + pool of Components and reuse instances. Most of the time this works + great. For those last remaining times where a Component cannot be + reused, use the SingleThreaded interface. +

+
+
+

+ The Avalon development team realized that many people wanted a simple + mechanism to build complex Logging target heirarchies. In the same + spirit as the RoleManager the team developed + a LogKitManager that can be given to the + Excalibur Component Management system meantioned above. Based on the + "logger" attribute it will give the proper Logger + object to the different Components. +

+
+
+

+ The concurrent package contains several classes + to assist in multithreaded programming: Lock + (a mutex implementation), DjikstraSemaphore, + ConditionalEvent, and + ThreadBarrier. +

+
+
+

+ This is modeled after the javax.sql.DataSource + class, but simplified. There are two implementations of the + DataSourceComponent: one that pools JDBC + connections explicitly, and one that uses a J2EE application server's + javax.sql.DataSource class. +

+
+
+

+ The IO utilties provide a number of FileFilters + and other File and IO specific utilities. +

+
+
+

+ The Pool implementations provide a Pool for + every occasion. You have an implementation that is blazingly fast, but + only usable in one thread -- which should be ok for implementing a + FlyWeight pattern. You also have DefaultPool, + which does not manage the number of objects in its pool. + SoftResourceManagingPool decommissions objects + that exceed a threshold when they are returned. Lastly, + HardResourceManagingPool throws an exception + when you have reached the maximum number of objects. The last three + pools are all ThreadSafe. +

+
+
+

+ The property utilities are used in conjunction with Context objects. + They give you the ability to expand "variables" in your + Resolvable object. It works like this: + "${resource}" will look for a Context value + named "resource" and substitute its value + for the symbol. +

+
+
+ + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/index.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/index.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,106 @@ + + + + + Paul Hammant + Berin Loritsch + Developing With Apache Avalon + + + +
+

+ Developing With Apache Avalon: Developer's Guide for the Avalon Framework +

+

+ Published 2001. Copyright 2001-2003 Apache Software Foundation. +

+ +

+ This developer's guide is dedicated to the three people who's vision + started the Avalon project: Federico Barbieri, Stefano Mazzocchi, and + Pierpaolo Fumagalli. Their concept for the Avalon project has stood + the test of time. +

+ + +

+ Redistribution and use in source and binary forms, with or + without modification, are permitted provided that the following + conditions are met: +

+
    +
  • +

    + Redistributions of source code must retain the above + copyright notice, this list of conditions and the following + disclaimer. +

    +
    • +
  • +

    + Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials + provided with the distribution. +

    +
    • +
  • +

    + The end-user documentation included with the redistribution, + if any, must include the following acknowledgment: + "This product includes software developed by the Apache + Software Foundation (http://www.apache.org/)." Alternately, + this acknowledgment may appear in the software itself, if + and wherever such third-party acknowledgments normally appear. +

    +
    • +
  • +

    + The names "Jakarta", "Apache Avalon", "Avalon Excalibur", + "Avalon Framework" and "Apache Software Foundation" must not + be used to endorse or promote products derived from this + software without prior written permission. For written + permission, please contact apache@apache.org. +

    +
    • +
  • +

    + Products derived from this software may not be called + "Apache", nor may "Apache" appear in their name, without + prior written permission of the Apache Software Foundation. +

    +
    • +
+

+ THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED + WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION + OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS + OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER + CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. +

+

+ This software consists of voluntary contributions made by many + individuals on behalf of the Apache Software Foundation. For more + information on the Apache Software Foundation, please see + <http://www.apache.org/>. +

+

+ Java and all Java-based + trademarks and logos are trademarks or registered trademarks + of Sun Microsystems, Inc., in the United States and other + countries. The Apache Software Foundation is independant of + Sun Microsystems. +

+ +
+ + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/introduction.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/introduction.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,342 @@ + + + + + Paul Hammant + Berin Loritsch + Introduction and Overview + + + +
+

+ In the beginning was Apache JServ. Stefano Mazzocchi and others + helping develop Apache JServ realized that several patterns used + in that project were generic enough to create a Server Framework. + On Wednesday January 27, 1999 (roughly a month after release 1.0b + of JServ) Stefano put together a proposal to start a project + called the Java Apache Server Framework. It was to be the basis + for all Java server code at Apache. The idea was to provide a + framework to put together components and reuse code across a + number of projects. +

+
+

+ Stefano Mazzocchi, Federico Barbieri, and Pierpaolo Fumagalli + created the initial version. Later in 2000, Berin Loritsch and + Peter Donald joined the project. By that time, Pierpaolo and + Stefano had moved on to other projects and Java Apache Server + Framework started to use the name Avalon. Those five developers + are the main people responsible for the current design and + concepts used by the framework. The current version is very + similar to the version that was released in June 2000. In fact, + the major difference is the reorganization of the packages, and + splitting the project into subprojects. The same design patterns + and interfaces exist today. +

+
+

+ Avalon is a parent project for five sub-projects: Framework, + Excalibur, LogKit, Phoenix, and Cornerstone. Most + people think of the Framework when they hear the name Avalon, + but it is more than that. Avalon began as the Java Apache + Server Framework that had the framework, utilities, components, + and a server's kernel implementation all in one project. +

+

+ Since all the pieces of Avalon are of different maturity levels, + and have different release cycles, we have decided to break + Avalon into the smaller projects mentioned above. That move also + enables new developers to understand and learn Avalon in distinct + chunks -- something that was almost impossible before. +

+ +

+ Avalon Framework is the basis for all the other projects under + the Avalon umbrella. It defines the interfaces, contracts, and + default implementations for Avalon. The Framework has the most + work put into it, and consequently is the most mature project. +

+ + +

+ Avalon Excalibur is a collection of server side Components that + you can use in your own projects. It includes pooling + implementations, database connection management, and Component + management implementations among others. +

+ + +

+ Avalon LogKit is a high speed logging toolkit that can be used by Framework, + Excalibur, Cornerstone, and Phoenix. It is modeled on the same + principles as the JDK 1.4 Logging package but is compatible with + JDK 1.2+. +

+ + +

+ Avalon Phoenix is a server kernel that manages the deployment + and execution of Services. +

+ + +

+ Avalon Cornerstone is a collection of services that you + can deploy in the Phoenix environment. The Blocks include socket + management and job scheduling among others. +

+ + +

+ Scratchpad is not really an official project, but it is the + staging area for software package that are not ready for inclusion in + the other projects yet. They are of varying quality, and their APIs are + not guaranteed to remain consistent until they are promoted. +

+ +
+
+

+ We are focusing on Avalon Framework in this overview, but we will + cover enough of Avalon Excalibur and Avalon LogKit to get you + started. We will use a hypothetical business server to demonstrate + how to practically use Avalon. It is beyond the scope of this + overview to define a full-blown methodology, or to cover every + aspect of all the sub projects. +

+

+ We decided to focus on Avalon Framework because it is the basis + for all of the other projects. If you can comprehend the framework, + you can comprehend any Avalon based system. You will also become + familiar with some of the programming idioms common in Avalon. + Another reason for focusing on the framework and touching on the + Avalon Excalibur and Avalon LogKit projects is that they are + officially released and supported. +

+
+
+

+ I have been asked on a couple of occasions to identify what Avalon + is good for, and what it is not good for. Avalon's focus is server + side programming and easing the maintainability and design of server + focused projects. Avalon can be described as a framework that + includes implementations of the framework. +

+

+ While Avalon is focused on server side solutions, many people have + found it to be useful for regular applications. The concepts used in + Framework, Excalibur, and LogKit are general enough to be used for + any project. The two projects that are more squarely focused on + the server are Cornerstone and Phoenix. +

+ + + + + + + + + + +
Framework
+
    +
  • +

    + A supporting or enclosing structure. +

    +
    • +
  • +

    + A basic system or arrangement as of ideas. +

    +
    • +
+
+ Webster's II New Riverside Dictionary +
+

+ The word framework is broad in application. + Frameworks that focus on a single industry like medical systems + or communications are called vertical market frameworks. The + reason being that the same framework will not work well in other + industries. Frameworks that are generic enough to be used across + multiple industries are known as horizontal market frameworks. + Avalon is a horizontal market framework. You would be able to + build vertical market frameworks using Avalon's Framework. +

+

+ The most compelling example of a vertical market framework built + with Avalon is the publishing framework Apache Cocoon. Apache + Cocoon version 2 is built using Avalon's Framework, Excalibur, and + LogKit projects. It makes use of the interfaces and contracts in + the Framework to reduce the time it takes for a developer to learn + how Cocoon works. It also leverages the data source management and + component management code in Excalibur so that it does not have to + reinvent the wheel. Lastly, it uses the LogKit to handle all the + logging in the publishing framework. +

+

+ Once you understand the principles behind Avalon Framework, you will + be able to comprehend any system built on Avalon. Once you can + comprehend the system, you will be able to catch bugs more quickly + that are due to the misuse of the framework. +

+ +

+ It is important to state that trying to use any tool as a magic + formula for success is begging for trouble. Avalon is no exception + to this rule. Even though Avalon's Framework was designed to work for + server solutions, it is equally at home when using it to build + building a Graphical User Interface (GUI) applications. Two examples + of this are + D-Haven.org's GUIApp + and Jesktop +

+

+ While you need to consider if Avalon is right for your project, + you can still learn from the principles and design that went into + it. The question you need to ask yourself is, "Where is this + project going to be used?" If the answer is that it will be run + in a server environment, then Avalon is a good choice whether you + are creating a Java Servlet, or creating a special purpose server. + If the answer is it will be run on a client's machine with no + interaction with a server, than chances are that Avalon might not + be a good fit. Even then, the Component model is very flexible + and can help manage complexity in a large application. +

+ +
+
+

+ All of Avalon is built with specific design principles. The two + most important patterns are Inversion of Control + and Separation of Concerns. Component Oriented + Programming, Aspect Oriented Programming, and Service Oriented + Programming also influence Avalon. Volumes could be written about + each of the programming principles, however they are design mindsets. +

+ +

+ Inversion of Control (IOC) is the concept that a Component is + always externally managed. This phrase was originally coined + by Brian Foote in one of his papers ( http://www.laputan.org/drc/drc.html + ) Everything a Component needs in the way of Contexts, + Configurations, and Loggers is given to the Component. In + fact, every stage in the life of a Component is controlled by + the code that created that Component. When you use this + pattern, you implement a secure method of Component + interaction in your system. +

+ + + +
Warning!
+ IOC is not equivalent to security! IOC provides a mechanism + whereby you can implement a scalable security model. In order + for a system to be truly secured, each Component must be secure, + no Component can modify the contents of objects that are passed + to them, and every interaction has to be with known entities. + Security is a major topic, and IOC is a tool in the programmer's + arsenal to achieve that goal. +
+ + +

+ The idea that you should view your problem space from different + concern areas resulted in the Separation of Concerns (SOC) pattern ( + + http://www.research.ibm.com/hyperspace/MDSOC.htm + ). + An example would be viewing a web server from different viewpoints + of the same problem space. A web server must be secure, stable, + manageable, configurable, and comply with the HTTP specifications. + Each of those attributes is a separate concern area. Some of these + concerns are related to other concerns such as security and + stability (if a server is not stable it can't be secure). +

+

+ The Separation of Concerns pattern in turn led to Aspect Oriented + Programming (AOP) ( + http://eclipse.org/aspectj/). + Researchers discovered that many concerns + couldn't be addressed at class or even method granularity. Those + concerns are called aspects. Examples of aspects include managing + the lifecycle of objects, logging, handling exceptions and cleaning + up resources. With the absence of a stable AOP implementation, the + Avalon team chose to implement Aspects or concerns by providing + small interfaces that a Component implements. +

+ + +

+ Component Oriented Programming (COP) is the idea of breaking a + system down into components, or facilities within a system. Each + facility has a work interface and contracts surrounding that + interface. This approach allows easy replacement of Component + instances without affecting code in other parts of the systems. + The major distinction between Object Oriented Programming (OOP) + and COP is the level of integration. The complexity of a COP + system is more easily managed due to fewer interdependencies + among classes, promoting the level of code reuse. +

+

+ One of the chief benefits of COP is the ability to modify portions + of your project's code without breaking the entire system. Another + benefit is the ability to have multiple implementations of the + Component that you can select at runtime. +

+ + +

+ Service Oriented Programming (SOP) is the idea of breaking a + system down into services provided by the system. +

+ + + + +
Service
+
    +
  • +

    + Work or duties performed for others. +

    +
    • +
  • +

    + A facility offering repair or maintenance. +

    +
    • +
  • +

    + A facility providing the public with a utility. +

    +
    • +
+
Webster's II New Riverside Dictionary
+

+ Avalon's Phoenix identifies a service as the interface and + contracts for a facility that Phoenix will provide. The + implementation of the service is called a Block. It is + important to realize that a server is made up of multiple + services. To take the example of a Mail server, there are + the protocol handling services, the authentication and + authorization services, the administration service, and the + core mail handling service. +

+

+ Avalon's Cornerstone provides a number of low-level services + that you can leverage for your own systems. The services + provided are connection management, socket management, + principal/role management, and scheduling. We touch on + services here because it is relevant to the process of + decomposing our hypothetical system down into the different + facilities. +

+ +
+ + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/navigation.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/navigation.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,40 @@ + + + Apache Avalon + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/strategies.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/developing/strategies.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,140 @@ + + + + + Paul Hammant + Berin Loritsch + It's a Stragedy! + + + +
+

No, it's not a typo. The title has a deliberate play on words + that implies that incorrect strategies can end up in tragedy. While + the word "tragedy" may be a bit strong, the thought process does + have a ring of truth to it. In this chapter we attempt to give you + helpful hints and tips to boost the performance of your code and + your development team. We will break the discussion into logging + strategies, development strategies, component strategies, testing + strategies, and finally some notes on security strategies.

+
+
+ +

Logging is a necessary function in any system. The problem + arises when the logging is not implemented in an efficient + manner. Before we get into the nuts and bolts of how + to create an efficient logging implementation, we have to identify + what + logging efficiency is.

+ +

In the spirit of the Separation of Concerns pattern, there + are two problem domains to consider: log organization and log + writing. Log organization is primarily concerned with how the + log categories are organized, and how the log files are + organized. Log writing has to do with the mechanics of writing + log entries.

+ + + +

The Avalon framework and team advocate a category based + approach to organizing loggers as opposed to a class name + based approach. There is a very good reason for this. First + is that categorization allows you to put information of like + kind in one location. Second, it allows you to turn on and + off an entire category of log messages.

+ +

The arguments for the class name based logging usually + fall under these assumptions:

+ +
    +
  1. +

    There is an implicit match between a class and a category.

    +
    2. + +
  2. +

    It makes it easier to get debug information from a + specific class if we are having problems with it.

    +
    3. + +
  3. +

    The configuration file can handle the actual mapping + of classname to log file.

    4. +
+ +

While these arguments have their point, so does a strict + category based logging approach:

+ +
    +
  1. +

    You can narrow your log messages farther than simple + class granularity. This way you can get information from + the part of the class that really needs it.

    2. + +
  2. +

    More often than not, a group of classes make up a + Component. In most cases, the Component is what you are + really interested in--not the individual classes.

    +
    3. + +
  3. +

    It is easier to manage a configuration file with + only a few categories that are bound to Component + instances during runtime you can separate the log files by + who is concerned with their contents.

    4. +
+ + + + +

I would argue that it is a mistake to use only one + category for all logging. The reason is that you will + inevitably need to turn on and off a whole class of + messages. Another reason is that you will need at least one + category for each log file you have. One effective approach + is to separate your logging needs into roles and + classifications.

+ +

If you have already decomposed your system into + Components, then you have one set of categories defined. I + would use a shorthand name for the category names for simple + reference (e.g. "resource" instead of + "org.apache.avalon.excalibur.resource.ResourceManager"). The + simplified names can be used for a broad set of + classes. Using the same example, the name "resource" implies + the Resource class, its manager, and anything that is + directly associated with the concept of a "resource".

+ +

You can also use classifications as a specialization of + the main role classification. For example, all + ComponentManager code would have a category name of + "component". This would allow you to have a Category manager + for the aforementioned "resource" infrastructure. Typically + classifications are sub-categories. In this case, the full + name of the "component" category would be + "resource.component". This means that we are referring to the + "component" classification for the "resource" role.

+ +

Most of your logging needs can be organized into this two + dimensional cross-section of Role and Classification. Roles are + best for main categories due to their logical + separation. Typical classifications are "component", "security", + and "pool". These same classifications can be used as standard + sub-categories of the different roles. This way your log entries + can have fine-grained control that is logically organized.

+ + + +

+The mechanics of log writing can vastly affect the +performance of your code. For instance, if you concatenate several +strings together in your log messages, the Java Virtual Machine +converts the concatenation to a StringBuffer, and performs the +expensive toString operation on the result. The +Logger interface provides a mechanism to optimize away +these conversions when they are not needed.

+ + +
+ + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/doc/articles.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/doc/articles.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,56 @@ + + + + Avalon Documentation Team + Apache Avalon: Articles + + + +
+

+ Avalon need not be as mysterious as its Arthurian counterpart. + The following articles will help guide you on your own quest for + understanding. +

+ +
    +
  • + Developing With Avalon: + An excellent white paper on the Avalon framework. + Recommended reading! +
    • +
  • + An Introduction to COP: + An introduction to Component Oriented Programming and the + core Avalon Framework. +
    • +
  • + COP Development + Principles: A look at design principles to consider when + developing in Avalon and COP in general. +
    • +
  • + The Avalon + Lifecycle: Introduces the standard Avalon lifecycle for components. +
    • +
  • + The Need For + Avalon: + In this document, Stefano introduces his vision for the Java Apache + Server Framework project. He explain why he believes that + open-source projects should invest more time in software + engineering and why this may be worth while even in very successful + and high quality software projects. [HISTOROICAL] +
    • +
  • + What Is A + Server: Pierpaolo Fumagalli explains how a + server could be developed using the benefits offered by the + Java Apache Server Framework (Avalon) and introduces the + reader to the concept of what a Block. [HISTORICAL] +
    • +
+ +
+ + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/doc/index.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/doc/index.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,128 @@ + + + + Avalon Documentation Team + Apache Avalon: Documentation + + + +
+

+ Avalon need not be as mysterious as its Arthurian counterpart. + The following documentation will help guide you on your own quest for + understanding. +

+ + + + + + + + + + + + + + + + + + + + + + + + + +
ResourceDescription
+ + Wiki + + The Avalon Wiki contains a growing collection of information + about Avalon, random thoughts on component models and + container solutions, roadmaps, development discussions, + general ideas and other inspirational material. Feel free to + contribute! +
+ + FAQ + + A community-maintained Frequenty Asked Questions database + in our wiki. +
+ + Glossary + Glossary of terms for Avalon technology
Product Documentation Each individual product or sub-project has its own section which + includes API documentation (javadocs), usage material, and + often simple tutorials.
Mailing ListsThe mailing list archives are full of tips, examples, + solutions, and explanations about Avalon.
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ResourceDescription
+ + Developing With Avalon + The Avalon Developers Guide. An excellent white paper + on the Avalon framework. Recommended reading!
+ An + Introduction to COP + An introduction to Component Oriented Programming and the + core Avalon Framework.
+ + COP Development Principles + A look at design principles to consider when developing in + Avalon and COP in general. +
+ + The Avalon Lifecycle + Introduces the standard Avalon lifecycle for components.
+ + The Need For Avalon + + In this document, Stefano introduces his vision for the Java Apache + Server Framework project. He explain why he believes that + open-source projects should invest more time in software + engineering and why this may be worth while even in very successful + and high quality software projects. [HISTOROICAL] +
+ What Is A + Server Pierpaolo Fumagalli explains how a + server could be developed using the benefits offered by the + Java Apache Server Framework (Avalon) and introduces the + reader to the concept of what a + Block. [HISTORICAL] +
+ +
+ + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/doc/navigation.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/doc/navigation.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,51 @@ + + + + + Apache Avalon + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/doc/wiki.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/doc/wiki.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,14 @@ + + + + Avalon Documentation Team + Apache Avalon: Wiki + + + +
+

The Avalon Wiki contains a growing collection of information about Avalon, random thoughts on component models and container solutions, roadmaps, development discussions, general ideas and other inspirational material.

+
+ + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/download.cgi ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/download.cgi Mon Jan 26 20:20:51 2004 @@ -0,0 +1,6 @@ +#!/bin/sh +# Wrapper script around mirrors.cgi script +# (we must change to that directory in order for python to pick up the +# python includes correctly) +cd /www/www.apache.org/dyn/mirrors +/www/www.apache.org/dyn/mirrors/mirrors.cgi $* Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/download.html ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/download.html Mon Jan 26 20:20:51 2004 @@ -0,0 +1,276 @@ + + + + Apache Avalon - Apache Avalon Downloads + + + + + + + + + + + + + + + +
+ + +
+
+
+

+ Avalon Download Site +

+ +
+ + +

Use the links below to download a binary distribution of + Avalon from one of our mirrors. It's a good idea to + verify the integrity + of the downloaded files using signatures downloaded from our + main distribution directory.

+ +

Avalon is distributed as zip and tar.gz + archives - the contents are the same. Please note that the tar.gz + archives contain file names longer than 100 characters and have been + created using GNU tar extensions. They must be untarred with a GNU + compatible version of tar.

+ +

If you do not see the file you need in the links below, please + see the master + distribution directory or, preferably, its + mirror.

+ +

Mirror

+

You are currently using the [preferred]. + If you encounter a problem with this mirror, please select another + mirror. If all mirrors are failing, there are backup + mirrors (at the end of the mirrors list) that should be available.

+ +
+

Other mirrors: + +

+ +

License

+ +

All avalon products are distributed under the terms of a slightly +modified Apache Software License (version 1.1). See our +License page, or the LICENSE.txt files +included in each distribution.

+ +

Projects

+ +

Here's a list of the most commonly requested distributions. You can +browse the repository for a full +range of our various distributions, including older versions.

+ +

Please note: we're still filling up this list; its incomplete +at the moment.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProductBinarySourceJars
Avalon-Fortressbinariesbroswejars
Avalon-Frameworkbinariessourcejars
Avalon-Logkitbinariesbroswejars
Avalon-Merlinbinariesbroswejars
Avalon-Phoenixbinariesbroswejars
+ +

Verify Releases

+ +

It is essential that you verify the integrity of the downloaded +files using the PGP or MD5 signatures.

+

The PGP signatures can be verified using PGP or GPG. First +download the KEYS +as well as the asc signature file for the particular +distribution. Make sure you get these files from the +main distribution +directory, rather than from a mirror. Then verify the signatures +using

+

+% pgpk -a KEYS
+% pgpv name-of-distributed-file.tar.gz.asc
+ +or
+ +% pgp -ka KEYS
+% pgp name-of-distributed-file.tar.gz.asc
+ +or
+ +% gpg --import KEYS
+% gpg --verify name-of-distributed-file.tar.gz.asc +

+ + + +

Doing so will ensure that your maven-enabled projects will always +be able to find the latest avalon binaries.

+ +
+ +
+
+
+
+ + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/apache-avalon-logo.png ============================================================================== Binary file. No diff available. Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/avalon-logo.svg ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/avalon-logo.svg Mon Jan 26 20:20:51 2004 @@ -0,0 +1,538 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +]> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The + + + Apache Avalon Project + + + h t t p : / / a v a l o n . a p a c h e . o r g / + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/avalon-power.png ============================================================================== Binary file. No diff available. Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/deployment.gif ============================================================================== Binary file. No diff available. Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/group-logo.gif ============================================================================== Binary file. No diff available. Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/icon.png ============================================================================== Binary file. No diff available. Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/merlin.gif ============================================================================== Binary file. No diff available. Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/project-logo.gif ============================================================================== Binary file. No diff available. Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/server-01.gif ============================================================================== Binary file. No diff available. Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/server-02.gif ============================================================================== Binary file. No diff available. Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/server-03.gif ============================================================================== Binary file. No diff available. Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/server-04.gif ============================================================================== Binary file. No diff available. Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/tortoise-cvs-screenshot.gif ============================================================================== Binary file. No diff available. Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/tortoisecvs-checkout.jpg ============================================================================== Binary file. No diff available. Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/tortoisecvs-settings.jpg ============================================================================== Binary file. No diff available. Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/wincvs-checkout.jpg ============================================================================== Binary file. No diff available. Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/wincvs-preferences.jpg ============================================================================== Binary file. No diff available. Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/images/wincvs-settings.jpg ============================================================================== Binary file. No diff available. Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/index.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/index.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,94 @@ + + + + Alex Karasulu + Apache Directory Project + + +
+ +
+
+

+ Describe the project and its intentions here. +

+
+
+
    +
  • + + Naming + : + Describes the Naming subproject here. +
    • +
  • + + LDAP + : + Describes the LDAP subproject here. +
    • +
  • + + Janus + : + Describes the Janus subproject here. +
    • +
  • + + Snickers + : + Describes the Snickers subproject here. +
    • +
+
+
+

+ If you're new to the Apache Directory Project, "Welcome!" You may + be now wondering where to start. The following should help you + find what you're looking for. +

+ +

+ Talk about the old LDAPd server and the new Eve server which + is to replace it for users of the software. +

+ + +

+ Talk and list the various APIs here that are useful to developers. +

+ + +

+ Whether you're a contributor or a committer, you'll should + familiarize yourself with the Coding Standards + document. The Community + section also reviews various standards, policies, and practices + within the Directory community. +

+ + +

+ Talk about the protocol. +

+ + +

+ Talk about the ASN.1 and Basic Encoding Rules. +

+ + +

+ Put some resource information here. +

+ +
+ + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/license.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/license.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,59 @@ + + + + Avalon Documentation Team + Apache Avalon License + + + +
+ + ============================================================================ + The Apache Software License, Version 1.1 + ============================================================================ + + Copyright (C) 1997-2001 The Apache Software Foundation. All rights reserved. + + Redistribution and use in source and binary forms, with or without modifica- + tion, are permitted provided that the following conditions are met: + + 1. Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + + 2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + + 3. The end-user documentation included with the redistribution, if any, must + include the following acknowledgment: "This product includes software + developed by the Apache Software Foundation (http://www.apache.org/)." + Alternately, this acknowledgment may appear in the software itself, if + and wherever such third-party acknowledgments normally appear. + + 4. The names "Jakarta", "Avalon", "Excalibur", "Avalon Framework" and + "Apache Software Foundation" must not be used to endorse or promote + products derived from this software without prior written permission. + For written permission, please contact apache@apache.org. + + 5. Products derived from this software may not be called "Apache", nor may + "Apache" appear in their name, without prior written permission of the + Apache Software Foundation. + + THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, + INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE + APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLU- + DING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS + OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON + ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF + THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + This software consists of voluntary contributions made by many individuals + on behalf of the Apache Software Foundation. For more information on the + Apache Software Foundation, please see <http://www.apache.org/>. + +
+ + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/mailing-lists.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/mailing-lists.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,63 @@ + + + + Avalon Documentation Team + Apache Avalon E-Mail Lists + + + + +
+

A mailing list is an electronic discussion forum that anyone can subscribe to. + When someone sends an email message to the mailing list, a copy of that message is + broadcast to everyone who is subscribed to that mailing list. Mailing lists provide + a simple and effective communication mechanism. With potentially thousands of + subscribers, there is a + common set of etiquette + guidelines that you should observe.

+
+
+ +

+ Light Traffic + Subscribe + Unsubscribe + Archive + News gateway +

+

+ This list is for users who are using Avalon in their own projects to ask + questions, share knowledge, and discuss issues related to using the Avalon + suite of software. +

+ + +

+ Medium Traffic + Subscribe + Unsubscribe + Archive + News gateway +

+

+ This list is for developers who are maintaining Avalon or wanting to influence + its design to ask questions, share knowledge, and discuss issues related to developing + the Avalon framework. +

+ + +

+ Medium Traffic + Subscribe + Unsubscribe + News gateway +

+

+ Changes to the Avalon CVSes are echoed to this list. +

+ +
+ + + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/navigation.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/navigation.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,47 @@ + + + + + Apache Directory + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/news.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/news.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,119 @@ + + + + Avalon Documentation Team + Apache Avalon News + + + + +
+ + + +

+ Thanks to Leo Simons and the other good folks of Apache Infrastructure, + Avalon has a new wiki site! The new + MoinMoin based site is at + http://wiki.apache.org/avalon. + Please contribute to our growing documentation! +

+ + + +

+ The Avalon Documentation Team is pleased to present the new and + improved Avalon web site. There will be regular updates + through November as we convert and update our site + documentation. If you have any suggestions or want to + contribute, please send an email to the developers' mailing list. +

+ + + +

+ The Avalon Team is proud to announce the release of Merlin 3.0 + Beta 1. Merlin is an advanced component and service management + solution that simplifies and enhances component development, + assembly and service deployment concerns. +

+

+ Merlin 3.0 binaries can be downloaded from the following site: +

+

+ + http://www.apache.org/dist/avalon/merlin/binaries/ +

+ +

Key Product Features:

+
    +
  • auto assembly
    • +
  • muli-layer configuration management
    • +
  • advanced context management
    • +
  • composite component management
    • +
  • packaged deployment scenarios
    • +
  • local and remote repository integration
    • +
  • integral jar extension management
    • +
  • Maven plugin support for meta-info generation and simulated deployment
    • +
  • product packaging and install services
    • +
  • based on Avalon component meta model
    • +
  • support for legacy migration
    • +
+ +

Product documentation, tutorials and specifications are available + on the Merlin Home + site or the download link referenced above. +

+ + + + + +

The Avalon Team is pleased to announce availability of the upgrade + releases of the Excalibur i18n + internationalization and Excalibur + Configuration utilities. These updates include minor + enhancements to configuration listing and equality testing, and + facilities enabling dynamic updating of a language locale. +

+ + + + +

+ The Avalon Team is proud to announce the general availability of Avalon Framework 4.1.5 +and Avalon Meta 1.1 +packages. The new framework release includes enhancements linked to +the new Avalon Meta model. Collectively the two packages represent an +important step forward in the evolution of the Avalon component model. +

+ +

New features introduced under the Avalon Meta package include:

+
    +
  • component type descriptor meta-info model
    • +
  • container-neutral framework
    • +
  • declaration of component type dependencies
    • +
  • declaration of service publication
    • +
  • specification of logging channel assumptions
    • +
  • context strategy and context casting assumptions
    • +
  • context entry dependencies
    • +
  • context entry generation semantic
    • +
  • configuration schema details
    • +
  • XML and serialized object support
    • +
+ +

+ Tools released in conjunction with the Avalon Meta package include + an Ant task and Maven plugin supporting the automation of meta-info + generation from @avalon javadoc tags. +

+ + + +
+ + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/components/index.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/components/index.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,68 @@ + + + + + + Stephen McConnell + Apache Avalon: Components + + + +
+ + + + + + + + + + + + + + + + + + +
TopicDescription
+ Cornerstone Collection +

+ The cornerstone project is the home of a set of component blocks + that can be used to simplify application development. These components + and typically singleton components that represent structural building + blocks. +

+
+ Excalibur Utilities +

+ The Excalibur project is the home of a set of utility services + used in the construction of formal blocks or container facilities. + Services include internationalizatioin, configuration utilities, + thread management, SEDA sytel even handling, a logging subsystems, + etc. +

+
+ Avalon Logkit +

+ Logkit is a complete logging framework (like log4j) as an + Avalon component. Most Avalon containers use it as the + default logging implementation. +

+
+ Third-Party Components +

+ A series of third-party components developed both here at Apache + and under external projects are described on this page. +

+
+ +
+ + + + + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/components/navigation.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/components/navigation.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,50 @@ + + + + + Apache Avalon + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/containers/index.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/containers/index.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,105 @@ + + + + Avalon Documentation Team + Apache Avalon: Containers + + + +
+ + +

Within Avalon their are a number of container solutions. This + reflects a historical divergence and a present convergence within + the area of containment technology within Avalon. The original + containment solutions ECM and Phoenix focussed on very different + approaches to component management. The ECM model dealt with + primarily pooled objects used in environments such as + Cocoon. The + Phoenix model dealt with a strict singleton model supporting + project such as James. + Recent developments have resulted in the + release of + Fortress + and Merlin. + Fortress replaces the ECM solution + and is positioned as a migration vehicle for components to move + towards Avalon's latest container - Merlin. The Merlin container + is an attempt at being a flexible and adaptive embedded container + that leverages a set of common containment facilities. + Merlin provides support for legacy Phoenix components and includes + many of of the lifestyle concepts introduced within Fortress.

+ + + + + + + + + + + + + + + + + + + +
ProductDescription
+

+ + Avalon Merlin +

+ 		+

+ The Merlin project deals with the broad area of service + and component management. The Merlin system is a container + that provides comprehensive support for the management of + complex component-based systems. Merlin uses a component + meta-model to facilitate the automated assembly and + deployment of simple and composite components. +

+
+

+ + Avalon Fortress +

+ 		+

+ 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. +

+
+

+ + ECM +

+ 		+

+ This package contains the ExcaliburComponentManager (ECM). ECM has + been depricated in favour of the new Fortress container.

+
+

+ + Phoenix +

+ 		+

+ Phoenix is a micro-kernel designed and implemented on top of + the Avalon framework. It provides a number of facilities to + manage the environment of Server Applications. Such facilities + include log management, classloading, thread management and + security. +

+
+ +
+ + + \ No newline at end of file Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/containers/navigation.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/containers/navigation.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,53 @@ + + + + + Apache Avalon + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/framework/index.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/framework/index.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,76 @@ + + + + Avalon Documentation Team + Apache Avalon: Framework + + + +
+ + +

The Avalon Component model is made up of a combination of classic + interfaces that define the artifacts exchanged between a container and + a component. The requirements presented by a component to container + are expressed using meta-info descriptors that are colocated with + component classes. Interfaces and default implementations are described + under Avalon Framework package. The meta-info descriptors and related tools + are included under the Avalon Meta package.

+ + + + + + + + + + + + + + + + + + + + +
ProductDescription
+

+ + Avalon Framework API and Implementation +

+ 		+

The Avalon Framework API and Implementation consists of interfaces that define relationships between commonly used application components, best-of-practice pattern enforcements, and several lightweight convenience implementations of the generic components.

+
+

+ + Avalon Meta +

+ 		+

The Avalon Meta Model defines the functional criteria for component types and services. A Type definition contains information about deployment and runtime dependencies together with information about the services that a component type can provide.

+
+

+ + Avalon Utilities +

+ 		+

A set of utilities shared by framework components supporting default property + management, environment variable resolution, exceptio reporting and a + parameterized map implementation (using within the repositroy package).

+
+

+ + Avalon Repository +

+ 		+

A joint initative by the Avalon Project and the Apache Directory Project + in the development of an inteligent bootstrappig, resource replication, + and artifact management framework.

+
+ +
+ + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/framework/navigation.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/framework/navigation.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,50 @@ + + + + + Apache Avalon + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/index.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/index.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,46 @@ + + + + Avalon Documentation Team + Apache Avalon: Products + + + +
+

+ Avalon consists of a number of product and sub-projects. +

+ + + + + + + + + + + + + + + + + +
NameDescription
Framework +

The framework collection includes a component meta model + used to describe component dependencies towards a container, and, + the classic framework APIs that describe the runtime contact + between a container and a component.

+
Containers +

A container is a platform supporting the management of + components. This page provides an overview of current and + legacy container solutions and links to respective home pages.

+
Components +

The components page provides a summary of the two main + component groups in Avalon - the course grained cornerstone + suite and the fine grain utilites under Excalibur.

+
+
+ + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/navigation.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/product/navigation.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,50 @@ + + + + + Apache Avalon + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/related/apache.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/related/apache.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,62 @@ + + + + Avalon Documentation Team + Apache Avalon: Related - Apache + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescription

Apache Directory Project

 +

+The Apache Java LDAP Server (a.k.a. Eve, f.k.a. LDAPd) is the flagship server under the new Apache Directory Project. Eve is a pure Java implementation of an LDAP version 3 server based on Avalon and SEDA. Eve, as the first of its kind, will revolutionize the way directories are used by enabling server embedding and rich database constructs like stored procedures and triggers. Eve leverages JNDI as the embedding API and allows the use of a server side JNDI LDAP provider to efficiently access server databases within stored procedures. +

+

+Eve's simplicity and modularity, thanks primarily to Avalon design patterns, makes it an ideal protocol experimentation and extention framework. Those forging the future of internet directory protocols on standards bodies like ldap-bis and others can use Eve to test and demonstrate the substance of new RFCs. Eve's swapable protocol components and plugable backends puts the focus on the protocol rather than code management and porting. +

+

Cocoon

Apache Cocoon is a web development framework built around the concepts of separation of concerns and component-based web development. +Cocoon implements these concepts around the notion of 'component pipelines', each component on the pipeline specializing on a particular operation. This makes it possible to use a Lego(tm)-like approach in building web solutions, hooking together components into pipelines without any required programming. +Cocoon is "web glue for your web application development needs". It is a glue that keeps concerns separate and allows parallel evolution of all aspects of a web application, improving development pace and reducing the chance of conflicts. +

FTP Server Project

FtpServer is a server component for Avalon that allows remote FTP client to attach and download files. The client software can be any type of FTP client written in any language. The criteria for eligibility is RFC compliance. The server uses several components. Some of the components have multiple implementations. For example user management has implementations that will use LDAP, JDBC and Cornerstone's Store facility for storage. +The server has a management console (GUI) that can connect over RMI to the server. +

Fulcrum

Fulcrum was originally created as part of the Turbine 3 effort. +The idea was to be able to decouple the services from Turbine 2 allowing +them to be used on both projects. Fulcrum is currently evolving into a +generic component repository useful in building web applications. Each +service is been converted into a stand alone component that can be released +independently of the other components. +

James

 +

The Java Apache Mail Enterprise Server (a.k.a. Apache James) is a 100% pure Java SMTP and POP3 Mail server and NNTP News server. James was designed to be a complete and portable enterprise mail engine solution based on currently available open protocols.

+

James is also a mail application platform. The James team have developed a Java API to let you write Java code to process emails that we call the mailet API. A mailet can generate an automatic reply, update a database, prevent spam, build a message archive, or whatever you can imagine. A matcher determines whether your mailet should process an email in the server. The James project hosts the Mailet API, and James provides an implementation of this mail application platform API.

+
+ +
+ + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/related/external.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/related/external.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,159 @@ + + + + Avalon Documentation Team + Apache Avalon: Related External + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescription

Plexus

An Avalon container developed externally at Codehaus

Keel Framework

+ Keel is ready made server side infrastructure Keel incorporates + multiple open source projects to provide you with a best of breed + framework that works right out of the box.

+

Jing DAO

Jing is a Data Access Object (DAO) framework that supports + Avalon components and works within Avalon containers.

OpenIM Instant Messaging

 +

The purpose of the OpenIM project is to produce a + fast, simple, and highly efficient instant messager server + with high modularisation and a codebase that uses the + Avalon tools and Merlin + Container created by Apache's Avalon project.

+

Jcrontab

 +

JCrontab provides a simple Java implementation of the + Unix cron service. An Avalon interface is provided.

+Hibernate Wrapper

 +

Hibernate is a topnotch ORM tool. An Avalon wrapper has + been written to faciliate using Hibernate in an Avalon + Environment.

+

Xingu Components

+ A collection of Avalon components including OJB and Hibernate + support, a business object API, ACL component, Messenging + component and more!

+

PhoenixJMS

An Avalon component wrapper for OpenJMS

+ Enterprise Object Broker

a "post-J2EE" application server.

Telnetd

Java telnet implementation

Spice

Spice is a repository of Components which support + Component Oriented Programming (COP) paradigms - in + particular, the Inversion of Control (IoC) design + pattern.

+

Ivory

Ivory provides easy integration between your + exiting java classes, Avalon services, and Axis. It + allows easy deployment of soap services with none of the + WSDD configuration that Axis normally mandates. Simply + register your class or service and wa-la, you have a new + RPC SOAP service. However, it also allows Avalon services + to be used with the standard WSDD configuration easily.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescription

Picocontainer

Picocontainer is a light weight IoC framework.

WebWork 2

an MVC web framework

+ + JBoss AOP

The JBoss Aspect Oriented Programming (AOP) framework

Spring Framework

A J2EE Application Framework

Hivemind

HiveMind is a services and configuration microkernel. + HiveMind allows you to create your application using a service + oriented architecture.

ObjectWeb Fractal

+ Fractal is a modular and extensible component model that + can be used with various programming languages to design, + implement, deploy and reconfigure various systems and + applications, from operating systems to middleware + platforms and to graphical user interfaces.

+

Jicarilla

+ The Jicarilla-Framework builds upon Type-3 IoC, adding + an Active interface to better support multi-threaded + components. Besides some pretty generic utility code + (like a set of base classes for nested exceptions), it + adds basic abstractions for the building blocks of + lightweight event-based systems, like sources, sinks, + stages, multicasters, etc.

+
+ +
+ + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/related/index.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/related/index.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,45 @@ + + + + Avalon Documentation Team + Apache Avalon: Related Projects + + + +
+ + + + + + + + + + + + + + + + + + +
NameDescription
Apache ProjectsOverview of a number of Apache projects that leverage + the Avalon framework, containers, and shared components. + The page includes details of the James Enterprise Messaging + Platform that leverages the Avalon component model and several + of the Cornerstone common components; the Turbine Fulcrum + component suite and development related to the Merlin + container, and the Cocoon project that is leveraging the + Fortress container as part of their overall development + strategy.
External ProjectsA list of external projects based on Avalon technochnologies + and services. This list includes a number of container iniatives + that leverage the Avalon container contract together with third-party + container extensions, through to dedication applications such the + OpenIM instant messaging project.
Avalon PoweredResources for the Avalon Powered logo + and site linking.
+ +
+ + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/related/navigation.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/related/navigation.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,50 @@ + + + + + Apache Avalon + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/related/powered.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/related/powered.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,19 @@ + + + + Avalon Documentation Team + Apache Avalon: Powered By + + + +
+ +

+ Got a project using Avalon? Email the developers' + mailing list and we'll add it to our site. +

+ Avalon Power + +
+ + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/sandbox/index.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/sandbox/index.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,47 @@ + + + + Avalon Documentation Team + Apache Avalon: Sandbox + + + +
+

+ The Sandbox is where Avaloners play with radical new ideas that result + in long "random thought" [RT] email threads and a few flame wars. If + you want to see what's on the bleeding edge of Avalon development, check + out the avalon-sandbox module from CVS. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProjectDescriptionDevelopers
Avalon#A C# implementation of the Avalon frameworkhammett
exporterAn AltRMI exporter for Merlin componentsfarra, mcconnell
sevakPhoenix block for embedded web/servlet containersproyal
eclipseEclipse IDE plugins for Avalon developmentniclas
+ +
+ + Added: incubator/directory/sitedocs/trunk/sitedocs/xdocs/sandbox/navigation.xml ============================================================================== --- (empty file) +++ incubator/directory/sitedocs/trunk/sitedocs/xdocs/sandbox/navigation.xml Mon Jan 26 20:20:51 2004 @@ -0,0 +1,46 @@ + + + + + Apache Avalon + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +