Package spoon.reflect.visitor.chain

Interface CtQuery

All Superinterfaces:
CtQueryable
All Known Implementing Classes:
CtQueryImpl
public interface CtQuery extends CtQueryable

CtQuery represents a query, which can be used to traverse a spoon model and collect children elements in several ways.

Creation: A query is created either from a CtElement, or it can be defined first from Factory.createQuery() and bound to root elements afterwards using setInput(Object...).

Chaining: In a query several steps can be chained, by chaining calls to map functions. The non-null outputs of one step are given as input to the next step. An iterable or array output is considered as a set of different inputs for the next step.

Evaluation: A CtQuery is lazily evaluated once list() or forEach(CtConsumer) are called.

  • Method Summary

    Modifier and Type
    Method
    Description
    CtQuery
    failurePolicy​(QueryFailurePolicy policy)
    Defines whether this query will throw ClassCastException when the output of the previous step cannot be cast to type of input of next step.
    <R extends CtElement>
    CtQuery
    filterChildren​(Filter<R> filter)
    Recursively scans all children elements of an input element.
    <R> R
    first()
    Actually evaluates the query and returns first elements produced in the last step.
    After the first element is found, the query evaluation is terminated.
    <R> R
    first​(Class<R> itemClass)
    Same as first(), but with static typing on the return type and the final filtering, which matches only the first result, which is assignable from that return type.
    <R> void
    forEach​(CtConsumer<R> consumer)
    Actually evaluates the query and for each produced output element of the last step, calls `consumer.accept(outputElement)`.
    boolean
    isTerminated()
     
    <R> List<R>
    list()
    Actually evaluates the query and returns all the elements produced in the last step.
    Note: The type R of the list is not checked by the query.
    <R> List<R>
    list​(Class<R> itemClass)
    Same as list(), but with static typing on the return type and the final filtering, which matches only results, which are assignable from that return type.
    <I> CtQuery
    map​(CtConsumableFunction<I> queryStep)
    Same as map(CtFunction), but the returned object is not handled by java's return statement, but by a call to CtConsumer.accept(Object), this allows efficient and easy to write chained processing, see CtConsumableFunction.
    <I,​ R> CtQuery
    map​(CtFunction<I,​R> function)
    Query elements based on a function, the behavior depends on the return type of the function.
    CtQuery
    name​(String name)
    Sets the name of current query, to identify the current step during debugging of a query
    <R extends CtElement>
    CtQuery
    select​(Filter<R> filter)
    The matched element for which (filter.matches(element)==true) is sent to the next query step.
    <T extends CtQuery>
    T
    setInput​(Object... input)
    Sets (binds) the input of the query.
    void
    terminate()
    Terminates the evaluation of this query.

  • Method Details

    • filterChildren

      <R extends CtElement> CtQuery filterChildren​(Filter<R> filter)
      Recursively scans all children elements of an input element. The matched child element for which (filter.matches(element)==true) are sent to the next query step. Essentially the same as CtElement.getElements(Filter) but more powerful, because it can be chained with other subsequent queries. Note: the input element (the root of the query, `this` if you're in CtElement) is also checked and may thus be also sent to the next step. The elements which throw ClassCastException during Filter.matches(CtElement) are considered as **not matching**, ie. are excluded.
      Specified by:
      filterChildren in interface CtQueryable
      Parameters:
      filter - used to filter scanned children elements of the AST tree. If null then all children elements pass to next step.
      Returns:
      this to support fluent API
      See Also:
      filterChildren(Filter)

    • select

      <R extends CtElement> CtQuery select​(Filter<R> filter)
      The matched element for which (filter.matches(element)==true) is sent to the next query step. The elements which throw ClassCastException during Filter.matches(CtElement) are considered as **not matching**, ie. are excluded.
      Parameters:
      filter - used to detect if input element can pass to next query step
      Returns:
      this to support fluent API

    • map

      <I,​ R> CtQuery map​(CtFunction<I,​R> function)
      Query elements based on a function, the behavior depends on the return type of the function.
      Return type of `function`Behavior
      BooleanSelect elements if the returned value of `function` is true (as for Filter).
      ? extends ObjectSend the returned value of `function` to the next step
      IterableSend each item of the collection to the next step
      Object[]Send each item of the array to the next step

      Specified by:
      map in interface CtQueryable
      Parameters:
      function - a Function with one parameter of type I returning a value of type R
      Returns:
      this to support fluent API
      See Also:
      map(CtFunction)

    • setInput

      <T extends CtQuery> T setInput​(Object... input)
      Sets (binds) the input of the query. If the query is created by CtQueryable.map(spoon.reflect.visitor.chain.CtFunction<I, R>) or CtQueryable.filterChildren(Filter), then the query is already bound to this element. A new call of setInput(Object...) is always possible, it resets the current binding and sets the new one.
      Parameters:
      input -
      Returns:
      this to support fluent API

    • forEach

      <R> void forEach​(CtConsumer<R> consumer)
      Actually evaluates the query and for each produced output element of the last step, calls `consumer.accept(outputElement)`. This avoids to create useless intermediate lists.
      Parameters:
      consumer - The consumer which accepts the results of the query

    • list

      <R> List<R> list()
      Actually evaluates the query and returns all the elements produced in the last step.
      Note: The type R of the list is not checked by the query. So use the type, which matches the results of your query, otherwise the ClassCastException will be thrown when reading the list.
      Returns:
      the list of elements collected by the query.
      See Also:
      for an efficient way of manipulating the elements without creating an intermediate list.

    • list

      <R> List<R> list​(Class<R> itemClass)
      Same as list(), but with static typing on the return type and the final filtering, which matches only results, which are assignable from that return type.
      Returns:
      the list of elements collected by the query.

    • first

      <R> R first()
      Actually evaluates the query and returns first elements produced in the last step.
      After the first element is found, the query evaluation is terminated. Note: The return type R is not checked by the query. So use the type, which matches the results of your query, otherwise the ClassCastException will be thrown.
      Returns:
      the first element found by the query.

    • first

      <R> R first​(Class<R> itemClass)
      Same as first(), but with static typing on the return type and the final filtering, which matches only the first result, which is assignable from that return type.
      Returns:
      the list of elements collected by the query.

    • failurePolicy

      CtQuery failurePolicy​(QueryFailurePolicy policy)
      Defines whether this query will throw ClassCastException when the output of the previous step cannot be cast to type of input of next step. The default value is QueryFailurePolicy.FAIL, which means than exception is thrown when there is a mismatch
      Note: The CtQueryable.filterChildren(Filter) step never throws ClassCastException
      Parameters:
      policy - the policy
      Returns:
      this to support fluent API

    • name

      CtQuery name​(String name)
      Sets the name of current query, to identify the current step during debugging of a query
      Parameters:
      name -
      Returns:
      this to support fluent API

    • map

      <I> CtQuery map​(CtConsumableFunction<I> queryStep)
      Same as map(CtFunction), but the returned object is not handled by java's return statement, but by a call to CtConsumer.accept(Object), this allows efficient and easy to write chained processing, see CtConsumableFunction.
      Specified by:
      map in interface CtQueryable
      Parameters:
      queryStep -
      Returns:
      this to support fluent API
      See Also:
      map(CtConsumableFunction)

    • terminate

      void terminate()
      Terminates the evaluation of this query. The query still returns all results collected before termination. This method should not throw an exception.

    • isTerminated

      boolean isTerminated()
      Returns:
      true if the evaluation has been terminated.