"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"

Creating BOM GeoServer Mapping Files for Observational Data

Introduction

This page describes how BOM Time Series GeoServer application schema mapping files were created and tested in windows development environment.It serves as a reference guide only and for official guide, please refer to http://docs.geoserver.org/latest/en/user/data/app-schema/index.html.

Required Tools and Softwares for Development

Here are the basic list of required tools and softwares :
  1. A good XML editor (e.g. Altova XMLSpy)
  2. Apache Tomcat - version 6 & above
  3. GeoServer war file - refer to for the recommended version @ https://www.seegrid.csiro.au/wiki/ASRDC/DeployBoMObservationalDataAsSF1#GeoServer Installation
  4. PostGIS Database - with SLAKE db
  5. An instance document or a database mapping file created by an information modeller.
  6. The application schema - either the official URI or the actual schema files

Step 1: Create Database Views base on the Instance Document

  1. An instance document or the database mapping file will give you details of which table and columns will be required in the mapping file. The time series instance document for BOM observational data mapping is here : https://www.seegrid.csiro.au/subversion/ASRDC/BOM/SLAKE/databaseMapping/InstanceDocument_Observation_baseOnts_TimeSeriesCoverage_wml2_V2.xml
  2. This is an important step and may be time consuming step if you do not understand the database model.
  3. At the moment, only one datasource (table/view) is allowed per mapping file. Feature joining may be used to join different mapping from different datasource. No feature chaining is used for Time Series mapping as it causes performance issue.
  4. For good performance, use materialized view rather than view as a complex view with huge dataset can really slow down GeoServer performance.

Step 2: Download and Install GeoServer

  1. First download the recommended version of GeoServer base on : https://www.seegrid.csiro.au/wiki/ASRDC/DeployBoMObservationalDataAsSF1#GeoServer Installation
  2. Deploy the war file to Tomcat and test the GeoServer installation with it's default data dir.
  3. Move on to next step if the installation is success.

Step 3: Setup Data Directory

  1. http://docs.geoserver.org/latest/en/user/data/app-schema/configuration.html - mentioned that you need to manual construct the GeoServer data directory. That's for the case where you do not have any example to be base on. Since we already have some complex feature available for BOM, we can reuse them. Simply download any example from https://www.seegrid.csiro.au/subversion/ASRDC/BOM/SLAKE/GeoServerConfig/ or https://www.seegrid.csiro.au/subversion/ASRDC/BOM/AHGF/GeoServerConfig/. Extract the zip file to a data directory (e.g. c:\data\bom).
  2. Get yourself familiar with the data directory structures and files (http://docs.geoserver.org/latest/en/user/data/app-schema/configuration.html)
  3. Point GeoServer to this new data direcotry, edit the web.xml file in %TOMCAT_HOME%/webapps/geoserver/WEB-INF dir : e.g.
       <context-param>
           <param-name>GEOSERVER_DATA_DIR</param-name>
           <param-value>C:\data\bom</param-value>
        </context-param>  
  4. Remove app-schema-cache directory (read more about schema caching : http://docs.geoserver.org/latest/en/user/data/app-schema/app-schema-resolution.html#cache)
  5. Move on to next step if you are familiar with the data directory now.

Step 4: Create Mapping File

  1. More information about mapping file : http://docs.geoserver.org/latest/en/user/data/app-schema/mapping-file.html
  2. Find out all the namespaces required in the mapping file - you can find this out base on the instance document. For times series mapping, we required the following namespaces (prefix:uri):
  3. Remove unwanted namespace sub directory in the workspaces directory (keep one with mapping file to be used later). Create new sub directory base on the list of namespaces above and create a workspace.xml and namespace.xml for each namespace sub directory. This is a requirement for GML 3.2.1 (as WaterML2.0 is base on GML3.2) where all secondary namespaces need to be defined explicitly : http://docs.geoserver.org/latest/en/user/data/app-schema/supported-gml-versions.html#gml-3-2-1.
  4. Create om:OM_Observation mapping file in om namespace sub directory :
    1. replicate from the namespace sub directory which you keep earlier and rename the files accordingly
    2. edit datastore.xml : change the id, name, workspace and the connectionParameters
    3. edit featuretype.xml : change id, name, nativename, namespace/id, title, abstract and store/id
    4. edit OM_Observation.xml - the actual time series application schema mapping file :
      1. change the namespaces - base on the namespaces identifed above
      2. change datastore to the correct jndi connection name (note : you can create constant parameter in %GEOSERVER_HOME%/WEB-INF/classes/app-schema.properties file and call the parameter using this syntax : $(parameter_name) in the mapping file.
      3. change the schemaUri to the correct URI
      4. change the sourceType to the table/view/materialized view
      5. change the targetElement to the feature type name you want
      6. working thru the rest of the mapping file base on the instance doc and map to correct column of the table/view/materialized view.
    5. It's good practice to run the GeoServer request to test the mapping file after you completed one or two mapping. As it can be difficult to identify which mapping give you problem if you test it at the end after completing the whole mapping file.

What to do if you encounter problem ?

  1. Finally, GeoServer may not provide you with a good error message when a mapping is incorrect or there's a null value in the table column or some typo error somewhere, etc :
    1. See if the error message is one of those : https://cgsrv1.arrc.csiro.au/blog/category/geoserver/
    2. Send an email to : siss@lists.csiro.au
Topic revision: r1 - 02 May 2012, FlorenceTan