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 6df2b64..d09754f 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 @@ -1,5 +1,5 @@ /** - * + * */ package fr.u_paris.gla.project.idfm; @@ -19,9 +19,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 { @@ -29,6 +38,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 */ @@ -36,34 +48,69 @@ public final class CSVStreamProvider { /** Distance to reach maximal speed in km */ private static final double TWO_ACCELERATION_DISTANCE = 0.2; + /** + * Current CSV Line + */ private final String[] line = new String[NetworkFormat.NUMBER_COLUMNS]; + /** + * Current CSV transport line iterator + */ private final 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<>(); // The transport id with its value private final Map transports; List descriptions = new ArrayList<>(); + /** + * 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; private String traceId = ""; private String traceType = ""; private String url_image = ""; - /** Create the stream provider */ + /** Create the stream provider + * @param traces an iterator of the possible traces + * @param t map of transports */ public CSVStreamProvider(Iterator traces, Map t) { this.currentTrace = traces; transports = t; } + /** 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(); @@ -71,6 +118,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; @@ -86,6 +136,9 @@ public final class CSVStreamProvider { } } + /** + * Skips to the next segment + */ private void skipToNextNewSegment() { do { this.start = this.currentSegmentStart.next(); @@ -132,6 +185,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(); @@ -155,9 +211,10 @@ public final class CSVStreamProvider { } - /** @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$ @@ -166,8 +223,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)); @@ -177,7 +235,7 @@ public final class CSVStreamProvider { *

* This is a model with an linear acceleration and deceleration periods and a * constant speed in between. - * + * * @param distance the distance (in km) * @return the duration of the trip (in hours) */ private static double distanceToTime(double distance) { @@ -204,7 +262,7 @@ public final class CSVStreamProvider { transp.addDescriptions(descriptions); } } - + } 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 cbf9f77..acb942a 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 @@ -30,20 +30,50 @@ 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; private static final int IDFM_TRACE_TYPE_INDEX = 3; + /** + * 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; private static final int IDFM_URL_INDEX = 10; @@ -53,11 +83,14 @@ public class IDFMNetworkExtractor { */ 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) @@ -192,6 +225,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()) { @@ -207,9 +243,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++) { @@ -227,6 +263,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], @@ -254,6 +295,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], line[IDFM_TRACE_ID_INDEX],line[IDFM_TRACE_TYPE_INDEX], line[IDFM_URL_INDEX]); List> buildPaths = buildPaths(line[IDFM_TRACE_SHAPE_INDEX]); @@ -266,6 +311,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) { @@ -280,6 +330,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 { @@ -307,6 +361,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 8dadf35..a46499d 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 */ @@ -65,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 c97b233..77020b6 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 @@ -14,11 +14,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 */ 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 b511757..8fa35db 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 @@ -1,5 +1,5 @@ /** - * + * */ package fr.u_paris.gla.project.utils; @@ -19,7 +19,7 @@ import com.opencsv.ICSVWriter; import com.opencsv.exceptions.CsvValidationException; /** A CSV tool class. - * + * * @author Emmanuel Bigeon */ public final class CSVTools { @@ -28,6 +28,11 @@ public final class CSVTools { // Tool class } + /** get a CSV file from a URL, download and parse it, and keep values in memory + * @param is 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 + */ private static void readCSVFromInputStream(InputStream is, Consumer contentLineConsumer) throws IOException { ICSVParser parser = new CSVParserBuilder().withSeparator(';').build(); @@ -46,7 +51,13 @@ public final class CSVTools { throw new IOException("Invalid csv file", e); //$NON-NLS-1$ } } - + + + /** get a CSV file from a file and parse it, keeping values in memory + * @param filename the saved file's name and path + * @param contentLineConsumer the variable used to store the data + * @throws IOException if it's impossible to read the file + */ public static void readCSVFromFile(String filename, Consumer contentLineConsumer) throws IOException { File file = new File(filename);