# $Id: //depot/prod/test/nacldev/lib/NACL/Exceptions/SnapmirrorSetFailure.pm#1 $
#
# Copyright (c) 2009-2011 NetApp Inc.
# All rights reserved.
#
## @summary Provide an exception class that is a subclass of
##          NATE::BaseException that will be thrown whenever SnapmirrorSet related operation could not be completed. 
##
## @author bkumaran@netapp.com
## @status Shared
## @pod here

=head1 NAME

NACL::Exceptions::SnapmirrorSetFailure

=head1 DESCRIPTION

This exception is thrown when SnapmirrorSet related operation could not be completed. 
In addition to the attributes that exception objects generally contain,
this exception also contains C<text> and C<exception_objects> attribute. 
This is a scalar, which will hold the error text and the array of exception objects. 

=head1 ATTRIBUTES

=head2 text 

This attribute is a scalar, which will hold the error text.

=head2 exception_objects 

This attribute is a array

Each entry in the array is a hash-reference which contains two keys:

=over

=item C< snapmirror >

The destination path of snapmirror. 

=item C< error >

The exception thrown NACL::STask::Snapmirror->purge

Being an array-field, this can be accessed in either scalar or list context.

    my $array_reference = $exception_obj->exception_objects();

                        or

    my @array = $exception_obj->exception_objects();

Assuming we have an array we can access the fields like:

    foreach my $entry (@array) {
        $Log->comment('Snapmirror ' . $entry->{snapmirror} . ' failed with '
            . $entry->{error});
    }

=back

=head1 EXAMPLE

    use NACL::Exceptions::SnapmirrorSetFailure;
    
    try {
	$sms->purge(nacltask_verify => 1);	
    } catch NACL::Exceptions::SnapmirrorSetFailure with {
        my $ex = shift;
        $Log->comment( "Text ".$ex->text() );
	my @array = $ex->exception_objects;
        foreach my $entry (@array) {
                $Log->comment('Snapmirror ' . $entry->{snapmirror} . 'failed with '
                . $entry->{error});
        }
    };

=cut

package NACL::Exceptions::SnapmirrorSetFailure;
use base qw(NATE::BaseException);
use Params::Validate qw(validate_with SCALAR ARRAYREF);
use NATE::Log qw(log_global);
my $Log = log_global();
my $may_enter = $Log->may_enter();
my $may_exit  = $Log->may_exit();
use Class::MethodMaker [array => 'exception_objects'];

sub new {
    $Log->enter() if $may_enter;
    my ($pkg, @args) = @_;
    my %opts = validate_with(
        params      => \@args,
        spec        => {
            text              => {type => SCALAR},
            exception_objects => {type => ARRAYREF},
        },
        allow_extra => 1
    );

    # BaseException->new expects the text to be provided as the first
    # (positional) parameter. All other fields are automatically set
    # in the object by BaseException->new.
    my $text = delete $opts{text};
    my $self = $pkg->SUPER::new($text, %opts);
    $Log->exit() if $may_exit;
    return $self;
} ## end sub new

1;