Make Timetable immutable

[vpaturet]

Summary

This PR refactors the Timetable class to make it immutable after construction.
The PR introduces a TimetableBuilder.

The builder enforces 2 business rules:

• trip times must be chronologically sorted in the timetable.
• a trip can be added only once in a given timetable.

In addition, the TripTimes sorting logic is removed from the TransitLayerMapper, since this is now redundant.

Implementation notes:
Most of the refactoring consists in deferring the creation of the Timetable and TripPattern instances by accumulating changes in their respective builders.
There are 3 notable difficulties:

1. Since a TripPattern contains a scheduled Timetable that must be created at the same time as the TripPattern itself, the 2 builders (TripPatternBuilder and TimetableBuilder) must be nested.
2. Updating the Timetables instances in the TimetableSnapshot:
   Implementing copy-on-write in TimetableSnapshot induces some extra work, with entities and collections being repeatedly re-created. When profiling this does not seem to impact performance significantly.
3. Importing GTFS trips: GenerateTripPatternsOperation:
   GTFS trips are grouped by direction in a given TripPattern. When using a builder, the direction of a Timetable must be evaluated before the Timetable is built, which adds some complexity.

Issue

No

Unit tests

Added unit tests.
Updated unit tests.

Documentation

No

[codecov]

Codecov Report

Attention: Patch coverage is 93.52941% with 11 lines in your changes missing coverage. Please review.

Project coverage is 69.84%. Comparing base (9c10a0e) to head (e15c3d0).
Report is 22 commits behind head on dev-2.x.

Files with missing lines	Patch %	Lines
...nner/transit/model/network/TripPatternBuilder.java	71.42%	2 Missing and 2 partials ⚠️
...main/java/org/opentripplanner/model/Timetable.java	81.25%	2 Missing and 1 partial ⚠️
...va/org/opentripplanner/model/TimetableBuilder.java	95.23%	1 Missing and 1 partial ⚠️
...tripplanner/transit/model/network/TripPattern.java	75.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@              Coverage Diff              @@
##             dev-2.x    #6017      +/-   ##
=============================================
+ Coverage      69.82%   69.84%   +0.02%     
- Complexity     17419    17451      +32     
=============================================
  Files           1974     1975       +1     
  Lines          74545    74600      +55     
  Branches        7633     7634       +1     
=============================================
+ Hits           52048    52106      +58     
+ Misses         19847    19843       -4     
- Partials        2650     2651       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[vpaturet]

As detailed in #6067, changing the order in which GTFS trips are imported changes the results of the speed test. This is most likely the reason why the speed test fails in this PR: while the order Trips are iterated over is the same, the order in which TripPatterns are built is different.

Investigating and fixing this issue is not in the scope of this PR, but we should at least make sure that test results are stable/reproducible.
This is implemented in the commit 16c8264 by ensuring that TripPatterns are built in the same order that Trips are imported.

@t2gran

[leonardehrenfried]

Thanks for the call where you explained the PR. I will give this a second review once @t2gran's issued have been resolve.

Also, there are merge conflicts.

[vpaturet]

Oops, this PR should have been tagged with Bump serialization id.
Not because a class structure has been changed, but because the sorting of trip times is now expected to be done at graph building time.
Any previously built graph stores the serialized TripTimes in an arbitrary order and will fail this precondition:

OpenTripPlanner/src/main/java/org/opentripplanner/routing/algorithm/raptoradapter/transit/TripPatternForDate.java

Line 96 in a3d0e67

// These depend on the tripTimes array being sorted