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

## @summary Base class for tasks which are not tied to a single component
## @author dl-nacl-dev@netapp.com
## @status shared
## @pod here

package NACL::MTask::MTask;

=head1 NAME

NACL::MTask::MTask

=head1 DESCRIPTION

This is the base class for tasks which are not tied to a single component, i.e.
the operations provided by these tasks can span multiple components/ multiple
instances of components.

(This is in contrast with the "single component tasks" 
L<NACL::STask::STask|lib-NACL-STask-STask-pm>, which is for
tasks whose operations are focussed on a single component)

=cut

use strict;
use warnings;

#use NACL::C::Component;
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_with HASHREF SCALAR);
use NACL::ChooseAPISet qw(call_on_apiset);

# Let's divide up the methods into user-facing methods and developer-only
# methods. Developer-only methods should begin with an underscore, user-facing
# methods should not.

######################## Methods for task users here #######################

=head1 METHODS FOR TASK USERS

Nothing to see here at the moment.

=cut

###################### Methods for task developers here ######################

=head1 METHODS FOR TASK DEVELOPERS

=head2 _copy_common_component_params

See L<NACL::GeneralUtils::_copy_common_component_params|lib-NACL-GeneralUtils-pm/_copy_common_component_params>.

=head2 _move_common_component_params

See L<NACL::GeneralUtils::_move_common_component_params|lib-NACL-GeneralUtils-pm/_move_common_component_params>.

=head2 _copy_common_component_params_with_ci

See L<NACL::GeneralUtils::_copy_common_component_params_with_ci|lib-NACL-GeneralUtils-pm/_copy_common_component_params_with_ci>.

=head2 _move_common_component_params_with_ci

See
L<NACL::GeneralUtils::_move_common_component_params_with_ci|lib-NACL-GeneralUtils-pm/_move_common_component_params_with_ci>.

=head2 _if_action_completed_already_validate_callback

L<_if_action_completed_already_validate_callback|lib-NACL-TaskUtils-pm/_if_action_completed_already_validate_callback>

=head2 _if_action_completed_already_validate_spec

L<_if_action_completed_already_validate_spec|lib-NACL-TaskUtils-pm/_if_action_completed_already_validate_spec>

=cut

use NACL::GeneralUtils qw(_copy_common_component_params
    _move_common_component_params
    _copy_common_component_params_with_ci
    _move_common_component_params_with_ci
    _copy_or_move_common_params
);
use NACL::TaskUtils qw(
    wait_for_replay
    _if_action_completed_already_validate_callback
    _if_action_completed_already_validate_spec
);

use NACL::ComponentUtils qw(_hash_copy
    _hash_move
    _verify_invocation
    _make_attribute_readonly
);

=head2 _common_validate_with

The Component's C<_common_validate_with> is available on MTasks as well.
This _common_validate_with requires 
L<_object_attributes_validate_spec|lib-NACL-MTask-MTask-pm/_object_attributes_validate_spec>
to be defined.

See L<_common_validate_with|lib-NACL-C-Component-pm/_common_validate_with>
for more documentation.

=head2 _common_validate_spec

Reuses the C<_common_validate_spec> defined by Components - this is the
validation spec for options common to all method calls. (includes
apiset_should, apiset_must, command_interface, method-timeout)

=head2 _common_validate_spec_without_ci

Reuses the C<_common_validate_spec_without_ci> defined by Components - same
as the above but C<command_interface> is not included.

=head2 _get_validate_with_spec

Reuses the C<_get_validate_with_spec> defined by Components

=cut 

BEGIN {

    # Make _common_validate_with and _common_validate_spec of
    # NACL::C::Component accessible here
    no strict 'refs';
    *{_common_validate_with} = \&NACL::C::Component::_common_validate_with;
    *{_common_validate_spec} = \&NACL::C::Component::_common_validate_spec;
    *{_common_validate_spec_without_ci}
        = \&NACL::C::Component::_common_validate_spec_without_ci;
    *{_get_validate_with_spec} = \&NACL::C::Component::_get_validate_with_spec;

    # These shouldn't be used anymore but are kept for backwards compatibility
    *{_component_common_validate_spec} = *{_common_validate_spec};
    *{_component_common_validate_spec_without_ci}
        = *{_common_validate_spec_without_ci};

    use strict 'refs';
}

=head2 _get_keys_names

The names of the attributes of the object. This is achieved by getting the
keys of the validation spec returned by
L<_object_attributes_validate_spec|lib-NACL-MTask-MTask-pm/_object_attributes_validate_spec>.

This is required for C<_common_validate_with>.

=cut

sub _get_keys_names {
    $Log->enter() if $may_enter;
    my $pkg_or_obj = shift;
    my @keys = keys %{ $pkg_or_obj->_object_attributes_validate_spec() };
    $Log->exit() if $may_exit;
    return @keys;
}

=head2 _include_object_attributes_validate_spec

Include the object attributes validation spec in the validation spec
constructed by C<_common_validate_with>.

=cut

sub _include_object_attributes_validate_spec {
    my $pkg_or_obj = shift;
    my %opts       = validate_with(
        params => \@_,
        spec   => { spec => { type => HASHREF } },
        allow_extra => 1    # We don't care about the other options
    );
    my %spec = %{ $opts{spec} };
    %spec = ( %{ $pkg_or_obj->_object_attributes_validate_spec() }, %spec );
    $Log->exit() if $may_exit;
    return %spec;
}

=head2 _object_attributes_validate_spec

This is the validation spec of the attributes of the MTask object. This
needs to be implemented in the MTask subclasses that call
_common_validate_with.

=cut

sub _object_attributes_validate_spec {
    return {};
}

# Required for _common_validate_with to work
sub _additional_common_validate_spec {return {}}

1;