TransXChange

Troubleshooting

This page gives some guidance on resolving problems with running the TransXChange Publisher.

Problems launching the publisher

If the publisher will not start (from the GUI or command line), then check that you don't have another window with the publisher running in it. Only one instance of the publisher may run at any one time.

You must also ensure that you have the required version of the Java Jun time installed (e.g. Version 6.2 for publisher 2.4_2)

Back to index

Possible causes of publishing problems

Documents may fail to publish for several different reasons:

  • The XML of the TransXChange document is invalid, causing a failure of the initial document validation step.
  • The XML of the TransXChange document is of a version level not supported by the publisher.
  • There are problems accessing on-line web services. (This Applies to Enhanced Publisher .2a_1 and later only).
  • The publisher Java environment is not configured with enough memory. See out of memory errors.
  • There is a bug in the publisher. See reporting issues below.

Errors are written to a log file, and displayed in the output window. The log file can be found in the logs directory.

Back to index

Common Publisher Error Messages & Remedies

Error Cause Remedy
Invalid request. Cannot find input document: ... No such TransXChange input document. Correct the name or location of the TransXChange input document and try again.
Invalid request. Cannot find output directory: ... The output directory specified does not exist. Create the out directory (e.g. using Windows Explorer) and try again.
The process cannot access the file because it is being used by another process. An output document already exists with the same name and is in use. Close PDF document (from Adobe Acrobat) and try again.
Version not supported The version of the schema is not supported by this version of the publisher Use a version of the publisher that does support version level, or update the document to the next level.
Only the timetable section can be published in HTML format. Invalid combination of publisher options. Change selection values - specify None for all sections except the timetable, and try again.
Error while parsing document. Invalid XML input document - does not conform to TransXChange XML schema. Correct errors reported and resubmit. You might find it convenient to use an XML validation tool to find and correct errors more efficiently. See the Technical FAQ.
Options not available. NaPTAN web service not available. This may be due to problems in on-line access or to the availability of the web service. See below.

Back to index

Firewall  Settings & How to tell if the web services are available?

The Route Map options of the enhanced publisher require the use of a broadband internet connection and the availability of two separate on-line web services to fetch stop and map data. If you have a firwall that restricts access to certain sites then you need to ensure that it is configured to permit requests to the necesary domains.

  • NaPTAN Stop service If you have specified that stop data should be retrieved from the NaPTAN web service and the stop data service is completely unavailable, you cannot print a route map. In this case the publisher will fail early with the error message "Could not get NaPTAN stop data response from web service". Note: If you have provided stop coordinates for all stops in the document itself (using full stop declarations in the 2.1 schema, and/or annotated coordinates in the 2.2x schema) you can still produce a route map even if the stop service is not available. Specify 'TransXChange Document' for the Stop data option on the Route map tab in the GUI. This will stop the publisher from attempting to use the Naptan web service.
  • Map image service: If you have specified map data should be retrieved from the map web service and the map service is completely unavailable, you cannot print a route map with a map image background. If this case the publisher will again fail early with the error message "Got response code x from: y" Note: Even if the map service is not available, it is still possible to produce a schematic route map without a map background. Specify 'None' for the Map data option on the Route map tab. This will stop the publisher from attempting to use the map web service.

Back to index

How to change the web service settings

1. Web service Configuration files

Some properties of the web services are configurable in the TransXchange Publisher application. There are separate configuration files for each web service. The web services  are located in the config subdirectory of the publisher folders and are:

  • Stop data: ../config/naptan.properties
  • Map tiles:
    • Publisher v2_4.0 and earlier : DEPRECATED ../config/multimap.properties
    • Publisher v2_4_1 and later : ../config/bing.properties

These files allow you to change the URL of the web service and also the number of retries attempted and the timeout period of the connection. The settings should not be changed unadvisedly.

Back to index

2. Proxy Settings (nt credentials)

If you need to access external services via a secure proxy, then it is possible to configure the proxy access.

To get the publisher to use a named proxy host, add the following lines to the TransXChangePublisher.l4j.ini file in the root of the publisher directory, specifying the appropriate proxy settings:

