Package org.eclipse.rdf4j.federated.evaluation

## Class FederationEvalStrategy

- java.lang.Object
- - org.eclipse.rdf4j.query.algebra.evaluation.impl.StrictEvaluationStrategy
  - - org.eclipse.rdf4j.federated.evaluation.FederationEvalStrategy

- All Implemented Interfaces:
    `EvaluationStrategy`, `FederatedServiceResolver`, `FederatedServiceResolverClient`, `UUIDable`
  Direct Known Subclasses:
    `SailFederationEvalStrategy`, `SparqlFederationEvalStrategy`

      public abstract class FederationEvalStrategy
      extends StrictEvaluationStrategy

  Base class for the Evaluation strategies.
  Author:
    Andreas Schwarte
  See Also:
    `SailFederationEvalStrategy`, `SparqlFederationEvalStrategy`

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected SourceSelectionCache` | `cache` |
    `protected Executor` | `executor` |
    `protected FederationContext` | `federationContext` |

    - ### Fields inherited from class org.eclipse.rdf4j.query.algebra.evaluation.impl.StrictEvaluationStrategy

      `dataset, serviceResolver, tripleSource`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `FederationEvalStrategy​(FederationContext federationContext)` |

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected SourceSelectionCache` | `createSourceSelectionCache()` | Create the `SourceSelectionCache`
    `Value` | `evaluate​(ConjunctiveFilterExpr node, BindingSet bindings)` |
    `Value` | `evaluate​(FilterExpr node, BindingSet bindings)` |
    `CloseableIteration<BindingSet,​QueryEvaluationException>` | `evaluate​(TupleExpr expr, BindingSet bindings)` | Evaluates the tuple expression against the supplied triple source with the specified set of variable bindings as input.
    `Value` | `evaluate​(ValueExpr expr, BindingSet bindings)` | Gets the value of this expression.
    `protected CloseableIteration<BindingSet,​QueryEvaluationException>` | `evaluateAtStatementSources​(Object preparedQuery, List<StatementSource> statementSources, QueryInfo queryInfo)` |
    `protected CloseableIteration<BindingSet,​QueryEvaluationException>` | `evaluateAtStatementSources​(String preparedQuery, List<StatementSource> statementSources, QueryInfo queryInfo)` |
    `protected CloseableIteration<BindingSet,​QueryEvaluationException>` | `evaluateAtStatementSources​(TupleExpr preparedQuery, List<StatementSource> statementSources, QueryInfo queryInfo)` |
    `abstract CloseableIteration<BindingSet,​QueryEvaluationException>` | `evaluateBoundJoinStatementPattern​(StatementTupleExpr stmt, List<BindingSet> bindings)` | Evaluate a bound join at the relevant endpoint, i.e.
    `abstract CloseableIteration<BindingSet,​QueryEvaluationException>` | `evaluateExclusiveGroup​(ExclusiveGroup group, BindingSet bindings)` |
    `protected CloseableIteration<BindingSet,​QueryEvaluationException>` | `evaluateExclusiveTupleExpr​(ExclusiveTupleExpr expr, BindingSet bindings)` | Evaluate an `ExclusiveTupleExpr`.
    `abstract CloseableIteration<BindingSet,​QueryEvaluationException>` | `evaluateGroupedCheck​(CheckStatementPattern stmt, List<BindingSet> bindings)` | Perform a grouped check at the relevant endpoints, i.e.
    `protected CloseableIteration<BindingSet,​QueryEvaluationException>` | `evaluateLeftJoin​(FedXLeftJoin leftJoin, BindingSet bindings)` | Evaluate a `FedXLeftJoin` (i.e.
    `CloseableIteration<BindingSet,​QueryEvaluationException>` | `evaluateNaryUnion​(NUnion union, BindingSet bindings)` |
    `CloseableIteration<BindingSet,​QueryEvaluationException>` | `evaluateNJoin​(NJoin join, BindingSet bindings)` |
    `CloseableIteration<BindingSet,​QueryEvaluationException>` | `evaluateService​(FedXService service, List<BindingSet> bindings)` | Evaluate a SERVICE using vectored evaluation, taking the provided bindings as input.
    `CloseableIteration<BindingSet,​QueryEvaluationException>` | `evaluateService​(FedXService service, BindingSet bindings)` |
    `CloseableIteration<BindingSet,​QueryEvaluationException>` | `evaluateSingleSourceQuery​(SingleSourceQuery query, BindingSet bindings)` |
    `protected abstract CloseableIteration<BindingSet,​QueryEvaluationException>` | `executeJoin​(ControlledWorkerScheduler<BindingSet> joinScheduler, CloseableIteration<BindingSet,​QueryEvaluationException> leftIter, TupleExpr rightArg, Set<String> joinVariables, BindingSet bindings, QueryInfo queryInfo)` | Execute the join in a separate thread using some join executor.
    `CloseableIteration<Statement,​QueryEvaluationException>` | `getStatements​(QueryInfo queryInfo, Resource subj, IRI pred, Value obj, Resource... contexts)` | Retrieve the statements matching the provided subject, predicate and object value from the federation members.
    `TupleExpr` | `optimize​(TupleExpr expr, EvaluationStatistics evaluationStatistics, BindingSet bindings)` | Execute the `QueryOptimizerPipeline` on the given `TupleExpr` to optimize its execution plan.
    `protected void` | `optimizeExclusiveExpressions​(TupleExpr query, QueryInfo queryInfo, GenericInfoOptimizer info)` | Optimize `ExclusiveTupleExpr`, e.g.
    `protected void` | `optimizeJoinOrder​(TupleExpr query, QueryInfo queryInfo, GenericInfoOptimizer info)` |
    `protected Set<Endpoint>` | `performSourceSelection​(List<Endpoint> members, SourceSelectionCache cache, QueryInfo queryInfo, GenericInfoOptimizer info)` | Perform source selection for all statements of the query.
    `protected boolean` | `propagateServices​(List<Service> serviceNodes)` | Whether to propagate a `SingleSourceQuery` containing SERVICE clauses.

    - ### Methods inherited from class org.eclipse.rdf4j.query.algebra.evaluation.impl.StrictEvaluationStrategy

      `evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, getLimit, getService, getUUID, getVarValue, getZeroLengthPathIterator, isReducedOrDistinct, isTrue, isUnbound, setFederatedServiceResolver, setOptimizerPipeline, setTrackResultSize, setTrackTime`

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

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

- - ### Field Detail

    - #### executor

          protected Executor executor

    - #### cache

          protected SourceSelectionCache cache

    - #### federationContext

          protected FederationContext federationContext

  - ### Constructor Detail

    - #### FederationEvalStrategy

          public FederationEvalStrategy​(FederationContext federationContext)

  - ### Method Detail

    - #### createSourceSelectionCache

          protected SourceSelectionCache createSourceSelectionCache()

      Create the `SourceSelectionCache`
      Returns:
        the `SourceSelectionCache`
      See Also:
        `FedXConfig.getSourceSelectionCacheSpec()`

    - #### optimize

          public TupleExpr optimize​(TupleExpr expr,
                                    EvaluationStatistics evaluationStatistics,
                                    BindingSet bindings)

      Description copied from class: `StrictEvaluationStrategy`
      Execute the `QueryOptimizerPipeline` on the given `TupleExpr` to optimize its execution plan.
      Specified by:
        `optimize` in interface `EvaluationStrategy`
      Overrides:
        `optimize` in class `StrictEvaluationStrategy`
      Parameters:
        `expr` - the `TupleExpr` to optimize.
        `evaluationStatistics` - this param is ignored!
        `bindings` - a-priori bindings supplied for the query, which can potentially be inlined.
      Returns:
        the optimized `TupleExpr`.
      See Also:
        `StrictEvaluationStrategy.setOptimizerPipeline(QueryOptimizerPipeline)`

    - #### performSourceSelection

          protected Set<Endpoint> performSourceSelection​(List<Endpoint> members,
                                                         SourceSelectionCache cache,
                                                         QueryInfo queryInfo,
                                                         GenericInfoOptimizer info)

      Perform source selection for all statements of the query. As a result of this method all statement nodes are annotated with their relevant sources.
      Parameters:
        `members` -
        `cache` -
        `queryInfo` -
        `info` -
      Returns:
        the set of relevant endpoints for the entire query

    - #### optimizeJoinOrder

          protected void optimizeJoinOrder​(TupleExpr query,
                                           QueryInfo queryInfo,
                                           GenericInfoOptimizer info)

    - #### propagateServices

          protected boolean propagateServices​(List<Service> serviceNodes)

      Whether to propagate a `SingleSourceQuery` containing SERVICE clauses. By default, the query is always evaluated within the FedX engine if it contains a SERVICE clause.

      Customized implementation may propagate a `SingleSourceQuery` including the SERVICE clause (e.g. for Wikidata the Label service can only be accessed in the wikidata endpoint.

      Parameters:
        `serviceNodes` -
      Returns:
        if `true`, a `SingleSourceQuery` containing SERVICE clauses is propagated as-is

    - #### optimizeExclusiveExpressions

          protected void optimizeExclusiveExpressions​(TupleExpr query,
                                                      QueryInfo queryInfo,
                                                      GenericInfoOptimizer info)

      Optimize `ExclusiveTupleExpr`, e.g. restructure the exclusive parts of the query AST.
      Parameters:
        `query` -
        `queryInfo` -
        `info` -

    - #### evaluate

          public CloseableIteration<BindingSet,​QueryEvaluationException> evaluate​(TupleExpr expr,
                                                                                        BindingSet bindings)
                                                                                 throws QueryEvaluationException

      Description copied from interface: `EvaluationStrategy`
      Evaluates the tuple expression against the supplied triple source with the specified set of variable bindings as input.
      Specified by:
        `evaluate` in interface `EvaluationStrategy`
      Overrides:
        `evaluate` in class `StrictEvaluationStrategy`
      Parameters:
        `expr` - The Tuple Expression to evaluate
        `bindings` - The variables bindings to use for evaluating the expression, if applicable.
      Returns:
        A closeable iterator over the variable binding sets that match the tuple expression.
      Throws:
        `QueryEvaluationException`

    - #### getStatements

          public CloseableIteration<Statement,​QueryEvaluationException> getStatements​(QueryInfo queryInfo,
                                                                                            Resource subj,
                                                                                            IRI pred,
                                                                                            Value obj,
                                                                                            Resource... contexts)
                                                                                     throws RepositoryException,
                                                                                            MalformedQueryException,
                                                                                            QueryEvaluationException

      Retrieve the statements matching the provided subject, predicate and object value from the federation members.

      For a bound statement, i.e. a statement with no free variables, the statement itself is returned if some member has this statement, an empty iteration otherwise.

      If the statement has free variables, i.e. one of the provided arguments in `null`, the union of results from relevant statement sources is constructed.

      Parameters:
        `subj` -
        `pred` -
        `obj` -
        `contexts` -
      Returns:
        the statement iteration
      Throws:
        `RepositoryException`
        `MalformedQueryException`
        `QueryEvaluationException`

    - #### evaluateService

          public CloseableIteration<BindingSet,​QueryEvaluationException> evaluateService​(FedXService service,
                                                                                               BindingSet bindings)
                                                                                        throws QueryEvaluationException

      Throws:
        `QueryEvaluationException`

    - #### evaluateSingleSourceQuery

          public CloseableIteration<BindingSet,​QueryEvaluationException> evaluateSingleSourceQuery​(SingleSourceQuery query,
                                                                                                         BindingSet bindings)
                                                                                                  throws QueryEvaluationException

      Throws:
        `QueryEvaluationException`

    - #### evaluateNJoin

          public CloseableIteration<BindingSet,​QueryEvaluationException> evaluateNJoin​(NJoin join,
                                                                                             BindingSet bindings)
                                                                                      throws QueryEvaluationException

      Throws:
        `QueryEvaluationException`

    - #### evaluateLeftJoin

          protected CloseableIteration<BindingSet,​QueryEvaluationException> evaluateLeftJoin​(FedXLeftJoin leftJoin,
                                                                                                   BindingSet bindings)
                                                                                            throws QueryEvaluationException

      Evaluate a `FedXLeftJoin` (i.e. an OPTIONAL clause)
      Parameters:
        `leftJoin` -
        `bindings` -
      Returns:
        the resulting iteration
      Throws:
        `QueryEvaluationException`
      See Also:
        `StrictEvaluationStrategy.evaluate(org.eclipse.rdf4j.query.algebra.LeftJoin, BindingSet)`

    - #### evaluateNaryUnion

          public CloseableIteration<BindingSet,​QueryEvaluationException> evaluateNaryUnion​(NUnion union,
                                                                                                 BindingSet bindings)
                                                                                          throws QueryEvaluationException

      Throws:
        `QueryEvaluationException`

    - #### executeJoin

          protected abstract CloseableIteration<BindingSet,​QueryEvaluationException> executeJoin​(ControlledWorkerScheduler<BindingSet> joinScheduler,
                                                                                                       CloseableIteration<BindingSet,​QueryEvaluationException> leftIter,
                                                                                                       TupleExpr rightArg,
                                                                                                       Set<String> joinVariables,
                                                                                                       BindingSet bindings,
                                                                                                       QueryInfo queryInfo)
                                                                                                throws QueryEvaluationException

      Execute the join in a separate thread using some join executor. Join executors are for instance: - `SynchronousJoin` - `SynchronousBoundJoin` - `ControlledWorkerJoin` - `ControlledWorkerBoundJoin` For endpoint federation use controlled worker bound join, for local federation use controlled worker join. The other operators are there for completeness. Use `executor` to execute the join (it is a runnable).
      Parameters:
        `joinScheduler` -
        `leftIter` -
        `rightArg` -
        `joinVariables` -
        `bindings` -
      Returns:
        the result
      Throws:
        `QueryEvaluationException`

    - #### evaluateExclusiveGroup

          public abstract CloseableIteration<BindingSet,​QueryEvaluationException> evaluateExclusiveGroup​(ExclusiveGroup group,
                                                                                                               BindingSet bindings)
                                                                                                        throws RepositoryException,
                                                                                                               MalformedQueryException,
                                                                                                               QueryEvaluationException

      Throws:
        `RepositoryException`
        `MalformedQueryException`
        `QueryEvaluationException`

    - #### evaluateExclusiveTupleExpr

          protected CloseableIteration<BindingSet,​QueryEvaluationException> evaluateExclusiveTupleExpr​(ExclusiveTupleExpr expr,
                                                                                                             BindingSet bindings)
                                                                                                      throws RepositoryException,
                                                                                                             MalformedQueryException,
                                                                                                             QueryEvaluationException

      Evaluate an `ExclusiveTupleExpr`. The default implementation converts the given expression to a SELECT query string and evaluates it at the source.
      Parameters:
        `expr` -
        `bindings` -
      Returns:
        the result
      Throws:
        `RepositoryException`
        `MalformedQueryException`
        `QueryEvaluationException`

    - #### evaluateBoundJoinStatementPattern

          public abstract CloseableIteration<BindingSet,​QueryEvaluationException> evaluateBoundJoinStatementPattern​(StatementTupleExpr stmt,
                                                                                                                          List<BindingSet> bindings)
                                                                                                                   throws QueryEvaluationException

      Evaluate a bound join at the relevant endpoint, i.e. i.e. for a group of bindings retrieve results for the bound statement from the relevant endpoints
      Parameters:
        `stmt` -
        `bindings` -
      Returns:
        the result iteration
      Throws:
        `QueryEvaluationException`

    - #### evaluateGroupedCheck

          public abstract CloseableIteration<BindingSet,​QueryEvaluationException> evaluateGroupedCheck​(CheckStatementPattern stmt,
                                                                                                             List<BindingSet> bindings)
                                                                                                      throws QueryEvaluationException

      Perform a grouped check at the relevant endpoints, i.e. for a group of bindings keep only those for which at least one endpoint provides a result to the bound statement.
      Parameters:
        `stmt` -
        `bindings` -
      Returns:
        the result iteration
      Throws:
        `QueryEvaluationException`

    - #### evaluateService

          public CloseableIteration<BindingSet,​QueryEvaluationException> evaluateService​(FedXService service,
                                                                                               List<BindingSet> bindings)
                                                                                        throws QueryEvaluationException

      Evaluate a SERVICE using vectored evaluation, taking the provided bindings as input. See `ControlledWorkerBoundJoin` and `FedXConfig.getEnableServiceAsBoundJoin()`
      Parameters:
        `service` -
        `bindings` -
      Returns:
        the result iteration
      Throws:
        `QueryEvaluationException`

    - #### evaluate

          public Value evaluate​(ValueExpr expr,
                                BindingSet bindings)
                         throws ValueExprEvaluationException,
                                QueryEvaluationException

      Description copied from interface: `EvaluationStrategy`
      Gets the value of this expression.
      Specified by:
        `evaluate` in interface `EvaluationStrategy`
      Overrides:
        `evaluate` in class `StrictEvaluationStrategy`
        `bindings` - The variables bindings to use for evaluating the expression, if applicable.
      Returns:
        The Value that this expression evaluates to, or null if the expression could not be evaluated.
      Throws:
        `ValueExprEvaluationException`
        `QueryEvaluationException`

    - #### evaluate

          public Value evaluate​(FilterExpr node,
                                BindingSet bindings)
                         throws ValueExprEvaluationException,
                                QueryEvaluationException

      Throws:
        `ValueExprEvaluationException`
        `QueryEvaluationException`

    - #### evaluate

          public Value evaluate​(ConjunctiveFilterExpr node,
                                BindingSet bindings)
                         throws ValueExprEvaluationException,
                                QueryEvaluationException

      Throws:
        `ValueExprEvaluationException`
        `QueryEvaluationException`

    - #### evaluateAtStatementSources

          protected CloseableIteration<BindingSet,​QueryEvaluationException> evaluateAtStatementSources​(Object preparedQuery,
                                                                                                             List<StatementSource> statementSources,
                                                                                                             QueryInfo queryInfo)
                                                                                                      throws QueryEvaluationException

      Throws:
        `QueryEvaluationException`

    - #### evaluateAtStatementSources

          protected CloseableIteration<BindingSet,​QueryEvaluationException> evaluateAtStatementSources​(String preparedQuery,
                                                                                                             List<StatementSource> statementSources,
                                                                                                             QueryInfo queryInfo)
                                                                                                      throws QueryEvaluationException

      Throws:
        `QueryEvaluationException`

    - #### evaluateAtStatementSources

          protected CloseableIteration<BindingSet,​QueryEvaluationException> evaluateAtStatementSources​(TupleExpr preparedQuery,
                                                                                                             List<StatementSource> statementSources,
                                                                                                             QueryInfo queryInfo)
                                                                                                      throws QueryEvaluationException

      Throws:
        `QueryEvaluationException`