10 Introduction to Spatial Web Services

This chapter introduces the Oracle Spatial support for spatial Web services. A Web service enables developers of Oracle Spatial applications to provide feature data and metadata to their application users over the Web.

This chapter contains the following major sections:

Note:

If you are using Spatial Web Feature Service (WFS) or Catalog Services for the Web (CSW) support, and if you have data from a previous release that was indexed using one or more SYS.XMLTABLEINDEX indexes, you must drop the associated indexes before the upgrade and re-create the indexes after the upgrade.

For more information, see Section A.2.

Section 10.1, "Types of Spatial Web Services"
Section 10.2, "Types of Users of Spatial Web Services"
Section 10.3, "Setting Up the Client for Spatial Web Services"
Section 10.4, "Demo Files for Sample Java Client"

10.1 Types of Spatial Web Services

Oracle Spatial provides the following types of Web services:

Geocoding, which enables users to associate spatial locations (longitude and latitude coordinates) with postal addresses. Geocoding support is explained in Chapter 11.
Yellow Pages, which enables users to find businesses by name or category based on their relationship to a location. Yellow Pages support is explained in Chapter 12.
Routing, which provides driving information and instructions for individual or multiple routes. Routing support is explained in Chapter 13.
OpenLS, which provides location-based services based on the Open Location Services Initiative (OpenLS) specification for geocoding, mapping, routing, and yellow pages. OpenLS support is explained in Chapter 14.
Web Feature Services (WFS), which enables users to find features (roads, rivers, and so on) based on their relationship to a location or a nonspatial attribute. WFS support is explained in Chapter 15.
Catalog Services for the Web (CSW), which describes the Oracle Spatial implementation of the Open GIS Consortium specification for catalog services. According to this specification: "Catalogue services support the ability to publish and search collections of descriptive information (metadata) for data, services, and related information objects." CSW support is explained in Chapter 16.

Security considerations for Web services are explained in Chapter 17.

10.2 Types of Users of Spatial Web Services

In the general business sense of the word "user," implementing any spatial Web services application involves the following kinds of people:

Administrators set up the Web services infrastructure. Administrators might create database users, grant privileges and access rights to new and existing database users, and do other operations that affect multiple database users. For Web feature services, administrators register feature tables, publish feature types, and unlock certain accounts.

For example, an administrator might set up the infrastructure to enable access to spatial features, such as roads and rivers.
Application developers create and manage the spatial data and metadata. They create spatial data tables, create spatial indexes, insert rows into the USER_SDO_GEOM_METADATA view, and use Spatial functions and procedures to implement the application logic.

For example, an application developer might create tables of roads and rivers, and implement application logic that enables end users to find roads and rivers based on spatial query criteria.
End users access the services through their Web browsers.

For example, an end user might ask for all roads that are within one mile of a specific river or that intersect (cross) that river.

From the perspective of an administrator, application developers and end users are all "users" because database users must be created to accommodate their needs. Application developers will connect to the database as users with sufficient privileges to create and manage spatial tables and to use Oracle Spatial functions and procedures. End users will access the database through a database user with limited access privileges, typically read-only access to data or limited write access.

The chapters about Spatial Web services are written for administrators and application developers, not for end users.

10.3 Setting Up the Client for Spatial Web Services

Before anyone can use Spatial Web services, you, as an administrator with the DBA role, must ensure that:

The $ORACLE_HOME/md/jlib/sdows.ear file is deployed into an OC4J instance.
The necessary database connections are defined (if you accepted the default location for the sdows.ear file deployment) in the <j2ee_home>/home/applications/sdows/META-INF/data-sources.xml file. This file defines database connections available for use with all Web services, including OpenLS and WFS.

You should then examine and modify the <j2ee_home>/home/applications/sdows/sdows/WEB-INF/conf/WSConfig.xml file, which controls Web services behavior. Example 10-1 shows the Oracle-supplied WSConfig.xml file, which you should modify as needed for your system environment. For more information about how to modify this and other files, see the Readme.txt file for the wsclient.jar demo file (described in Section 10.4)

Example 10-1 WSConfig.xml File

<?xml version="1.0"?>
<!-- This is the configuration file for Oracle 11g Spatial WS. -->
<!-- Note: All paths are resolved relative to where the WEB-INF directory 
           is located, unless specified as an absolute path name. 
