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 <[email protected]> Authored: Tue May 2 19:48:38 2017 -0700 Committer: Kenneth Knowles <[email protected]> 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}.
