Pluggable Transport Interface classes

This chapter describes the classes of the Pluggable Transport Interface provided by VisiBroker for C++. For information on how to implement support for a transport protocol via the VisiBroker Pluggable Transport Interface, see the chapter “VisiBroker Pluggable Transport Interface” in the VisiBroker for C++ Developer's Guide.

VSPTransConnection

This class is the abstract base class for a connection class that must be implemented for each transport protocol that is to be plugged in to VisiBroker, to allow VisiBroker to work with that particular transport protocol. Each instance of the derived class will represent a single connection between a server and a client. VisiBroker will request instances of this class be created (via the corresponding factory class, see “virtual CORBA::Boolean waitNextMessage(CORBA::ULong _timeout) = 0;”) on both the client and server side of the ORB, whenever a new connection is required.

Include file

The vptrans.h file should be included to use this class.

VISPTransConnection methods

virtual void close() = 0;

To be implemented by the derived connection class. This method closes the connection in an orderly fashion. This method must be able to close the connection from either the client- or the server-side of a connection.

virtual void connect(CORBA::ULongLong _timeout) = 0;

To be implemented by the derived connection class. This method will be called by the client-side ORB, and must communicate with the remote peer’s ‘Listener’ instance to setup a new connection on the server-side. The function does not return any error code, but should throw exceptions if any transport layer errors occur. Any exception may be thrown, including a CORBA User Exception, as the exception will be thrown back to the client CORBA application. CORBA::TRANSIENT is one possible exception that could be thrown.

The timeout value is in specified in milliseconds. A value of 0 means no timeout (block forever), and this is the default value, which is used unless the timeout is set through the VisiBroker QoS policy system. If the transport does not support timeouts on connect, it still can be used successfully. In this case the connect call must always block until the connection is established or has failed.

Parameter	Description
_timeout	Timeout value to use, in milliseconds. 0 indicates no timeout (block forever).

virtual void flush() = 0;

To be implemented by the derived connection class. If this transport buffers data, this method should immediately send all data buffered for output, and block until the data is sent. Otherwise, there is nothing to be done and it can return immediately.

virtual IOP::ProfileValue_ptr getPeerProfile() = 0;

To be implemented by the derived connection class. This method should return a copy of the Profile describing the peer endpoint used in this connection. The copy must be created on the heap and the caller is responsible for releasing the used memory. The Profile does not describe the actual connection for this instance, but the Profile of the ‘Listener’ endpoint used during the ‘connect’ call.

virtual CORBA::Long id() = 0;

To be implemented by the derived connection class. This method must return a unique number for each connection instance. The ID only needs to be unique for this transport. It is used to lookup/locate a connection instance during request dispatching for this transport.

virtual CORBA::Boolean isBridgeSignalling() = 0;

To be implemented by the derived connection class. This method is used to indicate to the ORB which worker thread ‘cooling’ strategy is to be used. If the method returns 0 (FALSE), it means that the protocol plug-in itself is going to handle the re-reading of the connection after a request has been read. This is only possible if the plug-in is capable of doing a blocking read with timeout on the protocol endpoint. If it cannot or chooses not to, this method should return 1 (TRUE), and the transport bridge will notify the thread if another request becomes available or the when the timeout is reached. Note that thread cooling only occurs if a cooling time is configured for that protocol instance.

virtual CORBA::Boolean isConnected() = 0;

To be implemented by the derived connection class. This method should return 1 (TRUE), if the remote peer is still connected. If the connection was closed by the peer or any error condition exists that prevents the use of this connection, it must return 0 (FALSE).

virtual CORBA::Boolean isDataAvailable() = 0;

To be implemented by the derived connection class. This method should return 1 (TRUE), if data is ready to be read from the connection. Otherwise, it should return 0 (FALSE).

virtual CORBA::Boolean no_callback() = 0;

To be implemented by the derived connection class. This method indicates whether a connection of this transport can be used to reverse the client/server setup and call back to a servant in the client code. It should return 0 (FALSE) if it can not, which will cause the ORB to create a new connection for this kind of call, or 1 (TRUE) if it can.

This feature is provided to support Bi-Directional IIOP, that was introduced in GIOP-1.2. See the CORBA specification for details.

virtual void read(CORBA::Boolean _isFirst, CORBA::Boolean _isLast, char* _data, CORBA::ULong _offset, CORBA::ULong _length, CORBA::ULongLong _timeout)= 0;

To be implemented by the derived connection class. This method reads data from the connection. It does not return any error code, but must signal transport related errors by throwing exceptions. The arguments describe a byte array with a given length that needs to be filled. This function must either fill the complete byte array successfully, timeout, or throw an exception.

The timeout parameter’s value defaults to 0 unless the user sets it through the VisiBroker QoS policies. A value of 0 indicates no timeout, and hence that the read should block forever waiting for data. Therefore, if this transport does not support timeouts on read/write, it still can be used successfully. In this case the read call must always block until all data has arrived.

