|Consortium Projects Forge My OW2|
Dream Framework Library
Please send comments on this document to firstname.lastname@example.org. Authors would be glad to hear from people using or extending Dream.
Copyright 2003-2005 INRIA.
655 avenue de l'Europe, ZIRST, Montbonnot St Martin, 38334 Saint-Ismier Cedex, France.
All rights reserved.
All product names mentioned herein are trademarks of their respective owners.
1 IntroductionThis document presents the components available within the DREAM library. Readers are expected to have a good knowledge of the Fractal component model and of the DREAM core documentation .
The DREAM component library encompasses several components that implement the various functionalities required for building communication middleware. Among these components, we can find protocols, queues, channels, routers, etc.
2 QueuesThis section describes the various queues that are available within the DREAM library. These queues are located into the org.objectweb.dream.queue package. Queues are generally composite components following a common architectural pattern: they are made of a set of components that implement the various functionalities needed to build a queue. Each of these components exists in several versions that allow building queues with various characteristics: push vs. pull inputs/outputs, ordered vs. unordered, active vs. inactive.
We start this section with a description of this architectural pattern. Then, we describe the components found in this pattern. Finally we show how they are assembled to build queues.
2.1 Architectural patternThe architectural pattern followed by queues is depicted in figure 1. Queues encompass three main components:
2.2 BuffersBuffer components generally provides two interfaces: one to add messages, one to get or remove them. Multiple versions of these interfaces are provided. The simplest are org.objectweb.dream.queue.BufferAdd and org.objectweb.dream.queue.BufferRemove. Others interfaces allow for instance, to add or remove messages associated with a key.
Buffers provided in the org.objectweb.dream.queue package implement the org.objectweb.dream.queue.BufferAdd and org.objectweb.dream.queue.BufferRemove interfaces. These implementations differ on the ordering of the messages. Messages may be sorted according to their insertion order (BufferFIFO, BufferLIFO), according to a sequence number (BufferAscendingSequenceNumber), or according to a key that is generated for each added message (BufferSorting).
2.3 Incoming handlersIncoming Handlers provide a in-push interface and are responsible to add received messages in the buffer. They implements a specific overflow policy:
2.4 Outgoing handlersOutgoing Handlers provide a out-pull interface. When the pull method is called, a message is removed from the buffer and returned. Outgoing Handlers provide a specific policy when no message is available in the buffer (the buffer may not be empty if it implements an oderring):
2.5 Queue personalitiesA queue personality is an assembly of a buffer, two handlers and a pump if any (for instance: Push/Pull, FIFO , blocking input and non-blocking output). DREAM provides an easy way to use queue personalities in ADL.
The org.objectweb.dream.queue.PushPullQueue ADL describes a Push/Pull queue component containing a Buffer, an Incoming Handler, an Outgoing Handler and a shared Message Manager. It takes four arguments:
The ADL org.objectweb.dream.queue.PushPushQueueActive describes a Push/Push queue component containing a Buffer, an Incoming Handler, an Outgoing Handler, a Pump, a shared Message Manager and a shared Activity Manager. It takes four arguments:
2.6 Add hoc QueuesDREAM provides some specific monolithic queue implementations. They provides usual policies and have better performance than their generic equivalent (see dreamlib performance results).
3 AggregatorsThis section describes the aggregator components provided by the DREAM library. These aggregators are located in the org.objectweb.dream.aggregator package.
An aggregator allows to aggregate multiple messages into a single on. Various implementations are provided, the differences between these implementations are the way that messages are retrieves and how the aggregated message is produced.
The DREAM library provides three aggregators and one disaggregator.
4 ProtocolsProtocols components provides abstractions inspired by the Jonathan framework. These abstractions are mainly based on the Export/Bind pattern. A protocol exports interfaces and returns identifiers (exportId). Other protocols instances can bind explicitly or silently to the exported interface using the associated exportId.
Protocols component implementations provides different way to exchange messages and various non functional properties. The main message exchange paradigms are Message Channel and Message Passing.
4.1 Message Channel protocolsA message channel is a two way, point to point communication channel (typically a TCP socket). Message Channel protocols provides the following interface:
The export method exports a ChannelFactory interface and returns an exportId which uniquely identify the exported channel factory.
The ChannelFactory interface has the following definition:
The bind method of the ChannelProtocol interface creates a new communication channel between the client (the component which call the bind method) and the server (the component which has exported the ChannelFactory interface). This method takes as parameter the export identifier of the exported channel factory and the IncomingPush interface on which the client wants to receive messages sent by the server. The method returns a OutgoingPush interface on which the client can send messages to the server.
On the server side when the binding is established, the instantiate method of the exported ChannelFactory interface is called. The given OutgoingPush interface can be used to send message to the client. The method returns the a IncomingPush interface on which messages coming from the client will be passed.
Protocol components may handle multiple communication channels at a time, each of these are implemented by session components.
Session components have OutgoingPush interfaces to send messages down the protocol stack, and IncomingPush interfaces for messages going up the protocol stack.
On server side, Session factory components are responsible to create session components. These factory components are instantiated at export time (a session factory is associated with an exported ChannelFactory interface). On client side, session components are created at bind time by the protocol itself.
4.1.1 The TCP protocolThe TCP/IP protocol component uses TCP sockets to implement communication channel. The export operation creates a ServerSocket wrapped in a session factory component, allocates a task that listen for incoming connections, and returns an export identifier containing the local host name and the listening port of the server socket.
Figure3 is a sequence diagram of the simple use case depicted in figure2. This exmaple is a client/server distributed application where the Server Protocol exports a ChannelFactory and the Client Protocol binds to it and sends a message. These three steps are shown in figure3 by the orange numbers.
4.1.2 Multiplexing exportsExport multiplexer protocol allows to export multiple channel factory over a single lower level export. This allows for instance to share a single server socket over multiple protocol components.
The first time the export method of the export multiplexer protocol is called, the protocol exports its own channel factory to the lower level protocol. Then for each latter exports, the protocol allocates a unique number to the channel factory it is exporting, and returns an export identifier containing the unique number and the export identifier of its own exported channel factory (called the lower level export identifier).
The bind method calls the bind method of the lower level protocol giving the lower level export identifier. Then it sends as first message, the unique number contained in the export identifier. At server side, when the instantiate method of the channel factory exported by the export multiplexer protocol is called, a new session is created. When the session receives the first message, it retrieves the unique number it contains, and call the instantiate method of the channel factory associated with this number.
Figure5 is a sequence diagram of the simple use case depicted in figure4. This exmaple is a client/server distributed application where the two diffrent Server Protocols exports a ChannelFactory and the Client Protocol binds to one of them and sends a message. These four steps are shown by the orange numbers.
4.1.3 Multiplexing bindingsBinding multiplexer protocol allows to multiplex multiple communication channels over a single one. This is useful when multiple clients on the same JVM want to open communication channels to the same channel factory.
The export method simply creates a session factory which is exported using the lower level protocol. The returned export identifer is the export identifier returned by the lower level protocol.
The bind method looks if a channel has already been opened with the same export identifier. If it is not the case, a new session is created and bound through the lower level protocol. If a channel already exists, a special bind message is sent on it. When this message is received by the session on the server side, the instantiate method of the channel factory is called. Since sessions component multiplex multiple channels over a single one, a chunk containing an identifer is put in every outgoing messages allowing the remote session to deliver messages to the correct upper channel.
Figure7 is a sequence diagram of the simple use case depicted in figure6. This exmaple is a client/server distributed application where the Server Protocol exports a ChannelFactory and two different Client Protocols bind to it and one of them sends a message. These four steps are shown by the orange numbers.
4.2 Message Passing protocolsMessage passing protocols allows to open access points to a message bus, and to send or receive messages on/from it. These protocols in opposite to channel protocol are not connection oriented. This means that they do not provide a bind operation.
Message Channel protocols provides the following interface:
The export method opens a local access point and returns a MessagePassingOutgoingPush interface that can be used to send messages over the message bus. The given IncomingPush interface is the interface on which incoming messages will be passed.
The MessagePassingOutgoingPush interface as the following signature:
The outgoingPush can be used to send messages to remote sites identified by the given export identifier.
The getLocalExpotId method returns the identifier of the local access point. More precisely, if, on a remote site, a message is sent with this export identifier as destination, the message will be received by the local access point.
4.2.1 The UDP protocolThe UDP protocol component uses UDP socket to implement message bus access point.
The export operation creates a DatagramSocket wrapped in a session component, allocates a task that retrieves and pushes incoming messages (if the given IncomingPush interface is not null), and returns the MessagePassingOutgoingPush interface the session component provides.
The export identifiers this protocol handles, contain hostname and port of datagram sockets. So the getLocalExpotId method returns an export identifier containing the local hostname an the local port of the datagram sockets. The outgoingPush takes as destination an export identifier containing the hostname and the port of the remote datagram sockets.
The UPD Protocol implementation can also add to incoming messages an ExportIdentifierChunk containing the identifier of the sender of the message (see MessagePassingProtocol#FROM_CHUNK_NAME and UDPProtocol.export).
4.2.2 Message passing over channel protocolThis protocol is a bridge between the message passing abstraction an message channel. It provides a message passing protocol interface and uses a message channel protocol as lower level protocol.
This protocol allows for instance to use a message passing protocol over reliable TCP channels rather than UDP sockets.
The protocol manage a cache of channels. These channels are opened and closed transparently by the protocol.
The export operation creates a Session Manager compnent which provides the MessagePassingOutgoingPush interface and the ChannelFactory interface. This Session Manager is exported through the lower message channel protocol, the returned export identifier will be used as the local access point identifier.
The outgoingPush method of the Session Manager try to find if a channel is already open for the given destination.
Moreover, the size of the channels cache is limited, so if a channel must be opened to send a message, and the cache is full, a channel must be closed before opening a new one. The implementation manages a LRU list in which channels are moved to the head of this list each time they are used (for sending or receiving a message). When a channel must be closed, the Session Manager closes the channel at the tail of the list.
In some case two channels may be opened for the same destination. This may happend if two protocols exchange two messages at the same time, while no channel is already opened between these two protocols.
Lets take the example of two protocols (P1 and P2). Each one has opened an access point using its respective Message passing over channel protocol, these two access points will be called SM1 and SM2 (SM as Session Manager). At the same time, P1 sends a message to P2 and P2 sends a message to P1.
Since SM1 has no opened channel for SM2, it opens a new one (called C1). For the same reason, SM2 opens a channel to SM1 (called C2). In fact the instantiate method of SM2 may have already been called (since SM1 is opening a channel to SM2) but we suppose that it has not yet received the message containing the identifier of this new channel, so SM2 does not know that C1 is a channel for SM1 (this kind of channels is called anonymous channel).
At this time: for SM1, C1 is a channel to SM2 and C2 is an anonymous channel; and for SM2, C2 is a channel to SM1 and C1 is an anonymous channel.
SM1 pushes through C1 a message containing its identifier and the message P1 is sending. SM2 pushes through C2 a message containing its identifier and the message of P2.
When SM1 receives through C2 the identifier of SM2, it finds that it has already an opened channel for SM2 in its cache. Idem for SM2. SM1 and SM2 must choose a channel to close and they must be sure that no message is being transmited by the channel they will close.
Each one computes a hash of their identifiers and compares them. If the local identifier is lower than the remote one, the channel in the cache must be closed and replaced by the anonymous channel.
Lets supposes that the hash of the identifier of SM1 is lower than the hash of the identifier of SM2. So C1 must be closed and replaced by C2 in the cache of SM1. But to be sure that no message is being transmited in C1, SM1 does not close C1 directly. It sends through it a close message. When SM2 receives this message, it closes C1.
Finally SM1 and SM2 has a unique channel (C2) between them, which can be used to send messages from SM1 to SM2 and messages from SM2 to SM1.
Figure10 is a sequence diagram of the simple use case depicted in figure9. This exmaple is a peer-to-peer distributed application where the Protocol components export an access point and exchange two messages. These different steps are shown by the orange numbers.
4.2.3 Buffering protocolsBuffering protocols allow to decouple execution flow from message flow. They can decouple incoming or outgoing messages. Decoupled messages are put in a waiting list and sent by an independent task.
4.2.4 Fragmentation protocolFragmentation protocol serializes fragments outgoing messages in order to push byte array messages with a maximum size. Incoming messages fragments are gathered and deserialized.
4.3 RPC protocolwe implement a RPC protocol over channel protocol. This implementation has been made for experimentation, and is not yet usable.
5 ChannelsChannels components make the use of protocol components easy! They allows to exchange messages from different address spaces. Channel components uses Message Passing Protocol to send and receives messages. When a Channel component is started, it exports itself through the lower Message Passing Protocol.
A Channel provides an in-push interface on which it receives messages that must be sent to another address space. The destination of the message (the export identifier of the remote access point) is resolved by a Destination Resolver component.
A Channel may also have a out-push client interface on which messages received from other address spaces will be pushed. Channels that has an out-push interface are named Channel In/Out, those who do not are named Channel Out.
Figure11 depicts an example of a channel component which uses TCP Protocol and Message Passing Over Channel Protocol.
The Destination Resolver implementation provided by DREAM retrieves the destination of each message in an ExportIdentifierChunk. A fractal attributes can be used to specify the name of the chunk, and if it should be removed before the message is sent.
Moreover, Channel In/Out implementation provides an attribute that allows to specify if an ExportIdentifierChunk should be added to incoming messages containing the identifier of the Channel that emits it.
DREAM provides the following channel ADL:
6 PumpsA Pump component is a bridge between Pull and Push. It contains a task and has two client interfaces in-pull and out-push. The task pulls a message on the in-pull interface and pushes it on the out-push interface. The task may be register in the Task Manager as mono threaded, multi threaded, or periodic.
Moreover a pump may be synchronized using a Mutex component (the Pump component has an optional mutex client interface). The mutex is locked before a message is pulled and released after it is pushed.
A pump has three policies that can be specified as fractal attributes:
7 RoutersRouter components have one Push input and multiple Push outputs, for each incoming message, they choose an output and forward the message through it. The DREAM library provides three simple Router implementations in the org.objectweb.dream.router package.
8 Serialization/De-serialization componentsThis section describes the Serialization/De-serialization components available in the DREAM library. These components are located in the org.objectweb.dream.serializator package. They allow to easily transforms a message into a byte array or restore a message from a byte array.
This document was translated from LATEX by HEVEA.
Copyright © 1999-2007, OW2 Consortium | contact | webmaster | Last modified at 2008-01-28 11:51 AM