# $Id: //depot/prod/test/nacldev/lib/NACL/STask/SystemServicesFirewallPolicy.pm# $
# Copyright (c) 2001-2013 NetApp, Inc., All Rights Reserved
# Any use, modification, or distribution is prohibited
# without prior written consent from NetApp, Inc.
#

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

package NACL::STask::SystemServicesFirewallPolicy;

use strict;
use warnings;

use base qw(NACL::C::SystemServicesFirewallPolicy 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 validate_with SCALAR SCALARREF OBJECT HASHREF BOOLEAN ARRAYREF);

use NATE::Exceptions::Argument qw(:try);
use NATE::BaseException                         ();
use NACL::APISet::Exceptions::ResponseException ();

use NACL::C::Exceptions::SystemServicesFirewallPolicy::AlreadyExists ;
use NACL::C::Exceptions::SystemServicesFirewallPolicy::DoesNotExist ;

=head1 NAME

NACL::STask::SystemServicesFirewallPolicy

=head1 DESCRIPTION

C<NACL::STask::SystemServicesFirewallPolicy> provide methods to create, purge
firewall policy in ONTAP.

It is created on top of C<NACL::C::SystemServicesFirewallPolicy> component.
Since it is derived class of C<NACL::C::SystemServicesFirewallPolicy>, we can use all the
methods of C<NACL::C::SystemServicesFirewallPolicy> 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 policy

(Required) The name of the firewall policy to be created.

=head1 METHODS

=head2 create

   ## Call for pre-FS builds
   my $SystemServicesFirewallPolicy = NACL::STask::SystemServicesFirewallPolicy->create(
                                  command_interface => $ci,
                                  policy            => $policy,
                                  action            => $action,
                                  service           => $service,
                               );

   ## Call for FS onwards
   my $SystemServicesFirewallPolicy_object = NACL::STask::SystemServicesFirewallPolicy->create(
                                  command_interface => $ci,
                                   policy => $policy,
                                   service => $service,
                                   vserver =>$vserver
                                  ...);


(Class Method) This method is used to create firewall policy for given application.
If policy exists, it will perform the action based on "nacltask_if_exists" parameter.
Default behaviour would be "die".

It supports only CMode.

=over

=item Options

=over

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

(Required) See L<NACL::C::Component|lib-NACL-C-Component-pm/command_interface>

=item C<< "policy" => $policy >>

(Required) Firewall Policy Name.

=item C<< 'vserver' => $string >>

Required for FS onwards, Not Applicable pre-FS

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

Required for pre-FS builds, Not Applicable for FS onwards

(Required) Specifies the action to be performed. It will be either allow or deny.

=item C<< "service" => $service >>

(Required) Services on which firewall policy is associated.

=item C<< "ip-list" => [ $ip-list1, $ip-list2, ... ] >>

(Optional) Server IP list . By default , it will match for all, ie 0.0.0.0/0.
           Arrayref, even if only a single value is to be sent it should
           specified as an arrayref containing that single value.

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

(Optional) What to do if the policy to be created already exists.
If $action is "die", then fail with an exception. If action is
"purge", then purge the firewall 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<< "nacltask_verify => $action" >>

(Optional) The user of this library can specify to verify whether the firewall
policy is created or not. If the action is 0, which is default, it wont
verify the creation. If the user sets the action to 1, it will verify
using the component state of this library.

command_interface, apiset_must, apiset_should, mode, etc. All of
the other various options supported by
L<< NACL::C::SystemServicesFirewallPolicy->create| lib-NACL-C-SystemServicesFirewallPolicy-pm/create >>

=back

=over

=item Exceptions

=over

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

This type of exception is thrown when an attempt is made to create SystemServicesFirewallPolicy that already exists.

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

This type of exception is thrown when verification fails for the created firewall policy.

=back

=cut