-Dhttp.proxyHost=proxyHostName
-Dhttp.proxyPort=portNumber

Back to index

Setting Explicit proxy settings with ntCredentials

The user must be authorised to the proxy. This may be done explicitly using the ntCredentials file (see below) . However you do not need to need to configure the ntCredentials file if the application is run under a Windows session where the logged on user has access to the internet via the specified proxy. As the application is run under a Windows session then the application process assumes the identity of that user.

If you need to configure individual process access settings, then it is possible to do so using the following file:

  • ntCredentials.properties

Within this file are four values:

  1. userName - The user name. This should not include the domain to authenticate with. For example: "user" is correct whereas "DOMAIN\\user" is not.
  2. password - The password.
  3. host - The host the authentication request is originating from. The computer name for the client machine.
  4. domain - The domain within which to authenticate.

Back to index

Location of configuration files

The TransXChange publisher has six configuration files, all located in the ../config subdirectory of the publisher folders.

  1. application.properties ; application  settings
  2. ntCredentials.properties ; proxy settings
  3. log4j.properties ; log4j files properties : Memory and heap settings
  4. multimap.properties ; web service settings (Deprecated): URL and timeout values for Publisher v2.4_0 and earlier
  5. bing.properties ; web service settings : URL and timeout values for Publisher v2.4_1 and later
  6. naptan.properties ; naptan web service

The configuration files can be moved to a different place if this is more convenient. Their location should be specified with the system property in the TransXChangePublisher.l4j.ini file located in the root of the publisher directory:

  • com.kizoom.transxchange.publisher.config.location

Back to index

What happens if there isn't enough memory?

The publisher is a portable application that runs on the Java Virtual Machine (VM). A Java VM can be configured to run in a certain amount of memory. If this is exceeded an "out of memory" error will occur. By default the Java VM memory limit is set to a sensible default appropriate for most timetables. However, for large TransXChange documents you may need to increase this allocation. You can do this simply by editing the configuration settings - see out of memory errors.

Back to index

What happens if some of the on-line data is missing?

The publisher will typically use the web services to fetch a number of different items of data (i.e. stops and map tiles). This means there may be modes of partial failure if the publisher is able to fetch some but not all of the required data:

  • Stop Data: If the NaPTAN web service cannot resolve all the stop data because the stops are not yet in the central NaPTAN database, the publisher will continue to produce output: it will draw on the map any stops for which it has location information, and mark in the route map stop index table any stops that it cannot plot. In this case the NaPTAN web service will also return a warning message which appears as a warning in the result pane of teh publisher GUI.
    • To resolve missing stop coordinates you must either arrange to get the NaPTAN definition submitted - see www.dft.gov.uk/naptan/, or include a full definition of the stop in the TransXChange document to be published using the StopPoint or AnnotatedStopRef tags.
  • Map data If the publisher is able to retrieve the metadata about map tiles, but not all the map image themselves, the publisher will draw the map, filling in the background for just the areas for which it has received images. This may result in some blank sections of map in the resulting document. The publisher will produce the warning "Did not successfully retrieve x out of y map tile images."
    • This may occur either if the map service is busy or there is insufficient bandwidth to download the tiles fast enough, so that the publisher times out. A longer time out period may be set using the configuration settings.

Back to index

What happens if the map service is running slowly?

The publisher uses the map web services to fetch map tiles if route map options are selected. If the map service is running very slowly this can cause timeouts and exceptions.

  • The values for timeouts on requests and the number of retries to attempt can be increased in the the bing.properties file.

Back to index

How to report publisher issues

If you think the problem is due to a bug in the publisher you can report it to TransXChange support . When reporting bugs please always include the following.

  1. The TransXChange XML document causing the publishing error.
  2. Any options you are using to publish the document, such as route map, etc
  3. The publisher version number. (See the About option on the Publisher  Desktop GUI.
  4. All log files from the publisher's logs directory.
  5. Any contents of the GUI output console, or any output from the command line.
  6. Any related information that may help.

Please check against the Technical FAQ and the known issues for the version of the publisher you are using before submitting a report. There may already be a workaround.

Back to index

Page last updated: 2012/04/27

UKGovTalk logo