Using Web Feature Service (WFS) with IBM Informix Dynamic Server

WFS and its IDS server-side UDRs

This article describes the Web Feature Service provided with IBM® Informix® Dynamic Server and shows you how to setup and use the built-in blade and its server-side UDRs, wfsregister(), wfsunregister(), and wfsexplode().

Share:

Carla Kleoppel (kleoppel@us.ibm.com), Staff Software Engineer, IBM

Carla Kleoppel works in the IBM-IDS Quality Assurance Team in areas covering server QA and blades QA.



02 October 2008

Introduction

A trend toward mainstream use of geographic technologies and map visualization has accelerated, as Mapquest®, Google™, Yahoo®, and Microsoft® mapping and route-planning sites have put the power of this approach in the hands of the general public. Mash-up and Web services development have made advanced capabilities easier to access and integrate than ever before, raising expectations that users can apply them to all their business processes and data.

The IBM Informix Dynamic Server 11.10 release has met the challenge by implementing a Web Feature Service (WFS) solution that customers can use as an interface for accessing and creating geographic data via a Web service. This helps the customers' gain platform independence.

This feature provides the ability to:

  • Query a dataset and retrieve features
  • Find the feature definition
  • Add, update, and delete features for a dataset
  • Lock features to prevent modifications

Requests to WFS can be made through HTTP GET or HTTP POST methods and is used in conjunction with the Geodetic DataBlade module and/or the Spatial DataBlade module.

Here is a typical WFS scenario:

  • The Web server receives the request from a client.
  • The Web server invokes the wfsdriver program which obtains information on the location of IDS client libraries, the database name, username and the encrypted password with which to connect to the IDS database.
  • The wfsdriver program connects to IDS and calls the wfsexplode() user-defined routine (UDR) in the shared object library which processes the transaction and formats an XML document to be returned.
  • The XML document is returned to the client. If any errors occurred during processing, an XML error document is returned.

WFS operations

The WFS DataBlade implements a Transaction WFS that supports GetCapabilities, DescribeFeatureType, GetFeature, and Transaction operations.

The GetCapabilities operation defines what the service can provide. It is typically utilized by geospatial mapping tools containing WFS clients to determine what is available from the offered service and to see what datasets are offered and query capabilities that can be used against the service. It lists operations it supports, types it can operate on, query predicates, output formats, and feature types available in that instance.

The DescribeFeatureType operation defines the data types in each type of feature that is served in the WFS. It outputs an XML-based schema that can be utilized to identify each field in the returned feature.

The GetFeature operation is responsible for retrieval and presentation of the data requested. It may consist of one to many queries that will be returned as a unioned set. Please note that joins between tables are not supported, and the query must resolve to a single table.

The Transaction operation allows for creation, modification, and deletion of features stored in WFS.

  • Creation (INSERT) - Requires using XML document, all fields in the table must be specified, and more than one feature instance can be specified in each transaction. Tables in which new identifiers are requested via this type of transaction must contain an IDS serial or serial8 column as the primary key.
  • Modification (UPDATE) – Requires using XML document and must contain one property tag that contains a Name/Value pair to indicate the column/value that is being changed in the feature instance. The XML TransactionResponse document shows the number of rows actually updated; if no rows qualify for the filter, zero is returned as the number of rows updated.
  • Deletion (DELETE) – May be sent via XML document or GET using key-value pairs and only needs to contain a filter. The XML TransactionResponse document shows the number of rows actually removed; if no rows qualify for the filter, zero is returned as the number of rows removed.

Installation and set up

The WFS DataBlade is automatically installed when you perform an installation (or custom installation that includes the built-in DataBlades) of the IDS Server 11.10.xC1 (or higher).

You will also need to install either the Spatial DataBlade 8.21.xC1 (or higher) or the Geodetic DataBlade 3.12.xC1 (or higher) and install a CGI-compliant Web server such as IBM HTTP Server.

