WFSRI 3.5 User Guide

Note: This is the WFSRI 3.5 User Guide. If you are running Version 3.0 or earlier, please see the WFSRI 3.0 User Guide.

The Web Feature Service Reference Implementation (WFSRI) is a test platform for publishing GML-formatted data to and retrieving it from the 4-Dimensional Weather Data Cube. Specifically, it allows providers to insert weather-related data sets into a database on a Web Feature Server, and it allows users to query and request the data sets.

This User Guide details how to:

• Configure Feature Types to be registered as Feature Tables in the database
• Customize the Get Capabilities response
• Enable request delegation to another upstream WFSRI when data is not found locally
• Configure data service profiles, or limits, on client requests
• Make use of various performance and monitoring metrics included with WFSRI 3.5
• Enable XML schema validation
• Use the provided wxConsumerLibray to both insert features into the Web Feature Service and request features from the Web Feature Service
• Create new Features of a given Feature Type by inserting them into their appropriate Feature Table
• Look up (query) Feature Types from a Web Feature Server via SOAP, KVP or POX
• Look up (query) Features in a given Feature Table
• Subscribe to automatic updates of Features from a Web Feature Server
• Use the WFSRI Repeater to replicate data from a WFSRI Origin Server to a WFSRI Distribution Server

Preparation

Defining Feature Tables / Types

Before you can have feature types added to your WFSRI database, you must create a set of files for each feature type. Many of these files for known feature types have already been created for you and supplied with the Registration Client but they may need to be modified for your service so you must check and alter each file as required. If you are creating a feature type which does not yet exist in the supplied set, you can use the existing files as a guide when creating the new files.

The feature type configuration file is a properties file which tells the registration client the location of the other required files, as well as providing other information required to configure and self-test the feature type. For each feature type to be added to the database, there must be a a feature type configuration file in $CONFIG_DIR/feature-types, such as contours.properties, and it should have the following information:

• producerName- The name of the Producer user account.
• producerPass- The password of the Producer user account.
• mapFile- The location of your feature's mapping file, or, Feature Table Definition XML file.
• featureTypeDetails- The location of your feature's Feature Type Registration Properties file.
• insertionXML- The location of your chosen Feature Type's Transaction-Insert XML file (used to perform self-test diagnostics).
• retrievalXML- The location of your chosen Feature Type's GetFeature XML file (used to perform self-test diagnostics).

The next four properties, if present in the file, are not used by the registration client and should be left blank:

• subscriptionXML- Not used by the registration client.
• renewalXML- Not used by the registration client.
• pauseXML- Not used by the registration client.
• resumeXML- Not used by the registration client.

The remaining set of files required for each feature type should be located in the appropriate subdirectories under $WFSRI_INSTALL/data. If the files do not exist for your required feature type, you must add them. If they exist but need to be modified for your particular feature type, you should modify the files supplied with the WFSRI installation.

The schema definition file for each feature type should be created and placed in $WFSRI_INSTALL/data/xsd, for example, $WFSRI_INSTALL/data/xsd/wxContour.xsd.

Each feature type requires a mapping file (i.e., a Feature Table Definition XML File) located in a subdirectory under $WFSRI_INSTALL/data/xml/mapping, for example, $WFSRI_INSTALL/data/xml/mapping/Contours/contours.xml. This file location is referenced in the feature type configuration file in $CONFIG_DIR/feature-types as the mapFile property (e.g. - mapFile=xml/mapping/Contours/contours.xml) and contains XML necessary to map the feature type fields in the XML schema to the feature table fields/columns in the WFS database.

If you would like details on preparing the Feature Table Definition XML, see the Specifying the Feature Table Definition XML entry on the WFSRI 3.5 User Guide Examples page.

Each feature type requires a registration file (i.e., a Feature Type Registration Properties File) located in a subdirectory under $WFSRI_INSTALL/data/xml/registration, for example, $WFSRI_INSTALL/data/xml/registration/Contours/contoursRegister.properties. This file location is referenced in the feature type configuration file in $CONFIG_DIR/feature-types as the featureTypeDetails property (e.g. - featureTypeDetails=xml/registration/Contours/contoursRegister.properties) and contains the following key value pairs denoting each element:

