@avalon

I've been through the emails on the subject of @avalon tags and looked 
at the docs from Huw Roberts on the Phoenix tags and I've gone back over 
some of my own stuff.  For the Phoenix case there are four tags, one to 
signal meta info generation and three dealing with services, 
dependencies and management access point respectively.  In the Fortress 
case you need a name, lifecycle, and either service market or service 
export declaration.  The Merlin case is a superset of the two.

  tag          Fortress    Merlin    Phoenix
  ------------------------------------------
  flag         -           yes       yes
  name         yes         yes       ?       
  lifestyle    yes         yes       -
  service      yes/?       yes       yes
  dependency   -           yes       yes

The rest of this email describes the tag and differences relative to 
Phoenix, Fortress and Merlin and attempt to draw a few conclusions. 
 Please note that I'm not proposing any particular convention for a 
delimiter re. namespece at this time.  I have following the 
<domain>:<tag> pattern used by the Phoenix tags for the purpose of this 
email.

The flag
--------

Both Phoenix and Merlin capture meta-info in XML files located under the 
<classname>.xinfo resource.  As tags can be used for documentation in 
classes that may or may not require an xinfo, you need a tag to flag the 
requirement to a tool.  The Phoenix tags use @phoenix:block (singnalling 
generation using the blockinfo DTD), the sandbox info package uses 
@avalon.component (singnalling generation using componentinfo DTD) and 
Merlin,  aligned with @avalon.type (signaling the type DTD).  In all 
cases we are simply flagging the fact the meta info generation is 
required. In practice we may need to provide information to a meta 
generation tool via this tag.  I've detailed more about this below 
relative to a proposed @avalon:meta <tool-directives> tag.

The name
--------

The name tag is short convenience name that refers to a particular full 
qualified classname. In Phoenix this is not used in the meta-generate 
utilities but is supported in the blockinfo DTD.  In Fortress the value 
of this tag is interpreted as a shorthand name to the fully qualified 
classname.  In Merlin the tag value is used as a convenience name in 
error and log messages, and as a base for appliance name resolution 
(when required).  Character restrictions apply.  Phoenix allows the 
alphanumeric characters, the underscore and period.  Merlin does not 
allow periods due to the use of the name in composite paths (URL related 
constraint). Fortress work has suggested a default shorthand name 
generation convention that appears workable across all containers.

The lifestyle
-------------

Phoenix does not appear to support alternative lifestyle declarations at 
this time.  The Fortress proposal appear close to Merlin but there 
questions as to if we should type and use a policy naming convention of 
a mechanism naming convention.  My own conclusion based on the email on 
this subject are that we should focus of mechanisms simply because we 
don't have a clear consensus of what these mechanisms apply in terms of 
policy at this stage.  Comparing Merlin and Fortress we have:

    Lifestyle   Fortress    Merlin
    ------------------------------
    singeton    ?           yes
    thread      yes         yes
    pooled      yes         yes
    transient   -           yes

I've marked the singleton case for Fortress with a ? because I'm not 
sure if the notion of "container" policy is equivalent to the Merlin 
"singleton" policy.  I've also chosen not to use the work container as 
Merlin singleton lifecycle handlers can server multiple containers (i.e. 
any singleton up the container hierarchy is shared).  My guess is that 
the Fortress "container" scope notion is probably is very close to the 
"singleton" in terms of the underlying assumption that the component 
implementation is thread safe (but this needs verification).

Service tag
-----------

Phoenix, Fortress and Merlin require the ability to declare the services 
that are exported as part of the work interface of a component.  Two 
approaches have surfaced in recent discussions - one being a tag that is 
functionally equivalent to a interface marker, the other being an the 
declaration of multiple interface export directives. The marker approach 
simplifies things because we can resolve export declarations for a 
component based on the component inheritance and implements graph.  
However, it comes at the price of not being able to exclude an export 
and still implement a service interface.  The explicit approach is more 
flexible but places the obligation on the developer to explicitly 
declare work interface at the type level. Both Phoenix and Merlin are 
logically oriented towards the explicit export approach as this directly 
reflects their respective underlying meta-info models.

