avalon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Berin Loritsch <blorit...@apache.org>
Subject [AMTAGS] Updating the spec
Date Mon, 21 Jul 2003 20:00:12 GMT
It is very clear to all of us that we need to update the AMTAGS spec.  To
that end, I want to list the tags specified by the Meta project in Sandbox.
After the results of the last vote we have:

@avalon.component name="" lifestyle="" version=""
@avalon.stage type=""
@avalon.service [type=""] version=""
@avalon.logger name=""
@avalon.extension type=""
@avalon.dependency type="" version="" key="" optional=""
@avalon.context type=""
@avalon.entry key="" alias="" type="" optional="" volatile
@avalon.attribute key="" value=""

The ones that are close to the current AMTAGS proposal are:

@avalon.component, @avalon.service, and @avalon.dependency

For @avalon.dependency, the difference is the addition of the "version"

For @avalon.service, its use is scoped.  If the tag is used by itself,
the "type" attribute is filled in by the class name where it was defined.
If the tag is used in conjunction with the @avalon.component tag, the
"type" attribute is required to define the type.  It also has the newer
"version" tag.

For @avalon.component, there are three new attributes: "name", "lifestyle",
and "version".

All three are still defined in the class header Javadocs.

For the version attributes, I suggest making their definition optional
but suggested.  It is valuable information for containers that support
dynamic resolution and upgrading of services/components--although not
required if you are working with a known set of components.

That means for the header info, we have the following meta-info:

  * @avalon.component name="my-component" lifestyle="singleton" version="1.0"
  * @avalon.service type="CompanyService" version="1.0.2"
public class MyComponent implements CompanyService {}

  * @avalon.service version="1.0.2"
public interface CompanyService {}

That will document the two versions of services.  Please note that for the
@avalon.component tag, the "lifestyle" attribute is an enumerated list:

singleton - One instance shared with all clients
pooled    - Multiple instances managed by a pool, no clients share references
transient - Multiple instances unmanaged, no clients share references
thread    - One instance per thread shared with all clients in the same thread

Now, for the lifecycle extensions tags (i.e. @avalon.extension, @avalon.stage)
I propose that we move them to a functional namespace: @lifecycle.extension and
@lifecycle.stage).  I still get confused over which references what, so I need
a little information on that.  Does ".extension" reference the interface that
is the lifecycle extension?  If so, that would mean that ".stage" would
reference the Creator/Accessor that does the actual logic for extending the
component's lifecycle.

The @avalon.dependency tag is still limited to the compose or service methods.
I believe that only documenting the version tag is necessary, unless we haven't
documented the "optional" attribute which is a true/false value.

The .context and .entry references are listed in the contextualize() method.
The .context entry has a "type" attribute to codify the dependence on a specific
context interface that extends the base interface.  For example, this is where
you would identify that a component requires the Phoenix BlockContext interface.
The .entry tags have a number of attributes that allow us to validate the
context entries authoritatively.  I would like to propose to place these into
a "validate" namespace or "context" namespace (conflict with the root name).
Basically, I would like to keep the abilities but place it in a functional
group.  I am not hard set on this, so it is definitely up for discussion.

The .logger tags are listed under the enableLogging() method.  This needs to be
expanded to include the setLogger() method of the deprecated Loggable interface.
It is used to communicate to the container in advance which categories that a
component expects to use.  Those categories should be sub-categories of what
the container's main category is.  IMO, this is most useful to tools that will
generate the logging configuration files and assembly files.  We might want
to put this under a functional namespace as well.

Lastly we have a generic @avalon.attribute tag that is nice and flexible.
However, it is unclear to me from the code where it is recognized.  It appears
to only be recognizable from the main class JavaDocs from the ANT tag code.
According to the model code, attributes would be applicable to the type, the
service, and dependencies.  It is unclear to me how we scope the attributes
to the specified dependency or service (if the service is specified with the
component implementation).


"They that give up essential liberty to obtain a little temporary safety
  deserve neither liberty nor safety."
                 - Benjamin Franklin

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

View raw message