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.payload;
15
16 import uk.nhs.interoperability.capabilities.DirectoryOfServices;
17 import uk.nhs.interoperability.infrastructure.ITKMessageProperties;
18 import uk.nhs.interoperability.infrastructure.ITKMessagingException;
19 import uk.nhs.interoperability.transport.ITKTransportRoute;
20
21 /**
22 * Interface representing the characteristics
23 * of an ITK message being transmitted via the
24 * ITK message transport and distribution layers (i.e. this API).
25 * <br/><br/>
26 *
27 * As well as providing a standard way of setting / obtaining
28 * the business payload (i.e. the business message itself) it
29 * also provides a standardised set of meta-data for the message
30 * too via the {@link ITKMessageProperties}. <br/><br/>
31 *
32 * <b>Note:</b> it is expected that business payload API developers will
33 * either provide classes that directly implement this interface or
34 * will provide suitable adaptor classes to enable the payload and
35 * transport distribution APIs to be seamlessly integrated.
36 *
37 * @author Michael Odling-Smee
38 * @author Nicholas Jones
39 * @since version 0.1
40 */
41 public interface ITKMessage {
42
43 /**
44 * Obtains the {@link ITKMessageProperties} associated with this
45 * message. These properties provide relevant addressing and meta-data
46 * about the message.
47 *
48 * @return the ITKMessageProperties associated with the message or
49 * <code>null</code> if no ITKMessageProprties have been set.
50 */
51 public ITKMessageProperties getMessageProperties();
52
53 /**
54 * Sets the {@link ITKMessageProperties} associated with this
55 * message. These properties provide relevant addressing and meta-data
56 * about the message.
57 *
58 * @param itkMessageProperties the ITKMessageProperties associated with the message.
59 */
60 public void setMessageProperties(ITKMessageProperties itkMessageProperties);
61
62 /**
63 * Sets the business payload portion of the message to be transmitted via
64 * the ITK transport and distribution infrastructure.<br/><br/>
65 *
66 * <b>Note:</b> those (ADT v2 pipe and hat) messages that ITK requires
67 * to be base64 encoded when being transmitted must not need to be pre-encoded - i.e.
68 * they should be supplied in plain text. It is the responsibility of the implementation
69 * to ensure that appropriate encoding/decoding is performed behind the scenes.<br/><br/>
70 *
71 * <b>Note: </b> for version 0.1 the signature of this method has been defined as a String
72 * to keep implementation simple. As a consequence implementations should ensure that payloads
73 * are provided as UTF-16 encoded strings.
74 *
75 * @param businessPayload A string representation of the business payload message
76 */
77 public void setBusinessPayload(String businessPayload);
78
79 /**
80 * Obtains the business payload portion of the message to be transmitted via
81 * the ITK transport and distribution infrastructure.<br/><br/>
82 *
83 * <b>Note:</b> those (ADT v2 pipe and hat) messages that ITK requires
84 * to be base64 encoded when being transmitted will not be encoded - i.e.
85 * they will be supplied in plain text. It is the responsibility of the implementation
86 * to ensure that appropriate encoding/decoding is performed behind the scenes.<br/><br/>
87 *
88 * @return for version 0.1 the return type of this method has been defined as a String
89 * to keep implementation simple. As a consequence the business payload will be returned as a
90 * UTF-16 encoded string
91 */
92 public String getBusinessPayload();
93
94 /**
95 * Obtains the full ITKMessage including any wrappers
96 *
97 * @return The full ITK message payload including wrappers.
98 * For ITKMessage instances that includes wrappers (for instance where the
99 * business payload has been wrapped in a distribution envelope or SOAP
100 * envelope) this method returns the full message. Otherwise the method
101 * returns an identical String to {@link #getBusinessPayload()}
102 *
103 * @throws ITKMessagingException If there is an error serialising the
104 * full ITKMessage
105 */
106 public String getFullPayload() throws ITKMessagingException;
107
108 /**
109 * Obtains any pre-resolved {@link ITKTransportRoute} associated
110 * with this ITKMessage.<br/><br/>
111 *
112 * A pre-resolved transport route might be present if this
113 * ITKMessage instance is a response where the return address
114 * is already known (e.g. via a SOAP <code><wsa:ReplyTo/></code>
115 * address provided in the request), or because the application layer
116 * has already resolved the {@link ITKTransportRoute} for the target
117 * destination.
118 *
119 * @return a pre-resolved {@link ITKTransportRoute} if present, or
120 * <code>null</code> otherwise. If no pre-resolved transport route is
121 * present it is the responsibility of the implementation to determine
122 * the {@link ITKTransportRoute} via the
123 * {@link DirectoryOfServices#resolveDestination(String, uk.nhs.interoperability.infrastructure.ITKAddress)}
124 * method call
125 */
126 public ITKTransportRoute getPreresolvedRoute();
127
128 /**
129 * Indicates whether this ITKMessage instance is
130 * in response to a request message such as a query
131 *
132 * @return <code>true</code> if this message is a
133 * response, <code>false</code> otherwise.
134 */
135 public boolean isResponse();
136
137 }