[guide] <alms-postfilters>

The <alms-postfilters> component lets you define a set of functions called module filters that SAM executes whenever it loads an antlib declared in an ALMS-dependent catalog. Each module filter is applied once— after the antlib package has been downloaded (and expanded if necessary) but before it has been moved to the local antlib repository; the filters are applied in the order they are declared in the <alms-postfilters> component. SAM includes several example module filters and you can create your own custom filters with the SAMS java libraries.

You associate a filter with an antlib through the module name you use to reference that antlib. Within SAM, this name is usually defined as the use parameter of the <method> element inside an <artifactdef> or <reactiondef> declaration. In the following example, you can associate a set of module filters with the “mkrequired” antlib package.

   <artifactdef name="dependencies">
      <defaults>
         <method use="mkrequired"/>
         <parameter name="in" value="@{dependencies.dir}"/>
      </defaults>
      …
   </artifactdef>

To apply one or more filters to every loaded antlib, use the specially named “*” module entry. This special entry tells SAM to automatically apply the named filters to every antlib unconditionally (after any other filters from an exactly matching module have been applied).

Parameters

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

The <module> element lets you insert a set of filters for a module into the catalog. You can define any number of module filter sets for a single catalog; however, each set must be uniquely named.

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

The <filter> element lets you define a single filter for a named module. You can define any number of filters for a single module. SAM has several predefined filters including a digest checker, a general token replacer, and a download info metafile creator. To use a custom filter you must create a Java class that implements the SAM ModuleFilter interface.

Nested Element: <parameter>^[0..*]
The <parameter> element lets you define a custom filter parameter for this instance of the filter. Refer to the specific filter’s documentation for a full description of any parameters.

Examples

The following snippet defines a set of aliases for all the filter classes used by a build. Note that the snippet uses both the category and forclass parameters to clearly mark the aliases as references to SAM module filter classes. Subsequent <alms-postfilters> declarations can use these aliases instead of hard-coding the filter classnames directly.

    <run-configuration name="common">
       <add-aliases>
          <category name="myfilters" forclass="com.idaremedia.sams.module.ModuleFilter">
             <alias name="stamper" forclass="myfilters.DownloadStamper"/>
             <alias name="localizer" forclass="myfilters.NamespaceApplicator"/>
             <alias name="verifier" forclass="myfilters.DigestChecker"/>
          </category>
          …
       </add-aliases>
    …

The following snippet defines a “verifier” filter and “stamper” filter for SAM to execute after each antlib download for any ALMS-dependent catalog that uses this standard.alms configuration. Note that because these filters apply to all antlibs, only the special module named “*” has to be defined.

    <almsdef id="standard.alms">
       <postfilters>
          <module name="*">
             <filter name="myfilters/verifier"/>
             <filter name="myfilters/stamper"/>
          </module>
       </postfilters/>
       …

Te following snippet uses the builtin SAMS module filter TokenReplacer on the antlib packages “mkreadmes” and “mkjavadocs”. Any occurances of @copyr@ and @title@ in the downloaded antlib script file will be replaced before the file is copied to the local uploads directory.

    <sam:almsdef id="default.alms">
       <postfilters>
          <module name="*">
             <filter classname="com.idaremedia.sams.module.filterdefs.TokenReplacer">
                <parameter name="begintoken" value="$$"/>
                <parameter name="endtoken" value="$$"/>
                <parameter name="token:xmlnslist"
                           value="xmlns:sam='antlib:com.idaremedia.sams'"/>
             </filter>
          </module>
          <module name="mkjavadocs">
             <filter classname="com.idaremedia.sams.module.filterdefs.TokenReplacer">
                <parameter name="token:copyr" value="(c) Copyright 1999 Me, Myself, and I"/>
                <parameter name="token:title" value="My Super API Documentation"/>
             </filter>
          </module>
          <module name="mkreadmes">
             <filter classname="com.idaremedia.sams.module.filterdefs.TokenReplacer">
                <parameter name="token:copyr" value="(c) Copyright 1999 Me, Myself, and I"/>
                <parameter name="token:title" value="My Super Project (2.1)"/>
             </filter>
          </module>
       </postfilters/>
       …

Related Topics

• The FlatModuleFilterCatalog Java class implements <alms-postfilters>.
• The <almsdef> type lets you define a custom module filter sets for ALMS dependent catalogs.
• The <add-aliases> task lets you define a set of module filter classname aliases.