You can define a data source to use the Java™ API to interact with a long-running
application on the Java platform.
The agent starts the application at startup and interacts with it
periodically. When you build the agent, Agent Builder creates the
source code for the application. You must customize the code to gather
the correct data. Depending on the code, the data source can produce
multiple data set that can contain a single row, multiple rows, or
event data.
About this task
Use the Java API
data source and the Java programming
language to collect data that cannot be collected by using other Agent
Builder data sources. The agent starts the Java application and sends a shutdown request
when it is time to shutdown. The Java application
must exit only when it is requested to do so.
An
agent that contains Java API
attribute groups interfaces with the Java application
process. The Java application
uses the Java Provider Client
API to interface with the agent. For information about the API, see
the
Javadoc on
the Tivoli® Monitoring and OMEGAMON® XE Information Center.
Using the Java API you can:
- Connect to the agent process and register for attribute groups
that are supported by the Java application
- Receive and reply to a request for sampled data
- Send data asynchronously for 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 in a Java application
and sends it using the Java API.
The procedure shows how to create a sample Java application to use as a starting point
for your Java application.
Procedure
- On the Agent Initial Data Source page
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. This
choice affects the sample Java application
that is created at the end of the wizard. For more information, see Sending data.
- Optional: Click Advanced to
modify the advanced properties for the attribute group. Advanced is
available when you select 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).
- Select Add additional attributes and
click Next to add other attributes to the agent.
References to the attributes are incorporated into the sample Java application that is created
at the end of the wizard.
- Click Next.
- On the Global
Java API Data Source Information page, 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 sample Java application is created with
the main Java method in this
class.
The JAR file is the archive that contains
the Java classes that comprise
the Java application. The JAR
file is packaged and installed with the agent.
- Optional: Define
the error codes that the Java application
can send, on the Global Java API Data Source Information page, Error
Codes section. These error codes are sent by the Java application when it cannot
collect data.
Restriction: An error code has
a limit of 256 characters. Only ASCII letters, digits, and underscores
are allowed. No spaces are allowed.
- Click Add in the
Error Codes section.
- In the Java API Error Code
Definition window, enter a display value.
- Enter an internal value. The internal value must be
an integer from 1,000 to 2,147,483,647.
- Define a message text for each error.
You can use message text that was entered previously by selecting
it from the 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. The
message window lists messages that are defined in the agent. Until
you define messages, the list remains blank. You can use Edit to
alter a defined message and Remove to delete
one or more messages that you defined.
- In the Messages (list) window, click Add to
see a Message Definition window. In the Message
Definition window, 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 are packaged
with the agent and copied to the agent system on agent installation.
The Java provider client API
JAR file is not listed here; it is automatically 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 1).
Click Edit to edit the imported file. For more
information, see (Editing a command file definition).
Table 1. File types for supplemental
filesFile type |
Description |
Executable |
Select this option if you want to include an
executable file with the agent. The agent does not use this file,
but it is in the path for the Java application
to use. |
Library |
Select this option if you to include a library
with the agent. The agent does not use this file, but it is in the
library path for the Java application
to use. |
Java resource |
Select this option to include Java resources with the agent. The agent does
not use this file, but it is in the class path for the Java application to use. |
Note: When a Java resource
supplemental file is added to the Agent Builder, the file is automatically
added to the project class path. The Java compiler
uses the supplemental file to resolve any references that your code
has, to classes in the resource.
For information about where
the Supplemental Files are installed with your agent, see (New files on your system).
- Optional: Create a filter to limit the data
that is returned by this attribute group, if the data is sampled.
Create a filter by clicking Advanced.
Note: The data is sampled if you did not select Produces
events on the Java API Information page.
For
more information about filtering data from an attribute group, see Filtering attribute groups.
- Optional: Add configuration properties
to the subnode. If you are adding this data source to a
subnode, the Subnode Configuration Overrides page
is shown so you can add configuration properties to the subnode.
At least one configuration property is needed under the subnode for
the sample Java application
to be created. At least one configuration property is needed because
the sample uses a configuration property to distinguish one subnode
instance from another.
- Do one of the following steps:
- If you are using the Agent wizard,
click Next.
- Otherwise, click Finish to save
the data source and open the Agent Editor.
What to do next
Select the correct operating systems on
the Java API Settings page. Make this selection
if this attribute group and the Java application,
run on operating systems different from the operating systems that
are defined for the agent. To open the 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.