[guide] <alms-storagepolicy>

The <alms-storagepolicy> component lets you define a custom ALMS storage policy that any ALMS-dependent catalog can use. A storage policy describes, among other things, how published antlib packages are organized at their source repositories, where local antlib packages will be stored, where published antlib packages can be can downloaded and post-processed before being stored locally, and how local antlib packages should be tested for “up-to-datedness”.

A storage policy is always associated with an ALMS instance (directly or indirectly through some catalog); by itself a storage policy has no useful function. To tell an ALMS instance how to store your antlib packages you must define an <almsdef> that includes your custom storage policy and then associate that almsdef with your catalog.

If you use an independent antlib repository synchronization tool, a storage policy lets you hook SAM into that tool’s local directory (or URL-accessible) storage or cache structure. In this scenario, the ALMS instance’s “download” operation becomes an optional local copy operation that ensures all antlib filters are applied as expected.

Every storage policy comes with a default name policy that governs how the ALMS instance converts your script-supplied retrieval method names into a published antlib package’s name. SAM supports four builtin naming policies and you are free to supply your own (see the NamePolicy interface in the SAM source distribution). Below the SAM policies are described briefly by name:

• sams or mkartifact: This is the default naming policy for ARM packages. Example layout: for an ARM named “mkreadmes”, its published package must be a jar located in a subdirectory “r” and named “readmes.jar”. The main archive must contain (at least) one antlib named “readmes.arm”. The archive will be extracted into a directory “r/readmes” in the ALMS’s assigned uploads area. Note that in this policy, the module’s name is always prefixed with a “mk” so that you can use the simple name in your artifact definitions without fear of a name collision with the ARM’s macrodef.
• simpleartifact: Use this naming policy for simple jar’ed ARM packages. Example layout: for an ARM named “readmes”, its published package must be a jar located in a subdirectory “r” and named “readmes.jar”. The main archive must contain (at least) one antlib named “readmes.arm”. The archive will be extracted into a directory “r/readmes” in the ALMS’s assigned uploads area.
• simplearchive: Use this naming policy for simple jar’ed antlib packages. Example layout: for an ARM named “readmes”, its published package must be a jar named “readmes.jar” that contains (at least) one antlib file named “readmes.xml”. The archive will be extracted into a directory “readmes” in the ALMS’s assigned uploads area.
• simplefile: Use this naming policy for single antlib files. Example layout: for an ARM named “readmes”, its published package will be a single file named “readmes.xml”. The file will be downloaded into a directory “readmes” in the ALMS’s assigned uploads area.

Parameters

Nested Elements

The <alms-storagepolicy> element does not support any nested elements.

Examples

The following snippet shows two ways to declare a custom storage policy for a reaction definition catalog; the first example uses SAM-based base urls, the second regular directory paths. The storage policy also declares that all antlib packages are distributed as simple single antlib files named like: method-name.xml.

    <add-reactiondefs...>
        <almsconfig>
            <storagepolicy
                  scratch="userscratch"
                  uploads="adhoc.workspace"
                  namepolicy="simplefile"/>
        </almsconfig>
        …
    </add-reactiondefs>
  -OR-
    <add-reactiondefs...>
        <almsconfig>
            <storagepolicy
                  scratchdir="${userscratch.dir}"
                  uploadsdir="${adhoc.workspace.dir}"
                  namepolicy="simplefile"/>
        </almsconfig>
        …
    </add-reactiondefs>

The following snippet shows how to disable local caching of downloaded antlibs. The specific catalog is told to ignore any pre-existing antlib packages in favor of newly downloaded copies. Note that the iteration will use the default SAM locations for all antlib package processing.

    <add-artifactdefs...>
        <almsconfig>
            <storagepolicy ignoreolduploads="yes"/>
        </almsconfig>
        …
    </add-artifactdefs>

The following snippet shows how to use an AntX criteria (downloaded-today) to determine if a pre-existing antlib package is still usable. Usually this function is performed by an external repository synchronization tool; however, SAM has several hooks to let you either connect SAM to such a tool’s local cache or author your own Ant up-to-date tests.

    <criteria id="downloaded-today">
       …
    </criteria>
    …
    <add-artifactdefs...>
        <almsconfig>
            <storagepolicy
                  uploads="local-antlibs"
                  uptodate="downloaded-today"/>
        </almsconfig>
        …
    </add-artifactdefs>

Related Topics

• The StoragePolicy Java class implements <alms-storagepolicy>.
• The <almsdef> type lets you define a custom storage policy for ALMS dependent catalogs.
• The <alms-postfilters> task lets you define custom antlib package post-processing the results of which you can use in adhoc up-to-date tests.