Class Region

java.lang.Object
adql.db.region.Region

public class Region extends Object
Object representation of a geometric 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 any supported string serialization:

The default serialization is returned by toString(). The default syntax is the one defined by DALI. However, if the type of the represented region is not supported by DALI or if a specific Coordinate System (which is not the default one) is used, then the STC/s syntax is used.

Since:
1.3
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    List all possible region types allowed in an STC-S expression.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    final double[][]
    List of coordinates' pairs.
    final CoordSys
    Coordinate system used by this region.
    final double
    Height of the BOX region.
    final double
    Radius of the CIRCLE region.
    final Region[]
    List of regions unified (UNION), intersected (INTERSECTION) or avoided (NOT).
    Type of the region.
    final double
    Width of the BOX region.
  • Constructor Summary

    Constructors
    Constructor
    Description
    Region(CoordSys coordSys, double[] coordinates)
    Constructor for a POINT/POSITION region.
    Region(CoordSys coordSys, double[][] coordinates)
    Constructor for a POINT/POSITION or a POLYGON region.
    Region(CoordSys coordSys, double[] coordinates, double radius)
    Constructor for a CIRCLE region.
    Region(CoordSys coordSys, double[] coordinates, double width, double height)
    Constructor for a BOX region.
    Region(Region region)
    Constructor for a NOT region.
    Region(Region.RegionType unionOrIntersection, CoordSys coordSys, Region[] regions)
    Constructor for a UNION or INTERSECTION region.
    Build a Region from the given ADQL representation.
  • Method Summary

    Modifier and Type
    Method
    Description
    static Region
    parse(String strRegion)
    Parse the given string serialization of a region.
    Get the DALI representation of this region.
    Get the STC-S representation of this region (in which default values of the coordinate system are explicitly written).
    Convert this region into its corresponding ADQL representation.
    Convert this region into its corresponding ADQL representation.
    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).
     

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
  • Field Details

    • type

      public final Region.RegionType type
      Type of the region.
    • coordSys

      public final 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 Region[] regions
      List of regions unified (UNION), intersected (INTERSECTION) or avoided (NOT).
  • Constructor Details

    • Region

      public Region(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(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(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(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(Region.RegionType unionOrIntersection, CoordSys coordSys, 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(Region region)
    Constructor for a NOT region.
    Parameters:
    region - Any region to not select.
  • Region

    public Region(GeometryFunction geometry) throws 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:
    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 Details

    • parse

      public static Region parse(String strRegion) throws ParseException
      Parse the given string serialization of a region.

      Note: Only two serializations are supported and tested (in this order): DALI and STC/s.

      Parameters:
      strRegion - The string serialization to parse.
      Returns:
      The corresponding region.
      Throws:
      ParseException - If the used serialization is not supported.
      Since:
      2.0
    • toDALI

      public String toDALI()
      Get the DALI representation of this region.

      Warning: The DALI serialization can not include the coordinate system information. Only the coordinates, radius, width and height are then used for this representation. No conversion is done. These values are returned as provided in the given coordinate system.

      Returns:
      Its DALI representation.
    • toSTCS

      public 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.
      See Also:
    • toFullSTCS

      public 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.
      See Also:
    • toString

      public String toString()
      Overrides:
      toString in class Object
    • toGeometry

      public GeometryFunction toGeometry()
      Convert this region into its corresponding ADQL representation.

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

      Returns:
      The corresponding ADQL representation.
      See Also:
    • toGeometry

      public GeometryFunction toGeometry(ADQLQueryFactory factory)
      Convert this region into its corresponding ADQL representation.

      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.