TransXChange

Technical FAQ

This page provides various items of technical information to assist TransXChange implementors. It assumes a technical knowledge of XML software.

Information on available technology is provided strictly on an 'as is' basis and without warranty, and no endorsement is intended of any platforms, components or proprietary tools mentioned.

TransXChange Implementors are invited to contribute their experience and information about XML implementation technologies to this page. Please send comments and questions to pti.support@trapezegroup.co.uk.

FAQ Index

Tools
  1. What software tools are available to read and navigate XML Schema?
  2. Can I convert TransXChange data into other formats?
Document Use
  1. How do I check that my TransXChange document is correct?
  2. How do I know which TransXChange schema version to use?
  3. What is the difference between the TransXChange registration schema and the general schema?
  4. Where should the XML schemas reside for my Application?
  5. How do I use TransXChange efficiently to reduce document size?
  6. Can I compress TransXChange Documents?
Publisher - General
  1. Which version of the publisher should I use?
  2. Can I run the TransXChange Publisher from the network?
  3. What is the difference between the desktop version of the publisher version and the EBSR embedded version?.
  4. What are the standard defaults for the publisher?
  5. What are the Prerequisites for using the TransXChange Publisher?
  6. Can I call the TransXChange Publisher from my own Applications?
  7. Can I use the publisher to publish Transxchange documents other than registrations?
  8. Where can I find the Publisher Logs?
Publisher Features
  1. Can I control the column sizes in the matrix timetables produced by the TransXChange Publisher?
  2. Can I control the order in which rows appear in the matrix timetables produced by the TransXChange Publisher?
  3. What coordinate reference system does the TransXChange Publisher use?
  4. Can I publish Flexible Services with the TransXChange Publisher?
Publisher - Trouble shooting
  1. How do I tell which version of the Publisher was used to produce a pdf?
  2. Why when I start the publisher do I sometimes get a "An error occurred while starting the application"?
  3. What do I do if I get an out of heap memory error?
  4. What do I do if I get an out of stack memory error (e.g. as message " Error occurred in RequiredModelMBean while trying to invoke operation publish")?
  5. Can I limit the number of threads the publisher uses for http requests?
  6. What known issues are there with the TransXChange Publisher?

Tools

What tools are available to read and navigate the Schema?

The TransXChange xsd schema files may be viewed as formatted text in a web browser or text editor. There are in addition a wide range of free and proprietary tools available to view and edit XML schemas in graphical editors. TransXChange is a large complex schema and the use of such a tool is strongly recommended, even just to read a schema.

Graphical XML editors

A current list of graphical; XML editors can be found at Open Directory Project. These all include validators. Some are4 shareware some are available under a commercial license.

The following are some popular XML editors that support graphical editing of both XML schemas and XML instance documents. No endorsement is implied by inclusion in this list.

Commercially Licensed tools

Shareware

Back to Index

What tools can I use to read a TransXChange Schema from my own Applications?

TransXChange uses standard XML technologies and can be parsed using off- the-shelf XML validators and parsers. /p>

Please note however, that the TransXChange schema models a complex problem domain, and so requires a relatively large, complex schema that uses XML's features in a fairly sophisticated fashion. It is modularised into smaller sub-schemas for maintainability and reusability; TransXChange is part of a unified set of UK Public Transport standards and it therefore references standard types and elements that are shared with other UK PT and government schemas such as NaPTAN (these are found in the /napt and /apd directories). Separate namespaces are used for various subschema. Keyref constraints, a new feature of XML, are also used, including xpath expressions for elements. It is therefore necessary to use fully featured tools that implement modern XML features to process the schema and instance documents.

  • The schema and the examples have been validated using the following validators
    • Xml Spy 2008 validator
    • Java JAXB validator.
    • Microsoft MSM 4.0 validator.
    • Sun multi-schema validator.
    • The TransXChange Publisher uses the JAVA JAXB bindings and JAXP DOM parser to validate and parse the schema. These were obtained as part of the Java Web Services Developer Pack (which bundles the JAXB and JAXP code, amongst other things), and testing was done on on versions 1.3 and 1.4 2. The Publisher provides an example of complex processing of TransXChange schema and documents using open platform technologies. Java and open source technology for processing XML has been available for some time and the JAXB, JAXP and Xerces tools are all mature technologies with good feature coverage.
    • Some shortcomings have been noted in the support of certain XML features in the Microsoft .net XML parsers, in particular in the support of MS XSD.exe parser for processing schemas imports and multiple namespaces (as of Dec 2005). The following paper provides some useful comparative discussion of issues with MS .dot net. technology. Please note that XML technology continues to develop fast and this will change over time. (A workaround for the xsd.exe shortcoming may possibly be to create an inline copy of the schema).

