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.consumer;
15
16 import com.xmlsolutions.annotation.Requirement;
17
18 import uk.nhs.interoperability.infrastructure.ITKMessagingException;
19 import uk.nhs.interoperability.payload.ITKMessage;
20
21 /**
22 * API contract for between the transport and application
23 * layers for a message/document consumer application. In this
24 * context the message/document consumer may be the receiver of
25 * a clinical correspondence message such as a discharge advice
26 * or it may be the service provider in a query/response pattern
27 * such as Spine Mini Services.<br/><br/>
28 *
29 * It is anticipated that clinical applications will either
30 * implement this interface directly - or use an an adaptor
31 * that is compliant with this interface
32 *
33 * @author Michael Odling-Smee
34 * @author Nicholas Jones
35 * @since version 0.1
36 */
37 public interface ITKMessageConsumer {
38
39
40 /**
41 * Call to process a request message where the application response is returned
42 * synchronously (in the same thread)
43 *
44 * @param request The itk request message to process. Examples might include an
45 * Spine Mini Services <code>getPatientDetailsByNHSNumberRequest-v1-0</code>
46 * message
47 *
48 * @return an <code>ITKMessage</code> representing the application/business response
49 * to the provided <code>request</code>. The response may represent business processing
50 * success or failure depending on the contents of the <code>request</code> and the
51 * implementation of the underlying service.
52 *
53 * @throws ITKMessagingException if there are any syntactic, semantic or more general
54 * application processing issues when processing the request or constructing the response.
55 * In this context the {@link ITKMessagingException} should not be used to represent
56 * business processing failures such as a query returned no results - in general the
57 * underlying messaging specifications support "error" business response to support
58 * these types of failure.
59 */
60 @Requirement(traceTo={"WS-PAT-01"})
61 public ITKMessage onSyncMessage(ITKMessage request) throws ITKMessagingException;
62
63 /**
64 * Call to process a request message where no application response is returned
65 * synchronously. This may be because no application response is expected, or
66 * because the resulting response will be sent back to the <code>request</code>
67 * originator asynchronously.
68 *
69 * @param request The itk request message to process. Examples might include an
70 * Spine Mini Services <code>nonCodedCDADocument-v2-0</code>
71 * message
72 *
73 * @throws ITKMessagingException if there are any syntactic, semantic or more general
74 * application processing issues when processing the request or constructing the response.
75 * In general it is recommended that full syntactic and as much business level validation
76 * as practical is performed against the <code>request</code> prior to the method returning
77 * such that faults can be raised and reported back via the underlying transport.
78 *
79 * In this context the {@link ITKMessagingException} should not be used to represent
80 * business processing failures such as a query returned no results - in general the
81 * underlying messaging specifications support "error" business response to support
82 * these types of failure.
83 */
84 @Requirement(traceTo={"WS-PAT-02"})
85 public void onMessage(ITKMessage request) throws ITKMessagingException;
86 }