001    /**
002     * OntoBride library.
003     * GAIA - Group for Artifical Intelligence Applications
004     * Departamento de Ingeniería del Software e Inteligencia Artificial
005     * Universidad Complutense de Madrid
006     * 
007     * Licensed under the terms of the GNU Library or Lesser General Public License (LGPL)
008     *
009     * @author Juan A. Recio García
010     * @version 1.2
011     * 
012     * This software is a subproject of the jCOLIBRI framework
013     * http://sourceforge.net/projects/jcolibri-cbr/
014     * http://gaia.fdi.ucm.es/projects/jcolibri/
015     * 
016     * File: SPARQL.java
017     * Created by: Antonio A. Sánchez Ruiz-Granados
018     * 22/03/2007
019     */
020    
021    package es.ucm.fdi.gaia.ontobridge;
022    
023    import java.util.Iterator;
024    import java.util.LinkedList;
025    import java.util.List;
026    
027    import com.hp.hpl.jena.ontology.OntModel;
028    import com.hp.hpl.jena.query.Query;
029    import com.hp.hpl.jena.query.QueryExecution;
030    import com.hp.hpl.jena.query.QueryExecutionFactory;
031    import com.hp.hpl.jena.query.QueryFactory;
032    import com.hp.hpl.jena.query.QuerySolution;
033    import com.hp.hpl.jena.query.ResultSet;
034    import com.hp.hpl.jena.query.ResultSetFormatter;
035    import com.hp.hpl.jena.rdf.model.Model;
036    
037    /**
038     * This class allows to ask SPARQL queries to the reasoner
039     * @author Antonio A. Sánchez Ruiz-Granados
040     */
041    public class SPARQL {
042            
043            private OntModel ONT_MODEL;
044            
045            public SPARQL(OntoBridge ob){
046                    ONT_MODEL = ob.getModel();
047            }
048            
049            /**************************************************************/
050            /*                SPARQL queries                              */
051            /**************************************************************/
052    
053            /**
054             * Executes a SPARQL query of type ASK (boolean query). Returns true 
055             * if the query has any results and false if there are no matches.
056             */
057            public boolean execAskQuery(String queryStr) {
058                    // Create a new query
059                    Query query = QueryFactory.create(queryStr);
060    
061                    // Execute the query and obtain results
062                    QueryExecution qe = QueryExecutionFactory.create(query, ONT_MODEL);
063                    boolean res = qe.execAsk();
064    
065                    // Important - free up resources used running the query
066                    qe.close();
067                    
068                    return res;
069            }
070            
071            /**
072             * Executes a SPARQL query of type SELECT and returns an iterator over 
073             * the solutions. This method creates a list in memory with all the 
074             * results so it must be use carefully. A query with a lot of results can 
075             * exhaust the memory.
076             * 
077             * To make a select query without taken care of memory, the next template 
078             * must be used:
079             * <pre>
080             *              // Create a new query
081             *              Query query = QueryFactory.create(queryStr);
082             *
083             *              // Execute the query and obtain results
084             *              QueryExecution qe = QueryExecutionFactory.create(query, ONT_MODEL);
085             *              ResultSet results = qe.execSelect();
086             *
087             *              // Use the results as needed...
088             *              QuerySolution sol;
089             *              while(results.hasNext()) {
090             *                      sol = results.nextSolution();
091             *                      ...;
092             *              }
093             *
094             *              // Important - free up resources used running the query
095             *              qe.close();
096             * </pre>
097             */
098            public Iterator<QuerySolution> execSelectQuery(String queryStr) {
099                    // Create a new query
100                    Query query = QueryFactory.create(queryStr);
101    
102                    // Execute the query and obtain results
103                    QueryExecution qe = QueryExecutionFactory.create(query, ONT_MODEL);
104                    ResultSet results = qe.execSelect();
105                    
106                    // Copy the results to a list.
107                    List<QuerySolution> res = new LinkedList<QuerySolution>();
108                    while(results.hasNext())
109                            res.add(results.nextSolution());
110    
111                    // Important - free up resources used running the query
112                    qe.close();
113                    
114                    return res.iterator();
115            }
116            
117            /**
118             * Executes a SPARQL query of type SELECT and prints the result as a table 
119             * in the specified stream (usually System.out)
120             */
121            public void execSelectQueryAndPrint(String queryStr, java.io.PrintStream outStream) {
122                    // Create a new query
123                    Query query = QueryFactory.create(queryStr);
124    
125                    // Execute the query and obtain results
126                    QueryExecution qe = QueryExecutionFactory.create(query, ONT_MODEL);
127                    ResultSet results = qe.execSelect();
128                    
129                    // Output query results 
130                    ResultSetFormatter.out(outStream, results, query);
131    
132                    // Important - free up resources used running the query
133                    qe.close();
134            }
135    
136            /**
137             * Executes a SPARQL query of type CONSTRUCT and returns a new model 
138             * with the results.
139             */
140            public Model execConstructQuery(String queryStr) {
141                    // Create a new query
142                    Query query = QueryFactory.create(queryStr);
143    
144                    // Execute the query and obtain results
145                    QueryExecution qe = QueryExecutionFactory.create(query, ONT_MODEL);
146                    Model model = qe.execConstruct();
147                    
148                    // Important - free up resources used running the query
149                    qe.close();
150                    
151                    return model;
152            }
153            
154            /**
155             * Executes a SPARQL query of type DESCRIBE and returns a new model 
156             * with the results.
157             * 
158             * The DESCRIBE query returns a single result RDF graph containing RDF 
159             * data about resources. This data is not prescribed by a SPARQL query, 
160             * where the query client would need to know the structure of the RDF in 
161             * the data source, but, instead, is determined by the SPARQL query 
162             * processor. The query pattern is used to create a result set. 
163             * The DESCRIBE  form takes each of the resources identified in a solution, 
164             * together with any resources directly named by IRI, and assembles a single 
165             * RDF graph by taking a "description" from the target knowledge base. 
166             * The description is determined by the query service. The syntax DESCRIBE * 
167             * is an abbreviation that identifies all of the variables in a query.
168             */
169            public Model execDescribeQuery(String queryStr) {
170                    // Create a new query
171                    Query query = QueryFactory.create(queryStr);
172    
173                    // Execute the query and obtain results
174                    QueryExecution qe = QueryExecutionFactory.create(query, ONT_MODEL);
175                    Model model = qe.execDescribe();
176                    
177                    // Important - free up resources used running the query
178                    qe.close();
179                    
180                    return model;
181            }       
182    }