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
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 AP 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 AP 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
 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 AP 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 AP 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 | 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 header.