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:

Use the following procedure to create an attribute group which collects data from a Java API

  1. On the Agent Initial Data Source page (Figure 198) or the Data Source Location page, click Custom programs in the Monitoring Data Categories area.
  2. In the Data Sources area, click Java API.
  3. Click Next.
  4. On the Java API Information page, enter an Attribute group name.
  5. Enter a help text for the attribute group.
  6. 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.
  7. (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.
  8. Click Next.
  9. On the Attribute Information page, specify the first attribute for the attribute group. For more information about creating attributes, see Creating attributes.
  10. Click Next.
  11. 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.

  12. (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
    1. 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.
    2. In the Java API Error Code Definition window Figure 201, enter a display value.
    3. Enter an internal value. The internal value must be an integer from 1,000 to 2,147,483,647.
    4. 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.

    5. 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.
    6. Click OK.
    7. 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.
  13. (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.
    For information about where the Supplemental Files are installed with your agent, see New files on your system.

    Click Edit to make changes to the imported file. For more information, see Editing a command file definition.

  14. Do one of the following steps:
    1. If you are using the New Agent Wizard, click Next.

      --OR--

    2. 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.