Services Configuration

Services and backend instances

Services run on one or more backend instances that perform the actual calculations. Technically, instances are Java virtual machines and are mostly independent from the server process. Each backend instance can serve one or more services. This approach allows a wide range of possible installations:

an xServer with only one service on one or more backend instances
an xServer with all services on all backend instances
an xServer with mixed backend instances serving a single service or multiple services

Configure services

Related file: xserver.conf

Backend services and instances are configured with two subsections in xserver.conf. The first entry is a named subsection in core.modules.definitions. Each of these definitions must specify a property services which contains an array of services that should be included for this definition. The order in which the services are specified does not affect the order in which they are started.

With the second property core.modules.instances it is defined how many backend instances should be started for each definition. The default configuration starts just one backend instance for the default definition:

core {
    modules {
        definitions {
            default {
                services = [xlocate, xmap, xroute]
            }
        }
        instances {
            default = 1
        }
    }
}

You can define multiple definitions and start multiple instances of each definition. Here's an example for 16 different backend instances:

core {
    modules {
        definitions {
            default {
                services = [xlocate, xmap, xroute]
            }
            rendering {
                services = [xmap]
            }
            routingAndLocating {
                services = [xlocate, xroute]
            }
        }
        instances {
            default = 2
            rendering = 8
            routingAndLocating = 6
        }
    }
}

Each backend instance uses the global setting core.moduleRunCmd to start a Java Virtual Machine (JVM). This setting can be overwirtten for each definiton. In this example a second service locate is defined which starts the xlocate service on a different backend with 512MB memory.

core {
    modules {
        definitions {
            default {
                services = [xmap, xroute]
            }
            locate {
                services = [xlocate]
                moduleRunCmd = "{jre}/bin/java -Dxserver.module={mod} -Xms512M -Xmx512M -Xss16M -cp {cp} -XX:ErrorFile={log}/hs_err_pid%p.log -XX:-CreateMinidumpOnCrash -Dcatalina.base={cbd} -Djava.rmi.server.hostname=localhost -Djava.library.path={lib} -Dxserver.logdirectory={log} -Dlog4j.configurationFile=file:///{cbd}/conf/logging-module.xml {arg} {cls} {xsr} {ins} {prt}"
            }
        }
        instances {
            default = 1
            locate = 1
        }
    }
}

Versioned API and hosting previous versions

Related file: xserver.conf

The PTV xServer has a versioned API. That means that it provides different APIs on different URLs and that with each minor release there will be updated APIs. It is possible to host different versions of the API. The PTV xServer 2.6 is delivered with the configuration

core {
    hostedVersions {
        default : [head, 2.6, experimental]
}

This configuration uses the entry default to specify that for the xRuntime service and all services defined in core.modules.definitions the versions 2.6, head and experimental should be hosted. The sequence of the versions can be in any order. In versions older than 2.6 the configuration of hostedVersions could be empty and the parameters have been changed, respectively. For the configuration of older versions see the documentation of the corresponding version. For the configuration above, the following URLs, for example for the xRoute service, are available:


http://localhost:50000/services/ws/XRoute
http://localhost:50000/services/ws/XRoute/2.6
http://localhost:50000/services/ws/XRoute/experimental

The first URL is a shortcut to the latest version which corresponds to version 2.6 in this case. It is configured with the parameter head. The second URL is a distinct URL which specifically addresses the version 2.6 of the xroute service. It is configured with the parameter 2.6. The last URL provides the experimental API. It is configured with the parameter experimental. For an overview of all available hosted versions open the page Administration -> Services.

If there is no entry core.hostedVersions.default each service defined in core.modules.definitions have to be configured explicitly in core.hostedVersions. Only existing services and xRuntime can be configured.

The availability of older versions is useful for backward compatibility. The default can be overwritten by setting the API version explicitly for a service:

core {
    modules {
        definitions {
            default {
                services = [xlocate, xmap, xroute]
            }
        }
        instances {
            default = 1
        }
    }
    hostedVersions {
        default : [head, 2.6, experimental],
        xlocate : [experimental],
        xmap : [2.5]
    }
}

Now the service xlocate is only delivered in version experimental, whereas xmap is only delivered in version 2.5. The service xRuntime and all other services configured in core.modules.definitions are available in the versions 2.6, head and experimental. This configuration hosts the following service URLs:


http://localhost:50000/services/ws/XLocate/experimental
http://localhost:50000/services/ws/XMap/2.5
http://localhost:50000/services/ws/XRoute
http://localhost:50000/services/ws/XRoute/2.6
http://localhost:50000/services/ws/XRoute/experimental
http://localhost:50000/services/ws/XRuntime
http://localhost:50000/services/ws/XRuntime/2.6
http://localhost:50000/services/ws/XRuntime/experimental

The xRuntime service does not have to be configured in the list of core.modules.definitions because it is necessary for PTV xServer core functionality and therefore always deployed automatically.

It is also possible to specify an interval of versions to be deployed for a service. An interval includes the specified start and end version. Either start or end version can be omitted to create an open interval. Overlapping intervals will be merged. Unavailable versions and invalid values will be ignored and a message is written to xserver.log. Blanks are not allowed.

Consider this example:

core {
    modules {
        definitions {
            default {
                services = [xlocate, xmap, xroute]
            }
        }
        instances {
            default = 1
        }
    }
    hostedVersions {
        default : [head, 2.6, experimental],
        xlocate : [2.2-2.4],
        xmap : [-2.2],
        xroute : [2.4-, experimental]
    }
}

This configuration results in the following URLs being available (for the PTV xServer 2.6):


http://localhost:50000/services/ws/XLocate/2.2
http://localhost:50000/services/ws/XLocate/2.3
http://localhost:50000/services/ws/XLocate/2.4
http://localhost:50000/services/ws/XMap/2.0
http://localhost:50000/services/ws/XMap/2.1
http://localhost:50000/services/ws/XMap/2.2
http://localhost:50000/services/ws/XRoute/2.4
http://localhost:50000/services/ws/XRoute/2.5
http://localhost:50000/services/ws/XRoute/2.6
http://localhost:50000/services/ws/XRoute/experimental
http://localhost:50000/services/ws/XRuntime
http://localhost:50000/services/ws/XRuntime/2.6
http://localhost:50000/services/ws/XRuntime/experimental