doc: Add design doc to NeTEx the netex import, and move the NetexBund…

…le to root package.
mfdz · Oct 26, 2020 · 56ad7ad · 56ad7ad
1 parent ee05ef3
commit 56ad7ad
Show file tree

Hide file tree

Showing 24 changed files with 285 additions and 61 deletions.
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
@@ -32,6 +32,11 @@ Short introduction to the REST API.
 Used to import GTFS transit data files.
 
 
+### [NeTEx import module](src/main/java/org/opentripplanner/netex/package.md)
+
+Used to import NeTEx transit data files.
+
+
 ### [Raptor transit routing](src/main/java/org/opentripplanner/transit/raptor/package.md)
 
 This is the OTP2 new transit routing engine implemented using the Raptor algorithm. It explains how

diff --git a/src/main/java/org/opentripplanner/netex/DegignOverview.png b/src/main/java/org/opentripplanner/netex/DegignOverview.png
diff --git a/src/main/java/org/opentripplanner/netex/DegignOverview.uxf b/src/main/java/org/opentripplanner/netex/DegignOverview.uxf
@@ -0,0 +1,150 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<diagram program="umlet" version="14.3.0">
+  <zoom_level>10</zoom_level>
+  <element>
+    <id>UMLClass</id>
+    <coordinates>
+      <x>100</x>
+      <y>200</y>
+      <w>100</w>
+      <h>30</h>
+    </coordinates>
+    <panel_attributes>NetexModule
+bg=#b0e0ff
+</panel_attributes>
+    <additional_attributes/>
+  </element>
+  <element>
+    <id>UMLInterface</id>
+    <coordinates>
+      <x>100</x>
+      <y>100</y>
+      <w>100</w>
+      <h>80</h>
+    </coordinates>
+    <panel_attributes>GraphBuilder
+</panel_attributes>
+    <additional_attributes/>
+  </element>
+  <element>
+    <id>Relation</id>
+    <coordinates>
+      <x>140</x>
+      <y>150</y>
+      <w>30</w>
+      <h>70</h>
+    </coordinates>
+    <panel_attributes>lt=&lt;&lt;.</panel_attributes>
+    <additional_attributes>10.0;10.0;10.0;50.0</additional_attributes>
+  </element>
+  <element>
+    <id>UMLClass</id>
+    <coordinates>
+      <x>300</x>
+      <y>200</y>
+      <w>100</w>
+      <h>30</h>
+    </coordinates>
+    <panel_attributes>NetexBundle
+bg=#b0e0ff
+</panel_attributes>
+    <additional_attributes/>
+  </element>
+  <element>
+    <id>Relation</id>
+    <coordinates>
+      <x>190</x>
+      <y>200</y>
+      <w>130</w>
+      <h>40</h>
+    </coordinates>
+    <panel_attributes>lt=&lt;-
+m1=1..n</panel_attributes>
+    <additional_attributes>110.0;10.0;10.0;10.0</additional_attributes>
+  </element>
+  <element>
+    <id>UMLNote</id>
+    <coordinates>
+      <x>500</x>
+      <y>140</y>
+      <w>140</w>
+      <h>40</h>
+    </coordinates>
+    <panel_attributes>Shared file
+/_stops.xml/</panel_attributes>
+    <additional_attributes/>
+  </element>
+  <element>
+    <id>UMLNote</id>
+    <coordinates>
+      <x>550</x>
+      <y>210</y>
+      <w>170</w>
+      <h>40</h>
+    </coordinates>
+    <panel_attributes>Shared Group file
+/_RUT.xml/
+</panel_attributes>
+    <additional_attributes/>
+  </element>
+  <element>
+    <id>UMLNote</id>
+    <coordinates>
+      <x>600</x>
+      <y>280</y>
+      <w>140</w>
+      <h>40</h>
+    </coordinates>
+    <panel_attributes>XML Group file
+/RUT-Line-21.xml/
+</panel_attributes>
+    <additional_attributes/>
+  </element>
+  <element>
+    <id>UMLClass</id>
+    <coordinates>
+      <x>470</x>
+      <y>110</y>
+      <w>290</w>
+      <h>230</h>
+    </coordinates>
+    <panel_attributes>/XML input files/
+</panel_attributes>
+    <additional_attributes/>
+  </element>
+  <element>
+    <id>Relation</id>
+    <coordinates>
+      <x>500</x>
+      <y>170</y>
+      <w>70</w>
+      <h>90</h>
+    </coordinates>
+    <panel_attributes>lt=&lt;-
+m1=*</panel_attributes>
+    <additional_attributes>50.0;60.0;10.0;60.0;10.0;10.0</additional_attributes>
+  </element>
+  <element>
+    <id>Relation</id>
+    <coordinates>
+      <x>390</x>
+      <y>200</y>
+      <w>100</w>
+      <h>30</h>
+    </coordinates>
+    <panel_attributes>lt=&lt;-</panel_attributes>
+    <additional_attributes>80.0;10.0;10.0;10.0</additional_attributes>
+  </element>
+  <element>
+    <id>Relation</id>
+    <coordinates>
+      <x>550</x>
+      <y>240</y>
+      <w>70</w>
+      <h>90</h>
+    </coordinates>
+    <panel_attributes>lt=&lt;-
+m1=*</panel_attributes>
+    <additional_attributes>50.0;60.0;10.0;60.0;10.0;10.0</additional_attributes>
+  </element>
+</diagram>
diff --git a/...tripplanner/netex/loader/NetexBundle.java → ...rg/opentripplanner/netex/NetexBundle.java b/...tripplanner/netex/loader/NetexBundle.java → ...rg/opentripplanner/netex/NetexBundle.java
@@ -1,10 +1,13 @@
-package org.opentripplanner.netex.loader;
+package org.opentripplanner.netex;
 
 import org.opentripplanner.datastore.CompositeDataSource;
 import org.opentripplanner.datastore.DataSource;
 import org.opentripplanner.graph_builder.DataImportIssueStore;
 import org.opentripplanner.model.impl.OtpTransitServiceBuilder;