• featuretypeName- the name of the Feature Type. For example, Contour.
• featuretypeURL- the namespace URI for the Feature Type. For example, http://www.eurocontrol.int/wx/1.1.
• featuretypeDescFile- the name and location of the XML used with a GetCapabilities response. The file location is given relative to $WFSRI_INSTALL/data, for example, xml/capability/Contours/Contours.xml.
• describeFeatureTypeFile- the Feature Type XSD used with a DescribeFeatureType response. The file location is given relative to $WFSRI_INSTALL/data, for example, xsd/wxContour.xsd.
• srsNS- the spatial reference system used by the Feature Type. For example, urn:ogc:def:crs:ESPG::4326.
• schemaName- the username of the Producer as a String. For example, GABRIEL.
• tableName- the name of the Feature Table. For example, CONTOURS.
• pKeyCol- the primary key of the Feature Table. For example, ID.
• pSpatialCol- the primary spatial column of the Feature Table. For example, GEOMETRY.
• gmlVersion- the version of GML used to define this Feature Type. For example, GML32.
• featureMemberNS- reserved for future use (ignored).
• featureMemberName- reserved for future use (ignored).
• mandatoryColumns- the feature table columns deemed mandatory. For example, ./contourValue, ./geometry.

In order to perform self-test diagnostics for a given feature type, each feature type requires an insertion XML file (to perform transaction-inserts) and a retrieval XML file (to perform GetFeature requests). The insertion XML file should be located in a subdirectory under $WFSRI_INSTALL/data/xml/transaction-insert, for example, $WFSRI_INSTALL/data/transaction-insert/ContoursData/contours-1.xml. This file location is referenced in the feature type configuration file in $CONFIG_DIR/feature-types as the insertionXML property (e.g. - insertionXML=xml/transaction-insert/ContoursData/contours-1.xml) and contains XML necessary to perform a Transaction Insert request. The retrieval XML file should be located in a subdirectory under $WFSRI_INSTALL/data/xml/get-feature, for example, $WFSRI_INSTALL/data/get-feature/ContoursQueries/contours-1.xml. This file location is referenced in the feature type configuration file in $CONFIG_DIR/feature-types as the retrievalXML property (e.g. - retrievalXML=xml/get-feature/ContoursQueries/contours-1.xml) and contains XML necessary to perform a Get Feature request.

Configuring the WFS Maintenance Scripts

With the Feature Tables and their Types registered, you should schedule executions of the WFS Maintenance Scripts. These scripts manage the WFS database; initializing them will specify how long to store data before deleting it and how often to optimize the database partitions.

The scripts are run by executing an SQL scheduling script from the prompt. First, however, you must create this scheduling script and fill its values in to conform to the Feature Types you have registered, set how long they are stored in the database, and schedule how often the checks are run.

1. Using your text editor of choice, create a new file named sched_maintenance.sql. This file may be located anywhere you wish, so long as you can remember its location and reference it from within the prompt. Copy and paste the following code into this new script file:
    
   
2. The above code contains two schedule jobs: a General Maintenance job that will flush the cache, and an example project maintenance job that may be edited and duplicated for every product registered as a Feature Type in your WFS installation. You must first edit the General Maintenance job's repeat_interval to match how often you would like the cache flushed.
    
3. Next, edit the Product Maintenance job, replacing the placeholders with appropriate values as detailed in the table below:
    

   <PRODUCT>	The name of the Feature Type associated with this maintenance job. This is an arbitrary identifier, used to reference the job when enabling, disabling, running, or stopping it. For example, Contours.
   <FTNAME>	The name of the Feature Table created for this Feature Type. For example, CONTOURS.
   <PROD>	The name of the Producer associated with this Feature Table. For example, CIWS.
   <SPATIAL>	The name of the given Feature Table's spatial column. For example, GEOMETRY.
   <RETENTION>	The amount of time data for this Feature Type should be retained before being deleted, in days, hours, minutes, and seconds. For example, 15 00:00:00.0 would store data for 15 days, 0 hours, 0 minutes, and 0 seconds.

   
   
4. Duplicate the product job and repeat for every Feature Type you have registered with the WFS. Save and close the sched_maintenance.sql file once you have finished.

The WFS Maintenance Scripts are run from the command line. You must be able to log into your WFS database as an administrator to execute them.

1. From your Linux terminal, log into your WFS database as the sandbox user.
    

   Error rendering macro 'table'

   Illegal group reference

   
   
2. At the SQL> prompt, execute your sched_maintenance.sql file by typing an @ symbol, followed by the path to the file.
    

   SQL>  @/path/to/sched_maintenance.sql

Customizing the Get Capabilities response

The metadata returned in the Get Capabilities response can now be customized by the service provider. In the $CONFIG_DIR, use the serviceProvider.xml and operationsMetadata.xml files as inputs for customizing the ServiceProvider and OperationsMetadata sections, respectively, of the WFS_Capabilities document. Ensure the XML fragments validate as minimal validation is done on the part of the WFSRI.

Enabling request delegation to another upstream WFSRI when data is not found locally