Back to Index

Can I convert TransXChange documents into other formats?

Yes, a number of suppliers provide tools to migrate legacy formats such as RJIS CIF into TransXChange.

The following tool allows conversion into Google Transit Feed Specification format.

Back to Index


Document Use

How do I check that my TransXChange document is correct?

To be valid a TransXChange document, xml documents must satisfy two levels of validity criteria:

1.Well-formedness and validity: Documents must parse and validate against the corresponding version of the TransXChange schema at the specified level - Registration or General - including all the integrity constraints coded within the schema, such as for key uniqueness and reference. Any document that does not satisfy the XML syntactic rules cannot be processed and will be rejected for Registration with VOSA/ESBR. It is likely also not to be accepted or understood correctly by other users of the General Schema.

2.Correctness: Documents must satisfy additional processing rules and constraints that are not enforceable in the XML of the schema, but which are specified in the TransXChange Schema Guide as named rules. Each rule is assigned a severity and a type: intrinsic (only require internal consistency within the document) or extrinsic (i.e. would require checking against an external database of allowed values).

  • Intrinsic Severity 1 & 2 rules must be satisfied in order register a document with VOSA. Any document that is not correct may be rejected for Registration and may not be accepted or understood correctly in uses on the General Schema.
  • Other applications are free to make their own interpretation of the semantic rules according to their purpose, but it is strongly advised that severity 1 rules are met.

The TransXChange Publisher includes a diagnostic checking function to perform a number of the intrinsic checks and produces a report as part of the published document.

The enhanced publisher available in 2007 allows you to run just the diagnostic report.

Back to Index

How do I know which version of the TransXChange Schema to use?

TransXChange follows a strict versioning scheme so that developers can manage differences in the schemas with each new release, and in particular detect the level of any given instance document so as to support the exchange of documents at different levels from different systems. Change notes are provided with each release of the schema..

  • Once frozen and released, schema versions will not be changed. You should develop against the latest stable release if you want to be sure there will be no further changes.
  • On occasion, preview versions of the schemas under development may be offered -- for informative purposes only -- in advance of being officially released; these will be labelled as work in progress (with a letter suffix on teh version number e.g. 2.2a) and may be changed to add in further modifications without notice. You should not develop against a preview version unless you are prepared to mend breakages due to schema changes as and when they occur.

At any given time teh Publisher will support one or more levels of the schema, e.g. as of Jan 2008 it supports 2.1 and 2.2a. Documents submitted to VOSA for EBSR may be in one of the supported levels.

Back to Index

What is the difference between the TransXChange Registration schema and the General schema?

There are two slightly different versions of the TXC schema: a registration schema, used for submitting Electronic Bus Service Registrations (EBSR) to VOSA, and a general schema that can be used for general purpose exchange of all or part of a timetable. The two variants are almost identical, except that in the EBSR registration version certain fields are mandatory. The general schema in contrast allows TXC to be used to exchange arbitrary subsets of TXC elements, without all the mandatory details required by the registration schema.

