diff --git a/proposal/myrmidon/docs/configuring.html b/proposal/myrmidon/docs/configuring.html new file mode 100644 index 000000000..af08c98b6 --- /dev/null +++ b/proposal/myrmidon/docs/configuring.html @@ -0,0 +1,419 @@ + + + + + + + + + + + + + + Apache Myrmidon - On Task Configuring in Ant2 + + + + + + + + + + +
+ +
Apache Myrmidon
+ + + + + + + + + + + + +
+
+
+

Myrmidon

+ +

User Guide

+ +

Extending Ant

+ +

Container Design

+
    +
+ 		+ + + +
+ + Introduction + +
+
+

This section will describe in detail the mechanism via which tasks are + configured. Configuration is the name given to the stage in tasks + lifecycle via which the XML representation is mapped onto the task + object.

+
+
+ + + +
+ + Names + +
+
+

When mapping the XML representation on to the task object you + need to be able map the names as they appear in the XML to the + names as they appear in the Java code. The process is for generating + a java name from the xml name is as follows.

+
    +
  1. Capitalize the first character of name.
    2. +
  2. Find any '-' characters in XML name and remove character and + capitalize the following letter. (And there must be a following + letter)
    3. +
+

Some example mappings;

+
+ + + + + + + + + + + + + + + + + 
+my-name    ===>   MyName
+aString    ===>   AString
+Basedir    ===>   Basedir
+baseDir    ===>   BaseDir
+url        ===>   Url
+
+

Note that the above transformation is lossy and as such the + following XML names all map to the same Java name. The ant1.x mapping + is similarly lossy and in practice this has not been an issue.

+
+ + + + + + + + + + + + + + + + + 
+base-dir   ===>   BaseDir
+Base-dir   ===>   BaseDir
+baseDir    ===>   BaseDir
+BaseDir    ===>   BaseDir
+
+

NOTE: We should really resolve this and either disallow '-' characters + or disallow uppercase or something. (PD)

+
+
+ + + +
+ + Resolving Values + +
+
+

The first stage of mapping the XML representation to the task + is resolving all text data. The text data that needs to be resolved + include the values of attributes and the content.

+

Resolution consists of expanding any property references in the text + data. Property references are identified as starting with the token + "${" and finishing with another "}" token. The text + in between is the name of a property. The value of the property replaces + the sequence of text starting with the "${" token and finishing + with the "}" token.

+

Note that the value of the property may not be a string. If the text data + contains text (or other property references) to either side of the property + reference then it must be converted to a + String.

+
+
+ + + +
+ + Modeller + +
+
+

Currently the representation of object are stored in a hierarchial + tree of org.apache.myrmidon.api.metadata.ModelElement + objects. Each ModelElement has a number of attributes and can have + either content or sub-elements.

+

In most cases it is the responsibility of the runtime to map + the ModelElement onto an object. However in some cases it may be useful + for the object to get access to it's own model and for it to explicitly + manage it's own configuration. In this case the object should implement + the org.apache.myrmidon.api.metadata.Modeller interface + which will provide the mechanism for the object to receive its own + representation and configure itself.

+

Note that the Modeller mechanism should be avoided if possible + as it adds considerable complexity to the implementing object.

+
+
+ + + +
+ + Attributes + +
+
+

To map an XML attribute on to a Java object, the name of the + attribute is mapped to a java name and prefixed with the string + "set". The resulting string is then used to look up a + method with a single parameter.

+

For example, for the attribute "world" would result + in a lookup of a method named "setWorld" with a single + parameter.

+

If multiple methods were matched during the lookup then an + exception is thrown indicating ambiguity. Theres is an exception + to this rule that allows 2 methods to be matched if one of the + methods takes a java.lang.String parameter. The method + that has the java.lang.String parameter is ignored and + the other method would be chosen. This exception is allowed as it is + common practice for a task to evolve from String parameters to more + strongly typed parameters.

+

The resolved text data of the attribute must be + converted to the type of the matched + methods parameter. For example, if the "setWorld" method + took a parameter of type java.io.File then the resolved + text data must be converted into a java.io.File. The + conversion is done by the Converter architecture that is more fully + described in the Converter HOWTO.

+

After the value is converted to the correct type the method is + invoked with the converted value.

+
+
+ + + +
+ + Content + +
+
+

The XML representation of object can have either have nested + elements or nested text (content) but not both. To add the content + to an object a method named "content" with one parameter is looked + up. The resolved text data for content is then + converted to the type of the parameter + and passed in via the method.

+
+
+ + + +
+ + Element + +
+
+

Mapping an ModelElement onto a java object is a series of steps. + If the ModelElement name ends with the string "-ref" then + it is treated as a reference element - see the Referrenced + Elements section. Otherwise, the element is first attempted to + be mapped as a Named Element and if no match is found via + that method it tries to treat the element as a Typed Element.

+ + + +
+ + Named Elements + +
+
+

To map a named ModelElement on to a Java object, the name of + the element is mapped to a java name and prefixed with the string + "add". The resulting string is then used to look up a + method with a single parameter.

