| Help Needed
This information has not been verified; todo make sure its correct; for instance, we are sure the EBNF grammar has been extended.
This is a new set of features in JON 2.0 that attempts to further automate the management of inventories, especially large ones.
A group definition is a rich, expressive "short-hand" for resource groups. At a high-level, a definition tells the system how to create a group; the details are handled by specifying a list of rules that tell the system how to find and aggregate the appropriate resources to add as members of the group.
Think of all the ways you might want to group resources in an enterprise: by cluster identifier, by broadcast group or some other network-level means, by logical service layer, by geographical location, by security domain, e.t.c.
Any individual resource may fall into multiple "buckets", and thus could potentially be a member of multiple groups. However this becomes a problem and more evident in large inventories. Do you really want to spend hours and hours creating hundreds of groups for thousands of resources across dozens of attributes?
It might not seem so bad if you only had to do it once, but nowadays enterprises are changing every day. Machines are stood up, reach an end of life, re-purposed or upgraded (hardware or software). With enterprises changing so rapidly, who really has the time to sit and make sure all of the hundreds of resource groups have accurate memberships?
Whereas in JON 1.x you had to create and populate all of your compatible and mixed groups, now you can leverage group definitions to do that tedious work for you. So what exactly can you do with this rich, expressive short-hand?
This section describes all the different attributes of a resource that you can leverage to write your definition. Please note that this section does not describe how to use group definitions (this is discussed later in this chapter). This section can serve as a quick reference for the terms that are supported when building up expressions.
|Subsystem||Major Type||Supported Attributes|
|Inventory||resource||id, name, version, parent-resource, grandparent-resource|
|resourceType||plugin, name, category (platform, server, service)|
A group definition is a collection of one or more valid expressions, and each expression must follow one of the following formats:
- <resource-expression> [ <string-match-expression> ] = <value>
- "groupby" <resource-expression>
- "memberof = <group name>
The first format is called a simple expression; the second, a pivoted expression; and the third, a narrowing expression. A group definition that contains only simple expressions (the first format) will only create one child group. A group definition that contains even one pivoted expression, has the potential to create many groups (see the other "Syntax References" sections for more information). Any created groups can be narrowed to be a subset of specified groups.
For those who like to refer to concise documentation
Extended Backus Naur form was used in favor of its more classical predecessor primarily to take advantage of the more concise and natural representation for repetition and grouping.
This section describes the <resource-expression> element in a much more explicit way. It contains every single unique path expression that can be formed by "unrolling" the current grammar.resource.id
Remember, each of these expressions can either be:
- prefixed with "groupby" (if you want to form a pivoted expression), or
- suffixed with "= <value>" (if you want to form a simple expression)
| Handy Hint
Simple expressions can match on a portion of the name using the optional <string-match-expression> element above. (see the example entitled "Just the raw measurement tables" below for sample usage)
Unfortunately, JON does not yet have an easy way to look up what the valid property names are for the pluginConfiguration, resourceConfiguration, or the traits. However, there is a way to navigate the resource type hierarchy using a special JSP page available only to administrators.
- Login as the administrator account ('rhqadmin', by default)
- Start by going to the following URL – http://<JON_BASE_URL>/admin/browser.jsp
- From there, navigate down to resource.ResourceType, and click it
- Then select from some resource type in the list (such as "JBossAS Server"), and click it
- In the "Simple Properties" table, click the pluginConfigurationDefinition link
- On this page, the names of all of the valid elements are in the "propertyDefinitions" section of the table
- For "JBossAS Server", you should see things like namingURL, principal, credentials, jbossHomeDir, configurationPath, configurationSet, etc
You can follow this same procedure to find the names of the resourceConfiguration properties too, just click the resourceConfigurationDefinition in step 5 instead of pluginConfigurationDefinition.
In each "unrolled" case above, the expression could have taken on one of two types - a pivoted expression, or a simple expression. A simple expression requires that you specify exactly one value that the expression must match. An example of this would be:resource.parent.type.category = Platform
This means that you want to search your entire inventory and find any resources that have a parent which happens to be a platform. In other words, you intend to create a single group, and put all of the direct children resources of any platform in your inventory into it. You can also take a further step and add another filter to the one above:resource.parent.type.category = Platform
resource.name.contains = JBossAS
This compound expression (each part of which must be on a separate line) will now search the entire inventory as above, but this time it will only add resources to the group if they also have "JBossAS" anywhere in their name.
Unfortunately for large inventories, this would almost certainly create a group with a very large membership. So, from a practical standpoint, it starts to lose its luster. Luckily, we still have a few tricks up our group definition sleeves...
Pivoted expressions are where the real power of group definitions shines through. Their features are described below. As an example, if we had a pivoted expression like:groupby resource.parent.name
The above expression would first take the portion after the "groupby" text, and ask the inventory for ALL unique "resource.parent.name" results. In other words, it is going to find one result for each uniquely named resource in the system, as long as that resource has one or more children resources. For each unique result, it would create one group, and put any resource into it that matched that criteria.
So let's say our inventory looked like:
The first part of the expression would find all the unique names of the parent resources, in this case:
- ResourceParentA (which has 3 direct children)
- ResourceChildA2 (which has 2 direct children, which are the grandchildren of its parent)
- ResourceParentB (which has 4 direct children)
Then, it will create one group for each of them, and populate them as necessary to satisfy the expression. The group members would be as follows:
|ResourceParentA||ResourceChildA1, ResourceChildA2, ResourceChildA3|
|ResourceParentB||ResourceChildB1, ResourceChildB2, ResourceChildB3, ResourceChildB4|
With only a few characters we have now automated the creation of three groups (but this would be more in larger inventories), and the memberships of those groups (which, again, in this case was small, but would normally be on the order of dozens).
The above is only an introduction to pivoted expressions. JBoss ON also supports compound pivoted expressions, which look very similar to the compound simple expression discussed at the beginning of this tutorial. An example of a compound pivoted expression might be:
The "groupby" text is required in the front of each expression that you want to make a pivot. This compound expression creates a compatible group - since we know that the members of a compatible group all have the same type, we've pivoted on both the plugin that defined the type as well as the type name itself to ensure that we will automatically get one group for each unique type currently known to the system.
And if that wasn't powerful enough we took the pivot concept one step further. Instead of having one gigantic compatible group of, say, EJB3 Session Beans across your entire enterprise, we are also pivoting on the parent. We will therefore get one group for each collection of Session Beans that share the same parent.
As you can see, pivoted expressions give us the ability to create extremely fine-grained, automatically managed, divisions of our resources. For a small inventory, this is handy tool; for a large inventory, this is a priceless tool.
And if that weren't enough, we also support the mixing and matching of pivoted and non-pivoted expressions in the same group definition. Let's use our last example, but filter the results even more precisely as follows:
This compound, mixed expression would constrain the search a bit. Instead of creating one compatible group for every single resource type known in the system, it would only create compatible groups for every unique resource type that is also a server.
For example, the following two expressions are processed in exactly the same way:
But the following two are not:
Unfortunately, in JON 2.0.0 there was a restriction that all grouped expressions had to come at the end of the list. If you try to put the grouped expression at the top of the list, or even in the middle, you will see odd results. So, feel free to change the ordering as you see fit, within these restrictions. This was fixed, and released in the 2.0.1 version of the product.
For the purposes of readability, you are allowed to insert blank lines into a group definition to help visually separate or aggregate related expressions together. For example, the following is allowed:
If a definition is so restrictive that it creates groups which end up having no resource members that match the filters, the group will not be created. This happens when you try to create extremely fine-grained groups of resources that match a very specific set of properties. Instead of creating a few empty groups, which could consequently make managing large numbers resource groups more difficult, the system will suppress their creation. This is yet another convenience that was added to make managing large inventories more intuitive.
The "memberof" expression specifies a single group. Resulting groups will be a subset of the specified group, including its recursive members if it is a recursive group. Without this created groups will be generated using the entire inventory. Note that specifying an empty or non-existent group name will prevent any groups from being created.
Multiple "memberof" expressions are allowed in the group definition. Each "memberof" expression specifies a single group. If multiple "memberof" conditions are specified then the resulting groups will be a subset of the union of resources in the specified groups.
Note: this could create very many groups in large inventories