template class Poco::Net::SocketConnector

Overview

This class implements the Connector part of the Acceptor-Connector design pattern. More…

#include <SocketConnector.h>

template <class ServiceHandler>
class SocketConnector
{
public:
    // construction

    SocketConnector(SocketAddress& address);

    SocketConnector(
        SocketAddress& address,
        SocketReactor& reactor
        );

    // methods

    virtual
    void
    registerConnector(SocketReactor& reactor);

    virtual
    void
    unregisterConnector();

    void
    onReadable(ReadableNotification* pNotification);

    void
    onWritable(WritableNotification* pNotification);

    void
    onConnect();

    void
    onError(ErrorNotification* pNotification);

protected:
    // methods

    virtual
    ServiceHandler*
    createServiceHandler();

    virtual
    void
    onError(int errorCode);

    SocketReactor*
    reactor();

    StreamSocket&
    socket();
};

Detailed Documentation

This class implements the Connector part of the Acceptor-Connector design pattern.

The Acceptor-Connector pattern has been described in the book “Pattern Languages of Program Design 3”, edited by Robert Martin, Frank Buschmann and Dirk Riehle (Addison Wesley, 1997).

The Acceptor-Connector design pattern decouples connection establishment and service initialization in a distributed system from the processing performed once a service is initialized. This decoupling is achieved with three components: Acceptors, Connectors and Service Handlers. The Connector actively establishes a connection with a remote server socket (usually managed by an Acceptor) and initializes a Service Handler to manage the connection.

The SocketConnector sets up a StreamSocket, initiates a non-blocking connect operation and registers itself for ReadableNotification, WritableNotification and ErrorNotification. ReadableNotification or WritableNotification denote the successful establishment of the connection.

When the StreamSocket becomes readable or writeable, the SocketConnector creates a ServiceHandler to service the connection and unregisters itself.

In case of an error (ErrorNotification), the SocketConnector unregisters itself and calls the onError() method, which can be overridden by subclasses to perform custom error handling.

The ServiceHandler class must provide a constructor that takes a StreamSocket and a SocketReactor as arguments, e.g.:

MyServiceHandler(const StreamSocket& socket, ServiceReactor& reactor)

When the ServiceHandler is done, it must destroy itself.

Subclasses can override the createServiceHandler() factory method if special steps are necessary to create a ServiceHandler object.

Construction

SocketConnector(
    SocketAddress& address,
    SocketReactor& reactor
    )

Creates an acceptor, using the given ServerSocket.

The SocketConnector registers itself with the given SocketReactor.

Methods

virtual
void
registerConnector(SocketReactor& reactor)

Registers the SocketConnector with a SocketReactor.

A subclass can override this and, for example, also register an event handler for a timeout event.

The overriding method must call the baseclass implementation first.

virtual
void
unregisterConnector()

Unregisters the SocketConnector.

A subclass can override this and, for example, also unregister its event handler for a timeout event.

The overriding method must call the baseclass implementation first.

virtual
ServiceHandler*
createServiceHandler()

Create and initialize a new ServiceHandler instance.

Subclasses can override this method.

virtual
void
onError(int errorCode)

Called when the socket cannot be connected.

Subclasses can override this method.

SocketReactor*
reactor()

Returns a pointer to the SocketReactor where this SocketConnector is registered.

The pointer may be null.

StreamSocket&
socket()

Returns a reference to the SocketConnector ‘s socket.