Update javadoc and clean naming.

src/main/org/insa/graph/io/BadFormatException.java

@@ -2,17 +2,20 @@ 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();

src/main/org/insa/graph/io/BadMagicNumberException.java

@@ -1,8 +1,11 @@
 package org.insa.graph.io;
 
-import java.io.IOException;
+/**
-
+ * Exception thrown when there is a mismatch between expected and actual magic
-public class BadMagicNumberException extends IOException {
+ * number.
+ *
+ */
+public class BadMagicNumberException extends BadFormatException {
 
     /**
      * 
@@ -13,9 +16,11 @@ public class BadMagicNumberException extends IOException {
     private int actualNumber, expectedNumber;
 
     /**
+     * Create a new BadMagicNumberException with the given expected and actual magic
+     * number.
      * 
-	 * @param actualVersion
+     * @param actualNumber Actual magic number (read from a file).
-	 * @param expectedVersion
+     * @param expectedNumber Expected magic number.
      */
     public BadMagicNumberException(int actualNumber, int expectedNumber) {
         super();
@@ -24,13 +29,17 @@ public class BadMagicNumberException extends IOException {
     }
 
     /**
-	 * 
+     * @return The actual magic number.
      */
-	public int getActualMagicNumber() { return actualNumber; }
+    public int getActualMagicNumber() {
+        return actualNumber;
+    }
 
     /**
-	 * 
+     * @return The expected magic number.
      */
-	public int getExpectedMagicNumber() { return expectedNumber; }
+    public int getExpectedMagicNumber() {
+        return expectedNumber;
+    }
 
 }

src/main/org/insa/graph/io/BadVersionException.java

@@ -1,8 +1,11 @@
 package org.insa.graph.io;
 
-import java.io.IOException;
+/**
-
+ * Exception thrown when the version of the file is not at least the expected
-public class BadVersionException extends IOException {
+ * one.
+ *
+ */
+public class BadVersionException extends BadFormatException {
 
     /**
      * 
@@ -14,8 +17,8 @@ public class BadVersionException extends IOException {
 
     /**
      * 
-	 * @param actualVersion
+     * @param actualVersion Actual version of the file.
-	 * @param expectedVersion
+     * @param expectedVersion Expected version of the file.
      */
     public BadVersionException(int actualVersion, int expectedVersion) {
         super();
@@ -24,12 +27,16 @@ public class BadVersionException extends IOException {
     }
 
     /**
-	 * 
+     * @return Actual version of the file.
      */
-	public int getActualVersion() { return actualVersion; }
+    public int getActualVersion() {
+        return actualVersion;
+    }
 
     /**
-	 * 
+     * @return Expected (minimal) version of the file.
      */
-	public int getExpectedVersion() { return expectedVersion; }
+    public int getExpectedVersion() {
+        return expectedVersion;
+    }
 }

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<GraphReaderObserver> 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
+     * @param access The value to parse.
-     * @return
+     * 
+     * @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...

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
+     * @param graph Graph containing the nodes.
-     * @throws IOException
+     * 
+     * @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.

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

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<GraphReaderObserver> 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
+     * @param version Version to check.
-     * @throws BadVersionException
+     * 
+     * @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
+     * Check if the given number matches the expected magic number.
-     * @throws BadMagicNumberException
+     * 
+     * @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
+     * Check if the next byte in the input stream correspond to the given byte.
-     * function consumes the next byte in the input stream.
      * 
-     * @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 {
+    protected void checkByteOrThrow(int b) throws IOException {
-        if (dis.readUnsignedByte() != i) {
+        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 length Number of bytes to read.
-     * @param charset
+     * @param charset Charset to use to convert the bytes into a string.
      * 
-     * @return an UTF-8 string read from the input.
+     * @return The convert string.
-     * @throws IOException
+     * 
+     * @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();

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);

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.
+     * @return The graph read.
-     * @throws Exception
+     * 
+     * @throws IOException When an exception occurs while reading the graph.
      * 
      */
     public Graph read() throws IOException;

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);
 

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;
+    private static final long serialVersionUID = 1L;
-    // Actual and expected magic numbers.
+
+    // Actual and expected map ID.
     private String actualMapId, expectedMapId;
 
     /**
+     * Create a new MapMismatchException with the given IDs.
      * 
-     * @param actualVersion
+     * @param actualMapId Actual map ID found when reading the path.
-     * @param expectedVersion
+     * @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;

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.
+     * @return Path read.
-     * @throws Exception
+     * 
+     * @throws IOException When an error occurs while reading the path.
      */
     public Path readPath(Graph graph) throws IOException;
 

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;
 

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));
                 }
             }
         }));