Parameter	Description
_isFirst	TRUE if this is the first time data is being read from the connection.
_isLast	TRUE if this is the last time data is being read from the connection.
_data	Byte array to read data into.
_offset	Offset into the array at which to start storing the read data.
_length	The number of bytes of data to be read.
_timeout	Timeout value to use, in milliseconds. 0 indicates no timeout (block forever)

virtual void setupProfile(const char* prefix, VISPTransProfileBase_ptr peer) = 0;

To be implemented by the derived connection class. This method is used to tell a newly created client-side connection object what peer it should try to connect to in later steps (when connect() is called.) The given VISPTransProfileBase_ptr base class should be cast to the Profile class type of the particular transport and all member data in the connection should be initialized from that instance. A prefix string is also passed, for property lookup, in case additional property parameters need to be read.

Parameter	Description
prefix	String prefix of the form “vbroker.se.<SE_name>.scm.<SCM_name>” that the method can use to read any protocol-specific VisiBroker properties that may have been set to configure this instance.
peer	Profile for the Listening endpoint that this connection will connect to. Given as an instance of this protocol’s Profile class, passed as a pointer to the base VISPTransProfile class.

virtual CORBA::Boolean waitNextMessage(CORBA::ULong _timeout) = 0;

To be implemented by the derived connection class. This method should block the calling thread until either data has arrived on this connection or the given timeout (in milliseconds) has expired. It should return 1 (TRUE) if data is available, or 0 (FALSE) if not. Note that a value of 0 for the _timeout parameter should never occur (as in this case the ORB should not call this method). Therefore receiving this value should be handled as an error, perhaps by logging an error message.

Parameter	Description
_timeout	Maximum amount of time to wait for a message (in seconds). 0 means wait forever.

virtual void write(CORBA::Boolean _isFirst, CORBA::Boolean _isLast, char* _data, CORBA::ULong _offset, CORBA::ULong _length, CORBA::ULongLong _timeout) = 0;

To be implemented by the derived connection class. This method sends data through the connection to the remote peer. It does not return any error code, but must signal transport related errors by throwing exceptions. The arguments describe a byte array with a given length that needs to be sent. This function must either send the complete byte array successfully, timeout, or throw an exception. The timeout parameter’s value defaults to 0 unless the user sets it through the VisiBroker QoS policies. A value of 0 indicates no timeout, and hence that the write should block forever waiting for data. Therefore, if this transport does not support timeouts on read/write, it still can be used successfully. In this case the write call must always block until all data has arrived.

Parameter	Description
_isFirst	TRUE if this is the first time data is being sent through the connection.
_isLast	TRUE if this is the last time data is being sent through the connection.
_data	Byte array of data that needs to be sent.
_offset	Offset from the array into which to start storing the read data.
_length	The number of bytes of data to be sent.
_timeout	Timeout value to use, in milliseconds. 0 indicates no timeout (block forever)

VISPTransConnectionFactory

This class is the abstract base class for a connection factory class that must be implemented for each transport protocol that is to be plugged in to VisiBroker, to allow VisiBroker to work with that particular transport protocol. A singleton instance of the derived class is registered with VisiBroker, via the “VISPTransRegistrar” class. The ORB calls the connection factory object to create instances of the connection class of the associated transport. The connection class is the corresponding class derived from class “VSPTransConnection”.

Include file

The vptrans.h file should be included to use this class.

VISPTransConnectionFactory methods

VISPTransConnection_ptr create(const char* prefix) = 0;

To be implemented by the derived connection factory class. This method creates a new instance of the corresponding connection class and returns the pointer to it cast to the base class type. The caller is responsible for the destruction of the instance when it is no longer required.

Parameter	Description
prefix	String prefix of the form “vbroker.se.<SE_name>.scm.<SCM_name>” that the method can use to read any protocol-specific VisiBroker properties that may have been set to configure the connection factory.

VISPTransListener

This class is the abstract base class for a listener factory that must be implemented for each transport protocol that is to be plugged in to VisiBroker, to allow VisiBroker to work with that particular transport protocol. Instances of the derived class are created each time a Server Engine is created that includes Server Connection Managers (‘SCMs’) that specify the particular transport protocol. One instance is created per SCM instance that specifies the protocol. The listener instances are used by the server-side ORB to wait for incoming connections and requests from clients. New connections and requests on existing connections are signaled by the listener to the ORB via the Pluggable Transport Interface’s Bridge class (see “VISPTransBridge”). When a request is received on an existing connection, the connection goes through a ‘Dispatch Cycle’. The Dispatch Cycle starts when the connection delivers data to the transport layer. In this initial state, the arrival of this data must be signaled to the ORB via the Bridge and then the Listener ignores the connection until the Dispatch process is completed (in the mean time, the connection is said to be in the ‘dispatch state’). The connection is returned to the initial state when the ORB makes a call to the Listener’s completedData() method. During the dispatch state the ORB will read directly from the connection until all requests are exhausted, avoiding any overhead incurred by the Bridge-Listener communication. In most cases, the transport layer uses blocking calls that wait for new connections. In order to handle this situation, the Listener should be made a subclass of the class VISThread and start a separate thread of execution that can be blocked without holding up the whole ORB.

