/ 
Kafka-1.02
River stage one • 2 direct dependents • 2 total dependents
/ Kafka::Exceptions

NAME

Kafka::Exceptions - Perl Kafka API exception definitions.

VERSION

This documentation refers to Kafka::Exceptions version 1.02 .

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;

DESCRIPTION

The purpose of the Kafka::Exceptions module is:

  • Declare a Kafka API exceptions hierarchy.

  • Provide additional methods for working with exceptions.

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 Kafka::Exception and its subclasses:

code

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

message

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

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

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

Kafka::Exception::Connection

See Kafka::Connection methods.

Kafka::Exception::Consumer

See Kafka::Consumer methods.

Kafka::Exception::IO

See Kafka::IO methods.

Kafka::Exception::Int64

See Kafka::Int64 methods.

Kafka::Exception::Producer

See Kafka::Producer methods.

Kafka::Exception::Protocol

See Kafka::Protocol methods.

Authors suggest using of Try::Tiny's try and catch to handle exceptions while working with Kafka package.

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

FUNCTIONS

The following functions are exported by Kafka::Exceptions module:

throw_args( $error_code, $description )

Converts arguments into Kafka::Exception constructor attributes "code" and "message".

throw_args() accepts the following arguments:

$error_code

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

$description

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

SEE ALSO

The basic operation of the Kafka package modules:

Kafka - constants and messages used by the Kafka package modules.

Kafka::Connection - interface to connect to a Kafka cluster.

Kafka::Producer - interface for producing client.

Kafka::Consumer - interface for consuming client.

Kafka::Message - interface to access Kafka message properties.

Kafka::Int64 - functions to work with 64 bit elements of the protocol on 32 bit systems.

Kafka::Protocol - functions to process messages in the Apache Kafka's Protocol.

Kafka::IO - low-level interface for communication with Kafka server.

Kafka::Exceptions - module designated to handle Kafka exceptions.

Kafka::Internals - internal constants and functions used by several package modules.

A wealth of detail about the Apache Kafka and the Kafka Protocol:

Main page at http://kafka.apache.org/

Kafka Protocol at https://cwiki.apache.org/confluence/display/KAFKA/A+Guide+To+The+Kafka+Protocol

SOURCE CODE

Kafka package is hosted on GitHub: https://github.com/TrackingSoft/Kafka

AUTHOR

Sergey Gladkov, <sgladkov@trackingsoft.com>

Please use GitHub project link above to report problems or contact authors.

CONTRIBUTORS

Alexander Solovey

Jeremy Jordan

Sergiy Zuban

Vlad Marchenko

COPYRIGHT AND LICENSE

Copyright (C) 2012-2017 by TrackingSoft LLC.

This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic at http://dev.perl.org/licenses/artistic.html.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.