The WFSRI now provides the ability to search for data in a parent, or upstream, WFS when the requested data is not found locally on the queried server. This functionality can be performed without the use of a registry/repository - when requested feature data is not found locally, a check is made to see if an upstream WFS has been configured and the request is then sent to that WFS. To enable this functionality, the $CONFIG_DIR/reroute.properties file must be configured with the information required to locate the upstream WFS. See the documentation within the $CONFIG_DIR/reroute.properties file to learn which properties to configure for this capability. If this property file exists, and is configured correctly, the WFS will automatically send the requests to the upstream WFS if the data is not stored locally. By default, the reroute.enabled flag is set to false to disable rerouting.

Configuring data service profiles, or limits, on client requests

The WFSRI now provides the ability to use service profiles to set rules which limit actions on client requests. For example, it will allow a service to limit the quantity of data all clients can request in one Get Feature request which can be used to prevent users from monopolizing a given WFS installation. To enable such a limit, the service provider would configure a service profile XML file to limit all requests for a given producers data to a maximum of one hour of data per Get Feature request. The configuration file $CONFIG_DIR/profiles.xml is now provided which can be used to set up the service profile for a given WFS. This file can contain multiple profile rules and can be configured on a producer-by-producer basis. The provided $CONFIG_DIR/profiles.xml file gives an example of how to limit the client to constrain the range of time requests to one hour of data per request, for a given producer.

Profiles can be created for any field returned in a GetFeature or Subscribe request which is of type string, boolean, integer, double, or date/time and which can be queried as a property which is equal, not equal, greater than (or equal) or less than (or equal) to a given value.

To enable the use of configured profiles in the profiles.xml file, create your own profiles in the $CONFIG_DIR/profiles.xml file. By default, the profiles.xml file is provided with one sample profile which has been commented out.

Making use of various performance and monitoring metrics

WFS service providers can now use JConsole to observe various monitoring metrics which are provided in the WFSRI. The $CONFIG_DIR/monitoring.properties file provides properties which can be used to enable or disable the reporting of monitoring metrics and the interval at which monitoring reports are generated (daily, weekly, monthly, quarterly, yearly).

Metrics gathered and reported include:

• Average request time for each request type
• Request Data Per Second
• Max Request Size
• Min Request Size
• Response Data Per Second
• Max Response Size
• Min Response Size
• Number of requests for each operation
• Average Request Size
• Average Response Size
• Number of requests
• Number of responses
• Total request size received
• Total response size sent

Enabling XML schema validation

The WFSRI now performs XML schema validation on incoming requests if the corresponding flag is set to true in the wfsri.properties file. Validation is enabled by default. To enable or disable validation, set the validation.enabled property in the $CONFIG_DIR/wfsri.properties to true or false respectively.

Executing WFS Operations

The NNEW team has released a generic SOAP client capable of executing all supported WFS operations. As outlined in the WFSRI 3.5 Installation Guide, the directory you download the SOAP client to should be referenced by the environment variable $SOAPCLIENT.

To execute operations with the SOAP client, type the following command into the Linux terminal from the $SOAPCLIENT directory, replacing the placeholders as directed in the table below:

See the sections below for more information on the appropriate XML files to pass for each of the supported operations.

Inserting Features

Once you have created a new Feature Table and registered its Feature Type, you can use the Transaction-Insert operation to insert Features of that type. See the Example Transaction-Insert Request XML File on the WFSRI 3.5 User Guide Examples page if you would like to view examples.

Querying the Capabilities of the Web Feature Server

The GetCapabilities operation can be used to determine what Feature Types are currently registered with a Web Feature Server, allowing you to then insert Features of those Feature Types into their respective Feature Tables. It can also be used to query other information from a Web Feature Server – information about its service provider, supported operations, and filtering capabilities for GetFeature queries – but retrieving a list of Feature Types is most common.

Performing a GetCapabilities Request with the SOAP Client

Performing a GetCapabilities Request via URLs (KVP encoding)

Using POX Rather Than SOAP to Perform Requests

The WFSRI now suports the use of POX, or Plain Old XML, to make requests rather than making requests via SOAP-wrapped messages. Although the WFSRI will now support POX, it is up to the user of the service to create a POX client, or interface, to make these calls. The Get Capabilities, Describe Feature Types, Get Features, Subscribe, Unsubscribe, Pause, Resume and Renew requests are all supported with a POX interface, and would look identical to the SOAP requests, minus the SOAP envelope which encapsulates the XML.

A POX interface is useful when no security requirements are mandated for the WFS and the user, or client, wishes to make straight XML calls to the service.

This example XML file is a GetCapabilities request for a Web Feature Server's service identification and provider, metadata, and list of Feature Types. As you can see, it is identical to the SOAP request. The SOAP client places a SOAP header (or envelope) around the POX request for users before sending the request on to the WFSRI:
 

Querying Individual Feature Types

Once you have used the GetCapabilities operation to determine what Feature Types are currently being stored in a Web Feature Server, you can then turn to the DescribeFeatureType operation to get their individual details. Note, however, that at the moment the DescribeFeatureType operation only supports requests for one Feature Type's information at a time.

