Changes between Version 7 and Version 8 of GeoManual


Ignore:
Timestamp:
18/04/08 17:27:20 (13 years ago)
Author:
ashaon
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • GeoManual

    v7 v8  
    2828[[BR]] 
    2929'''Figure 1: Structure of a Geoserver’s Data Directory''' 
     30 
     31 
     32== 2. Defining the DataStore for a FeatureType  == 
     33  
     34 
     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: 
     36  
     37[img http://proj.badc.rl.ac.uk/ndg/attachment/wiki/GeoManual/catalog.JPG] 
     38[[BR]] 
     39'''Figure 2: Catalog.xml file''' 
     40 
     41 
     42== 3. Configuring Geoserver for the "describeFeatureType" request == 
     43 
     44 
     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:   
     46 
     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. 
     48  
     49 
     50== 4. The "Info.xml" file == 
     51 
     52 
     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: 
     54 
     55 
     56{{{ 
     57<featureType datastore="midas_point"> ….</featureType> 
     58}}} 
     59 
     60 
     61The featureType element contains a number of mandatory child elements as outlined below: 
     62 
     63     1. ''name'' element – This element represents the name of the FeatureType in question. Example:  
     64{{{ 
     65<name>Station</Name> 
     66}}} 
     67 
     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:  
     69{{{ 
     70<SRS>4326</SRS> 
     71}}} 
     72 
     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:  
     74{{{ 
     75<title>Midas Station Observation Data</title> 
     76}}} 
     77 
     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:  
     79{{{ 
     80<abstract>Landslides pilot, main landslide inventory Geoscience Australia OracleSpatial data</abstract> 
     81}}} 
     82 
     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:  
     85{{{ 
     86<keywords>Landslide,Mappable</keywords> 
     87}}} 
     88 
     89     7. ''latLonBoundingBox'' element – This element contains the bounding box for the dataset presented. Example:  
     90{{{ 
     91<latLonBoundingBox dynamic="false" minx="110" miny="-43" maxx="160" maxy="-23" /> 
     92}}} 
     93 
     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:  
     95{{{ 
     96<styles default="point" /> 
     97}}} 
     98 
     99 
     100== 5. The Mapping File == 
     101 
     102 
     103The 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. 
     104 
     105'''5.1 Namespaces''' 
     106 
     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: 
     108 
     109 
     110{{{ 
     111<c:ComplexDataStore xmlns:c="http://www.geotools.org/complex" xmlns:ogc="http://www.opengis.net/ogc" 
     112        xmlns:xs="http://www.w3.org/2001/XMLSchema" 
     113        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     114        xsi:schemaLocation="http://www.geotools.org/complex ComplexDataStore.xsd                       http://www.opengis.net/ogc http://schemas.opengis.net/filter/1.1.0/expr.xsd"> 
     115 
     116    <namepsaces> 
     117        <Namespace> 
     118                <prefix>xlink</prefix> 
     119                <uri>http://www.w3.org/1999/xlink</uri> 
     120        </Namespace> 
     121    </namespaces> 
     122……………………………………………… 
     123}}} 
     124 
     125'''5.2 Configure source DataStores''' 
     126 
     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. 
     128 
     129 
     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: org.geotools.data.geometryless.wrapper.PGConnectionPool  
     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. 
     148 
     149'''Table 1: A List of Parameters required to configure a DataStore''' 
     150 
     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: 
     152 
     153{{{ 
     154…………………………………………………………………………………………… 
     155<sourceDataStores> 
     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>ngsdb1-vip.rl.ac.uk</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> 
     190oracle.jdbc.pool.OracleConnectionPoolDataSource 
     191</value> 
     192                                </Parameter> 
     193                                <Parameter> 
     194                                        <name>urlprefix</name> 
     195                                        <value> 
     196jdbc:oracle:thin:@//ngsdb1-vip.rl.ac.uk:1521/NGSDB.RL.AC.UK 
     197</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>  
     214 
     215                                                SELECT STATION_ID, OB_END_TIME, SRC_NAME,  
     216                                                         QUANTITY, FEATURE_TYPE, FEATURE_NAME,  
     217                                                         CODE_SPACE, UNIT, HIGH_PRCN_LON,  
     218HIGH_PRCN_LAT, ELEVATION   
     219                                        FROM NGSDB0042.POINT_FEATURE_SERIES 
     220                                        </value> 
     221                                </Parameter> 
     222                        </parameters> 
     223                </DataStore> 
     224        </sourceDataStores> 
     225………………………………………………………………………………………………… 
     226}}} 
     227 
     228 
     229'''5.3 Reference target types''' 
     230 
     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: 
     232 
     233 
     234{{{ 
     235<targetTypes> 
     236<FeatureType> 
     237<schemaUri>../../commonSchemas/csmlMain.xsd</schemaUri> 
     238        </FeatureType> 
     239</targetTypes> 
     240}}} 
     241 
     242 
     243'''5.4 Attribute and id(s) mappings''' 
     244 
     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 org.geotools.data.complex.FeatureTypeMapping object holds. 
     246 
     247For instance, this information is 
     248      1.a reference to a source FeatureSource:  
     249         
     250 
     251 
     252{{{ 
     253<sourceDataStore>oracle</sourceDataStore>  
     254        <!-- the is essentially the value of the id element of the  
     255        DataStore  element as mentioned earlier --> 
     256        <sourceType> csmlPointSeries</sourceType> 
     257 
     258        <!-- the is essentially the value of the  sqlView.1.typeName  
     259        parameter as mentioned in Table 1 --> 
     260}}} 
     261 
     262      2.a reference to an output FeatureType (the "community" schema).  This essentially refers to the root element of the output XML document:  
     263         
     264{{{ 
     265<targetType>csml:PointSeriesFeature</targetType> 
     266}}} 
     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: 
     271         
     272{{{ 
     273<groupBy> 
     274          <GroupByAttribute>STATION_ID</GroupByAttribute> 
     275        </groupBy> 
     276}}} 
     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: 
     283 
     284 
     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: 
     289 
     290<AttributeMapping> 
     291<targetAttribute>csml:location</targetAttribute> 
     292<sourceExpression> 
     293                <OCQL> 
     294strConcat((strConcat(HIGH_PRCN_LON,' ')),HIGH_PRCN_LAT) 
     295</OCQL> 
     296        </sourceExpression> 
     297</AttributeMapping> 
     298 
     299The output XML is: <csml:location>-2.76 67</csml:location> 
     300 
     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: 
     302 
     303 
     304<AttributeMapping> 
     305<targetAttribute> 
     306csml:value/csml:PointSeriesCoverage/csml:pointSeriesDomain/csml:TimeSeries/csml:timePositionList 
     307</targetAttribute> 
     308        <sourceExpression> 
     309                <OCQL>OB_END_TIME</OCQL> 
     310        </sourceExpression> 
     311</AttributeMapping> 
     312 
     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: 
     314 
     315<element name=”location” type=”gml:PointPropertyType”/> 
     316 
     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. 
     318 
     3195.4.1 Mapping to Multiple Occurrence Elements 
     320 
     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: 
     322 
     323<root> 
     324        <element> 
     325                <child>value1</child> 
     326        <element> 
     327<element> 
     328        <child>value2</child> 
     329</element> 
     330</root> 
     331 
     332the mapping configuration should be as follows: 
     333 
     334<AttributeMapping> 
     335<targetAttribute>root/element</targetAttribute> 
     336        <targetAttributeNode>elementType</targetAttributeNode> 
     337        <!—in the target Schema this should be <element name=”element” type=”elementType”/>--> 
     338        <isMultiple>true</isMultiple> 
     339</AttributeMapping> 
     340 
     341<AttributeMapping> 
     342<targetAttribute>root/element/child </targetAttribute> 
     343        <sourceExpression> 
     344<OCQL>value</OCQL> 
     345        </sourceExpression> 
     346</AttributeMapping> 
     347 
     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: 
     349 
     350<root> 
     351        <element> 
     352                <child>value1</child> 
     353                <child>value2</child> 
     354        <element> 
     355</root> 
     356 
     3575.4.2 Mapping to List Elements 
     358 
     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: 
     360 
     361<root> 
     362        <element> 
     363                <child>value1 value2</child> 
     364        <element> 
     365</root> 
     366 
     367The mapping configuration should be as follows: 
     368 
     369<AttributeMapping> 
     370<targetAttribute>root/element </targetAttribute> 
     371        <targetAttributeNode>elementType</targetAttributeNode> 
     372        <isList>true</isList> 
     373</AttributeMapping> 
     374 
     375<AttributeMapping> 
     376<targetAttribute>root/element/child </targetAttribute> 
     377        <sourceExpression> 
     378                <OCQL>value</OCQL> 
     379        </sourceExpression> 
     380</AttributeMapping> 
     381 
     382Below is a complete example of the typeMapping element, which uses all aspects of mapping configuration as mentioned above: 
     383 
     384<typeMappings> 
     385<FeatureTypeMapping> 
     386<sourceDataStore>oracle</sourceDataStore> 
     387                <sourceType>landslides_view</sourceType> 
     388                <targetElement>csml:PointSeriesFeature</targetElement> 
     389<groupBy> 
     390                        <GroupByAttribute>STATION_ID</GroupByAttribute> 
     391                </groupBy> 
     392<attributeMappings> 
     393<AttributeMapping> 
     394                                <targetAttribute> 
     395csml:PointSeriesFeature 
     396</targetAttribute> 
     397                                <idExpression>                                                                          <OCQL> 
     398strConcat(strConcat(FEATURE_TYPE,'.'),STATION_ID) 
     399</OCQL> 
     400                                </idExpression> 
     401                        </AttributeMapping> 
     402 
     403                        <AttributeMapping> 
     404                                        <targetAttribute>gml:description</targetAttribute> 
     405                                        <sourceExpression> 
     406                                                <OCQL>SRC_NAME</OCQL> 
     407                                        </sourceExpression> 
     408 
     409                                </AttributeMapping> 
     410 
     411                                <AttributeMapping> 
     412                                        <targetAttribute>csml:location</targetAttribute> 
     413 
     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> 
     421 
     422                                </AttributeMapping> 
     423 
     424                                <AttributeMapping> 
     425                                        <targetAttribute>csml:value/csml:PointSeriesCoverage</targetAttribute> 
     426                                        <idExpression> 
     427                                         
     428                                                <OCQL>strConcat((strConcat(strConcat(FEATURE_TYPE,'.'),STATION_ID)), '.cov')</OCQL> 
     429                                        </idExpression> 
     430 
     431 
     432                                </AttributeMapping> 
     433 
     434 
     435                                <AttributeMapping> 
     436                                        <targetAttribute>csml:value/csml:PointSeriesCoverage/csml:pointSeriesDomain/csml:TimeSeries</targetAttribute> 
     437                                        <idExpression> 
     438                                                 
     439                                                <OCQL>strConcat((strConcat(strConcat(FEATURE_TYPE,'.'),STATION_ID)), '.cov.time')</OCQL> 
     440                                        </idExpression> 
     441                                         
     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> 
     449 
     450                                </AttributeMapping> 
     451 
     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> 
     457 
     458                                </AttributeMapping> 
     459                                 
     460 
     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> 
     471 
     472                                <AttributeMapping> 
     473                                        <targetAttribute>csml:parameter/swe:Phenomenon</targetAttribute> 
     474                                        <idExpression> 
     475                                                <OCQL>FEATURE_NAME</OCQL> 
     476                                        </idExpression> 
     477 
     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>