Entur Tiamat overview - A developer's perspective

General

Tiamat is a backend for Stop Place Register used nationally in Norway.

• License: EUPL-1.2 with modifications

Dependent libraries

• Spring Boot (web framework)
• PostgreSQL/PostGIS
• HikariCP (JDBC connection pool)
• Hibernate (ORM)
• Hibernate-Spatial (spatial extension)
• Flyway (database migrations)
• GraphQL (web API)
• In-memory H2 with GeoDB extension used in testing

The current version of Entur Tiamat has numerous dependencies with critical vulnerabilities. They should be updated before it is possible to use Tiamat.

How to run Tiamat

• A couple of SNAPSHOT versions of other Entur libraries needs to be first installed into local Maven repository
  • netex-java-model
    • Downloads the NeTEx-XML XSD files from https://github.com/entur/NeTEx and generates java model using JAXB.
  • Entur superpom
  • Rutebanken-helpers
• Currently (11.2.2021), GeoTools repository needs to be manually added to pom.xml in order to download GeoTools libraries

Problems running Tiamat

The H2 database used for local testing is incompatible with the migrations used and is not possible to be used. A proper postgresql database is needed for local testing.

An EntityChangedListener should be manually created, since the ones defined ones do not run in a local environment.

Data model

Data model consists of JPA/Hibernate entities. JPA entity structure follows closely NeTEx entity structure generated by netex-java-model project.

Main entity types

Below is a list of main entity types that are processed in Spring-managed services. Entity type descriptions in this section are primarily taken and summarized from NeTEx documentation and from Entur's Stops handbook

• Site
  • An abstract type describing a place. May be a well known place to which passengers may refer to indicate the origin or destination of a trip.
• StopPlace
  • Represents a physical stop or station. A place comprising one or more locations where vehicles may stop and where passengers may board or leave vehicles or prepare their trip.
• Quay
  • A place such as platform within StopPlace where passengers have direct access to a vehicle.
• AccessSpace
  • A passenger area within a StopPlace such as a concourse or booking hall, immigration hall or security area that is accessible by passenger, but without a direct access to vehicles.
• PointOfInterest
  • A well known attraction such as museum, stadium, park, venue, etc.
• PathLink
  • The possible paths for passengers between points of an interchange are represented as PathLinks. E.g. Quays and AccessPlaces can be connected to each other using PathLinks. PathLinks are intended to describe a detailed topology for a station.
• PathLinkEnd
  • Beginning or end point (Site) for a PathLink
• NavigationPath
  • Designated path between two places. NavigationPath has a single direction from origin to destination. Sequences of PathLink can be assembled into named NavigationPath to guide the user through a site. The same PathLink may be reused in many different NavigationPaths.
• Parking
  • Designated locations for leaving vehicles such as cars, motorcycles or bicycles (e.g. a car park of 50 places).
• TopographicPlace
  • An abstract data type for geospatial settlement or inhabited areas, such as city, rural area or suburb.
• TariffZone
  • A zone used to define a zonal fare structure in a zone-counting or zone-matrix system.

Entity identification

• 64-bit integers (Long)
• Additionally a separate string-form NeTEx ID is maintained (e.g. "NSR:StopPlace:123")
  • Coordination in assigning IDs is done with Hazelcast between different backend server nodes

Entity versioning

• Each version has an ID which is a 64-bit integer
• Each version has validBetween property: fromDate -> toDate. The validity periods of different versions of same entity are non-overlapping.
• Old version to be terminated is set to end 1 ms before a new version's validity period begins
• Change history modeling
  • created: java.time.Instant
  • changed: java.time.Instant

Deployment

• CircleCI
• Terraform scripts for GCP setup

Functionality

The functionality of Tiamat is pretty well described on the front page of the Github project. Below is a short list of some of them:

• NeTEx import
• NeTEx export (Sync/Async)
• Versioning of stop places
• Merging of stop places
• Diffing of stop places

• Tiamat supports looking up and populating references to tariff zones and topographic places from polygon matches when saving a stop place.