view release on metacpan or  search on metacpan

lib/AFS/Command/Base.pod  view on Meta::CPAN

commands, simplifying subsequent coding a bit.

=over

=item command

This key has the pathname to the command to be used for execution.  By
default, this is the simple command name "vos", "bos", etc, and the
command will simply be found in your $PATH by exec().

If you want to run a specific version of vos not found in the $PATH,
then for example:

   my $vos = AFS::Command::VOS->new
     (
      command		=> "/ms/dist/openafs/PROJ/core/1.2.9/bin/vos",
     );

If the path given is invalid, then expect the API to implode on itself
when it can't be found, or it isn't an AFS vos command.

=item localauth, noauth, encrypt

All of these arguments correspond to command line arguments common
across the entire command line suite.  Typically, if an application
uses this flag once, it will be using it for B<all> subsequent calls as
well.  Therefore, the state of these flags can be set globally by
setting them when creating the command object.

    my $vos = AFS::Command::VOS->new
      (
       localauth	=> 1,
       encrypt		=> 1,
      );

NOTE: The encrypt option is only available in more recent versions of
AFS, and may be unsupported by the underlying commands.

XXX: What should the default behavior be?  Croak or carp? we can
figure out dynamically if the command supports it, and have the
constructor fail, or we can be lazy and let the first command fail.

=item quiet

The default behavior for the common -verbose flag is inverted.  By
default, all commands are run with the -verbose flag, in order to
capture maximum diagnostics when an error occurs.  Normally, the
chatty output is all trapped by the API anyway, so there is no
application visible noise, just more verbose errors.

There should be no need to disable verbosity, but for completeness,
specifying 'quiet' will turn off the default verbose output.

=item timestamps

If this argument is given, then the output collected from the commands
will be prepended with the date formatted using Date::Format with:

    %Y/%m/%d %H:%M:%S

This is primarily useful for debugging and timing of commands such as
vos release, which can be very time consuming.  Since we enable
-verbose by default, this option will let us determine the relative
time required for each step in these complex operations.

This only applies to commands that return simple return values, eg:
release, restore, etc.  Commands that return complex structures of
objects, such as listvldb, listvol, etc will not be affected.

=back

=head2 setCarp

This class method configures the carp and/or croak subroutines used
throughout the API.  By default, the obviously sensible thing is done:
the carp an croak subroutines exported by the Carp module are used.
These normally print output to stderr, and this method provides a
mechanism for trapping these errors and redirecting them elsewhere.

For example, stderr in a system daemon may be entirely ignored, and
syslog may be a more appropriate destination.  In this case, the
setCarp method may be used to configure this, globally, for the entire
API.

    AFS::Command->setCarp
      (

       carp => sub {
	   my ($lines) = @_;
	   foreach my $line ( split(/\n+/,$lines) ) {
	       syslog('warning',$line);
	   }
       },

       croak => sub {
	   my ($lines) = @_;
	   foreach my $line ( split(/\n+/,$lines) ) {
	       syslog('error',$line);
	   }
	   die $lines; # If we're dying, whine at stderr, too.
       },

      );

This method takes a list of key/value pairs, with only two supported
keys (anything else will be quietly ignored): carp an croak.  The
values are CODE references (anonymous subroutines, or references to
existing subroutines).  The carp CODE should not be fatal, however the
croak CODE should.  The API calls the croak method in very few places,
but when it does, it assumes that call will be fatal, so if you
provide a croak subroutine that doesn't die, the results will be
unpredictable, and unsupportable.

This method returns true of false, depending on whether or not the
carp and/or croak subroutines were properly configured.  If the values
are not CODE references, then this method will itself croak.

=head1 INSTANCE METHODS

=head2 errors