Detailed Consideration

Usually, a profile contains parameters which may be used for several requests (i.e. are not specific to a particular request). As an example, a profile which controls the course of a route might be used for all requests of a given use case. Therefore it is possible to store a profile in a central location and just refer to it in requests rather than having to specify parameters individually and repeatedly. This reduces the complexity of each request and thus saves time and effort.

Some profiles may be inherited from existing profiles by declaring them as a parent. Parent profiles may in turn be inherited. Child profiles then inherit all parameters from the parent, but may overwrite those parameters which are specific for their particular use case. The resulting merger of default values, (indirect or direct) parent profiles, and the child profile is called the effective profileClosed The effective profile is the composition of default values, all parent and child profiles for a single request.. It contains the final values of each parameter to be used in the algorithm.

Profile types

For each request the profile can be specified as storedProfile or requestProfile. It is possible to specify both of them as part of the RequestBase.

	"storedProfile": "myprofile",
	"requestProfile": {

Stored profilesClosed A stored profile is a (partial) profile persisted as an XML file.

Profiles stored in XML files are called stored profiles and can be specified in the field storedProfile of a request. They can be stored in the folder conf/profiles or on some web server and then requested using an http url. They will be cached to optimize for performance.

The folder conf/profiles may contain subfolders, it is scanned recursively for profiles. Profile file names must be unique for all folders. PTV xServer will shutdown immediately when a file name is found in more than one folder. PTV xServer will also shutdown immediately when an invalid profile is found. Please see the log files for detailed information on the erroneous profile.

For security reasons the access to stored profiles requested by an http url can be restricted to certain hosts. The administrator can configure this whitelistClosed A whitelist is a list of host names, IP addresses or IP ranges which are allowed access or to be accessed. All other hosts do not have access. by editing the key in the file xserver.conf. See PTV xServer Configuration File for more details.

PTV xServer provides an XML schema for the stored profiles which can be downloaded from StoredProfile.xsd. Profiles are automatically validated against the schema which can help to find typos during development. A valildation error will be presented in the response as follows.

		"parameter": "storedProfile",
		"hint": "Make sure that the profile xml is well-formed and can be validated against its schema.",
		"faultType": "com.ptvgroup.xserver.exceptions.InvalidValueFault",
		"message": "Could not parse profile. Reason: Error at line 7, column 36: invalid character encountered.",
		"value": "invalid.xml",
		"$type": "XServerException"

Request profilesClosed The request profile is a partial profile provided in object form for a specific request. Any parameter which is not set in the request profile will be taken from the stored profile.

Profiles can also be specified directly in the request. This is called a request profile, with the field requestProfile. A request profile does not have an explicit parent profile. However, a given stored profile is its implicit parent. Request profiles will not be cached, but processed for every request. Sending large request profiles may thus affect the performance. For frequently needed parameters it is thus recommended to create a new stored profile instead, unless these parameters are updated for every request.

Parents, Inheritance, and Effective Profiles

Stored profiles can specify a parent using the parent attribute. This allows users to update only selected parameters, while keeping the majority of the parent's settings intact.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<profile version="2" parent="myprofile">

The parent profile is defined using the parent attribute of the root element profile. The path is always relative to the current profile. In this example we chose the reference profileClosed The reference profile is a stored profile shipped with xServer 2 which can be used directly or as a basis of customization. myprofile. The extension .xml is added automatically. Note that file names are case sensitive for Linux. It is thus recommended to choose lower-case profile names in order to keep stored profiles portable.

Each profile can only have one parent, but a parent profile can have another parent. Duplicated files are not permitted in the profile chain to avoid circular dependencies.

The final value of each parameter is determined as follow:

  1. default value specified in the XML schema of the stored profile or the documentation
  2. value in the parent profile of the stored profile (or in the parent of the parent and so on)
  3. value in the stored profile
  4. value in the request profile

Each step overwrites values of the previous one.

Logging the effective profile

The effective profile for each request is logged at trace level. This is useful to find out if a parameter has been active for a request or not. To enable trace level in the configuration file logging-module.xml, see Logging Configuration.

Profile components

Apart from important top-level configuration options like the mapLanguage and the userLanguage a profile consists of a number of distinct sub-profiles. Following is a short description of the sub-profiles and their purpose.

Vehicle profile Describes the physical and legal properties of a vehicle. It is mainly used to calculate a route considering the vehicle properties such as height and weight. Further use cases are toll and emission calculation which are also highly vehicle-dependent.
Feature Layer profile Allows the configuration of the Feature Layers which contain additional data such as truck attributes, speed patterns, and restriction zones used for routing and map rendering.
Routing profile Contains parameters for configuring and tuning routing behavior.
Map profile Contains parameters for configuring the display of the map.

Good to know

Changing profiles at runtime

It is possible to change profiles stored in the folder conf/profiles without restarting the PTV xServer. The cache will be automatically updated with a changed profile.

It is also possible to add new profiles to existing folders without restarting the PTV xServer, but it is not possible to add new folders. In that case PTV xServer has to be restarted.

When adding new profiles at runtime, make sure that the file name is unique. Otherwise, the behavior when requesting this profile is undefined.

Technical Concept Profile & Map Versions
API Documentation Profile API Documentation