ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dona...@apache.org
Subject cvs commit: jakarta-ant-myrmidon/site/src/xdocs types.xml
Date Thu, 20 Jun 2002 00:35:53 GMT
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="peter@apache.org">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>
  &lt;roles version="1.0"&gt;
    &lt;role name="task" classname="org.apache.myrmidon.api.Task"/&gt;
    &lt;role name="task-listener" classname="org.apache.myrmidon.api.event.TaskListener"/&gt;
  &lt;/roles&gt;
  </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 &lt;copy/&gt; 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>
  &lt;types version="1.0"&gt;
    &lt;task name="copy" impl="org.apache.antlibs.file.CopyTask"/&gt;
  &lt;/types&gt;
  </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:ant-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:ant-dev-help@jakarta.apache.org>


Mime
View raw message