-import org.opentripplanner.netex.NetexModule;
+import org.opentripplanner.netex.loader.GroupEntries;
+import org.opentripplanner.netex.loader.NetexDataSourceHierarchy;
+import org.opentripplanner.netex.loader.NetexEntityDataIndex;
+import org.opentripplanner.netex.loader.NetexXmlParser;
 import org.opentripplanner.netex.loader.mapping.NetexMapper;
 import org.opentripplanner.netex.loader.parser.NetexDocumentParser;
 import org.opentripplanner.routing.trippattern.Deduplicator;
@@ -18,8 +21,7 @@
 import java.io.IOException;
 import java.util.Deque;
 import java.util.LinkedList;
-
-import static java.util.Collections.singletonList;
+import java.util.List;
 
 /**
  * Loads/reads a NeTEx bundle of a data source(zip file/directory/cloud storage) and maps it into
@@ -36,7 +38,7 @@ public class NetexBundle implements Closeable {
     private static final Logger LOG = LoggerFactory.getLogger(NetexModule.class);
 
     /** stack of NeTEx elements needed to link the input to existing data */
-    private final Deque<NetexImportDataIndex> netexIndex = new LinkedList<>();
+    private final Deque<NetexEntityDataIndex> netexIndex = new LinkedList<>();
 
     private final CompositeDataSource source;
 
@@ -76,7 +78,7 @@ public OtpTransitServiceBuilder loadBundle(
         otpMapper = new NetexMapper(transitBuilder, netexFeedId, deduplicator, issueStore);
 
         // Load data
-        loadZipFileEntries();
+        loadFileEntries();
 
         return transitBuilder;
     }
