7. Operations

7.1. Starting and Stopping a Resource

A resource can simple be started by using an operation.
This example looks for a specific resource by name, and then runs the start() function.

Example 13. Simple Start

//find the resource
criteria = new ResourceCriteria();
criteria.addFilterName('My JBossAS')

var servers = ResourceManager.findResourcesByCriteria(criteria);
var myJBossAS = ProxyFactory.getResource(servers.get(0).id)
myJBossAS.start()
Each resource type has its own defined operations, and even simple tasks like start and stop may have different methods depending on the resource. Try using a proxy resource and then the operations method to list the available operations. 
rhqadmin@localhost:7080$ server.operations
Array of org.rhq.bindings.client.ResourceClientProxy$Operation
name     description
-----------------------------------------------------------------------
restart  Shutdown and then start this application server.
start    Start this application server. 
shutdown Shutdown this application server via script or JMX.
3 rows
A more complex start or stop script can be used to iterate over an array of resources of the same type.

Example 14. Starting an Array 1

//find the resources
//use a plugin filter to make sure they are all of the same type
criteria = new ResourceCriteria();
criteria.addFilterPluginName('JBossAS5')

var resources = ResourceManager.findResourcesByCriteria(criteria).toArray();
var resType = ResourceTypeManager.getResourceTypeByNameAndPlugin('JBossAS Server', 'JBossAS5');

// go through the array
var idx=0;
var jbossServers = new Array();

for( i in resources ) {
     if( resources[i].resourceType.id == resType.id ) {
          jbossServers[idx] = resources[i];
          idx = idx + 1;     
     }
}

// restart the resources
for( a in resources ) {
     var jboss = ProxyFactory.getResource(jbossServers[a].id);
     jboss.restart()
}

Example 15. Starting an Array 2

//find the resources
//use a plugin filter to make sure they are all of the same type
criteria = new ResourceCriteria();
criteria.addFilterPluginName('JBossAS5')
criteria.addFilterResourceTypeName('JBossAS Server');

var jbossServers = ResourceManager.findResourcesByCriteria(criteria).toArray();

// restart the resources
for( a in jbossServers ) {
     var jboss = ProxyFactory.getResource(jbossServers[a].id);
     jboss.restart()
}

7.2. Scheduling Operations

The simplest way to run an operation is to create a proxy for the resource, and then run the operation on that proxy, in the form proxyName.operationName().

Example 16. Immediate Operation

rhqadmin@localhost:7080$ var agent = ProxyFactory.getResource(10008)
rhqadmin@localhost:7080$ agent.executeAvailabilityScan(true)
Invoking operation executeAvailabilityScan
Configuration [13903] - null
  isChangesOnly = true
  agentName = server.example.com
  resourceAvailabilities [0] {
  }
Operations can be run on a schedule. A schedule requires several configuration pieces:
  • The resource ID
  • The operation name
  • A delay period, meaning when in the future to start the operation (optional)
  • A repeat interval and count (optional)
  • A timeout period (optional)
  • Configuration parameters, if required by the operation
  • A description of the scheduled operation (optional)
This example runs an availability scan on a specific agent.

Example 17. Scheduled Operation Example

// find the agent
var rc = ResourceCriteria();
rc.addFilterResourceTypeName("RHQ Agent");
rc.addFilterVersion("3.1.2");

var agent = ResourceManager.findResourcesByCriteria(rc);

//set the config properties for the operation
var config = new Configuration();
config.put(new PropertySimple("changesOnly", "true") );

//schedule the operation
OperationManager.scheduleResourceOperation(
          agent.get(0).id,
          "executeAvailabilityScan",
	  0, // 0 means that the delay was skipped
          1,
	  0, // this skips the repeat count
          10000000,
	  config, 
          "test from cli"
	  );
This immediately prints the information for the scheduled operation. 
rhqadmin@localhost:7080$ exec -f /export/myscripts/test.js
ResourceOperationSchedule:
        resource: Resource[id=10008, uuid=e11390ec-34c4-49df-a4b6-c37c516f545c, type={RHQAgent}RHQ Agent, key=server.example.com RHQ Agent, name=RHQ Agent, parent=server.example.com, version=3.1.2]

