#
# Copyright (c) 2001-2012 NetApp, Inc., All Rights Reserved
#   Any use, modification, or distribution is prohibited
#   without prior written consent from NetApp, Inc.
#

## @summary VserverNfsKerberosRealm Task Module
## @author dl-nacl-dev@netapp.com
## @status private
## @pod here

package NACL::STask::VserverNfsKerberosRealm;

use strict;
use warnings;

use base qw(NACL::C::VserverNfsKerberosRealm NACL::STask::STask);

use NATE::Log qw(log_global);
my $Log = log_global();
my $may_enter = $Log->may_enter();
my $may_exit  = $Log->may_exit();
use Params::Validate qw(validate SCALAR BOOLEAN SCALARREF);
use NATE::BaseException qw(:try);

=head1 NAME

NACL::STask::VserverNfsKerberosRealm

=head1 DESCRIPTION

This library is deprecated, use NACL::STask::VserverNfsKerberosRealm instead
This library will be deleted soon

=head1 ATTRIBUTES

=head2 command_interface

(Required) A component object that represents the host to which to send commands.

=head2 vserver

The name of the vserver where Realm is configured, used to identify it uniquely.

(Note that if the command_interface attribute is a
L<NACL::C::Vserver|lib-NACL-C-Vserver-pm>, then this attribute will be undef)

=head1 METHODS

=head2 create

    my $realm  = NACL::STask::VserverNfsKerberosRealm->create(
        command_interface  => $command_interface,
        vserver            => $vserver_name,
        nacltask_if_exists => $action,        # default 'die'
        %other_options,                       # pass any other optiots
    );

(Class method) Enable and configure a Vserver Nfs kerberos realm.
Prior to this, the Vserver creation must be done and the Vserver
should exist within the cluster. This method provides additional
services beyond what's inherent to Vserver Nfs kerberos realm creation on the
cluster, as controlled and described by the new C<nacltask_if_exists>
and C<nacltask_verify> options.

=over

=item Options

=over

=item C<< if_exists=>$action >>

(Optional) What to do if the Vserver  kerberos realm has already been created.
If $action is "die" (the default), then fail with an exception (in the
same way that the VserverNfsKerberosRealm component would:  by trying the
vserver nfs kerberos realm create and letting the product complain about  realm already
existing). If action is "reuse", then verify the realm settings
with user specified options. If they match, return a task object
referring to the existing realm. If the action is reuse and the
options do not match, then delete the existing share and create a new
realm using options. If action is "purge", then delete the vserver
nfs kerberos realm.

=item C<< nacltask_verify => 0|1 >>

(Optional, defaults to 0)
This option is used to toggle whether to verify that the created realm
has exactly the same attributes as we specified in the call. A
L<NACL::Exceptions::VerifyFailure|lib-NACL-Exceptions-VerifyFailure-pm>
exception is thrown if one or more attributes of the creates realm
do not match the specified values.
This defaults to not being performed.

Note that if we want to verify for only some, but not all fields, we can do so
using L<verify_state|lib-NACL-C-Component-pm/verify_state>.

=item C<< _was_created => \$scalar >>

(Optional)
When this option is provided a reference to a scalar variable, the variable
gets filled in with a boolean value describing whether the nfs share
was found (value will be 0; this scenario is possible when
if_exists => "reuse") or whether the realm was created (value will be 1).
This is necessary to determine whether the realm needs to be
cleaned up later.

    my $was_created;
    my $realm_obj = NACL::STask::VserverNfsKerberosRealm->create(
        if_exists    => 'reuse',
        _was_created => \$was_created,
        %other_opts
    );
    # Operate on $realm_obj here
    # ...
    # Now determine whether to clean up the realm, since we're not sure
    # whether we reused an existing realm or created a new one
    if ($was_created) {
        # New realm was created. Clean it up.
        $realm_obj->purge();
    }

=item C<< "method-timeout"=>$timeout >>

(Optional) How long in seconds to wait for the job to finish or for
the state to become "online".  Defaults to 60 seconds.

=item C<< apiset_must=>$ruleset >>

(Optional)See L<NACL::C::Component|lib-NACL-C-Component-pm/apiset_must>

=item C<< apiset_should=>$ruleset >>

(Optional)See L<NACL::C::Component|lib-NACL-C-Component-pm/apiset_should>

=item C<< %other_options >>
(Optional) All of the other various options to

L<< NACL::C::VserverNfsKerberosRealm->create|lib-NACL-C-VserverNfsKerberosRealm-pm/create >>
like V3 V4.0 udp tcp spinauth default-win-user v4.0-acl etc.


=back

=back

=cut

