View Javadoc

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