Class Poco::Net::SocketConnector
Author: Applied Informatics Software Engineering GmbH and Contributors
Date: 2009-11-24

# 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, 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.

## Member Summary

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

## Constructors

### SocketConnector

explicit SocketConnector(
SocketAddress & address
);

Creates a SocketConnector, using the given Socket.

### SocketConnector

SocketConnector(
SocketAddress & address,
SocketReactor & reactor
);

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

## Destructor

### ~SocketConnector

virtual ~SocketConnector();

Destroys the SocketConnector.

## Member Functions

### onConnect

void onConnect();

### onError

void onError(
ErrorNotification * pNotification
);

### onReadable

void onReadable(
ReadableNotification * pNotification
);

### onWritable

void onWritable(
WritableNotification * pNotification
);

### registerConnector

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 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

virtual ServiceHandler * createServiceHandler();

Create and initialize a new ServiceHandler instance.

Subclasses can override this method.

### onError

virtual void onError(
int errorCode
);

Called when the socket cannot be connected.

Subclasses can override this method.

### reactor

SocketReactor * reactor();

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

The pointer may be null.

### socket

Socket & socket();

Returns a reference to the SocketConnector's socket.