donaldp 2002/06/19 17:35:53
Added: site/src/xdocs types.xml
Log:
Add in start of types deocumentation
Revision Changes Path
1.1 jakarta-ant-myrmidon/site/src/xdocs/types.xml
Index: types.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>On Roles and Types in Ant 2</title>
<author email="[EMAIL PROTECTED]">Peter Donald</author>
</properties>
<body>
<section name="Introduction">
<p>Where as Ant1 can be said to be be Task-centric, Myrmidon
can be said to be type-centric. To extend the runtime you write
a java class (a type) that implements various interfaces.</p>
</section>
<section name="Roles">
<p><a name="roles"/>Myrmidon places types in one or more
categories. Each category
represents a set of types that conform to a certain contract or
role. Some example roles include "task", "data-type", "condition",
"converter" etc.</p>
<p>Associated with each role is a java interface. The java
interface
must be implemented by all types in that role. So the "task" role
may
be associated with the "org.apache.myrmidon.api.Task" interface
while
the "converter" role may be associated with the
"org.apache.excalibur.converter.Converter" interface.</p>
<p>So you could place the
<code>org.apache.ant.CopyFileTask</code> into
the "task" role but it would be invalid to place it in the
"converter"
role as it does not implement the converter interface.</p>
<p>Currently the roles in the runtime are loaded from the
<em>Shared</em>
classloader (See <a href="classloaders.html">ClassLoaders</a> for
an over
view of classloaders). In the future the roles may also be loaded
from
<a href="librarys.html">Ant Libraries</> but due to some
classloader
issues this is currently not possible.</p>
<p>The runtime learns about the roles by reading a descriptor
present in
jar files under name <code>META-INF/ant-roles.xml</code>. This
xml descriptor
maps a short human readable role name (such as "task") to the
name of the
interface associated with role (ie
"org.apache.myrmidon.api.Task"). The runtime
expects that the interface defining role is present in the jar
that the
descriptor was loaded from.</p>
<p>An example descriptor follows;</p>
<source>
<roles version="1.0">
<role name="task" classname="org.apache.myrmidon.api.Task"/>
<role name="task-listener"
classname="org.apache.myrmidon.api.event.TaskListener"/>
</roles>
</source>
</section>
<section name="Types">
<p><a name="types"/>A Type is an implementation of one or more
Roles. Consider the role of "task";
all the tasks in ant are considered different types that are in a
particular role.
So <copy/> is a type in the "task" role, ""file-exists" is
a type in the
"condition" role, "fileset" is a type in the "data-type" role
etc. If a user wishes
to customize ant for their own build process or environment, it
is likely that they
will be implementing a type of some sort.</p>
<p>The type is registered into the ant runtime using a shortname
that may be prefixed
with a namespace. The namespace is separated from remainder of
shortname by a '.'
character. Each type also has an implementation key. In most
cases the implementation
key coresponds to the name of the class that implements the
type.</p>
<p>For instance consider the copy task, it has a shortname of
"file.copy" (note the
namespace "file") and an implementation key of
"org.apache.antlibs.file.CopyTask".</p>
<p>When a type needs to be created the first thing that occurs is
the implementation key
is retrieved. This implementation key is then passed to a
TypeFactory. The TypeFactory
then creates an instance of the typeand returns the instance to
caller. This may sound
complicated but luckily it is done behind the scenes. The caller
only need to say they
need a instance of type with specific shortname and an instance
is created and
returned.</p>
<p>Types are registered into the ant runtime using another file
descriptor stored in
jar library files. The xml descriptors are retrieved from
libraries from a file with path
<code>META-INF/ant-types.xml</code>. The format of the of the
descriptor is extensible
and thus not able to be fully defined by a DTD. For the vast
majority of types there is
a single XML element describing the type. The name of the element
is the name of the role
under which type is being registered. The XML element also has a
impl attribute (that
coresponds to implementation key) and a name attribute (that
coresponds to shortname of type
sans any namespace information).</p>
<p>For example if you wished to register the above mentioned copy
task you would use a
descriptor that looks like;</p>
<source>
<types version="1.0">
<task name="copy" impl="org.apache.antlibs.file.CopyTask"/>
</types>
</source>
<p>In some advanced cases you may see a factory attribute
specified in the type definition.
This indicates that the type needs to be loaded using a
non-standard TypeFactory. This can occur
where the implementation key does not represent a class or
represents a class that needs to be
wrapped to conform to the type. For example, Ant1.x tasks can be
registered as a normal Ant2
task if they use a special factory that loads the Ant1 task and
wraps it in an Ant2 class.
Another example would defining a task using an xml snippet as a
form of templating. The
implementation key would be the path of the xml snippet in jar
and the factory would load the
xml snippet and interpret it to create a task.</p>
<p>In other circumstances you may notice other attributes used in
the type descriptor. This is
because some roles can declare that they need the types need to
specify extra metadata. For
instance the "converter" role requires that type implementations
specify the source and destination
classes which they convert from and to respectively.</p>
</section>
</body>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
