You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@beam.apache.org by tg...@apache.org on 2017/05/10 17:26:37 UTC
[2/3] beam git commit: Update Coder Documentation
Update Coder Documentation
Project: http://git-wip-us.apache.org/repos/asf/beam/repo
Commit: http://git-wip-us.apache.org/repos/asf/beam/commit/01b3f87f
Tree: http://git-wip-us.apache.org/repos/asf/beam/tree/01b3f87f
Diff: http://git-wip-us.apache.org/repos/asf/beam/diff/01b3f87f
Branch: refs/heads/master
Commit: 01b3f87f977d44eac23eb5488074bbc638858a9d
Parents: 0b15956
Author: Thomas Groh <tg...@google.com>
Authored: Tue May 9 18:09:12 2017 -0700
Committer: Thomas Groh <tg...@google.com>
Committed: Wed May 10 10:26:24 2017 -0700
----------------------------------------------------------------------
.../org/apache/beam/sdk/coders/AtomicCoder.java | 17 +++++++++++++--
.../java/org/apache/beam/sdk/coders/Coder.java | 22 +++++++-------------
.../org/apache/beam/sdk/coders/CustomCoder.java | 17 +++++----------
.../apache/beam/sdk/coders/StructuredCoder.java | 10 +++++----
4 files changed, 34 insertions(+), 32 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/beam/blob/01b3f87f/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/AtomicCoder.java
----------------------------------------------------------------------
diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/AtomicCoder.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/AtomicCoder.java
index 7bcd532..b244ed5 100644
--- a/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/AtomicCoder.java
+++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/AtomicCoder.java
@@ -35,14 +35,22 @@ public abstract class AtomicCoder<T> extends StructuredCoder<T> {
/**
* {@inheritDoc}.
*
- * @throws NonDeterministicException
+ * <p>Unless overridden, does not throw. An {@link AtomicCoder} is presumed to be deterministic
+ *
+ * @throws NonDeterministicException if overridden to indicate that this sublcass of
+ * {@link AtomicCoder} is not deterministic
*/
@Override
public void verifyDeterministic() throws NonDeterministicException {}
+ /**
+ * {@inheritDoc}.
+ *
+ * @return the empty list
+ */
@Override
public List<? extends Coder<?>> getCoderArguments() {
- return null;
+ return Collections.emptyList();
}
/**
@@ -65,6 +73,11 @@ public abstract class AtomicCoder<T> extends StructuredCoder<T> {
return other != null && this.getClass().equals(other.getClass());
}
+ /**
+ * {@inheritDoc}.
+ *
+ * @return the {@link #hashCode()} of the {@link Class} of this {@link AtomicCoder}.
+ */
@Override
public final int hashCode() {
return this.getClass().hashCode();
http://git-wip-us.apache.org/repos/asf/beam/blob/01b3f87f/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/Coder.java
----------------------------------------------------------------------
diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/Coder.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/Coder.java
index 2ee532d..edcc3a8 100644
--- a/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/Coder.java
+++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/Coder.java
@@ -43,23 +43,17 @@ import org.apache.beam.sdk.values.TypeDescriptor;
* byte streams.
*
* <p>{@link Coder} instances are serialized during job creation and deserialized
- * before use, via JSON serialization. See {@link SerializableCoder} for an example of a
- * {@link Coder} that adds a custom field to
- * the {@link Coder} serialization. It provides a constructor annotated with
- * {@link com.fasterxml.jackson.annotation.JsonCreator}, which is a factory method used when
- * deserializing a {@link Coder} instance.
+ * before use. This will generally be performed by serializing the object via Java Serialization.
*
* <p>{@link Coder} classes for compound types are often composed from coder classes for types
* contains therein. The composition of {@link Coder} instances into a coder for the compound
* class is the subject of the {@link CoderProvider} type, which enables automatic generic
- * composition of {@link Coder} classes within the {@link CoderRegistry}. With particular
- * static methods on a compound {@link Coder} class, a {@link CoderProvider} can be automatically
- * inferred. See {@link KvCoder} for an example of a simple compound {@link Coder} that supports
- * automatic composition in the {@link CoderRegistry}.
+ * composition of {@link Coder} classes within the {@link CoderRegistry}. See {@link CoderProvider}
+ * and {@link CoderRegistry} for more information about how coders are inferred.
*
* <p>All methods of a {@link Coder} are required to be thread safe.
*
- * @param <T> the type of the values being transcoded
+ * @param <T> the type of values being encoded and decoded
*/
public abstract class Coder<T> implements Serializable {
/** The context in which encoding or decoding is being done. */
@@ -167,10 +161,10 @@ public abstract class Coder<T> implements Serializable {
}
/**
- * If this is a {@code Coder} for a parameterized type, returns the
- * list of {@code Coder}s being used for each of the parameters, or
- * returns {@code null} if this cannot be done or this is not a
- * parameterized type.
+ * If this is a {@link Coder} for a parameterized type, returns the
+ * list of {@link Coder}s being used for each of the parameters in the same order they appear
+ * within the parameterized type's type signature. If this cannot be done, or this
+ * {@link Coder} does not encode/decode a parameterized type, returns the empty list.
*/
public abstract List<? extends Coder<?>> getCoderArguments();
http://git-wip-us.apache.org/repos/asf/beam/blob/01b3f87f/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/CustomCoder.java
----------------------------------------------------------------------
diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/CustomCoder.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/CustomCoder.java
index c581923..e8ce5b1 100644
--- a/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/CustomCoder.java
+++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/CustomCoder.java
@@ -22,19 +22,12 @@ import java.util.Collections;
import java.util.List;
/**
- * An abstract base class for writing a {@link Coder} class that encodes itself via Java
- * serialization.
+ * An abstract base class that implements all methods of {@link Coder} except {@link Coder#encode}
+ * and {@link Coder#decode}.
*
- * <p>To complete an implementation, subclasses must implement {@link Coder#encode}
- * and {@link Coder#decode} methods.
- *
- * <p>Not to be confused with {@link SerializableCoder} that encodes objects that implement the
- * {@link Serializable} interface.
- *
- * @param <T> the type of elements handled by this coder
+ * @param <T> the type of values being encoded and decoded
*/
-public abstract class CustomCoder<T> extends Coder<T>
- implements Serializable {
+public abstract class CustomCoder<T> extends Coder<T> implements Serializable {
/**
* {@inheritDoc}.
@@ -61,5 +54,5 @@ public abstract class CustomCoder<T> extends Coder<T>
// This coder inherits isRegisterByteSizeObserverCheap,
// getEncodedElementByteSize and registerByteSizeObserver
- // from StructuredCoder. Override if we can do better.
+ // from Coder. Override if we can do better.
}
http://git-wip-us.apache.org/repos/asf/beam/blob/01b3f87f/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/StructuredCoder.java
----------------------------------------------------------------------
diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/StructuredCoder.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/StructuredCoder.java
index 42c0598..a145215 100644
--- a/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/StructuredCoder.java
+++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/StructuredCoder.java
@@ -33,11 +33,11 @@ import org.apache.beam.sdk.values.TypeDescriptor;
* <p>To extend {@link StructuredCoder}, override the following methods as appropriate:
*
* <ul>
- * <li>{@link #getComponents}: the default implementation returns {@link #getCoderArguments}.</li>
- * <li>{@link #getEncodedElementByteSize} and
- * {@link #isRegisterByteSizeObserverCheap}: the
+ * <li>{@link #getComponents}: the default implementation returns {@link #getCoderArguments}.
+ * <li>{@link #getEncodedElementByteSize} and {@link #isRegisterByteSizeObserverCheap}: the
* default implementation encodes values to bytes and counts the bytes, which is considered
- * expensive.</li>
+ * expensive. The default element byte size observer uses the value returned by
+ * {@link #getEncodedElementByteSize}.
* </ul>
*/
public abstract class StructuredCoder<T> extends Coder<T> {
@@ -45,6 +45,8 @@ public abstract class StructuredCoder<T> extends Coder<T> {
/**
* Returns the list of {@link Coder Coders} that are components of this {@link Coder}.
+ *
+ * <p>The default components will be equal to the value returned by {@link #getCoderArguments()}.
*/
public List<? extends Coder<?>> getComponents() {
List<? extends Coder<?>> coderArguments = getCoderArguments();