beam-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tg...@apache.org
Subject [2/3] beam git commit: Update Coder Documentation
Date Wed, 10 May 2017 17:26:37 GMT
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 <tgroh@google.com>
Authored: Tue May 9 18:09:12 2017 -0700
Committer: Thomas Groh <tgroh@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();


Mime
View raw message