Package adql.db

## Class STCS

- java.lang.Object
- - adql.db.STCS

-     public final class STCS
      extends java.lang.Object

  This class helps dealing with the subset of STC-S expressions described by the section "6 Use of STC-S in TAP (informative)" of the TAP Recommendation 1.0 (27th March 2010). This subset is limited to the most common coordinate systems and regions.

  Note: No instance of this class can be created. Its usage is only limited to its static functions and classes.

  ### Coordinate system

  The function `parseCoordSys(String)` is able to parse a string containing only the STC-S expression of a coordinate system (or an empty string or null which would be interpreted as the default coordinate system - UNKNOWNFRAME UNKNOWNREFPOS SPHERICAL2). When successful, this parsing returns an object representation of the coordinate system: `STCS.CoordSys`.

  To serialize into STC-S a coordinate system, you have to create a `STCS.CoordSys` instance with the desired values and to call the function `STCS.CoordSys.toSTCS()`. The static function `toSTCS(CoordSys)` is just calling the `STCS.CoordSys.toSTCS()` on the given coordinate system.

  ### Geometrical region

  As for the coordinate system, there is a static function to parse the STC-S representation of a geometrical region: `parseRegion(String)`. Here again, when the parsing is successful an object representation is returned: `STCS.Region`.

  This class lets also serializing into STC-S a region. The procedure is the same as with a coordinate system: create a `STCS.Region` and then call `STCS.Region.toString()`.

  The class `STCS.Region` lets also dealing with the `ADQLFunction` implementing a region. It is then possible to create a `STCS.Region` object from a such `ADQLFunction` and to get the corresponding STC-S representation. The static function `toSTCS(GeometryFunction)` is a helpful function which do these both actions in once.

  Note: The conversion from `ADQLFunction` to `STCS.Region` or STC-S is possible only if the `ADQLFunction` contains constants as parameter. Thus, a such function using a column, a concatenation, a math operation or using another function can not be converted into STC-S using this class.

  Since:
    1.3
  Version:
    1.4 (04/2017)
  Author:
    Grégory Mantelet (ARI)

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `STCS.CoordSys` | Object representation of an STC coordinate system.
    `static class` | `STCS.Flavor` | List of all possible flavors in an STC expression.
    `static class` | `STCS.Frame` | List of all possible frames in an STC expression.
    `static class` | `STCS.RefPos` | List of all possible reference positions in an STC expression.
    `static class` | `STCS.Region` | Object representation of an STC region.
    `static class` | `STCS.RegionType` | List all possible region types allowed in an STC-S expression.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static java.lang.String` | `buildCoordSysRegExp​(java.lang.String[] allowedCoordSys)` | Build a big regular expression gathering all of the given coordinate system syntaxes.
    `static STCS.CoordSys` | `parseCoordSys​(java.lang.String stcs)` | Parse the given STC-S representation of a coordinate system.
    `static STCS.Region` | `parseRegion​(java.lang.String stcsRegion)` | Parse the given STC-S expression representing a geometrical region.
    `static java.lang.String` | `toSTCS​(STCS.CoordSys coordSys)` | Convert an object representation of a coordinate system into an STC-S expression.
    `static java.lang.String` | `toSTCS​(STCS.Region region)` | Convert into STC-S the given object representation of a geometrical region.
    `static java.lang.String` | `toSTCS​(GeometryFunction region)` | Convert into STC-S the given ADQL representation of a geometrical function.

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

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

- - ### Method Detail

    - #### parseCoordSys

          public static STCS.CoordSys parseCoordSys​(java.lang.String stcs)
                                             throws ParseException

      Parse the given STC-S representation of a coordinate system.
      Parameters:
        `stcs` - STC-S expression of a coordinate system. Note: a NULL or empty string will be interpreted as a default coordinate system.
      Returns:
        The object representation of the specified coordinate system.
      Throws:
        `ParseException` - If the given expression has a wrong STC-S syntax.

    - #### toSTCS

          public static java.lang.String toSTCS​(STCS.CoordSys coordSys)

      Convert an object representation of a coordinate system into an STC-S expression.

      Note: A NULL object will be interpreted as the default coordinate system and so an empty string will be returned. Otherwise, this function is equivalent to `STCS.CoordSys.toSTCS()` (in which default values for each coordinate system part is not displayed).

      Parameters:
        `coordSys` - The object representation of the coordinate system to convert into STC-S.
      Returns:
        The corresponding STC-S expression.
      See Also:
        `STCS.CoordSys.toSTCS()`, `STCS.CoordSys.toFullSTCS()`

    - #### buildCoordSysRegExp

          public static java.lang.String buildCoordSysRegExp​(java.lang.String[] allowedCoordSys)
                                                      throws ParseException

      Build a big regular expression gathering all of the given coordinate system syntaxes.

      Each item of the given list must respect a strict syntax. Each part of the coordinate system may be a single value, a list of values or a '*' (meaning all values are allowed). A list of values must have the following syntax: `({value1}|{value2}|...)`. An empty string is NOT here accepted.

      Example: `(ICRS|FK4|FK5) * SPHERICAL2` is OK, but `(ICRS|FK4|FK5) *` is not valid because the flavor value is not defined.

      Since the default value of each part of a coordinate system should always be possible, this function ensure these default values are always possible in the returned regular expression. Thus, if some values except the default one are specified, the default value is automatically appended.

      Note: If the given array is NULL, all coordinate systems are allowed. But if the given array is empty, none except an empty string or the default value will be allowed.

      Parameters:
        `allowedCoordSys` - List of all coordinate systems that are allowed.
      Returns:
        The corresponding regular expression.
      Throws:
        `ParseException` - If the syntax of one of the given allowed coordinate system is wrong.

    - #### parseRegion

          public static STCS.Region parseRegion​(java.lang.String stcsRegion)
                                         throws ParseException

      Parse the given STC-S expression representing a geometrical region.
      Parameters:
        `stcsRegion` - STC-S expression of a region. Note: MUST be different from NULL.
      Returns:
        The object representation of the specified geometrical region.
      Throws:
        `ParseException` - If the given expression is NULL, empty string or if the STC-S syntax is wrong.

    - #### toSTCS

          public static java.lang.String toSTCS​(STCS.Region region)

      Convert into STC-S the given object representation of a geometrical region.
      Parameters:
        `region` - Region to convert into STC-S.
      Returns:
        The corresponding STC-S expression.

    - #### toSTCS

          public static java.lang.String toSTCS​(GeometryFunction region)
                                         throws ParseException

      Convert into STC-S the given ADQL representation of a geometrical function.

      Important note: Only `PointFunction`, `CircleFunction`, `BoxFunction`, `PolygonFunction` and `RegionFunction` are accepted here. Other extensions of `GeometryFunction` will throw an `IllegalArgumentException`.

      Parameters:
        `region` - ADQL representation of the region to convert into STC-S.
      Returns:
        The corresponding STC-S expression.
      Throws:
        `ParseException` - If the given object is NULL or not of the good type.