ruon.jiao
Class JIAO

java.lang.Object
  extended by ruon.jiao.JIAO

public class JIAO
extends java.lang.Object

The JIAO class is an API to the IAOP protocol, allowing you to communicate with the R-U-ON platform.

A process using this class is called an Agent. There are two kind of agents, Private and Public. A public agent is downloaded from the R-U-ON site and is tightly integrated with the R-U-ON web application. A private Agent is developed by an R-U-ON user. A private Agent can be monitored by the R-U-ON system but has a few limitations. It cannot be downloaded from the R-U-ON site and therefor cannot be automatically upgraded. In addition it cannot be configured by the R-U-ON system (embedded configuration variables are added to the agent during the download process). Look at our agent publishing program to see how you can make your agent an integral part of the R-U-ON system.

When creating an instance the caller should pass the Agent type and version. The JIAO object should be created once for the lifetime of the agent. It must not be constructed each time a call is made as that will seem to the R-U-ON platform like an agent reboot.

When the calling process is running for the first time it should obtain a new instance id by invoking register() and passing the customer id. The agent id should be persisted for subsequent execution of the agent process.

After the first construction the caller should use setAgentId() to set the id to the persisted value. If the caller uses register every time, a new agent will be created each time the agent is executed.

In order to make sure the server considers the Agent alive, the Agent must call keepalive() and act according to the returned Directive. The most common Directive is a request to SLEEP. The duration of the SLEEP indicates when the server is expecting the agent to make contact again (by callin keepalive() again).

To report alarms use the reportAlarms() method.

For information about the IAOP protcol, goto http://www.r-u-on.com/api/IAOP.pdf

Since:
jiao 1.0
Version:
1.0, 6/29/06
Author:
R-U-ON

Nested Class Summary
static class JIAO.Alarm
          An Alarm object passed to the reportAlarms() method to indicate an alarm
static class JIAO.Clear
          A Clear Alarm instruction passed to the reportAlarms() method.
static class JIAO.Directive
          Directive is returned by methods communicating with the server to indicate what the server is expecting the agent to do.
static class JIAO.Event
          An Event object, passed to the reportAlarms() method.
static class JIAO.IAlarm
          A class representing an Alarm, a Clear instructions or an Event.
 
Constructor Summary
JIAO(java.lang.String agentType, java.lang.String agentVersion, boolean https)
          Creates the JIAO class and initialized the agent type and version.
 
Method Summary
 byte[] getBinary()
          Only used in public agents.
 java.lang.String getEmbeddedVariable(java.lang.String name)
          Only used in public agents.
 JIAO.Directive keepAlive()
          Send a keep-alive signal to the R-U-ON server.
 java.lang.String register()
          Registers a new agent with the R-U-ON service.
 java.lang.String register(java.lang.String accountId)
          Registers a new agent with the R-U-ON service.
 JIAO.Directive reportAlarms(JIAO.IAlarm[] alarms, boolean incremental)
          Reports alarms to the R-U-ON server.
 void setAgentId(java.lang.String agentId)
          Sets the agent id with the value persisted from the call to register()
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JIAO

public JIAO(java.lang.String agentType,
            java.lang.String agentVersion,
            boolean https)
Creates the JIAO class and initialized the agent type and version.

Parameters:
agentType - The agent's type. This name will be displayed as the agent type in the management screen.
agentVersion - The agent's version. In the case of a public agent, the version string is used to determine if the agent should upgrade.
https - Indicate if ths agent will use https when communicating with the server (alternative is http).
Method Detail

getBinary

public byte[] getBinary()
                 throws JIAOException,
                        java.io.IOException
Only used in public agents.

Should be used as a response to an upgrade directive.

Contacts the server and get's an image of the agent binary.

Returns:
The binary image of the agent.
Throws:
java.io.IOException - If an IO error has occored.
JIAOException - If an IAOP error has occored

getEmbeddedVariable

public java.lang.String getEmbeddedVariable(java.lang.String name)
                                     throws JIAOException
Only used in public agents.

Read variables embedded in the agent during the download process.

Parameters:
name - Name of the variable
Returns:
The value of the variable
Throws:
JIAOException - Thrown when the variable is not found

keepAlive

public JIAO.Directive keepAlive()
                         throws java.io.IOException,
                                JIAOException
Send a keep-alive signal to the R-U-ON server.

Returns:
An instruction that should be executed by the agent.
Throws:
java.io.IOException - If an IO error has occored.
JIAOException - If an IAOP error has occored
See Also:
JIAO.Directive

register

public java.lang.String register()
                          throws java.io.IOException,
                                 JIAOException
Registers a new agent with the R-U-ON service.

This method should be called once per agent to obtain a new agent id. The agent id should be persisted for subsequent uses. Do not call this function each time the process is launched as each call will create a new agent for the given customer.

This method is intended for the use of a public agent.

Returns:
The new agent id, to be persisted for future JIAO instances.
Throws:
java.io.IOException - If an IO error has occored.
JIAOException - If an IAOP error has occored

register

public java.lang.String register(java.lang.String accountId)
                          throws java.io.IOException,
                                 JIAOException
Registers a new agent with the R-U-ON service.

This method should be called once per agent to obtain a new agent id. The agent id should be persisted for subsequent uses. Do not call this function each time the process is launched as each call will create a new agent for the given customer.

This method is intended for the use of a private agent.

Parameters:
accountId - The R-U-ON account id (obtained from the account settings page in the R-U-ON site).
Returns:
The new agent id, to be persisted for future JIAO instances.
Throws:
java.io.IOException - If an IO error has occored.
JIAOException - If an IAOP error has occored

reportAlarms

public JIAO.Directive reportAlarms(JIAO.IAlarm[] alarms,
                                   boolean incremental)
                            throws java.io.IOException,
                                   JIAOException
Reports alarms to the R-U-ON server.

Parameters:
alarms - An array of alarms, clears and events (Alarm, Clear, Event)
incremental - Indicates if the call is the full list of active alarms (snapshot) or a list of alarms that should be added or delted. In the case of a snapshot, all active alarms that are not reported in the array are implicitly supressed.
Returns:
An instruction that should be executed by the agent.
Throws:
java.io.IOException - If an IO error has occored.
JIAOException - If an IAOP error has occored
See Also:
JIAO.Alarm, JIAO.Clear, JIAO.Event

setAgentId

public void setAgentId(java.lang.String agentId)
Sets the agent id with the value persisted from the call to register()

When register succeeds, it is not neccessary to call this method.

Parameters:
agentId - The agent id returned by register in the past.