In order to complete the installation and setup, you need to follow these steps:

  1. Configure the WFS VP onconfig parameter using the code in Listing 1.
    Listing 1. Configure the WFS VP onconfig parameter:
    VPCLASS WFS,num=1,noyield
  2. Create a database with logging enabled (dbaccess example) as Listing 2 illustrates.
    Listing 2. Create a database with logging enabled (dbaccess example):
    create database testdb with log;
  3. Create a smart, large object space of at least 50MB as in Listing 3.
    Listing 3. Create a smart large object space of at least 50MB:
    onspaces –c –S sbspace –p /IFMXDATA/demo/sbspace –o 0 –s 50000 –Df LOGGING=ON
  4. Register the WFS DataBlade and the Spatial or Geodetic Datablade.
    Listing 4. Register the WFS DataBlade and the Spatial or Geodetic DataBlade:
    blademgr
    demo>list testdb
    There are not modules registered in the database testdb.
    demo>show modules
    ifxrltree.2.00  LLD.1.20.FC2
    mqblade.2.0		binaryudt.1.0
    bts.1.00		wfs.1.00.FC1
    ifxbuiltins.1.1	Node.2.0 c
    geodetic.3.12.FC1	spatial.8.21.FC1
    A ‘c’ indicates DataBlade module has client files.
    If a module is not found, check the prepare log.
    demo>register wfs.1.00.FC1 testdb
    Register module wfs.1.00.fC1 into database testdb? [Y/n]Y
    Registering DataBlade module… (may take a while).
    DataBlade wfs.1.00.FC1 was successfully registered in database testdb.
    Demo>register spatial.8.21.FC1 testdb
    Register module spatial.8.21.FC1 into database testdb? [Y/n]Y
    Registering DataBlade module... (may take a while).
    Module spatial.8.21.FC1 needs interfaces not registered in database testdb.
    The required interface is provided by the modules:
            1 - ifxrltree.2.00
    Select the number of a module above to register, or N :- 1
    Registering DataBlade module... (may take a while).
    DataBlade ifxrltree.2.00 was successfully registered in database testdb.
    Registering DataBlade module... (may take a while).
    DataBlade spatial.8.21.FC1 was successfully registered in database testdb.
    demo>quit
    Disconnecting...
  5. Create a directory that has the same name as your database to be used by the CGI program under where the Web server is installed. This directory contains a copy of the wfsdriver configuration file (wfs.cnf) and the wfsdriver CGI program (wfsdriver.exe).
  6. Run wfssetup. This is located in $INFORMIXDIR/extend/wfs.1.00.xC1/wfsdriver. This is a UNIX script, so users on Microsoft Windows need to create the wfs.cnf manually, as the one shown in Listing 5. This file needs to be placed with a copy of wfsdriver.exe in the CGI directory created in the previous step.
    Listing 5. Sample wfs.cnf file
    <global>
    debug_file C:\temp\wfsdriver.log
    debug_level 2
    </global>
    <setvar>
    INFORMIXDIR C:\PROGRA~1\IBM\IBMINF~1\11.10
    INFORMIXSERVER demo11_tcp
    </setvar>
    <map path=/testdb>
    database testdb
    user informix
    password 3b7d082236d445796cdfc33377400d699
    password_key demokey
    </map>
  7. The password_key value shown above can be generated using the wfspwcrypt utility found in $INFORMIXDIR/extend/wfs.1.00.xC1/wfsdriver.
    Listing 6. Usage and example for wfspwcrypt utility
    Usage:
    wfspwcrypt <database> <user> <key>
    
    Example:
    $ cd $INFORMIXDIR/extend/wfs.1.00.UC1/wfsdriver
    $ wfspwcrypt testdb informix demokey
    Enter password for user 'informix': *******
    Enter password again: *******
    password 5b29c069a79c2c9efc9f366a4d08c15e
    password_key demokey

    Important: If you are using Microsoft Windows as the Web server, you must make sure that the INFORMIXDIR and INFORMIXSERVER values declared in the wfs.cnf match the values as set using the setnet32 utility. This utility is included in both Informix-Connect and Informix Client SDK.

  8. Configure the Web server for the address:port that you want your service to be broadcast on and include the ScriptAlias line similar to the one shown in Listing 7.
    Listing 7. ScriptAlias entry in httpd.conf
    ScriptAlias /testdb “C:\Program Files\IBMHttpServer/testdb”
  9. If your table has a spatial column type, declare the table in sde.geometry_columns via an INSERT statement. This table is created when either the Spatial or Geodetic DataBlade is registered to the database. This allows WFS to understand what spatial reference system is being utilized in that particular table. The loadshp utility, which is included with the Spatial DataBlade, automatically creates a row in this table when tables are created or initialized. The table contains the following columns:
    • f_table_catalog: Typically contains the name of the catalog (database) when used with software such as ESRI ArcGIS. For a table to be enabled with WFS, this value needs to be set to ‘WFS’.
    • f_table_schema: Contains the schema owner name for the table
    • f_table_name: Contains the table name.
    • f_geometry_column: This is the name of the column that stores the point, linestring or polygon. If there are multiple such columns in the table, there needs to be one row in this table per column.
    • storage_type: This column can be set to NULL.
    • geometry_type: This column must be set to the type of geometry stored in the column.
    • coord_dimension: This column can be set to NULL.
    • srid: This column contains the spatial reference system in which the geometry is created. In the Spatial DataBlade, this value must be contained in the sde.spatial_references table. In the Geodetic DataBlade, this value must be contained in the geospatialref table. These tables are created when either the Spatial or Geodetic DataBlades are registered to the database
    Listing 8. Inserting a row into the geometry_columns table for WFS
    INSERT INTO ‘sde’.geometry_columns
    VALUES(‘WFS’,’informix’,’landplaces’, ‘geom’, NULL, 1, NULL, 4);
    1 row(s) inserted.

