Using PTV xServer internet in Java applications (xLocate)

 While xServer internet uses HTTP basic authentication with <user>/<password>, it is highly recommended to work with the token assigned to your subscription using the combination “xtok”/<token>. Using the token is a safer way than using your far more sensible account data.

This sample shows how to access xServer internet with PTV java client packages and uses PTV xLocate for a simple geocoding application. The tutorial assumes that you are using Eclipse. However, if you are familiar with Java, JAR files etc., you should get along with any other environment.

Step 1: Get the PTV Java Client Bundle

PTV provides client packages which encapsulate the WebService access. For this tutorial, you are going to need the xLocate client package and different third-party packages. Enter "xtok" as user and your token as password to access the download.

Download xLocate client package

Step 2: Prepare the Project Dependencies

Unzip the downloaded packages. In the project, we'll add the required JAR files using a classpath variable. Open "Window > Preferences", then navigate to "Java > Build Path > Classpath Variables" and add a variable named "XSERVER_CLIENTS" pointing to the folder containing the extracted client bundle.

Step 3: Create the Sample Project

Create a new project by starting the project wizard, "File > New > Java Project". On the "Create a Java Project" page, name the project "XLocateSample", leave all other settings and press "Next".

On the "Java Settings" page, directly navigate to the "Libraries" tab where we need to add the JAR files required by our project:

  • Call "Add Variable", select "XSERVER_CLIENTS", press "Extend", expand "ptv", select "<xlocate-jar>" and press "OK"
    (depending on the version of the client classes, "<xlocate-jar>" may differ)
  • Call "Add Variable" again, select "XSERVER_CLIENTS", press "Extend", expand "thirdParty", select all jars below that node and press OK.

Finally: Add the Code

Right click the project "XLocateSample" in the package explorer and select "New > Class". Name the class "XLocateSample", leave the package empty and press ok to have the class generated.

Copy the code below into the editor, fully replacing the generated code. Pay attention to the comments in the code!

import com.ptvag.jabba.service.baseservices.CallerContext;
import com.ptvag.jabba.service.baseservices.CallerContextProperty;
import com.ptvag.jabba.service.baseservices.ClientFactory;
import com.ptvag.jabba.service.baseservices.RemoteType;
import com.ptvag.xserver.common.PlainPoint;
import com.ptvag.xserver.xlocate.Address;
import com.ptvag.xserver.xlocate.AddressResponse;
import com.ptvag.xserver.xlocate.ResultAddress;
import com.ptvag.xserver.xlocate.XLocateRemoteInterface;
public class XLocateSample {
    public static void main(String[] args) {
//Create the client, setting username = "xtok", the required token and the url 
        XLocateRemoteInterface client = (XLocateRemoteInterface)ClientFactory.createClient(
            XLocateRemoteInterface.class, RemoteType.DOCSTYLE_CXF,
            "xtok", "<INSERT-YOUR-TOKEN-HERE>",
//Set a caller context switching coordinate format to EPSG:4326 
        CallerContextProperty setCoordFormat = new CallerContextProperty();
        CallerContext cc = new CallerContext();
        cc.setProperties(new CallerContextProperty[] { setCoordFormat });
//Setup the address you want to geocode 
        Address addr = new Address();
        addr.setStreet("Haid-und-Neu-Straße 13");
        try {
//Call the service
            AddressResponse resp = client.findAddress(addr, null, null, null);
// Evaluate response; print results on the console 
            ResultAddress[] resultAddresses = resp.getErrorCode() != 0 ?
                    new ResultAddress[0] : resp.getResultList();
                    System.out.println("found " + resultAddresses.length + " candidate(s)");
                    int n=0;
                    for (ResultAddress resultAddress : resultAddresses) {
                        PlainPoint p = resultAddress.getCoordinates().getPoint();
                        System.out.println("location #" + (++n) + ": x=" + p.getX() + ", y=" + p.getY());
        } catch (Throwable t) {
//handle errors
            System.out.println("failed to geocode address: " + t.getMessage());

The output of this sample should now look like this: