Characteristic
Short description
A profile is a collection of parameters used to configure the request. Full profiles consist of a number of specialized sub-profiles like the VehicleProfile which describes the properties of a vehicle. Profiles contain parameters which control how the response is calculated.
Use
A route corresponds to a path of a vehicle through the underlying transport network. The main attributes of a route are the distance and the time that the vehicle travels along the path. calculation and map rendering, or for the vehicle The term vehicle describes what is being routed or planned for. Vehicles are used in route calculation, distance matrix calculation and effectively also in tour planning. In route calculation, vehicle properties like overall size, weight and speed are in focus. In tour planning, it is vehicle properties like capacity and availability.
Commonly a vehicle is motorized, like a truck - including its trailer or a car. However also a bike or even a pedestrian are included in this definition.. Almost all parameters of a profile are optional. The defaults can be found in the documentation of each parameter and will not be changed in future versions. Therefore, a user-defined profile should only contain parameters which override defaults to keep it small and readable.
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 profile 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 profiles 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 whitelist 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 core.security.externalResourcesAccessWhitelist 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"
}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">
...
</profile>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 profile 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:
- default value specified in the XML schema of the stored profile or the documentation
- value in the parent profile of the stored profile (or in the parent of the parent and so on)
- value in the stored profile
- value in the request profile
Each step overwrites values of the previous one.
Show examples...
The following examples show how parent and child profile are composed:
Attributes present in both parent and child profile are overwritten, and attributes not present in the child profile remain unchanged. Attributes not present in the parent profile will be added.
parent profile
<element
attribute1="value1"
attribute3="value3"/>child profile
<element
attribute2="value2"
attribute3="newValue3"/>effective profile
<element
attribute1="value1"
attribute2="value2"
attribute3="newValue3"/>When a child profile defines additional elements, these elements are merged into the parent element to form the effective profile.
parent profile
<element>
<subElement1 attribute1="value1"/>
</element>child profile
<element>
<subElement2 attribute2="value2"/>
</element>effective profile
<element>
<subElement1 attribute1="value1"/>
<subElement2 attribute2="value2"/>
</element>When a child profile defines additional elements in a list, these elements will be appended to the list of the parent profile.
parent profile
<element>
<listElement attribute="value1"/>
<listElement attribute="value2"/>
</element>child profile
<element>
<listElement attribute="value3"/>
<listElement attribute="value4"/>
</element>effective profile
<element>
<listElement attribute="value1"/>
<listElement attribute="value2"/>
<listElement attribute="value3"/>
<listElement attribute="value4"/>
</element>When a child profile defines additional elements in a list where each list element has some key attribute such as an id, child elements will overwrite parent elements with the same key.
parent profile
<element>
<listElement key="key1" value="value1"/>
<listElement key="key2" value="value2"/>
</element>child profile
<element>
<listElement key="key2" value="newValue2"/>
<listElement key="key3" value="value3"/>
</element>effective profile
<element>
<listElement key="key1" value="value1"/>
<listElement key="key2" value="newValue2"/>
<listElement key="key3" value="value3"/>
</element>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.
Related Topics
| Technical Concept | Profile & Map Versions |
| API Documentation | Profile API Documentation |