Javadoc for common.io.stream

Adds some javadoc to Streamable, Writeable, and friends.

core/src/main/java/org/elasticsearch/common/io/stream/StreamInput.java

@@ -69,24 +69,22 @@ import java.util.function.Supplier;
 import static org.elasticsearch.ElasticsearchException.readException;
 import static org.elasticsearch.ElasticsearchException.readStackTrace;
 
+/**
+ * A stream from this node to another node. Technically, it can also be streamed to a byte array but that is mostly for testing.
+ */
 public abstract class StreamInput extends InputStream {
-
-    private final NamedWriteableRegistry namedWriteableRegistry;
-
     private Version version = Version.CURRENT;
 
-    protected StreamInput() {
+    /**
-        this.namedWriteableRegistry = new NamedWriteableRegistry();
+     * The version of the node on the other side of this stream.
-    }
+     */
-
-    protected StreamInput(NamedWriteableRegistry namedWriteableRegistry) {
-        this.namedWriteableRegistry = namedWriteableRegistry;
-    }
-
     public Version getVersion() {
         return this.version;
     }
 
+    /**
+     * Set the version of the node on the other side of this stream.
+     */
     public void setVersion(Version version) {
         this.version = version;
     }

core/src/main/java/org/elasticsearch/common/io/stream/StreamOutput.java

@@ -60,19 +60,24 @@ import java.util.List;
 import java.util.Map;
 
 /**
- *
+ * A stream from another node to this node. Technically, it can also be streamed from a byte array but that is mostly for testing.
  */
 public abstract class StreamOutput extends OutputStream {
 
     private Version version = Version.CURRENT;
 
+    /**
+     * The version of the node on the other side of this stream.
+     */
     public Version getVersion() {
         return this.version;
     }
 
-    public StreamOutput setVersion(Version version) {
+    /**
+     * Set the version of the node on the other side of this stream.
+     */
+    public void setVersion(Version version) {
         this.version = version;
-        return this;
     }
 
     public long position() throws IOException {

core/src/main/java/org/elasticsearch/common/io/stream/Streamable.java

@@ -22,11 +22,26 @@ package org.elasticsearch.common.io.stream;
 import java.io.IOException;
 
 /**
+ * Implementers can be written to a {@linkplain StreamOutput} and read from a {@linkplain StreamInput}. This allows them to be "thrown
+ * across the wire" using Elasticsearch's internal protocol. If the implementer also implements equals and hashCode then a copy made by
+ * serializing and deserializing must be equal and have the same hashCode. It isn't required that such a copy be entirely unchanged. For
+ * example, {@link org.elasticsearch.common.unit.TimeValue} converts the time to nanoseconds for serialization.
  *
+ * Prefer implementing {@link Writeable} over implementing this interface where possible. Lots of code depends on this interface so this
+ * isn't always possible.
+ *
+ * Implementers of this interface almost always declare a no arg constructor that is exclusively used for creating "empty" objects on which
+ * you then call {@link #readFrom(StreamInput)}. Because {@linkplain #readFrom(StreamInput)} isn't part of the constructor the fields
+ * on implementers cannot be final. It is these reasons that this interface has fallen out of favor compared to {@linkplain Writeable}.
  */
 public interface Streamable {
-
+    /**
+     * Set this object's fields from a {@linkplain StreamInput}.
+     */
     void readFrom(StreamInput in) throws IOException;
 
+    /**
+     * Write this object's fields to a {@linkplain StreamOutput}.
+     */
     void writeTo(StreamOutput out) throws IOException;
 }

core/src/main/java/org/elasticsearch/common/io/stream/StreamableReader.java

@@ -20,11 +20,17 @@ package org.elasticsearch.common.io.stream;
 
 import java.io.IOException;
 
+/**
+ * Implementers can be read from {@linkplain StreamInput} by calling their {@link #readFrom(StreamInput)} method.
+ *
+ * It is common for implementers of this interface to declare a <code>public static final</code> instance of themselves named PROTOTYPE so
+ * users can call {@linkplain #readFrom(StreamInput)} on it. It is also fairly typical for readFrom to be implemented as a method that just
+ * calls a constructor that takes {@linkplain StreamInput} as a parameter. This allows the fields in the implementer to be
+ * <code>final</code>.
+ */
 public interface StreamableReader<T> {
     /**
-     * Reads a copy of an object with the same type form the stream input
+     * Reads an object of this type from the provided {@linkplain StreamInput}. The receiving instance remains unchanged.
-     *
-     * The caller object remains unchanged.
      */
     T readFrom(StreamInput in) throws IOException;
 }

core/src/main/java/org/elasticsearch/common/io/stream/Writeable.java

@@ -21,10 +21,20 @@ package org.elasticsearch.common.io.stream;
 
 import java.io.IOException;
 
+/**
+ * Implementers can be written to a {@linkplain StreamOutput} and read from a {@linkplain StreamInput}. This allows them to be "thrown
+ * across the wire" using Elasticsearch's internal protocol. If the implementer also implements equals and hashCode then a copy made by
+ * serializing and deserializing must be equal and have the same hashCode. It isn't required that such a copy be entirely unchanged. For
+ * example, {@link org.elasticsearch.common.unit.TimeValue} converts the time to nanoseconds for serialization.
+ * {@linkplain org.elasticsearch.common.unit.TimeValue} actually implements {@linkplain Streamable} not {@linkplain Writeable} but it has
+ * the same contract.
+ *
+ * Prefer implementing this interface over implementing {@link Streamable} where possible. Lots of code depends on {@linkplain Streamable}
+ * so this isn't always possible.
+ */
 public interface Writeable<T> extends StreamableReader<T> {
-
     /**
-     * Writes the current object into the output stream out
+     * Write this into the {@linkplain StreamOutput}.
      */
     void writeTo(StreamOutput out) throws IOException;
 }

core/src/main/java/org/elasticsearch/common/io/stream/package-info.java

@@ -0,0 +1,23 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * Classes for streaming objects from one Elasticsearch node to another over its binary internode protocol.
+ */
+package org.elasticsearch.common.io.stream;