JPOX 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 JPOX-Spatial plugin allows
using spatial and traditional types simultaneously in persistent objects making JPOX a single interface to read and manipulate
any business data.
The implementation of these spatial types follows the OGC Simple Feature
specification, but adds further types where the datastores support them.
JPOX 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.
All scenarios are supported in JPOX from version 1.2.0-beta-1, except for jgeom2mysql which will be supported
starting with Version 1.2.0-beta-2.
| 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. JPOX-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!
JPOX-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.jpox.samples.jtsgeometry">
<extension vendor-name="jpox" key="spatial-dimension" value="2"/> [1]
<extension vendor-name="jpox" 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="jpox" key="mapping" value="no-userdata"/> [2]
</field>
</class>
<class name="SampleGeometryCollectionM" table="samplejtsgeometrycollectionm" detachable="true">
<extension vendor-name="jpox" 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="jpox" key="spatial-srid" value="-1"/> [1]
<extension vendor-name="jpox" 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 JPOX-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.
JPOX-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.
Depending on the mapping scenario you want to use, there is a different set of JARs that need to be in your classpath. Please see the
dependencies page for details.
