diff options
Diffstat (limited to 'qpid/doc/book/src/old')
38 files changed, 9687 insertions, 0 deletions
diff --git a/qpid/doc/book/src/old/ACL.xml b/qpid/doc/book/src/old/ACL.xml new file mode 100644 index 0000000000..ceb7cecb23 --- /dev/null +++ b/qpid/doc/book/src/old/ACL.xml @@ -0,0 +1,800 @@ +<?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="qpid_ACL"> + <title> + ACL + </title> + + <section role="h2" id="ACL-v2ACLfileformatforbrokers"> + <title> + v2 ACL file format for brokers + </title> + <para> + This new ACL implementation has been designed for implementation + and interoperability on all Qpid brokers. It is currently + supported in the following brokers: + </para> + + <table><title>ACL Support in Qpid Broker Versions</title> + <tgroup cols="2"> + <thead> + <row> + <entry> + Broker + </entry> + <entry> + Version + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + C++ + </entry> + <entry> + M4 onward + </entry> + </row> + <row> + <entry> + Java + </entry> + <entry> + M5 anticipated + </entry> + </row> + </tbody> + </tgroup></table> + + <para> + Contents + </para> + <itemizedlist> + <listitem><para> + <xref linkend="ACL-v2ACLfileformatforbrokers"/> + </para></listitem> + <listitem><para> + <itemizedlist> + <listitem><para> + <xref linkend="ACL-Specification"/> + </para></listitem> + <listitem><para> + <xref linkend="ACL-Validation"/> + </para></listitem> + <listitem><para> + <xref linkend="ACL-Examplefile-3A"/> + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <xref linkend="ACL-DesignDocumentation"/> + </para></listitem> + <listitem><para> + <itemizedlist> + <listitem><para> + <xref linkend="ACL-MappingofACLtrapstoactionandtype"/> + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <xref linkend="ACL-v2ACLUserGuide"/> + </para></listitem> + <listitem><para> + <itemizedlist> + <listitem><para> + <xref linkend="ACL-WritingGood-2FFastACL"/> + </para></listitem> + <listitem><para> + <xref linkend="ACL-GettingACLtoLog"/> + </para></listitem> + <listitem><para> + <xref linkend="ACL-UserId-2FdomainsrunningwithCbroker"/> + </para></listitem> + </itemizedlist> + </para></listitem> + </itemizedlist> + <para> + + </para><section role="h3" id="ACL-Specification"><title> + Specification + </title> + <para> + Notes on file formats + </para><itemizedlist> + <listitem><para>A line starting with the character '#' will be considered a + comment, and are ignored. + </para></listitem> + <listitem><para>Since the '#' char (and others that are commonly used for + comments) are commonly found in routing keys and other AMQP + literals, it is simpler (for now) to hold off on allowing + trailing comments (ie comments in which everything following a + '#' is considered a comment). This could be reviewed later once + the rest of the format is finalized. + </para></listitem> + <listitem><para>Empty lines ("") and lines that contain only whitespace (any + combination of ' ', '\f', '\n', '\r', '\t', '\v') are ignored. + </para></listitem> + <listitem><para>All tokens are case sensitive. "name1" != "Name1" and + "create" != "CREATE". + </para></listitem> + <listitem><para>Group lists may be extended to the following line by + terminating the line with the '\' character. However, this may + only occur after the group name or any of the names following the + group name. Empty extension lines (ie just a '\' character) are + not permitted. + + <programlisting> +# Examples of extending group lists using a trailing '\' character + +group group1 name1 name2 \ + name3 name4 \ + name5 + +group group2 \ + group1 \ + name6 + +# The following are illegal: + +# '\' must be after group name +group \ + group3 name7 name8 + +# No empty extension lines +group group4 name9 \ + \ + name10 +</programlisting> + + </para></listitem> + <listitem><para>Additional whitespace (ie more than one whitespace char) + between and after tokens is ignored. However group and acl + definitions must start with "group" or "acl" respectively and + with no preceding whitespace. + </para></listitem> + <listitem><para>All acl rules are limited to a single line. + </para></listitem> + <listitem><para>Rules are interpreted from the top of the file down until the + name match is obtained; at which point processing stops. + </para></listitem> + <listitem><para>The keyword "all" is reserved, and matches all individuals, + groups and actions. It may be used in place of a group or + individual name and/or an action - eg "acl allow all all", "acl + deny all all" or "acl deny user1 all". + </para></listitem> + <listitem><para>The last line of the file (whether present or not) will be + assumed to be "acl deny all all". If present in the file, any + lines below this one are ignored. + </para></listitem> + <listitem><para>Names and group names may contain only a-z, A-Z, 0-9, + '-','_'. + </para></listitem> + <listitem><para>Rules must be preceded by any group definitions they may use; + any name not previously defined as a group will be assumed to be + that of an individual. + </para></listitem> + <listitem><para>ACL rules must have the following tokens in order on a single + line: + <itemizedlist> + <listitem><para>The string literal "acl"; + </para></listitem> + <listitem><para>The permission; + </para></listitem> + <listitem><para>The name of a single group or individual or the keyword + "all"; + </para></listitem> + <listitem><para>The name of an action or the keyword "all"; + </para></listitem> + <listitem><para>Optionally, a single object name or the keyword "all"; + </para></listitem> + <listitem><para>If the object is present, then optionally one or more + property name-value pair(s) (in the form property=value). + </para></listitem> + </itemizedlist> + </para></listitem> + </itemizedlist> + <programlisting> +user = username[@domain[/realm]] +user-list = user1 user2 user3 ... +group-name-list = group1 group2 group3 ... + +group <group-name> = [user-list] [group-name-list] + + +permission = [allow|allow-log|deny|deny-log] +action = [consume|publish|create|access|bind|unbind|delete|purge|update] +object = [virtualhost|queue|exchange|broker|link|route|method] +property = [name|durable|owner|routingkey|passive|autodelete|exclusive|type|alternate|queuename|schemapackage|schemaclass] + +acl permission {<group-name>|<user-name>|"all"} {action|"all"} [object|"all"] [property=<property-value>] +</programlisting> +<!--h3--></section> + <section role="h3" id="ACL-Validation"><title> + Validation + </title> + <para> + The new ACL file format needs to perform validation on the acl + rules. The validation should be performed depending on the set + value: + </para><para> + strict-acl-validation=none + The default setting should be 'warn' + </para><para> + On validation of this acl the following checks would be expected: + </para> + <programlisting> +acl allow client publish routingkey=exampleQueue exchange=amq.direct +</programlisting> + <orderedlist> + <listitem><para>The If the user 'client' cannot be found, if the + authentication mechanism cannot be queried then a 'user' value + should be added to the file. + </para></listitem> + <listitem><para>There is an exchange called 'amq.direct' + </para></listitem> + <listitem><para>There is a queue bound to 'exampleQueue' on 'amq.direct' + </para></listitem> + </orderedlist><para> + Each of these checks that fail will result in a log statement + being generated. + </para><para> + In the case of a fatal logging the full file will be validated + before the broker shuts down. + </para> +<!--h3--></section> + + + <section role="h3" id="ACL-Examplefile-3A"><title> + Example file: + </title> + + <programlisting> + +# Some groups +group admin ted@QPID martin@QPID +group user-consume martin@QPID ted@QPID +group group2 kim@QPID user-consume rob@QPID +group publisher group2 \ + tom@QPID andrew@QPID debbie@QPID + +# Some rules +acl allow carlt@QPID create exchange name=carl.* +acl deny rob@QPID create queue +acl allow guest@QPID bind exchange name=amq.topic routingkey=stocks.ibm.# owner=self +acl allow user-consume create queue name=tmp.* + +acl allow publisher publish all durable=false +acl allow publisher create queue name=RequestQueue +acl allow consumer consume queue durable=true +acl allow fred@QPID create all +acl allow bob@QPID all queue +acl allow admin all +acl deny kim@QPID all +acl allow all consume queue owner=self +acl allow all bind exchange owner=self + +# Last (default) rule +acl deny all all +</programlisting> + +<!--h3--></section> + <!--h2--></section> + + + <section role="h2" id="ACL-DesignDocumentation"><title> + Design Documentation + </title> + <section role="h3" id="ACL-MappingofACLtrapstoactionandtype"><title> + Mapping of ACL + traps to action and type + </title> + <para> + The C++ broker maps the ACL traps in the follow way for AMQP + 0-10: + The Java broker currently only performs ACLs on the AMQP + connection not on management functions: + </para> + + <table> + <title>Mapping ACL Traps</title> + <tgroup cols="5"> + <thead> + <row> + <entry> + Object + </entry> + <entry> + Action + </entry> + <entry> + Properties + </entry> + <entry> + Trap C++ + </entry> + <entry> + Trap Java + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + Exchange + </entry> + <entry> + Create + </entry> + <entry> + name type alternate passive durable + </entry> + <entry> + ExchangeHandlerImpl::declare + </entry> + <entry> + ExchangeDeclareHandler + </entry> + </row> + <row> + <entry> + Exchange + </entry> + <entry> + Delete + </entry> + <entry> + name + </entry> + <entry> + ExchangeHandlerImpl::delete + </entry> + <entry> + ExchangeDeleteHandler + </entry> + </row> + <row> + <entry> + Exchange + </entry> + <entry> + Access + </entry> + <entry> + name + </entry> + <entry> + ExchangeHandlerImpl::query + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + Exchange + </entry> + <entry> + Bind + </entry> + <entry> + name routingkey queuename owner + </entry> + <entry> + ExchangeHandlerImpl::bind + </entry> + <entry> + QueueBindHandler + </entry> + </row> + <row> + <entry> + Exchange + </entry> + <entry> + Unbind + </entry> + <entry> + name routingkey + </entry> + <entry> + ExchangeHandlerImpl::unbind + </entry> + <entry> + ExchangeUnbindHandler + </entry> + </row> + <row> + <entry> + Exchange + </entry> + <entry> + Access + </entry> + <entry> + name queuename routingkey + </entry> + <entry> + ExchangeHandlerImpl::bound + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + Exchange + </entry> + <entry> + Publish + </entry> + <entry> + name routingKey + </entry> + <entry> + SemanticState::route + </entry> + <entry> + BasicPublishMethodHandler + </entry> + </row> + <row> + <entry> + Queue + </entry> + <entry> + Access + </entry> + <entry> + name + </entry> + <entry> + QueueHandlerImpl::query + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + Queue + </entry> + <entry> + Create + </entry> + <entry> + name alternate passive durable exclusive autodelete + </entry> + <entry> + QueueHandlerImpl::declare + </entry> + <entry> + QueueDeclareHandler + </entry> + </row> + <row> + <entry> + Queue + </entry> + <entry> + Purge + </entry> + <entry> + name + </entry> + <entry> + QueueHandlerImpl::purge + </entry> + <entry> + QueuePurgeHandler + </entry> + </row> + <row> + <entry> + Queue + </entry> + <entry> + Purge + </entry> + <entry> + name + </entry> + <entry> + Management::Queue::purge + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + Queue + </entry> + <entry> + Delete + </entry> + <entry> + name + </entry> + <entry> + QueueHandlerImpl::delete + </entry> + <entry> + QueueDeleteHandler + </entry> + </row> + <row> + <entry> + Queue + </entry> + <entry> + Consume + </entry> + <entry> + name (possibly add in future?) + </entry> + <entry> + MessageHandlerImpl::subscribe + </entry> + <entry> + BasicConsumeMethodHandler + BasicGetMethodHandler + </entry> + </row> + <row> + <entry> + <Object> + </entry> + <entry> + Update + </entry> + <entry> + + </entry> + <entry> + ManagementProperty::set + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + <Object> + </entry> + <entry> + Access + </entry> + <entry> + + </entry> + <entry> + ManagementProperty::read + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + Link + </entry> + <entry> + Create + </entry> + <entry> + + </entry> + <entry> + Management::connect + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + Route + </entry> + <entry> + Create + </entry> + <entry> + + </entry> + <entry> + Management:: -createFederationRoute- + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + Route + </entry> + <entry> + Delete + </entry> + <entry> + + </entry> + <entry> + Management:: -deleteFederationRoute- + </entry> + <entry> + + </entry> + </row> + <row> + <entry> + Virtualhost + </entry> + <entry> + Access + </entry> + <entry> + name + </entry> + <entry> + TBD + </entry> + <entry> + ConnectionOpenMethodHandler + </entry> + </row> + </tbody> + </tgroup></table><para> + Management actions that are not explicitly given a name property + it will default the name property to management method name, if + the action is 'W' Action will be 'Update', if 'R' Action will be + 'Access'. + </para><para> + for example, if the mgnt method 'joinCluster' was not mapped in + schema it will be mapped in ACL file as follows + </para> + + <table> + <title>Mapping Management Actions to ACL</title> + <tgroup cols="3"> + <thead> + <row> + <entry> + Object + </entry> + <entry> + Action + </entry> + <entry> + Property + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + Broker + </entry> + <entry> + Update + </entry> + <entry> + name=joinCluster + </entry> + </row> + </tbody> + </tgroup></table> + + <!--h3--></section> + <!--h2--></section> + + + <section role="h2" id="ACL-v2ACLUserGuide"><title> + v2 ACL User Guide + </title> + <section role="h3" id="ACL-WritingGood-2FFastACL"><title> + Writing Good/Fast ACL + </title> + <para> + The file gets read top down and rule get passed based on the + first match. In the following example the first rule is a dead + rule. I.e. the second rule is wider than the first rule. DON'T do + this, it will force extra analysis, worst case if the parser does + not kill the dead rule you might get a false deny. + </para> + <programlisting> +allow peter@QPID create queue name=tmp <-- dead rule!! +allow peter@QPID create queue +deny all all +</programlisting> + <para> + By default files end with + </para> + <programlisting> +deny all all +</programlisting> + <para> + the mode of the ACL engine can be swapped to be allow based by + putting the following at the end of the file + </para> + <programlisting> +allow all all +</programlisting> + <para> + Note that 'allow' based file will be a LOT faster for message + transfer. This is because the AMQP specification does not allow + for creating subscribes on publish, so the ACL is executed on + every message transfer. Also, ACL's rules using less properties + on publish will in general be faster. + </para> + <!--h3--></section> + + <section role="h3" id="ACL-GettingACLtoLog"><title> + Getting ACL to Log + </title> + <para> + In order to get log messages from ACL actions use allow-log and + deny-log for example + </para> + <programlisting> +allow-log john@QPID all all +deny-log guest@QPID all all +</programlisting> + <!--h3--></section> + + <section role="h3" id="ACL-UserId-2FdomainsrunningwithCbroker"><title> + User Id / + domains running with C++ broker + </title> + <para> + The user-id used for ACL is taken from the connection user-id. + Thus in order to use ACL the broker authentication has to be + setup. i.e. (if --auth no is used in combination with ACL the + broker will deny everything) + </para><para> + The user id in the ACL file is of the form + <user-id>@<domain> The Domain is configured via the + SASL configuration for the broker, and the domain/realm for qpidd + is set using --realm and default to 'QPID'. + </para><para> + To load the ACL module use, load the acl module cmd line or via + the config file + </para> + <programlisting> +./src/qpidd --load-module src/.libs/acl.so +</programlisting> + <para> + The ACL plugin provides the following option '--acl-file'. If do + ACL file is supplied the broker will not enforce ACL. If an ACL + file name is supplied, and the file does not exist or is invalid + the broker will not start. + </para> + <programlisting> +ACL Options: + --acl-file FILE The policy file to load from, loaded from data dir +</programlisting> + + <!--h3--></section> + <!--h2--></section> + +</section> diff --git a/qpid/doc/book/src/old/AMQP-.NET-Messaging-Client.xml b/qpid/doc/book/src/old/AMQP-.NET-Messaging-Client.xml new file mode 100644 index 0000000000..1d4001942b --- /dev/null +++ b/qpid/doc/book/src/old/AMQP-.NET-Messaging-Client.xml @@ -0,0 +1,108 @@ +<?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. + +--> + +<chapter> + <title> + AMQP .NET Messaging Client + </title> + <para> + Currently the .NET code base provides two client libraries that + are compatible respectively with AMQP 0.8 and 0.10. The 0.8 client + is located in <filename>qpid\dotnet</filename> and the 0.10 client + in: <filename>qpid\dotnet\client-010</filename>. + </para> + <para> + You will need an AMQP broker to fully use those client libraries. + Use M4 or later C++ broker for AMQP 0.10 or Java broker for AMQP + 0.8/0.9. + </para> + <section role="h3" id="AMQP.NETMessagingClient-UserGuides"> + <title> + User Guides + </title> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="NET-User-Guide.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Excel-AddIn.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="WCF.xml"/> + </section> + + <section role="h3" id="AMQP.NETMessagingClient-Examples"> + <title> + Examples + </title> + <itemizedlist> + <listitem> + <para> + <ulink url="http://svn.apache.org/viewvc/qpid/trunk/qpid/dotnet/client-010/examples/"/> + </para> + </listitem> + </itemizedlist> + <!--h3--> + </section> + +<!-- + + <section role="h3" id="AMQP.NETMessagingClient-DeveloperGuidelines"> + <title> + Developer Guidelines + </title> + <itemizedlist> + <listitem> + <para> + <xref linkend="qpid_Developer-Pages"/> + </para> + </listitem> + <listitem> + <para>Coding Standards </para> + </listitem> + <listitem> + <para>How Tos + <itemizedlist> + <listitem> + <para> + <xref linkend="qpid_Build-.NET-Client"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="qpid_Releasing"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="qpid_Run-tests"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="qpid_Setup-.Net-Client-on-Windows"/> + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + </section> + --> + + +</chapter> diff --git a/qpid/doc/book/src/old/AMQP-C++-Messaging-Client.xml b/qpid/doc/book/src/old/AMQP-C++-Messaging-Client.xml new file mode 100644 index 0000000000..73a2cd6c0b --- /dev/null +++ b/qpid/doc/book/src/old/AMQP-C++-Messaging-Client.xml @@ -0,0 +1,61 @@ +<?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. + +--> + +<chapter > + <title> + AMQP C++ Messaging Client + </title> + <section role="h3" id="AMQPCPPMessagingClient-UserGuides"> + <title> + User Guides + </title> + <itemizedlist> + <listitem> + <para> + <ulink url="http://qpid.apache.org/docs/api/cpp/html/index.html">C++ Client API (AMQP 0-10)</ulink> + </para> + </listitem> + </itemizedlist> + <!--h3--> + </section> + + <section role="h3" id="AMQPCPPMessagingClient-Examples"> + <title> + Examples + </title> + <itemizedlist> + <listitem> + <para> + <ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/cpp/examples/">AMQP C++ Client Examples </ulink> + </para> + </listitem> + <listitem> + <para> + <ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/cpp/examples/README.txt">Running the AMQP C++ Client Examples </ulink> + </para> + </listitem> + </itemizedlist> + <!--h3--> + </section> + + +</chapter> diff --git a/qpid/doc/book/src/old/AMQP-Java-JMS-Messaging-Client.xml b/qpid/doc/book/src/old/AMQP-Java-JMS-Messaging-Client.xml new file mode 100644 index 0000000000..8c14d67e14 --- /dev/null +++ b/qpid/doc/book/src/old/AMQP-Java-JMS-Messaging-Client.xml @@ -0,0 +1,94 @@ +<?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. + +--> + +<chapter> + + <title> + AMQP Java JMS Messaging Client + </title> + + <para>The Java Client supported by Qpid implements the <ulink + url="http://java.sun.com/products/jms/docs.html">Java JMS 1.1 + Specification</ulink>. </para> + + + <section role="h3" + id="AMQPJavaJMSMessagingClient-GeneralUserGuides"> + <title>General User Guides</title> + + +<!-- +Does not seem to exist! + + <listitem><para>AMQP Java JMS Client Feature Guide + </para></listitem> + +http://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=qpid&title=JMS-Client-Feature-Guide&linkCreation=true&fromPageId=4589057 +--> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="System-Properties.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Connection-URL-Format.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Binding-URL-Format.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-JMS-Selector-Syntax.xml"/> + +<!-- + <listitem><para>How to Use JNDI to configure the AMQP Java JMS Client + </para></listitem> + <listitem><para>Using the AMQP Java JMS Client with RT Java + </para></listitem> + <listitem><para>AMQP Java JMS Client Tuning Guide + </para></listitem> +--> + +<!--h3--></section> + + <section role="h3" id="AMQPJavaJMSMessagingClient-AMQPJavaJMSExamples"> + + <title>AMQP Java JMS Examples </title> + + <itemizedlist> + <listitem><para> + <ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/java/client/example/">Examples Directory</ulink> + </para></listitem> + + <listitem><para> + <ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/java/client/example/src/main/java/runSample.sh">Script for running examples</ulink> + </para></listitem> + <listitem><para> + <ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/java/client/example/src/main/java/org/apache/qpid/example/jmsexample/direct/">Direct Example</ulink> + </para></listitem> + <listitem><para> + <ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/java/client/example/src/main/java/org/apache/qpid/example/jmsexample/fanout/">Fanout Example</ulink> + </para></listitem> + <listitem><para> + <ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/java/client/example/src/main/java/org/apache/qpid/example/jmsexample/pubsub">Pub-Sub Example</ulink> + </para></listitem> + <listitem><para> + <ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/java/client/example/src/main/java/org/apache/qpid/example/jmsexample/requestResponse/">Request/Response Example</ulink> + </para></listitem> + <listitem><para> + <ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/java/client/example/src/main/java/org/apache/qpid/example/jmsexample/transacted/">Transacted Example</ulink></para></listitem> + </itemizedlist> + +<!--h3--></section> + +</chapter> diff --git a/qpid/doc/book/src/old/AMQP-Messaging-Broker-CPP.xml b/qpid/doc/book/src/old/AMQP-Messaging-Broker-CPP.xml new file mode 100644 index 0000000000..b4e0deb13d --- /dev/null +++ b/qpid/doc/book/src/old/AMQP-Messaging-Broker-CPP.xml @@ -0,0 +1,70 @@ +<?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. + +--> + +<part> + <title>AMQP Messaging Broker (Implemented in C++)</title> + <partintro> + <para>Qpid provides two AMQP messaging brokers:</para> + + <itemizedlist> + <listitem><para>Implemented in C++ - high performance, low latency, and RDMA support.</para></listitem> + <listitem><para>Implemented in Java - Fully JMS compliant, runs on any Java platform.</para></listitem> + </itemizedlist> + + <para>Both AMQP messaging brokers support clients in multiple languages, as long as the messaging client and the messaging broker use the same version of AMQP. See <link linkend="AMQP-Compatibility"/> to see which messaging clients work with each broker.</para> + + <para>This section contains information specific to the broker that is implemented in C++.</para> + </partintro> + +<chapter> + <title> + Running the AMQP Messaging Broker + </title> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Running-CPP-Broker.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Cheat-Sheet-for-configuring-Queue-Options.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Cheat-Sheet-for-configuring-Exchange-Options.xml"/> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Using-Broker-Federation.xml"/> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="SSL.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="LVQ.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="queue-state-replication.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Active-Active-Cluster.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ACL.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="producer-flow-control.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Using-message-groups.xml"/> +</chapter> + + +<chapter id="chapter-Managing-CPP-Broker"> + <title> + Managing the AMQP Messaging Broker + </title> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Managing-CPP-Broker.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="QMan-Qpid-Management-bridge.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Qpid-Management-Framework.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Management-Design-notes.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="QMF-Python-Console-Tutorial.xml"/> +</chapter> +</part> diff --git a/qpid/doc/book/src/old/AMQP-Python-Messaging-Client.xml b/qpid/doc/book/src/old/AMQP-Python-Messaging-Client.xml new file mode 100644 index 0000000000..15baf214ec --- /dev/null +++ b/qpid/doc/book/src/old/AMQP-Python-Messaging-Client.xml @@ -0,0 +1,62 @@ +<?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. + +--> + +<chapter> + <title> + AMQP Python Messaging Client + </title> + <section role="h3" id="AMQPPythonMessagingClient-UserGuides"> + <title> + User Guides + </title> + <itemizedlist> + <listitem> + <para> + <ulink url="http://qpid.apache.org/docs/api/python/html/index.html">Python Client API Guide</ulink> + </para> + </listitem> + </itemizedlist> + <!--h3--> + </section> + + <section role="h3" id="AMQPPythonMessagingClient-Examples"> + <title> + Examples + </title> + <itemizedlist> + <listitem> + <para> + <ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/python/examples/">AMQP Python Client Examples </ulink> + </para> + </listitem> + <listitem> + <para> + <ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/python/examples/README">Running the AMQP Python Client Examples </ulink> + </para> + </listitem> + </itemizedlist> + <!--h3--> + </section> + + <xi:include href="PythonBrokerTest.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + +</chapter> diff --git a/qpid/doc/book/src/old/AMQP-Ruby-Messaging-Client.xml b/qpid/doc/book/src/old/AMQP-Ruby-Messaging-Client.xml new file mode 100644 index 0000000000..45318c0beb --- /dev/null +++ b/qpid/doc/book/src/old/AMQP-Ruby-Messaging-Client.xml @@ -0,0 +1,40 @@ +<?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. + +--> + +<chapter> + <title> + AMQP Ruby Messaging Client + </title> + <para> + The Ruby Messaging Client currently has little documentation and + few examples. + </para> + <section role="h3" id="AMQPRubyMessagingClient-Examples"> + <title> + Examples + </title> + <para> + <ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/ruby/examples">AMQP Ruby Messaging Client Examples</ulink> + </para> + <!--h3--> + </section> +</chapter> diff --git a/qpid/doc/book/src/old/AMQP.xml b/qpid/doc/book/src/old/AMQP.xml new file mode 100644 index 0000000000..1a609649bb --- /dev/null +++ b/qpid/doc/book/src/old/AMQP.xml @@ -0,0 +1,98 @@ +<?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. + +--> + +<chapter> + +<title>AMQP (Advanced Message Queueing Protocol</title> + + +<para>AMQP <ulink url="http://www.amqp.org/" >Advanced +Message Queuing Protocol</ulink> is an open standard designed to +support reliable, high-performance messaging over the Internet. +AMQP can be used for any distributed or business application, and +supports common messaging paradigms like point-to-point, fanout, +publish-subscribe, and request-response.</para> +<para>Apache Qpid implements AMQP, including transaction management, +queuing, clustering, federation, security, management and +multi-platform support.</para> +<para>Apache Qpid implements the latest AMQP specification, providing +transaction management, queuing, distribution, security, +management, clustering, federation and heterogeneous multi-platform +support and a lot more.</para> +<para>Apache Qpid is highly optimized, and <ulink url= +"amqp-compatibility.html">aims to be 100% AMQP Compliant</ulink>.</para> + +<section> +<title>Download the AMQP Specifications</title> + +<itemizedlist> +<title>AMQP version 0-10</title> +<listitem><para><ulink url="https://jira.amqp.org/confluence/download/attachments/720900/amqp.0-10.pdf?version=1" +>AMQP 0-10 Specification (PDF)</ulink></para></listitem> +<listitem><para><ulink url="https://jira.amqp.org/confluence/download/attachments/720900/amqp.0-10.xml?version=1" +>AMQP 0-10 Protocol Definition XML</ulink></para></listitem> +<listitem><para><ulink url="https://jira.amqp.org/confluence/download/attachments/720900/amqp.0-10.dfd?version=1" +>AMQP 0-10 Protocol Definition DTD</ulink></para></listitem> +</itemizedlist> + + +<itemizedlist> +<title>AMQP version 0-9-1</title> +<listitem><para><ulink url= +"https://jira.amqp.org/confluence/download/attachments/720900/amqp0-9-1.pdf?version=1" +>AMQP 0-9-1 Specification (PDF)</ulink></para></listitem> +<listitem><para><ulink url= +"https://jira.amqp.org/confluence/download/attachments/720900/amqp0-9-1.xml?version=1" +>AMQP 0-9-1 Protocol Documentation (PDF)</ulink></para></listitem> +<listitem><para><ulink url= +"https://jira.amqp.org/confluence/download/attachments/720900/amqp0-9-1.dtd?version=1" +>AMQP 0-9-1 Protocol Definitions (XML)</ulink></para></listitem> +</itemizedlist> + + +<itemizedlist> +<title>AMQP version 0-9</title> +<listitem><para><ulink url= +"https://jira.amqp.org/confluence/download/attachments/720900/amqp0-9.pdf?version=1" +>AMQP 0-9 Specification (PDF)</ulink></para></listitem> +<listitem><para><ulink url= +"https://jira.amqp.org/confluence/download/attachments/720900/amqp0-9.xml?version=1" +>AMQP 0-9 Protocol Documentation (PDF)</ulink></para></listitem> +<listitem><para><ulink url= +"https://jira.amqp.org/confluence/download/attachments/720900/amqp0-9.dtd?version=1" +>AMQP 0-9 Protocol Definitions (XML)</ulink></para></listitem> +</itemizedlist> + + +<itemizedlist> +<title>AMQP version 0-8</title> +<listitem><para><ulink url= +"https://jira.amqp.org/confluence/download/attachments/720900/amqp0-8.pdf?version=1" +>AMQP 0-8 Specification (PDF)</ulink></para></listitem> +<listitem><para><ulink url="https://jira.amqp.org/confluence/download/attachments/720900/amqp0-8.dtd?version=1" +>AMQP 0-8 Protocol Documentation (PDF)</ulink></para></listitem> +<listitem><para><ulink url="https://jira.amqp.org/confluence/download/attachments/720900/amqp0-8.xml?version=1" +>AMQP 0-8 Protocol Definitions (XML)</ulink></para></listitem> +</itemizedlist> +</section> + +</chapter> diff --git a/qpid/doc/book/src/old/Binding-URL-Format.xml b/qpid/doc/book/src/old/Binding-URL-Format.xml new file mode 100644 index 0000000000..3d938b740a --- /dev/null +++ b/qpid/doc/book/src/old/Binding-URL-Format.xml @@ -0,0 +1,174 @@ +<?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="BindingURLFormat"> + <title> + Binding URL Format + </title> + <programlisting> +<Exchange Class>://<Exchange Name>/[<Destination>]/[<Queue>][?<option>='<value>'[&<option>='<value>']] +</programlisting> + <para> + This URL format is used for two purposes in the code base. The + broker uses this in the XML configuration file to create and bind + queues at broker startup. It is also used by the client as a + destination. + </para><para> + This format was used because it allows an explicit description of + exchange and queue relationship. + </para><para> + The Exchange Class is not normally required for client connection + as clients only publish to a named exchange however if exchanges + are being dynamically instantiated it will be required. The class + is required for the server to instantiate an exchange. + </para><para> + There are a number of options that are currently defined: + </para><table><title>Binding URL Options</title><tgroup cols="3"> + <tbody> + <row> + <entry> + Option + </entry> + <entry> + type + </entry> + <entry> + Description + </entry> + </row> + <row> + <entry> + exclusive + </entry> + <entry> + boolean + </entry> + <entry> + Is this an exclusive connection + </entry> + </row> + <row> + <entry> + autodelete + </entry> + <entry> + boolean + </entry> + <entry> + Should this queue be deleted on client disconnection + </entry> + </row> + <row> + <entry> + durable + </entry> + <entry> + boolean + </entry> + <entry> + Create a durable queue + </entry> + </row> + <row> + <entry> + clientid + </entry> + <entry> + string + </entry> + <entry> + Use the following client id + </entry> + </row> + <row> + <entry> + subscription + </entry> + <entry> + boolean + </entry> + <entry> + Create a subscription to this destination + </entry> + </row> + <row> + <entry> + routingkey + </entry> + <entry> + string + </entry> + <entry> + Use this value as the routing key + </entry> + </row> + </tbody> + </tgroup></table><para> + Using these options in conjunction with the Binding URL format + should allow future expansion as new and custom exchange types + are created. + </para><para> + The URL format requires <emphasis>that at least one</emphasis> Queue or + routingkey option be present on the URL. + </para><para> + The routingkey would be used to encode a topic as shown in the + examples section below. + </para> + + <section role="h4" id="BindingURLFormat-Examples"> + <title> + Examples + </title> + +<example> +<title> Queues</title> + <para> + A queue can be created in QPID using the following URL format. + </para><para> + direct://amq.direct//<Queue Name> + </para><para> + For example: direct://amq.direct//simpleQueue + </para><para> + Queue names may consist of any mixture of digits, letters, and + underscores. + </para> +</example> +<example> +<title>Topics</title> + <para> + A topic can be created in QPID using the following URL format. + </para><para> + topic://amq.topic/<Topic Subscription>/ + </para><para> + The topic subscription may only contain the letters A-Z and a-z + and digits 0-9. + </para> + <programlisting> +direct://amq.direct/SimpleQueue +direct://amq.direct/UnusuallyBoundQueue?routingkey='/queue' +topic://amq.topic?routingkey='stocks.#' +topic://amq.topic?routingkey='stocks.nyse.ibm' +</programlisting> +</example> +<!--h4--></section> +</section> diff --git a/qpid/doc/book/src/old/Book-Info.xml b/qpid/doc/book/src/old/Book-Info.xml new file mode 100644 index 0000000000..2e02fbe8ea --- /dev/null +++ b/qpid/doc/book/src/old/Book-Info.xml @@ -0,0 +1,68 @@ +<?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 bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<bookinfo id="book-Messaging_Installation_Guide-Messaging_Installation_Guide"> + <title>Apache Qpid</title> + <subtitle>Open Source AMQP Messaging</subtitle> + <edition>1</edition> + <pubsnumber>0</pubsnumber> + <productname>Apache Qpid</productname> + <productnumber>6</productnumber> + <corpauthor> + <inlinemediaobject> + <imageobject> + <imagedata fileref="Common_Content/images/qpid-logo.png" format="PNG" /> + </imageobject> + </inlinemediaobject> + </corpauthor> + + <copyright> + <year>2010</year> + <holder>The Apache Software Foundation</holder> + </copyright> + + <legalnotice> + <para>Licensed 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</para> + + <para><filename>http://www.apache.org/licenses/LICENSE-2.0</filename></para> + + <para>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. + </para> + + + </legalnotice> + +</bookinfo> + + diff --git a/qpid/doc/book/src/old/Book.xml b/qpid/doc/book/src/old/Book.xml new file mode 100644 index 0000000000..ee69532152 --- /dev/null +++ b/qpid/doc/book/src/old/Book.xml @@ -0,0 +1,93 @@ +<?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 book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<book> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Book-Info.xml"/> + <part> + <title>Basics</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Introduction.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Getting-Started.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Download.xml"/> + </part> + +<!-- + The broker sections define their own <part/> elements, with <partintro/> text. +--> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Messaging-Broker-CPP.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Messaging-Broker-Java.xml"/> + + <part> + <title>AMQP Messaging Clients Clients</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Java-JMS-Messaging-Client.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-C++-Messaging-Client.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-.NET-Messaging-Client.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Python-Messaging-Client.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Ruby-Messaging-Client.xml"/> + + </part> + <part> + <title>Appendices</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Compatibility.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Qpid-Interoperability-Documentation.xml"/> +<!-- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="FAQ.xml"/> --> + </part> +</book> + +<!-- +Documentation +Getting Started + + * Download + * Getting Started + +AMQP (Advanced Message Queueing Protocol) + + * Toward a Commodity Enterprise Middleware + * AMQP (Advanced Message Queueing Protocol) + +Qpid AMQP Brokers + + * AMQP Messaging Broker (implemented in C++) + * AMQP Messaging Broker (implemented in Java) + +Qpid AMQP Clients + + * AMQP Java JMS Messaging Client + * AMQP C++ Messaging Client + * AMQP .NET Messaging Client + * AMQP Python Messaging Client + * AMQP Ruby Messaging Client + +Interoperability + + * AMQP Compatibility + * SASL Interoperability + +FAQ + + * Frequently Asked Questions +--> diff --git a/qpid/doc/book/src/old/Broker-CPP.xml b/qpid/doc/book/src/old/Broker-CPP.xml new file mode 100644 index 0000000000..99584be23d --- /dev/null +++ b/qpid/doc/book/src/old/Broker-CPP.xml @@ -0,0 +1,40 @@ +<!-- + - + - 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. + - + --> +h1. Running the AMQP Messaging Broker + +* [Running an AMQP 0-10 C++ broker | RASC] +* [Configuring Queue Options|Cheat Sheet for configuring Queue Options] +* [Configuring Exchange Options|Cheat Sheet for configuring Exchange Options] +* [Using Broker Federation] +* [How to use SSL | SSL] +* [Understanding Last Value Queues (LVQ) |LVQ] +* [Queue State Replication|queue state replication] +* [Getting Started] +* [Starting a cluster] +* [Understanding Access Control Lists|Qpid ACLs] + +h2. Management + +* [Managing| MgmtC++] the C++ Broker +* [QMan - Qpid Management bridge] +* [Qpid Management Framework] +* [Qpid Management Framework (QMF) Protocol|management design notes] +* [Manage anything with Qpid - QMF Python Console Tutorial|QMF Python Console Tutorial] diff --git a/qpid/doc/book/src/old/Broker-Java.xml b/qpid/doc/book/src/old/Broker-Java.xml new file mode 100644 index 0000000000..f8ce89b185 --- /dev/null +++ b/qpid/doc/book/src/old/Broker-Java.xml @@ -0,0 +1,45 @@ +<!-- + - + - 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. + - + --> +h3. General User Guides + +* [Feature Guide| Java Broker Feature Guide] +* [FAQ|Qpid Java FAQ] +* [Getting Started Guide] +* [Broker Environment Variables|Java Environment Variables] +* [Troubleshooting Guide|Qpid Troubleshooting Guide] + +h3. How Tos +* [Add New Users] +* [Configure ACLs] +* [Configure Java Qpid to use a SSL connection.] +* [Configure Log4j CompositeRolling Appender] +* [Configure the Broker via config.xml] +* [Configure the Virtual Hosts via virtualhosts.xml] +* [Debug using log4j] +* [How to Tune M3 Java Broker Performance] +* [Qpid Java Build How To] +* [Use Priority Queues] + +h3. Management Tools +* [Qpid JMX Management Console] +* [MessageStore Tool] +* [Qpid Java Broker Management CLI] +* [Management Design notes] diff --git a/qpid/doc/book/src/old/Clients.xml b/qpid/doc/book/src/old/Clients.xml new file mode 100644 index 0000000000..3dc2d38e86 --- /dev/null +++ b/qpid/doc/book/src/old/Clients.xml @@ -0,0 +1,25 @@ +<!-- + - + - 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. + - + --> +[AMQP Java JMS Messaging Client] +[AMQP C++ Messaging Client] +[AMQP .NET Messaging Client] +[AMQP Python Messaging Client] +[AMQP Ruby Messaging Client] diff --git a/qpid/doc/book/src/old/Connection-URL-Format.xml b/qpid/doc/book/src/old/Connection-URL-Format.xml new file mode 100644 index 0000000000..cb772487cd --- /dev/null +++ b/qpid/doc/book/src/old/Connection-URL-Format.xml @@ -0,0 +1,387 @@ +<?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="Connection-URL-Format"> + <title> + Connection URL Format + </title> + + <section role="h4" id="ConnectionURLFormat-Format"> + <title> + Format + </title> + <programlisting> +amqp://[<user>:<pass>@][<clientid>]<virtualhost>[?<option>='<value>'[&<option>='<value>']] + </programlisting> + <para> + The connection url defines the values that are common across + the cluster of brokers. The virtual host is second in the list + as the AMQP specification demands that it start with a '/' + otherwise it be more readable to be swapped with + clientid. There is currently only one required option and that + is the <emphasis>brokerlist</emphasis> option. In addition the + following options are recognised. </para> +<!--h4--></section> + + + <section role="h4" id="ConnectionURLFormat-WorkedExample"> + + <title> Worked Example </title> + + + + <para> You could use a URL which looks something like this: + </para> + +<programlisting> +amqp://guest:guest@client1/development?brokerlist='tcp://localhost:5672' +</programlisting> + + <para> Breaking this example down, here's what it all + means: </para> + + <itemizedlist> + <listitem><para> amqp = the protocol we're using + </para></listitem> + + <listitem><para> guest:guest@localhost = username:password@clientid + where the clientid is the name of your server (used under + the covers but don't worry about this for now). Always use + the guest:guest combination at the moment.</para></listitem> + + <listitem><para> development = the name of the virtualhost, where the + virtualhost is a path which acts as a namespace. You can + effectively use any value here so long as you're consistent + throughout. The virtualhost must start with a slash "/" and + continue with names separated by slashes. A name consists of + any combination of at least one of [A-Za-z0-9] plus zero or + more of [.-_+!=:]. </para></listitem> + + <listitem><para>brokerlist = this is the host address and port for + the broker you want to connect to. The connection factory + will assume tcp if you don't specify a transport + protocol. The port also defaults to 5672. Naturally you have + to put at least one broker in this list. </para></listitem> + + </itemizedlist> + + <para> This example is not using failover so only provides + one host for the broker. If you do wish to connect using + failover you can provide two (or more) brokers in the + format: </para> + + <para> + brokerlist='tcp://host1&tcp://host2:5673' </para> + + <para>The default failover setup will automatically retry + each broker once after a failed connection. If the + brokerlist contains more than one server then these servers + are tried in a round robin. Details on how to modifiy this + behaviour will follow soon ! </para> + + <!--h4--> + </section> + + <section role="h4" + id="ConnectionURLFormat-Options"> + + <title> Options</title> + + <table> + <title>Connection URL Options</title> + <tgroup cols="3"> + <tbody> + <row> + <entry> + Option + </entry> + <entry> + Default + </entry> + <entry> + Description + </entry> + </row> + <row> + <entry> + brokerlist + </entry> + <entry> + see below + </entry> + <entry> + The list of brokers to use for this connection + </entry> + </row> + <row> + <entry> + failover + </entry> + <entry> + see below + </entry> + <entry> + The type of failover method to use with the broker list. + </entry> + </row> + <row> + <entry> + maxprefetch + </entry> + <entry> + 5000 + </entry> + <entry> + The maximum number of messages to prefetch from the broker. + </entry> + </row> + </tbody> + </tgroup></table> +<!--h4--></section> + +<section role="h4" id="ConnectionURLFormat-Brokerlistoption"> + <title> Brokerlist option </title> + <programlisting> +brokerlist='<broker url>[;<broker url>]' +</programlisting> + <para> + The broker list defines the various brokers that can be used for + this connection. A minimum of one broker url is required + additional URLs are semi-colon(';') delimited. + </para> +<!--h4--></section> + +<section role="h4" id="ConnectionURLFormat-BrokerURLformat"> + +<title> Broker URL format </title> + + <programlisting> +<transport>://<host>[:<port>][?<option>='<value>'[&<option>='<value>']] +</programlisting> + <para> + There are currently quite a few default values that can be + assumed. This was done so that the current client examples would + not have to be re-written. The result is if there is no + transport, 'tcp' is assumed and the default AMQP port of 5672 is + used if no port is specified. + </para><table><title>Broker URL- Transport</title> + <tgroup cols="1"> + <tbody> + <row> + <entry> + Transport + </entry> + </row> + <row> + <entry> + tcp + </entry> + </row> + <row> + <entry> + vm + </entry> + </row> + </tbody> + </tgroup></table><para> + Currently only 'tcp' and 'vm' transports are supported. Each + broker can take have additional options that are specific to that + broker. The following are currently implemented options. To add + support for further transports the + ''client.transportTransportConnection'' class needs updating + along with the parsing to handle the transport. + </para> + <table><title>Broker URL - Connection Options</title> + <tgroup cols="3"> + <tbody> + <row> + <entry> + Option + </entry> + <entry> + Default + </entry> + <entry> + Description + </entry> + </row> + <row> + <entry> + retries + </entry> + <entry> + 1 + </entry> + <entry> + The number of times to retry connection to this Broker + </entry> + </row> + <row> + <entry> + ssl + </entry> + <entry> + false + </entry> + <entry> + Use ssl on the connection + </entry> + </row> + <row> + <entry> + connecttimeout + </entry> + <entry> + 30000 + </entry> + <entry> + How long in (milliseconds) to wait for the connection to + succeed + </entry> + </row> + <row> + <entry> + connectdelay + </entry> + <entry> + none + </entry> + <entry> + How long in (milliseconds) to wait before attempting to + reconnect + </entry> + </row> + </tbody> + </tgroup></table> +<!--h4--></section> + + <section role="h4" id="ConnectionURLFormat-Brokerlistfailoveroption"> + + <title> Brokerlist failover option </title> + <programlisting> +failover='<method>[?<options>]' +</programlisting> + <para> + This option controls how failover occurs when presented with a + list of brokers. There are only two methods currently implemented + but interface qpid.jms.failover.FailoverMethod can be + used for defining further methods. + </para><para> + Currently implemented failover methods. + </para><table><title>Broker List - Failover Options</title><tgroup cols="2"> + <tbody> + <row> + <entry> + Method + </entry> + <entry> + Description + </entry> + </row> + <row> + <entry> + singlebroker + </entry> + <entry> + This will only use the first broker in the list. + </entry> + </row> + <row> + <entry> + roundrobin + </entry> + <entry> + This method tries each broker in turn. + </entry> + </row> + <row> + <entry> + nofailover + </entry> + <entry> + [New in 0.5] This method disables all retry and failover + logic. + </entry> + </row> + </tbody> + </tgroup></table><para> + The current defaults are naturally to use the 'singlebroker' when + only one broker is present and the 'roundrobin' method with + multiple brokers. The '''method''' value in the URL may also be + any valid class on the classpath that implements the + FailoverMethod interface. + </para><para> + The 'nofailover' method is useful if you are using a 3rd party + tool such as Mule that has its own reconnection strategy that you + wish to use. + </para> + + <table> + <title>Broker List - Failover Options</title> + <tgroup cols="3"> + <tbody> + <row> + <entry> + Option + </entry> + <entry> + Default + </entry> + <entry> + Description + </entry> + </row> + <row> + <entry> + cyclecount + </entry> + <entry> + 1 + </entry> + <entry> + The number of times to loop through the list of available + brokers before failure. + </entry> + </row> + </tbody> + </tgroup></table><para> + <emphasis>Note:</emphasis> Default was changed from 0 to 1 in Release 0.5 + </para> +<!--h4--></section> + + <section role="h3" id="ConnectionURLFormat-SampleURLs"> + + <title> + Sample URLs + </title> + <programlisting> +amqp:///test?brokerlist='localhost' +amqp:///test?brokerlist='tcp://anotherhost:5684?retries='10'' +amqp://guest:guest@/test?brokerlist='vm://:1;vm://:2'&failover='roundrobin' +amqp://guest:guest@/test?brokerlist='vm://:1;vm://:2'&failover='roundrobin?cyclecount='20'' +amqp://guest:guest@client/test?brokerlist='tcp://localhost;tcp://redundant-server:5673?ssl='true''&failover='roundrobin' +amqp://guest:guest@/test?brokerlist='vm://:1'&failover='nofailover' +</programlisting> + +<!--h3--></section> +</section> diff --git a/qpid/doc/book/src/old/Download.xml b/qpid/doc/book/src/old/Download.xml new file mode 100644 index 0000000000..7bc08143ac --- /dev/null +++ b/qpid/doc/book/src/old/Download.xml @@ -0,0 +1,174 @@ +<?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. + +--> + +<chapter id="chapter-Download"> + +<title>Download Apache Qpid</title> + +<para/> + + +<section><title>Production Releases</title> + +<para>These releases are well tested and appropriate for production use. 0.5 is the latest release of Qpid.</para> + +<para>Qpid supports the latest version of AMQP 0-10, and some components also the AMQP 0-8 and 0-9, earlier versions. The Java Broker and Client provide protocol negotiation. Other versions can be found at <ulink url="http://www.apache.org/dist/qpid/">http://www.apache.org/dist/qpid/</ulink></para> + +<para>For details on cross component compatibility among releases, see: <ulink url="### FIX ME ###">AMQP Release Compatibility for Qpid|AMQP compatibility</ulink></para> + +<para>If you have any questions about these releases, please mail the user list (<ulink url="mailto:users@qpid.apache.org">users@qpid.apache.org</ulink>).</para> + +</section> + +<section><title>0.5 Release</title> + +<section><title>Multiple Component Packages</title> + +<table frame="all"> +<title/> +<tgroup cols='4' align='left' colsep='1' rowsep='1'> +<thead><row><entry> Component </entry><entry> Download </entry><entry> AMQP 0-10 </entry><entry> AMQP 0-8/0-9 </entry></row></thead> +<tbody> +<row><entry> Full release & keys </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/">http://www.apache.org/dist/qpid/0.5/</ulink> </entry><entry> Y </entry><entry> Y </entry></row> +<row><entry> C++ broker & client </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/qpid-cpp-0.5.tar.gz">http://www.apache.org/dist/qpid/0.5/qpid-cpp-0.5.tar.gz</ulink> </entry><entry> Y </entry><entry> </entry></row> +<row><entry> Java broker, client & tools </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/qpid-java-0.5.tar.gz">http://www.apache.org/dist/qpid/0.5/qpid-java-0.5.tar.gz</ulink> </entry><entry> client </entry><entry> Y </entry></row> +</tbody> +</tgroup> +</table> +</section> + +<section><title>Single Component Package</title> + + +<table> +<title>Broker</title> +<tgroup cols="4" align='left' colsep='1' rowsep='1'> +<thead><row><entry> Language </entry><entry> Download </entry><entry> AMQP 0-10 </entry><entry> AMQP 0-8/0-9 </entry></row></thead> +<tbody> +<row><entry> Java </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/qpid-java-broker-0.5.tar.gz">http://www.apache.org/dist/qpid/0.5/qpid-java-broker-0.5.tar.gz</ulink> </entry><entry> </entry><entry> Y </entry></row> +</tbody> +</tgroup> +</table> + + +<table> +<title>Client</title> +<tgroup cols="4" align='left' colsep='1' rowsep='1'> +<thead><row><entry> Language </entry><entry> Download </entry><entry> AMQP 0-10 </entry><entry> AMQP 0-8/0-9 </entry></row></thead> +<tbody> +<row><entry> C# (.NET, WCF, Excel) 0-10 client (C++ Broker Compatible) </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/qpid-dotnet-0-10-0.5.zip">http://www.apache.org/dist/qpid/0.5/qpid-dotnet-0-10-0.5.zip</ulink> </entry><entry> Y </entry><entry> </entry></row> +<row><entry> C# (.NET) 0-8 client (Java Broker Compatible) </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/qpid-dotnet-0-8-0.5.zip">http://www.apache.org/dist/qpid/0.5/qpid-dotnet-0-8-0.5.zip</ulink> </entry><entry> </entry><entry> Y </entry></row> +<row><entry> Java </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/qpid-java-client-0.5.tar.gz">http://www.apache.org/dist/qpid/0.5/qpid-java-client-0.5.tar.gz</ulink> </entry><entry> Y </entry><entry> Y </entry></row> +<row><entry> Python </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/qpid-python-0.5.tar.gz">http://www.apache.org/dist/qpid/0.5/qpid-python-0.5.tar.gz</ulink> </entry><entry> Y </entry><entry> Y </entry></row> +<row><entry> Ruby </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/qpid-ruby-0.5.tar.gz">http://www.apache.org/dist/qpid/0.5/qpid-ruby-0.5.tar.gz</ulink> </entry><entry> Y </entry><entry> Y </entry></row> +</tbody> +</tgroup> +</table> + + +<table> +<title>C++ broker management</title> +<tgroup cols="3" align='left' colsep='1' rowsep='1'> +<thead><row><entry> Component </entry><entry> Download </entry><entry> AMQP 0-10 </entry></row></thead> +<tbody> +<row><entry> cmd line (packaged with python) </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/qpid-python-0.5.tar.gz">http://www.apache.org/dist/qpid/0.5/qpid-python-0.5.tar.gz</ulink> </entry><entry> Y </entry></row> +<row><entry> QMan JMX bridge, WS-DM </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/qpid-management-client-0.5.tar.gz">http://www.apache.org/dist/qpid/0.5/qpid-management-client-0.5.tar.gz</ulink> </entry><entry> Y </entry></row> +</tbody> +</tgroup> +</table> + + +<table> +<title>Java broker management</title> +<tgroup cols="2" align='left' colsep='1' rowsep='1'> +<thead><row><entry> Component </entry><entry> Download </entry></row></thead> +<tbody> +<row><entry> Eclipse RCP client </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/qpid-management-eclipse-plugin-0.5-linux-gtk-x86.tar.gz">Linux x86</ulink> +<ulink url="http://www.apache.org/dist/qpid/0.5/qpid-management-eclipse-plugin-0.5-linux-gtk-x86_64.tar.gz">Linux x86_64</ulink> +<ulink url="http://www.apache.org/dist/qpid/0.5/qpid-management-eclipse-plugin-0.5-macosx.zip">Mac OS X</ulink> +<ulink url="http://www.apache.org/dist/qpid/0.5/qpid-management-eclipse-plugin-0.5-win32-win32-x86.zip">Windows x86</ulink> +</entry></row> +<row><entry> Command line interface </entry><entry> <ulink url="http://www.apache.org/dist/qpid/0.5/qpid-management-tools-qpid-cli-0.5.tar.gz">http://www.apache.org/dist/qpid/0.5/qpid-management-tools-qpid-cli-0.5.tar.gz</ulink> </entry></row> +</tbody> +</tgroup> +</table> +</section> +</section> + + +<section id="qpid_3rd-Party-Libraries"><title>QpidComponents.org</title> + +<para><ulink url="http://QpidComponents.org">http://QpidComponents.org</ulink> provides further components for Apache Qpid, including both persistence and management tools. These components are open source, but are not developed as part of the Apache Qpid project due to licensing or other restrictions.</para> + +</section> + + +<section><title>Contributed C++ Packages</title> + +<section><title>Pre-built Linux Packages</title> + +<section><title>Fedora 8, 9, 10</title> + +<para>On Fedora, Qpid can be installed using yum. Because Java RPMs are not yet available in Fedora repos, the Java client is not in these distributions.</para> + +<para>To install the server:</para> +<programlisting> +# yum install qpidd +</programlisting> +<para>To install C++ and Python clients:</para> +<programlisting> +# yum install qpidc-devel +</programlisting> +<programlisting> +# yum install amqp python-qpid +</programlisting> +<para>To install documentation:</para> +<programlisting> +# yum install rhm-docs +</programlisting> +<para>To install persistence using an external store module:</para> +<programlisting> +# yum install rhm +</programlisting> +</section> +</section> + + +<section><title>Windows Installer</title> + +<para>The Windows installer is available from <ulink url="http://www.apache.org/dist/qpid/0.5-windows/qpidc-0.5.msi">http://www.apache.org/dist/qpid/0.5-windows/qpidc-0.5.msi</ulink>. It is built from the 0.5 C++ broker and client source distribution listed above. It has been tested for Windows XP SP2 and above.</para> + +<para>The Windows executables require the Visual C++ 2008 SP1 run-time components. If the Visual C++ 2008 SP1 runtime is not available, the Qpid broker will not execute. If you intend to run the broker and Visual C++ 2008 is not installed, you must install the Visual C++ 2008 SP1 Redistributable. Please see <ulink url="http://www.microsoft.com/downloads/details.aspx?familyid=A5C84275-3B97-4AB7-A40D-3802B2AF5FC2&displaylang=en">http://www.microsoft.com/downloads/details.aspx?familyid=A5C84275-3B97-4AB7-A40D-3802B2AF5FC2&displaylang=en</ulink> for download and installation instructions.</para> + +<para>If you intend to develop Qpid client applications using this kit, you should install <ulink url="http://www.boostpro.com/download/boost_1_35_0_setup.exe">Boost version 1.35</ulink> (please be sure to select VC9 support when installing) in addition to Visual Studio 2008 SP1.</para> + +</section> +</section> + +<section><title>Source Code Repository</title> + +<para>The latest version of the code is always available in the <ulink url="Source Repository">Source Repository</ulink>. +</para> +</section> + + +</chapter> diff --git a/qpid/doc/book/src/old/Excel-AddIn.xml b/qpid/doc/book/src/old/Excel-AddIn.xml new file mode 100644 index 0000000000..e38f620bd8 --- /dev/null +++ b/qpid/doc/book/src/old/Excel-AddIn.xml @@ -0,0 +1,169 @@ +<?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> + <title> + Excel AddIn + </title> + <section role="h1" id="ExcelAddIn-ExcelAddIn"> + <title> + Excel AddIn + </title> + <para> + Qpid .net comes with Excel AddIns that are located in: + </para> + <para> + <filename><project-root>\qpid\dotnet\client-010\addins</filename> + </para> + + <para> + There are currently three projects: + </para> + <variablelist> + <varlistentry> + <term>ExcelAddIn</term> + <listitem> + <para>An RTD excel Addin</para> + </listitem> + </varlistentry> + <varlistentry> + <term>ExcelAddInProducer + </term> + <listitem> + <para>A sample client to demonstrate the RTD AddIn</para> + </listitem> + </varlistentry> + <varlistentry> + <term>ExcelAddInMessageProcessor + </term> + <listitem> + <para>A sample message processor for the RTD AddIn</para> + </listitem> + </varlistentry> + </variablelist> + + <section role="h2" id="ExcelAddIn-QpidRDTAddIn"> + <title> + Qpid RDT AddIn + </title> + <section role="h3" id="ExcelAddIn-DeployingtheRTDAddIn"> + <title> + Deploying the RTD + AddIn + </title> + <para> + Excel provides a function called RTD (real-time data) that lets + you specify a COM server via its ProgId here "Qpid" so that you + can push qpid messages into Excel. + </para> + <para> + The provided RTD AddIn consumes messages from one queue and + process them through a provided message processor. + </para> + <para> + For using the Qpid RTD follows those steps: + </para> + + <procedure> + <step><para> + Copy the configuration Excel.exe.config into <filename>Drive\Program Files\Microsoft Office\Office12</filename>. + </para></step> + <step><para> + Edit <filename>Excel.exe.xml</filename> and set the targeted Qpid broker host, port + number, username and password. + </para></step> + <step> <para> + Select the cell or cell range to contain the RTD information + </para></step> + <step><para> + Enter the following formula <command>=rtd("Qpid",,"myQueue")</command>. Where + MyQueue is the queue from which you wish to receive messages from. + </para></step> + </procedure> + <para> + Note: The Qpid RTD is a COM-AddIn that must be registered with + Excel. This is done automatically when compiling the Addin with + visual studio. + </para> + <!--h3--> + </section> + + + <section role="h3" id="ExcelAddIn-Definingamessageprocessor"> + <title> + Defining a message processor + </title> + + <para> + The default behavior of the RDT AddIn is to display the message + payload. This could be altered by specifying your own message + processor. + A Message processor is a class that implements the API + <command>ExcelAddIn.MessageProcessor</command>. For example, the provided processor + in <filename>client-010\addins\ExcelAddInMessageProcessor</filename> displays the + message body and the the header price when specified. + </para> + <para> + To use you own message processor follows those steps: + </para> + <procedure> + <step><para>Write your own message processor that extends ExcelAddIn.MessageProcessor</para></step> + <step><para>Edit Excel.exe.config and uncomment the entries:</para> + <programlisting> +<add key="ProcessorAssembly" +value="<path>\qpid\dotnet\client-010\addins\ExcelAddInMessageProcessor\bin\Debug\ExcelAddInMessageProcessor.dll"/> + </programlisting> + <programlisting> + <add key="ProcessorClass" + value="ExcelAddInMessageProcessor.Processor"/> + </programlisting> + <itemizedlist> + <listitem> + <para>ProcessorAssembly is the path on the Assembly that contains + your processor class + </para> + </listitem> + <listitem> + <para>ProcessorClass is your processor class name + </para> + </listitem> + </itemizedlist> + </step> + <step><para>run excel and define a rtd function</para></step> + </procedure> + <para> + Note: the provided ExcelAddInProducer can be used for + testing the provided message processor. As messages are + sent to queue1 the following rtd function should be used + <command>=rtd("Qpid",,"queue1")</command>. + </para> + + <!--h3--> + </section> + + <!--h2--> + </section> + + <!--h1--> + </section> + +</section> diff --git a/qpid/doc/book/src/old/FAQ.xml b/qpid/doc/book/src/old/FAQ.xml new file mode 100644 index 0000000000..5647f18f69 --- /dev/null +++ b/qpid/doc/book/src/old/FAQ.xml @@ -0,0 +1,524 @@ +<!-- + - + - 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. + - + --> +{toc} + + +*This page is a collection of FAQ and How to-s for Qpid. If you have a question, post it to the users list and we will place the answer here to build out our FAQ/ How to.* + +h1. FAQ + +h2. About AMQP + +h3. What is AMQP? + +AMQP is a wire-level protocol and model for high performance enterprise messaging. + +[From the AMQP website:|http://www.amqp.org] + + AMQP is an Open Standard for Messaging Middleware. + + By complying to the AMQP standard, middleware products written for different platforms and in different languages can send messages to one another. AMQP addresses the problem of transporting value-bearing messages across and between organizations in a timely manner. + + AMQP enables complete interoperability for messaging middleware; both the networking protocol and the semantics of broker services are defined in AMQP. + +h3. Where did AMQP come from + +AMQP was born out from Frustration by John O'Hara at JPMC. He started a project internally to create commodity messaging that was easy to use. Carl Trieloff from Red Hat had started a project to build messaging for both users and for use in infrastructure, while looking around spoke to John about his work. Out of these discussion was born the AMQP working Group with 6 initial members, under an agreement that it will be eternally be licensed for everyone to use. + +Since then the Working Group has had many join, and has been making solid progress working on revisions of the specification. [For more details see.|http://jira.amqp.org/confluence/display/AMQP/About+AMQP] + +h3. Why use AMQP? + +AMQP is has been designed to be able to handle the hardest workloads, scale to the largest systems, but also deal with reduction of change and maintenance costs by doing a refresh on many aged practices. The specification is also not language specific allowing the freedom from language and platform lock in, without compromise on user experience, security, scalability and consistently excellent performance. + +[Text mostly taken from|http://jira.amqp.org/confluence/display/AMQP/About+AMQP] + +h2. Qpid & AMQP + + +h3. Is Qpid AMQP Compliant? + +Yes, Apache Qpid implements the latest AMQP specifications, providing transaction management, queuing, distribution, security, management, clustering, federation and heterogeneous multi-platform support and a lot more. And Apache Qpid is extremely fast. [Apache Qpid aims to be 100% AMQP Compliant|AMQP compatibility]. + +h3. What Client support does Qpid have? + +Apache Qpid provides AMQP Client APIs for the following languages: +* C+\+ +* C# .NET, using WCF +* Ruby +* Python +* Java JMS, fully conformant with Java CTS1.1 + +If you need another client, join the lists and ask or feel free to contribute one. + +h3. What messaging topologies are supported by AMQP and Qpid? + +AMQP provides the ability to do Point-to-Point, Peer-to-Peer, Pub-Sub, and Eventing. This allows many patterns to be craeted: + ++*Point-to-point*+ + +This is one of the simplest use-cases. AMQP allows for this in a few ways. + a.) A client can create a named queue allowing the producer to publish the message to the direct exchange with the key mapping the queue name. This will route the message to that queue. + b.) The above pattern can be extended by specifying a reply-to address in the published messages allowing for the consumer to reply the producer without knowing who it was send from prior to receiving the message. + ++*One-to-many*+ + +There are a few patterns that can be used. + + a.) AMQP provides a 'fanout' exchange which will send a message to all the queues that have been bound to it. Different domains or topics are created with the 'fanout' exchange by declaring different named fan-out exchanges. + + b.) A 'topic' or 'headers' exchange can also be used. in this case the pattern match is used to send the message to all the bound queues. It can be thought of as a filter allowing you to create just about any One-to-many routing patterns. + ++*Pub-Sub*+ + +Topic can be created with the 'topic' or other 'direct' exchange to allow consumer to bind to into the steams of data they care about. This pattern combined with the use of reply-to and Alternate-routing is the staple of what most people use messaging for today. + ++*FAST Reliable Messaging*+ + +AMQP 0-10 allows for fully reliable transfers between any two peers. This means that you can publish or subscribe to the broker fully reliable without requiring the need for transactions. This can all be done in async mode with the C++ broker allowing for high throughput while running entirely reliable. + ++*Transactional*+ + +AMQP supports two types of transactions in AMQP 0-10, TX and DTX. This allows for local (1PC), and 2PC transaction and the ability to coordinate with a TM (Transaction Manager). The Java broker supports TX, the C++ broker support TX, DTX, XA, JTA for fully ACID transactions. This allows you to commit a single unit of work with may contain enqueues & dequeues either locally on the broker, or in coordination with other transactional resource like RDBMS. + ++*Transient message delivery*+ + +By default messages are transient. Transient message can be sent to queues that are durable. They will not be safe stored or recovered, and will perform as any other transient message - fast! + ++*Durable message delivery*+ + +There is a header on each message where the message properties are specified, one of these is durability. Messages that are marked as durable and published to a durable queue will be safe stored. Durable messages will survive restart of the broker or cluster. + ++*Federation (Hub-spoke, Trees, graphs)*+ + +As AMQP 0-10 is symmetric for peer-to-peer communication all the building block are in place for creating networks of brokers. The C++ broker allows you to link the brokers together using 'qpid-route' and then create routes between the brokers either statically or with dynamic routes. + +This allows for a message to be published to one broker and consumed from another broker in the federated broker network. This feature is great to create data-center, or project isolation, but allow cross communication. It also allows networks to be created to scaled. [For more details see|Using Broker Federation] + ++*And many others, including custom pattern*+ + ++*Message Reply, Rings, Initial Value Caches, Last Value Messaging*+ + +All the above cases can be constructed using the AMQP and features of Qpid. For example reply can be constructed using message browsing and setting TTL on the messages. The C++ broker also support ring queues, last value queues, initial value caches on exchanges. With a bit of throught many additional patterns can be constructed. + +*+Store-and-forward+* + +Store-and-forward can be achieved by publishing to well know durable queues, that are not marked with auto delete. Consumers will be able to 'came back' to consume then at any time, even after restarts. + +h3. What AMQP and other exchanges does Qpid support? + +Both brokers support: + * Direct Exchange + * Topic Exchange + * Fanout Exchange + * Headers Exchange + +In additional the C++ broker support + * XML Exchange - Query routing + * Custom exchange via plug-in. + +Custom exchanges allow you to provide your own custom routing logic and algorithms via a plug-in. If you build an interesting exchange, please feel free to contribute it back to the Qpid project. + +h2. Security + +h3. What encryption does Qpid support? + + * Qpid support SSL/TSL as per the AMQP specification. + * In addition the C++ broker supports Kerberos encryption of messages independent on which transport is used. Support in not yet included in all clients for this but is in process. + +h3. What authentication does Qpid support? + +SASL Authentication is supported. All Clients support PLAIN, and Kerberos support if being added to all the clients. The C++ broker support Kerberbos authentication. + +h3. What authorization does Qpid support? + +Full ACL is supported in the brokers. [For details on configuring ACL see|Qpid ACLs]. + +ACL supports realms and allows for granular permission to be set on all the broker actions including management on an user or group basis. + +h3. How to setup Kerberos with the Java client + +You could force the java client to use kerberos auth by specifying it in the connection URL as follows. +{code} +amqp://guest:guest@clientid/testpath?brokerlist='tcp://localhost:5672?'&sasl_mechs='GSSAPI' +{code} + +You would then need to pass in the following jvm arguments +{code} +-Djavax.security.auth.useSubjectCrehttp://code.google.com/p/confluence-el/dsOnly=false +# (This will force the SASL GASSPI client to obtain the kerberos credentials explicitly instead of obtaining from the "subject" that owns the currents thread) +-Djava.security.auth.login.config=myjas.conf (this specifies the jass config file) +-Dsun.security.krb5.debug=true (to enable detailed debug info for troubleshooting) +{code} + +Before running the java client you would need to do kinit and grab a kerberos ticket. Alternative you could set useTicketCache=false and when the client loads, it will prompt you for the user/pass and will obtain the ticket +(You would also need to setup your kerberos environment properly -refer to doc links below). + +Sample JASS Config file +{code} +com.sun.security.jgss.initiate { + com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true; +}; +{code} + + +h2. Semantics of Exclusive + +h3. I want to be able to have an exclusive consumer, but when it dies I want another to be able to pick up the queue and then block others, can this be done? + +Yes, Declare you queue exclusive. this will prevent anyone else from connecting to the queue. If the consumer dies the next consumer can attach to the queue by redeclaring it using the exclusive flag. Make sure not to set auto delete. Any consumer trying to declare, while a consumer is attached to the queue will receive an exception. + +h3. When will the queue become free for a re-declare + +Once the session that held the consumer is closed. + + +h2. Performance + +h3. Does Qpid Perform (Latency/Throughput)? + +Yes, The Qpid C++ broker has been achieved great benchmark results in published papers by those that redistribute it. [Red Hat MRG|http://www.redhat.com/mrg] product build on Qpid has shown 760,000msg/sec ingress on an 8 way box or 6,000,000msg/sec OPRA messages. + +Latencies have been recored as low as 180-250us (.18ms-.3ms) for TCP round trip and 60-80us for RDMA round trip using the C++ broker. + +h3. How do I measure throughput? + +There is a great resource supplied in the C++ broker test directory called perftest. If allows you to create load on a broker for all the exchanges, multiple queues, multiple connection, coordinate multiple publishing and consuming processes, beachmark transactions and much much more such as acquire mode, txn size, message size. + +For all the options +{code} +./perftest --help +{code} + +h3. How do I measure latency? + +There is a great resource supplied in the C++ broker test directory called latencytest. It is a loopback test that produces messages by count or at a rate, time stamps them and then consumes them back and record the latency. It supports many of the Qpid options, including the ability to vary things like frame-size. + +Latencies to expect round trip: + * 1G TCP ~ .3ms -.5ms + * 10G TCP - .18ms - .22ms + * RDMA transport - 40us - 80us + +Don't forget to set tune the machine and set --tcp-nodelay on both the C++ broker & client. + +For all the options +{code} +./latencytest --help +{code} + +h3. How do I measure performance with Java clients? + +In Java we provide a utility called QpidBench. It allows you to test the performance of the native AMQP API in Java for 0-10 and the JMS API against both brokers. + +h3. Can I run my Java client with JAVA-RT? + +Yes, recently a thread abstraction layer has been added to the Java client allowing it to be used with both the SUN and IBM RT JVMs. This increases the determinism of latency when using the Java client. + +h3. Does Qpid support flow control? + +yes, AMQP 0-10 allows for flow control on the consumer and producer. + +h3. How do I configure producer side flow control + +from qpidd --help + +set the following in the config file on via cmd line options. +{code} + --max-session-rate MESSAGES/S (0) Sets the maximum message rate per session (0=unlimited) +{code} + +h2. Management + +h3. What Management does Qpid support + +The Java broker supports JMX and provides an Eclipse plug-in and command line tool to manage via JMX. The C++ broker has far more extensive management support via QMF which will be added to the Java broker in a future release. + +The C++ Broker supports a layered management protocol over AMQP called QMF. This allows for the management of resource either in the broker or connected to the broker via the AMQP fabric. This management includes statistics, control, eventing, and reporting/updating properties. + +h3. How do I manage a broker? + +A set of tools are provided to manage the C++ broker, they include + * qpid-tool - telnet type tool to access data, view schema, issue command an and QMF resource + * qpid-config - tool to configure queues, exchanges, etc. all the details on the AMQP model + * qpid-route - tool to configure broker federation + * qpid-events - utility that will print to cmd line or syslog event from a broker like, userconnected, user crested/deleted a queue. + * qpid-stats - utility that will print out queue statistics to the cmd line or syslog like rate and message depth. + +Then you can also access all thsi information via JMX or WS-DM (work in progress) using QMan. + +h3. What logging tracing and events does Qpid support? + +Qpid support the ability to output events from any the broker or any managed object via QMF, or to do a variety of logging from the broker & clients. for tracing options run qpidd --help. + +Multiple levels of of logging are supported in the C++ broker from debug, warning, error, info, etc -- all of which can be filtered. + +h3. Can I get to all the management data from a client? + +yes, All the management data is just AMQP messages on specially named queues. An API is provided for working with the management data called QMFC + +h3. What is QMF + +QMF is the layered Management protocol used to manage the C++ broker. For details on teh protocol see the Development pages. + +QMF allows you to manage any resource and provides the following infrsstructure: + * Properties + * Statistics + * Commands + * Events + * Schema for resources and versioning + * tools for creating agents and consuming QMF data. + +h3. What are QMF Agents, and what do they do for me? + +An Agent is any client (producer or consumer) that generates a QMF schema and registers itself to be management by QMF. + +A great use case of this is a consumer that is processing order from a queue can reference itself to that queue and for example provide a schema for the number or successful orders process and a method to suspend processing. Now it becomes possible to use qpid-tool to connect to the broker, see which order processors are on queue via the reference and the via the stats of the order processor client. It is also possible to issue a command to the client via qpid-tool to suspend processing. ACL in the broker can be applied to all these actions if desired. + +h3. What is QMFC and what does it do for mr? + +QMFC is the API used to consume QMF data, event and issue commands to QMF agents from an AMQP client. + +h3. What is QMan + +Qman is a tool that dynamically reads the QMF Schema information and creates JMX objects that consumed by any JMX console or application server to manage Qpid. QMan is also adding support for WS-DM management of QMF resources. + + +h2. Clustering, Federation and Disaster Recovery + +h3. Does Qpid provide Fault Tolerance for the cluster? + +The C++ broker has plug-ins for Active-Active clustering which keep all the nodes of the cluster in sync. This means that any action that is performed on one of the brokers on the cluster is performed on all of them at the same time. New nodes can be added to the cluster at any time, and removed at any time with no consequences, exept for the extra multi-cast load created for the sync on joining. + +h3. What does the cluster guarantee? + +Everything! All configuration, all messages and all actions are replicated in a cluster. This means that two consumers can be connected to different nodes in the cluster and they will behave EXACTLY the same as if they where on a single broker. + +h3. Do clients get notified members joining or leaving the cluster? + +yes, All clients are updated with the addresses of node add/removed as supported by the AMQP 0-10 specification. This means that the client can dynamically track the nodes in the cluster and reconnect as required. + +h3. Can I specify more than one host to connect initially to the cluster to avoid single point of failure? + +yes, the AMQP address is multi-honed and more than one IP address can be specified at the initial connection. The client will then iterate through the host until it makes a successful connection. This feature can also be used in none clustered brokers. + +h3. How does Clustering work? + +When C++ brokers are configured into a cluster, the nodes communicate with each other over a mulitcast protocol called AIS, an open Telco multicast protocol that provides all the quorum and group services. + +Every action that is performed on any node of the cluster is then sequenced via totem and then performed on each node of the cluster in sync. As the cluster backbone is multicast, a separate network can be used for cluster communication and there is little impact adding additional nodes to the cluster with-in reason. + +h3. What is Federation? + +Federation provides the ability to create networks of brokers that communicate with each other in all types of typologies. This allows a producer to publish messages to one broker and someone to consume the messages from another broke somewhere on the broker federated network. + +[For more details see|Using Broker Federation] + +h3. Disater recover features are in process, Q&A will be added once they are complete. + +h2. Heartbeats + +Heartbeat can be configured to allow clients to detect when a broker has failed and connect to another broker or cluster member.Heartbeats are sent by the broker at a client specified, per-connection frequency. If the client does not receive a heartbeat or any other traffic for two heartbeat intervals, the connection will be made to fail. + +h3. What would happen when there is a no heartbeat within a predefined interval? + +If there is no traffic for two heartbeat intervals, the client will fail the connection. The application will see the exact same response as when the connection is killed. + +h3. What happens if the broker is unable to send heartbeat? + +As above, if there is no other traffic the client will eventually kill the connection. + +h3. Does the client retry? + +You can control the heartbeat interval on the client through the heartbeat member of ConnectionSettings (it is measured in seconds). Some of the options on policies do vary for different clients. + +h3. Failover taking too long... + +First check to make sure a heartbeat has been specified in the connection properties for the connection. + +Then make sure that the interfaces on each broker are reachable from the host you run my clients, else it will take a long time for the socket to timeout until it gets to one that can be reached. + +Make sure the list of URL's on the cient are the ones you want tht client to try + +Make sure that the broker is only exporting URL's that the client can connect to, use the --cluster-url option on the broker to specify this. + +h2. Threading + +h3. Could someone provide a brief description of the worker thread duties in the current Qpid release? + +The broker uses IO threads for all the work it does. This means that when work is signalled via an event (socket, RDMA, timer) an IO thread is scheduled and it runs until it completes the work and then returns back to the IO thread pool. This allows the CPUs to be utilized efficiently. The general rule is that we allocate 1 thread per core +1. So on a 8 way machine you see worker-threads default to 9. On a 4 way it will be 5. Sometimes it if work changing the default allocation if: + +a.) you run on high core count machine >8 to a lower number +b.) if you taskset, then set to the cores allocated +1 + +h3. Why was the number X chosen as the default number of worker threads? + +Qpidd defaults to cores + 1 + +h3. What happens in parallel? + +Concurrency in the broker is at the session level. So yes. If you want more concurrency, create another session on the same connection. + +h3. How are worker threads allocated to individual client sessions if there are more clients than threads in the pool? + +They are not allocated to a specific client + +h2. Persistence + +h3. Does Qpid support persistence (durability)? + +Yes, there are third-party (non-Apache) modules for both C++ and Java. Historically, BDB has been used to provide persistence for both C++ and Java. However, this has created a licensing conflict with Apache, and thus the store modules are maintained off-site. + +The Java broker includes a fully Apache licensed persistent store that uses Derby DB. + +The terms _durable_ and _persistent_ are used interchangeably in this FAQ. + +h3. Where do I get the 3rd party persistence store modules? + +The 3rd party persistence store modules may be obtained through anonymous subversion at the following locations: + +C++: http://anonsvn.jboss.org/repos/rhmessaging/store/trunk/cpp +Java: http://anonsvn.jboss.org/repos/rhmessaging/store/trunk/java/bdbstore + +For further details see [3rd Party Libraries] + +h3. How do I build the persistence store module from subversion checkouts? + ++*C\+\+*+ +The README file contains detailed instructions, but here is a summary: + # Make sure that both the db4-devel and libaio-devel packages are installed prior to building. + # Make sure that qpid is built and you know the location of the qpid directory (ie the top-level directory containing the python and cpp sub-directories). + # In the store directory, run: +{code} +./bootstrap +./configure --with-qpid-checkout=/abs/path/to/qpid/dir +make +{code} +# When built, the store library *msgstore.so* will be located in the *lib/.libs* directory. + ++*Java*+ +TODO + +h3. How do I use the persistence store module? + ++*C\+\+*+ + # Start the broker making sure that the store module is loaded, ie +{code} +qpidd --load-module=/path/to/msgstore.so --data-dir=/path/to/store-files ... +{code} + # Make sure that queues that will handle persistent messages are set durable. +{note:title=Note: Existing non-persistent queues cannot be made persistent} +If a queue has been declared without persistence, doing so again with persistence enabled while the old queue still exists in the broker will be ignored. Make sure that when a queue is declared persistent, there is no non-persistent queue of the same name in existence. +{note} + # For each message sent to a durable queue, make sure that it is set durable. + ++*Java*+ +TODO + +h3. How do I configure the persistence store? + ++*C\+\+*+ + +The broker loads help information from each module. To see the help options for the store, load the store module and specify help: +{code} +qpidd --load-module /abs/path/to/store/lib/.libs/msgstore.so --help +{code} + +Note that a set of journal files will be created for each queue declared and marked persistent. Each persistent queue has its own private journal. These are stored in the data directory by default (ie it uses the broker's *\-\-data\-dir* setting) or can be overridden with the *\-\-store\-dir* option. Note that if the broker is started with the *\-\-no\-data\-dir* option, then no store default exists, and the *\-\-store\-dir* option MUST be specified. + +The store file details - or "store geometry" - can be set with command-line options. These include the size and number of files that make up the journal for each queue. The *\-\-num\-jfiles* options sets the number of files to use (between 4 and 64) and the *\-\-jfile\-size\-pgs* sets the size of the file in 64kiB blocks. + +The size of the pages in the write page cache is set with the *\-\-wcache\-page-size* option, and sets a size in KiB. (Legal values are powers of 2, ie: 1, 2, 4, 8, 16, 32, 64, 128). Typically small page sizes give improved latency (especially for small messages), but are bad for message throughput, while large page sizes improve throughput but may cause some messages to have higher latencies. + ++*Java*+ ++Derby Store+ +For details of configuring the Derby Store see [here|Derby Store Plugin] + ++3rd Party Stores+ + +For details of using the 3rd party persistent modules see [here|3rd Party Libraries] + + +h3. \[C++ store\] What is a RHM_IORES_ENQCAPTHRESH error? + +The journal ran out of space (ENQueue CAPacity THRESHold). The journal is a circular file buffer of fixed capacity set by the journal file size and number of files. When an attempt to write a record causes the journal to exceed an approx. 80% threshold, then the enqueue is rejected with this error code. Dequeues (a written record of a consumed message) may continue, however, as these free up space in the journal. Once space has been freed up, enqueues may continue as normal. + +This error may be caused by: +# The journal is too small for the size and number of messages being stored. The journal must be made large enough to hold all of the messages you expect to be on the queue at any one moment (a worst-case scenario). Make the journal capacity larger through the use of the *\-\-num\-jfiles* and *\-\-jfile\-size\-pgs* parameters. +{info:title=Rule of thumb for sizing the journal} +Make the journal twice the size of all the messages you need to store at any one moment in time. +{info} +# Messages are not being dequeued (consumed) as expected. Since the store is a circular file buffer, if one un-dequeued (not consumed) message remains, it can eventually "block" the storage of new messages as the buffer gets overwritten. + +h3. \[C++ store\] What is the TPL? What are the \-\-tpl\-\* options for? +The TPL stands for *Transaction Prepared List*. The store creates a single instance of a store for storing transaction boundaries called the Transaction Prepared List. Because the TPL is frequently flushed and has very different usage patterns to a normal store, it has been provided with its own set of configuration parameters: +* *\-\-tpl\-num\-jfiles:* The number of files in the TPL journal +* *\-\-tpl\-jfile\-size-pgs:* The file size in 64kiB blocks of the TPL journal. +* *\-\-tpl\-wcache\-page-size:* The size of the write cache in the TPL in KiB, which is typically set a lot smaller than the average message store. + +h1. How To + +h2. C++ + +h3. How to use RDMA with Qpid + +The RDMA plugin uses native OFED1.3 and puts AMQP directly onto the DMA. When using the RDMA plug-in for Qpid note the following +* IP over IB or Fibre needs to be setup for the initial negociation +* You need to make sure you have enough memory to pin for DMA use ulimit \-l something large +* you might need to edit /etc/security/limits.conf first then log in again + +Once you have it up and running, use latencytest to make sure it is working. You should see latencies between 50 and 80us round trip. + +h3. Message TTL, auto expire + +I need to be able to set time for a message that I send to be removed from the queue if it is not read by my subscriber. For example: I enqueue a message and I want it to be automatically dequeued after a certain amount of time has passed.Is there a feature like this in qpid? + +yes, the TTL can be set in the message headers and the messages get dequeued if TTL expires + +E.g. from c++: +{code} +Message m("Hello World!"); + m.getDeliveryProperties().setTtl(500); +{code} +Sets a 500 millisecond timeout. + +h3. How to install the qpid-tools for c++ broker? + +I see +{code} +[commands]$ ./qpid-queue-stats + Traceback (most recent call last): + File "./qpid-queue-stats", line 29, in + from qmf.console import Session, Console + ImportError: No module named qmf.console +{code} + +This problem occurs because the PYTHONPATH environment variable does not include the location of the qpid python files. If you are running from the SVN checkout, add <path>/qpid/python to PYTHONPATH (where <path> is the location of your SVN tree). If you are installing from source, make sure you configure with the same prefix where Python is installed. This is most likely: + +{code} +# configure --prefix=/usr +# make +# make install +{code} +If you are running from vendor RPMs, this should work automatically. + + +h2. Java +{children:page=Qpid Java How To} diff --git a/qpid/doc/book/src/old/Getting-Started.xml b/qpid/doc/book/src/old/Getting-Started.xml new file mode 100644 index 0000000000..216a52170e --- /dev/null +++ b/qpid/doc/book/src/old/Getting-Started.xml @@ -0,0 +1,90 @@ +<chapter id="Getting-Started"> + +<!-- + + 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. + +--> +<title>Getting Started</title> +<para>To get started with Apache Qpid, follow the steps below.</para> + +<orderedlist> +<listitem><para>Download Apache Qpid.</para></listitem> +<listitem> + <para>Start a broker. </para> + <itemizedlist> + <listitem><para><xref linkend="chapter-Running-a-Qpid-Java-Broker"/></para></listitem> + <listitem><para><xref linkend="section-Running-a-Qpid-CPP-Broker"/></para></listitem> + <listitem><para><xref linkend="chapter-Managing-CPP-Broker"/>(AMQP 0-10, works with the Qpid C++ broker)</para></listitem> + </itemizedlist> +</listitem> +<listitem> + <para>Run an example program from the downloaded software, or from the following URLs (these are svn URLs, which you can use to browse the examples or check them out):</para> + <itemizedlist> + <listitem><para>C++ (AMQP 0-10):</para> + <itemizedlist> + <listitem><para>Examples:</para><para><ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/cpp/examples/">https://svn.apache.org/repos/asf/qpid/trunk/qpid/cpp/examples/</ulink></para></listitem> + <listitem><para>Running the C++ Examples:</para><para><ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/cpp/examples/README.txt">https://svn.apache.org/repos/asf/qpid/trunk/qpid/cpp/examples/README.txt</ulink></para></listitem> + </itemizedlist> +</listitem> +<listitem> + <para>Java JMS (AMQP 0-10):</para> + <itemizedlist> + <listitem><para>Examples:</para><para><ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/java/client/example/">https://svn.apache.org/repos/asf/qpid/trunk/qpid/java/client/example/</ulink></para></listitem> + <listitem><para>Script for Running the Java JMS Examples </para><para><ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/java/client/example/src/main/java/runSample.sh">https://svn.apache.org/repos/asf/qpid/trunk/qpid/java/client/example/src/main/java/runSample.sh</ulink></para></listitem> + </itemizedlist> +</listitem> +<listitem> + <para>Python (AMQP 0-10):</para> + <itemizedlist> + <listitem><para>Examples:</para><para><ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/python/examples/">https://svn.apache.org/repos/asf/qpid/trunk/qpid/python/examples/</ulink></para></listitem> + <listitem><para>Running the Python Examples</para><para><ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/python/examples/README">https://svn.apache.org/repos/asf/qpid/trunk/qpid/python/examples/README</ulink></para></listitem> + </itemizedlist> +</listitem> +<listitem> + <para>Ruby (AMQP 0-10):</para> + <itemizedlist> + <listitem><para>Examples: </para><para><ulink url="https://svn.apache.org/repos/asf/qpid/trunk/qpid/ruby/examples/">https://svn.apache.org/repos/asf/qpid/trunk/qpid/ruby/examples/</ulink></para></listitem> + </itemizedlist> +</listitem> +<listitem> + <para>.NET (AMQP 0-10):</para> + <itemizedlist> + <listitem><para>Examples:</para><para><ulink url="http://svn.apache.org/viewvc/qpid/trunk/qpid/dotnet/client-010/examples/">http://svn.apache.org/viewvc/qpid/trunk/qpid/dotnet/client-010/examples/</ulink></para></listitem> + <listitem><para><xref linkend="NETUserGuide-Tutorial"/></para></listitem> + </itemizedlist> +</listitem> +</itemizedlist> +</listitem> +<listitem> + <para>Read the API Guides and Documentation</para> + <itemizedlist> + <listitem><para>C++ Client API (AMQP 0-10)</para><para><ulink url="http://qpid.apache.org/docs/api/cpp/html/index.html"></ulink></para></listitem> + <listitem><para><xref linkend="How-to-Use-JNDI"/></para></listitem> + <listitem><para>Python Client API (AMQP 0-10)</para><para><ulink url="http://qpid.apache.org/docs/api/python/html/index.html">http://qpid.apache.org/docs/api/python/html/index.html</ulink></para></listitem> + </itemizedlist> +</listitem> +<listitem> + <para>Get your Questions Answered</para> + <itemizedlist> + <listitem><para>Read the <xref linkend="FAQ"/></para></listitem> + <listitem><para>Ask a question on the user list</para><para>mailto:users-subscribe@qpid.apache.org</para></listitem> + </itemizedlist> +</listitem> +</orderedlist> +</chapter> diff --git a/qpid/doc/book/src/old/How-to-Use-JNDI.xml b/qpid/doc/book/src/old/How-to-Use-JNDI.xml new file mode 100644 index 0000000000..0d6315c2a3 --- /dev/null +++ b/qpid/doc/book/src/old/How-to-Use-JNDI.xml @@ -0,0 +1,175 @@ +<?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. + +--> + +<chapter id="How-to-Use-JNDI"> + <title> + How to Use JNDI + </title> + <section role="h2" id="HowtoUseJNDI-HowtousethePropertiesFileInitialContextFactory"> + <title> + How to use the PropertiesFileInitialContextFactory + </title> + + <para> + This ContextFactory uses a java properties formatted file to + setup initial values. + </para> + <section role="h3" id="HowtoUseJNDI-JNDIPropertysetup"> + <title> + JNDI Property setup + </title> + <para> + By setting the JNDI Initial Context Factory and URL as + below it is possible to load any File from the locally + mounted file system to use for JNDI purposes. The format + of the file is described in the next section. + </para> + <programlisting> +java.naming.factory.initial = org.apache.qpid.jndi.PropertiesFileInitialContextFactory +java.naming.provider.url = <path to JNDI File> +</programlisting> + <para> + By simply setting these two system properties you can jump + straight to the InitialContext creation in your code. + </para> + </section> + <section role="h3" id="HowtoUseJNDI-Examplepropertiesfile"> + <title> + Example properties file </title> + <para> + This is the example properties file. + </para> + <programlisting> +# register some connection factories +# connectionfactory.[jndiname] = [ConnectionURL] +connectionfactory.local = amqp://guest:guest@clientid/testpath?brokerlist='vm://:1' + +# register some queues in JNDI using the form +# queue.[jndiName] = [physicalName] +queue.MyQueue = example.MyQueue + +# register some topics in JNDI using the form +# topic.[jndiName] = [physicalName] +topic.ibmStocks = stocks.nyse.ibm + +# Register an AMQP destination in JNDI +# NOTE: Qpid currently only supports direct,topics and headers +# destination.[jniName] = [BindingURL] +destination.direct = direct://amq.direct//directQueue +</programlisting> + <para> + The property file allows a number of queues to be defined that + can then be discovered via JNDI. There are four properties used + by the PFICFactory. + <emphasis>connectionfactory.<jndiname></emphasis> this is the <xref linkend="Connection-URL-Format"/> that the connection + factory will use to perform connections. + <emphasis>queue.<jndiname></emphasis> this defines a jms queue or in + amqp a amq.direct exchange + <emphasis>topic.<jndiname></emphasis> this defines a jms topic or in + amqp a amq.topic exchange + <emphasis>destination.<jndiname></emphasis> this takes a <xref linkend="BindingURLFormat"/> + and so can be used for defining all amq destinations, queues, + topics and header matching. + </para><para> + In all of these properties the <emphasis><jndiname></emphasis> is the + string value that would be given when performing a lookup. + </para><para> + <emphasis>NOTE</emphasis>: This does not create the queue on the broker. You + should ensure that you have created the queue before publishing + to it. Queues can be declared in the virtualhosts.xml file so + that they are created on broker startup, or created dynamically + by consuming clients. Topics and other destinations that use + temporary queues cannot be created in this way, so a consumer + must be created first before publishing messages with mandatory + routing. + </para> + </section> + <section role="h3" id="HowtoUseJNDI-Examplelookupcode"> + <title> + Example lookup code + </title><!--h3--> + + <para> + The <emphasis>bindingValue</emphasis> is the String that would be placed in + <emphasis><jndiname></emphasis> above. + </para> + + <example> + <title>Simple JNDI lookup using files</title> + <programlisting> +//Ensure you have your system properties set +final String INITIAL_CONTEXT_FACTORY = "org.apache.qpid.jndi.PropertiesFileInitialContextFactory"; + +System.setProperty(Context.INITIAL_CONTEXT_FACTORY, INITIAL_CONTEXT_FACTORY); +System.setProperty(Context.PROVIDER_URL, _JNDIFile); + +// Create the initial context +Context ctx = new InitialContext(); + +// Perform the binds +object = ctx.lookup(bindingValue); + +// Close the context when we're done +ctx.close(); +</programlisting> +</example> + +<example> +<title>Simple JNDI lookup using properties</title> + + <programlisting> + +final String INITIAL_CONTEXT_FACTORY = "org.apache.qpid.jndi.PropertiesFileInitialContextFactory"; + +final String CONNECTION_JNDI_NAME = "local"; +final String CONNECTION_NAME = "amqp://guest:guest@clientid/testpath?brokerlist='vm://:1'"; + +final String QUEUE_JNDI_NAME = "queue"; +final String QUEUE_NAME = "example.MyQueue"; + +// Set the properties ... +Properties properties = new Properties(); +properties.put(Context.INITIAL_CONTEXT_FACTORY, INITIAL_CONTEXT_FACTORY); +properties.put("connectionfactory."+CONNECTION_JNDI_NAME , CONNECTION_NAME); +properties.put("queue."+QUEUE_JNDI_NAME , QUEUE_NAME); + +// Create the initial context +Context ctx = new InitialContext(properties); + +// Perform the lookups +ConnectionFactory factory = (ConnectionFactory)ctx.lookup(CONNECTION_JNDI_NAME); +Queue queue = (Queue)ctx.lookup(QUEUE_JNDI_NAME); + +// Close the context when we're done +ctx.close(); +</programlisting> +</example> + </section> + + <section> + <title>Using Qpid with Other JNDI Providers</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Using-Qpid-with-other-JNDI-Providers.xml"/> + </section> +<!--h2--> + </section> + +</chapter> diff --git a/qpid/doc/book/src/old/InfoPlugin.xml b/qpid/doc/book/src/old/InfoPlugin.xml new file mode 100644 index 0000000000..aebcd08c02 --- /dev/null +++ b/qpid/doc/book/src/old/InfoPlugin.xml @@ -0,0 +1,261 @@ +<?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 xmlns="http://docbook.org/ns/docbook" version="5.0"> +<title> +OSGI Info Plugin +</title> + <para> The Info OSGI Plugin was developed as a mean of monitoring the qpid broker startup/shutdown + times along with selected JVM and OS details. It was written as a OSGI plugin so it can be + used as needed. </para> + + +<section> + <title>How it works</title> + <para> Assuming the plugin is deployed, upon the Activator invocation (which happens when OSGI + loads the bundles), the plugin looks for its configuration file. If the file cannot be + found, the plugin does not perform any operation and will silently exit. If the + configuration is found, it is loaded and parsed. A predefined set of data is collected and + messages are generated as per the configuration templates (see below for details).</para> + <para> Further, the messages are sent using one of the supported protocols (currently http + post and soap) to the configured destination. The same scenario takes place on the plugin + unload phase which usually takes place upon broker shutdown. </para> +</section> + +<section> + <title>Data Gathering</title> + <para> +The info plugin collects a pre-defined set of data, and generates a message according to a template +defined in each section of the ini file. Data can be of 2 categories: +<orderedlist numeration="loweralpha" spacing="normal"> + <listitem> + <para>JVM specific</para> + </listitem> + <listitem> + <para>application specific</para> + </listitem> + </orderedlist> + </para> + <para> +Each data has a variable name associated which can be used for the message generation template. +The convention chosen for template is: @[variable (in uppercase)] (eg @IP, @PORT) (see configuration section +for message examples). +</para> +<para> +The following application specific info are gathered (variable names in round brackets): + + <orderedlist numeration="arabic" spacing="normal"> + <listitem> + <para>The JMX Port the application is listening to (jmxport)</para> + </listitem> + <listitem> + <para>The Port(s) the broker is listening to, comma delimited (port)</para> + </listitem> + <listitem> + <para>The Broker Version (version)</para> + </listitem> + <listitem> + <para>The key store path (KeystorePath)</para> + </listitem> + <listitem> + <para>The Plugin Directory (PluginDirectory)</para> + </listitem> + <listitem> + <para>The QPID work directory (QpidWork)</para> + </listitem> + <listitem> + <para>The JMX Principal Database (JMXPrincipalDatabase)</para> + </listitem> +</orderedlist> +</para> + <para> +The following JVM specific info are collected (variable names in round brackets): + + <orderedlist numeration="arabic" spacing="normal"> + <listitem> + <para>Hostname (hostname)</para> + </listitem> + <listitem> + <para>IP address of the current machine (ip)</para> + </listitem> + <listitem> + <para>Number of CPU cores (CPUCores)</para> + </listitem> + <listitem> + <para>Maximum memory (Maximum_Memory)</para> + </listitem> + <listitem> + <para>Free Memory (Free_Memory)</para> + </listitem> + <listitem> + <para>Java Class Path (java.class.path)</para> + </listitem> + <listitem> + <para>Jave Home (java.home)</para> + </listitem> + <listitem> + <para>Java VM Name (java.vm.name)</para> + </listitem> + <listitem> + <para>Java VM Vendor (java.vm.vendor)</para> + </listitem> + <listitem> + <para>Java VM Version (java.vm.version)</para> + </listitem> + <listitem> + <para>Java Class Version (java.class.version)</para> + </listitem> + <listitem> + <para>Java Runtime Version (java.runtime.version)</para> + </listitem> + <listitem> + <para>OS Architecture (os.arch)</para> + </listitem> + <listitem> + <para>Sun Architecture Data Model (sun.arch.data.model)</para> + </listitem> + <listitem> + <para>User home directory (user.home)</para> + </listitem> + <listitem> + <para>User Name (user.name)</para> + </listitem> + <listitem> + <para>User Time Zone (user.timezone)</para> + </listitem> + </orderedlist> +</para> +</section> + + +<section> + <title>Plugin Configuration</title> +<para> +The plugin configuration file is currently hardcoded to be: $QPID_HOME/etc/qpidinfo.ini +We plan to provide a mean to change the configuration by using system property (eg -DInfoPluginConfig) but +currently this is not available. +</para> +<para> +As it might be useful to send more than 1 message, eventually to different destinations, +we chose an ini file layout for the plugin configuration that consists of a global section +and set of individual sections, one for each message to be sent. +</para> + <para> + The configuration file has a global section composed of any key-value pairs placed before the start + of an ini-type section (eg [section]). The role of the global section is to provide a set of values + that would be inferred in each subsequent section. Any section from the config file can override any + global variable by specifying the respective key-value pair inside. + </para> + <para> The key protocol is mandatory, the plugin will not work if protocol=soap or protocol=http is + not specified. For soap, we expect the following keys to be present: <itemizedlist> + <listitem> + <para>soap.hostname</para> + </listitem> + <listitem> + <para>soap.port</para> + </listitem> + <listitem> + <para>soap.path</para> + </listitem> + <listitem> + <para>soap.envelope</para> + </listitem> + </itemizedlist> For http the following keys have to be present: <itemizedlist> + <listitem> + <para>http.url</para> + </listitem> + <listitem> + <para>http.envelope</para> + </listitem> + </itemizedlist> The names are self-explanatory, please see the example below. The protocol + key cannot be overwritten in the sections and it has to be chosen initially. </para> + </section> + +<section><title>Example Configuration</title> + <para> +For soap messages, we will abbreviate the XML header by omitting the namespaces in the config, +in order to be more readable. A minimal correct XML for the soap envelope would be + <programlisting> + <![CDATA[ + <?xml version=\"1.0\"?> + <soap:Envelope + xmlns:soap=\"http://www.w3.org/2001/12/soap-envelope\" + soap:encodingStyle=\"http://www.w3.org/2001/12/soap-encoding\"> + ...some content... + </soap:Envelope> + ]]> + </programlisting> + + NB. On the ini file, there can be no text wrapping for any entry (as above), the whole text should come into + a single line, irrespective of how long it is. + + </para> + +<programlisting> +<![CDATA[ +## Ini file using SOAP +protocol=soap +soap.hostname=host1 +soap.port=8080 + +[Message1] +soap.path=/axis2/services/QpidInfo +soap.action=qpidevent +soap.envelope=<?xml version=\"1.0\"?><soap:Envelope>@ACTION-@VERSION</soap:Envelope> + +[Message2] +soap.hostname=host2 +soap.port=9090 +soap.path=/axis1/services/Info +soap.envelope=<?xml version=\"1.0\"?><soap:Envelope">@ACTION-@VERSION from @IP:@PORT</soap:Envelope> + +## End of File +]]> +</programlisting> + +<para> +and another example, this time using http: + +<programlisting> +<![CDATA[ +protocol=http +http.url=http://mywebserver:8080/postServlet + +[Message1] +http.envelope=Event from qpid broker at: @IP, running qpid version: @VERSION + +[Message2] +http.url=http://myotherwebserver:9090/postServlet1 +http.envelope=Event for qpid broker @VERSION from @IP:@PORT running java @JAVA.VM.VERSION +]]> +</programlisting> + </para> + <para> + The ini file is supporting comments starting with # or ; anywhere in the file. + The global section is considered to be the first set of lines from the ini file before the first [Section] encountered. + </para> + </section> + +</section> + + + diff --git a/qpid/doc/book/src/old/Introduction.xml b/qpid/doc/book/src/old/Introduction.xml new file mode 100644 index 0000000000..8f92c207cf --- /dev/null +++ b/qpid/doc/book/src/old/Introduction.xml @@ -0,0 +1,106 @@ +<?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. + +--> + +<chapter> + +<title>Apache Qpid: Open Source AMQP Messaging</title> + +<para>Enterprise Messaging systems let programs communicate by exchanging messages, much as people communicate by exchanging email. Unlike email, enterprise messaging systems provide guaranteed delivery, speed, security, and freedom from spam. Until recently, there was no open standard for Enterprise Messaging systems, so programmers either wrote their own, or used expensive proprietary systems.</para> + +<para>AMQP Advanced Message Queuing Protocol is the first open standard for Enterprise Messaging. It is designed to support messaging for just about any distributed or business application. Routing can be configured flexibly, easily supporting common messaging paradigms like point-to-point, fanout, publish-subscribe, and request-response.</para> + +<para>Apache Qpid implements the latest AMQP specification, providing transaction management, queuing, distribution, security, management, clustering, federation and heterogeneous multi-platform support and a lot more. And Apache Qpid is extremely fast. Apache Qpid <ulink url="### FIX ME ###">aims to be 100% AMQP Compliant</ulink>.</para> + +<section> +<title>AMQP Messaging Brokers</title> + +<para>Qpid provides two AMQP messaging brokers:</para> + +<itemizedlist> + <listitem><para>Implemented in C++ - high performance, low latency, and RDMA support.</para></listitem> + <listitem><para>Implemented in Java - Fully JMS compliant, runs on any Java platform.</para></listitem> +</itemizedlist> + +<para>Both AMQP messaging brokers support clients in multiple languages, as long as the messaging client and the messaging broker use the same version of AMQP. See <ulink url="### FIX ME ###">Download</ulink> to see which messaging clients work with each broker.</para> + +</section> + +<section> +<title>AMQP Client APIs: C++, Java, JMS, Ruby, Python, and C#</title> + +<para>Qpid provides AMQP Client APIs for the following languages:</para> + +<itemizedlist> + <listitem><para>C++</para></listitem> + <listitem><para>Java, fully conformant with JMS 1.1</para></listitem> + <listitem><para>C# .NET, 0-10 using WCF</para></listitem> + <listitem><para>Ruby</para></listitem> + <listitem><para>Python</para></listitem> +</itemizedlist> + +</section> + +<section> +<title>Operating Systems and Platforms:</title> + +<para>The Qpid C++ broker runs on the following operating systems:</para> + +<itemizedlist> + <listitem><para>Linux systems</para></listitem> + <listitem><para>Windows</para></listitem> + <listitem><para>Solaris (coming soon)</para></listitem> +</itemizedlist> + +<para>The Qpid Java broker runs on:</para> + +<itemizedlist> + <listitem><para>Any Java platform</para></listitem> +</itemizedlist> + +<para>Qpid clients can be run on the following operating systems and platforms:</para> + +<itemizedlist> + <listitem><para>Java:</para> + <itemizedlist> + <listitem><para>any platform, production proven on Windows, Linux, Solaris</para></listitem> + </itemizedlist> + </listitem> + + + <listitem><para>C++:</para> + <itemizedlist> + <listitem><para>Linux</para></listitem> + <listitem><para>Windows</para></listitem> + <listitem><para>Solaris (coming soon)</para></listitem> + </itemizedlist> + </listitem> + + <listitem><para>C#</para> + <itemizedlist> + <listitem><para>.NET</para></listitem> + </itemizedlist> + </listitem> + +</itemizedlist> + +</section> +</chapter> diff --git a/qpid/doc/book/src/old/Java-Broker-StatusLogMessages.xml b/qpid/doc/book/src/old/Java-Broker-StatusLogMessages.xml new file mode 100644 index 0000000000..98f876e532 --- /dev/null +++ b/qpid/doc/book/src/old/Java-Broker-StatusLogMessages.xml @@ -0,0 +1,294 @@ +<?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. + +--> +<?oxygen RNGSchema="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" type="xml"?> +<book xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"> + <info> + <title>Operational Logging</title> + <author> + <orgname>Apache Software Foundation</orgname> + </author> + </info> + <chapter> + <title>Status Log Messages</title> + <para>This file was derivied from LogMessages used within the Java Broker and originally defined on: + <tag xlink:href="http://cwiki.apache.org/confluence/display/qpid/Status+Update+Design#StatusUpdateDesign-InitialStatusMessages">Apache Wiki</tag></para> + <sect1> + <title>Technical Notes:</title> + <para>The status log messages file is a standard Java Properties file so white space is respected at the end of + the lines. This file could be processed in a number of ways:</para> + <para> + <orderedlist> + <listitem> + <para>ResourceBundle</para> + <para>This file is loaded as a ResourceBundle. The en_US addition to the + file is the localisation. Additional localisations can be provided and + will automatically be selected based on the <locale> value in the + config.xml. The default locale is en_US.</para> + </listitem> + <listitem> + <para>MessageFormat</para> + <para> Each entry is prepared with the Java Core MessageFormat methods. + Therefore most functionality you can do via MessageFormat can be done + here: </para> + <para><tag xlink:href="http://java.sun.com/javase/6/docs/api/java/text/MessageFormat.html">Java API for MessageFormat</tag></para> + <para>The caveat here is that only default String and number FormatTypes can + be used. This is due to the processing described in 3 below. If support + for date, time or choice is required then the GenerateLogMessages class + should be updated to provide support.</para> + </listitem> + <listitem> + <para>GenerateLogMessage/Velocity Macro</para> + <para>This is the only processing that this file goes through</para> + <orderedlist> + <listitem> + <para>Class Generation:</para> + <para>The GenerateLogMessage processes this file and uses the + velocity Macro to create classes with static methods to perform + the logging and give us compile time validation. </para> + </listitem> + <listitem> + <para>Property Processing</para> + <para>During the class generation the message properties ({x}) are + identified and used to create the method signature.</para> + </listitem> + <listitem> + <para>Option Processing</para> + <para>The Classes perform final formatting of the messages at + runtime based on optional parameters that are defined within the + message. Optional parameters are enclosed in square brackets + e.g. [optional].</para> + </listitem> + </orderedlist> + </listitem> + </orderedlist> + </para> + <para><emphasis role="bold">Format Note:</emphasis></para> + <para> As mentioned earlier white space in this file is very important. One thing in + particular to note is the way MessageFormat performs its replacements. The + replacement text will totally replace the {xxx} section so there will be no addition + of white space or removal e.g. </para> + <programlisting><![CDATA[MSG = Text----{0}----]]> + </programlisting> + <para> When given parameter 'Hello' result in text: </para> + <programlisting><![CDATA[Text----Hello----]]> + </programlisting> + <para>For simple arguments this is expected however when using Style formats then it can + be a little unexpected. In particular a common pattern is used for number + replacements : {0,number,}. This is used in the Broker to display an Integer simply + as the Integer with no formatting. e.g new Integer(1234567) becomes the String + "1234567" which is can be contrasted with the pattern without a style format field : + {0,number} which becomes string "1,234,567".</para> + <para>What you may not expect is that {0,number, } would produce the String " 1234567" + note that the space after the ',' here has resulted in a space in front of the + number in the output.</para> + <para>More details on the SubformatPattern can be found on the API link above. To + provide fixed log messages as required by the Technical Specification:</para> + <para><tag xlink:href="http://cwiki.apache.org/confluence/display/qpid/Operational+Logging+-+Status+Update+-+Technical+SpecificationOperationalLogging-StatusUpdate-TechnicalSpecification-Howtoprovidefixedlogmessages">Operational Logging Tech Specification</tag></para> + <para>This file is processed by Velocity to create a number of classes that contain + static methods that provide LogMessages in the code to provide compile time + validation.</para> + <para>For details of what processing is done see GenerateLogMessages. </para> + <para>What a localiser or developer need know is the following: </para> + <para>The Property structure is important as it defines how the class and methods will + be built.</para> + </sect1> + <sect1> + <title>Class Generation</title> + <para> Each class of messages will be split in to their own <Class>Messages.java. + Each logmessage file contains only one class of messages the <Class> name is + derived from the name of the logmessages file e.g. <Class>_logmessages.properties. + </para> + </sect1> + <sect1> + <title>Property Format</title> + <para>The property format MUST adhere to the follow format to make it easier to use the + logging API as a developer but also so that operations staff can easily locate log + messages in the output.</para> + <para>The property file should contain entries in the following format:</para> + <programlisting><![CDATA[<Log Identifier,developer focused>=<Log Identifier,Operate focus>:<Log Message>]]> + </programlisting> + + <para>eg:</para> + <programlisting><![CDATA[SHUTTING_DOWN = BRK-1003 : Shutting down : {0} port {1,number,}]]> + </programlisting> + + <para>Note: the developer focused identifier will become a method name so only a valid + method name should be used. Currently only '-' are converted to '_'.</para> + <para>That said properties generate the logging code at build time so any error can be + easily identified.</para> + <para>The three character identifier show above in BRK-1003 should ideally be unique. + This is the only requirement, limiting to 3 characters is not required.</para> + <para>The current broker contains the following mappings:</para> + <para> + <table> + <title>Status Messages Mapping</title> + <tgroup cols="2"> + <colspec colname="c1" colnum="1" colwidth="118.29pt"/> + <colspec colname="c2" colnum="2" colwidth="135.18pt"/> + <thead> + <row> + <entry>Class</entry> + <entry> Type</entry> + </row> + </thead> + <tbody> + <row> + <entry>Broker</entry> + <entry>BRK</entry> + </row> + <row> + <entry>Management Console</entry> + <entry>MNG</entry> + </row> + <row> + <entry>VirtualHost</entry> + <entry>VHT</entry> + </row> + <row> + <entry>MessageStore</entry> + <entry>MST</entry> + </row> + <row> + <entry>ConfigStore</entry> + <entry>CFG</entry> + </row> + <row> + <entry>TransactionLog</entry> + <entry>TXN</entry> + </row> + <row> + <entry>Connection</entry> + <entry>CON</entry> + </row> + <row> + <entry>Channel</entry> + <entry>CHN</entry> + </row> + <row> + <entry>Queue</entry> + <entry>QUE</entry> + </row> + <row> + <entry>Exchange</entry> + <entry>EXH</entry> + </row> + <row> + <entry>Binding</entry> + <entry>BND</entry> + </row> + <row> + <entry>Subscription</entry> + <entry>SUB</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </sect1> + <sect1> + <title>Property Processing</title> + <para> + Each property is then processed by the GenerateLogMessages class to identify + the number and type of parameters, {x} entries. Parameters are defaulted to + String types but the use of FormatType number (e.g.{0,number}) will result + in a Number type being used. These parameters are then used to build the + method parameter list. e.g: + </para> + + <para>Property:</para> + <programlisting><![CDATA[SHUTTING_DOWN = BRK-1003 : Shutting down : {0} port {1,number,}]]></programlisting> + <para>becomes Method:</para> + <programlisting><![CDATA[public static LogMessage SHUTTING_DOWN(String param1, Number param2)]]> + </programlisting> + + <para> + This improves our compile time validation of log message content and + ensures that change in the message format does not accidentally cause + erroneous messages.</para> + </sect1> + <sect1> + <title>Option Processing</title> + <para> + Options are identified in the log message as being surrounded by square + brackets ([ ]). These optional values can themselves contain parameters + however nesting of options is not permitted. Identification is performed on + first matching so given the message: + </para> + <programlisting><![CDATA[Msg = Log Message [option1] [option2] ]]></programlisting> + <para> + Two options will be identified and enabled to select text 'option1' and + 'option2'. + </para> + <para> + The nesting of a options is not supported and will provide + unexpected results. e.g. Using Message: + </para> + <programlisting><![CDATA[Msg = Log Message [option1 [sub-option2]] ]]></programlisting> + <para> + The options will be 'option1 [sub-option2' and 'sub-option2'. The first + option includes the second option as the nesting is not detected. + </para> + <para> + The detected options are presented in the method signature as boolean options + numerically identified by their position in the message. e.g. + Property: + </para> + <programlisting><![CDATA[ CON-1001 = Open : Client ID {0} [: Protocol Version : {1}] ]]></programlisting> + <para>becomes Method:</para> + <programlisting><![CDATA[ public static LogMessage CON_1001(String param1, String param2, boolean opt1) ]]></programlisting> + <para> + The value of 'opt1' will show/hide the option in the message. Note that + 'param2' is still required however a null value can be used if the optional + section is not desired. + </para> + <para> + Again here the importance of white space needs to be highlighted. + Looking at the QUE-1001 message as an example. The first thought on how this + would look would be as follows: + </para> + <programlisting><![CDATA[ QUE-1001 = Create : Owner: {0} [AutoDelete] [Durable] [Transient] [Priority: {1,number,}] ]]></programlisting> + <para> + Each option is correctly defined so the text that is defined will appear when + selected. e.g. 'AutoDelete'. However, what may not be immediately apparent is + the white space. Using the above definition of QUE-1001 if we were to print + the message with only the Priority option displayed it would appear as this: + </para> + <programlisting><![CDATA[ "Create : Owner: guest Priority: 1" ]]></programlisting> + <para> + Note the spaces here in between gues and Priority are present because only the text between the brackets + has been removed. + </para> + <para> + Each option needs to include white space to correctly format the message. So + the correct definition of QUE-1001 is as follows: + </para> + <programlisting><![CDATA[ QUE-1001 = Create : Owner: {0}[ AutoDelete][ Durable][ Transient][ Priority: {1,number,}] ]]></programlisting> + <para> + Note that white space is included with each option and there is no extra + white space between the options. As a result the output with just Priority + enabled is as follows: + </para> + <programlisting><![CDATA[ "Create : Owner: guest Priority: 1" ]]></programlisting> + </sect1> + </chapter> +</book> diff --git a/qpid/doc/book/src/old/Java-JMS-Selector-Syntax.xml b/qpid/doc/book/src/old/Java-JMS-Selector-Syntax.xml new file mode 100644 index 0000000000..870e277b66 --- /dev/null +++ b/qpid/doc/book/src/old/Java-JMS-Selector-Syntax.xml @@ -0,0 +1,96 @@ +<!-- + - + - 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> + <title>Java JMS Selector Syntax</title> + <para>The AMQP Java JMS Messaging Client supports the following syntax for JMS selectors.</para> + +<programlisting><![CDATA[ +Comments: + + LINE_COMMENT: "--" (~["\n","\r"])* EOL + EOL: "\n"|"\r"|"\r\n" + BLOCK_COMMENT: "/*" (~["*"])* "*" ("*" | (~["*","/"] (~["*"])* "*"))* "/" + +Reserved Words (case insensitive): + + NOT: "NOT" + AND: "AND" + OR: "OR" + BETWEEN: "BETWEEN" + LIKE: "LIKE" + ESCAPE: "ESCAPE" + IN: "IN" + IS: "IS" + TRUE: "TRUE" + FALSE: "FALSE" + NULL: "NULL" + +Literals (case insensitive): + + DECIMAL_LITERAL: ["1"-"9"] (["0"-"9"])* (["l","L"])? + HEX_LITERAL: "0" ["x","X"] (["0"-"9","a"-"f","A"-"F"])+ + OCTAL_LITERAL: "0" (["0"-"7"])* + FLOATING_POINT_LITERAL: ( (["0"-"9"])+ "." (["0"-"9"])* (<EXPONENT>)? // matches: 5.5 or 5. or 5.5E10 or 5.E10 + | "." (["0"-"9"])+ (<EXPONENT>)? // matches: .5 or .5E10 + | (["0"-"9"])+ <EXPONENT> ) // matches: 5E10 + EXPONENT: "E" (["+","-"])? (["0"-"9"])+ + STRING_LITERAL: "'" ( ("''") | ~["'"] )* "'" + +Identifiers (case insensitive): + + ID : ["a"-"z", "_", "$"] (["a"-"z","0"-"9","_", "$"])* + QUOTED_ID : "\"" ( ("\"\"") | ~["\""] )* "\"" + +Grammar: + + JmsSelector := orExpression + orExpression := ( andExpression ( <OR> andExpression )* ) + andExpression := ( equalityExpression ( <AND> equalityExpression )* ) + equalityExpression := ( comparisonExpression ( "=" comparisonExpression + | "<>" comparisonExpression + | <IS> <NULL> + | <IS> <NOT> <NULL> )* ) + comparisonExpression := ( addExpression ( ">" addExpression + | ">=" addExpression + | "<" addExpression + | "<=" addExpression + | <LIKE> stringLitteral ( <ESCAPE> stringLitteral )? + | <NOT> <LIKE> <STRING_LITERAL> ( <ESCAPE> <STRING_LITERAL> )? + | <BETWEEN> addExpression <AND> addExpression + | <NOT> <BETWEEN> addExpression <AND> addExpression + | <IN> "(" <STRING_LITERAL> ( "," <STRING_LITERAL> )* ")" + | <NOT> <IN> "(" <STRING_LITERAL> ( "," <STRING_LITERAL> )* ")" )* ) + addExpression := multExpr ( ( "+" multExpr | "-" multExpr ) )* + multExpr := unaryExpr ( "*" unaryExpr | "/" unaryExpr | "%" unaryExpr )* + unaryExpr := ( "+" unaryExpr | "-" unaryExpr | <NOT> unaryExpr | primaryExpr ) + primaryExpr := ( literal | variable | "(" orExpression ")" ) + literal := ( <STRING_LITERAL> + | <DECIMAL_LITERAL> + | <HEX_LITERAL> + | <OCTAL_LITERAL> + | <FLOATING_POINT_LITERAL> + | <TRUE> + | <FALSE> + | <NULL> ) + variable := ( <ID> | <QUOTED_ID> ) +]]></programlisting> + +</section> diff --git a/qpid/doc/book/src/old/Management-Design-notes.xml b/qpid/doc/book/src/old/Management-Design-notes.xml new file mode 100644 index 0000000000..76f0dac926 --- /dev/null +++ b/qpid/doc/book/src/old/Management-Design-notes.xml @@ -0,0 +1,2136 @@ +<?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><title> + Management Design notes + </title><section role="h2" id="ManagementDesignnotes-StatusofThisDocument"><title> + Status + of This Document + </title> + + <para> + This document does not track any current development activity. It + is the specification of the management framework implemented in + the M3 release of the C++ broker and will be left here for user + and developer reference. + </para><para> + Development continues on the Qpid Management Framework (QMF) for + M4. If you are using M3, this is the document you need. If you + are using the SVN trunk, please refer to <xref linkend="qpid_Qpid-Management-Framework"/> for + up-to-date information. + </para> + <!--h2--></section> + + <section role="h2" id="ManagementDesignnotes-Introduction"><title> + Introduction + </title> + + <para> + This document describes the management features that are used in + the QPID C++ broker as of the M3 milestone. These features do not + appear in earlier milestones nor are they implemented in the Java + broker. + </para><para> + This specification is <emphasis>not</emphasis> a standard and is not endorsed + by the AMQP working group. When such a standard is adopted, the + QPID implementation will be brought into compliance with that + standard. + </para> + <!--h2--></section> + + <section role="h2" id="ManagementDesignnotes-Links"><title> + Links + </title> + + <itemizedlist> + <listitem><para>The schema is checked into <xref linkend="qpid_management-schema.xml"/>. + </para></listitem> + </itemizedlist><section role="h3" id="ManagementDesignnotes-DesignnoteforgettinginfoinandoutviaJMX"><title> + Design + note for getting info in and out via JMX + </title> + + <para> + <xref linkend="qpid_JMX-Gateway"/> + </para> + <!--h3--></section> + + <!--h2--></section> + + <section role="h2" id="ManagementDesignnotes-ManagementRequirements"><title> + Management + Requirements + </title> + + <itemizedlist> + <listitem><para>Must operate from a formally defined management schema. + </para></listitem> + <listitem><para>Must natively use the AMQP protocol and its type system. + </para></listitem> + <listitem><para>Must support the following operations + <itemizedlist> + <listitem><para>SET operation on configurable (persistent) aspects of + objects + </para></listitem> + <listitem><para>GET operation on all aspects of objects + </para></listitem> + <listitem><para>METHOD invocation on schema-defined object-specific + methods + </para></listitem> + <listitem><para>Distribution of unsolicited periodic updates of + instrumentation data + <itemizedlist> + <listitem><para>Data updates shall carry an accurate sample timestamp + for rate calculation + </para></listitem> + <listitem><para>Updates shall carry object create/delete timestamps. + </para></listitem> + <listitem><para>Transient objects shall be fully accounted for via + updates. Note that short-lived transient objects may come + and go within a single update interval. All of the + information pertaining to such an object must be captured + and transmitted. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para>Distribution of unsolicited event and/or alert + indications (schema defined) + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para>Role-based access control at object, operation, and method + granularity + </para></listitem> + <listitem><para>End-to-end encryption and signing of management content + </para></listitem> + <listitem><para>Schema must be self-describing so the management client need + not have prior knowledge of the management model of the system + under management. + </para></listitem> + <listitem><para>Must be extensible to support the management of objects + beyond the QPID component set. This allows AMQP to be used as a + general-purpose management protocol. + </para></listitem> + </itemizedlist> + <!--h2--></section> + + <section role="h2" id="ManagementDesignnotes-DefinitionofTerms"><title> + Definition + of Terms + </title> + + <table><title/><tgroup cols="2"> + <tbody> + <row> + <entry> + class + </entry> + <entry> + A type definition for a manageable object. + </entry> + </row> + <row> + <entry> + package + </entry> + <entry> + A grouping of class definitions that are related to a + single software component. The package concept is used to + extend the management schema beyond just the QPID software + components. + </entry> + </row> + <row> + <entry> + object + </entry> + <entry> + Also "manageable object". An instantiation of a class. An + object represents a physical or logical component in the + core function of the system under management. + </entry> + </row> + <row> + <entry> + property + </entry> + <entry> + A typed member of a class which represents a configurable + attribute of the class. In general, properties don't change + frequently or may not change at all. + </entry> + </row> + <row> + <entry> + statistic + </entry> + <entry> + A typed member of a class which represents an + instrumentation attribute of the class. Statistics are + always read-only in nature and tend to change rapidly. + </entry> + </row> + <row> + <entry> + method + </entry> + <entry> + A member of a class which represents a callable procedure + on an object of the class. Methods may have an arbitrary + set of typed arguments and may supply a return code. + Methods typically have side effects on the associated + object. + </entry> + </row> + <row> + <entry> + event + </entry> + <entry> + A member of a class which represents the occurence of an + event of interest within the system under management. + </entry> + </row> + <row> + <entry> + management broker + </entry> + <entry> + A software component built into the messaging broker that + handles management traffic and distributes management data. + </entry> + </row> + <row> + <entry> + management agent + </entry> + <entry> + A software component that is separate from the messaging + broker, connected to the management broker via an AMQP + connection, which allows any software component to be + managed remotely by QPID. + </entry> + </row> + </tbody> + </tgroup></table> + <!--h2--></section> + + + <section role="h2" id="ManagementDesignnotes-OperationalScenarios-3ABasicvs.Extended"><title> + Operational + Scenarios: Basic vs. Extended + </title> + + <para> + The extensibility requirement introduces complexity to the + management protocol that is unnecessary and undesirable for the + user/developer that wishes only to manage QPID message brokers. + For this reason, the protocol is partitioned into two parts: The + <emphasis>basic protocol</emphasis>, which contains only the capability to + manage a single broker; and the <emphasis>extended protocol</emphasis>, which + provides the hooks for managing an extended set of components. A + management console can be implemented using only the basic + protocol if the extended capabilities are not needed. + </para> +<!--h2--></section> + + + <section role="h2" id="ManagementDesignnotes-ArchitecturalFramework"><title> + Architectural + Framework + </title> + + <para> + <xref linkend="qpid_qmf_architecture"/> + </para> + <!--h2--></section> + + <section role="h2" id="ManagementDesignnotes-TheManagementExchange"><title> + The + Management Exchange + </title> + + <para> + The management exchange (called "qpid.management" currently) is a + special type of exchange used for remote management access to the + Qpid broker. The management exchange is an extension of the + standard "Topic" exchange. It behaves like a topic exchange with + the following exceptions: + </para><orderedlist> + <listitem><para>When a queue is successfully bound to the exchange, a method + is invoked on the broker's management agent to notify it of the + presence of a new remote managment client. + </para></listitem> + <listitem><para>When messages arrive at the exchange for routing, the + exchange examines the message's routing key and if the key + represents a management command or method, it routes it directly + to the management agent rather than routing it to queues using + the topic algorithm. + The management exchange is used by the management agent to + distribute unsolicited management data. Such data is classified + by the routing key allowing management clients to register for + only the data they need. + </para></listitem> + </orderedlist><section role="h3" id="ManagementDesignnotes-RoutingKeyStructure"><title> + Routing + Key Structure + </title> + + <para> + As noted above, the structure of the binding and routing keys + used on the management exchange is important to the function of + the management architecture. The routing key of a management + message determines: + </para><orderedlist> + <listitem><para>The type of message (i.e. operation request or unsolicited + update). + </para></listitem> + <listitem><para>The class of the object that the message pertains to. + </para></listitem> + <listitem><para>The specific operation or update type. + </para></listitem> + <listitem><para>The namespace in which the class belongs. This allows for + plug-in expansion of the management schema for manageable objects + that are outside of the broker itself. + </para></listitem> + </orderedlist><para> + Placing this information in the routing key provides the ability + to enforce access control at class, operation, and method + granularity. It also separates the command structure from the + content of the management message (i.e. element values) allowing + the content to be encrypted and signed end-to-end while still + allowing access control at the message-transport level. This + means that special access control code need not be written for + the management agent. + There are two general types of routing/binding key: + </para><itemizedlist> + <listitem><para> + <emphasis>Command</emphasis> messages use the key: + agent.<bank#> or broker + </para></listitem> + <listitem><para> + <emphasis>Unsolicited</emphasis> keys have the structure: + mgmt.<agent>.<type>.<package>.<class>.<severity> + where + <itemizedlist> + <listitem><para> + <agent> is the uuid of the originating + management agent, + </para></listitem> + <listitem><para> + <type> is one of "schema", "prop", "stat", + or "event", + </para></listitem> + <listitem><para> + <package> is the namespace in which the + <class> name is valid, and + </para></listitem> + <listitem><para> + <class> is the name of the class as defined + in the schema. + </para></listitem> + <listitem><para> + <severity> is relevant for events only. It + is one of "critical", "error", "warning", or "info". + </para></listitem> + </itemizedlist> + </para></listitem> + </itemizedlist><para> + In both cases, the content of the message (i.e. method arguments, + element values, etc.) is carried in the body segment of the + message. + </para><para> + The <package> namespace allows this management + framework to be extended with the addition of other software + packages. + </para> + <!--h3--></section> + <!--h2--></section> + + <section role="h2" id="ManagementDesignnotes-TheProtocol"><title> + The Protocol + </title> + + <section role="h3" id="ManagementDesignnotes-ProtocolHeader"><title> + Protocol + Header + </title> + + <para> + The body segments of management messages are composed of + sequences of binary-encoded data fields, in a manner consistent + with the 0-10 version of the AMQP specification. + </para><para> + All management messages begin with a message header: + </para> + <programlisting> + octet 0 1 2 3 4 5 6 7 + +---------+---------+---------+---------+---------+---------+---------+---------+ + | 'A' | 'M' | '1' | op-code | sequence | + +---------+---------+---------+---------+---------+---------+---------+---------+ +</programlisting> + <para> + The first three octets contain the protocol <emphasis>magic number</emphasis> + "AM1" which is used to identify the type and version of the + message. + </para><para> + The <emphasis>opcode</emphasis> field identifies the operation represented by + the message + </para> + <!--h3--></section> + + <section role="h3" id="ManagementDesignnotes-ProtocolExchangePatterns"><title> + Protocol + Exchange Patterns + </title> + + <para> + The following patterns are followed in the design of the + protocol: + </para><itemizedlist> + <listitem><para>Request-Response + </para></listitem> + <listitem><para>Query-Indication + </para></listitem> + <listitem><para>Unsolicited Indication + </para></listitem> + </itemizedlist><section role="h4" id="ManagementDesignnotes-TheRequestResponsePattern"><title> + The + Request-Response Pattern + </title> + + <para> + In the request-response pattern, a requestor sends a + <emphasis>request</emphasis> message to one of its peers. The peer then does + one of two things: If the request can be successfully processed, + a single <emphasis>response</emphasis> message is sent back to the requestor. + This response contains the requested results and serves as the + positive acknowledgement that the request was successfully + completed. + </para><para> + If the request cannot be successfully completed, the peer sends a + <emphasis>command complete</emphasis> message back to the requestor with an + error code and error text describing what went wrong. + </para><para> + The sequence number in the <emphasis>response</emphasis> or <emphasis>command + complete</emphasis> message is the same as the sequence number in the + <emphasis>request</emphasis>. + </para> + <programlisting> + Requestor Peer + | | + | --- Request (seq) ------------------------------------------> | + | | + | <----------------------------------------- Response (seq) --- | + | | +</programlisting> + + <programlisting> + Requestor Peer + | | + | --- Request (seq) ------------------------------------------> | + | | + | <-------------------------- Command Complete (seq, error) --- | + | | +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-TheQueryIndicationPattern"><title> + The + Query-Indication Pattern + </title> + + <para> + The query-indication pattern is used when there may be zero or + more answers to a question. In this case, the requestor sends a + <emphasis>query</emphasis> message to its peer. The peer processes the query, + sending as many <emphasis>indication</emphasis> messages as needed back to the + requestor (zero or more). Once the last <emphasis>indication</emphasis> has + been sent, the peer then sends a <emphasis>command complete</emphasis> message + with a success code indicating that the query is complete. + </para><para> + If there is an error in the <emphasis>query</emphasis>, the peer may reply with + a <emphasis>command complete</emphasis> message containg an error code. In this + case, no <emphasis>indication</emphasis> messages may be sent. + </para><para> + All <emphasis>indication</emphasis> and <emphasis>command complete</emphasis> messages shall + have the same sequence number that appeared in the <emphasis>query</emphasis> + message. + </para> + <programlisting> + Requestor Peer + | | + | --- Query (seq) --------------------------------------------> | + | | + | <--------------------------------------- Indication (seq) --- | + | <--------------------------------------- Indication (seq) --- | + | <--------------------------------------- Indication (seq) --- | + | <--------------------------------------- Indication (seq) --- | + | <--------------------------------------- Indication (seq) --- | + | | + | <------------------------ Command Complete (seq, success) --- | + | | +</programlisting> + + <programlisting> + Requestor Peer + | | + | --- Query (seq) --------------------------------------------> | + | | + | <-------------------------- Command Complete (seq, error) --- | + | | +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-TheUnsolicitedIndicationPattern"><title> + The + Unsolicited-Indication Pattern + </title> + + <para> + The unsolicited-indication pattern is used when one peer needs to + send unsolicited information to another peer, or to broadcast + information to multiple peers via a topic exchange. In this case, + indication messages are sent with the sequence number field set + to zero. + </para> + <programlisting> + Peer Peer + | | + | <----------------------------------- Indication (seq = 0) --- | + | <----------------------------------- Indication (seq = 0) --- | + | <----------------------------------- Indication (seq = 0) --- | + | <----------------------------------- Indication (seq = 0) --- | + | | +</programlisting> +<!--h4--></section> +<!--h3--></section> + + <section role="h3" id="ManagementDesignnotes-ObjectIdentifiers"><title> + Object + Identifiers + </title> + + <para> + Manageable objects are tagged with a unique 64-bit object + identifier. The object identifier space is owned and managed by + the management broker. Objects managed by a single management + broker shall have unique object identifiers. Objects managed by + separate management brokers may have the same object identifier. + </para><para> + If a management console is designed to manage multiple management + brokers, it must use the broker identifier as well as the object + identifier to ensure global uniqueness. + </para> + <programlisting> + 62 48 47 24 23 0 + +-+-------------+-----------------------+-----------------------+ + |0| sequence | bank | object | + +-+-------------+-----------------------+-----------------------+ + + bit 63 - reserved, must be zero + bits 63 .. 48 - broker boot sequence (32K) + bits 47 .. 24 - bank (16M) + bits 23 .. 0 - object (16M) +</programlisting> + <itemizedlist> + <listitem><para>For persistent IDs, boot-sequence is zero + </para></listitem> + <listitem><para>For non-persistent IDs, boot sequence is a constant number + which increments each time the management broker is restarted. + </para></listitem> + <listitem><para>Bank number: + <itemizedlist> + <listitem><para>0 - reserved + </para></listitem> + <listitem><para>1 - broker-persistent objects + </para></listitem> + <listitem><para>2..4 - store-persistent objects + </para></listitem> + <listitem><para>> 4 - transient objects + </para></listitem> + </itemizedlist> + </para></listitem> + </itemizedlist> +<!--h3--></section> + + + <section role="h3" id="ManagementDesignnotes-EstablishingCommunicationBetweenClientandAgent"><title> + Establishing Communication Between Client and Agent + </title> + + <para> + Communication is established between the management client and + management agent using normal AMQP procedures. The client creates + a connection to the broker and then establishes a session with + its corresponding channel. + </para><para> + Two private queues are then declared (only one if method + invocation is not needed). A management queue is declared and + bound to the qpid.management exchange. If the binding key is + "mgmt.#", all management-related messages sent to the exchange + will be received by this client. A more specific binding key will + result in a more restricted set of messages being received (see + the section on Routing Key Structure below). + </para><para> + If methods are going to be invoked on managed objects, a second + private queue must be declared so the client can receive method + replies. This queue is bound to the amq.direct exchange using a + routing key equal to the name of the queue. + </para><para> + When a client successfully binds to the qpid.management exchange, + the management agent schedules a schema broadcast to be sent to + the exchange. The agent will publish, via the exchange, a + description of the schema for all manageable objects in its + control. + </para> + <programlisting> + Client Broker + | | + | --- AMQP Connection and Session Setup ----------------------> | + | | + | --- Queue.declare (private data queue) ---------------------> | + | --- Bind queue to exchange 'qpid.management' key 'mgmt.#' --> | + | | + | --- Queue.declare (private method-reply queue) -------------> | + | --- Bind queue to exchange 'amq.direct' --------------------> | + | | + | --- Broker Request -----------------------------------------> | + | <---------------------------------------- Broker Response --- | + | | + | | + | | + | <------- Management schema via exchange 'qpid.management' --- | + | | +</programlisting> +<!--h3--></section> + + <section role="h3" id="ManagementDesignnotes-BroadcastofConfigurationandInstrumentationUpdates"><title> + Broadcast of Configuration and Instrumentation Updates + </title> + + <para> + The management agent will periodically publish updates to the + configuration and instrumentation of management objects under its + control. Under normal circumstances, these updates are published + only if they have changed since the last time they were + published. Configuration updates are only published if + configuration has changed and instrumentation updates are only + published if instrumentation has changed. The exception to this + rule is that after a management client binds to the + qpid.management exchange, all configuration and instrumentation + records are published as though they had changed whether or not + they actually did. + </para> + <programlisting> + Client Broker + | | + | <------------------ Object properties via 'mgmt.*.prop.#' --- | | + | <------------------ Object statistics via 'mgmt.*.stat.#' --- | | + | | | + | | | Publish Interval + | | | + | | | + | | V + | <------------------ Object properties via 'mgmt.*.prop.#' --- | + | <------------------ Object statistics via 'mgmt.*.stat.#' --- | + | | +</programlisting> +<!--h3--></section> + + <section role="h3" id="ManagementDesignnotes-InvokingaMethodonaManagedObject"><title> + Invoking + a Method on a Managed Object + </title> + + <para> + When the management client wishes to invoke a method on a managed + object, it sends a method request message to the qpid.management + exchange. The routing key contains the object class and method + name (refer to Routing Key Structure below). The method request + must have a header entry (reply-to) that contains the name of the + method-reply queue so that the method response can be properly + routed back to the requestor. + </para><para> + The method request contains a sequence number that is copied to + the method reply. This number is opaque to the management agent + and may be used by the management client to correlate the reply + to the request. The asynchronous nature of requests and replies + allows any number of methods to be in-flight at a time. Note that + there is no guarantee that methods will be replied to in the + order in which they were requested. + </para> + <programlisting> + Client Broker + | | + | --- Method Request (to exchange 'qpid.management') ---------> | + | | + | | + | <--------------- Method Reply (via exchange 'amq.direct') --- | + | | +</programlisting> +<!--h3--></section> + + + <section role="h3" id="ManagementDesignnotes-MessagesfortheBasicScenario"><title> + Messages + for the Basic Scenario + </title> + + <para> + The principals in a management exchange are the <emphasis>management + client</emphasis> and the <emphasis>management agent</emphasis>. The management + agent is integrated into the QPID broker and the management + client is a remote entity. A management agent may be managed by + zero or more management clients at any given time. Additionally, + a management client may manage multiple management agents at the + same time. + </para><para> + For authentication and access control, management relies on the + mechanisms supplied by the AMQP protocol. + </para><section role="h4" id="ManagementDesignnotes-BasicOpcodes"><title> + Basic Opcodes + </title> + + <table><title/><tgroup cols="3"> + <tbody> + <row> + <entry> + <emphasis>opcode</emphasis> + </entry> + <entry> + <emphasis>message</emphasis> + </entry> + <entry> + <emphasis>description</emphasis> + </entry> + </row> + <row> + <entry> + 'B' + </entry> + <entry> + Broker Request + </entry> + <entry> + This message contains a broker request, sent from the + management console to the broker to initiate a management + session. + </entry> + </row> + <row> + <entry> + 'b' + </entry> + <entry> + Broker Response + </entry> + <entry> + This message contains a broker response, sent from the + broker in response to a broker request message. + </entry> + </row> + <row> + <entry> + 'z' + </entry> + <entry> + Command Completion + </entry> + <entry> + This message is sent to indicate the completion of a + request. + </entry> + </row> + <row> + <entry> + 'Q' + </entry> + <entry> + Class Query + </entry> + <entry> + Class query messages are used by a management console to + request a list of schema classes that are known by the + management broker. + </entry> + </row> + <row> + <entry> + 'q' + </entry> + <entry> + Class Indication + </entry> + <entry> + Sent by the management broker, a class indication notifies + the peer of the existence of a schema class. + </entry> + </row> + <row> + <entry> + 'S' + </entry> + <entry> + Schema Request + </entry> + <entry> + Schema request messages are used to request the full schema + details for a class. + </entry> + </row> + <row> + <entry> + 's' + </entry> + <entry> + Schema Response + </entry> + <entry> + Schema response message contain a full description of the + schema for a class. + </entry> + </row> + <row> + <entry> + 'h' + </entry> + <entry> + Heartbeat Indication + </entry> + <entry> + This message is published once per publish-interval. It can + be used by a client to positively determine which objects + did not change during the interval (since updates are not + published for objects with no changes). + </entry> + </row> + <row> + <entry> + 'c', 'i', 'g' + </entry> + <entry> + Content Indication + </entry> + <entry> + This message contains a content record. Content records + contain the values of all properties or statistics in an + object. Such records are broadcast on a periodic interval + if 1) a change has been made in the value of one of the + elements, or 2) if a new management client has bound a + queue to the management exchange. + </entry> + </row> + <row> + <entry> + 'G' + </entry> + <entry> + Get Query + </entry> + <entry> + Sent by a management console, a get query requests that the + management broker provide content indications for all + objects that match the query criteria. + </entry> + </row> + <row> + <entry> + 'M' + </entry> + <entry> + Method Request + </entry> + <entry> + This message contains a method request. + </entry> + </row> + <row> + <entry> + 'm' + </entry> + <entry> + Method Response + </entry> + <entry> + This message contains a method result. + </entry> + </row> + </tbody> + </tgroup></table> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-BrokerRequestMessage"><title> + Broker + Request Message + </title> + + <para> + When a management client first establishes contact with the + broker, it sends a Hello message to initiate the exchange. + </para> + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'B' | 0 | + +-----+-----+-----+-----+-----------------------+ +</programlisting> + <para> + The Broker Request message has no payload. + </para> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-BrokerResponseMessage"><title> + Broker + Response Message + </title> + + <para> + When the broker receives a Broker Request message, it responds + with a Broker Response message. This message contains an + identifier unique to the broker. + </para> + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'b' | 0 | + +-----+-----+-----+-----+-----------------------+----------------------------+ + | brokerId (uuid) | + +----------------------------------------------------------------------------+ +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-CommandCompletionMessage"><title> + Command + Completion Message + </title> + + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'z' | seq | + +-----+-----+-----+-----+-----------------------+ + | Completion Code | + +-----------------------+-----------------------------------------+ + | Completion Text | + +-----------------------------------------------------------------+ +</programlisting> +<!--h4--></section> + + + <section role="h4" id="ManagementDesignnotes-ClassQuery"><title> + Class Query + </title> + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'Q' | seq | + +-----+-----+-----+-----+-----------------------+----------+ + | package name (str8) | + +----------------------------------------------------------+ +</programlisting> +<!--h4--></section> + + + <section role="h4" id="ManagementDesignnotes-ClassIndication"><title> + Class + Indication + </title> + + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'q' | seq | + +-----+-----+-----+-----+-----------------------+----------+ + | package name (str8) | + +----------------------------------------------------------+ + | class name (str8) | + +----------------------------------------------------------+ + | schema hash (bin128) | + +----------------------------------------------------------+ +</programlisting> +<!--h4--></section> + + + <section role="h4" id="ManagementDesignnotes-SchemaRequest"><title> + Schema Request + </title> + + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'S' | seq | + +-----+-----+-----+-----+-----------------------+----------+ + | packageName (str8) | + +----------------------------------------------------------+ + | className (str8) | + +----------------------------------------------------------+ + | schema-hash (bin128) | + +----------------------------------------------------------+ +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-SchemaResponse"><title> + Schema + Response + </title> + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 's' | seq | + +-----+-----+-----+-----+-----------------------+----------+ + | packageName (str8) | + +----------------------------------------------------------+ + | className (str8) | + +----------------------------------------------------------+ + | schema-hash (bin128) | + +-----------+-----------+-----------+-----------+----------+ + | propCnt | statCnt | methodCnt | eventCnt | + +-----------+-----------+-----------+-----------+----------------------------+ + | propCnt property records | + +----------------------------------------------------------------------------+ + | statCnt statistic records | + +----------------------------------------------------------------------------+ + | methodCnt method records | + +----------------------------------------------------------------------------+ + | eventCnt event records | + +----------------------------------------------------------------------------+ +</programlisting> + <para> + Each <emphasis>property</emphasis> record is an AMQP map with the following + fields. Optional fields may optionally be omitted from the map. + </para><table><title/><tgroup cols="3"> + <tbody> + <row> + <entry> + <emphasis>field name</emphasis> + </entry> + <entry> + <emphasis>optional</emphasis> + </entry> + <entry> + <emphasis>description</emphasis> + </entry> + </row> + <row> + <entry> + name + </entry> + <entry> + no + </entry> + <entry> + Name of the property + </entry> + </row> + <row> + <entry> + type + </entry> + <entry> + no + </entry> + <entry> + Type code for the property + </entry> + </row> + <row> + <entry> + access + </entry> + <entry> + no + </entry> + <entry> + Access code for the property + </entry> + </row> + <row> + <entry> + index + </entry> + <entry> + no + </entry> + <entry> + 1 = index element, 0 = not an index element + </entry> + </row> + <row> + <entry> + optional + </entry> + <entry> + no + </entry> + <entry> + 1 = optional element (may be not present), 0 = mandatory + (always present) + </entry> + </row> + <row> + <entry> + unit + </entry> + <entry> + yes + </entry> + <entry> + Units for numeric values (i.e. seconds, bytes, etc.) + </entry> + </row> + <row> + <entry> + min + </entry> + <entry> + yes + </entry> + <entry> + Minimum value for numerics + </entry> + </row> + <row> + <entry> + max + </entry> + <entry> + yes + </entry> + <entry> + Maximum value for numerics + </entry> + </row> + <row> + <entry> + maxlen + </entry> + <entry> + yes + </entry> + <entry> + Maximum length for strings + </entry> + </row> + <row> + <entry> + desc + </entry> + <entry> + yes + </entry> + <entry> + Description of the property + </entry> + </row> + </tbody> + </tgroup></table><para> + Each <emphasis>statistic</emphasis> record is an AMQP map with the following + fields: + </para><table><title/><tgroup cols="3"> + <tbody> + <row> + <entry> + <emphasis>field name</emphasis> + </entry> + <entry> + <emphasis>optional</emphasis> + </entry> + <entry> + <emphasis>description</emphasis> + </entry> + </row> + <row> + <entry> + name + </entry> + <entry> + no + </entry> + <entry> + Name of the statistic + </entry> + </row> + <row> + <entry> + type + </entry> + <entry> + no + </entry> + <entry> + Type code for the statistic + </entry> + </row> + <row> + <entry> + unit + </entry> + <entry> + yes + </entry> + <entry> + Units for numeric values (i.e. seconds, bytes, etc.) + </entry> + </row> + <row> + <entry> + desc + </entry> + <entry> + yes + </entry> + <entry> + Description of the statistic + </entry> + </row> + </tbody> + </tgroup></table><para> + <emphasis>method</emphasis> and <emphasis>event</emphasis> records contain a main map that + describes the method or header followed by zero or more maps + describing arguments. The main map contains the following fields: + </para><table><title/><tgroup cols="3"> + <tbody> + <row> + <entry> + <emphasis>field name</emphasis> + </entry> + <entry> + <emphasis>optional</emphasis> + </entry> + <entry> + <emphasis>description</emphasis> + </entry> + </row> + <row> + <entry> + name + </entry> + <entry> + no + </entry> + <entry> + Name of the method or event + </entry> + </row> + <row> + <entry> + argCount + </entry> + <entry> + no + </entry> + <entry> + Number of argument records to follow + </entry> + </row> + <row> + <entry> + desc + </entry> + <entry> + yes + </entry> + <entry> + Description of the method or event + </entry> + </row> + </tbody> + </tgroup></table><para> + Argument maps contain the following fields: + </para><table><title/><tgroup cols="5"> + <tbody> + <row> + <entry> + <emphasis>field name</emphasis> + </entry> + <entry> + <emphasis>method</emphasis> + </entry> + <entry> + <emphasis>event</emphasis> + </entry> + <entry> + <emphasis>optional</emphasis> + </entry> + <entry> + <emphasis>description</emphasis> + </entry> + </row> + <row> + <entry> + name + </entry> + <entry> + yes + </entry> + <entry> + yes + </entry> + <entry> + no + </entry> + <entry> + Argument name + </entry> + </row> + <row> + <entry> + type + </entry> + <entry> + yes + </entry> + <entry> + yes + </entry> + <entry> + no + </entry> + <entry> + Type code for the argument + </entry> + </row> + <row> + <entry> + dir + </entry> + <entry> + yes + </entry> + <entry> + no + </entry> + <entry> + yes + </entry> + <entry> + Direction code for method arguments + </entry> + </row> + <row> + <entry> + unit + </entry> + <entry> + yes + </entry> + <entry> + yes + </entry> + <entry> + yes + </entry> + <entry> + Units for numeric values (i.e. seconds, bytes, etc.) + </entry> + </row> + <row> + <entry> + min + </entry> + <entry> + yes + </entry> + <entry> + no + </entry> + <entry> + yes + </entry> + <entry> + Minimum value for numerics + </entry> + </row> + <row> + <entry> + max + </entry> + <entry> + yes + </entry> + <entry> + no + </entry> + <entry> + yes + </entry> + <entry> + Maximum value for numerics + </entry> + </row> + <row> + <entry> + maxlen + </entry> + <entry> + yes + </entry> + <entry> + no + </entry> + <entry> + yes + </entry> + <entry> + Maximum length for strings + </entry> + </row> + <row> + <entry> + desc + </entry> + <entry> + yes + </entry> + <entry> + yes + </entry> + <entry> + yes + </entry> + <entry> + Description of the argument + </entry> + </row> + <row> + <entry> + default + </entry> + <entry> + yes + </entry> + <entry> + no + </entry> + <entry> + yes + </entry> + <entry> + Default value for the argument + </entry> + </row> + </tbody> + </tgroup></table><para> + <emphasis>type codes</emphasis> are numerics with the following values: + </para><table><title/><tgroup cols="2"> + <tbody> + <row> + <entry> + <emphasis>value</emphasis> + </entry> + <entry> + <emphasis>type</emphasis> + </entry> + </row> + <row> + <entry> + 1 + </entry> + <entry> + uint8 + </entry> + </row> + <row> + <entry> + 2 + </entry> + <entry> + uint16 + </entry> + </row> + <row> + <entry> + 3 + </entry> + <entry> + uint32 + </entry> + </row> + <row> + <entry> + 4 + </entry> + <entry> + uint64 + </entry> + </row> + <row> + <entry> + 6 + </entry> + <entry> + str8 + </entry> + </row> + <row> + <entry> + 7 + </entry> + <entry> + str16 + </entry> + </row> + <row> + <entry> + 8 + </entry> + <entry> + absTime(uint64) + </entry> + </row> + <row> + <entry> + 9 + </entry> + <entry> + deltaTime(uint64) + </entry> + </row> + <row> + <entry> + 10 + </entry> + <entry> + objectReference(uint64) + </entry> + </row> + <row> + <entry> + 11 + </entry> + <entry> + boolean(uint8) + </entry> + </row> + <row> + <entry> + 12 + </entry> + <entry> + float + </entry> + </row> + <row> + <entry> + 13 + </entry> + <entry> + double + </entry> + </row> + <row> + <entry> + 14 + </entry> + <entry> + uuid + </entry> + </row> + <row> + <entry> + 15 + </entry> + <entry> + map + </entry> + </row> + <row> + <entry> + 16 + </entry> + <entry> + int8 + </entry> + </row> + <row> + <entry> + 17 + </entry> + <entry> + int16 + </entry> + </row> + <row> + <entry> + 18 + </entry> + <entry> + int32 + </entry> + </row> + <row> + <entry> + 19 + </entry> + <entry> + int64 + </entry> + </row> + </tbody> + </tgroup></table><para> + <emphasis>access codes</emphasis> are numerics with the following values: + </para><table><title/><tgroup cols="2"> + <tbody> + <row> + <entry> + <emphasis>value</emphasis> + </entry> + <entry> + <emphasis>access</emphasis> + </entry> + </row> + <row> + <entry> + 1 + </entry> + <entry> + Read-Create access + </entry> + </row> + <row> + <entry> + 2 + </entry> + <entry> + Read-Write access + </entry> + </row> + <row> + <entry> + 3 + </entry> + <entry> + Read-Only access + </entry> + </row> + </tbody> + </tgroup></table><para> + <emphasis>direction codes</emphasis> are numerics with the following values: + </para><table><title/><tgroup cols="2"> + <tbody> + <row> + <entry> + <emphasis>value</emphasis> + </entry> + <entry> + <emphasis>direction</emphasis> + </entry> + </row> + <row> + <entry> + 1 + </entry> + <entry> + Input (from client to broker) + </entry> + </row> + <row> + <entry> + 2 + </entry> + <entry> + Output (from broker to client) + </entry> + </row> + <row> + <entry> + 3 + </entry> + <entry> + IO (bidirectional) + </entry> + </row> + </tbody> + </tgroup></table> +<!--h4--></section> + + + <section role="h4" id="ManagementDesignnotes-HeartbeatIndication"><title> + Heartbeat + Indication + </title> + + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'h' | 0 | + +-----+-----+-----+-----+-----------------------+ + | timestamp of current interval (datetime) | + +-----------------------------------------------+ +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-ConfigurationandInstrumentationContentMessages"><title> + Configuration and Instrumentation Content Messages + </title> + + <para> + Content messages are published when changes are made to the + values of properties or statistics or when new management clients + bind a queue to the management exchange. + </para> + <programlisting> + +-----+-----+-----+-------+-----------------------+ + | 'A' | 'M' | '1' |'g/c/i'| seq | + +-----+-----+-----+-------+-----------------------+--------+ + | packageName (str8) | + +----------------------------------------------------------+ + | className (str8) | + +----------------------------------------------------------+ + | class hash (bin128) | + +-----+-----+-----+-----+-----+-----+-----+-----+----------+ + | timestamp of current sample (datetime) | + +-----+-----+-----+-----+-----+-----+-----+-----+ + | time object was created (datetime) | + +-----+-----+-----+-----+-----+-----+-----+-----+ + | time object was deleted (datetime) | + +-----+-----+-----+-----+-----+-----+-----+-----+ + | objectId (uint64) | + +-----+-----+-----+-----+-----+-----+-----+-----+ + | presence bitmasks (0 or more uint8 fields) | + +-----+-----+-----+-----+-----+-----+-----+-----+------------------------+ + | config/inst values (in schema order) | + +------------------------------------------------------------------------+ +</programlisting> + <para> + All timestamps are uint64 values representing nanoseconds since + the epoch (January 1, 1970). The objectId is a uint64 value that + uniquely identifies this object instance. + </para><para> + If any of the properties in the object are defined as optional, + there will be 1 or more "presence bitmask" octets. There are as + many octets as are needed to provide one bit per optional + property. The bits are assigned to the optional properties in + schema order (first octet first, lowest order bit first). + </para><para> + For example: If there are two optional properties in the schema + called "option1" and "option2" (defined in that order), there + will be one presence bitmask octet and the bits will be assigned + as bit 0 controls option1 and bit 1 controls option2. + </para><para> + If the bit for a particular optional property is set (1), the + property will be encoded normally in the "values" portion of the + message. If the bit is clear (0), the property will be omitted + from the list of encoded values and will be considered "NULL" or + "not present". + </para><para> + The element values are encoded by their type into the message in + the order in which they appeared in the schema message. + </para> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-GetQueryMessage"><title> + Get Query + Message + </title> + + <para> + A Get Request may be sent by the management console to cause a + management agent to immediately send content information for + objects of a class. + </para> + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'G' | seq | + +-----+-----+-----+-----+-----------------------+----------+ + | Get request field table | + +----------------------------------------------------------+ +</programlisting> + <para> + The content of a get request is a field table that specifies what + objects are being requested. Most of the fields are optional and + are available for use in more extensive deployments. + </para><table><title/><tgroup cols="4"> + <tbody> + <row> + <entry> + <emphasis>Field Key</emphasis> + </entry> + <entry> + <emphasis>Mandatory</emphasis> + </entry> + <entry> + <emphasis>Type</emphasis> + </entry> + <entry> + <emphasis>Description</emphasis> + </entry> + </row> + <row> + <entry> + "_class" + </entry> + <entry> + yes + </entry> + <entry> + short-string + </entry> + <entry> + The name of the class of objects being requested. + </entry> + </row> + <row> + <entry> + "_package" + </entry> + <entry> + no + </entry> + <entry> + short-string + </entry> + <entry> + The name of the extension package the class belongs to. If + omitted, the package defaults to "qpid" for access to + objects in the connected broker. + </entry> + </row> + <row> + <entry> + "_agent" + </entry> + <entry> + no + </entry> + <entry> + uuid + </entry> + <entry> + The management agent that is the target of the request. If + omitted, agent defaults to the connected broker. + </entry> + </row> + </tbody> + </tgroup></table><para> + When the management agent receives a get request, it sends + content messages describing the requested objects. Once the last + content message is sent, it then sends a Command Completion + message with the same sequence number supplied in the request to + indicate to the requestor that there are no more messages coming. + </para> +<!--h4--></section> + + + <section role="h4" id="ManagementDesignnotes-MethodRequest"><title> + Method Request + </title> + + <para> + Method request messages have the following structure. The + sequence number is opaque to the management agent. It is returned + unchanged in the method reply so the calling client can correctly + associate the reply to the request. The objectId is the unique ID + of the object on which the method is to be executed. + </para> + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'M' | seq | + +-----+-----+-----+-----+-----------------------+ + | objectId (uint64) | + +-----------------------------------------------+ + | methodName (str8) | + +-----------------------------------------------+------------------------+ + | input and bidirectional argument values (in schema order) | + +------------------------------------------------------------------------+ +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-MethodResponse"><title> + Method + Response + </title> + + <para> + Method reply messages have the following structure. The sequence + number is identical to that supplied in the method request. The + status code (and text) indicate whether or not the method was + successful and if not, what the error was. Output and + bidirectional arguments are only included if the status code was + 0 (STATUS_OK). + </para> + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'm' | seq | + +-----+-----+-----+-----+-----------------------+ + | status code | + +-----------------------+----------------------------------+ + | status text (str8) | + +-----------------------+----------------------------------+-------------+ + | output and bidirectional argument values (in schema order) | + +------------------------------------------------------------------------+ +</programlisting> + <para> + <emphasis>status code</emphasis> values are: + </para><table><title/><tgroup cols="2"> + <tbody> + <row> + <entry> + <emphasis>value</emphasis> + </entry> + <entry> + <emphasis>description</emphasis> + </entry> + </row> + <row> + <entry> + 0 + </entry> + <entry> + STATUS_OK - successful completion + </entry> + </row> + <row> + <entry> + 1 + </entry> + <entry> + STATUS_UNKNOWN_OBJECT - objectId not found in the agent + </entry> + </row> + <row> + <entry> + 2 + </entry> + <entry> + STATUS_UNKNOWN_METHOD - method is not known by the object + type + </entry> + </row> + <row> + <entry> + 3 + </entry> + <entry> + STATUS_NOT_IMPLEMENTED - method is not currently + implemented + </entry> + </row> + </tbody> + </tgroup></table> +<!--h4--></section> +<!--h3--></section> + + <section role="h3" id="ManagementDesignnotes-MessagesforExtendedScenario"><title> + Messages + for Extended Scenario + </title> + + <section role="h4" id="ManagementDesignnotes-ExtendedManagementProtocol"><title> + Extended + Management Protocol + </title> + + <para> + Qpid supports management extensions that allow the management + broker to be a central point for the management of multiple + external entities with their own management schemas. + </para> + <programlisting> + Broker Remote Agent + | | + | <----------------------------------------- Attach Request --- | + | --- Attach Response ----------------------------------------> | + | | + | <------------------------------------- Package Indication --- | + | <------------------------------------- Package Indication --- | + | | + | <--------------------------------------- Class Indication --- | + | <--------------------------------------- Class Indication --- | + | <--------------------------------------- Class Indication --- | + | <--------------------------------------- Class Indication --- | + | <--------------------------------------- Class Indication --- | + | | + | --- Schema Request (class key) -----------------------------> | + | <---------------------------------------- Schema Response --- | + | | + | --- Schema Request (class key) -----------------------------> | + | <---------------------------------------- Schema Response --- | + | | + | | +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-ExtendedOpcodes"><title> + Extended + Opcodes + </title> + + <table><title/><tgroup cols="3"> + <tbody> + <row> + <entry> + <emphasis>opcode</emphasis> + </entry> + <entry> + <emphasis>message</emphasis> + </entry> + <entry> + <emphasis>description</emphasis> + </entry> + </row> + <row> + <entry> + 'P' + </entry> + <entry> + Package Query + </entry> + <entry> + This message contains a schema package query request, + requesting that the broker dump the list of known packages + </entry> + </row> + <row> + <entry> + 'p' + </entry> + <entry> + Package Indication + </entry> + <entry> + This message contains a schema package indication, + identifying a package known by the broker + </entry> + </row> + <row> + <entry> + 'A' + </entry> + <entry> + Agent Attach Request + </entry> + <entry> + This message is sent by a remote agent when it wishes to + attach to a management broker + </entry> + </row> + <row> + <entry> + 'a' + </entry> + <entry> + Agent Attach Response + </entry> + <entry> + The management broker sends this response if an attaching + remote agent is permitted to join + </entry> + </row> + <row> + <entry> + 'x' + </entry> + <entry> + Console Added Indication + </entry> + <entry> + This message is sent to all remote agents by the management + broker when a new console binds to the management exchange + </entry> + </row> + </tbody> + </tgroup></table> +<!--h4--></section> + + + <section role="h4" id="ManagementDesignnotes-PackageQuery"><title> + Package Query + </title> + + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'P' | seq | + +-----+-----+-----+-----+-----------------------+ +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-PackageIndication"><title> + Package + Indication + </title> + + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'p' | seq | + +-----+-----+-----+-----+-----------------------+----------+ + | package name (str8) | + +----------------------------------------------------------+ +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-AttachRequest"><title> + Attach Request + </title> + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'A' | seq | + +-----+-----+-----+-----+-----------------------+----------+ + | label (str8) | + +-----------------------+----------------------------------+ + | system-id (uuid) | + +-----------------------+----------------------------------+ + | requested objId bank | + +-----------------------+ +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-AttachResponse-28success-29"><title> + Attach + Response (success) + </title> + + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'a' | seq | + +-----+-----+-----+-----+-----------------------+ + | assigned broker bank | + +-----------------------+ + | assigned objId bank | + +-----------------------+ +</programlisting> +<!--h4--></section> + + <section role="h4" id="ManagementDesignnotes-ConsoleAddedIndication"><title> + Console Added + Indication + </title> + + + <programlisting> + +-----+-----+-----+-----+-----------------------+ + | 'A' | 'M' | '1' | 'x' | seq | + +-----+-----+-----+-----+-----------------------+ +</programlisting> + + + + <!--h4--></section> + <!--h3--></section> + <!--h2--></section> + + +</section> + diff --git a/qpid/doc/book/src/old/NET-User-Guide.xml b/qpid/doc/book/src/old/NET-User-Guide.xml new file mode 100644 index 0000000000..7bfa20b8c8 --- /dev/null +++ b/qpid/doc/book/src/old/NET-User-Guide.xml @@ -0,0 +1,1383 @@ +<?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> + <title> + Apache Qpid: Open Source AMQP Messaging - .NET User Guide + </title> + <section role="h1" id="NETUserGuide-Tutorial"> + <title> + Tutorial + </title> + <para> + This tutorial consists of a series of examples using the three + most commonly used exchange types - Direct, Fanout and + Topic + exchanges. These examples show how to write applications that use + the most common messaging paradigms. + </para> + <itemizedlist> + <listitem> + <para>direct</para> + <para>In the direct examples, a message producer writes to the direct + exchange, specifying a routing key. A message consumer reads + messages from a named queue. This illustrates clean separation + of concerns - message producers need to know only the exchange + and the routing key, message consumers need to know only which + queue to use on the broker. + </para> + </listitem> + <listitem> + <para>fanout</para> + <para>The fanout examples use a fanout exchange and do not use + routing keys. Each binding specifies that all messages for a + given exchange should be delivered to a given queue. + </para> + </listitem> + <listitem> + <para>pub-sub</para> + <para>In the publish/subscribe examples, a publisher + application writes messages to an exchange, specifying a + multi-part key. A subscriber application subscribes to + messages that match the relevant parts of these keys, using a + private queue for each subscription. + </para> + </listitem> + <listitem> + <para>request-response</para> + <para>In the request/response examples, a simple service accepts + requests from clients and sends responses back to them. Clients + create their own private queues and corresponding routing keys. + When a client sends a request to the server, it specifies its + own routing key in the reply-to field of the request. The + server uses the client's reply-to field as the routing key for + the response. + </para> + </listitem> + </itemizedlist> + <section role="h2" id="NETUserGuide-RunningtheExamples"> + <title> + Running the + Examples + </title> + <para> + Before running the examples, you need to unzip the file + Qpid.NET-net-2.0-M4.zip, the following tree is created: + </para> + + + <programlisting> +<home> + |-qpid + |-lib (contains the required dlls) + |-examples + |- direct + | |-example-direct-Listener.exe + | |-example-direct-Producer.exe + |- fanout + | |-example-fanout-Listener.exe + | |-example-fanout-Producer.exe + |- pub-sub + | |-example-pub-sub-Listener.exe + | |-example-pub-sub-Publisher.exe + |- request-response + |-example-request-response-Client.exe + |-example-request-response-Server.exe + </programlisting> + + + <para> + Make sure your PATH contains the directory + <home>/qpid/lib + The examples can be run by executing the provided exe files: + </para> + + + <programlisting> +$ cd <home>/qpid/examples/examplefolder +$ example-...-.exe [hostname] [portnumber] + </programlisting> + + + <para> + where [hostname] is the qpid broker host name + (default is localhost) and [portnumber] is the port number on which the + qpid broker is accepting connection (default is 5672). + </para> + <!--h2--> + </section> + + <section role="h2" id="NETUserGuide-CreatingandClosingSessions"> + <title> + Creating + and Closing Sessions + </title> + + <para> + All of the examples have been written using the Apache Qpid .NEt + 0.10 API. The examples use the same skeleton code to initialize + the program, create a session, and clean up before exiting: + </para> + + + <programlisting> +using System; +using System.IO; +using System.Text; +using System.Threading; +using org.apache.qpid.client; +using org.apache.qpid.transport; + +... + + private static void Main(string[] args) + { + string host = args.Length > 0 ? args[0] : "localhost"; + int port = args.Length > 1 ? Convert.ToInt32(args[1]) : 5672; + Client connection = new Client(); + try + { + connection.connect(host, port, "test", "guest", "guest"); + ClientSession session = connection.createSession(50000); + + //--------- Main body of program -------------------------------------------- + + connection.close(); + } + catch (Exception e) + { + Console.WriteLine("Error: \n" + e.StackTrace); + } + } +... + </programlisting> + <!--h2--> + </section> + + <section role="h2" id="NETUserGuide-WritingDirectApplications"> + <title> + Writing + Direct Applications + </title> + + <para> + This section describes two programs that implement direct + messaging using a Direct exchange: + • org.apache.qpid.example.direct.Producer (from + example-direct-producer) publishes messages to the amq.direct + exchange, using the routing key routing_key. + •org.apache.qpid.example.direct.Listener (from + example-direct-Listener) uses a message listener to receive + messages from the queue named message_queue. + </para> + <section role="h3" id="NETUserGuide-RunningtheDirectExamples"> + <title> + Running the + Direct Examples + </title> + <para> + 1) Make sure your PATH contains the directory + <home>/qpid/lib + </para> + <para> + 2) Make sure that a qpid broker is running: + </para> + + + <programlisting> +$ ps -eaf | grep qpidd + </programlisting> + + + <para> + If a broker is running, you should see the qpidd process in the + output of the above + command. + </para> + <para> + 3) Read the messages from the message queue using direct + listener, as follows: + </para> + + + <programlisting> +$ cd <home>/qpid/examples/direct + </programlisting> + + + <para> + With cygwin: + </para> + + + <programlisting> +$ ./example-direct-Listener.exe [hostname] [portnumber] + </programlisting> + + + <para> + or with mono: + </para> + + + <programlisting> +$ mono ./example-direct-Listener.exe [hostname] [portnumber] + </programlisting> + + + <para> + This program is waiting for messages to be published, see next + step: + </para> + <para> + 4) Publish a series of messages to the amq.direct exchange by + running direct producer, as follows: + </para> + + + <programlisting> +$ cd <home>/qpid/examples/direct + </programlisting> + + + <para> + With cygwin: + </para> + + + <programlisting> +$ ./example-direct-Producer.exe [hostname] [portnumber] + </programlisting> + + + <para> + or with mono: + </para> + + + <programlisting> +$ mono ./example-direct-Producer.exe [hostname] [portnumber] + </programlisting> + + + <para> + This program has no output; the messages are routed to the + message queue, as instructed by the binding. + </para> + <para> + 5) Go to the windows where you are running your listener. You + should see the following output: + </para> + + + <programlisting> +Message: Message 0 +Message: Message 1 +Message: Message 2 +Message: Message 3 +Message: Message 4 +Message: Message 5 +Message: Message 6 +Message: Message 7 +Message: Message 8 +Message: Message 9 +Message: That's all, folks! + </programlisting> + + + <para> + Now we will examine the code for each of these programs. In each + section, we will discuss only + the code that must be added to the skeleton shown in Section + "Creating and Closing Sessions". + </para> + <!--h3--> + </section> + + <section role="h3" id="NETUserGuide-ReadingMessagesfromtheQueue"> + <title> + Reading + Messages from the Queue + </title> + + <para> + The program , listener.cs, is a message listener that receives + messages from a queue. + </para> + <para> + First it creates a queue named message_queue, then binds it to + the amq.direct exchange using the binding key routing_key. + </para> + + + <programlisting> +//--------- Main body of program -------------------------------------------- +// Create a queue named "message_queue", and route all messages whose +// routing key is "routing_key" to this newly created queue. +session.queueDeclare("message_queue"); +session.exchangeBind("message_queue", "amq.direct", "routing_key"); + </programlisting> + + + <para> + The queue created by this program continues to exist after the + program exits, and any message whose routing key matches the key + specified in the binding will be routed to the corresponding + queue by the broker. Note that the queue could have been be + deleted using the following code: + </para> + + + <programlisting> +session.queueDelete("message_queue"); + </programlisting> + + + <para> + To create a message listener, create a class derived from + IMessageListener, and override the messageTransfer method, + providing the code that should be executed when a message is + received. + </para> + + + <programlisting> +public class MessageListener : IMessageListener +{ + ...... + public void messageTransfer(IMessage m) + { + ..... +} + </programlisting> + + + <para> + The main body of the program creates a listener for the + subscription; attaches the listener to a message queue; and + subscribe to the queue to receive messages from the queue. + </para> + + + <programlisting> +lock (session) +{ + // Create a listener and subscribe it to the queue named "message_queue" + IMessageListener listener = new MessageListener(session); + session.attachMessageListener(listener, "message_queue"); + session.messageSubscribe("message_queue"); + // Receive messages until all messages are received + Monitor.Wait(session); +} + </programlisting> + + + <para> + The MessageListener's messageTransfer() function is called + whenever a message is received. In this example the message is + printed and tested to see if it is the final message. Once the + final message is received, the messages are acknowledged. + </para> + + + <programlisting> +BinaryReader reader = new BinaryReader(m.Body, Encoding.UTF8); +byte[] body = new byte[m.Body.Length - m.Body.Position]; +reader.Read(body, 0, body.Length); +ASCIIEncoding enc = new ASCIIEncoding(); +string message = enc.GetString(body); + Console.WriteLine("Message: " + message); +// Add this message to the list of message to be acknowledged +_range.add(m.Id); +if( message.Equals("That's all, folks!") ) +{ + // Acknowledge all the received messages + _session.messageAccept(_range); + lock(_session) + { + Monitor.Pulse(_session); + } +} + </programlisting> + <!--h3--> + </section> + + <section role="h3" id="NETUserGuide-PublishingMessagestoaDirectExchange"> + <title> + Publishing + Messages to a Direct Exchange + </title> + <para> + The second program in the direct example, Producer.cs, publishes + messages to the amq.direct exchange using the routing key + routing_key. + </para> + <para> + First, create a message and set a routing key. The same routing + key will be used for each message we send, so you only need to + set this property once. + </para> + + + <programlisting> +IMessage message = new Message(); +// The routing key is a message property. We will use the same +// routing key for each message, so we'll set this property +// just once. (In most simple cases, there is no need to set +// other message properties.) +message.DeliveryProperties.setRoutingKey("routing_key"); + </programlisting> + + + <para> + Now send some messages: + </para> + + + <programlisting> +// Asynchronous transfer sends messages as quickly as +// possible without waiting for confirmation. +for (int i = 0; i < 10; i++) +{ + message.clearData(); + message.appendData(Encoding.UTF8.GetBytes("Message " + i)); + session.messageTransfer("amq.direct", message); +} + </programlisting> + + + <para> + Send a final synchronous message to indicate termination: + </para> + + + <programlisting> +// And send a syncrhonous final message to indicate termination. +message.clearData(); +message.appendData(Encoding.UTF8.GetBytes("That's all, folks!")); +session.messageTransfer("amq.direct", "routing_key", message); +session.sync(); + </programlisting> + <!--h3--> + </section> + + <!--h2--> + </section> + + + <section role="h2" id="NETUserGuide-WritingFanoutApplications"> + <title> + Writing + Fanout Applications + </title> + + <para> + This section describes two programs that illustrate the use of a + Fanout exchange. + </para> + <itemizedlist> + <listitem> + <para>Listener.cs makes a unique queue private for each instance of + the listener, and binds that queue to the fanout exchange. All + messages sent to the fanout exchange are delivered to each + listener's queue. + </para> + </listitem> + <listitem> + <para>Producer.cs publishes messages to the fanout exchange. It + does not use a routing key, which is not needed by the fanout + exchange. + </para> + </listitem> + </itemizedlist> + <section role="h3" id="NETUserGuide-RunningtheFanoutExamples"> + <title> + Running the + Fanout Examples + </title> + + <para> + 1) Make sure your PATH contains the directory + <home>/qpid/lib + </para> + <para> + 2) Make sure that a qpid broker is running: + </para> + + + <programlisting> +$ ps -eaf | grep qpidd + </programlisting> + + + <para> + If a broker is running, you should see the qpidd process in the + output of the above + command. + </para> + <para> + 3) In separate windows, start one or more fanout listeners as + follows: + </para> + + + <programlisting> +$ cd <home>/qpid/examples/direct + </programlisting> + + + <para> + With cygwin: + </para> + + + <programlisting> +$ ./example-fanout-Listener.exe [hostname] [portnumber] + </programlisting> + + + <para> + or with mono: + </para> + + + <programlisting> +$ mono ./example-fanout-Listener.exe [hostname] [portnumber] + </programlisting> + + + <para> + The listener creates a private queue, binds it to the amq.fanout + exchange, and waits for messages to arrive on the queue. When the + listener starts, you will see the following message: + </para> + + + <programlisting> +Listening + </programlisting> + + + <para> + This program is waiting for messages to be published, see next + step: + </para> + <para> + 4) In a separate window, publish a series of messages to the + amq.fanout exchange by running fanout producer, as follows: + </para> + + + <programlisting> +$ cd <home>/qpid/examples/direct + </programlisting> + + + <para> + With cygwin: + </para> + + + <programlisting> +$ ./example-fanout-Producer.exe [hostname] [portnumber] + </programlisting> + + + <para> + or with mono: + </para> + + + <programlisting> +$ mono ./example-fanout-Producer.exe [hostname] [portnumber] + </programlisting> + + + <para> + This program has no output; the messages are routed to the + message queue, as prescribed by the binding. + </para> + <para> + 5) Go to the windows where you are running listeners. You should + see the following output for each listener: + </para> + + + <programlisting> +Message: Message 0 +Message: Message 1 +Message: Message 2 +Message: Message 3 +Message: Message 4 +Message: Message 5 +Message: Message 6 +Message: Message 7 +Message: Message 8 +Message: Message 9 +Message: That's all, folks! + </programlisting> + + + <para> + Now we will examine the code for each of these programs. In each + section, we will discuss only + the code that must be added to the skeleton shown in Section + "Creating and Closing Sessions". + </para> + + <!--h3--> + </section> + + <!--h2--> + </section> + + <section role="h2" id="NETUserGuide-ConsumingfromaFanoutExchange"> + <title> + Consuming from a + Fanout Exchange + </title> + + <para> + The first program in the fanout example, Listener.cs, creates a + private queue, binds it to the amq.fanout exchange, and waits for + messages to arrive on the queue, printing them out as they + arrive. It uses a Listener that is identical to the one used in + the direct example: + </para> + + + <programlisting> + public class MessageListener : IMessageListener + { + private readonly ClientSession _session; + private readonly RangeSet _range = new RangeSet(); + public MessageListener(ClientSession session) + { + _session = session; + } + + public void messageTransfer(IMessage m) + { + BinaryReader reader = new BinaryReader(m.Body, Encoding.UTF8); + byte[] body = new byte[m.Body.Length - m.Body.Position]; + reader.Read(body, 0, body.Length); + ASCIIEncoding enc = new ASCIIEncoding(); + string message = enc.GetString(body); + Console.WriteLine("Message: " + message); + // Add this message to the list of message to be acknowledged + _range.add(m.Id); + if (message.Equals("That's all, folks!")) + { + // Acknowledge all the received messages + _session.messageAccept(_range); + lock (_session) + { + Monitor.Pulse(_session); + } + } + } + } + </programlisting> + + + <para> + The listener creates a private queue to receive its messages and + binds it to the fanout exchange: + </para> + + + <programlisting> +string myQueue = session.Name; +session.queueDeclare(myQueue, Option.EXCLUSIVE, Option.AUTO_DELETE); +session.exchangeBind(myQueue, "amq.fanout", "my-key"); + </programlisting> + + + <para> + Now we create a listener and subscribe it to the queue: + </para> + + + <programlisting> +lock (session) +{ + Console.WriteLine("Listening"); + // Create a listener and subscribe it to my queue. + IMessageListener listener = new MessageListener(session); + session.attachMessageListener(listener, myQueue); + session.messageSubscribe(myQueue); + // Receive messages until all messages are received + Monitor.Wait(session); +} + </programlisting> + + + <section role="h3" id="NETUserGuide-PublishingMessagestotheFanoutExchange"> + <title> + Publishing + Messages to the Fanout Exchange + </title> + + <para> + The second program in this example, Producer.cs, writes messages + to the fanout queue. + </para> + + + <programlisting> +// Unlike topic exchanges and direct exchanges, a fanout +// exchange need not set a routing key. +IMessage message = new Message(); +// Asynchronous transfer sends messages as quickly as +// possible without waiting for confirmation. +for (int i = 0; i < 10; i++) +{ + message.clearData(); + message.appendData(Encoding.UTF8.GetBytes("Message " + i)); + session.messageTransfer("amq.fanout", message); +} + +// And send a syncrhonous final message to indicate termination. +message.clearData(); +message.appendData(Encoding.UTF8.GetBytes("That's all, folks!")); +session.messageTransfer("amq.fanout", message); +session.sync(); + </programlisting> + + <!--h3--> + </section> + + <!--h2--> + </section> + + <section role="h2" id="NETUserGuide-WritingPublish-2FSubscribeApplications"> + <title> + Writing + Publish/Subscribe Applications + </title> + + <para> + This section describes two programs that implement + Publish/Subscribe messaging using a topic exchange. + </para> + <para> + • Publisher.cS sends messages to the amq.topic exchange, + using the multipart routing keys usa.news, usa.weather, + europe.news, and europe.weather. + • Listener.cs creates private queues for news, weather, + usa, and europe, binding them to the amq.topic exchange using + bindings that match the corresponding parts of the multipart + routing keys. + </para> + <para> + In this example, the publisher creates messages for topics like + news, weather, and sports that happen in regions like Europe, + Asia, or the United States. A given consumer may be interested in + all weather messages, regardless of region, or it may be + interested in news and weather for the United States, but + uninterested in items for other regions. In this example, each + consumer sets up its own private queues, which receive precisely + the messages that particular consumer is interested in. + </para> + <section role="h3" id="NETUserGuide-RunningthePublishSubscribeExamples"> + <title> + Running + the Publish-Subscribe Examples + </title> + <para> + 1) Make sure your PATH contains the directory + <home>/qpid/lib + </para> + <para> + 2) Make sure that a qpid broker is running: + </para> + + + <programlisting> +$ ps -eaf | grep qpidd + </programlisting> + + + <para> + If a broker is running, you should see the qpidd process in the + output of the above + command. + </para> + <para> + 3) In separate windows, start one or more topic subscribers as + follows: + </para> + + + <programlisting> +$ cd <home>/qpid/examples/direct + </programlisting> + + + <para> + With cygwin: + </para> + + + <programlisting> +$ ./example-pub-sub--Listener.exe [hostname] [portnumber] + </programlisting> + + + <para> + or with mono: + </para> + + + <programlisting> +$ mono ./example-pub-sub-Listener.exe [hostname] [portnumber] + </programlisting> + + + <para> + You will see output similar to this: + </para> + + + <programlisting> +Listening for messages ... +Declaring queue: usa +Declaring queue: europe +Declaring queue: news +Declaring queue: weather + </programlisting> + + + <para> + Each topic consumer creates a set of private queues, and binds + each queue to the amq.topic exchange together with a binding that + indicates which messages should be routed to the queue. + </para> + <para> + 4) In another window, start the topic publisher, which publishes + messages to the amq.topic exchange, as follows: + </para> + + + <programlisting> +$ cd <home>/qpid/examples/direct + </programlisting> + + + <para> + With cygwin: + </para> + + + <programlisting> +$ ./example-pub-sub-Producer.exe [hostname] [portnumber] + </programlisting> + + + <para> + or with mono: + </para> + + + <programlisting> +$ mono ./example-pub-sub-Producer.exe [hostname] [portnumber] + </programlisting> + + + <para> + This program has no output; the messages are routed to the + message queues for each topic_consumer as specified by the + bindings the consumer created. + </para> + <para> + 5) Go back to the window for each topic consumer. You should see + output like this: + </para> + + + <programlisting> +Message: Message 0 from usa +Message: Message 0 from news +Message: Message 0 from weather +Message: Message 1 from usa +Message: Message 1 from news +Message: Message 2 from usa +Message: Message 2 from news +Message: Message 3 from usa +Message: Message 3 from news +Message: Message 4 from usa +Message: Message 4 from news +Message: Message 5 from usa +Message: Message 5 from news +Message: Message 6 from usa +Message: Message 6 from news +Message: Message 7 from usa +Message: Message 7 from news +Message: Message 8 from usa +Message: Message 8 from news +Message: Message 9 from usa +.... +Message: That's all, folks! from weather +Shutting down listener for control +Message: That's all, folks! from europe +Shutting down listener for control + </programlisting> + + + <para> + Now we will examine the code for each of these programs. In each + section, we will discuss only + the code that must be added to the skeleton shown in Section + "Creating and Closing Sessions". + </para> + <!--h3--> + </section> + + + <section role="h3" id="NETUserGuide-PublishingMessagestoaTopicExchange"> + <title> + Publishing + Messages to a Topic Exchange + </title> + + <para> + The first program in the publish/subscribe example, Publisher.cs, + defines two new functions: one that publishes messages to the + topic exchange, and one that indicates that no more messages are + coming. + </para> + <para> + The publishMessages function publishes a series of five messages + using the specified routing key. + </para> + + + <programlisting> +private static void publishMessages(ClientSession session, string routing_key) +{ + IMessage message = new Message(); + // Asynchronous transfer sends messages as quickly as + // possible without waiting for confirmation. + for (int i = 0; i < 10; i++) + { + message.clearData(); + message.appendData(Encoding.UTF8.GetBytes("Message " + i)); + session.messageTransfer("amq.topic", routing_key, message); + } +} + </programlisting> + + + <para> + The noMoreMessages function signals the end of messages using the + control routing key, which is reserved for control messages. + </para> + + + <programlisting> +private static void noMoreMessages(ClientSession session) +{ + IMessage message = new Message(); + // And send a syncrhonous final message to indicate termination. + message.clearData(); + message.appendData(Encoding.UTF8.GetBytes("That's all, folks!")); + session.messageTransfer("amq.topic", "control", message); + session.sync(); +} + </programlisting> + + + <para> + In the main body of the program, messages are published using + four different routing keys, and then the end of messages is + indicated by a message sent to a separate routing key. + </para> + + + <programlisting> +publishMessages(session, "usa.news"); +publishMessages(session, "usa.weather"); +publishMessages(session, "europe.news"); +publishMessages(session, "europe.weather"); + +noMoreMessages(session); + </programlisting> + <!--h3--> + </section> + + <section role="h3" id="NETUserGuide-ReadingMessagesfromtheQueue2"> + <title> + Reading + Messages from the Queue + </title> + + <para> + The second program in the publish/subscribe example, Listener.cs, + creates a local private queue, with a unique name, for each of + the four binding keys it specifies: usa.#, europe.#, #.news, and + #.weather, and creates a listener. + </para> + + + <programlisting> +Console.WriteLine("Listening for messages ..."); +// Create a listener +prepareQueue("usa", "usa.#", session); +prepareQueue("europe", "europe.#", session); +prepareQueue("news", "#.news", session); +prepareQueue("weather", "#.weather", session); + </programlisting> + + + <para> + The prepareQueue() method creates a queue using a queue name and + a routing key supplied as arguments it then attaches a listener + with the session for the created queue and subscribe for this + receiving messages from the queue: + </para> + + + <programlisting> +// Create a unique queue name for this consumer by concatenating +// the queue name parameter with the Session ID. +Console.WriteLine("Declaring queue: " + queue); +session.queueDeclare(queue, Option.EXCLUSIVE, Option.AUTO_DELETE); + +// Route messages to the new queue if they match the routing key. +// Also route any messages to with the "control" routing key to +// this queue so we know when it's time to stop. A publisher sends +// a message with the content "That's all, Folks!", using the +// "control" routing key, when it is finished. + +session.exchangeBind(queue, "amq.topic", routing_key); +session.exchangeBind(queue, "amq.topic", "control"); + +// subscribe the listener to the queue +IMessageListener listener = new MessageListener(session); +session.attachMessageListener(listener, queue); +session.messageSubscribe(queue); + </programlisting> + <!--h3--> + </section> + <!--h2--> + </section> + + <section role="h2" id="NETUserGuide-WritingRequest-2FResponseApplications"> + <title> + Writing + Request/Response Applications + </title> + + <para> + In the request/response examples, we write a server that accepts + strings from clients and converts them to upper case, sending the + result back to the requesting client. This example consists of + two programs. + </para> + <itemizedlist> + <listitem> + <para>Client.cs is a client application that sends messages to the + server. + • Server.cs is a service that accepts messages, converts + their content to upper case, and sends the result to the + amq.direct exchange, using the request's reply-to property as + the routing key for the response. + </para> + </listitem> + </itemizedlist> + <section role="h3" id="NETUserGuide-RunningtheRequest-2FResponseExamples"> + <title> + Running + the Request/Response Examples + </title> + <para> + 1) Make sure your PATH contains the directory + <home>/qpid/lib + </para> + <para> + 2) Make sure that a qpid broker is running: + </para> + + + <programlisting> +$ ps -eaf | grep qpidd + </programlisting> + + + <para> + If a broker is running, you should see the qpidd process in the + output of the above + command. + </para> + <para> + 3) Run the server. + </para> + <para> + $ cd <home>/qpid/examples/direct + </para> + + + <programlisting> + With cygwin: + </programlisting> + + + <para> + $ ./example-request-response-Server.exe [hostname] [portnumber] + </para> + + + <programlisting> + or with mono: + </programlisting> + + + <para> + $ mono ./example-request-response-Server.exe [hostname] [portnumber] + </para> + + + <programlisting> + You will see output similar to this: + </programlisting> + + + <para> + Waiting for requests + </para> + + + <programlisting> +4) In a separate window, start a client: + +$ cd <home>/qpid/examples/direct + </programlisting> + + + <para> + With cygwin: + </para> + + + <programlisting> +$ ./example-request-response-Client.exe [hostname] [portnumber] + </programlisting> + + + <para> + or with mono: + </para> + + + <programlisting> +$ mono ./example-request-response-Client.exe [hostname] [portnumber] + </programlisting> + + + <para> + You will see output similar to this: + </para> + + + <programlisting> +Activating response queue listener for: clientSystem.Byte[] +Waiting for all responses to arrive ... +Response: TWAS BRILLIG, AND THE SLITHY TOVES +Response: DID GIRE AND GYMBLE IN THE WABE. +Response: ALL MIMSY WERE THE BOROGROVES, +Response: AND THE MOME RATHS OUTGRABE. +Shutting down listener for clientSystem.Byte[] +Response: THAT'S ALL, FOLKS! + </programlisting> + + + <para> + 4) Go back to the server window, the output should be similar to + this: + </para> + + + <programlisting> +Waiting for requests +Request: Twas brillig, and the slithy toves +Request: Did gire and gymble in the wabe. +Request: All mimsy were the borogroves, +Request: And the mome raths outgrabe. +Request: That's all, folks! + </programlisting> + + + <para> + Now we will examine the code for each of these programs. In each + section, we will discuss only the code that must be added to the + skeleton shown in Section "Creating and Closing Sessions". + </para> + <!--h3--> + </section> + + + <section role="h3" id="NETUserGuide-TheClientApplication"> + <title> + The Client + Application + </title> + + <para> + The first program in the request-response example, Client.cs, + sets up a private response queue to receive responses from the + server, then sends messages the server, listening to the response + queue for the server's responses. + </para> + + + <programlisting> +string response_queue = "client" + session.getName(); +// Use the name of the response queue as the routing key +session.queueDeclare(response_queue); +session.exchangeBind(response_queue, "amq.direct", response_queue); + +// Create a listener for the response queue and listen for response messages. +Console.WriteLine("Activating response queue listener for: " + response_queue); +IMessageListener listener = new ClientMessageListener(session); +session.attachMessageListener(listener, response_queue); +session.messageSubscribe(response_queue); + </programlisting> + + + <para> + Set some properties that will be used for all requests. The + routing key for a request is request. + The reply-to property is set to the routing key for the client's + private queue. + </para> + + + <programlisting> +IMessage request = new Message(); +request.DeliveryProperties.setRoutingKey("request"); +request.MessageProperties.setReplyTo(new ReplyTo("amq.direct", response_queue)); + </programlisting> + + + <para> + Now send some requests... + </para> + + + <programlisting> +string[] strs = { + "Twas brillig, and the slithy toves", + "Did gire and gymble in the wabe.", + "All mimsy were the borogroves,", + "And the mome raths outgrabe.", + "That's all, folks!" + }; +foreach (string s in strs) +{ + request.clearData(); + request.appendData(Encoding.UTF8.GetBytes(s)); + session.messageTransfer("amq.direct", request); +} + </programlisting> + + + <para> + And wait for responses to arrive: + </para> + + + <programlisting> +Console.WriteLine("Waiting for all responses to arrive ..."); +Monitor.Wait(session); + </programlisting> + <!--h3--> + </section> + + <section role="h3" id="NETUserGuide-TheServerApplication"> + <title> + The Server + Application + </title> + + <para> + The second program in the request-response example, Server.cs, + uses the reply-to property as the routing key for responses. + </para> + <para> + The main body of Server.cs creates an exclusive queue for + requests, then waits for messages to arrive. + </para> + + + <programlisting> +const string request_queue = "request"; +// Use the name of the request queue as the routing key +session.queueDeclare(request_queue); +session.exchangeBind(request_queue, "amq.direct", request_queue); + +lock (session) +{ + // Create a listener and subscribe it to the request_queue + IMessageListener listener = new MessageListener(session); + session.attachMessageListener(listener, request_queue); + session.messageSubscribe(request_queue); + // Receive messages until all messages are received + Console.WriteLine("Waiting for requests"); + Monitor.Wait(session); +} + </programlisting> + + + <para> + The listener's messageTransfer() method converts the request's + content to upper case, then sends a response to the broker, using + the request's reply-to property as the routing key for the + response. + </para> + + + <programlisting> +BinaryReader reader = new BinaryReader(request.Body, Encoding.UTF8); +byte[] body = new byte[request.Body.Length - request.Body.Position]; +reader.Read(body, 0, body.Length); +ASCIIEncoding enc = new ASCIIEncoding(); +string message = enc.GetString(body); +Console.WriteLine("Request: " + message); + +// Transform message content to upper case +string responseBody = message.ToUpper(); + +// Send it back to the user +response.clearData(); +response.appendData(Encoding.UTF8.GetBytes(responseBody)); +_session.messageTransfer("amq.direct", routingKey, response); + </programlisting> + + <!--h3--> + </section> + <!--h2--> + </section> + <!--h1--> + </section> + + + </section> diff --git a/qpid/doc/book/src/old/PythonBrokerTest.xml b/qpid/doc/book/src/old/PythonBrokerTest.xml new file mode 100644 index 0000000000..ae7edade40 --- /dev/null +++ b/qpid/doc/book/src/old/PythonBrokerTest.xml @@ -0,0 +1,98 @@ +<?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> + <title> + PythonBrokerTest + </title> + <section role="h2" id="PythonBrokerTest-PythonBrokerSystemTestSuite"> + <title> + Python Broker System Test Suite + </title> + <para> + This is a suite of python client tests that exercise and verify + broker functionality. Python allows us to rapidly develop client + test scenarios and provides a 'neutral' set of tests that can run + against any AMQP-compliant broker. + </para> + <para> + The python/tests directory contains a collection of python + modules, each containing several unittest classes, each + containing a set of test methods that represent some test + scenario. Test classes inherit qpid.TestBas from + qpid/testlib.py, it inherits unittest.TestCase + but adds some qpid-specific setUp/tearDown and + convenience functions. + </para> + <para> + TODO: get pydoc generated up to qpid wiki or website + automatically? + </para> + <section role="h3" id="PythonBrokerTest-Runningthetests"> + <title> + Running the tests + </title> + <para> + Simplest way to run the tests: + </para> + <itemizedlist> + <listitem> + <para>Run a broker on the default port + </para> + </listitem> + <listitem> + <para> + ./run_tests + </para> + </listitem> + </itemizedlist> + <para> + For additional options: ./run_tests --help + </para> + <!--h3--> + </section> + + <section role="h3" id="PythonBrokerTest-Expectedfailures"> + <title> + Expected failures + </title> + <para> + Until we complete functionality, tests may fail because the + tested functionality is missing in the broker. To skip + expected failures in the C++ or Java brokers: + </para> + <programlisting> +./run_tests -I cpp_failing.txt +./run_tests -I java_failing.txt + </programlisting> + <para> + If you fix a failure, please remove it from the corresponding + list. + </para> + + <!--h3--> + </section> + + <!--h2--> + </section> + +</section> diff --git a/qpid/doc/book/src/old/QMan-Qpid-Management-bridge.xml b/qpid/doc/book/src/old/QMan-Qpid-Management-bridge.xml new file mode 100644 index 0000000000..f2c366dcbb --- /dev/null +++ b/qpid/doc/book/src/old/QMan-Qpid-Management-bridge.xml @@ -0,0 +1,166 @@ +<?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><title> + QMan - Qpid Management bridge + </title><section role="h1" id="QMan-QpidManagementbridge-QMan-3AQpidManagementBridge"><title> + QMan + : Qpid Management Bridge + </title> + <para> + QMan is a management bridge for Qpid. It allows external clients + to manage and monitor one or more Qpid brokers. + </para> + <para> + Please note: All WS-DM related concerns have to be considered + part of M5 release. + </para><para> + QMan exposes the broker management interfaces using Java + Management Extensions (JMX) and / or OASIS Web Services + Distributed Management (WSDM). While the first one is supposed to + be used by java based clients only the latter is an interoperable + protocol that enables management clients to access and receive + notifications of management-enabled resources using Web Services. + </para><para> + QMan can be easily integrated in your preexisting system in + different ways : + </para><itemizedlist> + <listitem><para>As a standalone application : in this case it runs as a + server. More specifically it enables communication via RMI (for + JMX) or via HTTP (for WS-DM); Note that when the WS-DM adapter is + used the JMX interface is not exposed; + </para></listitem> + <listitem><para>As a deployable unit : it is also available as a standard + Java web application (war); This is useful when there's a + preexisting Application Server in your environment and you don't + want start another additional server in order to run QMan. + </para></listitem> + </itemizedlist> + + <section role="h2" id="QMan-QpidManagementbridge-UserDocumentation"><title> + User + Documentation + </title> + <para> + With "User Documentation" we mean all information that you need + to know in order to use QMan from a user perspective. Those + information include : + </para><table><title/><tgroup cols="2"> + <tbody> + <row> + <entry> + Section + </entry> + <entry> + Description + </entry> + </row> + <row> + <entry> + <xref linkend="qpid_Get-me-up-and-running"/> + </entry> + <entry> + How to install & start QMan. + </entry> + </row> + <row> + <entry> + <xref linkend="qpid_QMan-User-Guide"/> + </entry> + <entry> + QMan (WS-DM version only) Administration Console. + </entry> + </row> + <row> + <entry> + <xref linkend="qpid_JMX-Interface-Specification"/> + </entry> + <entry> + Describes each JMX interface exposed by QMan. + </entry> + </row> + <row> + <entry> + <xref linkend="qpid_WS-DM-Interface-Specification"/> + </entry> + <entry> + Describes each WS-DM interface exposed by QMan. + </entry> + </row> + <row> + <entry> + <xref linkend="qpid_QMan-Messages-Catalogue"/> + </entry> + <entry> + Informational / Debug / Error / Warning messages catalogue. + </entry> + </row> + </tbody> + </tgroup></table> + <!--h2--></section> + + + <section role="h2" id="QMan-QpidManagementbridge-TechnicalDocumentation"><title> + Technical + Documentation + </title> + <para> + If you are interested in technical details about QMan and related + technologies this is a good starting point. In general this + section provides information about QMan design, interfaces, + patterns and so on... + </para> + + <table><title/><tgroup cols="2"> + <tbody> + <row> + <entry> + Section + </entry> + <entry> + Description + </entry> + </row> + <row> + <entry> + <xref linkend="qpid_QMan-System-Overview"/> + </entry> + <entry> + A short introduction about QMan deployment context. + </entry> + </row> + <row> + <entry> + <xref linkend="qpid_QMan-Components-View"/> + </entry> + <entry> + Describes QMan components, their interactions and + responsibilities. + </entry> + </row> + </tbody> + </tgroup></table> + +<!--h2--></section> +<!--h1--></section> + +</section> diff --git a/qpid/doc/book/src/old/Qpid-ACLs.xml b/qpid/doc/book/src/old/Qpid-ACLs.xml new file mode 100644 index 0000000000..a2b64061c3 --- /dev/null +++ b/qpid/doc/book/src/old/Qpid-ACLs.xml @@ -0,0 +1,49 @@ +<?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> + <title>Qpid ACL Formats</title> + <para> + The Qpid project has two ACL implementations currently. The java broker + has a simple XML configuration mechanism icluded as part of the main + broker configuration. The C++ broker and the latest versions of the Java + broker also have a new, text based ACL file format. + </para> + <bridgehead id="QpidACLs-Specifications"><anchor id="QpidACLs-Specifications" />Specifications</bridgehead> + <para> + The specifications for each of the ACL formats are linked here: + </para> + <para> + <xref linkend="JavaXMLACLs-specification" /> + <xref linkend="ACL-specification" /> + </para> + <bridgehead id="QpidACLs-UserGuides"><anchor id="QpidACLs-UserGuides" />User Guides</bridgehead> + <para> + To aid users in defining their ACLs we have a user guide for each + of the ACL formats and a page describing the security plugin mechanism in the Java broker. + </para> + <para> + <xref linkend="JavaXMLACLs-userguide" /> + <xref linkend="ACL-userguide" /> + <xref linkend="Security-Plugins-Documentation" /> + </para> +</section> diff --git a/qpid/doc/book/src/old/Qpid-Book.xml b/qpid/doc/book/src/old/Qpid-Book.xml new file mode 100644 index 0000000000..ee69532152 --- /dev/null +++ b/qpid/doc/book/src/old/Qpid-Book.xml @@ -0,0 +1,93 @@ +<?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 book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<book> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Book-Info.xml"/> + <part> + <title>Basics</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Introduction.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Getting-Started.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Download.xml"/> + </part> + +<!-- + The broker sections define their own <part/> elements, with <partintro/> text. +--> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Messaging-Broker-CPP.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Messaging-Broker-Java.xml"/> + + <part> + <title>AMQP Messaging Clients Clients</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Java-JMS-Messaging-Client.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-C++-Messaging-Client.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-.NET-Messaging-Client.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Python-Messaging-Client.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Ruby-Messaging-Client.xml"/> + + </part> + <part> + <title>Appendices</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Compatibility.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Qpid-Interoperability-Documentation.xml"/> +<!-- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="FAQ.xml"/> --> + </part> +</book> + +<!-- +Documentation +Getting Started + + * Download + * Getting Started + +AMQP (Advanced Message Queueing Protocol) + + * Toward a Commodity Enterprise Middleware + * AMQP (Advanced Message Queueing Protocol) + +Qpid AMQP Brokers + + * AMQP Messaging Broker (implemented in C++) + * AMQP Messaging Broker (implemented in Java) + +Qpid AMQP Clients + + * AMQP Java JMS Messaging Client + * AMQP C++ Messaging Client + * AMQP .NET Messaging Client + * AMQP Python Messaging Client + * AMQP Ruby Messaging Client + +Interoperability + + * AMQP Compatibility + * SASL Interoperability + +FAQ + + * Frequently Asked Questions +--> diff --git a/qpid/doc/book/src/old/Qpid-Compatibility-And-Interoperability-Book.xml b/qpid/doc/book/src/old/Qpid-Compatibility-And-Interoperability-Book.xml new file mode 100644 index 0000000000..f382f390c7 --- /dev/null +++ b/qpid/doc/book/src/old/Qpid-Compatibility-And-Interoperability-Book.xml @@ -0,0 +1,36 @@ +<?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 book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<book> + <chapter> + <title>AMQP Compatibility</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="AMQP-Compatibility.xml"/> + </chapter> + <chapter> + <title>Qpid Interoperability Documentation</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Qpid-Interoperability-Documentation.xml"/> + </chapter> +</book> diff --git a/qpid/doc/book/src/old/SASL-Compatibility.xml b/qpid/doc/book/src/old/SASL-Compatibility.xml new file mode 100644 index 0000000000..ad223792b5 --- /dev/null +++ b/qpid/doc/book/src/old/SASL-Compatibility.xml @@ -0,0 +1,70 @@ +<!-- + - + - 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. + - + --> +h2. Qpid Interoperability Documentation + +This page documents the various interoperable features of the Qpid clients. + + +h3. SASL +{anchor:sasl} +h4. Standard Mechanisms +[SASL Mechanisms |http://en.wikipedia.org/wiki/Simple_Authentication_and_Security_Layer#SASL_Mechanisms] + +This table list the various SASL mechanisms that each component supports. The version listed shows when this +functionality was added to the product. + +|| Component || ANONYMOUS || CRAM-MD5 || DIGEST-MD5 || EXTERNAL || GSSAPI/Kerberos || PLAIN || +| C++ Broker |M3 |M3 | M3 |0.8\[[#1]\]|M3 | M1 | +| C++ Client |M3 |0.5 | 0.5 |0.8\[[#1]\]| | M1 | +| Java Broker | | M1 | | | | M1 | +| Java Client | | M1 | | M1 | | M1 | +| .Net Client | M2 | M2 | M2 | M2 | | M2 | +| Python Client |0.6\[[#2]\]|0.6\[[#2]\]|0.6\[[#2]\] |0.6\[[#2]\]|0.6\[[#2]\] | M4 | +| Ruby Client |0.6\[[#2]\]|0.6\[[#2]\]|0.6\[[#2]\] |0.6\[[#2]\]|0.6\[[#2]\] | M4 | + +{anchor:1} +1: Only enabled for client authenticated SSL connections. +{anchor:2} +2: On linux only via cyrus-sasl integration. + +h4. Custom Mechanisms + +There have been some custom mechanisms added to our implementations. + +|| Component || AMQPLAIN || CRAM-MD5-HASHED || +| C++ Broker | | | +| C++ Client | | | +| Java Broker | M1 | M2 | +| Java Client | M1 | M2 | +| .Net Client | | | +| Python Client | M2 | | +| Ruby Client | M2 | | + + +h5. AMQPLAIN + +h5. CRAM-MD5-HASHED + +The Java SASL implementations require that you have the password of the user to validate the incoming request. This then means that the user's password must be stored on disk. For this to be secure either the broker must encrypt the password file or the need for the password being stored must be removed. + +The CRAM-MD5-HASHED SASL plugin removes the need for the plain text password to be stored on disk. The mechanism defers all functionality to the build in CRAM-MD5 module the only change is on the client side where it generates the hash of the password and uses that value as the password. This means that the Java Broker only need store the password hash on the file system. While a one way hash is not very secure compared to other forms of encryption in environments where the having the password in plain text is unacceptable this will provide and additional layer to protect the password. In particular this offers some protection where the same password may be shared amongst many systems. It offers no real extra protection against attacks on the broker (the secret is now the hash rather than the password). + + diff --git a/qpid/doc/book/src/old/SSL.xml b/qpid/doc/book/src/old/SSL.xml new file mode 100644 index 0000000000..a9a5cb953a --- /dev/null +++ b/qpid/doc/book/src/old/SSL.xml @@ -0,0 +1,180 @@ +<?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><title> + SSL + </title> + + <section role="h1" id="SSL-SSLHowto"><title> + SSL How to + </title> + + <section role="h2" id="SSL-C-5Cbroker-28M4andup-29"><title> + C++ broker (M4 and up) + </title> + <itemizedlist> + <listitem><para>You need to get a certificate signed by a CA, trusted by your + client. + </para></listitem> + </itemizedlist><itemizedlist> + <listitem><para>If you require client authentication, the clients certificate + needs to be signed by a CA trusted by the broker. + </para></listitem> + </itemizedlist><itemizedlist> + <listitem><para>Setting up the certificates for testing. + <itemizedlist> + <listitem><para>For testing purposes you could use the <xref linkend="qpid_gtstd"/> to setup your certificates. + </para></listitem> + <listitem><para>In summary you need to create a root CA and import it to + the brokers certificate data base. + </para></listitem> + <listitem><para>Create a certificate for the broker, sign it using the + root CA and then import it into the brokers certificate data + base. + </para></listitem> + </itemizedlist> + </para></listitem> + </itemizedlist><itemizedlist> + <listitem><para>Load the acl module using --load-module or if loading more + than one module, copy ssl.so to the location pointed by + --module-dir + + <programlisting> +Ex if running from source. ./qpidd --load-module /libs/ssl.so +</programlisting> + + </para></listitem> + </itemizedlist><itemizedlist> + <listitem><para>Specify the password file (a plain text file with the + password), certificate database and the brokers certificate name + using the following options + + <programlisting> +Ex ./qpidd ... --ssl-cert-password-file ~/pfile --ssl-cert-db ~/server_db/ --ssl-cert-name localhost.localdomain +</programlisting> + + </para></listitem> + </itemizedlist><itemizedlist> + <listitem><para>If you require client authentication you need to add + --ssl-require-client-authentication as a command line argument. + </para></listitem> + </itemizedlist><itemizedlist> + <listitem><para>Please note that the default port for SSL connections is + 5671, unless specified by --ssl-port + </para></listitem> + </itemizedlist><para> + Here is an example of a broker instance that requires SSL client + side authenticaiton + </para> + <programlisting> +./qpidd ./qpidd --load-module /libs/ssl.so --ssl-cert-password-file ~/pfile --ssl-cert-db ~/server_db/ --ssl-cert-name localhost.localdomain --ssl-require-client-authentication +</programlisting> + <!--h2--></section> + <section role="h2" id="SSL-JavaClient-28M4andup-29"><title> + Java Client (M4 and up) + </title> + <itemizedlist> + <listitem><para>This guide is for connecting with the Qpid c++ broker. + </para></listitem> + </itemizedlist><itemizedlist> + <listitem><para>Setting up the certificates for testing. In summary, + <itemizedlist> + <listitem><para>You need to import the trusted CA in your trust store and + keystore + </para></listitem> + <listitem><para>Generate keys for the certificate in your key store + </para></listitem> + <listitem><para>Create a certificate request using the generated keys + </para></listitem> + <listitem><para>Create a certficate using the request, signed by the + trusted CA. + </para></listitem> + <listitem><para>Import the signed certificate into your keystore. + </para></listitem> + </itemizedlist> + </para></listitem> + </itemizedlist><itemizedlist> + <listitem><para>Pass the following JVM arguments to your client. + + <programlisting> +-Djavax.net.ssl.keyStore=/home/bob/ssl_test/keystore.jks + -Djavax.net.ssl.keyStorePassword=password + -Djavax.net.ssl.trustStore=/home/bob/ssl_test/certstore.jks + -Djavax.net.ssl.trustStorePassword=password +</programlisting> + + </para></listitem> + </itemizedlist> + <!--h2--></section> + + <section role="h2" id="SSL-.NetClient-28M4andup-29"><title> + .Net Client (M4 and up) + </title> + <itemizedlist> + <listitem><para>If the Qpid broker requires client authentication then you + need to get a certificate signed by a CA, trusted by your client. + </para></listitem> + </itemizedlist><para> + Use the connectSSL instead of the standard connect method of the + client interface. + </para><para> + connectSSL signature is as follows: + </para> + <programlisting> +public void connectSSL(String host, int port, String virtualHost, String username, String password, String serverName, String certPath, bool rejectUntrusted) +</programlisting> + <para> + Where + </para><itemizedlist> + <listitem><para>host: Host name on which a Qpid broker is deployed + </para></listitem> + <listitem><para>port: Qpid broker port + </para></listitem> + <listitem><para>virtualHost: Qpid virtual host name + </para></listitem> + <listitem><para>username: User Name + </para></listitem> + <listitem><para>password: Password + </para></listitem> + <listitem><para>serverName: Name of the SSL server + </para></listitem> + </itemizedlist><itemizedlist> + <listitem><para>certPath: Path to the X509 certificate to be used when the + broker requires client authentication + </para></listitem> + <listitem><para>rejectUntrusted: If true connection will not be established + if the broker is not trusted (the server certificate must be + added in your truststore) + </para></listitem> + </itemizedlist> + <!--h2--></section> + + <section role="h2" id="SSL-Python-26RubyClient-28M4andup-29"><title> + Python & + Ruby Client (M4 and up) + </title> + <para> + Simply use amqps:// in the URL string as defined above + </para> + <!--h2--></section> + <!--h1--></section> +</section> diff --git a/qpid/doc/book/src/old/Security-Plugins.xml b/qpid/doc/book/src/old/Security-Plugins.xml new file mode 100644 index 0000000000..bf5cb726b3 --- /dev/null +++ b/qpid/doc/book/src/old/Security-Plugins.xml @@ -0,0 +1,611 @@ +<?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 xmlns="http://docbook.org/ns/docbook" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd" + version="5.0" + label="Security-Plugins-Documentation"> + <title>Security Plugins Documentation</title> + + <section role="h2" label="SPD-Introduction"> + <title>Introduction</title> + <para> + This document describes the structure and design of Qpid security plugins, for + the Java broker. In particular, the new <emphasis>Access Control</emphasis> plugin, which implements + the same ACL file syntax as the C++ broker, is examined in detail. The security + plugins use the broker's OSGi bundle functionality to manage their lifecycle, + and the <code>ConfigurationPlugin</code> mechanism to manage their configuration via the + Apache commons configuration XML configuration file. + </para> + <para> + The Java interfaces and packages used by the security plugins are described here, + although the Javadoc documentation generated from the source should also be + consulted, and as always reading the source should provide further insight and information. + </para> + </section> + <section role="h2" label="SPD-Use-Cases"> + <title>Use Cases</title> + <para> + The following use cases were identified and used to drive the design and development + of both the security plugin mechanism in general, and the access control plugin in particular. + </para> + <itemizedlist> + <listitem> + <para> + Allow access to broker functions to be controlled by an ACL, with the checks being + carried out independently of the mechanism used to access the broker. This would + mean that a single <literal>CREATE </literal> permission would apply whether the queue was + created when a user logged in and used it, or if that user connected to the broker + via JMX or QMF and used the management operations to create the queue. + </para> + </listitem> + <listitem> + <para> + Permissions must be definable at a virtualhost level, with fallback to global + permissions. This allows access to be granted for operations only on a certain + host, while global operations such as broker administration can be defined at + the global level. It also allows default behaviour to be specified globally and + then overridden on a per-host basis. + </para> + </listitem> + <listitem> + <para> + The ACL mechanism controls access to operations on particular objects for all users, + if at least one user has a rule controlling access to that operation on that type of + object. This means that all users requiring access to a particular operation must be + configured. The default behaviour will be to deny access. + </para> + </listitem> + <listitem> + <para> + It should be possible for the addition of one access control rule to trigger the + addition of other rules, to simplify creation of rulesets. + </para> + </listitem> + <listitem> + <para> + The behaviour of the access control mechanism should be configurable. + </para> + </listitem> + <listitem> + <para> + The Java and C++ brokers should share a common configuration file format. + </para> + </listitem> + <listitem> + <para> + It should be possible to configure access to not just internal broker application + objects, but to the management operations and attributes of the broker, as well + as to external objects such as plugins. + </para> + </listitem> + <listitem> + <para> + As long as a suitably authenticated channel is used to connect, access control + rules should be applied when performing operations on broker objects. This does + not hold when, for example, an operator has local access and is using JConsole + to manage the broker. + </para> + </listitem> + </itemizedlist> + </section> + <section role="h2" label="SPD-Java-Interfaces-Packages-Classes"> + <title>Java Interfaces, Packages and Classes</title> + <para> + This section describes the Java artifacts that are involved in security plugin development. + They are mostly contained in the package <code>org.apache.qpid.server.security</code> which + is part of the broker code. It is recommended that a package prefix is chosen for new + security plugins, and this should be used to form the packages for the implementing classes. + </para> + <para> + In general, when creating a new plugin, you need three classes. These would be the main + <code>PluginName</code> class, which should implement the <code>SecurityPlugin</code> + interface and have a public static instance of an anonymous internal classes that implements + <code>SecurityPluginfactory</code>. Additionally, the <code>PluginNameConfiguration</code> + class, which should implement the <code>ConfigurationPlugin</code> interface and have a + public static instance of an anonymous internal classes that implements + <code>ConfigurationPluginfactory</code>, and finally the <code>PluginNameActivator</code> + class, which should extend the <code>SecurityPluginActivator</code> abstract class + and implement the required methods exposing the factories from the other classes. + </para> + <para> + These classes need to be visible from the broker, so they should be placed in the + <code>org.apache.qpid.server.security.pluginname.plugins</code> package, which should be + listed in the manifest file. Any internal classes for the plugin should be placed in + the <code>org.apache.qpid.server.security.pluginname.config</code> package which + should be marked as provate in the manifest. + </para> + <para> + If logging using the actor and subject framework is required, the property file should + be located in the <code>org.apache.qpid.server.security.pluginname.logging</code> + package, and this should also be exported in the manifest file. + </para> + <section role="h3" label="SPD-OSGi"> + <title>OSGi</title> + <para> + The security plugins are now loaded using the <emphasis>Felix</emphasis> OSGi container, which is started + as an embedded process inside the broker. This loads all plugin .jar files from the + directory named in the <code>plugin-directory</code> configuration element, cacheing them in the + <code>cache-directory</code> directory. Note that, at present, the cache directory is cleared at + startup, although this behaviour may change. To create OSGi plugin bundles, a manifest + file - <code>MANIFEST.MF</code> is created that specifies certain attributes of the bundle. A + sample manifest file for one of the security plugins is shown below. + </para> + <programlisting> +Manifest-Version: 1.0 +Bundle-ManifestVersion: 2 +Bundle-Name: Qpid Broker-Plugins PluginName +Bundle-SymbolicName: broker-plugins-pluginname +Bundle-Description: Name description. +Bundle-License: http://www.apache.org/licenses/LICENSE-2.0.txt +Bundle-DocURL: http://www.apache.org/qpid/pluginname.html +Bundle-Version: 1.0.0 +Bundle-Activator: org.apache.qpid.server.security.pluginname.plugins.PluginNameActivator +Bundle-RequiredExecutionEnvironment: JavaSE-1.5 +Bundle-ActivationPolicy: lazy +Import-Package: org.apache.qpid +Private-Package: org.apache.qpid.server.security.pluginname.config, + org.apache.qpid.server.security.pluginname.logging +Export-Package: org.apache.qpid.server.security.pluginname.plugins + </programlisting> + <para> + The complete list of packages to import will be determined by the actual operation of + the plugin, however the number of exported packages should be kept to a minimum. + </para> + </section> + <section role="h3" label="SPD-Plugin"> + <title>Plugin</title> + <para> + This is the main interface to be extended by all plugins. It contains a + method that allows configuration via the <code>ConfigurationPlugin</code> + mechanism. + </para> + <programlisting> +public void configure(ConfigurationPlugin config); + </programlisting> + </section> + <section role="h3" label="SPD-PluginFactory"> + <title>PluginFactory and SecurityPluginFactory</title> + <para> + These factories are used to initialise instances of plugins and configure them appropriately. + The factories are managed by the OSGI framework started by the <code>PluginManager</code>, + which is also used to retrieve the instances. + </para> + <programlisting> +public Class<P> getPluginClass(); +public String getPluginName(); +public P newInstance(ConfigurationPlugin config) throws ConfigurationException; + </programlisting> + </section> + <section role="h3" label="SPD-SecurityPlugin"> + <title>SecurityPlugin</title> + <para> + This is the interface that defines security plugins. The <code>getDefault</code> method + returns the default result for the plugin when no configuration is found for some + situation. + </para> + <para> + The <code>authorise</code> method is the main entry-point to the plugin, and is called + by the <code>SecurityManager</code> with the relevant paramaters. Similarly, the + <code>access</code> method is used for the special case of controlling access to + the entire virtual host, and the <code></code> + </para> + <programlisting> +Result getDefault(); +Result access(ObjectType objectType, Object instance); +Result authorise(Operation operation, ObjectType objectType, ObjectProperties properties); + </programlisting> + </section> + <section role="h3" label="SPD-SecurityPluginActivator"> + <title>SecurityPluginActivator</title> + <para> + The activator registers the factories with the OSGI framework, based on the + implementations of the abstract methods. + </para> + <programlisting> +public abstract SecurityPluginFactory getFactory(); +public abstract ConfigurationPluginFactory getConfigurationFactory(); + </programlisting> + </section> + <section role="h3" label="SPD-AbstractPlugin"> + <title>AbstractPlugin</title> + <para> + This is a simple parent class, which allows a common point of extension + for shared plugin code. Currently it simply implements the interface with + abstract methods. + </para> + <programlisting> +public abstract Result access(ObjectType object, Object instance); +public abstract Result authorise(Operation operation, ObjectType object, ObjectProperties properties); + </programlisting> + </section> + <section role="h3" label="SPD-AbstractProxyPlugin"> + <title>AbstractProxyPlugin</title> + <para> + This class is designed to be extended by plugins that only wish to take part in a subset + of the possible security descisions. Normally, a call to the <code>authorise</code> method + is proxied to one of the provided methods, based on the operation, for example a <literal>CONSUME</literal> + access control check would be proxied to the <code>authoriseConsume</code> method with + the appropriate paramaters set. The default behaviour is to return <literal>ABSTAIN</literal>, meaning + the plugin does not handle this type of operation. If a method is overridden, it can then perform + whatever security checks are required and return <literal>ALLOWED</literal> or <literal>DENIED</literal> + as appropriate. + </para> + <programlisting> +public Result authoriseConsume(ObjectType object, ObjectProperties properties); +public Result authorisePublish(ObjectType object, ObjectProperties properties); +public Result authoriseCreate(ObjectType object, ObjectProperties properties); +public Result authoriseAccess(ObjectType object, ObjectProperties properties); +public Result authoriseBind(ObjectType object, ObjectProperties properties); +public Result authoriseUnbind(ObjectType object, ObjectProperties properties); +public Result authoriseDelete(ObjectType object, ObjectProperties properties); +public Result authorisePurge(ObjectType object, ObjectProperties properties); +public Result authoriseExecute(ObjectType object, ObjectProperties properties); +public Result authoriseUpdate(ObjectType object, ObjectProperties properties); +public Result accessVirtualhost(Object instance); + </programlisting> + </section> + </section> + <section role="h2" label="SPD-Access-Control-Security-Plugin"> + <title>Access Control Security Plugin</title> + <para> + This security plugin implements access control using the same configuration file syntax as the + C++ broker. The classes are all in sub-packages of the <code>org.apache.qpid.server.security.access</code> + package. The exposed classes consist of the plugoin itself, its OSGi activator and the configuration + plugin, as well as the properties file and generated code for logging. The private, internal classes, + consist of the ruleset implementation for managing access control list rules. The plugin also makes + extensive use of the enumerations provided by the broker as part of the security plugin interfaces, + for operations, objects and permissions. + </para> + <section role="h3" label="SPD-ACL-Enumerations"> + <title>Enumerations</title> + <para> + These enumerations are used to define exactly what a security plugin can control. + </para> + <para> + The <code>ObjectProperties</code> and <code>ObjectProperties.Property</code> lalala + </para> + <para> + The <code>ObjectType</code> + </para> + <para> + The <code>Operation</code> + </para> + <para> + The <code>Permission</code> + </para> + </section> + <section role="h3" label="SPD-ACL-Configuration"> + <title>Configuration</title> + <para> + Security plugins are configurable using the Qpid XML configuration file, under the <code><security></code> + element. This can be either inside the main <code><broker /></code> element, as a global plugin affecting + all virtual hosts, or under a <code><virtualhosts><virtualhost><name></code> element, where + the <code><name></code> element is the name of the virtual host that is to be configured. Each security + plugin must register the elements it expects to process using a <code>ConfigurationPlugin</code>, which is + documented elsewhere. + </para> + <para> + The plugins are checked in order, first for the virtual host, then globally, and the first <literal>ALLOWED</literal> or + <literal>DENIED</literal> response is used. + </para> + <para> + The ACL configuration file is specified via the contents of the <code><aclv2></code> element. This is simply + the path to the file, which is a plain text format, and is parseable by both Java and C++ brokers. The path can be + specified with embedded property value interpolation, for environment variables or other properties defined in the + configuration file. + </para> + <programlisting> +<![CDATA[ +<security> + <!-- global access control configuration file --> + <aclv2>${QPID_HOME}/etc/global-security-config.txt</aclv2> +</security> +]]> + </programlisting> + <section role="h4" label="SPD-ACL-File-Format"> + <title>File Format</title> + <para> + The file format is described below. + </para> + <itemizedlist> + <listitem> + <para> + Whitespace is considered to be any ASCII + byte with a value below <literal>0x20</literal>, and is + ignored when it occurs between tokens. + </para> + </listitem> + <listitem> + <para> + Continuations using the <literal>\</literal> + character (ASCII <literal>0x5c</literal>) are allowed + anywhere on a line, and + can consist of a blank line with a continuation + character as the last non-whitespace token + </para> + <programlisting> +group group1 name1 name2 \ + name3 name4 \ + name5 +acl allow group1 create queue \ + property1 = "value1" \ + property2 \ + = "value2" + </programlisting> + </listitem> + <listitem> + <para> + Comments are line-style comments, and any text after + an un-quoted <literal>#</literal> (ASCII <literal>0x23</literal>) + are ignored, including continuations. The <literal>#</literal> + charater may appear in a quoted string. + </para> + </listitem> + <listitem> + <para> + Quoted strings consist of any ASCII inside matching pairs of + <literal>'</literal> or <literal>"</literal> (ASCII <literal>0x27</literal> + and <literal>0x22</literal>) characters, including any + otherwise special characters. + </para> + </listitem> + <listitem> + <para> + Tokens are <emphasis>NOT</emphasis> case sensitive, but quoted + strings <emphasis>ARE</emphasis>. + </para> + </listitem> + <listitem> + <para> + The <literal>=</literal> (ASCII <literal>0x3d</literal>) character + is special, and is used to indicate property value assignment. + </para> + </listitem> + <listitem> + <para> + Wildcards are specified using the <literal>*</literal> (ASCII + <literal>0x2a</literal>) character in a property value string, + which may be quoted. + </para> + </listitem> + <listitem> + <para> + Empty lines and lines that contain only whitespace are ignored. + </para> + </listitem> + <listitem> + <para> + The keyword <literal>all</literal> is reserved, and matches all individuals, + groups and actions. It may be used in place of a group or + individual name and/or an action - eg <literal>acl allow all all</literal>, + <literal>acl deny all all</literal> or <literal>acl deny user1 all</literal>. + </para> + </listitem> + <listitem> + <para> + Rules are interpreted from the top of the file down until the + name match is obtained; at which point processing stops. + </para> + </listitem> + <listitem> + <para> + The last line of the file (whether present or not) will be + assumed to be <literal>acl deny all all</literal>. If present in the file, any + lines below this one are ignored. + </para> + </listitem> + <listitem> + <para> + Names and group names may contain only <literal>a-z</literal>, + <literal>A-Z</literal>, <literal>0-9</literal>, + <literal>-</literal>, <literal>@</literal>, <literal>/</literal> + or <literal>_</literal>. + </para> + </listitem> + <listitem> + <para> + Rules must be preceded by any configuration and group definitions they may use; + any name not previously defined as a group will be assumed to be + that of an individual user. + </para> + </listitem> + <listitem> + <para> + <literal>CONFIG</literal> lines must have the following tokens in order: + </para> + <itemizedlist> + <listitem> + <para>The string literal <literal>config</literal></para> + </listitem> + <listitem> + <para>One or more property name-value pairs, in the form <literal>property = value</literal> + where value is the token <literal>true</literal> or <literal>false</literal></para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> + GROUP lines must have the following tokens in order: + </para> + <itemizedlist> + <listitem> + <para>The string literal <literal>group</literal></para> + </listitem> + <listitem> + <para>The name of the group, which cannot contain <literal>@</literal> or + <literal>/</literal> characters</para> + </listitem> + <listitem> + <para>A whitespace separated list of user and group names. User names are formatted + as <literal>username/domain@realm</literal> and group names must have been defined + earlier in the file</para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> + ACL rules must have the following tokens in order: + </para> + <itemizedlist> + <listitem> + <para>An optional rule number, which should be expressible as a positive Java integer</para> + </listitem> + <listitem> + <para>The string literal <literal>acl</literal></para> + </listitem> + <listitem> + <para>The permission, one of <literal>allow</literal>, <literal>allow-log</literal>, + <literal>deny</literal> or <literal>deny-log</literal></para> + </listitem> + <listitem> + <para>The name of a single group or individual or the keyword <literal>all</literal></para> + </listitem> + <listitem> + <para>The name of an operation, which should be one of <literal>consume</literal>, + <literal>publish</literal>, <literal>create</literal>, <literal>access</literal>, + <literal>bind</literal>, <literal>unbind</literal>, <literal>delete</literal>, + <literal>purge</literal>, <literal>update</literal>, <literal>execute</literal> + or the keyword <literal>all</literal></para> + </listitem> + <listitem> + <para>Optionally, a single object type or the keyword <literal>all</literal></para> + <para>Objects allowed are <literal>virtualhost</literal>, <literal>queue</literal>, + <literal>topic</literal> and <literal>exchange</literal></para> + <para>Objects allowed are <literal>virtualhost</literal>, <literal>queue</literal>, + <literal>topic</literal>, <literal>exchange</literal>, <literal>link</literal>, + <literal>route</literal>, <literal>method</literal> and <literal>object</literal></para> + </listitem> + <listitem> + <para>If the object is present, then optionally one or more property name-value pairs in the form + <literal>property=value</literal>. The property and value can be separated from the + <literal>=</literal> charater by any amount of whitespace, and the calue can be quoted if + it contains special characters or whitespace.</para> + </listitem> + <listitem> + <para>Property values can add the wildcard <literal>*</literal> character at the end of the string + to indicate that any string beginning with the characters up to the wildcard will match, or + if the wildcard is the only character, that any string will match</para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + <para> + This allows a rather looser and more readable style for ACL files, + while still retaining the ability to read the stricter files accepted + by the C++ broker. Bear in mind that the group declarations are to be + deprecated, in favour of an external directory service, using a plugin + mechanism. + </para> + <para> + The initial number is used to allow rulesets to be created which allow + individual rules to be enabled and disabled using an admin interface, + and an ACL file using numbered lines would be restricted to having + increasing numbers per rule, although gaps would be allowed to enable + rules to be inserted later, again using an admin interface. This + administrative interface would also allow saving of a modified ruleset + and re-loading. + </para> + </section> + <section role="h4" label="SPD-ACL-Broker-Access-Control"> + <title>Broker Access Control</title> + <para> + The Java broker access control mechanism is used to protect internal + entities used by the broker. These are virtual hosts, queues, topics + and exchanges. The actual access control checks take place in the + methods that carry out the operations on these objects, in order to + ensure thatsecurity is both mechanism and protocol agnostic. + </para> + <para> + <emphasis>The Java broker does not support <code>LINK</code> or + <code>ROUTE</code> object types.</emphasis> + </para> + <para> + An example of the various rules that can be specified follows: + </para> + <programlisting> +acl allow robot create exchange name="robot.*" +acl deny kitten create queue +acl allow guest bind exchange name=amq.topic routingkey="kitten.#" +acl allow all create queue name="tmp.*" +acl allow guest publish all durable="false" +acl allow robot create queue name="robot" +acl allow kitten consume queue durable="true" +acl allow guest create all + </programlisting> + </section> + <section role="h4" label="SPD-ACL-Management-Access-Control"> + <title>Management Access Control</title> + <para> + The management of the broker using JMX is also protected by the security + plugins, in two ways. If the management interface is used to perform + operations that would be access controlled normally, the same rules + would still apply and be applied. However, this only occurs when the + JMX connection was authenticated. If JConsole is used to connect directly + to a broker process started by the same user, then no extra checks are made. + </para> + <para> + The management operations themselves are also able to be access controlled. + This is done using the <code>METHOD</code> object type. A component name + and method name are specified as properties, and these indicate the MBean + type name and JMX method name respectively. If the operation is set to + <code>ALL</code> then reading JMX attributes, writing JMX attributes and + invoking JMX operations are controlled by the rule. Otherwise, the three + operations <code>ACCESS</code>, <code>UPDATE</code> and <code>EXECUTE</code> + control reading, writing and invocation respectively. + </para> + <programlisting> +ACL ALLOW user ALL METHOD +ACL ALLOW user ALL METHOD name="method" +ACL ALLOW user ALL METHOD name="prefix*" +ACL ALLOW user ALL METHOD component="MBean" name="method" +ACL ALLOW user ACCESS METHOD component="MBean" +ACL ALLOW user UPDATE METHOD component="MBean" +ACL ALLOW user EXECUTE METHOD component="MBean" + </programlisting> + </section> + <section role="h4" label="SPD-ACL-External-Object-Access-Control"> + <title>External Object Access Control</title> + <para> + At the moment the C++ broker has an extension point to allow access control + of external objects. This will be provided in the Java broker as well, using the + <code>ACCESS OBJECT</code> rule, with package name and class name properties. + The external object must be able to retrieve a reference to the virtual host + it is running on, and then call the <code>accessObject</code> method. This + must be the responsibility of the external object. + </para> + <para> + <emphasis>Note that this is not currently implemented in the <code>SecurityManager</code>.</emphasis> + </para> + <programlisting> +ACL ALLOW user ACCESS OBJECT package="com.example.application" class="Extension" + </programlisting> + <programlisting> +if (!_vhost.getSecurityManager().accessObject("com.example.application", "Extension")) +{ + // TODO reject access somehow - exception +} + </programlisting> + </section> + </section> + </section> +</section> diff --git a/qpid/doc/book/src/old/System-Properties.xml b/qpid/doc/book/src/old/System-Properties.xml new file mode 100644 index 0000000000..40b823185f --- /dev/null +++ b/qpid/doc/book/src/old/System-Properties.xml @@ -0,0 +1,357 @@ +<?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> + + <title> + System Properties + </title> + + <section role="h2" id="SystemProperties-ExplanationofSystempropertiesusedinQpid"> + + <title> Explanation of System properties used in Qpid </title> + + <para> + This page documents the various System Properties that are + currently used in the Qpid Java code base. + </para> + +<!-- ######################################################### --> + + <section role="h3" id="SystemProperties-ClientProperties"> + <title> Client Properties </title> + + <variablelist> + <varlistentry> + <term>STRICT_AMQP</term> + <listitem> + <variablelist> + <varlistentry> + <term>Type</term> + <listitem><para>Boolean</para></listitem> + </varlistentry> + <varlistentry> + <term>Default</term> + <listitem><para>FALSE</para></listitem> + </varlistentry> + </variablelist> + <para> This forces the client to only send AMQP compliant + frames. This will disable a number of JMS features.</para> + + <itemizedlist> + <title> Features disabled by STRICT_AMQP</title> + <listitem><para>Queue Browser + </para></listitem> + <listitem><para>Message Selectors + </para></listitem> + <listitem><para>Durable Subscriptions + </para></listitem> + <listitem><para>Session Recover may result in duplicate message delivery + </para></listitem> + <listitem><para>Destination validation, so no InvalidDestinationException + will be thrown + </para></listitem> + </itemizedlist> + <para> + This is associated with property <xref linkend="SystemProperties-STRICTAMQPFATAL"/> + </para> + </listitem> + </varlistentry> + + + + <varlistentry id="SystemProperties-STRICTAMQPFATAL"> + <term>STRICT_AMQP_FATAL</term> + <listitem> + <variablelist> + <varlistentry> + <term>Type</term> + <listitem><para>Boolean</para></listitem> + </varlistentry> + <varlistentry> + <term>Default</term> + <listitem><para>FALSE</para></listitem> + </varlistentry> + </variablelist> + <para> + This will cause any attempt to utilise an enhanced feature to + throw and UnsupportedOperationException. When set to false then + the exception will not occur but the feature will be disabled. + </para> + <para> + e.g. + The Queue Browser will always show no messages. + Any message selector will be removed. + </para> + </listitem> + </varlistentry> + + + <varlistentry> + <term>IMMEDIATE_PREFETCH</term> + <listitem> + <variablelist> + <varlistentry> + <term>Type</term> + <listitem><para>Boolean</para></listitem> + </varlistentry> + <varlistentry> + <term>Default</term> + <listitem><para>FALSE</para></listitem> + </varlistentry> + </variablelist> + <para> + The default with AMQP is to start prefetching messages. However, + with certain 3rd party Java tools, such as Mule this can cause a + problem. Mule will create a consumer but never consume from it so + any any prefetched messages will be stuck until that session is + closed. This property is used to re-instate the default AMQP + behaviour. The default Qpid behaviour is to prevent prefetch + occurring, by starting the connection Flow Controlled, until a + request for a message is made on the consumer either via a + receive() or setting a message listener.</para> + </listitem> + </varlistentry> + + + + <varlistentry> + <term>qpid.sync_op_timeout</term> + <listitem> + <variablelist> + <varlistentry> + <term>Type</term> + <listitem><para>long</para></listitem> + </varlistentry> + <varlistentry> + <term>Default</term> + <listitem><para>60000</para></listitem> + </varlistentry> + </variablelist> + <para>The length of time (in milliseconds) to wait for a synchronous operation to complete. + For compatibility with older clients, the synonym amqj.default_syncwrite_timeout is supported.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>amq.dynamicsaslregistrar.properties</term> + <listitem> + <variablelist> + <varlistentry> + <term>Type</term> + <listitem><para>String</para></listitem> + </varlistentry> + <varlistentry> + <term>Default</term> + <listitem><para>org/apache/qpid/client/security/DynamicSaslRegistrar.properties</para></listitem> + </varlistentry> + </variablelist> + <para>The name of the SASL configuration properties file. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>amqj.heartbeat.timeoutFactor</term> + <listitem> + <variablelist> + <varlistentry> + <term>Type</term> + <listitem><para>float</para></listitem> + </varlistentry> + <varlistentry> + <term>Default</term> + <listitem><para>2.0</para></listitem> + </varlistentry> + </variablelist> + <para> + The factor used to get the timeout from the delay between + heartbeats + </para> + </listitem> + </varlistentry> + + + <varlistentry> + <term>amqj.tcp_nodelay</term> + <listitem> + <variablelist> + <varlistentry> + <term>Type</term> + <listitem><para>Boolean</para></listitem> + </varlistentry> + <varlistentry> + <term>Default</term> + <listitem><para>TRUE</para></listitem> + </varlistentry> + </variablelist> + <para> Disable Nagle's algorithm on the TCP connection. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>amqj.protocol.logging.level</term> + <listitem> + <variablelist> + <varlistentry> + <term>Type</term> + <listitem><para>Boolean</para></listitem> + </varlistentry> + <varlistentry> + <term>Default</term> + <listitem><para>null</para></listitem> + </varlistentry> + </variablelist> + <para>If set this will turn on protocol logging on the + client. </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>jboss.host</term> + <listitem> + <para> + Used by the JBossConnectionFactoryInitialiser to specify the host + to connect to perform JNDI lookups. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>jboss.port</term> + <listitem> + <para> + Used by the JBossConnectionFactoryInitialiser to specify the port + to connect to perform JNDI lookups. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>amqj.MaximumStateWait</term> + <listitem> + <variablelist> + <varlistentry> + <term>Default</term> + <listitem><para>30000</para></listitem> + </varlistentry> + </variablelist> + <para> + Used to set the maximum time the State Manager should wait before + timing out a frame wait. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> +<!-- ######################################################### --> + + <section role="h3" id="SystemProperties-ManagementProperties"> + + <title> + Management Properties + </title> + + <variablelist> + <varlistentry> + <term>security</term> + <listitem> + <variablelist> + <varlistentry> + <term>Default</term> + <listitem><para>null</para></listitem> + </varlistentry> + </variablelist> + <para> + String representing the Security level to be used to on + the connection to the broker. The null default results + in no security or PLAIN. When used with jmxconnector + 'javax.management.remote.jmxmp.JMXMPConnector' a + security value of 'CRAM-MD5' will result in all + communication to the broker being encrypted. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>jmxconnector</term> + <listitem> + <variablelist> + <varlistentry> + <term>Default</term> + <listitem><para>null</para></listitem> + </varlistentry> + </variablelist> + <para> + String representing the JMXConnector class used to + perform the connection to the broker. The null default + results in the standard JMX connector. Utilising + 'javax.management.remote.jmxmp.JMXMPConnector' and + security 'CRAM-MD5' will result in all communication to + the broker being encrypted. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>timeout</term> + <listitem> + <variablelist> + <varlistentry> + <term>Default</term> + <listitem><para>5000</para></listitem> + </varlistentry> + </variablelist> + <para> + Long value representing the milli seconds before + connection to the broker should timeout. + </para> + </listitem> + </varlistentry> + + </variablelist> + + </section> + + +<!-- ######################################################### --> + + + <section role="h3" id="SystemProperties-PropertiesusedinExamples"> + + <title> Properties used in Examples </title> + + <variablelist> + <varlistentry> + <term>archivepath</term> + <listitem> + <para> + Used in <filename>FileMessageDispatcher</filename>. This + properties specifies the directory to move payload + file(s) to archive location as no error</para> + </listitem> + </varlistentry> + </variablelist> +</section> +</section> +</section> diff --git a/qpid/doc/book/src/old/Using-Qpid-with-other-JNDI-Providers.xml b/qpid/doc/book/src/old/Using-Qpid-with-other-JNDI-Providers.xml new file mode 100644 index 0000000000..2bd7d761ef --- /dev/null +++ b/qpid/doc/book/src/old/Using-Qpid-with-other-JNDI-Providers.xml @@ -0,0 +1,215 @@ +<?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. + +--> + +<chapter> + + <title> + Using Qpid with other JNDI Providers + </title> + + <section role="h2" id="UsingQpidwithotherJNDIProviders-HowtouseaJNDIProvider"> + + <title> How to use a JNDI Provider </title> + + <para> + Qpid will work with any JNDI provider capable of storing Java + objects. We have a task to add our own initial context factory, + but until that's available .... + </para> + + <para> + First you must select a JNDI provider to use. If you aren't + already using an application server (i.e. Tomcat ?) which + provides JNDI support you could consider using either: + </para> + + <itemizedlist> + <listitem><para>Apache's <xref linkend="qpid_index"/> + which provides an LDAP JNDI implementation + </para></listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para>OR the SUN JNDI SPI for the FileSystem which can be + downloaded from <xref linkend="qpid_index"/> + </para> + <itemizedlist> + <listitem><para>Click : Download JNDI 1.2.1 & More button + </para></listitem> + <listitem><para>Download: File System Service Provider, 1.2 Beta 3 + </para></listitem> + <listitem><para>and then add the two jars in the lib dir to your class path. + </para></listitem> + </itemizedlist> + </listitem> + </itemizedlist> + + + <para> + There are two steps to using JNDI objects. + </para> + + <itemizedlist> + <listitem><para>Bind : Which stores a reference to a JMS + Object in the provider.</para></listitem> + <listitem><para>Lookup : Which tries to retrieve the + reference and create the JMS Object. </para></listitem> + </itemizedlist> + + <para> + There are two objects that would normally be stored in JNDI. + </para> + + <itemizedlist> + <listitem><para>A ConnectionFactory + </para></listitem> + <listitem><para>A Destination (Queue or Topic) + </para></listitem> + </itemizedlist> + + + <section role="h3" id="UsingQpidwithotherJNDIProviders-Binding"> + <title> + Binding + </title> + + <para> + Then you need to setup the values that the JNDI provider will + used to bind your references, something like this: + </para> + + <example> + <title>Setup JNDI</title> + + + <programlisting> +Hashtable env = new Hashtable(11); + env.put(Context.INITIAL_CONTEXT_FACTORY,"com.sun.jndi.fscontext.RefFSContextFactory"); + env.put(Context.PROVIDER_URL,LOCAL_FILE_PATH_FOR_STORING_BINDS_PATH_MUST_EXIST); +</programlisting> +</example> + + <para> + These values are then used to create a context to bind your + references. + </para> + +<example> + <title>Perform Binding of ConnectionFactory</title> + + + <programlisting> +try +{ + Context ctx = new InitialContext(env); + + // Create the object to be bound in this case a ConnectionFactory + ConnectionFactory factory = null; + + try + { + factory = new AMQConnectionFactory(CONNECTION_URL); + try + { + ctx.bind(binding, factory); + } + catch (NamingException e) + { + //Handle problems with binding. Such as the binding already exists. + } + } + catch (URLSyntaxException amqe) + { + //Handle any exception with creating ConnnectionFactory + } +} +catch (NamingException e) +{ + //Handle problem creating the Context. +} +</programlisting> +</example> + + <para> + To bind a queue instead simply create a AMQQueue object and use + that in the binding call. + </para> + +<example> +<title> Bind a AMQQueue</title> + <programlisting> +AMQQueue queue = new AMQQueue(QUEUE_URL); +ctx.bind(binding, queue); +</programlisting> +</example> + </section> + + <section role="h3" id="UsingQpidwithotherJNDIProviders-Lookup"> + <title> + Lookup + </title> + <para> + You can then get a queue connection factory from the JNDI + context. + </para> + + +<example> +<title> Perform Binding of ConnectionFactory</title> + + + <programlisting> +ConnectionFactory factory; +try +{ + factory= (ConnectionFactory)ctx.lookup(binding); +} +catch (NamingException e) +{ + //Handle problems with lookup. Such as binding does not exist. +} +</programlisting> +</example> + + <para> + Note that you need not cast the bound object back to an + AMQConnectionFactory so all your current JMS apps that + use JNDI can start using Qpid straight away. + </para> + + <!--h2--> + </section> + + <section role="h2" id="UsingQpidwithotherJNDIProviders-HowtocreateaTopicConnectionFactoryandQueueConnectionFactory"><title> + How to create a TopicConnectionFactory and + QueueConnectionFactory + </title> + <para> + AMQConnectionFactory implements TopicConnectionFactory and + QueueConnectionFactory as well as the ConnectionFactory. + </para> +<!--h3--> + </section> +<!--h2--> + </section> +</chapter> diff --git a/qpid/doc/book/src/old/WCF.xml b/qpid/doc/book/src/old/WCF.xml new file mode 100644 index 0000000000..aaf54463db --- /dev/null +++ b/qpid/doc/book/src/old/WCF.xml @@ -0,0 +1,137 @@ +<?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> + <title> + WCF + </title> + <section role="h1" id="WCF-Introduction"> + <title> + Introduction + </title> + + <para> + WCF (<emphasis>Windows Communication Foundation)</emphasis> unifies the .Net + communication capabilities into a single, common, general Web + service oriented framework. A good WCF tutorial can be found + <ulink url="http://www.netfxharmonics.com/2008/11/Understanding-WCF-Services-in-Silverlight-2#WCFSilverlightIntroduction">here</ulink>. + </para> + <para> + WCF separates how service logic is written from how services + communicate with clients. Bindings are used to specify the + transport, encoding, and protocol details required for clients + and services to communicate with each other. Qpid provide a WCF + binding: org.apache.qpid.wcf.model.QpidBinding. WCF Services that + use the Qpid binding communicate through queues that are + dynamically created on a Qpid broker. + </para> + <!--h1--> + </section> + <section role="h1" id="WCF-HowtouseQpidbinding"> + <title> + How to use Qpid binding + </title> + + <para> + WCF services are implemented using: + </para> + <itemizedlist> + <listitem> + <para>A service contract with one or more operation contracts. + </para> + </listitem> + <listitem> + <para>A service implementation for those contracts. + </para> + </listitem> + <listitem> + <para>A configuration file to provide that implementation with an + endpoint and a binding for that specific contract. + </para> + </listitem> + </itemizedlist> + <para> + The following configuration file can be used to configure a Hello + Service: + </para> + <programlisting> +<configuration> + <system.serviceModel> + <services> + <!-- the service class --> + <service name="org.apache.qpid.wcf.demo.HelloService"> + <host> + <baseAddresses> + <!-- Use SOAP over AMQP --> + <add baseAddress="soap.amqp:///" /> + </baseAddresses> + </host> + + <endpoint + address="Hello" + <!-- We use a Qpid Binding, see below def --> + binding="customBinding" + bindingConfiguration="QpidBinding" + <!-- The service contract --> + contract="org.apache.qpid.wcf.demo.IHelloContract"/> + </service> + </services> + + <bindings> + <customBinding> + <!-- cf def of the qpid binding --> + <binding name="QpidBinding"> + <textMessageEncoding /> + <!-- specify the host and port number of the broker --> + <QpidTransport + host="192.168.1.14" + port="5673" /> + </binding> + </customBinding> + </bindings> + + <extensions> + <bindingElementExtensions> + <!-- use Qpid binding element: org.apache.qpid.wcf.model.QpidTransportElement --> + <add + name="QpidTransport" + type="org.apache.qpid.wcf.model.QpidTransportElement, qpidWCFModel"/> + </bindingElementExtensions> + </extensions> + + </system.serviceModel> +</configuration> + </programlisting> + <para> + Endpoints and bindings can also be set within the service code: + </para> + <programlisting> +/* set HostName, portNumber and MyService accordingly */ +Binding binding = new QpidBinding("HostName", portNumber); +ServiceHost service = new ServiceHost(typeof(MyService), new Uri("soap.amqp:///")); +service.AddServiceEndpoint(typeof(IBooking), binding, "MyService"); +service.Open(); +.... + </programlisting> + <!--h1--> + </section> +</section> diff --git a/qpid/doc/book/src/old/schemas.xml b/qpid/doc/book/src/old/schemas.xml new file mode 100644 index 0000000000..6102e65f07 --- /dev/null +++ b/qpid/doc/book/src/old/schemas.xml @@ -0,0 +1,102 @@ +<?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. + +--> + +<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0"> + <uri resource="foo.xml" typeId="DocBook"/> + <uri resource="foo.xml" typeId="DocBook"/> + <uri resource="Programming-In-Apache-Qpid.xml" typeId="DocBook"/> + <uri resource="queue-state-replication.xml" typeId="DocBook"/> + <uri resource="AMQP-Messaging-Broker-Java-Book.xml" typeId="DocBook"/> + <uri resource="AMQP-Messaging-Broker-CPP-Book.xml" typeId="DocBook"/> + <uri resource="High-Level-API.xml" typeId="DocBook"/> + <uri resource="High-Level-API.xml" typeId="DocBook"/> + <uri resource="Java-JMS-Selector-Syntax.xml" typeId="DocBook"/> + <uri resource="ACL.xml" typeId="DocBook"/> + <uri resource="Add-New-Users.xml" typeId="DocBook"/> + <uri resource="AMQP-C++-Messaging-Client.xml" typeId="DocBook"/> + <uri resource="AMQP-Compatibility.xml" typeId="DocBook"/> + <uri resource="AMQP-Java-JMS-Messaging-Client.xml" typeId="DocBook"/> + <uri resource="AMQP-Messaging-Broker-CPP.xml" typeId="DocBook"/> + <uri resource="AMQP-Messaging-Broker-Java.xml" typeId="DocBook"/> + <uri resource="AMQP-.NET-Messaging-Client.xml" typeId="DocBook"/> + <uri resource="AMQP-Python-Messaging-Client.xml" typeId="DocBook"/> + <uri resource="AMQP-Ruby-Messaging-Client.xml" typeId="DocBook"/> + <uri resource="AMQP.xml" typeId="DocBook"/> + <uri resource="Binding-URL-Format.xml" typeId="DocBook"/> + <uri resource="Book-Info.xml" typeId="DocBook"/> + <uri resource="Book.xml" typeId="DocBook"/> + <uri resource="Broker-CPP.xml" typeId="DocBook"/> + <uri resource="Broker-Java.xml" typeId="DocBook"/> + <uri resource="Cheat-Sheet-for-configuring-Exchange-Options.xml" typeId="DocBook"/> + <uri resource="Cheat-Sheet-for-configuring-Queue-Options.xml" typeId="DocBook"/> + <uri resource="Clients.xml" typeId="DocBook"/> + <uri resource="Configure-ACLs.xml" typeId="DocBook"/> + <uri resource="Configure-Java-Qpid-to-use-a-SSL-connection.xml" typeId="DocBook"/> + <uri resource="Configure-Log4j-CompositeRolling-Appender.xml" typeId="DocBook"/> + <uri resource="Configure-the-Broker-via-config.xml.xml" typeId="DocBook"/> + <uri resource="Configure-the-Virtual-Hosts-via-virtualhosts.xml.xml" typeId="DocBook"/> + <uri resource="Configuring-Management-Users.xml" typeId="DocBook"/> + <uri resource="Configuring-Qpid-JMX-Management-Console.xml" typeId="DocBook"/> + <uri resource="Connection-URL-Format.xml" typeId="DocBook"/> + <uri resource="Debug-using-log4j.xml" typeId="DocBook"/> + <uri resource="Download.xml" typeId="DocBook"/> + <uri resource="Excel-AddIn.xml" typeId="DocBook"/> + <uri resource="FAQ.xml" typeId="DocBook"/> + <uri resource="foo.xml" typeId="DocBook"/> + <uri resource="f.xml" typeId="DocBook"/> + <uri resource="Getting-Started.xml" typeId="DocBook"/> + <uri resource="How-to-Tune-M3-Java-Broker-Performance.xml" typeId="DocBook"/> + <uri resource="How-to-Use-JNDI.xml" typeId="DocBook"/> + <uri resource="Introduction.xml" typeId="DocBook"/> + <uri resource="Java-Broker-Feature-Guide.xml" typeId="DocBook"/> + <uri resource="Java-Environment-Variables.xml" typeId="DocBook"/> + <uri resource="LVQ.xml" typeId="DocBook"/> + <uri resource="Management-Console-Security.xml" typeId="DocBook"/> + <uri resource="Management-Design-notes.xml" typeId="DocBook"/> + <uri resource="Managing-CPP-Broker.xml" typeId="DocBook"/> + <uri resource="MessageStore-Tool.xml" typeId="DocBook"/> + <uri resource="NET-User-Guide.xml" typeId="DocBook"/> + <uri resource="PythonBrokerTest.xml" typeId="DocBook"/> + <uri resource="QMan-Qpid-Management-bridge.xml" typeId="DocBook"/> + <uri resource="QMF-Python-Console-Tutorial.xml" typeId="DocBook"/> + <uri resource="Qpid-ACLs.xml" typeId="DocBook"/> + <uri resource="Qpid-Interoperability-Documentation.xml" typeId="DocBook"/> + <uri resource="Qpid-Java-Broker-Management-CLI.xml" typeId="DocBook"/> + <uri resource="Qpid-Java-Build-How-To.xml" typeId="DocBook"/> + <uri resource="Qpid-Java-FAQ.xml" typeId="DocBook"/> + <uri resource="Qpid-JMX-Management-Console-FAQ.xml" typeId="DocBook"/> + <uri resource="Qpid-JMX-Management-Console-User-Guide.xml" typeId="DocBook"/> + <uri resource="Qpid-JMX-Management-Console.xml" typeId="DocBook"/> + <uri resource="Qpid-Management-Features.xml" typeId="DocBook"/> + <uri resource="Qpid-Management-Framework.xml" typeId="DocBook"/> + <uri resource="Qpid-Troubleshooting-Guide.xml" typeId="DocBook"/> + <uri resource="queue-state-replication.xml" typeId="DocBook"/> + <uri resource="Running-CPP-Broker.xml" typeId="DocBook"/> + <uri resource="SASL-Compatibility.xml" typeId="DocBook"/> + <uri resource="SSL.xml" typeId="DocBook"/> + <uri resource="Active-Active-Cluster.xml" typeId="DocBook"/> + <uri resource="System-Properties.xml" typeId="DocBook"/> + <uri resource="Use-Priority-Queues.xml" typeId="DocBook"/> + <uri resource="Using-Broker-Federation.xml" typeId="DocBook"/> + <uri resource="Using-Qpid-with-other-JNDI-Providers.xml" typeId="DocBook"/> + <uri resource="WCF.xml" typeId="DocBook"/> +</locatingRules> |