[guide] <add-baseurls>

The <add-baseurls> task lets you define your base SAM resource locations for a particular iteration. Many SAM components will automatically check for and use a particular location, called a base url, if you have defined it; for example, the default ALMS storage policy will use the value of the userscratch base url when it determines where to store downloaded antlib packages. Each SAM component’s description states which, if any, base urls you must define for it to function properly.

You should think of a base url as a strongly typed, URL-based, connection instruction that can include non-trivial connection instructions like authentication credentials and retry policy. A base url usually serves as the root for an entire category of resources; for example, the “antlibs” base url might be the root of a remote repository of antlib-based packages. Although it is more common to retrieve information from base urls, they can be used for either uploading or downloading data; the exact role of the base url is determined by the SAM component that eventually uses it.

Because it is URL-based, base urls can refer to resource locations that are not part of the local file system; for example, it is common to include base urls that are http and ftp based. A base url can also use other protocols that are not part of the standard JRE platform if you configure the appropriate system properties to locate the custom protocols’ handlers.

Like much of the data in a SAM system you must declare a base url as part of a catalog, in this case, the iteration’s base urls catalog. In fact, each SAM iteration has at most one base url catalog that represents all of the base locations for your application; the <add-baseurls> task lets you define and install this catalog. If you call <add-baseurls> multiple times within a single iteration, each call layers its base urls in front of the pre-existing urls with later definitions masking earlier ones. Use the iterationid parameter to give each unique <add-baseurls> an iteration identifier; this identifier will prevent any re-run installer tasks from reinstalling the same set of base urls (as would occur if you use a task like <antcall> for example).

You can instruct a particular <add-baseurls> task to install shadow properties that contain the final resolved URLs in string form (both path and URL strings are supported). This is particularly useful if most of your base urls point to local filesystem objects as it lets you use either the path or the URL to refer to the location.

Parameters

Nested Element: <base>^[1..*]

The <base> element lets you insert a single base url into the catalog. Each base url must be uniquely named within a single <add-baseurls> instruction. You can define as many base urls in a single catalog as needed.

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

The <parameter> element lets you define custom connection options for the base url. Exactly how a parameter is used depends on the class of base url being defined. Generally, parameters are converted to generic request properties and passed as-is to the URL connection handler.

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

The <fixturecheck> element lets you insert a fixture verification assertion into this definition so you can verify that all required environment settings have been defined. The format of this element is exactly the same as the standalone AntX <fixturecheck> element; if the check fails, <add-baseurls> will signal a build error.

Examples

1) The following antlib snippet installs a base urls catalog that reflects a java library project’s directory layout. Note that the ordering of the <base> declarations is not important because absolute urls (no wrt option) are always resolved first. Also note that our directory names like “ workspace/” include the trailing slash that is required for proper URL parsing.

    <?xml version="1.0"?>
    <antlib>
      <add-baseurls pathsuffix=".dir">
          <fixturecheck isset="module_root" msg="'module_root' property defined"/>
          <!--
            | Project Layout
            -->
          <base for="root" uri="${$ospathurl:@(module_root)}" mustexist="yes"/>
          <base fortype="buildmeta" wrt="root" uri="build/"/>
          <base fortype="dependencies" wrt="root" uri="dependencies/"/>
          <base for="other-libs" wrt="dependencies" uri="libs/"/>
          <base for="other-testlibs" wrt="dependencies" uri="libs-programmertests/"/>
          <base for="other-config" wrt="dependencies" uri="config/"/>

          <base for="workspace" wrt="root" uri="workspace/"/>
          <base fortype="outputs" wrt="workspace" uri="outputs/"/>
          <base fortype="sources" wrt="workspace" uri="sources/"/>
          <base fortype="config" wrt="workspace" uri="config/"/>
          <base fortype="documents" wrt="workspace" uri="documents/"/>

          <base for="classes-outputs" wrt="outputs" uri="classes/"/>
          <base for="java-sources" wrt="sources" uri="java/main/"/>
          <base for="test-sources" wrt="sources" uri="java/tests/"/>
          <base for="web-sources" wrt="sources" uri="web/"/>
          <base for="test-outputs" wrt="outputs" uri="programmertests/"/>
          <base fortype="reports" wrt="documents" uri="reports/"/>
          <base for="apis" wrt="documents" uri="apis/"/>
      </add-baseurls>
      …
    </antlib>

2) The following snippet installs a set of base urls that reflects the location of many SAM-oriented resource repositories. Some of the base urls are file system based; many are located on the public internet and accessed using the standard HTTP protocol.

    <?xml version="1.0"?>
    <antlib>
      <add-baseurls urlsuffix="yes">
          <fixturecheck isset="TMP.url" msg="'TMP.url' property defined"/>
          <!--
            | Resource Homes
            -->
          <base for="ostempdir" uri="${TMP.url}"/>
          <base for="scratch" wrt="ostempdir"/>
          <base for="userscratch" wrt="ostempdir" uri="${user.name}/.builds/"/>
          <base fortype="antlibs" uri="http://antxtras.org/antlibs/" retries="1"/>
          <base fortype="arms" uri="http://antlibs.org/cornerstone/" retries="1"/>
          <base fortype="reactions" uri="file:///W:/builds/callbacks/"/>
      </add-baseurls>
      …
    </antlib>

Related Topics

• The BaseUrlCatalogInstallerTask Java class implements <add-baseurls>.
• A <run-configuration> is a special antlib that lets you define one or more <add-baseurls>.