| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package org.apache.jena.arq.querybuilder.clauses; |
| |
| import java.util.Collection; |
| import java.util.List; |
| import java.util.Map; |
| |
| import org.apache.jena.arq.querybuilder.AbstractQueryBuilder; |
| import org.apache.jena.arq.querybuilder.ExprFactory; |
| import org.apache.jena.arq.querybuilder.SelectBuilder; |
| import org.apache.jena.arq.querybuilder.handlers.WhereHandler; |
| import org.apache.jena.graph.FrontsTriple; |
| import org.apache.jena.graph.Node; |
| import org.apache.jena.graph.Triple; |
| import org.apache.jena.sparql.core.TriplePath; |
| import org.apache.jena.sparql.core.Var; |
| import org.apache.jena.sparql.expr.Expr; |
| import org.apache.jena.sparql.lang.sparql_11.ParseException; |
| |
| /** |
| * Interface that defines the WhereClause as per |
| * http://www.w3.org/TR/2013/REC-sparql11-query-20130321/#rWhereClause |
| * |
| * @param <T> |
| * The Builder type that the clause is part of. |
| */ |
| public interface WhereClause<T extends AbstractQueryBuilder<T>> { |
| |
| /** |
| * Adds a triple to the where clause. |
| * |
| * @param t |
| * The triple path to add |
| * @return This Builder for chaining. |
| */ |
| public T addWhere(Triple t); |
| |
| /** |
| * Adds a triple path to the where clause. |
| * |
| * @param t |
| * The triple path to add |
| * @return This Builder for chaining. |
| */ |
| public T addWhere(TriplePath t); |
| |
| /** |
| * Adds a triple to the where clause. |
| * |
| * @param t |
| * The triple to add |
| * @return This Builder for chaining. |
| */ |
| public T addWhere(FrontsTriple t); |
| |
| /** |
| * Adds a triple or triple path to the where clause. |
| * |
| * See {@link AbstractQueryBuilder#makeTriplePath} for conversion of the |
| * param values. |
| * |
| * @param s |
| * The subject. |
| * @param p |
| * The predicate. |
| * @param o |
| * The object. |
| * @return This Builder for chaining. |
| */ |
| public T addWhere(Object s, Object p, Object o); |
| |
| /** |
| * Adds the elements from the whereClause to this where Clause. |
| * |
| * @param whereClause |
| * The whereClause to add to this statement. |
| * @return This Builder for chaining. |
| */ |
| public T addWhere( AbstractQueryBuilder<?> whereClause); |
| |
| /** |
| * Add a variable or variable and values to the value statement. |
| * |
| * The first var (or first item in a collection) is converted to a variable using |
| * the makeVar strategy. A variable may be added multiple times, doing so |
| * will append values to the list of variable values. The order in which variables |
| * are added to the values table is preserved. |
| * |
| * Adding a collection as the var will use the first object in the collection as |
| * the var and the remaining objects as values. |
| * |
| * Values are created using makeNode() strategy except that null values are converted |
| * to UNDEF. |
| * |
| * @param var |
| * The variable or collection to add. |
| * @return The builder for chaining. |
| * @see AbstractQueryBuilder#makeNode(Object) |
| * @see AbstractQueryBuilder#makeVar(Object) |
| */ |
| public T addWhereValueVar(Object var); |
| |
| /** |
| * Add a variable and values to the value statement. |
| * |
| * The var is converted to a variable using |
| * the makeVar strategy. A variable may be added multiple times, doing so |
| * will append values to the list of variable values. The order in which variables |
| * are added to the values table is preserved. |
| * |
| * Values are created using makeNode() strategy except that null values are converted |
| * to UNDEF. |
| * |
| * @param var |
| * The variable to add. |
| * @param values The values for the variable |
| * @return The builder for chaining. |
| * @see AbstractQueryBuilder#makeNode(Object) |
| * @see AbstractQueryBuilder#makeVar(Object) |
| */ |
| public T addWhereValueVar(Object var, Object... values); |
| |
| |
| /** |
| * Add a data table to the value statement. |
| * |
| * Each key in the map is used converted into a variable using the makeVar strategy. |
| * The order in which variables are added to the values table is preserved. |
| * |
| * Variables are added in the iteration order for the map. It may be advisable to |
| * use a LinkedHashMap to preserver the insert order. |
| * |
| * @see java.util.LinkedHashMap |
| * |
| * Each item in the value collection is converted into a node using makeNode() strategy except that null values are converted |
| * to UNDEF. |
| * |
| * If there are already values in the value statement the data table is adds as follows: |
| * <ul> |
| * <li>If the variable already exists in the table the map values are appended to the list of values</li> |
| * <li>If the variable does not exist in the table and there are other variables defined, an appropriate |
| * number of nulls is added to the front of the map values to create UNDEF entries for the existing rows</li> |
| * <li>If there are variables in the value statement that are not specified in the map additional UNDEF |
| * entries are appended to them to account for new rows that are added.</li> |
| * </ul> |
| * |
| * @param dataTable |
| * The data table to add. |
| * @return The builder for chaining. |
| * @see AbstractQueryBuilder#makeNode(Object) |
| * @see AbstractQueryBuilder#makeVar(Object) |
| */ |
| public <K extends Collection<?>> T addWhereValueVars(Map<?,K> dataTable); |
| |
| |
| /** |
| * Add objects as a row of values. This method is different from the other methods in that |
| * the values are appended to each of the variables in the clause. There must be |
| * sufficient entries in the list to provide data for each variable in the table. |
| * Values objects are converted to nodes using the makeNode strategy. Variables will always |
| * be in the order added to the values table. |
| * |
| * @param values |
| * the collection of values to add. |
| * @return The builder for chaining. |
| * @see AbstractQueryBuilder#makeNode(Object) |
| */ |
| public T addWhereValueRow(Object... values); |
| |
| /** |
| * Add a collection of objects as row of values. This method is different from the other methods in that |
| * the values are appended to each of the variables in the clause. There must be |
| * sufficient entries in the list to provide data for each variable in the table. |
| * Values objects are converted to nodes using the makeNode strategy. Variables will always |
| * be in the order added to the values table. |
| * |
| * @param values |
| * the collection of values to add. |
| * @return The builder for chaining. |
| * @see AbstractQueryBuilder#makeNode(Object) |
| */ |
| public T addWhereValueRow(Collection<?> values); |
| |
| /** |
| * Get an unmodifiable list of vars from the where clause values in the order that they appear |
| * in the values table. |
| * @return an unmodifiable list of vars. |
| */ |
| public List<Var> getWhereValuesVars(); |
| |
| /** |
| * Get an unmodifiable map of vars from the where clause values and their values. |
| * |
| * Null values are considered as UNDEF values. |
| * |
| * @return an unmodifiable map of vars and their values. |
| */ |
| public Map<Var,List<Node>> getWhereValuesMap(); |
| |
| /** |
| * Reset the values table in the where clause to the initial |
| * undefined state. Used primarily to reset the builder values |
| * table to a known state. |
| */ |
| public T clearWhereValues(); |
| |
| /** |
| * Adds an optional triple to the where clause. |
| * |
| * @param t |
| * The triple to add |
| * @return This Builder for chaining. |
| */ |
| public T addOptional(Triple t); |
| |
| /** |
| * Adds an optional triple path to the where clause. |
| * |
| * @param t |
| * The triple path to add |
| * @return This Builder for chaining. |
| */ |
| public T addOptional(TriplePath t); |
| |
| /** |
| * Adds an optional triple as to the where clause. |
| * |
| * @param t |
| * The triple to add |
| * @return This Builder for chaining. |
| */ |
| public T addOptional(FrontsTriple t); |
| |
| /** |
| * Adds an optional triple or triple path to the where clause. |
| * |
| * See {@link AbstractQueryBuilder#makeTriplePath} for conversion of the |
| * param values. |
| * |
| * @param s |
| * The subject. |
| * @param p |
| * The predicate. |
| * @param o |
| * The object. |
| * @return This Builder for chaining. |
| */ |
| public T addOptional(Object s, Object p, Object o); |
| |
| /** |
| * Adds an optional group pattern to the where clause. |
| * |
| * @param t |
| * The select builder to add as an optional pattern |
| * @return This Builder for chaining. |
| */ |
| public T addOptional(AbstractQueryBuilder<?> t); |
| |
| /** |
| * Adds a filter to the where clause |
| * |
| * @param expression |
| * the expression to evaluate for the filter. |
| * @return @return This Builder for chaining. |
| * @throws ParseException |
| * If the expression can not be parsed. |
| */ |
| public T addFilter(String expression) throws ParseException; |
| |
| /** |
| * Adds a filter to the where clause |
| * |
| * Use ExprFactory or NodeValue static or the AbstractQueryBuilder.makeExpr |
| * methods to create the expression. |
| * |
| * @see ExprFactory |
| * @see org.apache.jena.sparql.expr.NodeValue |
| * @see AbstractQueryBuilder#makeExpr(String) |
| * |
| * @param expression |
| * the expression to evaluate for the filter. |
| * @return @return This Builder for chaining. |
| */ |
| public T addFilter(Expr expression); |
| |
| /** |
| * Add a sub query. |
| * |
| * @param subQuery |
| * The subquery as defined by a SelectBuilder. |
| * @return This builder for chaining. |
| */ |
| public T addSubQuery(AbstractQueryBuilder<?> subQuery); |
| |
| /** |
| * Add a union. |
| * |
| * @param union |
| * The union as defined by a SelectBuilder. |
| * @return This builder for chaining. |
| */ |
| public T addUnion(AbstractQueryBuilder<?> union); |
| |
| /** |
| * Add a graph statement to the query as per |
| * http://www.w3.org/TR/2013/REC-sparql11 |
| * -query-20130321/#rGraphGraphPattern. |
| * |
| * See {@link AbstractQueryBuilder#makeNode} for conversion of the graph |
| * param. |
| * |
| * @param graph |
| * The iri or variable identifying the graph. |
| * @param subQuery |
| * The graph to add. |
| * @return This builder for chaining. |
| */ |
| public T addGraph(Object graph, AbstractQueryBuilder<?> subQuery); |
| |
| /** |
| * Add a graph statement to the query as per |
| * http://www.w3.org/TR/2013/REC-sparql11 |
| * -query-20130321/#rGraphGraphPattern. |
| * |
| * See {@link AbstractQueryBuilder#makeNode} for conversion of the graph |
| * param. |
| * |
| * @param graph |
| * The iri or variable identifying the graph. |
| * @param triple |
| * a single s, p, o triple for the query. |
| * @return This builder for chaining. |
| */ |
| public T addGraph(Object graph, FrontsTriple triple); |
| /** |
| * Add a graph statement to the query as per |
| * http://www.w3.org/TR/2013/REC-sparql11 |
| * -query-20130321/#rGraphGraphPattern. |
| * |
| * See {@link AbstractQueryBuilder#makeNode} for conversion of the graph |
| * param. |
| * |
| * @param graph |
| * The iri or variable identifying the graph. |
| * @param subject The subject for the graph query |
| * @param predicate The predicate for the graph query. |
| * @param object The object for the graph query. |
| * @return This builder for chaining. |
| */ |
| public T addGraph(Object graph, Object subject, Object predicate, Object object); |
| /** |
| * Add a graph statement to the query as per |
| * http://www.w3.org/TR/2013/REC-sparql11 |
| * -query-20130321/#rGraphGraphPattern. |
| * |
| * See {@link AbstractQueryBuilder#makeNode} for conversion of the graph |
| * param. |
| * |
| * @param graph |
| * The iri or variable identifying the graph. |
| * @param triple |
| * a single triple for the query. |
| * @return This builder for chaining. |
| */ |
| public T addGraph(Object graph, Triple triple); |
| /** |
| * Add a graph statement to the query as per |
| * http://www.w3.org/TR/2013/REC-sparql11 |
| * -query-20130321/#rGraphGraphPattern. |
| * |
| * See {@link AbstractQueryBuilder#makeNode} for conversion of the graph |
| * param. |
| * |
| * @param graph |
| * The iri or variable identifying the graph. |
| * @param triplePath |
| * a single triple path for the query. |
| * @return This builder for chaining. |
| */ |
| public T addGraph(Object graph, TriplePath triplePath); |
| /** |
| * Add a bind statement to the query * |
| * http://www.w3.org/TR/2013/REC-sparql11-query-20130321/#rGraphGraphPattern. |
| * |
| * @param expression |
| * The expression to bind to the var. |
| * @param var |
| * The variable to bind to. |
| * @return This builder for chaining. |
| */ |
| public T addBind(Expr expression, Object var); |
| |
| /** |
| * Add a bind statement to the query |
| * http://www.w3.org/TR/2013/REC-sparql11-query-20130321/#rGraphGraphPattern. |
| * |
| * @param expression |
| * The expression to bind to the var. |
| * @param var |
| * The variable to bind to. |
| * @return This builder for chaining. |
| * @throws ParseException |
| */ |
| public T addBind(String expression, Object var) throws ParseException; |
| |
| /** |
| * Get the Where handler for this clause. |
| * |
| * @return The WhereHandler used by this clause. |
| */ |
| public WhereHandler getWhereHandler(); |
| |
| /** |
| * Create a list node from a list of objects as per RDF Collections. |
| * |
| * http://www.w3.org/TR/2013/REC-sparql11-query-20130321/#collections |
| * |
| * See {@link AbstractQueryBuilder#makeNode} for conversion of the param |
| * values. |
| * <p> |
| * usage: |
| * <ul> |
| * <li>list( param1, param2, param3, ... )</li> |
| * <li>addWhere( list( param1, param2, param3, ... ), p, o )</li> |
| * <li>addOptional( list( param1, param2, param3, ... ), p, o )</li> |
| * </ul> |
| * </p> |
| * |
| * @param objs |
| * the list of objects for the list. |
| * @return the first blank node in the list. |
| */ |
| public Node list(Object... objs); |
| |
| /** |
| * Add a minus clause to the query. |
| * |
| * https://www.w3.org/TR/2013/REC-sparql11-query-20130321/#rMinusGraphPattern |
| * |
| * @param t |
| * The select builder to add as a minus pattern |
| * @return this builder for chaining |
| */ |
| public T addMinus(AbstractQueryBuilder<?> t); |
| |
| } |