A TXC document that conforms to the registration schema will always also conform to the general schema. A document that conforms to the general schema may conform to the registration schema, but is not guaranteed to do so - it may be lacking some mandatory elements in which case it will not.

Documents that conform to either schema may be published with the TXC publisher.

Back to Index

Where should the XML schemas reside for my Application?

You may either:

  1. Reference an online version of the TransXChange schema at http://www.dft.gov.uk/transxchange/ using a URL given by the versioning schema. No guarantee can be given as to the availability or performance of the site providing the URL. Or
  2. Reference your own self-contained copy of the schema extracted from the TransXChange schema zip file. This is the recommended approach for production systems as it removes external dependencies and external scaling constraints on your application.

Please note the following points about schema location references:

  • If you are making a reference to the on-line schemas, you should always use the http://www.dft.gov.uk/transxchange/ domain as the root domain, as this will be the domain used in the long erm, and is the domain used in the TransXChange namespaces. (On mirror sites this URL is sometimes aliased in links to http://dft.gov.uk/transxchange)
  • Each version of the TransXChange Publisher ships its own copy of the TransXChange schema, which it references regardless of any schema named in a document being published. The schema version corresponds to that of the publisher. (This override was added in version 2.0f-2 to overcome difficulties some users had in typing the correct path to their own local copy of the schema.). You should not alter these schema copies or you may break the publisher.
  • If you are using a validation tool such as XML spy to validate your own documents, you still need to ensure that that the path indicated by the schemaLocation parameter points to the correct version of the schema for thedocument. The TransXChange examples provide an illustration of how to reference the on-line schema.
  • Catalogs provide a standard for specify the location of XML schemas to applications - see http://www.oasis-open.org/committees/entity/spec-2001-08-06.html, and for how to use with Java here: http://www.xml.com/pub/a/2004/03/03/catalogs.html. A suitable catalog is supplied with the publisher.

Back to Index

How do I use TransXChange efficiently to reduce the document size?

The TransXChange schema includes a number of mechanisms to reduce the size of instance documents. These are described in detail in the TransXChange Schema Guide. In particular:

  • Many elements may be reused in many different timetables, in particular stops, journey patterns and vehicle journeys and it is important to encode schedules to reference shared definitions, rather than to repeat identical information.
  • Inheritance semantics are used in a number of places to reduce the amount of information that needs to be exchanged. For example within a vehicle journey, only those vehicle timing links that are different from the underlying journey pattern need be specified. Operational dates and periods may also be specified by difference.

Applications that export TransXChange documents should be aware of these mechanisms and in particular (i) encode schedules so as to reference common definitions wherever possible, and (ii) encode schedules by difference wherever appropriate using the the inheritance mechanism described in the TransXChange Schema Guide. This is important not only for reducing document size, but also so that information about common structure is not lost.

Applications that parse and import TransXChange documents need to aware of these mechanisms and in particular (i) re-establish the reuse references when importing documents, and (ii) correctly implement the inheritance rules described in the TransXChange Schema Guide when processing content.

Back to Index

Can I compress TransXChange Documents?

Yes. XML is a verbose representation designed to afford some level of human readability. The TransXChange XML documents may be compressed significantly for storage and/or exchange: the compression process is completely independent and external to TransXChange itself and there are a number of well know open source approaches, such as gzip. See for example. Compression is still a topic of discussion and development, for example, see the W3 working group http://www.w3.org/XML/Binary/.

Back to Index


Publisher

Which version of the TransXChange Publisher should I use?

From time to time new versions of teh publisher are released with new features and fixes. Each version of the publisher has its own version number and supports only a specific version or versions of the schema. Publisher version numbers indicate the latest schema level supported. There may be more than one version of the publisher for a given schema level. For example for TransXChange schema level 2.1, there may be versions 2.1_1, 2.1_2 etc of the Publisher. Publisher versions 2.1_1 and earlier only support a single schema version. If a version of the Publisher does not support the version level of a particular TransXChange it will issue an error.

