Use the Java API to monitor data.

Use the Java™ API data source and the Java programming language to collect data in a long-running process that is separate from the agent process.

1. On the Agent Initial Data Source page or the Data Source Location page, click Custom programs in the Monitoring Data Categories area.
   Figure 1. Monitoring data with Java API

   
2. In the Data Sources area, click Java API.
3. Click Next.
4. On the Java API Information page, enter an Attribute group name.
   Figure 2. Java API Information window

   
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. This choice affects the sample Java application that is created at the end of the wizard. For more information, see (Sending data).
7. 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.
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. 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.
11. Click Next.
12. 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.

    Figure 3. Global Java API Data Source Information page

    
13. 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.
    1. Click Add in the Error Codes section.
    2. In the Java API Error Code Definition window, enter a display value.
       Figure 4. Java API Error Code Definition window,

       
    3. Enter an internal value. The internal value must be an integer from 1,000 to 2,147,483,647.
    4. 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.
    5. If no suitable message text is available, click Browse to set up the message text. The Messages (list) window is displayed (Figure 5). 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.
       Figure 5. Messages window

       
    6. 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.
       Figure 6. Message Definition window

       
       Note: The message identifier is automatically generated for you.
    7. Click OK.
    8. 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.
14. 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 files

    File 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).
15. 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.
16. 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.
17. Do one of the following steps:
    1. If you are using the New Agent wizard, click Next.
    2. Otherwise, click Finish to save the data source and open the Agent Editor.