wiki:GeoManual

Version 10 (modified by ashaon, 12 years ago) (diff)

--

GeoServer? "Complex DataStore/Community? Schema": User Manual

The objective of this document is to provide guidelines for creating and defining a FeatureType? that is to be exposed by the “Community Schema” version of Geoserver. In summary, this special version of Geoserver facilitates serving up data from a relational database, in an externally defined schema, which exists independently of the underlying data structure of the database. In order to achieve this feat, Geoserver requires the followings:

  1. An output (community) schema. This schema may exist independently of the actual data so it will be loaded from a schema file, defined in XML Schema language.
  2. An input FeatureType?. Geoserver FeatureTypes? are exposed by Geoserver DataStores?, so a suitable way is needed to specify the DataStore?'s connection parameters and the source FeatureType? name.
  3. The attribute and attribute id mapping definitions. They consist of a series of couples of XPath OGC Filter 1.0 Expressions. The former addresses the output schema properties and the later defines how the value of that properties are derived from the source Feature instances.

All this information is held by a FeatureTypeMapping? object, and a ComplexDataStore?, in turn, may hold an arbitrary number of that objects, each defining a FeatureType? that the DataStore? exposes.

Geoserver uses an XML file which contains these definitions, and whose location in the form of an URL must be used to create a DataStore? instance through the GeoTools? DataStoreFinder? lookup system. This document presents detailed instructions for creating these definitions, specifying database connection parameters along with other necessary configuration related aspects of exposing a FeatureType? through Geoserver.

1. Creating a New Feature Type

Followings are the steps for creating a new FeatureType? in the "Community Schema" version of Geoserver:

  1. Create a new folder in Geoserver Data Directory -> featureType folder (Figure 1). This folder will contain all file necessary to define a new Feature Type. The name of the folder may be anything but ideally it should be the same as the name of the Feature Type that it is intended for.
  2. Create an XML document called “info.xml” (case-sensitive) in the newly created folder. This file contains a formal definition of a Feature Type. Information provided in this file is also used by the GetCapabilities? request to Geoserver, to provide a brief overview of a FeatureType?. The structure of “info.xml” is described in section 4.
  3. Create an XML document containing the mappings between source features and target features of the FeatureType? being defined. The name of this XML file could be anything. The structure of this mapping file is described in section 5.
  4. The schema file along with other schemas that it depends on (unless they are referenced via URLs in the schema) that the XML output of a FeatureType? conforms to may also be placed in this folder. However, it is recommended to keep the schemas used for all FeatureTypes? exposed by Geoserver under the commonSchemas folder (Figure 1) in Georserver’s Data Directory.