Include file

The vptrans.h file should be included to use this class.

VISPTransListener methods

virtual void completedData(CORBA::Long id) = 0;

To be implemented by the derived listener class. This method is called when the ORB has completed reading a request from the connection with the given id and wants the Listener once again to signal any new incoming requests on that connection (via the Bridge).

Parameter	Description
id	Id of the connection that may once again be listened on.

virtual void destroy() = 0;

To be implemented by the derived listener class. This method instructs the Listener instance to tear down its endpoint and close all related active connections.

virtual IOP::ProfileValue_ptr getListenerProfile() = 0;

To be implemented by the derived listener class. This method should return the Profile describing the Listener instance’s endpoint on this transport. The returned Profile should be a copy on the heap and the caller (the ORB) takes over memory management of it.

virtual CORBA::Boolean isDataAvailable(CORBA::Long id) = 0;

To be implemented by the derived connection factory class. This method should return 1 (TRUE), if the connection with the given Id has data ready to be read. Returns 0 (FALSE) otherwise. Normally the call should just be forwarded to the transport layer to find out.

Parameter	Description
id	Id of the connection that should be queried to see if data is available.

virtual void setBridge(VISPTransBridge* up) = 0;

To be implemented by the derived listener class. This method establishes the ‘link’ to the Pluggable Transport Bridge instance to be used by this Listener instance. The pointer it passes to the Listener should be stored to allow ‘upcalls’ to be made into ORB when necessary.

Parameter	Description
up	Pointer to the Pluggable Transport Bridge instance that the Listener instance should use to communicate with the ORB.

VISPTransListenerFactory

This class is the abstract base class for a listener factory class that must be implemented for each transport protocol that is to be plugged in to VisiBroker, to allow VisiBroker to work with that particular transport protocol. A singleton instance of the derived class is registered with VisiBroker, via the VISPTransRegistrar class. The ORB calls this object to create instances of the listener class of the associated transport. The listener class is the corresponding class derived from class VISPTransListener, as described in “VISPTransListener”.

Include file

The vptrans.h file should be included to use this class.

VISPTransListenerFactory methods

VISPTransListener_ptr create(const char* propPrefix) = 0;

To be implemented by the derived listener factory class. This method creates a new instance of the corresponding listener class and returns the pointer to it cast to the base class type. The caller (the ORB) is responsible for the destruction of the instance when it is no longer required.

Parameter

Description

propPrefix

String prefix of the form “vbroker.se.<SE_name>.scm.<SCM_name>” that the method can use to read any protocol-specific VisiBroker properties that may have been set to configure the listener instance or the particular listener instance that is being created. Note that the factory can pass the prefix into the constructor of the listener instance it is creating, to allow it to read properties itself. This would require the derived listener class to have a constructor that takes the prefix as a parameter.

VISPTransProfileBase

class VISPTransProfileBase : public GIOP::ProfileBodyValue, public CORBA_DefaultValueRefCountBase

This class is the abstract base class for a Profile class that must be implemented for each transport protocol that is to be plugged in to VisiBroker, to allow VisiBroker to work with that particular transport protocol. This class provides the functionality to convert between a transport specific endpoint description and an CORBA IOP based IOR that can be exchanged with other CORBA implementations. It is also used during the process of binding a client to a server, by passing a ProfileValue to a ‘parsing’ function that has to return TRUE or FALSE, to determine whether a particular IOR is usable for this transport or not. An instance of the derived Profile class is frequently passed to functions via a pointer to its base class type. In order to support safe runtime downcasting with any C++ compiler, a ‘_downcast’ function must be provided that can test if the cast is legal or not.

Include file

The vptrans.h file should be included to use this class.

VISPTransProfileBase methods

static GIOP::ObjectKey* convert(const PortableServer::ObjectId& seq);

Converts octet sequence representation of an Object Key into the in-memory representation.

Parameter	Description
seq	Octet sequence version of Object Key, to be converted into in-memory representation.

void object_key(GIOP::ObjectKey_ptr k);

Set the Object Key for this Profile instance.

Parameter	Description
k	Object Key.

GIOP::ObjectKey_var object_key() const;

Get the Object Key for this Profile instance.

void version(const GIOP::Version& v);

Set the GIOP version for this Profile.

