[jboss-cvs] JBoss Messaging SVN: r6711 - in trunk/docs/user-manual/en: diagrams and 1 other directories.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Fri May 8 08:24:37 EDT 2009
Author: timfox
Date: 2009-05-08 08:24:37 -0400 (Fri, 08 May 2009)
New Revision: 6711
Added:
trunk/docs/user-manual/en/modules/messaging-concepts.xml
Removed:
trunk/docs/user-manual/en/modules/introduction.xml
Modified:
trunk/docs/user-manual/en/diagrams/architecture-diagrams.odg
trunk/docs/user-manual/en/master.xml
trunk/docs/user-manual/en/modules/architecture.xml
trunk/docs/user-manual/en/modules/preface.xml
Log:
user guide work
Modified: trunk/docs/user-manual/en/diagrams/architecture-diagrams.odg
===================================================================
(Binary files differ)
Modified: trunk/docs/user-manual/en/master.xml
===================================================================
--- trunk/docs/user-manual/en/master.xml 2009-05-08 08:56:25 UTC (rev 6710)
+++ trunk/docs/user-manual/en/master.xml 2009-05-08 12:24:37 UTC (rev 6711)
@@ -2,7 +2,7 @@
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN"
"../../../lib/docbook-support/support/docbook-dtd/docbookx.dtd" [
<!ENTITY preface SYSTEM "modules/preface.xml">
- <!ENTITY introduction SYSTEM "modules/introduction.xml">
+ <!ENTITY messaging-concepts SYSTEM "modules/messaging-concepts.xml">
<!ENTITY architecture SYSTEM "modules/architecture.xml">
]>
<book lang="en">
@@ -14,6 +14,6 @@
<toc></toc>
&preface;
- &introduction;
+ &messaging-concepts;
&architecture;
</book>
Modified: trunk/docs/user-manual/en/modules/architecture.xml
===================================================================
--- trunk/docs/user-manual/en/modules/architecture.xml 2009-05-08 08:56:25 UTC (rev 6710)
+++ trunk/docs/user-manual/en/modules/architecture.xml 2009-05-08 12:24:37 UTC (rev 6711)
@@ -1,6 +1,94 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="architecture">
<title>Architecture</title>
- <para/>
- <para>TODO: copy blurb from User Guide</para>
+ <para>In this section we will discuss the JBoss Messaging high level architecture and
+ concepts.</para>
+ <section>
+ <title>Core Architecture</title>
+ <para>JBoss Messaging core is designed simply as set of Plain Old Java Objects
+ (POJOs).</para>
+ <para>We've also designed it to have as few dependencies on external jars as possible. In
+ fact, JBoss Messaging core has <emphasis role="italic">zero</emphasis> dependencies on
+ any jars other than the standard JDK classes!</para>
+ <para>This allows JBoss Messaging to be easily embedded in your own project, or instantiated
+ in any dependency injection framework such as JBoss Microcontainer or Spring.</para>
+ <para>A JBoss Messaging server has its own high performance persistent journal, which it
+ uses for message and other persistence.</para>
+ <para>Using a high performance journal allows outrageous persistence message performance,
+ something not achievable when using a relational database for persistence.</para>
+ <para>JBoss Messaging clients, potential on different physical machines interact with the
+ JBoss Messaging server. JBoss Messaging currently provides two APIs for messaging at the
+ client side:</para>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>Core client API. This is a simple intuitive Java API that allows the full
+ set of messaging functionality without some of the complexities of
+ JMS.</para>
+ </listitem>
+ <listitem>
+ <para>JMS client API. The standard JMS classes are available at the client
+ side.</para>
+ </listitem>
+ </orderedlist>
+ </para>
+ <para>JMS semantics are implemented in a thin JMS facade layer on the client side.</para>
+ <para>The JBoss Messaging server does not speak JMS and in fact does not know anything about
+ JMS, it's a protocol agnostic messaging server designed to be used with multiple
+ different protocols.</para>
+ <para>When a user uses the JMS API on the client side, all JMS interactions are translated
+ into operations on the JBoss Messaging core client API before being transferred over the
+ wire using the JBoss Messaging wire format.</para>
+ <para>The server always just deals with core API interactions.</para>
+ <para>A schematic illustrating this relationship is shown in figure 1</para>
+ </section>
+ <section>
+ <title>JBoss Messaging embedded in your own application</title>
+ <para>JBoss Messaging core is designed as a set of simple POJOs so if you have an
+ application that requires messaging functionality internally but you don't want to
+ expose that as a messaging server you can directly instantiate and embed messaging
+ servers in your own application.</para>
+ <para>Here's a real code example demonstrating just how easy that is:</para>
+ <para><code> Server server = new MessagingServer(); </code></para>
+ </section>
+ <section>
+ <title>JBoss Messaging integrated with a JEE application server</title>
+ <para>JBoss Messaging provides its own fully functional Java Connector Architecture (JCA)
+ adaptor which enables it to be integrated easily into any JEE compliant application
+ server or servlet engine.</para>
+ <para>JEE application servers provide Message Driven Beans (MDBs), which are a special type
+ of Enterprise Java Beans (EJBs) which can process messages from sources such as JMS
+ systems or mail systems.</para>
+ <para>Problem the most common use of an MDB is to consume messages from a JMS messaging
+ system.</para>
+ <para>According to the JEE specification, a JEE application server uses a JCA adapter to
+ integrate with a JMS messaging system so it can consume messages for MDBs.</para>
+ <para>The JCA adapter is not only used by the JEE application server for <emphasis
+ role="italic">consuming</emphasis> messages via MDBs, it is also used when sending
+ message to the JMS messaging system e.g. from inside an EJB or servlet.</para>
+ <para>When integrating with a JMS messaging system from inside a JEE application server it
+ is always recommended that this is done via the JCA adaptor.</para>
+ <para>The application server's JCA service provides extra functionality such as connection
+ pooling and automatic transaction enlistment, which are desirable when using messaging,
+ say, from inside an EJB.</para>
+ <para>Diagram</para>
+ </section>
+ <section>
+ <title>JBoss Messaging stand-alone server</title>
+ <para>JBoss Messaging can also be deployed as a stand-alone server. This means a fully
+ independent messaging server not dependent on a JEE application server.</para>
+ <para>The standard stand-alone messaging server configuration comprises a core messaging
+ server, plus a JMS server manager service which allows JMS connection factorys, Queues
+ and Topics to be deployed from xml configuration on the server side, and also a JNDI
+ service.</para>
+ <para>We choose to include these in the standard stand-alone config since JMS and JNDI are
+ often requirements in many deployments. If JNDI or JMS is not required then these
+ services can easily be disabled in the configuration.</para>
+ <para>The stand-alone server configuration uses JBoss Microcontainer to instantiate and
+ enforce dependencies between the components. JBoss Microcontainer is a very lightweight
+ POJO bootstrapper.</para>
+ <para>The stand-alone server architecture is shown in figure X</para>
+ </section>
+
+
</chapter>
Deleted: trunk/docs/user-manual/en/modules/introduction.xml
===================================================================
--- trunk/docs/user-manual/en/modules/introduction.xml 2009-05-08 08:56:25 UTC (rev 6710)
+++ trunk/docs/user-manual/en/modules/introduction.xml 2009-05-08 12:24:37 UTC (rev 6711)
@@ -1,5 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<chapter id="introduction">
- <title>Introduction</title>
- <para>TODO</para>
-</chapter>
\ No newline at end of file
Added: trunk/docs/user-manual/en/modules/messaging-concepts.xml
===================================================================
--- trunk/docs/user-manual/en/modules/messaging-concepts.xml (rev 0)
+++ trunk/docs/user-manual/en/modules/messaging-concepts.xml 2009-05-08 12:24:37 UTC (rev 6711)
@@ -0,0 +1,252 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="introduction">
+ <title>Messaging Concepts</title>
+ <para>JBoss Messaging is an asynchronous messaging system, an example of <ulink
+ url="http://en.wikipedia.org/wiki/Message_oriented_middleware">Message Oriented
+ Middleware</ulink> , we'll just call them messaging systems in the remainder of this
+ book.</para>
+ <para>We'll first prevent a brief overview of what kind of things messaging systems do and and
+ where they're useful, and the kind of concepts you'll hear about in the messaging
+ world.</para>
+ <para>If you're already familiar with what a messaging system is and what it's capable of, then
+ you can skip this chapter.</para>
+ <para>Messaging systems allow you to loosely couple heteregenous systems together, whilst
+ typically providing reliability, transactions, and many other features.</para>
+ <para>Unlike systems based on a <ulink url="http://en.wikipedia.org/wiki/Remote_procedure_call"
+ >Remote Procedure Call</ulink> (RPC) pattern, messaging systems primarily use an
+ asynchronous message passing pattern with no tight relationship between requests and
+ responses. Most messaging systems also support a request-response mode but this is not a
+ primary feature of messaging systems.</para>
+ <para>Designing systems to be asynchronous from end-to-end allows you to really take advantage
+ of your hardware resources, minimising the amount of threads blocking on IO operations, and
+ to use your network bandwidth to its full capacity. With an RPC approach you have to wait
+ for a response for each request you make so are limited by the network round trip time, or
+ <emphasis role="italic">latency</emphasis> of your network. With an asynchronous you can
+ pipeline flows of messages in different directions, so are limited by the network <emphasis
+ role="italic">bandwidth</emphasis> not the latency. This typically allows you to create
+ much higher performance applications.</para>
+ <para>Messaging systems decouple the senders of messages from the consumers of messages. The
+ senders and consumers of messages are completely independent and know nothing of each other.
+ This allows you to create flexible, loosely coupled systems.</para>
+ <para>Often, large enterprises use a messaging system to implement a message bus which is to
+ loosely couple heterogenous systems together. Message buses often form the core of an <ulink
+ url="http://en.wikipedia.org/wiki/Enterprise_service_bus">Enterprise Service
+ Bus</ulink>. (ESB). Using a message bus to couple disparate systems can allow the system to
+ grow and adapt more flexible as new systems are added and old ones retired, without each
+ system having hard, brittle dependencies on each other.</para>
+ <section>
+ <title>Messaging styles</title>
+ <para>Messaging systems normally support two main styles of asynchronous messaging;<ulink
+ url="http://en.wikipedia.org/wiki/Message_queue"> message queue</ulink> (also known
+ as <emphasis role="italic">point-to-point messaging</emphasis>) and <ulink
+ url="http://en.wikipedia.org/wiki/Publish_subscribe">publish subscribe</ulink>
+ messaging. We'll summarise them briefly here:</para>
+ <section>
+ <title>The Message Queue Pattern</title>
+ <para>With this type of messaging you send a message to a queue. The message is then
+ typically persisted to provide a guarantee of delivery, then some time later the
+ messaging system delivers the message to a consumer. The consumer then processes the
+ message and when it is done, it acknowledges the message. Once the message is
+ acknowledged it disappears from the queue and is not available to be delivered
+ again. If the system crashes before the messaging server receives an acknowledgement
+ from the consumer, then on recovery, the message will be available to be delivered
+ to a consumer again.</para>
+ <para>With point-to-point messaging, there can be many consumers on the queue but a
+ particular message will only ever be consumed by a maximum of one of them. Senders
+ (also known as<emphasis role="italic"> producers</emphasis>) to the queue are
+ completely decoupled from receivers (also known as <emphasis role="italic"
+ >consumers</emphasis>) of the queue - they do not know of each others
+ existence.</para>
+ <para>A classic example of point to point messaging would be an order queue in a
+ company's book ordering system. Each order is represented as a message which is sent
+ to the order queue. There are many front end ordering systems which send orders to
+ the order queue. When a message arrives on the queue it is persisted - this ensures
+ that if the server crashes the order is not lost. There are many consumers on the
+ order queue - each representing an instance of an order processing component - this
+ can be on different physical machines but consuming from the same queue. The
+ messaging system delivers each message to one and only one of the ordering
+ processing components. Different messages can be processed by order processors, but
+ a single order is only processed by one order processor - this ensures orders aren't
+ processed twice.</para>
+ <para>As an order processor receives a message, its fulfils the order - sends order
+ information to the warehous system and then updates the order database with the
+ order details. Once it's done that it acknowledges the message to tell the server
+ that the order message is done and can be forgotten about. Often the send to the
+ warehouse system, update in database and acknowledgement will be completed in a
+ single transaction to ensure ACID properties.</para>
+ </section>
+ <section>
+ <title>The Publish-Subscribe Pattern</title>
+ <para>With publish-subscribe messaging many senders can send messages to an entity on
+ the server, often called a <emphasis role="italic">topic</emphasis>, e.g. in the JMS
+ world.</para>
+ <para>There can be many subscriptions on a topic, each subscription receives a copy of
+ <emphasis role="italic">each</emphasis> message sent to the topic. This differs
+ from the message queue pattern where each message is only consumed by a single
+ consumer.</para>
+ <para>Subscriptions can optionally be <emphasis role="italic">durable</emphasis> which
+ means they retain a copy of each message sent to the topic until the subscriber
+ consumes it.</para>
+ <para>An example of publish-subscribe messaging would be a news feed. As news articles
+ are created by different editors around the world they are sent to a news feed
+ topic. There are many subscribers around the world who are interested in receiving
+ news items - each one creates a subscription and the messaging system ensures that a
+ copy of each news message is delivered to each subscription.</para>
+ </section>
+ </section>
+ <section>
+ <title>Delivery guarantees</title>
+ <para>A key feature of most messaging systems is <emphasis role="italic">reliable
+ messaging</emphasis>. With reliable messaging the server gives a guarantee that the
+ message will be delivered once and only once to each consumer of a queue or each
+ subscription of a topic, even in the event of system failure. This is crucial for many
+ businesses - you don't want your orders fulfilled more than once, or your trades to be
+ lost or occur more than once.</para>
+ <para>In other cases you may not care about a once and only once delivery guarantee and are
+ happy to cope with duplicate deliveries. The messaging system allows you to configure
+ which delivery guarantees you require.</para>
+ </section>
+ <section>
+ <title>Transactions</title>
+ <para>Messaging systems typically support the sending and acknowledgement of multiple
+ messages in a single local transaction. JBoss Messaging also supports the sending and
+ acknowledgement of message as part of a large global transaction - using the Java
+ mapping of XA, JTA.</para>
+ </section>
+ <section>
+ <title>Durability</title>
+ <para> Messages are either durable or non durable. Durable messages will persisted in
+ permanent storage and will survive server failure. Non durable messages will not survive
+ server failure or restart. Examples of durable messages might be orders or trades, where
+ they cannot be lost. An example of a non durable message might be a stock price update.
+ This is transitory and there's no need for it to survive a restart. </para>
+ </section>
+ <section>
+ <title>Messaging APIs and protocols</title>
+ <para>How do client applications interact with messaging systems in order to send and
+ consume messages?</para>
+ <para>Several messaging systems provide their own proprietary APIs with which the client
+ communicates with the messaging system.</para>
+ <para>There are also some standard ways of operating with messaging systems and some
+ emerging standards in this space.</para>
+ <para>Let's take a brief look at these:</para>
+ <section>
+ <title>Java Message Service (JMS)</title>
+ <para><ulink url="http://en.wikipedia.org/wiki/Java_Message_Service">JMS</ulink> is part
+ of Sun's JEE specification. It's a Java API that encapsulates both message queue and
+ publish-subscribe messaging patterns. JMS is a lowest common denominator
+ specification - i.e. it was created to encapsulate common functionality of the
+ already existing messaging systems that were available at the time of its
+ creation.</para>
+ <para>JMS is a very popular API and is implemented by most messaging systems. JMS is
+ only available to clients running Java.</para>
+ <para>JMS does not define a standard wire format - it only defines a programmatic API so
+ JMS clients and servers from different vendors cannot interoperate since they will
+ most likely use the vendor's own internal wire protocol.</para>
+ <para>JBoss Messaging provides a fully compliant JMS 1.1 API.</para>
+ </section>
+ <section>
+ <title>System specific APIs</title>
+ <para>Many systems provide their own programmic API for which to interact with the
+ messaging system. The advantage of this it allows the full set of system
+ functionality to be exposed tp the client application. APIs like JMS are not
+ normally rich enough to expose all the extra featurs that most messaging systems
+ provide.</para>
+ <para>JBoss Messaging provides its own core client API for clients to use if they wish
+ to have access to functionality over and above that accesible via the JMS
+ API.</para>
+ </section>
+ <section>
+ <title>STOMP</title>
+ <para><ulink
+ url="http://en.wikipedia.org/wiki/Streaming_Text_Orientated_Messaging_Protocol"
+ >STOMP</ulink> is a very simple protocol for interoperating with messaging
+ systems. It defines a wire format, so theoretically any STOMP client can work with
+ any messaging system that supports STOMP. STOMP clients are available in many
+ different programming languages.</para>
+ <para>JBoss Messaging can be used by any STOMP client when using the <ulink
+ url="http://stomp.codehaus.org/StompConnect">StompConnect</ulink> broker which
+ translates STOMP protocol to the JMS API.</para>
+ <para>JBoss Messaging will be shortly implementing the STOMP protocol on the boker, thus
+ avoiding the usage of StompConnect.</para>
+ </section>
+ <section>
+ <title>AMQP</title>
+ <para><ulink url="http://en.wikipedia.org/wiki/AMQP">AMQP</ulink> is an emerging
+ standard for interoperable messaging. It also defines a wire format, so any AMQP
+ client can work with any messaging system that supports AMQP. AMQP clients are
+ available in many different programming languages.</para>
+ <para>JBoss Messaging will shortly be implementing AMQP.</para>
+ </section>
+ <section>
+ <title>REST</title>
+ <para><ulink url="http://en.wikipedia.org/wiki/Representational_State_Transfer"
+ >REST</ulink> approaches to messaging are showing a lot interest recently. With
+ a REST approach messaging resources are manipulated as resources, typically using a
+ simple set of operations on those resources, e.g. PUT, POST, GET etc. REST
+ approaches to messaging often use HTTP as their underlying protocol.</para>
+ <para>The advantage of a REST approach with HTTP is in its simplicity and the fact the
+ internet is already tuned to deal with HTTP optimally.</para>
+ <para>JBoss Messaging will shortly be implementing REST.</para>
+ </section>
+ </section>
+ <section>
+ <title>High Availability</title>
+ <para>High Availability (HA) means that the system should remain operation after failure of
+ one or more of the servers. The degree of support for HA varies from messaging system to
+ messaging system.</para>
+ <para>Some messaging systems require you to deal with server side failure by writing some
+ client side code which gets called on event of server failure, and in which you are
+ supposed to recreate your connections to another server.</para>
+ <para>JBoss Messaging provides 100% transparent failover where you don't have have to write
+ any special client side code to deal with failure. On failover JBoss Messaging will
+ automatically fail over your client connections to another server, and your client
+ sessions can continue as if nothing happened.</para>
+ </section>
+ <section>
+ <title>Clusters</title>
+ <para>Many messaging systems allow you to create groups of messaging servers called
+ <emphasis role="italic">clusters</emphasis>. Cluster allow the load of sending and
+ consuming messages to be spread over many servers. This allows your system to be able
+ scale horizontally by adding new servers to the cluster.</para>
+ <para>Degrees of support for clusters varies from messaging system to messaging system, with
+ some systems having fairly basic clusters where the cluster members being hardly aware
+ of each other.</para>
+ <para>JBoss Messaging provides very configurable state of the art clustering where messages
+ can be intelligently load balanced between the servers in the cluster, according to the
+ number of consumers on each node, and whether they are ready for messages.</para>
+ <para>JBoss Messaging also has the ability to automatically redistribute messages between
+ nodes of a cluster to prevent starvation on any particular node.</para>
+ <para>For full details on clustering please the clustering section.</para>
+ </section>
+ <section>
+ <title>Bridges and routing</title>
+ <para>Some messaging systems allow isolated clusters or single nodes to be bridged together,
+ typically over unreliable connections like a Wide Area Network (WAN).</para>
+ <para>A bridge normally consumes from a queue on one server and forwards messages to another
+ queue on a different server. Bridges cope with unreliable connections, automatically
+ reconnecting when the connections becomes available again.</para>
+ <para>JBoss Messaging bridges can be configured with filter expressions to only forward
+ certain messages, and transformation can be hooked in.</para>
+ <para>JBoss Messaging also allows routing between queues to be configured in server side
+ configuration. This allows complex routing networks to be set up forwarding or copying
+ messages from one destination to another, forming a global network of interconnected
+ brokers.</para>
+ </section>
+ <section>
+ <title>Other messaging system functionality</title>
+ <para>Here's a quick run through of other features and terms you might hear in the context
+ of messaging systems:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Message expiry</para>
+ <para>You can set a Time to Live (TTL) on a message. If you do this then if the
+ messaging system has not delivered the message by the time TTL comes then the
+ message will be discarded or possibly sent to a configurable other
+ destination.</para>
+ </listitem>
+ <listitem><para>Message redelivery</para></listitem>
+ <listitem><para>Blah blah</para></listitem>
+ </itemizedlist>
+ </section>
+</chapter>
Modified: trunk/docs/user-manual/en/modules/preface.xml
===================================================================
--- trunk/docs/user-manual/en/modules/preface.xml 2009-05-08 08:56:25 UTC (rev 6710)
+++ trunk/docs/user-manual/en/modules/preface.xml 2009-05-08 12:24:37 UTC (rev 6711)
@@ -1,6 +1,42 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="preface">
<title>Preface</title>
- <para/>
- <para>TODO: copy blurb from User Guide</para>
+ <para>The goal of JBoss Messaging is simple and uncompromising; to bring unrivalled levels of
+ performance and reliability to messaging, and to be the fastest, best featured and most
+ scalable multi-protocol messaging system.</para>
+ <para>Why use JBoss Messaging? Here are a few of the reasons:</para>
+ <itemizedlist>
+ <listitem>
+ <para>100% open source software. We use the Apache Software License version 2.0 to limit
+ restrictions on use.</para>
+ </listitem>
+ <listitem>
+ <para>Written in Java. Runs on any platform with a J2SE 5.0 JDK, that's everything from
+ Windows desktops to IBM mainframes.</para>
+ </listitem>
+ <listitem>
+ <para>Superb performance. Our class beating high performance journal provides persistent
+ messaging performance at rates normally seen for non persistent messaging.</para>
+ </listitem>
+ <listitem>
+ <para>Full feature set. All the features you'd expect in any serious messaging system,
+ and others you won't find anywhere else.</para>
+ </listitem>
+ <listitem>
+ <para>Elegant POJO based design with minimal third party dependencies. Run JBoss
+ Messaging stand-alone, run it in integrated in your favourite JEE application
+ server, or run it embedded inside your own product.</para>
+ </listitem>
+ <listitem>
+ <para>Seamless high availabilty. We provide server replication and completely
+ transparent client failover so you don't have to worry about coding your client
+ specially for an HA environment.</para>
+ </listitem>
+ <listitem>
+ <para>Hugely flexible clustering. Create clusters of servers that know how to load
+ balance messages. Link geographically distributed clusters over unreliable
+ connections to form a global network. Configure routing of messages in a highly
+ flexible way.</para>
+ </listitem>
+ </itemizedlist>
</chapter>
More information about the jboss-cvs-commits
mailing list