[Jboss-cvs] JBoss Messaging SVN: r1228 - branches/Branch_1_0/docs

Tue Aug 22 14:43:21 EDT 2006

Author: ovidiu.feodorov at jboss.com
Date: 2006-08-22 14:43:19 -0400 (Tue, 22 Aug 2006)
New Revision: 1228

Removed:
   branches/Branch_1_0/docs/JBossMQConfiguration.sxd
   branches/Branch_1_0/docs/JBossMessagingClientSide.sxd
   branches/Branch_1_0/docs/JBossMessagingConsumer.sxd
   branches/Branch_1_0/docs/JBossMessagingCore.txt
   branches/Branch_1_0/docs/JBossMessagingCoreGraphics.sxd
   branches/Branch_1_0/docs/JBossMessagingJMSFacade-MessageConsumer.sxd
   branches/Branch_1_0/docs/JBossMessagingJMSFacade.sxd
   branches/Branch_1_0/docs/JBossMessagingJMSFacade2.sxd
Log:
removed obsolete diagrams

Deleted: branches/Branch_1_0/docs/JBossMQConfiguration.sxd
===================================================================
(Binary files differ)

Deleted: branches/Branch_1_0/docs/JBossMessagingClientSide.sxd
===================================================================
(Binary files differ)

Deleted: branches/Branch_1_0/docs/JBossMessagingConsumer.sxd
===================================================================
(Binary files differ)

Deleted: branches/Branch_1_0/docs/JBossMessagingCore.txt
===================================================================

