Changes between Version 13 and Version 14 of GeoManual


Ignore:
Timestamp:
02/12/08 15:27:33 (11 years ago)
Author:
domlowe
Comment:

Fixing some of the false wikiwords

Legend:

Unmodified
Added
Removed
Modified
  • GeoManual

    v13 v14  
    1 = GeoServer "Complex !DataStore/Community Schema": User Manual = 
    2  
    3 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= !GeoServer "Complex !DataStore/Community Schema": User Manual = 
     2 
     3The 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: 
    44 
    55      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.  
    6       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.  
     6      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.  
    77      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.  
    88 
    9 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. 
     9All 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. 
    1010 
    1111Geoserver 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. 
     
    1515 
    1616 
    17 Followings are the steps for creating a new FeatureType in the "Community Schema" version of Geoserver: 
     17Followings are the steps for creating a new !FeatureType in the "Community Schema" version of Geoserver: 
    1818 
    1919   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. 
    2020     [[BR]] 
    21    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. 
     21   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. 
    2222     [[BR]] 
    23    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.  
     23   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.  
    2424     [[BR]] 
    25    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. 
     25   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 !Geoserver’s Data Directory. 
    2626 
    2727[[Image(geo_dir.JPG)]] 
     
    3030 
    3131 
    32 == 2. Defining the DataStore for a FeatureType  == 
     32== 2. Defining the !DataStore for a !FeatureType  == 
    3333  
    3434 
    35 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: 
     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: 
    3636  
    3737[[Image(catalog.JPG)]] 
     
    4343 
    4444 
    45 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:   
    46  
    47 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. 
     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. 
    4848  
    4949 
     
    5151 
    5252 
    53 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: 
     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: 
    5454 
    5555 
     
    6161The featureType element contains a number of mandatory child elements as outlined below: 
    6262 
    63      1. ''name'' element – This element represents the name of the FeatureType in question. Example:  
     63     1. ''name'' element – This element represents the name of the !FeatureType in question. Example:  
    6464{{{ 
    6565<name>Station</Name> 
    6666}}} 
    6767 
    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:  
     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:  
    6969{{{ 
    7070<SRS>4326</SRS> 
    7171}}} 
    7272 
    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:  
     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:  
    7474{{{ 
    7575<title>Midas Station Observation Data</title> 
    7676}}} 
    7777 
    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:  
     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:  
    7979{{{ 
    8080<abstract>Landslides pilot, main landslide inventory Geoscience Australia OracleSpatial data</abstract> 
     
    8282 
    8383     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:  
     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:  
    8585{{{ 
    8686<keywords>Landslide,Mappable</keywords> 
     
    101101 
    102102 
    103 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. 
     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. 
    104104 
    105105'''5.1 Namespaces''' 
    106106 
    107 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: 
     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: 
    108108 
    109109 
     
    123123}}} 
    124124 
    125 '''5.2 Configure source DataStores''' 
    126  
    127 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. 
     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. 
    128128 
    129129[[Image(table2.JPG)]] 
    130130[[BR]] 
    131131 
    132 '''Table 1: A List of Parameters required to configure a DataStore''' 
     132'''Table 1: A List of Parameters required to configure a !DataStore''' 
    133133 
    134134The 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: 
     
    212212'''5.3 Reference target types''' 
    213213 
    214 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: 
     214Bellow 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: 
    215215 
    216216 
     
    226226'''5.4 Attribute and id(s) mappings''' 
    227227 
    228 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. 
     228The 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. 
    229229 
    230230For instance, this information is 
    231       * a reference to a source FeatureSource:  
     231      * a reference to a source !FeatureSource:  
    232232         
    233233 
     
    243243}}} 
    244244 
    245       * a reference to an output FeatureType (the "community" schema).  This essentially refers to the root element of the output XML document:  
     245      * a reference to an output !FeatureType (the "community" schema).  This essentially refers to the root element of the output XML document:  
    246246         
    247247{{{ 
    248248<targetType>csml:PointSeriesFeature</targetType> 
    249249}}} 
    250       * database fields by which the retrieved result sets are to be grouped.  This is only necessary if there exist 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: 
     250      * database fields by which the retrieved result sets are to be grouped.  This is only necessary if there exist 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: 
    251251         
    252252{{{ 
     
    268268 
    269269 
    270 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: 
     270Geoserver 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: 
    271271 
    272272{{{ 
     
    371371''5.4.2 Mapping to List Elements'' 
    372372 
    373 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: 
     373Mapping 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: 
    374374 
    375375