Package org.eclipse.rdf4j.federated.util

## Class QueryStringUtil

- java.lang.Object
- - org.eclipse.rdf4j.federated.util.QueryStringUtil

-     public class QueryStringUtil
      extends Object

  Various static functions for query handling and parsing.
  Author:
    Andreas Schwarte

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static IRI` | `BNODE_URI` | A dummy URI which is used as a replacement for `BNode`s in `appendBNode(StringBuilder, BNode)` since BNodes cannot be expressed in SPARQL queries

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `QueryStringUtil()` |

  - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected static StringBuilder` | `appendBNode​(StringBuilder sb, BNode bNode)` | Append a dummy string (see `BNODE_URI`) to represent the BNode.
    `protected static StringBuilder` | `appendLiteral​(StringBuilder sb, Literal lit)` | Append the literal to the stringbuilder.
    `protected static StringBuilder` | `appendURI​(StringBuilder sb, IRI uri)` | Append the uri to the stringbuilder, i.e.
    `protected static StringBuilder` | `appendValue​(StringBuilder sb, Value value)` | Append a string representation of the value to the string builder.
    `protected static StringBuilder` | `appendVar​(StringBuilder sb, Var var, Set<String> varNames, BindingSet bindings)` | Append the variable to the provided StringBuilder.
    `protected static StringBuilder` | `appendVarId​(StringBuilder sb, Var var, String varID, Set<String> varNames, BindingSet bindings)` | Append the variable to the provided StringBuilder, however change name of variable by appending "_varId" to it.
    `static String` | `askQueryString​(ExclusiveTupleExpr expr, BindingSet bindings, Dataset dataset)` | Transform the `ExclusiveTupleExpr` into a ASK query string
    `static String` | `askQueryString​(StatementPattern stmt, BindingSet bindings, Dataset dataset)` | Construct a boolean ASK query for the provided statement.
    `protected static String` | `constructInnerUnion​(StatementPattern stmt, int outerID, Set<String> varNames, List<BindingSet> bindings)` |
    `protected static String` | `constructJoinArg​(ExclusiveTupleExpr exclusiveExpr, Set<String> varNames, BindingSet bindings)` | Construct a query substring from the `ExclusiveTupleExpr` that can be used as an argument to a `Join`.
    `protected static String` | `constructStatement​(StatementPattern stmt, Set<String> varNames, BindingSet bindings)` | Construct the statement string, i.e.
    `protected static String` | `constructStatementCheckId​(StatementPattern stmt, int varID, Set<String> varNames, BindingSet bindings)` | Construct the statement string, i.e.
    `protected static String` | `constructStatementId​(StatementPattern stmt, String varID, Set<String> varNames, BindingSet bindings)` | Construct the statement string, i.e.
    `protected static String` | `getValueString​(Value value)` | Return the string representation of this value, see `appendValue(StringBuilder, Value)` for details.
    `static boolean` | `hasFreeVars​(StatementPattern stmt, BindingSet bindings)` | returns true iff there is at least one free variable, i.e.
    `static List<String>` | `loadQueries​(String queryFile)` | load the queries from a queries file located at the specified path.
    `static String` | `selectQueryString​(ExclusiveGroup group, BindingSet bindings, FilterValueExpr filterExpr, AtomicBoolean evaluated, Dataset dataset)` | Construct a SELECT query for the provided `ExclusiveGroup`.
    `static String` | `selectQueryString​(ExclusiveTupleExprRenderer expr, BindingSet bindings, FilterValueExpr filterExpr, AtomicBoolean evaluated, Dataset dataset)` | Construct a SELECT query for the provided `ExclusiveTupleExprRenderer`
    `static String` | `selectQueryString​(StatementPattern stmt, BindingSet bindings, FilterValueExpr filterExpr, AtomicBoolean evaluated, Dataset dataset)` | Construct a SELECT query for the provided statement.
    `static String` | `selectQueryStringBoundCheck​(StatementPattern stmt, List<BindingSet> unionBindings, Dataset dataset)` | Construct a SELECT query for a grouped bound check.
    `static String` | `selectQueryStringBoundJoinVALUES​(StatementPattern stmt, List<BindingSet> unionBindings, FilterValueExpr filterExpr, AtomicBoolean evaluated, Dataset dataset)` | Creates a bound join subquery using the SPARQL 1.1 VALUES operator.
    `static String` | `selectQueryStringBoundUnion​(StatementPattern stmt, List<BindingSet> unionBindings, FilterValueExpr filterExpr, Boolean evaluated, Dataset dataset)` | Deprecated. replaced with `#selectQueryStringBoundJoinVALUES(StatementPattern, List, FilterValueExpr, AtomicBoolean)`
    `static String` | `selectQueryStringLimit1​(ExclusiveGroup group, BindingSet bindings, Dataset dataset)` | Construct a SELECT query for the provided `ExclusiveGroup` with LIMIT 1.
    `static String` | `selectQueryStringLimit1​(ExclusiveTupleExpr expr, BindingSet bindings, Dataset dataset)` | Construct a SELECT query for the provided expr with LIMIT 1.
    `static String` | `selectQueryStringLimit1​(StatementPattern stmt, BindingSet bindings, Dataset dataset)` | Construct a SELECT query for the provided statement with LIMIT 1.
    `static String` | `toString​(Resource subj, IRI pred, Value obj)` | Return a string representation of this statement using the following pattern, where variables are indicated using ?var and values are represented as strings.
    `static String` | `toString​(ArbitraryLengthPath node, Set<String> varNames, BindingSet bindings)` | Converts an `ArbitraryLengthPath` node to a sub query string and makes sure to insert any bindings.
    `static String` | `toString​(StatementPattern stmt)` | Return a string representation of this statement using the following pattern, where variables are indicated using ?var and values are represented as strings.
    `static String` | `toString​(Var var)` |

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### BNODE_URI

          public static final IRI BNODE_URI

      A dummy URI which is used as a replacement for `BNode`s in `appendBNode(StringBuilder, BNode)` since BNodes cannot be expressed in SPARQL queries

  - ### Constructor Detail

    - #### QueryStringUtil

          public QueryStringUtil()

  - ### Method Detail

    - #### hasFreeVars

          public static boolean hasFreeVars​(StatementPattern stmt,
                                            BindingSet bindings)

      returns true iff there is at least one free variable, i.e. there is no binding for any variable
      Parameters:
        `stmt` -
        `bindings` -
      Returns:
        whether free vars are available

    - #### toString

          public static String toString​(StatementPattern stmt)

      Return a string representation of this statement using the following pattern, where variables are indicated using ?var and values are represented as strings. Pattern: {s; p; o}
      Parameters:
        `stmt` -
      Returns:
        a string representation of the statement

    - #### toString

          public static String toString​(ArbitraryLengthPath node,
                                        Set<String> varNames,
                                        BindingSet bindings)

      Converts an `ArbitraryLengthPath` node to a sub query string and makes sure to insert any bindings.

      This method assumes that the `ArbitraryLengthPath.getPathExpression()` is a `StatementPattern`.

      Parameters:
        `node` -
        `varNames` -
        `bindings` -
      Returns:
        the query string

    - #### toString

          public static String toString​(Var var)

    - #### toString

          public static String toString​(Resource subj,
                                        IRI pred,
                                        Value obj)

      Return a string representation of this statement using the following pattern, where variables are indicated using ?var and values are represented as strings. Pattern: {s; p; o}
      Parameters:
        `subj` - the subject
        `pred` - the predicate
        `obj` - the object
      Returns:
        a string representation

    - #### selectQueryString

          public static String selectQueryString​(StatementPattern stmt,
                                                 BindingSet bindings,
                                                 FilterValueExpr filterExpr,
                                                 AtomicBoolean evaluated,
                                                 Dataset dataset)
                                          throws IllegalQueryException

      Construct a SELECT query for the provided statement.
      Parameters:
        `stmt` -
        `bindings` -
        `filterExpr` -
        `evaluated` - parameter can be used outside this method to check whether FILTER has been evaluated, false in beginning
      Returns:
        the SELECT query
      Throws:
        `IllegalQueryException` - if the query does not have any free variables

    - #### selectQueryString

          public static String selectQueryString​(ExclusiveTupleExprRenderer expr,
                                                 BindingSet bindings,
                                                 FilterValueExpr filterExpr,
                                                 AtomicBoolean evaluated,
                                                 Dataset dataset)
                                          throws IllegalQueryException

      Construct a SELECT query for the provided `ExclusiveTupleExprRenderer`
      Parameters:
        `stmt` -
        `bindings` -
        `filterExpr` -
        `evaluated` - parameter can be used outside this method to check whether FILTER has been evaluated, false in beginning
      Returns:
        the SELECT query
      Throws:
        `IllegalQueryException` - if the query does not have any free variables

    - #### selectQueryString

          public static String selectQueryString​(ExclusiveGroup group,
                                                 BindingSet bindings,
                                                 FilterValueExpr filterExpr,
                                                 AtomicBoolean evaluated,
                                                 Dataset dataset)
                                          throws IllegalQueryException

      Construct a SELECT query for the provided `ExclusiveGroup`. Note that bindings and filterExpr are applied whenever possible.
      Parameters:
        `group` - the expression for the query
        `bindings` - the bindings to be applied
        `filterExpr` - a filter expression or null
        `evaluated` - parameter can be used outside this method to check whether FILTER has been evaluated, false in beginning
      Returns:
        the SELECT query string
      Throws:
        `IllegalQueryException`

    - #### askQueryString

          public static String askQueryString​(ExclusiveTupleExpr expr,
                                              BindingSet bindings,
                                              Dataset dataset)

      Transform the `ExclusiveTupleExpr` into a ASK query string
      Parameters:
        `expr` -
        `bindings` -
      Returns:
        the ASK query string
      Throws:
        `IllegalQueryException`

    - #### selectQueryStringBoundUnion

          @Deprecated
          public static String selectQueryStringBoundUnion​(StatementPattern stmt,
                                                           List<BindingSet> unionBindings,
                                                           FilterValueExpr filterExpr,
                                                           Boolean evaluated,
                                                           Dataset dataset)

      Deprecated.
      replaced with `#selectQueryStringBoundJoinVALUES(StatementPattern, List, FilterValueExpr, AtomicBoolean)`
      Construct a SELECT query string for a bound union. Pattern: SELECT ?v_1 ?v_2 ?v_N WHERE { { ?v_1 p o } UNION { ?v_2 p o } UNION ... } Note that the filterExpr is not evaluated at the moment.
      Parameters:
        `stmt` -
        `unionBindings` -
        `filterExpr` -
        `evaluated` - parameter can be used outside this method to check whether FILTER has been evaluated, false in beginning
      Returns:
        the SELECT query string

    - #### selectQueryStringBoundJoinVALUES

          public static String selectQueryStringBoundJoinVALUES​(StatementPattern stmt,
                                                                List<BindingSet> unionBindings,
                                                                FilterValueExpr filterExpr,
                                                                AtomicBoolean evaluated,
                                                                Dataset dataset)

      Creates a bound join subquery using the SPARQL 1.1 VALUES operator.

      Example subquery:

           SELECT ?v ?__index WHERE {
              VALUES (?s ?__index) {
                (:s1 1) (:s2 2)
                ...
                (:sN N)
              }
              ?s name ?v.
           }

      Parameters:
        `stmt` -
        `unionBindings` -
        `filterExpr` -
        `evaluated` - parameter can be used outside this method to check whether FILTER has been evaluated, false in beginning
      Returns:
        the SELECT query string
      Since:
        3.0
      See Also:
        `SparqlFederationEvalStrategy`, `BoundJoinVALUESConversionIteration`

    - #### selectQueryStringBoundCheck

          public static String selectQueryStringBoundCheck​(StatementPattern stmt,
                                                           List<BindingSet> unionBindings,
                                                           Dataset dataset)

      Construct a SELECT query for a grouped bound check. Pattern: SELECT ?o_1 .. ?o_N WHERE { { s1 p1 ?o_1 FILTER ?o_1=o1 } UNION ... UNION { sN pN ?o_N FILTER ?o_N=oN }}
      Parameters:
        `stmt` -
        `unionBindings` -
      Returns:
        the SELECT query string

    - #### constructInnerUnion

          protected static String constructInnerUnion​(StatementPattern stmt,
                                                      int outerID,
                                                      Set<String> varNames,
                                                      List<BindingSet> bindings)

    - #### constructJoinArg

          protected static String constructJoinArg​(ExclusiveTupleExpr exclusiveExpr,
                                                   Set<String> varNames,
                                                   BindingSet bindings)

      Construct a query substring from the `ExclusiveTupleExpr` that can be used as an argument to a `Join`.

      This method can only be used for `ExclusiveTupleExpr` that additionally provide `ExclusiveTupleExprRenderer` capabilities. An exception to this is if the given expression is a `StatementPattern`, e.g. an `ExclusiveStatement` or `ExclusiveGroup`.

      Parameters:
        `exclusiveExpr` -
        `varNames` -
        `bindings` -
      Returns:
        the query string with bindings inserted

    - #### askQueryString

          public static String askQueryString​(StatementPattern stmt,
                                              BindingSet bindings,
                                              Dataset dataset)

      Construct a boolean ASK query for the provided statement.
      Parameters:
        `stmt` -
        `bindings` -
      Returns:
        the ASK query string

    - #### selectQueryStringLimit1

          public static String selectQueryStringLimit1​(StatementPattern stmt,
                                                       BindingSet bindings,
                                                       Dataset dataset)

      Construct a SELECT query for the provided statement with LIMIT 1. Such query can be used for source selection instead of ASK queries.
      Parameters:
        `stmt` -
        `bindings` -
      Returns:
        the SELECT query string

    - #### selectQueryStringLimit1

          public static String selectQueryStringLimit1​(ExclusiveTupleExpr expr,
                                                       BindingSet bindings,
                                                       Dataset dataset)

      Construct a SELECT query for the provided expr with LIMIT 1. Such query can be used for source selection instead of ASK queries.
      Parameters:
        `stmt` -
        `bindings` -
      Returns:
        the SELECT query string

    - #### selectQueryStringLimit1

          public static String selectQueryStringLimit1​(ExclusiveGroup group,
                                                       BindingSet bindings,
                                                       Dataset dataset)

      Construct a SELECT query for the provided `ExclusiveGroup` with LIMIT 1. Such query can be used for source selection instead of ASK queries.
      Parameters:
        `group` -
        `bindings` -
      Returns:
        the SELECT query string

    - #### constructStatement

          protected static String constructStatement​(StatementPattern stmt,
                                                     Set<String> varNames,
                                                     BindingSet bindings)

      Construct the statement string, i.e. "s p o . " with bindings inserted wherever possible. Note that the relevant free variables are added to the varNames set for further evaluation.
      Parameters:
        `stmt` -
        `varNames` -
        `bindings` -
      Returns:
        the constructed statement pattern

    - #### constructStatementId

          protected static String constructStatementId​(StatementPattern stmt,
                                                       String varID,
                                                       Set<String> varNames,
                                                       BindingSet bindings)

      Construct the statement string, i.e. "s p o . " with bindings inserted wherever possible. Variables are renamed to "var_"+varId to identify query results in bound queries. Note that the free variables are also added to the varNames set for further evaluation.
      Parameters:
        `stmt` -
        `varNames` -
        `bindings` -
      Returns:
        the constructed statement pattern

    - #### constructStatementCheckId

          protected static String constructStatementCheckId​(StatementPattern stmt,
                                                            int varID,
                                                            Set<String> varNames,
                                                            BindingSet bindings)

      Construct the statement string, i.e. "s p ?o_varID FILTER ?o_N=o ". This kind of statement pattern is necessary to later on identify available results.
      Parameters:
        `stmt` -
        `varID` -
        `varNames` -
        `bindings` -
      Returns:
        the statement pattern string

    - #### appendVar

          protected static StringBuilder appendVar​(StringBuilder sb,
                                                   Var var,
                                                   Set<String> varNames,
                                                   BindingSet bindings)

      Append the variable to the provided StringBuilder. Cases: 1) unbound: check provided bindingset for possible match a) match found: append matching value b) no match: append ?varName and add to varNames 2) bound: append value
      Parameters:
        `sb` -
        `var` -
        `varNames` -
        `bindings` -
      Returns:
        the stringbuilder

    - #### appendVarId

          protected static StringBuilder appendVarId​(StringBuilder sb,
                                                     Var var,
                                                     String varID,
                                                     Set<String> varNames,
                                                     BindingSet bindings)

      Append the variable to the provided StringBuilder, however change name of variable by appending "_varId" to it. Cases: 1) unbound: check provided bindingset for possible match a) match found: append matching value b) no match: append ?varName_varId and add to varNames 2) bound: append value
      Parameters:
        `sb` -
        `var` -
        `varNames` -
        `bindings` -
      Returns:
        the complemented string builder

    - #### getValueString

          protected static String getValueString​(Value value)

      Return the string representation of this value, see `appendValue(StringBuilder, Value)` for details.
      Parameters:
        `value` -
      Returns:
        the string representation

    - #### appendValue

          protected static StringBuilder appendValue​(StringBuilder sb,
                                                     Value value)

      Append a string representation of the value to the string builder. 1. URI: 2. Literal: "myLiteral"^^
      Parameters:
        `sb` -
        `value` -
      Returns:
        the string builder

    - #### appendURI

          protected static StringBuilder appendURI​(StringBuilder sb,
                                                   IRI uri)

      Append the uri to the stringbuilder, i.e. .
      Parameters:
        `sb` -
        `uri` -
      Returns:
        the string builder

    - #### appendBNode

          protected static StringBuilder appendBNode​(StringBuilder sb,
                                                     BNode bNode)

      Append a dummy string (see `BNODE_URI`) to represent the BNode. Note: currently it is not possible to retrieve values for a BNode via SPARQL, hence we use a dummy BNode which does not produce any results. A warning is printed to debug.
      Parameters:
        `sb` -
        `bNode` -
      Returns:
        the string builder

    - #### appendLiteral

          protected static StringBuilder appendLiteral​(StringBuilder sb,
                                                       Literal lit)

      Append the literal to the stringbuilder.
      Parameters:
        `sb` -
        `lit` -
      Returns:
        the string builder

    - #### loadQueries

          public static List<String> loadQueries​(String queryFile)
                                          throws FileNotFoundException,
                                                 IOException

      load the queries from a queries file located at the specified path. Expected format: - Queries are SPARQL queries in String format - queries are allowed to span several lines - a query is interpreted to be finished if an empty line occurs Ex: QUERY1 ... Q1 cntd QUERY2
      Parameters:
        `queryFile` -
      Returns:
        a list of queries for the query type
      Throws:
        `FileNotFoundException`
        `IOException`