7.3. Retrieving the Results of an Operation

Some operations really only report a success or failure, and that is all the information that is required. Other operations, however, may retrieve information from a resource or make a more complex change on the resource. In that case, that information needs to be returned so it can be used in further tasks.
The fetchResults(true) method can be used to return the results of the operation as part of the search for the operation history. 
// search for the operation
var c = new ResourceOperationHistoryCriteria()
c.addFilterId(schedule.id)
c.fetchResults(true)
var r = OperationManager.findResourceOperationHistoriesByCriteria(c)

// get the operation data
var h = r.get(0);

// get the results
var c = h.getResults();
c

Example 18. Printing the Results of a Process Scan

In this longer example, the script first runs an operation (a process scan on a platform) and then prints the results.
The first part of the script sets up the requirement for the resource ID and then searchs for that resource. 
if (args.length != 1) {
    throw "we need a resource id as an argument";
}

var platform = ResourceManager.getResource(args[0]);
The next part schedules the process scan operation. As covered in Section 7.2, “Scheduling Operations”, this sets the resource ID, operation name, and operation settings. 
var ros = OperationManager.scheduleResourceOperation(
   platform.id,
   "viewProcessList",
   0,
   1,
   0,
   15,
   null,
   "test operation"
);
The last part retrieves the operation history with two additional search settings:
  • fetchResults(true), which is required to include the operation result data and not just the status
  • a sort method, in this case addSortStartTime
There are also a couple of sleeps in the script to ensure that the operation has time to complete before the script attempts to retrieve the results. 
var opcrit = ResourceOperationHistoryCriteria();
opcrit.addFilterResourceIds(platform.id);
opcrit.fetchResults(true); // request the additional optional data in the result
opcrit.addSortStartTime(PageOrdering.DESC); // sort by start time
java.lang.Thread.sleep(1000); // wait a second to make sure operation is in the history

// wait for up to 15 seconds for last operation to complete, then print result
now=new Date().getTime();
while (new Date().getTime() - now < 15000 ) {
   operations = OperationManager.findResourceOperationHistoriesByCriteria(opcrit);
   if (operations.get(0).getResults() == null) {
      println("operation still pending result");
      java.lang.Thread.sleep(1000);
   } else {
      pretty.print(operations.get(0).getResults());
      break;
   }
}
if (operations.get(0).getErrorMessage() != null) {
      println("Error getting process list: ");
      pretty.print(operations.get(0).getErrorMessage());
}
This script prints the results of the operation as long as the operation has completed successfully: 
   } else {
      pretty.print(operations.get(0).getResults());
      break;
   }

7.4. Checking a Resource's Operations History

The operation history for a resource exists as an object, so it can be searched for, by criteria, same as other objects.

Example 19. Viewing the Operation History

// find the resource
var rc = ResourceCriteria();
rc.addFilterPluginName("RHQAgent");
rc.addFilterName("RHQ Agent");
rc.addFilterResourceTypeName("RHQ Agent");
rc.addFilterDescription("Agent");

var agent = ResourceManager.findResourcesByCriteria(rc);

// print the operation history for the resource
var opcrit = ResourceOperationHistoryCriteria()
opcrit.addFilterResourceIds(agent.get(0).id)
OperationManager.findResourceOperationHistoriesByCriteria(opcrit);
The (successful) operation results are in Configuration objects in the results table. 
rhqadmin@localhost:7080$ exec -f /export/myscripts/test.js
resource                                             results
-----------------------------------------------------------------------------------------------------------------
Resource[id=10008, uuid=e11390ec-34c4-49df-a4b6-c37c516f545c, type={RHQAgent}RHQ Agent, key=server.example.com RHQ Age Configuration[id=13903]
Resource[id=10008, uuid=e11390ec-34c4-49df-a4b6-c37c516f545c, type={RHQAgent}RHQ Agent, key=server.example.com RHQ Age Configuration[id=13913]
2 rows