Use Cases > PTV xLocate > How to Access Additional Geographic Data Stored in a Database

How to Access Additional Geographic Data Stored in a Database

PTV xLocate Server is delivered with an example database (derby) containing points of interest (POI) and traffic jams in Luxemburg and configuration files which allow to immediately search for POI categories like petrol-stations. Please see below for more information.

Configuration

PTV xLocate Server needs a configuration to describe the layout of the databases, which objects are available, and how searching is done on these objects. There is one configuration layout:

An xml file in the file system (usually the PTV xLocate Server's conf folder) which is called <configuration>-geodatasource.xml. How to configure the database for the geodatasource configuration.

The configuration's xml file is defined by an XML schema which contains the complete documentation, examples can be found in the conf folder. In order to validate your configuration file against the schema, please keep PTV xLocate Server running and use this URL as described below.

Configuration with xml

The following document is an example of a simple configuration by an xml file (also see conf/default-geodatasource.xml)

<?xml version="1.0" encoding="UTF-8"?>
<GeoDatasource majorVersion="1" minorVersion="0" xmlns="http://www.ptv.de/com/ptvag/xserver/engines/xpoidbaccess" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <Datasource driver="org.apache.derby.jdbc.ClientDriver" url="jdbc:derby://localhost:50026/poi" user="POI" password="POI"/>
 <Layers default="points-of-interest">
  <LayerInfo name="points-of-interest" coordType="PTV_GEODECIMAL" table="T_DATA_POI">
   <Profiles>
    <Profile name="default" filename="geodata-poi-default.xml"/>
    <Profile name="petrol-stations" filename="geodata-petrol-stations.xml"/>
    <Profile name="petrol-stations-alternative" filename="geodata-petrol-stations-alternative.xml"/>
    <Profile name="restaurants" filename="geodata-restaurants.xml"/>
   </Profiles>
   <AttributeMappings>
    <AttributeMapping attributeName="ID" columnName="ID" type="int"/>
    <AttributeMapping attributeName="X" columnName="X" type="int"/>
    <AttributeMapping attributeName="Y" columnName="Y" type="int"/>
    <AttributeMapping attributeName="COUNTRY" columnName="COUNTRY" type="String"/>
    <AttributeMapping attributeName="POSTALCODE" columnName="POSTALCODE" type="String"/>
    <AttributeMapping attributeName="STATE" columnName="STATE" type="String"/>
    <AttributeMapping attributeName="CITY" columnName="CITY" type="String"/>
    <AttributeMapping attributeName="CITY2" columnName="CITY2" type="String"/>
    <AttributeMapping attributeName="STREET" columnName="STREET" type="String"/>
    <AttributeMapping attributeName="HOUSENUMBER" columnName="HOUSENUMBER" type="String"/>
    <AttributeMapping attributeName="POINAME" columnName="POINAME" type="String"/>
    <AttributeMapping attributeName="PHONE" columnName="PHONENUMBER" type="String"/>
    <AttributeMapping attributeName="TYPE" columnName="FEATURECODE" type="String"/>
    <AttributeMapping attributeName="IMAGE" columnName="BILD" type="String"/>
   </AttributeMappings>
   <EngineParameters poiIdColumnName="ALIASID" aliasTypeColumnName="ALIASTYPE" aliasForColumnName="ALIASFOR">
    <Search luceneIndexPath="data/geodata/index"/>
   </EngineParameters>
  </LayerInfo>
  <LayerInfo name="geometries" coordType="PTV_MERCATOR" table="T_DATA_GEOMETRIES">
   <Profiles>
    <Profile name="default" filename="geodata-geometries.xml"/>
    <Profile name="alternative" filename="geodata-geometries-alternative.xml"/>
   </Profiles>
   <AttributeMappings>
    <AttributeMapping attributeName="ID" columnName="C_ID"/>
    <AttributeMapping attributeName="X" columnName="C_X"/>
    <AttributeMapping attributeName="Y" columnName="C_Y"/>
    <AttributeMapping attributeName="VALUE" columnName="C_INTVALUE"/>
   </AttributeMappings>
   <EngineParameters>
    <BoundingBox leftColumnName="C_XMIN" rightColumnName="C_XMAX" bottomColumnName="C_YMIN" topColumnName="C_YMAX"/>
    <Rendering geometryColumnName="C_WKBGEOMETRY" geometryType="WKB"/>
   </EngineParameters>
  </LayerInfo>
  <LayerInfo name="traffic" coordType="PTV_MERCATOR" table="T_DATA_TRAFFICINFO">
   <Profiles>
    <Profile name="default" filename="geodata-traffic.xml"/>
    <Profile name="alternative" filename="geodata-traffic-alternative.xml"/>
   </Profiles>
   <AttributeMappings>
    <AttributeMapping attributeName="ID" columnName="C_ID"/>
    <AttributeMapping attributeName="X" columnName="C_X"/>
    <AttributeMapping attributeName="Y" columnName="C_Y"/>
    <AttributeMapping attributeName="CATEGORY" columnName="C_CATEGORY"/>
    <AttributeMapping attributeName="TEXT" columnName="C_DESCRIPTION"/>
   </AttributeMappings>
   <EngineParameters>
    <BoundingBox leftColumnName="C_XMIN" rightColumnName="C_XMAX" bottomColumnName="C_YMIN" topColumnName="C_YMAX"/>
    <Rendering geometryColumnName="C_WKBGEOMETRY" geometryType="WKB"/>
    <Traffic exceptionPathColumnName="C_EXCEPTIONPATH"/>
   </EngineParameters>
  </LayerInfo>
 </Layers>
</GeoDatasource>

The element Datasource defines a database, where the data is available. The parameters are the JDBC-parameters driver for the database driver class, url for the database url, user for the database user and password for the database user password. In order to use a database driver different from derby, please install it to the shared/lib folder of PTV xLocate Server.

Each layer which is a set of data belonging together is configured by an element LayerInfo. It has the attributes:

name - the layer name. In this case there are layers with the layer name points-of-interests, geometries and traffic. If the layer name is omitted the layer points-of-interests is used (cf. attribute default at element Layers)
coordType - the coordinate format type. Except for OG_SRID all types can be applied as for the PTV xLocate Server requests: PTV_MERCATOR, OG_GEODECIMAL, PTV_GEODECIMAL, PTV_GEOMINSEC, etc.
Please note that for the Rendering geometryType KML only OG_GEODECIMAL can be used.
table - the database table name

Furthermore, a set of profiles (see below) and a set of attributes must be defined. Mandatory attributes are ID, X, and Y which must be mapped to columns in the table configured above. Other attributes can be defined and used within the profile in order to map the routing (malus) element. Please note that a columnName can be only used once in a AttributeMappings element.

Each profile configured in the Profiles element must obtain a name and can obtain a filename. If the filename is present, it must contain the path to the profile file relative to the geodatasource file path. Otherwise, the filename is assumed to be <name>.xml. When requesting the default profile, the profile called default is used. If it is not present, the first profile in the list is used.

Search behaviour (GeoDataProfile)

Information on how to perform searches on the database objects are stored in a GeoDataProfile. The profile's xml file is defined by an XML schema which contains the complete documentation, examples can be found in the conf folder (here as an example the contents of geodata-search-base.xml).

<?xml version="1.0" encoding="UTF-8"?>
<GeoDataProfile majorVersion="1" minorVersion="0" xmlns="http://www.ptv.de/com/ptvag/xserver/engines/xpoidbaccess" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ptv.de/com/ptvag/xserver/engines/xpoidbaccess http://localhost:50020/xlocate/schema/1.0/GeoDataProfile.xsd">
 <Search>
  <SortParameter>
   <SortField attributeName="poiname" order="Ascending"/>
   <SortField attributeName="country" order="Ascending"/>
   <SortField attributeName="city" order="Ascending"/>
   <SortField attributeName="city2" order="Ascending"/>
   <SortField attributeName="street" order="Ascending"/>
  </SortParameter>
  <SearchParameter countryCodeType="3" maximumResultSize="250" maximumSearchRange="300000" minimumSearchSimilarity="0.7" padResultList="false">
   <SearchField attributeName="country" fuzzy="false" multiword="false" prefix="false"/>
   <SearchField attributeName="postcode" fuzzy="false" multiword="false" prefix="true"/>
   <SearchField attributeName="city" fuzzy="true" multiword="true" prefix="true"/>
   <SearchField attributeName="city2" fuzzy="true" multiword="true" prefix="true"/>
   <SearchField attributeName="street" fuzzy="true" multiword="true" prefix="true"/>
   <SearchField attributeName="housenr" fuzzy="false" multiword="false" prefix="false"/>
   <SearchField attributeName="poiname" fuzzy="true" multiword="true" prefix="true"/>
   <SearchField attributeName="poitype" fuzzy="false" multiword="true" prefix="false"/>
  </SearchParameter>
 </Search>
</GeoDataProfile>

Each profile is automatically validated against the XML schema, validation errors are written to the log file and an exception is thrown. In order to fix the problem, please validate your profile against the schema, keep PTV xLocate Server running and use this URL as xsi:schemaLocation as follows.

<GeoDataProfile xmlns="http://www.ptv.de/com/ptvag/xserver/engines/xpoidbaccess"   
			xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
			xsi:schemaLocation="http://www.ptv.de/com/ptvag/xserver/engines/xpoidbaccess 
			http://localhost:50020/xlocate/schema/1.0/GeoDataProfile.xsd"
		majorVersion="1" minorVersion="0"/>

The profile can then automatically be validated by using tools such as Altova XMLSpy.

Profiles can be sub classed using the Parent tag. Example:

<GeoDataProfile ...>
		<Parent>
			geodata-search-base-profile
		</Parent>

In this example all information of the profile geodata-base-profile is imported into the current profile.

Note that changes in a sub-profile always overwrite the parent's values. Also note that the parent profile is specified by the filename without the .xml extension.