This chapter provides an overview of the TopLink support for Oracle Spatial, as well as demonstrates the ways to extend TopLink to support the mapping and querying of Oracle Spatial columns (MDSYS.SDO_GEOMETRY).
For more information about Oracle Spatial, see http://www.oracle.com/technology/products/spatial/index.html
This chapter includes the following sections:
TopLink provides support for direct mappings of database columns of type MDSYS.SDO_GEOMETRY to attributes of the oracle.spatial.geometry.JGeometry data type.
TopLink also provides support for spatial operators (see Section 112.3.3, "How to Perform Queries Using Spatial Operator Expressions") through the TopLink expression framework (see Section 110, "Introduction to TopLink Expressions"), as well as for custom object types that wrap SDO_GEOMETRY.
For information on using TopLink structure converter with application servers other than OC4J, see the relevant server documentation.
For information on configuring OC4J application server to use the TopLink structure converter, see Oracle Fusion Middleware Administration and Application Deployment Guide for Oracle Containers for Java EE
In TopLink, a oracle.toplink.platform.database.DatabasePlatform (see Section 96.1.3.1, "Database Platforms") stores a list of structure converters.
To create a custom converter, implement the oracle.toplink.platform.database.converters.StructConverter interface and register it on your direct-to-field mapping (see Section 27.3, "Direct-to-Field Mapping").
To use the StructConverter, do the following:
Configure the database platform (see Section 112.2.1, "How to Configure the Database Platform to Use Structure Converters").
Set up a mapping (see Section 112.2.2, "How to Set Up Mappings Using Structure Converters").
TopLink uses a database platform (see Section 96.1.3.1, "Database Platforms") to control the usage of database vendor-specific and version-specific operations such as SQL dialect, stored procedure calls, sequencing, as well as platform-specific type handling. You need to configure the platform to allow TopLink to use the advanced features of the database.
To add your structure converter to the DatabasePlatform, call addStructConverter(StructConverter converter) method of the DatabasePlatform. Call this method within your TopLink session (server or database) prior to the session login (see Section 89.3, "Configuring a Session Login").
Use direct-to-field mappings (see Section 27.3, "Direct-to-Field Mapping") to map your STRUCT types. For each mapping that maps to the type defined by the structure converter, set its field type to the STRUCT data type, as follows:
mapping.setFieldType(java.sql.Types.STRUCT);
To use the oracle.spatial.geometry.JGeometry, do the following:
Configure the database platform (see Section 112.3.1, "How to Configure the Database Platform to Use JGeometry").
Set up a mapping (see Section 112.3.2, "How to Map JGeometry Attributes").
You can query your mapped entities with expressions that use Spatial operators. For more information, see Section 112.3.3, "How to Perform Queries Using Spatial Operator Expressions".
To configure the database platform, add a structure converter in a form of the oracle.toplink.platform.database.oracle.converters.JGeometryConverter as follows:
databasePlatform.addStructConverter(new JGeometryConverter());
You must configure this platform within your TopLink session prior to the session login (see Section 89.3, "Configuring a Session Login").
Use direct-to-field mappings (see Section 27.3, "Direct-to-Field Mapping") to map your STRUCT types. For each mapping that maps to the type defined by the structure converter (JGeometry), set its field type to the STRUCT data type, as follows:
mapping.setFieldType(java.sql.Types.STRUCT);
With the configured database platform, you can read and write persistent entities with JGeometry attributes mapped to SDO_GEOMETRY columns. With this support, you can query for these mapped entities with native SQL queries using Oracle Spatial operators (see http://download-west.oracle.com/docs/cd/B19306_01/appdev.102/b14255/sdo_operat.htm#i76448).
Spatial operators are special SQL functions supported by Oracle Database to enable querying and comparison of columns containing geometry types. The spatial operators take the following format:
<SPATIAL-OP>(geometry1, geometry2, parameters) = 'TRUE'
For more information on spatial operators, see Oracle Spatial API Documentation.
In its oracle.toplink.expressions.spatial package, TopLink provides the expression support for the following Spatial operators:
SDO_WITHIN_DISTANCE
SDO_RELATE
SDO_FILTER
SDO_NN
Use the following methods of the oracle.toplink.expressions.spatial.SpatialExpressionFactory class to build expressions that use Spatial operators:
withinDistance
relate
filter
nearestNeighbor
All these methods have the following common set of parameters:
an expression (oracle.toplink.expressions.Expression) that points to JGeometry;
JGeometry object or an Expression;
an oracle.toplink.expressions.spatial.SpatialParameters object that defines the parameters to the function call.
The SpatialParameters class provides convenience methods that let you set the parameters representing the following:
minimum resolution;
maximum resolution;
units;
distance;
query type;
masks;
String of parameters.
Example 112-1 demonstrates how to construct a Spatial operator expression, and then relate it to an existing JGeometry with SpatialParameters created using a String.
Example 112-1 Relating an Expression Using String of Spatial Parameters
SpatialParameters parameters =
new SpatialParameters("MASK=ANYINTERACT QUERYTYPE=WINDOW");
Expression selectionCriteria =
SpatialExpressionFactory.relate(expressionBuilder.get("geometry"),
rectangle,
parameters);
Example 112-2 demonstrates how to relate two expressions with SpatialParameters constructed using convenience methods.
Example 112-2 Relating Two Expressions
SpatialParameters parameters = new SpatialParameters();
parameters.setQueryType(
SpatialParameters.QueryType.WINDOW.setMask(Mask.ANYINTERACT);
Expression selectionCriteria =
SpatialExpressionFactory.relate(expressionBuilder1.get("geometry"),
expressionBuilder2.get("geometry"),
parameters);