Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
Grounding |
|
| 0.0;0 |
1 | /* | |
2 | wsmo4j - a WSMO API and Reference Implementation | |
3 | ||
4 | Copyright (c) 2004-2007, Ontotext Lab. / SIRMA | |
5 | ||
6 | This library is free software; you can redistribute it and/or modify it under | |
7 | the terms of the GNU Lesser General Public License as published by the Free | |
8 | Software Foundation; either version 2.1 of the License, or (at your option) | |
9 | any later version. | |
10 | This library is distributed in the hope that it will be useful, but WITHOUT | |
11 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS | |
12 | FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more | |
13 | details. | |
14 | You should have received a copy of the GNU Lesser General Public License along | |
15 | with this library; if not, write to the Free Software Foundation, Inc., | |
16 | 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
17 | */ | |
18 | ||
19 | package org.wsmo.grounding.sawsdl; | |
20 | ||
21 | import java.net.URI; | |
22 | import java.util.List; | |
23 | ||
24 | import javax.xml.namespace.QName; | |
25 | ||
26 | import org.wsmo.common.IRI; | |
27 | import org.wsmo.common.exception.InvalidModelException; | |
28 | import org.wsmo.grounding.sawsdl.SchemaMapping; | |
29 | ||
30 | import org.wsmo.grounding.sawsdl.events.GroundingChangeEventListener; | |
31 | ||
32 | /** | |
33 | * A grounding object containing all SAWSDL annotations of a single WSDL document. | |
34 | * Each model annotation is represented by a single ModelRef object which can not be | |
35 | * shared with other groundings. | |
36 | * | |
37 | * The Grounding API offers a set of factory methods for creating the various types of | |
38 | * semantic model references. | |
39 | * | |
40 | */ | |
41 | public interface Grounding { | |
42 | ||
43 | /** | |
44 | * Creates and includes in this grounding object a single model reference from an | |
45 | * XML Schema attribute to a concept in a semantic model. | |
46 | * | |
47 | * @param attribute the name of the attribute to be annotated | |
48 | * @param target the semantic model id reference | |
49 | * @return A new attribute model reference | |
50 | * @throws InvalidModelException if the supplied attribute name is not defined in the | |
51 | * current WSDL document | |
52 | */ | |
53 | public AttributeModelRef createAttributeModelRef(QName attribute, IRI target) | |
54 | throws InvalidModelException; | |
55 | ||
56 | /** | |
57 | * Creates and includes in this grounding object a single model reference from an | |
58 | * XML Schema complexType to a concept in a semantic model. | |
59 | * | |
60 | * @param type the name of the complexType to be annotated | |
61 | * @param target the semantic model id reference | |
62 | * @return A new complexType model reference | |
63 | * @throws InvalidModelException if the supplied complexType name is not defined in the | |
64 | * current WSDL document | |
65 | */ | |
66 | public ComplexTypeModelRef createComplexTypeModelRef(QName type, IRI target) | |
67 | throws InvalidModelException; | |
68 | ||
69 | /** | |
70 | * Creates and includes in this grounding object a single model reference from an | |
71 | * XML Schema simpleType to a concept in a semantic model. | |
72 | * | |
73 | * @param type the name of the simpleType to be annotated | |
74 | * @param target the semantic model id reference | |
75 | * @return A new simpleType model reference | |
76 | * @throws InvalidModelException if the supplied simpleType name is not defined in the | |
77 | * current WSDL document | |
78 | */ | |
79 | public SimpleTypeModelRef createSimpleTypeModelRef(QName type, IRI target) | |
80 | throws InvalidModelException; | |
81 | ||
82 | /** | |
83 | * Creates and includes in this grounding object a single model reference from an | |
84 | * XML Schema element to a concept in a semantic model. | |
85 | * | |
86 | * @param element the name of the element to be annotated | |
87 | * @param target the semantic model id reference | |
88 | * @return A new element model reference | |
89 | * @throws InvalidModelException if the supplied element name is not defined in the | |
90 | * current WSDL document | |
91 | */ | |
92 | public ElementModelRef createElementModelRef(QName element, IRI target) | |
93 | throws InvalidModelException; | |
94 | ||
95 | /** | |
96 | * Creates and includes in this grounding object a single model reference from a | |
97 | * WSDL interface to a concept in a semantic model. This reference plays role of a | |
98 | * classification property. | |
99 | * | |
100 | * @param iface the name of the interface to be annotated | |
101 | * @param target the semantic model id reference | |
102 | * @return A new interface category reference | |
103 | * @throws InvalidModelException if the supplied interface name is not defined in the | |
104 | * current WSDL document | |
105 | */ | |
106 | public InterfaceCategory createInterfaceCategory(QName iface, IRI target) | |
107 | throws InvalidModelException; | |
108 | ||
109 | /** | |
110 | * Creates and includes in this grounding object a single model reference from a | |
111 | * WSDL operation to a concept in a semantic model. | |
112 | * | |
113 | * @param operation the name of the operation to be annotated | |
114 | * @param target the semantic model id reference | |
115 | * @return A new operation model reference | |
116 | * @throws InvalidModelException if the supplied operation name is not defined in the | |
117 | * current WSDL document | |
118 | */ | |
119 | public OperationModelRef createOperationModelRef(QName operation, IRI target) | |
120 | throws InvalidModelException; | |
121 | ||
122 | /** | |
123 | * Creates and includes in this grounding object a single model reference from a | |
124 | * WSDL operation fault to a concept in a semantic model. | |
125 | * | |
126 | * @param fault the name of the operation fault to be annotated | |
127 | * @param target the semantic model id reference | |
128 | * @return A new fault model reference | |
129 | * @throws InvalidModelException if the supplied operation fault name is not defined in the | |
130 | * current WSDL document | |
131 | */ | |
132 | public FaultModelRef createFaultModelRef(QName fault, IRI target) | |
133 | throws InvalidModelException; | |
134 | ||
135 | /** | |
136 | * Removes a single model reference from this grounding object. | |
137 | * | |
138 | * @param reference the model reference to be removed | |
139 | * @throws InvalidModelException if the supplied reference does not belong to this grounding | |
140 | * object | |
141 | */ | |
142 | public void removeModelRef(ModelRef reference) | |
143 | throws InvalidModelException;; | |
144 | ||
145 | /** | |
146 | * Lists all (regardless of specific type) model references in this grounding object. | |
147 | * Only the declared model references are listed, not the propagated ones. | |
148 | * | |
149 | * @return A list of model reference objects | |
150 | */ | |
151 | public List<ModelRef> listDeclaredModelRefs(); | |
152 | ||
153 | /** | |
154 | * Lists all model references for the specified WSDL or XML Schema entity in this grounding | |
155 | * object. | |
156 | * Only the declared model references are listed, not the propagated ones. | |
157 | * @param source the name of the WSDL or XML Schema entity | |
158 | * @return A list of model reference objects | |
159 | * @throws InvalidModelException if the supplied entity name is not defined in the | |
160 | * current WSDL document | |
161 | */ | |
162 | public List<ModelRef> listDeclaredModelRefs(QName source) throws InvalidModelException; | |
163 | ||
164 | /** | |
165 | * Lists all (regardless of specific type) model references in this grounding object, including the propagated ones. | |
166 | * | |
167 | * @return A list of model reference objects | |
168 | * @throws InvalidModelException if the model is somehow inconsistent | |
169 | */ | |
170 | public List<ModelRef> listModelRefs() throws InvalidModelException; | |
171 | ||
172 | /** | |
173 | * Lists all model references for the specified WSDL or XML Schema entity in this grounding | |
174 | * object, including the propagated ones. | |
175 | * @param source the name of the WSDL or XML Schema entity | |
176 | * @return A list of model reference objects | |
177 | * @throws InvalidModelException if the supplied entity name is not defined in the | |
178 | * current WSDL document | |
179 | */ | |
180 | public List<ModelRef> listModelRefs(QName source) throws InvalidModelException; | |
181 | ||
182 | /** | |
183 | * Creates and includes in this grounding object a mapping to a transformation schema responsible | |
184 | * for the lifting of the source entity to the corresponding semantic model entity. | |
185 | * | |
186 | * @param source the name of the XML Schema entity | |
187 | * @param schemaRef the identifier of the lifting schema | |
188 | * @return A new lifting schema mapping | |
189 | * @throws InvalidModelException if the supplied entity name is not defined in the | |
190 | * current WSDL document | |
191 | */ | |
192 | public LiftingSchemaMapping createLiftingSchemaMapping(QName source, URI schemaRef) | |
193 | throws InvalidModelException; | |
194 | ||
195 | /** | |
196 | * Creates and includes in this grounding object a mapping to a transformation schema responsible | |
197 | * for the lowering to the source entity from the corresponding semantic model entity. | |
198 | * | |
199 | * @param source the name of the XML Schema entity | |
200 | * @param schemaRef the identifier of the lowering schema | |
201 | * @return A new lowering schema mapping | |
202 | * @throws InvalidModelException if the supplied entity name is not defined in the | |
203 | * current WSDL document | |
204 | */ | |
205 | public LoweringSchemaMapping createLoweringSchemaMapping(QName source, URI schemaRef) | |
206 | throws InvalidModelException; | |
207 | ||
208 | /** | |
209 | * Removes a single lifting or lowering schema mapping from this grounding object. | |
210 | * @param mapping the mapping object to be removed | |
211 | * @throws InvalidModelException if the mapping object does not belong to this grounding | |
212 | * object | |
213 | */ | |
214 | public void removeSchemaMapping(SchemaMapping mapping) | |
215 | throws InvalidModelException; | |
216 | ||
217 | /** | |
218 | * Lists all lifting and lowering schema mappings of this grounding object. | |
219 | * Only the declared schema mappings are listed, not the propagated ones. | |
220 | * @return A list of schema mappings | |
221 | */ | |
222 | public List<SchemaMapping> listDeclaredSchemaMappings(); | |
223 | ||
224 | /** | |
225 | * Lists all lifting and lowering schema mappings for the source entity belonging to this | |
226 | * grounding object. | |
227 | * Only the declared schema mappings are listed, not the propagated ones. | |
228 | * @return A list of schema mappings | |
229 | */ | |
230 | public List<SchemaMapping> listDeclaredSchemaMappings(QName source) throws InvalidModelException; | |
231 | ||
232 | /** | |
233 | * Lists all lifting and lowering schema mappings of this grounding object, including the propagated ones. | |
234 | * @return A list of schema mappings | |
235 | * @throws InvalidModelException if the model is somehow inconsistent | |
236 | */ | |
237 | public List<SchemaMapping> listSchemaMappings() throws InvalidModelException; | |
238 | ||
239 | /** | |
240 | * Lists all lifting and lowering schema mappings for the source entity belonging to this | |
241 | * grounding object, including the propagated ones. | |
242 | * @return A list of schema mappings | |
243 | */ | |
244 | public List<SchemaMapping> listSchemaMappings(QName source) throws InvalidModelException; | |
245 | ||
246 | /** | |
247 | * Registers a grounding change listener to be notified when new model references and | |
248 | * schema mappings are created or removed from this grounding object. | |
249 | * @param listener | |
250 | */ | |
251 | public void addGroundingChangeListener(GroundingChangeEventListener listener); | |
252 | ||
253 | /** | |
254 | * Unregisters a grounding change listener. | |
255 | * @param listener | |
256 | */ | |
257 | public void removeGroundingChangeListener(GroundingChangeEventListener listener); | |
258 | ||
259 | } | |
260 | ||
261 | /* | |
262 | * $Log$ | |
263 | * Revision 1.6 2007/06/18 15:30:51 alex_simov | |
264 | * annotation propagation added (on behalf of Jacek) | |
265 | * | |
266 | * Revision 1.5 2007/04/27 17:46:31 alex_simov | |
267 | * javadoc added | |
268 | * | |
269 | * Revision 1.4 2007/04/27 13:34:07 alex_simov | |
270 | * bugfix | |
271 | * | |
272 | * Revision 1.3 2007/04/26 15:47:13 alex_simov | |
273 | * methods might throw InvalidModelExceptions | |
274 | * | |
275 | * Revision 1.2 2007/04/24 15:32:45 alex_simov | |
276 | * imports fix | |
277 | * | |
278 | * Revision 1.1 2007/04/24 14:09:44 alex_simov | |
279 | * new SA-WSDL api | |
280 | * | |
281 | */ |