avalon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Leo Simons <leosim...@apache.org>
Subject [proposal] AMTAGS (avalon meta tags)
Date Wed, 09 Apr 2003 10:06:59 GMT
In the light of all the recent discussion, here's a detailed proposal. I 
am not so sure wether avalon.info makes sense, but I think it makes more 
sense than avalon.name. I think this is what we should be doing, but 
feel free to tear apart.

cheers,

- Leo

                     -= Avalon AMTAGS =-

Javadoc tags and the avalon container-component contract
========================================================

This paper documents the tags currently in use and the tags that will 
likely be used in the feature to encode the semantics of the avalon 
container-component contract above and beyond the semantics encoded in 
avalon framework. These semantics are not neccessarily supported by all 
avalon containers. A container will normally indicate suppport for these 
tags by stating it supports (a subset or superset of) AMTAGS.

Here's a basic example of a component which has AMTAGS added to it:

/**
  * Avalon component which does things and goes places.
  *
  * @author Avalon Development Team
  * @see <a href="http://avalon.apache.org/amtags">AMTAGS</a> for info on
  *   the javadoc tags used.
  *
  * @avalon.service
  *   name="com.leosimons.my.MyService1"
  *   version=1.0
  *   version=1.1
  *   version=1.2
  *   shorthand=my-service1
  * @avalon.service
  *   name="com.leosimons.my.MyService2"
  * @avalon.info
  *   name="My Cool business server component"
  *   description="Defines an interesting server application
  *               component which implements some kind of business
  *               logic"
  */
public class MyComponent implements MyService1, MyService2, Servicable
{
SocketManager m_socketManager;

/**
  * @avalon.dependency
  *   name="org.apache.avalon.cornerstone.services.sockets.SocketManager"
  *   optional=false
  *   version=1.0
  *   semantics=MERLIN
  */
   public void service(ServiceManager serviceManager)
         throws ServiceException
   {
     m_socketManager = serviceManager.lookup(
       "org.apache.avalon.cornerstone.services.sockets.SocketManager");
   }
}


Basic Grammar
-------------
grammar is basically the same augment BNF as used in RFC 2616. Short 
summary:

- (a|b) is used to indicate a choice must be made to include
   either a or b
- [a] is used to identify that a can be optionally included
- a* is used to indicate zero or more elements can be present
- a+ is used to indicate one or more elements can be present
- whitespace is disregarded; if it must be present, it is indicated
   using a special marker

SP         = space character
HT         = tab character
FS         = dot character, or full stop
CRLF       = newline character(s)

FQCN       = fully qualified classname as per java language spec. May
              be enclosed with double quotes.
RCN        = classname which is resolvable to a FQCN within the current
              file based on the classname resolution as per the
              java language spec. Note that any FQCN is a RCN, but not
              all RCNs are FQCNs. May be enclosed with double quotes
WI         = work interface as defined in avalon-framework 4,
              normally a FQCN, can be a RCN in some containers
ROLE       = normally a WI, can be a shorthand identifier which is
              registered in some way with the container
FQCNWI     = FQCN identifying a WI
RCNWI      = RCN identifying a WI
string     = valid java string, with continuation across lines as per
              the javadoc specs, ie the string is continued after a
              newline if the character following the newline is a a
              space (disregarding any '*' on that line and the spaces
              preceding it)
quoted-string = string surrounded by double quotes, '"'
line       = valid java string which does not contain newlines
              as per java language spec
word       = valid java string which does not contain LWS
              as per perl-compatible regular expressions
LWS        = (SP | HT | CRLF)*
namespace  = word. Identifies a well-known prefix which defines some
              kind of additional semantics related to the tag
name       = word. Identifies a unique tag within a certain namespace
              which normally defines some kind of additional semantics.
value      = (line|quoted-string). Identifies a value to be associated
              with a certain namespace/name pair.



General Tag Format
------------------
AMTAGS follows the convention set forward by XDoclet. A property is 
defined as

PROPERTY   = word LWS* = LWS* value CRLF

an attribute is defined as

ATTRIBUTE  = @ namespace FS name (SP PROPERTY)*

examples of syntactically valid properties are

@avalon.dependency name="hi!"
@color.light.green
@text.message
     key=greeting
     value="How are you doing? nice weather today
            don't you think?"


