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>",
            "https://xlocate-eu-n-test.cloud.ptvgroup.com/xlocate/ws/XLocate"
        );
  
//Set a caller context switching coordinate format to EPSG:4326 
  
        CallerContextProperty setCoordFormat = new CallerContextProperty();
  
        setCoordFormat.setKey("CoordFormat");
        setCoordFormat.setValue("OG_GEODECIMAL");
  
        CallerContext cc = new CallerContext();
  
        cc.setProperties(new CallerContextProperty[] { setCoordFormat });
  
        client.setCallerContext(cc);
  
//Setup the address you want to geocode 
  
        Address addr = new Address();
  
        addr.setCountry("D");
        addr.setPostCode("76131");
        addr.setCity("Karlsruhe");
        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: