Class Protocol

All protocols inherit indirectly or directly from JavaGroups.JavaStack.Protocol. A Protocol defines the default behavior for all protocol layers, it for example sets up the incoming and outgoing queues, creates the two threads that pass messages between queues and maintains a reference to the layer above and below the current layer. All behavior can be overridden in subclasses, it is for example possible to write a protocol layer that does not use threads and queues altogether. The innards of a Protocol layer are shown in fig. 4.2.

  

Figure 4.2: Architecture of Protocol

Each protocol contains the following variables:

up_prot, down_prot

Each layer has a reference to the layer above and below it. If the down reference is null, it means that the layer is the bottommost layer in the stack (e.g. UDP). These are used to pass events up or down the stack.

stack

A reference to the ProtocolStack object itself. Layers used this to obtain information global to the stack. This field is deprecated and will be removed in a future release: events will be used instead to distribute information between protocol stack and individual layers. This breaks the dependence on ProtocolStack.

up_queue, down_queue

2 queues for storing messages from the layer below, to be processed and possibly passed on to the layer above, and for storing messages from the layer above, that are traveling downward.

up_handler, down_handler

2 threads handling the message passing in a layer. The up_handler removes messages from up_queue and calls method Up. This method may be overridden by subclasses of Protocol to process the message^4.5. The default Up method calls PassUp which in turn calls ReceiveUpEvent on its up_prot reference to the layer above it. ReceiveUpEvent just adds the message to the next layer's up_queue.

The processing for the down_handler is the same, except that messages travel down the stack. The 2 threads are started and stopped by methods StartInternal and StopInternal, which are called by the Configurator (see 4.1.5) when a stack is created and destroyed.

The 2 methods of Protocol that may need to be overridden in subclasses are Up and Down: layers will typically modify, reorder, or discard messages, and this is done in these 2 methods. Also important are methods PassUp and PassDown to forward a message to the layer above / below. They are typically called from with Up or Down to pass a message up/down the stack.

By overriding methods StartInternal and StopInternal, subclasses can govern the creation of the 2 threads: if both methods are empty, then no threads will be created, and the ReceiveUpEvent / ReceiveDownEvent methods will have to call Up / Down directly.

The default mechanism guarantees that messages are received in FIFO order, and that at most 1 down and 1 up message is handled in a protocol layer at the same time. Therefore, a message Q passed down the stack after P will never 'pass' P, i.e. if any layer receives both P and Q, then P will always be received before Q (unless a layer discards either or bother of the two messages).

There are 2 subclasses of Protocol: MessageProtocol (cf. 4.3.1) and RpcProtocol (cf. 4.3.2): whereas both enable peer communication between layers of different JChannel protocol stack instances, the former uses (synchronous) message passing to do so, while the latter employs (synchronous) remote method invocation.