Bundled Clients

Each PTV xServer is delivered with a client bundles ZIP file named as follows:

<name>-client-bundles-<version>.zip (cf.subfolder clients)
name=xlocate, xmap, xmapmatch, xroute, xtour, xdima and xcluster
version=1.18, 1.20 etc.

These files contain all libraries which are necessary for developing Java and .NET clients. The following table describes the folder structure in detail:

Java Clients

Using PTV's java clients, simply include all java libraries in your project. Adding an Eclipse project is described in section "Using PTV xServer with Java". Import the relevant libraries as shown in the next code snippet (PTV xTour Server is exemplarily used):

import com.ptvag.xserver.xtour.*;
import com.ptvag.jabba.service.baseservices.ClientFactory;
import com.ptvag.jabba.service.baseservices.RemoteType;
...	
// create xTour client:
String url = "http://localhost:50090/xtour/ws/XTour";
XTourRemoteInterface client = (XTourRemoteInterface) ClientFactory.createClient(
  XTourRemoteInterface.class, RemoteType.DOCSTYLE_CXF, "", "", "url");

Five arguments have to be added using the method createClient(arg1, ..., arg5) :

1. arg1: The remote interface type to create the corresponding client.
2. arg2: The remote type has to be set either for SOAP (use RemoteType.DOCSTYLE_CXF) or JSON (set RemoteType.REST_JSON).
3. arg3: The user name if authentication is used. Can be empty.
4. arg4: The user password if authentication is used. Can be empty.
5. arg5: Add the service url. Use the URL either for SOAP as http://<your_ip>:50090/xtour/ws/XTour or for JSON as http://<your_ip>:50090/xtour/rs.

After the client has been created the corresponding method (here: planBasicTours( )) can be executed.

Plan plan = client.planBasicTours(arg1, arg2, arg3, arg4, arg5);

Caution: This Java client does not run in the Google App Engine. Google App Engine only supports a subset of the Java standard libraries. In order to build a GAE-compatible client you need to create your own client classes from the WSDL; please follow Google's recommendations.

The entire code sample is available at PTV Cookbook.

.NET Clients

The .NET libraries (DLLs) provide pre-built clients for accessing the PTV xServer SOAP API. Add the provided .NET clients to your project's references as described in section "Using PTV xServer with .NET". Then, create a client which is exemplarily illustrated by using the PTV xTour Server:

using com.ptvag.jabba.clientbase.wsclient;
using com.ptvag.xserver.xtour.wsclient;
...
CClientConfig clientConfig = new CClientConfig("http://localhost:50090/xtour/ws/XTour");
CXTourClient client = new CXTourClient(clientConfig);

These two lines set up a client for the PTV xTour Server. Build your request objects and send the request. The client supports all methods specified in the API documentation. Execute the method as follows:

CPlan plan = client.PlanBasicTours(arg1, arg2, arg3, arg4, arg5);

The entire code sample is available at PTV Cookbook.

JavaScript Clients

Framework agnostic JavaScript clients are bundled with PTV xServer, supporting moderately modern browsers. If you want to support Internet Explorer before version 8, you should include the json2.js script from JSON.org as well to ensure there is a JSON parser and serializer object.

You can load the JavaScript clients from the main entry point, e.g.

<script src="http://mycompany.com:50030/xroute/xroute-client.js"></script>

To setup the JavaScript client, call the constructor in your applications script:

<script>
...
var xRoute = new XRouteClient();
...
</script>

If you call the constructor without arguments, the client code will retrieve the primary end point URL from the script location. You may also provide an argument with the base URL of the server (before the rs/... ). This is useful when you plan to bundle multiple javascript files into one big file and do not want to load scripts from their individual origins, or when you have no browser context. The client will figure out whether a cross domain request will be needed, and will automatically switch to the best available solution (Internet Explorer is as usual very special).

The client object offers functions that handle the complete communication. These functions are named after the XService operations they call. The first arguments of the client functions are the operation parameters from the API, the last argument representing the caller context. You can omit the caller context argument in which case the client will send a preset object. You can access and change that object using the client object attribute callerContext .

Following these arguments you should provide a callback handler that will be called when a reply has arrived from the server. The callback handler is called with three arguments:

1. responseObject - the returned response from the server, as a JavaScript object, or null in case of errors
2. exceptionObject - the returned exception from the server, also modelled as a JavaScript object, or null in case of a success
3. xhr - the XMLHttpRequest object, which you can query for details such as status codes. In case of CORS and Internet Explorer, the object may also be a XDomainRequest object which offers far fewer options.

The function will return immediately with the XMLHttpRequest (or XDomainRequest ) object after the request sending has been triggered. This object could be used to abort the sending or receive more status information, but can usually be ignored.

If you leave out the callback handler, the client object will attempt a synchronous communication and return immediately with a response, or throw an exception object. While looking more convenient, you should abstain from using the synchronous mode as this will lock your user interface.

After the callback handler, you can provide a further optional argument, the timeout . If you set the timeout to a positive value, the request will automatically terminate after at most this amount of milliseconds. This does not stop the server processing, but allows you to react on an overly busy server situation. In case of a client timeout, the callback handler will be called with null values for both response and exception object. You can also provide default timeouts on a per-function basis. To do so, set a timeout property on the function objects themselves:

xLocate.findSuggestion.timeout = 10000;

The client object also offers a setRequestHeader ( fieldName , fieldValue ) function which you can use to set a HTTP request header to be used for every call.

Below is a complete (and yet very short!) example for PTV xLocate Server. It searches for an address in Luxembourg and alerts the city of the first match.

<!DOCTYPE html>
<html>
  <head>
    <script src="http://mylocate.mycompany.com:50020/xlocate-client.js"></script>
    <script type="text/javascript">
    var xLocate = new XLocateClient(),
      addr = { country: "L", city: "Wellenstein", street: "Rue de la Moselle 5" };
    xLocate.findAddress(addr, null, null, null, null, found);
    function found(result, exception, xhr) { alert(result ? result.resultList[0].city :
      exception.errorMessage);
    }
    </script>
  </head>
  <body>
  ...
  </body>
</html>

For each job starter method, there is a corresponding job runner convenience method that handles the complete job transaction. In the easiest form these runners take the same arguments as the starter or their synchronous version. Additional optional parameters control progress updates and retry behavior. Refer to the API documentation or the Code Sample Browser ("Job Runner") for details.

Code samples are available for the PTV xServer at PTV's Code Sample Browser.

Copyright © 2024 PTV Logistics GmbH All rights reserved. | Imprint