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

## @summary VserverVscanOnDemandTask Task Module
## @author roopeshw@netapp.com, dl-nacl-dev
## @status shared
## @pod here

=head1 NAME

NACL::STask::VserverVscanOnDemandTask

=head1 DESCRIPTION

C<NACL::STask::VserverVscanOnDemandTask> provide methods to create,
purge,abort,run,schedule,unschedule,pause,resume,modify and show 
vserver vscan On-Demand Task in ONTAP.

It is created on top of C<NACL::C::VserverVscanOnDemandTask> component
Since it is derived class of C<NACL::C::VserverVscanOnDemandTask>,
we can use all the methods of C<NACL::C::VserverVscanOnDemandTask>
from the object of this task.

=head1 ATTRIBUTES

=head2 command_interface

(Required) A component object that represents the host to which to send commands
See L<NACL::C::Component::command_interface|lib-NACL-C-Component-pm/command_interface>.

=head2 vserver

(Required) The name of the Vserver to be used

=head2 task_name

(Required) The name of the task to be added.

=head2 scan_paths

(Required) Comma separated paths of the directory which need to be scanned.
 The path must be provided in unix-format and from the root of the Vserver.
 
=head2 report_directory

(Required) Path from the vserver root where task report need to be created.
 
=head1 METHODS

=head2 create

  my $OnDemandTask = NACL::STask::VserverVscanOnDemandTask->create(
                                   command_interface => $ci,
                                   'vserver' => $vserver,
								   'task-name'   => $task_name,
                                   'scan-paths'   => [$scan_paths1,$scan_path2,$scan_path3,...],
                                   'report-directory' => $report_directory,
                                   'nacltask_if_exists' => $action # default die
                                   %other_options,
                    );

(Class or Instance Method) This method is used to create the on-demand task.
If on-demand task already exists, it will perform the action based on
"nacltask_if_exists" parameter. Default behavior would be "die".

Uses CMode CLI/ZAPI.

=over

=item Options

=over

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

(Required for class method, Not Applicable for instance method)
See L<NACL::C::Component|lib-NACL-C-Component-pm/command_interface>

=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<< 'vserver' => $vserver >>

(Required for class method, Not Applicable for instance method)
The name of the Vserver to be used

=item C<< 'task-name' => $task_name >>

(Required for class method, Not Applicable for instance method)
Task name to be created.

=item C<< 'scan-paths' => $scan_paths >>

(Required for class method, Not Applicable for instance method)
Comma separated list of path of the directory which need to be scanned. 

=item C<< 'report-directory' => $report_directory >>

(Required for class method, Not Applicable for instance method)
Path where task report need to be created.


=item C<< 'nacltask_verify' => $nacltask_verify_boolean >>

(Optional)
If '0' (default), verification will not be performed.
If '1', verification will be performed to ensure that the addition did happen
successfully.


=item C<< "nacltask_if_exists => $action" >>

(Optional) What to do if the policy to be added already exists.
If $action is "die", then fail with an exception. If action is
"purge", then purge the policy(see the "purge" method, below)
before creating a new one. If $action is "reuse", It will return
the object of existing policy.

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

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

my $was_created;

my $ondemandtask_obj = NACL::STask::VserverVscanOnDemandTask->create(
                        $nacltask_if_exists     => 'reuse',
                        _was_created            => \$was_created,
                        %other_opts
                    );

# Operate on $ondemandtask_obj here
# ...
# Now determine whether to clean up the task, since we're not sure
# whether we reused an existing task or added a new one
if ($was_created) {
   # New task was added. Clean it up.
   $ondemandtak_obj->purge();
}

Supports all of the other various options to
NACL::C::VserverVscanOnDemandTask->create

L<< NACL::C::VserverVscanOnDemandTask->create|
lib-NACL-C-VserverVscanOnDemandTask-pm/create >>

=back

=back

=over

=item Exceptions

=over

=item C<NACL::C::Exceptions::VserverVscanOnDemandTask::AlreadyExists>

This type of exception is thrown when an attempt is made to create vserver vscan on-demand task that already exists.

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

This type of exception is thrown when verification fails for the added vserver vscan on-demand task.

=back

=back

=cut

package NACL::STask::VserverVscanOnDemandTask;

use strict;
use warnings;
use base qw(NACL::C::VserverVscanOnDemandTask NACL::STask::STask);
use Params::Validate
  qw(validate validate_with SCALAR SCALARREF ARRAYREF BOOLEAN );
