From 0694dcc62a28a98363cdd67a69e3f2c3ce82e072 Mon Sep 17 00:00:00 2001 From: Alex Filatov Date: Mon, 10 Jul 2017 13:20:49 +0300 Subject: [PATCH 1/3] [BEAM-2306] Add checkstyle check to fail the build when @Deprecated is used without @deprecated javadoc (or vice versa). The check is disabled for existing violations where reason for deprecation and/or alternative is not clear. --- .../construction/CreatePCollectionViewTranslation.java | 4 ++++ .../runners/core/construction/PTransformTranslation.java | 2 ++ .../apache/beam/runners/core/InMemoryTimerInternals.java | 9 +++++++++ .../java/org/apache/beam/runners/core/StateTags.java | 3 +++ .../apache/beam/runners/direct/DirectTimerInternals.java | 9 +++++++++ .../translation/wrappers/streaming/DoFnOperator.java | 9 +++++++++ .../org/apache/beam/runners/dataflow/DataflowRunner.java | 2 ++ .../options/DataflowPipelineWorkerPoolOptions.java | 3 +++ .../build-tools/src/main/resources/beam/checkstyle.xml | 8 ++++++++ .../src/main/java/org/apache/beam/sdk/coders/Coder.java | 6 ++++++ .../java/org/apache/beam/sdk/coders/CoderRegistry.java | 6 ++++++ .../src/main/java/org/apache/beam/sdk/io/AvroSource.java | 6 ------ .../main/java/org/apache/beam/sdk/testing/PAssert.java | 5 +++-- .../java/org/apache/beam/sdk/testing/StreamingIT.java | 2 ++ .../java/org/apache/beam/sdk/transforms/Combine.java | 1 - .../main/java/org/apache/beam/sdk/transforms/DoFn.java | 3 +++ .../main/java/org/apache/beam/sdk/transforms/View.java | 2 +- .../apache/beam/sdk/transforms/reflect/DoFnInvokers.java | 9 --------- .../java/org/apache/beam/sdk/util/IdentityWindowFn.java | 2 ++ .../org/apache/beam/sdk/values/PCollectionViews.java | 2 ++ .../src/main/java/org/apache/beam/sdk/values/PValue.java | 4 ++-- .../org/apache/beam/sdk/coders/DefaultCoderTest.java | 3 ++- .../apache/beam/runners/core/BoundedSourceRunner.java | 6 +++--- 23 files changed, 81 insertions(+), 25 deletions(-) diff --git a/runners/core-construction-java/src/main/java/org/apache/beam/runners/core/construction/CreatePCollectionViewTranslation.java b/runners/core-construction-java/src/main/java/org/apache/beam/runners/core/construction/CreatePCollectionViewTranslation.java index 8fc99b9f480f..e8be1370427a 100644 --- a/runners/core-construction-java/src/main/java/org/apache/beam/runners/core/construction/CreatePCollectionViewTranslation.java +++ b/runners/core-construction-java/src/main/java/org/apache/beam/runners/core/construction/CreatePCollectionViewTranslation.java @@ -86,7 +86,9 @@ public static PCollectionView getView( PCollectionView.class.getSimpleName()); } + // CHECKSTYLE.OFF: MissingDeprecated @Deprecated + // CHECKSTYLE.ON: MissingDeprecated static class CreatePCollectionViewTranslator implements TransformPayloadTranslator> { @Override @@ -113,8 +115,10 @@ public FunctionSpec translate( } /** Registers {@link CreatePCollectionViewTranslator}. */ + // CHECKSTYLE.OFF: MissingDeprecated @AutoService(TransformPayloadTranslatorRegistrar.class) @Deprecated + // CHECKSTYLE.ON: MissingDeprecated public static class Registrar implements TransformPayloadTranslatorRegistrar { @Override public Map, ? extends TransformPayloadTranslator> diff --git a/runners/core-construction-java/src/main/java/org/apache/beam/runners/core/construction/PTransformTranslation.java b/runners/core-construction-java/src/main/java/org/apache/beam/runners/core/construction/PTransformTranslation.java index bae7b0574b22..211aa01f036f 100644 --- a/runners/core-construction-java/src/main/java/org/apache/beam/runners/core/construction/PTransformTranslation.java +++ b/runners/core-construction-java/src/main/java/org/apache/beam/runners/core/construction/PTransformTranslation.java @@ -55,7 +55,9 @@ public class PTransformTranslation { // Less well-known. And where shall these live? public static final String WRITE_FILES_TRANSFORM_URN = "urn:beam:transform:write_files:0.1"; + // CHECKSTYLE.OFF: MissingDeprecated @Deprecated + // CHECKSTYLE.ON: MissingDeprecated public static final String CREATE_VIEW_TRANSFORM_URN = "urn:beam:transform:create_view:v1"; private static final Map, TransformPayloadTranslator> diff --git a/runners/core-java/src/main/java/org/apache/beam/runners/core/InMemoryTimerInternals.java b/runners/core-java/src/main/java/org/apache/beam/runners/core/InMemoryTimerInternals.java index e68bb2407c52..c29ea199ae9e 100644 --- a/runners/core-java/src/main/java/org/apache/beam/runners/core/InMemoryTimerInternals.java +++ b/runners/core-java/src/main/java/org/apache/beam/runners/core/InMemoryTimerInternals.java @@ -107,6 +107,9 @@ public void setTimer(StateNamespace namespace, String timerId, Instant target, setTimer(TimerData.of(timerId, namespace, target, timeDomain)); } + /** + * @deprecated use {@link #setTimer(StateNamespace, String, Instant, TimeDomain)}. + */ @Deprecated @Override public void setTimer(TimerData timerData) { @@ -136,6 +139,9 @@ public void deleteTimer(StateNamespace namespace, String timerId, TimeDomain tim throw new UnsupportedOperationException("Canceling a timer by ID is not yet supported."); } + /** + * @deprecated use {@link #deleteTimer(StateNamespace, String, TimeDomain)}. + */ @Deprecated @Override public void deleteTimer(StateNamespace namespace, String timerId) { @@ -145,6 +151,9 @@ public void deleteTimer(StateNamespace namespace, String timerId) { } } + /** + * @deprecated use {@link #deleteTimer(StateNamespace, String, TimeDomain)}. + */ @Deprecated @Override public void deleteTimer(TimerData timer) { diff --git a/runners/core-java/src/main/java/org/apache/beam/runners/core/StateTags.java b/runners/core-java/src/main/java/org/apache/beam/runners/core/StateTags.java index 53f9edcc9f4b..a98f47d02e02 100644 --- a/runners/core-java/src/main/java/org/apache/beam/runners/core/StateTags.java +++ b/runners/core-java/src/main/java/org/apache/beam/runners/core/StateTags.java @@ -302,6 +302,9 @@ public SimpleStateTag(StructuredId id, StateSpec spec) { this.spec = spec; } + /** + * @deprecated use {@link StateSpec#bind} method via {@link #getSpec} for now. + */ @Override @Deprecated public StateT bind(StateTag.StateBinder binder) { diff --git a/runners/direct-java/src/main/java/org/apache/beam/runners/direct/DirectTimerInternals.java b/runners/direct-java/src/main/java/org/apache/beam/runners/direct/DirectTimerInternals.java index a099368855ff..7db12a41030f 100644 --- a/runners/direct-java/src/main/java/org/apache/beam/runners/direct/DirectTimerInternals.java +++ b/runners/direct-java/src/main/java/org/apache/beam/runners/direct/DirectTimerInternals.java @@ -52,6 +52,9 @@ public void setTimer(StateNamespace namespace, String timerId, Instant target, timerUpdateBuilder.setTimer(TimerData.of(timerId, namespace, target, timeDomain)); } + /** + * @deprecated use {@link #setTimer(StateNamespace, String, Instant, TimeDomain)}. + */ @Deprecated @Override public void setTimer(TimerData timerData) { @@ -63,12 +66,18 @@ public void deleteTimer(StateNamespace namespace, String timerId, TimeDomain tim throw new UnsupportedOperationException("Canceling of timer by ID is not yet supported."); } + /** + * @deprecated use {@link #deleteTimer(StateNamespace, String, TimeDomain)}. + */ @Deprecated @Override public void deleteTimer(StateNamespace namespace, String timerId) { throw new UnsupportedOperationException("Canceling of timer by ID is not yet supported."); } + /** + * @deprecated use {@link #deleteTimer(StateNamespace, String, TimeDomain)}. + */ @Deprecated @Override public void deleteTimer(TimerData timerKey) { diff --git a/runners/flink/src/main/java/org/apache/beam/runners/flink/translation/wrappers/streaming/DoFnOperator.java b/runners/flink/src/main/java/org/apache/beam/runners/flink/translation/wrappers/streaming/DoFnOperator.java index 350f32367a84..a80f7b6ab425 100644 --- a/runners/flink/src/main/java/org/apache/beam/runners/flink/translation/wrappers/streaming/DoFnOperator.java +++ b/runners/flink/src/main/java/org/apache/beam/runners/flink/translation/wrappers/streaming/DoFnOperator.java @@ -752,6 +752,9 @@ public void setTimer( setTimer(TimerData.of(timerId, namespace, target, timeDomain)); } + /** + * @deprecated use {@link #setTimer(StateNamespace, String, Instant, TimeDomain)}. + */ @Deprecated @Override public void setTimer(TimerData timerKey) { @@ -770,6 +773,9 @@ public void setTimer(TimerData timerKey) { } } + /** + * @deprecated use {@link #deleteTimer(StateNamespace, String, TimeDomain)}. + */ @Deprecated @Override public void deleteTimer(StateNamespace namespace, String timerId) { @@ -783,6 +789,9 @@ public void deleteTimer(StateNamespace namespace, String timerId, TimeDomain tim "Canceling of a timer by ID is not yet supported."); } + /** + * @deprecated use {@link #deleteTimer(StateNamespace, String, TimeDomain)}. + */ @Deprecated @Override public void deleteTimer(TimerData timerKey) { diff --git a/runners/google-cloud-dataflow-java/src/main/java/org/apache/beam/runners/dataflow/DataflowRunner.java b/runners/google-cloud-dataflow-java/src/main/java/org/apache/beam/runners/dataflow/DataflowRunner.java index 5d9f0f32aca4..afe999c5eade 100644 --- a/runners/google-cloud-dataflow-java/src/main/java/org/apache/beam/runners/dataflow/DataflowRunner.java +++ b/runners/google-cloud-dataflow-java/src/main/java/org/apache/beam/runners/dataflow/DataflowRunner.java @@ -1292,7 +1292,9 @@ public final PCollection expand(PBegin input) { * A marker {@link DoFn} for writing the contents of a {@link PCollection} to a streaming * {@link PCollectionView} backend implementation. */ + // CHECKSTYLE.OFF: MissingDeprecated @Deprecated + // CHECKSTYLE.ON: MissingDeprecated public static class StreamingPCollectionViewWriterFn extends DoFn, T> { private final PCollectionView view; private final Coder dataCoder; diff --git a/runners/google-cloud-dataflow-java/src/main/java/org/apache/beam/runners/dataflow/options/DataflowPipelineWorkerPoolOptions.java b/runners/google-cloud-dataflow-java/src/main/java/org/apache/beam/runners/dataflow/options/DataflowPipelineWorkerPoolOptions.java index 00d2194f1f06..2239462ac2e8 100644 --- a/runners/google-cloud-dataflow-java/src/main/java/org/apache/beam/runners/dataflow/options/DataflowPipelineWorkerPoolOptions.java +++ b/runners/google-cloud-dataflow-java/src/main/java/org/apache/beam/runners/dataflow/options/DataflowPipelineWorkerPoolOptions.java @@ -53,6 +53,9 @@ enum AutoscalingAlgorithmType { /** Use numWorkers machines. Do not autoscale the worker pool. */ NONE("AUTOSCALING_ALGORITHM_NONE"), + /** + * @deprecated use {@link #THROUGHPUT_BASED}. + */ @Deprecated BASIC("AUTOSCALING_ALGORITHM_BASIC"), diff --git a/sdks/java/build-tools/src/main/resources/beam/checkstyle.xml b/sdks/java/build-tools/src/main/resources/beam/checkstyle.xml index ebbaa7df9b12..b2a74a775a84 100644 --- a/sdks/java/build-tools/src/main/resources/beam/checkstyle.xml +++ b/sdks/java/build-tools/src/main/resources/beam/checkstyle.xml @@ -81,6 +81,14 @@ page at http://checkstyle.sourceforge.net/config.html --> + + + + 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 edcc3a81c31d..a336f692de8a 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 @@ -57,7 +57,9 @@ */ public abstract class Coder implements Serializable { /** The context in which encoding or decoding is being done. */ + // CHECKSTYLE.OFF: MissingDeprecated @Deprecated + // CHECKSTYLE.ON: MissingDeprecated @Experimental(Kind.CODER_CONTEXT) public static class Context { /** @@ -128,7 +130,9 @@ public abstract void encode(T value, OutputStream outStream) * for some reason * @throws CoderException if the value could not be encoded for some reason */ + // CHECKSTYLE.OFF: MissingDeprecated @Deprecated + // CHECKSTYLE.ON: MissingDeprecated @Experimental(Kind.CODER_CONTEXT) public void encode(T value, OutputStream outStream, Context context) throws CoderException, IOException { @@ -153,7 +157,9 @@ public void encode(T value, OutputStream outStream, Context context) * for some reason * @throws CoderException if the value could not be decoded for some reason */ + // CHECKSTYLE.OFF: MissingDeprecated @Deprecated + // CHECKSTYLE.ON: MissingDeprecated @Experimental(Kind.CODER_CONTEXT) public T decode(InputStream inStream, Context context) throws CoderException, IOException { diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/CoderRegistry.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/CoderRegistry.java index 2ba548aa5869..55c370497328 100644 --- a/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/CoderRegistry.java +++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/CoderRegistry.java @@ -235,7 +235,9 @@ public Coder getCoder(TypeDescriptor type) throws CannotProvideCoderEx * * @throws CannotProvideCoderException if a {@link Coder} cannot be provided */ + // CHECKSTYLE.OFF: MissingDeprecated @Deprecated + // CHECKSTYLE.ON: MissingDeprecated @Internal public Coder getCoder( TypeDescriptor typeDescriptor, @@ -255,7 +257,9 @@ public Coder getCoder( * * @throws CannotProvideCoderException if a {@link Coder} cannot be provided */ + // CHECKSTYLE.OFF: MissingDeprecated @Deprecated + // CHECKSTYLE.ON: MissingDeprecated @Internal public Coder getOutputCoder( SerializableFunction fn, Coder inputCoder) @@ -277,7 +281,9 @@ public Coder getOutputCoder( * * @throws CannotProvideCoderException if a {@link Coder} cannot be provided */ + // CHECKSTYLE.OFF: MissingDeprecated @Deprecated + // CHECKSTYLE.ON: MissingDeprecated @Internal public Coder getCoder( Class subClass, diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/io/AvroSource.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/io/AvroSource.java index 37bbe46e3a3b..575218bf92ca 100644 --- a/sdks/java/core/src/main/java/org/apache/beam/sdk/io/AvroSource.java +++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/io/AvroSource.java @@ -237,12 +237,6 @@ public void validate() { super.validate(); } - @Deprecated // Added to let DataflowRunner migrate off of this; to be deleted. - public BlockBasedSource createForSubrangeOfFile(String fileName, long start, long end) - throws IOException { - return createForSubrangeOfFile(FileSystems.matchSingleFileSpec(fileName), start, end); - } - @Override public BlockBasedSource createForSubrangeOfFile(Metadata fileMetadata, long start, long end) { byte[] syncMarker = this.syncMarker; diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/PAssert.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/PAssert.java index 6e2b8c66fa41..ed80f2feee35 100644 --- a/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/PAssert.java +++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/PAssert.java @@ -861,8 +861,9 @@ private PCollectionViewAssert satisfies( } /** - * Always throws an {@link UnsupportedOperationException}: users are probably looking for - * {@link #isEqualTo}. + * @throws UnsupportedOperationException always + * @deprecated {@link Object#equals(Object)} is not supported on PAssert objects. If you meant + * to test object equality, use {@link #isEqualTo} instead. */ @Deprecated @Override diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/StreamingIT.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/StreamingIT.java index 427b908238ae..ea61a229121a 100644 --- a/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/StreamingIT.java +++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/StreamingIT.java @@ -30,6 +30,8 @@ * } * */ +// CHECKSTYLE.OFF: MissingDeprecated @Deprecated +// CHECKSTYLE.ONN: MissingDeprecated public interface StreamingIT { } diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/Combine.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/Combine.java index d7effb5f7ed9..c19535263006 100644 --- a/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/Combine.java +++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/Combine.java @@ -1416,7 +1416,6 @@ public static class SimpleCombineFn extends IterableCombineFn { * Returns a {@code CombineFn} that uses the given * {@code SerializableFunction} to combine values. */ - @Deprecated public static SimpleCombineFn of( SerializableFunction, V> combiner) { return new SimpleCombineFn<>(combiner); diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/DoFn.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/DoFn.java index a2e5c162c7cb..fc3681406054 100644 --- a/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/DoFn.java +++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/DoFn.java @@ -683,6 +683,9 @@ public class ProcessContinuation {} /** * Finalize the {@link DoFn} construction to prepare for processing. * This method should be called by runners before any processing methods. + * + * @deprecated use {@link Setup} or {@link StartBundle} instead. This method will be removed in a + * future release. */ @Deprecated public final void prepareForProcessing() {} 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 331b143f76c6..c94fad6a6aa5 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 @@ -497,7 +497,7 @@ public static CreatePCollectionView of( /** * Return the {@link PCollectionView} that is returned by applying this {@link PTransform}. * - *