+

For example, for the attribute "geometry" would result + in a lookup of a method named "addGeometry" with a single + parameter. If multiple methods were matched during the lookup then an + exception is thrown indicating ambiguity. If no methods were found that + match name then skip down to configuring "typed" elements.

+

The type of the methods single parameter is then examined to determine + what happens next. There are two valid situations, if neither of these are + satisfied, then an exception is thrown.

+
    +
  • The parameters type is org.apache.myrmidon.api.metadata.ModelElement
    • +
  • The parameters type is a concrete class
    • +
+

1. If the parameter has a type of org.apache.myrmidon.api.metadata.ModelElement + then the un-modified model representation of element is passed to object by invoking + the adder method.

+

2. If the parameters type is concrete then an instance of the parameter is + instantiated using the default constructor. This created object is then configured + in the same manner as task using the elements representation as the model. After + the object is configured it is passed into object by invoking the adder method.

+
+
+ + + +
+ + Referrenced Elements + +
+
+

A referenced element is one that has a name ending in + "-ref" and has a single attribute "name" + and no content or child elements.

+

The value of the "name" attribute is the name of a property. + The value of this property is retrieved from the TaskContext.

+

Like with Named Elements the name of the element (minus + the "-ref" part) is mapped to a java name and prefixed with the string + "add". The resulting string is then used to look up a + method with a single parameter. If multiple methods were matched during the lookup then an + exception is thrown indicating ambiguity.

+

The value retrieved from the TaskContext is then converted to the type + of the methods parameter and the add method is invoked with the converted value.

+

An example usage is the following;

+
+ + + + + + + + + + + + + + + + + 
+
+            <my-task ...>
+              <classpath-ref name="project.class.path"/>
+            </my-task>
+
+
+
+
+
+ + + +
+ + Typed Elements + +
+
+

"Typed" elements can also be added to an object. A typed element + is one in which the name of the element actually refers to a type rather than the + name of the adder to call.

+

For example, you may wish to allow a task to add arbitrary instances of the + Condition role to a task. So instead of adding methods such as + addAnd(AndCondition), addOr(OrCondition) and + addXor(XorCondition) you can instead add a single method + add(Condition). This vastly simplifies the amount of work required + to write tasks that take conditions. More importantly it allows end-users to + extend the number of elements selected by task. For instance if the user wanted + a "nand" condition they could write the Nand type use it in their build + file. For a discussion on roles and types see the Types + HOWTO.

+

To use a Typed adder there must be a single method named "add" that + has a single parameter. The parameter MUST be an abstract interface and + must be registered as a role. The name of the element is then used to lookup the + a type in the TypeManager with a role matching the interface name.

+

For example if an element named "nand" was added to an object that had + an adder with the signature void add( Condition condition ) then + the type named "nand" in the role "Condition" would be looked up. + An instance of the type would then be created using the default constructor and the + created object would be configured and then adder to object using adder.

+
+
+
+
+
+
+
+
+ Copyright © 2000-2002, Apache Software Foundation +
+
+ + + + + + + diff --git a/proposal/myrmidon/src/xdocs/configuring.xml b/proposal/myrmidon/src/xdocs/configuring.xml new file mode 100644 index 000000000..6b8dfcc16 --- /dev/null +++ b/proposal/myrmidon/src/xdocs/configuring.xml @@ -0,0 +1,205 @@ + + + + + On Task Configuring in Ant2 + Peter Donald + + + + +
+

This section will describe in detail the mechanism via which tasks are + configured. Configuration is the name given to the stage in tasks + lifecycle via which the XML representation is mapped onto the task + object.

+
+ +
+ +

When mapping the XML representation on to the task object you + need to be able map the names as they appear in the XML to the + names as they appear in the Java code. The process is for generating + a java name from the xml name is as follows.

+
    +
  1. Capitalize the first character of name.
    2. +
  2. Find any '-' characters in XML name and remove character and + capitalize the following letter. (And there must be a following + letter)
    3. +
+

Some example mappings;

+ +my-name ===> MyName +aString ===> AString +Basedir ===> Basedir +baseDir ===> BaseDir +url ===> Url +

Note that the above transformation is lossy and as such the + following XML names all map to the same Java name. The ant1.x mapping + is similarly lossy and in practice this has not been an issue.

+ +base-dir ===> BaseDir +Base-dir ===> BaseDir +baseDir ===> BaseDir +BaseDir ===> BaseDir +

NOTE: We should really resolve this and either disallow '-' characters + or disallow uppercase or something. (PD)

+
+ +
+

The first stage of mapping the XML representation to the task + is resolving all text data. The text data that needs to be resolved + include the values of attributes and the content.

+

Resolution consists of expanding any property references in the text + data. Property references are identified as starting with the token + "${" and finishing with another "}" token. The text + in between is the name of a property. The value of the property replaces + the sequence of text starting with the "${" token and finishing + with the "}" token.

+

Note that the value of the property may not be a string. If the text data + contains text (or other property references) to either side of the property + reference then it must be converted to a + String.

