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

## @summary LunAttribute ComponentState Module (auto-generated by CGT)
## @author dl-nacl-dev@netapp.com
## @status shared
## @pod here

=head1 NAME

NACL::CS::LunAttribute

=head1 DESCRIPTION

C<NACL::CS::LunAttribute> is a derived class of
L<NACL::CS::ComponentState::ONTAP|lib-NACL-CS-ComponentState-ONTAP-pm>. It represents the
state of an ONTAP LunAttribute.  A related class is
L<NACL::C::LunAttribute|lib-NACL-C-LunAttribute-pm>, which represents access
to an ONTAP LunAttribute.

=head1 ATTRIBUTES

The individual pieces of data that are part of the state of the LunAttribute
element are the attributes of the LunAttribute ComponentState.

Additionally, the command_interface used to obtain the ComponentState object is
also an attribute of the object. This makes it easier to obtain the component
object corresponding to the CS object, using
L<get_component_instance|lib-NACL-CS-ComponentState-pm/get_component_instance>.

=over

=item command_interface

The command_interface with which the CS object was obtained. (Available in
all CS objects regardless of requested_fields and the mode/interface)

=item C<< lun >>

*LUN Name
Filled in for CMode CLI/ZAPI, 7Mode CLI

Maps to:

7M CLI : path_last

=item C<< volume >>

*Volume Name
Filled in for CMode CLI/ZAPI

=item C<< qtree >>

*Qtree Name
Filled in for CMode CLI/ZAPI

=item C<< vserver >>

*Vserver Name
Filled in for CMode CLI/ZAPI

Maps to:
CM ZAPI:

Input:

If this option is specified in,
* 'filter',Invoked in the context of the specified vserver
* 'requested_fields', it  would translate to

<lun-get-attributes>
<vserver>$value</vserver>
</lun-get-attributes>

Output:

<lun-get-attributes>
<vserver>$value</vserver>
</lun-get-attributes>

=item C<< value >>

*Named Attribute Value
Filled in for CMode CLI/ZAPI, 7Mode CLI

=item C<< name >>

*Named Attribute
Filled in for CMode CLI/ZAPI, 7Mode CLI

Maps to:
CM ZAPI:

Input:

If this option is specified in,
* 'filter',Invoked in the context of the specified name
* 'requested_fields', it  would translate to

<lun-get-attributes>
<name>$value</name>
</lun-get-attributes>

Output:

<lun-get-attributes>
<name>$value</name>
</lun-get-attributes>

=item C<< path >>

*LUN Path
Filled in for CMode CLI/ZAPI, 7Mode CLI

Maps to:
CM ZAPI:

Input:

If this option is specified in,
* 'filter',Invoked in the context of the specified path
* 'requested_fields', it  would translate to

<lun-get-attributes>
<path>$value</path>
</lun-get-attributes>

Output:

<lun-get-attributes>
<path>$value</path>
</lun-get-attributes>

=item C<< path >>

Filled in for 7Mode CLI.

=item C<< anvil_fsconsistent >>

Filled in for 7Mode CLI.

=item C<< host_stamp >>

Filled in for 7Mode CLI.

=item C<< cylinder_size >>

Filled in for 7Mode CLI.

=item C<< custom >>

Filled in for 7Mode CLI.

=item C<< path_last >>

Filled in for 7Mode CLI.

=item C<< extent_size >>

Filled in for 7Mode CLI.

=item C<< read_only >>

Filled in for 7Mode CLI.

=item C<< type >>

Filled in for 7Mode CLI.

=item C<< enabled >>

Filled in for 7Mode CLI.

=back

=cut

package NACL::CS::LunAttribute;

use strict;
use warnings;
use Params::Validate qw(validate);
use NATE::Log qw(log_global);
my $Log = log_global();
my $may_enter = $Log->may_enter();
my $may_exit  = $Log->may_exit();

use NACL::Exceptions::InvalidChoice;
use NACL::C::_Mixins::Lun
    qw(_construct_path _extract_volume_qtree_lun_from_path);

use base 'NACL::CS::ComponentState::ONTAP';