This should not be used to obtain the output of any given application of this + * @deprecated This should not be used to obtain the output of any given application of this * {@link PTransform}. That should be obtained by inspecting the {@link Node} * that contains this {@link CreatePCollectionView}, as this view may have been replaced within * pipeline surgery. diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/reflect/DoFnInvokers.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/reflect/DoFnInvokers.java index 33c5a6ab2d1f..44b87a07bfe6 100644 --- a/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/reflect/DoFnInvokers.java +++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/reflect/DoFnInvokers.java @@ -17,7 +17,6 @@ */ package org.apache.beam.sdk.transforms.reflect; -import java.io.Serializable; import org.apache.beam.sdk.transforms.DoFn; /** Static utilities for working with {@link DoFnInvoker}. */ @@ -36,13 +35,5 @@ public static DoFnInvoker invokerFor( return ByteBuddyDoFnInvokerFactory.only().newByteBuddyInvoker(fn); } - /** TODO: remove this when Dataflow worker uses the DoFn overload. */ - @Deprecated - @SuppressWarnings({"unchecked"}) - public static DoFnInvoker invokerFor( - Serializable fn) { - return invokerFor((DoFn) fn); - } - private DoFnInvokers() {} } diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/util/IdentityWindowFn.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/util/IdentityWindowFn.java index ef6d83397f45..a018bd69b719 100644 --- a/sdks/java/core/src/main/java/org/apache/beam/sdk/util/IdentityWindowFn.java +++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/util/IdentityWindowFn.java @@ -111,7 +111,9 @@ public WindowMappingFn getDefaultWindowMappingFn() { getClass().getCanonicalName())); } + // CHECKSTYLE.OFF: MissingDeprecated @Deprecated + // CHECKSTYLE.ON: MissingDeprecated @Override public Instant getOutputTime(Instant inputTimestamp, BoundedWindow window) { return inputTimestamp; diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/values/PCollectionViews.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/values/PCollectionViews.java index e17e146353e4..636518b0cfe3 100644 --- a/sdks/java/core/src/main/java/org/apache/beam/sdk/values/PCollectionViews.java +++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/values/PCollectionViews.java @@ -186,7 +186,9 @@ private SingletonViewFn(boolean hasDefault, T defaultValue, Coder valueCoder) /** * Returns if a default value was specified. */ + // CHECKSTYLE.OFF: MissingDeprecated @Deprecated + // CHECKSTYLE.ON: MissingDeprecated @Internal public boolean hasDefault() { return hasDefault; diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/values/PValue.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/values/PValue.java index 108902879236..71f9465f7ff3 100644 --- a/sdks/java/core/src/main/java/org/apache/beam/sdk/values/PValue.java +++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/values/PValue.java @@ -37,8 +37,8 @@ public interface PValue extends POutput, PInput { /** * {@inheritDoc}. * - *

