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

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

package NACL::STask::VserverServicesLdap;

use strict;
use warnings;

use base qw(NACL::C::VserverServicesLdap 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);
use NACL::STask::VserverServicesLdapClient;
use Params::Validate qw( SCALAR );

use Class::MethodMaker [
    scalar => '_was_ldap_client_created',    #locally used
    scalar => [
        { -type => 'NACL::STask::VserverServicesLdapClient' },
        'ldapclient_stask_obj',
    ]
];

=head1 NAME

NACL::STask::VserverServicesLdap

=head1 DESCRIPTION

C<NACL::STask::VserverServicesLdap> provide methods to create & purge
vserver services ldap in ONTAP.

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

=head1 CLEANUP METHODS

Cleanup can be registered for the following methods

Cleanup methods are,


     VserverServicesLdap 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.

=head2 ldapclient_stask_obj

This parameter specifies NACL::STask::VserverServicesLdapClient object created as a prerequisite.

=head1 METHODS

=head2 create

   my $ldap_obj = NACL::STask::VserverServicesLdap->create(
        'command_interface'              => $ci,
        'client-config'                  => $Client_config,
        'client-enabled'                 => 'true',
        vserver                          => $TestVserver,
        servers                          => \@Servers,
        'nacltask_if_ldap_exists'        => $action, # default die
        'nacltask_if_ldap_client_exists' => $action, # default die
        'nacltask_to_cleanup'            => 1, #default 0
        'nacltask_cleanup_manager'       => $CleanupObj,
        %other_options,
    );

(Class Method) This method is used to configure LDAP on the particular vserver.
If LDAP service already exists, it will perform the action based on
"nacltask_if_ldap_exists" or "nacltask_if_ldap_client_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<< 'client-config' => $string >>

(Required) This parameter specifies the name of the LDAP client configuration
to associate with the LDAP configuration.

=item C<< 'client-enabled' => $string >>

(Required) This parameter specifies whether the LDAP client needs to enabled or not.

=item C<< servers => [ $server1 $server2 ..] >>

(Required,Arrayref) This parameter specifies the servers which are required to created the LDAP client.

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

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

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

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

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

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

   my $was_created;
   my $ldap_obj = NACL::STask::VserverServicesLdap->create(
                      nacltask_if_exists     => 'reuse',
                      _was_created            => \$was_created,
                      %other_opts
                  );
   # Operate on $ldap_obj here
   # Now determine whether to clean up the ldap, since we're not sure
   # whether we reused an existing ldap or created a new one

   if ($was_created) {
       # New LDAP configuration. Clean it up.
         $ldap_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>.

=back

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

=back

=over

=item Exceptions

=over

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

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

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

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

=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_ldap_exists => { type => SCALAR, default => "die" },
            nacltask_if_ldap_client_exists =>
                { type => SCALAR, default => "die" },
            $pkg->_cleanup_validate_spec(),
        },
        allow_extra => 1,
    );

    my ( %ldap_create_opts, %ldap_client_opts, %common_opts );
    my ($was_ldap_client_created);
    my ( %opts_for_cleanup, %opts_for_register, $nacltask_to_cleanup );

    $pkg->_copy_common_component_params_with_ci(
        source => \%opts,
        target => \%common_opts,
    );

    $pkg->_hash_copy(
        source => \%opts,
        target => \%ldap_create_opts,
        copy   => [qw( vserver client-config client-enabled )],
    );
    $pkg->_move_common_cleanup_opts(
         source  => \%opts,
         target  => \%opts_for_cleanup,
    );

    delete $opts{'client-enabled'};
    my $ldap_client_nacltask_if_exists
        = delete $opts{nacltask_if_ldap_client_exists};
    $ldap_create_opts{nacltask_if_exists}
        = delete $opts{nacltask_if_ldap_exists};

    my $ldap_client = NACL::STask::VserverServicesLdapClient->create(
        %common_opts,
        %opts,
        %opts_for_cleanup,
        nacltask_if_exists => $ldap_client_nacltask_if_exists,
        _was_created       => \$was_ldap_client_created,
    );

    my $self = $pkg->_create_helper( %common_opts, %ldap_create_opts,
        %opts_for_cleanup);
    if ($was_ldap_client_created) {
        $self->_was_ldap_client_created($was_ldap_client_created);
        $self->ldapclient_stask_obj($ldap_client);
    }

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

=head2 purge

    $Ldap_obj->purge();
            (or)
    NACL::STask::VserverServicesLdap->purge(
            'command_interface' => $ci,
            'vserver'           => $vserver_name,
            'client-config'     => $config,
            'nacltask_verify'   => 1,
    );

(Class or instance method)
This method is used to remove LDAP 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 NACL::C::Component::command_interface.

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

(Required for class method, Not Applicable for instance method)
Name of the vserver from which ldap services needs to be deleted.

=item C<< 'client-config' => $config >>

(Required for class method, Not Applicable for instance method)
Name of the LDAP client configuration which needs 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', It will pass if the LDAP configuration is already deleted.
If 'fail'(default), NACL::C::Exceptions::VserverServicesLdap::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>.

=back

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

=over

=item Exceptions

=back

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

This type of exception is thrown when an attempt is made to delete LDAP 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 LDAP configuration.

=back

=cut

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

    my %opts = $pkg_or_obj->_common_validate_with(
        params      => \@args,
        allow_extra => 1,
    );

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

    if ( $pkg_or_obj->_was_ldap_client_created() ) {
        $pkg_or_obj->{ldapclient_stask_obj}->purge();
    }

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


=head2 parents

    @parents = $vs_ldap_obj->parents();

( Class or Instance method ) This method returns the list containing the names of
the parent objects of this resource. Used for finding dependencies between resources.

=cut

sub parents {
    $Log->enter() if $may_enter;
    $Log->exit() if $may_exit;
    return qw(NACL::STask::VserverServicesLdapClient);
}

1;