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 */