fulmine.distribution.channel
Interface IChannel

All Superinterfaces:

IDestroyable, ILifeCycle, IRetransmitter, IRpcTransmissionManager, ISubscriptionManager

All Known Implementing Classes:

Channel

public interface IChannel
extends ISubscriptionManager, IRetransmitter, IRpcTransmissionManager, ILifeCycle

A channel is an abstraction of a 2-way communication link between 2 IFrameworkContext instances. A channel is connected to another, single, peer channel in a remote context.

Each channel can subscribe for IContainer instances held in the peer channel's context. The subscription is received by the remote peer channel and handled. The remote peer channel then sends updates that occur to the subscribed container instances. The local channel receives these updates and applies them to the corresponding remote container instances in the local context. When the update is applied to the container, notifications occur so listeners can react to the changes (via the event distribution framework).

A channel can issue retransmission requests for individual remote containers or all currently subscribed remote containers.

A channel is dependent on an IConnection.

Channels exchange the following types of messages

1. A subscription message - sent by a channel that wants to receive data changes for specific containers. The containers are identified by the type and identity regular expression string in the message payload.
2. An unsubscribe message - sent by a channel that wants to cancel a subscription. The subscription is identified by the type and identity regular expression string in the message payload.
3. A data message - sent by a channel when a container changes that has been subscribed for by the remote peer channel. The message payload is the byte[] encapsulating the data changes for the container.
4. A retransmit container message - sent by a channel to request that the containers identified by the type and identity regular expression have their current complete state retransmitted.
5. A retransmit all message - sent by a channel to request retransmission of the current complete state of all currently subscribed containers.
6. A container created message - sent by a channel when a local container is created in the channel's context.
7. A container destroyed message - sent by a channel when a local container is destroyed in the channel's context.
8. A syn message - sent by a channel when it is started. The channel expects a syn_ack message from the peer channel. Until the syn_ack is received, the channel is not usable.
9. A syn_ack message - sent by a channel in response to receiving a syn message. This signals the remote peer channel that this channel is ready for communication and receiving subscriptions.
10. A destroy connection message - sent by a channel when it wants to close the connection; the peer channel will destroy its connection when it receives this message.
11. An invoke RPC message - sent from a channel by a context to invoke an RPC in the receiving context.

When 2 channels connect, they must both synchronise readiness with each other using the syn-syn_ack sequence. Only when a channel receives the syn_ack from the other channel, can the channel be used. This applies to both channels participating in a link between 2 contexts.

The message format between channels in ABNF is:

 message   = header ":" payload
 
 header    = ALPHA ; used to identify the message type
 payload   = data / identity
 data      = 1*(OCTET)
 identity  = 1*(ALPHA / DIGIT) 0*("|" (1*(ALPHA / DIGIT))) ; e1|e2|e3
 

Author:

Ramon Servadei

Field Summary

static String	DELIMITER The delimiter for segments in the payload
static String	MSG_CONTAINER_DESTROYED The header for a container destroyed message.
static String	MSG_DATA The header for a data message.
static String	MSG_DESTROY_CONNECTION The destroy connection message.
static String	MSG_INVOKE_RPC The header for an 'invoke RPC' message.
static String	MSG_RETRANSMIT The retransmit message header.
static String	MSG_RETRANSMIT_ALL The retransmit all message header.
static String	MSG_SUBSCRIBE The header for a subscribe message.
static String	MSG_SYN The synchronise message.
static String	MSG_SYN_ACK The synchronise acknowledge message.
static String	MSG_UNSUBSCRIBE The header for a unsubscribe message.

Method Summary

IConnection	getConnection() Get the channel's connection
String	getRemoteContextIdentity() Get the identity of the remote context this channel connects to

Methods inherited from interface fulmine.event.subscription.ISubscriptionManager

addListener, eventSourceCreated, eventSourceDestroyed, getListeners, getSubscribedSources, getSubscribedSources, includes, isSubscribed, removeListener, subscribe, unsubscribe

Methods inherited from interface fulmine.ILifeCycle

isActive, start

Methods inherited from interface fulmine.IDestroyable

destroy

Methods inherited from interface fulmine.distribution.IRetransmitter

requestRetransmit, requestRetransmitAll, retransmit, retransmitAll

Methods inherited from interface fulmine.rpc.IRpcTransmissionManager

invokeRpc

Field Detail

DELIMITER

static final String DELIMITER

The delimiter for segments in the payload

See Also:

Constant Field Values

MSG_SUBSCRIBE

