Monitoring data using Java API
The Java application programming interface (API) data source allows the agent developer to use the Java programming language to carry out data collection in a long-running process that is separate from the agent process. This provides the flexibility to the agent developer to collect data that cannot be collected with the other data sources supported in the Agent Builder. The agent starts the Java application and sends a shutdown request when it is time to shutdown. The Java application must only exit when it is requested to do so.
An agent that contains Java API attribute groups starts a server that interfaces with the Java client process. The Java client uses the Java API to interface with the agent. For information about the API, see the Javadoc on the IBM® Tivoli® Monitoring and OMEGAMON® XE Information Center. The Java API provides the ability to:
- Connect to the agent process and register for attribute groups supported by the client
- Receive and reply to a request for sampled data
- Send data asynchronously to an attribute group that produces events
- Send an error for an attribute group where data collection is failing
- Support attribute groups in subnodes with configured subnode instances
- Receive and reply to a take action request
Use the following procedure to create an attribute group which collects data from a Java API
- On the Agent Initial Data Source page (Figure 198) or the Data Source Location page, click Custom programs in the Monitoring Data Categories area.
- In the Data Sources area, click Java API.
- Click Next.
- On the Java API Information page, enter an Attribute group name.
- Enter a help text for the attribute group.
- Select whether the attribute group Produces a single data row, Can produce more than one data row, or Produces events. For more information, see Sending data.
- (Optional) Click Advanced to modify the advanced properties for the attribute group. The Advanced button is active when you have selected that the attribute group Can produce more than one data row, or Produces events.
- Click Next.
- On the Attribute Information page, specify the first attribute for the attribute group. For more information about creating attributes, see Creating attributes.
- Click Next.
- On the Global Java API Data
Source Information page Figure 200,
enter a Class name and a Jar file name.
The class name is a fully-qualified class name whose main method is called when Java is started.
The jar file is the archive that contains the Java classes that comprise the Java client. The jar file is packaged and installed with the agent.
- (Optional) On the
Global Java API Data Source
Information page, Error Codes section, you can
define the error codes that the Java client
can send if it cannot collect data
- In the Error Codes section, click Add. An error code has a limit of 256 characters. Only ASCII letters, digits, and underscores are allowed. No spaces are permitted.
- In the Java API Error Code Definition window Figure 201, enter a display value.
- Enter an internal value. The internal value must be an integer from 1,000 to 2,147,483,647.
- You must define a message text for each error.
You can use message text that was entered previously by selecting
it from the drop-down list. Click OK to return
to the Global Java API Data
Source Information page. The message is logged in the agent log file.
If no suitable message text is available, click Browse to set up the message text. The Messages (list) window is displayed (Figure 202). The message window lists messages that are defined in the agent. Until you have defined messages, the list remains blank. You can use Edit to alter a defined message and Remove to delete one or more messages that you have defined.
- In the Messages (list) window, click Add to
see a Message Definition window (Figure 203), where
you can type the text that describes the meaning of the new message
and select the message type.
Note:The message identifier is automatically generated for you.
- Click OK.
- The Messages (list) window is displayed with the new message. To verify the message and return to the Global Java API Data Source Information page, click OK.
- (Optional) In the Supplemental
Files section of the Global Java API
Data Source Information page, you can add files that will be packaged
with the agent and copied to the agent system when the agent is installed.
The Java API Jar file should
not be listed here; it will automatically be copied to the agent system.
The File Type column describes how each file
is expected to be used. Three possible uses are described in the following
table:
Table 29. File types for supplemental files File Type Description Executable Select this option if you want to include an executable with the agent. The agent will not use this file, but it will be in the path for the Java client to use. Library Select this option if you to include a library with the agent. The agent will not use this file, but it will be in the library path for the Java client to use. Java resource Select this option to include Java resources with the agent. The agent will not use this file, but it will be in the classpath for the Java client to use. Click Edit to make changes to the imported file. For more information, see Editing a command file definition.
- Do one of the following steps:
- If you are using the New Agent Wizard, click Next.
--OR--
- Click Finish to save the data source and open the Agent Editor.
Select the operating systems for the attribute group, and for the Java API if one is not yet defined in the Operating Systems section of the Java API Settings page. To open this page, click Java API Settings in the outline view or click Global Settings in the Agent Editor on any Java API attribute group page.
Note:Error codes and supplemental files can be updated later in the Error Codes and Supplemental Files sections of the Java API Settings page. - If you are using the New Agent Wizard, click Next.