Changes between Version 7 and Version 8 of GeoManual

18/04/08 17:27:20 (13 years ago)



  • GeoManual

    v7 v8  
    2929'''Figure 1: Structure of a Geoserver’s Data Directory''' 
     32== 2. Defining the DataStore for a FeatureType  == 
     35In 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: 
     39'''Figure 2: Catalog.xml file''' 
     42== 3. Configuring Geoserver for the "describeFeatureType" request == 
     45The "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:   
     47In 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. 
     50== 4. The "Info.xml" file == 
     53The "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: 
     57<featureType datastore="midas_point"> ….</featureType> 
     61The featureType element contains a number of mandatory child elements as outlined below: 
     63     1. ''name'' element – This element represents the name of the FeatureType in question. Example:  
     68     2. ''SRS'' element – This element records the Spatial Reference System (SRS) that the FeatureType employs.  This information is included in the GetCapabilities request. Example:  
     73     3. ''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:  
     75<title>Midas Station Observation Data</title> 
     78     4. ''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:  
     80<abstract>Landslides pilot, main landslide inventory Geoscience Australia OracleSpatial data</abstract> 
     83     5. ''numDecimals'' element- <numDecimals value="8" /> 
     84     6. ''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:  
     89     7. ''latLonBoundingBox'' element – This element contains the bounding box for the dataset presented. Example:  
     91<latLonBoundingBox dynamic="false" minx="110" miny="-43" maxx="160" maxy="-23" /> 
     94     8. ''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:  
     96<styles default="point" /> 
     100== 5. The Mapping File == 
     103The FeatureTypes exposed by Geoserver are defined in a XML file which must comply to the schema at[].  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. 
     105'''5.1 Namespaces''' 
     107The 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: 
     111<c:ComplexDataStore xmlns:c="" xmlns:ogc="" 
     112        xmlns:xs="" 
     113        xmlns:xsi="" 
     114        xsi:schemaLocation=" ComplexDataStore.xsd             "> 
     116    <namepsaces> 
     117        <Namespace> 
     118                <prefix>xlink</prefix> 
     119                <uri></uri> 
     120        </Namespace> 
     121    </namespaces> 
     125'''5.2 Configure source DataStores''' 
     127The 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. 
     130'''Parameter''' '''Description''' 
     131    dbtype          Type of database. Example: “locationxy” for spatial database. (this has been used for both ECN and MIDAS datasets) 
     132    host            Database host name/ip address 
     133    port            Database port number 
     134    instance        Name of the database schema used. 
     135    user            Username required to access the database 
     136    password        Password associated with the username 
     137    driver          JDBC driver required to establish connection to the database used. Example:  
     138                    (postGreSQL), oracle.jdbc.pool.OracleConnectionPoolDataSource (oracle) 
     139    urlprefix       JDBC URL required to establish connection to the database. Example: jdbc:oracle:thin:@//host:1521/schema (oracle)  
     140    xcolumn         "Logitude" field of a spatial database 
     141    ycolumn         "Latitude" field of a spatial database 
     142    geom_name       This parameter records the spatial location associated with the dataset used.  The value of this parameter is calculated  
     143                    automatically using the values of xcolumn and ycolumn.  This parameter must be specified for dbtype "locationxy" 
     144    sqlView.1.typeName  An identifier for the SQL used to retrieve the dataset required from the database 
     145    sqlView.1.sqlQuery  The SQL statement used to retrieve the dataset required from the database. Geoserver supports the following SQL keywords:  
     146                        SELECT, FROM, WHERE, UNION, UNION ALL, ORDER BY, GROUP BY, JOIN.  It is recommended that tables in a SELECT statement be  
     147                        uniquely identified using "schema." prefix. 
     149'''Table 1: A List of Parameters required to configure a DataStore''' 
     151The 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: 
     156                <DataStore> 
     157                        <id>oracle</id> 
     158                        <parameters> 
     159                                <Parameter> 
     160                                        <name>dbtype</name> 
     161                                        <value>locationsxy</value> 
     162                                </Parameter> 
     163                                <Parameter> 
     164                                        <name>host</name> 
     165                                        <value></value> 
     166                                </Parameter> 
     167                                <Parameter> 
     168                                        <name>port</name> 
     169                                        <value>1521</value> 
     170                                </Parameter> 
     171                                <Parameter> 
     172                                        <name>instance</name> 
     173                                        <value>/NGSDB.RL.AC.UK</value> 
     174                                </Parameter> 
     175                                <Parameter> 
     176                                        <name>user</name> 
     177                                        <value>ngsdb0042</value> 
     178                                </Parameter> 
     179                                <Parameter> 
     180                                        <name>passwd</name> 
     181                                        <value>m3rryw34th3r</value> 
     182                                </Parameter> 
     183                                <Parameter> 
     184                                        <name>geom_name</name> 
     185                                        <value>POSITION</value> 
     186                                </Parameter> 
     187                                <Parameter> 
     188                                        <name>driver</name> 
     189                                        <value> 
     192                                </Parameter> 
     193                                <Parameter> 
     194                                        <name>urlprefix</name> 
     195                                        <value> 
     198                                </Parameter> 
     199                                <Parameter> 
     200                                        <name>xcolumn</name> 
     201                                        <value>ELEVATION </value> 
     202                                </Parameter> 
     203                                <Parameter> 
     204                                        <name>ycolumn</name> 
     205                                        <value>ELEVATION </value> 
     206                                </Parameter> 
     207                                <Parameter> 
     208                                        <name>sqlView.1.typeName</name> 
     209                                        <value>csmlPointSeries</value> 
     210                                </Parameter> 
     211                                <Parameter> 
     212                                        <name>sqlView.1.sqlQuery</name> 
     213                                        <value>  
     215                                                SELECT STATION_ID, OB_END_TIME, SRC_NAME,  
     216                                                         QUANTITY, FEATURE_TYPE, FEATURE_NAME,  
     217                                                         CODE_SPACE, UNIT, HIGH_PRCN_LON,  
     219                                        FROM NGSDB0042.POINT_FEATURE_SERIES 
     220                                        </value> 
     221                                </Parameter> 
     222                        </parameters> 
     223                </DataStore> 
     224        </sourceDataStores> 
     229'''5.3 Reference target types''' 
     231Bellow 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: 
     238        </FeatureType> 
     243'''5.4 Attribute and id(s) mappings''' 
     245The 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 object holds. 
     247For instance, this information is 
     248      1.a reference to a source FeatureSource:  
     254        <!-- the is essentially the value of the id element of the  
     255        DataStore  element as mentioned earlier --> 
     256        <sourceType> csmlPointSeries</sourceType> 
     258        <!-- the is essentially the value of the  sqlView.1.typeName  
     259        parameter as mentioned in Table 1 --> 
     262      2.a reference to an output FeatureType (the "community" schema).  This essentially refers to the root element of the output XML document:  
     267      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  
     268        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   
     269        required to inform ComplexDataStore the names of the "grouping" attributes, using the GroupByAttribute elements, which come below the  
     270        targetType element.  Below is an example of this: 
     274          <GroupByAttribute>STATION_ID</GroupByAttribute> 
     275        </groupBy> 
     277      4.the mappings between FeatureSource and FeatureType. The mappings consist of three sets of mappings, one for the identifyable attributes (the  
     278        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   
     279        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 
     280        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)  
     281        expression. That way, it is possible to easily define the expression without the need to write the lengthier Filter encoding equivalent.  Table  
     282        2 below provides examples of these three types of mapping: 
     285'''Table 2: Different Mapping Types''' 
     286Geoserver 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: 
     287strConcat (param1, param2)    
     288Geoserver 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: 
     293                <OCQL> 
     294strConcat((strConcat(HIGH_PRCN_LON,' ')),HIGH_PRCN_LAT) 
     296        </sourceExpression> 
     299The output XML is: <csml:location>-2.76 67</csml:location> 
     301It 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: 
     308        <sourceExpression> 
     309                <OCQL>OB_END_TIME</OCQL> 
     310        </sourceExpression> 
     313The 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: 
     315<element name=”location” type=”gml:PointPropertyType”/> 
     317then 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. 
     3195.4.1 Mapping to Multiple Occurrence Elements 
     321In 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: 
     324        <element> 
     325                <child>value1</child> 
     326        <element> 
     328        <child>value2</child> 
     332the mapping configuration should be as follows: 
     336        <targetAttributeNode>elementType</targetAttributeNode> 
     337        <!—in the target Schema this should be <element name=”element” type=”elementType”/>--> 
     338        <isMultiple>true</isMultiple> 
     342<targetAttribute>root/element/child </targetAttribute> 
     343        <sourceExpression> 
     345        </sourceExpression> 
     348The 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: 
     351        <element> 
     352                <child>value1</child> 
     353                <child>value2</child> 
     354        <element> 
     3575.4.2 Mapping to List Elements 
     359Mapping 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: 
     362        <element> 
     363                <child>value1 value2</child> 
     364        <element> 
     367The mapping configuration should be as follows: 
     370<targetAttribute>root/element </targetAttribute> 
     371        <targetAttributeNode>elementType</targetAttributeNode> 
     372        <isList>true</isList> 
     376<targetAttribute>root/element/child </targetAttribute> 
     377        <sourceExpression> 
     378                <OCQL>value</OCQL> 
     379        </sourceExpression> 
     382Below is a complete example of the typeMapping element, which uses all aspects of mapping configuration as mentioned above: 
     387                <sourceType>landslides_view</sourceType> 
     388                <targetElement>csml:PointSeriesFeature</targetElement> 
     390                        <GroupByAttribute>STATION_ID</GroupByAttribute> 
     391                </groupBy> 
     394                                <targetAttribute> 
     397                                <idExpression>                                                                          <OCQL> 
     400                                </idExpression> 
     401                        </AttributeMapping> 
     403                        <AttributeMapping> 
     404                                        <targetAttribute>gml:description</targetAttribute> 
     405                                        <sourceExpression> 
     406                                                <OCQL>SRC_NAME</OCQL> 
     407                                        </sourceExpression> 
     409                                </AttributeMapping> 
     411                                <AttributeMapping> 
     412                                        <targetAttribute>csml:location</targetAttribute> 
     414                                        <sourceExpression> 
     415                                                <OCQL>strConcat((strConcat(HIGH_PRCN_LON,' ')),HIGH_PRCN_LAT)</OCQL> 
     416                                        </sourceExpression> 
     417                                        <ClientProperty> 
     418                                                <name>srsName</name> 
     419                                                <value>'EPSG:4326'</value> 
     420                                        </ClientProperty> 
     422                                </AttributeMapping> 
     424                                <AttributeMapping> 
     425                                        <targetAttribute>csml:value/csml:PointSeriesCoverage</targetAttribute> 
     426                                        <idExpression> 
     428                                                <OCQL>strConcat((strConcat(strConcat(FEATURE_TYPE,'.'),STATION_ID)), '.cov')</OCQL> 
     429                                        </idExpression> 
     432                                </AttributeMapping> 
     435                                <AttributeMapping> 
     436                                        <targetAttribute>csml:value/csml:PointSeriesCoverage/csml:pointSeriesDomain/csml:TimeSeries</targetAttribute> 
     437                                        <idExpression> 
     439                                                <OCQL>strConcat((strConcat(strConcat(FEATURE_TYPE,'.'),STATION_ID)), '.cov.time')</OCQL> 
     440                                        </idExpression> 
     442                                        <targetAttributeNode>csml:TimeSeriesType</targetAttributeNode> 
     443                                        <isMultiple>true</isMultiple> 
     444                                </AttributeMapping> 
     445                                <AttributeMapping> 
     446                                        <targetAttribute>csml:value/csml:PointSeriesCoverage/gml:rangeSet</targetAttribute> 
     447                                        <targetAttributeNode>gml:RangeSetTypes</targetAttributeNode> 
     448                                        <isMultiple>true</isMultiple> 
     450                                </AttributeMapping> 
     452                                <AttributeMapping> 
     453                                        <targetAttribute>csml:value/csml:PointSeriesCoverage/csml:pointSeriesDomain/csml:TimeSeries/csml:timePositionList</targetAttribute> 
     454                                        <sourceExpression> 
     455                                                <OCQL>OB_END_TIME</OCQL> 
     456                                        </sourceExpression> 
     458                                </AttributeMapping> 
     461                                <AttributeMapping> 
     462                                        <targetAttribute>csml:value/csml:PointSeriesCoverage/gml:rangeSet/gml:QuantityList</targetAttribute> 
     463                                        <sourceExpression> 
     464                                                <OCQL>QUANTITY</OCQL> 
     465                                        </sourceExpression> 
     466                                        <ClientProperty> 
     467                                                <name>uom</name> 
     468                                                <value>UNIT</value> 
     469                                        </ClientProperty> 
     470                                </AttributeMapping> 
     472                                <AttributeMapping> 
     473                                        <targetAttribute>csml:parameter/swe:Phenomenon</targetAttribute> 
     474                                        <idExpression> 
     475                                                <OCQL>FEATURE_NAME</OCQL> 
     476                                        </idExpression> 
     478                                </AttributeMapping> 
     479                                <AttributeMapping> 
     480                                        <targetAttribute>csml:parameter/swe:Phenomenon/gml:name</targetAttribute> 
     481                                        <sourceExpression> 
     482                                                <OCQL>FEATURE_TYPE</OCQL> 
     483                                        </sourceExpression> 
     484                                        <ClientProperty> 
     485                                                <name>codeSpace</name> 
     486                                                <value>CODE_SPACE</value> 
     487                                        </ClientProperty> 
     488                                </AttributeMapping> 
     489                        </attributeMappings> 
     490                </FeatureTypeMapping> 
     491        </typeMappings>