Class STCS

java.lang.Object
adql.db.region.STCS

public final class STCS extends 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: CoordSys.

To serialize into STC-S a coordinate system, you have to create a CoordSys instance with the desired values and to call the function CoordSys.toSTCS(). The static function toSTCS(CoordSys) is just calling the 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 geometric region: parseRegion(String). Here again, when the parsing is successful an object representation is returned: Region.

This class lets also serializing into STC-S a region, thanks to toSTCS(Region). Alternatively, the shortcut function Region.toSTCS() can be used.

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

Note: The conversion from ADQLFunction to 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
  • Method Details

    • parseCoordSys

      public static CoordSys parseCoordSys(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 String toSTCS(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 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:
    • parseRegion

      public static Region parseRegion(String stcsRegion) throws ParseException
      Parse the given STC-S expression representing a geometric region.
      Parameters:
      stcsRegion - STC-S expression of a region. Note: MUST be different from NULL.
      Returns:
      The object representation of the specified geometric region.
      Throws:
      ParseException - If the given expression is NULL, empty string or if the STC-S syntax is wrong.
    • toSTCS

      public static String toSTCS(Region region)
      Convert into STC-S the given object representation of a geometric region.
      Parameters:
      region - Region to convert into STC-S.
      Returns:
      The corresponding STC-S expression.
      Since:
      2.0
    • toSTCS

      public static String toSTCS(Region region, boolean explicitCoordSys)
      Convert into STC-S the given object representation of a geometric region.
      Parameters:
      region - Region to convert into STC-S.
      Returns:
      The corresponding STC-S expression.
    • toSTCS

      public static String toSTCS(GeometryFunction region) throws ParseException
      Convert into STC-S the given ADQL representation of a geometric 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.