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

## @summary VserverCifsShareProperties task module
## @author dl-nacl-dev@netapp.com
## @status shared
## @pod here

=head1 NAME

NACL::STask::VserverCifsShareProperties

=head1 DESCRIPTION

C<NACL::STask::VserverCifsShareProperties> provides a number
 of methods related to CIFS Shares properties.

It builds on top of and is a derived class of
 C<NACL::C::VserverCifsShareProperties>.
This means that any functionality present in
L<NACL::C::VserverCifsShareProperties|lib-NACL-C-VserverCifsShareProperties-pm>
will also be present in this STask object. (functionality which is multi-step
will have overridden implementations defined here,
single step functionality will be directly re-used
from the component)

=head1 ATTRIBUTES

=head2 command_interface

(Required)

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

=head2 share-name

(Required)

The name of the share. 

=head2 vserver

(Required)

The name of the vserver on which this share exists. 

=head2 share-properties

(Required)

The share-properties which is added to the share. 

=head1 EXCEPTIONS

    1. NACL::Exceptions::VerifyFailure
      (This type of exception is thrown when verification fails for the
       added/removed CIFS shares properties.)

=cut

package NACL::STask::VserverCifsShareProperties;

use strict;
use warnings;

use base qw(NACL::C::VserverCifsShareProperties NACL::STask::STask);
use NATE::Log qw(log_global);
use Params::Validate
    qw(validate validate_with SCALAR OBJECT ARRAYREF BOOLEAN HASHREF);
use NATE::BaseException qw(:try);
use NACL::Exceptions::NoElementsFound;
use NACL::STask::_Mixins::CifsConfigReplayUtils qw(wait_for_cifs_share_replay);
use NACL::ComponentUtils qw(Dumper);

use Class::MethodMaker [scalar => 'share_properties',];
my $Log = log_global();
my $may_enter = $Log->may_enter();
my $may_exit  = $Log->may_exit();

=head1 METHODS

=head2 add

    my $share_obj = NACL::STask::VserverCifsShareProperties->add(
        command_interface   => $ci,
        vserver             => $vserver,
        "share-name"        => $share_name,
        "share-properties"  => \@properties,
        nacltask_verify     => 1,
    );

(Class method)
This method is required to add the share-properties to the cifs-shares created
for the vserver. This method will wait for the replay to be done using 
"diag nblade replay show" command to check for the property changes 
to take place.
The nacltask_if_exists support cannot be given for this STask as there no
error message returned when the existent share-properties is again added to the
cifs shares of the vserver.

=over

=item Options

=over

=item C<<command_interface => $ci>>

(Required) This contains the <NACL::C::CommandInterface::ONTAP> type of object
of the filer on which the share properties command.

=item C<<vserver => $vserver>>

(Required) The vserver on which the cifs share resides.

=item C<< "share-name" => $share_name >>

(Required) The share-name of the CIFS share for which we need to change 
the properties.

=item C<< "share-properties" => \@properties >>

(Required,ArrayRef) The option contains a array reference of values which are 
the properties to be added for share.

=item C<< "nacltask_verify" => $verify >>

(Optional,Boolean) This option is used to verify the properties are added to
cifs-shares. If the value is 1, the verification is done. If its 0, the 
verification is skipped. Defaults to 1.

=item C<< nacltask_replay_timeout => $val >>

(Optional, SCALAR)

The total timeout before complaining that the replay didn't succeed.
In order for this wait not to happen, timeout can be specified as 0.
The default value is 30 seconds.
This is for waiting for the config change to be replayed to the nblade.

=item C<< nacltask_replay_interval => $val >>

(Optional, SCALAR)

The interval between two invocations of diag nblade replay show.
The default value is 5 seconds. Applicable only if the nacltask_replay_timeout
value is greater than 0.

=item Other options

All of the options accepted by L<NACL::C::VserverCifsShareProperties::create|
lib-NACL-C-VserverCifsShareProperties-pm/create> are accepted by this method.

=back

=back

=over

=item Exceptions

=over

=item C<NACL::Exceptions::VerifyFailure>

This type of exception is thrown when verification fails for the added CIFS
shares properties.

=back

=back

=cut

sub add {
    $Log->enter() if $may_enter;
    my ($pkg, @args) = @_;

    my %opts = $pkg->_common_validate_with(
        params          => \@args,
        additional_spec => {
            nacltask_verify          => {type => SCALAR, default  => 1},
            nacltask_replay_timeout  => {type => SCALAR, optional => 1},
            nacltask_replay_interval => {type => SCALAR, optional => 1},
        },
        allow_extra => 1,
    );

    my $self;
    my %common_opts;
    $pkg->_copy_common_component_params(
        source => \%opts,
        target => \%common_opts
    );

    my %nacltask_options = ();
    $pkg->_move_nacltask_options(
        source => \%opts,
        target => \%nacltask_options,
    );

    my $verify = delete $nacltask_options{nacltask_verify};

    #share-properties addition
    $pkg->SUPER::add(%opts,%common_opts);

    #check for replay of changes to happen in the dblade
    $pkg->wait_for_cifs_share_replay(%opts, %common_opts, %nacltask_options,
        method_action => 'add');

    $pkg->verify_state(%opts,%common_opts) if ($verify);

    $self = $pkg->new(
        command_interface  => $opts{command_interface},
        vserver            => $opts{vserver},
        'share-name'       => $opts{'share-name'},
        'share-properties' => $opts{'share-properties'},
    );

    $Log->exit() if $may_exit;
    return $self;
} ## end sub add