A suggestion has been made that both could be applied - but to be frank 
I'm hesitant to go down this route as it could mean multiple potentially 
conflicting declarations.  On the other-hand I recognize that interface 
marking simplifies things. As we are dealing with the first step down 
this path, I'm going to suggest we stick with the explicit export 
approach and build on the Phoenix examples to propose a common model.

In both Phoenix and Merlin a service are versioned.  Fortress does not 
deal with service versions at this time.  I should also note that 
Phoenix meta generation tools do not appear to provide version support.  
In the Merlin environment the convention used to express a 
classname/version combination is to delineate classname and version with 
the ":" character as shown in the following examples:

  @avalon:service type="org.apache.Something:1.2"
  @avalon:service type="org.apache.SomethingElse"

Dependency tag
--------------

Component dependencies are resolved dynamically in Fortress whereas both 
Phoenix and Merlin provide support for component assembly prior to 
component deployment. Including the dependency tag in the core set of 
tags makes sense because it can be safely ignored by Fortress but 
included in Phoenix and Merlin meta info generation.  The proposed 
format for dependency tags is little more complex than the service tag 
in that a dependency in Phoenix? and Merlin can be declared as optional 
(although this isn't supported in the @phoenix.dependency tag) and the 
dependency may be associated with a lookup key.

  @avalon:dependency type="org.apache.Something:1.2"
  @avalon:dependency type="org.apache.SomethingElse" optional="true"
  @avalon:dependency type="org.apache.Whatever" key="thing"

In the above, the default value for the optional attribute is false.  
The default value of the key is the classname of the type argument.  
Resolution of a version in the absence of a declaration is assumed to be 
container dependent.  The version format should initially only deal with 
a single version (as opposed to getting into version constraint 
expressions) at this time.


Fortress taglist:
-----------------

The core taglist is basically what is needed for Fortress but prepared 
in such a way to be consistent with  Phoenix and Merlin extended 
requirements with the objective of evolving a complete Avalon taglist.

@avalon:name <name>
@avalon:lifestyle policy=<singleton|thread|pooled|transient>
@avalon:service type=<classname>:<version>

Extensions required for Phoenix and Merlin
------------------------------------------

The avalon.meta tag listed below corresponds to the meta generation flag 
described at the begining of this email. I've included a 
<tool-directive> slot where we can included tool instructions.  For 
example, the information presented here does not include management of 
the association of attributes to nested elements (an earea where javadoc 
usage falls appart) - e.g. you may want to instruct a tool to simply 
verify against an existing .xinfo file as opposed to generating an 
.xinfo.  I figure that we will be able to sort the details of the 
<tool-directive> value as we move forward with implementations backed 
with some more experience.

@avalon:meta <tool-directives>
@avalon:version <version>
@avalon:dependency type=<classname>:<version> key=<key>

Extensions required for Merlin
------------------------------

@avalon:context type=<classname>:<version>
@avalon:entry type=<classname>:<version> key=<key> alias=<alias>
@avalon:category name=<logging-channel-name>
@avalon:stage interface=<classname>
@avalon:extension interface=<classname>

I suggest the above tags be reserved.  They correspond to the additional 
information needed by Merlin to support supplementary context argument 
dependency declarations and context type definitions, logging channel 
names, lifecycle extension stage dependency, and lifecycle extension 
provision declarations.

Extensions required for Phoenix
-------------------------------

@avalon:mx interface=<classname>
@avalon:configuration schema=<schemaspec>

These tags don't appear to be supported in the Phoenix meta-generation 
task but are part of the blocking spec.  They include information needed 
to define the management interface access point and qualification of 
configuration schema. I suggest we apply the same approach here - in 
that these tags are reserved.

Comments welcome.

Cheers, Steve.

-- 

Stephen J. McConnell
mailto:[email protected]
http://www.osm.net