Creates one or more Ant properties for each lib-entry in the library. The property names are the embedded format strings, and the value is the location of the lib-entry's file.

For each entry in the library, this processor will match its attributes against the registered formatters. Each matched formatter will be used as the Ant property name, with the fully-qualified file location of the library entry as the property value.

This type runs at the property priority.

Parameters

Attribute Description Required format A format expression, to be used as a generated property name.

Nested Elements

format A format expression, to be used as a generated property name. Parameters Attribute Description Required text the format expression Yes

Creates one Ant path reference for the library, containing every entry in the library and its contained referenced libraries.

If the library has a pathid attribute, then its value is used as the refid for the generated path. If the library has a id attribute, then the refid for the path will be the prefix prepended to the id value. If neither of these attributes are specified, then the processor does not creates a path for the library.

The prefix default is "path.", but the default can be overridden with the prefix attribute in this element. Also, the library itself can define the prefix with the path-prefix attribute.

As of Antlion 0.9.0, you can specify <format> elements as an alternative to the prefix formatting. This allows for better customization of the ID generation. Specifying both a format and a prefix will cause an error.

This type runs at the path priority.

Parameters

Attribute Description Required prefix No (defaults to "path.")

Nested Elements

format Sets a format for the generation of the ID based on the attributes set on the library itself (rather than the elements in the library). If you add a format element, then specifying a prefix attribute will generate a build error. Parameters Attribute Description Required text The format text for the ID generation. Yes

Creates one Ant fileset reference for the library, containing every entry in the library and its contained referenced libraries. The base directory for the fileset will be the lowest-common denominator for all included files. Some operating systems may have problems with this technique, and in such situations an error is raised.

If the library has a filesetid attribute, then its value is used as the refid for the generated fileset. If the library has a id attribute, then the refid for the fileset will be the prefix prepended to the id value. If neither of these attributes are specified, then the processor does not creates a fileset for the library.

The prefix default is "fileset.", but the default can be overridden with the prefix attribute in this element. Also, the library itself can define the prefix with the fileset-prefix attribute.

As of Antlion 0.9.0, you can specify <format> elements as an alternative to the prefix formatting. This allows for better customization of the ID generation. Specifying both a format and a prefix will cause an error.

(As of Antlion 0.5.0) When an artifact or entry is determined to be a directory, then it is added to the fileset as a "**" pattern, meaning that the fileset will include all the files within the directory.

This type runs at the fileset priority.

Parameters

Attribute Description Required prefix The text to prepend to the generated reference id. No (defaults to "fileset.")

Nested Elements

format Sets a format for the generation of the ID based on the attributes set on the library itself (rather than the elements in the library). If you add a format element, then specifying a prefix attribute will generate a build error. Parameters Attribute Description Required text The format text for the ID generation. Yes

Since 0.4.0

Identical to the fileset processor, but generates an ordered filelist reference.

If the library has a filelistid attribute, then its value is used as the refid for the generated fileset. If the library has a id attribute, then the refid for the fileset will be the prefix prepended to the id value. If neither of these attributes are specified, then the processor does not creates a fileset for the library.

The prefix default is "filelist.", but the default can be overridden with the prefix attribute in this element. Also, the library itself can define the prefix with the filelist-prefix attribute.

As of Antlion 0.9.0, you can specify <format> elements as an alternative to the prefix formatting. This allows for better customization of the ID generation. Specifying both a format and a prefix will cause an error.

(As of Antlion 0.5.0) When an artifact or entry is determined to be a directory, then the directory itself is added to the filelist, but none of its contents. This is done because, in the case of artifacts, the directory might not exist at filelist creation time, making it impossible to discover the contents.

This type runs at the fileset priority.

Parameters

Attribute Description Required prefix The text to prepend to the generated reference id. No (defaults to "filelist.")

Nested Elements

format Sets a format for the generation of the ID based on the attributes set on the library itself (rather than the elements in the library). If you add a format element, then specifying a prefix attribute will generate a build error. Parameters Attribute Description Required text The format text for the ID generation. Yes

Adds the set of default processors (described here) into the policy.

Each added processor runs at its specific priority level.

Creates one Ant property, set to the names of the files in the library, without the path. This property value is suitable for setting the MANIFEST.MF file's Class-Path value. Only creates this property for libraries with the attribute manifest-classpath set to the name of the property to be set.

This type runs at the property priority.

For each attribute in the library whose name is in this element's list, add the name and value to each lib-entry which doesn't have the attribute with that name set. Note that this processor does not execute on referenced libraries.

