Use the following advisor methods and function calls in your custom
advisors.
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.
Constructor (provided by advisor base)
public <advisor_name> {
String sName;
String sVersion;
int iDefaultPort;
int iInterval;
String sDefaultLogFileName;
boolean replace
)
- sName
- The name of the custom advisor
- sVersion
- The version of the custom advisor.
- iDefaultPort
- The port number on which to contact the server if no port number is specified
in the call.
- iInterval
- The interval at which the advisor will query the servers.
- sDefaultLogFileName
- This parameter is required but not used. The only acceptable value is
a null string, ""
- replace
- Whether or not this advisor functions in replace mode. Possible values
are the following:
- true – Replace the load calculated by the advisor base
code with the value reported by the custom advisor.
- false – Add the load value reported by the custom advisor
to the load value calculated by the advisor base code.
ADV_AdvisorInitialize() method
void ADV_AdvisorInitialize()
This
method is provided to perform any initialization that might be required for
the custom advisor. This method is called after the advisor base module starts.
In many cases, including the standard advisors, this method is not used and
its code consists of a return statement only. This method can be used to call
the suppressBaseOpeningSocket() method, which is valid only
from within this method.
In many cases, including the standard advisors,
this method is not used and its code consists of a return statement only.
You can use this method to call the suppressBaseOpeningSocket method, which
is valid only from within the ADV_AdvisorInitialize method.
ADVLOG() method
The ADVLOG function allows a custom
advisor to write a text message to the advisor base log file. The format follows:
void ADVLOG (int logLevel, String message)
This command has the following parameters:
- logLevel
- The status level at which the message is written to the log file. The
advisor log file is organized in stages; the most urgent messages are given
status level 0 and less urgent messages receive higher numbers. The most verbose
type of message is given status level 5. These levels are used to control
the types of messages that the user receives in real time (The dscontrol command
is used to set verbosity). Catastrophic errors should always be logged at
level 0.
- message
- The message to write to the log file. The value for this parameter is
a standard Java string.
getAdvisorName function
The getAdvisorName function
returns a Java string with the suffix portion of your custom advisor name.
For example, for an advisor named ADV_cdload.java, this function returns the
value cdload.
This function does not take parameters.
Avoid trouble: It
is not possible for this value to change during one instantiation of an advisor.
gotcha
caller.getCurrentServerId()
The getCurrentServerId
function returns a Java string which is a unique representation for the current
server. Typically, this value changes each time you call your custom advisor,
because the advisor base code queries all server machines in series.
This
function takes no parameters.
caller.getCurrentClusterId()
The getCurrentClusterId
function call returns a Java string which is a unique representation for the
current cluster. Typically, this value changes each time you call your custom
advisor, because the advisor base queries all clusters in series.
This
function takes no parameters.
caller.getSocket()
The getSocket function call returns
a Java socket which represents the socket opened to the current server for
communication.
This function takes no parameters.
caller.getLatestLoad()
The getLatestLoad function
allows a custom advisor to obtain the latest load value for a given server
object. The load values are maintained in internal tables by the advisor base
code and the manager daemon. This function call is useful if you want to make
the behavior of one protocol or port dependent on the behavior of another.
For example, you might use this function call in a custom advisor that disabled
a particular application server if the Telnet server on that same machine
was disabled.
The syntax is:
int caller.getLatestLoad (String clusterId, int port, String serverId)
The three arguments together define one server
object.
This command has the following parameters:
- clusterId
- The cluster identifier of the server object for which to obtain the current
load value. This argument must be a Java string.
- port
- The port number of the server object for which to obtain the current load
value.
- serverId
- The server identifier of the server object for which to obtain the current
load value. This argument must be a Java string. The return value is an integer.
- A positive return value represents the actual load value assigned for
the object that was queried.
- The value -1 indicates that the server asked about is down.
- The value -2 indicates that the status of the server asked about is unknown.
caller.receive()
The receive function gets information
from the socket connection. The syntax is:
caller.receive(StringBuffer *response)
This
command has the following parameters:
- response
- This is a string buffer into which the retrieved data is placed. Additionally,
the function returns an integer value with the following significance:
- 0 indicates data was sent successfully.
- A negative number indicates an error.
caller.send()
The send function uses the established
socket connection to send a packet of data to the server, using the specified
port. The syntax is as follows:
caller.send(String command)
This
command has the following parameters:
- command
- This is a string containing the data to send to the server. The function
returns an integer value with the following significance:
- 0 indicates data was sent successfully.
- A negative number indicates an error.
getLoad()
int getLoad( int iConnectTime; ADV_Thread *caller )
This
function has the following parameters:
- iConnectTime
- The length of time, in milliseconds, that it took the connection to complete.
This load measurement is performed by the advisor base code and passed to
the custom advisor code, which can use or ignore the measurement when returning
the load value. If the connection fails, this value is set to -1.
- caller
- The instance of the advisor base class where advisor base methods are
provided.Function calls available to custom advisors: The methods, or functions,
described in the following sections can be called from custom advisors. These
methods are supported by the advisor base code. Some of these function calls
can be made directly, for example, function_name(), but others require the
prefix caller. Caller represents the base advisor instance that supports the
custom advisor that is being executed.
getAdviseOnPort()
The getAdviseOnPort function returns
the port number on which the calling custom advisor is running.
The
return value is a Java integer (int), and the function does not take parameters.
Note: It
is not possible for this value to change during one instantiation of an advisor.
getAdvisorName()
The getAdvisorName function returns
a Java string with the suffix portion of your custom advisor’s name. For example,
for an advisor named ADV_cdload.java, this function returns the value cdload.
This function takes no parameters. Note that it is not possible for this value
to change during one instantiation of an advisor.
getInterval()
The getInterval function returns the
advisor interval, that is, the number of seconds between advisor cycles. This
value is equal to the default value set in the custom advisor’s constructor,
unless the value has been modified at run time by using the dscontrol command.
The return value is a Java integer (int).
The function takes no parameters.
suppressBaseOpeningSocket()
The suppressBaseOpeningSocket
function call allows a custom advisor to specify whether the base advisor
code opens a TCP socket to the server on the custom advisor’s behalf. If your
advisor does not use direct communication with the server to determine its
status, it might not be necessary to open this socket. This function call
can be issued only once, and it must be issued from the ADV_AdvisorInitialize() method routine.
The
function takes no parameters.