AMQP Filter Expressions Version 1.0



AMQP Filter Expressions Version 1.0Working Draft 0223 August 2018Technical Committee:OASIS Advanced Message Queuing Protocol (AMQP) TCChairs:Rob Godfrey (rgodfrey@), Red HatClemens Vasters (clemensv@), MicrosoftEditors:Clemens Vasters (clemensv@), MicrosoftAdditional artifacts:This prose specification is one component of a Work Product that also includes:XML schemas: (list file names or directory name)Other parts (list titles and/or file names)Related work:This specification is related to:OASIS Advanced Message Queuing Protocol (AMQP) Version 1.0 Part 0: Overview. Edited by Robert Godfrey, David Ingham, and Rafael Schloming. 29 October 2012. OASIS Standard. XML namespaces:list namespaces declared within this specificationAbstract:The AMQP Filter Expressions specification describes a syntax for expressions consisting of property selectors, functions, and operators that can be used for conditional transfer operations and for configuring a messaging infrastructure to conditionally distribute, route, or retain messages.Status:This Working Draft (WD) has been produced by one or more TC Members; it has not yet been voted on by the TC or approved as a Committee Draft (Committee Specification Draft or a Committee Note Draft). The OASIS document Approval Process begins officially with a TC vote to approve a WD as a Committee Draft. A TC may approve a Working Draft, revise it, and re-approve it any number of times as a Committee Draft.This specification is provided under the RF on RAND Terms Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established. For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the TC’s web page ().Note that any machine-readable content (Computer Language Definitions) declared Normative for this Work Product is provided in separate plain text files. In the event of a discrepancy between any such plain text file and display content in the Work Product's prose narrative document(s), the content in the separate plain text file prevails.URI patterns:Initial publication URI: “Latest version” URI:(Managed by OASIS TC Administration; please don’t modify.)Copyright ? OASIS Open 2018. All Rights Reserved.All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.Table of Contents TOC \o "1-6" \h \z \u 1Introduction PAGEREF _Toc515367887 \h 41.1 IPR Policy PAGEREF _Toc515367888 \h 41.2 Terminology PAGEREF _Toc515367889 \h 41.3 Normative References PAGEREF _Toc515367890 \h 41.4 Non-Normative References PAGEREF _Toc515367891 \h 42Section Title PAGEREF _Toc515367892 \h 62.1 Level 2 section title PAGEREF _Toc515367893 \h 62.1.1 Level 3 section title PAGEREF _Toc515367894 \h 62.1.1.1 Level 4 section title PAGEREF _Toc515367895 \h 62.1.1.1.1 Level 5 PAGEREF _Toc515367896 \h 62.1.1.1.1.1Level 6 PAGEREF _Toc515367897 \h 63Conformance PAGEREF _Toc515367898 \h 7Appendix A. Acknowledgments PAGEREF _Toc515367899 \h 8Appendix B. Example Title PAGEREF _Toc515367900 \h 9B.1 Subsidiary section PAGEREF _Toc515367901 \h 9B.1.1 Sub-subsidiary section PAGEREF _Toc515367902 \h 9B.1.1.1 Sub-sub-subsidiary section PAGEREF _Toc515367903 \h 9B.1.1.1.1 Sub-sub-sub-subsidiary section PAGEREF _Toc515367904 \h 9Appendix C. Revision History PAGEREF _Toc515367905 \h 10IntroductionThis specification defines a set of AMQP type definitions for message filter expressions. Those filter expressions are designed for use in other specifications or by AMQP applications that require durable or ephemeral configuration of message filters. An example for such a configuration is the creation of a durable subscription on a message topic similar to the equivalent Java Message Service (JMS) construct.This specification only defines the data types and related syntax definitions for filters and does not prescribe specific application scenarios. The “property filter” type is specifically optimized for high-performance scenarios, does not require text parsing, and only allows for very simple matching conditions. The “SQL filter” type leans on SQL-92 just as the familiar SQL filter syntax used by Java Message Service (JMS) specifications and allows for complex filter conditions and also for implementation-specific extensibility.IPR PolicyThis specification is provided under the RF on RAND Terms Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established. For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the TC’s web page ().TerminologyThe key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] and [RFC8174] when, and only when, they appear in all capitals, as shown here.When used in this specification and unless explicitly stated otherwise, the term “message” always refers to an AMQP message using the default message format of [AMQP 1.0, 3.2.16] Normative References[RFC2119]Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <;.[RFC8174]Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <;.[AMQP 1.0][Full reference citation]Non-Normative References[Reference][Full reference citation](Remove Non-Normative References section if there are none. Remove this note and text below before submitting for publication.)Note: Each reference to a separate document or artifact in this work must be listed here and must be identified as either a Normative or a Non-Normative Reference. For all References – Normative and Non-Normative:Recommended approach: Set up [Reference] label elements as "Bookmarks", then create hyperlinks to them within the document. (Here’s how: Insert hyperlinkPlace in this documentscroll down to Bookmarks, select appropriate one.)Use the "Ref" paragraph style to format references.The proper format for citation of technical work produced by an OASIS TC (whether Standards Track or Non-Standards Track) is:[Citation Label]Work Product title (italicized). Edited by Albert Alston, Bob Ballston, and Calvin Carlson. Approval date (DD Month YYYY). OASIS Stage Identifier and Revision Number (e.g., OASIS Committee Specification Draft 01). Principal URI (version-specific URI, e.g., with stage component: somespec-v1.0-csd01.html). Latest version: (latest version URI, without stage identifiers).For example:[OpenDoc-1.2]Open Document Format for Office Applications (OpenDocument) Version 1.2. Edited by Patrick Durusau and Michael Brauer. 19 January 2011. OASIS Committee Specification Draft 07. . Latest version: sources:For references to IETF RFCs, use the approved citation formats at: references to W3C Recommendations, use the approved citation formats at: this note before submitting for publication.Filter ExpressionsFilter expressions are logical statements that refer to elements of an AMQP 1.0 message using the default AMQP message format as defined in AMQP 1.0, Section 3.2.16. When applied to a message, an expression MUST evaluate to a Boolean “true” or “false” result. Filter expressions can be used to include or exclude messages from a candidate set into a result set.Filter expressions either evaluate groups of other filter expressions, or they are evaluated referring to the fields contained within the “header” [AMQP 1.0, 3.2.1], “delivery-annotations” [AMQP 1.0, 3.2.2], “message-annotations” [AMQP 1.0, 3.2.3], “properties” [AMQP 1.0, 3.2.4], “application-properties” [AMQP 1.0, 3.2.5], “amqp-sequence” [AMQP 1.0, 3.2.7], “amqp-value” [AMQP 1.0, 3.2.8], and “footer” [AMQP 1.0, 3.2.9] sections of a message. Filters cannot be applied to contents the “data” payload section [AMQP 1.0, 3.2.6] of an AMQP message because the binary payload is opaque to the AMQP container presumably also encrypted. Grouping filter expressionsGrouping filter expressions allows logical combinations of other filter expressions. A grouping filter is of the AMQP archetype “filter” as a restriction of the “list” base type and enumerates one or more objects of archetype “filter”.Because grouping filters are filters they can themselves be grouped. Implementations supporting grouping expressions MAY restrict the depth of nesting permitted.all filterThis filter type groups one of multiple filters and evaluates to true if all filters it contains evaluate to true when matched against the candidate message. This is a logical “and” operation.<type name="all-filter" class="restricted" source="list" provides="filter"> <descriptor name="amqp:all-filter " code="0x00000000:0xFEFEFEFE"/></type>The filter-type is “amqp:all-filter”, with type-code 0x00000000:0xFEFEFEFE (To be assigned).any filterThis filter type groups one of multiple filters and evaluates to true if any of the filters it contains evaluate to true when matched against the candidate message. This is a logical “or” operation.<type name="any-filter " class="restricted" source="list" provides="filter"> <descriptor name="amqp:any-filter" code="0x00000000:0xFEFEFEFE"/></type>The filter-type is “amqp:any-filter”, with type-code 0x00000000:0xFEFEFEFE (To be assigned).not filterThis filter type groups one of multiple filters and evaluates to true if none of the filters it contains evaluate to true when matched against the candidate message.<type name="not-filter" class="restricted" source="list" provides="filter"> <descriptor name="amqp:not-filter" code="0x00000000:0xFEFEFEFE"/></type>The filter-type is “amqp:not-filter”, with type-code 0x00000000:0xFEFEFEFE (To be assigned).Property Filter ExpressionsProperty filters allow matching of message metadata against reference metadata. A property filter is if the archetype “filter”, and there are property filter types for each of these AMQP message sections: “header”, “message-annotations”, “properties”, “application-properties”, “amqp-sequence”, “amqp-value”, and “footer”.Each of the property filter types is a restriction of its corresponding message metadata section type, and therefore subject to the exact same rules as the respective message metadata section. For instance, the “properties-filter” reference expression type restricts the AMQP “properties” type and inherits all of its definitions.Any newly created instance of a property filter MUST have the values of all fields explicitly initialized to null, overriding any default values defined by the base type.A property filter matches the corresponding AMQP message section and is evaluated as true if each element of the reference data in the property filter matches the corresponding element in the AMQP message section.A field value in a property filter type matches its corresponding message metadata field value if:The reference field value is absent or NULL, orthe reference field value is equal to the value of the corresponding message metadata field, orthe reference field value is of an integer number type and the message metadata field is of a different integer number type, the reference value and the metadata field value are within the value range of both types, and the values are equal,the reference field value is of a floating-point number type and the message metadata field is of a different floating-point number type, the reference value and the metadata field value are within the value range of both types, and the values are equal, the reference field value is of type string and the reference field value’s and the message metadata field length is identical and ordinal values of the characters in the sequence match exactly (case sensitive), or the reference field value is of type string and that string is decorated with a modifier prefix (‘&&’+{operator}+’:’), and the message metadata field satisfies the modifier’s matching rule: Modifier PrefixDescription&S:suffixSuffix, case-sensitive. The message metadata field matches the expression if the ordinal values of the characters of the suffix expression equal the ordinal values of the same number of characters trailing the message metadata field value.&P:prefixPrefix, case-sensitive. The message metadata field matches the expression if the ordinal values of the characters of the prefix expression equal the ordinal values of the same number of characters leading the message metadata field value.&s:suffixSuffix, case-insensitive. The message metadata field matches the expression if the case-insensitive values of characters of the suffix expression equal the same number of case-insensitive values of characters trailing the message metadata field value.&p:prefixPrefix, case-insensitive. The message metadata field matches the expression if the case-insensitive values of characters of the prefix expression equal the same number of case-insensitive values of characters leading the message metadata field value.&i:expressionCase-insensitive. The message metadata field matches the expression if the case-insensitive values of characters of the expression equal the same number of case-insensitive values of characters in the message metadata field value.&&remaining-stringEscape prefix for case-sensitive matching of a string starting with ‘&’A map in a property filter matches its message metadata counterpart, for instance in the case of the “application-properties” section, if:every entry in the reference map is present (key lookup match) in the message metadata map, ANDthe value of the reference map entry matches the corresponding message metadata map value following the field matching rules defined above.A list in a property filter matches its message metadata counterpart, for instance in the case of the “amqp-sequence” section, if:every entry in the reference list is present (positional match) in the message metadata list, ANDthe value of the reference list entry matches the corresponding message metadata list value following the field matching rules defined above.properties filtersThis filter type applies to the immutable AMQP properties of the message (AMQP 3.2.4).The filter evaluates to true if all properties enclosed in the filter type match the respective properties in the message. Because the properties base type is an AMQP list, the default value for all elements in the filter is assumed to be null. <type name="properties-filter" class="restricted" source="properties" provides="filter"><descriptor name="amqp:properties-filter" code="0x00000000:0xFEFEFEFE"/></type>The filter-type is “amqp:properties-filter”, with type-code 0x00000000:0xFEFEFEFE (To be assigned).application-properties filterThis filter type applies to the AMQP application-properties section (AMQP 3.2.5).The filter evaluates to true if all properties enclosed in the filter type match the respective properties in the message. <type name="application-properties-filter" class="restricted" source="application-properties" provides="filter"><descriptor name="amqp:application-properties-filter" code="0x00000000:0xFEFEFEFE"/></type>The filter-type is “amqp:application-properties-filter”, with type-code 0x00000000:0xFEFEFEFE (To be assigned).message-annotations filterThis filter type applies to the AMQP message-annotations section (AMQP 3.2.3).The filter evaluates to true if all annotations enclosed in the filter type match the respective annotations in the message. <type name="message-annotations-filter" class="restricted" source="message-annotations" provides="filter"><descriptor name="amqp:message-annotations-filter" code="0x00000000:0xFEFEFEFE"/></type> The filter-type is “amqp:message-annotations-filter”, with type-code 0x00000000:0xFEFEFEFE (To be assigned).header filterThis filter type applies to the AMQP header section (AMQP 3.2.1).The filter evaluates to true if all header fields enclosed in the filter type match the respective header field values in the message. Because the header base type is an AMQP list, the default value for all elements in the filter is assumed to be null. <type name="header-filter" class="restricted" source="header" provides="filter"><descriptor name="amqp:header-filter" code="0x00000000:0xFEFEFEFE"/></type>The filter-type is “amqp:header-filter”, with type-code 0x00000000:0xFEFEFEFE (To be assigned).footer filterThis filter type applies to the AMQP footer section (AMQP 3.2.9).The filter evaluates to true if all footer fields enclosed in the filter type match the respective footer fields in the message. <type name="footer-filter" class="restricted" source="footer" provides="filter"><descriptor name="amqp:footer-filter" code="0x00000000:0xFEFEFEFE"/></type> The filter-type is “amqp:footer-filter”, with type-code 0x00000000:0xFEFEFEFE (To be assigned).SQL Filter Expressions.SQL filter expressions allow matching of message metadata against complex expressions that lean on the syntax of Structured Query Language (SQL) WHERE clauses. Using SQL-derived expressions for message filtering is in widespread implementation use because the Java Message Service (JMS) message selector syntax also leans on SQL. Neither the SQL standard (ISO 9075) nor the JMS standard are used as a normative foundation or constrain the expression syntax defined in this specification, but the syntax is informed by them.A SQL filter is of the AMQP archetype “filter” and restricts the string type to holding a text expression that follows the grammar rules described in this section. The grammar allows access to the “header”, “footer”, “message-annotations”, “properties”, “application-properties”, “amqp-value”, and “amqp-sequence” sections of any candidate message.<type name="sql-filter" class="restricted" source="string" provides="filter"><descriptor name="amqp:sql-filter" code="0x00000000:0xFEFEFEFE"/></type> The filter-type is “amqp:sql-filter”, with type-code 0x00000000:0xFEFEFEFE (To be assigned).Grammar ElementsThis whole section will need quite a bit more work, but I have most of the pieces there that I think we’ll need, including section qualifiers and composite type and array references.Predicatespredicate ::= unary-logical-operator predicate | predicate binary-logical-operator predicate | expression comparison-operator expression | property_value ‘IS’ [‘NOT’] ‘NULL’ | <expression> [‘NOT’] ‘IN’ ( <expression> {‘,’ <expression>} ) | <expression> [‘NOT’] ‘LIKE’ <pattern> [‘ESCAPE’ <escape_char>] | ‘EXISTS’ ‘(‘ <property> ‘)’ | ‘(‘ <predicate> ‘)’ Operatorsunary-logical-operator ::= ‘NOT’binary-logical-operator ::= ‘AND’ | ‘OR’comparison-operator ::= ‘=’ | ‘<>’ | ‘!=’ | ‘>’ | ‘>=’ | ‘<’ | ‘<=’Expressions<expression> ::= <constant> | <function> | <property_value> | <expression> ‘+’ | ‘-‘| ‘*’ | ‘/’ | ‘%’ <expression> | ‘+’ | ‘-‘ <expression> | ‘(‘ <expression> ‘)’ <pattern> ::= <expression> <pattern> must be an expression that is evaluated as a string. It is used as a pattern for the LIKE operator. It can contain the following wildcard characters:%: Any string of zero or more characters._: Any single character.<escape_char> ::= <expression> <escape_char> must be an expression that is evaluated as a string of length 1. It is used as an escape character for the LIKE operator.For example, property LIKE 'ABC\%' ESCAPE '\' matches ABC% rather than a string that starts with ABC.Constant Expressions<constant> ::= <integer_constant> | <decimal_constant> | <approximate_number_constant> | <boolean_constant> | NULL <integer_constant> is a string of numbers that are not enclosed in quotation marks and do not contain decimal points. <decimal_constant> is a string of numbers that are not enclosed in quotation marks, and contain a decimal point. <approximate_number_constant> is a number written in scientific notation<boolean_constant> := TRUE | FALSE <string_constant>String constants are enclosed in single quotation marks and include any valid Unicode characters. A single quotation mark embedded in a string constant is represented as two single quotation marks.Property References and Values<property_value> := <property> | <property>[‘.’<composite_type_reference>] | <property><array_element_reference><property> ::= [<section>’.’] <property_name> <section> ::= [‘header’ | ‘h’] | [‘footer’ | ‘f’] | [‘properties’ | ‘p’] | [‘application_properties’ | ‘a’] | [‘message_annotations’ | ‘m’] | [‘amqp-value’ | ‘v’] | [‘amqp-sequence’ | ‘s’] <section> is a qualifier for the section to which the <property> reference applies. The section qualifier ‘header’, with shorthand ‘h’, refers to the respective section in the AMQP message, and the other qualifiers refer to the same-named sections equivalently.<property_name> ::= <identifier> | <delimited_identifier> Composite Type and Array Value References <composite_type_reference> := <field_name> | <field_name> ’.’ <composite_type_reference> | <field_name> <array_element_reference><array_element_reference> := ‘[‘ <expression> ‘]’<field_name> ::= <identifier> | <delimited_identifier> Identifier Syntax<identifier> ::= <regular_identifier> | <delimited_identifier> <regular_identifier>:= <letter> {<letter> | <underscore> | <digit> }<delimited_identifier>:= ‘[‘ {<letter> | <symbol> | <digit> } ‘]’Conformance(Note: The OASIS TC Process requires that a specification approved by the TC at the Committee Specification Public Review Draft, Committee Specification or OASIS Standard level must include a separate section, listing a set of numbered conformance clauses, to which any implementation of the specification must adhere in order to claim conformance to the specification (or any optional portion thereof). This is done by listing the conformance clauses here.For the definition of "conformance clause," see OASIS Defined Terms. See "Guidelines to Writing Conformance Clauses": this note before submitting for publication.)Acknowledgments(Note: A Work Product approved by the TC must include a list of people who participated in the development of the Work Product. This is generally done by collecting the list of names in this appendix. This list shall be initially compiled by the Chair, and any Member of the TC may add or remove their names from the list by request.Remove this note before submitting for publication.)The following individuals have participated in the creation of this specification and are gratefully acknowledged:Participants: MACROBUTTON [Participant Name, Affiliation | Individual Member][Participant Name, Affiliation | Individual Member]Example TitletextSubsidiary sectiontextSub-subsidiary sectionTextSub-sub-subsidiary sectiontextSub-sub-sub-subsidiary sectiontextRevision HistoryRevisionDateEditorChanges Made[Rev number][Rev Date][Modified By][Summary of Changes] ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download