RDBMS : Spatial Types Support

DataNucleus supports by default a large number of Java types. DataNucleus Spatial supports the storage and query of a number of different spatial data types, like points, polygons or lines. Spatial types like these are used to store geographic information like locations, rivers, cities, roads, etc. The datanucleus-spatial plugin allows using spatial and traditional types simultaneously in persistent objects making DataNucleus a single interface to read and manipulate any business data.

The table below shows the currently supported Spatial SCO Java types in DataNucleus

Java Type Spec. DFG? Persistent? Proxied? PK? Plugin
oracle.spatial.geometry.JGeometry [1] datanucleus-spatial
com.vividsolutions.jts.geom.Geometry [1] datanucleus-spatial
com.vividsolutions.jts.geom.GeometryCollection [1] datanucleus-spatial
com.vividsolutions.jts.geom.LinearRing [1] datanucleus-spatial
com.vividsolutions.jts.geom.LineString [1] datanucleus-spatial
com.vividsolutions.jts.geom.MultiLineString [1] datanucleus-spatial
com.vividsolutions.jts.geom.MultiPoint [1] datanucleus-spatial
com.vividsolutions.jts.geom.MultiPolygon [1] datanucleus-spatial
com.vividsolutions.jts.geom.Point [1] datanucleus-spatial
com.vividsolutions.jts.geom.Polygon [1] datanucleus-spatial
org.postgis.Geometry [1] datanucleus-spatial
org.postgis.GeometryCollection [1] datanucleus-spatial
org.postgis.LinearRing [1] datanucleus-spatial
org.postgis.LineString [1] datanucleus-spatial
org.postgis.MultiLineString [1] datanucleus-spatial
org.postgis.MultiPoint [1] datanucleus-spatial
org.postgis.MultiPolygon [1] datanucleus-spatial
org.postgis.Point [1] datanucleus-spatial
org.postgis.Polygon [1] datanucleus-spatial
org.postgis.PGbox2d [1] datanucleus-spatial
org.postgis.PGbox3d [1] datanucleus-spatial
  • Dirty check mechanism is limited to immutable mode, it means, if you change a field of one of these spatial objects, you must reassign it to the owner object field to make sure changes are propagated to the database.

The implementation of these spatial types follows the OGC Simple Feature specification, but adds further types where the datastores support them.



Mapping Scenarios

DataNucleus supports different combinations of geometry libraries and spatially enabled databases. These combinations are called mapping scenarios . Each of these scenarios has a different set of advantages (and drawbacks), some have restrictions that apply. The table below tries to give as much information as possible about the different scenarios.

One such mapping scenario, is to use the Java geometry types from JTS (Java Topology Suite) and PostGIS as datastore. The short name for this mapping scenario is jts2postgis . The following table lists all supported mapping scenarios.

Geometry Libraries MySQL [1] Oracle [2] [4] PostgreSQL with PostGIS [3] [4] [5]
Oracle's JGeometry jgeom2mysql jgeom2oracle
Java Topology Suite (JTS) jts2mysql jts2oracle jts2postgis
PostGIS JDBC Geometries pg2mysql pg2postgis
  • [1] - MySQL doesn't support 3-dimensional geometries. Trying to persist them anyway results in undefined behaviour , there may be an exception thrown or the z-ordinate might just get stripped.
  • [2] - Oracle Spatial supports additional data types like circles and curves that are not defined in the OGC SF specification. Any attempt to read or persist one of those data types, if you're not using jgeom2oracle , will result in failure!
  • [3] - PostGIS added support for curves in version 1.2.0, but at the moment the JDBC driver doesn't support them yet. Any attempt to read curves geometries will result in failure, for every mapping scenario!
  • [4] - Both PostGIS and Oracle have a system to add user data to specific points of a geometry. In PostGIS these types are called measure types and the z-coordinate of every 2d-point can be used to store arbitrary (numeric) data of double precision associated with that point. In Oracle this user data is called LRS. DataNucleus-Spatial tries to handle these types as gracefully as possible. But the recommendation is to not use them, unless you have a mapping scenario that is known to support them, i.e. pg2postgis for PostGIS and jgeom2oracle for Oracle.
  • [5] - PostGIS supports two additional types called box2d and box3d, that are not defined in OGC SF. There are only mappings available for these types in pg2postgis , any attempt to read or persist one of those data types in another mapping scenario will result in failure!
Spatial types

This table lists all the spatial Java types that are currently supported. The JDBC type is the same for every Java type in a given database. It's SDO_GEOMETRY for Oracle, OTHER for PostGIS and BINARY for MySQL. When a type is supported by a database, the column type that is used for it, is listed after the icon. None of the types are proxied, this means that if you change an object field, you must reassign it to the owner object field to make sure changes are propagated to the database.