=head2 remove

    NACL::STask::VserverCifsShareProperties->remove(
        command_interface   => $command_interface,
        vserver             => $vserver,
        "share-name"        => $share_name,
        "share-properties"  => \@properties,
        nacltask_verify     => 1,
    );

    (or)

    $VserverCifsShareProperties_obj->remove();

(Class or Instance method)
Removes a share-properties for the particular vserver cifs share.
If the removal of the share-properties needs to be verified we
need to pass nacltask_verify as 1.
This method will wait for the replay to be done using "diag nblade replay show"
command to check for the property changes to take place.

=over

=item Options

=over

=item C<< vserver => $vserver >>

(Required for Class call, Not Applicable for Instance call)
Name of the vserver on which the CIFS share resides.

=item C<< share-name => $share_name >>

(Required for Class call, Not Applicable for Instance call)
Name of the cifs share.

=item C<< share-properties => \@properties >>

(Required for Class call, Not Applicable for Instance call)
Array reference containing the share-properties which needs to be deleted.

=item C<< nacltask_replay_timeout => $val >>

(Optional, SCALAR)

The total timeout before complaining that the replay didn't succeed.
In order for this wait not to happen, timeout can be specified as 0.
The default value is 30 seconds.
This is for waiting for the config change to be replayed to the nblade.
This can be skipped by sending in the value as 0.

=item C<< nacltask_replay_interval => $val >>

(Optional, SCALAR)

The interval between two invocations of diag nblade replay show.
The default value is 5 seconds. Applicable only if the nacltask_replay_timeout
value is greater than 0.

=item C<< nacltask_verify >>

(Optional) - when set to 1, share-properties removal will be verified.
             The verification will check whether the properties are removed
             completely from the table entries using 
             <NACL::C::VserverCifsShareProperties->find()> method.
           - when set to 0, the verification step is skipped.
           - by default its set to 1.

All of the other parameters accepted by
L<NACL::C::VserverCifsShareProperties::delete|
lib-NACL-C-VserverCifsShareProperties-pm/delete> are accepted by this method.

=back

=back

=over

=item Exceptions

=over

=item C<NACL::Exceptions::VerifyFailure>

This type of exception is thrown when verification fails for the removed CIFS
shares properties.

=back

=back

=cut

sub remove {
    $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 => SCALAR, default  => 1},
            nacltask_replay_timeout  => {type => SCALAR, optional => 1},
            nacltask_replay_interval => {type => SCALAR, optional => 1},
        },
        allow_extra => 1,
    );

    my %nacltask_options = ();
    $pkg_or_obj->_move_nacltask_options(
        source => \%opts,
        target => \%nacltask_options
    );

    my %common_opts;
    $pkg_or_obj->_copy_common_component_params(
        source => \%opts,
        target => \%common_opts
    );

    $opts{'share-properties'} ||= $pkg_or_obj->share_properties();
    my $verify = delete $nacltask_options{nacltask_verify};

    $pkg_or_obj->SUPER::remove(%opts,%common_opts);
    $pkg_or_obj->wait_for_cifs_share_replay(%opts, %common_opts,
        %nacltask_options, method_action => 'remove');

    $pkg_or_obj->
        _taskverify_remove_share_properties(%opts,%common_opts) if ($verify);
    $Log->exit() if $may_exit;
    return;
} ## end sub remove

sub _taskverify_remove_share_properties {

    $Log->enter() if $may_enter;
    my ($pkg_or_obj, %opts) = @_;

    my $command_interface = $opts{command_interface}
        || $pkg_or_obj->command_interface();
    my $share_properties = $opts{'share-properties'}
        || $pkg_or_obj->share_properties();
    my $vserver    = $opts{'vserver'}    || $pkg_or_obj->vserver();
    my $share_name = $opts{'share-name'} || $pkg_or_obj->share_name();
    my $pkg_name   = ref $pkg_or_obj     || $pkg_or_obj;

    my %common_opts;
    $pkg_or_obj->_copy_common_component_params(
        source => \%opts,
        target => \%common_opts
    );

    try {
        $pkg_name->find(
            command_interface => $command_interface,
            filter            => {
                'vserver'          => $vserver,
                'share-properties' => $share_properties,
                'share-name'       => $share_name,
            },
            %common_opts,
        );

        $Log->exit() if $may_exit;
        NACL::Exceptions::VerifyFailure->throw('Verification of removal '
            . ' of share-properties failed. The properties are still present'
        );
    }
    catch NACL::Exceptions::NoElementsFound with {
        $Log->debug('Share-properties are removed successfully');
    };

    $Log->exit() if $may_exit;
    return;
} ## end sub _taskverify_remove_share_properties

1;