Short Examples

CLI scripts follow a certain flow of events. Each functional element within that workflow, such as searching for a resource or object and then running an operation, has its own classes in the remote API.
Most actions in JBoss ON CLI scripts are repeatable — the part for running a search for a platform or for collecting live data for a metric is pretty similar across CLI scripts.
This section provides some basic examples for running a single, specific functional task. These individual script examples can be used consistently in larger script workflows and as part of task automation.

1. Searches

All object managers define operations for retrieving data. Most of the managers define criteria-based operations for data retrieval — meaning that the search can be based on attributes within the JBoss ON objects.
Criteria-based searches have methods in the form findObjectByCriteria, so a resource find method is findResourcesByCriteria and a group find method is findResourceGroupsByCriteria.
Searches are translated into a corresponding JPA-QL query.
The criteria classes reside in the org.rhq.core.domain.criteria package.

1.1. Setting Basic Search Criteria

The simplest criteria is to define results based on what they are, such as resource type, without any additional search parameters.
For example, this fetches all committed resources in the inventory because it has no filters to limit by resource type or ID.
rhqadmin@localhost:7080$ var criteria = new ResourceCriteria() // this sets the criteria to use for the search
rhqadmin@localhost:7080$ criteria.clearPaging() // this clears the 200 item page size to return all entries
rhqadmin@localhost:7080$ var resources = ResourceManager.findResourcesByCriteria(criteria) // this actually runs the search
rhqadmin@localhost:7080$ pretty.print(resources) // this prints the search results
id    name   versio curren resour
-------------------------------------------------------------------------------
10001 server Linux  UP     Linux
10002 server AS 4.2 UP     JBossA
10392 full-h        UP     Profil
10014 AlertH        UP     EJB3 S
10015 Adviso        UP     EJB3 S
10016 DataAc        UP     EJB3 S
10017 Affini        UP     EJB3 S
10011 Access        UP     Access
10391 ha            UP     Profil
...8<...
While the findResourcesByCriteria() is what runs the search, the pretty.print method is required to display the results.
This basic criteria search is translated into the following JPA-QL query:
SELECT r
FROM Resource r
WHERE ( r.inventoryStatus = InventoryStatus.COMMITTED

1.2. Using Sorting

The basic search criteria can be refined so that the resource results are sorted by plug-in.
To add sorting, call criteria.addSortPluginName(). Sorting criteria have methods in the form addSortXXX(PageOrdering order).
For example:
rhqadmin@localhost:7080$ var criteria = new ResourceCriteria() 
rhqadmin@localhost:7080$ criteria.addSortPluginName(PageOrdering.ASC) // adds a sort order to the results
rhqadmin@localhost:7080$ resources = ResourceManager.findResourcesByCriteria(criteria)
This criteria is translated into the following JPA-QL query:
SELECT r
FROM Resource r
WHERE ( r.inventoryStatus = InventoryStatus.COMMITTED )
ORDER BY r.resourceType.plugin ASC

1.3. Using Filtering

Adding additional matching criteria, like resource name in this example, further narrows the search results. To add filtering to any criteria, use methods of the form addFilterXXX().
rhqadmin@localhost:7080$ var criteria = new ResourceCriteria() 
rhqadmin@localhost:7080$ criteria.addFilterResourceTypeName('JBossAS Server') // a search filter
rhqadmin@localhost:7080$ resources = ResourceManager.findResourcesByCriteria(criteria)
The resulting JPA-QL query is as follows:
SELECT r
FROM Resource r
WHERE ( r.inventoryStatus = InventoryStatus.COMMITTED
AND LOWER( r.resourceType.name )  like 'JBossAS Server' ESCAPE '\\' )
This code retrieves all JBoss servers in the inventory. There can be multiple filters used with a single search. For example, this searches for JBoss servers that have been registered by a particular agent:
rhqadmin@localhost:7080$ var criteria = new ResourceCriteria()
rhqadmin@localhost:7080$ criteria.addFilterResourceTypeName('JBossAS Server')
rhqadmin@localhost:7080$ criteria.addFilterAgentName('localhost.localdomain')
rhqadmin@localhost:7080$ resources = ResourceManager.findResourcesByCriteria(criteria)
This generates the following JPA-QL query:
SELECT r
FROM Resource r
WHERE ( r.inventoryStatus = InventoryStatus.COMMITTED
AND LOWER( r.agent.name )  like 'localhost.localdomain' ESCAPE '\\' )

1.4. Fetching Associations

An association shows the hierarchy of parent and child resources. After retrieving the resources, it is possible to view their associated parent or child resources using a special fetch method.
Simply printing a list of children after a search will fail, even if the given server has child resources.
...8<...
rhqadmin@localhost:7080$ resource = resources.get(0)
rhqadmin@localhost:7080$ if (resource.childResources == null) print('no child resources')
The reason for this is that lazy loading is used throughout the domain layer for one-to-many and many-to-many associations. Since child resources are lazily loaded, the list of children has to explicitly set as a fetch in the search criteria.
For example:
rhqadmin@localhost:7080$ criteria.addFilterResourceTypeName('JBossAS Server')
rhqadmin@localhost:7080$ criteria.fetchChildResources(true)
rhqadmin@localhost:7080$ resources = ResourceManager.findResourcesByCriteria(criteria)
rhqadmin@localhost:7080$ resource = resources.get(0)
rhqadmin@localhost:7080$ if (resource.childResources == null) print('no child resources'); else pretty.print(resource.childResources)
id  name                               versio resourceType
-----------------------------------------------------------
222 AlertManagerBean                   EJB3 Session Bean
222 SchedulerBean                      EJB3 Session Bean
222 AlertDefinitionManagerBean         EJB3 Session Bean
222 AlertConditionConsumerBean         EJB3 Session Bean
222 PartitionEventManagerBean          EJB3 Session Bean
...8<...
The output varies depending on what is inventoried. These are the child resources of the JBoss ON server. The JPA-QL query that is generated appears as follows:
SELECT r
FROM Resource r
LEFT JOIN FETCH r.childResources
WHERE ( r.inventoryStatus = InventoryStatus.COMMITTED
AND LOWER( r.resourceType.name )  like 'JBossAS Server' ESCAPE '\\' )

1.5. Setting Page Sizes

Almost all searches return a paged list of results. By default, paged results are capped at 200 entries. So, for example, attempting to return all resources in the inventory only returns the first 200 resources, while querying the database directly may return several hundred resources.
The Criteria class defines some methods which can be used to control page sizes for search results.

Example 1. Clearing the Page Size

If there are more than 200 results, and all matching resources need to be contained in a single results set, the page limit can be cleared with the clearPaging
var criteria = new ResourceCriteria()
criteria.clearPaging()
var resources = ResourceManager.findResourcesByCriteria(criteria)

Example 2. Setting a Page Size

There can be times when a different page limit needs to be used, but for clarity or control, some paging still needs to be in effect.
The setPaging method sets the number of pages and the page size for the given search. Generally, since there is only a single page, the page number is set to 0, and then the page size can be reset higher or lower, as desired.
rhqadmin@localhost:7080$ var criteria = new ResourceCriteria()

rhqadmin@localhost:7080$ criteria.getPageSize()
200

rhqadmin@localhost:7080$ criteria.getPageNumber()
0

rhqadmin@localhost:7080$ criteria.setPaging(0,300)

rhqadmin@localhost:7080$ var resources = ResourceManager.findResourcesByCriteria(criteria)
id    name                                          currentAvailability resourceType
------------------------------------------------------------------------------------------------------------------
10032 RHQDS                                         UP                Datasource
10033 ResourceFactoryManagerBean                    UP                EJB3 Session Bean
10034 CoreTestBean                                  UP                EJB3 Session Bean
10035 rhq-postinstaller.war (//localhost/installer) UP                Web Application (WAR)
10036 ResourceMetadataManagerBean                   UP                EJB3 Session Bean
10037 SystemInfoManagerBean                         UP                EJB3 Session Bean
10105 wstools.sh                                    UP                Script
10038 PartitionEventManagerBean                     UP                EJB3 Session Bean
10039 CallTimeDataManagerBean                       UP                EJB3 Session Bean
10040 AlertDefinitionManagerBean                    UP                EJB3 Session Bean
10041 DiscoveryTestBean                             UP                EJB3 Session Bean
10123 wsconsume.sh                                  UP                Script
10042 ROOT.war (//localhost/)                       UP                Web Application (WAR)
10044 AlertManagerBean                              UP                EJB3 Session Bean
10045 AgentManagerBean                              UP                EJB3 Session Bean
... 8< ...
300 rows