1 /*
2 wsmo4j - a WSMO API and Reference Implementation
3
4 Copyright (c) 2005, University of Innsbruck, Austria
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 package org.wsmo.factory;
19
20
21 import java.util.*;
22
23 import org.omwg.logicalexpression.*;
24 import org.omwg.logicalexpression.terms.*;
25 import org.omwg.ontology.*;
26 import org.wsmo.common.*;
27 import org.wsmo.wsml.*;
28
29
30 /**
31 * This interface represents a logical expression factory
32 * it extends the generic logical expression factory by providing
33 * methods for the creation of an object model
34 *
35 * @author DERI Innsbruck, reto.krummenacher@deri.org
36 * @version $Revision: 1946 $ $Date: 2007-04-02 15:13:28 +0300 (Mon, 02 Apr 2007) $
37 * @see org.wsmo.factory.LogicalExpressionFactory
38 */
39 public interface LogicalExpressionFactory {
40
41 public static final String LEFACTORY_WSMO_FACTORY = "wsmo_factory";
42
43 public static final String LEFACTORY_DATA_FACTORY = "data_factory";
44
45 /**
46 * Creates a LogicalExpression object from string.
47 * @param expr the string representation of the logical expression
48 * @return The newly created LogicalExpression object.
49 */
50 LogicalExpression createLogicalExpression(String expr)
51 throws ParserException;
52
53 /**
54 * Creates a Logical Expression object from a string given a particular
55 * namespace context of a TopEntity
56 * @param expr the string representation of the logical expression
57 * @param nsHolder some Top entity that contains the namespace
58 * context (e.g.default Namespace)
59 * @return The newly created LogicalExpression object.
60 */
61 LogicalExpression createLogicalExpression(String expr, TopEntity nsHolder)
62 throws ParserException;
63
64 /**
65 * creates a negation (e.g. "not a")
66 * @param expr the expression that is affected by the operator
67 * @return negation
68 * @throws IllegalArgumentException in case the logical expression contains a nested CONSTRAINT
69 */
70 Negation createNegation(LogicalExpression expr)
71 throws IllegalArgumentException;
72
73 /**
74 * creates a naf (e.g. "naf a")
75 * @param expr the expression that is affected by the operator
76 * @return naf
77 * @throws IllegalArgumentException in case the logical expression contains a nested CONSTRAINT
78 */
79 NegationAsFailure createNegationAsFailure(LogicalExpression expr)
80 throws IllegalArgumentException;
81
82 /**
83 * creates a constraint
84 * @param expr the expression that is affected by the operator
85 * @return constraint
86 * @throws IllegalArgumentException in case the logical expression contains a nested CONSTRAINT
87 */
88 Constraint createConstraint(LogicalExpression expr)
89 throws IllegalArgumentException;
90
91 /**
92 * Creates a conjunction (e.g. "a and b")
93 *
94 * @param exprLeft the left expression that is conjunctively connected
95 * @param exprRight the right expression that is conjunctively connected
96 * @return conjunction
97 * @throws IllegalArgumentException
98 * <p>in case one of the two logical expressions is null
99 * <p>in case one of the two logical expressions contains a nested CONSTRAINT</p>
100 */
101 Conjunction createConjunction(LogicalExpression exprLeft, LogicalExpression exprRight)
102 throws IllegalArgumentException;
103
104 /**
105 * Creates a disjunction (e.g. "a or b").
106 *
107 * @param exprLeft the left expression that is connected
108 * @param exprRight the right expression that is connected
109 * @return conjunction
110 * @throws IllegalArgumentException
111 * <p>in case one of the two logical expressions is null
112 * <p>in case one of the two logical expressions contains a nested CONSTRAINT</p>
113 */
114 Disjunction createDisjunction(LogicalExpression exprLeft, LogicalExpression exprRight)
115 throws IllegalArgumentException;
116
117 /**
118 * Creates a Implication (e.g. "a implies b").
119 *
120 * @param exprLeft the left expression that is connected
121 * @param exprRight the right expression that is connected
122 * @return Implication
123 * @throws IllegalArgumentException
124 * <p>in case one of the two logical expressions is null
125 * <p>in case one of the two logical expressions contains a nested CONSTRAINT</p>
126 */
127 Implication createImplication(LogicalExpression exprLeft, LogicalExpression exprRight)
128 throws IllegalArgumentException;
129
130 /**
131 * Creates a Equivalence implication (e.g. "a equivalent b").
132 *
133 * @param exprLeft the left expression that is connected
134 * @param exprRight the right expression that is connected
135 * @return Implication
136 * @throws IllegalArgumentException
137 * <p>in case one of the two logical expressions is null
138 * <p>in case one of the two logical expressions contains a nested CONSTRAINT</p>
139 */
140 Equivalence createEquivalence(LogicalExpression exprLeft, LogicalExpression exprRight)
141 throws IllegalArgumentException;
142
143 /**
144 * Creates a LogicProgrammingRule (e.g. "a :- b").
145 *
146 * @param exprLeft the left expression that is connected
147 * @param exprRight the right expression that is connected
148 * @return LogicProgrammingRule
149 * @throws IllegalArgumentException
150 * <p>in case one of the two logical expressions is null
151 * <p>in case one of the two logical expressions contains a nested CONSTRAINT</p>
152 */
153 LogicProgrammingRule createLogicProgrammingRule(LogicalExpression exprLeft, LogicalExpression exprRight)
154 throws IllegalArgumentException;
155
156 /**
157 * Creates a InverseImplication (e.g. "a impliedBy b").
158 *
159 * @param exprLeft the left expression that is connected
160 * @param exprRight the right expression that is connected
161 * @return LogicProgrammingRule
162 * @throws InverseImplication
163 * <p>in case one of the two logical expressions is null
164 * <p>in case one of the two logical expressions contains a nested CONSTRAINT</p>
165 */
166 InverseImplication createInverseImplication(LogicalExpression exprLeft, LogicalExpression exprRight)
167 throws IllegalArgumentException;
168
169 /**
170 * creates a universally quantified expression (e.g. "forall {?a,?b} (?a memberOf ?b)")
171 * @param variables Set of variables that are quantified (e.g. [?a, ?b])
172 * @param expr the expression that is quantified
173 * @return a quantified expression
174 * @throws IllegalArgumentException
175 * <p>in case the logical expression contains a nested CONSTRAINT</p>
176 * <p>in case the Set of variables is null</p>
177 * <p>in case the arguments of the list aren't all of Type Variable</p>
178 */
179 UniversalQuantification createUniversalQuantification(Set <Variable> variables, LogicalExpression expr)
180 throws IllegalArgumentException;
181
182 /**
183 * creates a universally quantified expression (e.g. "forall ?a (?a memberOf A)")
184 * @param variables that is quantified (e.g. "?a")
185 * @param expr the expression that is quantified
186 * @return a quantified expression
187 * @throws IllegalArgumentException
188 * <p>in case the logical expression contains a nested CONSTRAINT</p>
189 */
190 UniversalQuantification createUniversalQuantification(Variable variable, LogicalExpression expr)
191 throws IllegalArgumentException;
192
193 /**
194 * creates a existentialy quantified expression (e.g. "exists {?a,?b} (?a memberOf ?b)")
195 * @param variables that is quantified (e.g. [?a,?b])
196 * @param expr the expression that is quantified
197 * @return a quantified expression
198 * @throws IllegalArgumentException
199 * <p>in case the logical expression contains a nested CONSTRAINT</p>
200 * <p>in case the Set of variables is null</p>
201 * <p>in case the arguments of the list aren't all of Type Variable</p>
202 */
203 ExistentialQuantification createExistentialQuantification(Set <Variable> variables, LogicalExpression expr)
204 throws IllegalArgumentException;
205
206 /**
207 * creates a universally quantified expression (e.g. "forall ?a (?a memberOf A)")
208 * @param variable that is quantified (e.g. "?a")
209 * @param expr the expression that is quantified
210 * @return a quantified expression
211 * @throws IllegalArgumentException
212 * <p>in case the logical expression contains a nested CONSTRAINT</p>
213 */
214 ExistentialQuantification createExistentialQuantification(Variable variable, LogicalExpression expr)
215 throws IllegalArgumentException;
216
217 /**
218 * creates an atom (e.g. distance(a,2,3))
219 * @param id identifier of Atom
220 * @param params list of parameters for that atom
221 * @return an atom
222 * @throws IllegalArgumentException in case the parameter id is a Value or the arguments of
223 * the list args aren't all of Type Term
224 */
225 Atom createAtom(Identifier id, List <Term> params)
226 throws IllegalArgumentException;
227
228 /**
229 * creates an compund molecule (e.g. a[b hasValue c]memberOf d).
230 * @param molecules a list of molecules that shall be grouped
231 * @return A CompoundMolecule
232 * @throws IllegalArgumentException in case:
233 * <li> the list does not only contain molecules or contains has less then 2 molecules
234 * <li> not all contained molecules have the same identifier
235 * <li> both MemberShip and SubConcept molecules are contained
236 */
237 CompoundMolecule createCompoundMolecule(List <Molecule> molecules)
238 throws IllegalArgumentException;
239
240 /**
241 * Creates a simple molecule of the form: a memberOf b
242 * @param idInstance A Term identifying the Molecule (left parameter)
243 * @param idConcept A Term identifying the Concept the idInstance is member of
244 * @return A MemberShipMolecule
245 * @throws IllegalArgumentException if one of the arguments is null
246 */
247 MembershipMolecule createMemberShipMolecule(Term idInstance, Term idConcept)
248 throws IllegalArgumentException;
249
250 /**
251 * Creates a compound molecule of the form: a memberOf {b,c}.
252 * This is just a convinience method for creating the compoung molecule
253 * using other existing methods of this factory
254 * @param idInstance A Term identifying the Molecule (left parameter)
255 * @param idConcept A list of terms identifying the concepts that idInstance is member of
256 * @return A CompoundMolecule
257 * @throws IllegalArgumentException if one of the arguments is null, or idConcepts
258 * contains less then 2 terms or an object that is not a term
259 */
260 CompoundMolecule createMemberShipMolecules(Term idInstance, List idConcepts)
261 throws IllegalArgumentException;
262
263 /**
264 * Creates a simple molecule of the form: a subConceptOf b
265 * @param idConcept A Term identifying the Molecule (left parameter)
266 * @param idSuperConcept A Term identifying the super concept of IdConcept
267 * @return A MemberShipMolecule
268 * @throws IllegalArgumentException if one of the arguments is null
269 */
270 SubConceptMolecule createSubConceptMolecule(Term idConcept, Term idSuperConcept)
271 throws IllegalArgumentException;
272
273 /**
274 * Creates a simple molecule of the form: a subConceptOf {b,c}
275 * @param idConcept A Term identifying the Molecule (left parameter)
276 * @param idSuperConcepts A list of terms identifying the super concepts of IdConcept
277 * @return A CompoundMolecule
278 * @throws IllegalArgumentException if one of the arguments is null, or if
279 * idConcepts has less then 2 elements or one of them is not a Term.
280 */
281 CompoundMolecule createSubConceptMolecules(Term idConcept, List idSuperConcept)
282 throws IllegalArgumentException;
283
284 /**
285 * Creates a simple molecule of the form: john[age hasValue 2]
286 * @param instanceID A Term identifying the Molecule (left parameter)
287 * @param attributeID A Term identifying the Attribute of the Molecule
288 * @param attributeValue A Term identifying the Value of the attributeID
289 * @return AttributeValueMolecule
290 * @throws IllegalArgumentException in case one of the terms is null
291 */
292 AttributeValueMolecule createAttributeValue(Term instanceID, Term attributeID, Term attributeValue)
293 throws IllegalArgumentException;
294
295 /**
296 * Creates a compound molecule of the form: john[relative hasValue {mary,lisa}]
297 * @param instanceID A Term identifying the Molecule (left parameter)
298 * @param attributeID A Term identifying the Attribute of the Molecule
299 * @param attributeValue A List of terms identifying the Values of the attributeID
300 * @return CompoundMolecule
301 * @throws IllegalArgumentException in case one of the parameters is null, or attributeValues
302 * contains less then 2 elements or one element in the list is not a term.
303 */
304 CompoundMolecule createAttribusteValues(Term instanceID, Term attributeID, List attributeValues)
305 throws IllegalArgumentException;
306
307 /**
308 * Creates a simple molecule of the form: john[age ofType _integer]
309 * @param instanceID A Term identifying the Molecule (left parameter)
310 * @param attributeID A Term identifying the Attribute of the Molecule
311 * @param attributeType A Term identifying the range of attributeID
312 * @return AttributeConstraintMolecule
313 * @throws IllegalArgumentException in case one of the terms is null
314 */
315 AttributeConstraintMolecule createAttributeConstraint(Term instanceID, Term attributeID, Term attributeType)
316 throws IllegalArgumentException;
317
318 /**
319 * Creates a compund molecule of the form: john[age ofType {human,man}]
320 * @param instanceID A Term identifying the Molecule (left parameter)
321 * @param attributeID A Term identifying the Attribute of the Molecule
322 * @param attributeTypes A List of terms identifying the range of attributeID
323 * @return CompoundMolecule
324 * @throws IllegalArgumentException in case one of the terms is null or attributeTypes
325 * is null, contains less then 2 molecules or an object that is not a term.
326 */
327 CompoundMolecule createAttributeConstraints(Term instanceID, Term attributeID, List attributeTypes)
328 throws IllegalArgumentException;
329
330 /**
331 * Creates a simple molecule of the form: john[anchestor impliesType human]
332 * @param instanceID A Term identifying the Molecule (left parameter)
333 * @param attributeID A Term identifying the Attribute of the Molecule
334 * @param attributeType A Term identifying the range of attributeID
335 * @return CompoundMolecule
336 * @throws IllegalArgumentException in case one of the terms is null
337 */
338 AttributeInferenceMolecule createAttributeInference(Term instanceID, Term attributeID, Term attributeType)
339 throws IllegalArgumentException;
340
341 /**
342 * Creates a compund molecule of the form: john[anchestor impliesType {human,man}]
343 * @param instanceID A Term identifying the Molecule (left parameter)
344 * @param attributeID A Term identifying the Attribute of the Molecule
345 * @param attributeTypes A List of terms identifying the range of attributeID
346 * @return CompoundMolecule
347 * @throws IllegalArgumentException in case one of the terms is null
348 */
349 CompoundMolecule createAttributeInferences(Term instanceID, Term attributeID, List attributeType)
350 throws IllegalArgumentException;
351
352 /**
353 * creates a constructed term (e.g. "_date(2005,2,2)")
354 *
355 * @param functionSymbol identifier of the constructed term
356 * @param terms arguments of the constructed term
357 * @return a constructed term
358 * @throws IllegalArgumentException in case the functionSymbol is null or the arguments of
359 * the list aren't all of Type Term
360 */
361 ConstructedTerm createConstructedTerm(IRI functionSymbol, List <Term> terms)
362 throws IllegalArgumentException;
363
364 /**
365 * creates a numbered anonymous ID (e.g. "_#2")
366 * @param number the number of the anonymous ID
367 * @return a numbered anonymous id
368 */
369 NumberedAnonymousID createAnonymousID(byte number);
370
371 /**
372 * Creates a new Variable instance
373 * @param varName The name of the new variable
374 * @return A newly created variable
375 */
376 Variable createVariable(String varName);
377 }
378 /*
379 * $Log$
380 * Revision 1.17 2007/04/02 12:13:15 morcen
381 * Generics support added to wsmo-api, wsmo4j and wsmo-test
382 *
383 * Revision 1.16 2006/06/21 07:46:13 vassil_momtchev
384 * createVariable(String) method moved from WsmoFactory to LogicalExpressionFactory interface
385 *
386 * Revision 1.15 2006/02/16 19:40:28 holgerlausen
387 * added convinience methods to logical expression factory:
388 * RFE 113501
389 *
390 * Revision 1.14 2005/09/21 06:28:56 holgerlausen
391 * removing explicit factory creations and introducing parameter maps for parsers
392 *
393 * Revision 1.13 2005/09/20 13:21:31 holgerlausen
394 * refactored logical expression API to have simple molecules and compound molecules (RFE 1290043)
395 *
396 * Revision 1.12 2005/09/09 11:58:20 holgerlausen
397 * fixed header logexp no longer extension
398 *
399 * Revision 1.11 2005/09/09 10:45:51 marin_dimitrov
400 * formatting
401 *
402 * Revision 1.10 2005/09/09 06:32:42 holgerlausen
403 * organize imports
404 *
405 * Revision 1.9 2005/09/07 13:13:28 holgerlausen
406 * Equation -> Equivalence (the former sounds more like an atom (a=b))
407 *
408 * Revision 1.8 2005/09/06 18:23:53 holgerlausen
409 * removed createSimpleTypes from LogicalExpressionFactory
410 * splited DataValue into simple and complex value classes
411 * removed explicit classes for simple datavalues (now all org.omwg.ontology.SimpledataValue)
412 * adopted Term visitor to new data structure
413 *
414 * Revision 1.7 2005/09/02 13:32:44 ohamano
415 * move logicalexpression packages from ext to core
416 * move tests from logicalexpression.test to test module
417 *
418 * Revision 1.17 2005/09/02 09:43:28 ohamano
419 * integrate wsmo-api and le-api on api and reference implementation level; full parser, serializer and validator integration will be next step
420 *
421 * Revision 1.16 2005/08/30 14:14:20 haselwanter
422 * Merging LE API to HEAD.
423 *
424 * Revision 1.15.2.2 2005/08/30 11:50:28 haselwanter
425 * Adapting javadocs.
426 *
427 * Revision 1.15.2.1 2005/08/29 14:35:02 haselwanter
428 * Additional creators for the added interfaces.
429 *
430 * Revision 1.15 2005/08/19 14:37:45 nathaliest
431 * JavaDoc added
432 *
433 * Revision 1.14 2005/08/18 16:15:40 nathaliest
434 * JavaDoc added
435 *
436 * Revision 1.13 2005/08/16 16:28:29 nathaliest
437 * JavaDoc added
438 * Method getArgument(int) at UnaryImpl, QuantifiedImpl and BinaryImpl changed
439 * Method equals(Object) at QuantifiedImpl changed
440 *
441 * Revision 1.12 2005/08/09 08:34:35 holgerlausen
442 * check now for valid varname in VariableImpl
443 *
444 * Revision 1.11 2005/08/02 19:48:04 holgerlausen
445 * AnonymousID->UnNbAnonymousID
446 * fixed all hash codes, such that one can rely on HasSet.equal()
447 * added serializedUID
448 *
449 * Revision 1.10 2005/08/02 15:25:42 holgerlausen
450 * Vector -> List IF
451 * no InvalidModelExcpetion anymore
452 *
453 * Revision 1.9 2005/07/29 07:27:45 ohamano
454 * organize imports
455 *
456 * Revision 1.8 2005/07/24 18:38:26 holgerlausen
457 * WSMLInterger ~ BigInter
458 * added WrappedParserException for logexp parsing
459 * delete SQName -> IRI with namespace heuristics as discussed [1]
460 * implemented equals for logexp (non equality reasoning but simple term identity)
461 * [1] http://sourceforge.net/tracker/index.php?func=detail&aid=1225411&group_id=113501&atid=665349
462 *
463 * Revision 1.7 2005/07/18 13:59:06 holgerlausen
464 * refactored: createLEXXX -> createWSMLXXX
465 * refined integration test (brakes on serializing)
466 * added unit testing to build xml
467 *
468 * Revision 1.6 2005/07/13 12:37:56 holgerlausen
469 * removed interfaces for SimpleDataType and aligned with wsmo4j
470 * XXXValue -> WSMLXXX
471 *
472 * Revision 1.5 2005/07/13 09:32:37 holgerlausen
473 * changed to compile with main wsmo4j / changed correspondence of wsml2java types
474 *
475 * Revision 1.4 2005/06/22 13:32:01 ohamano
476 * change header
477 *
478 * Revision 1.3 2005/06/21 14:01:43 holgerlausen
479 * compliant to new interface
480 *
481 * Revision 1.2 2005/06/20 08:30:03 holgerlausen
482 * formating
483 *
484 */