static final String MSG_SUBSCRIBE

The header for a subscribe message. This identifies that the message is subscribing for data changes from the container described in the message payload. The container identity is the last argument so it may contain "|" characters; the decode algorithm only needs to split on the first two occurrences of "|" to get the three arguments. The message structure in ABNF is:

 subscribe-message = header ":" container
 
 header           = "su"
 container        = type "|" domain "|" identity
 type             = DIGIT
 domain           = DIGIT
 identity-regex   = 1*(ALPHA / DIGIT)
 

See Also:

Constant Field Values

MSG_UNSUBSCRIBE

static final String MSG_UNSUBSCRIBE

The header for a unsubscribe message. This identifies that the message is unsubscribing for data changes from the container described in the message payload. The container identity is the last argument so it may contain "|" characters; the decode algorithm only needs to split on the first two occurrences of "|" to get the three arguments. The message structure in ABNF is:

 unsubscribe-message = header ":" container
 
 header             = "un"
 container        = type "|" domain "|" identity
 type             = DIGIT
 domain           = DIGIT
 identity-regex     = 1*(ALPHA / DIGIT)
 

See Also:

Constant Field Values

MSG_DATA

static final String MSG_DATA

The header for a data message. This identifies that the message payload is some data from a remote container. The message structure in ABNF is:

 data-message = header ":" data
 
 header       = "da"
 data         = 1*(OCTET)
 

See Also:

Constant Field Values

MSG_CONTAINER_DESTROYED

static final String MSG_CONTAINER_DESTROYED

The header for a container destroyed message. This identifies the container type and identity of a destroyed container. The container identity is the last argument so it may contain "|" characters; the decode algorithm only needs to split on the first two occurrences of "|" to get the three arguments. The message structure in ABNF is:

 container-destroyed = header ":" container
 
 header           = "cd"
 container        = type "|" domain "|" identity
 type             = DIGIT
 domain           = DIGIT
 identity         = 1*(ALPHA / DIGIT)
 

See Also:

Constant Field Values

MSG_SYN

static final String MSG_SYN

The synchronise message. This has no header or body. This is sent by a channel to synchronise with the other one. The expected response is a MSG_SYN_ACK. The channels cannot communicate until they are synchronised. The message structure in ABNF is:

 synchronise-message = "syn";
 

See Also:

Constant Field Values

MSG_SYN_ACK

static final String MSG_SYN_ACK

The synchronise acknowledge message. This has no header or body. This is sent in response to a MSG_SYN and confirms the connection between two channels - they are synchronised. The message structure in ABNF is:

 synchronise-acknowledge-message = "ack"
 

See Also:

Constant Field Values

MSG_RETRANSMIT

static final String MSG_RETRANSMIT

The retransmit message header. This is sent by a channel to request retransmission of the identified container. The container identity is the last argument so it may contain "|" characters; the decode algorithm only needs to split on the first two occurrences of "|" to get the three arguments. The message structure in ABNF is:

 retransmit-message = header ":" container
 
 header           = "tx"
 container        = type "|" domain "|" identity
 type             = DIGIT
 domain           = DIGIT
 identity-regex   = 1*(ALPHA / DIGIT)
 

See Also:

Constant Field Values

MSG_RETRANSMIT_ALL

static final String MSG_RETRANSMIT_ALL

The retransmit all message header. This is sent by a channel to request retransmission of all containers that are subscribed to by the channel's context. The message structure in ABNF is:

 retransmit-all-message = "rtx"
 

See Also:

Constant Field Values

MSG_INVOKE_RPC

static final String MSG_INVOKE_RPC

The header for an 'invoke RPC' message. This includes the data necessary for the RPC to be invoked in the receiving context. The message structure in ABNF is:

 invoke-rpc = header ":" data
 
 header     = "ir" 
 data       = 1*(ALPHA / DIGIT) ; opaque byte array holding the RPC to invoke
 

See Also:

Constant Field Values

MSG_DESTROY_CONNECTION

static final String MSG_DESTROY_CONNECTION

The destroy connection message. This is sent by a remote channel to signal that the local channel should destroy its connection to the remote channel. The message structure in ABNF is:

 destroy-channel-message = "destroyconnection"
 

See Also:

Constant Field Values

Method Detail

getRemoteContextIdentity

String getRemoteContextIdentity()

Get the identity of the remote context this channel connects to

Returns:

a string for the identity of the remote IFrameworkContext

getConnection

IConnection getConnection()

Get the channel's connection

Returns:

the IConnection used by the channel