Poco::RemotingNG

class Transport

File Information

Library: RemotingNG
Package: Transport
Header: Poco/RemotingNG/Transport.h

Description

Transport objects are responsible for setting up and maintaining a network (or other kind of) connection between Proxy objects on the client side and Listener objects on the server side, and for exchanging messages over that connection.

A Transport object also maintains Serializer and Deserializer objects.

Transport objects must support two message exchange patterns (MEP):

  • One-Way: a message is sent from the client to the server and the client does not expect to receive a reply from the server. With this pattern, the server has no way to provide status information back to the client, and the client has no way to know whether the call was successful.
  • Request-Reply: a message is sent from the client to the server and the client expects to receive a reply from the server. The reply may be a regular reply containing a return value and/or output parameters, or it may be a fault message, reporting an exception to the client.

Provided a Transport object is already connected, sending a one-way message is a three-step process:

  1. A new one-way message is started with a call to beginMessage(). This will prepare the Transport to deliver a one-way message to the server, as well as setting up a Serializer for creating the one-way message.
  2. The Serializer returned by beginMessage() is used to compose the actual message.
  3. The one-way message is delivered to the server with a call to sendMessage(). This completes the message exchange.

Doing a request-reply message exchange is a five-step process.

  1. A new request message is started with a call to beginRequest(). This will prepare the Transport to deliver a request message, as well as setting up a Serializer for creating the request message.
  2. The Serializer returned by beginRequest() is used to compose the actual message.
  3. The request is delivered to the server with a call to sendRequest(). After delivering the request, sendRequest() will wait for a reply from the server, and set up a Deserializer for reading the reply.
  4. The reply message is read using the Deserializer returned by sendRequest().
  5. A call to endRequest() ends the message exchange.

Transport objects must be able to deal with incomplete message exchange sequences. For example, if an exception occurs between a call to beginRequest() and the corresponding call to sendRequest(), sendRequest() and endRequest() will not be called for this exchange. When beginRequest() or beginMessage() is called the next time, it must do the necessary cleanup to reset the Transport object to a well-defined state.

Inheritance

Direct Base Classes: AttributedObject, Poco::RefCountedObject

All Base Classes: Poco::RefCountedObject, AttributedObject

Known Derived Classes: Poco::RemotingNG::HTTP::Transport, Poco::RemotingNG::JSONRPC::Transport, Poco::RemotingNG::TCP::Transport, Poco::RemotingNG::REST::Transport, Poco::RemotingNG::SOAP::Transport

Member Summary

Member Functions: beginMessage, beginRequest, connect, connected, disconnect, endPoint, endRequest, lock, sendMessage, sendRequest, unlock

Inherited Functions: clearAttributes, countAttributes, duplicate, enumerateAttributes, getAttribute, hasAttribute, operator =, referenceCount, release, removeAttribute, setAttribute

Types Aliases

NameValueMap

using NameValueMap = std::map < std::string, std::string >;

Ptr

using Ptr = Poco::AutoPtr < Transport >;

Constructors

Transport

Transport();

Creates a Transport.

Destructor

~Transport virtual

virtual ~Transport();

Destroys the Transport.

Member Functions

beginMessage virtual

virtual Serializer & beginMessage(
    const Identifiable::ObjectId & oid,
    const Identifiable::TypeId & tid,
    const std::string & messageName,
    SerializerBase::MessageType messageType
) = 0;

Prepare a one-way message and set up a Serializer for writing the request.

The messageType should be MESSAGE_REQUEST or MESSAGE_EVENT. Whether this is checked is up to the actual implementation.

Returns a Serializer for composing the message.

No response message will be sent back for a one-way request.

beginRequest virtual

virtual Serializer & beginRequest(
    const Identifiable::ObjectId & oid,
    const Identifiable::TypeId & tid,
    const std::string & messageName,
    SerializerBase::MessageType messageType
) = 0;

Prepare a two-way (request - reply) message exchange and set up a Serializer for writing the request.

The messageType should be MESSAGE_REQUEST or MESSAGE_EVENT. Whether this is checked is up to the actual implementation.

Returns a Serializer for composing the request message.

connect virtual

virtual void connect(
    const std::string & endPoint
) = 0;

Connects the transport to the given endpoint.

The format of the endpoint is specific to the Transport. Some Transport implementations may accept a complete URI as endpoint.

connected virtual

virtual bool connected() const = 0;

Returns true iff the Transport is connected to a Listener, false otherwise.

disconnect virtual

virtual void disconnect() = 0;

Disconnects the transport.

endPoint virtual

virtual const std::string & endPoint() const = 0;

Returns the endpoint to which this Transport is connected. If not connected, an empty string will be returned.

endRequest virtual

virtual void endRequest() = 0;

Ends a request - reply message exchange.

lock inline

void lock();

Locks the Transport's mutex.

sendMessage virtual

virtual void sendMessage(
    const Identifiable::ObjectId & oid,
    const Identifiable::TypeId & tid,
    const std::string & messageName,
    SerializerBase::MessageType messageType
) = 0;

Deliver the one-way message to the server and complete the message exchange.

All parameters must have the same value as the parameters passed to beginMessage(). If not, the behavior is undefined.

sendRequest virtual

virtual Deserializer & sendRequest(
    const Identifiable::ObjectId & oid,
    const Identifiable::TypeId & tid,
    const std::string & messageName,
    SerializerBase::MessageType messageType
) = 0;

Deliver the request message to the server, wait for a response and prepare a Deserializer for reading the reply.

All parameters must have the same value as the parameters passed to beginRequest(). If not, the behavior is undefined.

Returns a Deserializer for reading the reply message.

unlock inline

void unlock();

Unlocks the Transport's mutex.