View Javadoc

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