use NATE::Log qw(log_global);
my $Log = log_global();
my $may_enter = $Log->may_enter();
my $may_exit  = $Log->may_exit();
use NATE::Exceptions::Argument qw(:try);
use NATE::BaseException;
use NACL::C::Component;
use NACL::C::Exceptions::VserverVscanOnDemandTask::AlreadyScheduled qw(:try);
use Array::Utils qw(:all);

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

    if (defined($opts{'file-ext-to-exclude'})) {
        # w.r.t burt948009, except for field 'file-ext-to-exclude'
        # other fields will be verified
        # using _generic_create_modify_verify

        my $ci = $opts{command_interface};
        my $obj = NACL::CS::VserverVscanOnDemandTask->fetch(
            'command_interface' => $ci,
            requested_fields => [qw( file-ext-to-exclude )],
            filter => {'vserver' => $opts{vserver} }
        );
        my @files_fetch_opts = $obj->file_ext_to_exclude();
        my @files_create_opts = @{$opts{'file-ext-to-exclude'}};

           ## fetch obj will have value in ""
        my @fetch_opts;
        map {my $str = $_ ; $str =~ s/\"//g ; push @fetch_opts , $str;} @files_fetch_opts ;

        my $err_msg;
        if(array_diff(@fetch_opts,@files_create_opts)){
            $err_msg = "file-ext-to-exclude field does not match";
        }

        delete($opts{'file-ext-to-exclude'}) if (defined $opts{'file-ext-to-exclude'});

        try{
            $pkg_or_obj->_generic_create_modify_verify(%opts);
        }catch NACL::Exceptions::VerifyFailure with{
            my $e = shift;
            my $err_text = $e->text() . " ". $err_msg;
            $e->throw($err_text);
        };
    } else {
        $pkg_or_obj->_generic_create_modify_verify(%opts);
    }
    $Log->exit() if $may_exit;
}


__PACKAGE__->create_method_builder();

=head2 purge

    $Ondemandtask_obj->purge();
            (or)
    NACL::STask::VserverVscanOnDemandTask->purge(
            'command_interface' => $ci,
            'vserver'           => $vserver_name,
            'task-name'         => $task_name,
            'nacltask_verify'   => 1,
    );

(Class or instance method)
This method is used to purge a vserver vscan on-demand task.
Uses a CMode CLI/ZAPI APISet.

=over

=item Options

=over

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

(Required for class method, Not Applicable for instance method)
A component object that represents the host which to send commands.
See NACL::C::Component::command_interface

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

(Required for class method, Not Applicable for instance method)
 The name of the vserver.

=item C<< 'task-name' => $task_name >>

(Required for class method, Not Applicable for instance method)
The on-demand task name to be deleted.

=item C<< 'nacltask_verify' => $nacltask_verify_boolean >>

(Optional)
If '0' (default), verification will not be performed.
If '1', verification will be performed to ensure that the deletion did happen
successfully.

=item C<< nacltask_if_purged => $nacltask_if_purged >>

(Optional)
If 'pass' (default), It will pass if the policy task is already deleted.
If 'fail', It will fail if the policy task is already deleted.

Supports all of the other various options to
NACL::C::VserverVscanOnDemandTask->delete

L<< NACL::C::VserverVscanOnDemandTask->delete|
lib-NACL-C-VserverVscanOnDemandTask-pm/delete >>

=back

=back

=over

=item Exceptions

=over

=item C<NACL::C::Exceptions::VserverVscanOnDemandTask::DoesNotExist>

This type of exception is thrown when an attempt is made to delete vserver vscan on-demand task that does not exists.

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

This type of exception is thrown when verification fails for the deleted vserver vscan on-demand task.

=back

=back

=cut

__PACKAGE__->purge_method_builder();

=head2 modify
  
(Class or instance method)
This method is used to modify the scanner pool. "nacltask_verify"
parameter can be set to ensure all the attributes got a specified value.
And also provides an mechanism of cleanup for the objects that are modified
by this method.

=over

=item Options

=over

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

(Required for class method, Not Applicable for instance method)
A component object that represents the host which to send commands.
See L<NACL::C::Component::command_interface
  |lib-NACL-C-Component-pm/command_interface>.

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

(Optional, defaults to 0)
Verifies whether all of the attributes got set to the specified value.

Note that it is also possible to perform the verification later by calling
L<taskverify_modify|lib-NACL-STask-STask-pm/taskverify_modify>. This can
be used for cases where ONTAP chooses to not set all attributes to the exact
values specified. In the call we can specify those attributes we want
verified.

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

