1 /*
2 * Copyright 2010 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.openehealth.ipf.commons.ihe.ws.correlation;
17
18 import org.openehealth.ipf.commons.ihe.ws.cxf.audit.WsAuditDataset;
19
20 /**
21 * Interface for message correlators in asynchronous
22 * Web Service-based eHealth transactions.
23 * @author Dmytro Rud
24 */
25 public interface AsynchronyCorrelator<AuditDatasetType extends WsAuditDataset> {
26
27 /**
28 * When the Web Service context of an outgoing request message contains
29 * <code>Boolean.TRUE</code> value in the property with this name,
30 * then correlation items of this request message will be stored
31 * in the configured asynchrony correlator instance, even when the
32 * WS-Addressing <tt><ReplyTo></tt> header is not set.
33 */
34 String FORCE_CORRELATION = AsynchronyCorrelator.class.getName() + ".FORCE";
35
36 /**
37 * Stores a service endpoint URI.
38 * @param messageId
39 * WS-Addressing message ID of the request.
40 * @param serviceEndpointUri
41 * URL of the endpoint the request is being sent to.
42 */
43 void storeServiceEndpointUri(String messageId, String serviceEndpointUri);
44
45 /**
46 * Stores a user-defined correlation key.
47 * @param messageId
48 * WS-Addressing message ID of the request.
49 * @param correlationKey
50 * correlation key provided by the user.
51 */
52 void storeCorrelationKey(String messageId, String correlationKey);
53
54 /**
55 * Stores audit dataset.
56 * @param messageId
57 * WS-Addressing message ID of the request.
58 * @param auditDataset
59 * audit dataset.
60 */
61 void storeAuditDataset(String messageId, WsAuditDataset auditDataset);
62
63 /**
64 * Returns the URI of the endpoint to which the message with the given
65 * ID has been sent, or <code>null</code> if the message is unknown.
66 */
67 String getServiceEndpointUri(String messageId);
68
69 /**
70 * Returns the user-defined correlation key for the message with the
71 * given ID, or <code>null</code> if the message is unknown or the
72 * user did not provided any correlation key.
73 */
74 String getCorrelationKey(String messageId);
75
76 /**
77 * Returns the audit dataset for the request message with the
78 * given ID, or <code>null</code> if the message is unknown.
79 */
80 AuditDatasetType getAuditDataset(String messageId);
81
82 /**
83 * Stores a set of alternative keys for the message with the given
84 * WS-Addressing ID. When the <RelatesTo> header of the incoming
85 * response does not contain a valid/a known message ID for correlation,
86 * the system will use transaction-specific mechanisms to extract
87 * additional keys from the message body and to perform the correlation
88 * of their basis.
89 * <p>
90 * The correlator must maintain bi-directional correspondence
91 * between the "primary" key (WS-Addressing message ID of the request)
92 * and the alternative keys. The uniqueness of the alternative keys
93 * should be provided, but cannot be guaranteed.
94 *
95 * @param messageId
96 * WS-Addressing message ID of the request.
97 * @param alternativeKeys
98 * alternative keys, should be not <code>null</code>.
99 */
100 void storeAlternativeKeys(String messageId, String... alternativeKeys);
101
102 /**
103 * Determines WS-Addressing message ID ("primary key")
104 * which corresponds to the given alternative key.
105 * @param alternativeKey
106 * alternative key.
107 * @return
108 * WS-Addressing message ID or <code>null</code> when not found.
109 */
110 String getMessageId(String alternativeKey);
111
112 /**
113 * Deletes information pieces about the message with the given ID.
114 * <p>
115 * This method is supposed to be called internally after the correlation
116 * of an asynchronous response has been completed; the user does not have
117 * to call it explicitly (but who knows...).
118 * @return
119 * <code>true</code> when there actually was something to delete,
120 * i.e. when the given ID was known; <code>false</code> otherwise.
121 */
122 boolean delete(String messageId);
123 }