http://git-wip-us.apache.org/repos/asf/qpid-site/blob/6e5b75e1/content/releases/qpid-java-6.1.1/java-broker/book/Java-Broker-Management-Channel-AMQP-Intrinstic.html ---------------------------------------------------------------------- diff --git a/content/releases/qpid-java-6.1.1/java-broker/book/Java-Broker-Management-Channel-AMQP-Intrinstic.html b/content/releases/qpid-java-6.1.1/java-broker/book/Java-Broker-Management-Channel-AMQP-Intrinstic.html new file mode 100644 index 0000000..25c5091 --- /dev/null +++ b/content/releases/qpid-java-6.1.1/java-broker/book/Java-Broker-Management-Channel-AMQP-Intrinstic.html @@ -0,0 +1,146 @@ + + + + + 6.4. AMQP Intrinstic Management - Apache Qpid™ + + + + + + + + + + + + + +
+
+ Menu + + Search + + +
+ + + + + +
+ + +
+

6.4. AMQP Intrinstic Management

The AMQP protocols 0-8..0-10 allow for creation, deletion and query of Exchanges, Queue + and Bindings.

The exact details of how to utilise this commands depends of the client. See the + documentation accompanying the client for details.

+ +
+ + + + +
+
+
+ + http://git-wip-us.apache.org/repos/asf/qpid-site/blob/6e5b75e1/content/releases/qpid-java-6.1.1/java-broker/book/Java-Broker-Management-Channel-QMF.html ---------------------------------------------------------------------- diff --git a/content/releases/qpid-java-6.1.1/java-broker/book/Java-Broker-Management-Channel-QMF.html b/content/releases/qpid-java-6.1.1/java-broker/book/Java-Broker-Management-Channel-QMF.html new file mode 100644 index 0000000..5fbac33 --- /dev/null +++ b/content/releases/qpid-java-6.1.1/java-broker/book/Java-Broker-Management-Channel-QMF.html @@ -0,0 +1,144 @@ + + + + + 6.5. QMF - Apache Qpid™ + + + + + + + + + + + + + +
+
+ Menu + + Search + + +
+ + + + + +
+ + +
+

6.5. QMF

QMF is provided by an optional plugin.

+ +
+ + + + +
+
+
+ + http://git-wip-us.apache.org/repos/asf/qpid-site/blob/6e5b75e1/content/releases/qpid-java-6.1.1/java-broker/book/Java-Broker-Management-Channel-REST-API.html ---------------------------------------------------------------------- diff --git a/content/releases/qpid-java-6.1.1/java-broker/book/Java-Broker-Management-Channel-REST-API.html b/content/releases/qpid-java-6.1.1/java-broker/book/Java-Broker-Management-Channel-REST-API.html new file mode 100644 index 0000000..50a5d4c --- /dev/null +++ b/content/releases/qpid-java-6.1.1/java-broker/book/Java-Broker-Management-Channel-REST-API.html @@ -0,0 +1,409 @@ + + + + + 6.3. REST API - Apache Qpid™ + + + + + + + + + + + + + +
+
+ Menu + + Search + + +
+ + + + + +
+ + +
+

6.3. REST API

6.3.1. Introduction

This section describes the REST API provided by the Apache Qpid Broker for Java. 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 + curl.

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.

The GET method request retrieves information about an object, the + DELETE method requests the removal of one, and the PUT + or POST methods perform updates or create new objects. The + POST method is also used to invoke operations.

The REST API is versioned with the version number embedded within the URI. The general form + of the URI is /api/<version> where <version> is a dot separated + major and minor model version prefixed with "v", for example, "v6.1" (without the quotation marks). + For convenience the alias latest (/api/latest) signifies the + latest supported version.

There are also some ancillary services under URI /service used for + authentication and logout.

6.3.2. REST API documentation

REST API documentation is available on-line from any Broker at location + /apidocs. It is also linked from the menu of the Web Management Console. +

6.3.3. Authentication

Before you can use the REST API, you must authenticate. Authentication decisions are made + by the authentication + provider associated with HTTP port + on which you connect.

You may authenticate using SASL + (/service/sasl) or HTTP + Basic Authentication. The latter is convienent when using tools such as + curl on the command line. This is illustrated in the examples + below.

For SASL authentication use a GET request to + /service/sasl to get a list of supported SASL mechanisms, and use + PUT to the same URL to perform the SASL negotiation.

It is possible to end an authenticated session using + /service/logout.

6.3.4. Configured Object creation

Methods PUT or POST can be used to create ConfiguredObject.

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.

Example 6.1. Examples of REST calls for Queue creation

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:

PUT /api/latest/queue/vhn/vh HTTP/1.1
POST /api/latest/queue/vhn/vh HTTP/1.1
PUT /api/latest/queue/vhn/vh/my-queue HTTP/1.1

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.


