#
# Copyright (c) 2013 NetApp Inc.
# All rights reserved.
#
## @summary Provide an exception class that is a subclass of
##          NATE::BaseException that will be thrown when verification of one
##          or more sp event messages does not match the provided value.
##
## @author rahula@netapp.com, dl-nacl-dev@netapp.com
## @status Shared
## @pod here

=head1 NAME

NACL::Exceptions::SPEventCheckFailure

=head1 DESCRIPTION

This exception is thrown when verification of sp event messages does not pass.
In addition to the attributes that exception objects generally contain,
this exception also contains C<unmatched_events> and C<matched_events> attribute.
This is an array-reference, which will hold all the sp event message names which
did/did not match the criteria provided.

=head1 ATTRIBUTES

=head2 unmatched_events

=over

This attribute is an array-reference, which will hold all the sp event message
names which didn't match the criteria.

=head3 EXAMPLE

    use NACL::Exceptions::SPEventCheckFailure qw(:try);
    use NACL::MTask::SPEventLogDetector;

    try {
    my $SPLogdetector = NACL::MTask::SPEventLogDetector->->new(
        command_interface      => $Cluster,
        check_for_all_presence => ['message.must.occur'],
        check_for_absence      => ['should.not.occur'],
    );
    $SPLogdetector->start();
    ...

    # Perform any operations here
    ... $SPLogdetector->stop( 'check' => 0 );

    #do wait/or some other operations
    $SPLogdetector->check();
    }
    catch NACL::Exceptions::SPEventCheckFailure with {
        my $exception = shift;
        $Log->comment( "Event match failed" . $exception->text() );
        my $unmatched_events_arrayref = $exception->unmatched_events();
    );

=back

=head2 matched_events

=over

This attribute is an array-reference, which will hold all the sp event message
names which matched the criteria.

=head3 EXAMPLE

    use NACL::Exceptions::SPEventCheckFailure qw(:try);
    use NACL::MTask::SPEventLogDetector;

    try {
    my $SPLogdetector = NACL::MTask::SPEventLogDetector->new(
        command_interface      => $Cluster,
        check_for_all_presence => ['message.must.occur'],
        check_for_absence      => ['should.not.occur'],
    );
    $SPLogdetector->start();
    ...

    # Perform any operations here
    ... $SPLogdetector->stop( 'check' => 0 );

    #do wait/or some other operations
    $SPLogdetector->check();
    }
    catch NACL::Exceptions::SPEventCheckFailure with {
        my $exception = shift;
        $Log->comment( "Event match failed" . $exception->text() );
        my $matched_events_arrayref = $exception->matched_events();
    );

=back

=cut

package NACL::Exceptions::SPEventCheckFailure;
use base qw( NATE::BaseException NACL::Exceptions::EventCheckFailure );

use Class::MethodMaker [ scalar => 'matched_events', scalar => 'unmatched_events' ];

1;