If no attribute list is given, then it defaults to "groupid, group, version".

This type runs at the pre-repository priority, and has a default sub-priority of -4.

Parameters

Attribute Description Required attributes A comma-separated list of attributes that will be copied to all contained lib-entries that don't have that attribute set. No

The processor must be setup with a collection of "dynamic attributes". These specify an attribute to be added to each lib-entry with a value from the Ant properties. The specific Ant property can be specified as a format expression.

In other words, each dynamic attribute in this processor will declare an Ant property format based on existing attributes, and the resulting property name will be used to set the entry's corresponding attribute with the value of that property.

See the example below for how you can use this in practice.

This processor is also, as of Antlion 0.9.0, aliased as <property-attribute>, to help avoid confusion with <derived-attribute>. Please note that in Antlion 1.0.0, the name dynamic-attribute will be removed and replaced with property-attribute.

This type runs at the pre-repository priority, and has a default sub-priority of -3.

Nested Elements

attribute Defines one attribute to set in the lib-entry. If the lib-entry already has this attribute set, then this attribute will be skipped. Parameters Attribute Description Required attrib the name of the attribute to set. Yes property the format text defining the Ant property value to set the attribute to. Yes

Examples

<libraryDef> <policy> <repository dir="${3rdparty}"> <format text="[group]/[name]-[version].[type]" /> </repository> <path /> <dynamic-attribute> <attribute attrib="version" property="lib.[group].[name].version" /> <attribute attrib="version" property="lib.[group].version" /> </dynamic-attribute> </policy> <property name="lib.coverage.compile.version" value="4.5-beta2" /> <property name="lib.coverage.version" value="4.5-beta1" /> <library id="lib.coverage"> <entry group="coverage" name="compile" /> <entry group="coverage" name="report" /> <entry group="coverage" name="runtime" version="4.5-rc1" /> </library> </libraryDef> When the library lib.coverage is referenced, the <dynamic-attribute> processor will attempt to create the "version" attribute in each entry, based off of the listed attribute elements in order. Let's look at each one in turn: group="coverage" name="compile": Since the version attribute has not been set, the processor will attempt this entry. The first attribute element will attempt to match these two attributes against lib.[group].[name].version. It matches, being formatted as lib.coverage.compile.version. This, then, is looked up as a property, which was set to "4.5-beta2". The entry is now assigned the additional attribute version=4.5beta2. The second attribute element runs on this entry, but the version attribute has now been set, so it skips the entry. group="coverage" name="report": Since the version attribute has not been set, the processor will attempt this entry. The first attribute element will attempt to match these two attributes against lib.[group].[name].version. It matches, being formatted as lib.coverage.report.version. This, then, is looked up as a property, which is not set. So, the second attribute element attempts to match this entry against lib.[group].version, which maps to "lib.coverage.version". A property lookup is done, which succeeds, and so the attribute version=4.2-beta1 is associated with this entry. group="coverage" name="runtime": The version attribute has been set, so both attribute elements skip this entry.

Since 0.9.0

This maps from a format string to an attribute value. It allows for simple entry attributes to form more complex, derived attributes. Also, any declared derived attribute can build off of a previously declared derived attribute.

See the example below for how you can use this in practice.

This type runs at the pre-repository priority, and has a default sub-priority of -2, so it will run after the <dynamic-attribute> processor.

Nested Elements

attribute Defines one attribute to set in the lib-entry. If the lib-entry already has this attribute set, then this attribute will be skipped. Parameters Attribute Description Required attrib the name of the attribute to set. Yes format the format text defining the value of the attribute, based on the entry's settings. Yes

Examples

<libraryDef> <policy> <repository dir="${3rdparty}"> <format text="[group]/[filename]" /> </repository> <path /> <derived-attribute> <attribute attrib="filename" format="[name]-[version].[type]" /> </derived-attribute> </policy> <library id="lib.coverage"> <entry group="coverage" name="compile" version="4.5-beta1" /> </library> </libraryDef> When the library lib.coverage is referenced, the <derived-attribute> processor will attempt to create the "filename" attribute on the entry. Since the entry doesn't have the "filename" attribute, the processor proceeds to attempt to match the entry. The format text [name]-[version].[type] matches the entry's attributes, forming "compile-4.5-beta1.jar" (the "type" attribute defaults to "jar"). The entry now has the attribute filename="compile-4.5-beta1.jar".

Since 0.7.0