WFSRegister() UDR

Registering a table with the wfsregister() UDR ensures the table structure contains a single column primary key and does not contain any columns that cannot be mapped to the XML schema response. It also places a row in the table wfstables. This row contains three columns of metadata that can be updated with an SQL UPDATE statement and is in the XML response for a GetCapabilities transaction:

  • Tab_title— title of the table to be presented in geospatial mapping tool
  • Tab_abstract— abstract containing description of the table
  • Tab_keywords— keywords to aid in searching the catalog

Listing 9 shows how to register a table using the wfsregister() UDR.

Listing 9. Execute the wfsregister function (using dbaccess):
database testdb;
Database selected.
CREATE TABLE wfs_demo_table(col1 int, col2 ST_point);
Table created.
ALTER TABLE wfs_demo_table add constraint primary key (col1) constraint wfs_demo_table_pk;
Table altered.
INSERT into ‘sde’.geometry_columns values
(‘WFS’,‘informix’,‘wfs_demo_table’,‘col2’,null,1, null,0);
1 row(s) inserted.
EXECUTE FUNCTION wfsregister(‘wfs_demo_table’);
(expression) OK
UPDATE wfstables SET tab_title=’WFS Demo Title’, tab_abstract=’This dataset contains demo
data for WFS’, tab_keywords=SET{‘Demo’,’WFS’} WHERE regtabname=’wfs_demo_table’;
1 row(s) updated.
SELECT * from wfstables;
1 row(s) retrieved.
regtabname 	wfs_demo_table
tabowner	informix
serialpk_present	f
keycolname 	col1
tab_title 	WFS Demo Title
tab_abstract	This dataset contains demo data for WFS
tab_keywords	SET{‘Demo’,’WFS’}

WFSUnregister() UDR

Unregistering a table with the wfsunregister() UDR removes the row in the table wfstables.

Listing 10 shows how to unregister a table with the wfsunregister() UDR.

