Update javadoc and clean naming.

This commit is contained in:
Mikael Capelle 2018-03-07 17:10:02 +01:00
parent 17fb363493
commit 85fb193808
14 changed files with 237 additions and 142 deletions

View File

@ -2,17 +2,20 @@ package org.insa.graph.io;
import java.io.IOException; 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 { public class BadFormatException extends IOException {
/** /**
* *
*/ */
private static final long serialVersionUID = -5455552814725826052L; private static final long serialVersionUID = 1L;
/** /**
* *
* @param actualVersion
* @param expectedVersion
*/ */
public BadFormatException() { public BadFormatException() {
super(); super();

View File

@ -1,8 +1,11 @@
package org.insa.graph.io; 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; 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) { public BadMagicNumberException(int actualNumber, int expectedNumber) {
super(); 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;
}
} }

View File

@ -1,8 +1,11 @@
package org.insa.graph.io; 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) { public BadVersionException(int actualVersion, int expectedVersion) {
super(); 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;
}
} }

View File

@ -4,6 +4,7 @@ import java.io.DataInputStream;
import java.io.IOException; import java.io.IOException;
import java.util.ArrayList; import java.util.ArrayList;
import java.util.EnumMap; import java.util.EnumMap;
import java.util.List;
import org.insa.graph.AccessRestrictions; import org.insa.graph.AccessRestrictions;
import org.insa.graph.AccessRestrictions.AccessMode; 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;
import org.insa.graph.RoadInformation.RoadType; 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. // Map version and magic number targeted for this reader.
private static final int VERSION = 5; 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) // Length of the map id field (in bytes)
protected static final int MAP_ID_FIELD_LENGTH = 32; 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: // See the following for more information:
// https://github.com/Holt59/OSM2Graph/blob/master/src/main/org/laas/osm2graph/model/AccessData.java // 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. * @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) { protected static RoadType toRoadType(char ch) {
switch (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); super(MAGIC_NUMBER, VERSION, dis);
} }
@Override
public void addObserver(GraphReaderObserver observer) {
observers.add(observer);
}
@Override @Override
public Graph read() throws IOException { public Graph read() throws IOException {
@ -257,14 +270,16 @@ public class BinaryGraphReaderInsa2018 extends BinaryReader implements GraphRead
/** /**
* Read the next road information from the stream. * 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 { private RoadInformation readRoadInformation() throws IOException {
char type = (char) dis.readUnsignedByte(); char type = (char) dis.readUnsignedByte();
int x = dis.readUnsignedByte(); int x = dis.readUnsignedByte();
AccessRestrictions access = new AccessRestrictions(); AccessRestrictions access = new AccessRestrictions();
if (getCurrentVersion() >= 7) { if (getCurrentVersion() >= 7) {
access = toAccessInformationV7(dis.readLong()); access = toAccessInformation(dis.readLong());
} }
else if (getCurrentVersion() >= 6) { else if (getCurrentVersion() >= 6) {
// TODO: Try to create something... // TODO: Try to create something...

View File

@ -8,12 +8,21 @@ import org.insa.graph.Graph;
import org.insa.graph.Node; import org.insa.graph.Node;
import org.insa.graph.Path; import org.insa.graph.Path;
/**
* Implementation of {@link PathReader} to read paths in binary format.
*
*/
public class BinaryPathReader extends BinaryReader implements PathReader { public class BinaryPathReader extends BinaryReader implements PathReader {
// Map version and magic number targeted for this reader. // Map version and magic number targeted for this reader.
protected static final int VERSION = 1; protected static final int VERSION = 1;
protected static final int MAGIC_NUMBER = 0xdecafe; 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) { public BinaryPathReader(DataInputStream dis) {
super(MAGIC_NUMBER, VERSION, dis); super(MAGIC_NUMBER, VERSION, dis);
} }
@ -26,7 +35,8 @@ public class BinaryPathReader extends BinaryReader implements PathReader {
checkVersionOrThrow(dis.readInt()); checkVersionOrThrow(dis.readInt());
// Read map ID and check against graph. // 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())) { if (!mapId.equals(graph.getMapId())) {
throw new MapMismatchException(mapId, 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 { protected Node readNode(Graph graph) throws IOException {
// Discard zone. // Discard zone.

View File

@ -7,10 +7,16 @@ import java.util.Arrays;
import org.insa.graph.Arc; import org.insa.graph.Arc;
import org.insa.graph.Path; import org.insa.graph.Path;
/**
* Implementation of {@link PathWriter} to write paths in binary format.
*
*/
public class BinaryPathWriter extends BinaryWriter implements PathWriter { 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) { public BinaryPathWriter(DataOutputStream dos) {
super(dos); super(dos);
@ -25,7 +31,7 @@ public class BinaryPathWriter extends BinaryWriter implements PathWriter {
// Write map id. // Write map id.
byte[] bytes = Arrays.copyOf(path.getGraph().getMapId().getBytes("UTF-8"), byte[] bytes = Arrays.copyOf(path.getGraph().getMapId().getBytes("UTF-8"),
BinaryGraphReaderInsa2018.MAP_ID_FIELD_LENGTH); BinaryGraphReader.MAP_ID_FIELD_LENGTH);
dos.write(bytes); dos.write(bytes);
// Write number of arcs // Write number of arcs

View File

@ -2,9 +2,11 @@ package org.insa.graph.io;
import java.io.DataInputStream; import java.io.DataInputStream;
import java.io.IOException; import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
/**
* Base class for writing binary file.
*
*/
public abstract class BinaryReader { public abstract class BinaryReader {
// Map version and magic number targeted for this reader. // Map version and magic number targeted for this reader.
@ -15,28 +17,28 @@ public abstract class BinaryReader {
// InputStream // InputStream
protected DataInputStream dis; 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) { protected BinaryReader(int magicNumber, int minVersion, DataInputStream dis) {
this.magicNumber = magicNumber; this.magicNumber = magicNumber;
this.minVersion = minVersion; this.minVersion = minVersion;
this.dis = dis; 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 * Check if the given version is greater than the minimum version, and update
* the current version if it is. * 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 { protected void checkVersionOrThrow(int version) throws BadVersionException {
if (version < this.minVersion) { if (version < this.minVersion) {
@ -46,15 +48,18 @@ public abstract class BinaryReader {
} }
/** /**
* @return the current version. * @return The current version.
*/ */
protected int getCurrentVersion() { protected int getCurrentVersion() {
return this.curVersion; 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 { protected void checkMagicNumberOrThrow(int magicNumber) throws BadMagicNumberException {
if (this.magicNumber != magicNumber) { 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(); 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'. * 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 { protected String readFixedLengthString(int length, String charset) throws IOException {
byte[] bytes = new byte[length]; 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. * @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 { protected int read24bits() throws IOException {
int x = dis.readUnsignedShort(); int x = dis.readUnsignedShort();

View File

@ -3,24 +3,30 @@ package org.insa.graph.io;
import java.io.DataOutputStream; import java.io.DataOutputStream;
import java.io.IOException; import java.io.IOException;
/**
* Base class for writing binary file.
*
*/
public abstract class BinaryWriter { public abstract class BinaryWriter {
// Output stream. // Output stream.
protected DataOutputStream dos; 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) { protected BinaryWriter(DataOutputStream dos) {
this.dos = 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 { protected void write24bits(int value) throws IOException {
dos.writeShort(value >> 8); dos.writeShort(value >> 8);

View File

@ -4,20 +4,25 @@ import java.io.IOException;
import org.insa.graph.Graph; import org.insa.graph.Graph;
/**
* Base interface for classes that can read graph.
*
*/
public interface GraphReader { public interface GraphReader {
/** /**
* Add a new observer to this graph reader. * Add a new observer to this graph reader.
* *
* @param observer * @param observer Observer to add.
*/ */
public void addObserver(GraphReaderObserver observer); public void addObserver(GraphReaderObserver observer);
/** /**
* Read a graph an returns it. * 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; public Graph read() throws IOException;

View File

@ -4,6 +4,11 @@ import org.insa.graph.Arc;
import org.insa.graph.Node; import org.insa.graph.Node;
import org.insa.graph.RoadInformation; 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 { public interface GraphReaderObserver {
/** /**
@ -29,7 +34,7 @@ public interface GraphReaderObserver {
/** /**
* Notify that a new nodes has been read. * Notify that a new nodes has been read.
* *
* @param node * @param node read.
*/ */
public void notifyNewNodeRead(Node node); public void notifyNewNodeRead(Node node);
@ -43,7 +48,7 @@ public interface GraphReaderObserver {
/** /**
* Notify that a new descriptor has been read. * Notify that a new descriptor has been read.
* *
* @param desc * @param desc Descriptor read.
*/ */
public void notifyNewDescriptorRead(RoadInformation desc); public void notifyNewDescriptorRead(RoadInformation desc);
@ -57,7 +62,7 @@ public interface GraphReaderObserver {
/** /**
* Notify that a new arc has been read. * Notify that a new arc has been read.
* *
* @param arc * @param arc Arc read.
*/ */
public void notifyNewArcRead(Arc arc); public void notifyNewArcRead(Arc arc);

View File

@ -2,19 +2,26 @@ package org.insa.graph.io;
import java.io.IOException; 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 { 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; 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) { public MapMismatchException(String actualMapId, String expectedMapId) {
super(); super();
@ -23,14 +30,14 @@ public class MapMismatchException extends IOException {
} }
/** /**
* @return * @return Actual ID of the map (read from the path).
*/ */
public String getActualMapId() { public String getActualMapId() {
return actualMapId; return actualMapId;
} }
/** /**
* @return * @return Expected ID of the map.
*/ */
public String getExpectedMapId() { public String getExpectedMapId() {
return expectedMapId; return expectedMapId;

View File

@ -5,6 +5,10 @@ import java.io.IOException;
import org.insa.graph.Graph; import org.insa.graph.Graph;
import org.insa.graph.Path; import org.insa.graph.Path;
/**
* Base interface that should be implemented by class used to read paths.
*
*/
public interface PathReader { public interface PathReader {
/** /**
@ -12,8 +16,9 @@ public interface PathReader {
* *
* @param graph Graph of the path. * @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; public Path readPath(Graph graph) throws IOException;

View File

@ -4,14 +4,18 @@ import java.io.IOException;
import org.insa.graph.Path; import org.insa.graph.Path;
/**
* Base interface that should be implemented by class used to write paths.
*
*/
public interface PathWriter { public interface PathWriter {
/** /**
* Write a path. * Write the given path.
* *
* @param path Path to write. * @param path Path to write.
* *
* @throws Exception * @throws IOException When an error occurs while writing the path.
*/ */
public void writePath(Path path) throws IOException; public void writePath(Path path) throws IOException;

View File

@ -57,7 +57,7 @@ import org.insa.algo.weakconnectivity.WeaklyConnectedComponentsAlgorithm;
import org.insa.algo.weakconnectivity.WeaklyConnectedComponentsData; import org.insa.algo.weakconnectivity.WeaklyConnectedComponentsData;
import org.insa.graph.Graph; import org.insa.graph.Graph;
import org.insa.graph.Path; 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.BinaryPathReader;
import org.insa.graph.io.GraphReader; import org.insa.graph.io.GraphReader;
import org.insa.graph.io.MapMismatchException; import org.insa.graph.io.MapMismatchException;
@ -613,7 +613,7 @@ public class MainWindow extends JFrame {
"Cannot open the selected file."); "Cannot open the selected file.");
return; return;
} }
loadGraph(new BinaryGraphReaderInsa2018(stream)); loadGraph(new BinaryGraphReader(stream));
} }
} }
})); }));