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 2016/11/10 16:22:39 UTC
svn commit: r1769147 - in /qpid/java/branches/6.1.x: ./
doc/java-broker/src/docbkx/management/channels/Java-Broker-Management-Channel-REST-API.xml
doc/java-broker/src/docbkx/management/channels/Java-Broker-Management-Channel-REST-Query-API.xml
Author: kwall
Date: Thu Nov 10 16:22:39 2016
New Revision: 1769147
URL: http://svn.apache.org/viewvc?rev=1769147&view=rev
Log:
QPID-7502: [Java Broker] Add documentation for Query API
Merged from trunk with command:
svn merge -c 1769138,1769139 ^/qpid/java/trunk
Added:
qpid/java/branches/6.1.x/doc/java-broker/src/docbkx/management/channels/Java-Broker-Management-Channel-REST-Query-API.xml
- copied, changed from r1769138, qpid/java/trunk/doc/java-broker/src/docbkx/management/channels/Java-Broker-Management-Channel-REST-Query-API.xml
Modified:
qpid/java/branches/6.1.x/ (props changed)
qpid/java/branches/6.1.x/doc/java-broker/src/docbkx/management/channels/Java-Broker-Management-Channel-REST-API.xml
Propchange: qpid/java/branches/6.1.x/
------------------------------------------------------------------------------
--- svn:mergeinfo (original)
+++ svn:mergeinfo Thu Nov 10 16:22:39 2016
@@ -9,5 +9,5 @@
/qpid/branches/java-broker-vhost-refactor/java:1493674-1494547
/qpid/branches/java-network-refactor/qpid/java:805429-821809
/qpid/branches/qpid-2935/qpid/java:1061302-1072333
-/qpid/java/trunk:1766544,1766547,1766553,1766666,1766796-1766797,1766806,1767251,1767267-1767268,1767275,1767310,1767326,1767329,1767332,1767514,1767523,1767738,1767825,1767847-1767848,1767882,1767909,1767914,1768016-1768017,1768065,1768643,1768704,1768854,1768875,1768914,1768963,1768967,1768976
+/qpid/java/trunk:1766544,1766547,1766553,1766666,1766796-1766797,1766806,1767251,1767267-1767268,1767275,1767310,1767326,1767329,1767332,1767514,1767523,1767738,1767825,1767847-1767848,1767882,1767909,1767914,1768016-1768017,1768065,1768643,1768704,1768854,1768875,1768914,1768963,1768967,1768976,1769138-1769139
/qpid/trunk/qpid:796646-796653
Modified: qpid/java/branches/6.1.x/doc/java-broker/src/docbkx/management/channels/Java-Broker-Management-Channel-REST-API.xml
URL: http://svn.apache.org/viewvc/qpid/java/branches/6.1.x/doc/java-broker/src/docbkx/management/channels/Java-Broker-Management-Channel-REST-API.xml?rev=1769147&r1=1769146&r2=1769147&view=diff
==============================================================================
--- qpid/java/branches/6.1.x/doc/java-broker/src/docbkx/management/channels/Java-Broker-Management-Channel-REST-API.xml (original)
+++ qpid/java/branches/6.1.x/doc/java-broker/src/docbkx/management/channels/Java-Broker-Management-Channel-REST-API.xml Thu Nov 10 16:22:39 2016
@@ -342,6 +342,8 @@ curl --user admin -X PUT -d '{}' http:/
</para>
</section>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Management-Channel-REST-Query-API.xml"/>
+
<section xml:id="Java-Broker-Management-Channel-REST-API-CORS">
<title>Cross Origin Resource Sharing (CORS)</title>
<para> The Broker supports Cross Origin Resource Sharing (CORS)
Copied: qpid/java/branches/6.1.x/doc/java-broker/src/docbkx/management/channels/Java-Broker-Management-Channel-REST-Query-API.xml (from r1769138, qpid/java/trunk/doc/java-broker/src/docbkx/management/channels/Java-Broker-Management-Channel-REST-Query-API.xml)
URL: http://svn.apache.org/viewvc/qpid/java/branches/6.1.x/doc/java-broker/src/docbkx/management/channels/Java-Broker-Management-Channel-REST-Query-API.xml?p2=qpid/java/branches/6.1.x/doc/java-broker/src/docbkx/management/channels/Java-Broker-Management-Channel-REST-Query-API.xml&p1=qpid/java/trunk/doc/java-broker/src/docbkx/management/channels/Java-Broker-Management-Channel-REST-Query-API.xml&r1=1769138&r2=1769147&rev=1769147&view=diff
==============================================================================
--- qpid/java/trunk/doc/java-broker/src/docbkx/management/channels/Java-Broker-Management-Channel-REST-Query-API.xml (original)
+++ qpid/java/branches/6.1.x/doc/java-broker/src/docbkx/management/channels/Java-Broker-Management-Channel-REST-Query-API.xml Thu Nov 10 16:22:39 2016
@@ -23,35 +23,31 @@
<title>Query API</title>
<section xml:id="Java-Broker-Management-Channel-REST-Query-API-Introduction">
<title>Introduction</title>
- <para>The <emphasis>Qpid Broker for Java</emphasis> provides a powerful instrument called
- <emphasis>Query API</emphasis> allowing to retrieve the existing configured objects attributes
- satisfying user-provided filtering criteria.</para>
- <para>Developers and operators can use this instrument to monitor some subsets of configured objects.
+ <para>The <emphasis>Qpid Broker for Java</emphasis> provides a powerful feature called
+ the <emphasis>Query API</emphasis>. This allows the retrieval of the existing configured objects attributes
+ satisfying user-provided queries.</para>
+ <para>Developers and operators can use this feature to monitor the Broker.
For example, using <emphasis>Query API</emphasis> one can find all queues with queue depth
exceeding some limit or existing connections made from a particular location(s).</para>
</section>
<section xml:id="Java-Broker-Management-Channel-REST-Query-API-Overview">
<title>Query API Overview</title>
<para>
- The <emphasis>Query API</emphasis> allows to specify the category of configured objects to query,
- the comma-separated list of attributes and expressions to select,
- results filtering conditions, results sorting order and results offset and limit.
+ When using the <emphasis>Query API</emphasis> 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.
</para>
- <para>The <emphasis>Query API</emphasis> is available in two variations:
- <variablelist>
- <varlistentry>
- <term>broker wide</term>
- <listitem>
- <para>allows to query any configured objects on broker</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>virtual host wide</term>
- <listitem>
- <para>allows to query any configured objects on a particular virtual host</para>
- </listitem>
- </varlistentry>
- </variablelist>
+ <para>Queries associate with either the <emphasis>broker</emphasis> as a whole, or an
+ individual <emphasis>virtualhost</emphasis>. 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.
+ </para>
+ <para>
<table>
<title>Query API URLs</title>
<tgroup cols="2">
@@ -68,7 +64,7 @@
<para>/api/<version>/querybroker/<configured object category name></para>
</entry>
<entry>
- <para>Query API URL to query any configured objects on broker</para>
+ <para>Query API URL fragment to query the specified object type across the entire broker</para>
</entry>
</row>
<row>
@@ -77,7 +73,7 @@
<para>/api/<version>/queryvhost/<virtual host node name>/<virtual host name>/<configured object category name></para>
</entry>
<entry>
- <para>Query API URL to query configured objects on a particular virtual host</para>
+ <para>Query API URL fragment to query the specified object type for a specific virtualhost</para>
</entry>
</row>
</tbody>
@@ -85,9 +81,8 @@
</table>
</para>
<para>
- Both query services require specification of a configured object category name as part of URL.
- Attributes and expressions to select, filtering conditions, result ordering, limit and offset
- are specified using request parameters.
+ The QueryAPI accepts <literal>select</literal>, <literal>where</literal>, <literal>orderBy</literal>,
+ <literal>limit</literal> and <literal>offset</literal> request parameters.
<table>
<title>Query API request parameters</title>
<tgroup cols="2">
@@ -100,36 +95,52 @@
<tbody>
<row>
<entry>
- <para>select</para>
+ <para><literal>select</literal></para>
</entry>
<entry>
- <para>a comma-separated list of configured objects attribute names or expressions
- to select</para>
+ <para>The <literal>select</literal> 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. <literal>queueDepthBytes</literal>), but more complex
+ <link linkend="Java-Broker-Management-Channel-REST-Query-API-Expressions">expressions</link> are also supported.</para>
+ <para>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.</para>
+ <para>Column names can be overridden with an <literal>AS</literal>
+ clause e.g. <literal>now() AS currentDate</literal>
+ </para>
</entry>
</row>
<row>
<entry>
- <para>where</para>
+ <para><literal>where</literal></para>
</entry>
<entry>
- <para>filtering conditions; the syntax of the expression is based on a subset of
- the SQL92 conditional expression syntax similar to selector expressions in JMS.</para>
+ <para>The <literal>where</literal> provides a boolean expression defining the result set filtering.</para>
+ <para>The syntax of the <link linkend="Java-Broker-Management-Channel-REST-Query-API-Expressions">expression</link>
+ is based on a subset of the SQL92 conditional expression syntax and is similar to selector expressions in JMS e.g.
+ <literal>queueDepthBytes > 16384 AND name like '%flow_queue'</literal>.
+ </para>
</entry>
</row>
<row>
<entry>
- <para>orderBy</para>
+ <para><literal>orderBy</literal></para>
</entry>
<entry>
- <para>ordering conditions; the syntax of the expression is based on a subset of
+ <para>Ordering conditions; the syntax of the
+ <link linkend="Java-Broker-Management-Channel-REST-Query-API-Expressions">
+ expression
+ </link>
+ 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.</para>
+ or indexes (starting from 1) of attributes or expressions specified in select.
+ </para>
</entry>
</row>
<row>
<entry>
- <para>limit</para>
+ <para><literal>limit</literal></para>
</entry>
<entry>
<para>The maximum number of results to provide starting from given offset.</para>
@@ -137,7 +148,7 @@
</row>
<row>
<entry>
- <para>offset</para>
+ <para><literal>offset</literal></para>
</entry>
<entry>
<para>An offset in results (default is 0) to provide results from.</para>
@@ -148,41 +159,38 @@
</table>
</para>
<example>
- <title>Example of Query API request to retrieve queue names and depths.</title>
+ <title>Example of a Query API request to retrieve queue names and depths.</title>
<screen>GET api/latest/querybroker/queue?select=name,queueDepthBytes,queueDepthMessages&where=queueDepthBytes>0&orderBy=1 desc,2 desc&offset=0&limit=100 HTTP/1.1</screen>
</example>
</section>
<section xml:id="Java-Broker-Management-Channel-REST-Query-API-Results">
<title>Query API Results</title>
- <para>The <emphasis>Query API</emphasis> returns the JSON response with found results as JSON objects containing
- three fields.
+ <para>The <emphasis>Query API</emphasis> returns a JSON response. The response contains the following:
<variablelist>
<varlistentry>
- <term>headers</term>
+ <term><literal>headers</literal></term>
<listitem>
- <para>array containing configured objects attribute names corresponding to the Query select
- expression. Please, note that empty string can be returned for a user specified expressions
- in select if <emphasis>as</emphasis> given a name to the expression is missed .
- </para>
+ <para>ordered list of result set column names derived from the <literal>select</literal>
+ clause. Note that anonymous expressions (that is, those expressed without an
+ <literal>AS</literal>) will have empty column name.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>results</term>
+ <term><literal>results</literal></term>
<listitem>
- <para>two dimensional array containing attributes and/or expression values for the subset
- of found results </para>
+ <para>two dimensional array containing the result-set</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>total</term>
+ <term><literal>total</literal></term>
<listitem>
- <para>The total number of results matching the where conditions.</para>
+ <para>The <emphasis>total</emphasis> number of results matching the where criteria.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<example>
- <title>Example of Query API results for the query to retrieve queue names and depths.</title>
+ <title>Example of Query API call for queue names and depths.</title>
<screen>GET api/latest/querybroker/queue?select=name,queueDepthBytes,queueDepthMessages&where=queueDepthBytes>0&orderBy=1 desc,2 desc&offset=0&limit=100 HTTP/1.1</screen>
<programlisting language="javascript">
{
@@ -192,11 +200,20 @@
}
</programlisting>
</example>
- <section xml:id="Java-Broker-Management-Channel-REST-Query-API-Select">
- <title>Query API expressions and functions</title>
- <para>Query API <emphasis>select</emphasis>, <emphasis>where</emphasis> and <emphasis>orderBy</emphasis>
- can include expressions containing pre-defined functions or special variables.</para>
- <para>The following functions can be used in the expressions:
+ <section xml:id="Java-Broker-Management-Channel-REST-Query-API-Expressions">
+ <title>Query API expressions</title>
+
+ <para>Expressions within the <literal>select</literal>, <literal>where</literal> and <literal>orderBy</literal>
+ clauses can be comprised in the following manner. Expressions can be nested to arbitary depth. Parentheses
+ allow for precedence to be explicitly denoted.
+ <itemizedlist>
+ <listitem><para>variable name which can be an attribute name e.g <literal>queueDepthBytes</literal> or
+ a reference to a parent attribute <literal>$parent.name</literal></para></listitem>
+ <listitem><para>literal e.g. <literal>3</literal> or <literal>'foo'</literal></para></listitem>
+ <listitem><para>functions - see below e.g. <literal>now()</literal> or <literal>to_string(createdDate, '%tm/%td/%ty', 'EST')</literal></para></listitem>
+ <listitem><para>arithmetic operations e.g. <literal>3 * 4</literal> or <literal>to_string(now()) + name</literal></para></listitem>
+ </itemizedlist></para>
+ <para>The following functions are supported:
<table>
<title>Query API functions</title>
<tgroup cols="2">
@@ -209,15 +226,15 @@
<tbody>
<row>
<entry>
- <para>concat</para>
+ <para><literal>concat(obj[,obj..])</literal></para>
</entry>
<entry>
- <para>concatenates the parameters into a string</para>
+ <para>concatenates the given objects into a string</para>
</entry>
</row>
<row>
<entry>
- <para>now</para>
+ <para><literal>now()</literal></para>
</entry>
<entry>
<para>returns current date and time</para>
@@ -225,47 +242,44 @@
</row>
<row>
<entry>
- <para>to_date</para>
+ <para><literal>to_date(object)</literal></para>
</entry>
<entry>
- <para>converts string parameter into date and time</para>
+ <para>converts the first parameter, which must be a string. into a date. The
+ string must be in ISO-8601 format e.g. <literal>1970-01-01T10:00:00Z</literal>.</para>
</entry>
</row>
<row>
<entry>
- <para>date_add</para>
+ <para><literal>date_add(object, duration)</literal></para>
</entry>
<entry>
- <para>adds given period specified as the second parameter in ISO-8601 format duration
- to the given date specified as the first parameter</para>
+ <para>adds the given ISO-8601 duration <literal>duration</literal> e.g.
+ <literal>P1D</literal> or <literal>-PT10H</literal> to the date provided by the
+ first parameter.</para>
</entry>
</row>
<row>
<entry>
- <para>to_string</para>
+ <para><literal>to_string(object[, format[, timezone]])</literal></para>
</entry>
<entry>
- <para>converts given date (specified as a first parameter) into a string using optional
- format string (second parameter) and time zone name (third parameter)</para>
+ <para>Converts given object into a string.</para>
+ <para>If the format argument is present, it must be a Java
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${oracleJdkDocUrl}java/util/Formatter.html">Formatter</link>
+ compliant string e.g. <literal>%f</literal> or <literal>%tY-%tm-%td</literal>.
+ </para>
+ <para>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 the<literal>format</literal>.
+ If the timezone is omitted <literal>UTC</literal> is assumed.
+ </para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
- <para>
- A special notation <emphasis>$parent.</emphasis> can be used to access attributes of
- the parent of configured object.
- </para>
- <example>
- <title>Example of expressions</title>
- <literallayout>
- to_string(now()) as current_time,
- concat(name,'_test') as exp,
- $parent.name as parentName,
- $parent.type as parentType
- </literallayout>
- </example>
</section>
</section>
-</section>
\ No newline at end of file
+</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org