com.alarmpoint.integrationagent.apxml

## Interface APXMLMessage

- All Superinterfaces:
    java.io.Serializable

      public interface APXMLMessage
      extends java.io.Serializable

  This interface provides access to the essential properties of an APXML message. It is primarily focused on textual (String-based) access to APXML, which is the primary APAgent/APIA usage mode; however, readers are reminded that an APXML message encodes data objects (e.g., lists, integers, etc.), whose direct representation is used within the AlarmPoint Node.

  NOTE: By convention, implementations are thread-safe.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `AGENT_APPLICATION_ID` Messages use the agent_application_id to identify the APAgent or APIA.
    `static java.lang.String` | `AGENT_CLIENT_ID` Messages use the agent_client_id to identify the APAgent integration or APIA Integration Service.
    `static java.lang.String` | `APIA_PASSWORD` This token is used to specify the password that may be required when submitting APXML messages to the Integration Agent.
    `static java.lang.String` | `APIA_PRIORITY` This token is used to differentiate normal priority APXML messages from high priority APXML message.
    `static java.lang.String` | `APIA_PRIORITY_HIGH`
    `static java.lang.String` | `APIA_PRIORITY_NORMAL`
    `static java.lang.String` | `APIA_PROCESS_GROUP` This token is used to group APXML messages into subsets that are processed sequentially in FIFO order.
    `static java.lang.String` | `APIA_SOURCE` This token is used to indicate the source of an APXML message.
    `static java.lang.String` | `APIA_SOURCE_ALARMPOINT_PREFIX`
    `static java.lang.String` | `APIA_SOURCE_APCLIENT_PREFIX`
    `static java.lang.String` | `APIA_SOURCE_INTEGRATION_PREFIX`
    `static java.lang.String` | `COMPANY_NAME` Messages use the company_name token to specify the owning company.
    `static java.lang.String` | `DESTINATION` ExternalServiceRequest responses use destination to target the response.
    `static java.lang.String` | `ERROR_CODE` Error messages use the error_code to identify the problem cause.
    `static java.lang.String` | `ERROR_METHOD` The method/subclass for APXML sent by the server for failed submission.
    `static java.lang.String` | `ERROR_SUBCLASS`
    `static java.lang.String` | `LIST_DELIM_SUFFIX` Messages use a token with this suffix to indicate that its value represents a list delimiter for the corresponding unsuffixed token's value.
    `static java.lang.String` | `OK_METHOD` The method/subclass for APXML sent by the server for successful submission.
    `static java.lang.String` | `OK_SUBCLASS`
    `static java.lang.String` | `ORIGINATOR` ExternalServiceRequest messages use originator to indicate where the response should be targeted.
    `static java.lang.String` | `RECIPIENTS` Messages use the recipients token to specify who (e.g., user or group), should be contacted by whatever events/notifications the message initiates.
    `static java.lang.String` | `REQUEST_ID` ExternalServiceRequet/Message messages use request_id to uniquely identify the message.
    `static java.lang.String` | `REQUEST_METHOD` The method/subclass for APXML sent by ExternalServiceRequest2.
    `static java.lang.String` | `REQUEST_SUBCLASS`
    `static java.lang.String` | `RESPONSE_METHOD` The method/subclass for APXML sent to ExternalServiceRequest2.
    `static java.lang.String` | `RESPONSE_SUBCLASS`
    `static java.lang.String` | `SEND_METHOD` The method/subclass for APXML sent by ExternalServiceMessage.
    `static java.lang.String` | `SEND_SUBCLASS`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String` | `getMethod()` Gets the message's mandatory method, which defines the highest-level purpose of the message (e.g., Add, Delete, etc.).
    `java.lang.String` | `getSubclass()` Gets the message's optional subclass, which provides a more refined purpose to the message (e.g., Add/Event).
    `APXMLToken` | `getToken(java.lang.String key)` Gets the token (if any) with the specified case-insensitive key.
    `java.util.Iterator<APXMLToken>` | `getTokens()` Gets the list of tokens that this message contains.
    `int` | `getTransactionId()` Gets the mandatory transaction id, which is an application-defined value used track messages.
    `java.lang.String` | `getValue(java.lang.String key)` Gets the value of the token (if any) with the specified case-insensitive key.
    `boolean` | `hasToken(java.lang.String key)` Determines whether or not the message contains a token with the specified case-insensitive key.
    `APXMLToken` | `removeToken(java.lang.String key)` Ensures that the message does not contain a token with the specified case-insensitive key.
    `void` | `setMethod(java.lang.String method)` Sets the message's method.
    `void` | `setSubclass(java.lang.String subclass)` Sets the message's subclass.
    `APXMLToken` | `setToken(java.lang.String key, java.lang.Object val)` Adds/replaces an auto-typed token to/in this message.
    `APXMLToken` | `setToken(java.lang.String key, java.lang.Object val, APXMLToken.Type type)` The analog of `setToken(String, Object)`, but with an explicit token type.
    `void` | `setTransactionId(int transactionId)` Sets the message's transaction id.
    `java.lang.String` | `toString()` Gets the XML representation of this message.

- - ### Field Detail

    - #### REQUEST_METHOD

          static final java.lang.String REQUEST_METHOD

      The method/subclass for APXML sent by ExternalServiceRequest2.
      See Also:
        Constant Field Values

    - #### REQUEST_SUBCLASS

          static final java.lang.String REQUEST_SUBCLASS

    - #### RESPONSE_METHOD

          static final java.lang.String RESPONSE_METHOD

      The method/subclass for APXML sent to ExternalServiceRequest2.
      See Also:
        Constant Field Values

    - #### RESPONSE_SUBCLASS

          static final java.lang.String RESPONSE_SUBCLASS

    - #### SEND_METHOD

          static final java.lang.String SEND_METHOD

      The method/subclass for APXML sent by ExternalServiceMessage.
      See Also:
        Constant Field Values

    - #### SEND_SUBCLASS

          static final java.lang.String SEND_SUBCLASS

    - #### OK_METHOD

          static final java.lang.String OK_METHOD

      The method/subclass for APXML sent by the server for successful submission.
      See Also:
        Constant Field Values

    - #### OK_SUBCLASS

          static final java.lang.String OK_SUBCLASS

    - #### ERROR_METHOD

          static final java.lang.String ERROR_METHOD

      The method/subclass for APXML sent by the server for failed submission.
      See Also:
        Constant Field Values

    - #### ERROR_SUBCLASS

          static final java.lang.String ERROR_SUBCLASS

    - #### ERROR_CODE

          static final java.lang.String ERROR_CODE

      Error messages use the error_code to identify the problem cause.
      See Also:
        Constant Field Values

    - #### REQUEST_ID

          static final java.lang.String REQUEST_ID

      ExternalServiceRequet/Message messages use request_id to uniquely identify the message.
      See Also:
        Constant Field Values

    - #### ORIGINATOR

          static final java.lang.String ORIGINATOR

      ExternalServiceRequest messages use originator to indicate where the response should be targeted.
      See Also:
        Constant Field Values

    - #### DESTINATION

          static final java.lang.String DESTINATION

      ExternalServiceRequest responses use destination to target the response.
      See Also:
        Constant Field Values

    - #### AGENT_APPLICATION_ID

          static final java.lang.String AGENT_APPLICATION_ID

      Messages use the agent_application_id to identify the APAgent or APIA.
      See Also:
        Constant Field Values

    - #### AGENT_CLIENT_ID

          static final java.lang.String AGENT_CLIENT_ID

      Messages use the agent_client_id to identify the APAgent integration or APIA Integration Service.
      See Also:
        Constant Field Values

    - #### COMPANY_NAME

          static final java.lang.String COMPANY_NAME

      Messages use the company_name token to specify the owning company.
      See Also:
        Constant Field Values

    - #### RECIPIENTS

          static final java.lang.String RECIPIENTS

      Messages use the recipients token to specify who (e.g., user or group), should be contacted by whatever events/notifications the message initiates.
      See Also:
        Constant Field Values

    - #### LIST_DELIM_SUFFIX

          static final java.lang.String LIST_DELIM_SUFFIX

      Messages use a token with this suffix to indicate that its value represents a list delimiter for the corresponding unsuffixed token's value.
      See Also:
        Constant Field Values

    - #### APIA_SOURCE

          static final java.lang.String APIA_SOURCE

      This token is used to indicate the source of an APXML message. The source can either be APClient (in which case the IP address is added), AlarmPoint (in which case the server's URL is added), or an Integration Service (in which case <domain>|<name> is added).
      See Also:
        Constant Field Values

    - #### APIA_SOURCE_APCLIENT_PREFIX

          static final java.lang.String APIA_SOURCE_APCLIENT_PREFIX

      See Also:
        Constant Field Values

    - #### APIA_SOURCE_ALARMPOINT_PREFIX

          static final java.lang.String APIA_SOURCE_ALARMPOINT_PREFIX

      See Also:
        Constant Field Values

    - #### APIA_SOURCE_INTEGRATION_PREFIX

          static final java.lang.String APIA_SOURCE_INTEGRATION_PREFIX

      See Also:
        Constant Field Values

    - #### APIA_PRIORITY

          static final java.lang.String APIA_PRIORITY

      This token is used to differentiate normal priority APXML messages from high priority APXML message. The priority is used to partition the messages into separate processing queues.
      See Also:
        Constant Field Values

    - #### APIA_PRIORITY_NORMAL

          static final java.lang.String APIA_PRIORITY_NORMAL

      See Also:
        Constant Field Values

    - #### APIA_PRIORITY_HIGH

          static final java.lang.String APIA_PRIORITY_HIGH

      See Also:
        Constant Field Values

    - #### APIA_PROCESS_GROUP

          static final java.lang.String APIA_PROCESS_GROUP

      This token is used to group APXML messages into subsets that are processed sequentially in FIFO order. All messages without this token (or with an empty token value) are grouped in a single set called "apia_default_group". Messages with this token are processed in FIFO order with matching messages (based on the same token value), and concurrently with non-matching messages.
      See Also:
        Constant Field Values

    - #### APIA_PASSWORD

          static final java.lang.String APIA_PASSWORD

      This token is used to specify the password that may be required when submitting APXML messages to the Integration Agent.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getTransactionId

          int getTransactionId()

      Gets the mandatory transaction id, which is an application-defined value used track messages.
      Returns:
        an integer in the range [1,2147483647]

    - #### setTransactionId

          void setTransactionId(int transactionId)

      Sets the message's transaction id.
      Parameters:
        `transactionId` - - the transaction id; must be in the range [1,2147483647]
      See Also:
        `getTransactionId()`

    - #### getMethod

          java.lang.String getMethod()

      Gets the message's mandatory method, which defines the highest-level purpose of the message (e.g., Add, Delete, etc.).
      Returns:
        a non-empty String trimmed of leading/trailing whitespace.

    - #### setMethod

          void setMethod(java.lang.String method)

      Sets the message's method.

      NOTE: The method's case is preserved.

      Parameters:
        `method` - - the method; must be non-empty after trimming leading/trailing whitespace
      See Also:
        `getMethod()`

    - #### getSubclass

          java.lang.String getSubclass()

      Gets the message's optional subclass, which provides a more refined purpose to the message (e.g., Add/Event).
      Returns:
        a non-empty String trimmed of leading/trailing whitespace if the message has a subclass; otherwise, null

    - #### setSubclass

          void setSubclass(java.lang.String subclass)

      Sets the message's subclass.

      NOTE: The subclass' case is preserved.

      Parameters:
        `subclass` - - the subclass; may be null or empty (after trimming leading/trailing whitespace), to indicate that the message has no subclass
      See Also:
        `getSubclass()`

    - #### getToken

          APXMLToken getToken(java.lang.String key)

      Gets the token (if any) with the specified case-insensitive key.
      Parameters:
        `key` - - the name of the token; must be non-empty after trimming leading/trailing whitespace
      Returns:
        a non-null Token if the token exists; otherwise, null

    - #### getValue

          java.lang.String getValue(java.lang.String key)

      Gets the value of the token (if any) with the specified case-insensitive key.
      Parameters:
        `key` - - the name of the token; must be non-empty after trimming leading/trailing whitespace
      Returns:
        a non-null String if the token exists; otherwise, null

    - #### setToken

          APXMLToken setToken(java.lang.String key,
                              java.lang.Object val)

      Adds/replaces an auto-typed token to/in this message.

      NOTE: The token's key is trimmed of whitespace and converted to lowercase before inclusion.

      Parameters:
        `key` - - the name of the token; must be non-empty after trimming leading/trailing whitespace and cannot contain any internal spaces
        `val` - - the token's value; converted to string using Object.toString() with null value being treated as an empty string
      Returns:
        the previous token with the same name, or null if no such token existed

    - #### setToken

          APXMLToken setToken(java.lang.String key,
                              java.lang.Object val,
                              APXMLToken.Type type)

      The analog of `setToken(String, Object)`, but with an explicit token type.

      NOTE:No check is performed to verify that the value complies with the specified type.

      Parameters:
        `key` - - the name of the token; must be non-empty after trimming leading/trailing whitespace and cannot contain any internal spaces
        `val` - - the token's value; converted to string using Object.toString() with null value being treated as an empty string
        `type` - - the token's type; must be non-null
      Returns:
        the previous token with the same name, or null if no such token existed
      See Also:
        `setToken(String, Object)`

    - #### removeToken

          APXMLToken removeToken(java.lang.String key)

      Ensures that the message does not contain a token with the specified case-insensitive key.
      Parameters:
        `key` - - the name of the token to remove; must be non-empty after trimming leading/trailing whitespace
      Returns:
        the removed token, or null if no such token existed

    - #### hasToken

          boolean hasToken(java.lang.String key)

      Determines whether or not the message contains a token with the specified case-insensitive key.
      Parameters:
        `key` - - the name of the token; must be non-empty after trimming leading/trailing whitespace
      Returns:
        true if the message contains the token; otherwise, false

    - #### getTokens

          java.util.Iterator<APXMLToken> getTokens()

      Gets the list of tokens that this message contains.

      NOTE: The returned iterator is thread-safe.

      Returns:
        a non-null, but perhaps empty, immutable Iterator

    - #### toString

          java.lang.String toString()

      Gets the XML representation of this message.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a non-empty String trimmed of leading/trailing whitespace and with the <?xml...> header.