-
Language:
English
-
Language:
English
Red Hat Training
A Red Hat training course is available for Red Hat JBoss Operations Network
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
find
ObjectByCriteria
, 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