Return-Path: Delivered-To: apmail-jakarta-avalon-cvs-archive@apache.org Received: (qmail 37773 invoked from network); 2 Aug 2002 09:35:04 -0000 Received: from unknown (HELO nagoya.betaversion.org) (192.18.49.131) by daedalus.apache.org with SMTP; 2 Aug 2002 09:35:04 -0000 Received: (qmail 6654 invoked by uid 97); 2 Aug 2002 09:35:36 -0000 Delivered-To: qmlist-jakarta-archive-avalon-cvs@jakarta.apache.org Received: (qmail 6638 invoked by uid 97); 2 Aug 2002 09:35:35 -0000 Mailing-List: contact avalon-cvs-help@jakarta.apache.org; run by ezmlm Precedence: bulk List-Unsubscribe: List-Subscribe: List-Help: List-Post: List-Id: "Avalon CVS List" Reply-To: "Avalon Developers List" Delivered-To: mailing list avalon-cvs@jakarta.apache.org Received: (qmail 6627 invoked by uid 97); 2 Aug 2002 09:35:34 -0000 X-Antivirus: nagoya (v4198 created Apr 24 2002) Date: 2 Aug 2002 09:34:57 -0000 Message-ID: <20020802093457.47973.qmail@icarus.apache.org> From: mcconnell@apache.org To: jakarta-avalon-excalibur-cvs@apache.org Subject: cvs commit: jakarta-avalon-excalibur/assembly/src/xdocs assembly.xml faq.xml install.xml kernel.xml logging.xml support.xml X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N mcconnell 2002/08/02 02:34:57 Modified: assembly/src/java/org/apache/excalibur/merlin/assembly/resource ProfileDesignator.java assembly/src/java/org/apache/excalibur/merlin/model Profile.java assembly/src/xdocs assembly.xml faq.xml install.xml kernel.xml logging.xml support.xml Log: general documentation updates to include details on lifecycle extension Revision Changes Path 1.6 +1 -34 jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/assembly/resource/ProfileDesignator.java Index: ProfileDesignator.java =================================================================== RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/assembly/resource/ProfileDesignator.java,v retrieving revision 1.5 retrieving revision 1.6 diff -u -r1.5 -r1.6 --- ProfileDesignator.java 2 Aug 2002 06:36:09 -0000 1.5 +++ ProfileDesignator.java 2 Aug 2002 09:34:56 -0000 1.6 @@ -223,39 +223,6 @@ return m_profile; } - private void handleExtensions( int stage, Object object ) throws Exception - { - // - // apply creation phase extensions - // - - DefaultContext context = new DefaultContext(); - PhaseDescriptor[] phases = m_profile.getType().getPhases(); - - if( stage == ExtensionDescriptor.ACCESS ) - { - // - // process in forward order - // - - for( int i=0; i-1; i-- ) - { - processExtension( stage, phases[i], object, context ); - } - } - } - private void processExtension( int stage, PhaseDescriptor phase, Object object, Context context ) throws Exception { final Facility facility = m_profile.getFacility( phase ); 1.15 +2 -2 jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/Profile.java Index: Profile.java =================================================================== RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/java/org/apache/excalibur/merlin/model/Profile.java,v retrieving revision 1.14 retrieving revision 1.15 diff -u -r1.14 -r1.15 --- Profile.java 2 Aug 2002 06:34:51 -0000 1.14 +++ Profile.java 2 Aug 2002 09:34:56 -0000 1.15 @@ -431,7 +431,7 @@ } /** - * Return the facility associated as the phace provider. + * Return the facility associated as the phase provider. * @param phase the lifecycle phase specification * @return a reference to the phase extension */ 1.3 +84 -23 jakarta-avalon-excalibur/assembly/src/xdocs/assembly.xml Index: assembly.xml =================================================================== RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/xdocs/assembly.xml,v retrieving revision 1.2 retrieving revision 1.3 diff -u -r1.2 -r1.3 --- assembly.xml 29 Jul 2002 06:14:34 -0000 1.2 +++ assembly.xml 2 Aug 2002 09:34:56 -0000 1.3 @@ -8,12 +8,12 @@

-Merlin assembles component based on explicitly declared services together with packaged and implicitly derived services. Explicitly declared services include component profiles declared within a container. Packaged services include components that are supplied with profile infomation inside its jar file. Implicit services are derived from type information together with a system generated minimal profile. These components are initially identified by manifest entries that declare the components included within a jar file. +Merlin assembles component based on explicitly declared services together with packaged and implicitly derived services. Explicitly declared services include component profiles declared within a container. Packaged services include components that are supplied with profile information inside its jar file. Implicit services are derived from type information together with a system generated minimal profile. These components are initially identified by manifest entries that declare the components included within a jar file.

-Manifest entries are used to declare the existance of one or more component implementations within a jar file. An example of a manifest declaration is included here. +Manifest entries are used to declare the existence of one or more component implementations within a jar file. An example of a manifest declaration is included here. 

     Manifest-Version: 1.0
  @@ -37,6 +37,13 @@
   
     Name: org/apache/excalibur/playground/InvalidComponent.class
     Avalon-Block: true
  +
  +  Name: org/apache/excalibur/playground/DemoManager.class
  +  Avalon-Facility: true
  +
  +  Name: org/apache/excalibur/playground/EmbeddedDemo.class
  +  Avalon-Block: true
  +
@@ -51,10 +58,12 @@
  • context objects and access keys the component requires
  • service that the component is dependent on, and the role names that the component will use to resolve them using a service or component manager
  • the service that the component provides
    • +
  • lifecycle phases dependencies
    • +
  • lifecycle extensions that the component provides
  • other related attributes

    • -

    An example of a component .xinfo resoruce is presented in the following XML.

    +

    An example of a component .xinfo resource is presented in the following XML.

       
   <!--
  @@ -82,7 +91,7 @@
   
       <version>1.2.1</version>
   
  -    <!-- the set of attribibutes associated with the type
  +    <!-- the set of attributes associated with the type
            (attribute names and values are examples only) -->
   
       <attributes>
  @@ -95,20 +104,20 @@
     </component>
   
     <!--
  -  The set of logging catagories the component uses. 
  +  The set of logging categories the component uses. 
     -->
   
     <loggers>
   
  -    <logger name="store"/>
  -    <logger name="store.cache"/>
  -    <logger name="verifier"/>
  +    <logger name="store"/>
  +    <logger name="store.cache"/>
  +    <logger name="verifier"/>
   
     </loggers>
   
   
     <!-- 
  -  Declaration of the context constraints for the compoent type. 
  +  Declaration of the context constraints for the component type. 
     The "type" attribute is the name of an interface derived from the default
     contenxt interface org.apache.avalon.framework.context.Context 
     -->
  @@ -119,7 +128,7 @@
       Declaration of an entry in a context object, the "key" is
       the key used by a component to locate the context entry,
       the "type" is the classname of value (typically an interface)
  -    or primative type.  The default value is java.lang.String.
  +    or primitive type.  The default value is java.lang.String.
       The "optional" attribute is a boolean value derived from the 
       TRUE or FALSE that indicates if the context value must be 
       provided or not (default is FALSE). 
  @@ -132,9 +141,9 @@
   
     <!--
     Declaration of the set of services that this component is capable 
  -  of supplying.  Each service declarared under the services element
  +  of supplying.  Each service declared under the services element
     may be referenced by other component info descriptions as a 
  -  dependecy.  A container is responsible for the assemably of 
  +  dependency.  A container is responsible for the assembly of 
     components based on the connection of supply components to 
     consumer components via a common service description. 
     -->
  @@ -143,7 +152,7 @@
   
         <!-- 
         The service type is the classname of an interface and the
  -      version identifier qualifes the interface version.  The 
  +      version identifier qualifies the interface version.  The 
         default version value is 1.0.
         -->
   
  @@ -214,14 +223,63 @@
   
       </dependencies>
   
  +    <!-- 
  +    Declaration of the lifecycle phase extensions that this component is depednent on.
  +    -->
  +
  +    <phases>
  +
  +      <!-- 
  +      A phase declares the lifecycle phase interface implement by this component type
  +      under the <reference> element.  A phase declaration may also include an 
  +      <attributes> declaration.  Phase handlers (extensions) will be applied in 
  +      the same order as the declarations appear here - and will be deomissioning in 
  +      reverse order.
  +      -->
  +
  +      <phase>
  +        <reference type="org.apache.security.Securable"/>
  +      </phase>
  +      <phase>
  +        <reference type="org.apache.db.Persistable"/>
  +      </phase>
  +
  +    </phases>
  +
  +    <!-- 
  +    Components may optionally declare their ability to provide extension handling.  An
  +    extension is equivalent to a phase handler.  
  +    -->
  +
  +    <extensions>
  +
  +      <!-- 
  +      If a component type declares an extension, the component implementation 
  +      MUST implement the Extension interface. 
  +      Possible stage attributes values include CREATE, DESTROY, ACCESS, RELEASE, 
  +      INNER, OUTER and ALL.  The INNER attribute value is equivalent to both 
  +      ACCESS and RELEASE.  The OUTER attribute value is equivalent to CREATE and 
  +      DESTORY.  The ALL value is equivalent to both INNER and OUTER.  
  +      -->
  +
  +      <extension stage="ALL">
  +        <reference type="org.apache.excalibur.playground.DemoExtension"/>
  +        <attributes>
  +          <attribute key="status" value="experimental"/>
  +      </attributes>
  +
  +      </extension>
  +
  +    </extensions>
  +
     </component-info>

    -Given a set of compoenent types Merlin initially establishes the set of candidates based on the declared dependecies and services. For every component declared or implied in the assembly Merlin will attempt to locate a set of candidate supplies. For every supplier Merlin will attempt to resolve the suppliers dependecies. If a failure occurs, the failed component is disgarded as a potential supplier candidate. Each component type is associated with at least one instantiation profile (explicit, packaged, and/or explicit). Profiles imply an inital ranking of candidates. Explicit profiles (that is component declarations included within a container declaration in the kernel defintion) are given highest priority. Package profiles (profiles declared in a <class-name>.xprofile resource take second priority, following by implicit profiles (only generated in the absence of explicit or packaged profiles). +Given a set of component types Merlin initially establishes the set of candidates based on the declared dependencies and services. For every component declared or implied in the assembly Merlin will attempt to locate a set of candidate supplies. For every supplier Merlin will attempt to resolve the suppliers dependencies. If a failure occurs, the failed component is discarded as a potential supplier candidate. Each component type is associated with at least one instantiation profile (explicit, packaged, and/or explicit). Profiles imply an initial ranking of candidates. Explicit profiles (that is component declarations included within a container declaration in the kernel definition) are given highest priority. Package profiles (profiles declared in a <class-name>.xprofile resource take second priority, following by implicit profiles (only generated in the absence of explicit or packaged profiles).

    -

    Profiles appear as declarations inside container defintions. A typical profile declaration includes inforation about the configuration, context and logging setup of the component type. An example component profile is included below:

    +

    Profiles appear as declarations inside container definitions. A typical profile declaration includes information about the configuration, context and logging set-up of the component type. An example component profile is included below:

            <!--
  @@ -230,11 +288,13 @@
        may be serviced by components declared in parent container.
        -->
   
  -     <component name="complex" class="org.apache.excalibur.playground.ComplexComponent" activation="startup">
  +     <component name="complex" 
  +         class="org.apache.excalibur.playground.ComplexComponent" 
  +         activation="startup">
   
  -        <loggers priority="DEBUG">
  +        <categories priority="DEBUG">
             <category name="init" priority="DEBUG" />
  -        </loggers>
  +        </categories>
   
           <!--
           Include the following context value in the context supplied a component using this 
  @@ -270,16 +330,16 @@
        </component>
    -

    In the majority of cases, a single candidate will be located to act as a supplier. In those occasions where multiple candidates exist, Merlin will invoke a candidate selection process. This pocesses involves instantiation of a service selector from one of the following sources:

    +

    In the majority of cases, a single candidate will be located to act as a supplier. In those occasions where multiple candidates exist, Merlin will invoke a candidate selection process. This involves instantiation of a service selector from one of the following sources:

      -
    • a classname declared as a value of the depedency attribute "avalon.service.selector"
      • +
    • a classname declared as a value of the dependency attribute "avalon.service.selector"
    • a class named <dependent-service-classname>Selector within the classpath
    • the default merlin service selector implemetation

    -The service Selector will be supplied with the set of candidate profiles and the set of known facilities. In this context a facility is a component that has already been assembled (either expliciity or implicity as a result of another denpdency). The default selector will attempt to resolve the selection by applying the following tests: +The service Selector will be supplied with the set of candidate profiles and the set of known facilities. In this context a facility is a component that has already been assembled (either explicitly or implicitly as a result of another dependency). The default selector will attempt to resolve the selection by applying the following tests:

      @@ -289,7 +349,7 @@
    • an implicit profile

    -

    Please note that the selection model and interfaces may be changed as a result of more intensive usage assessment. The current approach of supplying a non-ordered set of profiles negates the possibility for order upward searching within a container hierachy. An alternative approach of delegating the selction to the container based on a supplier selection handler is under consideration. +

    Please note that the selection model and interfaces may be changed as a result of more intensive usage assessment. The current approach of supplying a non-ordered set of profiles negates the possibility for order upward searching within a container hierarchy. An alternative approach of delegating the selection to the container based on a supplier selection handler is under consideration.

    On completion of a selection process a graph of candidates is established from which the order establishment of services is resolved and Merlin proceeds with the service activation phase.

    @@ -302,5 +362,6 @@ + 1.3 +4 -4 jakarta-avalon-excalibur/assembly/src/xdocs/faq.xml Index: faq.xml =================================================================== RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/xdocs/faq.xml,v retrieving revision 1.2 retrieving revision 1.3 diff -u -r1.2 -r1.3 --- faq.xml 21 Jul 2002 07:02:07 -0000 1.2 +++ faq.xml 2 Aug 2002 09:34:56 -0000 1.3 @@ -11,7 +11,7 @@

    Merlin and Fortress are very similar in that they both address the requirement for an embeddable component container. Merlin and Fortress differ in terms of the requirements that they meet. Fortress focuses on the needs related to frequent service activation requests based on service interface request supplied by a client to a service or component manager. Merlin on the other-hand is more concerned with complex service management systems establishment.

    -

    Fortress contains a more complete set of service/component manager in terms of lifestyle handling than Merlin, however, the functionality inside Fortress concerning formal dependency management and service assembly is relatively weak. Relative to the Merlin architecture, Fortress can be considered as a type of container. Looking forward, it would be desirable for Merlin to be able to include Fortress as a type of container (i.e. have Fortress implement the Merlin Container interface). This would expand the service lifestyle models available. Another approach would be to merge the Fortress and Merlin developments, however there are important issues relating to assumptions made at the level of service/component manager lookup request and semantics related to component/service selectors that remain open.

    +

    Fortress contains a more complete set of service/component manager in terms of lifestyle handling than Merlin, however, the functionality inside Fortress concerning formal dependency management and service assembly is relatively weak. Relative to the Merlin architecture, Fortress can be considered as a type of container. Looking forward, it would be desirable for Merlin to be able to include Fortress as a type of container (i.e. have Fortress implement the Merlin Container interface). This would expand the service lifestyle models available. Another approach would be to merge the Fortress and Merlin developments, however there are important issues relating to assumptions made at the level of service/component manager lookup request and semantics related to component/service selectors that remain open.

    User's familiar with the ECM framework will find may aspects of Fortress familiar. User's that have experience problems related to larger scale activation ordering, complex configuration, or context dependent components will find Merlin more appropriate to their needs.

    @@ -28,9 +28,9 @@ -

    The meta model defined in both Containerkit and Merlin separates out the notion of type related meta-info from the criteria for instantiation - commonly referred to a meta-data. The containerkit and Merlin meta-info APIs are basically equivalent, in fact both models currently share the same DTD for XML based component type declarations.

    +

    The meta model defined in both Containerkit and Merlin separates out the notion of type related meta-info from the criteria for instantiation - commonly referred to a meta-data. The Merlin meta-info API is basically a superset of the containerkit API. The Merlin meta-info model goes beyond conterkit by providing explicit declaration of lifecycle extension depedencies, and lifecycle extension handlers.

    -

    The Merlin API used more human friendly naming conventions (e.g. a type is referred to a Type, a component profile at the meta-data level is called a Profile, the association between profiles is called an Association - whereas containerkit references the same entries using more technically oriented naming conventions - ComponentInfo, ComponentMetaData and DependencyMetaData respectively). Aside from naming conventions, the Merlin meta-info model includes a method through which a client can assess a default configuration associated and packaged with the type.

    +

    The Merlin API used more human friendly naming conventions (e.g. a type is referred to a Type, a component profile at the meta-data level is called a Profile, the association between profiles is called an Association - whereas containerkit references the same entries using more technically oriented naming conventions - ComponentInfo, ComponentMetaData and DependencyMetaData respectively). Aside from naming conventions, the Merlin meta-info model includes a method through which a client can assess a default configuration associated and packaged with the type, allows dynamic addition of association, and includes support for formal lifecycle extension management.

    At the meta-data levels the differences are more significant. Containerkit requires that the associations between produced and consumers are declared at the time of meta-data creation (final constructor arguments). In the Merlin model these assembly directives can be added progressively (non-final variables). This reflects the divergence in the approaches to assembly enabled in Merlin (dynamic) versus the (static) approach employed by Phoenix.

    1.2 +3 -2 jakarta-avalon-excalibur/assembly/src/xdocs/install.xml Index: install.xml =================================================================== RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/xdocs/install.xml,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- install.xml 21 Jul 2002 05:04:10 -0000 1.1 +++ install.xml 2 Aug 2002 09:34:56 -0000 1.2 @@ -25,7 +25,8 @@ cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login password: anoncvs - cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic checkout jakarta-avalon-excalibur/assembly + cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic checkout + jakarta-avalon-excalibur/assembly     1.3 +4 -2 jakarta-avalon-excalibur/assembly/src/xdocs/kernel.xml Index: kernel.xml =================================================================== RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/xdocs/kernel.xml,v retrieving revision 1.2 retrieving revision 1.3 diff -u -r1.2 -r1.3 --- kernel.xml 20 Jul 2002 05:03:01 -0000 1.2 +++ kernel.xml 2 Aug 2002 09:34:56 -0000 1.3 @@ -38,7 +38,9 @@ </fileset> </classpath> <container name="root"> - <component name="test" class="org.apache.excalibur.playground.BasicComponent" activation="true"/> + <component name="test" + class="org.apache.excalibur.playground.BasicComponent" + activation="true"/> </container> </kernel> 1.3 +4 -2 jakarta-avalon-excalibur/assembly/src/xdocs/logging.xml Index: logging.xml =================================================================== RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/xdocs/logging.xml,v retrieving revision 1.2 retrieving revision 1.3 diff -u -r1.2 -r1.3 --- logging.xml 26 Jul 2002 06:17:04 -0000 1.2 +++ logging.xml 2 Aug 2002 09:34:56 -0000 1.3 @@ -144,7 +144,9 @@ Component profile declaration. -->     
      -     <component name="complex" class="org.apache.excalibur.playground.ComplexComponent" activation="true">
  +     <component name="complex" 
  +       class="org.apache.excalibur.playground.ComplexComponent" 
  +       activation="true">

    <!-- Multiple categories may be declared - each category defines a priority and target to be used for the respective caegory. Category names are scoped relative to the component. As such a category name of "init" translates to a full logging category path of <container-path>root.init. The logging element may contain priority and target attribute values. These values will overide the container wide defaults. --> 1.2 +6 -6 jakarta-avalon-excalibur/assembly/src/xdocs/support.xml Index: support.xml =================================================================== RCS file: /home/cvs/jakarta-avalon-excalibur/assembly/src/xdocs/support.xml,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- support.xml 21 Jul 2002 05:04:10 -0000 1.1 +++ support.xml 2 Aug 2002 09:34:56 -0000 1.2 @@ -23,23 +23,23 @@ 0.7 - Registration and Discovery + Registration and Discovery Services supporting the registration and discovery of information and service resources, maintenance of information (updating, replacement, retraction), and the referral of information and service descriptions. 0.7 - Collaboration Framework + Collaboration Framework Component providing support for the execution of collaborative business processes in which the policy concerning rights and privaliges and the sequencing of multiple participants is declared through DPML (Digital Product Modelling Language). 0.8 - Community Framework + Community Framework Component providing support for the management of shared workspaces and membership semantics based on business roles, associated community and membership policies, notions of implicit roles, management of quorums, and control over membership to user associations. 2.1 - Session Framework + Session Framework Service components supporting the establishment and management of people, places, things and business processes. The framework supplies a common business model through which business services may be activated as process, associated to users as tasks, consuming and producing resources that may be published in provate and shared workspaces, across a distribution information system. 0.9 - Gateway + Gateway Services supporting user centric web based interaction with business processes, tasks, workspaces, and service directories. The Gateway services defines a suite of servlet that provide a consitent view of a user's business context, available resources, and the characteristics, features, and policies of the resources available and in use.

    -- To unsubscribe, e-mail: For additional commands, e-mail: