###
###  Copyright 2000-2007 University of Illinois Board of Trustees
###  All rights reserved. 
###
###  PSGConf::Action - base claass for psgconf action types
###
###  Campus Information Technologies and Educational Services
###  University of Illinois at Urbana-Champaign
###


package PSGConf::Action;

use strict;


###############################################################################
###  constructor
###############################################################################

my %defaults = (
	requires_reboot		=> 0,
	quiet			=> 0
);

sub new
{
	my ($class, %opts) = @_;
	my ($self, $caller, $ct);

	$self = \%opts;

	$self->{changed} = 0;
	map {
		$self->{$_} = $defaults{$_}
			if (!exists($self->{$_}));
	} keys %defaults;

	if ((!exists($self->{name}) || $self->{name} eq '')
	    && ! $self->{quiet})
	{
		for ($ct = 0; $caller = (caller($ct))[3]; $ct++)
		{
			last
				if ($caller !~ m/^PSGConf::Action::/);
		}
		$caller = (caller(1))[3]
			if (!defined($caller));

		die "PSGConf::Action->new(): no name attribute from caller $caller\n";
	}

	return bless($self, $class);
}


###############################################################################
###  utility function to set tmpfile
###############################################################################

sub _set_tmpfile
{
     my ($self, $psgconf) = @_;

     return
          if (exists($self->{tmpfile}));

     $self->{tmpfile} = $self->{name};
     ###
     ### FIXME: We need to properly handle spaces when 
     ### we start working with MacOS X.
     ###
     $self->{tmpfile} =~ s|[/      ]|_|g;
     $self->{tmpfile} = $psgconf->{tmpdir} . '/' . $self->{tmpfile};
}


###############################################################################
###  do() method
###############################################################################

### FIXME: this is for backward-compatibility only!
sub do
{
	my ($self, $psgconf) = @_;

	warn $0 . ": WARNING: class '"
		     . ref($self)
		     . ": 'fix' method should be renamed 'do'\n";

	return $self->fix($psgconf);
}


###############################################################################
###  check method
###############################################################################

sub check
{
	my ($self, $psgconf) = @_;

	### return 0 so diff() and do() will never get called
	return 0;
}


###############################################################################
###  requires_reboot method
###############################################################################

sub requires_reboot
{
	my ($self) = @_;

	return $self->{requires_reboot};
}


###############################################################################
###  name method
###############################################################################

sub name
{
	my ($self) = @_;

	return $self->{name};
}


###############################################################################
###  quiet method
###############################################################################

sub quiet
{
	my ($self) = @_;

	return $self->{quiet};
}


###############################################################################
###  changed method
###############################################################################

sub changed
{
	my ($self) = @_;

	return $self->{changed};
}


###############################################################################
###  documentation
###############################################################################

1;

__END__

=head1 NAME

PSGConf::Action - base class for PSGConf action types

=head1 SYNOPSIS

  use PSGConf::Action;

  $psgconf->register_actions(
		PSGConf::Action->new(
			'name'			=> '/path/to/file',
			'requires_reboot'	=> 1,
			...
		),
		...
	);

=head1 DESCRIPTION

The B<PSGConf::Action> module provides a class that represents an action
in B<PSGConf>.

The B<PSGConf::Action> class is not intended to be used to directly
instantiate action objects, but it does support the following methods
for use in subclasses:

=over 4

=item new()

The constructor.  It can be passed a hash to set the object's
attributes.  The object will be created as a reference to this hash.

The following attributes are supported:

=over 4

=item I<name>

Indicates the "name" of the action, which will be printed in the
"checking" message when the check() method is called.  For actions that
create or manipulate a file, it is typically set to the absolute path
of the file.

This attribute is mandatory unless the I<quiet> attribute is enabled.

=item I<quiet>

A boolean value that indicates whether a "checking" message should be
printed when the check() method is called.  If not set, it defaults to 0.

=item I<requires_reboot>

A boolean value that indicates whether the system needs to be rebooted
if the do() method succeeds.  If not set, it defaults to 0.

=back

In addition, the constructor always initializes the object's I<changed>
attribute to 0.

=item name()

Returns the object's I<name> attribute.

=item quiet()

Returns the object's I<quiet> attribute.

=item requires_reboot()

Returns the object's I<requires_reboot> attribute.

=item changed()

Returns the object's I<changed> attribute.

=back

Subclasses should always define the following methods:

=over 4

=item check()

Check to see whether the action needs to be performed.  Returns 0 (and
sets the object's I<changed> attribute to true) if no change is needed,
1 if the action needs to be performed, and -1 on error.

=item diff()

Displays a detailed list of the changes that will be made to the
system.  No return value.

=item _set_tmpfile()

Utility method for use in subclasses' check() method.  Takes a reference
to a B<PSGConf> object as its only parameter.  Sets the object's
I<tmpfile> attribute based on the object's I<name> attribute and the
B<PSGConf> object's I<tmpdir> attribute.

=item do()

Actually perform the action.  Returns 1 on success, or -1 on error.

=back

=head1 SEE ALSO

L<perl>

L<PSGConf>

=cut