NO-JIRA: Merge changes from trunk.

Command was:

svn merge https://svn.apache.org/repos/asf/qpid/trunk



git-svn-id: https://svn.apache.org/repos/asf/qpid/branches/java-broker-bdb-ha2@1581428 13f79535-47bb-0310-9956-ffa450edef68

5 files changed, 122 insertions, 108 deletions

diff --git a/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml b/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml
index 116fd8daef..6cb1b768ab 100644
--- a/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml
+++ b/qpid/doc/book/src/cpp-broker/Active-Passive-Cluster.xml
@@ -47,7 +47,7 @@ under the License.
     <para>
       This approach relies on an external <firstterm>cluster resource manager</firstterm>
       to detect failures, choose the new primary and handle network partitions. <ulink
-      url="https://fedorahosted.org/cluster/wiki/RGManager">Rgmanager</ulink> is supported
+      url="https://fedorahosted.org/cluster/wiki/RGManager">rgmanager</ulink> is supported
       initially, but others may be supported in the future.
     </para>
     <section id="ha-at-least-once">
@@ -81,7 +81,7 @@ under the License.
 	<footnote>
 	  <para>
 	  Clients must use "at-least-once" reliability to enable re-send of unacknowledged
-	  messages. This is the default behavior, no options need be set to enable it. For
+	  messages. This is the default behaviour, no options need be set to enable it. For
 	  details of client addressing options see &#34;Using the Qpid Messaging API&#34;
 	  in <citetitle>Programming in Apache Qpid</citetitle>.
 	  </para>
@@ -102,7 +102,7 @@ under the License.
       </para>
       <para>
 	When a new primary is promoted after a fail-over it is initially in
-	"recovering" mode. In this mode, it delays acknowledgment of messages
+	"recovering" mode. In this mode, it delays acknowledgement of messages
 	on behalf of all the backups that were connected to the previous
 	primary. This protects those messages against a failure of the new
 	primary until the backups have a chance to connect and catch up.
@@ -277,18 +277,15 @@ ssl_addr = "ssl:" host [":" port]'
 	    <entry><literal>ha-public-url <replaceable>URL</replaceable></literal> </entry>
 	    <entry>
 	      <para>
-		The URL <footnoteref linkend="ha-url-grammar"/> is advertised to
-		clients as the "known-hosts" for fail-over.  It can be a list or
-		a single virtual IP address. A virtual IP address is recommended.
+		This option is only needed for backwards compatibility if you
+		have been using the <literal>amq.failover</literal> exchange.
+		This exchange is now obsolete, it is recommended to use a
+		virtual IP address instead.
 	      </para>
 	      <para>
-		Using this option you can put client and broker traffic on
-		separate networks, which is recommended.
-	      </para>
-	      <para>
-		Note: When HA clustering is enabled the broker option
-		<literal>known-hosts-url</literal> is ignored and over-ridden by
-		the <literal>ha-public-url</literal> setting.
+		If set, this URL is advertized by the
+		<literal>amq.failover</literal> exchange and overrides the
+		broker option <literal>known-hosts-url</literal>
 	      </para>
 	    </entry>
 	  </row>
@@ -426,7 +423,7 @@ NOTE: fencing is not shown, you must configure fencing appropriately for your cl
 -->
 
 <cluster name="qpid-test" config_version="18">
-  <!-- The cluster has 3 nodes. Each has a unique nodid and one vote
+  <!-- The cluster has 3 nodes. Each has a unique nodeid and one vote
        for quorum. -->
   <clusternodes>
     <clusternode name="node1.example.com" nodeid="1"/>
@@ -498,20 +495,17 @@ NOTE: fencing is not shown, you must configure fencing appropriately for your cl
     </para>
     <para>
       The <literal>resources</literal> section also defines a virtual IP
-      address for clients.
+      address for clients: <literal>20.0.20.200</literal>.
     </para>
     <para>
-      To take advantage of the virtual IP addresses, <filename>qpidd.conf</filename>
-      should contain these  lines:
+      <filename>qpidd.conf</filename> should contain these  lines:
     </para>
     <programlisting>
       ha-cluster=yes
