[guide] <managesams>

The <managesams> task lets you perform two essential SAM administration functions. First it lets you bootstrap the SAM system from your driver Ant script. By explicitly starting the SAM system you ensure a SAM-based iteration is created and properly initialized as early as possible. Although an AntX iteration always exists; a <managesams> task will ensure it is of a SAM-compatible type and has all the expected services like a public artifact locations catalog. The second primary function of the <managesams> task is to let you create named run harnesses. Many SAM components use a run harness to perform their script-observable activities. By using different run harnesses you can isolate your different components and partition your observer callbacks.

The best place to use <managesams> to initialize your SAM environment is from a root or “driver” project. Child projects (triggered using tasks like <subant>, <ant>, and even <antcall>) should expect to have a SAM iteration already installed (and pre-loaded with shared declarations like artifact definitions). This best practise is no different from declaring all of your task and macro definitions in a single parent project before launching sub-builds that automatically inherit all of those type definitions. If a child project does install iteration fixture, SAM will try to automatically remove that fixture when the child project terminates to ensure that references to now defunct projects are not left inadvertently dangling off the shared iteration.

If you want to ensure your scripts use a SAMS iteration but do not need any of the other functionality <managesams> provides, you can define a service properties resource file com.idaremedia.antx.Iteration in your META-INF/services directory. The service file should contain the fully qualified classname of the SAMS Iteration type: com.idaremedia.sams.Iteration.

Parameters

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

The <parameter> element lets you specify options to the named manager action as simple key-value pairs. The legitimate values for the parameter’s name and value attributes depends on the manager’s action parameter. The following sub-sections describe the allowed values for a parameter name in the context of a particular action.

When action=“install”

When action=“install-runharness”

When the action is install-runharness each parameter’s name is set to the name of the run harness you want created. The parameter’s value is not needed. If a run harness with the given name already exists, a new one is not created.

When action=“uninstall-fixture”

When the action is uninstall-fixture each parameter’s name is set to the name of the type of fixture you want removed. Only fixture items, like catalogs, installed from within the current project are removed from the current iteration (and all items of the named type are removed). The parameter’s value is not needed. The set of known fixture types includes: “runharness”, “artifactdefs”, “reactiondefs”, “modulefilters”, “aliases”, and “baseurls”. Regular build scripts would rarely use this action as SAM automatically purges locally installed iteration fixture when the (child)project terminates. This action is included as an aid to script development and testing.

Examples

The following snippet bootstraps the SAM system.

    <project name="driver" default="help" xmlns:c="antlib:com.idaremedia.sams.install">
        <c:managesams/>
        ...
    </project>

The following snippet bootstraps the SAM system and immediately applies a startup configuration file boot.rcf.

    <project name="driver" default="help" xmlns:c="antlib:com.idaremedia.sams.install">
        <c:managesams action="install">
           <parameter name="inifile" value="boot.rcf"/>
        </c:managesams>
        ...
    </project>

The following snippet bootstraps the SAM system and then creates two run harnesses: Builds and Deploy. Note that we must call <managesams> two times, each time with different action parameter.

    <project name="driver" default="help" xmlns:c="antlib:com.idaremedia.sams.install">
        <c:managesams/>
        <c:managesams action="install-runharness">
           <parameter name="Builds"/>
           <parameter name="Deploy"/>
        </c:managesams>
        ...
    </project>

Related Topics

• The SAMSManagerTask Java class implements <managesams>.
• The <fixturedef> task lets you load and apply a startup <run-configuration> to the current iteration.