Package adql.translator

## Class PgSphereTranslator

- java.lang.Object
- - adql.translator.JDBCTranslator
  - - adql.translator.PostgreSQLTranslator
    - - adql.translator.PgSphereTranslator

- All Implemented Interfaces:
    `ADQLTranslator`

      public class PgSphereTranslator
      extends PostgreSQLTranslator

  Translates all ADQL objects into the SQL adaptation of Postgres+PgSphere.

  Actually only the geometrical functions and types are translated in this class. The other functions are managed by `PostgreSQLTranslator`.

  Version:
    1.4 (07/2017)
  Author:
    Grégory Mantelet (CDS;ARI)

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `protected static class` | `PgSphereTranslator.PgSphereGeometryParser` | Let parse a geometry serialized with the PgSphere syntax.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected static double` | `ANGLE_CIRCLE_TO_POLYGON` | Angle between two points generated while transforming a circle into a polygon.

    - ### Fields inherited from class adql.translator.PostgreSQLTranslator

      `caseSensitivity`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `PgSphereTranslator()` | Builds a PgSphereTranslator which always translates in SQL all identifiers (schema, table and column) in a case sensitive manner ; in other words, schema, table and column names will be surrounded by double quotes in the SQL translation.
    `PgSphereTranslator​(boolean allCaseSensitive)` | Builds a PgSphereTranslator which always translates in SQL all identifiers (schema, table and column) in the specified case sensitivity ; in other words, schema, table and column names will all be surrounded or not by double quotes in the SQL translation.
    `PgSphereTranslator​(boolean catalog, boolean schema, boolean table, boolean column)` | Builds a PgSphereTranslator which will always translate in SQL identifiers with the defined case sensitivity.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected java.lang.String` | `circleToPolygon​(double[] center, double radius)` | Convert the specified circle into a polygon.
    `DBType` | `convertTypeFromDB​(int dbmsType, java.lang.String rawDbmsTypeName, java.lang.String dbmsTypeName, java.lang.String[] params)` | Convert any type provided by a JDBC driver into a type understandable by the ADQL/TAP library.
    `java.lang.String` | `convertTypeToDB​(DBType type)` | Convert any type provided by the ADQL/TAP library into a type understandable by a JDBC driver.
    `java.lang.String` | `translate​(Comparison comp)` |
    `java.lang.String` | `translate​(AreaFunction areaFunction)` |
    `java.lang.String` | `translate​(BoxFunction box)` |
    `java.lang.String` | `translate​(CentroidFunction centroidFunction)` |
    `java.lang.String` | `translate​(CircleFunction circle)` |
    `java.lang.String` | `translate​(ContainsFunction fct)` |
    `java.lang.String` | `translate​(DistanceFunction fct)` |
    `java.lang.String` | `translate​(ExtractCoord extractCoord)` |
    `java.lang.String` | `translate​(IntersectsFunction fct)` |
    `java.lang.String` | `translate​(PointFunction point)` |
    `java.lang.String` | `translate​(PolygonFunction polygon)` |
    `STCS.Region` | `translateGeometryFromDB​(java.lang.Object jdbcColValue)` | Parse the given JDBC column value as a geometry object and convert it into a `STCS.Region`.
    `java.lang.Object` | `translateGeometryToDB​(STCS.Region region)` | Convert the given STC region into a DB column value.

    - ### Methods inherited from class adql.translator.PostgreSQLTranslator

      `isCaseSensitive, translate, translate, translate, translate`

    - ### Methods inherited from class adql.translator.JDBCTranslator

      `appendIdentifier, appendIdentifier, getColumnName, getDefaultADQLFunction, getDefaultADQLList, getDefaultADQLList, getDefaultColumnReference, getQualifiedSchemaName, getQualifiedTableName, getTableName, translate, translate, translate, translate, translate, translate, translate, translate, translate, translate, translate, translate, translate, translate, translate, translate, translate, translate, translate, translate, translate, translate, translate, translate, translate, translate, translate, translate, translate, translate`

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

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