sub create {
    $Log->enter() if $may_enter;
    my $pkg = shift;

    my %opts = $pkg->_common_validate_with(
        params          => \@_,
        additional_spec => {
            nacltask_if_exists => $pkg->_if_exists_validate_spec(),
            nacltask_verify    => { type => SCALAR, default => 0 },
            _was_created       => { type => SCALARREF, optional => 1 },
        },
        allow_extra => 1,
    );
    # Transform %opts from the options we received into the options to
    # pass to the base class method.
    my ( $self, %common_opts, %nacltask_opts );
    $pkg->_copy_common_component_params_with_ci(
        source => \%opts,
        target => \%common_opts
    );
    $pkg->_move_nacltask_options(
        source => \%opts,
        target => \%nacltask_opts
    );

    my $was_created        = delete $opts{_was_created};
    my $nacltask_if_exists = delete $nacltask_opts{nacltask_if_exists};
    my $nacltask_verify    = delete $nacltask_opts{nacltask_verify};

  CREATE: {
        use warnings;
        try {
            $self         = $pkg->SUPER::create(%opts);
            $$was_created = 1;
        }
        catch NACL::C::Exceptions::SystemServicesFirewallPolicy::AlreadyExists with {
                my $exception = shift;
                $self = $pkg->_element_exists_handler(
                    create_opts        => \%opts,
                    nacltask_if_exists => $nacltask_if_exists,
                    exception          => $exception
                );
                if ( !$self ) {
                    no warnings qw(exiting);
                    redo CREATE;
                }
       };
    }
    if ($nacltask_verify) {
        $pkg->verify_state(%opts);
    }
    $Log->exit() if $may_exit;
    return $self;

} ## end sub create

=head2 purge

    $SystemServicesFirewallPolicy->purge();

            (or)
    ## Call for pre-FS builds 
    NACL::STask::SystemServicesFirewallPolicy->purge(
              'command_interface'=> $ci,
               policy            => $policy,
               action            => $action,
               service           => $service,
    );

    ## Call for FS onwards
    NACL::STask::SystemServicesFirewallPolicy->purge(
                      'command_interface'=> $ci,
                       policy            => $policy,
                       vserver           => $vserver,
                       service           => $service,
    );

(Class or instance method)
This method is used to delete the specified firewall policy.
It supports only CMode.

=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<< "policy" => $policy >>

(Required) Firewall Policy Name.

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

Required for pre-FS builds, Not Applicable for FS onwards
(Required) Specifies the action to be performed. It will be either allow or deny.

=item C<< 'vserver' => $string >>

Required for FS onwards, Not Applicable pre-FS

=item C<< "service" => $service >>

(Required) Services on which firewall policy is associated.

=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 descriptor is already deleted.
If 'fail', It will fail if the descriptor is already deleted.

=back

=over

=item Exceptions

=over

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

This type of exception is thrown when an attempt is made to delete SystemServicesFirewallPolicy that does not exists.

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

This type of exception is thrown when verification fails for the deleted firewall policy.

=back

=cut

sub purge {
    $Log->enter() if $may_enter;
    my $pkg_or_obj      = shift;
    my %orig_opts       = @_;
    my $additional_spec = {
        nacltask_verify    => { type => BOOLEAN, default => 0 },
        nacltask_if_purged => { type => BOOLEAN, default => 'die' },
    };

    # Throw away options specific to the task
    $pkg_or_obj->_hash_move(
        source => \%orig_opts,
        target => {},
        move   => [ keys %{$additional_spec} ]
    );
    my %opts = $pkg_or_obj->_common_validate_with(
        params          => \@_,
        additional_spec => $additional_spec,
    );

    my %common_opts;
    $pkg_or_obj->_copy_common_component_params_with_ci(
        source => \%opts,
        target => \%common_opts
    );
    my $if_purged = delete $opts{nacltask_if_purged};
    try {
        $pkg_or_obj->SUPER::delete( %common_opts, %orig_opts );
    }
    catch NACL::C::Exceptions::SystemServicesFirewallPolicy::DoesNotExist with {
        my $exception = shift;
        if ( $if_purged !~ /pass/i ) {
            $Log->exit() if $may_exit;
            $exception->throw();
        }
    };
    if ( $opts{nacltask_verify} ) {
        $pkg_or_obj->_generic_purge_verify(%orig_opts);
    }
    $Log->exit() if $may_exit;
}

1;