#
# 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 when verification of one
##          or more event messages does not match the provided value.
##
## @author chethanm@netapp.com, dl-nacl-dev@netapp.com
## @status Shared
## @pod here

=head1 NAME

NACL::Exceptions::EventCheckFailure

=head1 DESCRIPTION

This exception is thrown when verification of 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 a array-reference, which will hold all the event message names which 
did/didn't match the criteria provided.

=head1 ATTRIBUTES

=head2 unmatched_events

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

=head1 EXAMPLE

    use NACL::Exceptions::EventCheckFailure qw(:try);
    use NACL::MTask::EventLogDetector;

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

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

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

=head2 matched_events

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

=head1 EXAMPLE

    use NACL::Exceptions::EventCheckFailure qw(:try);
    use NACL::MTask::EventLogDetector;

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

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

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

=cut

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

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

1;