ITKMessageProperties (ITK API and Reference Implementation mini-site 0.1-SNAPSHOT API)

All Known Implementing Classes:

ITKMessagePropertiesImpl
```
public interface ITKMessageProperties
```
Interface that represents the addressing, audit and other meta-data information associated with the ITK Message. This interface allows these properties to be passed between the application and transport layers.

Since:

version 0.1

Author:

Michael Odling-Smee, Nicholas Jones

See Also:
ITKMessage

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`BUSINESS_ACK_HANDLING_SPECIFICATION_KEY` The handling specification key for the property that allows the message originator to specify whether or not they would like a business Acknowledgement. Permissible values for this handling specification are the Strings `true` or `false`
`static String`	`INTERACTION_HANDLING_SPECIFICATION_KEY` The handling specification key for the property that allows the message originator to explicitly specify the interaction id of the message. The value for this handling specification should be the interaction id of the message - e.g.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addHandlingSpecification(String key, String value)` Allows the message originator to add a handling specification to the associated `ITKMessage`. Handling specifications provide an extensible mechanism for the message originator to attach special processing instructions with the message.
`ITKIdentity`	`getAuditIdentity()` Returns the audit identity of the ITK message originator
`String`	`getBusinessPayloadId()` Obtains the business payloadId associated with this message.
`ITKAddress`	`getFromAddress()` Obtains the originators ITK address
`String`	`getHandlingSpecification(String key)` Convenience method that allows the value of the handling specification to be obtained directly.
`Map<String,String>`	`getHandlingSpecifications()` Obtains the Map of the handling specifications associated with the `ITKMessage`. Handling specifications provide an extensible mechanism for the message originator to attach special processing instructions with the message.
`ITKTransportProperties`	`getInboundTransportProperties()` Obtains the `ITKTransportProperties` that are associated with the ITKMessage that was received by the service provider on the inbound leg in an asynchronous request/response invocation. The `inboundITKTransportProperties` are not expected to be processed by the application layer, however where present the application layer is responsible for attaching the `inboundITKTransportProperties` to any responses generated such that these transport properties are available to the transport layers transmitting the response. A typical use of this mechanism is for the propagation of the `<wsa:replyTo/>` address such that it is available to the to the transport layers managing the "reply". Note although this pattern adds some additional burden on the application layer it offers significant advantages over the alternative where the transport layer has to maintain state and correlate messages - potentially over several distributed nodes
`String`	`getProfileId()` Obtains the profileId associated with the ITKMessage.
`String`	`getServiceId()` ITK message service associated with the message
`ITKAddress`	`getToAddress()` Obtains the destination address for the associated ITK Message. Note Whilst the ITK Specifications allow for multiple recipients to be specified this version of the ITK API only supports a single recipient to be defined as this satisfies the majority of anticipated use-cases.
`String`	`getTrackingId()` Obtains the tracking id associated with the ITKMessage when sending the message between two or more endpoints.
`void`	`setAuditIdentity(ITKIdentity auditIdentity)` Sets the audit identity of the message originator
`void`	`setBusinessPayloadId(String businessPayloadId)` Sets the business payloadId associated with this message.
`void`	`setFromAddress(ITKAddress fromAddress)` Sets the originators address for this message.
`void`	`setInboundTransportProperties(ITKTransportProperties inboundITKTransportProperties)` Sets the `ITKTransportProperties` that are associated with the ITKMessage that was received by the service provider on the inbound leg in an asynchronous request/response invocation. The `inboundITKTransportProperties` are not expected to be processed by the application layer, however where present the application layer is responsible for attaching the `inboundITKTransportProperties` to any responses generated such that these transport properties are available to the transport layers transmitting the response. A typical use of this mechanism is for the propagation of the `<wsa:replyTo/>` URL such that it is available to the to the transport layers managing the "reply". Note although this pattern adds some additional burden on the application layer it offers significant advantages over the alternative where the transport layer has to maintain state and correlate messages - potentially over several distributed nodes
`void`	`setProfileId(String profileId)` Sets the profileId associated with the ITKMessage.
`void`	`setServiceId(String serviceId)` Sets the ITK message serviceId associated with this message
`void`	`setToAddress(ITKAddress toAddress)` Sets the destination address for the associated ITK Message. Note Whilst the ITK Specifications allow for multiple recipients to be specified this version of the ITK API only supports a single recipient to be defined as this satisfies the majority of anticipated use-cases.
`void`	`setTrackingId(String trackingId)` Sets the tracking id associated with the ITKMessage prior to sending the message between two or more endpoints.

- Field Detail
  - BUSINESS_ACK_HANDLING_SPECIFICATION_KEY
```
static final String BUSINESS_ACK_HANDLING_SPECIFICATION_KEY
```
    The handling specification key for the property that allows the message originator to specify whether or not they would like a business Acknowledgement.
    
    Permissible values for this handling specification are the Strings true or false
    
    See Also:
    Constant Field Values
  - INTERACTION_HANDLING_SPECIFICATION_KEY
```
static final String INTERACTION_HANDLING_SPECIFICATION_KEY
```
    The handling specification key for the property that allows the message originator to explicitly specify the interaction id of the message.
    
    The value for this handling specification should be the interaction id of the message - e.g. urn:nhs-itk:interaction:verifyNHSNumberRequest-v1-0
    
    See Also:
    Constant Field Values
- Method Detail
  - getFromAddress
```
ITKAddress getFromAddress()
```
    Obtains the originators ITK address
    
    Returns:
    and ITKAddress object with the address details of the message originator
  - setFromAddress
```
void setFromAddress(ITKAddress fromAddress)
```
    Sets the originators address for this message.
    
    Parameters:
    fromAddress - the ITKAddress object with the address details of the message originator
  - getToAddress
```
ITKAddress getToAddress()
```
    Obtains the destination address for the associated ITK Message.
    
    Note Whilst the ITK Specifications allow for multiple recipients to be specified this version of the ITK API only supports a single recipient to be defined as this satisfies the majority of anticipated use-cases.
    
    Returns:
    The ITKAddress object containing the address details of the intended recipient
  - setToAddress
```
void setToAddress(ITKAddress toAddress)
```
    Sets the destination address for the associated ITK Message.
    
    Note Whilst the ITK Specifications allow for multiple recipients to be specified this version of the ITK API only supports a single recipient to be defined as this satisfies the majority of anticipated use-cases.
    
    Parameters:
    toAddress - the ITKAddress object containing the address details of the intended recipient
  - getAuditIdentity
```
ITKIdentity getAuditIdentity()
```
    Returns the audit identity of the ITK message originator
    
    Returns:
    An ITKIdentity object containing the audit id
  - setAuditIdentity
```
void setAuditIdentity(ITKIdentity auditIdentity)
```
    Sets the audit identity of the message originator
    
    Parameters:
    An - ITKIdentity object containing the audit id
  - getServiceId
```
String getServiceId()
```
    ITK message service associated with the message
    
    Returns:
    a String identifying the ITK Service Id
  - setServiceId
```
void setServiceId(String serviceId)
```
    Sets the ITK message serviceId associated with this message
    
    Parameters:
    serviceId - The String identifying the ITK Service (from ITK Domain Message Specifications)
  - getBusinessPayloadId
```
String getBusinessPayloadId()
```
    Obtains the business payloadId associated with this message. This business payload message Id is typically used for tracking and correlating messages.
    
    Note The business payload id is logically distinct from the getTrackingId() as it is an id that is typically embedded somewhere in the business payload - for example as a document instance id in a CDA message, whereas the getTrackingId() is specifically an id assigned when sending the message between two or more endpoints and should not have meaning beyond the original ITK transmission and associated acknowledgements.
    
    Returns:
    The UUID associated with the ITK Message business payload
  - setBusinessPayloadId
```
void setBusinessPayloadId(String businessPayloadId)
```
    Sets the business payloadId associated with this message. This business payload message Id is typically used for tracking and correlating messages
    
    Parameters:
    businessPayloadId - The UUID associated with the ITK Message business payload
  - getProfileId
```
String getProfileId()
```
    Obtains the profileId associated with the ITKMessage. The profile Id represents the set of rules used to construct the message and provides a single String that aides with message/document version management as well as allowing message/document consumers to understand whether or not they are capable of handling the associated ITK Message
    
    Returns:
    The profile id (e.g. nhs-en:profile:nonCodedCDADocument-v2-0)
  - setProfileId
```
void setProfileId(String profileId)
```
    Sets the profileId associated with the ITKMessage. The profile Id represents the set of rules used to construct the message and provides a single String that aides with message/document version management as well as allowing message/document consumers to understand whether or not they are capable of handling the associated ITK Message
    
    Parameters:
    profileId - The profile id (e.g. nhs-en:profile:nonCodedCDADocument-v2-0)
  - getTrackingId
```
String getTrackingId()
```
    Obtains the tracking id associated with the ITKMessage when sending the message between two or more endpoints. The tracking id should not have meaning beyond the original ITK transmission and associated acknowledgements. In particular the trackingId is not expected to be an id directly represented in the business payload such as a CDA document instance id. Ids associated with the business payload are obtained via getBusinessPayloadId().
    
    The primary purpose of the tracking Id is for operational reasons (i.e. allows entries in log file across different servers and nodes to be tied together) and for correlation of asynchronous acknowledgements such as ITK Infrastructure acknowledgements (see ITKAckDetails.getTrackingRef()) and ITK Business Acknowledgements.
    
    Returns:
    a String with the UUID represent the tracking Id
  - setTrackingId
```
void setTrackingId(String trackingId)
```
    Sets the tracking id associated with the ITKMessage prior to sending the message between two or more endpoints. The tracking id should not have meaning beyond the original ITK transmission and associated acknowledgements. In particular the trackingId is not expected to be an id directly represented in the business payload such as a CDA document instance id. Ids associated with the business payload are set via setBusinessPayloadId(String).
    
    The primary purpose of the tracking Id is for operational reasons (i.e. allows entries in log file across different servers and nodes to be tied together) and for correlation of asynchronous acknowledgements such as ITK Infrastructure acknowledgements (see ITKAckDetails.getTrackingRef()) and ITK Business Acknowledgements.
    
    Parameters:
    trackingId - a String UUID representing the tracking Id for this transmission. Note if the message is resent a new tracking Id should be created
  - setInboundTransportProperties
```
void setInboundTransportProperties(ITKTransportProperties inboundITKTransportProperties)
```
    Sets the ITKTransportProperties that are associated with the ITKMessage that was received by the service provider on the inbound leg in an asynchronous request/response invocation.
    
    The inboundITKTransportProperties are not expected to be processed by the application layer, however where present the application layer is responsible for attaching the inboundITKTransportProperties to any responses generated such that these transport properties are available to the transport layers transmitting the response.
    
    A typical use of this mechanism is for the propagation of the <wsa:replyTo/> URL such that it is available to the to the transport layers managing the "reply".
    
    Note although this pattern adds some additional burden on the application layer it offers significant advantages over the alternative where the transport layer has to maintain state and correlate messages - potentially over several distributed nodes
    
    Parameters:
    inboundITKTransportProperties - The ITKTransportProperties that were obtained from the inbound message.
  - getInboundTransportProperties
```
ITKTransportProperties getInboundTransportProperties()
```
    Obtains the ITKTransportProperties that are associated with the ITKMessage that was received by the service provider on the inbound leg in an asynchronous request/response invocation.
    
    The inboundITKTransportProperties are not expected to be processed by the application layer, however where present the application layer is responsible for attaching the inboundITKTransportProperties to any responses generated such that these transport properties are available to the transport layers transmitting the response.
    
    A typical use of this mechanism is for the propagation of the <wsa:replyTo/> address such that it is available to the to the transport layers managing the "reply".
    
    Note although this pattern adds some additional burden on the application layer it offers significant advantages over the alternative where the transport layer has to maintain state and correlate messages - potentially over several distributed nodes
    
    Returns:
    inboundITKTransportProperties - the ITKTransportProperties that were obtained from the inbound message.
  - getHandlingSpecifications
```
Map<String,String> getHandlingSpecifications()
```
    Obtains the Map of the handling specifications associated with the ITKMessage.
    
    Handling specifications provide an extensible mechanism for the message originator to attach special processing instructions with the message. The current ITK specifications provide two built-in handling specifications - one for requesting a business acknowledgement message (BUSINESS_ACK_HANDLING_SPECIFICATION_KEY), and one to explicitly associated an interaction Id with the message (INTERACTION_HANDLING_SPECIFICATION_KEY).
    
    Returns:
    The Map of all handling specifications associated with the message. For each entry in the Map contains both the key (e.g. urn:nhs:itk:ns:201005:ackrequested) and the associated value. If no handling specifications are associated with the message then an empty map is returned.
  - addHandlingSpecification
```
void addHandlingSpecification(String key,
                            String value)
