$ rhq-cli
The RHQ CLI is a standalone Java application. It uses the Java Scripting API, and therefore requires Java 6 or later. The CLI offers a way to interact with RHQ programmatically, allowing developers and administrators to further integrate RHQ into their environments. Java 6 ships with the Rhino JavaScript engine, and as such, JavaScript is the supported scripting language in the CLI. A large subset of RHQ functionality is exposed in the CLI including,
The CLI is a shell/interpreter that allows you to execute statements in an interactive fashion. This can be useful for prototyping. Scripts, stored in files, can be executed as well, providing the capability to develop more fully automated solutions.
The RHQ CLI can be run from within a console window.
The rhq-cli-env.bat file, located in the <cli-install-dir>\bin directory, contains a detailed listing of the environment variables that the CLI requires to run. For most variables, sensible defaults are used and therefore do not need editing. It is important, however, to set the correct path to your Java installation.
You should not edit rhq-cli.bat - if you need to customize the launch parameters of the RHQ CLI, edit the environment variable values in rhq-cli-env.bat.
To run the RHQ CLI, execute the rhq-cli.bat located in <cli-install-dir>\bin directory of the installation. You can pass in any of the RHQ CLI Command Line Options.
The rhq-cli.bat script looks for specific environment variables during its execution. These variables can be modified to suit your system requirements. For example, you can point the RHQ CLI at a new JVM or you can define VM options. Note that you should not edit the rhq-cli.bat file. If you need to customize the launch parameters of the RHQ CLI, either set the environment variables at the command prompt, or edit the values in rhq-cli-env.bat. The comments at the top of the rhq-cli-env.bat file contain a detailed list of these environment variables. You do not have to set any specific variables to get the RHQ CLI to run; sensible defaults are used.
The RHQ CLI can be run from within a shell of a terminal window.
The rhq-cli-env.sh file, located in the <cli-install-dir>/bin/ directory, contains a detailed list of the environment variables that the RHQ CLI requires to run. For most variables, sensible defaults are used and therefore do not need editing. It is important however, to set the correct path to your Java installation. Before starting the RHQ CLI, it is best to ensure that either the RHQ_CLI_JAVA_HOME or the RHQ_CLI_JAVA_EXE_FILE_PATH variable is set appropriately.
You should not edit rhq-cli.sh - if you need to customize the launch parameters of the RHQ CLI, edit the environment variable values in rhq-cli-env.sh.
To run the RHQ CLI, run the rhq-cli.sh script located in the <cli-install-dir>/bin directory of the installation. You can pass in any of the RHQ CLI Command Line Options.
Both rhq-cli.bat and rhq-cli.sh accept the following command line options.
|
Option |
Description |
|
-h, --help |
Displays the help text of the command line options of the CLI |
|
-u, --user |
The username used to log into the RHQ server |
|
-p, --password |
The password used to log into the RHQ server |
|
-P |
Display a password prompt where input is not echoed backed to the screen |
|
-s, --host |
The RHQ server against which the CLI will execute commands. Defaults to localhost. |
|
-t, --port |
The port on which the RHQ server is accepting HTTP requests. Defaults to 7080. |
|
-c, --command |
A command to be executed. The command must be surrounded in double quotes. The CLI will exit after the command has finished executing. |
|
-f, --file |
The pathname of a script to execute. See Executing Scripts for additional information on running scripts. |
|
-v, --version |
Causes the CLI and RHQ server version information to be displayed once connected to the the CLI. |
|
--transport |
Determines whether or not SSL will be used for the communication layer protocol between the CLI and the RHQ server. If not specified the value is determined from the {{port} option. If you use a port that ends in 443, SSL will be used. You only need to explicitly specify the transport when your RHQ server is listening over SSL on a port that does not end with 443. |
|
--args-style |
Indicates the style or format of arguments passed to the script. See Executing Scripts for additional information. |
Below are some examples of various ways that the CLI can be invoked.
$ rhq-cli
This is the simplest way to start the CLI, without any options. You will be connected to the CLI but not logged into the RHQ server. While not logged in you can execute scripts and script commands; however, most of the RHQ functionality is not available until you are logged in.
$ rhq-cli -u rhqadmin -p rhqadmin
This will connect to the CLI and attempt to log you in with the specified credentials on the RHQ server running on localhost.
$ rhq-cli -u rhqadmin -p rhqadmin -s 192.168.1.100 -t 70443
This will connect to the CLI, attempt to log you into the RHQ server on 192.168.1.100 that is listening on port 70443. Because the port number ends with 443, the CLI will attempt to communicate with the RHQ server over SSL using the sslservlet transport strategy.
$ rhq-cli -u rhqadmin -P
This will connect to the CLI and prompt the user for a password.
$ rhq-cli -u rhqadmin -p rhqadmin -c "pretty.print(ResourceTypeManager.findResourceTypesByCriteria(new ResourceTypeCriteria()))" > resource_types.txt
This connects to the CLI, logs you into the RHQ server running on localhost, executes the command in quotes, redirecting the output to the file resource_types.txt. There is a quite a bit going on with that single command. Let's start with ResourceTypeManager.findResourceTypesByCriteria(new ResourceTypeCriteria()). This invokes the findResourceTypesByCriteria operation on ResourceTypeManager. A new ResourceTypeCriteria object is passed as the argument. Because nothing has been specified on the criteria object, all resource types will be returned. Now let's looks at the pretty.print(...) portion. pretty is an implicit object made available to commands and scripts by the CLI. It is very useful for outputting objects in a readable, tabular format, designed with enhanced capabilities for domain objects. In review, this single command gives us a nicely formatted,text-based report of the resource types in our inventory.
$ rhq-cli -f my_script.js
This connects to the CLI and executes the script file, my_script.js. The CLI terminates immediately after the script has finished executing.
As previously stated, the CLI is built using the Java Scripting API that was introduced in Java 6. The majority of commands and scripts that you write will be executed by the underlying script engine. Built-in commands however, are native Java code and not executed by the underlying script engine. This is similar to other interpreters like Python where some modules are implemented in C and built right into the interpreter. This distinction is important because built-in commands cannot be processed by the script engine. Objects though, providing hooks into the built-in commands, are exposed to the scripting environment.
The following is a list of built-in commands along with the options and arguments that they accept. Each of the built-in commands takes a help option. Using the short form, <command> -h, will display the command syntax and a short description. Using its long form, <command> --help, will display the command syntax and a more detailed description.
Syntax
login <username> <password> [host port [transport]]
Description
Log into a RHQ server with the specified username and password. The host name (or IP address) and port can be optionally specified. The host name defaults to localhost and the port defaults to 7080. The transport argument is optional. It determines whether or not SSL will be used for the communication layer protocol between the CLI and the RHQ server. If not specified the value is determined from the port argument.. If you use a port that ends in 443, SSL will be used. You only need to explicitly specify the transport when your RHQ server is listening over SSL on a port that does not end with 443.
Syntax
logout
Description
Log out from the RHQ server but does not exit from the CLI interpreter.
Syntax
quit
Description
Exits the CLI interpreter.
Syntax
version
Description
Displays detailed version information about the CLI.
Syntax
exec <statement> | [--args-style=<indexed|named>] -f <file> [args]
Description
Executes a statement or a script with the specified file name. A statement wraps onto multiple lines using backslashes. See below for an example.
Options
|
Option |
Description |
|
-f, --file |
The file name of the script to execute. A valid file name must be specified. |
|
--args-style |
Indicates the style or format of arguments passed to the script. Must have a value of either indexed or named. |
Examples
localhost:7080> exec var x = 1
localhost:7080(rhqadmin)> for (i = 1; i < 3; ++i) { \
localhost:7080(rhqadmin)> println(i); \
localhost:7080(rhqadmin)> }
1
2
localhost:7080(rhqadmin)>
localhost:7080(rhqadmin)> exec -f myscript.js
localhost:7080(rhqadmin)> exec -f myscript.js 1 2 3
localhost:7080(rhqadmin)> exec --style=named -f myscript.js x=1 y=2 y=3
Syntax
record [-b | -e] [-a] -f <file>
Description
Records user input commands to a file.
Options
|
Option |
Description |
|
-b, --start |
Specify this option to start recording. |
|
-e, --end |
Specify this option to stop recording. |
|
-a, --append |
Appends output to the end of a file. If not specified, output will be written starting at the beginning of the file. |
|
-f, --file |
The file where output will be written. |
The CLI provides two modes of operation - interactive and non-interactive. In interactive mode, you can execute an individual statement, whereas in non-interactive mode, you execute an entire batch of commands in the form of a script. Non-interactive mode provides the capability to automate tasks such as collecting metrics on managed resources or executing a scheduled operation. Interactive mode provides a rich environment for prototyping, testing, learning and discovering features of the CLI, and more. In the following sections, we will take a close look at some of the features and functionality in the CLI. Unless stated otherwise, it can be assumed that the following features and functionality discussed are available in both modes of operation.
The CLI makes available the entire Remote API as well as enhanced Proxy objects for writing scripts.
There are a number of variables that are bound to the script context. A number of those variables though, are available only after you have logged in. Implicit variables are listed in the table below. The last column in the table indicates whether or not accessing the variable requires login.
|
Variable |
Type |
Description |
Access reqiures login |
|
subject |
Represents the current, logged in user. For security purposes, all remote service invocations require the subject to be passed; however, the CLI will implicitly pass the subject for you. |
YES |
|
|
pretty |
org.rhq.enterprise.client.TabularWriter |
Provides for tabular-formatted output and handles converting objects, particularly domain objects in the packages under org.rhq.core.domain, into a format suitable for display in the console. |
NO |
|
unlimitedPC |
TODO |
NO |
|
|
pageControl |
Used to specify paging and sorting on data retrieval operations |
NO |
|
|
exporter |
org.rhq.enterprise.client.Exporter |
Used to export output to a file. Supported formats are plain text in tabular format and CSV. |
NO |
|
ProxyFactory |
org.rhq.enterprise.client.utility.ResourceClientProxy.Factory |
TODO |
|
|
rhq |
org.rhq.enterprise.client.Controller |
Exposes methods (of the same name) for the built-in commands - login, logout, quit. |
NO |
|
scriptUtil |
org.rhq.enterprise.client.utility.ScriptUtil |
Provides various methods that may be useful when writing scripts |
NO |
|
AlertManager |
Provides an interface into the alerts subsystem |
YES |
|
|
AlertDefinitionManager |
org.rhq.enterprise.server.alert.AlertDefinitionManagerRemote |
Provides an interface into the alerts definition subsystem |
YES |
|
AvailabilityManager |
org.rhq.enterprise.server.measurement.AvailabilityManagerRemote |
Provides an interface into the measurement subsytem that can be used to determine resources' availability |
YES |
|
CallTimeDataManager |
org.rhq.enterprise.server.measurement.CallTimeDataManagerRemote |
Provides an interface into the measurement subsystem for retrieving call-time metric data |
YES |
|
ChannelManager |
Provides an interface into the content subsystem for working with channels |
YES |
|
|
ConfigurationManager |
org.rhq.enterprise.server.configuration.ConfigurationManagerRemote |
Provides an interface into the configuration subsystem |
YES |
|
DataAccessManager |
Provides an interface for executing user-defined queries |
YES |
|
|
EventManager |
Provides an interface into the events subsystem |
YES |
|
|
MeasurementBaselineManager |
org.rhq.enterprise.server.measurement.MeasurementBaselineManagerRemote |
Provides an interface into the measurement subsystem for working with measurement baselines |
YES |
|
MeasurementDataManager |
org.rhq.enterprise.server.measurement.MeasurementDataManagerRemote |
Provides an interface into the measurement subsystem for working with measurement data |
YES |
|
MeasurementDefinitionManager |
org.rhq.enterprise.server.measurement.MeasurementDefinitionManagerRemote |
Provides an interface into the measurement subsystem for working with measurement definitions |
YES |
|
MeasurementScheduleManager |
org.rhq.enterprise.server.measurement.MeasurementScheduleManagerRemote |
Provides an interface into the measurement subsystem for working with measurement schedules |
YES |
|
OperationManager |
Provides an interface into the operation subsystem |
YES |
|
|
ResourceManager |
Provides an interface into the resource subsystem |
YES |
|
|
ResourceGroupManager |
org.rhq.enterprise.server.resource.group.ResourceGroupManagerRemote |
Provides an interface into the resource group subsystem |
YES |
|
ResourceTypeManager |
org.rhq.enterprise.server.resource.ResourceTypeManagerRemote |
Provides an interface into the resource subsystem for working with resource types |
YES |
|
RoleManager |
Provides an interface into the security subsystem for working with security rules and roles |
YES |
|
|
SubjectManager |
Provides an interface into the security subsystem for working with users |
YES |
|
|
SupportManager |
Provides an interface into the reporting subsystem for getting reports of managed resources |
YES |
In the Java programming language, you do not have to import classes in the java.lang package. They are automatically made available. Classes in other packages however, have to be explicitly imported. In the CLI, there are a number of classes from various packages that you are likely to use on a routine basis. For example, if I want to query resources, then I am likely use the class org.rhq.core.domain.critiera.ResourceCriteria. The CLI automatically imports packages under and including org.rhq.core.domain. This means that while we can write,
var criteria = new org.rhq.core.domain.criteria.ResourceCriteria(); var resource = new org.rhq.core.domain.resource.Resource();
we can more succinctly write,
var criteria = new ResourceCritiera(); var resource = new Resource();
A feature that is common to Unix and Linux shells like Bash is that of auto completion of commands. I can start typing the first few letters of a command, press the tab key, and the shell will finish it for me. The CLI provides the Auto Completor which is similar in nature.
The Auto Complete is only available in interactive mode.
The Auto Completor provides tab-completion for any object bound in the script context. In fact, if you want to see a listing of objects bound in the script context, simply press that tab key. I can also use the Auto Completor to see a list of available methods for a particular object. At the CLI prompt, type ResourceManager. followed by the tab key and you should see something like,
rhqadmin@localhost:7080$ ResourceManager. findResourceComposites findResourceLineage findResourcesByCriteria getResource resource toString uninventoryResources
Then enter ResourceManager.f followed by the tab key. You should see something like,
rhqadmin@localhost:7080$ ResourceManager.findResource findResourceComposites findResourceLineage findResourcesByCriteria rhqadmin@localhost:7080$ ResourceManager.findResource
In the snippet above, the command prompt is displaying findResource because the Auto Complete was able to complete the line to that point. Then it displays a list of available methods. The Auto Completor can be extremely useful for discovering objects and their methods. It will also save you a lot of typing.
A feature common to nearly (if not) all programming languages is the ability to pass arguments to the program to be executed. In Java, the entry point into a program is a class's main method, and it take a String array as an argument. That array holds any arguments passed to the program. In a similar fashion, arguments can be passed to CLI scripts. Arguments passed to a script can be accessed in the implict args array.
if (args.length < 2) {
throw "Not enough arguments!";
}
for (i in args) {
println('args[' + i '] = ' + args[i]);
}
The args variable is only available when executing a script in non-interactive mode or with exec -f.
In addition to the traditional style of indexed-based arguments, you can also pass named arguments to a script as demonstrated in the following example.
rhqadmin@localhost:7080$ exec -f echo_args.js --args-style=named x=1 y=2
for (i in args) {
println('args[' + i '] = ' + args[i]);
}
println('named args...');
println('x = ' + x);
println('y = ' + y);
And that produces that following output,
args[0] = 1 args[1] = 2 named args... x = 1 y = 2
There are a few key things to point out.
You have to explicitly specify that you are using named arguments via the --args-style option
The values of the named arguments are still accessible via the implicit args array
The named arguments, x and y, are bound into the script context as variables
All of the managers define operations for retrieving data. Most of the managers define criteria-based operations for data retrieval. The Criteria API provides a flexible framework for fine-tuned query operations. The criteria classes reside in the org.rhq.core.domain.criteria package. We will jump right into some examples to illustrate how to work with the criteria APIs. Suppose we want to look up resources in our inventory.
rhqadmin@localhost:7080$ var criteria = new ResourceCriteria() rhqadmin@localhost:7080$ var resources = ResourceManager.findResourcesByCriteria(criteria)
In this example the first thing to note is that we do not have to import the ResourceCriteria class. Recall from the Auto-Imported Packages section that the org.rhq.core.domain.criteria package is automatically imported for us. Next, take note of the method, findResourcesByCriteria. All of the criteria-based query operations are of the form findXXXByCriteria. This basic criteria search is translated into the following JPA-QL query,
SELECT r FROM Resource r WHERE ( r.inventoryStatus = InvetoryStatus.COMMITTED )
As we can see from the JPA-QL query, this will fetch all committed resources in our inventory.
Next we will modify our criteria a bit to sort the resources by plugin.
rhqadmin@localhost:7080$ criteria.addSortPluginName(PageOrdering.ASC) 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
To add sorting, we call criteria.addSortPluginName(). To add sorting to any criteria, you will use methods of the form addSortXXX(PageOrdering order).
Now let's add some filtering to refine our search results. We will filter on the resource type name.
rhqadmin@localhost:7080$ criteria.addFilterResourceTypeName('JBossAS Server')
rhqadmin@localhost:7080$ resources = ResourceManager.findResourcesByCriteria(criteria)
To add filtering to any criteria, you will use methods of the form addFilterXXX(). The resulting JPA-QL quyery is,
SELECT r FROM Resource r WHERE ( r.inventoryStatus = InventoryStatus.COMMITTED AND LOWER( r.resourceType.name ) like 'JBossAS Server' ESCAPE '\\' )
This little bit of code is all that is needed to retrieve all JBoss servers in our inventory. Let's further refine our criteria to find JBoss servers that have been registered by a particular agent.
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 '\\' )
After we have retrieved resources, let's look at how we can drill down into and view child resources. Consider this code,
rhqadmin@localhost:7080$ criteria.addFilterResourceTypeName('JBossAS Server')
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')
This code will indeed print the string no child resources even if the JBoss server has child resources, which is likely. The reason for this is that lazy loading is used throughout the domain layer for one-to-many and many-to-many associations. If you are not familiar with lazy loading, take a look at the article, Some explanations on lazy loading. Since child resources are lazily loaded, we need to specify in the criteria that they should be fetched.
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)
As you see with the call to criteria.fetchChildResources(true), all criteria methods that specify that a particular lazy association should be fetched are of the form, fetchXXX(). The output from the above is,
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
222 AlertTemplateManagerBean EJB3 Session Bean
223 RHQ Server Group Definition / DynaGroups Subsystem RHQ Server Group Definition / DynaGrou
222 DiscoveryTestBean EJB3 Session Bean
222 PerspectiveManagerBean EJB3 Session Bean
222 ResourceAvailabilityManagerBean EJB3 Session Bean
222 AlertDampeningManagerBean EJB3 Session Bean
218 localhost.localdomain Embedded JBossWeb Server 2.0. 2.0.1. Embedded Tomcat Server
222 ResourceGroupManagerBean EJB3 Session Bean
222 FailoverListManagerBean EJB3 Session Bean
222 ResourceFactoryManagerBean EJB3 Session Bean
222 AccessBean EJB3 Session Bean
222 MeasurementTestBean EJB3 Session Bean
223 wstools.sh Script
222 EventManagerBean EJB3 Session Bean
222 ContentSourceManagerBean EJB3 Session Bean
223 RHQ Server Alerts Engine Subsystem RHQ Server Alerts Engine Subsystem
222 AlertConditionManagerBean EJB3 Session Bean
222 ResourceMetadataManagerBean EJB3 Session Bean
222 ResourceManagerBean EJB3 Session Bean
222 GroupDefinitionExpressionBuilderManagerBean EJB3 Session Bean
222 MeasurementViewManagerBean EJB3 Session Bean
218 JmsXA Connection Factory ConnectionFactory
222 ResourceTypeManagerBean EJB3 Session Bean
223 JBoss Cache subsystem 1.0 JBossCacheSubsystem
218 NoTxRHQDS Datasource Datasource
222 DataAccessBean EJB3 Session Bean
222 AlertConditionCacheManagerBean EJB3 Session Bean
222 MeasurementProblemManagerBean EJB3 Session Bean
222 ServerManagerBean EJB3 Session Bean
222 OperationHistorySubsystemManagerBean EJB3 Session Bean
222 ClusterManagerBean EJB3 Session Bean
222 run.sh Script
...
The actual output you see will vary depending on what you have inventoried. These are the child resources of my RHQ server. The JPA-QL query that is generated looks like,
SELECT r FROM Resource r LEFT JOIN FETCH r.childResources WHERE ( r.inventoryStatus = InventoryStatus.COMMITTED AND LOWER( r.resourceType.name ) like 'JBossAS Server' ESCAPE '\\' )
TODO Add a link to more examples (when the example docs are written)
TabularWriter provides for tabular-formatted output. In addition to formatting, it handles converting objects, particularly domain objects in the packages under org.rhq.core.domain, into a format suitable for display in the interactive console. Let's look at an example to illustrate the utility of TabularWriter.
rhqadmin@localhost:7080$ criteria = ResourceCriteria()
rhqadmin@localhost:7080$ criteria.addFilterResourceTypeName('service-alpha')
rhqadmin@localhost:7080$ criteria.addFilterParentResourceName('server-omega-0')
rhqadmin@localhost:7080$ resources = ResourceManager.findResourcesByCriteria(criteria)
id name version resourceType
----------------------------------------------------------------------------------------------------------------------
11373 service-alpha-8 1.0 service-alpha
11374 service-alpha-1 1.0 service-alpha
11375 service-alpha-0 1.0 service-alpha
11376 service-alpha-4 1.0 service-alpha
11377 service-alpha-2 1.0 service-alpha
11378 service-alpha-3 1.0 service-alpha
11379 service-alpha-5 1.0 service-alpha
11380 service-alpha-9 1.0 service-alpha
11381 service-alpha-6 1.0 service-alpha
11382 service-alpha-7 1.0 service-alpha
10 rows
The TabularWriter instance that is bound in the script context under the name pretty is implicitly invoked to display the results of ResourceManager.findResourcesByCriteria. The returned resources are displayed in very readable, tabular format. Now let's look at the output if we do not use TabularWriter.
rhqadmin@localhost:7080$ println(resources) PageList[Resource[id=11373, type=service-alpha, key=service-alpha-8, name=service-alpha-8, version=1.0], Resource[id=11374, type=service-alpha, key=service-alpha-1, name=service-alpha-1, version=1.0], Resource[id=11375, type=service-alpha, key=service-alpha-0, name=service-alpha-0, version=1.0], Resource[id=11376, type=service-alpha, key=service-alpha-4, name=service-alpha-4, version=1.0], Resource[id=11377, type=service-alpha, key=service-alpha-2, name=service-alpha-2, version=1.0], Resource[id=11378, type=service-alpha, key=service-alpha-3, name=service-alpha-3, version=1.0], Resource[id=11379, type=service-alpha, key=service-alpha-5, name=service-alpha-5, version=1.0], Resource[id=11380, type=service-alpha, key=service-alpha-9, name=service-alpha-9, version=1.0], Resource[id=11381, type=service-alpha, key=service-alpha-6, name=service-alpha-6, version=1.0], Resource[id=11382, type=service-alpha, key=service-alpha-7, name=service-alpha-7, version=1.0]]
For display purposes, this output is not very usable. Let's look at one more example in which we display a single entity.
rhqadmin@localhost:7080$ pretty.print(resources.get(0)) Resource: id: 11373 name: service-alpha-8 version: 1.0 resourceType: service-alpha
Notice that the formatting is different when displaying a single object. Lastly, it should be pointed out that only a subset of the properties in the Resource class are displayed. TabularWriter determines the properties to display via the Summary annotation. If a field of an entity has the @Summary annotation, TabularWriter will include it in the output.
exporter is an implicit script variable that can assist with writing output to a file. Under the covers it uses TabularWriter; however, in addition to writing plain text in a tabular format, it also supports CSV-formatting. First, we will look at an example of exporting to a file as plain text.
rhqadmin@localhost:7080$ exporter.setTarget('raw', 'output.txt')
rhqadmin@localhost:7080$ exporter.write(resources)
Note that we do not have to worry about file IO operations like opening or closing the file. Exporter handles the IO operations for us. Now we will export the results to a CSV file.
rhqadmin@localhost:7080$ exporter.setTarget('csv', 'output.csv')
rhqadmin@localhost:7080$ exporter.write(resources)
Resource Proxies are custom objects generated in the CLI context that simplify interacting with the remote and domain APIs. Proxies are obtained through the ProxyFactory by calling getResource() and providing a resource identifier.
var rhelServerOne = ProxyFactory.getResource(10001);
From there the proxy will exhibit the behavior of a custom local interface for that resource. It will expose methods to invoke operations. There will be properties for viewing metrics that connect to the live metric system. There is also support for viewing and editing current configurations and updating and deploying content.
rhqadmin@localhost:7080$ ProxyFactory.getResource(10001)
ResourceClientProxy_$$_javassist_2:
OSName: MacOSX
OSVersion: 10.5.7
architecture: i386
contentTypes: {}
createdDate: Thu Aug 06 16:59:32 EDT 2009
description: Mac OS X Operating System
freeMemory: 120.2MB
freeSwapSpace: 984.7MB
hostname: ghinklembp.local
id: 10001
idle: 40%
measurements: [Used Memory, Wait Load, Total Memory, System Load,
OS Name, Free Memory, Hostname, Architecture, Idle,
Total Swap Space, Used Swap Space, User Load, OS Version,
Free Swap Space]
modifiedDate: Thu Aug 06 16:59:32 EDT 2009
name: ghinklembp
operations: [org.rhq.enterprise.client.proxy.ResourceClientProxy$Operation@234a98fa,
org.rhq.enterprise.client.proxy.ResourceClientProxy$Operation@7681572f]
resourceType: Mac OS X
systemLoad: 0%
totalMemory: 4GB
totalSwapSpace: 4GB
usedMemory: 3.9GB
usedSwapSpace: 3GB
userLoad: 50%
version: MacOSX 10.5.7
waitLoad: 0%
To run an operation on the proxy call the bound method representing that operation.
platform.viewProcessList(); agent.updateAllPlugins(); jbossas.restart();
The resource proxy offers access to both the connection properties and the configuration of the resource itself. Configuration data for a resource such as a datasource can be viewed and edited live.
datasource.getResourceConfiguration()
The proxy also integrates with the resource configuration editing wizard to update configurations via a question and answer session. This interactive wizard will ask for the values of each configuration property and has some special keystrokes to simplify editing. Pressing return will select the default or existing value for a property. Pressing ctrl-d is equivalent to setting the "unset" checkbox in the configuration UI. Pressing ctrl-k will exit out of the wizard at any point. Pressing ctrl-e will display the help description for the current property. At the end of the wizard you can choose to review, save, cancel or edit the configuration again. Once you select save the configuration will be updated live on the remote resource.
datasource.editResourceConfiguration()
For resources that support backing content such as JBoss Application Server EAR and WAR resources the content features will be exposed to the proxy allowing you to retrieve or update the content behind that deployed resource.
The following will retrieve the EAR file from the agent and download it to the cli saving it as a file with the same name as the deployed file. You can also pass in a relative or fully qualified path to save the content to.
myCustomEAR.retrieveBackingContent(null);
You can send a new version of the content via the following command by passing in the name of the file to send. This will deploy a new version of your custom application content and automatically increment the internal version tracking.
myCustomEAR.updateBackingContent('CustomEAR_v2.ear');