The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Kafka-0.800_16
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 0.800_16 .

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 {
    if ( blessed( $_ ) && $_->isa( 'Kafka::Exception' ) ) {
        if ( $_->isa( 'Kafka::Exception::Connection' ) ) {
            # Specific treatment for 'Kafka::Connection' class error
        } elsif ( $_->isa( 'Kafka::Exception::IO' ) ) {
            # Specific treatment for 'Kafka::IO' class error
        }
        warn ref( $_ ), " error:\n", $_->message, "\n", $_->trace->as_string, "\n";
        exit;
    } else {
        die $_;
    }
};

# Closes the connection and cleans up
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.

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

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

AUTHOR

Sergey Gladkov, <sgladkov@trackingsoft.com>

CONTRIBUTORS

Alexander Solovey

Jeremy Jordan

Vlad Marchenko

COPYRIGHT AND LICENSE

Copyright (C) 2012-2013 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.