Package adql.query

## Class ClauseConstraints

- java.lang.Object
- - adql.query.ADQLList<T>
  - - adql.query.ClauseADQL<ADQLConstraint>
    - - adql.query.ClauseConstraints

- All Implemented Interfaces:
    `ADQLObject`, `java.lang.Iterable<ADQLConstraint>`
  Direct Known Subclasses:
    `ConstraintsGroup`

      public class ClauseConstraints
      extends ClauseADQL<ADQLConstraint>

  Represents a clause which deals with `ADQLConstraint`s (i.e. WHERE, HAVING).

  The logical operators AND (see `AND`) and OR (see `OR`) are managed in a separated list by this class. To add a constraint you can use the default add functions or use the one defined by this class:

  - `add(String, ADQLConstraint`: which lets you specify the logical operator between the added constraint (index=size()) and the previous one (index=size()-1) in the list.
  - `add(int, String, ADQLConstraint`: which lets you specify the logical operator between the added constraint (index) and the previous one (index-1) in the list.

  If no logical separator is specified the default one is used (see `getDefaultSeparator()`). The only way to set this default separator is during the `ClauseConstraints` creation (see `ClauseConstraints(String, String)`).

  Version:
    01/2012
  Author:
    Grégory Mantelet (CDS)
  See Also:
    `ConstraintsGroup`

- - ### Nested Class Summary

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

      `ADQLList.ADQLListIterator`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `AND` | The logical separator AND.
    `protected java.lang.String` | `defaultSeparator` | The logical separator used when none is specified during a constraint insertion (by default = `OR`).
    `static java.lang.String` | `OR` | The logical separator OR (By default, the default separator (see `getDefaultSeparator()`) is equals to OR).

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ClauseConstraints​(ClauseConstraints toCopy)` | Builds a ClauseConstraints by copying the given one.
    `ClauseConstraints​(java.lang.String name)` | Builds a constraints list with only its name (which will prefix the whole list).
    `ClauseConstraints​(java.lang.String name, java.lang.String logicalSep)` | Builds a constraints list with its name and its default separator.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `add​(int index, ADQLConstraint constraint)` | Adds the given item (if not null) at the given position into this clause.
    `void` | `add​(int index, java.lang.String logicalSep, ADQLConstraint constraint)` | Adds the given constraint with the given separator at the given position in the constraints list.
    `boolean` | `add​(ADQLConstraint constraint)` | Adds the given item (if not null) at the end of this clause.
    `boolean` | `add​(java.lang.String logicalSep, ADQLConstraint constraint)` | Adds the given constraint with the given separator.
    `static java.lang.String` | `checkSeparator​(java.lang.String sepToCheck)` | Checks/Converts the given separator in one of the two logical separators.
    `void` | `clear()` | Clears this clause.
    `ADQLObject` | `getCopy()` | Gets a (deep) copy of this ADQL object.
    `java.lang.String` | `getDefaultSeparator()` | Gets the default constraints separator (`AND` or `OR`).
    `java.lang.String[]` | `getPossibleSeparators()` | Only two values in this case: the both logical separators: `AND` and `OR`.
    `java.lang.String` | `getSeparator​(int index)` | Returns always ",", except if the index is incorrect (index <= 0 or index >= size()).
    `ADQLConstraint` | `remove​(int index)` | Removes the specified ADQL item.
    `ADQLConstraint` | `set​(int index, ADQLConstraint constraint)` | Replaces the specified ADQL item by the given one.
    `ADQLConstraint` | `set​(int index, java.lang.String logicalSep, ADQLConstraint constraint)` | Replaces the specified constraint by the given one with the given constraint separator.

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

      `adqlIterator, get, getName, getPosition, isEmpty, iterator, setPosition, size, toADQL`

    - ### 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`

