Using xServer with Java

Using the Bundled Clients for the SOAP API

The SOAP API clients can be found in the directory java/soap of the bundle and are standard JAX-WS clients. They can be used with Java 8 and above, but PTV recommends to use either Java 8 or Java 17, as the client classes are tested with these Java versions. If you use Java 11 or above you have to add also the jaxws runtime libraries, as the jax-ws APIs were removed from JDK 11. These runtime jars are also provided in the subdirectory 3rdParty-Java11+. All clients of PTV xServer can be downloaded or can be found in the subdirectory client-bundle of the PTV xServer's installation directory. The clients are backward compatible but we recommend using the client-bundle with the same version as your PTV xServer. For experimental features it is required to use the xserver-client-bundle-<version>.zip with the same version as the PTV xServer.

To start a project, follow these steps:

Step 1

1. Create a new Java project by selecting File -> New -> Java Project.
2. Give your sample a name, for example xRouteSample.

Step 2

1. Click next and switch to the libraries tab.
2. Add the xserver-java-soap-client.jar (or xserver-java-soap-client-experimental.jar) as an external library and click finish.

Step 3

1. Right click on the src directory in your new project and select New -> Class to create your sample class.
2. Give it a package name and a class name and click finish.

Step 4

Enter the following code, which calculates a simple two waypoint A waypoint is a geographic location used to specify start, destination and possible stopovers for a route. route 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.:

Step 5

Run the code by clicking the Run button in the Eclipse toolbar.

You should then see the following output in the console window:

Route distance: 18825.0m

Using the Bundled Clients for the JSON API

The JSON API clients can be found in the directory java/openapi of the bundle. They can be used with Java 8 and above, but PTV Logistics recommends to use either Java 8 or Java 17, as the client classes are tested with these Java versions.

Step 1

As step 1 for the SOAP API.

Step 2

As step 2 for the SOAP API, but add the xserver-java-oas-client.jar or xserver-java-oas-client-experimental.jar as an external library to the project instead.

Step 3

As step 3 for the SOAP API.

Step 4

Enter the following code, which calculates a simple two waypoint route:

Step 5

Run the code by clicking the Run button in the Eclipse toolbar.

You should then see the following output in the console window:

Route distance: 3924.0m.

Using the client-bundle in a Maven project

There are two options to integrate the client bundle provided by the xServer in a Maven project:

Using a multi-module Maven project

To use the xServer client bundle in a multi-module project, add the following configuration to the parent pom of the module you want to use the clients in:

<plugins>
    <plugin>
        <artifactId>maven-antrun-plugin</artifactId>
        <version>{version}</version>
        <executions>
            <execution>
                <id>download and unpack xServer client bundle</id>
                <phase>generate-sources</phase>
                <configuration>
                    <target>
                        <get src="{xServerHost}/dashboard/Content/Resources/xserver-client-bundle/xserver-client-bundle-{clientVersion}.zip"
                            dest="${project.build.directory}/xserver-client-bundle.zip"/>
                        <unzip src="${project.build.directory}/xserver-client-bundle.zip" dest="${project.build.directory}/xserver-client-bundle" />
                    </target>
                </configuration>
                <goals>
                    <goal>run</goal>
                </goals>
            </execution>
        </executions>
    </plugin>
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-install-plugin</artifactId>
        <version>{version}</version>
        <executions>
            <execution>
                <id>install xServer client bundle</id>
                <phase>generate-sources</phase>
                <goals>
                    <goal>install-file</goal>
                </goals>
                <configuration>
                    <groupId>{groupId}</groupId>
                    <artifactId>{artifactId}</artifactId>
                    <version>{version}</version>
                    <packaging>jar</packaging>
                    <file>${project.build.directory}/xserver-client-bundle/java/{path to desired jar file}</file>
                </configuration>
            </execution>
        </executions>
    </plugin>
</plugins>
        

After that add the client bundle as dependency to the child module:

