add some comments

[iotcloud.git] / src / java / iotcloud / Slot.java

diff --git a/src/java/iotcloud/Slot.java b/src/java/iotcloud/Slot.java
index 9de69db52d06dd09f786f15a2fc0e9cfce917c52..6604894e0e364e3cf556f254ac828ba4a74394d6 100644 (file)
--- a/src/java/iotcloud/Slot.java
+++ b/src/java/iotcloud/Slot.java
@@ -4,18 +4,36 @@ import java.nio.ByteBuffer;
 import javax.crypto.Mac;
 import java.util.Arrays;
 
+/**
+ * Data structuring for holding Slot information.
+ * @author Brian Demsky
+ * @version 1.0
+ */
+
 class Slot implements Liveness {
+       /** Sets the slot size. */
        static final int SLOT_SIZE=2048;
+       /** Sets how many bytes we reserve. */
        static final int RESERVED_SPACE=64;
+       /** Sets the size for the HMAC. */
        static final int HMAC_SIZE=32;
 
+       /** Sequence number of the slot. */
        private long seqnum;
+       /** HMAC of previous slot. */
        private byte[] prevhmac;
+       /** HMAC of this slot. */
        private byte[] hmac;
+       /** Machine that sent this slot. */
        private long machineid;
+       /** Vector of entries in this slot. */
        private Vector<Entry> entries;
+       /** Pieces of information that are live. */
        private int livecount;
+       /** Flag that indicates whether this slot is still live for
+        * recording the machine that sent it. */
        private boolean seqnumlive;
+       /** Number of bytes of free space. */
        private int freespace;
 
        Slot(long _seqnum, long _machineid, byte[] _prevhmac, byte[] _hmac) {
@@ -51,11 +69,19 @@ class Slot implements Liveness {
                freespace -= e.getSize();
        }
 
+       /**
+        * Returns true if the slot has free space to hold the entry without
+        * using its reserved space. */
+
        boolean hasSpace(Entry e) {
                int newfreespace = freespace - e.getSize();
                return newfreespace > RESERVED_SPACE;
        }
 
+       /**
+        * Returns true if the slot can fit the entry potentially using the
+        * reserved space. */
+
        boolean canFit(Entry e) {
                int newfreespace = freespace - e.getSize();
                return newfreespace >= 0;
@@ -92,7 +118,8 @@ class Slot implements Liveness {
        byte[] encode(Mac mac) {
                byte[] array=new byte[SLOT_SIZE];
                ByteBuffer bb=ByteBuffer.wrap(array);
-               bb.position(HMAC_SIZE);                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 //Leave space for the HMACs
+               /* Leave space for the slot HMAC.  */
+               bb.position(HMAC_SIZE);
                bb.put(prevhmac);
                bb.putLong(seqnum);
                bb.putLong(machineid);
@@ -100,7 +127,7 @@ class Slot implements Liveness {
                for(Entry entry:entries) {
                        entry.encode(bb);
                }
-               //Compute our HMAC
+               /* Compute our HMAC */
                mac.update(array, HMAC_SIZE, array.length-HMAC_SIZE);
                byte[] realmac=mac.doFinal();
                hmac = realmac;
@@ -109,10 +136,20 @@ class Slot implements Liveness {
                return array;
        }
 
+       /**
+        * Returns the empty size of a Slot. Includes 2 HMACs, the machine
+        * identifier, the sequence number, and the number of entries.
+        */
        int getBaseSize() {
                return 2*HMAC_SIZE+2*Long.BYTES+Integer.BYTES;
        }
 
+       /**
+        * Returns the live set of entries for this Slot.  Generates a fake
+        * LastMessage entry to represent the information stored by the slot
+        * itself.
+        */
+
        Vector<Entry> getLiveEntries() {
                Vector<Entry> liveEntries=new Vector<Entry>();
                for(Entry entry: entries)
@@ -125,23 +162,44 @@ class Slot implements Liveness {
                return liveEntries;
        }
 
+       /**
+        * Returns the sequence number of the slot.
+        */
+
        long getSequenceNumber() {
                return seqnum;
        }
 
+       /**
+        * Returns the machine that sent this slot.
+        */
+
        long getMachineID() {
                return machineid;
        }
 
+       /**
+        * Records that a newer slot records the fact that this slot was
+        * sent by the relevant machine.
+        */
+
        void setDead() {
                decrementLiveCount();
                seqnumlive=false;
        }
 
+       /**
+        * Update the count of live entries.
+        */
+
        void decrementLiveCount() {
                livecount--;
        }
 
+       /**
+        * Returns whether the slot stores any live information.
+        */
+
        boolean isLive() {
                return livecount > 0;
        }