Poco::Net

template < class ServiceHandler >

class SocketConnector

Library: Net
Package: Reactor
Header: Poco/Net/SocketConnector.h

Description

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, SocketReactor& 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.

Member Summary

Member Functions: createServiceHandler, onConnect, onError, onReadable, onWritable, reactor, registerConnector, socket, unregisterConnector

Constructors

SocketConnector inline

explicit SocketConnector(
    const SocketAddress & address
);

Creates a SocketConnector, using the given Socket.

SocketConnector inline

SocketConnector(
    const SocketAddress & address,
    SocketReactor & reactor,
    bool doRegister = true
);

Creates an connector, using the given ServerSocket. The SocketConnector registers itself with the given SocketReactor.

Destructor

~SocketConnector virtual inline

virtual ~SocketConnector();

Destroys the SocketConnector.

Member Functions

onConnect inline

void onConnect();

onError inline

void onError(
    ErrorNotification * pNotification
);

onReadable inline

void onReadable(
    ReadableNotification * pNotification
);

onWritable inline

void onWritable(
    WritableNotification * pNotification
);

registerConnector virtual inline

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.

unregisterConnector virtual inline

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.

createServiceHandler protected virtual inline

virtual ServiceHandler * createServiceHandler();

Create and initialize a new ServiceHandler instance.

Subclasses can override this method.

onError protected virtual inline

virtual void onError(
    int errorCode
);

Called when the socket cannot be connected.

Subclasses can override this method.

reactor protected inline

SocketReactor * reactor();

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

The pointer may be null.

socket protected inline

StreamSocket & socket();

Returns a reference to the SocketConnector's socket.