File Information
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 
explicit SocketConnector(
const SocketAddress & address
);
Creates a SocketConnector, using the given Socket.
SocketConnector
SocketConnector(
const SocketAddress & address,
SocketReactor & reactor,
bool doRegister = true
);
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
StreamSocket & socket();
Returns a reference to the SocketConnector's socket.