1. Developer's Guide
  2. Spatial Web Services
  3. Introduction to Spatial Web Services

11 Introduction to Spatial Web Services

This chapter introduces the Oracle Spatial and Graph support for spatial web services.

A web service enables developers of Oracle Spatial and Graph applications to provide feature data and metadata to their application users over the web.

Note:

If you are using Spatial and Graph 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 Index Maintenance Before and After an Upgrade (WFS and CSW).

Topics:

  • Types of Spatial Web Services
    Oracle Spatial and Graph provides the following types of web services.
  • 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.
  • Deploying and Configuring Spatial Web Services
    This topic describes actions that apply to deploying and configuring spatial web services, and particularly WFS, WCS, and CSW.
  • Spatial Web Services Administration Console
    Oracle Spatial and Graph provides a Spatial Web Services administration console, which consists of several components to help configure the WFS, WCS, and CSW web service engines, to test each service, and to display error logs for diagnosis. It is shipped within the sdows.ear.zip file.

11.1 Types of Spatial Web Services

Oracle Spatial and Graph 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 Geocoding Address Data.

  • 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 Business Directory (Yellow Pages) Support.

  • Routing, which provides driving information and instructions for individual or multiple routes. Routing support is explained in Routing Engine.

  • 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 OpenLS Support.

  • 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 Web Feature Service (WFS) Support.

  • Catalog Services for the Web (CSW), which describes the Oracle Spatial and Graph 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 Catalog Services for the Web (CSW) Support.

  • Web Coverage Services (WCS), which provides access to coverage data in forms that are useful for client-side rendering, as input into scientific models, and for other clients.. WCS support is explained in Web Coverage Service (WCS) Support.

    For an overview of WCS, see https://en.wikipedia.org/wiki/Web_Coverage_Service. For an introductory comparison of WCS to related web services, see http://gis.stackexchange.com/questions/80948/what-are-the-differences-between-wms-wfs-wcs-wps.

11.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 can use the WFS Admin Console to register feature tables and publish feature types.

    • For catalog service for the web services, administrators can use CSW Admin Console to publish record types.

    • For web coverage services, administrators can use WCS Admin Console to publish coverages.

    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 HTTP requests using KVP, POST, or SOAP protocol.

    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 and Graph functions and procedures. End users will access the database through OGC operations using a database user with limited access privileges, typically read-only access to data or limited write access.

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

11.3 Deploying and Configuring Spatial Web Services

This topic describes actions that apply to deploying and configuring spatial web services, and particularly WFS, WCS, and CSW.

These services are implemented as Java web applications and can be deployed to run on WebLogic 12.1.3 or later. The required Java version is JDK 1.8 or later. They are packaged in the sdows.ear.zip file.

  • WFS, CSW, and CSW are packaged in the sdows.ear.zip file.

  • The Geocoder service is packaged in the geocoder.ear.zip file.

  • The Routing Engine is packaged in the routeserver.ear.zip file.

In addition to the “general” instructions in this topic, see the chapter about each specific spatial web service that you plan to use for any additional deployment and configuration tasks.

Deploying any Oracle Spatial and Graph web services includes the following major tasks.

  1. Preparing WebLogic Server (Version 12.1.3 or Later)

  2. Creating a Domain on WebLogic Server

  3. Unpacking the sdows.ear.zip File (WFS, WCS, CSW)

  4. Deploying Spatial Web Services on WebLogic Server and Editing the web.xml File

  5. Ensuring the Web Service Web Project is in the Active State

  6. Configuring Each Spatial Web Service

Preparing WebLogic Server (Version 12.1.3 or Later)

Before you deploy the web service engine, it is recommended that you create a managed server in WebLogic Server.

For the Web Service Engine to be successfully deployed on a managed server, a WebLogic domain must be created.

Creating a Domain on WebLogic Server

You must ensure that a domain exists for web services on WebLogic Server. To create a spatial domain, follow these steps.

  1. Log in to the WebLogic Server console.

  2. Select Create a New WebLogic Domain, and click Next.

  3. Select Domain Source: Generate a Domain Configured Automatically, and click Next.

  4. Configure the Administrator Username and Password, and click Next.

  5. For Server Start Mode, select Development or Production.

  6. For JDK, select one of the available JDKs.

  7. For Customize Environment and Service Settings, either accept the default values or specify any customizations.

  8. On the Create WebLogic Domain page, click Create, then Next.

  9. On the Creating Domain page, click Done.

For more information about creating and configuring a domain, see the WebLogic Server documentation.

