You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by kw...@apache.org on 2015/12/02 14:25:56 UTC
svn commit: r1717626 - in /qpid/java/trunk/doc/book/src/java-broker:
concepts/ images/ management/channels/ management/managing/
Author: kwall
Date: Wed Dec 2 13:25:56 2015
New Revision: 1717626
URL: http://svn.apache.org/viewvc?rev=1717626&view=rev
Log:
QPID-6805: [Java Broker Documentation] Replace REST API object table with link to /apidocs
Corrected a few other typos too and addressed some review comments from orudyy@apache.org
Modified:
qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Overview.xml
qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Queues.xml
qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhosts.xml
qpid/java/trunk/doc/book/src/java-broker/images/Broker-Model.png
qpid/java/trunk/doc/book/src/java-broker/images/VirtualHost-Model.png
qpid/java/trunk/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml
qpid/java/trunk/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Keystores.xml
qpid/java/trunk/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Ports.xml
Modified: qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Overview.xml
URL: http://svn.apache.org/viewvc/qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Overview.xml?rev=1717626&r1=1717625&r2=1717626&view=diff
==============================================================================
--- qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Overview.xml (original)
+++ qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Overview.xml Wed Dec 2 13:25:56 2015
@@ -67,7 +67,7 @@
</para>
<para>
<figure>
- <title>Broker Structure</title>
+ <title>Broker Structure showing major entities</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/Broker-Model.png" format="PNG" scalefit="1"/>
Modified: qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Queues.xml
URL: http://svn.apache.org/viewvc/qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Queues.xml?rev=1717626&r1=1717625&r2=1717626&view=diff
==============================================================================
--- qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Queues.xml (original)
+++ qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Queues.xml Wed Dec 2 13:25:56 2015
@@ -30,7 +30,8 @@
hold/buffer messages for later delivery to consumer applications. An <link
linkend="Java-Broker-Concepts-Exchanges">Exchange</link> for passing messages to a queue.
Consumers subscribe to a queue in order to receive messages for it. </para>
- <para>The Broker supports different queue types, each with different delivery semantics. It also supports messages on a queue to be treated as a group.</para>
+ <para>The Broker supports different queue types, each with different delivery semantics. Queues also have the ability to group messages
+ together for delivery to a single consumer.</para>
<section id="Java-Broker-Concepts-Queues-Types">
<title>Types</title>
<para>The Broker supports four different queue types, each with different delivery semantics.<itemizedlist>
Modified: qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhosts.xml
URL: http://svn.apache.org/viewvc/qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhosts.xml?rev=1717626&r1=1717625&r2=1717626&view=diff
==============================================================================
--- qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhosts.xml (original)
+++ qpid/java/trunk/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhosts.xml Wed Dec 2 13:25:56 2015
@@ -46,7 +46,7 @@
<para>A <emphasis>Consumer</emphasis> represents a live consumer that is attached to queue.</para>
<para><emphasis>Loggers</emphasis> are responsible for producing logs for this virtualhost.</para>
<para> The following diagram depicts the Virtualhost model: <figure>
- <title>Virtualhost Model</title>
+ <title>Virtualhost Model showing major entities</title>
<mediaobject>
<imageobject>
<imagedata fileref="images/VirtualHost-Model.png" format="PNG" scalefit="1"/>
Modified: qpid/java/trunk/doc/book/src/java-broker/images/Broker-Model.png
URL: http://svn.apache.org/viewvc/qpid/java/trunk/doc/book/src/java-broker/images/Broker-Model.png?rev=1717626&r1=1717625&r2=1717626&view=diff
==============================================================================
Binary files qpid/java/trunk/doc/book/src/java-broker/images/Broker-Model.png (original) and qpid/java/trunk/doc/book/src/java-broker/images/Broker-Model.png Wed Dec 2 13:25:56 2015 differ
Modified: qpid/java/trunk/doc/book/src/java-broker/images/VirtualHost-Model.png
URL: http://svn.apache.org/viewvc/qpid/java/trunk/doc/book/src/java-broker/images/VirtualHost-Model.png?rev=1717626&r1=1717625&r2=1717626&view=diff
==============================================================================
Binary files qpid/java/trunk/doc/book/src/java-broker/images/VirtualHost-Model.png (original) and qpid/java/trunk/doc/book/src/java-broker/images/VirtualHost-Model.png Wed Dec 2 13:25:56 2015 differ
Modified: qpid/java/trunk/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml
URL: http://svn.apache.org/viewvc/qpid/java/trunk/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml?rev=1717626&r1=1717625&r2=1717626&view=diff
==============================================================================
--- qpid/java/trunk/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml (original)
+++ qpid/java/trunk/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml Wed Dec 2 13:25:56 2015
@@ -22,364 +22,127 @@
<section id="Java-Broker-Management-Channel-REST-API">
<title>REST API</title>
- <para> This section provides a brief overview of the REST interfaces, which can be used directly to
- monitor and manage the Broker instance.</para>
-
<section id="Java-Broker-Management-Channel-REST-API-Introduction">
<title>Introduction</title>
- <para>The REST interface support traditional REST model which uses the GET method requests to
- retrieve the information about broker configured objects, DELETE method requests to delete the
- configured object, PUT to create or update the configured object and POST to perform the
- configured objects updates and creation.</para>
- <para>The REST API is versioned with the version number built into the URL. The general form of
- the URL is <literal>/api/<version></literal> where <version> is a major model version prefixed with "v", for example, v3.
- For convenience the alias <literal>latest</literal> (<literal>/api/latest</literal>) signifies the latest supported version.
- There are also some ancillary services under URI <literal>/service</literal>.</para>
- <para>The remainder of this section will assume you are using the <literal>/api/latest</literal> form.</para>
+ <para>This section describes the REST API provided by the Java Broker. The REST API is intended
+ for use by developers who wish to automate the management or monitoring of the Qpid Broker. It
+ is also very useful for adhoc monitoring on the command line using tools such as
+ <literal>curl</literal>.</para>
+ <para>The REST API provides access to all of the Broker's entities using hierarchical paths
+ expressed by the URI. Responses are returned in JSON format.</para>
+ <para>The <literal>GET</literal> method request retrieves information about an object, the
+ <literal>DELETE</literal> method requests the removal of one, and the <literal>PUT</literal>
+ or <literal>POST</literal> methods perform updates or create new objects. The
+ <literal>POST</literal> method is also used to invoke operations.</para>
+ <para>The REST API is versioned with the version number embedded withinthe URI. The general form
+ of the URI is <literal>/api/<version></literal> where <version> is a major model
+ version prefixed with "v", for example, v3. For convenience the alias
+ <literal>latest</literal> (<literal>/api/latest</literal>) signifies the latest supported
+ version.</para>
+ <para>There are also some ancillary services under URI <literal>/service</literal> used for
+ authentication and logout.</para>
</section>
-
- <section id="Java-Broker-Management-Channel-REST-API-URI">
- <title>REST interfaces</title>
- <para>The following REST interfaces are implemented on Qpid Broker</para>
- <table>
- <title>Rest services</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>REST Service URI</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <itemizedlist>
- <listitem><para>/api/latest/broker</para></listitem>
- </itemizedlist>
- </entry>
- <entry>
- <para>Manages broker instance attributes and provides current values of Broker attributes and children</para>
- </entry>
- </row>
- <row>
- <entry>
- <itemizedlist>
- <listitem><para>/api/latest/virtualhostnode</para></listitem>
- <listitem><para>/api/latest/virtualhostnode/<virtual host node name></para></listitem>
- </itemizedlist>
- </entry>
- <entry>
- <para>Manages(creates/deletes/updates) Virtual Host Node(s) on Broker and provides current values of Virtual Host Node attributes and its children</para>
- </entry>
- </row>
- <row>
- <entry>
- <itemizedlist>
- <listitem><para>/api/latest/virtualhost</para></listitem>
- <listitem><para>/api/latest/virtualhost/<virtual host node name></para></listitem>
- <listitem><para>/api/latest/virtualhost/<virtual host node name>/<virtual host name></para></listitem>
- </itemizedlist>
- </entry>
- <entry>
- <para>Manages(creates/deletes/updates) Virtual Host on Virtual Host Node and provides current values of Virtual Host attributes and its children</para>
- </entry>
- </row>
- <row>
- <entry>
- <itemizedlist>
- <listitem><para>/api/latest/queue</para></listitem>
- <listitem><para>/api/latest/queue/<virtual host node name></para></listitem>
- <listitem><para>/api/latest/queue/<virtual host node name>/<virtual host name></para></listitem>
- <listitem><para>/api/latest/queue/<virtual host node name>/<virtual host name>/<queue name></para></listitem>
- </itemizedlist>
- </entry>
- <entry>
- <para>Manages(creates/deletes/updates) Queue(s) on Virtual Host and provides current values of Queue attributes and its children</para>
- </entry>
- </row>
- <row>
- <entry>
- <itemizedlist>
- <listitem><para>/api/latest/exchange</para></listitem>
- <listitem><para>/api/latest/exchange/<virtual host node name></para></listitem>
- <listitem><para>/api/latest/exchange/<virtual host node name>/<virtual host name></para></listitem>
- <listitem><para>/api/latest/exchange/<virtual host node name>/<virtual host name>/<exchange name></para></listitem>
- </itemizedlist>
- </entry>
- <entry>
- <para>Manages(creates/deletes/updates) Exchanges(s) on Virtual Host and provides current values of Exchange attributes and its children</para>
- </entry>
- </row>
- <row>
- <entry>
- <itemizedlist>
- <listitem><para>/api/latest/binding</para></listitem>
- <listitem><para>/api/latest/binding/<virtual host node name></para></listitem>
- <listitem><para>/api/latest/binding/<virtual host node name>/<virtual host name></para></listitem>
- <listitem><para>/api/latest/binding/<virtual host node name>/<virtual host name>/<exchange name></para></listitem>
- <listitem><para>/api/latest/binding/<virtual host node name>/<virtual host name>/<exchange name>/<queue name>/<binding name></para></listitem>
- </itemizedlist>
- </entry>
- <entry>
- <para>Manages(creates/deletes) Binding(s) of Queue to Exchange and provides current values of Binding attributes</para>
- </entry>
- </row>
- <row>
- <entry>
- <itemizedlist>
- <listitem><para>/api/latest/connection</para></listitem>
- <listitem><para>/api/latest/connection/<connection name></para></listitem>
- </itemizedlist>
- </entry>
- <entry>
- <para>Manages (deletes) AMQP Connection(s) and provides current values of Connection attributes and its Sessions</para>
- </entry>
- </row>
- <row>
- <entry>
- <itemizedlist>
- <listitem><para>/api/latest/session</para></listitem>
- <listitem><para>/api/latest/session/<connection name></para></listitem>
- <listitem><para>/api/latest/session/<connection name>/<session name></para></listitem>
- </itemizedlist>
- </entry>
- <entry>
- <para>Manages (deletes) Session(s) on Connection and provides values of Session attributes and its Consumers</para>
- </entry>
- </row>
- <row>
- <entry>
- <itemizedlist>
- <listitem><para>/api/latest/port</para></listitem>
- <listitem><para>/api/latest/port/<port name></para></listitem>
- </itemizedlist>
- </entry>
- <entry>
- <para>Manages(creates/deletes/updates) Port(s) on Broker and provides the information about current values of Port attributes and its children</para>
- </entry>
- </row>
- <row>
- <entry>
- <itemizedlist>
- <listitem><para>/api/latest/authenticationprovider</para></listitem>
- <listitem><para>/api/latest/authenticationprovider/<authentication provider name></para></listitem>
- </itemizedlist>
- </entry>
- <entry>
- <para>Manages(creates/deletes/updates) AuthenticationProvider(s) on Broker and provides the information about current values of AuthenticationProvider attributes and its children</para>
- </entry>
- </row>
- <row>
- <entry>
- <itemizedlist>
- <listitem><para>/api/latest/user</para></listitem>
- <listitem><para>/api/latest/user/<authentication provider name>/<user name></para></listitem>
- <listitem><para>/api/latest/user/<authentication provider name>/<user name></para></listitem>
- </itemizedlist>
- </entry>
- <entry>
- <para>Manages(creates/deletes/updates) User(s) on AuthenticationProvider and provides the information about current values of User attributes</para>
- </entry>
- </row>
- <row>
- <entry>
- <itemizedlist>
- <listitem><para>/api/latest/accesscontrolprovider</para></listitem>
- <listitem><para>/api/latest/accesscontrolprovider/<access control provider name></para></listitem>
- </itemizedlist>
- </entry>
- <entry>
- <para>Manages(creates/deletes/updates) AccessControlProvider on Broker and provides the information about current values of AccessControlProvider attributes</para>
- </entry>
- </row>
- <row>
- <entry>
- <itemizedlist>
- <listitem><para>/api/latest/groupprovider</para></listitem>
- <listitem><para>/api/latest/groupprovider/<group provider name></para></listitem>
- </itemizedlist>
- </entry>
- <entry>
- <para>Manages(creates/deletes/updates) GroupProvider on Broker and provides the information about current values of GroupProvider attributes and its children</para>
- </entry>
- </row>
- <row>
- <entry>
- <itemizedlist>
- <listitem><para>/api/latest/group</para></listitem>
- <listitem><para>/api/latest/group/<group provider name></para></listitem>
- <listitem><para>/api/latest/group/<group provider name>/<group name></para></listitem>
- </itemizedlist>
- </entry>
- <entry>
- <para>Manages(creates/deletes/updates) Group on GroupProvider and provides the information about current values of Group attributes and its children</para>
- </entry>
- </row>
- <row>
- <entry>
- <itemizedlist>
- <listitem><para>/api/latest/groupmember</para></listitem>
- <listitem><para>/api/latest/groupmember/<group provider name></para></listitem>
- <listitem><para>/api/latest/groupmember/<group provider name>/<group name></para></listitem>
- <listitem><para>/api/latest/groupmember/<group provider name>/<group name>/<user name></para></listitem>
- </itemizedlist>
- </entry>
- <entry>
- <para>Manages(creates/deletes) GroupMember(s) on Group and provides the information about current values of GroupMember attributes</para>
- </entry>
- </row>
- <row>
- <entry>
- <itemizedlist>
- <listitem><para>/api/latest/keystore</para></listitem>
- <listitem><para>/api/latest/keystore/<key store name></para></listitem>
- </itemizedlist>
- </entry>
- <entry>
- <para>Manages(creates/deletes/updates) KeyStore(s) on Broker and provides the information about current values of KeyStore attributes</para>
- </entry>
- </row>
- <row>
- <entry>
- <itemizedlist>
- <listitem><para>/api/latest/truststore</para></listitem>
- <listitem><para>/api/latest/truststore/<trust store name></para></listitem>
- </itemizedlist>
- </entry>
- <entry>
- <para>Manages(creates/deletes/updates) TrustStore(s) on Broker and provides the information about current values of TrustStore attributes</para>
- </entry>
- </row>
- <row>
- <entry>
- <itemizedlist>
- <listitem><para>/api/latest/preferencesprovider</para></listitem>
-= <listitem><para>/api/latest/preferencesprovider/<authentication provider name></para></listitem>
- <listitem><para>/api/latest/preferencesprovider/<authentication provider name>/<preferences provider name></para></listitem>
- </itemizedlist>
- </entry>
- <entry>
- <para>Manages(creates/deletes/updates) PreferencesProvider on AuthenticationProvider and provides the information about current values of PreferencesProvider attributes</para>
- </entry>
- </row>
- <row>
- <entry>
- <itemizedlist>
- <listitem><para>/api/latest/plugin</para></listitem>
- <listitem><para>/api/latest/plugin/<plugin name></para></listitem>
- </itemizedlist>
- </entry>
- <entry>
- <para>Manages(creates/deletes/updates) Plugin(s) on Broker and provides the information about current values of Plugin attributes</para>
- </entry>
- </row>
- <row>
- <entry>
- <itemizedlist>
- <listitem><para>/api/latest/remotereplicationnode</para></listitem>
- <listitem><para>/api/latest/remotereplicationnode/<virtual host node name></para></listitem>
- <listitem><para>/api/latest/remotereplicationnode/<virtual host node name>/<replication node name></para></listitem>
- </itemizedlist>
- </entry>
- <entry>
- <para>Manages(creates/deletes/updates) RemoteReplicationNode(s) on VirtualHostNode and provides the information about current values of RemoteReplicationNode attributes</para>
- </entry>
- </row>
- <row>
- <entry>
- <itemizedlist>
- <listitem><para>/api/latest/(broker|virtualhost)logger</para></listitem>
- <listitem><para>/api/latest/(broker|virtualhost)logger/<logger name></para></listitem>
- </itemizedlist>
- </entry>
- <entry>
- <para>Manages(creates/deletes/updates) Broker or Virtualhost Loggers(s) and provides the information about current values of the attributes. Some implementations have operations
- that allow the names of log files and log content to be retrieved.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>/service/sasl</para>
- </entry>
- <entry>Sasl authentication. Retrieves user current authentication status and broker supported SASL mechanisms (GET). Authenticates user using supported SASL mechanisms (PUT requests)</entry>
- </row>
- <row>
- <entry>
- <para>/service/logout</para>
- </entry>
- <entry>Log outs user (GET only)</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ <section id="Java-Broker-Management-Channel-REST-API-APIDocs">
+ <title>REST API documentation</title>
+ <para>REST API documentation is available on-line from any Java Broker at location
+ <literal>/apidocs</literal>. It is also linked from the menu of the Web Management Console.
+ </para>
+ </section>
+ <section id="Java-Broker-Management-Channel-REST-API-Authentication">
+ <title>Authentication</title>
+ <para>Before you can use the REST API, you must authenticate. Authentication decisions are made
+ by the <link linkend="Java-Broker-Concepts-Authentication-Providers">authentication
+ provider</link> associated with HTTP <link linkend="Java-Broker-Concepts-Ports">port</link>
+ on which you connect.</para>
+ <para>You may authenticate using <ulink url="https://www.ietf.org/rfc/rfc4422.txt">SASL</ulink>
+ (<literal>/service/sasl</literal>) or <ulink url="https://tools.ietf.org/html/rfc2617">HTTP
+ Basic Authentication</ulink>. The latter is convienent when using tools such as
+ <literal>curl</literal> on the command line. This is illustrated in the examples
+ below.</para>
+ <para>For SASL authentication use a <literal>GET</literal> request to
+ <literal>/service/sasl</literal> to get a list of supported SASL mechanisms, and use
+ <literal>PUT</literal> to the same URL to perform the SASL negotiation.</para>
+ <para>It is possible to end an authenticated session using
+ <literal>/service/logout</literal>.</para>
</section>
<section id="Java-Broker-Management-Channel-REST-API-Create">
<title>Configured Object creation</title>
<para>Methods PUT or POST can be used to create ConfiguredObject.</para>
- <para>
- ConfiguredObject can be created by submitting PUT request against ConfiguredObject full URI (the one ending with configured object name)
- or by submitting PUT/POST request against parent URI.
- The request encoding should be json (application/json) and request body should contain attributes values in json format.
- On successful completion of operation a response should be returned having response status code set to 201 and response header "Location" set to ConfiguredObject full URI.
- If object with a such name/id already exist and POST/PUT requests is made against parent URI,
- an error response should be returned having response code 409 (conflict) and body containing the json with the reason of operation failure.
- If object with a such name/id already exist and and PUT request is made against ConfiguredObject full URI,
- then ConfiguredObject update should be performed and http status code 200 should be returned.
- If ConfiguredObject cannot be created because of validation failure(s) the response should have http status code set 422 (Unprocessible Entity)
- and body should contain json with the reason of operation failure. On any other failure to create ConfiguredObject the response should have status code set to 400 (Bad Request)
- and payload should contain a json with error explaining the exact reason of failure.
- </para>
+ <para> ConfiguredObject can be created by submitting PUT request against ConfiguredObject full
+ URI (the one ending with configured object name) or by submitting PUT/POST request against
+ parent URI. The request encoding should be json (application/json) and request body should
+ contain attributes values in json format. On successful completion of operation a response
+ should be returned having response status code set to 201 and response header "Location" set
+ to ConfiguredObject full URI. If object with a such name/id already exist and POST/PUT
+ requests is made against parent URI, an error response should be returned having response code
+ 409 (conflict) and body containing the json with the reason of operation failure. If object
+ with a such name/id already exist and and PUT request is made against ConfiguredObject full
+ URI, then ConfiguredObject update should be performed and http status code 200 should be
+ returned. If ConfiguredObject cannot be created because of validation failure(s) the response
+ should have http status code set 422 (Unprocessible Entity) and body should contain json with
+ the reason of operation failure. On any other failure to create ConfiguredObject the response
+ should have status code set to 400 (Bad Request) and payload should contain a json with error
+ explaining the exact reason of failure. </para>
<example>
<title>Examples of REST calls for Queue creation</title>
- <para>
- To create Queue with name "my-queue" on a virtual host with name "vh" (which is contained within virtual host node with name "vhn") either of the following requests should be made:
- </para>
+ <para> To create Queue with name "my-queue" on a virtual host with name "vh" (which is
+ contained within virtual host node with name "vhn") either of the following requests should
+ be made: </para>
<screen><![CDATA[PUT /api/latest/queue/vhn/vh HTTP/1.1]]></screen>
<screen><![CDATA[POST /api/latest/queue/vhn/vh HTTP/1.1]]></screen>
<screen><![CDATA[PUT /api/latest/queue/vhn/vh/my-queue HTTP/1.1]]></screen>
- <para>
- Response code 201 should be returned on successful queue creation. Response header "Location" should be set to "/api/latest/queue/test/my-queue".
- If queue with name "my-queue" already exists and either of 2 first requests above were used, an error response with response code 409 (conflict) and body containing json with message
- that queue exists should be returned. If queue with name "my-queue" exists and last request is used, then Queue update should occur.
- </para>
+ <para> Response code 201 should be returned on successful queue creation. Response header
+ "Location" should be set to "/api/latest/queue/test/my-queue". If queue with name "my-queue"
+ already exists and either of 2 first requests above were used, an error response with
+ response code 409 (conflict) and body containing json with message that queue exists should
+ be returned. If queue with name "my-queue" exists and last request is used, then Queue
+ update should occur. </para>
</example>
</section>
<section id="Java-Broker-Management-Channel-REST-API-Update">
<title>Configured Object update</title>
<para>Methods PUT or POST can be used to update ConfiguredObject.</para>
- <para>
- ConfiguredObject can be updated by submitting PUT or POST request against ConfiguredObject full URI (the one ending with configured object name).
- The request encoding should be json (application/json) and request body should contain a ConfiguredObject json (with all or only modified attributes).
- On successful completion of operation a response code 200 should be returned.
- If ConfiguredObject does not exists and PUT method is used, such object should be created (201 response will be returned in this case).
- If ConfiguredObject does not exists and POST method is used, an error response should be returned having response status code 404 and payload with json explaining the problem.
- If any error occur on update, a response with response code 400 or 422 or 404 should be sent back to the client containing json body with error details.
- </para>
+ <para> ConfiguredObject can be updated by submitting PUT or POST request against
+ ConfiguredObject full URI (the one ending with configured object name). The request encoding
+ should be json (application/json) and request body should contain a ConfiguredObject json
+ (with all or only modified attributes). On successful completion of operation a response code
+ 200 should be returned. If ConfiguredObject does not exists and PUT method is used, such
+ object should be created (201 response will be returned in this case). If ConfiguredObject
+ does not exists and POST method is used, an error response should be returned having response
+ status code 404 and payload with json explaining the problem. If any error occur on update, a
+ response with response code 400 or 422 or 404 should be sent back to the client containing
+ json body with error details. </para>
<example>
<title>Examples of REST calls for Queue update</title>
- <para>To update Queue with name "my-queue" on a virtual host with name "vh" (contained in virtual host node with name "vhn") either of the following requests can be made:</para>
+ <para>To update Queue with name "my-queue" on a virtual host with name "vh" (contained in
+ virtual host node with name "vhn") either of the following requests can be made:</para>
<screen><![CDATA[POST /api/latest/queue/vhn/vh/my-queue HTTP/1.1]]></screen>
<screen><![CDATA[POST /api/latest/queue/vhn/vh/my-queue HTTP/1.1]]></screen>
</example>
</section>
<section id="Java-Broker-Management-Channel-REST-API-Delete">
<title>Configured Object deletion</title>
- <para>Method DELETE can be used to delete ConfiguredObject. Alternatively, ConfiguredObject can be deleted with update request having desiredState attribute set to value "DELETED".
- POST or PUT methods can be used in this case.</para>
+ <para>Method DELETE can be used to delete ConfiguredObject. Alternatively, ConfiguredObject can
+ be deleted with update request having desiredState attribute set to value "DELETED". POST or
+ PUT methods can be used in this case.</para>
<para>On successful completion of operation a response code 200 should be returned.</para>
<para>With DELETE method object ConfiguredObject in following ways:</para>
<itemizedlist>
<listitem>
- <para>by submitting DELETE request using ConfiguredObject full URI (the one ending with configured object name)</para>
+ <para>by submitting DELETE request using ConfiguredObject full URI (the one ending with
+ configured object name)</para>
</listitem>
<listitem>
- <para>by submitting DELETE request using parent URI and providing parameters having the same names as children attributes, for example, id, name, etc.
- Multiple children can be deleted in a such way. Many "id" parameters can be specified in such requests. Only children with matching attribute values will be deleted.</para>
+ <para>by submitting DELETE request using parent URI and providing parameters having the same
+ names as children attributes, for example, id, name, etc. Multiple children can be deleted
+ in a such way. Many "id" parameters can be specified in such requests. Only children with
+ matching attribute values will be deleted.</para>
</listitem>
</itemizedlist>
<example>
<title>Examples of REST calls for Queue deletion</title>
- <para>To delete Queue with name "my-queue" on a virtual host with name "vh" (contained in virtual host node with name "vhn") either of the following requests can be made:</para>
+ <para>To delete Queue with name "my-queue" on a virtual host with name "vh" (contained in
+ virtual host node with name "vhn") either of the following requests can be made:</para>
<screen><![CDATA[DELETE /api/latest/queue/vhn/vh/my-queue HTTP/1.1]]></screen>
<screen><![CDATA[DELETE /api/latest/queue/vhn/vh?name=my-queue HTTP/1.1]]></screen>
<screen><![CDATA[DELETE /api/latest/queue/vhn/vh?id=real-queue-id HTTP/1.1]]></screen>
@@ -387,21 +150,24 @@
</section>
<section id="Java-Broker-Management-Channel-REST-API-Get">
<title>Retrieving Configured Object details</title>
- <para>Method GET is used to retrieve ConfiguredObject attributes values and children hierarchy.</para>
- <para>A particular ConfiguredObject details can be retrieved using full ConfiguredObject URI (the one ending with configured object name)</para>
- <para>A collection of ConfiguredObjects can be retrieved using parent URI. Request parameters
- (having the same name as attributes) can be used to filter the returned configured objects.</para>
- <para>The REST URI (/api/latest/>category</*) are hierarchical. It is permitted to replace REST URI elements with an
- "asterisks" in GET requests to denote all object of a particular type. Additionally, trailing
- object type in the URL hierarchy can be omitted. In this case GET request will return all of the
- object underneath of the current object.</para>
+ <para>Method GET is used to retrieve ConfiguredObject attributes values and children
+ hierarchy.</para>
+ <para>A particular ConfiguredObject details can be retrieved using full ConfiguredObject URI
+ (the one ending with configured object name)</para>
+ <para>A collection of ConfiguredObjects can be retrieved using parent URI. Request parameters
+ (having the same name as attributes) can be used to filter the returned configured
+ objects.</para>
+ <para>The REST URI (/api/latest/>category</*) are hierarchical. It is permitted to replace
+ REST URI elements with an "asterisks" in GET requests to denote all object of a particular
+ type. Additionally, trailing object type in the URL hierarchy can be omitted. In this case GET
+ request will return all of the object underneath of the current object.</para>
<para>For example, for binding URL <literal>http://localhost:8080/api/latest/binding/<vhost
node>/<vhost>/<exchange>/<queue>/<binding></literal> replacing of
- <literal><exchange></literal> with "asterisks"
- (<literal>http://localhost:8080/api/<ver>/binding/<vhost
+ <literal><exchange></literal> with "asterisks"
+ (<literal>http://localhost:8080/api/<ver>/binding/<vhost
node>/<vhost>/*/<queue>/<binding></literal>) will result in the GET
- response containing the list of bindings for all of the exchanges in the virtualhost having the
- given name and given queue.</para>
+ response containing the list of bindings for all of the exchanges in the virtualhost having
+ the given name and given queue.</para>
<para>If <literal><binding></literal> and <literal><queue></literal> are omitted in
binding REST URL (<literal>http://localhost:8080/api/<ver>/binding/<vhost
node>/<vhost>/<exchangename></literal>) the GET request will result in
@@ -409,31 +175,49 @@
<para>Additional parameters supported in GET requests:</para>
<variablelist>
<varlistentry>
- <term>depth</term><listitem><para>To restrict the depth of hierarchy of configured objects to return in response</para></listitem>
+ <term>depth</term>
+ <listitem>
+ <para>To restrict the depth of hierarchy of configured objects to return in
+ response</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term>actuals</term><listitem><para>If set to "true" attribute actual values are returned instead of effective</para></listitem>
+ <term>actuals</term>
+ <listitem>
+ <para>If set to "true" attribute actual values are returned instead of effective</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term>includeSysContext</term><listitem><para>If set to "true" all system context variables are returned</para></listitem>
+ <term>includeSysContext</term>
+ <listitem>
+ <para>If set to "true" all system context variables are returned</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term>inheritedActuals</term><listitem><para>If set to "true" actual values for all inherited context is returned.</para></listitem>
+ <term>inheritedActuals</term>
+ <listitem>
+ <para>If set to "true" actual values for all inherited context is returned.</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term>oversize</term><listitem><para>Sets the maximum length for values of over-sized attributes to trim</para></listitem>
+ <term>oversize</term>
+ <listitem>
+ <para>Sets the maximum length for values of over-sized attributes to trim</para>
+ </listitem>
</varlistentry>
<varlistentry>
- <term>extractInitialConfig</term><listitem><para>If set to "true", the returned json can be used as initial configuration.</para></listitem>
+ <term>extractInitialConfig</term>
+ <listitem>
+ <para>If set to "true", the returned json can be used as initial configuration.</para>
+ </listitem>
</varlistentry>
</variablelist>
</section>
<section id="Java-Broker-Management-Channel-REST-API-Operations">
<title>Configured Object operations</title>
- <para>Method POST is used to invoke Configured Objects operations. Some operations
- support parameters. Pass parameters using a JSON request body containing a map with
- a map entry for each parameter.
- </para>
+ <para>Method POST is used to invoke Configured Objects operations. Some operations support
+ parameters. Pass parameters using a JSON request body containing a map with a map entry for
+ each parameter. </para>
<example>
<title>Example of REST call to invoke the Queue clear queue operation</title>
<para>To clear the queue with name "my-queue" on a virtual host with name "vh".</para>
@@ -443,269 +227,121 @@
<section id="Java-Broker-Management-Channel-REST-API-Status-Codes">
<title>HTTP status codes returned by REST interfaces</title>
<table>
- <title>HTTP status codes returned by REST interfaces</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Status code</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para>200</para>
- </entry>
- <entry>
- <para>REST request is successfully completed. This status code can be returned by update, delete and get requests.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>201</para>
- </entry>
- <entry>
- <para>New configured object is created. It is returned by REST PUT and POST requests for creation of configured objects.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>400</para>
- </entry>
- <entry>
- <para>REST request cannot be performed due to errors in request.
- It can be returned from create, update and delete requests.
- The details of a problem are provided in the response payload in json format.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>401</para>
- </entry>
- <entry>
- <para>The request requires user authentication</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>403</para>
- </entry>
- <entry>
- <para>Execution of request is not allowed due to failure to authorize user operation.</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>404</para>
- </entry>
- <entry>
- <para>
- The requested configured object cannot be found. This status code can be returned from POST update requests if configured object does not exist.
- The reason for the status code is provided in the response payload in json format.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>409</para>
- </entry>
- <entry>
- <para>The request can not be performed because its execution can create conflicts in the broker.
- This status code can be returned from POST/PUT create requests against parent URI if configured object with requested name or id already exists.
- The status code 409 can also be returned if removal or update of configured object can violate system integrity.
- The reason for the status code is provided in the response payload in json format.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>422</para>
- </entry>
- <entry>
- <para>The request can not be performed because provided information either incomplete or invalid.
- This status code can be returned from create or update requests.
- The reason for the status code is provided in the response payload in json format.</para>
- </entry>
- </row>
- </tbody>
- </tgroup>
+ <title>HTTP status codes returned by REST interfaces</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Status code</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>200</para>
+ </entry>
+ <entry>
+ <para>REST request is successfully completed. This status code can be returned by
+ update, delete and get requests.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>201</para>
+ </entry>
+ <entry>
+ <para>New configured object is created. It is returned by REST PUT and POST requests
+ for creation of configured objects.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>400</para>
+ </entry>
+ <entry>
+ <para>REST request cannot be performed due to errors in request. It can be returned
+ from create, update and delete requests. The details of a problem are provided in
+ the response payload in json format.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>401</para>
+ </entry>
+ <entry>
+ <para>The request requires user authentication</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>403</para>
+ </entry>
+ <entry>
+ <para>Execution of request is not allowed due to failure to authorize user
+ operation.</para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>404</para>
+ </entry>
+ <entry>
+ <para> The requested configured object cannot be found. This status code can be
+ returned from POST update requests if configured object does not exist. The reason
+ for the status code is provided in the response payload in json format. </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>409</para>
+ </entry>
+ <entry>
+ <para>The request can not be performed because its execution can create conflicts in
+ the broker. This status code can be returned from POST/PUT create requests against
+ parent URI if configured object with requested name or id already exists. The status
+ code 409 can also be returned if removal or update of configured object can violate
+ system integrity. The reason for the status code is provided in the response payload
+ in json format. </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>422</para>
+ </entry>
+ <entry>
+ <para>The request can not be performed because provided information either incomplete
+ or invalid. This status code can be returned from create or update requests. The
+ reason for the status code is provided in the response payload in json
+ format.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
</table>
</section>
<section id="Java-Broker-Management-Channel-REST-API-Examples">
<title>Examples of REST requests with curl</title>
- <example>
- <title>Examples of queue creation using curl (authenticating as user admin):</title>
- <programlisting><![CDATA[
+ <example>
+ <title>Examples of queue creation using curl (authenticating as user admin):</title>
+ <programlisting><![CDATA[
#create a durable queue
curl --user admin -X PUT -d '{"durable":true}' http://localhost:8080/api/latest/queue/<vhostnode name>/<vhostname>/<queuename>
#create a durable priority queue
curl --user admin -X PUT -d '{"durable":true,"type":"priority"}' http://localhost:8080/api/latest/queue/<vhostnode name>/<vhostname>/<queuename>
]]></programlisting>
- </example>
- <example>
- <title>Example of binding a queue to an exchange using curl</title>
- <programlisting><![CDATA[
+ </example>
+ <example>
+ <title>Example of binding a queue to an exchange using curl</title>
+ <programlisting><![CDATA[
curl --user admin -X PUT -d '{}' http://localhost:8080/api/latest/binding/<vhostnode name>/<vhostname>/<exchangename>/<queue-name>/<binding-name>
]]></programlisting>
- </example>
- <para> NOTE: These curl examples utilise unsecure HTTP transport. To use the examples it is first
- necessary enable Basic authentication for HTTP within the HTTP Management Configuration (it is
- off by default). For details see <xref linkend="Java-Broker-Management-Managing-Plugin-HTTP"/>
- </para>
+ </example>
+ <para> NOTE: These curl examples utilise unsecure HTTP transport. To use the examples it is
+ first necessary enable Basic authentication for HTTP within the HTTP Management Configuration
+ (it is off by default). For details see <xref
+ linkend="Java-Broker-Management-Managing-Plugin-HTTP"/>
+ </para>
</section>
- <section id="Java-Broker-Management-Channel-REST-API-Docs">
- <title>Web interfaces with REST API Documentation</title>
- <para>Java Broker provides auxiliary web interfaces containing basic description of available REST services and their attributes.</para>
- <para>Such services are available under /apidocs/* and can be accessed by authenticated users.</para>
- <table>
- <title>Rest services documentation</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>REST Service URI</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <para>/api/latest/broker</para>
- </entry>
- <entry>
- <para>Provides information about Broker REST interfaces</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>/api/latest/virtualhostnode</para>
- </entry>
- <entry>
- <para>Provides information about Virtual Host Node attributes and types</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>/api/latest/virtualhost</para>
- </entry>
- <entry>
- <para>Provides information about Virtual Host Node attributes and types</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>/api/latest/port</para>
- </entry>
- <entry>
- <para>Provides information about Port attributes and types</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>/api/latest/authenticationprovider</para>
- </entry>
- <entry>
- <para>Provides information about Authentication Provider attributes and types</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>/api/latest/accesscontrolprovider</para>
- </entry>
- <entry>
- <para>Provides information about Access Control Provider attributes and types</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>/api/latest/keystore</para>
- </entry>
- <entry>
- <para>Provides information about Keystore attributes and types</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>/api/latest/truststore</para>
- </entry>
- <entry>
- <para>Provides information about Truststore attributes and types</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>/api/latest/queue</para>
- </entry>
- <entry>
- <para>Provides information about Queue attributes and types</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>/api/latest/exchange</para>
- </entry>
- <entry>
- <para>Provides information about Exchange attributes and types</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>/api/latest/binding</para>
- </entry>
- <entry>
- <para>Provides information about Binding attributes and types</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>/api/latest/groupprovider</para>
- </entry>
- <entry>
- <para>Provides information about Group Provider attributes and types</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>/api/latest/brokerlogger</para>
- </entry>
- <entry>
- <para>Provides information about Broker Logger attributes and types</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>/api/latest/virtualhostlogger</para>
- </entry>
- <entry>
- <para>Provides information about Virtual Host Logger attributes and types</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>/api/latest/group</para>
- </entry>
- <entry>
- <para>Provides information about Group attributes and types</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>/api/latest/groupmember</para>
- </entry>
- <entry>
- <para>Provides information about Group Member attributes and types</para>
- </entry>
- </row>
- <row>
- <entry>
- <para>/api/latest/user</para>
- </entry>
- <entry>
- <para>Provides information about User attributes and types</para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
+
</section>
Modified: qpid/java/trunk/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Keystores.xml
URL: http://svn.apache.org/viewvc/qpid/java/trunk/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Keystores.xml?rev=1717626&r1=1717625&r2=1717626&view=diff
==============================================================================
--- qpid/java/trunk/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Keystores.xml (original)
+++ qpid/java/trunk/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Keystores.xml Wed Dec 2 13:25:56 2015
@@ -53,7 +53,8 @@
</listitem>
<listitem>
<para><emphasis>Auto Generated Self Signed</emphasis> has the ability to
- generate a self signed certificate.</para>
+ generate a self signed certificate and produce a truststore
+ suitable for use by an application using the Qpid JMS client.</para>
<para>The use of self signed certficates is not recommended for production
use.</para>
</listitem>
Modified: qpid/java/trunk/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Ports.xml
URL: http://svn.apache.org/viewvc/qpid/java/trunk/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Ports.xml?rev=1717626&r1=1717625&r2=1717626&view=diff
==============================================================================
--- qpid/java/trunk/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Ports.xml (original)
+++ qpid/java/trunk/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Ports.xml Wed Dec 2 13:25:56 2015
@@ -30,6 +30,25 @@
<para>Any number of ports defined to use AMQP or HTTP protocols can be defined. JMX is limited
to a single port instance per JMX protocol type.</para>
<para>Ports can only be managed by the HTTP management channel.</para>
+ <section id="Java-Broker-Management-Managing-Ports-Context">
+ <title>Context</title>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>qpid.port.max_open_connections</emphasis>. The default maximum number
+ of concurrent connections supported by an AMQP port.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>qpid.port.amqp.acceptBacklog</emphasis>. The backlog is the maximum
+ number of pending connections that may be queued by the AMQP port. Once the queue
+ is full, further connections will be refused. This is a request to the operating system
+ which may or may not be respected. The operating system itself may impose a ceiling.
+ <footnote><para>Some Linux distributions govern the ceiling with a <literal>sysctl</literal>
+ setting <literal>net.core.somaxconn</literal>.</para></footnote></para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
<section id="Java-Broker-Management-Managing-Ports-Attributes">
<title>Attributes</title>
<para><itemizedlist>
@@ -68,7 +87,7 @@
<listitem>
<para><emphasis>Keystore</emphasis>. <link
linkend="Java-Broker-Management-Managing-Keystores">Keystore</link>
- containing the Broker's private key. Required if the SSL is in use.</para>
+ containing the Broker's private key. Required if SSL is in use.</para>
</listitem>
<listitem>
<para><emphasis>Want/Need Client Auth</emphasis>. Client authentication can be
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org