- - ### Field Detail

    - #### ANGLE_CIRCLE_TO_POLYGON

          protected static double ANGLE_CIRCLE_TO_POLYGON

      Angle between two points generated while transforming a circle into a polygon. This angle is computed by default to get at the end a polygon of 32 points.
      Since:
        1.3
      See Also:
        `circleToPolygon(double[], double)`

  - ### Constructor Detail

    - #### PgSphereTranslator

          public PgSphereTranslator()

      Builds a PgSphereTranslator which always translates in SQL all identifiers (schema, table and column) in a case sensitive manner ; in other words, schema, table and column names will be surrounded by double quotes in the SQL translation.
      See Also:
        `PostgreSQLTranslator()`

    - #### PgSphereTranslator

          public PgSphereTranslator​(boolean allCaseSensitive)

      Builds a PgSphereTranslator which always translates in SQL all identifiers (schema, table and column) in the specified case sensitivity ; in other words, schema, table and column names will all be surrounded or not by double quotes in the SQL translation.
      Parameters:
        `allCaseSensitive` - true to translate all identifiers in a case sensitive manner (surrounded by double quotes), false for case insensitivity.
      See Also:
        `PostgreSQLTranslator(boolean)`

    - #### PgSphereTranslator

          public PgSphereTranslator​(boolean catalog,
                                    boolean schema,
                                    boolean table,
                                    boolean column)

      Builds a PgSphereTranslator which will always translate in SQL identifiers with the defined case sensitivity.
      Parameters:
        `catalog` - true to translate catalog names with double quotes (case sensitive in the DBMS), false otherwise.
        `schema` - true to translate schema names with double quotes (case sensitive in the DBMS), false otherwise.
        `table` - true to translate table names with double quotes (case sensitive in the DBMS), false otherwise.
        `column` - true to translate column names with double quotes (case sensitive in the DBMS), false otherwise.
      See Also:
        `PostgreSQLTranslator(boolean, boolean, boolean, boolean)`

  - ### Method Detail

    - #### translate

          public java.lang.String translate​(PointFunction point)
                                     throws TranslationException

      Specified by:
        `translate` in interface `ADQLTranslator`
      Overrides:
        `translate` in class `PostgreSQLTranslator`
      Throws:
        `TranslationException`

    - #### translate

          public java.lang.String translate​(CircleFunction circle)
                                     throws TranslationException

      Specified by:
        `translate` in interface `ADQLTranslator`
      Overrides:
        `translate` in class `PostgreSQLTranslator`
      Throws:
        `TranslationException`

    - #### translate

          public java.lang.String translate​(BoxFunction box)
                                     throws TranslationException

      Specified by:
        `translate` in interface `ADQLTranslator`
      Overrides:
        `translate` in class `PostgreSQLTranslator`
      Throws:
        `TranslationException`

    - #### translate

          public java.lang.String translate​(PolygonFunction polygon)
                                     throws TranslationException

      Specified by:
        `translate` in interface `ADQLTranslator`
      Overrides:
        `translate` in class `PostgreSQLTranslator`
      Throws:
        `TranslationException`

    - #### translate

          public java.lang.String translate​(ExtractCoord extractCoord)
                                     throws TranslationException

      Specified by:
        `translate` in interface `ADQLTranslator`
      Overrides:
        `translate` in class `PostgreSQLTranslator`
      Throws:
        `TranslationException`

    - #### translate

          public java.lang.String translate​(DistanceFunction fct)
                                     throws TranslationException

      Specified by:
        `translate` in interface `ADQLTranslator`
      Overrides:
        `translate` in class `PostgreSQLTranslator`
      Throws:
        `TranslationException`

    - #### translate

          public java.lang.String translate​(AreaFunction areaFunction)
                                     throws TranslationException

      Specified by:
        `translate` in interface `ADQLTranslator`
      Overrides:
        `translate` in class `PostgreSQLTranslator`
      Throws:
        `TranslationException`

    - #### translate

          public java.lang.String translate​(CentroidFunction centroidFunction)
                                     throws TranslationException

      Specified by:
        `translate` in interface `ADQLTranslator`
      Overrides:
        `translate` in class `PostgreSQLTranslator`
      Throws:
        `TranslationException`

    - #### translate

          public java.lang.String translate​(ContainsFunction fct)
                                     throws TranslationException

      Specified by:
        `translate` in interface `ADQLTranslator`
      Overrides:
        `translate` in class `PostgreSQLTranslator`
      Throws:
        `TranslationException`

    - #### translate

          public java.lang.String translate​(IntersectsFunction fct)
                                     throws TranslationException

      Specified by:
        `translate` in interface `ADQLTranslator`
      Overrides:
        `translate` in class `PostgreSQLTranslator`
      Throws:
        `TranslationException`

    - #### translate

          public java.lang.String translate​(Comparison comp)
                                     throws TranslationException

      Specified by:
        `translate` in interface `ADQLTranslator`
      Overrides:
        `translate` in class `JDBCTranslator`
      Throws:
        `TranslationException`

    - #### convertTypeFromDB

          public DBType convertTypeFromDB​(int dbmsType,
                                          java.lang.String rawDbmsTypeName,
                                          java.lang.String dbmsTypeName,
                                          java.lang.String[] params)

      Description copied from class: `JDBCTranslator`
      Convert any type provided by a JDBC driver into a type understandable by the ADQL/TAP library.
      Overrides:
        `convertTypeFromDB` in class `PostgreSQLTranslator`
      Parameters:
        `dbmsType` - Type returned by a JDBC driver. Note: this value is returned by ResultSetMetadata.getColumnType(int) and correspond to a type of java.sql.Types
        `rawDbmsTypeName` - Full name of the type returned by a JDBC driver. Note: this name is returned by ResultSetMetadata.getColumnTypeName(int) ; this name may contain parameters
        `dbmsTypeName` - Name of type, without the eventual parameters. Note: this name is extracted from rawDbmsTypeName.
        `params` - The eventual type parameters (e.g. char string length). Note: these parameters are extracted from rawDbmsTypeName.
      Returns:
        The corresponding ADQL/TAP type or NULL if the specified type is unknown.

    - #### convertTypeToDB

          public java.lang.String convertTypeToDB​(DBType type)

      Description copied from class: `JDBCTranslator`

      Convert any type provided by the ADQL/TAP library into a type understandable by a JDBC driver.

      Note: The returned DBMS type may contain some parameters between brackets.

      Overrides:
        `convertTypeToDB` in class `PostgreSQLTranslator`
      Parameters:
        `type` - The ADQL/TAP library's type to convert.
      Returns:
        The corresponding DBMS type or NULL if the specified type is unknown.

    - #### translateGeometryFromDB

          public STCS.Region translateGeometryFromDB​(java.lang.Object jdbcColValue)
                                              throws ParseException

      Description copied from class: `JDBCTranslator`

      Parse the given JDBC column value as a geometry object and convert it into a `STCS.Region`.

      Note: Generally the returned object will be used to get its STC-S expression.

      Note: If the given column value is NULL, NULL will be returned.

      Important note: This function is called ONLY for value of columns flagged as geometries by `JDBCTranslator.convertTypeFromDB(int, String, String, String[])`. So the value should always be of the expected type and format. However, if it turns out that the type is wrong and that the conversion is finally impossible, this function SHOULD throw a `ParseException`.

      Overrides:
        `translateGeometryFromDB` in class `PostgreSQLTranslator`
      Parameters:
        `jdbcColValue` - A JDBC column value (returned by ResultSet.getObject(int)).
      Returns:
        The corresponding `STCS.Region` if the given value is a geometry.
      Throws:
        `ParseException` - If the given object is not a geometrical object or can not be transformed into a `STCS.Region` object.

    - #### translateGeometryToDB

          public java.lang.Object translateGeometryToDB​(STCS.Region region)
                                                 throws ParseException

      Description copied from class: `JDBCTranslator`

      Convert the given STC region into a DB column value.

      Note: This function is used only by the UPLOAD feature, to import geometries provided as STC-S expression in a VOTable document inside a DB column.

      Note: If the given region is NULL, NULL will be returned.

      Overrides:
        `translateGeometryToDB` in class `PostgreSQLTranslator`
      Parameters:
        `region` - The region to store in the DB.
      Returns:
        The corresponding DB column object.
      Throws:
        `ParseException` - If the given STC Region can not be converted into a DB object.

    - #### circleToPolygon

          protected java.lang.String circleToPolygon​(double[] center,
                                                     double radius)

      Convert the specified circle into a polygon. The generated polygon is formatted using the PgSphere syntax.

      Note: The center coordinates and the radius are expected in degrees.

      Parameters:
        `center` - Center of the circle ([0]=ra and [1]=dec).
        `radius` - Radius of the circle.
      Returns:
        The PgSphere serialization of the corresponding polygon.
      Since:
        1.3