- - ### Field Detail

    - #### OR

          public static final java.lang.String OR

      The logical separator OR (By default, the default separator (see `getDefaultSeparator()`) is equals to OR).
      See Also:
        Constant Field Values

    - #### AND

          public static final java.lang.String AND

      The logical separator AND.
      See Also:
        Constant Field Values

    - #### defaultSeparator

          protected final java.lang.String defaultSeparator

      The logical separator used when none is specified during a constraint insertion (by default = `OR`).

  - ### Constructor Detail

    - #### ClauseConstraints

          public ClauseConstraints​(java.lang.String name)

      Builds a constraints list with only its name (which will prefix the whole list).

      Note: The default separator is automatically set to OR.

      Parameters:
        `name` - The name/prefix of the list.

    - #### ClauseConstraints

          public ClauseConstraints​(java.lang.String name,
                                   java.lang.String logicalSep)

      Builds a constraints list with its name and its default separator.

      Note: if the given separator is no `AND` or `OR`, the default separator is automatically set to `OR`.

      Parameters:
        `name` - The name/prefix of the list.
        `logicalSep` - The constraints separator (a logical separator: `AND` or `OR`).
      See Also:
        `checkSeparator(String)`

    - #### ClauseConstraints

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

      Builds a ClauseConstraints by copying the given one.

      Parameters:
        `toCopy` - The ClauseConstraints to copy.
      Throws:
        `java.lang.Exception` - If there is an error during the copy.
      See Also:
        `checkSeparator(String)`

  - ### Method Detail

    - #### getDefaultSeparator

          public final java.lang.String getDefaultSeparator()

      Gets the default constraints separator (`AND` or `OR`).
      Returns:
        The default separator.

    - #### checkSeparator

          public static final java.lang.String checkSeparator​(java.lang.String sepToCheck)

      Checks/Converts the given separator in one of the two logical separators. If the given separator is neither AND nor OR, then the returned separator is `OR`.
      Parameters:
        `sepToCheck` - The separator to check/convert.
      Returns:
        The understood separator (OR if neither AND nor OR).

    - #### add

          public boolean add​(ADQLConstraint constraint)
                      throws java.lang.NullPointerException

      Description copied from class: `ADQLList`
      Adds the given item (if not null) at the end of this clause.
      Overrides:
        `add` in class `ADQLList<ADQLConstraint>`
      Parameters:
        `constraint` - The ADQL item to add to this clause.
      Returns:
        true if the given item has been successfully added, false otherwise.
      Throws:
        `java.lang.NullPointerException` - If the given item is null.
      See Also:
        `ADQLList.add(adql.query.ADQLObject)`, `add(String, ADQLConstraint)`

    - #### add

          public void add​(int index,
                          ADQLConstraint constraint)
                   throws java.lang.NullPointerException,
                          java.lang.ArrayIndexOutOfBoundsException

      Description copied from class: `ADQLList`
      Adds the given item (if not null) at the given position into this clause.
      Overrides:
        `add` in class `ADQLList<ADQLConstraint>`
      Parameters:
        `index` - Position at which the given item must be added.
        `constraint` - ADQL item to add to this clause.
      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:
        `ADQLList.add(int, adql.query.ADQLObject)`, `add(int, String, ADQLConstraint)`

    - #### add

          public boolean add​(java.lang.String logicalSep,
                             ADQLConstraint constraint)
                      throws java.lang.NullPointerException

      Adds the given constraint with the given separator. The separator is added just before the added constraint, that is to say between the last constraint of the list and the added one.
      Parameters:
        `logicalSep` - The separator to add just before the given constraint.
        `constraint` - The constraint to add.
      Returns:
        true if the constraint has been successfully added, false otherwise.
      Throws:
        `java.lang.NullPointerException` - If the given constraint is null.
      See Also:
        `ADQLList.add(ADQLObject)`, `checkSeparator(String)`

    - #### add

          public void add​(int index,
                          java.lang.String logicalSep,
                          ADQLConstraint constraint)
                   throws java.lang.NullPointerException,
                          java.lang.ArrayIndexOutOfBoundsException

      Adds the given constraint with the given separator at the given position in the constraints list. The separator is added just before the added constraint, that is to say between the (index-1)-th constraint of the list and the added one (at the index position).
      Parameters:
        `index` - Position at which the given constraint must be added.
        `logicalSep` - The constraints separator to add just before the given constraint.
        `constraint` - The constraint to add.
      Throws:
        `java.lang.NullPointerException` - If the given constraint is null.
        `java.lang.ArrayIndexOutOfBoundsException` - If the given index is incorrect (index < 0 || index >= size()).
      See Also:
        `ADQLList.add(int, ADQLObject)`, `checkSeparator(String)`

    - #### set

          public ADQLConstraint set​(int index,
                                    ADQLConstraint constraint)
                             throws java.lang.NullPointerException,
                                    java.lang.ArrayIndexOutOfBoundsException

      Description copied from class: `ADQLList`
      Replaces the specified ADQL item by the given one.
      Overrides:
        `set` in class `ADQLList<ADQLConstraint>`
      Parameters:
        `index` - Position of the item to replace.
        `constraint` - Replacer of the specified ADQL item.
      Returns:
        The replaced ADQL 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()).
      See Also:
        `ADQLList.set(int, adql.query.ADQLObject)`, `set(int, String, ADQLConstraint)`

    - #### set

          public ADQLConstraint set​(int index,
                                    java.lang.String logicalSep,
                                    ADQLConstraint constraint)
                             throws java.lang.NullPointerException,
                                    java.lang.ArrayIndexOutOfBoundsException

      Replaces the specified constraint by the given one with the given constraint separator. The separator is added just before the added constraint, that is to say between the (index-1)-th constraint of the list and the added one (at the index position).
      Parameters:
        `index` - Position of the constraint to replace.
        `logicalSep` - The separator to insert just before the given constraint (if null, the previous separator is kept).
        `constraint` - The replacer.
      Returns:
        The replaced constraint.
      Throws:
        `java.lang.NullPointerException` - If the given constraint is null.
        `java.lang.ArrayIndexOutOfBoundsException` - If the given index is incorrect (index < 0 || index >= size()).
      See Also:
        `ADQLList.set(int, ADQLObject)`

    - #### clear

          public void clear()

      Description copied from class: `ADQLList`
      Clears this clause.
      Overrides:
        `clear` in class `ADQLList<ADQLConstraint>`

    - #### remove

          public ADQLConstraint remove​(int index)
                                throws java.lang.ArrayIndexOutOfBoundsException

      Description copied from class: `ADQLList`
      Removes the specified ADQL item.
      Overrides:
        `remove` in class `ADQLList<ADQLConstraint>`
      Parameters:
        `index` - Index of the ADQL item to remove.
      Returns:
        The removed ADQL item.
      Throws:
        `java.lang.ArrayIndexOutOfBoundsException` - If the index is out of range (index < 0 || index > size()).

    - #### 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<ADQLConstraint>`
      Returns:
        The copy of this ADQL object.
      Throws:
        `java.lang.Exception` - If there is any error during the copy.

    - #### getPossibleSeparators

          public java.lang.String[] getPossibleSeparators()

      Only two values in this case: the both logical separators: `AND` and `OR`.
      Overrides:
        `getPossibleSeparators` in class `ClauseADQL<ADQLConstraint>`
      Returns:
        Possible separators.
      See Also:
        `ADQLList.getPossibleSeparators()`

    - #### getSeparator

          public java.lang.String getSeparator​(int index)
                                        throws java.lang.ArrayIndexOutOfBoundsException

      Description copied from class: `ClauseADQL`
      Returns always ",", except if the index is incorrect (index <= 0 or index >= size()).
      Overrides:
        `getSeparator` in class `ClauseADQL<ADQLConstraint>`
      Parameters:
        `index` - Index of the right list item.
      Returns:
        The corresponding separator.
      Throws:
        `java.lang.ArrayIndexOutOfBoundsException` - If the index is less or equal than 0, or is greater or equal than `size()`.
      See Also:
        `ADQLList.getSeparator(int)`