diff options
| author | Alex Rudyy <orudyy@apache.org> | 2015-04-15 10:00:55 +0000 |
|---|---|---|
| committer | Alex Rudyy <orudyy@apache.org> | 2015-04-15 10:00:55 +0000 |
| commit | b15e32a943ae269c1c7dae4b2084e2ad87f3940d (patch) | |
| tree | 8b3206ffa501d186fee43b3cc3ab3ef924b53e3b /qpid/doc/book/src/java-broker/concepts | |
| parent | 0a0baee45ebcff44635907d457c4ff6810b09c87 (diff) | |
| download | qpid-python-b15e32a943ae269c1c7dae4b2084e2ad87f3940d.tar.gz | |
QPID-6481: Move java broker docbook into java source tree
git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1673703 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'qpid/doc/book/src/java-broker/concepts')
10 files changed, 0 insertions, 952 deletions
diff --git a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Authentication-Providers.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Authentication-Providers.xml deleted file mode 100644 index d361efb0ab..0000000000 --- a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Authentication-Providers.xml +++ /dev/null @@ -1,31 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<!-- - - Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. - ---> - -<section id="Java-Broker-Concepts-Authentication-Providers"> - <title>Authentication Providers</title> - <para> - <emphasis>Authentication Providers</emphasis> are used by <emphasis>Ports</emphasis> to authenticate connections. - Many <emphasis>Authentication Providers</emphasis> can be configured on the Broker at the same time, from which - each <emphasis>Port</emphasis> can be assigned one. - </para> - <para>Some Authentication Providers offer facilities for creation and deletion of users.</para> -</section> diff --git a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Broker.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Broker.xml deleted file mode 100644 index 90193176a7..0000000000 --- a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Broker.xml +++ /dev/null @@ -1,26 +0,0 @@ -<?xml version="1.0"?> -<!-- - - Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. - ---> -<section id="Java-Broker-Concepts-Broker"> - <title>Broker</title> - <para>The <emphasis>Broker</emphasis> is the outermost entity within the system.</para> - <para>The Broker is backed by storage. This storage is used to record the durable entities that exist beneath it.</para> -</section> diff --git a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Exchanges.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Exchanges.xml deleted file mode 100644 index 5eb02dc5dd..0000000000 --- a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Exchanges.xml +++ /dev/null @@ -1,204 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<!-- - - Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. - ---> - -<section id="Java-Broker-Concepts-Exchanges"> -<title>Exchanges</title> - <para>An <emphasis>Exchange</emphasis> is a named entity within the <emphasis>Virtualhost</emphasis> which receives - messages from producers and routes them to matching <emphasis>Queue</emphasis>s within the <emphasis>Virtualhost</emphasis>.</para> - <para>The server provides a set of exchange types with each exchange type implementing a different routing algorithm. For details of how - these exchanges types work see <xref linkend="Java-Broker-Concepts-Exchanges-Types"/> below.</para> - <para>The server predeclares a number of exchange instances with names starting with "<literal>amq.</literal>". These are defined in - <xref linkend="Java-Broker-Concepts-Exchanges-Predeclared"/>.</para> - <para>Applications can make use the pre-declared exchanges, or they may declare their own. The number of exchanges within a virtual host is - limited only by resource constraints.</para> - <para>The behaviour when an exchange is unable to route a message to any queue is defined in <xref linkend="Java-Broker-Concepts-Exchanges-UnroutableMessage"/></para> - <section id="Java-Broker-Concepts-Exchanges-Predeclared"> - <title>Predeclared Exchanges</title> - <para>Each virtual host pre-declares the following exchanges: - <itemizedlist> - <listitem><para>amq.direct (an instance of a direct exchange)</para></listitem> - <listitem><para>amq.topic (an instance of a topic exchange)</para></listitem> - <listitem><para>amq.fanout (an instance of a fanout exchange)</para></listitem> - <listitem><para>amq.match (an instance of a headers exchange)</para></listitem> - </itemizedlist> - </para> - <para>The conceptual "<literal>default exchange</literal>" always exists, effectively a special instance of - direct exchange which uses the empty string as its name. All queues are automatically bound to it upon their creation - using the queue name as the binding key, and unbound upon their deletion. It is not possible to manually add or remove - bindings within this exchange.</para> - <para>Applications may not declare exchanges with names beginning with "<literal>amq.</literal>". Such names are reserved for system use.</para> - </section> - <section id="Java-Broker-Concepts-Exchanges-Types"> - <title>Exchange Types</title> - <para> - The following Exchange types are supported. - <itemizedlist> - <listitem><para>Direct</para></listitem> - <listitem><para>Topic</para></listitem> - <listitem><para>Fanout</para></listitem> - <listitem><para>Headers</para></listitem> - </itemizedlist> - These exchange types are described in the following sub-sections.</para> - - <section id="Java-Broker-Concepts-Exchanges-Types-Direct"> - <title>Direct</title> - <para>The direct exchange type routes messages to queues based on an exact match between - the routing key of the message, and the binding key used to bind the queue to the exchange. Additional - filter rules may be specified using a <link linkend="Java-Broker-Concepts-Exchanges-BindingArguments-JMSSelector"> - binding argument specifying a JMS message selector</link>. - </para> - <para>This exchange type is often used to implement point to point messaging. When used in this manner, the normal - convention is that the binding key matches the name of the queue. It is also possible to use this exchange type - for multi-cast, in this case the same binding key is associated with many queues.</para> - <figure> - <title>Direct exchange</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/Exchange-Direct.png" format="PNG" scalefit="1"/> - </imageobject> - </mediaobject> - </figure> - <para>The figure above illustrates the operation of direct exchange type. The yellow messages published with the routing key - "<literal>myqueue</literal>" match the binding key corresponding to queue "<literal>myqueue</literal>" and so are routed there. The red - messages published with the routing key "<literal>foo</literal>" match two bindings in the table so a copy of the message is - routed to both the "<literal>bar1</literal>" and "<literal>bar2</literal>" queues.</para> - <para>The routing key of the blue message matches no binding keys, so the message is unroutable. It is handled as described - in <xref linkend="Java-Broker-Concepts-Exchanges-UnroutableMessage"/>.</para> - </section> - <section id="Java-Broker-Concepts-Exchanges-Types-Topic"> - <title>Topic</title> - <para>This exchange type is used to support the classic publish/subscribe paradigm.</para> - <para>The topic exchange is capable of routing messages to queues based on wildcard matches between the routing key and the - binding key pattern defined by the queue binding. Routing keys are formed from one or more words, with each word delimited - by a full-stop (.). The pattern matching characters are the * and # symbols. The * symbol matches a single word and the # - symbol matches zero or more words.</para> - <para>Additional filter rules may be specified using a <link linkend="Java-Broker-Concepts-Exchanges-BindingArguments-JMSSelector"> - binding argument specifying a JMS message selector</link>.</para> - <para>The following three figures help explain how the topic exchange functions.</para> - <para></para> - <figure> - <title>Topic exchange - exact match on topic name</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/Exchange-Topic.png" format="PNG" scalefit="1"/> - </imageobject> - </mediaobject> - </figure> - <para>The figure above illustrates publishing messages with routing key "<literal>weather</literal>". The exchange routes each - message to every bound queue whose binding key matches the routing key.</para> - <para>In the case illustrated, this means that each subscriber's queue receives every yellow message.</para> - <figure> - <title>Topic exchange - matching on hierarchical topic patterns</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/Exchange-Topic-Hierarchical.png" format="PNG" scalefit="1"/> - </imageobject> - </mediaobject> - </figure> - <para>The figure above illustrates publishing messages with hierarchical routing keys. As before, the exchange routes each - message to every bound queue whose binding key matches the routing key but as the binding keys contain wildcards, the - wildcard rules described above apply.</para> - <para>In the case illustrated, <literal>sub1</literal> has received the red and green message as "<literal>news.uk</literal>" and "<literal>news.de</literal>" - match binding key "<literal>news.#</literal>". The red message has also gone to <literal>sub2</literal> and <literal>sub3</literal> as it's routing key - is matched exactly by "<literal>news.uk</literal>" and by "<literal>*.uk</literal>".</para> - <para>The routing key of the yellow message matches no binding keys, so the message is unroutable. It is handled as described - in <xref linkend="Java-Broker-Concepts-Exchanges-UnroutableMessage"/>.</para> - <figure> - <title>Topic exchange - matching on JMS message selector</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/Exchange-Topic-JMSSelector.png" format="PNG" scalefit="1"/> - </imageobject> - </mediaobject> - </figure> - <para>The figure above illustrates messages with properties published with routing key "<literal>shipping</literal>".</para> - <para>As before, the exchange routes each message to every bound queue whose binding key matches the routing key but as a JMS selector - argument has been specified, the expression is evaluated against each matching message. Only messages whose message header values or properties - match the expression are routed to the queue.</para> - <para>In the case illustrated, <literal>sub1</literal> has received the yellow and blue message as their property "<literal>area</literal>" - cause expression "<literal>area in ('Forties', 'Cromarty')</literal>" to evaluate true. Similarly, the yellow message has also gone to - <literal>gale_alert</literal> as its property "<literal>speed</literal>" causes expression "<literal>speed > 7 and speed < 10</literal>" - to evaluate true.</para> - <para>The properties of purple message cause no expressions to evaluate true, so the message is unroutable. It is handled as described in - <xref linkend="Java-Broker-Concepts-Exchanges-UnroutableMessage"/>.</para> - </section> - <section id="Java-Broker-Concepts-Exchanges-Types-Fanout"> - <title>Fanout</title> - <para>The fanout exchange type routes messages to all queues bound to the exchange, regardless of the message's routing key.</para> - <para>Filter rules may be specified using a <link linkend="Java-Broker-Concepts-Exchanges-BindingArguments-JMSSelector"> - binding argument specifying a JMS message selector</link>.</para> - <figure> - <title>Fanout exchange</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/Exchange-Fanout.png" format="PNG" scalefit="1"/> - </imageobject> - </mediaobject> - </figure> - </section> - <section id="Java-Broker-Concepts-Exchanges-Types-Headers"> - <title>Headers</title> - <para>The headers exchange type routes messages to queues based on header properties within the message. The message is passed to - a queue if the header properties of the message satisfy the <link linkend="Java-Broker-Concepts-Exchanges-BindingArguments-x-match"> - x-match expression</link> specified by the binding arguments with which the queue was bound. - </para> - </section> - </section> - <section id="Java-Broker-Concepts-Exchanges-BindingArguments"> - <title>Binding Arguments</title> - <para>Binding arguments are used by certain exchange types to further filter messages.</para> - <section id="Java-Broker-Concepts-Exchanges-BindingArguments-JMSSelector"> - <title>JMS Selector</title> - <para>The binding argument <literal>x-filter-jms-selector</literal> specifies a JMS selector conditional expression. The expression - is written in terms of message header and message property names. If the expression evaluates to true, the message is routed to the queue. - This type of binding argument is understood by exchange types direct, topic and fanout.<footnote><para> - This is a Qpid specific extension.</para></footnote>.</para> - </section> - <section id="Java-Broker-Concepts-Exchanges-BindingArguments-x-match"> - <title>x-match</title> - <para>The binding argument <literal>x-match</literal> is understood by exchange type headers. It can take two values, dictating how the - rest of the name value pairs are treated during matching.</para> - <itemizedlist> - <listitem><para><literal>all</literal> implies that all the other pairs must match the headers property of a message for that message to be routed - (i.e. an AND match)</para></listitem> - <listitem><para><literal>any</literal> implies that the message should be routed if any of the fields in the headers property match one of the - fields in the arguments table (i.e. an OR match)</para></listitem> - </itemizedlist> - <para>A field in the bind arguments matches a field in the message if either the field in the bind arguments has no value and a field of the - same name is present in the message headers or if the field in the bind arguments has a value and a field of the same name exists in the - message headers and has that same value.</para> - </section> - </section> - <section id="Java-Broker-Concepts-Exchanges-UnroutableMessage"> - <title>Unrouteable Messages</title> - <para>If an exchange is unable to route a message to any queues, the Broker will: - <itemizedlist> - <listitem><para>If using AMQP 0-10 protocol, and an alternate exchange has been set on the exchange, the message is routed to the alternate exchange. - The alternate exchange routes the message according to its routing algorithm and its binding table. If the messages is still unroutable, - the message is discarded.</para></listitem> - <listitem><para>If using AMQP protocols 0-8..0-9-1, and the publisher set the mandatory flag and the<link linkend="Java-Broker-Close-Connection-When-No-Route"> - close when no route</link> feature did not close the connection, the message is returned to the Producer.</para></listitem> - <listitem><para>Otherwise, the message is discarded.</para></listitem> - </itemizedlist> - </para> - </section> -</section> diff --git a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Other-Services.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Other-Services.xml deleted file mode 100644 index 854a8001d6..0000000000 --- a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Other-Services.xml +++ /dev/null @@ -1,58 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<!-- - - Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. - ---> - -<section id="Java-Broker-Concepts-Other-Services"> -<title>Other Services</title> - <para> - The Broker can also have <emphasis>Access Control Providers</emphasis>, <emphasis>Group Providers</emphasis>, - <emphasis>Keystores</emphasis>, <emphasis>Trustores</emphasis> and [Management] <emphasis>Plugins</emphasis> configured. - </para> - - <section id="Java-Broker-Concepts-Access-Control-Providers"> - <title>Access Control Providers</title> - <para><emphasis>Access Control Providers</emphasis> are used to authorize various operations relating to Broker objects.</para> - <para>Access Control Provider configuration and management details are covered in <xref linkend="Java-Broker-Security-ACLs"/>.</para> - </section> - - <section id="Java-Broker-Concepts-Group-Providers"> - <title>Group Providers</title> - <para><emphasis>Group Providers</emphasis> are used to aggregate authenticated user principals into groups - which can be then be used in Access Control rules applicable to the whole group.</para> - <para>Group Provider configuration and management is covered in <xref linkend="Java-Broker-Security-Group-Providers"/>.</para> - </section> - - <section id="Java-Broker-Concepts-Keystores"> - <title>Keystores</title> - <para><emphasis>Keystores</emphasis> are used to configure details of keystores holding SSL keys and certificates - for the SSL transports on Ports.</para> - <para>Keystore configuration and management is covered in <xref linkend="Java-Broker-Management-Managing-Keystores"/>.</para> - </section> - - <section id="Java-Broker-Concepts-Truststores"> - <title>Truststores</title> - <para><emphasis>Truststores </emphasis> are used to configure details of keystores holding SSL certificates - for trusting Client Certificate on SSL ports. - </para> - <para>Truststore configuration and management is covered in <xref linkend="Java-Broker-Management-Managing-Truststores"/>.</para> - </section> - -</section> diff --git a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Overview.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Overview.xml deleted file mode 100644 index 691cf2aab3..0000000000 --- a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Overview.xml +++ /dev/null @@ -1,77 +0,0 @@ -<?xml version="1.0"?> -<!-- - - Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. - ---> -<section id="Java-Broker-Concepts-Overview"> - <title>Overview</title> - <para>The Broker comprises of a number of entities. This section summaries the purpose of - each of the entities and describes the relationships between them. These details are developed - further in the sub-sections that follow.</para> - <para>The most important entity is the <emphasis>Virtualhost</emphasis>. A virtualhost is an - independent namespace in which messaging is performed. A <emphasis>virtualhost</emphasis> exists - in a container called a <emphasis>virtualhost node</emphasis>. A virtualhost node has exactly - one virtualhost.</para> - <para><emphasis>Ports</emphasis> accept connections for messaging and management. The Broker - supports any number of ports. When connecting for messaging, the user specifies a virtualhost - name to indicate the virtualhost to which it is to be connected.</para> - <para><emphasis>Authentication Providers</emphasis> assert the identity of the user as it connects - for messaging or management. The Broker supports any number of authentication providers. Each - port is associated with exactly one authentication provider. The port uses the authentication - provider to assert the identity of the user as new connections are received.</para> - <para><emphasis>Group Providers</emphasis> provide mechanisms that provide grouping of users. A - Broker supports zero or more group providers.</para> - <para><emphasis>Access Control Provider</emphasis> allows the abilities of users (or groups of - users) to be restrained. A Broker can have zero or one access control providers.</para> - <para><emphasis>Keystores</emphasis> provide a repositories of certificates and are used when the - Broker accepts SSL connections. Any number of keystore providers can be defined. Keystores are - be associated with Ports defined to accepts SSL.</para> - <para><emphasis>Truststores</emphasis> provide a repositories of trust and are used to validate a - peer. Any number of truststore provides can be defined. Truststores can be associated with Ports - and other entities that form SSL connections.</para> - <para><emphasis>Remote Replication Nodes</emphasis> are used when the high availability feature is - in use. It is the remote representation of other virtualhost nodes that form part of the same - group.</para> - <para>These concepts will be developed over the forthcoming pages. The diagrams below also help - put these entities in context of one and other.</para> - <para><figure> - <title>Message Flow through Key Entities</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/Broker-MessageFlow.png" format="PNG" scalefit="1"/> - </imageobject> - <textobject> - <phrase>Message Flow through the Key Entities of the Broker</phrase> - </textobject> - </mediaobject> - </figure></para> - <para><figure> - <title>Broker Structure</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/Broker-Model.png" format="PNG" scalefit="1"/> - </imageobject> - <textobject> - <phrase>Broker Structure</phrase> - </textobject> - </mediaobject> - </figure> - </para> - -</section> diff --git a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Ports.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Ports.xml deleted file mode 100644 index 9f577ca5f4..0000000000 --- a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Ports.xml +++ /dev/null @@ -1,60 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<!-- - - Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. - ---> - -<section id="Java-Broker-Concepts-Ports"> - <title>Ports</title> - <para> The Broker supports configuration of <emphasis>Ports</emphasis> to specify the particular - AMQP messaging and HTTP/JMX management connectivity it offers for use. </para> - <para> Each Port is configured with the particular <emphasis>Protocols</emphasis> and - <emphasis>Transports</emphasis> it supports, as well as the <emphasis>Authentication - Provider</emphasis> to be used to authenticate connections. Where SSL is in use, the - <emphasis>Port</emphasis> configuration also defines which <emphasis>Keystore</emphasis> - to use and (where supported) which <emphasis>TrustStore(s)</emphasis> and whether Client - Certificates should be requested/required. </para> - <para> Different <emphasis>Ports</emphasis> can support different protocols, and many - <emphasis>Ports</emphasis> can be configured on the Broker.</para> - <para> The following AMQP protocols are currently supported by the Broker: <itemizedlist> - <listitem><para><emphasis>AMQP 0-8</emphasis></para></listitem> - <listitem><para><emphasis>AMQP 0-9</emphasis></para></listitem> - <listitem><para><emphasis>AMQP 0-9-1</emphasis></para></listitem> - <listitem><para><emphasis>AMQP 0-10</emphasis></para></listitem> - <listitem><para><emphasis>AMQP 1.0</emphasis></para></listitem> - </itemizedlist> - </para> - - <para> Additionally, HTTP and JMX ports can be configured for use by the associated management - plugins. </para> - <para>This diagram explains how Ports, <link - linkEnd="Java-Broker-Concepts-Authentication-Providers">Authentication Providers</link> - and an Access Control Provider work together to allow an application to form a connection to - a Virtualhost.<figure> - <title>Control flow during Authentication</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/Broker-PortAuthFlow.png" format="PNG" scalefit="1"/> - </imageobject> - <textobject> - <phrase>Control flow during Authentication</phrase> - </textobject> - </mediaobject> - </figure></para> -</section> diff --git a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Queues.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Queues.xml deleted file mode 100644 index 103a62ec38..0000000000 --- a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Queues.xml +++ /dev/null @@ -1,372 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<!-- - - Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. - ---> - -<!DOCTYPE entities [ -<!ENTITY % entities SYSTEM "../commonEntities.xml"> -%entities; -]> -<section id="Java-Broker-Concepts-Queues"> - <title>Queues</title> - <para><emphasis>Queue</emphasis>s are named entities within a <link linkend="Java-Broker-Concepts-Virtualhosts">Virtualhost</link> that - hold/buffer messages for later delivery to consumer applications. An <link - linkend="Java-Broker-Concepts-Exchanges">Exchange</link> for passing messages to a queue. - Consumers subscribe to a queue in order to receive messages for it. </para> - <para>The Broker supports different queue types, each with different delivery semantics. It also messages on a queue to be treated as a group.</para> - <section id="Java-Broker-Concepts-Queues-Types"> - <title>Types</title> - <para>The Broker supports four different queue types, each with different delivery semantics.<itemizedlist> - <listitem> - <para><link linkend="Java-Broker-Concepts-Queues-Types-Standard" - >Standard</link> - a simple First-In-First-Out (FIFO) queue</para> - </listitem> - <listitem> - <para><link linkend="Java-Broker-Concepts-Queues-Types-Priority" - >Priority</link> - delivery order depends on the priority of each message</para> - </listitem> - <listitem> - <para><link linkend="Java-Broker-Concepts-Queues-Types-Sorted">Sorted</link> - - delivery order depends on the value of the sorting key property in each message</para> - </listitem> - <listitem> - <para><link linkend="Java-Broker-Concepts-Queues-Types-LVQ">Last Value - Queue</link> - also known as an LVQ, retains only the last (newest) message received - with a given LVQ key value</para> - </listitem> - </itemizedlist></para> - <section id="Java-Broker-Concepts-Queues-Types-Standard"> - <title>Standard</title> - <para>A simple First-In-First-Out (FIFO) queue</para> - </section> - <section id="Java-Broker-Concepts-Queues-Types-Priority"> - <title>Priority</title> - <para>In a priority queue, messages on the queue are delivered in an order determined by the - <ulink url="&oracleJeeDocUrl;javax/jms/Message.html#getJMSPriority()">JMS priority message - header</ulink> within the message. By default Qpid supports the 10 priority levels - mandated by JMS, with priority value 0 as the lowest priority and 9 as the highest. </para> - <para>It is possible to reduce the effective number of priorities if desired.</para> - <para>JMS defines the <ulink url="&oracleJeeDocUrl;javax/jms/Message.html#DEFAULT_PRIORITY"> - default message priority</ulink> as 4. Messages sent without a specified priority use this - default. </para> - </section> - <section id="Java-Broker-Concepts-Queues-Types-Sorted"> - <title>Sorted Queues</title> - <para>Sorted queues allow the message delivery order to be determined by value of an arbitrary - <ulink url="&oracleJeeDocUrl;javax/jms/Message.html#getStringProperty()">JMS message - property</ulink>. Sort order is alpha-numeric and the property value must have a type - java.lang.String.</para> - <para>Messages sent to a sorted queue without the specified JMS message property will be - inserted into the 'last' position in the queue.</para> - </section> - <section id="Java-Broker-Concepts-Queues-Types-LVQ"> - <title>Last Value Queues (LVQ)</title> - <para>LVQs (or conflation queues) are special queues that automatically discard any message - when a newer message arrives with the same key value. The key is specified by arbitrary - <ulink url="&oracleJeeDocUrl;javax/jms/Message.html#getPropertyNames()">JMS message - property</ulink>.</para> - <para>An example of an LVQ might be where a queue represents prices on a stock exchange: when - you first consume from the queue you get the latest quote for each stock, and then as new - prices come in you are sent only these updates. </para> - <para>Like other queues, LVQs can either be browsed or consumed from. When browsing an - individual subscriber does not remove the message from the queue when receiving it. This - allows for many subscriptions to browse the same LVQ (i.e. you do not need to create and - bind a separate LVQ for each subscriber who wishes to receive the contents of the - LVQ).</para> - <para>Messages sent to an LVQ without the specified property will be delivered as normal and - will never be "replaced".</para> - </section> - </section> - <section id="Java-Broker-Concepts-Queues-QueueDeclareArguments"> - <title>Queue Declare Arguments</title> - <para>To create a priority, sorted or LVQ queue programmatically from JMX or AMQP, pass the - appropriate queue-declare arguments.</para> - <table> - <title>Queue-declare arguments understood for priority, sorted and LVQ queues</title> - <tgroup cols="4"> - <thead> - <row> - <entry>Queue type</entry> - <entry>Argument name</entry> - <entry>Argument name</entry> - <entry>Argument Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>priority</entry> - <entry>x-qpid-priorities</entry> - <entry>java.lang.Integer</entry> - <entry>Specifies a priority queue with given number priorities</entry> - </row> - <row> - <entry>sorted</entry> - <entry>qpid.queue_sort_key</entry> - <entry>java.lang.String</entry> - <entry>Specifies sorted queue with given message property used to sort the - entries</entry> - </row> - <row> - <entry>lvq</entry> - <entry>qpid.last_value_queue_key</entry> - <entry>java.lang.String</entry> - <entry>Specifies lvq queue with given message property used to conflate the - entries</entry> - </row> - </tbody> - </tgroup> - </table> - </section> - <section id="Java-Broker-Concepts-Queues-Message-Grouping"> - <title>Messaging Grouping</title> - <para> The broker allows messaging applications to classify a set of related messages as - belonging to a group. This allows a message producer to indicate to the consumer that a group - of messages should be considered a single logical operation with respect to the application. </para> - <para> The broker can use this group identification to enforce policies controlling how messages - from a given group can be distributed to consumers. For instance, the broker can be configured - to guarantee all the messages from a particular group are processed in order across multiple - consumers. </para> - <para> For example, assume we have a shopping application that manages items in a virtual - shopping cart. A user may add an item to their shopping cart, then change their mind and - remove it. If the application sends an <emphasis>add</emphasis> message to the broker, - immediately followed by a <emphasis>remove</emphasis> message, they will be queued in the - proper order - <emphasis>add</emphasis>, followed by <emphasis>remove</emphasis>. </para> - <para> However, if there are multiple consumers, it is possible that once a consumer acquires - the <emphasis>add</emphasis> message, a different consumer may acquire the - <emphasis>remove</emphasis> message. This allows both messages to be processed in parallel, - which could result in a "race" where the <emphasis>remove</emphasis> operation is incorrectly - performed before the <emphasis>add</emphasis> operation. </para> - <section id="Java-Broker-Concepts-Queues-GroupingMessages"> - <title>Grouping Messages</title> - <para> In order to group messages, the application would designate a particular message header - as containing a message's <emphasis>group identifier</emphasis>. The group identifier stored - in that header field would be a string value set by the message producer. Messages from the - same group would have the same group identifier value. The key that identifies the header - must also be known to the message consumers. This allows the consumers to determine a - message's assigned group. </para> - <para> The header that is used to hold the group identifier, as well as the values used as - group identifiers, are totally under control of the application. </para> - </section> - <section id="Java-Broker-Concepts-Queues-BrokerRole"> - <title> The Role of the Broker in Message Grouping </title> - <para> The broker will apply the following processing on each grouped message: <itemizedlist> - <listitem> - <para>Enqueue a received message on the destination queue.</para> - </listitem> - <listitem> - <para>Determine the message's group by examining the message's group identifier - header.</para> - </listitem> - <listitem> - <para>Enforce <emphasis>consumption ordering</emphasis> among messages belonging to the - same group. <emphasis>Consumption ordering</emphasis> means one of two things - depending on how the queue has been configured. </para> - <itemizedlist> - <listitem> - <para> In default mode, a group gets assigned to a single consumer for the lifetime - of that consumer, and the broker will pass all subsequent messages in the group to - that consumer. </para> - </listitem> - <listitem> - <para>In 'shared groups' mode (which gives the same behaviour as the Qpid C++ - Broker) the broker enforces a looser guarantee, namely that all the - <emphasis>currently unacknowledged messages</emphasis> in a group are sent to - the same consumer, but the consumer used may change over time even if the - consumers do not. This means that only one consumer can be processing messages - from a particular group at any given time, however if the consumer acknowledges - all of its acquired messages then the broker <emphasis>may</emphasis> pass the - next pending message in that group to a different consumer. </para> - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - </para> - <para> The absence of a value in the designated group header field of a message is treated as - follows: <itemizedlist> - <listitem> - <para> In default mode, failure for a message to specify a group is treated as a desire - for the message not to be grouped at all. Such messages will be distributed to any - available consumer, without the ordering quarantees imposed by grouping. </para> - </listitem> - <listitem> - <para> In 'shared groups' mode (which gives the same behaviour as the Qpid C++ Broker) - the broker assigns messages without a group value to a 'default group'. Therefore, all - such "unidentified" messages are considered by the broker as part of the same group, - which will handled like any other group. The name of this default group is - "qpid.no-group", although it can be customised as detailed below. </para> - </listitem> - </itemizedlist> - </para> - <para> Note that message grouping has no effect on queue browsers.</para> - <para> Note well that distinct message groups would not block each other from delivery. For - example, assume a queue contains messages from two different message groups - say group "A" - and group "B" - and they are enqueued such that "A"'s messages are in front of "B". If the - first message of group "A" is in the process of being consumed by a client, then the - remaining "A" messages are blocked, but the messages of the "B" group are available for - consumption by other consumers - even though it is "behind" group "A" in the queue. </para> -</section> -</section> - <section id="Java-Broker-Concepts-Queues-SetLowPrefetch"> - <title>Using low pre-fetch with special queue types</title> - <para>Qpid clients receive buffered messages in batches, sized according to the pre-fetch value. - The current default is 500. </para> - <para>However, if you use the default value you will probably <emphasis>not</emphasis> see - desirable behaviour when using priority, sorted, lvq or grouped queues. Once the broker has - sent a message to the client its delivery order is then fixed, regardless of the special - behaviour of the queue. </para> - <para>For example, if using a priority queue and a prefetch of 100, and 100 messages arrive with - priority 2, the broker will send these messages to the client. If then a new message arrives - will priority 1, the broker cannot leap frog messages of lower priority. The priority 1 will - be delivered at the front of the next batch of messages to be sent to the client.</para> - <para> So, you need to set the prefetch values for your client (consumer) to make this sensible. - To do this set the Java system property <varname>max_prefetch</varname> on the client - environment (using -D) before creating your consumer. </para> - <para>A default for all client connections can be set via a system property: </para> - <programlisting> --Dmax_prefetch=1 -</programlisting> - <para> The prefetch can be also be adjusted on a per connection basis by adding a - <varname>maxprefetch</varname> value to the <ulink url="&qpidjmsdocClientConectionUrl;" - >Connection URLs</ulink> - </para> - <programlisting> -amqp://guest:guest@client1/development?maxprefetch='1'&brokerlist='tcp://localhost:5672' -</programlisting> - <para>Setting the Qpid pre-fetch to 1 will give exact queue-type semantics as perceived by the - client however, this brings a performance cost. You could test with a slightly higher - pre-fetch to trade-off between throughput and exact semantics.</para> - </section> - <section id="Java-Broker-Concepts-Queue-EnsureNonDestructiveConsumers"> - <title>Forcing all consumers to be non-destructive</title> - <para>When a consumer attaches to a queue, the normal behaviour is that messages are - sent to that consumer are acquired exclusively by that consumer, and when the consumer - acknowledges them, the messages are removed from the queue.</para> - <para>Another common pattern is to have queue "browsers" which send all messages to the - browser, but do not prevent other consumers from receiving the messages, and do not - remove them from the queue when the browser is done with them. Such a browser is an - instance of a "non-destructive" consumer.</para> - <para>If every consumer on a queue is non destructive then we can obtain some interesting - behaviours. In the case of a <link linked="Java-Broker-Concepts-Queues-Types-LVQ">LVQ - </link> then the queue will always contain the most up to date value for every key. For - a standard queue, if every consumer is non-destructive then we have something that - behaves like a topic (every consumer receives every message) except that instead of - only seeing messages that arrive after the point at which the consumer is created, all - messages which have not been removed due to TTL expiry (or, in the case of LVQs, - overwirtten by newer values for the same key).</para> - <para>A queue can be created to enforce all consumers are non-destructive. This can be - be achieved using the following queue declare argument:</para> - <table> - <tgroup cols="3"> - <thead> - <row> - <entry>Argument Name</entry> - <entry>Argument Type</entry> - <entry>Argument Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>qpid.ensure_nondestructive_consumers</entry> - <entry>java.lang.Boolean</entry> - <entry>Set to true if the queue should make all consumers attached to it behave - non-destructively. (Default is false).</entry> - </row> - </tbody> - </tgroup> - </table> - <para>Through the <link linkend="Java-Broker-Management-Channel-REST-API">REST</link> api, - the equivalent attribute is named <varname>ensureNondestructiveConsumers</varname>. - </para> - <section> - <title>Bounding size using min/max TTL</title> - <para>For queues other than LVQs, having only non-destructive consumers could mean that - messages would never get deleted, leaving the queue to grow unconstrainedly. To - prevent this you can use the ability to set the maximum TTL of the queue. To ensure - all messages have the same TTL you could also set the minimum TTL to the same value. - </para> - <para>Minimum/Maximum TTL for a queue can be set though the HTTP Management UI, using the - REST API or by hand editing the configuration file (for JSON configuration stores). - The attribute names are <varname>minimumMessageTtl</varname> and - <varname>maximumMessageTtl</varname> and the TTL value is given in milliseconds.</para> - </section> - <section> - <title>Choosing to receive messages based on arrival time</title> - <para>A queue with no destructive consumers will retain all messages until they expire - due to TTL. It may be the case that a consumer only wishes to receive messages - that have been sent in the last 60 minutes, and any new messages that arrive, or - alternatively it may wish only to receive newly arriving messages and not any that - are already in the queue. This can be achieved by using a filter on the arrival - time.</para> - <para>A special parameter <varname>x-qpid-replay-period</varname> can be used in the - consumer declaration to control the messages the consumer wishes to receive. The - value of <varname>x-qpid-replay-period</varname> is the time, in seconds, for which - the consumer wishes to see messages. A replay period of 0 indicates only newly - arriving messages should be sent. A replay period of 3600 indicates that only - messages sent in the last hour - along with any newly arriving messages - should be - sent.</para> - <table> - <title>Setting the replay period</title> - <tgroup cols="2"> - <thead> - <row> - <entry>Syntax</entry> - <entry>Example</entry> - </row> - </thead> - <tbody> - <row> - <entry>Addressing</entry> - <entry>myqueue ; { link : { x-subscribe: { arguments : { x-qpid-replay-period : '3600' } } } }</entry> - </row> - <row> - <entry>Binding URL</entry> - <entry>direct://amq.direct/myqueue/myqueue?x-qpid-replay-period='3600'</entry> - </row> - </tbody> - </tgroup> - </table> - </section> - <section> - <title>Setting a default filter</title> - <para>A common case might be that the desired default behaviour is that newly attached consumers - see only newly arriving messages (i.e. standard topic-like behaviour) but other consumers - may wish to start their message stream from some point in the past. This can be achieved by - setting a default filter on the queue so that consumers which do not explicitly set a replay - period get a default (in this case the desired default would be 0).</para> - <para>The default filter set for a queue can be set via the REST API using the attribute named - <varname>defaultFilters</varname>. This value is a map from filter name to type and arguments. - To set the default behaviour for the queue to be that consumers only receive newly arrived - messages, then you should set this attribute to the value:</para> - <screen> - { "x-qpid-replay-period" : { "x-qpid-replay-period" : [ "0" ] } } - </screen> - <para> - If the desired default behaviour is that each consumer should see all messages arriving in - the last minute, as well as all new messages then the value would need to be:</para> - <screen> - { "x-qpid-replay-period" : { "x-qpid-replay-period" : [ "60" ] } } - </screen> - - </section> - - - </section> - -</section> diff --git a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-RemoteReplicationNodes.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-RemoteReplicationNodes.xml deleted file mode 100644 index b9162fd8e3..0000000000 --- a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-RemoteReplicationNodes.xml +++ /dev/null @@ -1,27 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<!-- - - Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. - ---> - -<section id="Java-Broker-Concepts-RemoteReplicationNodes"> - <title>Remote Replication Nodes</title> - <para>Used for HA only. A <emphasis>remote replication node</emphasis> is a representation of - another virtualhost node in the group.</para> -</section> diff --git a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhost-Nodes.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhost-Nodes.xml deleted file mode 100644 index c1dd903aed..0000000000 --- a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhost-Nodes.xml +++ /dev/null @@ -1,37 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<!-- - - Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. - ---> - -<section id="Java-Broker-Concepts-Virtualhost-Nodes"> - <title>Virtualhost Nodes</title> - <para>A <emphasis>virtualhost node</emphasis> is a container for the virtualhost. It has exactly - one virtualhost.</para> - <para>A <emphasis>virtualhost node</emphasis> is backed by storage. This storage is used to record - the durable entities that exist beneath the virtualhost node (the virtualhost, queues, exchanges - etc).</para> - <para>When HA is in use, it is the virtualhost nodes of many Brokers that come together to form - the group. The virtualhost nodes together elect a master. When the high availability feature is - in use, the virtualhost node has <link linkend="Java-Broker-Concepts-RemoteReplicationNodes" - >remote replications nodes</link>. There is a remote replication node corresponding to each - remote virtualhost node that form part of the group.</para> - - -</section> diff --git a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhosts.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhosts.xml deleted file mode 100644 index ecc898627e..0000000000 --- a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhosts.xml +++ /dev/null @@ -1,60 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<!-- - - Licensed to the Apache Software Foundation (ASF) under one - or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. - ---> - -<section id="Java-Broker-Concepts-Virtualhosts"> - <title>Virtualhosts</title> - <para>A virtualhost is a namespace in which messaging is performed. Virtualhosts are independent; - the messaging goes on a within a virtualhost is independent of any messaging that goes on in - another virtualhost. For instance, a queue named <emphasis>foo</emphasis> defined in one - virtualhost is completely independent of a queue named <emphasis>foo</emphasis> in another - virtualhost.</para> - <para>A virtualhost is identified by a name which must be unique broker-wide. Clients use the name - to identify the virtualhost to which they wish to connect when they connect.</para> - <para>A virtualhost exists in a container called a virtualhost node.</para> - <para>The virtualhost comprises of a number of entities. This section summaries the purpose of - each of the entities and describes the relationships between them. These details are developed - further in the sub-sections that follow.</para> - <para><emphasis>Exchanges</emphasis> is a named entity within the Virtual Host which receives - messages from producers and routes them to matching Queues.</para> - <para><emphasis>Queues</emphasis> are named entities that hold messages for delivery to consumer - applications.</para> - <para><emphasis>Bindings</emphasis> are relationships between Exchanges and Queue that facilitate - routing of messages from the Exchange to the Queue.</para> - <para><emphasis>Connections</emphasis> represent a live connection to the virtualhost from a - messaging client.</para> - <para>A <emphasis>Session</emphasis> represents a context for the production or consumption of - messages. Connection support many Sessions.</para> - <para>A <emphasis>Consumer</emphasis> represents a live consumer that is attached to queue.</para> - <para> The following diagram depicts the Virtualhost model: <figure> - <title>Virtualhost Model</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/VirtualHost-Model.png" format="PNG" scalefit="1"/> - </imageobject> - <textobject> - <phrase>Virtual Host Model</phrase> - </textobject> - </mediaobject> - </figure> - </para> - <para>A <emphasis>virtualhost</emphasis> is backed by storage which is used to store the messages.</para> -</section> |