Unpacking the sdows.ear.zip File (WFS, WCS, CSW)

Before anyone can use Spatial and Graph WFS, WCS, and CSW services, you, as an administrator with the DBA role, must ensure that the sdows.ear.zip file, found in $ORACLE_HOME/md/jlib, is unzipped into a desired directory before deployment. The resulting path should end with an sdows.ear directory, which is sometimes referred to as the sdows exploded directory.

Deploying Spatial Web Services on WebLogic Server and Editing the web.xml File

Spatial web services should be deployed as an exploded directory because log files are generated inside this directory.

For backward compatibility for WFS service only (because WCS 2.0.1 and CSW 2.0.2 are newly added services as of Release 12.2), if you prefer SpatialWS-SpatialWS-context-root (or any other preferred root name), then in the web.xml file, for the <env-entry-name>oracle/spatial/ws/publish_url_as/contextPath</env-entry-name> element, specify the desired value in its <env-entry-value> element. In this case, also modify these other files to reflect a root other than the default oraclespatial: application.xml, context.xml, weblogic.xml, wfs.wsdl and csw202.wsdl.

Similarly, if you need to change the servlet path for WFS, WCS, or CSW, all relevant <env-entry-name> and <env-entry-type> elements in the web.xml file must specify the desired values. For example: 

<env-entry-name>oracle/spatial/ws/publish_url_as/servletPath/wfs</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>

<env-entry-name>oracle/spatial/ws/publish_url_as/servletPath/csw</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>

<env-entry-name>oracle/spatial/ws/publish_url_as/servletPath/wcs</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>

If a proxy server is used as an intermediary for requests from clients, the following env-entry elements in the web.xml file should be edited.

  • oracle/spatial/ws/publish_url_as/host

  • oracle/spatial/ws/publish_url_as/port

  • oracle/spatial/ws/publish_url_as/protocol

  • oracle/spatial/ws/publish_url_as/contextPath

  • oracle/spatial/ws/publish_url_as/servletPath/ws

  • oracle/spatial/ws/publish_url_as/servletPath/wfs

  • oracle/spatial/ws/publish_url_as/servletPath/csw

  • oracle/spatial/ws/publish_url_as/servletPath/wcs

  • oracle/spatial/ws/publish_url_as/xmlservletPath/ws

  • oracle/spatial/ws/publish_url_as/xmlservletPath/wfs

  • oracle/spatial/ws/publish_url_as/xmlservletPath/csw

  • oracle/spatial/ws/publish_url_as/xmlservletPath/wcs

To deploy a spatial web service on WebLogic Server, follow these steps.

  1. Log in to the WLS console

  2. Click Deployments, then Install.

  3. Ensure that Path is set to the application deployment (Exploded Archive) directory.

  4. Select sdows.ear (a directory), and click Next.

  5. Ensure that the Install this deployment as an application targeting style is selected, and click Next.

  6. In the list of potential servers to which to deploy the WFS Engine, select the name of the managed server that you created, select I will make the deployment accessible from the following location, enter the Exploded Archive (Application deployment) Directory, and click Next.

  7. Ensure that the deployment name is sdows, and click Finish.

Ensuring the Web Service Web Project is in the Active State

After completing the necessary steps for a spatial web service, check on the Deployments page that the application is in the Active state.

If it is in the Prepared state, click Start to start the application.

Configuring Each Spatial Web Service

The next step is to configure each spatial web service that you will use (such as WFS, WCS, or CSW) independently. You must 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), modify configuration files or create data sources in WebLogic Server.

See the chapter for each relevant spatial web service for instructions specific to that service.

11.4 Spatial Web Services Administration Console

Oracle Spatial and Graph provides a Spatial Web Services administration console, which consists of several components to help configure the WFS, WCS, and CSW web service engines, to test each service, and to display error logs for diagnosis. It is shipped within the sdows.ear.zip file.

To access the administration console, go to a URL in the following format:

http://<system-name>:<port>/oraclespatial/

  • The Configuration File tabs let you modify service parameters like logging level or service provider information displayed in GetCapabilities response for service.

  • The Test tabs for WFS, WCS, and CSW let you create simple requests for different operations, which you can edit to add or modify parameters, and then send as HTTP POST/XML requests. The responses are also displayed.

  • The Log tabs for WFS, WCS, and CSW let you display the content of the log files for each service. Each Log tab also lets you download the logs compressed in a zip file, so that you can later use the information to diagnose problems.

The console pages and WFS, WCS, and CSW are described in more detail in the chapters about those services.