NAME

AFS::Command -- Wrapper Classes for the AFS Command Line Utilities

INTRODUCTION

Welcome to the OO Perl API for the AFS Command Line Utilities. OK, enough with formalities....

This set of classes implements a perl API for developing systems administration applications for AFS, and is essentially a complete rewrite of a similar API developed for perl4 almost a decade ago.

The API is designed to be as intuitive as the underlying command themselves. One of the strengths of the AFS CLI is its consistent command line parsing, since all of the utilities share a common library, and this API leverages this fact. The methods available, and their available arguments, are determined dynamically by parsing the command help strings.

This API is also designed to complement the existing perl5 AFS::* namespace, and co-exist with it.

OBJECT ARCHITECTURE

WARNING: This is an early design phase (1.x) of this API, and it is in its infancy, so expect it to change in future releases, and expect to change your code to accomodate it.

The entire API is designed to be pure OO, with the following classes:

AFS::Command::(VOS|BOS|PTS|FS)

These are the primary classes used by applications directly. All of the other objects are used internally to encapsulate the data parsed from the underlying commands, and returned by the primary methods.

Each of these classes has a shared constructor (new), and methods that correspond to each of the underlying commands. For example, the "vos" utility has a command called "listvldb", and the AFS::Command::VOS objects have a "listvldb" method. Each of the methods such as "listvldb" take a list of key/value pairs that correspond to the command line options for the "vos listvldb" command.

These classes implement the externally supported interface to the entire API. If you use anything else, you're mucking with internals, and you get what you deserver when your code implodes.

For details, see the module documentation for each of the above.

Also, the only reason there is no AFS::Command::KAS is that the author's AFS infrastructure is an MIT Kerberos site, and since we don't use the kas utility, there has never been a need for such a module.

The author would welcome a contributed module to support KAS via the same interface, but note that the AFS::KAS module exists as part of the existing AFS module suite, although the API is very different.

AFS::Command::Base

This is the base class for the command suite, which implements the shared constructor, and a couple of other useful class and object methods.

AFS::Object

This is the base class for the objects returned from the command methods that encapsulate some form of structured data. Many of the methods return simple boolean true/false values (either the command worked, or it failed), with no need for any special objects, so we don't create them. Anything that has to return interesting data uses this class, or one of its base classes.

The subclasses are associated with data structures such as volume headers, a VLDB entry, or a partition on a server. Each of these classes has methods to retrieve the objects they "contain", such as a method to query the list of volume names on a partition object, and a method to get a list of VLDB entries from a VLDB site.

The data structures, and their varying relationships, are documented in details of the methods for each of the commands, and the specific interfaces for each object type are documented in the corresponding class documentation.

The subclasses for encapsulating the VLDB data are:

    AFS::Object::VLDB
    AFS::Object::VLDBEntry
    AFS::Object::VLDBSite

The subclasses for encapsulating the volume headers are:

    AFS::Object::FileServer
    AFS::Object::VolServer
    AFS::Object::Partition
    AFS::Object::Volume
    AFS::Object::VolumeHeader

The subclasses for encapsulating the bosserver data are:

    AFS::Object::BosServer
    AFS::Object::Instance

Note that none of these classes are specifically documented, since the structure of the classes is subject to change. The API for accessin the results of any given AFS command (eg. vos listvol) is considered reasonably stable, but the encapsulation may change radically.

Don't get too attached to these class names, because they will likely be rearranged in a future release.

cpanm AFS::Object

perl -MCPAN -e shell
install AFS::Object