specs/apache-filters.xml - qpid-broker-j - Git at Google

 <!--

    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.
 -->
 <?xml-stylesheet type="text/xsl" href="amqp.xsl"?>

 <amqp name="apache-filters" label="Apache Proposed AMQP 1-0 Filters">
   <section name="legacy-amqp" title="Legacy AMQP Exchange Binding Support">
     <doc>
       <p>
         Versions of AMQP prior to 1.0 prescribed a model of Exchanges and Queues, where Queues were
         bound to Exchanges with a binding key whose meaning depended upon the type of the Exchange.
         In order to allow a consistent mechanism for addressing legacy AMQP Exchanges over AMQP 1.0
         the following filter types are defined. Use of an Exchange as an address for a Source thus
         can be seen as equivalent to constructing exclusive queues bound to an Exchange in legacy
         AMQP versions.
       </p>
       <p>
         Containers which support the filters that are defined in this section should advertise the
         capability <term>APACHE.ORG:LEGACY_AMQP_EXCHANGE_FILTERS</term> in their connection
         capabilities when sending the open performative, and MUST provide this capability on
         sources supporting these filter types.
       </p>
     </doc>
  	<type class="restricted" name="legacy-amqp-direct-binding" source="string" provides="filter">
  		<descriptor name="apache.org:legacy-amqp-direct-binding:string"
                     code="0x0000468C:0x00000000"/>
         <doc>
           <p>
             The legacy-amqp-direct-binding filter consists of a described string value. The filter
             matches a message if and only if the described string value exactly matches the subject
             field of the Properties section of the message being evaluated. If the message has no
             Properties section, or if the subject field of the Properties section is not set, then
             the legacy-amqp-direct-binding filter does not match.
           </p>
         </doc>
  	</type>

  	<type class="restricted" name="legacy-amqp-topic-binding" source="string" provides="filter">
  		<descriptor name="apache.org:legacy-amqp-topic-binding:string"
                     code="0x0000468C:0x00000001"/>
         <doc>
           <p>
             The legacy-amqp-topic-binding filter consists of a described string value. The value
             value described by the type is interpreted as a pattern to match against the subject
             field of the Properties section of the message being evaluated.
           </p>
           <ul>
             <li>The pattern is formed using zero or more tokens, with each token delimited by the
                 "." character. The tokens "#" and "*" have special meanings.</li>
             <li>The token consisting of the single character "*" matches a single word in the
                 subject field.</li>
             <li>The token consisting of the single character "#" matches zero or more words in the
                 subject field.</li>
           </ul>
           <p>
             Thus the filter value "*.stock.#" would match the subjects "usd.stock" and
             "eur.stock.db" but not "stock.nasdaq".
           </p>
           <p>
             If the message has no Properties section, or if the subject field of the Properties
             section is not set, then the legacy-amqp-topic-binding filter matches only if the value
             of the filter is a single "#".
           </p>
         </doc>
  	</type>

  	<type class="restricted" name="legacy-amqp-headers-binding" source="map" provides="filter">
  		<descriptor name="apache.org:legacy-amqp-headers-binding:map" code="0x0000468C:0x00000002"/>
         <doc>
           <p>
             The legacy-amqp-headers-binding filter consists of a described map value. The map
             value described by the type is interpreted as a pattern to match against the
             application-properties section of the message being evaluated. The map has the same
             restriction as the application-properties section, namely that the keys of this are
             restricted to be of type string (which excludes the possibility of a null key) and the
             values are restricted to be of simple types only, that is, excluding map, list, and
             array types.
           </p>
           <p>
             The key "x-match" in the described map has special meaning. This key MUST map to the
             symbolic value "any" or the symbolic value "all" within the described map. All other
             keys which begin "x-" MUST be ignored by the source when evaluating. If the value for
             "x-match" is "all" then all other valid key-value pairs in the map MUST match with an
             entry with the same key in the application-properties section. If the value for
             "x-match" is "any" then the filter will accept the message if at least one key-value
             pair matches the equivalent key value pair in the application-properties section.
           </p>
           <p>
             A key-value pair in the filter's map matches a key-value pair in the
             application-properties section if the keys are identical (including the same type), or
             if the value in the filter map for the key is null.
           </p>
         </doc>
  	</type>
   </section>
   <section name="jms" title="Java Message Service Support">

     <doc>
       <p>
         The Java Message Service defines two types of filtering of messages: firstly the ability to
         exclude from a subscription messages sent by the same connection, secondly a more general
         filtering syntax known as "selectors" based on an SQL like syntax.
       </p>
       <p>
         AMQP filter extensions through which these two types of
         filtering may be achieved are defined below. Their use, though
         motivated by support for JMS, is not restricted to JMS.
       </p>
     </doc>

 	<type class="composite" name="no-local-filter" source="list" provides="filter">
 		<descriptor name="apache.org:no-local-filter:list" code="0x0000468C:0x00000003"/>
         <doc>
           <p>
             A message will be accepted by the simple-no-local-filter if and only if the message
             was originally sent to the container of the source on a separate connection from that
             which is currently receiving from the source.
           </p>
           <p>
             Containers which support this filter should advertise the
             capability <term>APACHE.ORG:NO_LOCAL</term> in their
             connection capabilities when sending the open
             performative, and MUST provide this capability on sources
             supporting these filter types.
           </p>
         </doc>
 	</type>

 	<type class="restricted" name="selector-filter" provides="filter" source="string">
 		<descriptor name="apache.org:selector-filter:string" code="0x0000468C:0x00000004"/>
         <doc>
           <p>
             The Java Message Service "selector" defines an SQL like
             syntax for filtering messages.  The selector filters based
             on the values of "headers" and "properties". The
             selector-filter uses the selector as defined by JMS but
             with the names of JMS headers translated into their AMQP
             equivalents. The defined JMS headers can be mapped to
             equivalent fields within the AMQP message sections:
           </p>
 <picture title="Mapping JMS Headers to AMQP fields">
 JMS Header Name   | AMQP 1.0 Field
 ==================|====================================================
 JMSCorrelationID  | correlation-id field of properties section
 JMSDeliveryMode   | durable field of header section
 JMSDestination    | to field of the properties section
 JMSExpiration     | absolute-expiry-time of properties section
 JMSMessageID      | message-id of properties section
 JMSPriority       | priority field of header section
 JMSRedelivered    | delivery-count > 0 in header section
 JMSReplyTo        | reply-to in properties section
 JMSTimestamp      | creation-time of properties section
 JMSType           | annotation jms-type in message-annotations section
 </picture>
         <p>
           When encoding the selector string on the wire, these JMS
           header names should be translated to amqp.<i>field_name</i>
           where <i>field_name</i> is the appropriate AMQP 1.0 field
           named in the table above, with the hyphen replaced by an
           underscore. For example, the selector: "JMSCorrelationID =
           'abc' AND color = 'blue' AND weight > 2500" would be
           transferred over the wire as: "amqp.correlation_id = 'abc'
           AND color = 'blue' AND weight > 2500"
         </p>
         <p>
           The "properties" of the JMS message are equivalent to the AMQP application-properties
           section. Thus a reference to a property Foo in a message selector would be evaluated
           as the value associated with the key "Foo" (if present) in the application-properties
           section.
         </p>
         <p>
           The operands of the JMS selector are defined in terms of the types available within JMS,
           When evaluated against the application properties section, the values within that section
           MUST be evaluated according to the following type mapping.
         </p>
 <picture title="Mapping AMQP types to JMS types">
 AMQP Type         | JMS Selector Type
 ==================|===================
 null              | null
 boolean           | boolean
 ubyte             | short
 ushort            | int
 uint              | long
 ulong             | long
 byte              | byte
 short             | short
 int               | int
 long              | long
 float             | float
 double            | double
 decimal32         | double
 decimal64         | double
 decimal128        | double
 char              | char
 timestamp         | long
 uuid              | byte[16]
 binary            | byte[]
 string            | String
 symbol            | String
 </picture>
           <p>
             Containers which support this filter should advertise the
             capability <term>APACHE.ORG:SELECTOR</term> in their
             connection capabilities when sending the open
             performative, and MUST provide this capability on sources
             supporting these filter types.
           </p>
         </doc>
 	</type>
   </section>
   <section name="xquery" title="An xquery based filter">
       <type class="restricted" name="xquery" source="string" provides="filter">
           <descriptor name="apache.org:xquery-filter:string" code="0x0000468C:0x00000005"/>
           <doc>
             <p>
             The xquery filter consists of a described string value
             containing a valid xquery string against which messages
             are matched.
             </p>
             <p>
             Containers which support the filter defined in this
             section should advertise the capability
             <term>APACHE.ORG:XQUERY</term> in their connection
             capabilities when sending the open performative.
             </p>
           </doc>
      </type>
  </section>
 </amqp>
	<!--

	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->
	<?xml-stylesheet type="text/xsl" href="amqp.xsl"?>

	<amqp name="apache-filters" label="Apache Proposed AMQP 1-0 Filters">
	<section name="legacy-amqp" title="Legacy AMQP Exchange Binding Support">
	<doc>
	<p>
	Versions of AMQP prior to 1.0 prescribed a model of Exchanges and Queues, where Queues were
	bound to Exchanges with a binding key whose meaning depended upon the type of the Exchange.
	In order to allow a consistent mechanism for addressing legacy AMQP Exchanges over AMQP 1.0
	the following filter types are defined. Use of an Exchange as an address for a Source thus
	can be seen as equivalent to constructing exclusive queues bound to an Exchange in legacy
	AMQP versions.
	</p>
	<p>
	Containers which support the filters that are defined in this section should advertise the
	capability <term>APACHE.ORG:LEGACY_AMQP_EXCHANGE_FILTERS</term> in their connection
	capabilities when sending the open performative, and MUST provide this capability on
	sources supporting these filter types.
	</p>
	</doc>
	<type class="restricted" name="legacy-amqp-direct-binding" source="string" provides="filter">
	<descriptor name="apache.org:legacy-amqp-direct-binding:string"
	code="0x0000468C:0x00000000"/>
	<doc>
	<p>
	The legacy-amqp-direct-binding filter consists of a described string value. The filter
	matches a message if and only if the described string value exactly matches the subject
	field of the Properties section of the message being evaluated. If the message has no
	Properties section, or if the subject field of the Properties section is not set, then
	the legacy-amqp-direct-binding filter does not match.
	</p>
	</doc>
	</type>

	<type class="restricted" name="legacy-amqp-topic-binding" source="string" provides="filter">
	<descriptor name="apache.org:legacy-amqp-topic-binding:string"
	code="0x0000468C:0x00000001"/>
	<doc>
	<p>
	The legacy-amqp-topic-binding filter consists of a described string value. The value
	value described by the type is interpreted as a pattern to match against the subject
	field of the Properties section of the message being evaluated.
	</p>
	<ul>
	<li>The pattern is formed using zero or more tokens, with each token delimited by the
	"." character. The tokens "#" and "*" have special meanings.</li>
	<li>The token consisting of the single character "*" matches a single word in the
	subject field.</li>
	<li>The token consisting of the single character "#" matches zero or more words in the
	subject field.</li>
	</ul>
	<p>
	Thus the filter value "*.stock.#" would match the subjects "usd.stock" and
	"eur.stock.db" but not "stock.nasdaq".
	</p>
	<p>
	If the message has no Properties section, or if the subject field of the Properties
	section is not set, then the legacy-amqp-topic-binding filter matches only if the value
	of the filter is a single "#".
	</p>
	</doc>
	</type>

	<type class="restricted" name="legacy-amqp-headers-binding" source="map" provides="filter">
	<descriptor name="apache.org:legacy-amqp-headers-binding:map" code="0x0000468C:0x00000002"/>
	<doc>
	<p>
	The legacy-amqp-headers-binding filter consists of a described map value. The map
	value described by the type is interpreted as a pattern to match against the
	application-properties section of the message being evaluated. The map has the same
	restriction as the application-properties section, namely that the keys of this are
	restricted to be of type string (which excludes the possibility of a null key) and the
	values are restricted to be of simple types only, that is, excluding map, list, and
	array types.
	</p>
	<p>
	The key "x-match" in the described map has special meaning. This key MUST map to the
	symbolic value "any" or the symbolic value "all" within the described map. All other
	keys which begin "x-" MUST be ignored by the source when evaluating. If the value for
	"x-match" is "all" then all other valid key-value pairs in the map MUST match with an
	entry with the same key in the application-properties section. If the value for
	"x-match" is "any" then the filter will accept the message if at least one key-value
	pair matches the equivalent key value pair in the application-properties section.
	</p>
	<p>
	A key-value pair in the filter's map matches a key-value pair in the
	application-properties section if the keys are identical (including the same type), or
	if the value in the filter map for the key is null.
	</p>
	</doc>
	</type>
	</section>
	<section name="jms" title="Java Message Service Support">

	<doc>
	<p>
	The Java Message Service defines two types of filtering of messages: firstly the ability to
	exclude from a subscription messages sent by the same connection, secondly a more general
	filtering syntax known as "selectors" based on an SQL like syntax.
	</p>
	<p>
	AMQP filter extensions through which these two types of
	filtering may be achieved are defined below. Their use, though
	motivated by support for JMS, is not restricted to JMS.
	</p>
	</doc>

	<type class="composite" name="no-local-filter" source="list" provides="filter">
	<descriptor name="apache.org:no-local-filter:list" code="0x0000468C:0x00000003"/>
	<doc>
	<p>
	A message will be accepted by the simple-no-local-filter if and only if the message
	was originally sent to the container of the source on a separate connection from that
	which is currently receiving from the source.
	</p>
	<p>
	Containers which support this filter should advertise the
	capability <term>APACHE.ORG:NO_LOCAL</term> in their
	connection capabilities when sending the open
	performative, and MUST provide this capability on sources
	supporting these filter types.
	</p>
	</doc>
	</type>

	<type class="restricted" name="selector-filter" provides="filter" source="string">
	<descriptor name="apache.org:selector-filter:string" code="0x0000468C:0x00000004"/>
	<doc>
	<p>
	The Java Message Service "selector" defines an SQL like
	syntax for filtering messages. The selector filters based
	on the values of "headers" and "properties". The
	selector-filter uses the selector as defined by JMS but
	with the names of JMS headers translated into their AMQP
	equivalents. The defined JMS headers can be mapped to
	equivalent fields within the AMQP message sections:
	</p>
	<picture title="Mapping JMS Headers to AMQP fields">
	JMS Header Name \| AMQP 1.0 Field
	==================\|====================================================
	JMSCorrelationID \| correlation-id field of properties section
	JMSDeliveryMode \| durable field of header section
	JMSDestination \| to field of the properties section
	JMSExpiration \| absolute-expiry-time of properties section
	JMSMessageID \| message-id of properties section
	JMSPriority \| priority field of header section
	JMSRedelivered \| delivery-count > 0 in header section
	JMSReplyTo \| reply-to in properties section
	JMSTimestamp \| creation-time of properties section
	JMSType \| annotation jms-type in message-annotations section
	</picture>
	<p>
	When encoding the selector string on the wire, these JMS
	header names should be translated to amqp.<i>field_name</i>
	where <i>field_name</i> is the appropriate AMQP 1.0 field
	named in the table above, with the hyphen replaced by an
	underscore. For example, the selector: "JMSCorrelationID =
	'abc' AND color = 'blue' AND weight > 2500" would be
	transferred over the wire as: "amqp.correlation_id = 'abc'
	AND color = 'blue' AND weight > 2500"
	</p>
	<p>
	The "properties" of the JMS message are equivalent to the AMQP application-properties
	section. Thus a reference to a property Foo in a message selector would be evaluated
	as the value associated with the key "Foo" (if present) in the application-properties
	section.
	</p>
	<p>
	The operands of the JMS selector are defined in terms of the types available within JMS,
	When evaluated against the application properties section, the values within that section
	MUST be evaluated according to the following type mapping.
	</p>
	<picture title="Mapping AMQP types to JMS types">
	AMQP Type \| JMS Selector Type
	==================\|===================
	null \| null
	boolean \| boolean
	ubyte \| short
	ushort \| int
	uint \| long
	ulong \| long
	byte \| byte
	short \| short
	int \| int
	long \| long
	float \| float
	double \| double
	decimal32 \| double
	decimal64 \| double
	decimal128 \| double
	char \| char
	timestamp \| long
	uuid \| byte[16]
	binary \| byte[]
	string \| String
	symbol \| String
	</picture>
	<p>
	Containers which support this filter should advertise the
	capability <term>APACHE.ORG:SELECTOR</term> in their
	connection capabilities when sending the open
	performative, and MUST provide this capability on sources
	supporting these filter types.
	</p>
	</doc>
	</type>
	</section>
	<section name="xquery" title="An xquery based filter">
	<type class="restricted" name="xquery" source="string" provides="filter">
	<descriptor name="apache.org:xquery-filter:string" code="0x0000468C:0x00000005"/>
	<doc>
	<p>
	The xquery filter consists of a described string value
	containing a valid xquery string against which messages
	are matched.
	</p>
	<p>
	Containers which support the filter defined in this
	section should advertise the capability
	<term>APACHE.ORG:XQUERY</term> in their connection
	capabilities when sending the open performative.
	</p>
	</doc>
	</type>
	</section>
	</amqp>