Code/Projects/PacketLevelSignatureExtractor/src/main/java/edu/uci/iotproject/detection/AbstractClusterMatcher.java

   1 package edu.uci.iotproject.detection;
   2
   3 import org.pcap4j.core.PcapPacket;
   4
   5 import java.util.ArrayList;
   6 import java.util.List;
   7 import java.util.Objects;
   8
   9 /**
  10  * Base class for classes that search a traffic trace for sequences of packets that "belong to" a given cluster (in
  11  * other words, classes that attempt to classify traffic as pertaining to a given cluster).
  12  *
  13  * @author Janus Varmarken {@literal <jvarmark@uci.edu>}
  14  * @author Rahmadi Trimananda {@literal <rtrimana@uci.edu>}
  15  */
  16 abstract public class AbstractClusterMatcher {
  17
  18     /**
  19      * The cluster that describes the sequence of packets that this {@link AbstractClusterMatcher} is trying to detect
  20      * in the observed traffic.
  21      */
  22     protected final List<List<PcapPacket>> mCluster;
  23
  24     /**
  25      * Observers registered for callbacks from this {@link AbstractClusterMatcher}.
  26      */
  27     protected final List<ClusterMatcherObserver> mObservers;
  28
  29     protected AbstractClusterMatcher(List<List<PcapPacket>> cluster) {
  30         // ===================== PRECONDITION SECTION =====================
  31         cluster = Objects.requireNonNull(cluster, "cluster cannot be null");
  32         if (cluster.isEmpty() || cluster.stream().anyMatch(inner -> inner.isEmpty())) {
  33             throw new IllegalArgumentException("cluster is empty (or contains an empty inner List)");
  34         }
  35         for (List<PcapPacket> clusterMember : cluster) {
  36             if (clusterMember.size() != cluster.get(0).size()) {
  37                 throw new IllegalArgumentException("All sequences in cluster must contain the same number of packets");
  38             }
  39         }
  40         // ================================================================
  41         // Let the subclass prune the provided cluster
  42         mCluster = pruneCluster(cluster);
  43         mObservers = new ArrayList<>();
  44     }
  45
  46     /**
  47      * Register for callbacks from this cluster matcher.
  48      * @param observer The target of the callbacks.
  49      */
  50     public final void addObserver(ClusterMatcherObserver observer) {
  51         mObservers.add(observer);
  52     }
  53
  54     /**
  55      * Deregister for callbacks from this cluster matcher.
  56      * @param observer The callback target that is to be deregistered.
  57      */
  58     public final void removeObserver(ClusterMatcherObserver observer) {
  59         mObservers.remove(observer);
  60     }
  61
  62     /**
  63      * Allows subclasses to specify how to prune the input cluster provided to the constructor.
  64      * @param cluster The input cluster provided to the constructor.
  65      * @return The pruned cluster to use in place of the input cluster.
  66      */
  67     abstract protected List<List<PcapPacket>> pruneCluster(List<List<PcapPacket>> cluster);
  68
  69     // TODO: move Direction outside Conversation so that this is less confusing.
  70 //    abstract protected Conversation.Direction[] getPacketDirections(List<PcapPacket> packets);
  71
  72 }