org.modeshape.jcr.query.engine

## Class ScanningQueryEngine

- java.lang.Object
- - org.modeshape.jcr.query.engine.ScanningQueryEngine

- All Implemented Interfaces:
    QueryEngine
  Direct Known Subclasses:
    IndexQueryEngine

      @Immutable
      public class ScanningQueryEngine
      extends Object
      implements QueryEngine

  A `QueryEngine` implementation that always scans all nodes in the workspace(s) and filtering out any node that does not satisfy the criteria. This scanning is not very efficient and can result in slow queries, especially when the repository is quite large or when the number of nodes that satisfies the query's criteria is a small fraction of all possible nodes in the workspace(s).

  However, this fully-functional QueryEngine implementation is designed to be subclassed when the nodes for a particular source (and optionally criteria) can be found more quickly. In such cases, the subclass should override the `#createNodeSequenceForSource(QueryCommand, QueryContext, PlanNode, Columns, QuerySources)` method or the `#createNodeSequenceForSource(QueryCommand, QueryContext, PlanNode, IndexPlan, Columns, QuerySources)` method and return a NodeSequence that contains only the applicable nodes.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `ScanningQueryEngine.Builder`
    `protected static class` | `ScanningQueryEngine.DynamicOperandFilter` Interface for evaluating a `DynamicOperand` against the current row in a `NodeSequence.Batch` and returning the corresponding value.
    `protected static class` | `ScanningQueryEngine.PropertyValueExtractor`
    `static class` | `ScanningQueryEngine.ResultColumns`
    `protected static class` | `ScanningQueryEngine.RowFilterSupplier` A `NodeSequence.RowFilter` implementation that lazily initializes the real RowFilter implementation the first time it's needed and thereafter will simply delegate to the implementation.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static Logger` | `LOGGER` We don't use the standard logging convention here; we want clients to easily configure logging for the indexes
    `protected Optimizer` | `optimizer`
    `protected Planner` | `planner`
    `protected static Set<Name>` | `PSEUDO_COLUMN_NAMES`
    `protected String` | `repositoryName`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ScanningQueryEngine(ExecutionContext context, String repositoryName, Planner planner, Optimizer optimizer)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static ScanningQueryEngine.Builder` | `builder()`
    `protected RowExtractors.ExtractFromRow` | `createExtractFromRow(DynamicOperand operand, QueryContext context, QueryResults.Columns columns, QuerySources sources, TypeSystem.TypeFactory<?> defaultType, boolean allowMultiValued, boolean isLike)` Create a `RowExtractors.ExtractFromRow` implementation that performs the supplied `DynamicOperand` against a current row in the current batch.
    `protected RowExtractors.ExtractFromRow` | `createExtractFromRow(String selectorName, String propertyName, QueryContext context, QueryResults.Columns columns, QuerySources sources, TypeSystem.TypeFactory<?> defaultType, boolean allowMultiValued)` Create a `RowExtractors.ExtractFromRow` implementation that accesses the value(s) in the property identified by the supplied selector and property names.
    `protected RowExtractors.ExtractFromRow` | `createExtractReferencesFromRow(String selectorName, QueryContext context, QueryResults.Columns columns, QuerySources sources, TypeSystem.TypeFactory<?> defaultType)` Create a `RowExtractors.ExtractFromRow` implementation that accesses the REFERENCE value(s) in the properties of the node identified by the supplied selector names.
    `protected NodeSequence` | `createNodeSequence(QueryCommand originalQuery, org.modeshape.jcr.query.engine.ScanningQueryEngine.ScanQueryContext context, PlanNode plan, QueryResults.Columns columns, QuerySources sources)` Create a node sequence containing the results of the original query as defined by the supplied plan.
    `protected NodeSequence` | `createNodeSequenceForSource(QueryCommand originalQuery, QueryContext context, PlanNode sourceNode, IndexPlan index, QueryResults.Columns columns, QuerySources sources)` Create a node sequence for the given index
    `protected NodeSequence` | `createNodeSequenceForSource(QueryCommand originalQuery, QueryContext context, PlanNode sourceNode, QueryResults.Columns columns, QuerySources sources)` Create a node sequence for the given source.
    `QueryContext` | `createQueryContext(ExecutionContext context, RepositoryCache repositoryCache, Set<String> workspaceNames, Map<String,NodeCache> overriddenNodeCachesByWorkspaceName, Schemata schemata, RepositoryIndexes indexDefns, NodeTypes nodeTypes, BufferManager bufferManager, PlanHints hints, Map<String,Object> variables)` Create a new context for query execution.
    `protected NodeSequence.RowFilter` | `createRowFilter(Constraint constraint, QueryContext context, QueryResults.Columns columns, QuerySources sources)` Create a `NodeSequence.RowFilter` implementation given the supplied constraints.
    `protected RowExtractors.ExtractFromRow` | `createSortingExtractor(List<Ordering> orderings, Map<SelectorName,SelectorName> sourceNamesByAlias, QueryContext context, QueryResults.Columns columns, QuerySources sources)` Create an `RowExtractors.ExtractFromRow` instance that produces for given row a single object that can be used to sort all rows in the specified order.
    `protected RowExtractors.ExtractFromRow` | `createSortingExtractor(Ordering ordering, Map<SelectorName,SelectorName> sourceNamesByAlias, QueryContext context, QueryResults.Columns columns, QuerySources sources)` Create an `RowExtractors.ExtractFromRow` instance that produces for given row a single object that can be used to sort all rows in the specified order.
    `protected QueryResults.Columns` | `determineProjectedColumns(PlanNode optimizedPlan, org.modeshape.jcr.query.engine.ScanningQueryEngine.ScanQueryContext context)` Compute the columns that are defined in the supplied `plan node`.
    `protected TypeSystem.TypeFactory<?>` | `determineType(DynamicOperand operand, QueryContext context, QueryResults.Columns columns)`
    `QueryResults` | `execute(QueryContext queryContext, QueryCommand query)` Execute the supplied query by planning, optimizing, and then processing it.
    `protected QueryResults` | `executeOptimizedQuery(org.modeshape.jcr.query.engine.ScanningQueryEngine.ScanQueryContext context, QueryCommand command, QueryResults.Statistics statistics, PlanNode plan)` Execute the optimized query defined by the supplied `plan node`.
    `protected static Object` | `literalValue(StaticOperand staticOperand, QueryContext context, TypeSystem.TypeFactory<?> type)` Get the literal value that is defined in the supplied `StaticOperand`.
    `protected static Set<?>` | `literalValues(SetCriteria setCriteria, QueryContext context, TypeSystem.TypeFactory<?> type)`
    `void` | `shutdown()` Signal that the engine is no longer needed and should clean up and/or close any resources.
    `static String` | `toRegularExpression(String likeExpression)` Convert the JCR like expression to a regular expression.
    `protected static String` | `toWildcardExpression(String likeExpression)` Convert the JCR like expression to a Lucene wildcard expression.

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

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

- - ### Field Detail

    - #### LOGGER

          protected static final Logger LOGGER

      We don't use the standard logging convention here; we want clients to easily configure logging for the indexes

    - #### PSEUDO_COLUMN_NAMES

          protected static final Set<Name> PSEUDO_COLUMN_NAMES

    - #### repositoryName

          protected final String repositoryName

    - #### planner

          protected final Planner planner

    - #### optimizer

          protected final Optimizer optimizer

  - ### Constructor Detail

    - #### ScanningQueryEngine

          public ScanningQueryEngine(ExecutionContext context,
                             String repositoryName,
                             Planner planner,
                             Optimizer optimizer)

  - ### Method Detail

    - #### builder

          public static ScanningQueryEngine.Builder builder()

    - #### execute

          public QueryResults execute(QueryContext queryContext,
                             QueryCommand query)
                               throws QueryCancelledException,
                                      RepositoryException

      Execute the supplied query by planning, optimizing, and then processing it.
      Specified by:
        `execute` in interface `QueryEngine`
      Parameters:
        `queryContext` - the context in which the query should be executed; same instance as returned by `createQueryContext(org.modeshape.jcr.ExecutionContext, org.modeshape.jcr.cache.RepositoryCache, java.util.Set<java.lang.String>, java.util.Map<java.lang.String, org.modeshape.jcr.cache.NodeCache>, org.modeshape.jcr.query.validate.Schemata, org.modeshape.jcr.RepositoryIndexes, org.modeshape.jcr.NodeTypes, org.modeshape.jcr.query.BufferManager, org.modeshape.jcr.query.plan.PlanHints, java.util.Map<java.lang.String, java.lang.Object>)`
        `query` - the query that is to be executed
      Returns:
        the query results; never null
      Throws:
        `IllegalArgumentException` - if the context or query references are null
        `QueryCancelledException` - if the query was cancelled
        `RepositoryException` - if there was a problem executing the query

    - #### determineProjectedColumns

          protected QueryResults.Columns determineProjectedColumns(PlanNode optimizedPlan,
                                                       org.modeshape.jcr.query.engine.ScanningQueryEngine.ScanQueryContext context)

      Compute the columns that are defined in the supplied `plan node`. If the supplied plan node is not a `project node`, the method finds the first PROJECT node below the given node.
      Parameters:
        `optimizedPlan` - the optimized plan node in a query plan; may not be null
        `context` - the query context; may not be null
      Returns:
        the representation of the projected columns; never null

    - #### shutdown

          public void shutdown()

      Description copied from interface: `QueryEngine`
      Signal that the engine is no longer needed and should clean up and/or close any resources.
      Specified by:
        `shutdown` in interface `QueryEngine`

    - #### createQueryContext

          public QueryContext createQueryContext(ExecutionContext context,
                                        RepositoryCache repositoryCache,
                                        Set<String> workspaceNames,
                                        Map<String,NodeCache> overriddenNodeCachesByWorkspaceName,
                                        Schemata schemata,
                                        RepositoryIndexes indexDefns,
                                        NodeTypes nodeTypes,
                                        BufferManager bufferManager,
                                        PlanHints hints,
                                        Map<String,Object> variables)

      Description copied from interface: `QueryEngine`
      Create a new context for query execution.
      Specified by:
        `createQueryContext` in interface `QueryEngine`
      Parameters:
        `context` - the context in which the query is being executed; may not be null
        `repositoryCache` - the repository cache that should be used to load results; may be null if no results are to be loaded
        `workspaceNames` - the name of each workspace to be queried, or an empty set if all the workspaces should be queried; may not be null
        `overriddenNodeCachesByWorkspaceName` - the NodeCache instances that should be used to load results, which will be used instead of the RepositoryCache's NodeCache for a given workspace name; may be null or empty
        `schemata` - the schemata
        `indexDefns` - the definitions for the currently-defined indexes; never null
        `nodeTypes` - the snapshot of node types; may not be null
        `bufferManager` - the buffer manager; may not be null
        `hints` - the hints, or null if there are no hints
        `variables` - the mapping of variables and values, or null if there are no such variables
      Returns:
        the context; never null

    - #### executeOptimizedQuery

          protected QueryResults executeOptimizedQuery(org.modeshape.jcr.query.engine.ScanningQueryEngine.ScanQueryContext context,
                                           QueryCommand command,
                                           QueryResults.Statistics statistics,
                                           PlanNode plan)

      Execute the optimized query defined by the supplied `plan node`.
      Parameters:
        `context` - the context in which the query is to be executed; may not be null
        `command` - the original query; may not be null
        `statistics` - the statistics for the current query execution
        `plan` - the optimized plan for the query; may not be null
      Returns:
        the query results; never null but possibly empty

    - #### createNodeSequence

          protected NodeSequence createNodeSequence(QueryCommand originalQuery,
                                        org.modeshape.jcr.query.engine.ScanningQueryEngine.ScanQueryContext context,
                                        PlanNode plan,
                                        QueryResults.Columns columns,
                                        QuerySources sources)

      Create a node sequence containing the results of the original query as defined by the supplied plan.
      Parameters:
        `originalQuery` - the original query command; may not be null
        `context` - the context in which the query is to be executed; may not be null
        `plan` - the optimized plan for the query; may not be null
        `columns` - the result column definition; may not be null
        `sources` - the query sources for the repository; may not be null
      Returns:
        the sequence of results; null only if the type of plan is not understood

    - #### createNodeSequenceForSource

          protected NodeSequence createNodeSequenceForSource(QueryCommand originalQuery,
                                                 QueryContext context,
                                                 PlanNode sourceNode,
                                                 QueryResults.Columns columns,
                                                 QuerySources sources)

      Create a node sequence for the given source.
      Parameters:
        `originalQuery` - the original query command; may not be null
        `context` - the context in which the query is to be executed; may not be null
        `sourceNode` - the `PlanNode.Type.SOURCE` plan node for one part of a query; may not be null
        `columns` - the result column definition; may not be null
        `sources` - the query sources for the repository; may not be null
      Returns:
        the sequence of results; null only if the type of plan is not understood

    - #### createNodeSequenceForSource

          protected NodeSequence createNodeSequenceForSource(QueryCommand originalQuery,
                                                 QueryContext context,
                                                 PlanNode sourceNode,
                                                 IndexPlan index,
                                                 QueryResults.Columns columns,
                                                 QuerySources sources)

      Create a node sequence for the given index
      Parameters:
        `originalQuery` - the original query command; may not be null
        `context` - the context in which the query is to be executed; may not be null
        `sourceNode` - the `PlanNode.Type.SOURCE` plan node for one part of a query; may not be null
        `index` - the `IndexPlan` specification; may not be null
        `columns` - the result column definition; may not be null
        `sources` - the query sources for the repository; may not be null
      Returns:
        the sequence of results; null only if the type of index is not understood

    - #### createSortingExtractor

          protected RowExtractors.ExtractFromRow createSortingExtractor(List<Ordering> orderings,
                                                            Map<SelectorName,SelectorName> sourceNamesByAlias,
                                                            QueryContext context,
                                                            QueryResults.Columns columns,
                                                            QuerySources sources)

      Create an `RowExtractors.ExtractFromRow` instance that produces for given row a single object that can be used to sort all rows in the specified order.
      Parameters:
        `orderings` - the specification of the sort order; may not be null or empty
        `sourceNamesByAlias` - the map of selector names keyed by their aliases; may not be null but may be empty
        `context` - the context in which the query is to be executed; may not be null
        `columns` - the result column definition; may not be null
        `sources` - the query sources for the repository; may not be null
      Returns:
        the extractor; never null

    - #### createSortingExtractor

          protected RowExtractors.ExtractFromRow createSortingExtractor(Ordering ordering,
                                                            Map<SelectorName,SelectorName> sourceNamesByAlias,
                                                            QueryContext context,
                                                            QueryResults.Columns columns,
                                                            QuerySources sources)

      Create an `RowExtractors.ExtractFromRow` instance that produces for given row a single object that can be used to sort all rows in the specified order.
      Parameters:
        `ordering` - the specification of the sort order; may not be null or empty
        `sourceNamesByAlias` - the map of selector names keyed by their aliases; may not be null but may be empty
        `context` - the context in which the query is to be executed; may not be null
        `columns` - the result column definition; may not be null
        `sources` - the query sources for the repository; may not be null
      Returns:
        the extractor; never null

    - #### createRowFilter

          protected NodeSequence.RowFilter createRowFilter(Constraint constraint,
                                               QueryContext context,
                                               QueryResults.Columns columns,
                                               QuerySources sources)

      Create a `NodeSequence.RowFilter` implementation given the supplied constraints. The resulting filter can be applied to a NodeSequence by using `NodeSequence.filter(NodeSequence, RowFilter)`.
      Parameters:
        `constraint` - the constraints to be applied by the filter; may not be null;
        `context` - the context in which the query is to be executed; may not be null
        `columns` - the result column definition; may not be null
        `sources` - the query sources for the repository; may not be null
      Returns:
        the row filter that implements the constraints; never null

    - #### determineType

          protected TypeSystem.TypeFactory<?> determineType(DynamicOperand operand,
                                                QueryContext context,
                                                QueryResults.Columns columns)

    - #### createExtractFromRow

          protected RowExtractors.ExtractFromRow createExtractFromRow(DynamicOperand operand,
                                                          QueryContext context,
                                                          QueryResults.Columns columns,
                                                          QuerySources sources,
                                                          TypeSystem.TypeFactory<?> defaultType,
                                                          boolean allowMultiValued,
                                                          boolean isLike)

      Create a `RowExtractors.ExtractFromRow` implementation that performs the supplied `DynamicOperand` against a current row in the current batch.
      Parameters:
        `operand` - the dynamic operand
        `context` - the context in which the query is to be executed; may not be null
        `columns` - the result column definition; may not be null
        `sources` - the query sources for the repository; may not be null
        `defaultType` - the type that should be used by default, or null if an exception should be thrown when the type for the property name could not be determined
        `allowMultiValued` - true if the extractor called upon a particular node and multi-valued property return an Object[] that contains all the resulting values of the property, or false if only the first value should be returned
        `isLike` - true if the result will be used in a LIKE operation, or false otherwise; this may affect the number of results that will be returned
      Returns:
        the dynamic operation implementation; never null

    - #### createExtractFromRow

          protected RowExtractors.ExtractFromRow createExtractFromRow(String selectorName,
                                                          String propertyName,
                                                          QueryContext context,
                                                          QueryResults.Columns columns,
                                                          QuerySources sources,
                                                          TypeSystem.TypeFactory<?> defaultType,
                                                          boolean allowMultiValued)

      Create a `RowExtractors.ExtractFromRow` implementation that accesses the value(s) in the property identified by the supplied selector and property names.
      Parameters:
        `selectorName` - the name of the selector containing the node(s) to be accessed; may not be null
        `propertyName` - the name of the property on the node(s) to be accessed; may not be null
        `context` - the context in which the query is to be executed; may not be null
        `columns` - the result column definition; may not be null
        `sources` - the query sources for the repository; may not be null
        `defaultType` - the type that should be used by default, or null if an exception should be thrown when the type for the property name could not be determined
        `allowMultiValued` - true if the extractor called upon a particular node and multi-valued property return an Object[] that contains all the resulting values of the property, or false if only the first value should be returned
      Returns:
        the dynamic operation implementation; never null

    - #### createExtractReferencesFromRow

          protected RowExtractors.ExtractFromRow createExtractReferencesFromRow(String selectorName,
                                                                    QueryContext context,
                                                                    QueryResults.Columns columns,
                                                                    QuerySources sources,
                                                                    TypeSystem.TypeFactory<?> defaultType)

      Create a `RowExtractors.ExtractFromRow` implementation that accesses the REFERENCE value(s) in the properties of the node identified by the supplied selector names.
      Parameters:
        `selectorName` - the name of the selector containing the node(s) to be accessed; may not be null
        `context` - the context in which the query is to be executed; may not be null
        `columns` - the result column definition; may not be null
        `sources` - the query sources for the repository; may not be null
        `defaultType` - the type that should be used by default, or null if an exception should be thrown when the type for the property name could not be determined
      Returns:
        the dynamic operation implementation; never null

    - #### literalValue

          protected static Object literalValue(StaticOperand staticOperand,
                            QueryContext context,
                            TypeSystem.TypeFactory<?> type)

      Get the literal value that is defined in the supplied `StaticOperand`. If the supplied static operand is a `BindVariableValue`, the the variable value is obtained from the `variables` in the `QueryContext`. Otherwise, this method simply casts the `StaticOperand` to a `Literal` value.
      Parameters:
        `staticOperand` - the static operand; may be null
        `context` - the query context; may not be null
        `type` - the type factory for the expected type; may be null if the value should be used as-is
      Returns:
        the literal value; may be null

    - #### literalValues

          protected static Set<?> literalValues(SetCriteria setCriteria,
                             QueryContext context,
                             TypeSystem.TypeFactory<?> type)

    - #### toWildcardExpression

          protected static String toWildcardExpression(String likeExpression)

      Convert the JCR like expression to a Lucene wildcard expression. The JCR like expression uses '%' to match 0 or more characters, '_' to match any single character, '\x' to match the 'x' character, and all other characters to match themselves.
      Parameters:
        `likeExpression` - the like expression; may not be null
      Returns:
        the expression that can be used with a WildcardQuery; never null

    - #### toRegularExpression

          public static String toRegularExpression(String likeExpression)

      Convert the JCR like expression to a regular expression. The JCR like expression uses '%' to match 0 or more characters, '_' to match any single character, '\x' to match the 'x' character, and all other characters to match themselves. Note that if any regex metacharacters appear in the like expression, they will be escaped within the resulting regular expression.
      Parameters:
        `likeExpression` - the like expression; may not be null
      Returns:
        the expression that can be used with a WildcardQuery; never null

Copyright © 2008-2014 JBoss, a division of Red Hat. All Rights Reserved.