com.alarmpoint.integrationagent.script.api
Interface IntegrationServiceRequest


public interface IntegrationServiceRequest

This is the interface through which the JavaScript implementation of an Integration Service can send an Integration Service Request to another Integration Service, regardless of whether the targeted Integration Service is local or remote. Integration Service Requests can be targeted to a specific Integration Agent or can be routed to which ever Integration Agent supports the targeted Integration Service.

NOTE: Implementations of this class are not required to be thread-safe, so instances of this interface should only be used by a single thread.


Method Summary
 java.lang.Object send()
          Sends the Integration Service Request to the targeted Integration Service.
 void setAction(java.lang.String action)
          Sets the (required) name of the Integration Service Request action that will be executed by the targeted Integration Service.
 void setAgentId(java.lang.String agentId)
          Sets the (optional) id of the Integration Agent to which the request will be sent, regardless of whether or not the Integration Agent provides the service specified by setDomain(String) and setName(String).
 void setDomain(java.lang.String domain)
          Sets the (required) Event Domain of the targeted Integration Service (e.g., "default").
 void setName(java.lang.String name)
          Sets the (required) name of the targeted Integration Service (e.g., "sample").
 void setTimeout(long timeout)
          Sets the (optional) timeout, in seconds, which determines how long the request will wait for a response from the targeted Integration Agent before generating an exception that is sent to the caller.
 void setToken(java.lang.String key, java.lang.Object value)
          Adds or replaces one of the parameters that will be passed to the targeted Integration Service's action.
 

Method Detail

setAgentId

void setAgentId(java.lang.String agentId)
Sets the (optional) id of the Integration Agent to which the request will be sent, regardless of whether or not the Integration Agent provides the service specified by setDomain(String) and setName(String).

If the specified Integration Agent cannot be located, the request will fail (i.e., there will be no failover to another Integration Agent even providing the targeted Integration Service).

NOTE: An Integration Agent's id complies with the requirements for XML Schema tokens: it does not contain line feeds, carriage returns, tabs, leading or trailing spaces, or multiple spaces.

Parameters:
agentId - - the Integration Agent's id; may be null or empty (after trimming leading/trailing whitespace), to indicate that no specific agent is being targeted.

setDomain

void setDomain(java.lang.String domain)
Sets the (required) Event Domain of the targeted Integration Service (e.g., "default").

NOTE: An Integration Service's domain complies with the following regular expression: [a-zA-Z0-9\-_]+

Parameters:
domain - - the Integration Service's Event Domain; must be non-empty after trimming trailing/leading whitespace.

setName

void setName(java.lang.String name)
Sets the (required) name of the targeted Integration Service (e.g., "sample").

NOTE: An Integration Service's name complies with the following regular expression: [a-zA-Z]([a-zA-Z0-9\-])*

Parameters:
name - - the Integration Service's name; must be non-empty after trimming leading/trailing whitespace.

setTimeout

void setTimeout(long timeout)
Sets the (optional) timeout, in seconds, which determines how long the request will wait for a response from the targeted Integration Agent before generating an exception that is sent to the caller.

If an explicit timeout is not set, the default value is 30 seconds.

Parameters:
timeout - - the timeout in seconds; must be positive.
See Also:
send()

setAction

void setAction(java.lang.String action)
Sets the (required) name of the Integration Service Request action that will be executed by the targeted Integration Service.

NOTE: An action's name corresponds to a method in the targeted Integration Service's JavaScript implementation, and complies with the following regular expression: [a-zA-Z]([a-zA-Z0-9\_])*

Parameters:
action - - the action's name; must be non-empty after trimming leading/trailing whitespace.

setToken

void setToken(java.lang.String key,
              java.lang.Object value)
Adds or replaces one of the parameters that will be passed to the targeted Integration Service's action.

NOTE: The parameters that required by an Integration Service's action depend on the JavaScript implementation of this action. Please consult the targeted Integration Service's documentation for the required parameters and their relevant values.

Parameters:
key - - the parameter's name; must be non-empty after trimming leading/trailing whitespace.
value - - the parameter's value; may be null.

send

java.lang.Object send()
                      throws java.lang.Exception
Sends the Integration Service Request to the targeted Integration Service. If no specified Integration Agent is being targeted, then the request may go to any Integration Agent that actively provides the targeted Integration Service, with preference given to the caller's Integration Agent (i.e., the local Integration Agent), if it provides the Integration Service.

If there are multiple remote Integration Agents that are eligible to receive the request, one is randomly chose. If the chosen Integration Agent fails to process the request, there is no failover, and an exception will be sent to the caller.

NOTE: The result of the Integration Service Request depends on the implementation of the targeted Integration Service. Please consult the targeted Integration Service's documentation for the required parameters and their relevant values.

Returns:
the result of the Integration Service Request; may be null.
Throws:
java.lang.Exception - if the targeted Integration Service responds with an error or the request times out.