[guide] <alms-searchpath>

The <alms-searchpath> component lets you define an ALMS antlib search path that any ALMS-dependent catalog can use. Every ALMS instance has an associated search path that it uses to locate antlibs. By default this search path is set to a single url defined in the build-iteration’s base urls catalog. The exact base url the ALMS uses is defined by its creator; for example, an artifact definition catalog tells its enclosed ALMS instance to use the “arms” base url for all antlib downloads whereas a cleanup definition catalog wants to use the “cleanups” base url. While this default single url behavior is adequate for many uses, an ALMS instance must also allow your application to specify its own kind of multi-sourced search path if it is to support independently administered antlib repositories; this is where you need to use <alms-searchpath>. To tell an ALMS instance where to find your custom antlib repositories you must define an <almsdef> that includes your custom search path and then associate that almsdef with your catalog.

Out-of-the-box the <alms-searchpath> item lets you declare three kinds of searchable targets and you can provide your own adapters to other types of targets. The first kind of target, a single readable base url, is also the default for most ALMS instances. The URL described by the base url is assumed to be the root of the antlib repository; all antlibs are loaded relative to this base using the ALMS’s naming policy to determine the final URL. Typically this base url uses one of the better known protocols like http, ftp, or file. The second kind of searchable target is a standard Ant <dirset> or <filelist>. You would use this kind of target when your antlib repository is best represented as a collection of disparate local directories— each directory is assumed to represent the root of a local independent antlib repository. Use the <filelist> variant to guarantee the order in which the directories are searched. The last kind of search target is a sequence of independent urls. Each url is assumed to be the root of an antlib repository.

Parameters

Nested Element: <catalog>^[0..*]

The <catalog> element lets you include an entry from a standalone base urls catalog into the search path. You would typically use a <catalog> entry to supplement the iteration-bound catalog with a project-bound base url catalog. The exact base url the ALMS uses from the named catalog is defined by its creator; this element merely defines the parent catalog.

Nested Element: <dirset>^[0..*]

The <dirset> element lets you insert a collection of antlib repository root directories into the search path. You would typically use a <dirset> to link an external repository sync tool’s cache into the SAM system. This element is the same as a standard Ant <dirset> item.

Nested Element: <dirlist>^[0..*]

The <dirlist> element lets you insert an ordered collection of antlib repository root directories into the search path. You would typically use a <dirlist> to link an external repository sync tool’s cache into the SAM system while ensuring the order in which the directories where searched. This element is the same as a standard Ant <filelist> item with the caveat that the named items should refer to directories only.

Nested Element: <urls>^[0..*]

The <urls> element lets you insert an ordered collection of antlib repository root urls into the search path. You would typically use a <urls> entry to use a collection of remote antlib repositories without having to declare a SAMS catalog for each one. This element is the same as a standard AntX <urls> item.

Nested Element: <defaultsearchpath>^[0..1]

The <defaultsearchpath> element lets you mark where the current iteration’s base urls catalog’s entry should be searched. If omitted, the current iteration’s base urls catalog is completely ignored by the ALMS instance.

Examples

The following script snippet declares a standalone ALMS search path that first searches two local ARM package directories before the fallback iteration location (wherever that is).

    <alms-searchpath id="alms.searchpath">
        <dirset dir="${dependencies.dir}/antlibs">
          <include name="packageABC"/>
          <include name="package123"/>
        </dirset>
        <defaultsearchpath/>
    </alms-searchpath>

The following script snippet references the ALMS search path declared in the previous example as part of an artifact definition catalog. Note that you can also declare the search path directly inside the catalog definition using the same syntax as the standalone declaration.

    <add-artifactdefs category="Deploy">
        <almsconfig>
            <searchpath refid="alms.searchpath"/>
        </almsconfig>
        …
    </add-artifactdefs>

The following script snippet declares a standalone ALMS search path that searches several local directories in a particular order before the fallback iteration location (wherever that is).

    <alms-searchpath id="alms.searchpath">
        <dirlist dir="${user.home}/.builds/antlibs"/>
        <dirlist dir="${buildtools.dir}/antlibs">
          <file name="project"/>
          <file name="enterprise"/>
          <file name="stubs"/>
        </dirlist>
        <defaultsearchpath/>
    </alms-searchpath>

The following script snippet declares a standalone ALMS search path that searches several remote antlib (cleanupdef) repositories in a particular order.

    <alms-searchpath id="saladbar.cleanups">
        <urls prefix="http://www." suffix=".org/saladbar/cleanupdefs/">
          <url value="antlibs"/>
          <url value="antxtras"/>
        </urls>
        <defaultsearchpath/>
    </alms-searchpath>

Related Topics

• The CatalogSearchDef Java class implements <alms-searchpath>.
• The <almsdef> type lets you define a custom search path for ALMS dependent catalogs.