You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jena.apache.org by sa...@apache.org on 2012/04/24 03:40:20 UTC
svn commit: r1329525 - in
/incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client:
Connection.java QueryParameterizer.java QueryStatement.java
SPARQLException.java http/SparqlHttpConnection.java
Author: sallen
Date: Tue Apr 24 01:40:20 2012
New Revision: 1329525
URL: http://svn.apache.org/viewvc?rev=1329525&view=rev
Log:
jena-client Query parameterization interface.
Added:
incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/QueryParameterizer.java
incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/QueryStatement.java
incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/SPARQLException.java
Modified:
incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/Connection.java
incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/http/SparqlHttpConnection.java
Modified: incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/Connection.java
URL: http://svn.apache.org/viewvc/incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/Connection.java?rev=1329525&r1=1329524&r2=1329525&view=diff
==============================================================================
--- incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/Connection.java (original)
+++ incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/Connection.java Tue Apr 24 01:40:20 2012
@@ -23,12 +23,13 @@ import org.apache.jena.client.service.Se
import org.apache.jena.client.service.UpdateService;
import org.openjena.atlas.lib.Closeable;
+import com.hp.hpl.jena.query.Query;
import com.hp.hpl.jena.query.QueryExecution;
import com.hp.hpl.jena.sparql.core.Transactional;
import com.hp.hpl.jena.update.UpdateProcessor;
/**
- * A connection to a specific repository. SPARQL statements are executed and results returned within the context of a connection.
+ * A connection (session) with a specific repository. SPARQL statements are executed and results returned within the context of a connection.
*/
public interface Connection extends Transactional, Closeable
{
@@ -63,12 +64,15 @@ public interface Connection extends Tran
BulkDataHandler getBulkDataHandler();
// TODO stick with legacy query execution/update interfaces, or create new?
+ QueryStatement createQueryStatement(String queryString);
+ QueryStatement createQueryStatement(Query query);
+
QueryExecution createQuery(String query);
UpdateProcessor createUpdate(String updateQuery);
// TODO make ParameterizedQueryExecution and ParameterizedUpdateProcessor
QueryExecution createParameterizedQuery(String query);
- UpdateProcessor createPparameterizedUpdate(String updateQuery);
+ UpdateProcessor createParameterizedUpdate(String updateQuery);
Updater createBulkUpdater();
Added: incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/QueryParameterizer.java
URL: http://svn.apache.org/viewvc/incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/QueryParameterizer.java?rev=1329525&view=auto
==============================================================================
--- incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/QueryParameterizer.java (added)
+++ incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/QueryParameterizer.java Tue Apr 24 01:40:20 2012
@@ -0,0 +1,193 @@
+package org.apache.jena.client;
+
+import java.net.URL;
+import java.util.Calendar;
+
+import org.apache.jena.iri.IRI;
+
+import com.hp.hpl.jena.datatypes.RDFDatatype;
+import com.hp.hpl.jena.graph.Node;
+import com.hp.hpl.jena.rdf.model.Literal;
+import com.hp.hpl.jena.rdf.model.RDFNode;
+
+/**
+ * Replaces variables in a query string with parameters specified via the {@code set*} methods.
+ */
+interface QueryParameterizer
+{
+ /**
+ * Clears the value for a parameter so the given variable will not have a value injected.
+ * @param var Variable
+ */
+ void clearParam(String var);
+
+ /**
+ * Clears all parameter values.
+ */
+ void clearParams();
+
+ /**
+ * Sets a Parameter
+ * @param var Variable
+ * @param node Value
+ * <p>
+ * Setting a parameter to null is equivalent to calling {@link #clearParam(String)} for the given variable
+ * </p>
+ */
+ void setParam(String var, Node node);
+
+ /**
+ * Sets a Parameter
+ * @param var Variable
+ * @param node Value
+ * <p>
+ * Setting a parameter to null is equivalent to calling {@link #clearParam(String)} for the given variable
+ * </p>
+ */
+ void setParam(String var, RDFNode node);
+
+ /**
+ * Sets a Parameter to an IRI
+ * @param var Variable
+ * @param iri IRI
+ * <p>
+ * Setting a parameter to null is equivalent to calling {@link #clearParam(String)} for the given variable
+ * </p>
+ */
+ void setIri(String var, String iri);
+
+ /**
+ * Sets a Parameter to an IRI
+ * @param var Variable
+ * @param iri IRI
+ * <p>
+ * Setting a parameter to null is equivalent to calling {@link #clearParam(String)} for the given variable
+ * </p>
+ */
+ void setIri(String var, IRI iri);
+
+ /**
+ * Sets a Parameter to an IRI
+ * @param var Variable
+ * @param url URL used as IRI
+ * <p>
+ * Setting a parameter to null is equivalent to calling {@link #clearParam(String)} for the given variable
+ * </p>
+ */
+ void setIri(String var, URL url);
+
+ /**
+ * Sets a Parameter to a Literal
+ * @param var Variable
+ * @param lit Value
+ * <p>
+ * Setting a parameter to null is equivalent to calling {@link #clearParam(String)} for the given variable
+ * </p>
+ */
+ void setLiteral(String var, Literal lit);
+
+ /**
+ * Set a Parameter to a literal
+ * @param var Variable
+ * @param value Lexical Value
+ * <p>
+ * Setting a parameter to null is equivalent to calling {@link #clearParam(String)} for the given variable
+ * </p>
+ */
+ void setLiteral(String var, String value);
+
+ /**
+ * Sets a Parameter to a literal with a language
+ * @param var Variable
+ * @param value Lexical Value
+ * @param lang Language
+ * <p>
+ * Setting a parameter to null is equivalent to calling {@link #clearParam(String)} for the given variable
+ * </p>
+ */
+ void setLiteral(String var, String value, String lang);
+
+ /**
+ * Sets a Parameter to a typed literal
+ * @param var Variable
+ * @param value Lexical Value
+ * @param datatype Datatype
+ * <p>
+ * Setting a parameter to null is equivalent to calling {@link #clearParam(String)} for the given variable
+ * </p>
+ */
+ void setLiteral(String var, String value, RDFDatatype datatype);
+
+ /**
+ * Sets a Parameter to a boolean literal
+ * @param var a variable, by name.
+ * @param value boolean
+ */
+ void setLiteral(String var, boolean value);
+
+ /**
+ * Sets a Parameter to an integer literal
+ * @param var Variable
+ * @param i Integer Value
+ */
+ void setLiteral(String var, int i);
+
+ /**
+ * Sets a Parameter to an integer literal
+ * @param var Variable
+ * @param l Integer Value
+ */
+ void setLiteral(String var, long l);
+
+ /**
+ * Sets a Parameter to a float literal
+ * @param var Variable
+ * @param f Float value
+ */
+ void setLiteral(String var, float f);
+
+ /**
+ * Sets a Parameter to a double literal
+ * @param var Variable
+ * @param d Double value
+ */
+ void setLiteral(String var, double d);
+
+ /**
+ * Sets a Parameter to a date time literal. The {@code Calendar} parameter
+ * is converted to an XSDDateTime in the query.
+ * @param var Variable
+ * @param dt Date Time value
+ */
+ void setLiteral(String var, Calendar dt);
+
+
+ /**
+ * Clears any raw string parameters.
+ */
+ void clearRawStrings();
+
+ /**
+ * Replaces parameters specified with Java <em>format specifiers</em> with properly escaped
+ * versions of the arguments passed in. This is useful for properly escaping variables
+ * that must appear inside of string literals.
+ * <p/>
+ * <p/>
+ * Example (developer wants to replace %1$s with a user-inputed string):
+ * <pre>
+ * {@code FILTER regex(?name, "^%1$s", "i") }
+ * </pre>
+ *
+ * @param args
+ * Arguments referenced by the format specifiers in the
+ * <a href="http://docs.oracle.com/javase/6/docs/api/java/util/Formatter.html#syntax">
+ * format string</a>. If there are more arguments than format specifiers, the
+ * extra arguments are ignored. The number of arguments is variable and may be zero.
+ *
+ * @see java.util.Formatter
+ */
+ // TODO Maybe using java.util.Formatter is too general to use here.
+ // TODO Do we need to specify the order in which this occurs? (before or after the setParam methods)
+ // TODO The implementation of this method will need extra scrutiny to make sure it doesn't allow SPARQL-injection attacks
+ void setRawStrings(String... args);
+}
Added: incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/QueryStatement.java
URL: http://svn.apache.org/viewvc/incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/QueryStatement.java?rev=1329525&view=auto
==============================================================================
--- incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/QueryStatement.java (added)
+++ incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/QueryStatement.java Tue Apr 24 01:40:20 2012
@@ -0,0 +1,129 @@
+package org.apache.jena.client;
+
+import java.util.Iterator;
+import java.util.concurrent.TimeUnit;
+
+import com.hp.hpl.jena.graph.Triple;
+import com.hp.hpl.jena.query.ResultSet;
+import com.hp.hpl.jena.rdf.model.Model;
+
+
+/**
+ *
+ *
+ * @see Connection#createQueryStatement
+ * @see ResultSet
+ */
+public interface QueryStatement extends QueryParameterizer
+{
+ /**
+ * Retrieves the {@link Connection} object that produced this <code>QueryStatement</code> object.
+ * @return the connection that produced this statement
+ * @throws SPARQLException if a database access error occurs or this method is called on a closed <code>QueryStatement</code>
+ */
+ Connection getConnection();
+
+ /**
+ * Execute a SELECT query.
+ *
+ * @return
+ */
+ ResultSet execSelect();
+
+ /**
+ * Execute a CONSTRUCT query, putting the statements into a newly created memory model.
+ * @return an in-memory model containing the results of the CONSTRUCT query
+ */
+ Model execConstruct();
+
+ /**
+ * Execute a CONSTRUCT query, putting the statements into <code>model</code>.
+ * @param model the model to put the statements into
+ * @return the <code>model</code> argument that was passed in as a parameter,
+ * augmented by the addition of any results from the CONSTRUCT query
+ */
+ Model execConstruct(Model model);
+
+ /**
+ * Execute a CONSTRUCT query, returning the results as an iterator of {@link Triple}.
+ * <p/>
+ * <b>Caution:</b> This method may return duplicate Triples (which could be useful if you only
+ * need the results for stream processing, as it can avoid having to place the results in a Model).
+ *
+ * @return An iterator of Triple objects (possibly containing duplicates) generated
+ * by applying the CONSTRUCT template of the query to the bindings in the WHERE clause.
+ */
+ Iterator<Triple> execConstructTriples();
+
+ /** Execute a DESCRIBE query */
+
+ /**
+ * Execute a DESCRIBE query, putting the statements into a newly created memory model.
+ * @return an in-memory model containing the results of the DESCRIBE query
+ */
+ Model execDescribe();
+
+ /**
+ * Execute a DESCRIBE query, putting the statements into <code>model</code>.
+ * @param model the model to put the statements into
+ * @return the <code>model</code> argument that was passed in as a parameter,
+ * augmented by the addition of any results from the DESCRIBE query
+ */
+ Model execDescribe(Model model);
+
+ /**
+ * Execute an ASK query.
+ * @return a <code>boolean</code> corresponding to the result of the ASK query
+ */
+ boolean execAsk();
+
+ /**
+ * Cancels this <code>QueryStatement</code> object mid-execution if the implementation supports it.
+ * This method can be called by a different thread that is currently executing the query. There
+ * is no guarantee that the concrete implementation actually will stop or that it will do so immediately.
+ * No operations on the query execution or any associated result set are permitted after this call
+ * and may cause exceptions to be thrown.
+ */
+ void cancel();
+
+ // TODO need to update the implementations to follow the timeout behavior specified here, specifically the zero and negative timeout
+ /**
+ * Set the number of milliseconds to wait for a <code>QueryStatement</code> to return the first result.
+ * @param timeout the new query timeout limit in milliseconds; zero or a negative number means there is no limit
+ * @see #setTimeout(long, TimeUnit)
+ */
+ void setTimeout(long timeout);
+
+ /**
+ * Set the amount of time to wait for a <code>QueryStatement</code> to return the first result.
+ * @param timeout the new query timeout limit in <code>timeoutUnits</code>; zero or a negative number means there is no limit
+ * @param timeoutUnits the time units in which <code>timeout</code> is specified
+ */
+ void setTimeout(long timeout, TimeUnit timeoutUnits);
+
+ /**
+ * Set the number of milliseconds to wait for execution; the first timeout refers to time to first result, the second
+ * refers to overall query execution after the first result. Processing will be aborted if a timeout expires.
+ * @param timeout1 the new timeout limit for the first result in milliseconds; zero or a negative number means there is no limit
+ * @param timeout2 the new timeout limit for the total execution time in milliseconds; zero or a negative number means there is no limit
+ */
+ void setTimeout(long timeout1, long timeout2);
+
+ /**
+ * Set timeouts on the query execution; the first timeout refers to time to first result, the second
+ * refers to overall query execution after the first result. Processing will be aborted if a timeout expires.
+ * @param timeout1 the new timeout limit for the first result in <code>timeUnit1</code>; zero or a negative number means there is no limit
+ * @param timeUnit1 the time units in which <code>timeout1</code> is specified
+ * @param timeout2 the new timeout limit for the total execution time in <code>timeUnit2</code>; zero or a negative number means there is no limit
+ * @param timeUnit2 the time units in which <code>timeUnit2</code> is specified
+ */
+ void setTimeout(long timeout1, TimeUnit timeUnit1, long timeout2, TimeUnit timeUnit2);
+
+
+ /**
+ * Returns the Query as a String.
+ * @return the query represented as a String.
+ */
+ @Override
+ String toString();
+}
Added: incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/SPARQLException.java
URL: http://svn.apache.org/viewvc/incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/SPARQLException.java?rev=1329525&view=auto
==============================================================================
--- incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/SPARQLException.java (added)
+++ incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/SPARQLException.java Tue Apr 24 01:40:20 2012
@@ -0,0 +1,14 @@
+package org.apache.jena.client;
+
+import com.hp.hpl.jena.sparql.ARQException;
+
+/**
+ * An Exception that provides information on a SPARQL database access error or other SPARQL error.
+ */
+public class SPARQLException extends ARQException
+{
+ public SPARQLException(String msg, Throwable cause) { super(msg, cause) ; }
+ public SPARQLException(String msg) { super(msg) ; }
+ public SPARQLException(Throwable cause) { super(cause) ; }
+ public SPARQLException() { super() ; }
+}
Modified: incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/http/SparqlHttpConnection.java
URL: http://svn.apache.org/viewvc/incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/http/SparqlHttpConnection.java?rev=1329525&r1=1329524&r2=1329525&view=diff
==============================================================================
--- incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/http/SparqlHttpConnection.java (original)
+++ incubator/jena/Experimental/jena-client/trunk/src/main/java/org/apache/jena/client/http/SparqlHttpConnection.java Tue Apr 24 01:40:20 2012
@@ -2,6 +2,7 @@ package org.apache.jena.client.http;
import org.apache.jena.client.BulkDataHandler;
import org.apache.jena.client.ConnectionBase;
+import org.apache.jena.client.QueryStatement;
import org.apache.jena.client.Repository;
import org.apache.jena.client.UpdateDeleter;
import org.apache.jena.client.UpdateInserter;
@@ -11,6 +12,7 @@ import org.apache.jena.client.service.Qu
import org.apache.jena.client.service.Service;
import org.apache.jena.client.service.UpdateService;
+import com.hp.hpl.jena.query.Query;
import com.hp.hpl.jena.query.QueryExecution;
import com.hp.hpl.jena.query.ReadWrite;
import com.hp.hpl.jena.update.UpdateProcessor;
@@ -187,7 +189,7 @@ public class SparqlHttpConnection extend
}
@Override
- public UpdateProcessor createPparameterizedUpdate(String updateQuery)
+ public UpdateProcessor createParameterizedUpdate(String updateQuery)
{
// TODO Auto-generated method stub
return null;
@@ -235,4 +237,18 @@ public class SparqlHttpConnection extend
}
+ @Override
+ public QueryStatement createQueryStatement(String queryString)
+ {
+ // TODO Auto-generated method stub
+ return null;
+ }
+
+ @Override
+ public QueryStatement createQueryStatement(Query query)
+ {
+ // TODO Auto-generated method stub
+ return null;
+ }
+
}