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.

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!

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.

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.

[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.

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()