001: /*
002: * LICENSE INFORMATION
003: * Copyright 2005-2007 by FZI (http://www.fzi.de).
004: * Licensed under a BSD license (http://www.opensource.org/licenses/bsd-license.php)
005: * <OWNER> = Max Völkel
006: * <ORGANIZATION> = FZI Forschungszentrum Informatik Karlsruhe, Karlsruhe, Germany
007: * <YEAR> = 2007
008: *
009: * Project information at http://semweb4j.org/rdf2go
010: */
011: package org.ontoware.rdf2go.model;
012:
013: import org.ontoware.aifbcommons.collection.ClosableIterable;
014: import org.ontoware.rdf2go.exception.MalformedQueryException;
015: import org.ontoware.rdf2go.exception.ModelRuntimeException;
016: import org.ontoware.rdf2go.exception.QueryLanguageNotSupportedException;
017:
018: /**
019: * Interface for SPARQL and other query languages.
020: *
021: * @author voelkel
022: *
023: */
024: public interface Sparqlable {
025:
026: /**
027: * returns results for SPARQL Select queries, as supported by underlying
028: * implementation. For some implementations (Sesame) it is urgently
029: * necessary to iterate over all statements of the returned iterator in
030: * order to close resources properly.
031: *
032: * Iterator must be auto-close, i.e. when last element is fetched, the
033: * implementation must call close().
034: *
035: * @param queryString
036: * The SPARQL select query string
037: * @return a QueryResultTable
038: * @throws ModelRuntimeException
039: * if an error happens when executing the query
040: * @throws MalformedQueryException
041: * if the query is not a valid SPARQL SELECT query
042: */
043: QueryResultTable sparqlSelect(String queryString)
044: throws MalformedQueryException, ModelRuntimeException;
045:
046: /**
047: * returns results for queries in other query languages as a
048: * QueryResultTable as supported by underlying implementation. For some
049: * implementations (Sesame) it is urgently necessary to iterate over all
050: * statements of the returned iterator in order to close resources properly.
051: *
052: * Iterator must be auto-close, i.e. when last element is fetched, the
053: * implementation must call close().
054: *
055: * @param queryString
056: * The select query string
057: * @return a QueryResultTable
058: * @throws ModelRuntimeException
059: * if the execution throws an exception
060: * @throws QueryLanguageNotSupportedException
061: * if the given query langauge is not supported
062: * @throws MalformedQueryException
063: * if the query is not a valid query in the given query language
064: */
065: QueryResultTable querySelect(String query, String querylanguage)
066: throws QueryLanguageNotSupportedException,
067: MalformedQueryException, ModelRuntimeException;
068:
069: /**
070: * @return results for SPARQL Construct queries, as supported by underlying
071: * implementation.
072: *
073: * Iterator is auto-close, i.e. when last element is fetched, the
074: * implementation must call close().
075: *
076: * @throws ModelRuntimeException
077: * if the execution throws an exception
078: * @throws MalformedQueryException
079: * if the query is not a valid SPARQL CONSTRUCT query
080: */
081: ClosableIterable<Statement> sparqlConstruct(String query)
082: throws ModelRuntimeException, MalformedQueryException;
083:
084: /**
085: * @return results for other construct-like queries, as supported by
086: * underlying implementation.
087: *
088: * Iterator is auto-close, i.e. when last element is fetched, the
089: * implementation must call close().
090: * @param query
091: * @param querylanguage
092: * @throws ModelRuntimeException
093: * if the execution throws an exception
094: * @throws QueryLanguageNotSupportedException
095: * if the adapter can't understand the given query language
096: * @throws MalformedQueryException
097: * if the query is not a valid construct query in the given
098: * query language
099: */
100: ClosableIterable<Statement> queryConstruct(String query,
101: String querylanguage)
102: throws QueryLanguageNotSupportedException,
103: MalformedQueryException, ModelRuntimeException;
104:
105: /**
106: * SPARQL ask queries
107: *
108: * @param query
109: * a SPARQL AKS query
110: * @return the query result as true or false
111: * @throws ModelRuntimeException
112: * if the execution throws an exception
113: * @throws MalformedQueryException
114: * if the query is not a valid SPARQL ASK query
115: */
116: boolean sparqlAsk(String query) throws ModelRuntimeException,
117: MalformedQueryException;
118:
119: /**
120: * Iterator must be auto-close, i.e. when last element is fetched, the
121: * implementation must call close(). This means a regular user can call this
122: * method without calling close(), if all elements are consumed.
123: *
124: * @param query
125: * @return a ClosableIterable over all statements returned by this query
126: * @throws ModelRuntimeException
127: * if the execution throws an exception
128: * @throws MalformedQueryException
129: * if the query is not a valid SPARQL DESCRIBE query
130: */
131: ClosableIterable<Statement> sparqlDescribe(String query)
132: throws ModelRuntimeException;
133:
134: }
|