Package org.apache.jena.arq.querybuilder

Class AbstractQueryBuilder<T extends AbstractQueryBuilder<T>>

java.lang.Object
org.apache.jena.arq.querybuilder.AbstractQueryBuilder<T>
Type Parameters:
T - The derived class type. Used for return types.
All Implemented Interfaces:
Cloneable, PrologClause<T>, ValuesClause<T>
Direct Known Subclasses:
AskBuilder, ConstructBuilder, DescribeBuilder, SelectBuilder, WhereBuilder
public abstract class AbstractQueryBuilder<T extends AbstractQueryBuilder<T>> extends Object implements Cloneable, PrologClause<T>, ValuesClause<T>
Base class for all QueryBuilders.

  • Method Details

    • makeNode

      public Node makeNode(Object o)
      Make a Node from an object.
      • Will return Node.ANY if object is null.
      • Will return the enclosed Node from a FrontsNode
      • Will return the object if it is a Node.
      • Will call NodeFactoryExtra.parseNode() using the prefix mapping if the object is a String
      • Will create a literal representation if the parseNode() fails or for any other object type.
      Uses the internal query prefix mapping to resolve prefixes.
      Parameters:
      o - The object to convert. (may be null)
      Returns:
      The Node value.

    • makeNodeOrPath

      @Deprecated public static Object makeNodeOrPath(Object o, PrefixMapping pMapping)
      Deprecated.
      use Converters.makeNodeOrPath(Object, PrefixMapping)
      Creates a Path or Node as appropriate.
      • Will return Node.ANY if object is null.
      • Will return the object if it is a Path
      • Will return the enclosed Node from a FrontsNode
      • Will return the object if it is a Node.
      • Will call PathParser.parse() using the prefix mapping if the object is a String
      • Will call NodeFactoryExtra.parseNode() using the currently defined prefixes if the object is a String and the PathParser.parse() fails.
      • Will create a literal representation if the parseNode() fails or for any other object type.
      Parameters:
      o - the object that should be interpreted as a path or a node.
      pMapping - the prefix mapping to resolve path or node with
      Returns:
      the Path or Node

    • asSubQuery

      public ElementSubQuery asSubQuery()

    • makeTriplePath

      @Deprecated(since="5.0.0") public TriplePath makeTriplePath(Object s, Object p, Object o)
      Deprecated.
      Use makeTriplePaths(Object, Object, Object)
      Make a triple path from the objects. For subject, predicate and objects nodes
      • Will return Node.ANY if object is null.
      • Will return the enclosed Node from a FrontsNode
      • Will return the object if it is a Node.
      • If the object is a String
        • For predicate only will attempt to parse as a path
        • for subject, predicate and object will call NodeFactoryExtra.parseNode() using the currently defined prefixes if the object is a String
      • Will create a literal representation if the parseNode() fails or for any other object type.
      Parameters:
      s - The subject object
      p - the predicate object
      o - the object object.
      Returns:
      a TriplePath

    • makeTriplePaths

      public List<TriplePath> makeTriplePaths(Object s, Object p, Object o)
      Make a collecton triple path from the objects. For subject, predicate and objects nodes
      • Will return Node.ANY if object is null.
      • Will return the enclosed Node from a FrontsNode
      • Will return the object if it is a Node.
      • For subject and object only, if the object is a collection, will convert each item in the collection into a node and create an RDF list. All RDF list nodes are included in the collection.
      • If the object is a String
        • For predicate only, will attempt to parse as a path
        • for subject, predicate and object will call NodeFactoryExtra.parseNode() using the currently defined prefixes if the object is a String
      • Will create a literal representation if the parseNode() fails or for any other object type.
      Parameters:
      s - The subject object
      p - the predicate object
      o - the object object.
      Returns:
      a TriplePath

    • makeExpr

      public Expr makeExpr(String expression) throws QueryParseException
      A convenience method to make an expression from a string. Evaluates the expression with respect to the current query.
      Parameters:
      expression - The expression to parse.
      Returns:
      the Expr object.
      Throws:
      QueryParseException - on error.

    • quote

      @Deprecated public static String quote(String q)
      Deprecated.
      Converters.quoted(String)
      A convenience method to quote a string.
      Parameters:
      q - the string to quote. Will use single quotes if there are no single quotes in the string or if the double quote is before the single quote in the string. Will use double quote otherwise.
      Returns:
      the quoted string.

    • checkVar

      @Deprecated public static Node checkVar(Node n)
      Deprecated.
      use Converters.checkVar(Node)
      Verify that any Node_Variable nodes are returned as Var nodes.
      Parameters:
      n - the node to check
      Returns:
      the node n or a new Var if n is an instance of Node_Variable

    • makeNode

      @Deprecated public static Node makeNode(Object o, PrefixMapping pMapping)
      Deprecated.
      use Converters.makeNode(Object, PrefixMapping)
      Make a node from an object while using the associated prefix mapping.
      • Will return Node.ANY if object is null.
      • Will return the enclosed Node from a FrontsNode
      • Will return the object if it is a Node.
      • Will call NodeFactoryExtra.parseNode() using the currently defined prefixes if the object is a String
      • Will create a literal representation if the parseNode() fails or for any other object type.
      Parameters:
      o - The object to convert (may be null).
      pMapping - The prefix mapping to use for prefix resolution.
      Returns:
      The Node value.

    • makeVar

      @Deprecated public static Var makeVar(Object o) throws ARQInternalErrorException
      Deprecated.
      use Converters.makeVar(Object)
      Make a Var from an object.
      • Will return Var.ANON if object is null.
      • Will return null if the object is "*" or Node_RuleVariable.WILD
      • Will return the object if it is a Var
      • Will return resolve FrontsNode to Node and then resolve to Var
      • Will return resolve Node if the Node implements Node_Variable, otherwise throws an NotAVariableException (instance of ARQInternalErrorException)
      • Will return ?x if object is "?x"
      • Will return ?x if object is "x"
      • Will return the enclosed Var of a ExprVar
      • For all other objects will return the "?" prefixed to the toString() value.
      Parameters:
      o - The object to convert.
      Returns:
      the Var value.
      Throws:
      ARQInternalErrorException

    • getHandlerBlock

      public abstract HandlerBlock getHandlerBlock()
      Get the HandlerBlock for this query builder.
      Returns:
      The associated handler block.

    • getPrologHandler

      public final PrologHandler getPrologHandler()
      Description copied from interface: PrologClause
      Get the prolog handler for this clause.
      Specified by:
      getPrologHandler in interface PrologClause<T extends AbstractQueryBuilder<T>>
      Returns:
      The PrologHandler this clause is using.

    • getValuesHandler

      public ValuesHandler getValuesHandler()
      Description copied from interface: ValuesClause
      Get the value handler for this clause.
      Specified by:
      getValuesHandler in interface ValuesClause<T extends AbstractQueryBuilder<T>>
      Returns:
      The ValueHandler this clause is using.

    • getWhereHandler

      public final WhereHandler getWhereHandler()
      Gets the where handler used by this QueryBuilder.
      Returns:
      the where handler used by this QueryBuilder.

    • addWhere

      public final T addWhere(AbstractQueryBuilder<?> whereClause)
      Adds the contents of the whereClause to the where clause of this builder.
      Parameters:
      whereClause - the where clause to add.
      Returns:
      this builder for chaining.

    • getExprFactory

      public final ExprFactory getExprFactory()
      Description copied from interface: PrologClause
      Get the expression factory that works with the prefixes for this builder.
      Specified by:
      getExprFactory in interface PrologClause<T extends AbstractQueryBuilder<T>>
      Returns:
      an ExprFactory for this builder.

    • setVar

      public void setVar(Var var, Node value)
      Set a variable replacement. During build all instances of var in the query will be replaced with value. If value is null the replacement is cleared.
      Parameters:
      var - The variable to replace
      value - The value to replace it with or null to remove the replacement.

    • setVar

      public void setVar(Object var, Object value)
      Set a variable replacement. During build all instances of var in the query will be replaced with value. If value is null the replacement is cleared. See makeVar(java.lang.Object) for conversion of the var param. See makeNode(java.lang.Object) for conversion of the value param.
      Parameters:
      var - The variable to replace.
      value - The value to replace it with or null to remove the replacement.

    • addPrefix

      public T addPrefix(String pfx, Resource uri)
      Description copied from interface: PrologClause
      Adds a prefix.
      Specified by:
      addPrefix in interface PrologClause<T extends AbstractQueryBuilder<T>>
      Parameters:
      pfx - The prefix.
      uri - The URI for the prefix
      Returns:
      This builder for chaining.

    • addPrefix

      public T addPrefix(String pfx, Node uri)
      Description copied from interface: PrologClause
      Adds a prefix.
      Specified by:
      addPrefix in interface PrologClause<T extends AbstractQueryBuilder<T>>
      Parameters:
      pfx - The prefix.
      uri - The URI for the prefix
      Returns:
      This builder for chaining.

    • addPrefix

      public T addPrefix(String pfx, String uri)
      Description copied from interface: PrologClause
      Adds a prefix.
      Specified by:
      addPrefix in interface PrologClause<T extends AbstractQueryBuilder<T>>
      Parameters:
      pfx - The prefix.
      uri - The URI for the prefix
      Returns:
      This builder for chaining.

    • addPrefixes

      public T addPrefixes(Map<String,String> prefixes)
      Description copied from interface: PrologClause
      Adds prefixes.
      Specified by:
      addPrefixes in interface PrologClause<T extends AbstractQueryBuilder<T>>
      Parameters:
      prefixes - A mapping of prefix to URI to add.
      Returns:
      This builder for chaining.

    • addPrefixes

      public T addPrefixes(PrefixMapping prefixMapping)
      Description copied from interface: PrologClause
      Adds prefixes.
      Specified by:
      addPrefixes in interface PrologClause<T extends AbstractQueryBuilder<T>>
      Parameters:
      prefixMapping - A PrefixMapping instance..
      Returns:
      This builder for chaining.

    • setBase

      public T setBase(String base)
      Description copied from interface: PrologClause
      Sets the base URI.
      Specified by:
      setBase in interface PrologClause<T extends AbstractQueryBuilder<T>>
      Parameters:
      base - The base URI to use.
      Returns:
      This builder for chaining.

    • setBase

      public T setBase(Object base)
      Description copied from interface: PrologClause
      Sets the base URI. See makeNode(java.lang.Object) for conversion of the uri param. The resulting Node must be a URI.
      Specified by:
      setBase in interface PrologClause<T extends AbstractQueryBuilder<T>>
      Parameters:
      base - The base URI to use.
      Returns:
      This builder for chaining.

    • makeValueNodes

      @Deprecated public static Collection<Node> makeValueNodes(Iterator<?> iter, PrefixMapping prefixMapping)
      Deprecated.
      use Converters.makeValueNodes(Iterator, PrefixMapping)
      Creates a collection of nodes from an iterator of Objects.
      Parameters:
      iter - the iterator of objects, may be null or empty.
      prefixMapping - the PrefixMapping to use when nodes are created.
      Returns:
      a Collection of nodes or null if iter is null or empty.

    • makeValueNodes

      public Collection<Node> makeValueNodes(Iterator<?> iter)
      Creates a collection of nodes from an iterator of Objects. Uses the prefix mapping from the PrologHandler.
      Parameters:
      iter - the iterator of objects, may be null or empty.
      Returns:
      a Collection of nodes or null if iter is null or empty.

    • addValueVar

      public T addValueVar(Object var)
      Description copied from interface: ValuesClause
      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.
      Specified by:
      addValueVar in interface ValuesClause<T extends AbstractQueryBuilder<T>>
      Parameters:
      var - The variable or collection to add.
      Returns:
      The builder for chaining.
      See Also:

    • addValueVar

      public T addValueVar(Object var, Object... objects)
      Description copied from interface: ValuesClause
      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.
      Specified by:
      addValueVar in interface ValuesClause<T extends AbstractQueryBuilder<T>>
      Parameters:
      var - The variable to add.
      objects - The values for the variable
      Returns:
      The builder for chaining.
      See Also:

    • addValueVars

      public <K extends Collection<?>> T addValueVars(Map<?,K> dataTable)
      Description copied from interface: ValuesClause
      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. 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:
      • If the variable already exists in the table the map values are appended to the list of values
      • 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
      • 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.
      Specified by:
      addValueVars in interface ValuesClause<T extends AbstractQueryBuilder<T>>
      Parameters:
      dataTable - The data table to add.
      Returns:
      The builder for chaining.
      See Also:

    • addValueRow

      public T addValueRow(Object... values)
      Description copied from interface: ValuesClause
      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.
      Specified by:
      addValueRow in interface ValuesClause<T extends AbstractQueryBuilder<T>>
      Parameters:
      values - the collection of values to add.
      Returns:
      The builder for chaining.
      See Also:

    • addValueRow

      public T addValueRow(Collection<?> values)
      Description copied from interface: ValuesClause
      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.
      Specified by:
      addValueRow in interface ValuesClause<T extends AbstractQueryBuilder<T>>
      Parameters:
      values - the collection of values to add.
      Returns:
      The builder for chaining.
      See Also:

    • getValuesVars

      public List<Var> getValuesVars()
      Description copied from interface: ValuesClause
      Get an unmodifiable list of vars in the order that they appear in the values table.
      Specified by:
      getValuesVars in interface ValuesClause<T extends AbstractQueryBuilder<T>>
      Returns:
      an unmodifiable list of vars.

    • getValuesMap

      public Map<Var,List<Node>> getValuesMap()
      Description copied from interface: ValuesClause
      Get an unmodifiable map of vars and their values. Null values are considered as UNDEF values.
      Specified by:
      getValuesMap in interface ValuesClause<T extends AbstractQueryBuilder<T>>
      Returns:
      an unmodifiable map of vars and their values.

    • clearValues

      public T clearValues()
      Description copied from interface: ValuesClause
      Reset the values table to the initial undefined state. Used primarily to reset the builder values table to a known state.
      Specified by:
      clearValues in interface ValuesClause<T extends AbstractQueryBuilder<T>>
      Returns:
      The builder for chaining.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • buildString

      public final String buildString()
      Build the query as a string.
      Returns:
      the string representation of the query.

    • build

      public final Query build()
      Build the query. Performs the var replacements as specified by setVar(var,node) calls.
      Returns:
      The query.

    • clone

      public static Query clone(Query q2)
      Close the query. This can be used when the query would not normally parse as is required by the Query.clone() method.
      Parameters:
      q2 - The query to clone
      Returns:
      A clone of the q2 param.

    • rewrite

      public static Query rewrite(Query q2, Map<Var,Node> values)
      Rewrite a query replacing variables as specified in the values map.
      Parameters:
      q2 - The query to rewrite
      values - a Mapping of var to node for replacement.
      Returns:
      The new query with the specified vars replaced.