Berin Loritsch wrote:
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" attribute.
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.
I'm attempting to clarify this defintion - @avalon.service many de defined at the [class] or [interface] context.
[class] - declares that the component type exports a service specified by the type and version attributes - multiple service declaration may exist - the type attribute is required - the version attribute defaults to 1.0 - results in the generation of a <service type="Xxx" version="X.Y.Z"/> clause in the type definition.
[interface] - declares the interface as a defintion of a service - vertion attribute is optional and defaults to 1.0.
Sound about right?
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.
Agreed - currently the type version (component implementation version) is not used with Merlin but it is available as a readonly management attribute.
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
+1
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.
Based on the feedback from Aaron - I updated these two so that the reference is to a key (a urn). The stage is the declaration by a component that it is dependent on the container facilitating the execution of an extension on the component. The container is responsible for locating and deploying an component the declares itself as an extension provider by declaring the @avalon.extension key="urn:me:whatever" (i.e. the same key that the stage declares).
I'm not keen on shfting this outside of the @avalon namspace because its not different to a @avalon.dependency or @avalon.context - they all relate to lifecycle fulfilment.
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.
I'm ok with the logic of @avalon.context.entry (as opposed to @avalon.entry) but I'm not keen on "validate" - basically validation applies on almost everything in one way or another.
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).
Attributes are present in the meta-info model at the level of component, context, dependency, extension, service export, service definition, and stage. Under the @avalon scheme the only attribute handlined relates to component (via assignment of attributes under the <info> block using the @avalon.attribute tag. All of the other constructs are basically ignored. A solution to this that was suggested by Leo it to allow these tags to contain any attributes, and if the attribute is not "type" or "version", we assign the attribute name and value as an attribute of the respective meta-info element.
For example:
@avalon.dependency type="MyService" version="1.1" color="red"
would generate the following XML form:
<dependency type="MyService" version="1.1">
<attributes>
<attribute key="color" value="red"/>
</attributes>
</dependency>Steve.
--
Stephen J. McConnell mailto:[EMAIL PROTECTED] http://www.osm.net
Sent via James running under Merlin as an NT service. http://avalon.apache.org/sandbox/merlin
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
