View Javadoc

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  import uk.nhs.interoperability.consumer.ITKMessageConsumer;
17  import uk.nhs.interoperability.infrastructure.ITKMessageProperties;
18  import uk.nhs.interoperability.infrastructure.ITKMessagingException;
19  import uk.nhs.interoperability.payload.ITKMessage;
20  
21  import com.xmlsolutions.annotation.Requirement;
22  
23  /**
24   * Interface that represents the application entry point for sending ITK messages to a remote
25   * Destination. The interface provides both synchronous and asynchronous operations where
26   * <quote>synchronous</quote> and <quote>asynchronous</quote> represent the perspective of the
27   * the application rather than necessarily the one or more underlying transport hops.
28   * 
29   * @see ITKMessageConsumer
30   * @see ITKCallbackHandler
31   * 
32   * @author Michael Odling-Smee
33   * @author Nicholas Jones
34   * @since version 0.1
35   * 
36   */
37  public interface ITKMessageSender {
38  
39  	/**
40  	 * Operation that allows a business payload to be sent to the
41  	 * destination service/system with no response expected (a.k.a. "fire and forget").
42  	 * 
43  	 * @param request    This is the business payload being sent which 
44  	 * must include an appropriately populated {@link ITKMessageProperties}. 
45  	 *  
46  	 * @exception ITKMessagingException If the addressing and message meta-data
47  	 * properties are not populated, the {@link ITKMessage#getFullPayload()} is null/blank or if there is a
48  	 * technical exception invoking the service provider,
49  	 * first node in the distribution (for instance if a SOAP 
50  	 * fault is returned by the service provider) 
51  	 */
52  	public void send(ITKMessage request) throws ITKMessagingException;
53  
54  	/**
55  	 * Operation that allows a business payload to be sent synchronously to the
56  	 * destination service/system returning the appropriate business response.
57  	 * 
58  	 * @param request    This is the business payload being sent which 
59  	 * must include an appropriately populated {@link ITKMessageProperties}.  
60  	 * 
61  	 * @exception ITKMessagingException If the addressing and message meta-data
62  	 * properties are not populated, the {@link ITKMessage#getFullPayload()} is null/blank or if there is a
63  	 * technical exception invoking the service provider (for instance if a SOAP
64  	 * fault is returned by the service provider) 
65  	 */
66  	@Requirement(traceTo={"WS-PAT-01"})
67  	public ITKMessage sendSync(ITKMessage request) throws ITKMessagingException;
68  
69  	/**
70  	 * Operation that allows a business payload to be sent asynchronously to the
71  	 * destination service/system.
72  	 * No object is returned but transport/protocol errors may be thrown
73  	 * The response will be handled by a separate process {@link ITKCallbackHandler#onMessage(ITKMessage)}
74  	 * 
75  	 * @param businessPayload    This is the business payload being sent which 
76  	 * must include an appropriately populated {@link ITKMessageProperties}.  
77  	 * 
78  	 * @exception ITKMessagingException If the addressing and message meta-data
79  	 * properties are not populated, the  {@link ITKMessage#getFullPayload()} is
80  	 * null/blank or if there is a technical exception invoking the service provider
81  	 * such as underlying transport errors or timeouts (for instance if a SOAP fault
82  	 * is returned synchronously by the service provider) 
83  	 */
84  	@Requirement(traceTo={"WS-PAT-02"})
85  	public void sendAsync(ITKMessage businessPayload) throws ITKMessagingException;
86  
87  
88  }