honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Javadoc for common.io.stream 

Adds some javadoc to Streamable, Writeable, and friends.
This commit is contained in:
Nik Everett 2016-02-09 10:57:20 -05:00
parent 5d359f737f
commit e3aba38bac
6 changed files with 77 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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;
}

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

@ -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 {

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

@ -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;
}

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

@ -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
*
* 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;
}

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

@ -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;
}

23
core/src/main/java/org/elasticsearch/common/io/stream/package-info.java Normal file
View File

@ -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;