From 51b769e7d9fa61e017e551ec2592724eaf48f2c6 Mon Sep 17 00:00:00 2001 From: MAMBILA TETE jean philipp <@mambilat> Date: Sat, 6 Apr 2024 10:23:26 +0200 Subject: [PATCH] more javadoc --- src/main/java/fr/u_paris/gla/project/App.java | 2 +- .../gla/project/idfm/CSVStreamProvider.java | 69 +++++++++++++++++-- .../idfm/CSVStreamSchedulesProvider.java | 3 + .../project/idfm/IDFMNetworkExtractor.java | 66 +++++++++++++++++- .../u_paris/gla/project/io/NetworkFormat.java | 14 +++- .../gla/project/io/ScheduleFormat.java | 8 +++ .../u_paris/gla/project/utils/CSVTools.java | 10 +++ 7 files changed, 160 insertions(+), 12 deletions(-) diff --git a/src/main/java/fr/u_paris/gla/project/App.java b/src/main/java/fr/u_paris/gla/project/App.java index 47d9a85..9441ed7 100644 --- a/src/main/java/fr/u_paris/gla/project/App.java +++ b/src/main/java/fr/u_paris/gla/project/App.java @@ -63,7 +63,7 @@ public class App { } } - /** @param out */ + /** @param out the output stream */ public static void printAppInfos(PrintStream out) { Properties props = new Properties(); try (InputStream is = App.class.getResourceAsStream("application.properties")) { //$NON-NLS-1$ diff --git a/src/main/java/fr/u_paris/gla/project/idfm/CSVStreamProvider.java b/src/main/java/fr/u_paris/gla/project/idfm/CSVStreamProvider.java index 37f8202..136584b 100644 --- a/src/main/java/fr/u_paris/gla/project/idfm/CSVStreamProvider.java +++ b/src/main/java/fr/u_paris/gla/project/idfm/CSVStreamProvider.java @@ -18,9 +18,18 @@ import java.util.Set; import fr.u_paris.gla.project.io.NetworkFormat; import fr.u_paris.gla.project.utils.GPS; +/** + * CSV Stream Provider class + */ public final class CSVStreamProvider { + /** + * Formatter from numbers into GPS Coordinates + */ private static final NumberFormat GPS_FORMATTER = NetworkFormat .getGPSFormatter(); + /** + * Formatter from numbers into MM:SS + */ private static final NumberFormat MINUTES_SECOND_FORMATTER = NumberFormat .getInstance(Locale.ENGLISH); static { @@ -28,6 +37,9 @@ public final class CSVStreamProvider { } /** Number of seconds in a minute. */ private static final int SECONDS_IN_MINUTES = 60; + /** + * Number of seconds in an hour + */ private static final long SECONDS_IN_HOURS = 3_600; // Magically chosen values /** Maximal speed in km/h */ @@ -35,25 +47,59 @@ public final class CSVStreamProvider { /** Distance to reach maximal speed in km */ private static final double TWO_ACCELERATION_DISTANCE = 0.2; + /** + * Current CSV Line + */ private String[] line = new String[NetworkFormat.NUMBER_COLUMNS]; + /** + * Current CSV transport line iterator + */ private Iterator currentTrace; + /** + * Current Stop path iterator + */ private Iterator> currentPath = Collections.emptyIterator(); + /** + * current iterator for the begin of the line + */ private Iterator currentSegmentStart = Collections.emptyIterator(); + /** + * current iterator for the end of the line + */ private Iterator currentSegmentEnd = Collections.emptyIterator(); + /** + * HashMap of the current line's segments + */ Map> lineSegments = new HashMap<>(); + /** + * current begin of line + */ private StopEntry start = null; + /** + * current end of line + */ private StopEntry end = null; + /** + * csv stream iterator checker + */ private boolean hasNext = false; + /** + * tells if we're already on the next + */ private boolean onNext = false; - /** Create the stream provider */ + /** Create the stream provider + * @param traces an iterator of the possible traces */ public CSVStreamProvider(Iterator traces) { this.currentTrace = traces; } + /** Method that tells if we have segments or paths to go through + * @return if there are next elements or not + */ public boolean hasNext() { if (!this.onNext) { skipToNext(); @@ -61,6 +107,9 @@ public final class CSVStreamProvider { return this.hasNext; } + /** + * Skip to either the next segment or the next path + */ private void skipToNext() { if (this.onNext) { return; @@ -76,6 +125,9 @@ public final class CSVStreamProvider { } } + /** + * Skips to the next segment + */ private void skipToNextNewSegment() { do { this.start = this.currentSegmentStart.next(); @@ -115,6 +167,9 @@ public final class CSVStreamProvider { } while (currentSegmentStart == null); } + /** Store current trace' data as a String array + * @return The newly generated line of text + */ public String[] next() { if (!this.onNext) { skipToNext(); @@ -135,9 +190,10 @@ public final class CSVStreamProvider { return Arrays.copyOf(this.line, this.line.length); } - /** @param stop1 - * @param nextLine - * @param i */ + /** creates adds a station into the next line String + * @param stop the stop + * @param nextLine the next line + * @param index the stop index in the next line */ private static void fillStation(StopEntry stop, String[] nextLine, int index) { nextLine[index] = stop.lname; nextLine[index + 1] = MessageFormat.format("{0}, {1}", //$NON-NLS-1$ @@ -146,8 +202,9 @@ public final class CSVStreamProvider { } - /** @param distanceToTime - * @return */ + /** turns a number into a formatted time string + * @param time the time value + * @return the time as a String */ private static String formatTime(long time) { return MessageFormat.format("{0}:{1}", //$NON-NLS-1$ MINUTES_SECOND_FORMATTER.format(time / SECONDS_IN_MINUTES), MINUTES_SECOND_FORMATTER.format(time % SECONDS_IN_MINUTES)); diff --git a/src/main/java/fr/u_paris/gla/project/idfm/CSVStreamSchedulesProvider.java b/src/main/java/fr/u_paris/gla/project/idfm/CSVStreamSchedulesProvider.java index d45493a..03e63d1 100644 --- a/src/main/java/fr/u_paris/gla/project/idfm/CSVStreamSchedulesProvider.java +++ b/src/main/java/fr/u_paris/gla/project/idfm/CSVStreamSchedulesProvider.java @@ -13,6 +13,9 @@ import java.util.Locale; import java.util.Map; import java.util.Set; +/** + * the CSV Stream Provider (for the Schedules) + */ public class CSVStreamSchedulesProvider { private static final NumberFormat MINUTES_SECOND_FORMATTER = NumberFormat .getInstance(Locale.ENGLISH); diff --git a/src/main/java/fr/u_paris/gla/project/idfm/IDFMNetworkExtractor.java b/src/main/java/fr/u_paris/gla/project/idfm/IDFMNetworkExtractor.java index c8c2e2e..3ab49fe 100644 --- a/src/main/java/fr/u_paris/gla/project/idfm/IDFMNetworkExtractor.java +++ b/src/main/java/fr/u_paris/gla/project/idfm/IDFMNetworkExtractor.java @@ -34,34 +34,67 @@ public class IDFMNetworkExtractor { private static final Logger LOGGER = Logger .getLogger(IDFMNetworkExtractor.class.getName()); + /** + * the URL of the Trace CSV + */ // IDF mobilite API URLs private static final String TRACE_FILE_URL = "https://data.iledefrance-mobilites.fr/api/explore/v2.1/catalog/datasets/traces-des-lignes-de-transport-en-commun-idfm/exports/csv?lang=fr&timezone=Europe%2FBerlin&use_labels=true&delimiter=%3B"; + /** + * The URL of the Stops CSV + */ private static final String STOPS_FILE_URL = "https://data.iledefrance-mobilites.fr/api/explore/v2.1/catalog/datasets/arrets-lignes/exports/csv?lang=fr&timezone=Europe%2FBerlin&use_labels=true&delimiter=%3B"; + /** + * the index in the CSV of a Trace's ID + */ // IDF mobilite csv formats private static final int IDFM_TRACE_ID_INDEX = 0; + /** + * the index in the CSV of a Trace's Name + */ private static final int IDFM_TRACE_SNAME_INDEX = 1; + /** + * the index in the CSV of a Trace's shape + */ private static final int IDFM_TRACE_SHAPE_INDEX = 6; + /** + * The index in the CSV of the Stops' id + */ private static final int IDFM_STOPS_RID_INDEX = 0; + /** + * The index in the CSV of the Stops' schedules + */ private static final int IDFM_STOPS_SCHEDULES_INDEX = 3; + /** + * The index in the CSV of the Stops' names + */ private static final int IDFM_STOPS_NAME_INDEX = 5; + /** + * The index in the CSV of the Stops' longitude + */ private static final int IDFM_STOPS_LON_INDEX = 6; + /** + * The index in the CSV of the Stops' latitude + */ private static final int IDFM_STOPS_LAT_INDEX = 7; // Magically chosen values /** A number of stops on each line */ private static final int GUESS_STOPS_BY_LINE = 5; + /** + * The quarter of a kilometer as a static value + */ // Well named constants private static final double QUARTER_KILOMETER = .25; /** - * Main entry point for the extractor of IDF mobilite data into a network as + * Main entry point for the extractor of IDF mobilité data into a network as * defined by this application. * * @param args - * the arguments (expected one for the destination file) + * the arguments (expected one for the destination file) */ public static void main(String[] args) { @@ -115,6 +148,9 @@ public class IDFMNetworkExtractor { } } + /** Clean the traces/remove the unresolved lines + * @param traces the traces to clean + */ private static void cleanTraces(Map traces) { Set toRemove = new HashSet<>(); for (Entry traceEntry : traces.entrySet()) { @@ -131,7 +167,9 @@ public class IDFMNetworkExtractor { } } - /** @param path */ + /** Tells if the current trasport line has all its stops entries resolved + * @param stops the stops list + * @return if the line is "clean"*/ private static boolean cleanLine(List> stops) { for (List path : stops) { for (int i = 0; i < path.size(); i++) { @@ -150,6 +188,11 @@ public class IDFMNetworkExtractor { return true; } + /** adds a stop to all related variables + * @param line the transport line involved with the new stop + * @param traces the traces related to it + * @param stops the general stops list + */ private static void addStop(String[] line, Map traces, List stops) { StopEntry entry = new StopEntry(line[IDFM_STOPS_NAME_INDEX], @@ -167,6 +210,10 @@ public class IDFMNetworkExtractor { stops.add(entry); } + /** add a line to the related list of traces + * @param line the line as a string + * @param traces the traces + */ private static void addLine(String[] line, Map traces) { TraceEntry entry = new TraceEntry(line[IDFM_TRACE_SNAME_INDEX]); List> buildPaths = buildPaths(line[IDFM_TRACE_SHAPE_INDEX]); @@ -179,6 +226,11 @@ public class IDFMNetworkExtractor { } } + /** add a new entry as a candidate to a trace + * @param trace the trace + * @param entry the entry + * @return the trace in question + */ private static TraceEntry addCandidate(TraceEntry trace, StopEntry entry) { for (List path : trace.getPaths()) { for (StopEntry stopEntry : path) { @@ -193,6 +245,10 @@ public class IDFMNetworkExtractor { return trace; } + /** turn a JSON list of stops into a list of paths + * @param pathsJSON the JSON String of all paths + * @return the paths as a List of StopEntries + */ private static List> buildPaths(String pathsJSON) { List> all = new ArrayList<>(); try { @@ -220,6 +276,10 @@ public class IDFMNetworkExtractor { return all; } + /** extract the terminus out of a JSON file + * @param JSON the JSON + * @return a list of strings related to the terminus + */ private static List extractTerminus(String JSON) { List all = new ArrayList<>(); try { diff --git a/src/main/java/fr/u_paris/gla/project/io/NetworkFormat.java b/src/main/java/fr/u_paris/gla/project/io/NetworkFormat.java index ff95c99..814cc54 100644 --- a/src/main/java/fr/u_paris/gla/project/io/NetworkFormat.java +++ b/src/main/java/fr/u_paris/gla/project/io/NetworkFormat.java @@ -14,8 +14,10 @@ import java.util.Locale; * * @author Emmanuel Bigeon */ public final class NetworkFormat { - + /** The amount of columns in the CSV file */ public static final int NUMBER_COLUMNS = 8; + + /** The amount of decimal places in the GPS' coordinates */ public static final int GPS_PRECISION = 18; /** The index of the line name in the network format */ @@ -45,11 +47,19 @@ public final class NetworkFormat { // Tool class } + /** Convert a {@link java.lang.String} into a {@link java.time.Duration} + * @param duration the {@link java.lang.String} + * @return the {@link java.time.Duration} object + */ public static Duration parseDuration(String duration) { LocalTime time = LocalTime.parse("00:" + duration, DURATION_FORMATTER); return Duration.between(time, ZERO); } + /** Format a {@link java.time.Duration} into a {@link java.lang.String} + * @param duration an object of type {@link java.time.Duration} + * @return a String that depicts the duration in format MM:SS + */ public static String formatDuration(Duration duration) { return Long.toString(duration.toMinutes()) + ":" + DURATION_SECONDS_FORMATTER.format(duration.toSecondsPart()); @@ -57,7 +67,7 @@ public final class NetworkFormat { /** Get a formatter for the numbers in a GPS coordinate pair * - * @return the formatter for numbers in a GPS coordinate pair */ + * @return the {@link java.text.NumberFormat} formatter for numbers in a GPS coordinate pair */ public static NumberFormat getGPSFormatter() { NumberFormat instance = NumberFormat.getNumberInstance(Locale.ENGLISH); instance.setMaximumFractionDigits(GPS_PRECISION); diff --git a/src/main/java/fr/u_paris/gla/project/io/ScheduleFormat.java b/src/main/java/fr/u_paris/gla/project/io/ScheduleFormat.java index fc4d4ba..14a13fd 100644 --- a/src/main/java/fr/u_paris/gla/project/io/ScheduleFormat.java +++ b/src/main/java/fr/u_paris/gla/project/io/ScheduleFormat.java @@ -13,11 +13,16 @@ import java.util.List; * @author Emmanuel Bigeon */ public final class ScheduleFormat { + /** The amount of columns in the CSV file */ public static final int NUMBER_COLUMNS = 4; + /** The index of the line name in the schedule format */ public static final int LINE_INDEX = 0; + /** The index of the trip sequence in the schedule format */ public static final int TRIP_SEQUENCE_INDEX = 1; + /** The index of the terminus name in the schedule format */ public static final int TERMINUS_INDEX = 2; + /** The index of the time in the schedule format */ public static final int TIME_INDEX = 3; /** Hidden constructor for tool class */ @@ -37,6 +42,9 @@ public final class ScheduleFormat { throw new RuntimeException("Not implemented yet"); } + /** Create a {@link java.time.format.DateTimeFormatter} object used to format Dates + * @return the formatter + */ public static DateTimeFormatter getTimeFormatter() { return DateTimeFormatter.ofPattern("HH:mm").withResolverStyle(ResolverStyle.LENIENT); } diff --git a/src/main/java/fr/u_paris/gla/project/utils/CSVTools.java b/src/main/java/fr/u_paris/gla/project/utils/CSVTools.java index b3194f9..5332a41 100644 --- a/src/main/java/fr/u_paris/gla/project/utils/CSVTools.java +++ b/src/main/java/fr/u_paris/gla/project/utils/CSVTools.java @@ -32,6 +32,11 @@ public final class CSVTools { // Tool class } + /** get a CSV file from a URL, download and parse it, and keep values in memory + * @param url the address of the CSV file + * @param contentLineConsumer the variable used to store the data + * @throws IOException if it's impossible to download the file + */ public static void readCSVFromURL(String url, Consumer contentLineConsumer) throws IOException { ICSVParser parser = new CSVParserBuilder().withSeparator(';').build(); @@ -52,6 +57,11 @@ public final class CSVTools { } } + /** Save our current CSV variable's data into an actual file + * @param filename the saved file's name and path + * @param contentLineConsumer our data variable + * @throws IOException if we can't write the data into the file + */ public static void writeCSVToFile(String filename, Stream contentLineConsumer) throws IOException { try (FileWriter writer = new FileWriter(filename, StandardCharsets.UTF_8)) {