"Seegrid will be due for a migration to confluence on the 1st of August. Any update on or after the 1st of August will NOT be migrated"

PID Service Cookbook

Contents

User Guide

Introduction

On this page we'll take a look at various common scenarios and the mapping rule design pattern that users will need to use to implement the desired behaviour.

Inheritance

GeoSciML CGI Classifier

Problem

The functional requirement for GeoSciML resources repository defined the common pattern for URI identifiers. The pattern is designed to recognise two generic types of identifiers defined by the first two components of the URI:

  • Case 1: /classifier/cgi/*
  • Case 2: /classifier/ics/*

with no specific behaviour defined for identifiers that belong to the parent /classifier/.

Case 1

In the general case all the requests coming in via http://resource.geosciml.org/classifier/cgi/* are to be dispatched to the following service:
  • http://auscope-services-test.arrc.csiro.au/elda-demo/api/cgi/resource?uri=$0

for example:

  • http://resource.geosciml.org/classifier/cgi/lithology/basalt
    • is dispatched to http://auscope-services-test.arrc.csiro.au/elda-demo/api/cgi/resource?uri= http://resource.geosciml.org/classifier/cgi/lithology/basalt
  • http://resource.geosciml.org/classifier/cgi/contacttype/contact
    • is dispatched to http://auscope-services-test.arrc.csiro.au/elda-demo/api/cgi/resource?uri= http://resource.geosciml.org/classifier/cgi/contacttype/contact

However, an exception from this rule is made for /classifier/cgi/stratchart/* URIs that are being dispatched to a different service:
  • http://resource.geosciml.org/classifier/cgi/stratchart/*
    • is dispatched to http://def.seegrid.csiro.au/sissvoc/isc2012/resource?uri= http://resource.geosciml.org/classifier/cgi/stratchart/*

Case 2

Another general case controls the way /classifier/ics/* type of URIs is dispatched by the service. The requirement defines that all requests that belong to /classifier/ics/ path are dispatched via http://def.seegrid.csiro.au/sissvoc/isc2012/resource?uri= {URI} service endpoint.

For example:

  • http://resource.geosciml.org/classifier/ics/ischart/Pliocene
    • is dispatched to http://def.seegrid.csiro.au/sissvoc/isc2012/resource?uri= http://resource.geosciml.org/classifier/ics/ischart/Pliocene

Solution

As we can see from the problem defined above, there're two main use cases: one for /classifier/cgi/* and another one for /classifier/ics/* types of URIs. In addition to the generic behaviour the former rule defines an exception for URIs that belong to the /classifier/cgi/stratchart/* group. In order to achieve the dispatch behaviour outlined above we create two mapping rules for both general use cases that inherit from the "Catch all" rule and create a separate mapping rule for /classifier/cgi/stratchart/* type of URIs to accommodate the special use case. The special mapping inherits from the /classifier/cgi/* mapping rule as all its instance URIs are also a subset of a more generic rule. It also ensures that a more specific mapping rule will be asserted before the generic one.

General case for /classifier/cgi/* is defined as follows:

where default action is set to:
  • http://auscope-services-test.arrc.csiro.au/elda-demo/api/cgi/resource?uri=${RAW:${ENV:FULL_REQUEST_URI}}

This mapping rules is very simple and doesn't take into account the file extension (the whole URI is treated as an extension-less URI).

A more specific mapping rule stipulates that /classifier/cgi/* must be followed by at least two sub-directories, e.g. http://resource.geosciml.org/classifier/cgi/lithology/basalt, and is configured as follows:

where parent is set to /classifier/cgi/* mapping rule and the default action is set to:
  • http://auscope-services-test.arrc.csiro.au/elda-demo/api/cgi/resource$2?uri=${RAW:${ENV:SERVER_ADDR}$1}

Please note that this mapping rule also makes use of file extension that might be appended to the URI. Extension is captured by the second capture group in the mapping regular expression and is accessed via $2 in the default action.

To accommodate for the exceptional use case of http://resource.geosciml.org/classifier/cgi/stratchart/* we define another mapping rule that inherits from ^(/classifier/cgi/.+?/[^0-9].+?)(\.[^.]*$|$) that we just created.

where default action is set to (similar to the previous one):
  • http://def.seegrid.csiro.au/sissvoc/isc2012/resource$2?uri=${RAW:${ENV:SERVER_ADDR}$1}

The second general use case /classifier/ics/* is configured as follows and inherits from "Catch all" mapping rule:

where default action is set to (similar to the previous ones):
  • http://def.seegrid.csiro.au/sissvoc/isc2012/resource$2?uri=${RAW:${ENV:SERVER_ADDR}$1}

PID Service Backup

To explore the use case on your own restore the backup file geosciml_classifier_uc.psb in your PID Service (version 1.1 and above) instance to walk through the examples above.

Condition Sets

The concept of condition sets is described in the User Guide. On this cookbook page we aim to give a real world worked example how one may benefit from used pre-bundled sets of conditions with an ultimate goal of simplifying mapping rule management in distributed systems.

SIRF Example

Complete example is available as a set of PID Service Backup file for your detailed analysis - SIRF_Example_ConditionSets.zip.

Inside that archive you will find two directories - "Original" containing backup files of original rules for us to use as a base line, and "Refactored with ConditionSets" that contains backup files of refactored rules. As you may notice there're two mapping rules one inheriting from another with many conditions that are duplicated in these rules, e.g. _view=^FTC-SKOS-search?, _view=^FTC-Mappings?, etc. These conditions are forming separate APIs that define a particular behavior of different rules mapped to different URI patterns. Although, these URIs that conform to certain APIs may use different services for resource resolution they must follow the same query principles - use of querystring parameters, MIME types, etc. Condition sets provide the ability to encapsulate these sets of conditions into separately managed entities - ConditionSets. These entities, condition sets, live independently and aren't associated with any URI patterns. Mapping rules must make an explicit reference to these condition sets by the use of ConditionSet condition type.

The following image shows the two rules of these example and relationship between them:

Now, we have identified the need to separate API-specific conditions from rule-specific conditions within each rule to simplify the rule management. We have identified three APIs:

  • SIRF API - for the sake of simplicity in this example, this API only states that each SIRF-enabled URI supports _view=qrcode querystring parameters that returns a QR code of that URI.
  • LID API - defines LID-specific querystring parameters that must be supported by an URI, e.g. _view=alternates, _view=lid and _view=idresolver.
  • FTC API - encapsulates all Feature Type Catalog (FTC) specific conditions (where _view querystring parameter starts with FTC-).

When encapsulating conditions into condition sets one must remember that condition sets live independently of a URI pattern it might be used in. Thus, it should make no reference to regular expression capture groups in the URI pattern (e.g. ${URI:index}, $1, etc.). Action items within each condition must be constructed only using condition type specific placeholders (e.g. ${C:param}, ${QS:param}, etc.), lookup maps (e.g. ${LOOKUP:namespace:param}), environment variables (e.g. ${ENV:REQUEST_URI}), and other supported functions.

Once this separation is done the following condition sets are constructed:

  • conditionSet_SIRF.xml:
<conditionSet xmlns="urn:csiro:xmlns:pidsvc:backup:1.0">
   <name>SIRF API</name>
   <conditions>
      <condition>
         <type>QueryString</type>
         <match>_view=^qrcode$</match>
         <actions>
            <action>
               <type>303</type>
               <name>location</name>
               <value>${RAW:${ENV:FULL_REQUEST_URI}}?_pidsvcqr=90</value>
            </action>
         </actions>
      </condition>
   </conditions>
</conditionSet>

From the condition above you may notice that it makes no reference to the base URI as this condition sets may be distributed and deployed in any environment and be applied to any URI pattern. Instead it uses FULL_REQUEST_URI environment variable to retrieve the original URI.

  • conditionSet_LID.xml:
<conditionSet xmlns="urn:csiro:xmlns:pidsvc:backup:1.0">
   <name>LID API</name>
   <conditions>
      <condition>
         <type>QueryString</type>
         <match>_view=^alternates$&amp;_format?</match>
         <actions>
            <action>
               <type>303</type>
               <name>location</name>
               <value>${LOOKUP:http\://id.sirf.net/ns/service_location:ftc}/resourcelist?baseuri=${ENV:URI_REGISTER}&amp;item=${RAW:${ENV:RESOURCE_NAME_EXT}}&amp;_format=${C:_format}&amp;_lang=en</value>
            </action>
         </actions>
      </condition>
      <condition>
         <type>QueryString</type>
         <match>_view=^(lid|idresolver)$&amp;_format?</match>
         <actions>
            <action>
               <type>303</type>
               <name>location</name>
               <value>${LOOKUP:http\://id.sirf.net/ns/service_location:ftc}/feature?uri=${RAW:${ENV:FULL_REQUEST_URI}}&amp;_format=${C:_format}</value>
            </action>
         </actions>
      </condition>
   </conditions>
</conditionSet>

From the condition set above you may notice that redirect action value has also been refactored to make no reference to the service endpoint (i.e. http://sirf-data.csiro.au/sissvoc/ftc), instead it uses a lookup map that serves as an external config. References to $3 (capture group from URI pattern recognition regular expression) have also been replaced with environment variable placeholder ${RAW:${ENV:RESOURCE_NAME_EXT}}.

  • conditionSet_FTC.xml:
<conditionSet xmlns="urn:csiro:xmlns:pidsvc:backup:1.0">
   <name>FTC API</name>
   <conditions>
      <condition>
         <type>QueryString</type>
         <match>_view=^FTC-ElementChildren$&amp;_format?</match>
         <actions>
            <action>
               <type>303</type>
               <name>location</name>
               <value>${LOOKUP:http\://id.sirf.net/ns/service_location:ftc}/children?uri=${RAW:${ENV:FULL_REQUEST_URI}}&amp;_format=${C:_format}</value>
            </action>
         </actions>
      </condition>
      <condition>
         <type>QueryString</type>
         <match>_view=^FTC-SKOS-search?</match>
         <actions>
            <action>
               <type>303</type>
               <name>location</name>
               <value>${LOOKUP:http\://id.sirf.net/ns/service_location:sissvoc_search}?endpoint=${LOOKUP:http\://id.sirf.net/ns/service_location:ftc}&amp;q=${RAW:${ENV:RESOURCE_NAME_EXT}}</value>
            </action>
         </actions>
      </condition>
      <condition>
         <type>QueryString</type>
         <match>_view=^FTC-Mappings?</match>
         <actions>
            <action>
               <type>303</type>
               <name>location</name>
               <value>${LOOKUP:http\://id.sirf.net/ns/service_location:sissvoc_search}?endpoint=${LOOKUP:http\://id.sirf.net/ns/service_location:ftc}&amp;q=${RAW:${ENV:RESOURCE_NAME_EXT}}</value>
            </action>
         </actions>
      </condition>
      <!-- other conditions were omitted for brevity -->
   </conditions>
</conditionSet>

In conditionSet_FTC.xml same changes have been done as in conditionSet_LID.xml to make the conditions work independent of the URI pattern they're applied to.

The lookup map is shown below:
<?xml version="1.0" encoding="UTF-8"?>
<lookup xmlns="urn:csiro:xmlns:pidsvc:backup:1.0">
   <ns>http://id.sirf.net/ns/service_location</ns>
   <default type="Constant"/>
   <Static>
      <pair>
         <key>ftc</key>
         <value>http://sirf-data.csiro.au/sissvoc/ftc</value>
      </pair>
      <pair>
         <key>sissvoc_search</key>
         <value>http://sissvoc.ereefs.info/search</value>
      </pair>
   </Static>
</lookup>

Once all condition sets and lookup maps are formed the mapping rules may be changed accordingly to make use of these condition sets. The following is an extract from a re-factored backup file:
<mapping>
   <path>^/def/schema/([^/]*)/([^/]*)/([^/]+)$</path>
   <type>Regex</type>
   <description>General API for all schemas, providing default view for application schema, classes and properties</description>
   <action>
      <type>303</type>
      <name>location</name>
      <value>${LOOKUP:http\://id.sirf.net/ns/service_location:ftc}/resource?uri=${RAW:${ENV:FULL_REQUEST_URI}}&amp;_format=${C:_format}</value>
   </action>
   <conditions>
      <condition>
         <type>ConditionSet</type>
         <match>SIRF API</match>
      </condition>
      <condition>
         <type>ConditionSet</type>
         <match>LID API</match>
      </condition>
      <condition>
         <type>ConditionSet</type>
         <match>FTC API</match>
      </condition>

      <!-- Other conditions may follow as usually -->
      <condition>
         <type>QueryString</type>
         <match>_view=^OWL$&amp;_format?</match>
         <actions>
            <action>
               <type>303</type>
               <name>location</name>
               <value>https://svnserv.csiro.au/svn/SIRF/public/def/schema/$1/$2.rdf#$3</value>
            </action>
         </actions>
      </condition>
      <condition>
         <type>ContentType</type>
         <match>text/html</match>
         <actions>
            <action>
               <type>303</type>
               <name>location</name>
               <value>${LOOKUP:http\://id.sirf.net/ns/service_location:ftc}/resource?uri=${RAW:${ENV:FULL_REQUEST_URI}}</value>
            </action>
         </actions>
      </condition>
   </conditions>
</mapping>

In the web management console it is implemented as a separate condition type ConditionSet:

-- PavelGolodoniuc - 22 Jul 2013
Topic attachments
I Attachment Action Size Date Who Comment
SIRF_Example_ConditionSets.zipzip SIRF_Example_ConditionSets.zip manage 27.9 K 01 Jul 2014 - 17:16 PavelGolodoniuc SIRF Example - use of condition sets
classifier_cgi.pngpng classifier_cgi.png manage 36.9 K 23 Jul 2013 - 14:58 PavelGolodoniuc  
classifier_cgi_a_b.pngpng classifier_cgi_a_b.png manage 42.2 K 23 Jul 2013 - 15:13 PavelGolodoniuc  
classifier_cgi_stratchart.pngpng classifier_cgi_stratchart.png manage 39.1 K 23 Jul 2013 - 15:19 PavelGolodoniuc  
classifier_ics_ischart.pngpng classifier_ics_ischart.png manage 35.7 K 23 Jul 2013 - 15:30 PavelGolodoniuc  
conditionsets_rules.pngpng conditionsets_rules.png manage 4.9 K 01 Jul 2014 - 15:52 PavelGolodoniuc  
conditionsets_ui.pngpng conditionsets_ui.png manage 19.7 K 01 Jul 2014 - 16:40 PavelGolodoniuc SIRF Example - condition sets (UI)
geosciml_classifier_uc.psbpsb geosciml_classifier_uc.psb manage 0.7 K 23 Jul 2013 - 15:47 PavelGolodoniuc GeoSciML classifier use case
Topic revision: r5 - 01 Jul 2014, PavelGolodoniuc
 

Current license: All material on this collaboration platform is licensed under a Creative Commons Attribution 3.0 Australia Licence (CC BY 3.0).