Creating Custom Communication Points

Types of Custom Communication Points

Custom Communication Points are composed of at least of two classes:

• The Custom Communication Point class itself.
• A connection class that represents individual connections.

The Communication Point class delegates to the connection class the creating of an instance of a communications connection.  You could thus end up with multiple instances of the connection class if you have multiple connections, one instance per connection.  Connections are responsible for actually sending and receiving messages over their specific communication channel.

Connection creation is delegated via the Communication Point class getConnection() method.  However, this class does not handle tear down and destruction of connection classes, it only handles the setup side of things.  For this reason we do not keep references to connections inside the Communication Point class. Hence the Rhapsody engine will call getConnection() against the Communication Point class to create a connection, the engine will maintain a reference to the connection, and to drop the connection will call dropConnection() and cleanup() directly against the connection, not against the Communication Point class.  So do not think of the Communication Point class as a wrapper around connections.

All custom communication points extend AbstractCommunicationPoint which requires you to implement the getConnection() method. The getConnection() method creates a connection instance which is an instance of CommunicationPointConnection. Your connection class then implements the CommunicationPointConnection interface.

There are three variations of the Connection class:

• CommunicationPointConnection interface – is applicable to a blocked input type in which you have to implement a receiveMessage(Message) method that blocks until a message is available or some time-out has occurred.  Hence the Rhapsody Engine will call your receiveMessage as soon as it can and then the method will block until you can return a message.  As soon as you return a message, the engine can call the method again to await the next message. It is similar to a blocked read that you may be familiar with from socket programming and you may end up actually wrapping such a read method if you are writing a TCP communication point.

• PollingInputConnection interface – is a child of CommunicationPointConnection, but additionally requires implementation of the PollingInputConnection.isInputAvailable() method.  For this type of connection, the Rhapsody Engine will call (poll) your connection at regular intervals (getRefreshDelay() to determine if a message is available.  To do this it calls isInputAvailable().  If there is a message available you return a true value after which the Rhapsody Engine then calls the receiveMessage which returns the waiting message to Rhapsody. The Rhapsody Engine will then start polling isInputAvailable() to await the next message.

• SingleConnectionCommunicationPoint interface – allows one connection, obviating issues of synchronization (if they are an issue for you) that can occur with bi-directional communications. In bi-directional communications there is no relationship between input and output messages and messages can be received and sent at will on any thread or connection. With a SingleConnectionCommunicationPoint all traffic passes through the same class (like a singleton). This can also be useful if your code shares resources in a non-thread safe way, or has other issues with thread-safety.

Operational Modes

From Rhapsody IDE, you can choose a set of operational modes for a communication point. These are Input, Output, Bi-directional, In->Out, Out->In.

Within your implementation, you must support a single SupportedMode, which are named slightly differently:

You can only implement one of the above modes. Thus:

• If you only want to allow INPUT, then you must implement SupportedMode.INPUT.
• If you only want to allow OUTPUT, then you must implement SupportedMode.OUTPUT.
• If you want to allow INPUT or OUTPUT, then you implement SupportedMode.UNIDIRECTIONAL.
• If you want to allow  INPUT or OUTPUT or OUT-IN orIN-OUT then you implement SupportedMode.TWO_WAY.
• If you want to allow any mode of operation, then you implement SupportedMode.BIDIRECTIONAL.  Even though the SupportedMode is labeled BIDIRECTIONAL, it includes all the other possible modes – in other words, it is then down to your code to do a bit of "if-then-else" to configure its behavior according to what the user chooses on the drop-down list for communication point configuration mode in the Rhapsody IDE.

Relationship between Mode and Type

Operational mode does not specify type of protocol your communication point is implementing:

• A Blocking type
• A Polling type
• A Singleton type

On the other hand, type dictates the appropriate connection type or mode of operation. A bi-directional communication point, for example, could use polling on its input side or it could use blocked read.

Threading Considerations

When the communication point is running in BIDIRECTIONAL mode, there are separate threads calling the sendMessage(Message) and receiveMessage(Message) methods of the communication point connections. So the methods must be either completely independent of each other (which is the common case) or written in a thread-safe way (for example, using synchronized blocks with shared resources).

If the communication point is running in INPUT, OUTPUT or OUT_IN mode, then there will only be one thread using any one connection for both send and receive activities so you do not need to synchronize access within the class to member data.

If you want to ensure that your communication point can only ever have one connection at a time, you can implement the SingleConnectionCommunicationPoint interface. This interface does not define any methods – it simply indicates to the engine that this communication point may only be configured to use one connection at a time.