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

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.