(Optional, default to 0(no to cleanup)
Flag indicating if this operation needs to be registered for clean up or not.

=item C<< nacltask_cleanup_manager >>

Cleanup manager to be used for registering.
Default : Will use the default cleanup manager.

=item other options

See L<NACL::C::VserverVscanOnDemandTask::modify
|lib-NACL-C-VserverVscanOnDemandTask-pm/modify> for all the other options
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 modified
on demand task.

=back

=back

=cut

__PACKAGE__->modify_method_builder();
__PACKAGE__->create_method_builder(
    stask_method_name => 'unschedule',
    c_method_name     => 'unschedule',
    c_exception_name  => 'DoesNotExist',
);

=head2 schedule

  NACL::STask::VserverVscanOnDemand->schedule(
      command_interface => $command_interface,
	  'task-name'       => $Task_name,
      schedule          => $schedule,
      nacltask_verify   => 0|1 # defaults to 0,
      %other_options
  );

(Class method) This method is used to schedule On-Demand Scan. Also verify that
the on-demand command has been scheduled if C<nacltask_verify> is set to 1.

=over 

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

(Optional, defaults to 0)
When set to 1, the on-demand schedule is verified.
When set to 0, verification is not performed.

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

(Optional, defaults to "die")
This arguments specifies what should be done if the scan has already
been scheduled. "pass" means that the exception should be suppressed,
a value of "die" will result in the exception being propagated.

=item other options

See
L<NACL::C::VserverVscanOnDemand->schedule|lib-NACL-C-VserverVscanOnDemand-pm/schedule> for
all the other options accepted by this method.

=back

=over

=item Exceptions

=over

=item C<NACL::C::Exceptions::VserverVscanOnDemand::AlreadyScheduled>

This type of exception is thrown when an attempt is made to schedule vscan ondemand when it is already scheduled.

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

This type of exception is thrown when verification fails to find any scheduled vscan ondemand command.

=back

=cut

sub schedule {
    $Log->enter() if $may_enter;
    my $pkg_or_obj = shift;
    my %opts       = $pkg_or_obj->_common_validate_with(
        params          => \@_,
        additional_spec => {
            nacltask_verify => { type => SCALAR, default => 0 },
            nacltask_if_scheduled =>
              $pkg_or_obj->_if_action_completed_already_validate_spec(
                name => 'nacltask_if_scheduled'
              ),
            $pkg_or_obj->_cleanup_validate_spec(),
        },
        allow_extra => 1
    );

    #Transform %opts from the options we received into the options to
    #pass to the base class method.
    my (
        %nacltask_opts,     %opts_for_cleanup, $nacltask_to_cleanup,
        $opts_for_register, $register_for_cleanup
    );

    $pkg_or_obj->_move_common_cleanup_opts(
        source              => \%opts,
        target              => \%opts_for_cleanup,
        nacltask_to_cleanup => \$register_for_cleanup
    );

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

    my $verify       = $nacltask_opts{'nacltask_verify'};
    my $if_scheduled = $nacltask_opts{'nacltask_if_scheduled'};

    $opts_for_register =
      $pkg_or_obj->_common_modify_for_cleanup( %opts_for_cleanup, %opts )
      if ($register_for_cleanup);

    try {
        $pkg_or_obj->SUPER::schedule(%opts);
    }
    catch NACL::C::Exceptions::VserverVscanOnDemandTask::AlreadyScheduled with {
        my $exception = shift;
        if ( $if_scheduled =~ /die/i ) {
            $Log->exit() if $may_exit;
            $exception->throw();
        }
    };

    # Verification based on the nacltask_opts
    $pkg_or_obj->verify_state(%opts) if ($verify);
    $pkg_or_obj->_register_for_cleanup( %{$opts_for_register} )
      if ($register_for_cleanup);
    $Log->exit() if $may_exit;
    return;
} ## end sub schedule

=head2 run

  NACL::STask::VserverVscanOnDemand->run(
      command_interface => $command_interface,
      'task-name'       => $Task_name,
      nacltask_verify   => 0|1 # defaults to 0,
      %other_options
  );


(Class method) This method is used to run On-Demand Scan. Also verify that
 the on-demand command has started the run if C<nacltask_verify> is set to 1.

=over

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

(Optional, defaults to 0)
When set to 1, the on-demand run is verified.
When set to 0, verification is not performed.

=item other options

See L<NACL::C::VserverVscanOnDemand->run|lib-NACL-C-VserverVscanOnDemand-pm/run>
for all the other options accepted by this method.

=back

=over

=item Exceptions

=over

=item C<NACL::APISet::Exceptions::CommandFailedException>

This type of exception is thrown when an attempt is made to delete vscan ondemand report.

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

This type of exception is thrown when verification fails to find any vscan on-demand report.

=back

=cut

sub run {
    $Log->enter() if $may_enter;
    my $pkg  = shift;
    my %opts = $pkg->_common_validate_with(
        params          => \@_,
        additional_spec => {
            nacltask_verify => { type => SCALAR, default => 0 },
            nacltask_wait   => { type => SCALAR, default => 0 },
        },
        allow_extra => 1,
    );

    my %nacltask_opts;

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

    my $verify = $nacltask_opts{'nacltask_verify'};
    my $wait   = $nacltask_opts{'nacltask_wait'};
    my $job_component;

    $pkg->SUPER::run( %opts, job_component => \$job_component );

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

    if ( $job_component && $wait ) {
        my %common_opts;
        $pkg->_copy_common_component_params(
            source => \%opts,
            target => \%common_opts
        );
        $job_component->wait_on_job(%common_opts);
    }

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

=head2 unschedule

  NACL::STask::VserverVscanOnDemand->unschedule(
      command_interface => $command_interface,
      vserver           => $vs_name,
      'task-name'       => $Task_name,
      nacltask_wait     => 0|1 # defaults to 1,
      %other_options
  );


(Class method) This method is used to unschedule On-Demand Scan. Defaults
to waiting for the scan to be unscheduled.

=over

=item Options

=over

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

(Optional, defaults to 1)
When set to 1 waits for the scan to be unscheduled.

It is also possible to wait later by invoking the L<wait_for_unschedule>
method.

=item other options

See
L<NACL::C::VserverVscanOnDemand->schedule|lib-NACL-C-VserverVscanOnDemand-pm/schedule> for
all the other options accepted by this method.

=back

=back

=cut

1;