1 /*
2 Licensed under the Apache License, Version 2.0 (the "License");
3 you may not use this file except in compliance with the License.
4 You may obtain a copy of the License at
5
6 http://www.apache.org/licenses/LICENSE-2.0
7
8 Unless required by applicable law or agreed to in writing, software
9 distributed under the License is distributed on an "AS IS" BASIS,
10 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11 See the License for the specific language governing permissions and
12 limitations under the License.
13 */
14 package uk.nhs.interoperability.infrastructure;
15
16 import java.util.Map;
17
18 import uk.nhs.interoperability.payload.ITKMessage;
19 import uk.nhs.interoperability.transport.ITKTransportProperties;
20
21 /**
22 * Interface that represents the addressing, audit and other meta-data information
23 * associated with the ITK Message. This interface allows these properties to be
24 * passed between the application and transport layers.
25 *
26 * @see ITKMessage
27 *
28 * @author Michael Odling-Smee
29 * @author Nicholas Jones
30 * @since version 0.1
31 *
32 */
33 public interface ITKMessageProperties {
34
35 /**
36 * The handling specification key for the property that allows the message originator
37 * to specify whether or not they would like a business Acknowledgement.</br/><br/>
38 *
39 * Permissible values for this handling specification are the Strings <code>true</code>
40 * or <code>false</code>
41 */
42 public static final String BUSINESS_ACK_HANDLING_SPECIFICATION_KEY = "urn:nhs:itk:ns:201005:ackrequested";
43
44 /**
45 * The handling specification key for the property that allows the message originator
46 * to explicitly specify the interaction id of the message.<br/><br/>
47 *
48 * The value for this handling specification should be the interaction id of the message -
49 * e.g. <code>urn:nhs-itk:interaction:verifyNHSNumberRequest-v1-0</code>
50 */
51 public static final String INTERACTION_HANDLING_SPECIFICATION_KEY = "urn:nhs-itk:ns:201005:interaction";
52
53 /**
54 * Obtains the originators ITK address
55 * @return and ITKAddress object with the address details of the message originator
56 */
57 public ITKAddress getFromAddress();
58
59 /**
60 * Sets the originators address for this message.
61 * @param fromAddress the ITKAddress object with the address details of the message
62 * originator
63 */
64 public void setFromAddress(ITKAddress fromAddress);
65
66 /**
67 * Obtains the destination address for the associated ITK Message.<br/><br/>
68 * <b>Note</b> Whilst the ITK Specifications allow for multiple recipients
69 * to be specified this version of the ITK API only supports a single recipient
70 * to be defined as this satisfies the majority of anticipated use-cases.
71 *
72 * @return The ITKAddress object containing the address details of the
73 * intended recipient
74 */
75 public ITKAddress getToAddress();
76
77 /**
78 * Sets the destination address for the associated ITK Message.<br/><br/>
79 * <b>Note</b> Whilst the ITK Specifications allow for multiple recipients
80 * to be specified this version of the ITK API only supports a single recipient
81 * to be defined as this satisfies the majority of anticipated use-cases.
82 *
83 * @param toAddress the ITKAddress object containing the address details of the
84 * intended recipient
85 */
86 public void setToAddress(ITKAddress toAddress);
87
88 /**
89 * Returns the audit identity of the ITK message originator
90 * @return An ITKIdentity object containing the audit id
91 */
92 public ITKIdentity getAuditIdentity();
93
94 /**
95 * Sets the audit identity of the message originator
96 * @param An ITKIdentity object containing the audit id
97 */
98
99 public void setAuditIdentity(ITKIdentity auditIdentity);
100
101 /**
102 * ITK message service associated with the message
103 * @return a String identifying the ITK Service Id
104 */
105 public String getServiceId();
106
107 /**
108 * Sets the ITK message serviceId associated with this message
109 * @param serviceId The String identifying the ITK Service (from ITK Domain Message Specifications)
110 */
111 public void setServiceId(String serviceId);
112
113 /**
114 * Obtains the business payloadId associated with this
115 * message. This business payload message Id is typically
116 * used for tracking and correlating messages.<br/><br/>
117 * <b>Note</b> The business payload id is logically distinct
118 * from the {@link #getTrackingId()} as it is an id that is
119 * typically embedded somewhere in the business payload - for
120 * example as a document instance id in a CDA message, whereas
121 * the {@link #getTrackingId()} is specifically an id assigned
122 * when sending the message between two or more endpoints and
123 * should not have meaning beyond the original ITK transmission and
124 * associated acknowledgements.
125 *
126 * @return The UUID associated with the ITK Message business
127 * payload
128 */
129 public String getBusinessPayloadId();
130
131 /**
132 * Sets the business payloadId associated with this
133 * message. This business payload message Id is typically
134 * used for tracking and correlating messages
135 * @param businessPayloadId The UUID associated with the
136 * ITK Message business payload
137 */
138 public void setBusinessPayloadId(String businessPayloadId);
139
140 /**
141 * Obtains the profileId associated with the ITKMessage.
142 * The profile Id represents the set of rules used to
143 * construct the message and provides a single String
144 * that aides with message/document version management as well
145 * as allowing message/document consumers to understand whether
146 * or not they are capable of handling the associated ITK Message
147 *
148 * @return The profile id (e.g. <code>nhs-en:profile:nonCodedCDADocument-v2-0</code>)
149 */
150 public String getProfileId();
151
152 /**
153 * Sets the profileId associated with the ITKMessage.
154 * The profile Id represents the set of rules used to
155 * construct the message and provides a single String
156 * that aides with message/document version management as well
157 * as allowing message/document consumers to understand whether
158 * or not they are capable of handling the associated ITK Message
159 *
160 * @param profileId The profile id (e.g. <code>nhs-en:profile:nonCodedCDADocument-v2-0</code>)
161 */
162 public void setProfileId(String profileId);
163
164 /**
165 * Obtains the tracking id associated with the ITKMessage
166 * when sending the message between two or more endpoints.
167 * The tracking id should not have meaning beyond the original
168 * ITK transmission and associated acknowledgements. In
169 * particular the trackingId is not expected to be an id directly
170 * represented in the business payload such as a CDA document
171 * instance id. Ids associated with the business payload are
172 * obtained via {@link #getBusinessPayloadId()}.<br/><br/>
173 * The primary purpose of the tracking Id is for operational
174 * reasons (i.e. allows entries in log file across different
175 * servers and nodes to be tied together) and for correlation
176 * of asynchronous acknowledgements such as ITK Infrastructure
177 * acknowledgements (see {@link ITKAckDetails#getTrackingRef()})
178 * and ITK Business Acknowledgements.
179 *
180 * @return a String with the UUID represent the tracking Id
181 */
182 public String getTrackingId();
183
184 /**
185 * Sets the tracking id associated with the ITKMessage
186 * prior to sending the message between two or more endpoints.
187 * The tracking id should not have meaning beyond the original
188 * ITK transmission and associated acknowledgements. In
189 * particular the trackingId is not expected to be an id directly
190 * represented in the business payload such as a CDA document
191 * instance id. Ids associated with the business payload are
192 * set via {@link #setBusinessPayloadId(String)}.<br/><br/>
193 * The primary purpose of the tracking Id is for operational
194 * reasons (i.e. allows entries in log file across different
195 * servers and nodes to be tied together) and for correlation
196 * of asynchronous acknowledgements such as ITK Infrastructure
197 * acknowledgements (see {@link ITKAckDetails#getTrackingRef()})
198 * and ITK Business Acknowledgements.
199 *
200 * @param trackingId a String UUID representing the tracking Id
201 * for this transmission. Note if the message is resent a new tracking
202 * Id should be created
203 */
204 public void setTrackingId(String trackingId);
205
206 /**
207 * Sets the {@link ITKTransportProperties} that are associated with the
208 * ITKMessage that was received by the service provider on the inbound
209 * leg in an asynchronous request/response invocation.<br/><br/>
210 *
211 * The <code>inboundITKTransportProperties</code> are not expected to
212 * be processed by the application layer, however where present
213 * <b>the application layer is responsible for attaching the
214 * <code>inboundITKTransportProperties</code> to any responses generated</b>
215 * such that these transport properties are available to the transport layers
216 * transmitting the response.<br/><br/>
217 *
218 * A typical use of this mechanism is for the propagation of the
219 * <code><wsa:replyTo/></code> URL such that it is available to the
220 * to the transport layers managing the "reply".<br/><br/>
221 *
222 * <b>Note</b> although this pattern adds some additional burden on the
223 * application layer it offers significant advantages over the alternative
224 * where the transport layer has to maintain state and correlate messages
225 * - potentially over several distributed nodes
226 *
227 * @param inboundITKTransportProperties The {@link ITKTransportProperties} that
228 * were obtained from the inbound message.
229 */
230 public void setInboundTransportProperties(ITKTransportProperties inboundITKTransportProperties);
231
232 /**
233 * Obtains the {@link ITKTransportProperties} that are associated with the
234 * ITKMessage that was received by the service provider on the inbound
235 * leg in an asynchronous request/response invocation.<br/><br/>
236 *
237 * The <code>inboundITKTransportProperties</code> are not expected to
238 * be processed by the application layer, however where present
239 * <b>the application layer is responsible for attaching the
240 * <code>inboundITKTransportProperties</code> to any responses generated</b>
241 * such that these transport properties are available to the transport layers
242 * transmitting the response.<br/><br/>
243 *
244 * A typical use of this mechanism is for the propagation of the
245 * <code><wsa:replyTo/></code> address such that it is available to the
246 * to the transport layers managing the "reply".<br/><br/>
247 *
248 * <b>Note</b> although this pattern adds some additional burden on the
249 * application layer it offers significant advantages over the alternative
250 * where the transport layer has to maintain state and correlate messages
251 * - potentially over several distributed nodes
252 *
253 * @return <code>inboundITKTransportProperties</code> - the {@link ITKTransportProperties} that
254 * were obtained from the inbound message.
255 */
256 public ITKTransportProperties getInboundTransportProperties();
257
258 /**
259 * Obtains the Map of the handling specifications associated with the
260 * {@link ITKMessage}.<br/><br/>
261 *
262 * Handling specifications provide an extensible
263 * mechanism for the message originator to attach special processing instructions
264 * with the message.
265 * The current ITK specifications provide two built-in handling specifications
266 * - one for requesting a business acknowledgement message
267 * ({@link #BUSINESS_ACK_HANDLING_SPECIFICATION_KEY}), and one to explicitly
268 * associated an interaction Id with the message
269 * ({@link #INTERACTION_HANDLING_SPECIFICATION_KEY}).
270 *
271 * @return The {@link Map} of all handling specifications associated
272 * with the message. For each entry in the Map contains both the key
273 * (e.g. <code>urn:nhs:itk:ns:201005:ackrequested</code>) and the
274 * associated value. If no handling specifications are associated
275 * with the message then an empty map is returned.
276 */
277 public Map<String, String> getHandlingSpecifications();
278
279 /**
280 *
281 * Allows the message originator to add a handling specification to the
282 * associated {@link ITKMessage}.<br/><br/>
283 *
284 * Handling specifications provide an extensible
285 * mechanism for the message originator to attach special processing instructions
286 * with the message.
287 * The current ITK specifications provide two built-in handling specifications
288 * - one for requesting a business acknowledgement message
289 * ({@link #BUSINESS_ACK_HANDLING_SPECIFICATION_KEY}), and one to explicitly
290 * associated an interaction Id with the message
291 * ({@link #INTERACTION_HANDLING_SPECIFICATION_KEY}).
292 *
293 * @param key The handling specification key - for instance
294 * {@link #BUSINESS_ACK_HANDLING_SPECIFICATION_KEY}
295 *
296 * @param value The appropriate <code>value</code> for the handling specification
297 */
298 public void addHandlingSpecification(String key, String value);
299
300 /**
301 * Convenience method that allows the value of the handling specification
302 * to be obtained directly.
303 *
304 * @param key The handling specification key - for instance {@link #BUSINESS_ACK_HANDLING_SPECIFICATION_KEY}
305 * @return The <code>value</code> associated with the provided key or <code>null</code> if the
306 * handling specification indicated by the key was not present
307 */
308 public String getHandlingSpecification(String key);
309
310 }