Package adql.query

## Class ClauseSelect

- java.lang.Object
- - adql.query.ADQLList<T>
  - - adql.query.ClauseADQL<SelectItem>
    - - adql.query.ClauseSelect

- All Implemented Interfaces:
    `ADQLObject`, `java.lang.Iterable<SelectItem>`

      public class ClauseSelect
      extends ClauseADQL<SelectItem>

  The SELECT clause of an ADQL query.

  This ADQL clause is not only a list of ADQL items:

  - The user can specify the maximum number of rows the query must return.
  - He can also ask that all the returned rows are unique according to the first returned column.
  Version:
    1.4 (09/2017)
  Author:
    Grégory Mantelet (CDS;ARI)

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class adql.query.ADQLList

      `ADQLList.ADQLListIterator`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ClauseSelect()` | Builds an empty SELECT clause.
    `ClauseSelect​(boolean distinctColumns)` | Builds an empty SELECT clause by specifying whether the returned rows are unique (regarding the first returned columns).
    `ClauseSelect​(boolean distinctColumns, int limit)` | Builds an empty SELECT clause.
    `ClauseSelect​(int limit)` | Builds an empty SELECT clause whose the returned rows must be limited to the given number.
    `ClauseSelect​(ClauseSelect toCopy)` | Builds a SELECT clause by copying the given one.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `add​(int index, ADQLOperand operand)` | Adds an operand to this SELECT clause at the given position.
    `boolean` | `add​(ADQLOperand operand)` | Adds an operand to this SELECT clause.
    `boolean` | `distinctColumns()` | Tells whether this clause imposes that returned rows are unique (regarding the first returned column).
    `ADQLObject` | `getCopy()` | Gets a (deep) copy of this ADQL object.
    `int` | `getLimit()` | Gets the maximum number of rows imposed by this SELECT clause.
    `boolean` | `hasLimit()` | Indicates whether this SELECT clause imposes a maximum number of rows.
    `ADQLOperand` | `searchByAlias​(java.lang.String alias)` | Gets the operand which is associated with the given alias (case sensitive).
    `java.util.List<SelectItem>` | `searchByAlias​(java.lang.String alias, boolean caseSensitive)` | Gets all the select items which are associated with the given alias.
    `ADQLOperand` | `searchByIndex​(int index)` | Gets the specified operand.
    `ADQLOperand` | `set​(int index, ADQLOperand operand)` | Replaces the specified operand by the given one.
    `void` | `setDistinctColumns​(boolean distinct)` | Changes the DISTINCT flag of this SELECT clause.
    `void` | `setLimit​(int limit)` | Changes the maximum number of rows this clause imposes.
    `void` | `setNoLimit()` | Sets no maximum number of rows (classic SELECT).
    `java.lang.String` | `toADQL()` | Gets the ADQL expression of this object.

    - ### Methods inherited from class adql.query.ClauseADQL

      `getPossibleSeparators, getSeparator`

    - ### Methods inherited from class adql.query.ADQLList

      `add, add, adqlIterator, clear, get, getName, getPosition, isEmpty, iterator, remove, set, setPosition, size`

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

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

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

      `forEach, spliterator`

- - ### Constructor Detail

    - #### ClauseSelect

          public ClauseSelect()

      Builds an empty SELECT clause.

    - #### ClauseSelect

          public ClauseSelect​(boolean distinctColumns)

      Builds an empty SELECT clause by specifying whether the returned rows are unique (regarding the first returned columns).
      Parameters:
        `distinctColumns` - true means unique rows (= SELECT DISTINCT), false otherwise (= SELECT or = SELECT ALL).

    - #### ClauseSelect

          public ClauseSelect​(int limit)

      Builds an empty SELECT clause whose the returned rows must be limited to the given number.
      Parameters:
        `limit` - Maximum number of returned rows (= SELECT TOP limit).

    - #### ClauseSelect

          public ClauseSelect​(boolean distinctColumns,
                              int limit)

      Builds an empty SELECT clause.
      Parameters:
        `distinctColumns` - true means unique rows (= SELECT DISTINCT), false otherwise (= SELECT or = SELECT ALL).
        `limit` - Maximum number of returned rows (= SELECT TOP limit).

    - #### ClauseSelect

          public ClauseSelect​(ClauseSelect toCopy)
                       throws java.lang.Exception

      Builds a SELECT clause by copying the given one.
      Parameters:
        `toCopy` - The SELECT clause to copy.
      Throws:
        `java.lang.Exception` - If there is an error during the copy.

  - ### Method Detail

    - #### distinctColumns

          public final boolean distinctColumns()

      Tells whether this clause imposes that returned rows are unique (regarding the first returned column).
      Returns:
        true for SELECT DISTINCT, false for SELECT ALL.

    - #### setDistinctColumns

          public final void setDistinctColumns​(boolean distinct)

      Changes the DISTINCT flag of this SELECT clause.
      Parameters:
        `distinct` - true for SELECY DISTINCT, false for SELECT ALL.

    - #### hasLimit

          public final boolean hasLimit()

      Indicates whether this SELECT clause imposes a maximum number of rows.
      Returns:
        true this clause has a TOP flag, false otherwise.

    - #### getLimit

          public final int getLimit()

      Gets the maximum number of rows imposed by this SELECT clause.
      Returns:
        Maximum number of rows the query must return (SELECT TOP limit).

    - #### setNoLimit

          public final void setNoLimit()

      Sets no maximum number of rows (classic SELECT).

    - #### setLimit

          public final void setLimit​(int limit)

      Changes the maximum number of rows this clause imposes.
      Parameters:
        `limit` - The maximum number of returned rows (SELECT TOP limit).

    - #### add

          public boolean add​(ADQLOperand operand)
                      throws java.lang.NullPointerException

      Adds an operand to this SELECT clause.

      IMPORTANT: The given operand will not be added directly ! It will be encapsulated in a `SelectItem` object which will be then added to the SELECT clause.

      Parameters:
        `operand` - The operand to add.
      Returns:
        true if the operand has been successfully added, false otherwise.
      Throws:
        `java.lang.NullPointerException` - If the given item is null.
      See Also:
        `SelectItem`

    - #### add

          public void add​(int index,
                          ADQLOperand operand)
                   throws java.lang.NullPointerException,
                          java.lang.ArrayIndexOutOfBoundsException

      Adds an operand to this SELECT clause at the given position.

      IMPORTANT: The given operand will not be added directly ! It will be encapsulated in a `SelectItem` object which will be then added to the SELECT clause.

      Parameters:
        `index` - The position at which the given operand must be added.
        `operand` - The operand to add.
      Throws:
        `java.lang.NullPointerException` - If the given item is null.
        `java.lang.ArrayIndexOutOfBoundsException` - If the index is out of range (index < 0 || index > size()).
      See Also:
        `SelectItem`

    - #### set

          public ADQLOperand set​(int index,
                                 ADQLOperand operand)
                          throws java.lang.NullPointerException,
                                 java.lang.ArrayIndexOutOfBoundsException

      Replaces the specified operand by the given one.

      IMPORTANT: The given operand will not be added directly ! It will be encapsulated in a `SelectItem` object which will be then added to the SELECT clause.

      Parameters:
        `index` - The position of the SELECT item to replace.
        `operand` - The replacer of the specified SELECT item.
      Returns:
        The replaced SELECT item.
      Throws:
        `java.lang.NullPointerException` - If the given item is null.
        `java.lang.ArrayIndexOutOfBoundsException` - If the index is out of range (index < 0 || index > size()).

    - #### searchByIndex

          public ADQLOperand searchByIndex​(int index)
                                    throws java.lang.ArrayIndexOutOfBoundsException

      Gets the specified operand.
      Parameters:
        `index` - Index of the operand to retrieve.
      Returns:
        The corresponding operand.
      Throws:
        `java.lang.ArrayIndexOutOfBoundsException` - If the index is out of range (index < 0 || index > size()).

    - #### searchByAlias

          public ADQLOperand searchByAlias​(java.lang.String alias)

      Gets the operand which is associated with the given alias (case sensitive).
      Parameters:
        `alias` - Alias of the operand to retrieve.
      Returns:
        The corresponding operand or null if none has been found.
      See Also:
        `searchByAlias(String, boolean)`

    - #### searchByAlias

          public java.util.List<SelectItem> searchByAlias​(java.lang.String alias,
                                                          boolean caseSensitive)

      Gets all the select items which are associated with the given alias.
      Parameters:
        `alias` - Alias of the operand to retrieve.
      Returns:
        All the corresponding select items.

    - #### getCopy

          public ADQLObject getCopy()
                             throws java.lang.Exception

      Description copied from interface: `ADQLObject`
      Gets a (deep) copy of this ADQL object.
      Specified by:
        `getCopy` in interface `ADQLObject`
      Overrides:
        `getCopy` in class `ClauseADQL<SelectItem>`
      Returns:
        The copy of this ADQL object.
      Throws:
        `java.lang.Exception` - If there is any error during the copy.

    - #### toADQL

          public java.lang.String toADQL()

      Description copied from interface: `ADQLObject`
      Gets the ADQL expression of this object.
      Specified by:
        `toADQL` in interface `ADQLObject`
      Overrides:
        `toADQL` in class `ADQLList<SelectItem>`
      Returns:
        The corresponding ADQL expression.