Separates an entry into multiple entries if it defines a list of values in a specific attribute. This can be useful for simplifying the declaration of several entries with relatively the same information.

If an entry does not define the listAttribute, then it will not be split. Split entries will not be added to the final entry set, rather only the entries that it is split into are added.

This runs at the repository priority, with a default sub-priority of -1, so that each split-out entry can be discovered.

Parameters

Attribute Description Required listAttribute the name of the attribute that will be split. The value should be a list, and the processor will generate one entry for each list item. Yes destinationAttribute the name of the attribute that will be set to the split-out values from listAttribute. This can be the same attribute name as the attribute specified in listAttribute. Yes

Examples

<libraryDef> <policy> <repository dir="${3rdparty}"> <format text="[group]/[name]-[version].[type]" /> </repository> <path /> <split listAttribute="name-list" destinationAttribute="name" /> </policy> <library id="lib.jboss"> <entry group="jboss" name-list="jssa, client, j2ee" version="4.0.2" /> </library> </libraryDef> The entry will be split such that, when the repository processors run, it will look just like the user declared the library as: <library id="lib.jboss"> <entry group="jboss" name="jssa" version="4.0.2" /> <entry group="jboss" name-list="client" version="4.0.2" /> <entry group="jboss" name-list="j2ee" version="4.0.2" /> </library>

Since 0.4.0

Ensures that every entry was discovered by a repository. If an entry did not match a file in a repository, then the build will fail. If the entry is marked as an artifact (meaning that it may not be built at the time of the library definition), the file does not need to exist. Otherwise, the referenced file must exist, and conform to the type classification (if the "type" attribute is "dir", then the location must be a directory, otherwise it must be a file).

Note that this will work correctly in conjunction with the <compatible-version> processor: multiple entries that are filtered down to a single entry will cause the <must-find> processor to only check the final, single entry for existence.

This runs at the validate priority.

Since 0.7.0

This processor intends to select a single version of an entry from a listed set of versions. It finds all the entries in a library that have matching values for the attributes specified in the matchAttributes parameter, and selects the entry with the versionAttribute value that best meets the selection criteria.

Let's say we define the processor like this: <compatible-version versionAttribute="compatible-version" matchAttributes="g, n, type" chooseHighestVersion="true" /> and we have a library setup like this (we're interested in the outcome of library id "z"): <library id="widget"> <lib-entry g="mine" n="widget" version="1.0" /> <lib-entry g="apache" n="log4j" compatible-version="1.2.6" /> </library> <library id="gui"> <lib-entry g="mine" n="gui" version="1.0beta2" /> <lib-entry g="apache" n="log4j" compatible-version="1.2.8" /> </library> <library id="z"> <library refid="widget" /> <library refid="gui" /> </library> Based on the matchAttributes list, the <compatible-version> processor will look at the group of entries that share values for these attributes. In this case, it will group all of the log4j library entries together, since they have a matching g, n, and type (which, here, defaults to "jar"). The other two jars will be left as-is.

From the log4j set, the processor chooses the highest version entry, which happens to be "1.2.8". Then, whenever some processor that runs at a priority after this processor executes, it will see library "z" as having only the widget entry, the gui entry, and the log4j version 1.2.8 entry.

This processor, when combined with the <split> processor, can allow for easy-to-generate compabile version entries.

This runs immediately after the Repositories processors.

The mechanism for selecting the right version is done by using a custom java.util.Comparator class to sort the version strings, and select the first item in the list.

The default sorter works by splitting the version string into tokens. It sees the tokens as a string of numbers or of letters. Non-alphanumeric characters are ignored and considered token separators. In the case of version strings like "1.2beta2a", the ordered token list is "1", "2", "beta", "2", "a". It then follows a set of rules for ordering:

1. Numbers are ordered like numbers, and never like decimal points, so that "1.2" would be an earlier version than "1.10".
2. Letter strings are sorted according to the JVM's locale-specific sort mechanism, such that "a" is an earlier version than "b". This is also dependent on whether the ignoreVersionCase flag is set or not.
3. If version A has more tokens than version B, then version A will only be considered earlier than B if the first "extra" token is a letter string. Thus, "1.2beta" and "1.2rc" are earlier than "1.2", but "1.2" is earlier than "1.2.1". Likewise, "1.2rc" is earlier than "1.2rc2".

You can add your own Comparator by either adding the class to the Ant classpath and referencing the class name in the versionComparatorClass parameter, or by registering the class via a <typedef> declaration and adding it as an element to the processor.

