001/**
002 * OntologyConnector.java
003 * jCOLIBRI2 framework. 
004 * @author Juan A. Recio-Garc�a.
005 * GAIA - Group for Artificial Intelligence Applications
006 * http://gaia.fdi.ucm.es
007 * 07/06/2007
008 */
009package es.ucm.fdi.gaia.jcolibri.connector;
010
011import java.io.FileWriter;
012import java.net.URL;
013import java.util.ArrayList;
014import java.util.Collection;
015import java.util.Iterator;
016import java.util.List;
017
018import javax.xml.parsers.DocumentBuilder;
019import javax.xml.parsers.DocumentBuilderFactory;
020
021import org.apache.logging.log4j.LogManager;
022import org.w3c.dom.Document;
023import org.w3c.dom.Node;
024import org.w3c.dom.NodeList;
025
026import es.ucm.fdi.gaia.jcolibri.cbrcore.Attribute;
027import es.ucm.fdi.gaia.jcolibri.cbrcore.CBRCase;
028import es.ucm.fdi.gaia.jcolibri.cbrcore.CaseBaseFilter;
029import es.ucm.fdi.gaia.jcolibri.cbrcore.CaseComponent;
030import es.ucm.fdi.gaia.jcolibri.cbrcore.Connector;
031import es.ucm.fdi.gaia.jcolibri.connector.ontologyutils.OntologyInfo;
032import es.ucm.fdi.gaia.jcolibri.connector.ontologyutils.OntologyMapping;
033import es.ucm.fdi.gaia.jcolibri.datatypes.Instance;
034import es.ucm.fdi.gaia.jcolibri.exception.InitializingException;
035import es.ucm.fdi.gaia.jcolibri.util.FileIO;
036import es.ucm.fdi.gaia.jcolibri.util.OntoBridgeSingleton;
037import es.ucm.fdi.gaia.jcolibri.util.ProgressController;
038import es.ucm.fdi.gaia.ontobridge.OntoBridge;
039import es.ucm.fdi.gaia.ontobridge.OntologyDocument;
040
041/**
042 * Implements a generic Ontology connector.
043 * It uses OntoBridge to manage the ontologies and the reasoner.
044 * To configure this connector create a configuration xml file following this schema:
045 * <a href="OntologyConnector.xsd">/doc/configfilesSchemas/OntologyConnector.xsd</a>:<p>
046 * <img src="OntologyConnectorSchema.jpg">
047 * <p>
048 * This connector only maps case structures without compound attributes.
049 * All attributes must be Instance typed.
050 * 
051 * For a complete example see Test 10.
052 * 
053 * @author Juan A. Recio-Garcia
054 * @version 2.0
055 */
056public class OntologyConnector implements Connector {
057        
058        private Class<?> descriptionClass;
059        private Class<?> solutionClass;
060        private Class<?> justOfSolutionClass;
061        private Class<?> resultClass;
062        
063        private OntologyInfo mainOntologyInfo;
064        private ArrayList<OntologyInfo> subOntologiesInfo;
065        
066        private String CaseMainConcept;
067        
068        private ArrayList<OntologyMapping> descriptionMappings;
069        private ArrayList<OntologyMapping> solutionMappings;
070        private ArrayList<OntologyMapping> justOfSolutionMappings;
071        private ArrayList<OntologyMapping> resultMappings;
072        
073        private boolean modified;
074        
075        private OntologyInfo getOntologyInfo(Node node)
076        {
077                OntologyInfo oi = new OntologyInfo();
078                NodeList ontologyNodes = node.getChildNodes();
079                for(int i=0; i<ontologyNodes.getLength(); i++)
080                {
081                        Node n = ontologyNodes.item(i);
082                        if(n.getNodeName().equals("URL"))
083                                oi.setUrl(n.getTextContent());
084                        else if(n.getNodeName().equals("LocalCopy"))
085                                oi.setLocalCopy(n.getTextContent());    
086                }
087                return oi;
088        }
089        
090        private void getOntologyMappings(Node mappings, ArrayList<OntologyMapping> descriptionMappings) {
091                NodeList mappingNodes = mappings.getChildNodes();
092                for(int i=0; i<mappingNodes.getLength(); i++)
093                {
094                        Node n = mappingNodes.item(i);
095                        if(!n.getNodeName().equals("Map"))
096                                continue;
097                        OntologyMapping om = new OntologyMapping();
098                        NodeList contents = n.getChildNodes();
099                        for(int j=0; j<contents.getLength(); j++)
100                        {
101                                Node c = contents.item(j);
102                                if(c.getNodeName().equals("Property"))
103                                        om.setProperty(c.getTextContent());
104                                else if(c.getNodeName().equals("Concept"))
105                                        om.setConcept(c.getTextContent());
106                                else if(c.getNodeName().equals("Attribute"))
107                                        om.setAttribute(c.getTextContent());
108                        }
109                        descriptionMappings.add(om);
110                }
111        }
112        
113        /** 
114         * Initializes the connector from an XML config file.
115         * This method reads the configuration and launches OntoBridge with the Pellet reasoner.
116         * Then the ontologies are loaded into memory.
117         * 
118         * @see Connector#initFromXMLfile(URL)
119         */
120        public void initFromXMLfile(URL file) throws InitializingException {
121                
122                
123                try {
124                        DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
125                        DocumentBuilder db = dbf.newDocumentBuilder();
126                        Document doc = db.parse(file.openStream());
127                        
128                        /* Main Ontology Info */
129                        mainOntologyInfo = getOntologyInfo(doc.getElementsByTagName("MainOntology").item(0));
130
131                        /* SubOntologies Info */
132                        subOntologiesInfo = new ArrayList<OntologyInfo>();
133                        NodeList subOntologiesNodes = doc.getElementsByTagName("SubOntology");
134                        for(int i=0; i<subOntologiesNodes.getLength(); i++)
135                                subOntologiesInfo.add(getOntologyInfo(subOntologiesNodes.item(i)));
136                        
137                        /* Case Main Concept */
138                        this.CaseMainConcept = doc.getElementsByTagName("CaseMainConcept").item(0).getTextContent();
139                        
140                        
141                        /* Description mapping */
142                        this.descriptionClass = Class.forName(doc.getElementsByTagName("DescriptionClassName").item(0).getTextContent());
143                        Node mappings = doc.getElementsByTagName("DescriptionMappings").item(0);
144                        this.descriptionMappings = new ArrayList<OntologyMapping>();
145                        getOntologyMappings(mappings, descriptionMappings);
146                        
147                        /* Solution mapping */
148                        try{
149                                this.solutionClass =  Class.forName(doc.getElementsByTagName("SolutionClassName").item(0).getTextContent());
150                                mappings = doc.getElementsByTagName("SolutionMappings").item(0);
151                                this.solutionMappings = new ArrayList<OntologyMapping>();
152                                getOntologyMappings(mappings, solutionMappings);
153                        }catch(Exception e) {}
154                        
155                        /* JustOfSolution mapping */
156                        try{
157                                this.justOfSolutionClass =  Class.forName(doc.getElementsByTagName("JustificationOfSolutionClassName").item(0).getTextContent());
158                                mappings = doc.getElementsByTagName("JustificationOfSolutionMappings").item(0);
159                                this.justOfSolutionMappings = new ArrayList<OntologyMapping>();
160                                getOntologyMappings(mappings, justOfSolutionMappings);
161                        }catch(Exception e) {}
162                        
163                        /* result mapping */
164                        try{
165                                this.resultClass =  Class.forName(doc.getElementsByTagName("ResultClassName").item(0).getTextContent());
166                                mappings = doc.getElementsByTagName("ResultMappings").item(0);
167                                this.resultMappings = new ArrayList<OntologyMapping>();
168                                getOntologyMappings(mappings, resultMappings);
169                        }catch(Exception e) {}
170                        
171                        
172
173                        // Now let's initialize Ontobridge
174                        
175                        // Obtain a reference to OntoBridge
176                        OntoBridge ob = es.ucm.fdi.gaia.jcolibri.util.OntoBridgeSingleton.getOntoBridge();
177                        // Configure it to work with the Pellet reasoner
178                        ob.initWithPelletReasoner();
179                        // Setup the main ontology
180                        OntologyDocument mainOnto = new OntologyDocument(this.mainOntologyInfo.getUrl(), 
181                        FileIO.findFile(this.mainOntologyInfo.getLocalCopy()).toExternalForm());
182                        // Setup subontologies
183                        ArrayList<OntologyDocument> subOntologies = new ArrayList<OntologyDocument>();
184                        for(OntologyInfo oi : this.subOntologiesInfo)
185                        {
186                                OntologyDocument subOnto = new OntologyDocument(oi.getUrl(), 
187                                FileIO.findFile(oi.getLocalCopy()).toURI().toString());
188                                subOntologies.add(subOnto);
189                        }
190                        
191                        // Load the ontology
192                        ob.loadOntology(mainOnto, subOntologies, false);
193
194                        
195                        // Set modified to false
196                        this.modified = false;
197                        
198                } catch (Exception e) {
199                        throw new InitializingException(e);
200                }
201                
202                
203        }
204
205
206        /* (non-Javadoc)
207         * @see jcolibri.cbrcore.Connector#retrieveAllCases()
208         */
209        public List<CBRCase> retrieveAllCases() {
210
211                //Result list
212                ArrayList<CBRCase> cases = new ArrayList<CBRCase>();
213                
214                //Obtain OntoBridge
215                OntoBridge ob = OntoBridgeSingleton.getOntoBridge();
216                
217                ProgressController.init(this.getClass(), "Loading concepts", ProgressController.UNKNOWN_STEPS);
218                
219                //Obtain instances
220                Iterator<String> caseInstances =  ob.listInstances(this.CaseMainConcept);
221                while(caseInstances.hasNext())
222                {
223                        String caseInstance = caseInstances.next();
224                        CBRCase _case = new CBRCase();
225                        
226                        try {
227                                //Map description
228                                CaseComponent description = (CaseComponent)this.descriptionClass.newInstance();
229                                retrieveCaseComponent(ob, description, caseInstance, this.descriptionMappings);
230                                _case.setDescription(description);
231                                
232                                //Map solution
233                                if(this.solutionClass != null)
234                                {
235                                        CaseComponent cc = (CaseComponent)this.solutionClass.newInstance();
236                                        retrieveCaseComponent(ob, cc, caseInstance, this.solutionMappings);     
237                                        _case.setSolution(cc);
238                                }
239                                
240                                //Map justification of solution
241                                if(this.justOfSolutionClass != null)
242                                {
243                                        CaseComponent cc = (CaseComponent)this.justOfSolutionClass.newInstance();
244                                        retrieveCaseComponent(ob, cc, caseInstance, this.justOfSolutionMappings);                       
245                                        _case.setJustificationOfSolution(cc);
246                                }
247                                
248                                //Map result solution
249                                if(this.resultClass != null)
250                                {
251                                        CaseComponent cc = (CaseComponent)this.resultClass.newInstance();
252                                        retrieveCaseComponent(ob, cc, caseInstance, this.resultMappings);
253                                        _case.setResult(cc);
254                                }
255                                
256                                // If everything ok add the case to the list
257                                cases.add(_case);
258                                
259                        } catch (Exception e) {
260                                LogManager.getLogger(this.getClass()).error(e);
261                        }
262                        
263                        ProgressController.step(this.getClass());
264                }
265                ProgressController.finish(this.getClass());
266                return cases;
267        }
268        
269        private void retrieveCaseComponent(OntoBridge ob, CaseComponent cc, String mainInstanceName, ArrayList<OntologyMapping> mappings) throws Exception
270        {
271                //Id
272                Instance id = new Instance(mainInstanceName);
273                cc.getIdAttribute().setValue(cc, id);
274                
275                //Other attributes
276                for(OntologyMapping om: mappings)
277                {
278                        // Obtain CaseComponent attribute
279                        Attribute at = new Attribute(om.getAttribute(), cc.getClass());
280                        
281                        // Find values of the property. It could have several values.
282                        Iterator<String> values = ob.listPropertyValue(mainInstanceName, om.getProperty());
283                        // Find which value is instance of the concept
284                        boolean found = false;
285                        while(values.hasNext() && !found)
286                        {
287                                String valueInstance = values.next();
288                                if(ob.isInstanceOf(valueInstance, om.getConcept()))
289                                {
290                                        found = true;
291                                        Instance concept = new Instance(valueInstance);
292                                        at.setValue(cc, concept);
293                                }
294                        }
295                }
296
297        }
298
299        /**
300         * UnImplemented.
301         * @see Connector#retrieveSomeCases(CaseBaseFilter)
302         */
303        public List<CBRCase> retrieveSomeCases(CaseBaseFilter filter) {
304                LogManager.getLogger(this.getClass()).error("retrieveSomeCases(CaseBaseFilter) method is not yet implemented");
305                return null;
306        }
307
308        /** 
309         * Stores cases into the ontology.
310         * @see Connector#storeCases(Collection)
311         */
312        public void storeCases(Collection<CBRCase> cases) {
313                
314                if(cases.isEmpty())
315                        return;
316                else
317                        modified = true;
318                
319                
320                //Obtain OntoBridge
321                OntoBridge ob = OntoBridgeSingleton.getOntoBridge();
322                
323                ProgressController.init(this.getClass(), "Storing concepts/cases", cases.size());
324                for(CBRCase _case: cases)
325                {
326                        try {
327                                if(!ob.existsInstance(_case.getID().toString(),this.CaseMainConcept))
328                                        ob.createInstance(this.CaseMainConcept, _case.getID().toString());
329                                createCaseComponent(_case.getDescription(), this.descriptionMappings);
330                                createCaseComponent(_case.getSolution(), this.solutionMappings);
331                                createCaseComponent(_case.getJustificationOfSolution(), this.justOfSolutionMappings);
332                                createCaseComponent(_case.getResult(), this.resultMappings);
333                        } catch (Exception e) {
334                                LogManager.getLogger(this.getClass()).error("Error storing case: "+_case+". Cause: "+ e.getMessage());
335                        }
336                        ProgressController.step(this.getClass());
337                }
338                ProgressController.finish(this.getClass());
339        }
340        
341        private void createCaseComponent(CaseComponent cc, ArrayList<OntologyMapping> maps) throws Exception
342        {
343                if((cc == null)||(maps==null))
344                        return;
345                
346                OntoBridge ob = OntoBridgeSingleton.getOntoBridge();
347                
348                String mainInstance = cc.getIdAttribute().getValue(cc).toString();
349
350                for(OntologyMapping om: maps)
351                {
352                        
353                        Attribute at = new Attribute(om.getAttribute(), cc.getClass());
354                        String instance = at.getValue(cc).toString();
355                        if(!ob.existsInstance(instance,om.getConcept()))
356                                ob.createInstance(om.getConcept(), instance);
357                        ob.createOntProperty(mainInstance, om.getProperty(), instance);
358                }
359                
360                
361        }
362
363        /**
364         * If there was any modification to the ontology, the owl file is replaced with a new one that contains the changes.
365         * The new owl file is completely regenerated from scrach with the current content of the reasoner (not including the inferred model).
366         * OntoBridge uses the RDF/XML-ABBREV syntax for the owl files.
367         * 
368         * @see Connector#close()
369         */
370        public void close() {
371                if(!modified)
372                        return;
373                OntoBridge ob = OntoBridgeSingleton.getOntoBridge();
374                try {
375                        ob.save(new FileWriter(FileIO.findFile(this.mainOntologyInfo.getLocalCopy()).getFile()));
376                } catch (Exception e) {
377                        LogManager.getLogger(this.getClass()).error(e);
378                }
379
380        }
381
382        /**
383         * Deletes cases in the ontology. Only the main instance (case id mapped instance) is removed, so the instances mapped to attributes are keep. 
384         * @see Connector#deleteCases(Collection)
385         */
386        public void deleteCases(Collection<CBRCase> cases) {
387
388                if(cases.isEmpty())
389                        return;
390                else
391                        modified = true;
392                
393                OntoBridge ob = OntoBridgeSingleton.getOntoBridge();
394                
395                ProgressController.init(this.getClass(), "Deleting concepts/cases", cases.size());
396                for(CBRCase _case: cases)
397                {
398                        ob.delete(_case.getID().toString());
399                        ProgressController.step(this.getClass());
400                }
401                ProgressController.finish(this.getClass());
402
403        }
404
405        
406        
407        /**************************************************************/
408        /*********** Public API for the connector configuration       */
409        /**************************************************************/
410
411        
412        /**
413         * @return Returns the caseMainConcept.
414         */
415        public String getCaseMainConcept() {
416                return CaseMainConcept;
417        }
418
419        /**
420         * @return Returns the descriptionMappings.
421         */
422        public ArrayList<OntologyMapping> getDescriptionMappings() {
423                return descriptionMappings;
424        }
425
426        /**
427         * @return Returns the justOfSolutionMappings.
428         */
429        public ArrayList<OntologyMapping> getJustOfSolutionMappings() {
430                return justOfSolutionMappings;
431        }
432
433        /**
434         * @return Returns the mainOntologyInfo.
435         */
436        public OntologyInfo getMainOntologyInfo() {
437                return mainOntologyInfo;
438        }
439
440        /**
441         * @return Returns the resultMappings.
442         */
443        public ArrayList<OntologyMapping> getResultMappings() {
444                return resultMappings;
445        }
446
447        /**
448         * @return Returns the solutionMappings.
449         */
450        public ArrayList<OntologyMapping> getSolutionMappings() {
451                return solutionMappings;
452        }
453
454        /**
455         * @return Returns the subOntologiesInfo.
456         */
457        public ArrayList<OntologyInfo> getSubOntologiesInfo() {
458                return subOntologiesInfo;
459        }
460        
461        
462        
463}