The publisher is packaged for two separate environments:

  • TXC Publisher for the Desktop, as downloadable from this site. This can be used to publish documents from a PC using a choice of options
  • TXC Publisher for EBSR embedded workflow. This uses the same publishing engine, but invokes it with a fixed set of Publishing options - see below.

Back to Index

Can I run the TransXChange Publisher from the network?

No, the publisher install and run environment is not currently supported for running it from a network. At the moment it should be installed on the desktop of each user. This may be possible be addressed as a future enhancement.

Back to Index

What is the difference between the desktop version of the publisher version and the EBSR embedded version?

The two versions of the publisher use the same publishing engine to read a TXC document, process it and render it as a pdf. The versions differ as follows

  1. Options & Defaults
    • The EBSR version uses a fixed set of Publishing options.
    • The desktop publisher has an addition GUI that allow different output options to be set.
    • Formatting
      • The EBSR version uses different title headings.
      • The EBSR version uses a different background to 'watermark' the officialdocument.

Back to Index

What are the standard defaults for the publisher?

The EBSRversion of the publisher uses a particular set of default values for the output options, as shown in the table below. These are fixed.

The desktop version of the publisher allows different options to be specified, but defaults to a set of initial values. Since version 2.2a_6, these are the same as for the EBSR version. Prior to that they were as shown in the right hand column.



Defaults
Tab Option EBSR Desktop



Current
(after 2.2a_6 +)
Old
up to (2.2a_5)
Main Particulars Basic Basic Full

Timetable Full Full Full

Diagnostic Report Full Full Full

Stop Points PTP PTP All

Merge Similar Frequency Journeys Journeys Yes Yes Yes

Include embedded image Yes Yes Yes
Route Track Map Route Track Full Full None

Scale Auto Auto Auto

Tiling A4 A4 A4

Combine Route Directions No No No

Stop Data Source Web Web Web

Stop Data Source Web Web Web
Advanced Validate XML Yes Yes Yes

Stop Data Source PDF PDF PDF

Back to Index

What are the Prerequisites for the TransXChange Publisher?

The TransXChange publisher runs in a windows environment - see publisher prerequisites.

Note that in order to run the publisher on your machine, you must first have installed the required version of the Java Runtime Environment (JRE) version. as described in the installation instructions. If you do not have the correct version of the JRe you may get an error message when you try to run the publisher such as "An error occurred while starting the application".

To Publish maps, the TransXChange publisher normally needs at least 1024MB of heap memory memory. The memory can be increased - see Publishing

Back to Index

Can I call the Publisher from my own Applications?

Yes. The TransXChange Publisher is can be invoked in three different ways

  1. By using the desktop user interafce component provided this collects and validates the various inopuyt parameters and then calls a publisher service API.
  2. By using a command line procedure which accepts a number of parameters. This incurs an overhead to start the Java environment and process the TransXChange schema every time the Publisher runs. This use is deprecated.
  3. By calling the web service API directly. An XMLma is available tt describe the required parameters.

Back to Index

Can I use the TransXChange Publisher to publish Transxchange documents other than registrations?

Yes, the publisher can be used to publish TXC documents that conform to both the general and the registration schema. However in order to produce a document, sufficient data needs to be present to populate the required elements. It is possible to populate a TXC general schema document very sparsely, say with just operator or route data, in which case the publisher will not produce meaningful results, or in some cases may crash.

Back to Index

Where can I find the TransXChange Publisher Logs?

The Publisher outputs a log to a file as it proceeds. This will incude more detailed messages about any failure, for example an "out of memory" error. The log should be sent when reporting a problem. The logs are located in the ../logs subdirectory of the publisher.

  • ../logs/application.log
  • ../logs/jetty.log

Back to Index