Geometry Library Java Type MySQL Oracle PostGIS
JGeometry oracle.spatial.geometry.JGeometry geometry SDO_GEOMETRY
JTS com.vividsolutions.jts.geom.Geometry geometry SDO_GEOMETRY geometry
JTS com.vividsolutions.jts.geom.GeometryCollection geometry SDO_GEOMETRY geometry
JTS com.vividsolutions.jts.geom.LinearRing geometry SDO_GEOMETRY geometry
JTS com.vividsolutions.jts.geom.LineString geometry SDO_GEOMETRY geometry
JTS com.vividsolutions.jts.geom.MultiLineString geometry SDO_GEOMETRY geometry
JTS com.vividsolutions.jts.geom.MultiPoint geometry SDO_GEOMETRY geometry
JTS com.vividsolutions.jts.geom.MultiPolygon geometry SDO_GEOMETRY geometry
JTS com.vividsolutions.jts.geom.Point geometry SDO_GEOMETRY geometry
JTS com.vividsolutions.jts.geom.Polygon geometry SDO_GEOMETRY geometry
PostGIS-JDBC org.postgis.Geometry geometry geometry
PostGIS-JDBC org.postgis.GeometryCollection geometry geometry
PostGIS-JDBC org.postgis.LinearRing geometry geometry
PostGIS-JDBC org.postgis.LineString geometry geometry
PostGIS-JDBC org.postgis.MultiLineString geometry geometry
PostGIS-JDBC org.postgis.MultiPoint geometry geometry
PostGIS-JDBC org.postgis.MultiPolygon geometry geometry
PostGIS-JDBC org.postgis.Point geometry geometry
PostGIS-JDBC org.postgis.Polygon geometry geometry
PostGIS-JDBC org.postgis.PGbox2d box2d
PostGIS-JDBC org.postgis.PGbox3d box3d

Metadata

DataNucleus-Spatial has defined some metadata extensions that can be used to give additional information about the geometry types in use. The position of these tags in the meta-data determines their scope. If you use them inside a <field>-tag the values are only used for that field specifically, if you use them inside the <package>-tag the values are in effect for all (geometry) fields of all classes inside that package, etc.

<package name="org.datanucleus.samples.jtsgeometry">
    <extension vendor-name="datanucleus" key="spatial-dimension" value="2"/> [1]
    <extension vendor-name="datanucleus" key="spatial-srid" value="4326"/> [1]

    <class name="SampleGeometry" detachable="true">
        <field name="id"/>
        <field name="name"/>
        <field name="geom" persistence-modifier="persistent">
            <extension vendor-name="datanucleus" key="mapping" value="no-userdata"/> [2]
        </field>
    </class>

    <class name="SampleGeometryCollectionM" table="samplejtsgeometrycollectionm" detachable="true">
        <extension vendor-name="datanucleus" key="postgis-hasMeasure" value="true"/> [3]
        <field name="id"/>
        <field name="name"/>
        <field name="geom" persistence-modifier="persistent"/>
    </class>

    <class name="SampleGeometryCollection3D" table="samplejtsgeometrycollection3d" detachable="true">
        <extension vendor-name="datanucleus" key="spatial-srid" value="-1"/> [1]
        <extension vendor-name="datanucleus" key="spatial-dimension" value="3"/> [1]
        <field name="id"/>
        <field name="name"/>
        <field name="geom" persistence-modifier="persistent"/>
    </class>
</package>
  • [1] - The srid & dimension values are used in various places. One of them is schema creation, when using PostGIS, another is when you query the SpatialHelper.
  • [2] - Every JTS geometry object can have a user data object attached to it. The default behaviour is to serialize that object and store it in a separate column in the database. If for some reason this isn't desired, the mapping extension can be used with value "no-mapping" and DataNucleus-Spatial will ignore the user data objects.
  • [3] - If you want to use measure types in PostGIS you have to define that using the postgis-hasMeasure extension.
Querying Spatial types

DataNucleus-Spatial defines a set of functions that can be applied to spatial types in JDOQL queries. These functions follow the definitions in the OGC Simple Feature specification and are translated into appropriate SQL statements, provided the underlying database system implements the functions and the geometry object model accordingly. There are also some additional functions that are not defined OGC SF, most of them are database specific.

This set of more than eighty functions contains:

  • Basic methods on geometry objects like IsSimple() and Boundary() .
  • Methods for testing spatial relations between geometric objects like Intersects() and Touches()
  • Methods that support spatial analysis like Union() and Difference()
  • Methods to create geometries from WKB/WKT (Well Known Binary/Text) like GeomFromText() and GeomFromWKB()

For a compelete list of all supported functions and usage examples, please see JDOQL : Spatial Methods.

Dependencies

Depending on the mapping scenario you want to use, there is a different set of JARs that need to be in your classpath.