KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > hp > hpl > jena > reasoner > rulesys > GenericRuleReasoner


1 /******************************************************************
2  * File: GenericRuleReasoner.java
3  * Created by: Dave Reynolds
4  * Created on: 08-Jun-2003
5  *
6  * (c) Copyright 2003, 2004, 2005 Hewlett-Packard Development Company, LP
7  * [See end of file]
8  * $Id: GenericRuleReasoner.java,v 1.24 2005/04/12 16:40:18 der Exp $
9  *****************************************************************/
10 package com.hp.hpl.jena.reasoner.rulesys;
11
12 import com.hp.hpl.jena.reasoner.*;
13 import com.hp.hpl.jena.reasoner.rulesys.impl.*;
14 import com.hp.hpl.jena.vocabulary.*;
15 import com.hp.hpl.jena.vocabulary.ReasonerVocabulary;
16 import com.hp.hpl.jena.graph.*;
17 import com.hp.hpl.jena.rdf.model.*;
18
19 import java.util.*;
20
21 /**
22  * A reasoner interface that is able to invoke any of the useful
23  * rule engine combinations. The rule set can be set after the reasoner
24  * instance is created. The mode can be set to forward, backward or hybrid.
25  * The OWL-specific rule augmentation can be included. Each of these settings
26  * can be controlled using the configuration graph, specific methods calls or
27  * generic setParameter calls.
28  *
29  * @author <a HREF="mailto:der@hplb.hpl.hp.com">Dave Reynolds</a>
30  * @version $Revision: 1.24 $ on $Date: 2005/04/12 16:40:18 $
31  */
32 public class GenericRuleReasoner extends FBRuleReasoner {
33
34     /** Prepared set of rules used for Backward-only mode */
35     protected LPRuleStore bRuleStore;
36     
37     /** the current rule mode */
38     protected RuleMode mode = HYBRID;
39     
40     /** Flag, if true we cache the closure of the pure rule set with its axioms */
41     protected static final boolean cachePreload = true;
42     
43     /** Flag, if true then subClass and subProperty lattices will be optimized using TGCs, only applicable to HYBRID reasoners */
44     protected boolean enableTGCCaching = false;
45     
46     /** Flag, if true then rules will be augmented by OWL translations of the schema */
47     protected boolean enableOWLTranslation = false;
48     
49     /** Optional set of preprocessing hooks to be run in sequence during preparation time, only applicable to HYBRID modes */
50     protected HashSet preprocessorHooks;
51     
52     /** Flag, if true then find results will be filtered to remove functors and illegal RDF */
53     public boolean filterFunctors = true;
54     
55     /** A prebuilt copy of the OWL translation hook */
56     private static final OWLRuleTranslationHook owlTranslator = new OWLRuleTranslationHook();
57     
58     /** Constant - the mode description for pure forward chaining */
59     public static final RuleMode FORWARD = new RuleMode("forward");
60     
61     /** Constant - the mode description for pure forward chaining, using RETE engine */
62     public static final RuleMode FORWARD_RETE = new RuleMode("forwardRETE");
63     
64     /** Constant - the mode description for pure backward chaining */
65     public static final RuleMode BACKWARD = new RuleMode("backward");
66     
67     /** Constant - the mode description for mixed forward/backward, this is the default mode */
68     public static final RuleMode HYBRID = new RuleMode("hybrid");
69     
70 // =======================================================================
71 // Constructors
72
73     /**
74      * Constructor. This is the raw version that does not reference a ReasonerFactory
75      * and so has no capabilities description.
76      * @param rules a list of Rule instances which defines the ruleset to process
77      */
78     public GenericRuleReasoner(List rules) {
79         super(rules);
80     }
81     
82     /**
83      * Constructor
84      * @param factory the parent reasoner factory which is consulted to answer capability questions
85      * @param configuration RDF node to configure the rule set and mode, can be null
86      */
87     public GenericRuleReasoner(ReasonerFactory factory, Resource configuration) {
88         super(factory, configuration);
89     }
90     
91     /**
92      * Constructor
93      * @param rules a list of Rule instances which defines the ruleset to process
94      * @param factory the parent reasoner factory which is consulted to answer capability questions
95      */
96     public GenericRuleReasoner(List rules, ReasonerFactory factory) {
97         super(rules, factory);
98     }
99     
100     /**
101      * Internal constructor, used to generated a partial binding of a schema
102      * to a rule reasoner instance.
103      */
104     protected GenericRuleReasoner(List rules, Graph schemaGraph, ReasonerFactory factory, RuleMode mode) {
105         this(rules, factory);
106         this.schemaGraph = schemaGraph;
107         this.mode = mode;
108     }
109     
110 // =======================================================================
111 // Parameter control
112
113     /**
114      * Set the direction of rule inference desired.
115      * If set to a pure mode (FORWARD, BACKWARD) then the rules will be
116      * interpreted as operating in that direction which ever direction
117      * they were written in. In HYBRID mode then the direction of the rule
118      * itself which control whether it is used in forward or backward mode.
119      * In addition, HYBRID mode allows forward rules to generate addition
120      * backward rules.
121      */
122     public void setMode(RuleMode mode) {
123         if (schemaGraph != null) {
124             throw new ReasonerException("Can't change mode of a reasoner bound to a schema");
125         }
126         this.mode = mode;
127         preload = null;
128         bRuleStore = null;
129     }
130     
131     /**
132      * Set (or change) the rule set that this reasoner should execute.
133      * This will not affect inference models already created from this reasoner.
134      * @param rules a list of Rule objects
135      */
136     public void setRules(List rules) {
137         // Currently redunant but it will differ from the inherited
138 // version in the future
139 super.setRules(rules);
140     }
141     
142     /**
143      * Set to true to enable translation of selected parts of an OWL schema
144      * to additional rules. At present only intersction statements are handled this way.
145      * The translation is only applicable in HYBRID mode.
146      */
147     public void setOWLTranslation(boolean enableOWLTranslation) {
148         if (enableOWLTranslation && (mode != HYBRID)) {
149             throw new ReasonerException("Can only enable OWL rule translation in HYBRID mode");
150         }
151         this.enableOWLTranslation = enableOWLTranslation;
152         if (enableOWLTranslation) {
153             addPreprocessingHook(owlTranslator);
154         } else {
155             removePreprocessingHook(owlTranslator);
156         }
157     }
158     
159     /**
160      * Set to true to enable caching of subclass/subproperty lattices in a
161      * specialized cache rather than using the rule systems. This has substantially
162      * higher performance but it is done as a separate initialization pass and so
163      * can only work correct with some rule sets. This is only guaranteed to be implemented
164      * for the HYBRID mode.
165      */
166     public void setTransitiveClosureCaching(boolean enableTGCCaching) {
167         this.enableTGCCaching = enableTGCCaching;
168     }
169    
170     /**
171      * Set to true to cause functor-valued literals to be dropped from rule output.
172      * Default is true.
173      */
174     public void setFunctorFiltering(boolean param) {
175         filterFunctors = param;
176     }
177     
178     /**
179      * Add a new preprocessing hook defining an operation that
180      * should be run when the inference graph is being prepared. This can be
181      * used to generate additional data-dependent rules or translations.
182      * This is only guaranted to be implemented for the HYBRID mode.
183      */
184     public void addPreprocessingHook(RulePreprocessHook hook) {
185         if (preprocessorHooks == null) {
186             preprocessorHooks = new HashSet();
187         }
188         preprocessorHooks.add(hook);
189     }
190     
191     /**
192      * Remove a preprocessing hook. defining an operation that
193      */
194     public void removePreprocessingHook(RulePreprocessHook hook) {
195         if (preprocessorHooks != null) {
196             preprocessorHooks.remove(hook);
197         }
198     }
199         
200     protected boolean doSetResourceParameter( Property parameter, Resource value )
201         {
202         if (parameter.equals( JenaModelSpec.ruleSetURL ))
203             {
204             addRules( Rule.rulesFromURL( value.getURI() ) );
205             }
206         else if (parameter.equals( JenaModelSpec.ruleSet ))
207             {
208             StmtIterator that = value.listProperties( JenaModelSpec.ruleSetURL );
209             while (that.hasNext())
210                 {
211                 addRules( Rule.rulesFromURL( that.nextStatement().getResource().getURI() ) );
212                 }
213             StmtIterator it = value.listProperties( JenaModelSpec.hasRule );
214             while (it.hasNext())
215                 {
216                 addRules( Rule.parseRules( it.nextStatement().getString() ) );
217                 }
218             }
219         else
220             return false;
221         return true;
222         }
223     
224     /**
225      * Internal version of setParameter that does not directly raise an
226      * exception on parameters it does not reconize.
227      * @return false if the parameter was not recognized
228      */
229     protected boolean doSetParameter(Property parameter, Object JavaDoc value) {
230         if (parameter.equals(ReasonerVocabulary.PROPderivationLogging)) {
231             recordDerivations = Util.convertBooleanPredicateArg(parameter, value);
232         } else if (parameter.equals(ReasonerVocabulary.PROPtraceOn)) {
233             traceOn = Util.convertBooleanPredicateArg(parameter, value);
234         } else if (parameter.equals(ReasonerVocabulary.PROPenableFunctorFiltering)) {
235             filterFunctors = Util.convertBooleanPredicateArg(parameter, value);
236             
237         } else if (parameter.equals(ReasonerVocabulary.PROPenableOWLTranslation)) {
238             enableOWLTranslation = Util.convertBooleanPredicateArg(parameter, value);
239             if (enableOWLTranslation) {
240                 addPreprocessingHook(owlTranslator);
241             } else {
242                 removePreprocessingHook(owlTranslator);
243             }
244             
245         } else if (parameter.equals(ReasonerVocabulary.PROPenableTGCCaching)) {
246             enableTGCCaching = Util.convertBooleanPredicateArg(parameter, value);
247             
248         } else if (parameter.equals(ReasonerVocabulary.PROPruleMode)) {
249             if (value.equals(FORWARD.name)) {
250                 mode = FORWARD;
251             } else if (value.equals(FORWARD_RETE.name)) {
252                 mode = FORWARD_RETE;
253             } else if (value.equals(BACKWARD.name)) {
254                 mode = BACKWARD;
255             } else if (value.equals(HYBRID.name)) {
256                 mode = HYBRID;
257             } else {
258                 throw new IllegalParameterException("PROPruleMode can only be 'forward'm 'forwardRETE', 'backward', 'hybrid', not " + value);
259             }
260             
261         } else if (parameter.equals(ReasonerVocabulary.PROPruleSet)) {
262             if (value instanceof String JavaDoc) {
263                 addRules( loadRules( (String JavaDoc)value ) );
264             } else {
265                 throw new IllegalParameterException("PROPruleSet value should be a URI string. Was a " + value.getClass());
266             }
267         } else {
268             return false;
269         }
270         return true;
271     }
272     
273 // =======================================================================
274 // Implementation methods
275
276     /**
277      * Precompute the implications of a schema graph. The statements in the graph
278      * will be combined with the data when the final InfGraph is created.
279      */
280     public Reasoner bindSchema(Graph tbox) throws ReasonerException {
281         if (schemaGraph != null) {
282             throw new ReasonerException("Can only bind one schema at a time to a GenericRuleReasoner");
283         }
284         Graph graph = null;
285         if (mode == FORWARD) {
286             graph = new BasicForwardRuleInfGraph(this, rules, null, tbox);
287             ((InfGraph)graph).prepare();
288         } else if (mode == FORWARD_RETE) {
289                 graph = new RETERuleInfGraph(this, rules, null, tbox);
290                 ((InfGraph)graph).prepare();
291         } else if (mode == BACKWARD) {
292             graph = tbox;
293         } else {
294             List ruleSet = rules;
295             graph = new FBRuleInfGraph(this, ruleSet, getPreload(), tbox);
296             if (enableTGCCaching) ((FBRuleInfGraph)graph).setUseTGCCache();
297             ((FBRuleInfGraph)graph).prepare();
298         }
299         GenericRuleReasoner grr = new GenericRuleReasoner(rules, graph, factory, mode);
300         grr.setDerivationLogging(recordDerivations);
301         grr.setTraceOn(traceOn);
302         grr.setTransitiveClosureCaching(enableTGCCaching);
303         grr.setFunctorFiltering(filterFunctors);
304         if (preprocessorHooks != null) {
305             for (Iterator i = preprocessorHooks.iterator(); i.hasNext(); ) {
306                 grr.addPreprocessingHook((RulePreprocessHook)i.next());
307             }
308         }
309         return grr;
310     }
311     
312     /**
313      * Attach the reasoner to a set of RDF data to process.
314      * The reasoner may already have been bound to specific rules or ontology
315      * axioms (encoded in RDF) through earlier bindRuleset calls.
316      *
317      * @param data the RDF data to be processed, some reasoners may restrict
318      * the range of RDF which is legal here (e.g. syntactic restrictions in OWL).
319      * @return an inference graph through which the data+reasoner can be queried.
320      * @throws ReasonerException if the data is ill-formed according to the
321      * constraints imposed by this reasoner.
322      */
323     public InfGraph bind(Graph data) throws ReasonerException {
324         Graph schemaArg = schemaGraph == null ? getPreload() : schemaGraph;
325         InfGraph graph = null;
326         if (mode == FORWARD) {
327             graph = new BasicForwardRuleInfGraph(this, rules, schemaArg);
328             ((BasicForwardRuleInfGraph)graph).setTraceOn(traceOn);
329         } else if (mode == FORWARD_RETE) {
330                 graph = new RETERuleInfGraph(this, rules, schemaArg);
331                 ((BasicForwardRuleInfGraph)graph).setTraceOn(traceOn);
332         } else if (mode == BACKWARD) {
333             graph = new LPBackwardRuleInfGraph(this, getBruleStore(), data, schemaArg);
334             ((LPBackwardRuleInfGraph)graph).setTraceOn(traceOn);
335         } else {
336             List ruleSet = ((FBRuleInfGraph)schemaArg).getRules();
337             FBRuleInfGraph fbgraph = new FBRuleInfGraph(this, ruleSet, schemaArg);
338             graph = fbgraph;
339             if (enableTGCCaching) fbgraph.setUseTGCCache();
340             fbgraph.setTraceOn(traceOn);
341             fbgraph.setFunctorFiltering(filterFunctors);
342             if (preprocessorHooks!= null) {
343                 for (Iterator i = preprocessorHooks.iterator(); i.hasNext(); ) {
344                     fbgraph.addPreprocessingHook((RulePreprocessHook)i.next());
345                 }
346             }
347         }
348         graph.setDerivationLogging(recordDerivations);
349         graph.rebind(data);
350         return graph;
351     }
352     
353     /**
354      * Get the single static precomputed rule closure.
355      */
356     protected synchronized InfGraph getPreload() {
357         if (cachePreload && preload == null && mode == HYBRID) {
358             if (mode == HYBRID) {
359                 preload = new FBRuleInfGraph(this, rules, null);
360                 if (enableTGCCaching) ((FBRuleInfGraph)preload).setUseTGCCache();
361             } else if (mode == FORWARD) {
362                 preload = new BasicForwardRuleInfGraph(this, rules, null);
363             } else if (mode == FORWARD_RETE) {
364                 preload = new RETERuleInfGraph(this, rules, null);
365             }
366             preload.prepare();
367         }
368         return preload;
369     }
370     
371     /**
372      * Return the prepared backward only rules.
373      */
374     protected LPRuleStore getBruleStore() {
375         if (bRuleStore == null) {
376             bRuleStore = new LPRuleStore(rules);
377         }
378         return bRuleStore;
379     }
380     
381 // =======================================================================
382 // Inner classes
383
384     /**
385      * Class used as an enum for describing rule modes.
386      */
387     public static class RuleMode {
388         /** Name for the mode */
389         String JavaDoc name;
390         
391         /** Constructor */
392         protected RuleMode(String JavaDoc name) {
393             this.name = name;
394         }
395         
396         public String JavaDoc toString() {
397             return name;
398         }
399     }
400     
401 }
402
403
404
405 /*
406     (c) Copyright 2003, 2004, 2005 Hewlett-Packard Development Company, LP
407     All rights reserved.
408
409     Redistribution and use in source and binary forms, with or without
410     modification, are permitted provided that the following conditions
411     are met:
412
413     1. Redistributions of source code must retain the above copyright
414        notice, this list of conditions and the following disclaimer.
415
416     2. Redistributions in binary form must reproduce the above copyright
417        notice, this list of conditions and the following disclaimer in the
418        documentation and/or other materials provided with the distribution.
419
420     3. The name of the author may not be used to endorse or promote products
421        derived from this software without specific prior written permission.
422
423     THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
424     IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
425     OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
426     IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
427     INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
428     NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
429     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
430     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
431     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
432     THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
433 */
Popular Tags