CommunicationPointConnection

CommunicationPointConnection defines the interface for communication point connections used by Rhapsody. Connections are returned by CommunicationPoint implementations and are responsible for actually sending and receiving messages over their specific communication channel.

There is no configure(Configuration) method in this interface. Any required configuration of a connection should be done by the parent CommunicationPoint when the connection is created.

There are a number of important conventions to be aware of when implementing a communication point connection:

It is expected that when a ConnectionException is thrown from any method, for any reason, that the state of the connection is set to ERROR and any other communication threads using the connection will throw a ConnectionFailedException the next time they attempt to use the connection. If this is not done it is possible (with a bidirectional comm point) to have a communication thread left running, with no way to stop it, and this makes the communication point impossible to stop.
It is expected that a connection will either be a PollingInputConnection with an effective implementation of the PollingInputConnection.isInputAvailable() method or has a receiveMessage(Message) method that blocks until a message is available or some time-out has occurred. It is possible to write an implementation that does not implement the PollingInputConnection interface and where receiveMessage(Message) immediately returns false if no message is available. Such an implementation will work correctly but will result in a busy loop (with the engine constantly calling receiveMessage(Message)) which will impact negatively on the performance of the Rhapsody server.

CommunicationPointConnection States

Enum class State:

UNCONNECTED - there is no connection yet
CONNECTED - It is currently connected.
CLOSED - Connection is closed.
ERROR - Error happened in the connection.

Method	Description
`int getId()`	Retrieves the identifier that identifies this connection. Should be unique amongst all connections from the same communication point, and must not change over the lifetime of the connection.
`dropConnection()`	Drops this connection if the connection is able to be dropped and later re-established. Will be called by the engine if the connection is doing output only, an idle time-out is specified and no message has been sent from the connection in that amount of time. If this connection is able to disconnect and reconnect at a later time then this method should disconnect and set the connections state to `UNCONNECTED`.
`reconnect()`	Reconnects this connection if required. Will be called by the engine if `sendMessage(Message)` is about to be called and the `getState()` returns `UNCONNECTED`. Will only be called after a previous call to `{@link #dropConnection}`. Exceptions: `ConnectionException` - if an error occurs reconnecting. `InterruptedException` - if interrupted while reconnecting.
`State getState()`	Gets the state of this connection. Must return one of: `CONNECTED`, `UNCONNECTED`, `ERROR` or `CLOSED`.
`cleanup()`	Cleans up after the connection has finished being used.
`finishComms()`	Signal to finish any communication taking place as soon as possible. Basically used to interrupt blocked receives.
`boolean receiveMessage(Message message)`	Gets a message from the connection. Must write any incoming message data to the body of the message. Returns true if a full message was successfully received, or false otherwise. Properties may also be set on the Message. Parameters: `message` - the message object to populate with the incoming data Exceptions: `ConnectionException` - if the connection failed during the receive. `MessageException` - if the connection failed to manipulate the message. `InterruptedException` - if the thread is interrupted while receiving a message.
`messageProcessed(boolean success)`	Notifies connection that the last received message has been received by the engine. Allows the connection to mark the message as processed so it is received again if successfully received, or to queue it again for receipt if it was not received. Parameters: `success` - whether the engine successfully received the message or not. Exceptions: `ConnectionException` - if the connection fails. `MessageProcessedFailedException` - if the message is failed to be marked as processed. `InterruptedException` - if the thread is interrupted while marking the message as processed.
`sendMessage(Message message)`	Sends a message over the connection. Should throw a `ConnectionException` if the connection fails and a `SendMessageFailedException` if the message is badly formed and therefore cannot be sent. It is important the correct exception is thrown at the correct time by implementations of this method. Parameters: `message` - the message to send. Exceptions: `ConnectionException` - if the connection fails during the send. `SendMessageFailedException` - if the message is badly formed and therefore cannot be sent. `InterruptedException` - if the thread is interrupted while sending a message. A `ConnectionException` will result in the connection being dropped. Rhapsody will automatically try to re-establish the connection and resend the message that was attempting to be sent when the connection failed. So if a badly formed message incorrectly causes a `ConnectionException` then you will get repeated errors until the communication point is forced to shut down. A `SendMessageFailedException` causes the message to be sent to the Error Queue but the connection is left open. So a bad connection which incorrectly results in a `SendMessageFailedException` will result in many messages being sent to the Error Queue. If this method returns without throwing an error Rhapsody assumes the message has been sent safely and will mark the message as sent.
`initSend()`	Initialises a connection to send a number of messages. Called immediately before multiple calls to `sendMessage(Message)` which are then followed by a call to `finishSend()`. So this method can be used to perform some function that is required to prepare the connection for sending messages. Exceptions: `ConnectionException` - if the connection fails. `InterruptedException` - if the thread is interrupted while initializing the sending operation.
`finishSend()`	Cleans up a connection after sending a number of messages. Called immediately after multiple calls to `sendMessage(Message)`. This method can be used to perform some function to clean up the connection after sending the message data. Note that Rhapsody regards a message as sent when `sendMessage(Message)` completes successfully so this method may not implement any code vital to the successful sending of the message. It is intended to be used for some routine task that only needs to be done once a connection has finished sending all messages queued for it but is not critical to the actual sending of the messages. Exceptions: `InterruptedException` - if the thread is interrupted while performing the send cleanup.

Save