+
+ +
+

Currently the representation of object are stored in a hierarchial + tree of org.apache.myrmidon.api.metadata.ModelElement + objects. Each ModelElement has a number of attributes and can have + either content or sub-elements.

+

In most cases it is the responsibility of the runtime to map + the ModelElement onto an object. However in some cases it may be useful + for the object to get access to it's own model and for it to explicitly + manage it's own configuration. In this case the object should implement + the org.apache.myrmidon.api.metadata.Modeller interface + which will provide the mechanism for the object to receive its own + representation and configure itself.

+

Note that the Modeller mechanism should be avoided if possible + as it adds considerable complexity to the implementing object.

+
+ +
+

To map an XML attribute on to a Java object, the name of the + attribute is mapped to a java name and prefixed with the string + "set". The resulting string is then used to look up a + method with a single parameter.

+

For example, for the attribute "world" would result + in a lookup of a method named "setWorld" with a single + parameter.

+

If multiple methods were matched during the lookup then an + exception is thrown indicating ambiguity. Theres is an exception + to this rule that allows 2 methods to be matched if one of the + methods takes a java.lang.String parameter. The method + that has the java.lang.String parameter is ignored and + the other method would be chosen. This exception is allowed as it is + common practice for a task to evolve from String parameters to more + strongly typed parameters.

+

The resolved text data of the attribute must be + converted to the type of the matched + methods parameter. For example, if the "setWorld" method + took a parameter of type java.io.File then the resolved + text data must be converted into a java.io.File. The + conversion is done by the Converter architecture that is more fully + described in the Converter HOWTO.

+

After the value is converted to the correct type the method is + invoked with the converted value.

+
+ +
+

The XML representation of object can have either have nested + elements or nested text (content) but not both. To add the content + to an object a method named "content" with one parameter is looked + up. The resolved text data for content is then + converted to the type of the parameter + and passed in via the method.

+
+ +
+

Mapping an ModelElement onto a java object is a series of steps. + If the ModelElement name ends with the string "-ref" then + it is treated as a reference element - see the Referrenced + Elements section. Otherwise, the element is first attempted to + be mapped as a Named Element and if no match is found via + that method it tries to treat the element as a Typed Element.

+ +

To map a named ModelElement on to a Java object, the name of + the element is mapped to a java name and prefixed with the string + "add". The resulting string is then used to look up a + method with a single parameter.

+ +

For example, for the attribute "geometry" would result + in a lookup of a method named "addGeometry" with a single + parameter. If multiple methods were matched during the lookup then an + exception is thrown indicating ambiguity. If no methods were found that + match name then skip down to configuring "typed" elements.

+ +

The type of the methods single parameter is then examined to determine + what happens next. There are two valid situations, if neither of these are + satisfied, then an exception is thrown.

+
    +
  • The parameters type is org.apache.myrmidon.api.metadata.ModelElement
    • +
  • The parameters type is a concrete class
    • +
+

1. If the parameter has a type of org.apache.myrmidon.api.metadata.ModelElement + then the un-modified model representation of element is passed to object by invoking + the adder method.

+

2. If the parameters type is concrete then an instance of the parameter is + instantiated using the default constructor. This created object is then configured + in the same manner as task using the elements representation as the model. After + the object is configured it is passed into object by invoking the adder method.

+ + +

A referenced element is one that has a name ending in + "-ref" and has a single attribute "name" + and no content or child elements.

+ +

The value of the "name" attribute is the name of a property. + The value of this property is retrieved from the TaskContext.

+ +

Like with Named Elements the name of the element (minus + the "-ref" part) is mapped to a java name and prefixed with the string + "add". The resulting string is then used to look up a + method with a single parameter. If multiple methods were matched during the lookup then an + exception is thrown indicating ambiguity.

+ +

The value retrieved from the TaskContext is then converted to the type + of the methods parameter and the add method is invoked with the converted value.

+ +

An example usage is the following;

+ + + + +]]> + + +

"Typed" elements can also be added to an object. A typed element + is one in which the name of the element actually refers to a type rather than the + name of the adder to call.

+

For example, you may wish to allow a task to add arbitrary instances of the + Condition role to a task. So instead of adding methods such as + addAnd(AndCondition), addOr(OrCondition) and + addXor(XorCondition) you can instead add a single method + add(Condition). This vastly simplifies the amount of work required + to write tasks that take conditions. More importantly it allows end-users to + extend the number of elements selected by task. For instance if the user wanted + a "nand" condition they could write the Nand type use it in their build + file. For a discussion on roles and types see the Types + HOWTO.

+

To use a Typed adder there must be a single method named "add" that + has a single parameter. The parameter MUST be an abstract interface and + must be registered as a role. The name of the element is then used to lookup the + a type in the TypeManager with a role matching the interface name.

+ +

For example if an element named "nand" was added to an object that had + an adder with the signature void add( Condition condition ) then + the type named "nand" in the role "Condition" would be looked up. + An instance of the type would then be created using the default constructor and the + created object would be configured and then adder to object using adder.

+ + +
+ +