HHH-14925 Switch for Postgis to javatype/jdbctype

Also some documentation improvements and dead code removal.
This commit is contained in:
Karel Maesen 2021-11-11 12:28:44 +01:00
parent cf477a61ff
commit e48da8d52c
4 changed files with 57 additions and 118 deletions

View File

@ -59,23 +59,6 @@ For Maven, you need to add the following dependency:
----
====
[[spatial-configuration-dialect]]
==== Dialects
Hibernate Spatial extends the Hibernate ORM dialects so that the spatial functions of the database are made available within HQL and JPQL.
So, for instance, instead of using the `PostgreSQL82Dialect`, we use the Hibernate Spatial extension of that dialect which is the `PostgisDialect`.
[[spatial-configuration-dialect-example]]
.Specifying a spatial dialect
====
[source,xml]
----
<property
name="hibernate.dialect"
value="org.hibernate.spatial.dialect.postgis.PostgisDialect"
/>
----
====
Not all databases support all the functions defined by Hibernate Spatial.
The table below provides an overview of the functions provided by each database. If the function is defined in the
@ -88,135 +71,99 @@ relevant section.
.Hibernate Spatial dialect function support
[cols=",,,,,,,," |options="header",]
|================================
|Function | Description | PostgresSQL | Oracle 10g/11g | MySQL | SQLServer | GeoDB (H2) | DB2 | CockroachDB
|Function | Description | PostgresSQL | Oracle 10g/11g | MySQL | SQLServer | H2GIS | DB2 | CockroachDB
|Basic functions on Geometry | | | | | | | |
|`int dimension(Geometry)` | SFS §2.1.1.1 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`String geometrytype(Geometry)` | SFS §2.1.1.1 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`int srid(Geometry)` | SFS §2.1.1.1 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`Geometry envelope(Geometry)` | SFS §2.1.1.1 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`String astext(Geometry)` | SFS §2.1.1.1 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`byte[] asbinary(Geometry)` | SFS §2.1.1.1 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`boolean isempty(Geometry)` | SFS §2.1.1.1 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`boolean issimple(Geometry)` | SFS §2.1.1.1 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`Geometry boundary(Geometry)` | SFS §2.1.1.1 | {yes} | {yes} | {no} | {yes} | {yes} | {yes} | {yes}
|`int st_dimension(Geometry)` | SFS §2.1.1.1 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`String st_geometrytype(Geometry)` | SFS §2.1.1.1 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`int st_srid(Geometry)` | SFS §2.1.1.1 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`Geometry st_envelope(Geometry)` | SFS §2.1.1.1 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`String st_astext(Geometry)` | SFS §2.1.1.1 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`byte[] st_asbinary(Geometry)` | SFS §2.1.1.1 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`boolean st_isempty(Geometry)` | SFS §2.1.1.1 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`boolean st_issimple(Geometry)` | SFS §2.1.1.1 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`Geometry st_boundary(Geometry)` | SFS §2.1.1.1 | {yes} | {yes} | {no} | {yes} | {yes} | {yes} | {yes}
|Functions for testing Spatial Relations between geometric objects | | | | | | | |
|`boolean equals(Geometry, Geometry)` | SFS §2.1.1.2 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`boolean disjoint(Geometry, Geometry)` | SFS §2.1.1.2 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`boolean intersects(Geometry, Geometry)` | SFS §2.1.1.2 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`boolean touches(Geometry, Geometry)` | SFS §2.1.1.2 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`boolean crosses(Geometry, Geometry)` | SFS §2.1.1.2 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`boolean within(Geometry, Geometry)` | SFS §2.1.1.2 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`boolean contains(Geometry, Geometry)` | SFS §2.1.1.2 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`boolean overlaps(Geometry, Geometry)` | SFS §2.1.1.2 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`boolean relate(Geometry, Geometry, String)` | SFS §2.1.1.2 | {yes} | {yes} | {no} | {yes} | {yes} | {yes} | {yes}
|`boolean st_equals(Geometry, Geometry)` | SFS §2.1.1.2 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`boolean st_disjoint(Geometry, Geometry)` | SFS §2.1.1.2 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`boolean st_intersects(Geometry, Geometry)` | SFS §2.1.1.2 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`boolean st_touches(Geometry, Geometry)` | SFS §2.1.1.2 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`boolean st_crosses(Geometry, Geometry)` | SFS §2.1.1.2 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`boolean st_within(Geometry, Geometry)` | SFS §2.1.1.2 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`boolean st_contains(Geometry, Geometry)` | SFS §2.1.1.2 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`boolean st_overlaps(Geometry, Geometry)` | SFS §2.1.1.2 | {yes} | {yes} | {yes} | {yes} | {yes} | {yes} | {yes}
|`boolean st_relate(Geometry, Geometry, String)` | SFS §2.1.1.2 | {yes} | {yes} | {no} | {yes} | {yes} | {yes} | {yes}
|Functions that support Spatial Analysis | | | | | | | |
|`double distance(Geometry, Geometry)` | SFS §2.1.1.3 | {yes} | {yes} | {no} | {yes} | {yes} | {yes} | {yes}
|`Geometry buffer(Geometry, double)` | SFS §2.1.1.3 | {yes} | {yes} | {no} | {yes} | {yes} | {yes} | {yes}
|`Geometry convexhull(Geometry)` | SFS §2.1.1.3 | {yes} | {yes} | {no} | {yes} | {yes} | {yes}^(1)^ | {no}
|`Geometry intersection(Geometry, Geometry)` | SFS §2.1.1.3 | {yes} | {yes} | {no} | {yes} | {yes} | {yes}^(1)^ | {yes}
|`Geometry geomunion(Geometry, Geometry)` | SFS §2.1.1.3 (renamed from union) | {yes} | {yes} | {no} | {yes} | {yes} | {yes}^(1)^ | {yes}
|`Geometry difference(Geometry, Geometry)` | SFS §2.1.1.3 | {yes} | {yes} | {no} | {yes} | {yes} | {yes}^(1)^ | {yes}
|`Geometry symdifference(Geometry, Geometry)` | SFS §2.1.1.3 | {yes} | {yes} | {no} | {yes} | {yes} | {yes}^(1)^ | {yes}
|`double st_distance(Geometry, Geometry)` | SFS §2.1.1.3 | {yes} | {yes} | {no} | {yes} | {yes} | {yes} | {yes}
|`Geometry st_buffer(Geometry, double)` | SFS §2.1.1.3 | {yes} | {yes} | {no} | {yes} | {yes} | {yes} | {yes}
|`Geometry st_convexhull(Geometry)` | SFS §2.1.1.3 | {yes} | {yes} | {no} | {yes} | {yes} | {yes}^(1)^ | {no}
|`Geometry st_intersection(Geometry, Geometry)` | SFS §2.1.1.3 | {yes} | {yes} | {no} | {yes} | {yes} | {yes}^(1)^ | {yes}
|`Geometry st_geomunion(Geometry, Geometry)` | SFS §2.1.1.3 (renamed from union) | {yes} | {yes} | {no} | {yes} | {yes} | {yes}^(1)^ | {yes}
|`Geometry st_difference(Geometry, Geometry)` | SFS §2.1.1.3 | {yes} | {yes} | {no} | {yes} | {yes} | {yes}^(1)^ | {yes}
|`Geometry st_symdifference(Geometry, Geometry)` | SFS §2.1.1.3 | {yes} | {yes} | {no} | {yes} | {yes} | {yes}^(1)^ | {yes}
|Common non-SFS functions | | | | | | | |
|`boolean dwithin(Geometry, Geometry, double)` | Returns true if the geometries are within the specified distance of one another | {yes} | {yes} | {no} | {no} | {yes} | {yes} | {yes}
|`Geometry transform(Geometry, int)` | Returns a new geometry with its coordinates transformed to the SRID referenced by the integer parameter | {yes} | {yes} | {no} | {no} | {no} | {no} | {yes}
|Spatial aggregate Functions | | | | | | | |
|`Geometry extent(Geometry)` | Returns a bounding box that bounds the set of returned geometries | {yes} | {yes} | {no} | {no} | {no} | {no} | {yes}
|`boolean st_dwithin(Geometry, Geometry, double)` | Returns true if the geometries are within the specified distance of one another | {yes} | {yes} | {no} | {no} | {yes} | {yes} | {yes}
|`Geometry st_transform(Geometry, int)` | Returns a new geometry with its coordinates transformed to the SRID referenced by the integer parameter | {yes} | {yes} | {no} | {no} | {no} | {no} | {yes}
|Spatial st_aggregate Functions | | | | | | | |
|`Geometry st_extent(Geometry)` | Returns a bounding box that bounds the set of returned geometries | {yes} | {yes} | {no} | {no} | {no} | {no} | {yes}
|================================
^(1)^ Argument Geometries need to have the same dimensionality.
[[spatial-configuration-dialect-postgis]]
Postgis::
For Postgis from versions 1.3 and later, the best dialect to use is `org.hibernate.spatial.dialect.postgis.PostgisDialect`.
+
This translates the HQL spatial functions to the Postgis SQL/MM-compliant functions.
For older, pre v1.3 versions of Postgis, which are not SQL/MM compliant, the dialect `org.hibernate.spatial.dialect.postgis.PostgisNoSQLMM` is provided.
[NOTE]
====
In previous versions Hibernate Spatial registered the SFS spatial functions under names without the "st_" prefix. Starting
from Hibernate 6.0, the functions are registered both with and without the prefix. So, e.g., both `st_dimension(geom)` and
`dimension(geom)` will work.
====
=== Database notes
[[spatial-configuration-dialect-mysql]]
MySQL::
There are several dialects for MySQL:
`MySQLSpatialDialect`:::
a spatially-extended version of Hibernate `MySQLDialect`
`MySQL5SpatialDialect`:::
a spatially-extended version of Hibernate `MySQL5Dialect`
`MySQLSpatial56Dialect`:::
a spatially-extended version of Hibernate `MySQL55Dialect`.
[NOTE]
====
MySQL versions before 5.6.1 had only limited support for spatial operators.
Most operators only took account of the minimum bounding rectangles (MBR) of the geometries, and not the geometries themselves.
+
This changed in version 5.6.1, when MySQL introduced `ST_*` spatial operators.
The dialect `MySQLSpatial56Dialect` uses these newer, more precise operators.
These dialects may, therefore, produce results that differ from that of the other spatial dialects.
+
For more information, see this page in the MySQL reference guide (esp. the section https://dev.mysql.com/doc/refman/5.7/en/spatial-relation-functions.html[Functions That Test Spatial Relations Between Geometry Objects])
====
[[spatial-configuration-dialect-oracle]]
Oracle10g/11g::
There is currently only one Oracle spatial dialect: `OracleSpatial10gDialect` which extends the Hibernate dialect `Oracle10gDialect`.
This dialect has been tested on both Oracle 10g and Oracle 11g with the `SDO_GEOMETRY` spatial database type.
There is currently only support for the `SDO_GEOMETRY` type.
+
This dialect can be configured using the Hibernate property:
+
`hibernate.spatial.connection_finder`:::
the fully-qualified class name for the implementation of the `ConnectionFinder` to use (see below).
.The `ConnectionFinder` interface
[NOTE]
====
The `SDOGeometryType` requires access to an `OracleConnection` object when converting a geometry to SDO_GEOMETRY.
In some environments, however, the `OracleConnection` is not available (e.g. because a Java EE container or connection pool proxy wraps the connection object in its own `Connection` implementation).
A `ConnectionFinder` knows how to retrieve the `OracleConnection` from the wrapper or proxy Connection object that is passed into prepared statements.
A `ConnectionFinder` knows how to retrieve the `OracleConnection` from the wrapper or proxy Connection object that is passed into prepared statements. It can be configured with the `hibernate.spatial.connection_finder` property:
+
When the passed object is not already an `OracleConnection`, the default implementation will attempt to retrieve the `OracleConnection` by recursive reflection.
It will search for methods that return `Connection` objects, execute these methods and check the result.
If the result is of type `OracleConnection` the object is returned.
Otherwise, it recurses on it.
+
In may cases, this strategy will suffice.
If not, you can provide your own implementation of this interface on the classpath, and configure it in the `hibernate.spatial.connection_finder` property.
Note that implementations must be thread-safe and have a default no-args constructor.
====
SQL Server::
The dialect `SqlServer2008Dialect` supports the `GEOMETRY` type in SQL Server 2008 and later.
Currently, The `GEOGRAPHY` type is not currently supported.
[NOTE]
====
The `GEOGRAPHY` type is not currently supported.
====
CockroachDB::
The dialect `CockroachDB` support the `GEOMETRY` type in CockroachDB v20.2 and later.
[NOTE]
====
The `GEOGRAPHY` type is not currently supported.
====
The dialect `CockroachDB` support the `GEOMETRY` type in CockroachDB v20.2 and later. The `GEOGRAPHY` type is currently not supported.
H2GIS::
The `H2DBDialect` supports the H2GIS, a spatial extension of the H2 in-memory database.
[NOTE]
====
The dialect has been tested with H2GIS version 1.5
====
The `H2DBDialect` supports the H2GIS, a spatial extension of the H2 in-memory database. This dialect can be used as a replacement for the `GeoDB` dialect that was supported in previous versions. The major difference with `GeoDB` is that the `GEOGRAPHY` column type is not present in `H2GIS`.
DB2::
The `DB2SpatialDialect` supports the spatial extensions of the DB2 LUW database.
The dialect has been tested with DB2 LUW 11.1.
The dialect does not support DB2 for z/OS or DB2 column-oriented databases.
[NOTE]
====
+
In order to use the DB2 Hibernate Spatial capabilities, it is necessary to first execute the following
SQL statements which will allow DB2 to accept Extended WellKnown Text (EWKT) data and return EWKT data.
One way to do this is to copy these statements into a file such as ewkt.sql and execute it in a DB2 command window
with a command like 'db2 -tvf ewkt.sql'.
with a command sucha as `db2 -tvf ewkt.sql`.
[source, SQL, indent=0]
----
@ -250,10 +197,6 @@ create transform for db2gse.st_geometry db2_program (
to sql with function db2gse.geomfromewkt(varchar(32000)) );
----
====
[[spatial-types]]
=== Types

View File

@ -41,12 +41,13 @@ sourceSets.test.resources {
tasks.test {
// for now we cannot run with 'h2' project.db due to compatability issues H2 requires 4.200 but H2GIS 1.5 needs 4.197
enabled = ['pgsql',
// 'h2', -- for now we cannot run with 'h2'due to compatability issues we needs H2 at 4.200 but H2GIS only works with 4.197
// 'pgsql_ci', -- disable running in CI until typing issues are resolved
'h2',
'pgsql_ci',
'cockroachdb',
'mariadb',
// 'mysql_ci',
'mysql_docker'].contains( project.db )
'mysql_ci',
'mysql_docker'
].contains( project.db )
}
tasks.test.include '**/*'

View File

@ -16,7 +16,6 @@ import org.hibernate.type.descriptor.jdbc.JdbcLiteralFormatter;
import org.geolatte.geom.Geometry;
import org.geolatte.geom.codec.Wkt;
import org.geolatte.geom.jts.JTS;
public class GeometryLiteralFormatter<T> implements JdbcLiteralFormatter<T> {
@ -41,8 +40,4 @@ public class GeometryLiteralFormatter<T> implements JdbcLiteralFormatter<T> {
appender.appendSql( ")" );
}
private Geometry<?> jts2Gl(T value) {
return JTS.from( (org.locationtech.jts.geom.Geometry) value );
}
}

View File

@ -28,8 +28,8 @@ public class PostgisDialectContributor implements ContributorImplementor {
public void contributeTypes(TypeContributions typeContributions) {
HSMessageLogger.LOGGER.typeContributions( this.getClass().getCanonicalName() );
typeContributions.contributeType( new GeolatteGeometryType( PGGeometryJdbcType.INSTANCE_WKB_2 ) );
typeContributions.contributeType( new JTSGeometryType( PGGeometryJdbcType.INSTANCE_WKB_2 ) );
// typeContributions.contributeType( new GeolatteGeometryType( PGGeometryJdbcType.INSTANCE_WKB_2 ) );
// typeContributions.contributeType( new JTSGeometryType( PGGeometryJdbcType.INSTANCE_WKB_2 ) );
typeContributions.contributeJavaTypeDescriptor( GeolatteGeometryJavaTypeDescriptor.INSTANCE );
typeContributions.contributeJavaTypeDescriptor( JTSGeometryJavaTypeDescriptor.INSTANCE );
typeContributions.contributeJdbcTypeDescriptor( PGGeometryJdbcType.INSTANCE_WKB_2 );