Composing a Search Expression

Note Only the STRING attribute type is supported on deployable descriptors or connected CIs. The attribute cannot be static and cannot contain calculated attributes.

A search expression is composed from logical operators and conditions. Supported logical operators are “And” and “Or”.

Conditions are expressions that are evaluated using a provider’s connection strings and a consumer’s configuration documents. Conditions differ according to the type of the file, that is, properties configuration documents have different conditions than XML documents.

Here is an example of a search expression for a properties configuration document: To create a dependency between a provider and consumer, only if the provider’s IP address exists in the consumer’s MyConfig.properties configuration document under the key IPADDRESS. This would be written in the dependency configuration document as:

<PropertiesConfigurationDocument name="MyConfig.properties"> (Type and name of the configuration document)
   <Condition> (Beginning of the search expression)
      <Operator type="and"> (Operator)
         <KeyCondition key="IPADDRESS"> (Start a condition and state its type)
            <Values>
               <Value>${IP_ADDRESS}</Value> (Use a variable stating the provider’s IP address)
            </Values>
         </KeyCondition>
      </Operator>
   </Condition>
</PropertiesConfigurationDocument>

Note

  • You can use the wildcard character "*" in a signature file to specify multiple configuration documents, for example, use *.properties in the example above. The "*" character must be the first character in the name string.
  • There must be at least one <Operator> element in a <Condition> element, even if it is logically unnecessary, since there is only one search condition, as in the example above.

Let’s look at a more complicated search expression: Either the provider’s IP address exists in the consumer’s MyConfig.properties configuration document under the key IPADDRESS, or the provider’s host name exists in the same file under the key HOST:

<PropertiesConfigurationDocument name="MyConfig.properties"> (Type and Name of the configuration document)
   <Condition> (Beginning of the search expression)
      <Operator type="or"> (Operator)
         <KeyCondition key="IPADDRESS"> (Start a condition and state its type)
            <Values>
               <Value>${IP_ADDRESS}</Value> (Use a variable stating the provider’s IP address)
            </Values>
         </KeyCondition>
         <KeyCondition key="HOST"> (Start another condition, under the same operator)
            <Values>
               <Value>${HOSTNAME}</Value> (Use a variable stating the provider’s host name)
            </Values>
         </KeyCondition>
      </Operator>
   </Condition>
</PropertiesConfigurationDocument>

The logical operators can be nested to create conditions such as (C1 AND (C2 OR C3)), so the XML would look like this:

<PropertiesConfigurationDocument name="MyConfig.properties"> (Type and Name of the configuration document)
   <Condition> 
      <Operator type="and"> 
         C1
         <Operator type=”or”>
            C2
            C3
         </Operator>
      </Operator>
   </Condition>
</PropertiesConfigurationDocument>

where C1, C2, C3 are the XML snippets of the required search conditions.

There are three supported type of files, and each has its own type of search expression:

  • PropertiesConfigurationDocument – a file where each line has the format of key=value. For more information, see Properties Configuration Documents.

    KeyCondition – a condition on the value of a given key

  • XmlConfigurationDocument – an XML file. For more information, see XML Configuration Documents.

    XPathCondition – evaluates an XPath query

  • TextConfigurationDocument – any text configuration document. For more information, see Text Configuration Documents.

    RegExp – evaluates a regular expression

For more information about default values, see Using Default Values of Variables.

ClosedTroubleshooting

  • Having different concepts in the same node of condition tree is not permitted. Likewise, having two leaves with different concepts under the same operator is also not permitted.

    For example, the following condition definition is invalid:

    <Condition>
    <Operator type="and">
        <XPathCondition>
            <XPath>/Setup/Configuration/Hostname[matches(@Name, '.*?${Concept1.HOSTNAME}.*')]</XPath>
        </XPathCondition>
        <XPathCondition>
            <XPath>/Setup/Configuration/Port[matches(text(), '${Concept2.PORT}')]</XPath>
        </XPathCondition>
    </Operator>
</Condition>