NAME

IMS::ReleaseMgr - Perl extension for managing IMS Release Manager packages

SYNOPSIS

    use IMS::ReleaseMgr;

    $P = new IMS::ReleaseMgr(name => 'mpgcpd',
                             email => 'contractor@aol.com',
                             file => '/tmp/inbound/mpgcpd.tar');
    $P->validate;
    if (! $P->commit(directory => '/opt/ims/incoming'))
    {
        die "Error attempting to commit package: " . $self->error .
            "\nStopped ";
    }
    $P->close;

    exit 0;

DESCRIPTION

The IMS::ReleaseMgr package is designed to provide an API layer over the IMSS Release Manager software, for Perl programs. The goal is to provide a means by which a program can place an archive file and create the release manager ticket file without the developer being concerned about the finer implementation points. The interface is implemented in an object-oriented approach, with an object destructor that verifies a package was saved prior to destruction (the destruction is unavoidable, but the person running the application does receive notitification, aiding in problem tracking).

Deploying content to servers is a basic requirement for supporting the web development environment that IMSS is responsible for. In addition, for those hostnames that are in fact implemented as a cluster of mirrored servers, simple writing of the data is not sufficient, as it must also be propagated to the mirror hosts.

By using this library in place of simply writing data to pre-determined directories, the release manager is able to step in and manage the deployment and mirroring of data. This frees the application developer from concerns of how to ensure successful mirroring.

METHODS

This interface is implemented as an object class, allowing the data and functions to be wrapped together and remain transparent to the user. Unless otherwise noted, any methods that take arguments take them in a name-value form, such as: name = value. See the sample code above.

The functions and methods available are:

new

The object constructor. This initializes and returns an object of the IMS::ReleaseMgr class. Named arguments are: name, the name of the project that the content is deploying to; file, the name of the tar archive file that contains the material being released; filehandle, an alternative to file that accepts a currently-open filehandle; directory, the directory on the client side where the release manager expects incoming files to be placed; emails, a list-reference of e-mail addresses that should receive the per-stage notification from the release manager; and email, a short-form of emails that passes a single address in via a scalar.

error

Returns the error text, and possibly the context, of the most recent error. If called in a scalar context, it returns simply the error text (which may be the null string). In a list context, it returns a three-value list of the text, followed by the file in which the code was in, and the line number of that file. If called in a void context, nothing is returned.

If the IMS::ReleaseMgr class is used as a super-class, then the implementor of the sub-class may have use of the internal call style: if error is called with any arguments, they are treated as text, file and line, in that order. These values are then set as the current error text, etc. This is the means used internally both to set and clear errors. Applications SHOULD NOT use these, as the API is not considered public and therefore more succeptible to change. This form should only be used within the IMS::ReleaseMgr package or sub-classes.

abort

This can be used in place of close below, in cases where a fatal error has occurred (such as in validation). It performs clean-up and clears flags so that no warning is generated at object destruction (as a last-gasp measure, the class destructor makes a final check that the data was indeed written to disk before being lost). It takes one named parameter, called nodelete, that is passed unexamined through to the cleanup method. The return value is always true.

validate

Perform certain integrity checks on the archive file portion of the object. The package must contain a file whose name is either weblist or Weblist. Additionally, it cannot contain any of: absolute paths, symbolic links, or relative paths containing the .. directory element. These content restrictions are to improve security. If the return value is undef, then there was something wrong (use error to check). The success value returned is the object value itself (the reference). The only argument accepted is the named parameter verbose, which if non-null means to include much more verbose information in the error text generated at failure.

commit

This is the means by which to actually put to disk the archive data, and create the release manager information file. This will fail if no directory has been specified (either with new or by a parameter to this method) or if the package has not been validated. The named parameters that are accepted here are: directory, the directory into which the archive should be placed. If this was specified in new, it can be overridden here. The other is noupload, which disables upload-request settings in the release manager file. The release manager propagates packages throughout a mirrored environment; if passed in with a non-null value, this disables that feature. Great care should be taken in using this feature, as it could cause data to not be mirrored correctly. The return value is undef on error, object reference on success.

close

This routine checks that data has been successfully commited prior to object destruction. It calls cleanup if it has not already been called. This is also a place-holder for either future expansion or for sub-classing. Return value is undef on error, object reference on success.

cleanup

Perform any cleaning tasks that need to be done between data commit and object destruction. This is called by close if it has not already been called. Return value is undef on error, object reference on success. It takes one optional named parameter, nodelete. If set to non-null, it prevents the deletion of any temporary files that the IMS::ReleaseMgr package created during the processing of this object. Since close will not call cleanup a second time, explicit calling of cleanup with this parameter set to 1 (or any value) will prevent file deletion and leave the files in place for debugging and analysis.

sync

This is used to ensure that any internal buffers or file-pointers are syncronized, generally prior to a validate or commit. It is called by both of those methods, so it is rarely used itself. It is provided as a hook for sub-classes or for future functionality. Return value is undef on error, the object reference on success.

The insistence of most methods of returning the object reference upon success enables chains such as:

    $P = IMS::ReleaseMgr->new()->validate->commit->close;

Such a chain will die after the first link that returns failure. Of course, it will do so in an exceedingly noisy and ungainful manner, but it may be useful for Perl one-liners.

AUTHOR

Randy J. Ray <randyr@nafohq.hp.com>

SEE ALSO

perl(1).