Technical Concepts > About Scripting Support

About Scripting Support

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

Benefits

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

overriding specific default parameters
adding additional information to responses
adding billing informations
access third party systems and enhance response with additional data
disable single methods or parameters by throwing an exception

Prerequisites

You need PTV xServer 1.18 or newer to use scripting.
Scripting is only supported for on premise or private cloud solutions.
For the time being PTV xServer supports Groovy as scripting language.

Installation Guide

To set up a script,

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

for development, enable script logging by uncommenting the following block in conf/module-logging.properties

#logger.ScriptingLogger.name=com.ptvgroup.xserver.framework.ScriptingLogger
#logger.ScriptingLogger.level=error
#logger.ScriptingLogger.additivity=false
#logger.ScriptingLogger.appenderRef.SCRIPTINGLOGGER.ref=SCRIPTINGLOGGER
#appender.SCRIPTINGLOGGER.type=File
#appender.SCRIPTINGLOGGER.name=SCRIPTINGLOGGER
#appender.SCRIPTINGLOGGER.fileName=${sys:xserver.logdirectory}/${sys:xserver}-scripting.log
#appender.SCRIPTINGLOGGER.layout.type=PatternLayout
#appender.SCRIPTINGLOGGER.layout.pattern=%d;%p;%c;%m%n

Programming Guide

To write a script,

add needed imports and extend the adapter class corresponding to the module (e.g. XTourAdapter),
overwrite methods you want to modify:
- modify input parameters as needed,
- call super method, unless you want to replace the implementation altogether,
- modify response object 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
start PTV xServer and send requests,
if it does not work as expected have a look at the log file logs/scripting.log for compile or runtime errors,
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 Scripts

Here are simple examples for PTV xServer that can be extended and adapted for your particular needs.

The following script forbids the use of an operation:

import com.ptvag.xserver.common.*
import com.ptvag.xserver.xtour.*
import com.ptvag.jabba.service.baseservices.CallerContext

public class XTourGroovy extends XTourAdapter {
  public Plan planOvernightTours(TransportOrder[] orders, Depot[] depots, Vehicle vehicle,
    OvernightParams params, Plan plan, CallerContext context) {
     log.info("planOvernightTours is not available on this machine.")
     throw new XServiceException("This method is not available!")
   }
}

The next example shows how to modify an xLocate response. The script removes result entries if their totalScore is below a minimum value. The minimumScore can be specified as an additional parameter within the CallerContext:

import com.ptvag.xserver.xlocate.*
import com.ptvag.jabba.service.baseservices.*

public class XLocateGroovy extends XLocateAdapter {
  public AddressResponse findAddress(Address addr, SearchOptionBase[] options, 
    SortOption[] sorting, ResultField[] additionalFields, CallerContext callerContext) {
    CallerContextProperty minScoreProperty = 
      callerContext.getCallerContextProperty("minimumScore")
    int minimumScore = 50
    if (minScoreProperty != null) {
      minimumScore = Integer.valueOf(minScoreProperty.value)
    }
    log.debug("Call super findAddress")
    AddressResponse result = 
      super.findAddress(addr, options, sorting, additionalFields, callerContext)
    ArrayList newResultList = new ArrayList()
    for (ResultAddress address : result.resultList) {
      if (address.totalScore <  minimumScore) {
        log.debug("Removing element with score " + address.totalScore)
      } else {
        newResultList.add(address)
      }
    }
    result.resultList = newResultList
    addBillingInformationUseCase("minimumScore")
    return result
  }
}