From 85fb193808a041c8e66bd5177bef0e8a212468a0 Mon Sep 17 00:00:00 2001 From: Mikael Capelle Date: Wed, 7 Mar 2018 17:10:02 +0100 Subject: [PATCH] Update javadoc and clean naming. --- .../org/insa/graph/io/BadFormatException.java | 27 ++++---- .../graph/io/BadMagicNumberException.java | 69 +++++++++++-------- .../insa/graph/io/BadVersionException.java | 67 ++++++++++-------- ...erInsa2018.java => BinaryGraphReader.java} | 39 +++++++---- .../org/insa/graph/io/BinaryPathReader.java | 22 ++++-- .../org/insa/graph/io/BinaryPathWriter.java | 10 ++- src/main/org/insa/graph/io/BinaryReader.java | 69 +++++++++++-------- src/main/org/insa/graph/io/BinaryWriter.java | 14 ++-- src/main/org/insa/graph/io/GraphReader.java | 11 ++- .../insa/graph/io/GraphReaderObserver.java | 11 ++- .../insa/graph/io/MapMismatchException.java | 19 +++-- src/main/org/insa/graph/io/PathReader.java | 9 ++- src/main/org/insa/graph/io/PathWriter.java | 8 ++- src/main/org/insa/graphics/MainWindow.java | 4 +- 14 files changed, 237 insertions(+), 142 deletions(-) rename src/main/org/insa/graph/io/{BinaryGraphReaderInsa2018.java => BinaryGraphReader.java} (89%) diff --git a/src/main/org/insa/graph/io/BadFormatException.java b/src/main/org/insa/graph/io/BadFormatException.java index da90f55..d69b879 100644 --- a/src/main/org/insa/graph/io/BadFormatException.java +++ b/src/main/org/insa/graph/io/BadFormatException.java @@ -2,20 +2,23 @@ package org.insa.graph.io; import java.io.IOException; +/** + * Exception thrown when a format-error is detected when reading a graph (e.g., + * non-matching check bytes). + * + */ public class BadFormatException extends IOException { - /** - * - */ - private static final long serialVersionUID = -5455552814725826052L; + /** + * + */ + private static final long serialVersionUID = 1L; - /** - * - * @param actualVersion - * @param expectedVersion - */ - public BadFormatException() { - super(); - } + /** + * + */ + public BadFormatException() { + super(); + } } diff --git a/src/main/org/insa/graph/io/BadMagicNumberException.java b/src/main/org/insa/graph/io/BadMagicNumberException.java index e3b81f3..98209b8 100644 --- a/src/main/org/insa/graph/io/BadMagicNumberException.java +++ b/src/main/org/insa/graph/io/BadMagicNumberException.java @@ -1,36 +1,45 @@ package org.insa.graph.io; -import java.io.IOException; +/** + * Exception thrown when there is a mismatch between expected and actual magic + * number. + * + */ +public class BadMagicNumberException extends BadFormatException { -public class BadMagicNumberException extends IOException { + /** + * + */ + private static final long serialVersionUID = -2176603967548838864L; - /** - * - */ - private static final long serialVersionUID = -2176603967548838864L; - - // Actual and expected magic numbers. - private int actualNumber, expectedNumber; - - /** - * - * @param actualVersion - * @param expectedVersion - */ - public BadMagicNumberException(int actualNumber, int expectedNumber) { - super(); - this.actualNumber = actualNumber; - this.expectedNumber = expectedNumber; - } - - /** - * - */ - public int getActualMagicNumber() { return actualNumber; } - - /** - * - */ - public int getExpectedMagicNumber() { return expectedNumber; } + // Actual and expected magic numbers. + private int actualNumber, expectedNumber; + + /** + * Create a new BadMagicNumberException with the given expected and actual magic + * number. + * + * @param actualNumber Actual magic number (read from a file). + * @param expectedNumber Expected magic number. + */ + public BadMagicNumberException(int actualNumber, int expectedNumber) { + super(); + this.actualNumber = actualNumber; + this.expectedNumber = expectedNumber; + } + + /** + * @return The actual magic number. + */ + public int getActualMagicNumber() { + return actualNumber; + } + + /** + * @return The expected magic number. + */ + public int getExpectedMagicNumber() { + return expectedNumber; + } } diff --git a/src/main/org/insa/graph/io/BadVersionException.java b/src/main/org/insa/graph/io/BadVersionException.java index df9d99e..a8dead3 100644 --- a/src/main/org/insa/graph/io/BadVersionException.java +++ b/src/main/org/insa/graph/io/BadVersionException.java @@ -1,35 +1,42 @@ package org.insa.graph.io; -import java.io.IOException; +/** + * Exception thrown when the version of the file is not at least the expected + * one. + * + */ +public class BadVersionException extends BadFormatException { -public class BadVersionException extends IOException { + /** + * + */ + private static final long serialVersionUID = 7776317018302386042L; - /** - * - */ - private static final long serialVersionUID = 7776317018302386042L; - - // Actual and expected version.. - private int actualVersion, expectedVersion; - - /** - * - * @param actualVersion - * @param expectedVersion - */ - public BadVersionException(int actualVersion, int expectedVersion) { - super(); - this.actualVersion = actualVersion; - this.expectedVersion = expectedVersion; - } - - /** - * - */ - public int getActualVersion() { return actualVersion; } - - /** - * - */ - public int getExpectedVersion() { return expectedVersion; } + // Actual and expected version.. + private int actualVersion, expectedVersion; + + /** + * + * @param actualVersion Actual version of the file. + * @param expectedVersion Expected version of the file. + */ + public BadVersionException(int actualVersion, int expectedVersion) { + super(); + this.actualVersion = actualVersion; + this.expectedVersion = expectedVersion; + } + + /** + * @return Actual version of the file. + */ + public int getActualVersion() { + return actualVersion; + } + + /** + * @return Expected (minimal) version of the file. + */ + public int getExpectedVersion() { + return expectedVersion; + } } diff --git a/src/main/org/insa/graph/io/BinaryGraphReaderInsa2018.java b/src/main/org/insa/graph/io/BinaryGraphReader.java similarity index 89% rename from src/main/org/insa/graph/io/BinaryGraphReaderInsa2018.java rename to src/main/org/insa/graph/io/BinaryGraphReader.java index 999f224..5e15450 100644 --- a/src/main/org/insa/graph/io/BinaryGraphReaderInsa2018.java +++ b/src/main/org/insa/graph/io/BinaryGraphReader.java @@ -4,6 +4,7 @@ import java.io.DataInputStream; import java.io.IOException; import java.util.ArrayList; import java.util.EnumMap; +import java.util.List; import org.insa.graph.AccessRestrictions; import org.insa.graph.AccessRestrictions.AccessMode; @@ -16,7 +17,11 @@ import org.insa.graph.Point; import org.insa.graph.RoadInformation; import org.insa.graph.RoadInformation.RoadType; -public class BinaryGraphReaderInsa2018 extends BinaryReader implements GraphReader { +/** + * Implementation of {@link GraphReader} to read graph in binary format. + * + */ +public class BinaryGraphReader extends BinaryReader implements GraphReader { // Map version and magic number targeted for this reader. private static final int VERSION = 5; @@ -25,13 +30,17 @@ public class BinaryGraphReaderInsa2018 extends BinaryReader implements GraphRead // Length of the map id field (in bytes) protected static final int MAP_ID_FIELD_LENGTH = 32; + // List of observers + protected List observers = new ArrayList<>(); + /** - * Create a new access information by parsing the given value (V6 version). + * Parse the given long value into a new instance of AccessRestrictions. * - * @param access - * @return + * @param access The value to parse. + * + * @return New instance of access restrictions parsed from the given value. */ - protected static AccessRestrictions toAccessInformationV7(final long access) { + protected static AccessRestrictions toAccessInformation(final long access) { // See the following for more information: // https://github.com/Holt59/OSM2Graph/blob/master/src/main/org/laas/osm2graph/model/AccessData.java @@ -77,9 +86,8 @@ public class BinaryGraphReaderInsa2018 extends BinaryReader implements GraphRead * * @param ch Character to convert. * - * @return Road type corresponding to ch. + * @return Road type corresponding to the given character. * - * @see http://wiki.openstreetmap.org/wiki/Highway_tag_usage. */ protected static RoadType toRoadType(char ch) { switch (ch) { @@ -125,14 +133,19 @@ public class BinaryGraphReaderInsa2018 extends BinaryReader implements GraphRead } /** - * Create a new BinaryGraphReader using the given DataInputStream. + * Create a new BinaryGraphReader that read from the given input stream. * - * @param dis + * @param dis Input stream to read from. */ - public BinaryGraphReaderInsa2018(DataInputStream dis) { + public BinaryGraphReader(DataInputStream dis) { super(MAGIC_NUMBER, VERSION, dis); } + @Override + public void addObserver(GraphReaderObserver observer) { + observers.add(observer); + } + @Override public Graph read() throws IOException { @@ -257,14 +270,16 @@ public class BinaryGraphReaderInsa2018 extends BinaryReader implements GraphRead /** * Read the next road information from the stream. * - * @throws IOException + * @return The next RoadInformation in the stream. + * + * @throws IOException if an error occurs while reading from the stream. */ private RoadInformation readRoadInformation() throws IOException { char type = (char) dis.readUnsignedByte(); int x = dis.readUnsignedByte(); AccessRestrictions access = new AccessRestrictions(); if (getCurrentVersion() >= 7) { - access = toAccessInformationV7(dis.readLong()); + access = toAccessInformation(dis.readLong()); } else if (getCurrentVersion() >= 6) { // TODO: Try to create something... diff --git a/src/main/org/insa/graph/io/BinaryPathReader.java b/src/main/org/insa/graph/io/BinaryPathReader.java index 28c8af4..961f5f8 100644 --- a/src/main/org/insa/graph/io/BinaryPathReader.java +++ b/src/main/org/insa/graph/io/BinaryPathReader.java @@ -8,12 +8,21 @@ import org.insa.graph.Graph; import org.insa.graph.Node; import org.insa.graph.Path; +/** + * Implementation of {@link PathReader} to read paths in binary format. + * + */ public class BinaryPathReader extends BinaryReader implements PathReader { // Map version and magic number targeted for this reader. protected static final int VERSION = 1; protected static final int MAGIC_NUMBER = 0xdecafe; + /** + * Create a new BinaryPathReader that read from the given input stream. + * + * @param dis Input stream to read from. + */ public BinaryPathReader(DataInputStream dis) { super(MAGIC_NUMBER, VERSION, dis); } @@ -26,7 +35,8 @@ public class BinaryPathReader extends BinaryReader implements PathReader { checkVersionOrThrow(dis.readInt()); // Read map ID and check against graph. - String mapId = readFixedLengthString(BinaryGraphReaderInsa2018.MAP_ID_FIELD_LENGTH, "UTF-8"); + String mapId = readFixedLengthString(BinaryGraphReader.MAP_ID_FIELD_LENGTH, + "UTF-8"); if (!mapId.equals(graph.getMapId())) { throw new MapMismatchException(mapId, graph.getMapId()); @@ -49,10 +59,14 @@ public class BinaryPathReader extends BinaryReader implements PathReader { } /** - * Read a node from the stream and returns id. + * Read a node from the input stream and returns it. * - * @return - * @throws IOException + * @param graph Graph containing the nodes. + * + * @return The next node in the input stream. + * + * @throws IOException if something occurs while reading the note. + * @throws IndexOutOfBoundsException if the node is not in the graph. */ protected Node readNode(Graph graph) throws IOException { // Discard zone. diff --git a/src/main/org/insa/graph/io/BinaryPathWriter.java b/src/main/org/insa/graph/io/BinaryPathWriter.java index 1c729df..222d0b5 100644 --- a/src/main/org/insa/graph/io/BinaryPathWriter.java +++ b/src/main/org/insa/graph/io/BinaryPathWriter.java @@ -7,10 +7,16 @@ import java.util.Arrays; import org.insa.graph.Arc; import org.insa.graph.Path; +/** + * Implementation of {@link PathWriter} to write paths in binary format. + * + */ public class BinaryPathWriter extends BinaryWriter implements PathWriter { /** - * @param dos + * Create a new BinaryPathWriter that writes to the given output stream. + * + * @param dos Output stream to write to. */ public BinaryPathWriter(DataOutputStream dos) { super(dos); @@ -25,7 +31,7 @@ public class BinaryPathWriter extends BinaryWriter implements PathWriter { // Write map id. byte[] bytes = Arrays.copyOf(path.getGraph().getMapId().getBytes("UTF-8"), - BinaryGraphReaderInsa2018.MAP_ID_FIELD_LENGTH); + BinaryGraphReader.MAP_ID_FIELD_LENGTH); dos.write(bytes); // Write number of arcs diff --git a/src/main/org/insa/graph/io/BinaryReader.java b/src/main/org/insa/graph/io/BinaryReader.java index ad4745d..4084359 100644 --- a/src/main/org/insa/graph/io/BinaryReader.java +++ b/src/main/org/insa/graph/io/BinaryReader.java @@ -2,9 +2,11 @@ package org.insa.graph.io; import java.io.DataInputStream; import java.io.IOException; -import java.util.ArrayList; -import java.util.List; +/** + * Base class for writing binary file. + * + */ public abstract class BinaryReader { // Map version and magic number targeted for this reader. @@ -15,28 +17,28 @@ public abstract class BinaryReader { // InputStream protected DataInputStream dis; - // List of observers - protected List observers = new ArrayList<>(); - + /** + * Create a new BinaryReader that reads from the given stream and that expected + * the given magic number and at least the given minimum version. + * + * @param magicNumber Magic number of files to be read. + * @param minVersion Minimum version of files to be read. + * @param dis Input stream from which to read. + */ protected BinaryReader(int magicNumber, int minVersion, DataInputStream dis) { this.magicNumber = magicNumber; this.minVersion = minVersion; this.dis = dis; } - /** - * {@inheritDoc} - */ - public void addObserver(GraphReaderObserver observer) { - observers.add(observer); - } - /** * Check if the given version is greater than the minimum version, and update * the current version if it is. * - * @param version - * @throws BadVersionException + * @param version Version to check. + * + * @throws BadVersionException if the given version is not greater than the + * minimum version. */ protected void checkVersionOrThrow(int version) throws BadVersionException { if (version < this.minVersion) { @@ -46,15 +48,18 @@ public abstract class BinaryReader { } /** - * @return the current version. + * @return The current version. */ protected int getCurrentVersion() { return this.curVersion; } /** - * @param magicNumber - * @throws BadMagicNumberException + * Check if the given number matches the expected magic number. + * + * @param magicNumber The magic number to check. + * + * @throws BadMagicNumberException If the two magic numbers are not equal. */ protected void checkMagicNumberOrThrow(int magicNumber) throws BadMagicNumberException { if (this.magicNumber != magicNumber) { @@ -63,28 +68,31 @@ public abstract class BinaryReader { } /** - * Check if the next byte in the input stream correspond to the given byte. This - * function consumes the next byte in the input stream. + * Check if the next byte in the input stream correspond to the given byte. * - * @param i Byte to check against. + * This function consumes the next byte in the input stream. * - * @throws IOException + * @param b Byte to check. + * + * @throws IOException if an error occurs while reading the byte. + * @throws BadFormatException if the byte read is not the expected one. */ - protected void checkByteOrThrow(int i) throws IOException { - if (dis.readUnsignedByte() != i) { + protected void checkByteOrThrow(int b) throws IOException { + if (dis.readUnsignedByte() != b) { throw new BadFormatException(); } } /** - * Read an bytes array of fixed length from the input and convert it to a string + * Read a byte array of fixed length from the input and convert it to a string * using the given charset, removing any trailing '\0'. * - * @param length - * @param charset + * @param length Number of bytes to read. + * @param charset Charset to use to convert the bytes into a string. * - * @return an UTF-8 string read from the input. - * @throws IOException + * @return The convert string. + * + * @throws IOException if an error occurs while reading or converting. */ protected String readFixedLengthString(int length, String charset) throws IOException { byte[] bytes = new byte[length]; @@ -93,11 +101,12 @@ public abstract class BinaryReader { } /** - * Read 24 bits from the stream and return the corresponding integer value. + * Read 24 bits in BigEndian order from the stream and return the corresponding + * integer value. * * @return Integer value read from the next 24 bits of the stream. * - * @throws IOException + * @throws IOException if an error occurs while reading from the stream. */ protected int read24bits() throws IOException { int x = dis.readUnsignedShort(); diff --git a/src/main/org/insa/graph/io/BinaryWriter.java b/src/main/org/insa/graph/io/BinaryWriter.java index 43e5cf7..a6a263f 100644 --- a/src/main/org/insa/graph/io/BinaryWriter.java +++ b/src/main/org/insa/graph/io/BinaryWriter.java @@ -3,24 +3,30 @@ package org.insa.graph.io; import java.io.DataOutputStream; import java.io.IOException; +/** + * Base class for writing binary file. + * + */ public abstract class BinaryWriter { // Output stream. protected DataOutputStream dos; /** - * @param dos + * Create a new BinaryWriter that writes to the given output stream. + * + * @param dos Stream to write to. */ protected BinaryWriter(DataOutputStream dos) { this.dos = dos; } /** - * Write a 24-bits integer in BigEndian to the output stream. + * Write a 24-bits integer in BigEndian order to the output stream. * - * @param value + * @param value Value to write. * - * @throws IOException + * @throws IOException if an error occurs while writing to the stream. */ protected void write24bits(int value) throws IOException { dos.writeShort(value >> 8); diff --git a/src/main/org/insa/graph/io/GraphReader.java b/src/main/org/insa/graph/io/GraphReader.java index 113ac56..10a9d48 100644 --- a/src/main/org/insa/graph/io/GraphReader.java +++ b/src/main/org/insa/graph/io/GraphReader.java @@ -4,20 +4,25 @@ import java.io.IOException; import org.insa.graph.Graph; +/** + * Base interface for classes that can read graph. + * + */ public interface GraphReader { /** * Add a new observer to this graph reader. * - * @param observer + * @param observer Observer to add. */ public void addObserver(GraphReaderObserver observer); /** * Read a graph an returns it. * - * @return Graph. - * @throws Exception + * @return The graph read. + * + * @throws IOException When an exception occurs while reading the graph. * */ public Graph read() throws IOException; diff --git a/src/main/org/insa/graph/io/GraphReaderObserver.java b/src/main/org/insa/graph/io/GraphReaderObserver.java index ed614f7..3ff65a8 100644 --- a/src/main/org/insa/graph/io/GraphReaderObserver.java +++ b/src/main/org/insa/graph/io/GraphReaderObserver.java @@ -4,6 +4,11 @@ import org.insa.graph.Arc; import org.insa.graph.Node; import org.insa.graph.RoadInformation; +/** + * Base interface that should be implemented by classes that want to observe the + * reading of a graph by a {@link GraphReader}. + * + */ public interface GraphReaderObserver { /** @@ -29,7 +34,7 @@ public interface GraphReaderObserver { /** * Notify that a new nodes has been read. * - * @param node + * @param node read. */ public void notifyNewNodeRead(Node node); @@ -43,7 +48,7 @@ public interface GraphReaderObserver { /** * Notify that a new descriptor has been read. * - * @param desc + * @param desc Descriptor read. */ public void notifyNewDescriptorRead(RoadInformation desc); @@ -57,7 +62,7 @@ public interface GraphReaderObserver { /** * Notify that a new arc has been read. * - * @param arc + * @param arc Arc read. */ public void notifyNewArcRead(Arc arc); diff --git a/src/main/org/insa/graph/io/MapMismatchException.java b/src/main/org/insa/graph/io/MapMismatchException.java index 095d461..fca9f70 100644 --- a/src/main/org/insa/graph/io/MapMismatchException.java +++ b/src/main/org/insa/graph/io/MapMismatchException.java @@ -2,19 +2,26 @@ package org.insa.graph.io; import java.io.IOException; +/** + * Exception thrown when there is mismatch between the expected map ID and the + * actual map ID when reading a graph. + * + */ public class MapMismatchException extends IOException { /** * */ - private static final long serialVersionUID = 3076730078387819138L; - // Actual and expected magic numbers. + private static final long serialVersionUID = 1L; + + // Actual and expected map ID. private String actualMapId, expectedMapId; /** + * Create a new MapMismatchException with the given IDs. * - * @param actualVersion - * @param expectedVersion + * @param actualMapId Actual map ID found when reading the path. + * @param expectedMapId Expected map ID from the graph. */ public MapMismatchException(String actualMapId, String expectedMapId) { super(); @@ -23,14 +30,14 @@ public class MapMismatchException extends IOException { } /** - * @return + * @return Actual ID of the map (read from the path). */ public String getActualMapId() { return actualMapId; } /** - * @return + * @return Expected ID of the map. */ public String getExpectedMapId() { return expectedMapId; diff --git a/src/main/org/insa/graph/io/PathReader.java b/src/main/org/insa/graph/io/PathReader.java index 856cf46..b1836b9 100644 --- a/src/main/org/insa/graph/io/PathReader.java +++ b/src/main/org/insa/graph/io/PathReader.java @@ -5,6 +5,10 @@ import java.io.IOException; import org.insa.graph.Graph; import org.insa.graph.Path; +/** + * Base interface that should be implemented by class used to read paths. + * + */ public interface PathReader { /** @@ -12,8 +16,9 @@ public interface PathReader { * * @param graph Graph of the path. * - * @return A new path. - * @throws Exception + * @return Path read. + * + * @throws IOException When an error occurs while reading the path. */ public Path readPath(Graph graph) throws IOException; diff --git a/src/main/org/insa/graph/io/PathWriter.java b/src/main/org/insa/graph/io/PathWriter.java index 0b54cc0..098fcab 100644 --- a/src/main/org/insa/graph/io/PathWriter.java +++ b/src/main/org/insa/graph/io/PathWriter.java @@ -4,14 +4,18 @@ import java.io.IOException; import org.insa.graph.Path; +/** + * Base interface that should be implemented by class used to write paths. + * + */ public interface PathWriter { /** - * Write a path. + * Write the given path. * * @param path Path to write. * - * @throws Exception + * @throws IOException When an error occurs while writing the path. */ public void writePath(Path path) throws IOException; diff --git a/src/main/org/insa/graphics/MainWindow.java b/src/main/org/insa/graphics/MainWindow.java index 78efb21..9d84a0c 100644 --- a/src/main/org/insa/graphics/MainWindow.java +++ b/src/main/org/insa/graphics/MainWindow.java @@ -57,7 +57,7 @@ import org.insa.algo.weakconnectivity.WeaklyConnectedComponentsAlgorithm; import org.insa.algo.weakconnectivity.WeaklyConnectedComponentsData; import org.insa.graph.Graph; import org.insa.graph.Path; -import org.insa.graph.io.BinaryGraphReaderInsa2018; +import org.insa.graph.io.BinaryGraphReader; import org.insa.graph.io.BinaryPathReader; import org.insa.graph.io.GraphReader; import org.insa.graph.io.MapMismatchException; @@ -613,7 +613,7 @@ public class MainWindow extends JFrame { "Cannot open the selected file."); return; } - loadGraph(new BinaryGraphReaderInsa2018(stream)); + loadGraph(new BinaryGraphReader(stream)); } } }));