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 [email protected] 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: [email protected] For additional commands, e-mail: [email protected]