Listing 10. Execute the wfsunregister function (using dbaccess):
database testdb;
Database selected.
EXECUTE FUNCTION wfsunregister(‘wfs_demo_table’);
(expression) OK
SELECT * from wfstables;
No rows found.

WFSExplode() UDR

The WFSExplode() UDR function processes the WFS operations and formats an XML document to be returned to the wfsdriver program. If any errors occurred during processing, an XML error document is returned.

Listing 11 shows how the WFSExplode() UDR processes the WFS operation and formats an XML document.

Listing 11. Example of xml file containing insert, update, delete:
<?xml version="1.0" ?>
<wfs:Transaction
        version="1.1.0"
        service="WFS"
        …
        <wfs:Insert idgen="GenerateNew" handle="Stmt 1">
           <natlrestratings>
            <id/>
		<restaurant_id>43546</restaurant_id>
		<foodquality>3</foodquality>
		<servicequality>3</servicequality>
		<comments>Lasagna is great</comments>
		<visit_time>2007-10-07T19:35:00.00000</visit_time>
	   </natlrestratings>
	</wfs:Insert>
	</wfs.Update typeName=”natlrestaurants”>
	   <wfs:Property>
		<wfs:Name>mobilerater:locn</wfs:Name>
		<wfs:Value>
		   <gml:Point>
			<gml:pos>-86.1456333 37.325453</gml:pos>
		   </gml:Point>
		</wfs:Value>
	   </wfs:Property>
	   <ogc:Filter>
		<ogc:GmlObjectId gml:id=”natlrestaurants.43546”/>
	   </ogc:Filter>
	</wfs:Update>
	<wfs:Delete typeName=”natlrestaurants”>
	   <ogc:Filter>
		<ogc:GMLObjectId gml:id=”natlrestaurants.44223”/>
	   </ogc:Filter>
	</wfs:Delete>
</wfs:Transaction>

Listing 12 shows an XML error document that gets returned if there is an error during processing.

Listing 12. Example XML returned document:
<?xml version="1.0" ?>
   <wfs:TransactionResponse
        version="1.1.0"
        service="WFS"
	 …
	<wfs:TransactionSummary>
	   <wfs:totalInserted>1</wfs:totalInserted>
	   <wfs:totalUpdated>1</wfs:totalUpdated>
	   <wfs:totalDeleted>1</wfs:totalDeleted>
	</wfs:TransactionSummary>
	<wfs:InsertResults>
	   <wfs:Feature handle=”Stmt 1”>
		<ogc:FeatureId fid=”natlrestratings.132457364”/>
	   </wfs:Feature>
	</wfs:InsertResults>
</wfs:TransactionResponse>

Listing 13 shows a different way of how to execute the wfsexplode function.

Listing 13. Execute the wfsexplode function (using dbaccess):
Execute function wfsexplode(‘www.yourserver.com’,’/testdb/wfsdriver?’,
FILETOCLOB (‘transactions.xml’,’client’)) into :ret_reg:

Using WFS

A common application that uses WFS is geospatial mapping where features that are stored in the database can be sent to tools such as The Carbon Project’s Gaia 3.

Gaia doesn’t know how to connect to databases, but it does know about Web services such as WFS and mapping services such as Yahoo! Maps. A combination of different tools and services can be used in layers to create a rich display for analysis and annotation.

Figure 1 shows a screenshot of Gaia 3 that has multiple layers defined using WFS and Yahoo! Maps providing the base map. The layers shown are US airports, landmarks, water polygons, landmark polygons, and earthquake data.

Figure 1. Gaia 3 Screenshot, courtesy of The Carbon Project.

Figure 2 shows how layers can be added by using Tools->Add Layer. Press the pink “+” button shown in the "Add Layer to Map" window; this brings up the "Add an OGC Service to the List" dialog box. In that box, entered the following values:

You should get a figure that looks much like the one in Figure 2.