use Class::MethodMaker [
    scalar => 'lun',
    scalar => 'volume',
    scalar => 'qtree',
    scalar => 'vserver',
    scalar => 'value',
    scalar => 'name',
    scalar => 'path',

    # These fields show up for CMode-CLI, but are really old so are not
    # documented above
    scalar => 'namedAttr',
    scalar => 'namedAttrVal',

    #7Mode specific fields
    scalar => 'space_alloc',
    scalar => 'anvil_fsconsistent',
    scalar => 'host_stamp',
    scalar => 'serial',
    scalar => 'cylinder_size',
    scalar => 'custom',
    scalar => 'path_last',
    scalar => 'extent_size',
    scalar => 'read_only',
    scalar => 'type',
    scalar => 'enabled',
];

=head1 METHODS

=head2 fetch

    my $LunAttribute_state  = NACL::CS::LunAttribute->fetch(command_interface => $ci, ...);
    my @LunAttribute_states = NACL::CS::LunAttribute->fetch(command_interface => $ci, ...);

(Class method)
Discovers which elements are present and returns their state in ComponentState
objects. Called in scalar context it returns only one state object, in list
context it returns all state objects.
See L<NACL::CS::ComponentState|lib-NACL-CS-ComponentState-pm/fetch> for a
more detailed description along with a complete explanation of the options
it accepts.

Uses a CMode CLI/ZAPI APISet.

Invokes 'lun-get-attributes' API for CMode ZAPI.

Invokes 'lun attribute list' command for 7Mode CLI.

=over

=item Exceptions

=over

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

When there are no elements matching the query specified or elements of that type
doesn't exist, then this exception will be thrown.

=back

=back

=cut

sub fetch {
    $Log->enter() if $may_enter;
    my ($pkg, @args) = @_;
    my @state_objs = $pkg->SUPER::fetch(
        @args,
        choices => [
            {   method    => '_fetch_cmode_cli',
                interface => 'CLI',
                set       => 'CMode'
            },
            {   method    => '_fetch_cmode_zapi',
                interface => 'ZAPI',
                set       => 'CMode',
                check     => '_check_cmode_zapi',
            },
            {   method    => '_fetch_7mode_cli',
                interface => 'CLI',
                set       => '7Mode'
            }
        ],
        exception_text => 'No matching lun attribute(s) found',
    );
    $Log->exit() if $may_exit;
    return wantarray ? @state_objs : $state_objs[0];
}

sub _fetch_cmode_cli {
    $Log->enter() if $may_enter;
    my ($pkg, @args) = @_;
    my @state_objs
        = $pkg->SUPER::_fetch_cmode_cli(@args, api => 'lun_attribute_show',);
    $Log->exit() if $may_exit;
    return @state_objs;
}

sub _fetch_cmode_zapi {
    $Log->enter() if $may_enter;
    my ($pkg, @args) = @_;
    my %opts = validate @args, $pkg->_fetch_backend_validate_spec();

    # ZAPI is vserver-scoped, so determine the vserver on which to invoke
    # the ZAPI.
    my $command_interface = $opts{command_interface};

    # We make a deep copy because _handle_zapi_vserver_context updates the
    # hash-reference.
    my %filter  = %{$opts{filter}};
    my $vserver = $pkg->_handle_zapi_vserver_context(
	 api_opts          => \%filter,
         command_interface => $command_interface
    );
    if (!defined $filter{path}) {
	# '""' is the null qtree. _construct_path expects qtree to not be
        # provided in this case, so we delete it.
	if (defined $filter{qtree} && $filter{qtree} eq '""') {
            delete $filter{qtree};
	}
	$pkg->_construct_path(params => \%filter);
    }
    my $path = $filter{path};
    # "name" is optional for the ZAPI.
    my %api_args;
    if (defined $filter{name}) {
	$api_args{name} = $filter{name};
    }
    my $apiset   = $opts{apiset};
    my $response = $apiset->lun_get_attributes(
	'vserver-override-name' => $vserver,
	path                    => $path,
	%api_args,
    );
    my $output = $response->get_parsed_output();
    if (!@$output) {
        # No rows in the output, return immediately
	$Log->exit() if $may_exit;
	return;
    }

    # ZAPI returns only for a single lun, so the value of vserver and
    # the path will be same for all rows. We compute the values of
    # volume+qtree+lun once from the path and we can set all these
    # values for all rows.

    my %path_attrs = (path => $path, vserver => $vserver);
    @path_attrs{'volume', 'qtree', 'lun'}
	 = $pkg->_extract_volume_qtree_lun_from_path(path => $path);

    # For the null qtree, the extract method returns qtree as undef. We should
    # turn this into '""'.

   $path_attrs{qtree} = '""' if (!defined $path_attrs{qtree});
    my @state_objs;
    foreach my $row (@{$output->[0]{'attributes'}[0]{'lun-attribute-info'}}) {
	my %cs_attrs = (name => $row->{name}, value => $row->{value});
	my $obj = $pkg->new(command_interface => $command_interface);

        # The fields we set in the object should contain the path attrs
	# along with the name+value for that row

        $obj->_set_fields(row => {%path_attrs, %cs_attrs});
	push @state_objs, $obj;
   }
   $Log->exit() if $may_exit;
   return @state_objs;
}