@@ -91,28 +93,28 @@ public void checkInputs() {
     /* private methods */
 
     /** Load all files entries in the bundle */
-    private void loadZipFileEntries() {
+    private void loadFileEntries() {
 
         // Add a global(this zip file) shared NeTEX DAO
-        netexIndex.addFirst(new NetexImportDataIndex());
+        netexIndex.addFirst(new NetexEntityDataIndex());
 
         // Load global shared files
         loadFilesThenMapToOtpTransitModel("shared file", hierarchy.sharedEntries());
 
         for (GroupEntries group : hierarchy.groups()) {
             LOG.info("reading group {}", group.name());
 
-            newNetexImportDataScope(() -> {
+            scopeInputData(() -> {
                 // Load shared group files
                 loadFilesThenMapToOtpTransitModel(
                         "shared group file",
                         group.sharedEntries()
                 );
 
                 for (DataSource entry : group.independentEntries()) {
-                    newNetexImportDataScope(() -> {
+                    scopeInputData(() -> {
                         // Load each independent file in group
-                        loadFilesThenMapToOtpTransitModel("group file", singletonList(entry));
+                        loadFilesThenMapToOtpTransitModel("group file", List.of(entry));
                     });
                 }
             });
@@ -123,8 +125,8 @@ private void loadZipFileEntries() {
      * make a new index and pushes it on the index stack, before executing the task and
      * at the end pop of the index.
      */
-    private void newNetexImportDataScope(Runnable task) {
-        netexIndex.addFirst(new NetexImportDataIndex(index()));
+    private void scopeInputData(Runnable task) {
+        netexIndex.addFirst(new NetexEntityDataIndex(index()));
         task.run();
         netexIndex.removeFirst();
     }
@@ -144,7 +146,7 @@ private void loadFilesThenMapToOtpTransitModel(String fileDescription, Iterable<
         otpMapper.mapNetexToOtp(index().readOnlyView());
     }
 
-    private NetexImportDataIndex index() {
+    private NetexEntityDataIndex index() {
         return netexIndex.peekFirst();
     }
 

diff --git a/src/main/java/org/opentripplanner/netex/NetexModule.java b/src/main/java/org/opentripplanner/netex/NetexModule.java
@@ -10,7 +10,6 @@
 import org.opentripplanner.model.calendar.CalendarServiceData;
 import org.opentripplanner.model.calendar.ServiceDateInterval;
 import org.opentripplanner.model.impl.OtpTransitServiceBuilder;
-import org.opentripplanner.netex.loader.NetexBundle;
 import org.opentripplanner.routing.graph.Graph;
 import org.opentripplanner.routing.impl.DefaultFareServiceFactory;
 import org.opentripplanner.routing.services.FareServiceFactory;

diff --git a/src/main/java/org/opentripplanner/netex/configure/NetexConfig.java b/src/main/java/org/opentripplanner/netex/configure/NetexConfig.java
@@ -5,7 +5,7 @@
 import org.opentripplanner.datastore.FileType;
 import org.opentripplanner.datastore.file.ZipFileDataSource;
 import org.opentripplanner.netex.NetexModule;
-import org.opentripplanner.netex.loader.NetexBundle;
+import org.opentripplanner.netex.NetexBundle;
 import org.opentripplanner.netex.loader.NetexDataSourceHierarchy;
 import org.opentripplanner.standalone.config.BuildConfig;
 

diff --git a/src/main/java/org/opentripplanner/netex/loader/GroupEntries.java b/src/main/java/org/opentripplanner/netex/loader/GroupEntries.java
@@ -11,7 +11,7 @@
  * with a set of shared group entries and a set of _individual_
  * entries.
  */
-class GroupEntries {
+public class GroupEntries {
     private final String name;
     private final List<DataSource> sharedEntries = new ArrayList<>();
     private final List<DataSource> entries = new ArrayList<>();
@@ -28,15 +28,15 @@ void addSharedEntry(DataSource entry) {
         sharedEntries.add(entry);
     }
 
-    Collection<DataSource> sharedEntries() {
+    public Collection<DataSource> sharedEntries() {
         return sharedEntries;
     }
 
     void addIndependentEntries(DataSource entry) {
         entries.add(entry);
     }
 
-    Collection<DataSource> independentEntries() {
+    public Collection<DataSource> independentEntries() {
         return entries;
     }
 }
diff --git a/src/main/java/org/opentripplanner/netex/loader/NetexDataSourceHierarchy.java b/src/main/java/org/opentripplanner/netex/loader/NetexDataSourceHierarchy.java
@@ -56,15 +56,15 @@ public NetexDataSourceHierarchy prepare(
         return this;
     }
 
-    String description() {
+    public String description() {
         return source.path();
     }
 
-    Iterable<DataSource> sharedEntries() {
+    public Iterable<DataSource> sharedEntries() {
         return sharedEntries;
     }
 
-    Iterable<GroupEntries> groups() {
+    public Iterable<GroupEntries> groups() {
         return groupEntries.values();
     }
 

diff --git a/...er/netex/loader/NetexImportDataIndex.java → ...er/netex/loader/NetexEntityDataIndex.java b/...er/netex/loader/NetexImportDataIndex.java → ...er/netex/loader/NetexEntityDataIndex.java
@@ -64,7 +64,7 @@
  * {@link NetexImportDataIndexReadOnlyView} witch is passed to the mapping code for translation into
  * OTP domain model objects.
  */
-public class NetexImportDataIndex {
+public class NetexEntityDataIndex {
 
     // Indexes to entities
     public final HierarchicalMapById<Authority> authoritiesById;
@@ -111,7 +111,7 @@ public class NetexImportDataIndex {
     /**
      * Create a root node.
      */
-    public NetexImportDataIndex() {
+    public NetexEntityDataIndex() {
         this.authoritiesById = new HierarchicalMapById<>();
         this.dayTypeById = new HierarchicalMapById<>();
         this.dayTypeAssignmentByDayTypeId = new HierarchicalMultimap<>();
@@ -146,7 +146,7 @@ public NetexImportDataIndex() {
      * Create a child node.
      * @param parent can not be <code>null</code>.
      */
-    NetexImportDataIndex(NetexImportDataIndex parent) {
+    public NetexEntityDataIndex(NetexEntityDataIndex parent) {
         this.authoritiesById = new HierarchicalMapById<>(parent.authoritiesById);
         this.dayTypeById = new HierarchicalMapById<>(parent.dayTypeById);
         this.dayTypeAssignmentByDayTypeId = new HierarchicalMultimap<>(parent.dayTypeAssignmentByDayTypeId);

diff --git a/src/main/java/org/opentripplanner/netex/loader/NetexXmlParser.java b/src/main/java/org/opentripplanner/netex/loader/NetexXmlParser.java
@@ -9,18 +9,18 @@
 import java.io.InputStream;
 
 /** Simple wrapper to perform typesafe xml parsing and simple error handling. */
-class NetexXmlParser {
+public class NetexXmlParser {
     /** used to parse the XML. */
     private final Unmarshaller unmarshaller;
 
-    NetexXmlParser() {
+    public NetexXmlParser() {
         this.unmarshaller = createUnmarshaller();
     }
 
     /**
      * Parse an input stream and return the root document type for the given xml file (stream).
      */
-    PublicationDeliveryStructure parseXmlDoc(InputStream stream) throws JAXBException {
+    public PublicationDeliveryStructure parseXmlDoc(InputStream stream) throws JAXBException {
         JAXBElement<PublicationDeliveryStructure> root;
 
         //noinspection unchecked

diff --git a/src/main/java/org/opentripplanner/netex/loader/mapping/NetexMapper.java b/src/main/java/org/opentripplanner/netex/loader/mapping/NetexMapper.java
@@ -15,7 +15,7 @@
 import org.opentripplanner.model.Trip;
 import org.opentripplanner.model.TripPattern;
 import org.opentripplanner.model.impl.OtpTransitServiceBuilder;
-import org.opentripplanner.netex.loader.NetexImportDataIndex;
+import org.opentripplanner.netex.loader.NetexEntityDataIndex;
 import org.opentripplanner.netex.loader.NetexImportDataIndexReadOnlyView;
 import org.opentripplanner.netex.loader.mapping.calendar.CalendarMapper;
 import org.opentripplanner.netex.support.DayTypeRefsToServiceIdAdapter;
@@ -82,7 +82,7 @@ public NetexMapper(
     /**
      * <p>
      * This method mappes the last Netex file imported using the *local* entities in the
-     * hierarchical {@link NetexImportDataIndex}.
+     * hierarchical {@link NetexEntityDataIndex}.
      * </p>
      * <p>
      * Note that the order in which the elements are mapped is important. For example, if a file