note: Avalon-Phoenix uses a slightly different tag format, where the 
seperator between namespace and tag name is a colon, ':' instead of a 
full stop '.'.

                   The avalon namespace
                   ====================
This namespace is for encoding of semantics which are automatically 
implied by avalon-framework.

common properties
-----------------

     [semantics=(ECM|FORTRESS|MERLIN|word)]

semantics: Additional semantics above and beyond those defined in this 
document can be implied by specifying this property. If present, a 
container SHOULD either report in some way that it does not support 
particular semantics to the end user (though it MAY continue to 
operate), or follow the additional semantics implied.

Predefined semantics:

ECM      = additional semantics as defined by the ECM container
FORTRESS = additional semantics as defined by the ECM container and as
            defined by the Fortress container
PHOENIX  = additional semantics as defined by the phoenix container
MERLIN   = additional semantics as defined by the merlin container

The value of this property must be a word.

     PROPERTY*

Any non-specified property MAY be added to any tag. Containers SHOULD 
ignore all non-specified properties they do not understand, though they 
MAY report in a non-disruptive way that they have found a property they 
do not understand.

dependency
----------
general format:

     @avalon.dependency
         name=ROLE
         [optional=(true|false)]
         [version=word]

applies to:

      either the service() or the compose() method of a component
      implementation

description:

identifies an entry in a ServiceManager or ComponentManager this 
component expects. Whether this tag applies to the ServiceManager or 
ComponentManager is to be determined from whether the component 
implements Serviceable (implying the former) or Composable (implying the 
latter). The component MUST implement exactly one of those two 
interfaces as per the AF4 contracts.

properties:

name - specify the work interface of which the component requires an 
implementation by setting the name property. A container MUST support
a FQCN as a valid value, it MAY support RCN or shorthand names as valid 
values.

optional - specify whether the dependency is needed for proper operation 
of the component or not. A container MAY ignore this property.

version - specify the version of the work interface which is desired for 
this component. A container MAY ignore this property.

example:

/**
  * @avalon.dependency
  *   name="org.apache.avalon.cornerstone.services.sockets.SocketManager"
  *   optional=false
  *   version=1.0
  *   semantics=MERLIN
  */
public void service(ServiceManager serviceManager)
         throws ServiceException {

service
-------
general format:

     @avalon.service
         name=WI
         (version=word)*
         [shorthand=(string|quoted-string)]

applies to:

      the class of a component implementation

description:

identifies a WI exposed by this component. It's use is similar to the 
common practice in avalon-framework components to specify a public final 
static String ROLE member.

properties:

name - specify the work interface this component exports.

version - specify the version of the work interface which this component 
exposes. May be included multiple time to specify multiple version 
supported. A container MAY ignore this property.

shorthand - specifies a shorthand name which can be used to identify the 
WI this component exports. A container MAY ignore this property.

example:

/**
  * @avalon.service
  *   name="com.leosimons.my.MyService1"
  *   version=1.0
  *   version=1.1
  *   version=1.2
  *   shorthand=my-service1
  * @avalon.service
  *   name="com.leosimons.my.MyService2"
  */
public class MyComponent implements MyService1, MyService2 {


name
----
general format:

     @avalon.info
         name=(string|quoted-string)
         [description=(string|quoted-string)]

applies to:

      the class of a component implementation or a work interface

description:

provides human-readable information which may be useful in contexts like 
management GUIs. A container MAY ignore all of or parts of this tag.

properties:

name - a human-readable name for this component or interface

description - a human-readable description of this component.

example:

/**
  * @avalon.info
  *   name="My Cool business server component"
  *   description="Defines an interesting server application
  *               component which implements some kind of business
  *               logic"
  */
public class MyComponent {



                   The phoenix namespace
                   =====================
This namespace is for encoding of semantics which are implied by 
Avalon-Phoenix (PHOENIX). See 
http://avalon.apache.org/phoenix/bdg/doclet-tags.html.



                   The merlin namespace
                   ====================
This namespace is for encoding of semantics which are implied by 
Avalon-Merlin (MERLIN). See 
http://avalon.apache.org/sandbox/merlin/meta/index.html.



                   The ecm namespace
                   =================
This namespace is for encoding of semantics which are implied by 
Excalibur's Component Manager (ECM). It is currently empty.




                   The fortress namespace
                   ======================
This namespace is for encoding of semantics which are implied by 
Avalon-Fortress (FORTRESS). It is currently still undocumented.



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


Mime
View raw message