Skip to main content
Jump to: navigation, search

Difference between revisions of "Introduction to EclipseLink Support for Oracle Spatial (ELUG)"

m (How to Perform Queries Using Spatial Operator Expressions)
m
 
(12 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
[[Image:Elug draft icon.png]] '''For the latest EclipseLink documentation, please see http://www.eclipse.org/eclipselink/documentation/ '''
 +
 +
----
 
<div style="float:right;border:1px solid #000000;padding:5px">__TOC__
 
<div style="float:right;border:1px solid #000000;padding:5px">__TOC__
 
[[Special:Whatlinkshere/Introduction to EclipseLink Support for Oracle Spatial (ELUG)|Related Topics]]</div>
 
[[Special:Whatlinkshere/Introduction to EclipseLink Support for Oracle Spatial (ELUG)|Related Topics]]</div>
Line 9: Line 12:
  
 
==EclipseLink Support for Oracle Spatial==
 
==EclipseLink Support for Oracle Spatial==
 
+
EclipseLink provides support for direct mappings of database columns of type <tt>MDSYS.SDO_GEOMETRY</tt> to attributes of the <tt>oracle.spatial.geometry.JGeometry</tt> data type.  
EclipseLink provides support for direct mappings of database columns of type <tt>MDSYS.SDO_GEOMETRY</tt> to attributes of the <tt>oracle.spatial.geometry.JGeometry</tt> data type. Because this conversion requires an active JDBC connection, perform the conversion in the database platform (see [[Introduction%20to%20Data%20Access%20(ELUG)#Database Platforms|Database Platforms]]) during retrieval from the JDBC result set. Then you must convert into a <tt>STRUCT</tt> type (for writing back into a SQL statement).
+
<!-- Because this conversion requires an active JDBC connection, perform the conversion in the database platform (see [[Introduction%20to%20Data%20Access%20(ELUG)#Database Platforms|Database Platforms]]) during retrieval from the JDBC result set. Then you must convert into a <tt>STRUCT</tt> type (for writing back into a SQL statement).
  
 
Consider the following:
 
Consider the following:
 
* You cannot express the <tt>JGeometry</tt> data type using literal SQL–always convert it to a <tt>STRUCT</tt> type, and then bind.
 
* You cannot express the <tt>JGeometry</tt> data type using literal SQL–always convert it to a <tt>STRUCT</tt> type, and then bind.
* The object-relational data type structure mapping (see [[Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG)#Object-Relational Data Type Structure Mapping|Object-Relational Data Type Structure Mapping]]) enables EclipseLink to build a Java object from the returned <tt>STRUCT</tt> type–instead, allow <tt>JGeometry</tt> to perform the conversion.
+
* The object-relational data type structure mapping (see [[Introduction%20to%20Object-Relational%20Data%20Type%20Mappings%20(ELUG)#Object-Relational Data Type Structure Mapping|Object-Relational Data Type Structure Mapping]]) enables EclipseLink to build a Java object from the returned <tt>STRUCT</tt> type–instead, allow <tt>JGeometry</tt> to perform the conversion. -->
  
 
EclipseLink also provides support for spatial operators (see [[#How to Perform Queries Using Spatial Operator Expressions|How to Perform Queries Using Spatial Operator Expressions]]) through the EclipseLink expression framework (see [[Introduction%20to%20EclipseLink%20Expressions%20(ELUG)#Introduction to EclipseLink Expressions|Introduction to EclipseLink Expressions]]), as well as for custom object types that wrap <tt>SDO_GEOMETRY</tt>.
 
EclipseLink also provides support for spatial operators (see [[#How to Perform Queries Using Spatial Operator Expressions|How to Perform Queries Using Spatial Operator Expressions]]) through the EclipseLink expression framework (see [[Introduction%20to%20EclipseLink%20Expressions%20(ELUG)#Introduction to EclipseLink Expressions|Introduction to EclipseLink Expressions]]), as well as for custom object types that wrap <tt>SDO_GEOMETRY</tt>.
  
For information on configuring OC4J application server to use the EclipseLink structure converter, see ''Oracle Fusion Middleware Administration and Application Deployment Guide for Oracle Containers for Java EE''.
+
For information on using EclipseLink structure converter with application servers (for example, Oracle WebLogic Server, JBoss, or SunAS), see the relevant server documentation.
 
+
For information on using EclipseLink structure converter with other application servers (for example, JBoss, BEA WebLogic Server or SunAS), see the relevant server documentation.
+
  
 
==Using Structure Converters==
 
==Using Structure Converters==
Line 32: Line 33:
  
  
===How to Configure the Database Platform to Use Structure Convertes===
+
===How to Configure the Database Platform to Use Structure Converters===
 
EclipseLink uses a database platform (see [[Introduction%20to%20Data%20Access%20(ELUG)#Database Platforms|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 EclipseLink to use the advanced features of the database.
 
EclipseLink uses a database platform (see [[Introduction%20to%20Data%20Access%20(ELUG)#Database Platforms|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 EclipseLink to use the advanced features of the database.
  
Line 40: Line 41:
 
Use direct-to-field mappings (see [[Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct-to-Field Mapping|Direct-to-Field Mapping]]) to map your <tt>STRUCT</tt> types. For each mapping that maps to the type defined by the structure converter, set its field type to the <tt>STRUCT</tt> data type, as follows:
 
Use direct-to-field mappings (see [[Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct-to-Field Mapping|Direct-to-Field Mapping]]) to map your <tt>STRUCT</tt> types. For each mapping that maps to the type defined by the structure converter, set its field type to the <tt>STRUCT</tt> data type, as follows:
 
  mapping.setFieldType(java.sql.Types.STRUCT);
 
  mapping.setFieldType(java.sql.Types.STRUCT);
 +
 +
  
 
==Using JGeometry==
 
==Using JGeometry==
Line 49: Line 52:
  
 
You can query your mapped entities with expressions that use Spatial operators. For more information, see [[#How to Perform Queries Using Spatial Operator Expressions|How to Perform Queries Using Spatial Operator Expressions]].
 
You can query your mapped entities with expressions that use Spatial operators. For more information, see [[#How to Perform Queries Using Spatial Operator Expressions|How to Perform Queries Using Spatial Operator Expressions]].
 
  
  
 
===How to Configure the Database Platform to Use JGeometry===
 
===How to Configure the Database Platform to Use JGeometry===
To configure the database platform, add a structure converter in a form of the <tt>oracle.toplink.platform.database.oracle.converters.JGeometryConverter</tt> as follows:
+
To configure the database platform, add a structure converter in a form of the <tt>org.eclipse.persistence.platform.database.oracle.converters.JGeometryConverter</tt> as follows:
 
   
 
   
 
  databasePlatform.addStructConverter(new JGeometryConverter());
 
  databasePlatform.addStructConverter(new JGeometryConverter());
  
 
You must configure this platform within your EclipseLink session prior to the session login (see [[Configuring%20a%20Session%20(ELUG)|Configuring a Session Login]]).
 
You must configure this platform within your EclipseLink session prior to the session login (see [[Configuring%20a%20Session%20(ELUG)|Configuring a Session Login]]).
 
 
  
 
===How to Map JGeometry Attributes===
 
===How to Map JGeometry Attributes===
 
Use direct-to-field mappings (see [[Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct-to-Field Mapping|Direct-to-Field Mapping]]) to map your <tt>STRUCT</tt> types. For each mapping that maps to the type defined by the structure converter (<tt>JGeometry</tt>), set its field type to the <tt>STRUCT</tt> data type, as follows:
 
Use direct-to-field mappings (see [[Introduction%20to%20Relational%20Mappings%20(ELUG)#Direct-to-Field Mapping|Direct-to-Field Mapping]]) to map your <tt>STRUCT</tt> types. For each mapping that maps to the type defined by the structure converter (<tt>JGeometry</tt>), set its field type to the <tt>STRUCT</tt> data type, as follows:
 
  mapping.setFieldType(java.sql.Types.STRUCT);
 
  mapping.setFieldType(java.sql.Types.STRUCT);
 
  
  
Line 100: Line 99:
 
* masks;
 
* masks;
 
* <tt>String</tt> of parameters.
 
* <tt>String</tt> of parameters.
 
  
 
The following example demonstrates how to construct a Spatial operator expression, and then relate it to an existing <tt>JGeometry</tt> with <tt>SpatialParameters</tt> created using a <tt>String</tt>.<br>
 
The following example demonstrates how to construct a Spatial operator expression, and then relate it to an existing <tt>JGeometry</tt> with <tt>SpatialParameters</tt> created using a <tt>String</tt>.<br>
Line 123: Line 121:
 
                                                                 expressionBuilder2.get("geometry"),
 
                                                                 expressionBuilder2.get("geometry"),
 
                                                                 parameters);
 
                                                                 parameters);
 +
 +
<span id="Example 108-3"></span>
 +
 +
'''''Using Nearest Neighbor'''''
 +
SpatialParameters parameters = new SpatialParameters();
 +
parameters.setParams("sdo_num_res=10");
 +
Expression expression = SpatialExpressionFactory.nearestNeighbor(expressionBuilder.get("geometry"), geom, parameters);
  
  
Line 130: Line 135:
  
 
[[Category: EclipseLink User's Guide]]
 
[[Category: EclipseLink User's Guide]]
[[Category: Draft]]
+
[[Category: Release 1]]
 
[[Category: Task]]
 
[[Category: Task]]

Latest revision as of 11:16, 23 July 2012

Elug draft icon.png For the latest EclipseLink documentation, please see http://www.eclipse.org/eclipselink/documentation/


This section provides an overview of the EclipseLink support for Oracle Spatial, as well as demonstrates the ways to extend EclipseLink 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


EclipseLink Support for Oracle Spatial

EclipseLink provides support for direct mappings of database columns of type MDSYS.SDO_GEOMETRY to attributes of the oracle.spatial.geometry.JGeometry data type.

EclipseLink also provides support for spatial operators (see How to Perform Queries Using Spatial Operator Expressions) through the EclipseLink expression framework (see Introduction to EclipseLink Expressions), as well as for custom object types that wrap SDO_GEOMETRY.

For information on using EclipseLink structure converter with application servers (for example, Oracle WebLogic Server, JBoss, or SunAS), see the relevant server documentation.

Using Structure Converters

In EclipseLink, a org.eclipse.persistence.platform.database.DatabasePlatform (see Database Platforms) stores a list of structure converters.

To create a custom converter, implement the org.eclipse.persistence.platform.database.converters.StructConverter interface and register it on your direct-to-field mapping (see Direct-to-Field Mapping).

To use the StructConverter, do the following:

  1. Configure the database platform (see How to Configure the Database Platform to Use Structure Convertes).
  2. Set up a mapping (see How to Set Up Mappings Using Structure Converters).


How to Configure the Database Platform to Use Structure Converters

EclipseLink uses a database platform (see 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 EclipseLink 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 EclipseLink session (server or database) prior to the session login (see Configuring a Session Login).

How to Set Up Mappings Using Structure Converters

Use direct-to-field mappings (see 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);


Using JGeometry

To use the oracle.spatial.geometry.JGeometry, do the following:

  1. Configure the database platform (see How to Configure the Database Platform to Use JGeometry).
  2. Set up a mapping (see How to Map JGeometry Attributes).

You can query your mapped entities with expressions that use Spatial operators. For more information, see How to Perform Queries Using Spatial Operator Expressions.


How to Configure the Database Platform to Use JGeometry

To configure the database platform, add a structure converter in a form of the org.eclipse.persistence.platform.database.oracle.converters.JGeometryConverter as follows:

databasePlatform.addStructConverter(new JGeometryConverter());

You must configure this platform within your EclipseLink session prior to the session login (see Configuring a Session Login).

How to Map JGeometry Attributes

Use direct-to-field mappings (see 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);


How to Perform Queries Using Spatial Operator Expressions

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.

Spatial operators are special SQL functions supported by the 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 at http://download.oracle.com/docs/cd/B28359_01/appdev.111/b28401/toc.htm.

EclipseLink provides the expression support for the following Spatial operators:

  • SDO_WITHIN_DISTANCE
  • SDO_RELATE
  • SDO_FILTER
  • SDO_NN

Use the following methods of the org.eclipse.persistence.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:

  1. an expression (org.eclipse.persistence.expressions.Expression) that points to JGeometry;
  2. JGeometry object or an Expression;
  3. an org.eclipse.persistence.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.

The following example demonstrates how to construct a Spatial operator expression, and then relate it to an existing JGeometry with SpatialParameters created using a String.


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

The following example demonstrates how to relate two expressions with SpatialParameters constructed using convenience methods.

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

Using Nearest Neighbor

SpatialParameters parameters = new SpatialParameters();
parameters.setParams("sdo_num_res=10");
Expression expression = SpatialExpressionFactory.nearestNeighbor(expressionBuilder.get("geometry"), geom, parameters);



Copyright Statement

Back to the top