6.3.5. Configured Object update

Methods PUT or POST can be used to update ConfiguredObject.

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.

Example 6.2. Examples of REST calls for Queue update

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:

POST /api/latest/queue/vhn/vh/my-queue HTTP/1.1
POST /api/latest/queue/vhn/vh/my-queue HTTP/1.1

6.3.6. Configured Object deletion

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.

On successful completion of operation a response code 200 should be returned.

With DELETE method object ConfiguredObject in following ways:

  • by submitting DELETE request using ConfiguredObject full URI (the one ending with + configured object name)

  • 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.

Example 6.3. Examples of REST calls for Queue deletion

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:

DELETE /api/latest/queue/vhn/vh/my-queue HTTP/1.1
DELETE /api/latest/queue/vhn/vh?name=my-queue HTTP/1.1
DELETE /api/latest/queue/vhn/vh?id=real-queue-id HTTP/1.1

6.3.7. Retrieving Configured Object details

Method GET is used to retrieve ConfiguredObject attributes values and children + hierarchy.

A particular ConfiguredObject details can be retrieved using full ConfiguredObject URI + (the one ending with configured object name)

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.

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.

For example, for binding URL http://localhost:8080/api/latest/binding/<vhost + node>/<vhost>/<exchange>/<queue>/<binding> replacing of + <exchange> with "asterisks" + (http://localhost:8080/api/<ver>/binding/<vhost + node>/<vhost>/*/<queue>/<binding>) 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.

