Package adql.db

## Class STCS.Region

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

- Enclosing class:
    STCS

      public static class STCS.Region
      extends java.lang.Object

  Object representation of an STC region.

  This class contains a field for each possible parameter of a region. Depending of the region type some are not used. In such case, these unused fields are set to NULL.

  An instance of this class can be easily serialized into STC-S using `toSTCS()`, `toFullSTCS()` or `toString()`. `toFullSTCS()` will display default value explicit on the contrary to `toSTCS()` which will replace them by empty strings.

  Since:
    1.3
  Version:
    1.3 (10/2014)
  Author:
    Grégory Mantelet (ARI)

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `double[][]` | `coordinates` | List of coordinates' pairs.
    `STCS.CoordSys` | `coordSys` | Coordinate system used by this region.
    `double` | `height` | Height of the BOX region.
    `double` | `radius` | Radius of the CIRCLE region.
    `STCS.Region[]` | `regions` | List of regions unified (UNION), intersected (INTERSECTION) or avoided (NOT).
    `STCS.RegionType` | `type` | Type of the region.
    `double` | `width` | Width of the BOX region.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Region​(STCS.CoordSys coordSys, double[] coordinates)` | Constructor for a POINT/POSITION region.
    `Region​(STCS.CoordSys coordSys, double[][] coordinates)` | Constructor for a POINT/POSITION or a POLYGON region.
    `Region​(STCS.CoordSys coordSys, double[] coordinates, double radius)` | Constructor for a CIRCLE region.
    `Region​(STCS.CoordSys coordSys, double[] coordinates, double width, double height)` | Constructor for a BOX region.
    `Region​(STCS.Region region)` | Constructor for a NOT region.
    `Region​(STCS.RegionType unionOrIntersection, STCS.CoordSys coordSys, STCS.Region[] regions)` | Constructor for a UNION or INTERSECTION region.
    `Region​(GeometryFunction geometry)` | Build a Region from the given ADQL representation.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.lang.String` | `toFullSTCS()` | Get the STC-S representation of this region (in which default values of the coordinate system are explicitly written).
    `GeometryFunction` | `toGeometry()` | Convert this region into its corresponding ADQL representation.
    `GeometryFunction` | `toGeometry​(ADQLQueryFactory factory)` | Convert this region into its corresponding ADQL representation.
    `java.lang.String` | `toSTCS()` | Get the STC-S representation of this region (in which default values of the coordinate system are not written ; they are replaced by empty strings).
    `java.lang.String` | `toString()` |

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

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

- - ### Field Detail

    - #### type

          public final STCS.RegionType type

      Type of the region.

    - #### coordSys

          public final STCS.CoordSys coordSys

      Coordinate system used by this region. Note: only the NOT region does not declare a coordinate system ; so only for this region this field is NULL.

    - #### coordinates

          public final double[][] coordinates

      List of coordinates' pairs. The second dimension of this array represents a pair of coordinates ; it is then an array of two elements. Note: this field is used by POINT, BOX, CIRCLE and POLYGON.

    - #### width

          public final double width

      Width of the BOX region.

    - #### height

          public final double height

      Height of the BOX region.

    - #### radius

          public final double radius

      Radius of the CIRCLE region.

    - #### regions

          public final STCS.Region[] regions

      List of regions unified (UNION), intersected (INTERSECTION) or avoided (NOT).

  - ### Constructor Detail

    - #### Region

          public Region​(STCS.CoordSys coordSys,
                        double[] coordinates)

      Constructor for a POINT/POSITION region.

      Important note: The array of coordinates is used like that. No copy is done.

      Parameters:
        `coordSys` - Coordinate system. note: It MAY BE null ; if so, the default coordinate system will be chosen
      `coordinates` - A pair of coordinates ; coordinates[0] and coordinates[1].

  - #### Region

        public Region​(STCS.CoordSys coordSys,
                      double[][] coordinates)

    Constructor for a POINT/POSITION or a POLYGON region.

    Whether it is a polygon or a point depends on the number of given coordinates:

    - 1 item => POINT/POSITION
    - more items => POLYGON

    Important note: The array of coordinates is used like that. No copy is done.

    Parameters:
      `coordSys` - Coordinate system. note: It MAY BE null ; if so, the default coordinate system will be chosen
    `coordinates` - List of coordinates' pairs ; coordinates[n] = 1 pair = 2 items (coordinates[n][0] and coordinates[n][1]) ; if 1 pair, it is a POINT/POSITION, but if more, it is a POLYGON.

