File Coverage

lib/Kafka/Exceptions.pm

Criterion	Covered	Total	%
statement	23	23	100.0
branch	2	2	100.0
condition			n/a
subroutine	8	8	100.0
pod	1	1	100.0
total	34	34	100.0

package Kafka::Exceptions;

=head1 NAME

Kafka::Exceptions - Perl Kafka API exception definitions.

=head1 VERSION

This documentation refers to C version 1.07 .

=cut



use 5.010;
use strict;
use warnings;



our $DEBUG = 0;

our $VERSION = '1.07';

use Exporter qw(
    import
);
our @EXPORT = qw(
    throw_args
);



use Exception::Class (
    'Kafka::Exception' => {
        fields  => [ 'code', 'message' ],
    },
    'Kafka::Exception::Connection' => {
        isa     => 'Kafka::Exception',
        fields  => [ 'request', 'response', 'io_error' ],
    },
    'Kafka::Exception::Consumer' => {
        isa     => 'Kafka::Exception',
    },
    'Kafka::Exception::Int64' => {
        isa     => 'Kafka::Exception',
    },
    'Kafka::Exception::IO' => {
        fields  => [ 'errno' ],
        isa     => 'Kafka::Exception',
    },
    'Kafka::Exception::Producer' => {
        isa     => 'Kafka::Exception',
    },
    'Kafka::Exception::Protocol' => {
        isa     => 'Kafka::Exception',
    },
);

use Kafka qw(
    %ERROR
);
use Kafka::Internals qw(
    format_message
);

Kafka::Exception->Trace(1); # include stack traces


=head1 SYNOPSIS

    use 5.010;
    use strict;
    use warnings;

    use Scalar::Util qw(
        blessed
    );
    use Try::Tiny;

    # A simple example of Kafka::Connection usage:
    use Kafka::Connection;

    # connect to local cluster with the defaults
    my $connection;
    try {
        $connection = Kafka::Connection->new( host => 'localhost' );
    } catch {
        my $error = $_;
        if ( blessed( $error ) && $error->isa( 'Kafka::Exception' ) ) {
            if ( $error->isa( 'Kafka::Exception::Connection' ) ) {
                # Specific treatment for 'Kafka::Connection' class error
            } elsif ( $error->isa( 'Kafka::Exception::IO' ) ) {
                # Specific treatment for 'Kafka::IO' class error
            }
            warn ref( $error ), " error:\n", $error->message, "\n", $error->trace->as_string, "\n";
            exit;
        } else {
            die $error;
        }
    };

    # Closes the connection and cleans up
    $connection->close;
    undef $connection;

=head1 DESCRIPTION

The purpose of the C module is:

=over 3

=item *

Declare a Kafka API exceptions hierarchy.

=item *

Provide additional methods for working with exceptions.

=back

It is designed to make exception handling structured, simpler and better by encouraging use
of hierarchy of exceptions in application (vs single catch-all exception class).

The following additional attributes are available in C and its subclasses:

=over 3

=item C

An error code that references error in C<%Kafka::ERROR> hash.

=item C

An error message that contains information about the encountered failure.
This message may contain additional details which are not provided by C<%Kafka::ERROR> hash.

=back

Exception objects provide accessor methods for these attributes. Attributes are inherited by
subclasses.

Various Kafka API modules throw exceptions objects of a C subclass specific
to that module:

=over 3

=item C

See L methods.

=item C

See L methods.

=item C

See L methods.

=item C

See L methods.

=item C

See L methods.

=item C

See L methods.

=back

Authors suggest using of L's C and C to handle exceptions while
working with L package.

You may also want to review documentation of L,
which is the default base class for all exception objects created by this module.

=cut

#-- constructor ----------------------------------------------------------------

#-- public attributes ----------------------------------------------------------

=head2 FUNCTIONS

The following functions are exported by C module:

=cut

=head3 C

Converts arguments into C constructor attributes L and L.

C accepts the following arguments:

=over 3

=item C<$error_code>

The code of the last error.
The code must match the error codes defined in the module L.

=item C<$description>

An additional error description that contains information about the encountered problem.

=back

=cut
sub throw_args {
    my $error_code = shift;
    my $description = shift;

    return (
        code    => $error_code,
        message => format_message( '%s%s', $ERROR{ $error_code }, $description ? ": $description" : '' ),
        @_,
    );
}

#-- private attributes ---------------------------------------------------------

#-- private methods ------------------------------------------------------------



1;

__END__