If <binding> and <queue> are omitted in + binding REST URL (http://localhost:8080/api/<ver>/binding/<vhost + node>/<vhost>/<exchangename>) the GET request will result in + returning all bindings for all queues for the given exchange in the virtual host.

Additional parameters supported in GET requests:

depth

To restrict the depth of hierarchy of configured objects to return in + response

actuals

If set to "true" attribute actual values are returned instead of effective

includeSysContext

If set to "true" all system context variables are returned

inheritedActuals

If set to "true" actual values for all inherited context is returned.

oversize

Sets the maximum length for values of over-sized attributes to trim

extractInitialConfig

If set to "true", the returned json can be used as initial configuration.

6.3.8. Configured Object operations

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.

Example 6.4. Example REST call invoking the operation clear queue

To clear the queue with name "my-queue" on a virtual host with name "vh".

POST api/latest/queue/vhn/vh/my-queue/clearQueue HTTP/1.1

6.3.9. HTTP status codes returned by REST interfaces

Table 6.1. HTTP status codes returned by REST interfaces

Status codeDescription
+

200

+
+

REST request is successfully completed. This status code can be returned by + update, delete and get requests.

+
+

201

+
+

New configured object is created. It is returned by REST PUT and POST requests + for creation of configured objects.

+
+

400

+
+

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.

+
+

401

+
+

The request requires user authentication

+
+

403

+
+

Execution of request is not allowed due to failure to authorize user + operation.

+
+

404

+
+

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.

+
+

409

+
+

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.

+
+

422

+
+

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.

+

6.3.10. Examples of REST requests with curl

Example 6.5. Examples of queue creation using curl (authenticating as user admin):

+#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>
+            

Example 6.6. Example of binding a queue to an exchange using curl

+curl --user admin -X PUT  -d '{}' http://localhost:8080/api/latest/binding/<vhostnode name>/<vhostname>/<exchangename>/<queue-name>/<binding-name>
+            

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 Section 7.16, “HTTP Plugin” +

6.3.11. Query API

6.3.11.1. Introduction

The Qpid Broker for Java provides a powerful feature called + the Query API. This allows the retrieval of the existing configured objects attributes + satisfying user-provided queries.

Developers and operators can use this feature to monitor the Broker. + For example, using Query API one can find all queues with queue depth + exceeding some limit or existing connections made from a particular location(s).

6.3.11.2. Query API Overview

+ When using the Query API one specifies the category of the object + to query, a list of attributes to return in the result set, an optional where clause, + expressed as a predicate, that determines the filtering criteria, ordering, and + limit/offset. The features should be readily recognisable to anyone who has has familiarity + with SQL. +

Queries associate with either the broker as a whole, or an + individual virtualhost. Queries associated with the Broker + can query any object within the Broker. Queries associated with a virtualhost are limited + to the objects of the virtualhost itself. For instance a queue query associated + with a virtualhost queries only the queues belonging to that virtualhost. On the other + hand, a queue query associated with the Broker sees all the queues belonging on the entire + Broker. +

+

Table 6.2. Query API URLs

Query API URLDescription
+

/api/latest/querybroker/<configured object category name>

+

/api/<version>/querybroker/<configured object category name>

+
+

Query API URL fragment to query the specified object type across the entire broker

+
+

/api/latest/queryvhost/<virtual host node name>/<virtual host name>/<configured object category name>

+

/api/<version>/queryvhost/<virtual host node name>/<virtual host name>/<configured object category name>

+
+

Query API URL fragment to query the specified object type for a specific virtualhost

+


+

+ The QueryAPI accepts select, where, orderBy, + limit and offset request parameters. +

Table 6.3. Query API request parameters

Parameter NameParameter Description
+

select

+
+

The select defines the columns of the result set. It is a + comma-separated list of expressions. At its most simple, an expression can be + the name of the attribute (e.g. queueDepthBytes), but more complex + expressions are also supported.

+

Columns within the result set are named. For expressions that are simple attribute + names, the column names will follow the attributes themselves. By default, other + expressions will have a no name.

+

Column names can be overridden with an AS + clause e.g. now() AS currentDate +

+
+

where

+
+

The where provides a boolean expression defining the result set filtering.

+

The syntax of the expression + is based on a subset of the SQL92 conditional expression syntax and is similar to selector expressions in JMS e.g. + queueDepthBytes > 16384 AND name like '%flow_queue'. +

+
+

orderBy

+
+

Ordering conditions; the syntax of the + + expression + + is based on a subset of + the SQL92 ordering expression syntax. Similar to ordering expressions in SQL, + one can specify in ordering expression attributes names, sub-expressions + or indexes (starting from 1) of attributes or expressions specified in select. +

+
+

limit

+
+

The maximum number of results to provide starting from given offset.

+
+

offset

+
+

An offset in results (default is 0) to provide results from.

+


+

Example 6.7. Example of a Query API request to retrieve queue names and depths.

GET api/latest/querybroker/queue?select=name,queueDepthBytes,queueDepthMessages&where=queueDepthBytes>0&orderBy=1 desc,2 desc&offset=0&limit=100 HTTP/1.1

6.3.11.3. Query API Results

The Query API returns a JSON response. The response contains the following: +

headers

ordered list of result set column names derived from the select + clause. Note that anonymous expressions (that is, those expressed without an + AS) will have empty column name.

results

two dimensional array containing the result-set

total

The total number of results matching the where criteria.

+

Example 6.8. Example of Query API call for queue names and depths.

GET api/latest/querybroker/queue?select=name,queueDepthBytes,queueDepthMessages&where=queueDepthBytes>0&orderBy=1 desc,2 desc&offset=0&limit=100 HTTP/1.1
+{
+    "headers" : [ "name", "queueDepthBytes", "queueDepthMessages" ],
+    "results" : [ [ "foo", 312, 26], [ "bar", 300, 24 ] ],
+    "total" : 2
+}
+            

Query API expressions

Expressions within the select, where and orderBy + clauses can be comprised in the following manner. Expressions can be nested to arbitary depth. Parentheses + allow for precedence to be explicitly denoted. +

  • variable name which can be an attribute name e.g queueDepthBytes or + a reference to a parent attribute $parent.name

  • literal e.g. 3 or 'foo'

  • functions - see below e.g. now() or to_string(createdDate, '%tm/%td/%ty', 'EST')

  • arithmetic operations e.g. 3 * 4 or to_string(now()) + name

The following functions are supported: +

Table 6.4. Query API functions

Function NameFunction Description
+

concat(obj[,obj..])

+
+

concatenates the given objects into a string

+
+

now()

+
+

returns current date and time

+
+

to_date(object)

+
+

converts the first parameter, which must be a string. into a date. The + string must be in ISO-8601 format e.g. 1970-01-01T10:00:00Z.

+
+

date_add(object, duration)

+
+

adds the given ISO-8601 duration duration e.g. + P1D or -PT10H to the date provided by the + first parameter.

+
+

to_string(object[, format[, timezone]])

+
+

Converts given object into a string.

+

If the format argument is present, it must be a Java + Formatter + compliant string e.g. %f or %tY-%tm-%td. +

+

The timezone argument is significant if the object is a Date. If the timezone + argument is specified it must be a valid Java timezone name. The date is converted + to the specified timezone before being formatted by theformat. + If the timezone is omitted UTC is assumed. +

+


+

6.3.12. Cross Origin Resource Sharing (CORS)

The Broker supports Cross Origin Resource Sharing (CORS) + to allow web management consoles other than the one embedded in the + broker to use the REST API. This feature must be enabled by configuring + the CORS Allow Origins and related attributes on the + Section 7.16, “HTTP Plugin” +

+ +
+ + + + +
+
+
+ + http://git-wip-us.apache.org/repos/asf/qpid-site/blob/6e5b75e1/content/releases/qpid-java-6.1.1/java-broker/book/Java-Broker-Management-Channel-Web-Console.html ---------------------------------------------------------------------- diff --git a/content/releases/qpid-java-6.1.1/java-broker/book/Java-Broker-Management-Channel-Web-Console.html b/content/releases/qpid-java-6.1.1/java-broker/book/Java-Broker-Management-Channel-Web-Console.html new file mode 100644 index 0000000..4916f15 --- /dev/null +++ b/content/releases/qpid-java-6.1.1/java-broker/book/Java-Broker-Management-Channel-Web-Console.html @@ -0,0 +1,191 @@ + + + + + 6.2. Web Management Console - Apache Qpid™ + + + + + + + + + + + + + +
+
+ Menu + + Search + + +
+ + + + + +
+ + +
+

6.2. Web Management Console

The Web Management Console provides a simple and intuitive interface for the Management + and Control of the Broker. From here, all aspects of the Broker can be controlled, + including:

  • add, remove and monitor queues

  • inspect, move, copy or delete messages

  • add, remove and monitor virtualhosts

  • configure and control high availability

+

The remainder of the section provides an introduction to the web management console and + its use.

6.2.1. Accessing the Console

The Web Management Console is provided by the HTTP Management Plugin. Providing the + HTTP Management Plugin is in its default configuration, the Web Management Console can + be accessed by pointing a browser at the following URL:

+ http://myhost.mydomain.com:8080 +

The Console will prompt you to login using a username and password.

Figure 6.1. Web Management Console - Authentication

Web Console Authentication

6.2.2. Orientation

After you have logged on you will see a screen similar to the following. The elements + of the screen are now explained.

Figure 6.2. Web Management Orientation - Console

The Web Console

+

  • A - Hierarchy view. Expandable/collapsible view + showing all entities within the Broker. Double click on an entity name to + cause its tab to be opened.

  • B - Tab. Shows the details of an entity including its + attributes and its child entities.

  • C - Occluded tab. Click tab name to bring the tab to + the front.

  • D - Auto restore check box. Checked tabs will be + automatically restored on subsequent login.

  • E - Close. Click to close the tab.

  • F - User Menu. Access to Preferences, Logout and + Help.

+

Figure 6.3. Web Management Orientation - Tab

A tab within the Web Consle

The elements of a tab are now explained:

  • 1 - Attribute Panel. Shows the attributes of the + entity. Click the panel title bar opens/closes the panel.

  • 2 - Child Panels. Panels containing a table listing + the children of the entity. Click the panel title bar opens/closes the + panel.

  • 3 - Child Row. Row summarizing a child entity. Double + click to open the child tab.

  • 4 - Child Operations. Buttons to add a new child or + perform operations on existing children.

+

6.2.3. Managing Entities

All the Entities of the Broker of can be managed through the Web Console.

6.2.3.1. Adding Entities

To add a new entity, click the Add button + on the Child Panel on the Parent's tab. Clicking the Add button causes an add + dialogue to be displayed.

Add dialogues allow you to set the attributes of the new child, and set context + variables. Most fields on the add dialogue have field level help that give more + details about the attribute and any default value (which may be expressed in terms + of a context variable) that will take effect if you leave the attribute unset. An + example add dialogue is shown in the figure that follows.

Figure 6.4. Web Management Orientation - Add Dialogue

Example add dialogue showing field level help

6.2.3.2. Editing Entities

To edit an existing entity, click the Edit + button on the tab corresponding to the Entity itself. Editing an entity lets you + change some of its attributes and modify its context variables. Most fields on the + edit dialogue have field level help that give more details about the attribute and + any default value. An example edit dialogue is shown in the figure that + follows.

Figure 6.5. Web Management Orientation - Edit Dialogue

Example edit dialogue

6.2.3.3. Deleting Entities

To remove an existing entity, click the + Delete button on the tab corresponding to the Entity itself. + For some child types, you can select many children from the parent's type and delete + many children at once.

6.2.3.4. Context Variables

All Entities within the Broker have the ability to have context + variables associated with them.

Most add and edit dialogues have the ability to make context variable assignments. + To add/change/remove a context variable, click the Context Variable panel to expand + it.

Figure 6.6. Web Management Orientation - Context Variables

Editting Context Variables

You will see any context variables already associated with the object, called + local context variables in bold, and any inherited from above in normal face.

Since context variables can be defined in terms of other context variables, the + display has two value columns: actual and effective. Actual shows the value truely + associated with the variable, where as effective shows the resulting value, after + variable expansion has taken place.

The + button allows new variables to be added. The + - button removes existing ones.

You change an existing local variables defintion by clicking on the actual value. + You can also provide a local definition for an inherited value + by clicking on the actual value and typing its new value.

+ +
+ + + + +
+
+
+ + --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org For additional commands, e-mail: commits-help@qpid.apache.org