Add class comments

5 files changed, 32 insertions, 0 deletions

diff --git a/clustercontroller-core/src/main/java/com/yahoo/vespa/clustercontroller/core/rpc/ClusterStateBundleCodec.java b/clustercontroller-core/src/main/java/com/yahoo/vespa/clustercontroller/core/rpc/ClusterStateBundleCodec.java
index 4200aec55a9..250d7bbe46a 100644
--- a/clustercontroller-core/src/main/java/com/yahoo/vespa/clustercontroller/core/rpc/ClusterStateBundleCodec.java
+++ b/clustercontroller-core/src/main/java/com/yahoo/vespa/clustercontroller/core/rpc/ClusterStateBundleCodec.java
@@ -3,6 +3,15 @@ package com.yahoo.vespa.clustercontroller.core.rpc;
 
 import com.yahoo.vespa.clustercontroller.core.ClusterStateBundle;
 
+/**
+ * Provides opaque encoding and decoding of ClusterStateBundles for transmission over RPC.
+ *
+ * Implementations may choose to compress the encoded representation of the bundle.
+ *
+ * It is important that the input given to decode() is exactly equal to that given from
+ * encode() for the results to be correct. Implementations must ensure that this information
+ * is enough to losslessly reconstruct the full encoded ClusterStateBundle.
+ */
 public interface ClusterStateBundleCodec {
 
     EncodedClusterStateBundle encode(ClusterStateBundle stateBundle);
diff --git a/clustercontroller-core/src/main/java/com/yahoo/vespa/clustercontroller/core/rpc/EncodedClusterStateBundle.java b/clustercontroller-core/src/main/java/com/yahoo/vespa/clustercontroller/core/rpc/EncodedClusterStateBundle.java
index d502c5ce598..784c8c23c87 100644
--- a/clustercontroller-core/src/main/java/com/yahoo/vespa/clustercontroller/core/rpc/EncodedClusterStateBundle.java
+++ b/clustercontroller-core/src/main/java/com/yahoo/vespa/clustercontroller/core/rpc/EncodedClusterStateBundle.java
@@ -3,6 +3,13 @@ package com.yahoo.vespa.clustercontroller.core.rpc;
 
 import com.yahoo.compress.Compressor;
 
+/**
+ * Contains an opaque encoded (possibly compressed) representation of a ClusterStateBundle.
+ *
+ * This bundle can in turn be sent over the wire or serialized by ensuring that all components
+ * of the Compressor.Compression state can be reconstructed by the receiver. In practice this
+ * means sending the Compression's <em>type</em>, <em>uncompressedSize</em> and <em>data</em>.
+ */
 public class EncodedClusterStateBundle {
 
     private final Compressor.Compression compression;
diff --git a/clustercontroller-core/src/main/java/com/yahoo/vespa/clustercontroller/core/rpc/SlimeClusterStateBundleCodec.java b/clustercontroller-core/src/main/java/com/yahoo/vespa/clustercontroller/core/rpc/SlimeClusterStateBundleCodec.java
index eb6c2280491..c37bd8313a9 100644
--- a/clustercontroller-core/src/main/java/com/yahoo/vespa/clustercontroller/core/rpc/SlimeClusterStateBundleCodec.java
+++ b/clustercontroller-core/src/main/java/com/yahoo/vespa/clustercontroller/core/rpc/SlimeClusterStateBundleCodec.java
@@ -11,6 +11,14 @@ import com.yahoo.vespa.clustercontroller.core.ClusterStateBundle;
 import java.util.HashMap;
 import java.util.Map;
 
+/**
+ * Implementation of ClusterStateBundleCodec which uses structured Slime binary encoding
+ * to implement (de-)serialization of ClusterStateBundle instances. Encoding format is
+ * intentionally extensible so that we may add other information to it later.
+ *
+ * LZ4 compression is transparently applied during encoding and decompression is
+ * subsequently applied during decoding.
+ */
 public class SlimeClusterStateBundleCodec implements ClusterStateBundleCodec {
 
     private static final Compressor compressor = new Compressor(CompressionType.LZ4, 3, 0.90, 1024);
diff --git a/clustercontroller-core/src/test/java/com/yahoo/vespa/clustercontroller/core/ClusterStateBundleUtil.java b/clustercontroller-core/src/test/java/com/yahoo/vespa/clustercontroller/core/ClusterStateBundleUtil.java
index 31adb93fc49..e097874682a 100644
--- a/clustercontroller-core/src/test/java/com/yahoo/vespa/clustercontroller/core/ClusterStateBundleUtil.java
+++ b/clustercontroller-core/src/test/java/com/yahoo/vespa/clustercontroller/core/ClusterStateBundleUtil.java
@@ -6,6 +6,10 @@ import com.yahoo.vdslib.state.ClusterState;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
+/**
+ * Helper functions for constructing a ClusterStateBundle for a baseline state and zero or more
+ * explicit bucket space states.
+ */
 public class ClusterStateBundleUtil {
 
     public static ClusterStateBundle makeBundle(String baselineState, StateMapping... bucketSpaceStates) {
diff --git a/clustercontroller-core/src/test/java/com/yahoo/vespa/clustercontroller/core/StateMapping.java b/clustercontroller-core/src/test/java/com/yahoo/vespa/clustercontroller/core/StateMapping.java
index f88802c09ef..f6eaf86e8f4 100644
--- a/clustercontroller-core/src/test/java/com/yahoo/vespa/clustercontroller/core/StateMapping.java
+++ b/clustercontroller-core/src/test/java/com/yahoo/vespa/clustercontroller/core/StateMapping.java
@@ -3,6 +3,10 @@ package com.yahoo.vespa.clustercontroller.core;
 
 import com.yahoo.vdslib.state.ClusterState;
 
+/**
+ * Tuple representing a mapping from a named bucket space to the derived ClusterState
+ * for that space.
+ */
 public class StateMapping {
 
     final String bucketSpace;