1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
|
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.tuscany.sca.interfacedef;
import org.apache.tuscany.sca.interfacedef.util.Audit;
/**
* The InterfaceContractMapper is responsible to match interfaces
*
* @version $Rev$ $Date$
* @tuscany.spi.extension.asclient
*/
public interface InterfaceContractMapper {
/**
* @param source The source interface contract
* @param target The target interface contract
* @param compatibility The compatibility style
* @param ignoreCallback
* @param silent
* @return
* @throws IncompatibleInterfaceContractException
*/
boolean checkCompatibility(InterfaceContract source,
InterfaceContract target,
Compatibility compatibility,
boolean ignoreCallback,
boolean silent) throws IncompatibleInterfaceContractException;
/**
* @param source The source interface contract
* @param target The target interface contract
* @param compatibility The compatibility style
* @param ignoreCallback
* @param silent
* @return
* @throws IncompatibleInterfaceContractException
* this interface is intended to incrementally replace the variant without the audit trail
* the presence of both interfaces implies a state of partial development
*/
boolean checkCompatibility(InterfaceContract source,
InterfaceContract target,
Compatibility compatibility,
boolean ignoreCallback,
boolean silent,
Audit audit) throws IncompatibleInterfaceContractException;
/**
* Test if the source data type is compatible with the target data type. The
* compatibility is defined as follows.
* <ul>
* <li>source's logical type is either the same or subtype of the target's
* logical type
* </ul>
* For example, if the source type is a SDO Customer and the target type is
* a JAXB Customer and both Customer are generated from the same XSD type.
*
* @param source The source data type
* @param target The target data type
* @param passByValue A flag to indicate how the compatibility is checked
* <ul>
* <li>true: Check the two types as compatible "by-value" (can be copied)
* <li>false: Check the two types as compatible "by-reference" (can be assigned)
* </ul>
* @return true if the source data type is the same or subtype of the target data type
*/
boolean isCompatible(DataType<?> source, DataType<?> target, boolean passByValue);
/**
* Check if source operation is compatible with the target operation. A source operation is
* compatible with the target operation means the following:
*
* <ol>
* <li>compatibility for the two operations is defined as compatibility
* of the signature, i.e., the operation name, the input types, and the output types are the same
*
* <li>the order of the input and output types of the source operation is the same as the order of
* the input and output types for the corresponding target operation
* <li>the set of Faults and Exceptions expected by the source operation is the same as or is
* a SUPERSET of the set of Faults and Exceptions specified by the corresponding target operation
* </ol>
*
* Simply speaking, any request from the source operation can be processed by the target operation and
* the normal response or fault/exception from the target operation can be handled by the source operation.
*
* Please note this compatibility check is NOT symmetric. But the following should be guaranteed:
* <ul>
* <li>(source, target, SUB) == (target, source, SUPER)
* <li>(source, target, MUTUAL) == (source, target, SUB) && (target, source, SUB) == (source, target, SUPER) && (source, target, SUPER)
*
* @param source The source operation
* @param target The target operation
* @param compatibilityType The type of compatibility
* @return true if the source operation is compatible with the target
* operation
*/
boolean isCompatible(Operation source, Operation target, Compatibility compatibilityType);
boolean isCompatibleByReference(Operation source, Operation target, Compatibility compatibilityType);
boolean isCompatibleByValue(Operation source, Operation target, Compatibility compatibilityType);
/**
* Similar to isCompatibleByValue with the one difference that isCompatibleByValue will "unwrap" a wrapperStyle
* operation to compare it to a non-wrapperStyle operation. One the other hand, isCompatibleWithoutUnwrapByValue
* will return false, i.e. not-compatible, if the source and target operation do not have the same wrapperStyle.
*
*
* @param source The source operation
* @param target The target operation
* @param compatibilityType The type of compatibility
* @return true if the source operation is compatible with the target
* operation
*/
boolean isCompatibleWithoutUnwrapByValue(Operation source, Operation target, Compatibility compatibilityType);
/**
* An interface A is a Compatible Subset of a second interface B if and only if all of points 1 through 6
* in the following list apply:
* <ol>
* <li>interfaces A and B are either both remotable or else both local
* <li>the set of operations in interface A is the same as or is a subset of the set of operations in
* interface B
* <li>compatibility for individual operations of the interfaces A and B is defined as compatibility
* of the signature, i.e., the operation name, the input types, and the output types are the same
* <li>the order of the input and output types for each operation in interface A is the same as the
* order of the input and output types for the corresponding operation in interface B
* <li>the set of Faults and Exceptions expected by each operation in interface A is the same as or is
* a superset of the set of Faults and Exceptions specified by the corresponding operation in interface B
* <li>for checking the compatibility of 2 remotable interfaces which are in different interface
* languages, both are mapped to WSDL 1.1 (if not already WSDL 1.1) and compatibility checking is done
* between the WSDL 1.1 mapped interfaces.<br>
* For checking the compatibility of 2 local interfaces which are in different interface languages, the
* method of checking compatibility is defined by the specifications which define those interface types,
* which must define mapping rules for the 2 interface types concerned.
*
* </ol>
*
* <b>The callback interfaces are not considered her.</b>
*
* @param source The source interface
* @param target The target interface
* @return true if the source interface is a compatible subset of the target interface
*/
boolean isCompatibleSubset(Interface source, Interface target);
/**
* An interface A is a Compatible Subset of a second interface B if and only if all of points 1 through 7
* in the following list apply:
* <ol>
* <li>interfaces A and B are either both remotable or else both local
* <li>the set of operations in interface A is the same as or is a subset of the set of operations in
* interface B
* <li>compatibility for individual operations of the interfaces A and B is defined as compatibility
* of the signature, i.e., the operation name, the input types, and the output types are the same
* <li>the order of the input and output types for each operation in interface A is the same as the
* order of the input and output types for the corresponding operation in interface B
* <li>the set of Faults and Exceptions expected by each operation in interface A is the same as or is
* a superset of the set of Faults and Exceptions specified by the corresponding operation in interface B
* <li>for checking the compatibility of 2 remotable interfaces which are in different interface
* languages, both are mapped to WSDL 1.1 (if not already WSDL 1.1) and compatibility checking is done
* between the WSDL 1.1 mapped interfaces.<br>
* For checking the compatibility of 2 local interfaces which are in different interface languages, the
* method of checking compatibility is defined by the specifications which define those interface types,
* which must define mapping rules for the 2 interface types concerned.
* <li>if either interface A or interface B declares a callback interface then both interface
* A and interface B declare callback interfaces and the callback interface declared on interface B is a
* compatible subset of the callback interface declared on interface A, according to points 1 through 6
* above
* </ol>
*
* @param source The source interface contract
* @param target The target interface contract
* @return true if the source interface contract is a compatible subset of the target interface contract
*/
boolean isCompatibleSubset(InterfaceContract source, InterfaceContract target);
/*
* the variant of isCompatibleSubset with the audit parameter is intended to supersed the other
* -- the presence of both indicates a partial development state
*/
boolean isCompatibleSubset(InterfaceContract source, InterfaceContract target, Audit audit);
/**
* Check that two interfaces are mutually compatible. The interfaces are mutually compatible if the two
* interfaces have the same set of operations, with each operation having the same signature (name, input
* types, output types and fault/exception types).
*
* @param source an interface
* @param target a second interface
* @return true if the two interfaces are mutually compatible, otherwise return false
*/
public boolean isMutuallyCompatible(Interface source, Interface target);
/**
* An interface A is Compatible with a second interface B if and only if all of points 1 through 7 in the
* following list apply:<p>
* <ol>
* <li>interfaces A and B are either both remotable or else both local
* <li>the set of operations in interface A is the same as the set of operations in interface B
* <li>compatibility for individual operations of the interfaces A and B is defined as compatibility
* of the signature, i.e., the operation name, the input types, and the output types are the same
* <li>the order of the input and output types for each operation in interface A is the same as the
* order of the input and output types for the corresponding operation in interface B
* <li>the set of Faults and Exceptions expected by each operation in interface A is the
* same as the set of Faults and Exceptions specified by the corresponding operation in interface B
* <li>for checking the compatibility of 2 remotable interfaces which are in different interface
* languages, both are mapped to WSDL 1.1 (if not already WSDL 1.1) and compatibility checking is done
* between the WSDL 1.1 mapped interfaces.
* <br>For checking the compatibility of 2 local interfaces which are in different interface languages,
* the method of checking compatibility is defined by the specifications which define those interface types,
* which must define mapping rules for the 2 interface types concerned.
* <li>if either interface A or interface B declares a callback interface then both interface
* A and interface B declare callback interfaces and the callback interface declared on interface A is
* compatible with the callback interface declared on interface B, according to points 1 through 6 above
*
* @param source - the source interface contract
* @param target - the target interface contract
* @return true if the source and target interface contracts are mutually compatible
*/
boolean isMutuallyCompatible(InterfaceContract source, InterfaceContract target);
/**
* Map the source operation to a compatible operation in the target interface
*
* @param target The target interface
* @param source The source operation
* @return A compatible operation if the target interface is compatible superset of the source interface
*/
Operation map(Interface target, Operation source);
}
|