--- branches/Branch_1_0/docs/JBossMessagingCore.txt	2006-08-22 17:18:53 UTC (rev 1227)
+++ branches/Branch_1_0/docs/JBossMessagingCore.txt	2006-08-22 18:43:19 UTC (rev 1228)
@@ -1,195 +0,0 @@
-!!!Overview
-
-This document contains JBossMessaging server design notes. It starts by presenting general asynchronous messaging paterns that will be used for the server architecture and continues by describing individual "building blocks" which the server architecture will be based on. One of the goals of this document is to identify as many common elements as possible between two possible and independent server implementations:
-* __Serverful JMS (SFJMS)__ - the classical hub-and-spoke, where all message routing and persistence logic is implemented in the same address space of only one VM. The client code will interact with the client-side of the JMS runtime, which is responsible with establishing a connection to the server and providing the JMS functionality. The core of the server is located in the address space of only one VM.\\[SFJMS.png]
-* __Serverless JMS (SLJMS)__ - a distributed JMS provider architecture, that is built in top of the reliable multicasting capabilites of JGroups and its optimized for a high throughput LAN publisher-subscriber model. Since with JGroups the concept of central server doesn't exist anymore, the message routing and destination management functions will have to be implemented in a distributed manner, with "portions" of the server living in each client's VM. In this respect, the previous model in which the JMS client code and the JMS client-side runtime were co-located in the same VM and the server code was running in a completely different VM is replaced by a model in which the JMS client code, the JMS client-runtime and portions of the JMS server run-time are located together in the address space of the same VM.\\[SLJMS.png]
-
-
-
-Leaving aside perfomance considerations relative to different usage patterns, the two different server implementation should be equivalent from the client's point of view: all that JMS client code sees is a JMS 1.1 compliant provider.
-
-The first part of the document briefly presents the asynchronous messaging patterns used by the SFJMS/SLJMS implementations. The building blocks of the server architecture are presented next, followed by a series of use cases in which previously described building blocksare assembled and provide JMS-specific functionality.
-
-
-!!!Asynchronous Messaging Patterns
-
-!Message Channel
-
-Messaging application transmit data through ''Message Channels''. A ''Message Channel'' is a virtual unidirectional ''pipe'' than connects a producer of asynchonous messages to one or more consumers. A message sent by a producer is delivered to one, or more consumers. Two of the most known asynchronous messaging communication paradigms (Point-to-Point and Publish/Subscribe messaging) are in fact two different variations of this basic pattern, with different behaviors that will be insisted upon below.
-
-!Pipes and Filters
-
-''Pipes and Filters'' architectural style can be employed to divide a larger processing task into a sequence of smaller and independent processing steps. The processing steps are the ''filters'' that are connected via ''pipes''. In this particular case, the pipes can be thought as instances of simple ''Messaging Channels''. Aggregations of pipes such as ~BasicChannels (presented below) and filters (routers, loggers, etc) could lead to ''Message Channels'' with complex and configurable behavior. Both SFJMS and SLJMS will implement their message routing and persistence mechanisms based on a pipes and filters architecture.
-
-!Message Router
-
-A simple channel provides just very primitive routing capabilities: the channel's client sends a message to the channel and the channel guarantees that the message will be delivered to the receiver. More complex behaviors can be obtainted by interconnecting channels via ''Message Routers''. A ''Message Router'' is a device that accepts a message and synchronously sends it to one (or more than one, by message duplication) of its output channels.
-
-!Point-to-Point Channel
-
-The ''Point-to-Point Channel'' is a complex instance of a ''Message Channel'', which ensures that only one receiver (in case there are more than one receivers) consumes the message. The channel can have multiple receivers that can consume multiple messages concurrently, but only one of them can successfully consume a particular message. The receivers do not have to explicitely coordinate with each other; they become competing consumers and they are coordinated by the channel.
-
-If no recevier is connected to the channel at the moment the message is sent, the channel stores the message until at least one receiver connects, and then delivers the message.
-
-!Publish-Subscribe Channel
-
-The ''Publish-Subscribe Channel'' is a different instance of a ''Message Channel'' which broadcasts a message to ''all'' interested receivers. The channel takes care that each connected receiver is notified once and only once of a particular event. It works like this: its input channel splits into multiple output channels, one for each receiver. When an event is published on the channel, the ''Publish-Subscribe Channel'' delivers a copy of the message to each of the output channels. Each output channel has only one subscriber, which is allowed to consume a message only once. It this way, each subscriber gets the message only once and consumed copies disapear from the channel.
-
-By default, a ''Publish-Subscribe Channel'' doesn't deliver messages to subscribers that are not connected at the moment the channel receives the message for delivery. If a subscriber is interested to receive the messages that othewise it would have missed, it could register as a ''Durable Subscriber''. In this case the channel will "keep" the messages until the subscriber connects and then deliver the messages to it. As presented in the upcoming sections, it is very natural to implement this behavior using the right combination of basic channels and routers.
-
-!Guaranteed Delivery
-
-One of the main advantages of an asynchronous delivery system over a RPC-based system is that the sender, the network and the reciever do not have to be working at the same time. If the network is down, the messaging provider stores the message until the connection is restored and the message can be forwared. The same thing happens if the receiver is down. This is the ''store-and-forward'' process the messaging is based on. However, if the messages are only stored in memory, they are subject to the VM or system crash.
-
-The ''Guaranteed Delivery'' pattern makes sure that messages survive a VM or system crash. The messaging system uses a built-in datastore to persist messages. The key of the pattern is that a send operation does not sucessfully complete until the message is safely persisted in the datastore. Subsequently, the message is not deleted from the datastore until it is successfully forwarded and stored in the next datastore.
-
-Persistence increases the reliability, but comes at the expense of performance.
-
-!!!Server Design
-
-The implementation of the JMS Provider's core is based on the concepts of Receiver and Channel. Each of these is represented by a Java interface. Various implementations of these interfaces are combined to provide the functionality specific to a Point-to-Point messaging domain (queues) and Publish/Subscribe messaging domain. The semantics of these interfaces, as described below, remains valid both in a serverful and a serverless (distributed) context.
-
-!!Message
-
-A Message represents an atomic, self contained unit of data that flows through the system. A Message must be serializable, since there are situations when a Message must be sent over a network connection between two distributed components of the messaging system (a Channel and a remote output Receiver). The Message supports the concept of message header. Various messaging system components can attach or remove headers to/from the message, primarily for message flow management purposes.
-
-The Message does not have the concept of message address, though. The core of the message system is an assembly of Channels and Receivers that routes a message "flowing" through it, by inforcing a certain "path" resulted from its configuration.
-
-!!Receiver
-
-A component that handles Messages. Handling could mean consumption or synchronous/asynchronous forwarding to another Receiver(s). The Java interface that defines a Receiver has only one single method:
-
-{{{
-public interface Receiver
-{
-    public boolean handle(Message message);
-
-}
-}}}
-
-Upon receiving a Message, a Receiver could consume the message, could store it or forward it to one or more Receivers. The Receiver interface doesn't enforce any message handling behavior; the behavior rather depends on a specific implementation. The Receiver interface makes sure though, that handling a message produces an unequivocal positive or negative ''acknowledgment''.
-
-
-If {{handle()}} returns {{true}} it means the {{Receiver}} acknowledges the message receipt and from that moment, it is solely responsible with the consumption/delivery of the message. The sender does not need to worry anymore about the message and it is sure that the receiver will do its best effort to insure the delivery. If {{handle()}} returns {{false}} it means the {{Receiver}} refused to handle the message. It is the sender's responsibility to decide if to re-attempt delivery or to give up.  When invoking this method, be prepared to deal with unchecked exceptions the Receiver may throw. This is equivalent with a negative acknowledgement, but the sender may also decide to remove this Receiver from its list and not attempt delivery to it anymore.
-
-!!Channel
-
-A Channel is a Receiver, in the sense that it accepts messages for handling, but it only forwards the messages, it cannot consume them. The Channel interface extends Receiver. The Channel's responsibility are:
-* To choose the output Receiver(s)
-* To forward the message, deciding whether to forward synchronously or asynchronously
-
-
-{{{
-public interface Channel extends Receiver {
-
-    public boolean deliver();
-    public boolean hasMessages();
-
-}
-}}}
-
-A Channel can have zero, one or more Receivers it can potentially forward messages to. They're called ''output'' Receivers. If there is more than one output Receiver, the Channel may deliver the message to none, one or more than one Receivers, according to the logic particular to a specific Channel implementation.
-
-The Channel always prefers synchronous delivery. If there is at least a Receiver connected to the Channel, and the Receiver is willing to accept the message (calling {{send()}} on it returns true), the Channel forwards the message on the same thread that performed the delivery and its {{send()}} method returns true.
-
-However, synchronous delivery is not always possible. The Channel may not have any output Receiver, or its Receivers may be unable to accept messages or "broken". In this situations, the Channel ''stores'' the Message locally, in the hope that delivery may become possible some time in the future. Storing the message automatically triggers positive acknowledgment. The Channel's {{send()}} method immediately returns true.
-
-The Channel attempts to deliver stored message when its {{deliver()}} method is called. The algorithm to choose the message destination depends on the Channel implementation. {{deliver()}} returns true if all messages have been delivered or false if there are still messages to be delivered after the calls completes. As an implementation detail, the asynchronous delivery can be triggered by an event such adding a new receiver, or there could be a background thread that tries to deliver from time to time if stored messages exist.
-
-The Channel implementations must allow for a way to force synchronous delivery. That is, if the Channel is declared synchronous, then {{send()}} either delivers synchronously or fails. In this situation the Channel never stores messages.
-
-
-!!The Relationship between a Channel and its Receivers
-
-An output Receiver ''never pulls'' a message from a Channel. It only declares its availability, should a message arrive, by registering to the Channel. The Receiver doesn't even know that is "associated" with
-a Channel. It's the Channel that ''pushes'' the message to its Receivers. For a messaging handling system build with Channels and Receivers, there is always a unidirectional flow of messages from the input to the output of the system.
-
-TODO: How to deal with the situation when a Receiver goes off-line (send() returns false) while the
-Receiver is still being connected to the Channel, and then goes back on-line (send() potentially
-returns true). There are two possibilities:
-# Polling (a Channel background thread)
-# The Receiver must somehow send a notification to the channel ... but this makes the Receiver aware of the Channel
-
-
-!!Distributor
-
-The Distributor interface provides a way to attach or detach output Receivers to/from a sender.
-
-{{{
-public interface Distributor {
-
-    public boolean add(Receiver receiver);
-
-    public boolean remove(Receiver receiver);
-
-    public boolean contains(Receiver receiver);
-
-    public Iterator iterator();
-
-    public void clear();
-
-    public boolean acknowledged(Receiver receiver);
-
-}
-}}}
-
-!!Routers
-
-A Router is a message handling component that sends a message ''synchronously'' to none, one, several or all of its Receivers. It this respect, a Router behaves pretty much like a Channel, with the only difference that it never behaves asynchronously. It never stores a message, it either routes is successfully to its Receivers or the ((handle()}} call fails, returning false. We introduced the concept of Router in addition to the concept of Channel especially to be able to easier encapsulate different "routing" algorithms. Routers are a natural candidate for the job of "routing delegate", used by a Channel to decide whom to send a message. A Router is a Receiver and a Distributor.
-
-Two very intuitive Router implementations are the ~PointToPointRouter, which synchronously routes a message by forwarding it to one and only one Receiver, and ~PointToMultipointRouter, which synchronously routes a message by duplicating it and forwarding it to all its Receivers. The first one is used to assemble a Queue, and the second one is used by a Topic, as we will see below.
-
-!!Same-Address-Space Primitives
-
-!Pipe
-
-A Pipe is a Channel with only one output. Only one receiver can be connected to a pipe at a time. Synchronous delivery is attempted, but if it is not possible, the pipe will hold the message. The asynchronous behaviour can be turned off by seting "synchronous" flag true. If the pipe is "synchronous" and the synchronous delivery fails, the overall delivery fails and the pipe won't hold the message.
-
-
-!!Destination (Queues and Topics)
-
-Both a Queue and a Topic have a common internal structure, which allows us to define a common ~AbstractDestination base class.
-
-[AbstractDestination.png]
-
-An ~AbstractDestination uses an input Pipe (a Channel with only one output Receiver), which is connected to a Router:
-* A Queue uses an asynchronous input Pipe connected to a ~PointToPointRouter
-* A Topic uses a synchronous input Pipe (remember that Channels can be forced to be synchronous) connected to a ~PointToMultipointRouter
-
-[PointToPointChannel.png]
-
-[PublishSubscribeChannel.png]
-
-A Topic with durable subscriptions can be very simply built by extending a regular Topic and inserting Pipes between the ~PointToMultipointRouter and the Topic's Receivers.
-
-
-!!Distributed Primitives
-
-!~DistributedPipe
-
-A distributed pipe is a channel with only one output, that spans accross two address spaces. It allows sending messages synchronously or asynchronously, in one direction, between two VMs. It is implemented with a pair of two distributed pipe endopoints (~PipeInput and ~PipeOutput).
-
-Multiple distributed pipes can share the same ~PipeOutput instance (and implicitly the pipeID), as long the ~PipeIntput instances are different.
-
-[DistributedPipe.png]
-
-
-!~ReplicatedPipe
-
-
-!!Distributed Destinations
-
-A ~DistributedQueuePeer is an extension of a stand-alone Queue, and similarly to its ancestor it lives in the address space of only one VM. However, one or more ~DistributedQueuePeers interact and coordinate into creating a ''distributed queue'' that spans multiple VM, where senders and receivers can be located on any of the participating VMs.
-
-The ~DistributedQueuePeer is similar in structure to a regular Queue, with the addition that for each remote peer, the DistributedQueuePeer's Router maintains a reference to a distributed synchronous output Pipe, which knows how to send a received message to its corresponding remote peer. This way, a message that is forwarded to the distributed Pipe (from the Router's point of view, is not different from a local delivery) goes to the ~DistributedQueuePeer and gets delivered remotely to one and only one Receiver.
-
-Care must be taken to avoid infinite loops, since each ~DistributedQueuePeer maintains references to each of its peers, so a message possibly can go from DQP1 to DQP2 and back to DQP1.
-
-A ~DistributedQueuePeer has two states: ''initialized'' and ''connected''. Calling connect() transitions the ~DistributedQueuePeer from the "initialized" to "connected" state. For the transition to succeed, the underlying JChannel must be connected, and this is a necessary, but not sufficient condition.
-
-[DistributedQueue.png]
-
-
------
-
-[Back to JBossMessagingDesign|JBossMessagingDesign]

Deleted: branches/Branch_1_0/docs/JBossMessagingCoreGraphics.sxd
===================================================================
(Binary files differ)

Deleted: branches/Branch_1_0/docs/JBossMessagingJMSFacade-MessageConsumer.sxd
===================================================================
(Binary files differ)

Deleted: branches/Branch_1_0/docs/JBossMessagingJMSFacade.sxd
===================================================================
(Binary files differ)

Deleted: branches/Branch_1_0/docs/JBossMessagingJMSFacade2.sxd
===================================================================
(Binary files differ)