Performing a DescribeFeatureType Request

The following is an example DescribeFeatureType Request XML file:

When passing a DescribeFeatureType XML file to a Web Feature Server, ensure the namespace prefix (in the case of the above example, "tfdm") is included in the TypeName element's value.

If the XML is properly formatted, the Web Feature Server will respond with the appropriate Feature Type's schema.

Requesting Feature Data

Once you have a Web Service containing inserted feature data, you can use the GetFeature operation to request the feature data. See the Example GetFeature Request XML File on the WFSRI 3.5 User Guide Examples page if you would like to view examples.

Subscribing to Feature Data Updates

In addition to using the GetFeature Request to perform one-time requests of feature data, the WFSRI supports client subscriptions. Using the generic SOAP client, consumers can pass special GetFeature subscription requests to the WFSRI, subscribing themselves to updates of Feature data as changes are published to the Web Feature Server.

Subscription Request

Subscription Response

Pausing and Resuming Subscriptions

Renewing Expiring Subscriptions

Unsubscribing

Running the WFSRI Repeater Application

Version 3.5 of the WFSRI comes with the WFSRI Repeater: a component that retrieves data from an origin Web Feature Server and replicates it to a distribution server. The Repeater provides clients with the ability to retrieve the same data from the distribution server as exists on the origin server, in cases where they may not have access to the latter system.

Each instance of the WFSRI Repeater can only subscribe to updates of a single Feature Type from an Origin Server. Thus, you must run concurrent instances of the Repeater if you want to subscribe to updates of multiple Feature Types and pass them on to a Distribution Server.

To run an instance of the Repeater, you must make a copy of the $WFSRI_REPEATER/wfs-repeater.properties file tailored to the Feature Type you wish to repeat, and have on hand that Feature Type's Subscription Request XML file, before running the Repeater's .jar executable.

1. Create a custom copy of the $WFSRI_REPEATER/wfs-repeater.properties file, tailoring its key value pairs to fit the data type you plan to subscribe to:
    
   Origin-Related Properties
   • originEndpoint – This is the endpoint of the origin WFSRI instance. It must match the wfs.url element in the $CONFIG_DIR/wfsri.properties file on the origin Web Feature Server. For example, http://origin-server:8084/wfsri-3.5/wfs.
      
   • originUsername – This is the username of a user in the origin WFSRI instance. It must match an entry in the userMap element of the $WFSRI_HOME/WEB-INF/CamelContext.xml file on the origin Web Feature Server. For example, ORIGINWFSUSER.
      
   • originPassword – This is the password of a user in the origin WFSRI instance. Like the originUsername, it must match an entry in the userMap element of the $WFSRI_HOME/WEB-INF/CamelContext.xml file on the origin Web Feature Server. For example, TEST.
      
     Distribution-Related Properties
   • distributionEndpoint – This is the endpoint of the distribution WFSRI instance. It must match the wfs.url element in the $CONFIG_DIR/wfsri.properties file on the distribution Web Feature Server. For example, http://distribution-server:8084/wfsri-3.5/wfs.
      
   • distributionUsername – This is the username of a producer in the distribution WFSRI instance. It must match an entry in the userMap element of the $WFSRI_HOME/WEB-INF/CamelContext.xml file on the distribution Web Feature Server. For example, DISTRIBWFSUSER.
      
   • distributionPassword – This is the password of a producer in the distribution WFSRI instance. Like the distributionUsername, it must match an entry in the userMap element of the $WFSRI_HOME/WEB-INF/CamelContext.xml file on the distribution Web Feature Server. For example, TEST.
      
     Other Properties
   • subscribeFilename - This is the filename of the Subscribe request XML file, relative to the $WFS_REPEATER/conf directory, used to create a subscription on the origin WFSRI instance. Using the $WFS_REPEATER/lightningFlashSub.xml file as an example, modify the value of the typeNames attribute in the GetFeature/Query element to your chosen Feature Type, using the form <namespace prefix>:<local name>. Ensure the namespace prefix is bound by an xmlns attribute in the Subscribe element. For example, WFSRI 3.5 User Guide Examples#Example Subscribe Request File.
      
2. Run the following command in your Linux terminal from the $WFSRI_REPEATER directory to execute the wfsri-repeater-3.5.jar file, replacing the <file> placeholder with the name of your customized copy of the wfs-repeater.properties file, also relative to the $WFS_REPEATER/conf directory:
    

   Error rendering macro 'table'

   Illegal group reference

    
   Thus, if your custom copy of the wfs-repeater.properties file was called custom.properties, and was located in the $WFS_REPEATER/conf directory, the command would be:
    

   Error rendering macro 'table'

   Illegal group reference