... {panel:border=1}
|
{toc}
{panel}
|
|
h1. Introduction
|
The Jopr RHQ CLI is a standalone Java application. It uses the [Java Scripting API|http://java.sun.com/javase/6/docs/api/javax/script/package-summary.html], and therefore requires Java 6 or later. The CLI offers a way to interact with Jopr RHQ programmatically, allowing developers and administrators to further integrate Jopr RHQ into their environments. Java 6 ships with the [Rhino|http://www.mozilla.org/rhino/] JavaScript engine, and as such, JavaScript is the supported scripting language in the CLI. A large subset of Jopr RHQ functionality is exposed in the CLI including,
|
|
h1. Running the Jopr RHQ CLI
|
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.
|
...
|
h2. Running on Windows
|
The Jopr RHQ CLI can be run from within a console window.
|
h3. Setting Environment Variables
|
...
|
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.
|
{note}You should not edit rhq-cli.bat - if you need to customize the launch parameters of the Jopr RHQ CLI, edit the environment variable values in rhq-cli-env.bat.{note}
|
|
h3. Running in a Windows Console
|
To run the Jopr RHQ CLI, execute the rhq-cli.bat located in _<cli-install-dir>_\bin directory of the installation. You can pass in any of the [Jopr [RHQ CLI Command Line Options|#Jopr Options|#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 Jopr 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 Jopr 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 Jopr RHQ CLI to run; sensible defaults are used.
|
h2. Running on Linux/Unix
|
The Jopr RHQ CLI can be run from within a shell of a terminal window.
|
h3. Setting Environment Variables
|
The rhq-cli-env.sh file, located in the _<cli-install-dir>_/bin/ directory, contains a detailed list of the environment variables that the Jopr 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 Jopr 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.
|
|
{note}You should not edit rhq-cli.sh - if you need to customize the launch parameters of the Jopr RHQ CLI, edit the environment variable values in rhq-cli-env.sh.{note}
|
|
h3. Running in a Shell
|
To run the Jopr 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 [Jopr [RHQ CLI Command Line Options|#Jopr Options|#RHQ CLI Command Line Options].
|
|
h1. Jopr 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 Jopr RHQ server |
|
| *\-p, \--password* | The password used to log into the Jopr RHQ server |
|
| *\-P* | Display a password prompt where input is not echoed backed to the screen |
|
| *\-s, \--host* | The Jopr RHQ server against which the CLI will execute commands. Defaults to localhost. |
|
| *\-t, \--port* | The port on which the Jopr 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|#Executing Scripts] below for additional information on running scripts. |
|
| *\-v, \--version* | Causes the CLI and Jopr 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 Jopr 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 Jopr 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|#Executing Scripts] below for additional information. |
|
...
h2. Examples
Below are some examples of various ways that the CLI can be invoked.
{code}
|
$ rhq-cli
{code}
|
This is the simplest way to start the CLI, without any options. You will be connected to the CLI but not logged into the Jopr RHQ server. While not logged in you can execute scripts and script commands; however, most of the Jopr RHQ functionality is not available until you are logged in.
|
\\
|
... {code}
|
$ rhq-cli -u rhqadmin -p rhqadmin
{code}
|
This will connect to the CLI and attempt to log you in with the specified credentials on the Jopr RHQ server running on localhost.
|
\\
|
... {code}
|
$ rhq-cli -u rhqadmin -p rhqadmin -s 192.168.1.100 -t 70443
{code}
|
This will connect to the CLI, attempt to log you into the Jopr 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 Jopr RHQ server over SSL using the sslservlet transport strategy.
|
\\
|
... {code}
$ rhq-cli -u rhqadmin -P
{code}
This will connect to the CLI and prompt the user for a password.
\\
{code}
|
$ rhq-cli -u rhqadmin -u rhqadmin -c "pretty.print(ResourceTypeManager.findResourceTypesByCriteria(new ResourceTypeCriteria()))" > resource_types.txt
{code}
|
This connects to the CLI, logs you into the Jopr 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.
|
\\
|
... {code} $ rhq-cli -f my_script.js {code} This connects to the CLI and executes the script file, {{my_script.js}}. The CLI terminates immediately after the script has finished executing. h1. Built-in Commands 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. h2. login *Syntax* {{login <username> <password> \[host port \[transport\]\]}} |
*Description*
|
Log into a Jopr 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 Jopr 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 Jopr RHQ server is listening over SSL on a port that does not end with 443.
|
h2. logout
|
...
*Syntax*
{{logout}}
|
*Description*
|
Log out from the Jopr RHQ server but does not exit from the CLI interpreter.
|
h2. quit
|
...
*Syntax*
{{quit}}
*Description*
Exits the CLI interpreter.
h2. version
*Syntax*
{{version}}
*Description*
Displays detailed version information about the CLI.
h2. exec
*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}}. See the section, [Executing scripts|#Executing Scripts] for additional details.\] |
*Examples*
{code:title=executing a single statement}localhost:7080> exec var x = 1
{code}
\\
{code:title=executing a multi-line statement}localhost:7080(rhqadmin)> for (i = 1; i < 3; ++i) { \
localhost:7080(rhqadmin)> println(i); \
localhost:7080(rhqadmin)> }
1
2
localhost:7080(rhqadmin)>
{code}
\\
{code:title=executing a named script without arguments}localhost:7080(rhqadmin)> exec -f myscript.js
{code}
\\
{code:title=executing a named script with arguments}localhost:7080(rhqadmin)> exec -f myscript.js 1 2 3
{code}
\\
|
{code:title=executing a named script with named arguments}localhost:7080(rhqadmin)> exec --style=named -f myscript.js x=1 y=2 y=3
{code}
|
|
h2. record
|
... *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. |
h1. Working with the CLI
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.
|
h2. The API
|
This is a first pass at the services and related classes within RHQ to be exposed.
|
The CLI makes available the entire [Remote API|API Documentation] as well as enhanced [#Proxy] objects for writing scripts.
|
|
[Domain Classes|http://jopr.org/javadoc/domain/index.html]
[Plugin API Classes|http://jopr.org/javadoc/plugin-api/index.html]
[Remote API Classes|http://jopr.org/javadoc/remote-api/index.html]
|
h2. Implicit Variables
|
... 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 | [org.rhq.core.domain.auth.Subject|http://jopr.org/javadoc/domain/org/rhq/core/domain/auth/Subject.html] | 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 | [org.rhq.core.domain.util.PageControl|http://jopr.org/javadoc/domain/org/rhq/core/domain/util/PageControl.html] | *TODO* | NO |
| pageControl | [org.rhq.core.domain.util.PageControl|http://jopr.org/javadoc/domain/org/rhq/core/domain/util/PageControl.html] | 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 | [org.rhq.enterprise.server.alert.AlertManagerRemote|http://jopr.org/javadoc/remote-api/org/rhq/enterprise/server/alert/AlertManagerRemote.html] | Provides an interface into the alerts subsystem | YES |
| AlertDefinitionManager | [org.rhq.enterprise.server.alert.AlertDefinitionManagerRemote|http://jopr.org/javadoc/remote-api/org/rhq/enterprise/server/alert/AlertDefinitionManagerRemote.html] | Provides an interface into the alerts definition subsystem | YES |
| AvailabilityManager | [org.rhq.enterprise.server.measurement.AvailabilityManagerRemote|http://jopr.org/javadoc/remote-api/org/rhq/enterprise/server/measurement/AvailabilityManagerRemote.html] | Provides an interface into the measurement subsytem that can be used to determine resources' availability | YES |
| CallTimeDataManager | [org.rhq.enterprise.server.measurement.CallTimeDataManagerRemote|http://jopr.org/javadoc/remote-api/org/rhq/enterprise/server/measurement/CallTimeDataManagerRemote.html] | Provides an interface into the measurement subsystem for retrieving call-time metric data | YES |
| ChannelManager | [org.rhq.enterprise.server.content.ChannelManagerRemote|http://jopr.org/javadoc/remote-api/org/rhq/enterprise/server/content/ChannelManagerRemote.html] | Provides an interface into the content subsystem for working with channels | YES |
| ConfigurationManager | [org.rhq.enterprise.server.configuration.ConfigurationManagerRemote|http://jopr.org/javadoc/remote-api/org/rhq/enterprise/server/configuration/ConfigurationManagerRemote.html] | Provides an interface into the configuration subsystem | YES |
| DataAccessManager | [org.rhq.enterprise.server.report.DataAccessRemote|http://jopr.org/javadoc/remote-api/org/rhq/enterprise/server/report/DataAccessManagerRemote.html] | Provides an interface for executing user-defined queries | YES |
| EventManager | [org.rhq.enterprise.server.event.EventManagerRemote|http://jopr.org/javadoc/remote-api/org/rhq/enterprise/server/event/EventManagerRemote.html] | Provides an interface into the events subsystem | YES |
| MeasurementBaselineManager | [org.rhq.enterprise.server.measurement.MeasurementBaselineManagerRemote|http://jopr.org/javadoc/remote-api/org/rhq/enterprise/server/measurement/MeasurementBaselineManagerRemote.html] | Provides an interface into the measurement subsystem for working with measurement baselines | YES |
| MeasurementDataManager | [org.rhq.enterprise.server.measurement.MeasurementDataManagerRemote|http://jopr.org/javadoc/remote-api/org/rhq/enterprise/server/measurement/MeasurementDataManagerRemote.html] | Provides an interface into the measurement subsystem for working with measurement data | YES |
| MeasurementDefinitionManager | [org.rhq.enterprise.server.measurement.MeasurementDefinitionManagerRemote|http://jopr.org/javadoc/remote-api/org/rhq/enterprise/server/measurement/MeasurementDefinitionManagerRemote.html] | Provides an interface into the measurement subsystem for working with measurement definitions | YES |
| MeasurementScheduleManager | [org.rhq.enterprise.server.measurement.MeasurementScheduleManagerRemote|http://jopr.org/javadoc/remote-api/org/rhq/enterprise/server/measurement/MeasurementScheduleManagerRemote.html] | Provides an interface into the measurement subsystem for working with measurement schedules | YES |
| OperationManager | [org.rhq.enterprise.server.operation.OperationManagerRemote|http://jopr.org/javadoc/remote-api/org/rhq/enterprise/server/operation/OperationManagerRemote.html] | Provides an interface into the operation subsystem | YES |
| ResourceManager | [org.rhq.enterprise.server.resource.ResourceManagerRemote|http://jopr.org/javadoc/remote-api/org/rhq/enterprise/server/resource/ResourceManagerRemote.html] | Provides an interface into the resource subsystem | YES |
| ResourceGroupManager | [org.rhq.enterprise.server.resource.group.ResourceGroupManagerRemote|http://jopr.org/javadoc/remote-api/org/rhq/enterprise/server/resource/group/ResourceGroupManagerRemote.html] | Provides an interface into the resource group subsystem | YES |
| ResourceTypeManager | [org.rhq.enterprise.server.resource.ResourceTypeManagerRemote|http://jopr.org/javadoc/remote-api/org/rhq/enterprise/server/resource/ResourceTypeManagerRemote.html] | Provides an interface into the resource subsystem for working with resource types | YES |
| RoleManager | [org.rhq.enterprise.server.authz.RoleManagerRemote|http://jopr.org/javadoc/remote-api/org/rhq/enterprise/server/authz/RoleManagerRemote.html] | Provides an interface into the security subsystem for working with security rules and roles | YES |
| SubjectManager | [org.rhq.enterprise.server.auth.SubjectManagerRemote|http://jopr.org/javadoc/remote-api/org/rhq/enterprise/server/auth/SubjectManagerRemote.html] | Provides an interface into the security subsystem for working with users | YES |
| SupportManager | [org.rhq.enterprise.server.support.SupportManagerRemote|http://jopr.org/javadoc/remote-api/org/rhq/enterprise/server/support/SupportManagerRemote.html] | Provides an interface into the reporting subsystem for getting reports of managed resources | YES |
h2. Auto-Imported Packages
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,
{code}
var criteria = new org.rhq.core.domain.criteria.ResourceCriteria();
var resource = new org.rhq.core.domain.resource.Resource();
{code}
we can more succinctly write,
{code}
var criteria = new ResourceCritiera();
|
var resource = new Resource();
{code}
|
|
h2. Auto Completor
|
... 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.
{info}The Auto Complete is only available in interactive mode.{info}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,
{noformat}rhqadmin@localhost:7080$ ResourceManager.
findResourceComposites findResourceLineage findResourcesByCriteria getResource
resource toString uninventoryResources
{noformat}Then enter {{ResourceManager.f}} followed by the tab key. You should see something like,
{noformat}rhqadmin@localhost:7080$ ResourceManager.findResource
findResourceComposites findResourceLineage findResourcesByCriteria
rhqadmin@localhost:7080$ ResourceManager.findResource
{noformat}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.
h2. Script Arguments
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.
{code:title=Handling Script Arguments}if (args.length > 2) {
throw "Not enough arguments!";
}
for (i in args) {
println('args[' + i '] = ' + args[i]);
}
{code}
{info}The args variable is only available when executing a script in non-interactive mode or with exec \-f.
{info}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.
{code}
rhqadmin@localhost:7080$ exec -f echo_args.js --args-style=named x=1, y=2
{code}
{code:title=echo_args.js}for (i in args) {
println('args[' + i '] = ' + args[i]);
}
println('named args...');
println('x = ' + x);
println('y = ' + y);
{code}
And that produces that following output,
{noformat}args[0] = 1
args[1] = 2
named args...
x = 1
y = 2{noformat}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
h2. Criteria Searching
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.
h3. Basic Criteria
{code}
rhqadmin@localhost:7080$ var criteria = new ResourceCriteria()
rhqadmin@localhost:7080$ var resources = ResourceManager.findResourcesByCriteria(criteria)
{code}
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|#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 find{_}XXX{_}ByCriteria. This basic criteria search is translated into the following JPA-QL query,
\\
{code}
SELECT r
FROM Resource r
WHERE ( r.inventoryStatus = InvetoryStatus.COMMITTED )
{code}
\\
As we can see from the JPA-QL query, this will fetch all committed resources in our inventory.
h3. Sorting
Next we will modify our criteria a bit to sort the resources by plugin.
\\
{code}
rhqadmin@localhost:7080$ criteria.addSortPluginName(PageOrdering.ASC)
rhqadmin@localhost:7080$ resources = ResourceManager.findResourcesByCriteria(criteria)
{code}
\\
This criteria is translated into the following JPA-QL query,
\\
{code}
SELECT r
FROM Resource r
WHERE ( r.inventoryStatus = InventoryStatus.COMMITTED )
ORDER BY r.resourceType.plugin ASC
{code}
\\
To add sorting, we call {{criteria.addSortPluginName()}}. To add sorting to any criteria, you will use methods of the form addSort{_}XXX_(PageOrdering order).
h3. Filtering
Now let's add some filtering to refine our search results. We will filter on the resource type name.
\\
{code}
rhqadmin@localhost:7080$ criteria.addFilterResourceTypeName('JBossAS Server')
rhqadmin@localhost:7080$ resources = ResourceManager.findResourcesByCriteria(criteria)
{code}
To add filtering to any criteria, you will use methods of the form addFilter{_}XXX_(). The resulting JPA-QL quyery is,
\\
{code}
SELECT r
FROM Resource r
WHERE ( r.inventoryStatus = InventoryStatus.COMMITTED
AND LOWER( r.resourceType.name ) like 'JBossAS Server' ESCAPE '\\' )
{code}
\\
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.
\\
{code}
rhqadmin@localhost:7080$ criteria.addFilterResourceTypeName('JBossAS Server')
rhqadmin@localhost:7080$ criteria.addFilterAgentName('localhost.localdomain')
rhqadmin@localhost:7080$ resources = ResourceManager.findResourcesByCriteria(criteria)
{code}
\\
This generates the following JPA-QL query,
\\
{code}
SELECT r
FROM Resource r
WHERE ( r.inventoryStatus = InventoryStatus.COMMITTED
|
AND LOWER( r.agent.name ) like 'localhost.localdomain' ESCAPE '\\' )
{code}
|
|
h3. Fetching Associations
|
... After we have retrieved resources, let's look at how we can drill down into and view child resources. Consider this code,
{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')
{code}
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|https://www.hibernate.org/162.html]. Since child resources are lazily loaded, we need to specify in the criteria that they should be fetched.
{code}
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)
{code}
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, fetch{_}XXX_(). The output from the above is,
{noformat}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
|
...
{noformat}
|
The actual output you see will vary depending on what you have inventoried. These are the child resources of my Jopr RHQ server. The JPA-QL query that is generated looks like,
|
{code}
|
... SELECT r
FROM Resource r
LEFT JOIN FETCH r.childResources
WHERE ( r.inventoryStatus = InventoryStatus.COMMITTED
AND LOWER( r.resourceType.name ) like 'JBossAS Server' ESCAPE '\\' )
{code}
\\
*TODO* Add a link to more examples (when the example docs are written)
h2. Displaying Output
h3. TabularWriter
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.
{noformat}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
{noformat}
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.
{noformat}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]]
{noformat}
For display purposes, this output is not very usable. Let's look at one more example in which we display a single entity.
{noformat}rhqadmin@localhost:7080$ pretty.print(resources.get(0))
Resource:
id: 11373
name: service-alpha-8
version: 1.0
resourceType: service-alpha
{noformat}
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|http://jopr.org/javadoc/domain/org/rhq/core/domain/resource/Resource.html] class are displayed. TabularWriter determines the properties to display via the [Summary|http://jopr.org/javadoc/domain/org/rhq/core/domain/util/Summary.html] annotation. If a field of an entity has the {{@Summary}} annotation, TabularWriter will include it in the output.
h3. Exporter
{{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.
{noformat}rhqadmin@localhost:7080$ exporter.setTarget('raw', 'output.txt')
rhqadmin@localhost:7080$ exporter.write(resources)
{noformat}
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.
{noformat}rhqadmin@localhost:7080$ exporter.setTarget('csv', 'output.csv')
|
rhqadmin@localhost:7080$ exporter.write(resources)
{noformat}
|
|
h1. Proxy
|
... 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.
{code}
var rhelServerOne = ProxyFactory.getResource(10001);
{code}
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.
{code}
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%
{code}
|
|
h2. Running Operations
|
... To run an operation on the proxy call the bound method representing that operation.
{code}
platform.viewProcessList();
agent.updateAllPlugins();
|
jbossas.restart();
{code}
|
|
h2. Configurations
|
... 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.
{code}
datasource.getResourceConfiguration()
{code}
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.
{code}
|
datasource.editResourceConfiguration()
{code}
|
|
h2. Content
|
... 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.
{code}
myCustomEAR.retrieveBackingContent(null);
{code}
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.
{code}
|
myCustomEAR.updateBackingContent('CustomEAR_v2.ear');
{code}
|
|
h1. References
|
... * [Java Scripting Programmer's Guide|http://java.sun.com/javase/6/docs/technotes/guides/scripting/programmer_guide/index.html]
* [scripting.dev.java.net|https://scripting.dev.java.net/]
* [Rhino: JavaScript for Java|http://www.mozilla.org/rhino/]
* [THe Java Persistence Query Langauge (JEE 5 Tutorial)|http://java.sun.com/javaee/5/docs/tutorial/backup/update3/doc/QueryLanguage.html]
|