VisiBroker for C++ API Reference Guide : RTCORBA::PriorityModelPolicy : Pluggable Transport Interface classes

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.
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.
TRUE if this is the first time data is being read from the connection.
TRUE if this is the last time data is being read from the connection.
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.
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.
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.
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.
TRUE if this is the first time data is being sent through the connection.
TRUE if this is the last time data is being sent through the connection.
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.
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).
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.
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.
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.
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.
void object_key(GIOP::ObjectKey_ptr k);
Set the Object Key for this Profile instance.
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.
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).
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.
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.
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.
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.
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).
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.
void closedByPeer(CORBA::Long conId);
Tell the ORB that the connection with the given id 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.