Creating a custom advisor

A custom advisor is a small piece of Java code, provided as a class file, that is called by the Load Balancer base code to determine the load on a server. The base code provides all necessary administrative services, including starting and stopping an instance of the custom advisor, providing status and reports, recording history information in a log file, and reporting advisor results to the manager component.

About this task

Custom advisors are called after native, or standard, advisors have been searched. If the Load Balancer does not find a specified advisor among the list of standard advisors, it consults the list of custom advisors. When the Load Balancer base code calls a custom advisor, the following steps happen:
  1. The Load Balancer base code opens a connection with the server machine.
  2. If the socket opens, the base code calls the specified advisor’s GetLoad function.
  3. The advisor’s GetLoad function performs the steps that the user has defined for evaluating the server’s status, including waiting for a response from the server. The function terminates execution when the response is received.
  4. The Load Balancer base code closes the socket with the server and reports the load information to the manager. Depending on whether the custom advisor operates in normal mode or in replace mode, the base code sometimes does additional calculations after the GetLoad function terminates.
Custom advisors can be designed to interact with the Load Balancer in either normal mode or replace mode. The choice for the mode of operation is specified in the custom advisor file as a parameter in the constructor method. (Each advisor operates in only one of these modes, based on its design.)
  • Normal mode: the custom advisor exchanges data with the server, and the base advisor code times the exchange and calculates the load value. The base code then reports this load value to the manager. The custom advisor returns the value zero to indicate success, or negative one to indicate an error.

    To specify normal mode, set the replace flag in the constructor to false.

  • Replace mode: the base code does not perform any timing measurements. The custom advisor code performs whatever operations are specified, based on its unique requirements, and then returns an actual load number. The base code accepts the load number and reports it, unaltered, to the manager. For best results, normalize your load numbers between 10 and 1000, with 10 representing a fast server and 1000 representing a slow server.

    To specify replace mode, set the replace flag in the constructor to true.

Like all advisors, a custom advisor extends the functionality of the advisor base class, which is called ADV_Base. The advisor base performs most of the advisor’s functions, such as reporting loads back to the manager for use in the manager’s weight algorithm. The advisor base also performs socket connect and close operations and provides send and receive methods for use by the advisor. The advisor is used only for sending and receiving data on the specified port for the server that is being investigated. The TCP methods provided within the advisor base are timed to calculate load. A flag within the constructor of the advisor base overwrites the existing load with the new load returned from the advisor, if desired.
Note: Based on a value set in the constructor, the advisor base supplies the load to the weight algorithm at specified intervals. If the advisor has not completed processing and cannot return a valid load, the advisor base uses the previously reported load.

Procedure

  1. Name your advisor. Custom advisor file names must follow the form ADV_name.java, where name is the name that you choose for your advisor.
    Avoid trouble Avoid trouble:
    • You must use the ADV_ prefix for the advisor name.
    • You must name the custom advisor using lower-case alphabetic characters to eliminate case sensitivity when an operator types commands on a command line.
    • The custom advisor class must be located within the install_root/lib/CustomAdvisors subdirectory.
    • According to Java conventions, the name of the class defined within the file must match the name of the file.
    gotcha
  2. Write your custom advisor. Read Custom advisor methods and function calls for a list of methods and function calls to use in your advisor. Be aware that custom advisors need to have all the required routines. Advisors must have the following base class methods:
    • A constructor routine. The constructor calls the base class constructor.
    • An ADV_AdvisorInitialize method. This method provides a way to perform additional steps after the base class completes its initialization.
    • A getLoad routine. The base advisor class performs the socket opening; the getLoad function only needs to issue the appropriate send and receive requests to complete the advising cycle.

  3. Compile the advisor.
    • You must write custom advisors in the Java language and compile them with a Java compiler that is at the same level as the Load Balancer code. To check the version of Java on your system, run the following command from the install_root/java/bin directory:
      java -fullversion
      If the current directory is not part of your path, you will need to specify that Java should be run from the current directory to ensure you are getting the correct version information. In this case, run the following command from the install_root/java/bin directory:
      ./java -fullversion
    • The following files are referenced during compilation:
      • The custom advisor file.
      • The base classes file, ibmnd.jar, which is found in the install_root/servers/lib directory.
    • Your classpath environment variable must point to both the custom advisor file and the base classes file during the compilation. A compile command might have the following format, if your advisor is in the current directory:
      install_path/java/bin/javac -classpath install_root/servers/lib/ibmlb.jar ADV_name.java
    • The output of the compilation is a class file, for example, ADV_name.class. Before starting the advisor, copy the class file to the install_root/servers/lib/CustomAdvisors/ directory.
    Note: You can compile custom advisors on one operating system and run on another operating system. For example, you can compile your advisor on a Windows system, copy the resulting class file, in binary format, to a Linux machine, and run the custom advisor there. For AIX, HP-UX, Linux, and Solaris operating systems, the syntax is similar.
  4. Run your custom advisor. Custom advisors are called after native, or standard, advisors are searched. If Load Balancer does not find a specified advisor among the list of standard advisors, it consults the list of custom advisors.
    1. If you have not already done so, copy the advisor’s class file to the CustomAdvisors subdirectory on the Load Balancer machine. For example, for a custom advisor named myping, the file path is install_root/servers/lib/CustomAdvisors/ADV_myping.class.
    2. Configure the Load Balancer, start its manager function, and issue the command to start your custom advisor. The custom advisor is specified by its name, excluding the ADV_ prefix and the file extension:
      dscontrol advisor start name.ext port
      The port number specified in the command is the port on which the advisor will open a connection with the target server.
Task topic    

Terms and conditions for information centers | Feedback

Last updated: January 17, 2013 11:24 AM EST
File name: tprf_advcust.html