What do I do if I get an out of heap Memory Error: Can I control the amount of heap memory used by the TransXChange Publisher?

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 heap memory. If this is exceeded an "out of memory" error will occur and will be reported in the application log. The actual amount of memory needed depends on the size of the timetable document to be published, and the options selected; additional memory is used to produce a route map, and even more to publish at a large scale. By default, the Java VM heap memory limit is set to a sensible default appropriate for publishing an average sized TransXChange timetable document. However, for large TransXChange documents you may need to increase the memory allocation. If you have additional memory available increasing the heap size can also improve performance. You can increase the available memory simply by editing the appropriate setting in the publish.bat file (for the command line version), or the TransXChangePublisher.l4j.ini file (for the GUI version). These files can be found in the base directory where you unpacked the publisher distribution.

In either file you need to change the setting that begins -Xmx. using 'k' (KB), 'm' (MB) or 'g' (GB) as a suffix to indicate the units. For example, to change the heap from 512MB to 1024MB, edit the relevant line -Xmx512m to change it to be -Xmx1024m. You must exit and restart the publisher for the change to come into effect. If you try to increase the memory beyond what is available on your machine you will get an error emssage when you try to restart the publisher.

If you get an "out of memory" error at startup you should reduce the memory size.

Back to Index

What do I do if I get an out of stack memory error (e.g. "Error occurred in RequiredModelMBean while trying to invoke operation publish" - more information may be found in the application log. )?

This error can be caused by a configuration limit on Java VM stack memory when publishing documents with large numbers of particulars - for example lots of working days. A Java VM can be configured to run in a certain amount of stack memory. By default the Java VM stack 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 setting in the publish.bat file (for the command line version), or the TransXChangePublisher.l4j.ini file (for the GUI version). These files can be found in the config directory where you unpacked the publisher distribution.

In both files you need to add or change the setting that begins -Xss. For example, to change the stack from 256k to 3072k, edit the relevant file and change -Xss256k to -Xss3072k.

If there is no explicit setting add -Xss3072 just before the -Xmx1024m (or other -Xmx value). The file should look like this when done:

# Launch4j runtime config.
# Launch4j runtime config.
# Add any JVM arguments to this file.
# Restrict network connections - useful for debugging catalog resolution issues.
#-Djava.security.manager=com.kizoom.transxchange.parser.RestrictedNetworkAccessSecurityManager
-Dcom.kizoom.transxchange.publisher.config.location=config
-Dcom.kizoom.transxchange.publisher.timetableMatrix.maxTimeColumnsPerPage=14
-Dcom.kizoom.transxchange.publisher.timetableMatrix.maxStopWidthPoints=200.0
-Dcom.kizoom.util.HttpUtil.MaximumConnectionsPerHost=500
# Default Java Stack Max Memory per thread -Xss3072k
-Xss3072k
# Java Heap Initial memory pool: -Xms256m
-Xms256m
# Java Heap Maximum Memory. -Xmx1024m
-Xmx1024m
# Debug options
-Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n

Back to Index

Can I limit the number of threads the publisher uses for http requests?

Yes. To speed up publishing of maps, the publisher will attempt to fetch many map tiles in parallel from the map service.  You may limit the number of requests made at a time using the webservice.maxpreloadthreads value in the bing.properties file. The publisher is shipped with this value set to a sensible default appropriate for an average machine.

webservice.url=http://dev.virtualearth.net/REST/V1/Imagery/Metadata/Road/
webservice.retries=5
# timeout  increased from 5 to 10
webservice.timeout.seconds=10
webservice.images.retries=5
webservice.images.timeout.seconds=10
#  maxpreloadthreads reduced from 100 to 20
 webservice.maxpreloadthreads=10

Back to Index

Can I control the column sizes in the matrix timetables produced by the TransXChange Publisher?

Yes. The publisher has sensible defaults which are appropriate for most timetables. However, for timetables that have very long stop names, it may be desirable to override the settings which control column sizes. The settings are in publish.bat (for the command line version), or TransXChangePublisher.l4j.ini (for the GUI version) in the base directory where you unpacked the publisher distribution.

