From 17133cd4b8b50640ec8b35a34cb80285eec52989 Mon Sep 17 00:00:00 2001
From: Janus Varmarken <varmarken@gmail.com>
Date: Wed, 25 Jul 2018 17:03:30 -0700
Subject: [PATCH] TcpConversationUtils.java: added Javadoc

---
 .../analysis/TcpConversationUtils.java        | 25 +++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)

diff --git a/Code/Projects/SmartPlugDetector/src/main/java/edu/uci/iotproject/analysis/TcpConversationUtils.java b/Code/Projects/SmartPlugDetector/src/main/java/edu/uci/iotproject/analysis/TcpConversationUtils.java
index 2f5f415..77c7743 100644
--- a/Code/Projects/SmartPlugDetector/src/main/java/edu/uci/iotproject/analysis/TcpConversationUtils.java
+++ b/Code/Projects/SmartPlugDetector/src/main/java/edu/uci/iotproject/analysis/TcpConversationUtils.java
@@ -10,12 +10,26 @@ import org.pcap4j.packet.TcpPacket;
 import java.util.*;
 
 /**
- * TODO add class documentation.
+ * Utility functions for analyzing and structuring (sets of) {@link Conversation}s.
  *
- * @author Janus Varmarken
+ * @author Janus Varmarken {@literal <jvarmark@uci.edu>}
+ * @author Rahmadi Trimananda {@literal <rtrimana@uci.edu>}
  */
 public class TcpConversationUtils {
 
+
+    /**
+     * <p>
+     *      Given a {@link Conversation}, extract its set of "packet pairs", i.e., pairs of request-reply packets.
+     * </p>
+     *
+     * <b>Note:</b> in the current implementation, if one endpoint sends multiple packets back-to-back with no
+     * interleaved reply packets from the other endpoint, such packets are converted to one-item pairs (i.e., instances
+     * of {@lin PcapPacketPair} where {@link PcapPacketPair#getSecond()} is {@code null}).
+     *
+     * @param conv The {@code Conversation} for which packet pairs are to be extracted.
+     * @return The packet pairs extracted from {@code conv}.
+     */
     public static List<PcapPacketPair> extractPacketPairs(Conversation conv) {
         List<PcapPacket> packets = conv.getPackets();
         List<PcapPacketPair> pairs = new ArrayList<>();
@@ -49,6 +63,13 @@ public class TcpConversationUtils {
     }
 
 
+    /**
+     * Given a list of TCP conversations and associated DNS mappings, groups the conversations by hostname.
+     * @param tcpConversations The list of TCP conversations.
+     * @param ipHostnameMappings The associated DNS mappings.
+     * @return A map where each key is a hostname and its associated value is a list of conversations where one of the
+     *         two communicating hosts is that hostname (i.e. its IP maps to the hostname).
+     */
     public static Map<String, List<Conversation>> groupConversationsByHostname(List<Conversation> tcpConversations, DnsMap ipHostnameMappings) {
         HashMap<String, List<Conversation>> result = new HashMap<>();
         for (Conversation c : tcpConversations) {
-- 
2.34.1