Red Hat Training
A Red Hat training course is available for Red Hat JBoss Operations Network
2.2. About the Dynamic Search Syntax
JBoss ON has its own search syntax for dynamic searches. The syntax is supposed to be relatively simple while covering a wide array of search-able items and allowing different phrases to be coupled together.
The basic dynamic search matched whatever text is entered in the search box in a general substring search. The search can allow a more detailed and targeted syntax, in this form:
[search_area].[search_property] operator value operator additional_search
The search_area identifies what type of entry — resource or group — is being searched for. This is an optional value because the search area is implied by the location of the search; i.e., searching in the Resources area implies a resource search, so it's not necessary to include the resource. part of the search.
Figure 2.3. Searching by Resources Traits
2.2.1. Basic String Searches
The simplest search with the dynamic search is a substring search. The given search term can match any part or all of the returned value.
Figure 2.4. Matching the Search Term
The search term agen has search suggestions that match (case-insensitive) every resource that has that string anywhere in its name, at the beginning (Agent Plugin Container), middle (RHQ Agent Launcher Script), or end (rhq_agent). Likewise, the results include every resource with that string, regardless of where it appears in the resource entry or attribute.
When multiple words or terms are used together, the search treats them each as individual search terms in an implied AND search. (These complex searches are covered more in Section 2.2.3, “Complex AND and OR Searches”.) However, there can be instances when a multi-word search term should be treated as a single search term, and, for that, the dynamic search allows quotation marks.
Important
Dynamic searches do not support wildcard characters like asterisks (*) or regular expressions.
The search syntax can use either single (') or double (") quotation marks to enclose a search term that includes whitespace. (Obviously, search terms without whitespaces do not require quotes.) If a search term has a series of space-separated words, then each word is treated as a separate search term in an AND search. For example:
postgres table myexampletable
Using quotation marks tells the search to treat that as a literal phrase rather than individual search terms. As with other search terms, phrases can be strung together in a space-separated list:
"My Compatible Group" 'test box' plugin=jboss 123.4.5.6 trait[partitionName]='my example group' server.example.com
If a search term contains double or single quotation marks in the name, then the other type of boundary character must be used. For example, this group name contains a single quotation mark (apostrophe) character:
name="Production's Main Group"
Make sure to use the same opening and closing term character (you cannot mix single and double quotation marks.) Also, a single quotation mark is only treated as a search definition character when it occurs at the beginning of a search term. 'Hello world requires a closing single quote; Production's does not.
A search can also look for a string where it occurs within a result. For this, the search allows boundary characters that set whether a string occurs at the beginning or end of a value or if it must be an exact match to the value.
The caret (^) character sets that a search term must appear at the beginning of the result string. For example:
resource.xml:id=^100
This means that only resources with an ID which starts with 100 will be returned in the search.
Likewise, a string may occur only at the end of a value. The boundary character for an end value is a dollar sign ($). For example:
script$
This returns any resource with any value that ends in script.
Using both a caret and a dollar sign, together, means that the matching result must exactly match the search term, with no additional characters.
The search characters in Table 2.1, “String Operators” limit the search string by setting where in the result value the string appears.
Table 2.1. String Operators
| Operator | Description |
|---|---|
| string | The string can occur anywhere in the result string. |
| ^string | The given string must appear at the beginning of the result value. |
| string$ | The given string must appear at the end of the result value. |
| ^string$ | The result must be an exact match of the given string, with no leading or trailing characters. |
Note
The dynamic search syntax treats null as an acceptable value for a search. Running a search which passes null will look for any resource or group with a null value for that property:
resource.trait[Database.startTime] = null
However, putting quotation marks around the term null will look for a resource or group with a value of the string null:
name = "null"
2.2.2. Property Searches
The search can be narrowed by looking for a specific value or type of attribute in the entry by using a search property. For example, looking for a resource with a CPU usage of 80% (trait) is different than looking for an entry with an ID that includes 80 (id). The available properties are listed in Table 2.2, “Resource Search Contexts” and Table 2.3, “Group Search Contexts”.
Note
It's possible to search using group criteria in the resource search, and the reverse, by specifying the search area and the appropriate properties. For example, it's possible to do a search in the groups area to return the list of groups that a specific resource belongs to. This is done by explicitly passing the search context and search property. For example, in the Groups page, to list any group which contains a resource managed by the Postgres plug-in:
resource.type.plugin = Postgres
Important
The parameter suggestions for connection, configuration, and trait use the internal property names for the property names (connection[property_name]) rather than the names used in the JBoss ON GUI.
Table 2.2. Resource Search Contexts
| Property | Description |
|---|---|
| resource.id | The resource ID number assigned by JBoss ON. |
| resource.name | The resource name, which is displayed in the UI. |
| resource.version | The version number of the resource. |
| resource.type.plugin | The resource type, defined by the plug-in used to manage the resource. |
| resource.type.name | The resource type, by name. |
| resource.type.category | The resource type category (platform, server, or service). |
| resource.availability | The resource availability, either UP or DOWN. |
| resource.pluginConfiguration[property-name] | The value of any possible configuration entry in a plug-in. |
| resource.resourceConfiguration[property-name] | The value of any possible configuration entry in a resource. |
| resource.trait[property-name] | The value of any possible measurement trait for a resource. |
There are slightly fewer search properties for groups, since groups have simpler entries than resources.
Table 2.3. Group Search Contexts
| Property | Description |
|---|---|
| group.name | The name of the group. |
| group.plug-in | For a compatible group, the plug-in which defines the resource type for this group. |
| group.type | For a compatible group, the resource type for this group. |
| group.category | The resource type category (platform, server, or service). |
| group.kind | The type of group, either mixed or compatible. |
| group.availability | The availability of resource in the group, either UP or DOWN. |
The operator first refers to how the results should match the search string (value). This can require an exact match, every value but the one given in the search string. The operator then refers to how multiple search strings relate to each other (AND or OR); both explicit AND and OR statements and parenthetical statements are allowed. Complex searches are covered in Section 2.2.3, “Complex AND and OR Searches”.
Table 2.4. Search String Operators
| Operator | Description |
|---|---|
| = | Case-insensitive match. |
| == | Case-exact match. |
| != | Case-insensitive negative match (meaning, the value is not the string). |
| !== | Case-exact negative match (meaning, the value is not the string). |
2.2.3. Complex AND and OR Searches
The dynamic search bar assumes that each individual word is a search term (unless terms are defined using quotation marks). Implicitly, multi-word searches are treated as AND searches. For example:
postgres server myserver
This is treated as a series of AND terms:
postgres AND server AND myserver
The dynamic search also allows OR searches, with terms separated by a pipe (|). For example:
postgres | jbossas
Both AND and OR searches can be entered, and complex searches can be written by stringing multiple search strings together. When there are both AND and OR search criteria, the AND terms are processed first. For example, this search term searches for both B and C, and then either A or B/C.
a | b c
Note
When there are both AND and OR terms used in a complex search, AND terms are given preference. However, terms in parenthesis are evaluated even before AND expressions, so parentheses can be used to override the natural search preference.
Search phrases can be nested to multiple levels using parentheses to group search terms. These parentheses can also be used to override the preferences for AND matches, forcing at least some OR expressions to be processed first. For example, this expression searches for the OR terms first, matching a OR b and c OR d, and then running an AND search on the results of the two OR searches:
(a | b) (c | d)
The results will contain several combinations of values: a c, a d, b c, and b d.
Multiple levels of nesting are allows. For example, this expression requires a AND either b OR c AND d:
(a) (b | (c d))
The matching resources, then, can contain values matching a c d or a b.
