You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@beam.apache.org by ke...@apache.org on 2017/05/04 13:11:33 UTC
[2/8] beam git commit: Annotate internal pieces of sdks.transforms
Annotate internal pieces of sdks.transforms
Project: http://git-wip-us.apache.org/repos/asf/beam/repo
Commit: http://git-wip-us.apache.org/repos/asf/beam/commit/c1b26a1b
Tree: http://git-wip-us.apache.org/repos/asf/beam/tree/c1b26a1b
Diff: http://git-wip-us.apache.org/repos/asf/beam/diff/c1b26a1b
Branch: refs/heads/master
Commit: c1b26a1b53c334ab171fad60501ba67593fde5d2
Parents: f4dfbb2
Author: Kenneth Knowles <kl...@google.com>
Authored: Tue May 2 19:48:38 2017 -0700
Committer: Kenneth Knowles <kl...@google.com>
Committed: Thu May 4 06:09:30 2017 -0700
----------------------------------------------------------------------
.../beam/sdk/transforms/AppliedPTransform.java | 7 ++--
.../beam/sdk/transforms/CombineFnBase.java | 22 ++++++++----
.../beam/sdk/transforms/Materialization.java | 6 +++-
.../beam/sdk/transforms/Materializations.java | 11 ++++--
.../org/apache/beam/sdk/transforms/View.java | 36 +++++++++++++-------
.../org/apache/beam/sdk/transforms/ViewFn.java | 6 +++-
6 files changed, 62 insertions(+), 26 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/beam/blob/c1b26a1b/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/AppliedPTransform.java
----------------------------------------------------------------------
diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/AppliedPTransform.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/AppliedPTransform.java
index bdb61b8..4e049a5 100644
--- a/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/AppliedPTransform.java
+++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/AppliedPTransform.java
@@ -20,16 +20,14 @@ package org.apache.beam.sdk.transforms;
import com.google.auto.value.AutoValue;
import java.util.Map;
import org.apache.beam.sdk.Pipeline;
+import org.apache.beam.sdk.annotations.Internal;
import org.apache.beam.sdk.values.PInput;
import org.apache.beam.sdk.values.POutput;
import org.apache.beam.sdk.values.PValue;
import org.apache.beam.sdk.values.TupleTag;
/**
- * Represents the application of a {@link PTransform} to a specific input to produce
- * a specific output.
- *
- * <p>For internal use.
+ * <b><i>For internal use only; no backwards-compatibility guarantees.</i></b>
*
* <p>Inputs and outputs are stored in their expanded forms, as the condensed form of a composite
* {@link PInput} or {@link POutput} is a language-specific concept, and {@link AppliedPTransform}
@@ -40,6 +38,7 @@ import org.apache.beam.sdk.values.TupleTag;
* @param <OutputT> transform output type
* @param <TransformT> transform type
*/
+@Internal
@AutoValue
public abstract class AppliedPTransform<
InputT extends PInput, OutputT extends POutput,
http://git-wip-us.apache.org/repos/asf/beam/blob/c1b26a1b/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/CombineFnBase.java
----------------------------------------------------------------------
diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/CombineFnBase.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/CombineFnBase.java
index a881099..29990cd 100644
--- a/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/CombineFnBase.java
+++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/CombineFnBase.java
@@ -21,6 +21,7 @@ import com.google.common.collect.ImmutableMap;
import java.io.Serializable;
import java.lang.reflect.Type;
import java.lang.reflect.TypeVariable;
+import org.apache.beam.sdk.annotations.Internal;
import org.apache.beam.sdk.coders.CannotProvideCoderException;
import org.apache.beam.sdk.coders.Coder;
import org.apache.beam.sdk.coders.CoderRegistry;
@@ -31,14 +32,19 @@ import org.apache.beam.sdk.transforms.display.HasDisplayData;
import org.apache.beam.sdk.values.TypeDescriptor;
/**
- * This class contains the shared interfaces and abstract classes for different types of combine
+ * <b><i>For internal use only; no backwards-compatibility guarantees.</i></b>
+ *
+ * <p>This class contains the shared interfaces and abstract classes for different types of combine
* functions.
*
* <p>Users should not implement or extend them directly.
*/
+@Internal
public class CombineFnBase {
/**
- * A {@code GloballyCombineFn<InputT, AccumT, OutputT>} specifies how to combine a
+ * <b><i>For internal use only; no backwards-compatibility guarantees.</i></b>
+ *
+ * <p>A {@code GloballyCombineFn<InputT, AccumT, OutputT>} specifies how to combine a
* collection of input values of type {@code InputT} into a single
* output value of type {@code OutputT}. It does this via one or more
* intermediate mutable accumulator values of type {@code AccumT}.
@@ -50,6 +56,7 @@ public class CombineFnBase {
* @param <AccumT> type of mutable accumulator values
* @param <OutputT> type of output values
*/
+ @Internal
public interface GlobalCombineFn<InputT, AccumT, OutputT> extends Serializable, HasDisplayData {
/**
@@ -93,16 +100,19 @@ public class CombineFnBase {
}
/**
- * An abstract {@link GlobalCombineFn} base class shared by
- * {@link CombineFn} and {@link CombineFnWithContext}.
+ * <b><i>For internal use only; no backwards-compatibility guarantees.</i></b>
*
- * <p>Do not extend this class directly.
- * Extends {@link CombineFn} and {@link CombineFnWithContext} instead.
+ * <p>An abstract {@link GlobalCombineFn} base class shared by {@link CombineFn} and {@link
+ * CombineFnWithContext}.
+ *
+ * <p>Do not extend this class directly. Extends {@link CombineFn} and {@link
+ * CombineFnWithContext} instead.
*
* @param <InputT> type of input values
* @param <AccumT> type of mutable accumulator values
* @param <OutputT> type of output values
*/
+ @Internal
abstract static class AbstractGlobalCombineFn<InputT, AccumT, OutputT>
implements GlobalCombineFn<InputT, AccumT, OutputT>, Serializable {
private static final String INCOMPATIBLE_GLOBAL_WINDOW_ERROR_MESSAGE =
http://git-wip-us.apache.org/repos/asf/beam/blob/c1b26a1b/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/Materialization.java
----------------------------------------------------------------------
diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/Materialization.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/Materialization.java
index 7cd6256..6fb8c29 100644
--- a/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/Materialization.java
+++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/Materialization.java
@@ -18,15 +18,19 @@
package org.apache.beam.sdk.transforms;
+import org.apache.beam.sdk.annotations.Internal;
import org.apache.beam.sdk.runners.PipelineRunner;
/**
- * How a view should be physically materialized by a {@link PipelineRunner}.
+ * <b><i>For internal use only; no backwards-compatibility guarantees.</i></b>
+ *
+ * <p>How a view should be physically materialized by a {@link PipelineRunner}.
*
* <p>A {@link PipelineRunner} will support some set of materializations, and will reject
* {@link ViewFn ViewFns} that require materializations it does not support. See
* {@link Materializations} for known implementations.
*/
+@Internal
public interface Materialization<T> {
/**
* Gets the URN describing this {@link Materialization}. This is a stable, SDK-independent URN
http://git-wip-us.apache.org/repos/asf/beam/blob/c1b26a1b/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/Materializations.java
----------------------------------------------------------------------
diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/Materializations.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/Materializations.java
index 35925fa..6e4f83d 100644
--- a/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/Materializations.java
+++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/Materializations.java
@@ -20,12 +20,16 @@ package org.apache.beam.sdk.transforms;
import org.apache.beam.sdk.annotations.Experimental;
import org.apache.beam.sdk.annotations.Experimental.Kind;
+import org.apache.beam.sdk.annotations.Internal;
import org.apache.beam.sdk.util.WindowedValue;
/**
- * Utility methods for constructing known {@link Materialization materializations} for a
+ * <b><i>For internal use only; no backwards-compatibility guarantees.</i></b>
+ *
+ * <p>Utility methods for constructing known {@link Materialization materializations} for a
* {@link ViewFn}.
*/
+@Internal
public class Materializations {
/**
* The URN for a {@link Materialization} where the primitive view type is an iterable of fully
@@ -36,9 +40,12 @@ public class Materializations {
"urn:beam:sideinput:materialization:iterable:0.1";
/**
- * A {@link Materialization} where the primitive view type is an iterable of fully specified
+ * <b><i>For internal use only; no backwards-compatibility guarantees.</i></b>
+ *
+ * <p>A {@link Materialization} where the primitive view type is an iterable of fully specified
* windowed values.
*/
+ @Internal
public static <T> Materialization<Iterable<WindowedValue<T>>> iterable() {
return new IterableMaterialization<>();
}
http://git-wip-us.apache.org/repos/asf/beam/blob/c1b26a1b/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/View.java
----------------------------------------------------------------------
diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/View.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/View.java
index b3b8918..d17d423 100644
--- a/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/View.java
+++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/View.java
@@ -19,6 +19,7 @@ package org.apache.beam.sdk.transforms;
import java.util.List;
import java.util.Map;
+import org.apache.beam.sdk.annotations.Internal;
import org.apache.beam.sdk.coders.Coder;
import org.apache.beam.sdk.coders.CoderException;
import org.apache.beam.sdk.runners.PipelineRunner;
@@ -237,11 +238,13 @@ public class View {
}
/**
- * Not intended for direct use by pipeline authors; public only so a {@link PipelineRunner} may
- * override its behavior.
+ * <b><i>For internal use only; no backwards-compatibility guarantees.</i></b>
+ *
+ * <p>Public only so a {@link PipelineRunner} may override its behavior.
*
* <p>See {@link View#asList()}.
*/
+ @Internal
public static class AsList<T> extends PTransform<PCollection<T>, PCollectionView<List<T>>> {
private AsList() { }
@@ -259,11 +262,13 @@ public class View {
}
/**
- * Not intended for direct use by pipeline authors; public only so a {@link PipelineRunner} may
- * override its behavior.
+ * <b><i>For internal use only; no backwards-compatibility guarantees.</i></b>
+ *
+ * <p>Public only so a {@link PipelineRunner} may override its behavior.
*
* <p>See {@link View#asIterable()}.
*/
+ @Internal
public static class AsIterable<T>
extends PTransform<PCollection<T>, PCollectionView<Iterable<T>>> {
private AsIterable() { }
@@ -282,11 +287,13 @@ public class View {
}
/**
- * Not intended for direct use by pipeline authors; public only so a {@link PipelineRunner} may
- * override its behavior.
+ * <b><i>For internal use only; no backwards-compatibility guarantees.</i></b>
+ *
+ * <p>Public only so a {@link PipelineRunner} may override its behavior.
*
* <p>See {@link View#asSingleton()}.
*/
+ @Internal
public static class AsSingleton<T> extends PTransform<PCollection<T>, PCollectionView<T>> {
private final T defaultValue;
private final boolean hasDefault;
@@ -396,11 +403,13 @@ public class View {
}
/**
- * Not intended for direct use by pipeline authors; public only so a {@link PipelineRunner} may
- * override its behavior.
+ * <b><i>For internal use only; no backwards-compatibility guarantees.</i></b>
+ *
+ * <p>Public only so a {@link PipelineRunner} may override its behavior.
*
* <p>See {@link View#asMultimap()}.
*/
+ @Internal
public static class AsMultimap<K, V>
extends PTransform<PCollection<KV<K, V>>, PCollectionView<Map<K, Iterable<V>>>> {
private AsMultimap() { }
@@ -422,11 +431,13 @@ public class View {
}
/**
- * Not intended for direct use by pipeline authors; public only so a {@link PipelineRunner} may
- * override its behavior.
+ * <b><i>For internal use only; no backwards-compatibility guarantees.</i></b>
+ *
+ * <p>Public only so a {@link PipelineRunner} may override its behavior.
*
* <p>See {@link View#asMap()}.
*/
+ @Internal
public static class AsMap<K, V>
extends PTransform<PCollection<KV<K, V>>, PCollectionView<Map<K, V>>> {
private AsMap() { }
@@ -459,13 +470,14 @@ public class View {
// Internal details below
/**
- * Creates a primitive {@link PCollectionView}.
+ * <b><i>For internal use only; no backwards-compatibility guarantees.</i></b>
*
- * <p>For internal use only by runner implementors.
+ * <p>Creates a primitive {@link PCollectionView}.
*
* @param <ElemT> The type of the elements of the input PCollection
* @param <ViewT> The type associated with the {@link PCollectionView} used as a side input
*/
+ @Internal
public static class CreatePCollectionView<ElemT, ViewT>
extends PTransform<PCollection<ElemT>, PCollectionView<ViewT>> {
private PCollectionView<ViewT> view;
http://git-wip-us.apache.org/repos/asf/beam/blob/c1b26a1b/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/ViewFn.java
----------------------------------------------------------------------
diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/ViewFn.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/ViewFn.java
index cdfcb88..d51a917 100644
--- a/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/ViewFn.java
+++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/ViewFn.java
@@ -18,11 +18,14 @@
package org.apache.beam.sdk.transforms;
import java.io.Serializable;
+import org.apache.beam.sdk.annotations.Internal;
import org.apache.beam.sdk.values.PCollection;
import org.apache.beam.sdk.values.PCollectionView;
/**
- * A function to adapt a primitive "view" of a {@link PCollection} - some materialization
+ * <b><i>For internal use only; no backwards-compatibility guarantees.</i></b>
+ *
+ * <p>A function to adapt a primitive "view" of a {@link PCollection} - some materialization
* specified in the Beam model and implemented by the runner - to a user-facing view type
* for side input.
*
@@ -36,6 +39,7 @@ import org.apache.beam.sdk.values.PCollectionView;
* @param <PrimitiveViewT> the type of the underlying primitive view, provided by the runner
* {@code <ViewT>} the type of the value(s) accessible via this {@link PCollectionView}
*/
+@Internal
public abstract class ViewFn<PrimitiveViewT, ViewT> implements Serializable {
/**
* Gets the materialization of this {@link ViewFn}.