[img  http://proj.badc.rl.ac.uk/ndg/attachment/wiki/GeoManual/geo_dir.JPG]
Figure 1: Structure of a Geoserver’s Data Directory

2. Defining the DataStore? for a FeatureType?

In order to serve up a FeatureType? through Geoserver, it is necessary to properly define the associated DataStore? in the Geoserver catalog. The Geoserver catalog is defined and configured in an XML document called “catalog.xml” in Geoserver’s data directory. This XML document essentially contains three categories of information: datastores to load, namespaces to be used by the datastores and styles to be used for the Web Map Service (see section 4). Figure 2 below provides an example of the catalog.xml document with explanations for each of its significant aspects: [img  http://proj.badc.rl.ac.uk/ndg/attachment/wiki/GeoManual/catalog.JPG]
Figure 2: Catalog.xml file

3. Configuring Geoserver for the "describeFeatureType" request

The "describeFeatureType" request for a particular FeatureType? against Geoserver is essentially a request for a schema file which could be used to validate a feature in the WFS getFeature response for that FeatureType?. In theory, Geoserver should be able to dynamically generate this schema file based on the mappings specified in the mapping file (Section 5) for a FeatureType?. Unfortunately, at present, Geoserver does not handle this request very well. To get around this problem, the module of Geoserver that is responsible for dealing with "describeFeatureType" request has been modified so that it uses the relevant schema file from the Geoserver’s data directory instead of trying to generate it dynamically. This requires further configuration of the Geoserver’s data directory as follows:

In geoserver's data directory (Figure 1), create two folders called "schemas" and "xsl_conf". In the folder called "xsl_conf", create a file called "xsl_conf_describe.config", which should contain key-value pairs where keys will be the names of different FeatureTypes? exposed by Geoserver and values will be relative paths to their corresponding schema files. An example of this is PointSeriesFeature?=schemas/csml.xsd, where PointSeriesFeature? is the name of a FeatureType? and schema/csml.xsd is the relative path to its corresponding schema file. The "schemas" folder will contain all schema files that are to be used as the results of “describeFeatureType” requests for the FeatureTypes? defined in Geoserver.

4. The "Info.xml" file

The "info.xml" document must contain the root element featureType with the attribute datastore, which represents the name of the datastore that the FeatureType? in question belongs to. The value of the datastore element must correspond to the identifier of a properly defined datastore in the Geoserver’s catalog.xml file (see section 2). An example of the featureType is given below:

<featureType datastore="midas_point"> ….</featureType>

The featureType element contains a number of mandatory child elements as outlined below:

  1. name element – This element represents the name of the FeatureType? in question. Example:
    <name>Station</Name>
    
  1. SRS element – This element records the Spatial Reference System (SRS) that the FeatureType? employs. This information is included in the GetCapabilities? request. Example:
    <SRS>4326</SRS>
    
  1. title element – This element records a textual title of the FeatureType? in question and is also included in the Geoserver’s response to GetCapabilities? request. Example:
    <title>Midas Station Observation Data</title>
    
  1. abstract element - This element represents a brief description of the dataset presented by the FeatureType?. This information is also included in the Geoserver’s response to GetCapabilities? request. Example:
    <abstract>Landslides pilot, main landslide inventory Geoscience Australia OracleSpatial data</abstract>
    
  1. numDecimals element- <numDecimals value="8" />
  2. keywords element - This element contains a list of simple keywords that are used to describe the dataset presented by the FeatureType? in question. Keywords are delimited by ",". Example:
    <keywords>Landslide,Mappable</keywords>
    
  1. latLonBoundingBox element – This element contains the bounding box for the dataset presented. Example:
    <latLonBoundingBox dynamic="false" minx="110" miny="-43" maxx="160" maxy="-23" />
    
  1. styles element – This element records the identifier to the Styled Layer Descriptor (SLD) file that is used for the Feature Type in question. SLD is an open standard XML based language to describe how maps should look. This is identifier must be the value of the “id” attribute of a properly defined style element in the Catalog.xml file (Figure 2). Example:
    <styles default="point" />
    

5. The Mapping File

The FeatureTypes? exposed by Geoserver are defined in a XML file which must comply to the schema at http://docs.codehaus.org/download/attachments/39940/ComplexDataStore.xsd?version=1. The root element of such a configuration file is ComplexDataStore?. The elements of this file follow the object/property convention. The mappings file may be given any name as long as its full path is passed as a DataStore? configuration parameter in catalog.xml file.

5.1 Namespaces

The first step to creating a mapping file for a FeatureType?, is to declare all namespaces that the elements of the target schema are bound to. The ComplexDataStore?.xsd provides the namespaces element for this purpose. A namespace is recorded under the child element Namespace of the namespaces element. The namespaces element may contain as many Namespace elements as required. An example of how to define a namespace in a mapping file is as follows:

<c:ComplexDataStore xmlns:c="http://www.geotools.org/complex" xmlns:ogc="http://www.opengis.net/ogc"
	xmlns:xs="http://www.w3.org/2001/XMLSchema"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.geotools.org/complex ComplexDataStore.xsd                       http://www.opengis.net/ogc http://schemas.opengis.net/filter/1.1.0/expr.xsd">

    <namepsaces>
        <Namespace>
		<prefix>xlink</prefix>
		<uri>http://www.w3.org/1999/xlink</uri>
	</Namespace>
    </namespaces>
………………………………………………

5.2 Configure source DataStores?

The next step is to specify information necessary to acquire the data source (e.g. database) used. This information is recorded under the DataStore? element, which is a child element of sourceDataStores element. The DataStore? element requires a unique identifier which is recorded under its child element id. Information, such as database drivers and SQL used to retrieve the desired dataset is recorded as a series of name-value pairs under parameters/Parameter elements. It is permissible to add as many Parameter/name and Parameter/value elements as needed to configure the source datastore used, and as many DataStore? elements as needed. The table below outlines a list of different parameters required to define a DataStore? element.

[img  http://proj.badc.rl.ac.uk/ndg/attachment/wiki/GeoManual/table2.JPG]

Table 1: A List of Parameters required to configure a DataStore?

The following XML snippet is an example of the sourceDataStores element, which demonstrates the configuration required to connect to and retrieve data from an oracle database:

……………………………………………………………………………………………
<sourceDataStores>
		<DataStore>
			<id>oracle</id>
			<parameters>
				<Parameter>
					<name>dbtype</name>
					<value>locationsxy</value>
				</Parameter>
				<Parameter>
					<name>host</name>
					<value>ngsdb1-vip.rl.ac.uk</value>
				</Parameter>
				<Parameter>
					<name>port</name>
					<value>1521</value>
				</Parameter>
				<Parameter>
					<name>instance</name>
					<value>/NGSDB.RL.AC.UK</value>
				</Parameter>
				<Parameter>
					<name>user</name>
					<value>ngsdb0042</value>
				</Parameter>
				<Parameter>
					<name>passwd</name>
					<value>m3rryw34th3r</value>
				</Parameter>
				<Parameter>
					<name>geom_name</name>
					<value>POSITION</value>
				</Parameter>
				<Parameter>
					<name>driver</name>
					<value>
oracle.jdbc.pool.OracleConnectionPoolDataSource
</value>
				</Parameter>
				<Parameter>
					<name>urlprefix</name>
					<value>
jdbc:oracle:thin:@//ngsdb1-vip.rl.ac.uk:1521/NGSDB.RL.AC.UK
</value>
				</Parameter>
				<Parameter>
					<name>xcolumn</name>
					<value>ELEVATION </value>
				</Parameter>
				<Parameter>
					<name>ycolumn</name>
					<value>ELEVATION </value>
				</Parameter>
				<Parameter>
					<name>sqlView.1.typeName</name>
					<value>csmlPointSeries</value>
				</Parameter>
				<Parameter>
					<name>sqlView.1.sqlQuery</name>
					<value> 

						SELECT STATION_ID, OB_END_TIME, SRC_NAME, 
							 QUANTITY, FEATURE_TYPE, FEATURE_NAME, 
							 CODE_SPACE, UNIT, HIGH_PRCN_LON, 
HIGH_PRCN_LAT, ELEVATION  
					FROM NGSDB0042.POINT_FEATURE_SERIES
					</value>
				</Parameter>
			</parameters>
		</DataStore>
	</sourceDataStores>
…………………………………………………………………………………………………

5.3 Reference target types

Bellow the sourceDataStores element, it is required to reference the locations of the schemas to be loaded in order to parse the schema-to-FeatureModel?. Schema locations may be either relative to the mapping file or absolute URL's. This information is recorded under the targetTypes element. An example of this element is given below:

<targetTypes>
<FeatureType>
<schemaUri>../../commonSchemas/csmlMain.xsd</schemaUri>
	</FeatureType>
</targetTypes>

5.4 Attribute and id(s) mappings

The last step is to define how to map attributes from one source FeatureType? to a target one. The typeMappings property contains a series of FeatureTypeMapping? elements, where each one defines exactly the information that a org.geotools.data.complex.FeatureTypeMapping? object holds.

For instance, this information is

1.a reference to a source FeatureSource?:

<sourceDataStore>oracle</sourceDataStore> 
	<!-- the is essentially the value of the id element of the 
	DataStore  element as mentioned earlier -->
	<sourceType> csmlPointSeries</sourceType>

	<!-- the is essentially the value of the  sqlView.1.typeName 
	parameter as mentioned in Table 1 -->

2.a reference to an output FeatureType? (the "community" schema). This essentially refers to the root element of the output XML document:

<targetType>csml:PointSeriesFeature</targetType>

3.database fields by which the retrieved result sets are to be grouped. This is only necessary if there exists one-to-many relationships between

the source and target schemas, i.e. if the output schema contains attribute(s) that has multiplicity greater than 1. In such a case, it is required to inform ComplexDataStore? the names of the "grouping" attributes, using the GroupByAttribute? elements, which come below the targetType element. Below is an example of this:

<groupBy>
          <GroupByAttribute>STATION_ID</GroupByAttribute>
	</groupBy>

4.the mappings between FeatureSource? and FeatureType?. The mappings consist of three sets of mappings, one for the identifyable attributes (the

ones with gml:id), such as instances of the FeatureType? itself and any direct or nested property that is also identifyable. The second is for mapping to any other attribute of an element in the target schema. The final type of mapping is for the target attribute values. It should be noted that both for id and attribute mappings, the expression used to assign a value is expressed as an OGC's Common Query Language (OCQL) expression. That way, it is possible to easily define the expression without the need to write the lengthier Filter encoding equivalent. Table 2 below provides examples of these three types of mapping:

[img  http://proj.badc.rl.ac.uk/ndg/attachment/wiki/GeoManual/table.JPG]
Table 2: Different Mapping Types

Geoserver supports any combination of the three aforementioned mappings under an AttributeMapping? element. In addition, as Table 2 above highlights, it is also possible to assign a string literal value, i.e. a value that is not retrieved from any of fields in the SQL result set, to a target attribute. In order for Geoserver to accurately distinguish between SQL field values and string literal value, the former should be in single quotes (‘’). It is also possible to concatenate values of a number of SQL fields or string literal value or a combination of both using the strContact function. The format of this function is as follows:

strConcat (param1, param2)

Geoserver allows the use of nested strConcat functions, i.e. use of a strConcat function as a parameter of another strConcat function. A string literal value should be in single quotes if used as one of the parameters of a strConcat functions. The following is an example of the use of the strConcat function in an attribute mapping:

<AttributeMapping>
     <targetAttribute>csml:location</targetAttribute>
     <sourceExpression>
         <OCQL>strConcat((strConcat(HIGH_PRCN_LON,' ')),HIGH_PRCN_LAT)</OCQL>
     </sourceExpression>
</AttributeMapping>

The output XML is:

<csml:location>-2.76 67</csml:location>

It should also be noted that in order to specify mapping to a child element of an element in the target schema, the full XPath for the child element must be specified under the targetAttribute element. The following example demonstrates the use of XPath in targetAttribute element:

<AttributeMapping>
   <targetAttribute>
      csml:value/csml:PointSeriesCoverage/csml:pointSeriesDomain/csml:TimeSeries/csml:timePositionList
   </targetAttribute>
   <sourceExpression>
      <OCQL>OB_END_TIME</OCQL>
   </sourceExpression>
</AttributeMapping>

The only exception to the aforementioned rule applies to mapping to a gml:PointPropertyType element. In such a case, targetAttribute element should contain an XPath up to the element that is of type gml:PointPropertyType. For example, if the definition of an element, say “location” is as follows:

<element name="location" type="gml:PointPropertyType"/>

then the value of the targetAttribute element that corresponds to this element should just be location instead of location/gml:Point/gml:pos. Furthermore, the OCQL value of this element should be the value of geom_name parameter as mentioned in Table 1. The reason for this exception is that Geoserver is capable of automatically defining the value of a gml:PointPropertyType element based on the spatial location associated (i.e. the value of geom_name parameter) with the dataset used.

5.4.1 Mapping to Multiple Occurrence Elements

In order to accurately map to an element in the target schema which has multiplicity greater than 1, Geoserver requires the use of the “isMultiple” element under the AttributeMapping? element. So in order to output the following:

  <root>
	     <element>
		<child>value1</child>
	     <element>
             <element>
	        <child>value2</child>
             </element>
        </root>

the mapping configuration should be as follows:

<AttributeMapping>
       <targetAttribute>root/element</targetAttribute>
       <targetAttributeNode>elementType</targetAttributeNode>
       <!—in the target Schema this should be <element name=”element” type=”elementType”/>-->
       <isMultiple>true</isMultiple>
    </AttributeMapping>

    <AttributeMapping>
       <targetAttribute>root/element/child </targetAttribute>
       <sourceExpression>
         <OCQL>value</OCQL>
       </sourceExpression> 
    </AttributeMapping>

The current version of Geoserver cannot handle a mappable multiple occurrence element in the target schema. For example, at present it is not possible to output the following through Geoserver:

<root>
	<element>
		<child>value1</child>
		<child>value2</child>
	<element>
</root>

5.4.2 Mapping to List Elements

Mapping to a list type element in the target schema requires the use of the “isList” element under the AttributeMapping? element. So, in order to output the following:

<root>
	<element>
		<child>value1 value2</child>
	<element>
</root>

The mapping configuration should be as follows:

<AttributeMapping>
<targetAttribute>root/element </targetAttribute>
	<targetAttributeNode>elementType</targetAttributeNode>
	<isList>true</isList>
</AttributeMapping>

<AttributeMapping>
<targetAttribute>root/element/child </targetAttribute>
	<sourceExpression>
		<OCQL>value</OCQL>
	</sourceExpression>
</AttributeMapping>

Below is a complete example of the typeMapping element, which uses all aspects of mapping configuration as mentioned above:

<typeMappings>
<FeatureTypeMapping>
<sourceDataStore>oracle</sourceDataStore>
		<sourceType>landslides_view</sourceType>
		<targetElement>csml:PointSeriesFeature</targetElement>
<groupBy>
			<GroupByAttribute>STATION_ID</GroupByAttribute>
		</groupBy>
<attributeMappings>
<AttributeMapping>
				<targetAttribute>
csml:PointSeriesFeature
</targetAttribute>
				<idExpression>										<OCQL>
strConcat(strConcat(FEATURE_TYPE,'.'),STATION_ID)
</OCQL>
				</idExpression>
			</AttributeMapping>

			<AttributeMapping>
					<targetAttribute>gml:description</targetAttribute>
					<sourceExpression>
						<OCQL>SRC_NAME</OCQL>
					</sourceExpression>

				</AttributeMapping>

				<AttributeMapping>
					<targetAttribute>csml:location</targetAttribute>

					<sourceExpression>
						<OCQL>strConcat((strConcat(HIGH_PRCN_LON,' ')),HIGH_PRCN_LAT)</OCQL>
					</sourceExpression>
					<ClientProperty>
						<name>srsName</name>
						<value>'EPSG:4326'</value>
					</ClientProperty>

				</AttributeMapping>

				<AttributeMapping>
					<targetAttribute>csml:value/csml:PointSeriesCoverage</targetAttribute>
					<idExpression>
					
						<OCQL>strConcat((strConcat(strConcat(FEATURE_TYPE,'.'),STATION_ID)), '.cov')</OCQL>
					</idExpression>


				</AttributeMapping>


				<AttributeMapping>
					<targetAttribute>csml:value/csml:PointSeriesCoverage/csml:pointSeriesDomain/csml:TimeSeries</targetAttribute>
					<idExpression>
						
						<OCQL>strConcat((strConcat(strConcat(FEATURE_TYPE,'.'),STATION_ID)), '.cov.time')</OCQL>
					</idExpression>
					
					<targetAttributeNode>csml:TimeSeriesType</targetAttributeNode>
					<isMultiple>true</isMultiple>
				</AttributeMapping>
				<AttributeMapping>
					<targetAttribute>csml:value/csml:PointSeriesCoverage/gml:rangeSet</targetAttribute>
					<targetAttributeNode>gml:RangeSetTypes</targetAttributeNode>
					<isMultiple>true</isMultiple>

				</AttributeMapping>

				<AttributeMapping>
					<targetAttribute>csml:value/csml:PointSeriesCoverage/csml:pointSeriesDomain/csml:TimeSeries/csml:timePositionList</targetAttribute>
					<sourceExpression>
						<OCQL>OB_END_TIME</OCQL>
					</sourceExpression>

				</AttributeMapping>
				

				<AttributeMapping>
					<targetAttribute>csml:value/csml:PointSeriesCoverage/gml:rangeSet/gml:QuantityList</targetAttribute>
					<sourceExpression>
						<OCQL>QUANTITY</OCQL>
					</sourceExpression>
					<ClientProperty>
						<name>uom</name>
						<value>UNIT</value>
					</ClientProperty>
				</AttributeMapping>

				<AttributeMapping>
					<targetAttribute>csml:parameter/swe:Phenomenon</targetAttribute>
					<idExpression>
						<OCQL>FEATURE_NAME</OCQL>
					</idExpression>

				</AttributeMapping>
				<AttributeMapping>
					<targetAttribute>csml:parameter/swe:Phenomenon/gml:name</targetAttribute>
					<sourceExpression>
						<OCQL>FEATURE_TYPE</OCQL>
					</sourceExpression>
					<ClientProperty>
						<name>codeSpace</name>
						<value>CODE_SPACE</value>
					</ClientProperty>
				</AttributeMapping>
			</attributeMappings>
		</FeatureTypeMapping>
	</typeMappings>

Attachments