<dependencies>            
    <dependency>
        <groupId>com.ptvgroup</groupId>
        <artifactId>xserver-java-oas-client-experimental</artifactId>
        <version>1.0</version>
    </dependency>
</dependencies>
        

In the child pom disable the steps done in the parent pom if you don't want to repeat them in the child module:

<plugins>
    <plugin>
        <artifactId>maven-antrun-plugin</artifactId>
        <version>1.8</version>
        <executions>
            <execution>
                <id>download and unpack xServer client bundle</id>
                <phase>none</phase>
            </execution>
        </executions>
    </plugin>
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-install-plugin</artifactId>
        <version>2.5</version>
        <executions>
            <execution>
                <id>install xServer client bundle</id>
                <phase>none</phase>
            </execution>
        </executions>
    </plugin>
</plugins>
        

Using a single-module Maven project

To use the xServer client bundle in a single-module project, first download and install the client in your local directory using mvn install:install-file -Dfile=<path-to-file> -DgroupId=<group-id> -DartifactId=<artifact-id> -Dversion=<version> -Dpackaging=<packaging> and add the client as dependency:

<dependencies>            
    <dependency>
        <groupId>com.ptvgroup</groupId>
        <artifactId>xserver-java-oas-client-experimental</artifactId>
        <version>1.0</version>
    </dependency>
</dependencies>
        

Afterwards you can add the steps used in the multi-module to automatically update your client when building your project:

<plugins>
    <plugin>
        <artifactId>maven-antrun-plugin</artifactId>
        <version>1.8</version>
        <executions>
            <execution>
                <id>download and unpack xServer client bundle</id>
                <phase>generate-sources</phase>
                <configuration>
                    <target>
                        <get src="{xServerHost}/dashboard/Content/Resources/xserver-client-bundle/xserver-client-bundle-{clientVersion}.zip"
                            dest="${project.build.directory}/xserver-client-bundle.zip"/>
                        <unzip src="${project.build.directory}/xserver-client-bundle.zip" dest="${project.build.directory}/xserver-client-bundle" />
                    </target>
                </configuration>
                <goals>
                    <goal>run</goal>
                </goals>
            </execution>
        </executions>
    </plugin>
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-install-plugin</artifactId>
        <version>2.5</version>
        <executions>
            <execution>
                <id>install xServer client bundle</id>
                <phase>generate-sources</phase>
                <goals>
                    <goal>install-file</goal>
                </goals>
                <configuration>
                    <groupId>com.ptvgroup</groupId>
                    <artifactId>xserver-java-oas-client-experimental</artifactId>
                    <version>1.0</version>
                    <packaging>jar</packaging>
                    <file>${project.build.directory}/xserver-client-bundle/java/{path to desired jar file}</file>
                </configuration>
            </execution>
        </executions>
    </plugin>
</plugins>
        

Generating Clients for the SOAP API

Generating Clients for the JSON API

The JSON API of PTV xServer provides two different options for generation, WADL or OpenAPI 2.0 documents. While WADL is also supported by soapUI there are a lot of different tools to generate clients from an OpenAPI 2.0 document. In order to improve the quality of client generation the OpenAPI documents contain some vendor extensions. Some important notes regarding the OpenAPI Documents can be found here.

Special handling for Binary Responses for Autorest generated clients

    class ChunkInterceptor implements okhttp3.Interceptor {
        @NotNull
        @Override
        public Response intercept(Chain chain) throws IOException {
            Response response = chain.proceed(chain.request());
            ResponseBody body = response.body();
            if (body != null) {
                body.source().request(Long.MAX_VALUE);
            }
            return response;
        }

    }

    okhttp3.OkHttpClient.Builder builder = new okhttp3.OkHttpClient.Builder();
    builder.addInterceptor(new ChunkInterceptor());
    xServerApi = new XServerImpl("<the baseUrl>", builder, new Retrofit.Builder());