-->
 
<WSConfig>
 
  <!-- ****************************************************************** -->
  <!-- ************************ Logging Settings ************************ -->
  <!-- ****************************************************************** -->
 
  <!-- Uncomment the following to modify logging. Possible values are:
       log_level = "fatal"|"error"|"warn"|"info"|"debug"|"finest"  
                 default: info) ;
       log_thread_name = "true" | "false" ;
       log_time = "true" | "false" ;
       one or more log_output elements.
  -->
  <!--
    <logging log_level="info" log_thread_name="false"
             log_time="true">
       <log_output name="System.err" />
       <log_output name="log/ws.log" />
    </logging>
  -->
 
  <!-- ****************************************************************** -->
  <!-- ********************** WFS Cache Settings ************************ -->
  <!-- ****************************************************************** -->
 
   <!-- 
    Uncomment the cached_feature_types tag to specify the list of feature types that are cached. 
    By default no feature types are cached.
   -->
   <!--
   <cached_feature_types>
        <feature_type ns="http://www.example.com/myns1" name="ROADS1" />
        <feature_type ns="http://www.example.com/myns2" name="HIGHWAYS" />
   </cached_feature_types>
   -->
 
   <!-- 
    Uncomment the wfs_cache_sync_interval tag to specify the interval in 
    milliseconds in which the WFS Cache Synchronization thread will run.
    Default is 10000 millisec.
   -->
   <!-- 
   <wfs_cache_sync_interval>10000</wfs_cache_sync_interval>
   -->
 
 
  <!-- ****************************************************************** -->
  <!-- ********************* WFS Parameters********************* -->
  <!-- ****************************************************************** -->
 
 
   <!--
    Uncomment the wfs_admin_conn_name tag to specify the name of the connection in oc4j 
    data-sources.xml configuration file for the spatial_wfs_admin_usr. 
    Default value is jdbc/WFS_ADMIN_CONN_NAME.
   -->
   <!-- 
     <wfs_admin_conn_name>jdbc/WFS_ADMIN_CONN_NAME</wfs_admin_conn_name>
   -->
 
   <!--
    Uncomment the wfs_query_timeout tag to specify the query timeout value,
    which is used, when server-side locking API is called.
    The value of this tag can be a non-negative integer, and its unit is seconds.
    Default value is 10 seconds.
   -->
   <!-- 
     <wfs_query_timeout>10</wfs_query_timeout>
   -->
 
    <!--
    Uncomment the wfs_lock_expiry tag to configure the default wfs lock expiry value,
    which is the expiry time for wfs locks, if lock expiry value is not
    explicitly specified in GetFeatureWithLock or LockFeature requests.
    The value of this tag can be a non-negative integer, and its unit is minutes.
    Default value is 4 minutes.
   -->
   <!-- 
     <wfs_lock_expiry>4</wfs_lock_expiry>
   -->
 
    <!--
    Uncomment the wfs_xsd_loc_url tag to specify the URL of WFS / GML 2.1.2 specification XSDs on your server.
    This MUST be provided.
    -->
 
    <!-- 
     <wfs_xsd_loc_url>http://machine:port/xsds/</wfs_xsd_loc_url>
    -->
 
    <!--
    Uncomment the wfs_ex_xsd_loc_url tag to specify the URL of OGC Exception specification XSDs on your server.
    WFS Exceptions are reports as per this XSD. If this tag is not provided then it will be initialized with 
    the value provided for wfs_xsd_loc_url (by default).
    -->
 
    <!-- 
     <wfs_ex_xsd_loc_url>http://machine:port/xsds/</wfs_ex_xsd_loc_url>
    -->
 
 
    <!--
    Uncomment the gml3_xsd_loc_url tag to specify the URL of GML 3.1.1 specification XSDs on your server.
    This is needed ONLY when using GML3.1.1. 
    -->
 
    <!-- 
     <gml3_xsd_loc_url>http://machine:port/xsds/</gml3_xsd_loc_url>
    -->
 
   <!-- ****************************************************************** -->
   <!-- ********************** CSW Cache Settings ************************ -->
   <!-- ****************************************************************** -->
 
   <!-- 
   <cached_record_types>
        <record_type ns="http://www.opengis.net/cat/csw" name="Record" />
   </cached_record_types>
   <csw_cache_sync_interval>10000</csw_cache_sync_interval>
   <csw_cache_id>CSW_CACHE_ID</csw_cache_id>
   -->
 
   <!-- ****************************************************************** -->
   <!-- ********************* CSW Parameters********************* -->
   <!-- ****************************************************************** -->
   <!-- 
     <csw_admin_conn_name>CSW_ADMIN_CONN_NAME</csw_admin_conn_name>
   -->
 
    <!--
    Uncomment the csw_xsd_loc_url tag to specify the URL of CSW 2.0.0 specification XSDs on your server.
    -->
 
    <!--
     <csw_xsd_loc_url>http://machine:port/xsds/</csw_xsd_loc_url>
    -->
 
    <!--
    Uncomment the csw_ex_xsd_loc_url tag to specify the URL of OWS Exception specification XSDs on your server.
    CSW Exceptions are reports as per this XSD. If this tag is not provided then it will be initialized with 
    the value provided for csw_xsd_loc_url (by default).
    This MUST be provided if you are running CSW.
    -->
    <!-- 
     <csw_ex_xsd_loc_url>http://machine:port/xsds/</csw_ex_xsd_loc_url>
    -->
 
 
  <!-- ****************************************************************** -->
  <!-- ********************* Guest and XML user parameters ************** -->
  <!-- ****************************************************************** -->
 
  <Handlers>
    <OpenLS>
      <JavaClass>           oracle.spatial.ws.openls.OpenLsHandler </JavaClass>
      <Anonymous_xml_user>  SpatialWsXmlUser                       </Anonymous_xml_user>
      <Proxy_management>
        <Proxy_authentication/>
 
        <!--
          or
            <Application_user_management/>
          or
            <Fixed_app_user/>
          -->
 
      </Proxy_management>
    </OpenLS>
 
    <WFS>
      <JavaClass>           oracle.spatial.wfs.WFSHandler </JavaClass>
      <Anonymous_xml_user>  SpatialWsXmlUser                       </Anonymous_xml_user>
      <Proxy_management>    <Proxy_authentication/>                </Proxy_management>
    </WFS>
    <CSW>
      <JavaClass>           oracle.spatial.csw.CSWHandler </JavaClass>
      <Anonymous_xml_user>  SpatialWsXmlUser                       </Anonymous_xml_user>
      <Proxy_management>    <Proxy_authentication/>                </Proxy_management>
    </CSW>
    <SpatialWS_Sdo_Request>
      <JavaClass>           oracle.spatial.ws.svrproxy.SdoRequestHandler </JavaClass>
      <Anonymous_xml_user>  SpatialWsXmlUser                       </Anonymous_xml_user>
      <Proxy_management>    <Proxy_authentication/>                </Proxy_management>
    </SpatialWS_Sdo_Request>
    <SpatialWS_Sdo_Test_Request>
      <JavaClass>           oracle.spatial.ws.svrproxy.SdoTestRequestHandler </JavaClass>
      <Anonymous_xml_user>  SpatialWsXmlUser                       </Anonymous_xml_user>
      <Proxy_management>    <Proxy_authentication/>                </Proxy_management>
    </SpatialWS_Sdo_Test_Request>
    <Network>
      <JavaClass>           oracle.spatial.network.xml.NetworkWSHandler </JavaClass>
      <Proxy_management>    <Fixed_app_user/>                      </Proxy_management>
    </Network>
  </Handlers>
</WSConfig>

You must also perform specific tasks that depend on which Web services you will be supporting for use in your environment. You will probably need to create and grant privileges to database users. You may need to download and load special data (such as for geocoding) or to modify configuration files. See the chapters on individual Web services for any specific requirements.

10.4 Demo Files for Sample Java Client

To help you get started with Spatial Web services, Oracle supplies a. jar file (wsclient.jar) with the source code and related files for setting up a sample Java client. To use this file, follow these steps:

Find wsclient.jar under the Spatial demo directory.
Expand (unzip) wsclient.jar into a directory of your choice.

The top-level directory for all the files in the .jar file is named src.
In the src directory, read the file named Readme.txt and follow its instructions.

The Readme.txt file contains detailed explanations and guidelines.