```
    Allows the message originator to add a handling specification to the associated ITKMessage.
    
    Handling specifications provide an extensible mechanism for the message originator to attach special processing instructions with the message. The current ITK specifications provide two built-in handling specifications - one for requesting a business acknowledgement message (BUSINESS_ACK_HANDLING_SPECIFICATION_KEY), and one to explicitly associated an interaction Id with the message (INTERACTION_HANDLING_SPECIFICATION_KEY).
    
    Parameters:
    key - The handling specification key - for instance BUSINESS_ACK_HANDLING_SPECIFICATION_KEY
    value - The appropriate value for the handling specification
  - getHandlingSpecification
```
String getHandlingSpecification(String key)
```
    Convenience method that allows the value of the handling specification to be obtained directly.
    
    Parameters:
    key - The handling specification key - for instance BUSINESS_ACK_HANDLING_SPECIFICATION_KEY
    
    Returns:
    The value associated with the provided key or null if the handling specification indicated by the key was not present

All content is available under the Open Government Licence, except where otherwise stated
All example source code is available under Apache 2.0, except where otherwise stated

Interface ITKMessageProperties

Field Summary

Method Summary

Field Detail

BUSINESS_ACK_HANDLING_SPECIFICATION_KEY

INTERACTION_HANDLING_SPECIFICATION_KEY

Method Detail

getFromAddress

setFromAddress

getToAddress

setToAddress

getAuditIdentity

setAuditIdentity

getServiceId

setServiceId

getBusinessPayloadId

setBusinessPayloadId

getProfileId

setProfileId

getTrackingId

setTrackingId

setInboundTransportProperties

getInboundTransportProperties

getHandlingSpecifications

addHandlingSpecification

getHandlingSpecification