Parameters

Attribute Description Required versionAttribute the name of the attribute which contains the version string. If the values of this attribute does not equal (case sensitive) between two entries which match, then the build fails. The default value is "compatible-version". No matchAttributes defines a comma-separated list of attributes whose values must equal for two entries to be considered referencing the same library file. The default match attributes are: "group", "groupid", "artifact", "artifactid", and "type". No ignoreMatchCase a boolean which tells the processor if the values of the match attributes should be case insensitive (true) or must match exactly (false, the default). No ignoreVersionCase a boolean which tells the processor if the version selection should take case sensitivity into consideration (false, the default), or if case should be ignored (true). This parameter will be ignored if a custom Comparator is used. No chooseHighestVersion a boolean which tells the processor which version should take precedence: the higher version (true), or the lower version (false, the default). No

Examples

<libraryDef> <policy> <repository dir="${3rdparty}"> <format text="[group]/[name]-[compatible-version].[type]" /> </repository> <path /> <split listAttribute="compatible-with" destinationAttribute="compatible-version" /> <compatible-version versionAttribute="compatible-version" chooseHighestVersion="true" matchAttributes="group, name, type" /> </policy> <library id="lib.apache"> <entry group="apache" name="log4j" compatible-with="1.2.6, 1.2.7, 1.2.8" /> <entry group="apache" name="xml-api" compatible-version="2.6.1" /> <entry group="apache" name="xml-api" compatible-version="2.6.2" /> </library> </libraryDef> When the library lib.apache is referenced, the <compatible-version> processor will search the library, and retrieve the highest version for each of log4j and xml-api jar files. The first entry is split into three entries (via the <split> processor), one for each version. Since all of these three share the same values for the group and name attributes, the entry with the "highest" version string from these three will be chosen (1.2.8 in this case). The same is true for the xml-api set (2.6.2 will be chosen). Thus, the <path> processor will create a path instance, with refid "path.lib.apache", which contains a reference to ${3rdparty}/apache/log4j-1.2.8.jar and ${3rdparty}/apache/xml-api-2.6.2.jar.

Since 0.3.1

The next release of Antlion will include a different processor which should supercede this one, but <version-check> will remain due to it being a slightly different check for versions.

For each library group, check if any entry defines the same library file but a different version. If such a conflict exists, then a build error is raised. Two entries are considered referencing the same library file if their "match" attributes are identical.

There is no way for this checker to be 100% accurate. There exist some circumstances where the entries reference the same library file but in different ways, but the versions are different. For instance, some library packages like Cactus come with their own copies of common libraries, which may be used elsewhere in a repository. Such libraries are difficult to define such that they may be version checked.

Note that even if two libraries are binary compatible, this will still fail. The versions must either exactly match, or this processor will fail the build. Human intervention is required to determine which library version to use, and the build must be correspondingly altered.

Future note: currently there are plans to expand the version dependency checking of Antlion. This will allow for a library to define compatible versions of an entry, from which only one will be chosen. This should solve many of the issues surrounding binary compatibility between Java JAR files.

This type runs at the validate priority.

Parameters

Attribute Description Required versionAttribute the name of the attribute which contains the version string. If the values of this attribute does not equal (case sensitive) between two entries which match, then the build fails. The default value is "version". No matchAttributes defines a comma-separated list of attributes whose values must equal for two entries to be considered referencing the same library file. The default match attributes are: "group", "groupid", "artifact", "artifactid", and "type". No ignoreMatchCase a boolean which tells the checker if the values of the match attributes should be case insensitive (true) or must match exactly (false, the default). No

Since 0.4.0

Allows for writing a custom processor in a scripting language supported by the Ant task <script>.

See the How-To Guide on Policies for details on how to use this processor.

You may give the source either inside the <script> tag, or reference a file containing the script by specifying the src attribute.

Parameters

Attribute Description Required src the location of the source file of the script to execute. No language the name of the scripting language that will be executed. Yes priority the priority of the <script> processor. This dictates the order in which the processor executes relative to the other processors. You may either give an number, or a descriptive name: Name order number first -150 prerepositories -50 repositories 0 properties 150 filesets 250 paths 350 validate 450 last 550 If a priority isn't given, then it defaults to the paths priority. Since you can directly set the priority level here, a <script> processor does not have a sub-priority. More details regarding priorities are discussed in the policy how-to guide. No libraryName the resource name of the library argument to the script. Defaults to "library". No loggerName the resource name of the logger argument to the script. Defaults to "logger". No