- #### Region

      public Region​(STCS.CoordSys coordSys,
                    double[] coordinates,
                    double radius)

  Constructor for a CIRCLE region.

  Important note: The array of coordinates is used like that. No copy is done.

  Parameters:
    `coordSys` - Coordinate system. note: It MAY BE null ; if so, the default coordinate system will be chosen
  `coordinates` - A pair of coordinates ; coordinates[0] and coordinates[1].
  `radius` - The circle radius.

- #### Region

      public Region​(STCS.CoordSys coordSys,
                    double[] coordinates,
                    double width,
                    double height)

  Constructor for a BOX region.

  Important note: The array of coordinates is used like that. No copy is done.

  Parameters:
    `coordSys` - Coordinate system. note: It MAY BE null ; if so, the default coordinate system will be chosen
  `coordinates` - A pair of coordinates ; coordinates[0] and coordinates[1].
  `width` - Width of the box.
  `height` - Height of the box.

- #### Region

      public Region​(STCS.RegionType unionOrIntersection,
                    STCS.CoordSys coordSys,
                    STCS.Region[] regions)

  Constructor for a UNION or INTERSECTION region.

  Important note: The array of regions is used like that. No copy is done.

  Parameters:
    `unionOrIntersection` - Type of the region to create. Note: It can be ONLY a UNION or INTERSECTION. Another value will throw an IllegalArgumentException).
    `coordSys` - Coordinate system. note: It MAY BE null ; if so, the default coordinate system will be chosen
  `regions` - Regions to unite or to intersect. Note: At least two regions must be provided.

- #### Region

      public Region​(STCS.Region region)

  Constructor for a NOT region.
  Parameters:
    `region` - Any region to not select.

- #### Region

      public Region​(GeometryFunction geometry)
             throws java.lang.IllegalArgumentException,
                    ParseException

  Build a Region from the given ADQL representation.

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

  Parameters:
    `geometry` - The ADQL representation of the region to create here.
  Throws:
    `java.lang.IllegalArgumentException` - If the given geometry is neither of `PointFunction`, `BoxFunction`, `PolygonFunction` and `RegionFunction`.
    `ParseException` - If the declared coordinate system, the coordinates or the STC-S definition has a wrong syntax.

- ### Method Detail

  - #### toSTCS

        public java.lang.String toSTCS()

    Get the STC-S representation of this region (in which default values of the coordinate system are not written ; they are replaced by empty strings).

    Note: This function build the STC-S just once and store it in a class attribute. The value of this attribute is then returned at next calls of this function.

    Returns:
      Its STC-S representation.

  - #### toFullSTCS

        public java.lang.String toFullSTCS()

    Get the STC-S representation of this region (in which default values of the coordinate system are explicitly written).

    Note: This function build the STC-S just once and store it in a class attribute. The value of this attribute is then returned at next calls of this function.

    Returns:
      Its STC-S representation.

  - #### toString

        public java.lang.String toString()

    Overrides:
      `toString` in class `java.lang.Object`

  - #### toGeometry

        public GeometryFunction toGeometry()

    Convert this region into its corresponding ADQL representation.

    - POSITION: `PointFunction`
    - CIRCLE: `CircleFunction`
    - BOX: `BoxFunction`
    - POLYGON: `PolygonFunction`
    - UNION, INTERSECTION, NOT: `RegionFunction`

    Note: This function is using the default ADQL factory, built using `ADQLQueryFactory()`.

    Returns:
      The corresponding ADQL representation.
    See Also:
      `toGeometry(ADQLQueryFactory)`

  - #### toGeometry

        public GeometryFunction toGeometry​(ADQLQueryFactory factory)

    Convert this region into its corresponding ADQL representation.

    - POSITION: `PointFunction`
    - CIRCLE: `CircleFunction`
    - BOX: `BoxFunction`
    - POLYGON: `PolygonFunction`
    - UNION, INTERSECTION, NOT: `RegionFunction`

    Note: This function build the ADQL representation just once and store it in a class attribute. The value of this attribute is then returned at next calls of this function.

    Parameters:
      `factory` - The factory of ADQL objects to use.
    Returns:
      The corresponding ADQL representation.