/ 
POEx-Role-TCPClient-1.100910
/ POEx::Role::TCPClient

NAME

POEx::Role::TCPClient - A Moose Role that provides TCPClient behavior

VERSION

version 1.100910

DESCRIPTION

POEx::Role::TCPClient bundles up the lower level SocketFactory/ReadWrite combination of wheels into a simple Moose::Role. It builds upon other POEx modules such as POEx::Role::SessionInstantiation and POEx::Types.

The events for SocketFactory and for each ReadWrite instantiated are methods that can be advised in any way deemed fit. Advising these methods is actually encouraged and can simplify code for the consumer.

The only method that must be provided by the consuming class is handle_inbound_data.

The connect event must be invoked to initiate a connection.

PROTECTED_ATTRIBUTES

socket_factories

traits:Hash, isa: HashRef[Object]

The POE::Wheel::SocketFactory objects created in connect are stored here and managed via the following provides:

{
    get_socket_factory => 'get',
    set_socket_factory => 'set',
    delete_socket_factory => 'delete',
    has_socket_factories => 'count',
    has_socket_factory => 'exists',
}

wheels

traits: Hash, isa: HashRef, clearer: clear_wheels

When connections are finished, a POE::Wheel::ReadWrite object is created and stored in this attribute, keyed by WheelID. Wheels may be accessed via the following provided methods.

{
    get_socket_factory => 'get',
    set_socket_factory => 'set',
    delete_socket_factory => 'delete',
    has_socket_factories => 'count',
    has_socket_factory => 'exists',
}

wheels

traits: Hash, isa: HashRef, clearer: clear_wheels

When connections are finished, a POE::Wheel::ReadWrite object is created and stored in this attribute, keyed by WheelID. Wheels may be accessed via the following provided methods.

{
    get_wheel => 'get',
    set_wheel => 'set',
    delete_wheel => 'delete',
    count_wheels => 'count',
    has_wheel => 'exists',
}

last_wheel

is: rw, isa: WheelID

This holds the last ID created from the handle_on_connect method. Handy if the protocol requires client initiation.

filter

is: rw, isa: Filter

This stores the filter that is used when constructing wheels. It will be cloned for each connection completed. By default, instantiates a POE::Filter::Line object.

connection_tags

traits: Hash, is: ro, isa: HashRef[Ref]

This stores any arbitrary user data passed to connect keyed by the socket factory ID. Handy to match up multiple connects for composers.

{
    get_connection_tag => 'get',
    set_connection_tag => 'set',
    delete_connection_tag => 'delete',
    has_connection_tags => 'count',
    has_connection_tag => 'exists',
}

PUBLIC_METHODS

connect

(Str :$remote_address, Int :$remote_port, Maybe[Ref] :$tag) is Event

connect is used to initiate a connection to a remote source. It accepts two named arguments that both required, remote_address and remote_port. They are passed directly to SocketFactory. If tag is provided, it will be stored in connection_tags and keyed by the socket factory's ID.

shutdown()

is Event

shutdown unequivically terminates the TCPClient by clearing all wheels and aliases, forcing POE to garbage collect the session.

PROTECTED_METHODS

handle_on_connect

(GlobRef $socket, Str $address, Int $port, WheelID $id) is Event

handle_on_connect is the SuccessEvent of the SocketFactory instantiated in _start.

handle_connect_error

(Str $action, Int $code, Str $message, WheelID $id) is Event

handle_connect_error is the FailureEvent of the SocketFactory

handle_socket_error

(Str $action, Int $code, Str $message, WheelID $id) is Event

handle_socket_error is the ErrorEvent of each POE::Wheel::ReadWrite instantiated.

REQUIRES

METHODS

handle_inbound_data

($data, WheelID $id) is Event

This required method will be passed the data received, and from which wheel it came.

AUTHOR

Nicholas Perez <nperez@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2010 by Nicholas Perez.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.