From e3aba38bac1fab9d9d922b24f6b777d401fc68d9 Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Tue, 9 Feb 2016 10:57:20 -0500 Subject: [PATCH] Javadoc for common.io.stream Adds some javadoc to Streamable, Writeable, and friends. --- .../common/io/stream/StreamInput.java | 20 ++++++++-------- .../common/io/stream/StreamOutput.java | 11 ++++++--- .../common/io/stream/Streamable.java | 17 +++++++++++++- .../common/io/stream/StreamableReader.java | 12 +++++++--- .../common/io/stream/Writeable.java | 14 +++++++++-- .../common/io/stream/package-info.java | 23 +++++++++++++++++++ 6 files changed, 77 insertions(+), 20 deletions(-) create mode 100644 core/src/main/java/org/elasticsearch/common/io/stream/package-info.java diff --git a/core/src/main/java/org/elasticsearch/common/io/stream/StreamInput.java b/core/src/main/java/org/elasticsearch/common/io/stream/StreamInput.java index 868880276ec..8eda42ae9be 100644 --- a/core/src/main/java/org/elasticsearch/common/io/stream/StreamInput.java +++ b/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(); - } - - protected StreamInput(NamedWriteableRegistry namedWriteableRegistry) { - this.namedWriteableRegistry = namedWriteableRegistry; - } - + /** + * The version of the node on the other side of this stream. + */ 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; } diff --git a/core/src/main/java/org/elasticsearch/common/io/stream/StreamOutput.java b/core/src/main/java/org/elasticsearch/common/io/stream/StreamOutput.java index fb8c32de154..864da006bf0 100644 --- a/core/src/main/java/org/elasticsearch/common/io/stream/StreamOutput.java +++ b/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 { diff --git a/core/src/main/java/org/elasticsearch/common/io/stream/Streamable.java b/core/src/main/java/org/elasticsearch/common/io/stream/Streamable.java index f2b77113e14..4added7df31 100644 --- a/core/src/main/java/org/elasticsearch/common/io/stream/Streamable.java +++ b/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; } diff --git a/core/src/main/java/org/elasticsearch/common/io/stream/StreamableReader.java b/core/src/main/java/org/elasticsearch/common/io/stream/StreamableReader.java index 28e2175f4ce..6bb1c5653f3 100644 --- a/core/src/main/java/org/elasticsearch/common/io/stream/StreamableReader.java +++ b/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 public static final 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 + * final. + */ public interface StreamableReader { /** - * Reads a copy of an object with the same type form the stream input - * - * The caller object remains unchanged. + * Reads an object of this type from the provided {@linkplain StreamInput}. The receiving instance remains unchanged. */ T readFrom(StreamInput in) throws IOException; } diff --git a/core/src/main/java/org/elasticsearch/common/io/stream/Writeable.java b/core/src/main/java/org/elasticsearch/common/io/stream/Writeable.java index 9025315dc43..9ff3de736c5 100644 --- a/core/src/main/java/org/elasticsearch/common/io/stream/Writeable.java +++ b/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 extends StreamableReader { - /** - * Writes the current object into the output stream out + * Write this into the {@linkplain StreamOutput}. */ void writeTo(StreamOutput out) throws IOException; } diff --git a/core/src/main/java/org/elasticsearch/common/io/stream/package-info.java b/core/src/main/java/org/elasticsearch/common/io/stream/package-info.java new file mode 100644 index 00000000000..6f84f31785c --- /dev/null +++ b/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; \ No newline at end of file