From 0470a67f0f29a8d59feb387fe637d9567bf1e3f8 Mon Sep 17 00:00:00 2001 From: Louis Date: Wed, 22 Jan 2020 13:43:25 +0100 Subject: [PATCH] Add documentation --- src/protocolP2P/CodeType.java | 7 +++++ src/protocolP2P/FileList.java | 31 +++++++++++++++++-- src/protocolP2P/FilePart.java | 23 +++++++++++++- src/protocolP2P/Payload.java | 38 +++++++++++++++++++++--- src/protocolP2P/ProtocolP2PDatagram.java | 24 +++++++++++++++ 5 files changed, 115 insertions(+), 8 deletions(-) diff --git a/src/protocolP2P/CodeType.java b/src/protocolP2P/CodeType.java index f13e805..e38de49 100644 --- a/src/protocolP2P/CodeType.java +++ b/src/protocolP2P/CodeType.java @@ -1,4 +1,11 @@ package protocolP2P; + +/** Request/Response code's type enum. + * @author Louis Royer + * @author Flavien Haas + * @author JS Auge + * @version 1.0 + */ public enum CodeType { REQUEST, RESPONSE, diff --git a/src/protocolP2P/FileList.java b/src/protocolP2P/FileList.java index e46ad33..7c98455 100644 --- a/src/protocolP2P/FileList.java +++ b/src/protocolP2P/FileList.java @@ -5,14 +5,35 @@ import protocolP2P.RequestResponseCode; import exception.ProtocolError; import exception.InternalError; +/** Representation of payload for list response. + * @author Louis Royer + * @author Flavien Haas + * @author JS Auge + * @version 1.0 + */ public class FileList extends Payload { private final static RequestResponseCode requestResponseCode = RequestResponseCode.LIST_RESPONSE; private ArrayList content; - public FileList(ArrayList content) { + /** Constructor (typically used by the server) with an ArrayList parameter containing + * filenames. + * @param content a list of files. Must not be empty. + * @throws InternalError + */ + public FileList(ArrayList content) throws InternalError { + /* assert to help debugging */ + assert !content.isEmpty() : "Payload size of FileList must not be empty, use EmptyDirectory from Payload instead"; + if (content.isEmpty()) { + throws new InternalError(); + } this.content = content; } + /** Constructor (typically used by client) with a byte[] parameter containing the datagram received. + * @param datagram the full datagram received + * @throws ProtocolError + * @throws InternalError + */ public FileList(byte[] datagram) throws ProtocolError, InternalError { //TODO /* assert to help debugging */ @@ -24,8 +45,12 @@ public class FileList extends Payload { int size = getPayloadSize(datagram); } - /** To datagram with padding */ - public byte[] toDatagram() { + /** Returns a byte[] containing datagram with padding. + * This datagram is still incomplete and should not be send directly. + * ProtocolP2PDatagram will use this method to generate the complete datagram. + * @return datagram with padding + */ + protected byte[] toDatagram() { byte[] datagram; // java initialize all to zero // size is keep blank (ProtocolP2PDatagram will handle it) // set request/response code diff --git a/src/protocolP2P/FilePart.java b/src/protocolP2P/FilePart.java index 984e98a..bc05a3e 100644 --- a/src/protocolP2P/FilePart.java +++ b/src/protocolP2P/FilePart.java @@ -4,6 +4,12 @@ import protocolP2P.RequestResponseCode; import exception.ProtocolError; import exception.InternalError; +/** Representation of payload for load response. + * @author Louis Royer + * @author Flavien Haas + * @author JS Auge + * @version 1.0 + */ public class FilePart extends Payload { private static final RequestResponseCode requestResponseCode = RequestResponseCode.LOAD_RESPONSE; private String filename; @@ -11,6 +17,12 @@ public class FilePart extends Payload { private int offset; private byte[] partialContent; + /** Constructor (typically used by server) with informations about file part to send as parameters. + * @param filename name of the file to send + * @param totalSize total size of the file to send + * @param offset where in the file begins the part we are sending + * @param partialContent content of the file we send + */ public FilePart(String filename, int totalSize, int offset, byte[] partialContent) { this.filename = filename; this.totalSize = totalSize; @@ -18,6 +30,11 @@ public class FilePart extends Payload { this.partialContent = partialContent; } + /** Constructor (typically used by client) with datagram received as parameter. + * @param datagram the full datagram received + * @throws ProtocolError + * @throws InternalError + */ public FilePart(byte[] datagram) throws ProtocolError, InternalError { //TODO /* assert to help debugging */ @@ -29,7 +46,11 @@ public class FilePart extends Payload { int size = getPayloadSize(datagram); } - /** To datagram with padding */ + /** Returns a byte[] containing datagram with padding. + * This datagram is still incomplete and should not be send directly. + * ProtocolP2PDatagram will use this method to generate the complete datagram. + * @return datagram with padding + */ public byte[] toDatagram() { byte[] datagram; // java initialize all to zero // size is keep blank (ProtocolP2PDatagram will handle it) diff --git a/src/protocolP2P/Payload.java b/src/protocolP2P/Payload.java index 4e3cc6c..220e323 100644 --- a/src/protocolP2P/Payload.java +++ b/src/protocolP2P/Payload.java @@ -4,13 +4,21 @@ import protocolP2P.FilePart; import protocolP2P.FileList; import exception.ProtocolError; import exception.InternalError; - +/** Representation of payload. If payload has a size, use subclasses instead. + * @author Louis Royer + * @author Flavien Haas + * @author JS Auge + * @version 1.0 + */ public class Payload { private RequestResponseCode requestResponseCode; protected final static int PAYLOAD_SIZE_POSITON = 4; protected final static int PAYLOAD_START_POSITION = 8; - /** To create request/response with a payload size of zero */ + /** Consructor used to create Payload with a payload size of zero using a RRCode. + * @param requestResponseCode Request/Response code associated with the payload + * @throws InternalError + */ public Payload(RequestResponseCode requestResponseCode) throws InternalError { /* asserts to help debugging */ assert requestResponseCode != requestResponseCode.LIST_RESPONSE : "LIST_RESPONSE must use FilePart class"; @@ -19,6 +27,12 @@ public class Payload { checkRequestResponseCode(); // this can throw InternalError } + /** Constructor used to create a Payload (when no more specific subclasses exists) using datagram as parameter. + * If payload size is not empty, using subclass is required. + * @param datagram the full datagram received + * @throws ProtocolError + * @throws InternalError + */ public Payload(byte[] datagram) throws ProtocolError, InternalError { /* asserts to help debugging */ assert RequestResponseCode.fromCode(datagram[RequestResponseCode.RRCODE_POSITION]) != RequestResponseCode.LIST_RESPONSE : "LIST_RESPONSE must use FilePart class"; @@ -27,6 +41,9 @@ public class Payload { checkRequestResponseCode(); // this can throw InternalError } + /** Used to check RRCode used is compatible with this class use, or if a more specific subclass is required. + * @throws InternalError + */ private void checkRequestResponseCode() throws InternalError { /* Incorrect use cases (use subclasses instead) */ if (requestResponseCode == RequestResponseCode.LIST_RESPONSE || requestResponseCode == RequestResponseCode.LOAD_RESPONSE) { @@ -34,7 +51,11 @@ public class Payload { } } - /** Payload with padding */ + /** Returns a byte[] containing datagram with padding. + * This datagram is still incomplete and should not be send directly. + * ProtocolP2PDatagram will use this method to generate the complete datagram. + * @return datagram with padding + */ public byte[] toDatagram() { byte [] datagram = new byte[8]; // java initialize all to zero // size is keep blank (ProtocolP2PDatagram will handle it) @@ -44,6 +65,11 @@ public class Payload { // payload size is 0 (this is what java have initialized datagram) } + /** Set payload’s size in a datagram. + * @param size integer representing payload size + * @param datagram datagram to be completed + * @return datagram with payload’s size set + */ protected static byte[] setPayloadSize(int size, byte[] datagram) { for(int i=0;i<4;i++) { datagram[Payload.PAYLOAD_SIZE_POSITON + i] = (byte) (size >> (8 * (3 - i)) & 0xFF); @@ -51,7 +77,11 @@ public class Payload { } return datagram; } - + + /** Get payload’s size from a datagram. + * @param datagram the full datagram received + * @return integer representing payload size + */ protected static int getPayloadSize(byte[] datagram) { int size = 0; for(int i=0;i<4;i++) { diff --git a/src/protocolP2P/ProtocolP2PDatagram.java b/src/protocolP2P/ProtocolP2PDatagram.java index 5ae58a9..31ae53f 100644 --- a/src/protocolP2P/ProtocolP2PDatagram.java +++ b/src/protocolP2P/ProtocolP2PDatagram.java @@ -6,17 +6,31 @@ import protocolP2P.RequestResponseCode; import java.util.ArrayList; import java.lang.Byte; +/** Representation of datagram. + * @author Louis Royer + * @author Flavien Haas + * @author JS Auge + * @version 1.0 + */ public class ProtocolP2PDatagram { private final static byte PROTOCOL_VERSION = 0x11; private final static int VERSION_POSITON = 0; private byte version; private Payload payload; + /** Constructor with payload parameter (typically used when sending datagram). + * @param payload the payload associated with the datagram to send + */ public ProtocolP2PDatagram(Payload payload) { version = PROTOCOL_VERSION; this.payload = payload; } + /** Constructor with datagram as byte[] parameter (typically used when receiving datagram). + * @param datagram the full datagram received + * @throws ProtocolError + * @throws VersionError + */ public ProtocolP2PDatagram(byte[] datagram) throws ProtocolError, VersionError { // unwrap version version = datagram[VERSION_POSITON]; @@ -35,16 +49,26 @@ public class ProtocolP2PDatagram { } } + /** Returns a byte[] containing full datagram (typically used when sending datagram). + * This datagram is still complete and ready to be send. + * @return the full datagram to send + */ public byte[] toDatagram() { byte[] datagram = payload.toDatagram(); datagram[VERSION_POSITON] = version; return datagram; } + /** Returns Payload associated with the datagram. + * @return payload associated with the datagram + */ public Payload getPayload() { return payload; } + /** Used to check protocol version when a datagram is constructed from bytes[]. + * @throws VersionError + */ private void checkProtocolVersion() throws VersionError { if (PROTOCOL_VERSION != version) { throw new VersionError();