sub _check_cmode_zapi {
    $Log->enter() if $may_enter;
    my ($pkg, %opts) = @_;
    my $filter = $opts{filter};

    # ZAPI is vserver scoped, so if the vserver is not provided then we cannot
    # use the ZAPI. Check for presence of vserver in the filter or if the
    # command_interface is a vserver object
    if (   !defined $filter->{vserver}
        && !$opts{command_interface}->isa('NACL::C::Vserver'))
    {
        $Log->exit() if $may_exit;
        NACL::Exceptions::InvalidChoice->throw("'vserver' was not provided "
                . " so the ZAPI cannot be used (the 'lun-get-attributes' ZAPI "
                . 'is vserver-scoped)');
    }

   # The ZAPI also requires path to be specified, so check for presence of
   # path OR all the constituents of path (volume+qtree+lun). Also, check that
   # there are no special characters (ZAPI requires an exact path, not one
   # with wildcard characters)
    my $path = $filter->{path};
    if (defined $filter->{path}) {
        my $has_sp_chr
            = $pkg->_check_relational_regex_filter(filter_value => $path);
        if ($has_sp_chr) {
            $Log->exit() if $may_exit;
            NACL::Exceptions::InvalidChoice->throw('Cannot use the ZAPI '
                    . "implementation because the 'path' specified (value = "
                    . "'$path') has special characters");
        }
    } else {
        if (   defined $filter->{volume}
            && defined $filter->{qtree}
            && defined $filter->{lun})
        {
            foreach my $field (qw(volume qtree lun)) {
                my $value      = $filter->{$field};
                my $has_sp_chr = $pkg->_check_relational_regex_filter(
                    filter_value => $value);
                if ($has_sp_chr) {
                    $Log->exit() if $may_exit;
                    NACL::Exceptions::InvalidChoice->throw('Cannot use the '
                            . "ZAPI implementation because the 'path' is "
                            . 'necessary for the ZAPI and was not provided. '
                            . "Also, since '$field' was specified with "
                            . "special characters (value = '$value'), the "
                            . 'path could not be constructed');
                }
            }
        } else {
            $Log->exit() if $may_exit;
            NACL::Exceptions::InvalidChoice->throw('Cannot use the ZAPI '
                    . "implementation because the 'path' ins necessary for "
                    . 'the ZAPI, but was not provided. Further, all the '
                    . 'constituents of the path (volume+qtree+lun) were '
                    . 'not provided, so we could not construct the path');
        }
    }

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

sub _fetch_7mode_cli {
    $Log->enter() if $may_enter;
    my ($pkg, %opts) = @_;
    my @state_objs;
    my $apiset           = $opts{apiset};
    my $filter           = $opts{filter};
    my $requested_fields = $opts{requested_fields};
    my %api_args;
    my @orig_requested_fields = @{$opts{requested_fields}};
    my %orig_filter           = %{$opts{filter}};
    $pkg->_remove_relational_regex_filters(
        filter           => \%orig_filter,
        requested_fields => \@orig_requested_fields
    );
    $requested_fields = \@orig_requested_fields;
    $filter           = \%orig_filter;

    # "lun show" allows us to filter by path or volume name
    # If both path and volume are provided in the filter we provide higher
    # priority to path, since that would refer to a specific LUN
    if (exists $filter->{path}) {
        $api_args{'lun-path'} = $filter->{path};
    } elsif (exists $filter->{volume} && $filter->{lun}) {
        $api_args{'lun-path'}
            = '/vol/' . $filter->{volume} . '/' . $filter->{lun};
    }
    my $response = $apiset->lun_attribute_list(%api_args);
    my $output   = $response->get_parsed_output();
    foreach my $list_output (@{$output}) {
        my $obj = $pkg->new(command_interface => $opts{command_interface});
        $obj->_set_fields(row => $list_output);
        push @state_objs, $obj;
    }

    $Log->exit() if $may_exit;
    return @state_objs;
} ## end sub _fetch_7mode_cli

1;