-      ha-public-url=20.0.10.200
       ha-brokers-url=20.0.20.1,20.0.20.2,20.0.20.3
     </programlisting>
     <para>
-      This configuration allows clients to connect to a single address:
-      20.0.10.200.  The brokers connect to each other directly via the addresses
+      The brokers connect to each other directly via the addresses
       listed in <command>ha-brokers-url</command>. Note the client and broker
       addresses are on separate sub-nets, this is recommended but not required.
     </para>
@@ -622,10 +616,7 @@ NOTE: fencing is not shown, you must configure fencing appropriately for your cl
     <para>
       Clients can only connect to the primary broker. Backup brokers reject any
       connection attempt by a client. Clients rejected by a backup broker will
-      automatically fail-over until they connect to the primary. if
-      <literal>ha-public-url</literal> contains multiple addresses, the client
-      will them all in rotation. If it is a virtual IP address the clients will
-      retry on the same address until it is reconnected.
+      automatically fail-over until they connect to the primary.
     </para>
     <para>
       Clients are configured with the URL for the cluster (details below for
@@ -704,10 +695,10 @@ NOTE: fencing is not shown, you must configure fencing appropriately for your cl
 	Heartbeats are disabled by default. You can enable them by specifying a
 	heartbeat interval (in seconds) for the connection via the
 	<literal>heartbeat</literal> option. For example:
-	<programlisting>
-	  qpid::messaging::Connection c("node1,node2,node3","{reconnect:true,heartbeat:10}");
-	</programlisting>
       </para>
+      <programlisting>
+	qpid::messaging::Connection c("node1,node2,node3","{reconnect:true,heartbeat:10}");
+      </programlisting>
     </section>
     <section id="ha-python-client">
       <title>Python clients</title>
@@ -886,6 +877,3 @@ NOTE: fencing is not shown, you must configure fencing appropriately for your cl
   </section>
 
 </section>
-
-<!-- LocalWords:  scalability rgmanager multicast RGManager mailto LVQ qpidd IP dequeued Transactional username API
--->
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Security-ACLs.xml b/qpid/doc/book/src/java-broker/Java-Broker-Security-ACLs.xml
index 03537115a4..bd0d543c05 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Security-ACLs.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Security-ACLs.xml
@@ -25,9 +25,7 @@
   <title>Access Control Lists</title>
   <para>
     In Qpid, Access Control Lists (ACLs) specify which actions can be performed by each authenticated user.
-    To enable, an <emphasis>Access Control Provider</emphasis> needs to be configured on the <emphasis>Broker</emphasis>
-    level or/and ACL configuration should be provided on a <emphasis>Virtual Host</emphasis> level.
-    The first imposes the ACL broker wide, and the second is applied to individual virtual hosts.
+    To enable, an <emphasis>Access Control Provider</emphasis> needs to be configured on the <emphasis>Broker</emphasis>.
     The <emphasis>Access Control Provider</emphasis> of type "AclFile" uses local file to specify the ACL rules.
     By convention, this file should have a .acl extension.
   </para>
@@ -41,12 +39,7 @@
 
   <para>Only one <emphasis>Access Control Provider</emphasis> can be used by the Broker.
     If several <emphasis>Access Control Providers</emphasis> are configured on Broker level
-    only one of them will be used (the latest one). <xref linkend="Java-Broker-Virtual-Hosts-Configuration-File-ACL"/>
-    shows how to configure ACL on <emphasis>Virtual Host</emphasis> using virtual host configuration xml.
-    If both Broker <emphasis>Access Control Provider</emphasis> and <emphasis>Virtual Host</emphasis> ACL are configured,
-    the <emphasis>Virtual Host</emphasis> ACL is used for authorization of operations on <emphasis>Virtual Host</emphasis> and
-    Virtual Host objects and Broker level ACL is used to authorization of operations on Broker and Broker children
-    (excluding Virtual Hosts having ACL configured).
+    only one of them will be used (the latest one).
   </para>
 
  <para>
@@ -114,6 +107,20 @@
       properties.  Most projects probably won't need this degree of flexibility.  A reasonable approach is to choose to apply permissions
       at a certain level of abstraction (e.g. QUEUE) and apply them consistently across the whole system.
     </para>
+    <note>
+        <para>
+        Some rules can be restricted to the virtual host if property virtualhost_name is specified.
+        <example>
+        <title>Restrict rules to specific virtual hosts</title>
+        <programlisting>
+      ACL ALLOW bob CREATE QUEUE virtualhost_name="test"
+      ACL ALLOW bob ALL EXCHANGE virtualhost_name="prod"
+    </programlisting>
+        </example>
+        In the example above the first rule allows user "bob" to create queues on virtual host "test" only.
+        The second rule allows user "bob" any action with exchanges on virtual host "prod".
+        </para>
+    </note>
   </section>
 
   <section role="h4" id="Java-Broker-Security-ACLs-Syntax">
@@ -125,7 +132,7 @@
        ACL rules follow this syntax:
     </para>
     <programlisting>
-     ACL {permission} {&lt;group-name&gt;|&lt;user-name>&gt;|ALL} {action|ALL} [object|ALL] [property="&lt;property-value&gt;"]
+     ACL {permission} {&lt;group-name&gt;|&lt;user-name&gt;|ALL} {action|ALL} [object|ALL] [property="&lt;property-value&gt;"]
     </programlisting>
 
     <para>
@@ -163,90 +170,144 @@
   </table>
   <table id="table-Java-Broker-Security-ACLs-Syntax_actions">
     <title>List of ACL actions</title>
-    <tgroup cols="2">
+    <tgroup cols="4">
+    <thead>
+        <row>
+          <entry><para>Action</para></entry>
+          <entry><para>Description</para></entry>
+          <entry><para>Supported object types</para></entry>
+          <entry><para>Supported properties</para></entry>
+        </row>
+      </thead>
       <tbody>
         <row>
           <entry> <command>CONSUME</command> </entry>
           <entry> <para> Applied when subscriptions are created </para> </entry>
+          <entry><para>QUEUE</para></entry>
+          <entry><para>name, autodelete, temporary, durable, exclusive, alternate, owner, virtualhost_name</para></entry>
         </row>
         <row>
           <entry> <command>PUBLISH</command> </entry>
           <entry> <para> Applied on a per message basis on publish message transfers</para> </entry>
+          <entry><para>EXCHANGE</para></entry>
+          <entry><para>name, routingkey, immediate, virtualhost_name</para></entry>
         </row>
         <row>
           <entry> <command>CREATE</command> </entry>
           <entry> <para> Applied when an object is created, such as bindings, queues, exchanges</para> </entry>
+          <entry><para>EXCHANGE, QUEUE, USER, GROUP</para></entry>
+          <entry><para>see properties on the corresponding object type</para></entry>
         </row>
         <row>
           <entry> <command>ACCESS</command> </entry>
           <entry> <para> Applied when an object is read or accessed</para> </entry>
+          <entry><para>VIRTUALHOST, MANAGEMENT</para></entry>
+          <entry><para>name (for VIRTUALHOST only)</para></entry>
         </row>
         <row>
           <entry> <command>BIND</command> </entry>
           <entry> <para> Applied when queues are bound to exchanges</para> </entry>
+          <entry><para>EXCHANGE</para></entry>
+          <entry><para>name, routingKey, queuename, virtualhost_name, temporary, durable</para></entry>
         </row>
         <row>
           <entry> <command>UNBIND</command> </entry>
           <entry> <para> Applied when queues are unbound from exchanges</para> </entry>
+          <entry><para>EXCHANGE</para></entry>
+          <entry><para>name, routingKey, queuename, virtualhost_name, temporary, durable</para></entry>
         </row>
         <row>
           <entry> <command>DELETE</command> </entry>
           <entry> <para> Applied when objects are deleted </para> </entry>
+          <entry><para>EXCHANGE, QUEUE, USER, GROUP</para></entry>
+          <entry><para>see properties on the corresponding object type</para></entry>
         </row>
         <row>
           <entry> <command>PURGE</command> </entry> <entry>
           <para>Applied when purge the contents of a queue</para> </entry>
+          <entry><para>QUEUE</para></entry>
+          <entry><para> </para></entry>
         </row>
         <row>
           <entry> <command>UPDATE</command> </entry>
           <entry> <para> Applied when an object is updated </para> </entry>
+          <entry><para>EXCHANGE, QUEUE, USER, GROUP</para></entry>
+          <entry><para>see EXCHANGE and QUEUE properties</para></entry>
         </row>
         <row>
           <entry> <command>CONFIGURE</command> </entry>
-          <entry> <para> Applied when an object is configured via REST management interfaces(Java Broker only).</para> </entry>
+          <entry> <para> Applied when an object is configured via REST management interfaces.</para> </entry>
+          <entry><para>BROKER</para></entry>
+          <entry><para> </para></entry>
+        </row>
+        <row>
+          <entry><command>ACCESS_LOGS</command> </entry>
+          <entry><para>Allows/denies to the specific user an operation to download broker log file(s) over REST interfaces</para> </entry>
+          <entry><para>BROKER</para></entry>
+          <entry><para> </para></entry>
         </row>
       </tbody>
     </tgroup>
   </table>
   <table id="table-Java-Broker-Security-ACLs-Syntax_objects">
     <title>List of ACL objects</title>
-    <tgroup cols="2">
+    <tgroup cols="4">
+      <thead>
+        <row>
+          <entry><para>Object type</para></entry>
+          <entry><para>Description</para></entry>
+          <entry><para>Supported actions</para></entry>
+          <entry><para>Supported properties</para></entry>
+        </row>
+      </thead>
       <tbody>
         <row>
           <entry> <command>VIRTUALHOST</command> </entry>
-          <entry> <para>A virtualhost (Java Broker only)</para> </entry>
+          <entry> <para>A virtualhost</para> </entry>
+          <entry><para>ALL, ACCESS</para> </entry>
+          <entry><para>name</para> </entry>
         </row>
         <row>
           <entry> <command>MANAGEMENT </command> </entry>
-          <entry> <para>Management - for web and JMX (Java Broker only)</para> </entry>
+          <entry> <para>Management - for web and JMX</para> </entry>
+          <entry><para>ALL, ACCESS</para> </entry>
+          <entry><para> </para></entry>
         </row>
         <row>
           <entry> <command>QUEUE</command> </entry>
           <entry> <para>A queue </para> </entry>
+          <entry><para>ALL, CREATE, DELETE, PURGE, CONSUME, UPDATE</para></entry>
+          <entry><para>name, autodelete, temporary, durable, exclusive, alternate, owner, virtualhost_name</para></entry>
         </row>
         <row>
           <entry> <command>EXCHANGE</command> </entry>
-        <entry> <para>An exchange </para> </entry>
+          <entry><para>An exchange</para></entry>
+          <entry><para>ALL, ACCESS, CREATE, DELETE, BIND, UNBIND, PUBLISH, UPDATE</para></entry>
+          <entry><para>name, autodelete, temporary, durable, type, virtualhost_name, queuename(only for BIND and UNBIND), routingkey(only for BIND and UNBIND, PUBLISH)</para></entry>
         </row>
         <row>
           <entry> <command>USER</command> </entry>
-          <entry> <para>A user (Java Broker only)</para> </entry>
+          <entry> <para>A user</para> </entry>
+          <entry><para>ALL, CREATE, DELETE, UPDATE</para></entry>
+          <entry><para>name</para></entry>
         </row>
         <row>
           <entry> <command>GROUP</command> </entry>
-          <entry> <para>A group (Java Broker only)</para> </entry>
+          <entry> <para>A group</para> </entry>
+          <entry><para>ALL, CREATE, DELETE, UPDATE</para></entry>
+          <entry><para>name</para></entry>
         </row>
         <row>
           <entry> <command>METHOD</command> </entry>
-          <entry> <para>Management or agent or broker method (Java Broker only)</para> </entry>
-        </row>
-        <row>
-          <entry> <command>LINK</command> </entry>
-          <entry> <para>A federation or inter-broker link (not currently used in Java Broker)</para> </entry>
+          <entry> <para>Management or agent or broker method</para> </entry>
+          <entry><para>ALL, ACCESS, UPDATE</para></entry>
+          <entry><para>name, component, virtualhost_name</para></entry>
         </row>
         <row>
           <entry> <command>BROKER</command> </entry>
           <entry> <para>The broker</para> </entry>
+          <entry><para>ALL, CONFIGURE, ACCESS_LOGS</para></entry>
+          <entry><para> </para></entry>
         </row>
       </tbody>
     </tgroup>
@@ -268,10 +329,6 @@
           <entry> <para> String. Specifies routing key </para> </entry>
         </row>
         <row>
-          <entry> <command>passive</command> </entry>
-          <entry> <para> Boolean. Indicates the presence of a <parameter>passive</parameter> flag </para> </entry>
-        </row>
-        <row>
           <entry> <command>autodelete</command> </entry>
           <entry> <para> Boolean. Indicates whether or not the object gets deleted when the connection is closed </para> </entry>
         </row>
@@ -297,15 +354,7 @@
         </row>
         <row>
           <entry> <command>component</command> </entry>
-          <entry> <para> String. JMX component name (Java Broker only)</para> </entry>
-        </row>
-        <row>
-          <entry> <command>schemapackage</command> </entry>
-          <entry> <para> String. QMF schema package name (Not used in Java Broker)</para> </entry>
-        </row>
-        <row>
-          <entry> <command>schemaclass</command> </entry>
-          <entry> <para> String. QMF schema class name (Not used in Java Broker)</para> </entry>
+          <entry> <para> String. JMX component name</para> </entry>
         </row>
         <row>
           <entry> <command>from_network</command> </entry>
@@ -322,9 +371,6 @@
               (e.g. 192.168.1.0/24; see <ulink url="http://tools.ietf.org/html/rfc4632">RFC 4632</ulink>)
               or wildcards (e.g. 192.169.1.*).
             </para>
-            <para>
-              Java Broker only.
-            </para>
           </entry>
         </row>
         <row>
@@ -354,8 +400,21 @@
               $JAVA_HOME/lib/security/java.security. The latter is preferred because it is JVM
               vendor-independent.
             </para>
+          </entry>
+        </row>
+        <row>
+          <entry><command>virtualhost_name</command></entry>
+          <entry>
             <para>
-              Java Broker only.
+              String. A name of virtual host to which the rule is applied.
+            </para>
+          </entry>
+        </row>
+        <row>
+          <entry><command>immediate</command></entry>
+          <entry>
+            <para>
+              Boolean. A property can be used to restrict PUBLISH action to publishing only messages with given immediate flag.
             </para>
           </entry>
         </row>
@@ -363,28 +422,24 @@
     </tgroup>
   </table>
   <table id="table-Java-Broker-Security-ACLs-Syntax_javacomponents">
-    <title>List of ACL rules</title>
-    <tgroup cols="3">
+    <title>List of ACL JMX Components</title>
+    <tgroup cols="2">
       <tbody>
         <row>
           <entry> <command>UserManagement</command> </entry>
           <entry> <para>User maintainance; create/delete/view users, change passwords etc</para> </entry>
-          <entry> <para>permissionable at broker level only</para> </entry>
         </row>
         <row>
           <entry> <command>ConfigurationManagement</command> </entry>
           <entry> <para>Dynammically reload configuration from disk.</para> </entry>
-          <entry> <para>permissionable at broker level only</para> </entry>
         </row>
         <row>
           <entry> <command>LoggingManagement</command> </entry>
           <entry> <para>Dynammically control Qpid logging level</para> </entry>
-          <entry> <para>permissionable at broker level only</para> </entry>
         </row>
         <row>
           <entry> <command>ServerInformation</command> </entry>
           <entry> <para>Read-only information regarding the Qpid: version number etc</para> </entry>
-          <entry> <para>permissionable at broker level only</para> </entry>
         </row>
         <row>
           <entry> <command>VirtualHost.Queue</command> </entry>
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts-Configuration.xml b/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts-Configuration.xml
index 6a4c8485e3..43007a3242 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts-Configuration.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts-Configuration.xml
@@ -43,36 +43,7 @@
     </para>
   </section>
 
-    <section id="Java-Broker-Virtual-Hosts-Configuration-File-ACL">
-        <title>Configuring ACL</title>
-        <para><xref linkend="Java-Broker-Security-ACLs"/> provides the details of ACL, rules, formats, etc.</para>
-        <para>
-        To apply an ACL on a single virtualhost named <replaceable>test</replaceable>, add the following to the virtualhosts.xml:
-        </para>
-
-        <programlisting>
-&lt;virtualhost&gt;
-...
-    &lt;name&gt;test&lt;/name&gt;
-    &lt;test&gt;
-      ...
-      &lt;security&gt;                          <co id="Java-Broker-Virtual-Hosts-Configuration-Security-ACL-1"/>
-        ...
-        &lt;acl&gt;<replaceable>${conf}/vhost_test.acl</replaceable>&lt;/acl&gt; <co  id="Java-Broker-Virtual-Hosts-Configuration-Security-ACL-2"/>
-        ...
-      &lt;/security&gt;
-      ...
-    &lt;/test&gt;
-&lt;/virtualhost&gt;
-        </programlisting>
-        <calloutlist>
-            <callout arearefs="Java-Broker-Virtual-Hosts-Configuration-Security-ACL-1"><para>A security section of configuration is used to declare the ACL</para></callout>
-            <callout arearefs="Java-Broker-Virtual-Hosts-Configuration-Security-ACL-2"><para>A path to an ACL file is configured (assuming that <replaceable>conf</replaceable> has been set to a suitable
-      location such as ${QPID_HOME}/etc)</para></callout>
-        </calloutlist>
-    </section>
-
-    <section role="h3" id="Java-Broker-Stores-Memory-Store-Configuration">
+  <section role="h3" id="Java-Broker-Stores-Memory-Store-Configuration">
         <title>Configuring MemoryMessageStore</title>
         <para>
         An example of MemoryMessageStore configuration for a virtual host is shown below:
diff --git a/qpid/doc/book/src/java-broker/commonEntities.xml b/qpid/doc/book/src/java-broker/commonEntities.xml
index 2e7a181d65..8dd3d61f55 100644
--- a/qpid/doc/book/src/java-broker/commonEntities.xml
+++ b/qpid/doc/book/src/java-broker/commonEntities.xml
@@ -22,7 +22,7 @@
 <!ENTITY qpidDownloadUrl "http://qpid.apache.org/download.html">
 <!ENTITY qpidCppBook "../../AMQP-Messaging-Broker-CPP-Book/html/">
 
-<!ENTITY qpidCurrentRelease "0.27">
+<!ENTITY qpidCurrentRelease "0.29">
 
 <!ENTITY windowsBrokerDownloadFileName "qpid-java-broker-&qpidCurrentRelease;.zip">
 <!ENTITY windowsExtractedBrokerDirName "qpid-broker-&qpidCurrentRelease;">
diff --git a/qpid/doc/book/src/jms-client-0-8/commonEntities.xml b/qpid/doc/book/src/jms-client-0-8/commonEntities.xml
index b3d1658fa8..d3247f0483 100644
--- a/qpid/doc/book/src/jms-client-0-8/commonEntities.xml
+++ b/qpid/doc/book/src/jms-client-0-8/commonEntities.xml
@@ -19,7 +19,7 @@
 
 -->
 
-<!ENTITY qpidVersion "0.27">
+<!ENTITY qpidVersion "0.29">
 <!ENTITY qpidDownloadUrlDesc "the Apache Qpid project web site">
 <!ENTITY qpidDownloadUrl "http://qpid.apache.org/download.html">