sub create {
    $Log->enter() if $may_enter;
    my ( $pkg, @args ) = @_;
    my %opts = $pkg->_common_validate_with(
        params          => \@args,
        additional_spec => {
            nacltask_if_exists => $pkg->_if_exists_validate_spec(),
            $pkg->_cleanup_validate_spec(),
            nacltask_verify => { type => BOOLEAN,   default  => 0 },
            _was_created    => { type => SCALARREF, optional => 1 },
        },
        allow_extra => 1,
    );

    # move the cleanup related options to separate hash
    my (%opts_for_cleanup, %opts_for_register, $nacltask_to_cleanup);
    $pkg->_move_common_cleanup_opts(
        source              => \%opts,
        target              => \%opts_for_cleanup,
    );

    # Transform %opts from the options we received into the options to
    # pass to the base class method.
    my $if_exists = delete $opts{nacltask_if_exists};
    my $verify = delete $opts{nacltask_verify};
    my $was_created = delete $opts{_was_created};
    $$was_created = 0;

    my $self;

CREATE: {
        use warnings qw(exiting);
        try {
            $self         = $pkg->SUPER::create(%opts);
            $$was_created = 1;
            $pkg->taskverify_create(%opts) if $verify;
        }
        catch NACL::C::Exceptions::VserverNfsKerberosRealm::AlreadyExists with {
            my $exception = shift;
            $self = $pkg->_element_exists_handler(
                create_opts        => \%opts,
                nacltask_if_exists => $if_exists,
                exception          => $exception
            );
            if ( !$self ) {
                no warnings qw(exiting);
                redo CREATE;
            }
        };
    }

    # Register this resource with the Cleanup Manager for cleanup
    $pkg->_copy_common_opts_for_cleanup(
        'source'              => {%opts, %opts_for_cleanup},
        'target'              => \%opts_for_register,
        'nacltask_to_cleanup' => \$nacltask_to_cleanup,
        'to_cleanup'          => 'purge'
    );
    $pkg->_register_for_cleanup(%opts_for_register) if ( $nacltask_to_cleanup && $$was_created );

    $Log->exit() if $may_exit;
    return $self;
}

=head2 purge

    NACL::STask::VserverNfsKerberosRealm->purge(
        command_interface => $command_interface,
        vserver => $vserver_name,
        ...
    );

    $nfsshare->purge(...);

(Class or instance method) This method deletes the nfs kerberos realm of
the vserver.

=over

=item Options

=over

=item C<< _was_deleted => \$scalar >>

(Optional)
When this option is provided a reference to a scalar variable, the variable
gets filled in with a boolean value describing whether the realm
did not exist (value will be 0; this scenario is possible when
nacltask_if_purged => "pass") or whether the realm was deleted
(value will be 1).

=item C<< nacltask_verify => 0|1 >>

(Optional, defaults to 0)
This option is used to toggle whether to verify realm has been purged.
L<NACL::Exceptions::VerifyFailure|lib-NACL-Exceptions-VerifyFailure-pm>
exception is thrown if this verification failed.
This defaults to not being performed.

Note that this can also be performed in a separate call using
C<taskverify_purge>. Example:

    $realm_obj->purge();
    ...
    $eralm_obj->taskverify_purge();

=item C<< nacltask_if_purged => 'die' | 'pass' >>

(Optional, defaults to 'die')
Used to specify whether attempting to purge when the realm has
already been previously purged should result in a failure or not.
When this is 'die' (the default), it throws an exception.
When this is 'pass' it does not error out if has already been purged.

=item C<< apiset_must=>$ruleset >>

(Optional)See L<NACL::C::Component|lib-NACL-C-Component-pm/apiset_must>

=item C<< apiset_should=>$ruleset >>

(Optional)See L<NACL::C::Component|lib-NACL-C-Component-pm/apiset_should>

=back

=back

=cut

sub purge {
    $Log->enter() if $may_enter;
    my ( $pkg_or_obj, @args ) = @_;
    my %opts = $pkg_or_obj->_common_validate_with(
        params          => \@args,
        additional_spec => {
            nacltask_verify    => { type => BOOLEAN, default => 0 },
            nacltask_if_purged => { type => SCALAR,  default => 'die' },
            _was_deleted       => { type => SCALARREF, optional => 1 },
        },
        allow_extra => 1,
    );
    my $verify = delete $opts{nacltask_verify};
    my $if_purged = delete $opts{nacltask_if_purged};
    my $was_deleted  = delete $opts{_was_deleted};
    $$was_deleted = 0;
    try {
        $pkg_or_obj->delete(%opts);
        $$was_deleted = 1;
        $pkg_or_obj->taskverify_purge(%opts) if $verify;
    }
    catch NACL::C::Exceptions::VserverNfsKerberosRealm::DoesNotExist with {
        my $exception = shift;
        $pkg_or_obj->_handle_if_purged(
            exception          => $exception,
            nacltask_if_purged => $if_purged
        );
    };

    $Log->exit() if $may_exit;
}

1;