Server-side Scripting

Introduction

PTV xServer supports server-sided scripting for all primary functions.

Server-sided scripting allows developers to add or modify behavior. Example use cases are:

  • overriding specific default parameters

  • adding additional information to responses

  • adding billing information

  • access third party systems and enhance response with additional data

  • disable single operations or fields by throwing an exception

Installation Guide

To set up a script,

  1. in folder conf create a subfolder scripts,

  2. within the scripts folder, create a file modulename.groovy (case-sensitive, e.g. xtour.groovy) - this script will be automatically called by the module,

  3. for development, enable separate script logging by activating the RollingFile Appender ScriptingLog and the logger com.ptvgroup.xserver.runtime.ScriptingLogger in conf/logging.xml.

Programming Guide

Scripts must be written in Groovy. To write a script,

  1. add needed imports and extend the adapter class corresponding to the module (e.g. XLocateAdapter),

  2. overwrite operations you want to modify:

    • modify input parameters as needed,

    • call the super operation, unless you want to replace the implementation altogether,

    • modify the response as needed,

    • you can call the log object to log into a dedicated scripting log as needed,

    • add billing information with the method addBillingInformationUseCase()

    • return response, or throw exception

  3. start PTV xServer and send requests,

  4. if it does not work as expected have a look at the log file ${sys:xserver.logdirectory}/scripting.log for compile or runtime errors,

  5. the script can be changed on the fly without restarting the server.

Scripts are executed within module processes and have no access to server functionality. Therefore, jobs cannot be modified directly but as they call the synchronous version internally they inherit all scripting modifications of their synchronous counterpart.

Example Script

Here is a simple example for xlocate which calls the super operation and then adds an extra result entry:

import com.ptvgroup.xserver.xlocate.*;
import com.ptvgroup.xserver.exceptions.XServerException;

   public class XLocateGroovy extends XLocateModuleAdapter {

      public LocationsResponse searchLocations(SearchLocationsRequest request) throws XServerException {
		 log.info("Scripting call!")
		 LocationsResponse response = super.searchLocations(request);
		 SearchLocationsResult searchResult = new SearchLocationsResult();
		 Location location = new Location();
		 Address address = new Address();
		 address.setCity("My City");
		 address.setCountry("My Country");
		 address.setHouseNumber("23");
		 address.setPostalCode("12345");
		 location.setAddress(address);
		 searchResult.setLocation(location);
		 response.getResults().add(searchResult);
		 return response;
      }
}