A {@link PValue} always expands into itself. Calling {@link #expand()} on a PValue is almost - * never appropriate. + * @deprecated A {@link PValue} always expands into itself. Calling {@link #expand()} on a PValue + * is almost never appropriate. */ @Deprecated Map, PValue> expand(); diff --git a/sdks/java/core/src/test/java/org/apache/beam/sdk/coders/DefaultCoderTest.java b/sdks/java/core/src/test/java/org/apache/beam/sdk/coders/DefaultCoderTest.java index aa8d94c2c1af..274fef444cf0 100644 --- a/sdks/java/core/src/test/java/org/apache/beam/sdk/coders/DefaultCoderTest.java +++ b/sdks/java/core/src/test/java/org/apache/beam/sdk/coders/DefaultCoderTest.java @@ -89,7 +89,8 @@ public Coder coderFor(TypeDescriptor typeDescriptor, private static class OldCustomSerializableCoder extends SerializableCoder { // Extending SerializableCoder isn't trivial, but it can be done. - @Deprecated // old form using a Class + + // Old form using a Class. @SuppressWarnings("unchecked") public static SerializableCoder of(Class recordType) { checkArgument(OldCustomRecord.class.isAssignableFrom(recordType)); diff --git a/sdks/java/harness/src/main/java/org/apache/beam/runners/core/BoundedSourceRunner.java b/sdks/java/harness/src/main/java/org/apache/beam/runners/core/BoundedSourceRunner.java index 3338c3a8918b..f708d79e79f1 100644 --- a/sdks/java/harness/src/main/java/org/apache/beam/runners/core/BoundedSourceRunner.java +++ b/sdks/java/harness/src/main/java/org/apache/beam/runners/core/BoundedSourceRunner.java @@ -114,9 +114,9 @@ public BoundedSourceRunner createRunnerForPTransform( } /** - * The runner harness is meant to send the source over the Beam Fn Data API which would be - * consumed by the {@link #runReadLoop}. Drop this method once the runner harness sends the - * source instead of unpacking it from the data block of the function specification. + * @deprecated The runner harness is meant to send the source over the Beam Fn Data API which + * would be consumed by the {@link #runReadLoop}. Drop this method once the runner harness sends + * the source instead of unpacking it from the data block of the function specification. */ @Deprecated public void start() throws Exception { From f1a3e1915fe4bc31adec57349050b7e38b2d7caa Mon Sep 17 00:00:00 2001 From: Alex Filatov Date: Tue, 11 Jul 2017 09:27:05 +0300 Subject: [PATCH 2/3] [BEAM-2306] Add missing @deprecated javadocs. --- .../CreatePCollectionViewTranslation.java | 15 ++++++++++----- .../beam/runners/dataflow/DataflowRunner.java | 5 ++--- .../java/org/apache/beam/sdk/coders/Coder.java | 18 +++++++++++------- .../apache/beam/sdk/testing/StreamingIT.java | 6 ++++-- .../apache/beam/sdk/util/IdentityWindowFn.java | 3 --- .../beam/sdk/values/PCollectionViews.java | 3 --- 6 files changed, 27 insertions(+), 23 deletions(-) diff --git a/runners/core-construction-java/src/main/java/org/apache/beam/runners/core/construction/CreatePCollectionViewTranslation.java b/runners/core-construction-java/src/main/java/org/apache/beam/runners/core/construction/CreatePCollectionViewTranslation.java index e8be1370427a..c67d688d932d 100644 --- a/runners/core-construction-java/src/main/java/org/apache/beam/runners/core/construction/CreatePCollectionViewTranslation.java +++ b/runners/core-construction-java/src/main/java/org/apache/beam/runners/core/construction/CreatePCollectionViewTranslation.java @@ -86,9 +86,11 @@ public static PCollectionView getView( PCollectionView.class.getSimpleName()); } - // CHECKSTYLE.OFF: MissingDeprecated + /** + * @deprecated runners should move away from translating `CreatePCollectionView` and treat this + * as part of the translation for a `ParDo` side input. + */ @Deprecated - // CHECKSTYLE.ON: MissingDeprecated static class CreatePCollectionViewTranslator implements TransformPayloadTranslator> { @Override @@ -114,11 +116,14 @@ public FunctionSpec translate( } } - /** Registers {@link CreatePCollectionViewTranslator}. */ - // CHECKSTYLE.OFF: MissingDeprecated + /** + * Registers {@link CreatePCollectionViewTranslator}. + * + * @deprecated runners should move away from translating `CreatePCollectionView` and treat this + * as part of the translation for a `ParDo` side input. + */ @AutoService(TransformPayloadTranslatorRegistrar.class) @Deprecated - // CHECKSTYLE.ON: MissingDeprecated public static class Registrar implements TransformPayloadTranslatorRegistrar { @Override public Map, ? extends TransformPayloadTranslator> diff --git a/runners/google-cloud-dataflow-java/src/main/java/org/apache/beam/runners/dataflow/DataflowRunner.java b/runners/google-cloud-dataflow-java/src/main/java/org/apache/beam/runners/dataflow/DataflowRunner.java index afe999c5eade..3c967199f25c 100644 --- a/runners/google-cloud-dataflow-java/src/main/java/org/apache/beam/runners/dataflow/DataflowRunner.java +++ b/runners/google-cloud-dataflow-java/src/main/java/org/apache/beam/runners/dataflow/DataflowRunner.java @@ -82,6 +82,7 @@ import org.apache.beam.sdk.PipelineResult.State; import org.apache.beam.sdk.PipelineRunner; import org.apache.beam.sdk.annotations.Experimental; +import org.apache.beam.sdk.annotations.Internal; import org.apache.beam.sdk.coders.ByteArrayCoder; import org.apache.beam.sdk.coders.Coder; import org.apache.beam.sdk.coders.Coder.NonDeterministicException; @@ -1292,9 +1293,7 @@ public final PCollection expand(PBegin input) { * A marker {@link DoFn} for writing the contents of a {@link PCollection} to a streaming * {@link PCollectionView} backend implementation. */ - // CHECKSTYLE.OFF: MissingDeprecated - @Deprecated - // CHECKSTYLE.ON: MissingDeprecated + @Internal public static class StreamingPCollectionViewWriterFn extends DoFn, T> { private final PCollectionView view; private final Coder dataCoder; 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 a336f692de8a..78a4a0276637 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 @@ -56,10 +56,14 @@ * @param the type of values being encoded and decoded */ public abstract class Coder implements Serializable { - /** The context in which encoding or decoding is being done. */ - // CHECKSTYLE.OFF: MissingDeprecated + /** + * The context in which encoding or decoding is being done. + * + * @deprecated to implement a coder, do not use any `Context`. Just implement only those abstract + * methods which do not accept a `Context` and leave the default implementations for methods + * accepting a `Context`. + */ @Deprecated - // CHECKSTYLE.ON: MissingDeprecated @Experimental(Kind.CODER_CONTEXT) public static class Context { /** @@ -129,10 +133,10 @@ public abstract void encode(T value, OutputStream outStream) * @throws IOException if writing to the {@code OutputStream} fails * for some reason * @throws CoderException if the value could not be encoded for some reason + * + * @deprecated only implement and call {@link #encode(Object value, OutputStream)} */ - // CHECKSTYLE.OFF: MissingDeprecated @Deprecated - // CHECKSTYLE.ON: MissingDeprecated @Experimental(Kind.CODER_CONTEXT) public void encode(T value, OutputStream outStream, Context context) throws CoderException, IOException { @@ -156,10 +160,10 @@ public void encode(T value, OutputStream outStream, Context context) * @throws IOException if reading from the {@code InputStream} fails * for some reason * @throws CoderException if the value could not be decoded for some reason + * + * @deprecated only implement and call {@link #decode(InputStream)} */ - // CHECKSTYLE.OFF: MissingDeprecated @Deprecated - // CHECKSTYLE.ON: MissingDeprecated @Experimental(Kind.CODER_CONTEXT) public T decode(InputStream inStream, Context context) throws CoderException, IOException { diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/StreamingIT.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/StreamingIT.java index ea61a229121a..475372de2cbe 100644 --- a/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/StreamingIT.java +++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/testing/StreamingIT.java @@ -29,9 +29,11 @@ * StreamingPipeline.main(...); * } * + * + * @deprecated tests which use unbounded PCollections should be in the category + * {@link UsesUnboundedPCollections}. Beyond that, it is up to the runner and test configuration + * to decide whether to run in streaming mode. */ -// CHECKSTYLE.OFF: MissingDeprecated @Deprecated -// CHECKSTYLE.ONN: MissingDeprecated public interface StreamingIT { } diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/util/IdentityWindowFn.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/util/IdentityWindowFn.java index a018bd69b719..54ac77c59522 100644 --- a/sdks/java/core/src/main/java/org/apache/beam/sdk/util/IdentityWindowFn.java +++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/util/IdentityWindowFn.java @@ -111,9 +111,6 @@ public WindowMappingFn getDefaultWindowMappingFn() { getClass().getCanonicalName())); } - // CHECKSTYLE.OFF: MissingDeprecated - @Deprecated - // CHECKSTYLE.ON: MissingDeprecated @Override public Instant getOutputTime(Instant inputTimestamp, BoundedWindow window) { return inputTimestamp; diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/values/PCollectionViews.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/values/PCollectionViews.java index 636518b0cfe3..f2a30973da64 100644 --- a/sdks/java/core/src/main/java/org/apache/beam/sdk/values/PCollectionViews.java +++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/values/PCollectionViews.java @@ -186,9 +186,6 @@ private SingletonViewFn(boolean hasDefault, T defaultValue, Coder valueCoder) /** * Returns if a default value was specified. */ - // CHECKSTYLE.OFF: MissingDeprecated - @Deprecated - // CHECKSTYLE.ON: MissingDeprecated @Internal public boolean hasDefault() { return hasDefault; From 499bd87a8dc78c82b474721e706b3b74d5e32a64 Mon Sep 17 00:00:00 2001 From: Alex Filatov Date: Tue, 11 Jul 2017 23:49:21 +0300 Subject: [PATCH 3/3] [BEAM-2306] Add missing @deprecated javadocs. --- .../core/construction/PTransformTranslation.java | 6 ++++-- .../org/apache/beam/sdk/coders/CoderRegistry.java | 15 +++++++++------ 2 files changed, 13 insertions(+), 8 deletions(-) diff --git a/runners/core-construction-java/src/main/java/org/apache/beam/runners/core/construction/PTransformTranslation.java b/runners/core-construction-java/src/main/java/org/apache/beam/runners/core/construction/PTransformTranslation.java index 211aa01f036f..0b4a2ab31db3 100644 --- a/runners/core-construction-java/src/main/java/org/apache/beam/runners/core/construction/PTransformTranslation.java +++ b/runners/core-construction-java/src/main/java/org/apache/beam/runners/core/construction/PTransformTranslation.java @@ -55,9 +55,11 @@ public class PTransformTranslation { // Less well-known. And where shall these live? public static final String WRITE_FILES_TRANSFORM_URN = "urn:beam:transform:write_files:0.1"; - // CHECKSTYLE.OFF: MissingDeprecated + /** + * @deprecated runners should move away from translating `CreatePCollectionView` and treat this + * as part of the translation for a `ParDo` side input. + */ @Deprecated - // CHECKSTYLE.ON: MissingDeprecated public static final String CREATE_VIEW_TRANSFORM_URN = "urn:beam:transform:create_view:v1"; private static final Map, TransformPayloadTranslator> diff --git a/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/CoderRegistry.java b/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/CoderRegistry.java index 55c370497328..53cb6d398492 100644 --- a/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/CoderRegistry.java +++ b/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/CoderRegistry.java @@ -234,10 +234,11 @@ public Coder getCoder(TypeDescriptor type) throws CannotProvideCoderEx * type uses the given {@link Coder}. * * @throws CannotProvideCoderException if a {@link Coder} cannot be provided + * + * @deprecated This method is to change in an unknown backwards incompatible way once support for + * this functionality is refined. */ - // CHECKSTYLE.OFF: MissingDeprecated @Deprecated - // CHECKSTYLE.ON: MissingDeprecated @Internal public Coder getCoder( TypeDescriptor typeDescriptor, @@ -256,10 +257,11 @@ public Coder getCoder( * used for its input elements. * * @throws CannotProvideCoderException if a {@link Coder} cannot be provided + * + * @deprecated This method is to change in an unknown backwards incompatible way once support for + * this functionality is refined. */ - // CHECKSTYLE.OFF: MissingDeprecated @Deprecated - // CHECKSTYLE.ON: MissingDeprecated @Internal public Coder getOutputCoder( SerializableFunction fn, Coder inputCoder) @@ -280,10 +282,11 @@ public Coder getOutputCoder( * subclass, given {@link Coder Coders} to use for all other type parameters (if any). * * @throws CannotProvideCoderException if a {@link Coder} cannot be provided + * + * @deprecated This method is to change in an unknown backwards incompatible way once support for + * this functionality is refined. */ - // CHECKSTYLE.OFF: MissingDeprecated @Deprecated - // CHECKSTYLE.ON: MissingDeprecated @Internal public Coder getCoder( Class subClass,