RTI Connext Java API
Version 6.1.0
|
A subset of SQL syntax is used in several parts of the specification:
filter_expression
in the com.rti.dds.topic.ContentFilteredTopic query_expression
in the com.rti.dds.subscription.QueryCondition topic_expression
in the com.rti.dds.topic.MultiTopic filter_expression
in the com.rti.dds.subscription.TopicQuerySelection filter_expression
in the com.rti.dds.infrastructure.ChannelSettings_tThose expressions may use a subset of SQL, extended with the possibility to use program variables in the SQL expression. The allowed SQL expressions are defined with the BNF-grammar below.
The following notational conventions are made:
'Terminals'
are quoted and typeset in a fixed width font. They are written in upper case in most cases in the BNF-grammar below, but should be case insensitive.
Expression ::= FilterExpression
| TopicExpression
| QueryExpression
.
FilterExpression ::= Condition
TopicExpression ::= SelectFrom { Where } ';'
QueryExpression ::= { Condition }{ 'ORDER BY'
(FIELDNAME // ',') }
.
SelectFrom ::='SELECT'
Aggregation'FROM'
Selection . Aggregation ::='*'
| (SubjectFieldSpec // ',') . SubjectFieldSpec ::= FIELDNAME | FIELDNAME'AS'
IDENTIFIER | FIELDNAME IDENTIFIER . Selection ::= TOPICNAME | TOPICNAME NaturalJoin JoinItem . JoinItem ::= TOPICNAME | TOPICNAME NaturalJoin JoinItem |'('
TOPICNAME NaturalJoin JoinItem')'
. NaturalJoin ::='INNER JOIN'
|'INNER NATURAL JOIN'
|'NATURAL JOIN'
|'NATURAL INNER JOIN'
. Where ::='WHERE'
Condition . Condition ::= Predicate | Condition'AND'
Condition | Condition'OR'
Condition |'NOT'
Condition |'('
Condition')'
. Predicate ::= ComparisonPredicate | BetweenPredicate . ComparisonPredicate ::= ComparisonTerm RelOp ComparisonTerm . ComparisonTerm ::= FieldIdentifier | Parameter . BetweenPredicate ::= FieldIdentifier'BETWEEN'
Range | FieldIdentifier'NOT BETWEEN'
Range . FieldIdentifier ::= FIELDNAME | IDENTIFIER . RelOp ::='='
|'>'
|'>='
|'<'
|'<='
|'<>'
|'LIKE'
|'MATCH'
. Range ::= Parameter'AND'
Parameter . Parameter ::= INTEGERVALUE | CHARVALUE | FLOATVALUE | STRING | ENUMERATEDVALUE | BOOLEANVALUE | PARAMETER .
Note – INNER JOIN, INNER NATURAL JOIN, NATURAL JOIN, and NATURAL INNER JOIN are all aliases, in the sense that they have the same semantics. They are all supported because they all are part of the SQL standard.
The syntax and meaning of the tokens used in the SQL grammar is described as follows:
Formal notation:
IDENTIFIER: LETTER (PART_LETTER)* where LETTER: [ "A"-"Z","_","a"-"z" ] PART_LETTER: [ "A"-"Z","_","a"-"z","0"-"9" ]
Formal notation:
FIELDNAME: FieldNamePart ( "." FieldNamePart )* where FieldNamePart : IDENTIFIER ( "[" Index "]" )* Index> : (["0"-"9"])+ | ["0x","0X"](["0"-"9", "A"-"F", "a"-"f"])+
Primitive IDL types referenced by FIELDNAME are treated as different types in Predicate according to the following table:
Predicate Data Type | IDL Type |
BOOLEANVALUE | boolean |
INTEGERVALUE | octet, (unsigned) short, (unsigned) long, (unsigned) long long |
FLOATVALUE | float, double |
CHARVALUE | char, wchar |
STRING | string, wstring |
ENUMERATEDVALUE | enum |
Formal notation:
TOPICNAME : IDENTIFIER
Formal notation:
INTEGERVALUE : (["+","-"])? (["0"-"9"])+ [("L","l")]? | (["+","-"])? ["0x","0X"](["0"-"9", "A"-"F", "a"-"f"])+ [("L","l")]?
Formal notation:
CHARVALUE : "'" (~["'"])? "'"
Formal notation:
FLOATVALUE : (["+","-"])? (["0"-"9"])* (".")? (["0"-"9"])+ (EXPONENT)? where EXPONENT: ["e","E"] (["+","-"])? (["0"-"9"])+
Formal notation:
STRING : "'" (~["'"])* "'"
Formal notation:
ENUMERATEDVALUE : "'" ["A" - "Z", "a" - "z"] ["A" - "Z", "a" - "z", "_", "0" - "9"]* "'"
Formal notation (case insensitive):
BOOLEANVALUE : ["TRUE","FALSE"]
Formal notation:
PARAMETER : "%" (["0"-"9"])+
Strings used as parameter values must contain the enclosing quotation marks (') within the parameter value, and not place the quotation marks within the expression statement. For example, the following expression is legal: <PRE>" symbol MATCH %0 " with parameter 0 = " 'IBM' "</PRE>whereas the following expression will not compile: <PRE>" symbol MATCH '%0' " with parameter 0 = " IBM "</PRE>
Only certain combination of type comparisons are valid in <i>Predicate</i>. The following table marked all the compatible pairs with 'YES': <TABLE> <TR> <TD></TD> <TD><b>BOOLEANVALUE</b></TD> <TD><b>INTEGERVALUE</b></TD> <TD><b>FLOATVALUE</b></TD> <TD><b>CHARVALUE</b></TD> <TD><b>STRING</b></TD> <TD><b>ENUMERATEDVALUE</b></TD> </TR> <TR> <TD><b>BOOLEAN</b></TD> <TD>YES</TD> <TD></TD> <TD></TD> <TD></TD> <TD></TD> <TD></TD> </TR> <TR> <TD><b>INTEGERVALUE</b></TD> <TD></TD> <TD>YES</TD> <TD>YES</TD> <TD></TD> <TD></TD> <TD></TD> </TR> <TR> <TD><b>FLOATVALUE</b></TD> <TD></TD> <TD>YES</TD> <TD>YES</TD> <TD></TD> <TD></TD> <TD></TD> </TR> <TR> <TD><b>CHARVALUE</b></TD> <TD></TD> <TD></TD> <TD></TD> <TD>YES</TD> <TD>YES</TD> <TD>YES</TD> </TR> <TR> <TD><b>STRING</b></TD> <TD></TD> <TD></TD> <TD></TD> <TD>YES</TD> <TD>YES(*1)</TD> <TD>YES</TD> </TR> <TR> <TD><b>ENUMERATEDVALUE</b></TD> <TD></TD> <TD>YES</TD> <TD></TD> <TD>YES(*2)</TD> <TD>YES(*2)</TD> <TD>YES(*3)</TD> </TR> </TABLE>
The relational operator MATCH may only be used with string fields. The right-hand operator is a string pattern. A string pattern specifies a template that the left-hand field value must match. The characters ,/\?*[]-^!% have special meanings unless they are escaped by the escape character \.
MATCH is case-sensitive.
The pattern allows limited "wild card" matching under the following rules:
Character | Meaning |
, | "," separates a list of alternate patterns. The field string is matched if it matches one or more of the patterns. |
/ | "/" in the pattern string matches a / in the field string. This character is used to separate a sequence of mandatory substrings. |
? | "?" in the pattern string matches any single non-special characters in the field string. |
* | "*" in the pattern string matches 0 or more non-special characters in field string. |
[charlist] | Matches any one of the characters from the list of characters in charlist. |
[s-e] | Matches any character any character from s to e, inclusive. |
% | "%" is used to designate filter expressions parameters. |
[!charlist] or [^charlist] | Matches any characters not in charlist (not supported). |
[!s-e] or [^s-e] | Matches any characters not in the interval [s-e] (not supported). |
\ | Escape character for special characters. |
The syntax is similar to the POSIX fnmatch syntax (1003.2-1992 section B.6). The MATCH syntax is also similar to the 'subject' strings of TIBCO Rendezvous.
The default encoding for IDL strings is UTF-8. RTI Connext offers ISO 8859-1 as an alternative encoding for IDL strings.
In order to configure ISO 8859-1 as the encoding for filtering of IDL strings, you can set the DomainParticipant property dds.domain_participant.filtering_character_encoding to ISO-8859:
The possible values for dds.domain_participant.filtering_character_encoding are:
Unicode supports multiple ways to encode some characters, most notably accented characters. A composed character in Unicode can often have a number of different ways of representing the character. For example:
The lexical comparison of the two characters above will return false. In order to do the correct comparison the characters need to be normalized, that is, reduced to the same character composition.
When the character encoding for filtering of IDL strings is UTF-8, the Unicode normalization behavior can be controlled using a DomainParticipant property called dds.domain_participant.filtering_unicode_normalization.
The possible values of the normalization property are:
Because normalization may affect performance, and it is enabled by default, the property allows disabling the normalization process per DomainParticipant using the value OFF. However, you should be aware that doing this may lead to unexpected behavior.
Assuming Topic "Location" has as an associated type a structure with fields "flight_id, x, y, z", and Topic "FlightPlan" has as fields "flight_id, source, destination". The following are examples of using these expressions.
Example of a filter_expression (for com.rti.dds.topic.ContentFilteredTopic) or a query_expression (for com.rti.dds.subscription.QueryCondition):
"z < 1000 AND x < 23"
Examples of a filter_expression using MATCH (for com.rti.dds.topic.ContentFilteredTopic) operator:
"symbol MATCH 'NASDAQ/GOOG'"
"symbol MATCH 'NASDAQ/[A-M]*'"
Example of a topic_expression (for com.rti.dds.topic.MultiTopic [Not supported (optional)]):
"SELECT flight_id, x, y, z AS height FROM 'Location' NATURAL JOIN 'FlightPlan' WHERE height < 1000 AND x <23"