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.source;
15
16
17 import uk.nhs.interoperability.infrastructure.ITKAckDetails;
18 import uk.nhs.interoperability.payload.ITKMessage;
19
20 import com.xmlsolutions.annotation.Requirement;
21
22 /**
23 * Interface defining the application responsibilities
24 * for managing asynchronous invocation responses - including
25 * standard business responses (e.g. query responses), business
26 * acknowledgements and infrastructure acknowledgements and
27 * infrastructure negative acknowledgements
28 *
29 * @author Michael Odling-Smee
30 * @author Nicholas Jones
31 * @since 0.1
32 *
33 */
34 public interface ITKCallbackHandler {
35
36 /**
37 * Allows the transport and distribution infrastructure
38 * to pass back an asynchronous response received in
39 * response to an asynchronous request.<br/><br/>
40 *
41 * The response message may be a generic ITK Business
42 * Acknowledgement (for instance as a result of a <code>sendCDA</code>
43 * invocation) or a specific business response associated
44 * with the request message.<br/><br/>
45 *
46 * <b>Note: </b> It is the responsibility of the application to maintain
47 * state and do the necessary correlation of this message against the original
48 * request to complete the transaction.
49 *
50 * @param response The {@link ITKMessage} representing the response
51 */
52 @Requirement(traceTo={"WS-PAT-02"})
53 public abstract void onMessage(ITKMessage response);
54
55 /**
56 * Method invoked by the transport and distribution layer
57 * upon receipt of a positive infrastructure acknowledgement (Ack).<br/><br/>
58 *
59 * Application components are not required to provide any functionality
60 * that is triggered by this acknowledgement however it is anticipated
61 * that this could be used to implement "delivery receipt" functionality.
62 *
63 * @param ack The (positive) acknowledgement. This can be correlated
64 * back to the request via the {@link ITKAckDetails#getTrackingRef()}
65 * method. Note correlation is an application layer responsibility.
66 */
67 @Requirement(traceTo={"WS-PAT-02"})
68 public abstract void onAck(ITKAckDetails ack);
69
70 /**
71 * Method invoked by the transport and distribution layer
72 * upon receipt of a negative infrastructure acknowledgement (Nack).<br/><br/>
73 *
74 * Application components are not required to provide any functionality
75 * that is triggered by this acknowledgement however it is anticipated
76 * that this could be used to implement "delivery failure" functionality.
77 *
78 * @param ack The (negative) acknowledgement. This can be correlated
79 * back to the request via the {@link ITKAckDetails#getTrackingRef()}
80 * method. Note correlation is an application layer responsibility. Details
81 * of the error associated with the "delivery failure" can be retrieved via
82 * the {@link ITKAckDetails#getNackError()} method.
83 */
84 @Requirement(traceTo={"WS-PAT-02"})
85 public abstract void onNack(ITKAckDetails ack);
86
87 }