Parameter	Description
v	GIOP Version.

GIOP::Version& version();

Get the GIOP version of this Profile.

const GIOP::Version& version() const;

Get the GIOP version of this Profile.

static const VISValueInfo& _info();

Get the VisiBroker ValueInfo for this Profile type.

VISPTransProfileBase members

static const VISValueInfo& _stat_info;

Stores the VisiBroker ValueInfo for this particular Profile type.

VISPTransProfileBase base class methods

IOP::ProfileValue_ptr copy()

To be implemented by the derived listener factory class. This method should make an exact copy on the free store and return a pointer to it. It is good coding practice to use the copy constructor inside of this function.

CORBA::Boolean matchesTemplate(IOP::ProfileValue_ptr body);

To be implemented by the derived Profile class. This method should return 1 (TRUE) if there is an IOR in the given data, that can be used to connect through this transport. Otherwise return 0 (FALSE).

Parameter	Description
body	Profile to be checked, to see if it can be used by this transport.

IOP::ProfileId tag()

To be implemented by the derived Profile class. This method should return the unique tag value for this Profile.

IOP::TaggedProfile* toTaggedProfile();

To be implemented by the derived Profile class. This method should return a tagged (stringified) Profile instance created with the values read from this instance’s member data.

static VISPTransProfileBase* _downcast(CORBA::ValueBase* vbptr);

To be implemented by the derived Profile class. Function to downcast a base class pointer to an instance of this Profile class.

Parameter	Description
vbptr	Profile instance passed as base Value type pointer.

virtual void* _safe_downcast(const VISValueInfo &info) const;

To be implemented by the derived listener factory class. Virtual method called by ORB during downcast, to check type info data.

Parameter	Description
info	VisiBroker Value Info for this Profile type.

VISPTransProfileFactory

This class is the abstract base class for a Profile factory class that must be implemented for each transport protocol that is to be plugged in to VisiBroker, to allow VisiBroker to work with that particular transport protocol. A singleton instance of the derived class is registered with VisiBroker, via the VISPTransRegistrar class. The ORB calls this object to create instances of the Profile class of the associated transport. The Profile class is the corresponding class derived from class VISPTransProfileBase, as described in “VISPTransProfileBase”.

Include file

The vptrans.h file should be included to use this class.

VISPTransProfileFactory methods

IOP::ProfileValue_ptr create(const IOP::TaggedProfile& profile)

Read the tagged IOR and create a Profile describing a Listener endpoint.

Parameter	Description
profile	CDR encoded IOR to be read.

CORBA::ULong hash(VISPTransProfileBase_ptr prof);

Support the optimized storage of profiles in a hashed lookup table by calculating a hash number for the given instance. Return 0 if you do not provide hash values.

Parameter	Description
prof	Profile instance to produce hash value for.

IOP::ProfileId getTag();

Return the unique Profile Id tag for the type of Profile created by this factory.

VISPTransBridge

This class provides a generic interface between the transport classes and the ORB. It provides methods to signal various events occurring in the transport layer.

Include file

The vptrans.h file should be included to use this class.

VISPTransBridge methods

CORBA::Boolean addInput(VISPTransConnection_ptr con);

Send a connection request to the ORB through the bridge, by passing a pointer to the Connection instance representing the Listener endpoint. The returned flag signals whether the ORB has accepted the new connection (returns 1 (TRUE)) or refused it (returns 0 (FALSE)). The latter might happen due to resource constraints or due to a restriction on connections (set up through the property system).

Members	Description
con	Connection object representing the Listener endpoint you wish to connect to.

void signalDataAvailable(CORBA::Long conId);

Passes the connection id to the ORB of a connection that just got new data from the transport layer. This will start the dispatch cycle for incoming requests.

Members	Description
conId	Connection Id of connection you want to indicate data is available on.

void closedByPeer(CORBA::Long conId);

Tell the ORB that the connection with the given id was closed by the remote peer.

Members	Description
conId	Connection Id of the connection you want to indicate was closed by the remote peer.

VISPTransRegistrar

This class must be used to register a new transport with the ORB. The protocol name string given during registration is used as identifier of this transport and must be unique in the scope of that ORB. It is also used as a prefix in the name string of properties related to this transport.

Include file

The vptrans.h file should be included to use this class.

VISPTransRegistrar methods

static void addTransport(const char* protocolName, VISPTransConnectionFactory* connFac, VISPTransListenerFactory* listFac, VISPTransProfileFactory* profFac);

Register the protocol name string and the three Factory instances used to create specific classes for this transport. This method is static and can therefore be called at any time during the initialization of the ORB.

Members	Description
protocolName	Name to be used to identify this transport protocol.
connFac	Pointer to singleton instance of the connection factory.
listFac	Pointer to singleton instance of the listener factory.
profFac	Pointer to singleton instance of the profile factory.