To control the maximum number of time columns that appear on each page, edit the setting

com.kizoom.transxchange.publisher.timetableMatrix.maxTimeColumnsPerPage

For instance, to change it to be 10, the following should appear in publish.bat and/or TransXChangePublisher.l4j.ini:

-Dcom.kizoom.transxchange.publisher.timetableMatrix.maxTimeColumnsPerPage=10 

To control the maximum width of the stop name column, edit the setting com.kizoom.transxchange.publisher.timetableMatrix.maxStopWidthPoints. For instance, to change it to be 150 points, the following should appear in publish.bat and/or TransXChangePublisher.l4j.ini:

-Dcom.kizoom.transxchange.publisher.timetableMatrix.maxStopWidthPoints=150.0

Can I control the order in which stops appear as rows in the matrix timetables produced by the TransXChange Publisher?

Yes. By default the stops will be listed in the order in which they appear in the journey pattern. Where there are route variants represented by different alternative route sections, the stops will be further grouped within each section.

You can override the default order by specifying a sequenceNumber attribute on the stops of the journey pattern, using the JourneyPatternTimingLink/From and JourneyPatternTimingLink/To StopUsage elements. If any stops of a journey pattern are numbered, all the stops in the journey pattern should be numbered uniquely and monotonically, otherwise unpredictable results may occur.

Back to Index

What coordinate reference system does the TransXChange Publisher use?

For stop point and track point coordinates, a TransXChange document may contain geospatial references in OS Grid Eastings and Northings, WGS84 latitude and longitude, or both.  In Eire  Irish Transverse Mercator (ITM) may be used (+TXC +2.5) When plotting route tracks on maps the Publisher chooses coordinates as follows:

  1. If OS Grid Easting and Northing coordinates are available for a point, it uses them directly
  2. If only WGS84 coordinates are available for a point it converts them to OS Grid using a standard transform.

For the positions of Stop Points on the Route Map, the Publisher normally fetches the stop coordinates from the NaPTAN database which holds them in OS Grid Eastings and Northings.

Back to Index

Can I publish Flexible Services?

The TransXChange publisher currently only provides limited support for flexible services

  • Only the basic service details and stops are shown in the Particulars
  • Flexible route specific details such as timebands not published.
  • Timetable matrix and route track are not supported

To Publish a Flexible route you should use the following options

  • Particulars: Either Full or None
  • Timetable: None
  • Diagnostic: Either Full or None
  • Route Track Map: or None

Back to Index

How do I tell which version of the Publisher was used to produce a pdf?

The version of the publisher used to produce a document is printed at the end of the matrix section of document

See also Publisher Troubleshooting.

Back to Index

Why when I start the publisher do I sometimes get a "An error occurred while starting the application"?

This error can arise in different circumstances:

  • If you start the publisher by clicking on the desktop icon, and then, before the publisher has finished initialisation, click again, this error can appear. Because only a single instance of the desktop publisher is allowed at a time, the second attempt will result in an error.
  • If the prerequisite J2RE components are not present.
  • If you attempt to invoke the publisher indirectly using a mechanism (for example a shortcut link) that does not set required environmental variables such as the path correctly.

See also Publisher Troubleshooting.

Back to Index

What are the known issues with the TransXChange Publisher?

Issues can be categorised into three groups.

  1. Features that cannot yet be supported because the TransXChange schema does not contain the necessary information elements. There is a consultation process for enhancing the TransXChange schema, and also suggesting any necessary concomitant support in the publisher.
  2. Features that are possible using the current schema, but are outside of the TransXChange Publishers' current scope. (For example, the Publisher is intended to support the ESBR registration process and does not include operational data). There is a consultation process for making suggestions to add new features. Please contact us if you have suggestions for adding elements.
  3. Known issues in specific versions of the publisher

See also Publisher Troubleshooting.

Back to Index



Page last updated: 2013/03/30

<