Figure 2. Adding the IDS WFS Service to Gaia, courtesy of The Carbon Project.

Press OK and Gaia retrieves the GetCapabilities transaction document and presents the list of layers to be selected as Figure 3 illustrates. Once you have highlighted one of the layers, be sure to select GML3 for the GML version. (GML2 can increase the amount of time needed to process the XML response.) Limit the number of features to 100 and specify the Use a Bounding-Box Filter. This limits the area in which features will be displayed based on the current map view.

Figure 3. Layer presentation screen from Gaia, courtesy of The Carbon Project.

In addition to geospatial mapping applications, the WFS DataBlade can also be used in location-based services applications. LBS are services that are based on a desired location. You can construct these applications using the GetFeature operation and the DWithin (Distance Within) predicate.

Consider a GPS-enabled mobile phone based application that can show you the restaurants within a given radius of your current location. These restaurants could be selected by type and ranked by user rating. Listing 14 shows a sample DWithin query along with the SQL that is generated by the WFSExplode() UDR that such an application might utilize.

Listing 14. Location-based services with DWithin
<?xml version=”1.0” ?>
<GetFeature
   service=”WFS”
   version=”1.1.0”
   maxFeatures=”5”
   ...
   <Query typeName=”natlrestaurants”>
     <ogc:PropertyName>mobilerater:name</ogc:PropertyName>
     <ogc:PropertyName>mobilerater:address</ogc:PropertyName>
     <ogc:PropertyName>mobilerater:rating</ogc:PropertyName>
     <ogc:Filter>
        <And>
           <PropertyIsEqualTo>
               <PropertyName>mobilerater:resttype</PropertyName>
               <Literal>Italian</Literal>
           </PropertyIsEqualTo>
           <DWithin>
              <PropertyName>mobilerater:locn</PropertyName>
              <gml:Point>
                  <gml:pos>-84.35 31.764</gml:pos>
              </gml:Point>
              <Distance units=’mi’>1</Distance>
           <DWithin>
      </And>
  </ogc:Filter>
  <ogc:SortBy>
      <ogc:SortProperty>
           <ogc:PropertyName>mobilerater:rating</ogc:PropertyName>
           <ogc:SortOrder>DESC</ogc:SortOrder>
       </ogc:SortProperty>
  </ogc:SortBy>
 </Query>
</GetFeature>

Equivalent SQL:
SELECT FIRST 5 name, address, rating FROM natlrestaurants
WHERE ST_Intersects(locn, ST_Buffer(ST_GeomFromGML(‘<gml:Point
xmlns:gml=”http://www.opengis.net/gml”><gml:pos>-84.35
31.764</gml:pos></gml:Point>’,4),1609.344))
AND resttype = ‘Italian’
ORDER BY rating DESC;

Conclusion

The WFS feature provides a solution that customers can use to gain platform independence and an interface for accessing and creating geographic data via a Web service. It provides the ability to query, retrieve, and apply INSERT, UPDATE, and DELETE transactions to geographic data through HTTP- and XML-based protocol and is used in conjunction with the Geodetic DataBlade and/or the Spatial DataBlade.

In this article you saw an overview of how customers can use WFS and the server-side UDRs. We have also discussed enabling the publication of location-based data using the WFS DataBlade in combination with the Geodetic and Spatial DataBlades. This opens a new capability for your business environment to utilize geospatial mapping tools to present colorful maps for analysis and presentation as well as the ability to provide location-based services over the internet without having to learn complex spatial SQL functions and predicates or designing complex protocols for exchanging data.


Acknowledgements

The author would like to thank Alan Caldera for sharing his expertise that was quite helpful during the formation of this article.

Resources

Learn

Get products and technologies

  • Build your next development project with IBM trial software, available for download directly from developerWorks.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Information management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Information Management
ArticleID=342883
ArticleTitle=Using Web Feature Service (WFS) with IBM Informix Dynamic Server
publish-date=10022008