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.