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

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

package NACL::STask::VserverServicesDns;

use strict;
use warnings;

use base qw(NACL::C::VserverServicesDns 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 NACL::STask::_VserverServices qw(:all !_replay_check);
use NACL::APISet::Exceptions::CommandFailedException qw(:try);
use NACL::C::VserverServicesNameServiceGetxxbyyy;
use Params::Validate qw(ARRAYREF);

=head1 NAME

NACL::STask::VserverServicesDns

=head1 DESCRIPTION

C<NACL::STask::VserverServicesDns> provide methods to create,
purge vserver services dns in ONTAP.

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

=head1 CLEANUP METHODS

Cleanup can be registered for the following methods, '_create_helper'.

Cleanup methods are,
     VserverServicesDns  Method         Cleanup Method
    -----------------------------------------------
     create                             purge

=head1 ATTRIBUTES

=head2 command_interface

(Required) A component object that represents the node 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.

=head1 METHODS

=head2 create

   my $dns_obj = NACL::STask::VserverServicesDns->create(
       'command_interface'  => $ci,
       'vserver'            => $vserver,
       domains              => \@DomainList,
       'name-servers'       => \@ServerList,
       state                => 'enabled',
       'nacltask_if_exists' => $action # default die
       'nacltask_to_cleanup'      => 1, #default 0
       'nacltask_cleanup_manager' => $CleanupObj,
       %other_options,
  );

(Class Method) This method is used to configure DNS on the particular vserver.
If DNS service already exists, it will perform the action based on
"nacltask_if_exists" parameter. Default behavior would be "die".

=over

=item Options

=over

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

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

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

(Required) Name of the vserver to be used.

=item C<< "domains" => [ $domain1, $domain2, ... ] >>

(Required,Arrayref) The DNS domain names which needs to be configured for the vserver.

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

(Optional) What to do if the DNS to be configured already exists.
If $action is "die", then fail with NACL::C::Exceptions::VserverServicesDns::AlreadyExists.
If $action is "purge", then purge the DNS configuration(see the "purge" method below)
before creating a new one.
If $action is "reuse", It will return the object of existing DNS configuration for the vserver.

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

(Optional) The user of this library can specify to verify whether the DNS is configured or not.
If the action is 0, which is default, verification is not done.
If the user sets the action to 1, it will verify it using the component state of this library.

=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 DNS was available (value will be 0; this
scenario is possible when if_exists => "reuse") or whether the
DNS was created (value will be 1). This is necessary to
determine whether the DNS configuration needs to be cleaned up later.

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

=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 C<MCC options>

The options accepted for MCC configuration replication verification is
documented at L<MCC options|lib-NACL-STask-STask-pm/mcc_options>.

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

=back

=back

=over

=item Exceptions

=over

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

This type of exception is thrown when an attempt is made to configure DNS on a given vserver when it already exists.

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

This type of exception is thrown when verification fails for the DNS configured on a given vserver.

=back

=back

=cut

sub create {
    $Log->enter() if $may_enter;
    my $pkg = shift;
    my $self = $pkg->_create_helper(@_);
    $Log->exit() if $may_exit;
    return $self;
} ## end sub create

=head2 purge

    $Dns_obj->purge();
            (or)
    NACL::STask::VserverServicesDns->purge(
            'command_interface' => $ci,
            'vserver'           => $vserver_name,
            domains             => \@DomainList,
            'name-servers'      => \@ServerList,
            'nacltask_verify'   => 1,
    );

(Class or instance method)
This method is used to remove DNS configured for a particular vserver.

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

(Required for class method, Not Applicable for instance method)
Name of the vserver to be used.

=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) Default value is 'fail'.
If 'pass', It will pass if the DNS configuration is already deleted.
If 'fail', NACL::C::Exceptions::VserverServicesDns::DoesNotExist type of exception is raised.

=item C<MCC options>

The options accepted for MCC configuration replication verification is
documented at L<MCC options|lib-NACL-STask-STask-pm/mcc_options>.

All of the other various options,
See L<< NACL::C::VserverServicesDns::delete|lib-NACL-C-VserverServicesDns-pm/delete >>

=back

=back

=over

=item Exceptions

=over

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

This type of exception is thrown when an attempt is made to delete DNS configuration on a given vserver whch does not exists.

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

This type of exception is thrown when verification fails for the deleted DNS configuration.

=back

=back

=cut

sub purge {
    $Log->enter() if $may_enter;
    my $pkg_or_obj = shift;
    $pkg_or_obj->_purge_helper(@_);
    $Log->exit() if $may_exit;
} ## end sub purge

#
# _replay_check: supporting method called by _VserverServices.
# Method to check if command replayed to secd.
#
sub _replay_check {
    $Log->enter() if $may_enter;
    my ( $pkg_or_obj, @args ) = @_;

    my %opts = $pkg_or_obj->_common_validate_with(
        params          => \@args,
        additional_spec => {'domains' => {type => ARRAYREF},}
    );

    my %common_params;
    $pkg_or_obj->_copy_common_component_params_with_ci(
        source => \%opts,
        target => \%common_params
    );

    my $domains = $opts{domains};
    # need to resolve any one.
    my $resolved = 0;
    my $exp;
    foreach my $domain (@$domains) {
        try {
            NACL::C::VserverServicesNameServiceGetxxbyyy->getaddrinfo(
                vserver => $opts{vserver},
                node    => 'local',
                hostname => $domain,
                %common_params,
            );
            # at least one entry got resolved
            $resolved = 1;
        } catch NACL::APISet::Exceptions::CommandFailedException with {
            $exp = shift;
            if ($exp->text() =~ /Failed to resolve|hostname nor servname provided, or not known/) {
            } else {
                $Log->exit() if $may_exit;
                $exp->throw();
            }
        };
        if ($resolved) {
            last;
        }
    }

    if (!$resolved) {
        $exp->set_text("Failed to resolve any of (@$domains) domains...\n".
                "Original error:\n" . $exp->text());
        $Log->exit() if $may_exit;
        $exp->throw();
    }
}
1;