Package adql.search

## Class SimpleReplaceHandler

- java.lang.Object
- - adql.search.SimpleSearchHandler
  - - adql.search.SimpleReplaceHandler

- All Implemented Interfaces:
    `IReplaceHandler`, `ISearchHandler`, `java.lang.Iterable<ADQLObject>`
  Direct Known Subclasses:
    `RemoveHandler`

      public abstract class SimpleReplaceHandler
      extends SimpleSearchHandler
      implements IReplaceHandler

  Lets searching and replacing ADQL objects which match with the condition defined in the function `SimpleSearchHandler.match(ADQLObject)`.

  - By default, this replace handler does not search recursively (that's to say, it does not search in sub-queries).
  - By default, this replace handler does not stop to the first matching object.
  - The matching objects are simply collected in an ArrayList.
  - Matching objects are collected before their replacement.
  Version:
    1.4 (06/2016)
  Author:
    Grégory Mantelet (CDS;ARI)
  See Also:
    `RemoveHandler`

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected int` | `nbReplacement` | Count matching objects which have been replaced successfully.

    - ### Fields inherited from class adql.search.SimpleSearchHandler

      `results`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `SimpleReplaceHandler()` | Builds a SimpleReplaceHandler:
    `SimpleReplaceHandler​(boolean recursive)` | Builds a SimpleReplaceHandler which does not stop at the first match.
    `SimpleReplaceHandler​(boolean recursive, boolean onlyFirstMatch)` | Builds a SimpleReplaceHandler.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected ADQLObject` | `addMatchAndReplace​(ADQLObject matchObj, ADQLIterator it)` | Adds the given ADQL object as one result of the research, and then replace its reference inside its parent.
    `int` | `getNbReplacement()` | Gets the number of matched objects which have been successfully replaced.
    `protected abstract ADQLObject` | `getReplacer​(ADQLObject objToReplace)` | Gets (generate on the fly or not) an ADQLObject which must replace the given one (expected to be an ADQLObject that has matched).
    `protected void` | `reset()` | Resets this handler before the beginning of the research: by default, the list of results is cleared.
    `void` | `searchAndReplace​(ADQLObject startObj)` | Searches all matching ADQL objects from the given ADQL object (included) and replaces them by their corresponding ADQL object.

    - ### Methods inherited from class adql.search.SimpleSearchHandler

      `addMatch, getNbMatch, goInto, isFinished, isRecursive, iterator, match, onlyFirstMatch, search, setOnlyFirstMatch, setRecursive`

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

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

    - ### Methods inherited from interface adql.search.ISearchHandler

      `getNbMatch, iterator, search`

    - ### Methods inherited from interface java.lang.Iterable

      `forEach, spliterator`

- - ### Field Detail

    - #### nbReplacement

          protected int nbReplacement

      Count matching objects which have been replaced successfully.

  - ### Constructor Detail

    - #### SimpleReplaceHandler

          public SimpleReplaceHandler()

      Builds a SimpleReplaceHandler:

      - not recursive,
      - and which does not stop at the first match.

    - #### SimpleReplaceHandler

          public SimpleReplaceHandler​(boolean recursive)

      Builds a SimpleReplaceHandler which does not stop at the first match.
      Parameters:
        `recursive` - true to search also in sub-queries, false otherwise.

    - #### SimpleReplaceHandler

          public SimpleReplaceHandler​(boolean recursive,
                                      boolean onlyFirstMatch)

      Builds a SimpleReplaceHandler.
      Parameters:
        `recursive` - true to search also in sub-queries, false otherwise.
        `onlyFirstMatch` - true to stop at the first match, false otherwise.

  - ### Method Detail

    - #### getNbReplacement

          public int getNbReplacement()

      Description copied from interface: `IReplaceHandler`
      Gets the number of matched objects which have been successfully replaced.
      Specified by:
        `getNbReplacement` in interface `IReplaceHandler`
      Returns:
        The number of replaced objects.

    - #### reset

          protected void reset()

      Description copied from class: `SimpleSearchHandler`
      Resets this handler before the beginning of the research: by default, the list of results is cleared.
      Overrides:
        `reset` in class `SimpleSearchHandler`

    - #### addMatchAndReplace

          protected ADQLObject addMatchAndReplace​(ADQLObject matchObj,
                                                  ADQLIterator it)

      Adds the given ADQL object as one result of the research, and then replace its reference inside its parent.

      Thus, the matched item added in the list is no longer available in its former parent.

      Warning: the second parameter (it) may be null if the given match is the root search object itself.

      Parameters:
        `matchObj` - An ADQL object which has matched to the research criteria.
        `it` - The iterator from which the matched ADQL object has been extracted.
      Returns:
        The match item after replacement if any replacement has occurred, or `null` if the item has been removed, or the object given in parameter if there was no replacement.

    - #### searchAndReplace

          public void searchAndReplace​(ADQLObject startObj)

      Description copied from interface: `IReplaceHandler`
      Searches all matching ADQL objects from the given ADQL object (included) and replaces them by their corresponding ADQL object.
      Specified by:
        `searchAndReplace` in interface `IReplaceHandler`
      Parameters:
        `startObj` - The ADQL object from which the search must start.

    - #### getReplacer

          protected abstract ADQLObject getReplacer​(ADQLObject objToReplace)
                                             throws java.lang.UnsupportedOperationException

      Gets (generate on the fly or not) an ADQLObject which must replace the given one (expected to be an ADQLObject that has matched).

      IMPORTANT: It is the responsibility of the object which calls this method to apply the replacement !

      Note: If the returned value is null it may be interpreted as a removal of the matched ADQL object. Note also that it is still the responsibility of the object which calls this method to apply the removal !

      Parameters:
        `objToReplace` - The ADQL item to replace.
      Returns:
        The replacement ADQL item.
      Throws:
        `java.lang.UnsupportedOperationException` - If the this method must not be used.