avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From blorit...@apache.org
Subject cvs commit: avalon-excalibur/lifecycle/src/xdocs extension.xml fortress.xml index.xml interfaces.xml list.xml menu.xml merlin.xml
Date Tue, 11 Mar 2003 13:31:35 GMT
bloritsch    2003/03/11 05:31:35

  Added:       lifecycle LICENSE.TXT WARNING.txt ant.properties.sample
                        build.xml default.properties
               lifecycle/src/etc checkstyle.properties project.mf
               lifecycle/src/java/org/apache/avalon/lifecycle
                        AbstractAccessor.java AbstractCreator.java
                        Accessor.java Creator.java package.html
               lifecycle/src/xdocs extension.xml fortress.xml index.xml
                        interfaces.xml list.xml menu.xml merlin.xml
  Log:
  Adding new lifecycle package to replace the container package--this is the official version
  
  Revision  Changes    Path
  1.1                  avalon-excalibur/lifecycle/LICENSE.TXT
  
  Index: LICENSE.TXT
  ===================================================================
  /*
  
   ============================================================================
                     The Apache Software License, Version 1.1
   ============================================================================
  
   Copyright (C) 1999-2002 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", "Apache Avalon", "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/>.
  
  */
  
  
  
  1.1                  avalon-excalibur/lifecycle/WARNING.txt
  
  Index: WARNING.txt
  ===================================================================
  *****************************  W A R N I N G  **********************************
  
    All user accessible points in this software package are to be considered
    "alpha". This means that the developer team is not investing _any_ effort
    in providing back compatibility between alpha releases.
    
    This software will continue to be released as "alpha" until both code, 
    schemas and APIs will be considered stable.
    
    Until then, there will be no warranty that newer versions will maintain back
    compatibility even in the most simple cases.
    
    On the other hand, once "beta" status is reached, back incompatible changes
    will be made only if absolutely necessary to reach "final" status.
    
    The Avalon development team understands the importance of reliable
    software as well as the importance of protecting user investiments by the
    creation of a solid development platform that doesn't change.
  
    On the other hand, being the Avalon project a pioneer in many fields, this
    cannot be guaranteed before a final status is reached for the software.
    
    Until then, no effort will be provided to guarantee back compatibility.
    
    You have been warned.
  
  *****************************  W A R N I N G  **********************************
  
  
  
  
  1.1                  avalon-excalibur/lifecycle/ant.properties.sample
  
  Index: ant.properties.sample
  ===================================================================
  # -----------------------------------------------------------------------------
  # Component ant.properties.sample
  #
  # This is an example "ant.properties" file, used to customize the building of
  # the component for your local environment.  It defines the location of all
  # external modules that this component depend on.  Copy this file to
  # "ant.properties" in the source directory, and customize it as needed.
  #
  # The ant.properties values in this directory apply only to this component.
  # It is overridden by ../ant.properties and ~/build.properties
  # It overrides all default.properties files and ~/.ant.properties
  #
  # $Id: ant.properties.sample,v 1.1 2003/03/11 13:31:33 bloritsch Exp $
  # -----------------------------------------------------------------------------
  
  # --------------------------------------------------
  #                REQUIRED LIBRARIES
  # --------------------------------------------------
  
  # ----- Avalon Framework -----
  #avalon-framework.home=${basedir}/../../avalon
  #avalon-framework.lib=${avalon-framework.home}/target/lib
  #avalon-framework.jar=${avalon-framework.lib}/avalon-framework.jar
  
  
  
  1.1                  avalon-excalibur/lifecycle/build.xml
  
  Index: build.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <project name="Avalon Lifecycle Extension" default="install" basedir=".">
  
      <property file="${user.home}/build.properties"/>
      <property file="${basedir}/../ant.properties"/>
      <property file="${basedir}/ant.properties"/>
      <property file="${user.home}/.ant.properties"/>
      <property file="${basedir}/../default.properties"/>
      <property file="${basedir}/default.properties"/>
  
      <!-- Classpath for product -->
      <path id="project.class.path">
          <pathelement location="${avalon-framework.jar}"/>
          <pathelement location="${build.classes}"/>
          <pathelement location="${checkstyle.jar}"/>
          <pathelement path="${java.class.path}"/>
      </path>
  
      <path id="tools.class.path">
          <pathelement location="${junit.jar}"/>
          <fileset dir="${jakarta-site.dir}/lib"/>
      </path>
  
      <path id="test.class.path">
          <pathelement location="${build.testclasses}"/>
          <pathelement location="${junit.jar}"/>
          <path refid="project.class.path"/>
      </path>
      <property name="cp" refid="test.class.path"/>
  
      <target name="main" depends="context,jar" description="Build the project"/>
      <target name="rebuild" depends="clean,main" description="Rebuild the project"/>
  
      <target name="context" depends="dependencies">
        <uptodate property="uptodate" targetfile="${build.lib}/${jar.name}">
          <srcfiles dir="src">
            <include name="**/*.*"/>
          </srcfiles>
        </uptodate>
      </target>
  
      <target name="flags">
          <available property="framework.present"
                 classname="org.apache.avalon.framework.Version"
                 classpathref="project.class.path" />
      </target>
  
      <target name="dependencies" depends="flags" unless="framework.present">
        <echo>Framework not present - downloading from: ${remote.repository}</echo>
        <mkdir dir="${local.repository}"/>
  	<get src="${remote.repository}/${avalon-framework.id}/jars/${avalon-framework.name}"
  		dest="${local.repository}/${avalon-framework.name}"
  		verbose="true"
  		usetimestamp="true"/>
      </target>
  
      <!-- Compiles the source code -->
      <target name="compile" depends="context,dependencies" description="Compiles the source code" unless="uptodate">
  
          <echo message="building ${ant.project.name}"/>
          <mkdir dir="${build.classes}"/>
  
          <!-- Compile all classes excluding the tests. -->
          <javac srcdir="${java.dir}"
              destdir="${build.classes}"
              debug="${build.debug}"
              optimize="${build.optimize}"
              deprecation="${build.deprecation}"
              target="1.2">
              <classpath refid="project.class.path" />
              <include name="**/*.java"/>
          </javac>
  
          <!-- copy resources to same location as .class files -->
          <copy todir="${build.classes}">
              <fileset dir="${java.dir}">
                  <exclude name="**/*.java"/>
                  <exclude name="**/package.html"/>
              </fileset>
          </copy>
  
      </target>
  
      <!-- Compiles the unit test source code -->
      <target name="compile-test" depends="compile" description="Compiles the source code">
          <mkdir dir="${build.testsrc}"/>
  
          <!-- Copy over all of the tests applying test filters -->
          <copy todir="${build.testsrc}">
              <fileset dir="${test.dir}"/>
          </copy>
  
          <mkdir dir="${build.testclasses}"/>
  
          <!-- Compile all test classes. -->
          <javac srcdir="${build.testsrc}"
              destdir="${build.testclasses}"
              debug="${build.debug}"
              optimize="${build.optimize}"
              deprecation="${build.deprecation}"
              target="1.2">
              <classpath refid="test.class.path" />
              <include name="**/*.java"/>
          </javac>
  
          <copy todir="${build.testclasses}">
              <fileset dir="${test.dir}">
                  <exclude name="**/*.java"/>
                  <exclude name="**/package.html"/>
              </fileset>
          </copy>
  
      </target>
  
      <!-- Copies and filters the license. Used by jar and dist -->
      <target name="prepare-conf">
          <mkdir dir="${build.conf}"/>
          <copy todir="${build.conf}" flatten="true">
              <fileset dir="../" includes="LICENSE.txt"/>
              <filterset>
                  <filter token="year" value="${year}"/>
              </filterset>
          </copy>
      </target>
  
      <!-- Creates all the .jar file -->
      <target name="jar" depends="compile, prepare-conf" description="Generates the jar files" unless="uptodate">
  
          <mkdir dir="${build.lib}"/>
  
          <jar jarfile="${build.lib}/${jar.name}"
              basedir="${build.classes}"
              compress="${build.compress}"
              manifest="${src.dir}/etc/project.mf">
  
              <exclude name="**/test/**"/>
              <zipfileset dir="${build.conf}" prefix="META-INF/">
                  <include name="LICENSE.txt"/>
              </zipfileset>
          </jar>
      </target>
  
      <target name="install" depends="jar">
        <mkdir dir="${local.repository}"/>
        <copy toDir="${local.repository}" file="${build.dir}/lib/${jar.name}"/>
      </target> 
  
      <!-- Creates all the Javadocs -->
      <target name="javadocs" depends="compile" description="Generates the javadocs" unless="skip.javadocs">
  
          <mkdir dir="${build.javadocs}"/>
          <javadoc packagenames="org.apache.*"
              sourcepath="${java.dir}"
              destdir="${build.javadocs}">
              <classpath refid="project.class.path" />
              <doclet name="com.sun.tools.doclets.standard.Standard">
                  <param name="-author"/>
                  <param name="-version"/>
                  <param name="-doctitle" value="${Name}"/>
                  <param name="-windowtitle" value="${Name} API"/>
                  <param name="-link" value="http://java.sun.com/j2se/1.4/docs/api/"/>
                  <param name="-link" value="http://java.sun.com/j2ee/sdk_1.3/techdocs/api/"/>
                  <param name="-link" value="${j2se.api.link}"/>
                  <param name="-link" value="${j2ee.api.link}"/>
                  <param name="-link" value="${avalon.api.link}"/>
                  <param name="-bottom"
                      value="&quot;Copyright &#169; ${year} Apache Avalon Project. All Rights Reserved.&quot;"/>
              </doclet>
          </javadoc>
      </target>
  
      <target name="test" depends="compile-test" description="Perform the unit tests" unless="skip.tests">
  
          <echo message="Performing Unit Tests" />
  
          <mkdir dir="${build.tests}"/>
  
          <junit fork="true"
              haltonfailure="${junit.failonerror}"
              printsummary="yes"
              dir="${build.tests}">
              <classpath refid="test.class.path"/>
  
              <formatter type="xml"/>    <!-- xml reports for junitreport -->
              <formatter type="plain" usefile="false"/>  <!-- text reports for humans     -->
  
              <batchtest todir="${build.tests}">
                  <fileset dir="${build.testclasses}">
                      <include name="**/test/*TestCase.class"/>
                      <exclude name="**/Abstract*"/>
                  </fileset>
              </batchtest>
          </junit>
  
      </target>
  
      <target name="test-reports" depends="test" description="Generate Reports for the unit tests">
  
          <mkdir dir="${build.reports}/junit"/>
  
          <junitreport todir="${build.reports}/junit">
              <fileset dir="${build.tests}">
                  <include name="TEST-*.xml"/>
              </fileset>
              <report format="frames" todir="${build.reports}/junit"/>
          </junitreport>
  
          <!-- Clean up the xml reports used by the junitreport task -->
          <!--
          <delete>
              <fileset dir="${build.tests}" includes="TEST-*.xml"/>
              <fileset dir="${build.tests}" includes="TESTS-*.xml"/>
          </delete>
          -->
  
      </target>
  
    <target name="checkstyle" if="do.checkstyle">
      <taskdef classpath="${checkstyle.jar}"
         resource="checkstyletask.properties"/>
      <mkdir dir="${build.dir}"/>
      <checkstyle
        properties="${etc.dir}/checkstyle.properties" 
        failOnViolation="false">
        <fileset dir="${java.dir}"
                 includes="**/*.java"/>
        <property key="checkstyle.cache.file" file="${checkstyle-cache}"/>
        <formatter type="plain"/>
        <formatter type="xml" toFile="${build.dir}/checkstyle-results.xml"/>
      </checkstyle>
    </target>
  
    <!-- Creates the distribution -->
    <target name="dist"
          depends="dist-jar, javadocs"
          description="Generates a distribution (jar + javadocs + src )">
  
          <copy file="${build.conf}/LICENSE.txt" todir="${dist.dir}"/>
          <copy file="../KEYS" todir="${dist.dir}"/>
  
          <zip zipfile="${dist.dir}/src.zip" compress="true">
              <zipfileset dir="src/java"/>
          </zip>
  
          <zip zipfile="${dist.dir}/docs.zip" compress="true">
              <zipfileset dir="build/docs"/>
          </zip>
  
          <mkdir dir="${dist.base}"/>
  
          <zip zipfile="${dist.base}/${dist.name}.zip" compress="true">
              <zipfileset dir="${dist.dir}" prefix="${dist.name}"/>
          </zip>
  
          <delete dir="${dist.dir}" />
  
      </target>
  
      <!-- Creates a mini jar-only distribution -->
      <target name="dist-jar" depends="jar">
          <mkdir dir="${dist.dir}"/>
          <copy todir="${dist.dir}">
              <fileset dir="${build.lib}">
                  <include name="*.jar"/>
              </fileset>
          </copy>
      </target>
  
      <!-- Creates a minimal distribution -->
      <target name="dist.lite"
          depends="dist-jar, test, javadocs"
          description="Generates a minimal distribution (jar + javadocs)">
          <copy file="../LICENSE.txt" todir="${dist.dir}"/>
          <copy file="../KEYS" todir="${dist.dir}"/>
      </target>
  
      <target name="docs" depends="xdocs, javadocs" description="generates all the Avalon documentation"/>
  
      <target name="xdocs" description="generates the xdocs-based documentation">
        <ant antfile="${basedir}/../cocoonbuild.xml"/>
      </target>
  
      <target name="site" depends="docs" description=" Places Docs ready for hosting on website">
          <mkdir dir="../site/dist/docs/${dir-name}"/>
          <copy todir="../site/dist/docs/${dir-name}">
              <fileset dir="${build.docs}">
                  <include name="**"/>
              </fileset>
          </copy>
      </target>
  
      <!-- Cleans up build and distribution directories -->
      <target name="clean" description="Cleans up the project">
          <delete file="checkstyle.cache"/>
          <delete dir="${build.dir}" />
          <delete dir="${dist.dir}" />
          <delete dir="test" /> <!-- unit testing output directory -->
          <delete>
              <fileset dir="." includes="velocity.*"/>
              <fileset dir="." includes="**/*~" defaultexcludes="no"/>
          </delete>
      </target>
  
      <target name="real-clean" depends="clean" description="Cleans up the project, including distributions">
          <delete dir="${dist.base}" />
      </target>
  
  </project>
  
  
  
  1.1                  avalon-excalibur/lifecycle/default.properties
  
  Index: default.properties
  ===================================================================
  # -------------------------------------------------------------------
  # B U I L D  P R O P E R T I E S
  # -------------------------------------------------------------------
  # Specifies default property values
  # Overridden by ../default.properties and all ant.properties
  # Not user-editable; use ant.properties files instead
  
  name=avalon-lifecycle
  Name=Avalon Containment Lifecycle Extensions
  dir-name=lifecycle
  version=1.0
  package-version=1.0
  year=2000-2002
  
  remote.repository = http://www.osm.net/repository
  local.repository = ../lib
  
  # --------------------------------------------------
  #                REQUIRED LIBRARIES
  # --------------------------------------------------
  
  # ----- Avalon Framework, version 4.1 or later -----
  avalon-framework.id = avalon-framework
  avalon-framework.version = 4.1.4
  avalon-framework.name = ${avalon-framework.id}-${avalon-framework.version}.jar
  avalon-framework.jar=${local.repository}/${avalon-framework.name}
  
  # ----- Avalon Sandbox -----
  avalon-sandbox.home=${basedir}/..
  
  # ----- Excalibur -----
  excalibur.home=${basedir}/../../avalon-excalibur
  
  
  # --------------------------------------------------
  
  #  Settings used to configure compile environment
  build.debug = on
  build.optimize = off
  build.deprecation = off
  build.compress = false
  junit.failonerror = false
  
  #  location of intermediate products
  build.dir = build
  build.testsrc = ${build.dir}/testsrc
  build.testclasses = ${build.dir}/testclasses
  build.lib = ${build.dir}/lib
  build.conf = ${build.dir}/conf
  build.classes = ${build.dir}/classes
  build.tests = ${build.dir}/tests
  build.reports = ${build.dir}/reports
  build.docs = ${build.dir}/docs
  build.javadocs = ${build.docs}/api
  
  #  Set the properties for source directories
  src.dir = src
  java.dir = ${src.dir}/java
  conf.dir = ${src.dir}/conf
  test.dir = ${src.dir}/test
  etc.dir = ${src.dir}/etc
  
  #  Set the properties for distribution directories
  dist.dir = dist
  dist.javadocs = ${dist.dir}/docs/api
  
  xdocs.dir = ${src.dir}/xdocs
  docs.dir = ${dist.dir}/docs
  jakarta-site.dir = ../../jakarta-site
  
  #  name of .zip/.tar.gz/.bz2 files and their top-level directory
  dist.name = ${name}-${version}
  
  #  name of jar file
  jar.name = ${name}-${package-version}.jar
  
  #  property indicating directory where all distribution archives are placed
  dist.base = distributions
  
  # misc.
  
  checkstyle-cache = ${build.dir}/checkstyle.cache
  
  depchecker.prefix=.
  
  # javadoc links
  doc.root = ../../../../..
  j2se.api.link = http://java.sun.com/j2se/1.4/docs/api/
  j2ee.api.link = http://java.sun.com/j2ee/sdk_1.3/techdocs/api/
  avalon.api.link = ${doc.root}/avalon/docs/api
  
  
  
  
  1.1                  avalon-excalibur/lifecycle/src/etc/checkstyle.properties
  
  Index: checkstyle.properties
  ===================================================================
  checkstyle.lcurly.type=nl
  checkstyle.lcurly.method=nl
  checkstyle.lcurly.other=nl
  
  checkstyle.rcurly=alone
  
  # TODO: Should not be ignored for readability!!!
  checkstyle.ignore.braces=no
  checkstyle.ignore.importlength=yes
  checkstyle.ignore.public.in.interface=no
  checkstyle.ignore.whitespace=yes
  checkstyle.ignore.whitespace.cast=yes
  
  checkstyle.paren.pad=space
  
  # TODO: Try to get the files ot match the default values
  # default 80 maxlinelen
  checkstyle.maxlinelen=250
  # default 2000
  checkstyle.maxfilelen=3000
  # default 150 maxmethodlen
  checkstyle.maxmethodlen=180
  # default 150 maxmethodlen
  checkstyle.maxconstructorlen=100
  
  # default 7
  checkstyle.maxparameters=13
  
  checkstyle.pattern.member=^m_[a-z](_?[a-zA-Z0-9])*$
  checkstyle.pattern.static=^c_[a-z](_?[a-zA-Z0-9])*$
  checkstyle.pattern.const=^[A-Z](_?[A-Z0-9]+)*$
  checkstyle.pattern.method=[a-z](_?[a-zA-Z0-9]+)*$
  checkstyle.pattern.parameter=[a-z](_?[a-zA-Z0-9]+)*$
  checkstyle.pattern.localvar=[a-z](_?[a-zA-Z0-9]+)*$
  
  # TODO: Use an invalid pattern temporarily until the TODOs have been resolved to make the nightly builds work!!!
  checkstyle.pattern.todo=xTODO:x
  
  checkstyle.javadoc.scope=protected
  checkstyle.javadoc.checkUnusedThrows=true
  
  checkstyle.require.packagehtml=yes
  
  checkstyle.allow.noauthor=no
  checkstyle.allow.protected=yes
  checkstyle.allow.package=no
  checkstyle.allow.tabs=no
  
  # The official header file
  checkstyle.header.file=../LICENSE.txt
  
  # These instantiations should be illegal, use the static constants instead. 
  checkstyle.illegalInstantiations=java.lang.Boolean
  
  
  
  
  1.1                  avalon-excalibur/lifecycle/src/etc/project.mf
  
  Index: project.mf
  ===================================================================
  Manifest-Version: 1.0
  Created-By: Apache Avalon
  Extension-Name: avalon-lifecycle
  Specification-Vendor: Apache Software Foundation
  Implementation-Vendor: Apache Software Foundation
  Implementation-Vendor-Id: ASF
  Specification-Version: 1.0
  Implementation-Version: 1.0
  Extension-List: framework
  framework-Extension-Name: avalon-framework
  framework-Specification-Version: 1.0
  framework-Implementation-Version: 4.1.4
  framework-Implementation-Vendor-Id: ASF
  
  
  
  1.1                  avalon-excalibur/lifecycle/src/java/org/apache/avalon/lifecycle/AbstractAccessor.java
  
  Index: AbstractAccessor.java
  ===================================================================
  /*
  
   ============================================================================
                     The Apache Software License, Version 1.1
   ============================================================================
  
   Copyright (C) 1999-2002 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", "Apache Avalon", "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/>.
  
  */
  
  package org.apache.avalon.lifecycle;
  
  import org.apache.avalon.framework.context.Context;
  import org.apache.avalon.framework.logger.AbstractLogEnabled;
  
  /**
   * Abstract implementation of a <code>Accessor</code>.
   * @author <a href="mailto:dev@avalon.apache.org">Avalon Development Team</a>
   */
  public class AbstractAccessor extends AbstractLogEnabled implements Accessor
  {
  
      //=======================================================================
      // Accessor
      //=======================================================================
  
      /**
       * Access stage handler.
       *
       * @param object the object that is being accessed
       * @param context the context instance required by the access handler
       *    implementation
       * @exception Exception if an error occurs
       */
      public void access( Object object, Context context )
          throws Exception
      {
          if( getLogger() == null )
          {
              return;
          }
  
          if( getLogger().isDebugEnabled() )
          {
              getLogger().debug(
                  "accessing " + object.getClass().getName()
                  + "#" + System.identityHashCode( object ) );
          }
      }
  
      /**
       * Release stage handler.
       *
       * @param object the object that is being released
       * @param context the context instance required by the release handler
       *    implementation
       */
      public void release( Object object, Context context )
      {
          if( getLogger() == null )
          {
              return;
          }
  
          if( getLogger().isDebugEnabled() )
          {
              getLogger().debug(
                  "releasing " + object.getClass().getName()
                  + "#" + System.identityHashCode( object ) );
          }
      }
  }
  
  
  
  1.1                  avalon-excalibur/lifecycle/src/java/org/apache/avalon/lifecycle/AbstractCreator.java
  
  Index: AbstractCreator.java
  ===================================================================
  /*
  
   ============================================================================
                     The Apache Software License, Version 1.1
   ============================================================================
  
   Copyright (C) 1999-2002 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", "Apache Avalon", "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/>.
  
  */
  
  package org.apache.avalon.lifecycle;
  
  import org.apache.avalon.framework.context.Context;
  import org.apache.avalon.framework.logger.AbstractLogEnabled;
  
  /**
   * Abstract implementation of a <code>Creator</code>.
   * @author <a href="mailto:dev@avalon.apache.org">Avalon Development Team</a>
   */
  public class AbstractCreator extends AbstractLogEnabled implements Creator
  {
  
      //=======================================================================
      // Creator
      //=======================================================================
  
      /**
       * Create stage handler.
       *
       * @param object the object that is being created
       * @param context the context instance required by the create handler
       *    implementation
       * @exception Exception if an error occurs
       */
      public void create( Object object, Context context )
          throws Exception
      {
          if( getLogger() == null )
          {
              return;
          }
  
          if( getLogger().isDebugEnabled() )
          {
              getLogger().debug(
                  "creating " + object.getClass().getName()
                  + "#" + System.identityHashCode( object ) );
          }
      }
  
      /**
       * Destroy stage handler.
       *
       * @param object the object that is being destroyed
       * @param context the context instance required by the handler
       *    implementation
       */
      public void destroy( Object object, Context context )
      {
          if( getLogger() == null )
          {
              return;
          }
  
          if( getLogger().isDebugEnabled() )
          {
              getLogger().debug(
                  "destroying " + object.getClass().getName()
                  + "#" + System.identityHashCode( object ) );
          }
      }
  }
  
  
  
  1.1                  avalon-excalibur/lifecycle/src/java/org/apache/avalon/lifecycle/Accessor.java
  
  Index: Accessor.java
  ===================================================================
  /*
  
   ============================================================================
                     The Apache Software License, Version 1.1
   ============================================================================
  
   Copyright (C) 1999-2002 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", "Apache Avalon", "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/>.
  
  */
  package org.apache.avalon.lifecycle;
  
  import org.apache.avalon.framework.context.Context;
  
  /**
   * The <code>Accessor</code> interface describes the access and release
   * stages that occur between a service or component manager and a container
   * during service deployment.  Lifecycle extensions supporting access
   * and release stages must implement this interface.
   *
   * @author <a href="mailto:dev@avalon.apache.org">Avalon Development Team</a>
   * @version CVS $Revision: 1.1 $ $Date: 2003/03/11 13:31:34 $
   */
  public interface Accessor
  {
      /**
       * Access stage handler.
       *
       * @param object the object that is being accessed
       * @param context the context instance required by the access handler
       *    implementation
       * @exception Exception if an error occurs
       */
      void access( Object object, Context context )
          throws Exception;
  
      /**
       * Release stage handler.
       *
       * @param object the object that is being released
       * @param context the context instance required by the release handler
       *    implementation
       */
      void release( Object object, Context context );
  
  }
  
  
  
  1.1                  avalon-excalibur/lifecycle/src/java/org/apache/avalon/lifecycle/Creator.java
  
  Index: Creator.java
  ===================================================================
  /*
  
   ============================================================================
                     The Apache Software License, Version 1.1
   ============================================================================
  
   Copyright (C) 1999-2002 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", "Apache Avalon", "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/>.
  
  */
  package org.apache.avalon.lifecycle;
  
  import org.apache.avalon.framework.context.Context;
  
  /**
   * The <code>Creator</code> interface describes the create and destroy
   * stages that occur between a component and a container
   * during service management.  Lifecycle extensions supporting create
   * and destroy stages must implement this interface.
   *
   * @author <a href="mailto:dev@avalon.apache.org">Avalon Development Team</a>
   * @version CVS $Revision: 1.1 $ $Date: 2003/03/11 13:31:34 $
   */
  public interface Creator
  {
      /**
       * Create stage handler.
       *
       * @param object the object that is being created
       * @param context the context instance required by the create handler
       *    implementation
       * @exception Exception if an error occurs
       */
      void create( Object object, Context context )
          throws Exception;
  
      /**
       * Destroy stage handler.
       *
       * @param object the object that is being destroyed
       * @param context the context instance required by the handler
       *    implementation
       */
      void destroy( Object object, Context context );
  
  }
  
  
  
  1.1                  avalon-excalibur/lifecycle/src/java/org/apache/avalon/lifecycle/package.html
  
  Index: package.html
  ===================================================================
  <body>
  Container independent interfaces and classes supporting component lifecycle extension.
  </body>
  
  
  
  1.1                  avalon-excalibur/lifecycle/src/xdocs/extension.xml
  
  Index: extension.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>Lifecycle Extensions</title>
      <authors>
        <person name="Avalon Development Team" email="dev@avalon.apache.org"/>
      </authors>
    </header>
    <body>
  
    <s1 title="What are lifecycle extensions ?">
     <p>
      Lifecycle extensions are additional stages a component can traverse through during
      it's lifetime. Lifecycle extensions allow a container to provide extra functionality
      to components in addition to the standard stages defined by Avalon Framework.
     </p>
  
     <p>
      Avalon Framework defines a set of standard interfaces often termed as Lifecycle
      stages that can be used by a container to determine the components requirements
      during deployment and subsequent decommissioning.
     </p>
  
     <p>
      These interfaces allows the developer to separate the various concerns involved when
      writing a component. Often termed SoC and IoC (Separation of Concerns and Inversion of
      Control), these concepts represent one of the primary advantages of using Avalon.
     </p>
  
     <p>
      Sometimes it's useful to extend this development paradigm from the framework level
      into the application domain, to create customized lifecycle extensions that are called
      upon in addition to the standard set defined by the Avalon Framework.
     </p>
  
     <p>
      Such custom lifecycle stages can further enable domain specific logic across many,
      perhaps even unrelated components, can reduce code duplication, and allows the developer
      to reuse the same development and thinking paradigm as the standard lifecycle stages.
     </p>
  
     <p>
      For example, you might want to pass a specialized SecurityManager to some of your
      components before they are initialized, or have their internal state persistently cached
      during system shutdown and restored at during startup. You might want to pass user
      dependent decryption keys to your component, or give components the opportunity to
      recycle themselves before being disposed or returned to a pooled component handler.
     </p>
  
     <p>
      The possibilities and number of extensions are only limited by the requirements of your
      particular application domain.
     </p>
  
     <p>
      This document describes how to add new lifecycle extensions using <strong>Fortress</strong>
      and <strong>Merlin</strong> containers.
      This document assumes a knowledge of what an Avalon lifecycle is, and a basic understanding
      of the standard lifecycle interfaces Avalon Framework defines. References in this document to
      Service and ServiceManager can also be freely interpreted as Component and ComponentManager
      by the reader.
     </p>
  
     <p>
      <note>As at the time of writing, Fortress and Merlin is the only Avalon container that
      supports lifecycle extensions, which means components that use this feature will not work
      with the other Avalon containers (ExcaliburComponentManager, Phoenix, Tweety, etc)</note>
     </p>
  
     <p>
      Support for lifecycle extensions in the other Avalon containers is technically possible but
      has not yet been discussed. Please check with the Avalon developer mailing list if you use
      one of these containers and would like to use lifecycle extensions.
     </p>
  
    </s1>
  
    <s1 title="How do I extend a Component's lifecycle ?">
     <p>
      Extending a Component's lifecycle is straightforward. An overview of the process
      follows:
     </p>
  
      <ol>
       <li>Define the new component interface</li>
  
       <p>
        Create the new interface defining the operations that should be called upon components
        that implement this interface. Using the previously mentioned examples, this would be
        your <code>SecurityManageable</code>, <code>Cacheable</code>, <code>Decryptable</code>,
        <code>Recycleable</code> interfaces.
       </p>
  
       <li>Define an extension object that calls upon the methods defined in the new interface,
       during one or more of the pre-defined phases of component's lifecycle</li>
  
       <p>
        Create a class that implements the <code>Creator</code> and/or <code>Accessor</code>
        interfaces and implemets the interaction with target components supplied under the
        create, destroy, access and relase operations.
       </p>
  
       <li>Register your extension object</li>
  
       <p>
         This depends on the container you are using.  In
         Merlin you need to include the &lt;extensions&gt; tag in the component .xinfo file and
         Merlin will automatically recognize it.  In Fortress you register the extension object
         with a <code>LifecycleExtensionManager</code>
       </p>
  
       <li>Implement the new component interface on your component</li>
  
       <p>
        Add the new <code>implements</code> clause to your Component, or Component implementation,
        and write any methods defined in the implemented interface.
       </p>
  
       <p>
        Proceed as normal. Checking for extensions is done implicitly within both Fortress and
        Merlin. Once lifecycle extensions are registered they will be activated during the 4
        phases defined later in this document.
       </p>
      </ol>
    </s1>
  
    <s1 title="When can a Component's lifecycle be extended ?">
     <p>
      The life of any component can be broken down to the following phases:
     </p>
  
      <ol>
       <li>Creation</li>
  
       <p>
        When the component is instantiated.
       </p>
  
       <li>Access</li>
  
       <p>
        When the component is accessed via a ServiceManager/Selector
        (<code>lookup()/select()</code>).
       </p>
  
       <li>Release</li>
  
       <p>
        When the component is released via a ServiceManager/Selector (<code>release()</code>).
       </p>
  
       <li>Destruction</li>
  
       <p>
        When the component is decommissioned, ready for garbage collection.
       </p>
  
      </ol>
  
     <p>
      <note>A component will go through it's Creation and Destruction phase only once. Since
      extension classes can implement different handling strategies (Poolable, ThreadSafe,
      etc), the access and release phases of a component can be applied multiple times.</note>
     </p>
  
     <p>
      Lifecycle extensions can be added to any of the above defined phases. This allows
      you to control the interception point your particular extension will be applied under.
     </p>
  
     <p>
      For example, thread or user dependent extensions would be added at the access and release
      levels (ie. when the component is retrieved and returned to the ServiceManager) as they
      depend on runtime data not available until they are actually used.
     </p>
  
     <p>
      More static, or global extensions would be added at the creation or destruction level, since
      they do not depend on any external data that change during runtime, nor are they particular
      to any one context of use.
     </p>
  
    </s1>
  
    <s1 title="Lifestyle Extension Interfaces">
  
        <p>
        A container manages extensions using an extension handler.  Handlers may implement
        the <code>Creator</code> and/or <code>Accessor</code> interfaces.  A creator extension
        will be activated during the create and destroy stages of a component lifecycle.  A
        accessor extension will be activated during the access and release stages.
        </p>
  
        <s2 title="The Creator Interface">
  
  <p>The <code>Creator</code> interface describes the create and destroy
  stages that occur between a component and a container
  during service management.  Lifecycle extensions supporting create
  and destroy stages must implement this interface.</p>
  
        <source>
   package org.apache.avalon.lifecycle;
  
   import org.apache.avalon.framework.context.Context;
  
   public interface Creator
   {
      /**
       * Create stage handler.
       *
       * @param object the object that is being created
       * @param context the context instance required by the create handler
       *    implementation
       * @exception Exception if an error occurs
       */
      void create( Object object, Context context )
          throws Exception;
  
      /**
       * Destroy stage handler.
       *
       * @param object the object that is being destroyed
       * @param context the context instance required by the handler
       *    implementation
       */
      void destroy( Object object, Context context );
  
   }
       </source>
        </s2>
  
        <s2 title="Accessor Interface">
  <p>
  The <code>Accessor</code> interface describes the access and release
  stages that occur between a service or component manager and a container
  during service deployment.  Lifecycle extensions supporting access
  and release stages must implement this interface.
  </p>
  <source>
   package org.apache.avalon.lifecycle;
  
   import org.apache.avalon.framework.context.Context;
  
   public interface Accessor
   {
      /**
       * Access stage handler.
       *
       * @param object the object that is being accessed
       * @param context the context instance required by the access handler
       *    implementation
       * @exception Exception if an error occurs
       */
      void access( Object object, Context context )
          throws Exception;
  
      /**
       * Release stage handler.
       *
       * @param object the object that is being released
       * @param context the context instance required by the release handler
       *    implementation
       */
      void release( Object object, Context context );
  
   }
  </source>
     </s2>
    </s1>
  
    <s1 title="Need more information ?">
     <p>
      If you have any particular questions, comments, etc, please send an email to the Avalon
      developer mailing <link href="mailto:dev@avalon.apache.org">list</link>.
     </p>
    </s1>
  
    </body>
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2003/03/11 13:31:34 $
      </legal>
    </footer>
  </document>
  
  
  
  1.1                  avalon-excalibur/lifecycle/src/xdocs/fortress.xml
  
  Index: fortress.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>Fortress Lifecycle Extensions</title>
      <authors>
        <person name="Avalon Development Team" email="dev@avalon.apache.org"/>
      </authors>
    </header>
    <body>
  
    <s1 title="Example">
  
     <p>
      Let's look at a simple example. The following is also available as a working sample
      in Fortress' examples directory.
     </p>
  
     <p>
      Our example implements a Lifecycle extension for passing a <code>SecurityManager</code> to
      Components. We'll call it the <code>SecurityManageable</code> interface.
     </p>
  
    <s2 title="Define the component extension interface">
  
     <p>
      First we define the new Component extension interface.
     </p>
  
     <source>
     /**
      * Simple custom lifecycle extension interface for supplying a component
      * with a security manager.
      */
     public interface SecurityManageable
     {
         /**
          * Pass a SecurityManager object to the component
          *
          * @param manager a SecurityManager value
          */
         void secure( SecurityManager manager )
             throws SecurityException;
     }
     </source>
  
    </s2>
  
    <s2 title="Create the lifecycle extensions class">
  
     <p>
      Next we define the actual extension implementation which invokes the <code>secure()</code>
      method. We extend from <code>AbstractAccessor</code> since we only want
      <code>secure()</code> to be invoked upon each access (ie. lookup()) to the component, and
      don't need to implement the other 3 LifecycleExtension methods (create, release, and
      destroy).
     </p>
  
     <source>
     /**
      * Some custom extensions for this container's components.
      */
     public class Extensions
         extends AbstractAccessor
     {
         /**
          * Access, called when the given component is being
          * accessed (ie. via lookup() or select()).
          *
          * @param component a Component instance
          * @param context a Context instance
          * @exception Exception if an error occurs
          */
         public void access( Object component, Context context )
             throws Exception
         {
             if ( component instanceof SecurityManageable )
             {
                 // pass in a simple security manager, a real system might want to pass
                 // in specialized/custom security managers
                 ( ( SecurityManageable ) component ).secure( new SecurityManager() );
             }
         }
     }
     </source>
  
     <p>
      <note>An extension class may run components through any given number of
      extensions, and are not limited to just one.</note>
     </p>
  
    </s2>
  
    <s2 title="Register the lifecycle extensions class">
  
     <p>
      We then inform our container about the extension. This could be done in several different
      ways, for simplicity we'll extend <code>initialize()</code> and add it to the
      <code>LifecycleExtensionManager</code> there.
     </p>
  
     <p>
      (an alternative might be to initialize a LifecycleExtensionManager before creating the
      container and pass it in via the <code>FortressConfig.setExtensionManager()</code> method,
      or to create a LifecycleExtensionManager subclass that includes the extension preset)
     </p>
  
     <source>
     /**
      * Simple container that includes custom lifecycle extensions.
      */
     public final class ExtendedContainer
         extends DefaultContainer
     {
         public void initialize()
             throws Exception
         {
             super.initialize();
  
             m_extManager.addExtension( new Extensions() );
         }
     }
     </source>
  
    </s2>
  
    <s2 title="Use the new component interface">
  
     <p>
      To use the new SecurityManageable lifecycle extension, we simply implement
      SecurityManageable just as we do with any other Avalon lifecycle interfaces
      (assuming a predefined Component interface <code>ExtendedComponent</code>).
     </p>
  
     <source>
     /**
      * ExtendedComponentImpl, demonstrating the use of a custom
      * lifecycle stage SecurityManageable. This code does
      * a simple access check for several files on the file system and logs
      * the results accordingly.
      */
     public class ExtendedComponentImpl
         extends AbstractLogEnabled
         implements ExtendedComponent, SecurityManageable
     {
         /**
          * Pass a SecurityManager object to the component
          *
          * @param manager a SecurityManager value
          */
         public void secure( final SecurityManager manager )
             throws SecurityException
         {
             getLogger().info( "Received SecurityManager instance: " + manager );
  
             final String[] files = { "/tmp", "/vmlinuz", "/usr/lib/libc.a" };
  
             for ( int i = 0; i &lt; files.length; ++i )
             {
                 try
                 {
                     manager.checkRead( files[ i ] );
                     getLogger().info( "Thread can read " + files[ i ] );
                 }
                 catch ( SecurityException e )
                 {
                     getLogger().info( "Thread can not read " + files[ i ] );
                 }
             }
         }
     }
     </source>
    </s2>
  
    </s1>
  
    </body>
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2003/03/11 13:31:35 $
      </legal>
    </footer>
  </document>
  
  
  
  1.1                  avalon-excalibur/lifecycle/src/xdocs/index.xml
  
  Index: index.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
  
    <header>
      <title>Lifecycle Extensions</title>
      <authors>
        <person name="Avalon Development Team" email="dev@avalon.apache.org"/>
      </authors>
    </header>
  
    <body>
  
      <s1 title="Introduction">
  
        <p>The Lifecycle package contains a set of interfaces and classes supporting portable lifecycle extensions.</p>
  
        <p>Contributions to this project are based on co-development actives by container projects aiming towards cross-container component portability and consistent service management.</p>
  
        <p>The first step in the container project has been undertaken between the Fortress and Merlin containers on the subject of lifestyle extension support. The original design and implementation of lifecycle extensions by Marcus Crafter was implemented using the Fortress container.  Subsequently, and alternative implementation based on Marcus' design was introduced using the Merlin container leading to two incompatible solutions aiming at the same objective.  Through a process of cross-project collaboration, the Fortress and Merlin developers reached consensus on a common set of APIs and abstract implementation. These resources constitute the first sub-project of the Excalibur Container package.</p>
  
      </s1>
  
    </body>
  
    <footer>
      <legal>
        Copyright (c) @year@ The Apache Avalon Project All rights reserved.
        $Revision: 1.1 $ $Date: 2003/03/11 13:31:35 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  
  1.1                  avalon-excalibur/lifecycle/src/xdocs/interfaces.xml
  
  Index: interfaces.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>Extension Interfaces</title>
      <authors>
        <person name="Avalon Development Team" email="dev@avalon.apache.org"/>
      </authors>
    </header>
    <body>
  
    <s1 title="Lifestyle Extension Interfaces">
  
        <p>
        A container manages extensions using an extension handler.  Handlers may implement
        the <code>Creator</code> and/or <code>Accessor</code> interfaces.  A creator extension
        will be activated during the create and destroy stages of a component lifecycle.  A
        accessor extension will be activated during the access and release stages.
        </p>
  
        <s2 title="The Creator Interface">
  
  <p>The <code>Creator</code> interface describes the create and destroy
  stages that occur between a component and a container
  during service management.  Lifecycle extensions supporting create
  and destroy stages must implement this interface.</p>
  
        <source>
   package org.apache.avalon.lifecycle;
  
   import org.apache.avalon.framework.context.Context;
  
   public interface Creator
   {
      /**
       * Create stage handler.
       *
       * @param object the object that is being created
       * @param context the context instance required by the create handler
       *    implementation
       * @exception Exception if an error occurs
       */
      void create( Object object, Context context )
          throws Exception;
  
      /**
       * Destroy stage handler.
       *
       * @param object the object that is being destroyed
       * @param context the context instance required by the handler
       *    implementation
       */
      void destroy( Object object, Context context );
  
   }
       </source>
        </s2>
  
        <s2 title="Accessor Interface">
  <p>
  The <code>Accessor</code> interface describes the access and release
  stages that occur between a service or component manager and a container
  during service deployment.  Lifecycle extensions supporting access
  and release stages must implement this interface.
  </p>
  <source>
   package org.apache.avalon.lifecycle;
  
   import org.apache.avalon.framework.context.Context;
  
   public interface Accessor
   {
      /**
       * Access stage handler.
       *
       * @param object the object that is being accessed
       * @param context the context instance required by the access handler
       *    implementation
       * @exception Exception if an error occurs
       */
      void access( Object object, Context context )
          throws Exception;
  
      /**
       * Release stage handler.
       *
       * @param object the object that is being released
       * @param context the context instance required by the release handler
       *    implementation
       */
      void release( Object object, Context context );
  
   }
  </source>
     </s2>
    </s1>
  
    </body>
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2003/03/11 13:31:35 $
      </legal>
    </footer>
  </document>
  
  
  
  1.1                  avalon-excalibur/lifecycle/src/xdocs/list.xml
  
  Index: list.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <header>
      <title>Mailing List</title>
      <authors>
        <person name="Avalon Development Team" email="dev@avalon.apache.org"/>
      </authors>
    </header>
    <body>
  
      <s1 title="Mailing Lists">
  <p>
  The Excalibur Container project is part of the Apache Avalon Project. The <a href="http://jakarta.apache.org/site/mail2.html#Avalon">Avalon User list</a> is available for general questions and queries relating to Avalon initiatives.
  </p>
      </s1>
  
    </body>
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2003/03/11 13:31:35 $
      </legal>
    </footer>
  
  </document>
  
  
  
  
  1.1                  avalon-excalibur/lifecycle/src/xdocs/menu.xml
  
  Index: menu.xml
  ===================================================================
  
  <project name="Avalon Lifecycle Extensions"
      href="http://jakarta.apache.org/avalon/sandbox/lifecycle">
  
    <title>Excalibur Container</title>
  
    <body>
  
      <item name="Apache" href="http://www.apache.org"/>
      <item name="Avalon Home" href="http://jakarta.apache.org/avalon"/>
      <item name="Avalon Sandbox" href="http://jakarta.apache.org/avalon/sandbox"/>
  
      <menu name="Lifecycle">
        <item name="Overview" href="index.html"/>
        <item name="Extensions" href="extension.html"/>
        <item name="Interfaces" href="interfaces.html"/>
      </menu>
  
      <menu name="Tutorial">
        <item name="Fortress" href="fortress.html"/>
        <item name="Merlin" href="merlin.html"/>
      </menu>
  
      <menu name="Related Links">
        <item name="Fortress Home" href="http://jakarta.apache.org/avalon/excalibur/fortress/"/>
        <item name="Merlin Home" href="http://jakarta.apache.org/avalon/excalibur/merlin"/>
      </menu>
  
      <menu name="Reference">
        <item name="Mailing List" href="list.html"/>
        <item name="Javadoc" href="api/"/>
      </menu>
  
      </body>
    
  </project>
  
  
  
  
  1.1                  avalon-excalibur/lifecycle/src/xdocs/merlin.xml
  
  Index: merlin.xml
  ===================================================================
  <?xml version="1.0"?>
  
  <document>
    <properties>
      <title>Lifecycle Extensions</title>
      <authors>
        <person name="Avalon Development Team" email="dev@avalon.apache.org"/>
      </authors>
    </properties>
    <body>
  
    <s1 title="Example">
  
      <s2 title="Create your lifestyle stage interface">
  
  <p>
  The following interface is your domain specific lifecycle stage interface.  It is the interface that an extension handler will use to interact with your component during deployment and decommissioning.
  </p>
  
        <source>
   public interface Exploitable
   {
      /**
       * Operation invoked by an exploitation manager.
       * @param message a message to be displayed
       */
       void exploit( String message );
   }
        </source>
  
      </s2>
  
      <s2 title="Create the lifestyle extension handler">
  
  <p>
  An extension handler is the implementation class that will be activated by the Merlin container to handle domain specific tasks during the deployment and decommissioning phases.  The extension can implement etier or both of the Creator and Accessor interfaces depeding on the particular extension requirements.  IN this example we are defining a simple creation stage handler that supplies a message to an instance of Exploitable.
  </p>
        <source>
   public class ExploitationManager implements Creator
   {
      /**
       * Operation invoked by a container to request creation
       * stage extension interception.
       * @param object a component to manager
       * @param context the context
       */
       public void create( Object object, Context context )
       {
           if( object instanceof Exploitable )
           {
               ((Expoitable)object).exploit( "hello" );
           }
       }
  
      /**
       * Operation invoked by a container to request destroy
       * stage extension interception.
       * @param object a component to manager
       * @param context the context
       */
       public void destroy( Object object, Context context )
       {
       }
   }
        </source>
  
  <p>
  To complete the defintion of you extension handler you need to prepare the meta-info that will be used by Merlin to identify the extension and the stage interface is supports.  The following &lt;type/&gt; declaration includes an &lt;extensions/&gt; tag that contains a &lt;reference/&gt; element that includes the reference to the Explitable lifecycle stage interface. This is the key that Merlin uses to associate a handler with a component.  If you extension class requires any specific context values, they should be declared in a context element within the extension element.
  </p>
  
        <source>
  &lt;type&gt;
  
     &lt;info&gt;
        &lt;name&gt;my-extension-handler&lt;/name&gt;
     &lt;/info&gt;
  
     &lt;extensions&gt;
       &lt;extension&gt;
        &lt;name&gt;exploitation&lt;/name&gt;
        &lt;reference type="Exploitable" version="1.0"/>
       &lt;/extension&gt;
     &lt;/extensions&gt;
  
  &lt;/type&gt;
  
        </source>
  
      </s2>
  
      <s2 title="Create a component implementing the stage interface">
        <source>
   public class MyComponent extends AbstractLogEnabled implements Exploitable
   {
      /**
       * Operation invoked by an exploitation manager.
       * @param message a message to be displayed
       */
       public void exploit( String message )
       {
           getLogger().info( message );
       }
   }
        </source>
  
  <p>
  To complete the defintion of your component you need to prepare the meta-info that will be used by Merlin to identify the stage interface is requires a handler for.  The following &lt;type/&gt; declaration includes an &lt;stage/&gt; tag that contains a &lt;reference/&gt; element that includes the reference to the Exploitable lifecycle stage interface. This is the key that Merlin uses to associate the component with a handler capable of handling the Exploitable interface.
  </p>
  
        <source>
  &lt;type&gt;
  
     &lt;info&gt;
        &lt;name&gt;my-component&lt;/name&gt;
     &lt;/info&gt;
  
     &lt;stages&gt;
       &lt;stage&gt;
        &lt;name&gt;exploit-me&lt;/name&gt;
        &lt;reference type="Exploitable" version="1.0"/>
       &lt;/stage&gt;
     &lt;/stages&gt;
  
  &lt;/type&gt;
  
        </source>
      </s2>
  
      <s2 title="Register you component and the extension">
  
  <p>To complete the process you need to declare your handler and component in a jar manifest file.  The following entries show the declaration of the component and the extension handler.</p>
  
        <source>
    Manifest-Version: 1.0
    Created-By: Ant 1.5
  
    Name: MyComponent.class
    Avalon: Type
  
    Name: ExploitationManager.class
    Avalon: Type
        </source>
  
      </s2>
  
      <s2 title="Execute the example">
  
  <p>To execute the example you simply need to include a reference to you component within a Merlin container declaration.  The following XML source declares a Merlin kernel, container, and component.  You don't need to include the handler because Merlin can sort that out itself based on the information supplied in the meta-info declarations.</p>
  
        <source>
   &lt;kernel&gt;
  
     &lt;container name="my-container&gt;
  
       &lt;classpath&gt;
         &lt;fileset dir="lib"&gt;
           &lt;include name="my-domo.jar"/&gt;
         &lt;/fileset&gt;
       &lt;/classpath&gt;
  
       &lt;component name="demo" class="MyComponent" activation="startup"/&gt;
  
     &lt;container&gt;
  
   &lt;/kernel&gt;
        </source>
  
      </s2>
  
    </s1>
  
    </body>
    <footer>
      <legal>
        Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
        $Revision: 1.1 $ $Date: 2003/03/11 13:31:35 $
      </legal>
    </footer>
  </document>
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: cvs-unsubscribe@avalon.apache.org
For additional commands, e-mail: cvs-help@avalon.apache.org


Mime
View raw message