Merge pull request #5 from informatik-ag-ngl/f/unified_message

Replaced Message inheritance architecture by MessageAttachment class, added documentation

src/main/java/envoy/data/LoginCredentials.java

@@ -6,6 +6,8 @@ import java.security.NoSuchAlgorithmException;
 import java.util.Formatter;
 
 /**
+ * Contains a {@link User}'s login information.<br>
+ * <br>
  * Project: <strong>envoy-common</strong><br>
  * File: <strong>LoginCredentials.java</strong><br>
  * Created: <strong>29.12.2019</strong><br>
@@ -25,24 +27,15 @@ public class LoginCredentials implements Serializable {
 	 *
 	 * @param name     the name of the user
 	 * @param password the password of the user (will be converted to a hash)
-	 * @throws NoSuchAlgorithmException
+	 * @throws NoSuchAlgorithmException if the algorithm used is unknown
+	 * @since Envoy Common v0.2-alpha
 	 */
 	public LoginCredentials(String name, char[] password) throws NoSuchAlgorithmException {
 		this.name		= name;
 		passwordHash	= getSha256(toByteArray(password));
 	}
 
-	@Override
+	private byte[] getSha256(byte[] input) throws NoSuchAlgorithmException { return MessageDigest.getInstance("SHA-256").digest(input); }
-	public String toString() {
-		Formatter form = new Formatter();
-		form.format("LoginCredentials[name=%s,passwordHash=", name);
-		for (int i = 0; i < passwordHash.length; i++)
-			form.format("%02x", passwordHash[i]);
-		form.format("]");
-		String str = form.toString();
-		form.close();
-		return str;
-	}
 
 	private byte[] toByteArray(char[] chars) {
 		byte[] bytes = new byte[chars.length * 2];
@@ -53,9 +46,14 @@ public class LoginCredentials implements Serializable {
 		return bytes;
 	}
 
-	private byte[] getSha256(byte[] input) throws NoSuchAlgorithmException {
+	@Override
-		MessageDigest md = MessageDigest.getInstance("SHA-256");
+	public String toString() {
-		return md.digest(input);
+		try (Formatter form = new Formatter()) {
+			form.format("LoginCredentials[name=%s,passwordHash=", name);
+			for (byte element : passwordHash)
+				form.format("%02x", element);
+			return form.format("]").toString();
+		}
 	}
 
 	/**

src/main/java/envoy/data/Message.java

@@ -1,6 +1,7 @@
 package envoy.data;
 
 import java.io.Serializable;
+import java.text.SimpleDateFormat;
 import java.util.Date;
 
 /**
@@ -13,66 +14,78 @@ import java.util.Date;
  * Created: <strong>28.12.2019</strong><br>
  *
  * @author Kai S. K. Engelbart
+ * @author Leon Hofmeister
  * @since Envoy Common v0.2-alpha
  */
-public abstract class Message implements Serializable {
+public class Message implements Serializable {
 
-	private final long	id;
+	/**
-	private final User	sender, recipient;
+	 * This enumeration defines all possible statuses a {link Message} can have.
+	 *
+	 * @since Envoy Common v0.2-alpha
+	 */
+	public static enum MessageStatus {
+
+		/**
+		 * is selected, if a message was sent but not received by the server yet.
+		 */
+		WAITING,
+
+		/**
+		 * is selected, if a sent message was received by the server.
+		 */
+		SENT,
+
+		/**
+		 * is selected, if a message was delivered from the server to the recipient, but
+		 * has not been read yet.
+		 */
+		RECEIVED,
+
+		/**
+		 * is selected, if a recipient opened the corresponding chat of said message.
+		 */
+		READ
+	}
+
+	private final long					id, senderId, recipientId;
+	private final transient User		sender, recipient;
 	private final Date					date;
+	private final String				text;
+	private final MessageAttachment<?>	attachment;
 
 	private MessageStatus status;
 
 	private static final long serialVersionUID = -4393477412979594435L;
 
 	/**
-	 * Initializes a {@link Message} from the client's perspective. The current date
+	 * Initializes a {@link Message} with values for all of its properties. The use
-	 * is used as the message date and the status is set to
+	 * of this constructor is only intended for the {@link MessageBuilder} class, as
-	 * {@link MessageStatus#WAITING}.
+	 * this class provides {@code null} checks and default values for all
+	 * properties.
 	 *
 	 * @param id         unique ID
 	 * @param sender     the user who sends the message
 	 * @param recipient  the user who receives the message
+	 * @param date       the creation date of the message
+	 * @param text       the text content of the message
+	 * @param attachment the attachment of the message, if present
+	 * @param status     the current {@link MessageStatus} of the message
 	 * @since Envoy Common v0.2-alpha
 	 */
-	public Message(long id, User sender, User recipient) {
+	Message(long id, User sender, User recipient, Date date, String text, MessageAttachment<?> attachment, MessageStatus status) {
 		this.id			= id;
 		this.sender		= sender;
 		this.recipient	= recipient;
-		date			= new Date();
+		this.date		= date;
-		status			= MessageStatus.WAITING;
+		this.text		= text;
+		this.attachment	= attachment;
+		this.status		= status;
+
+		senderId	= sender.getId();
+		recipientId	= recipient.getId();
 	}
 
-	/**
-	 * @return the ID of this message
-	 * @since Envoy Common v0.2-alpha
-	 */
-	public long getId() { return id; }
-
-	/**
-	 * @return the sender of this message
-	 * @since Envoy Common v0.2-alpha
-	 */
-	public User getSender() { return sender; }
-
-	/**
-	 * @return the recipient of this message
-	 * @since Envoy Common v0.2-alpha
-	 */
-	public User getRecipient() { return recipient; }
-
-	/**
-	 * @return the date at which this message was created
-	 * @since Envoy Common v0.2-alpha
-	 */
-	public Date getDate() { return date; }
-
-	/**
-	 * @return the current status of this message
-	 * @since Envoy Common v0.2-alpha
-	 */
-	public MessageStatus getStatus() { return status; }
-
 	/**
 	 * Changes the current {@link MessageStatus} to the next logical status.<br>
 	 * <br>
@@ -91,7 +104,68 @@ public abstract class Message implements Serializable {
 		status = MessageStatus.values()[status.ordinal() + 1];
 	}
 
-	public static enum MessageStatus {
+	@Override
-		WAITING, SENT, RECEIVED, READ
+	public String toString() {
+		return String.format("TextMessage[id=%d,sender=%s,recipient=%s,date=%s,status=%s,text=%s]",
+				id,
+				sender,
+				recipient,
+				new SimpleDateFormat("dd.MM.yyyy HH:mm:ss").format(date),
+				status,
+				text);
 	}
+
+	/**
+	 * @return the ID of this message
+	 * @since Envoy Common v0.2-alpha
+	 */
+	public long getId() { return id; }
+
+	/**
+	 * @return the sender of this message
+	 * @since Envoy Common v0.2-alpha
+	 */
+	public User getSender() { return sender; }
+
+	/**
+	 * @return the sender ID of this message
+	 * @since Envoy Common v0.2-alpha
+	 */
+	public long getSenderId() { return senderId; }
+
+	/**
+	 * @return the recipient of this message
+	 * @since Envoy Common v0.2-alpha
+	 */
+	public User getRecipient() { return recipient; }
+
+	/**
+	 * @return the recipient ID of this message
+	 * @since Envoy Common v0.2-alpha
+	 */
+	public long getRecipientId() { return recipientId; }
+
+	/**
+	 * @return the date at which this message was created
+	 * @since Envoy Common v0.2-alpha
+	 */
+	public Date getDate() { return date; }
+
+	/**
+	 * @return the text content of this message
+	 * @since Envoy Common v0.2-alpha
+	 */
+	public String getText() { return text; }
+
+	/**
+	 * @return the messageAttachment
+	 * @since Envoy Common v0.2-alpha
+	 */
+	public MessageAttachment<?> getAttachment() { return attachment; }
+
+	/**
+	 * @return the current status of this message
+	 * @since Envoy Common v0.2-alpha
+	 */
+	public MessageStatus getStatus() { return status; }
 }

src/main/java/envoy/data/MessageAttachment.java

@@ -0,0 +1,24 @@
+package envoy.data;
+
+import java.io.Serializable;
+
+/**
+ * This interface should be used for any type supposed to be a {@link Message}
+ * attachment (i.e. images or sound).<br>
+ * <br>
+ * Project: <strong>envoy-common</strong><br>
+ * File: <strong>MessageAttachment.java</strong><br>
+ * Created: <strong>30 Dec 2019</strong><br>
+ *
+ * @author Leon Hofmeister
+ * @param <T> the type of this message attachment
+ * @since Envoy Common v0.2-alpha
+ */
+public interface MessageAttachment<T> extends Serializable {
+
+	/**
+	 * @return the type implementing this interface
+	 * @since Envoy Common v0.2-alpha
+	 */
+	T get();
+}

src/main/java/envoy/data/MessageBuilder.java

@@ -0,0 +1,125 @@
+package envoy.data;
+
+import java.util.Date;
+
+import envoy.data.Message.MessageStatus;
+
+/**
+ * Provides a method of constructing the {@link Message} class.<br>
+ * <br>
+ * Project: <strong>envoy-common</strong><br>
+ * File: <strong>MessageBuilder.java</strong><br>
+ * Created: <strong>31.12.2019</strong><br>
+ * 
+ * @author Kai S. K. Engelbart
+ * @since Envoy Common v0.2-alpha
+ */
+public class MessageBuilder {
+
+	// Mandatory properties without default values
+	private final User sender, recipient;
+
+	// Properties with default values
+	private long					id;
+	private Date					date;
+	private String					text;
+	private MessageAttachment<?>	attachment;
+	private Message.MessageStatus	status;
+
+	/**
+	 * Creates an instance of {@link MessageBuilder} with all mandatory values
+	 * without defaults for the {@link Message} class.
+	 *
+	 * @param sender    the user who sends the {@link Message}
+	 * @param recipient the user who received the {@link Message}
+	 * @since Envoy Common v0.2-alpha
+	 */
+	public MessageBuilder(User sender, User recipient) {
+		if (sender == null) throw new NullPointerException("Message sender is null");
+		if (recipient == null) throw new NullPointerException("Message recipient is null");
+		this.sender		= sender;
+		this.recipient	= recipient;
+	}
+
+	/**
+	 * Creates an instance of {@link Message} with the previously supplied values.
+	 * If a mandatory value is not set, a default value will be used instead:<br>
+	 * <br>
+	 * <table border="1">
+	 * <tr>
+	 * <td>{@code date}</td>
+	 * <td>{@code new Date()}</td>
+	 * <tr>
+	 * <tr>
+	 * <td>{@code text}</td>
+	 * <td>{@code ""}</td>
+	 * <tr>
+	 * <tr>
+	 * <td>{@code status}</td>
+	 * <td>{@code MessageStatus.WAITING}</td>
+	 * <tr>
+	 * </table>
+	 * 
+	 * @return a new instance of {@link Message}
+	 * @since Envoy Common v0.2-alpha
+	 */
+	public Message build() {
+		// Supplement default values
+		if (date == null) date = new Date();
+		if (text == null) text = "";
+		if (status == null) status = MessageStatus.WAITING;
+
+		return new Message(id, sender, recipient, date, text, attachment, status);
+	}
+
+	/**
+	 * @param id the unique ID of the {@link Message} to create
+	 * @return this {@link MessageBuilder}
+	 * @since Envoy Common v0.2-alpha
+	 */
+	public MessageBuilder setId(long id) {
+		this.id = id;
+		return this;
+	}
+
+	/**
+	 * @param date the creation date of the {@link Message} to create
+	 * @return this {@link MessageBuilder}
+	 * @since Envoy Common v0.2-alpha
+	 */
+	public MessageBuilder setDate(Date date) {
+		this.date = date;
+		return this;
+	}
+
+	/**
+	 * @param text the text of the {@link Message} to create
+	 * @return this {@link MessageBuilder}
+	 * @since Envoy Common v0.2-alpha
+	 */
+	public MessageBuilder setText(String text) {
+		this.text = text;
+		return this;
+	}
+
+	/**
+	 * @param attachment the {@link MessageAttachment} of the {@link Message} to
+	 *                   create
+	 * @return this {@link MessageBuilder}
+	 * @since Envoy Common v0.2-alpha
+	 */
+	public MessageBuilder setAttachment(MessageAttachment<?> attachment) {
+		this.attachment = attachment;
+		return this;
+	}
+
+	/**
+	 * @param status the {@link MessageStatus} of the {@link Message} to create
+	 * @return this {@link MessageBuilder}
+	 * @since Envoy Common v0.2-alpha
+	 */
+	public MessageBuilder setStatus(Message.MessageStatus status) {
+		this.status = status;
+		return this;
+	}
+}

src/main/java/envoy/data/MessageIdGenerator.java

@@ -0,0 +1,44 @@
+package envoy.data;
+
+/**
+ * Generates increasing IDs between two numbers.<br>
+ * <br>
+ * Project: <strong>envoy-common</strong><br>
+ * File: <strong>MessageIdGenerator.java</strong><br>
+ * Created: <strong>31.12.2019</strong><br>
+ * 
+ * @author Kai S. K. Engelbart
+ * @since Envoy Common v0.2-alpha
+ */
+public class MessageIdGenerator {
+
+	private final long	end;
+	private long		current;
+
+	/**
+	 * Creates an instance of {@link MessageIdGenerator}.
+	 *
+	 * @param begin the first ID
+	 * @param end   the last ID
+	 * @since Envoy Common v0.2-alpha
+	 */
+	public MessageIdGenerator(long begin, long end) {
+		current		= begin;
+		this.end	= end;
+	}
+
+	/**
+	 * @return {@code true} if there are unused IDs remaining
+	 * @since Envoy Common v0.2-alpha
+	 */
+	public boolean hasNext() { return current < end; }
+
+	/**
+	 * @return the next ID
+	 * @since Envoy Common v0.2-alpha
+	 */
+	public long next() {
+		if (!hasNext()) throw new IllegalStateException("All IDs have been used");
+		return current++;
+	}
+}

src/main/java/envoy/data/TextMessage.java

@@ -1,54 +0,0 @@
-package envoy.data;
-
-import java.text.SimpleDateFormat;
-
-/**
- * Represents a {@link Message} with content that is comprised of text.<br>
- * <br>
- * Project: <strong>envoy-common</strong><br>
- * File: <strong>TextMessage.java</strong><br>
- * Created: <strong>28.12.2019</strong><br>
- * 
- * @author Kai S. K. Engelbart
- * @since Envoy Common v0.2-alpha
- */
-public class TextMessage extends Message {
-
-	private final String content;
-
-	private static final long serialVersionUID = 1538164720632899917L;
-
-	/**
-	 * Initializes a {@link TextMessage} from the client's perspective. The current
-	 * date
-	 * is used as the message date and the status is set to
-	 * {@link envoy.data.Message.MessageStatus#WAITING}.
-	 * 
-	 * @param id        unique ID
-	 * @param sender    the user who sends the message
-	 * @param recipient the user who receives the message
-	 * @param content   the content of the message
-	 * @since Envoy Common v0.2-alpha
-	 */
-	public TextMessage(long id, User sender, User recipient, String content) {
-		super(id, sender, recipient);
-		this.content = content;
-	}
-
-	@Override
-	public String toString() {
-		return String.format("TextMessage[id=%d,sender=%s,recipient=%s,date=%s,status=%s,content=%s]",
-				getId(),
-				getSender(),
-				getRecipient(),
-				new SimpleDateFormat("dd.MM.yyyy HH:mm:ss").format(getDate()),
-				getStatus(),
-				content);
-	}
-
-	/**
-	 * @return the content of this {@link TextMessage}
-	 * @since Envoy Common v0.2-alpha
-	 */
-	public String getContent() { return content; }
-}

src/main/java/envoy/data/User.java

@@ -1,6 +1,8 @@
 package envoy.data;
 
 import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.List;
 
 /**
  * Represents a unique user with a unique, numeric ID, a name and a current
@@ -15,8 +17,38 @@ import java.io.Serializable;
  */
 public class User implements Serializable {
 
+	/**
+	 * This enumeration defines all possible statuses a user can have.
+	 *
+	 * @since Envoy Common v0.2-alpha
+	 */
+	public static enum UserStatus {
+
+		/**
+		 * select this, if a user is online and can be interacted with
+		 */
+		ONLINE,
+
+		/**
+		 * select this, if a user is online but unavailable at the moment (sudden
+		 * interruption)
+		 */
+		AWAY,
+
+		/**
+		 * select this, if a user is online but unavailable at the moment (polite way)
+		 */
+		BUSY,
+
+		/**
+		 * select this, if a user is offline
+		 */
+		OFFLINE;
+	}
+
 	private final long			id;
 	private final String		name;
+	private final List<User>	contacts	= new ArrayList<>();
 
 	private UserStatus status;
 
@@ -51,6 +83,12 @@ public class User implements Serializable {
 	 */
 	public String getName() { return name; }
 
+	/**
+	 * @return a list of all users this user can send messages to
+	 * @since Envoy Client v0.2-alpha
+	 */
+	public List<User> getContacts() { return contacts; }
+
 	/**
 	 * @return the current status of this user
 	 * @since Envoy Client v0.2-alpha
@@ -64,8 +102,4 @@ public class User implements Serializable {
 	 * @since Envoy Client v0.2-alpha
 	 */
 	public void setStatus(UserStatus status) { this.status = status; }
-
-	public static enum UserStatus {
-		ONLINE, AWAY, BUSY, OFFLINE;
-	}
 }

src/main/java/envoy/event/MessageEvent.java

@@ -11,6 +11,9 @@ import envoy.data.Message;
  */
 public class MessageEvent implements Event<Message> {
 
+	/**
+	 * the {@link Message} attached to this {@link MessageEvent}.
+	 */
 	protected final Message message;
 
 	/**

src/main/java/envoy/exception/EnvoyException.java

@@ -12,9 +12,24 @@ public class EnvoyException extends Exception {
 
 	private static final long serialVersionUID = 2096147309395387479L;
 
-	public EnvoyException(String message, Throwable cause) { super(message, cause); }
+	/**
-
+	 * @param message the message to display once this Exception is thrown
+	 * @since Envoy Common v0.2-alpha
+	 */
 	public EnvoyException(String message) { super(message); }
 
+	/**
+	 * @param message the message to display once this Exception is thrown
+	 * @param cause   the {@link Throwable} which resulted in the throw of an
+	 *                EnvoyException
+	 * @since Envoy Common v0.2-alpha
+	 */
+	public EnvoyException(String message, Throwable cause) { super(message, cause); }
+
+	/**
+	 * @param cause the {@link Throwable} which resulted in the throw of an
+	 *              EnvoyException
+	 * @since Envoy Common v0.2-alpha
+	 */
 	public EnvoyException(Throwable cause) { super(cause); }
 }

src/main/java/envoy/util/SerializationUtils.java

@@ -11,8 +11,6 @@ import java.io.ObjectOutputStream;
 import java.io.OutputStream;
 import java.io.Serializable;
 
-import envoy.exception.EnvoyException;
-
 /**
  * Project: <strong>envoy-client</strong><br>
  * File: <strong>SerializationUtils.java</strong><br>
@@ -23,16 +21,19 @@ import envoy.exception.EnvoyException;
  */
 public class SerializationUtils {
 
-	private SerializationUtils() {}
+	private static byte[] intToBytes(int n) { return new byte[] { (byte) (n >>> 24), (byte) (n >>> 16), (byte) (n >>> 8), (byte) n }; }
 
 	/**
 	 * Deserializes an arbitrary {@link Serializable} object from a file.
 	 *
 	 * @param <T>             the type of the object to deserialize
-	 * @param file            the file deserialize from
+	 * @param file            the file to deserialize from
 	 * @param serializedClass the class of the object to deserialize
 	 * @return the deserialized object
-	 * @throws EnvoyException if an error occurred during deserialization
+	 * @throws IOException            if something failed while deserializing the
+	 *                                object
+	 * @throws ClassNotFoundException if the deserialized object can not be linked
+	 *                                to a class
 	 * @since Envoy Common v0.2-alpha
 	 */
 	public static <T extends Serializable> T read(File file, Class<T> serializedClass) throws IOException, ClassNotFoundException {
@@ -40,6 +41,18 @@ public class SerializationUtils {
 		return read(new FileInputStream(file), serializedClass);
 	}
 
+	/**
+	 * @param <T>             the deserialized object
+	 * @param in              the {@link InputStream} of a serialized Object
+	 * @param serializedClass the object type to convert the deserialized object
+	 *                        into
+	 * @return the deserialized object
+	 * @throws IOException            if something failed while deserializing the
+	 *                                object
+	 * @throws ClassNotFoundException if the deserialized object can not be linked
+	 *                                to a class
+	 * @since Envoy Common v0.2-alpha
+	 */
 	public static <T extends Serializable> T read(InputStream in, Class<T> serializedClass) throws IOException, ClassNotFoundException {
 		try (ObjectInputStream oin = new ObjectInputStream(in)) {
 			return serializedClass.cast(oin.readObject());
@@ -90,5 +103,5 @@ public class SerializationUtils {
 		out.write(objBytes);
 	}
 
-	private static byte[] intToBytes(int n) { return new byte[] { (byte) (n >>> 24), (byte) (n >>> 16), (byte) (n >>> 8), (byte) n }; }
+	private SerializationUtils() {}
 }