Merge pull request #19576 from 2m/wip-deprecate-stage-2m

#19553 deprecate stage infra

akka-docs/rst/general/stream/stages-overview.rst

@@ -20,7 +20,7 @@ Custom components are not covered by this table since their semantics are define
 Simple processing stages
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-These stages are all expressible as a ``PushPullStage``. These stages can transform the rate of incoming elements
+These stages are all expressible as a ``GraphStage``. These stages can transform the rate of incoming elements
 since there are stages that emit multiple elements for a single input (e.g. `mapConcat') or consume
 multiple elements before emitting one output (e.g. ``filter``). However, these rate transformations are data-driven, i.e. it is
 the incoming elements that define how the rate is affected. This is in contrast with :ref:`detached-stages-overview`
@@ -122,7 +122,7 @@ a single output combining the elements from all of the inputs in different ways.
 Stage                  Emits when                                                                                                                  Backpressures when                                                                                                              Completes when
 =====================  =========================================================================================================================   ==============================================================================================================================  =====================================================================================
 merge                  one of the inputs has an element available                                                                                  downstream backpressures                                                                                                        all upstreams complete (*)
-mergeSorted            all of the inputs have an element available                                                                                 downstream backpressures                                                                                                        all upstreams complete    
+mergeSorted            all of the inputs have an element available                                                                                 downstream backpressures                                                                                                        all upstreams complete
 mergePreferred         one of the inputs has an element available, preferring a defined input if multiple have elements available                  downstream backpressures                                                                                                        all upstreams complete (*)
 zip                    all of the inputs have an element available                                                                                 downstream backpressures                                                                                                        any upstream completes
 zipWith                all of the inputs have an element available                                                                                 downstream backpressures                                                                                                        any upstream completes

akka-docs/rst/java/stream/migration-guide-2.0-2.4-java.rst

@@ -98,3 +98,18 @@ Materialized values of the following sources and sinks:
 have been changed from ``Long`` to ``akka.stream.io.IOResult``.
 This allows to signal more complicated completion scenarios. For example, on failure it is now possible
 to return the exception and the number of bytes written until that exception occured.
+
+PushStage, PushPullStage and DetachedStage have been deprecated in favor of GraphStage
+======================================================================================
+
+The :class:`PushStage` :class:`PushPullStage` and :class:`DetachedStage` classes have been deprecated and
+should be replaced by :class:`GraphStage` (:ref:`graphstage-java`) which is now a single powerful API
+for custom stream processing.
+
+Update procedure
+----------------
+
+Please consult the :class:`GraphStage` documentation (:ref:`graphstage-java`) and the `previous migration guide`_
+on migrating from :class:`AsyncStage` to :class:`GraphStage`.
+
+.. _`previous migration guide`: http://doc.akka.io/docs/akka-stream-and-http-experimental/2.0.2/java/migration-guide-1.0-2.x-java.html#AsyncStage_has_been_replaced_by_GraphStage

akka-docs/rst/scala/stream/migration-guide-2.0-2.4-scala.rst

@@ -95,3 +95,18 @@ Materialized values of the following sources and sinks:
 have been changed from ``Long`` to ``akka.stream.io.IOResult``.
 This allows to signal more complicated completion scenarios. For example, on failure it is now possible
 to return the exception and the number of bytes written until that exception occured.
+
+PushStage, PushPullStage and DetachedStage have been deprecated in favor of GraphStage
+======================================================================================
+
+The :class:`PushStage` :class:`PushPullStage` and :class:`DetachedStage` classes have been deprecated and
+should be replaced by :class:`GraphStage` (:ref:`graphstage-scala`) which is now a single powerful API
+for custom stream processing.
+
+Update procedure
+----------------
+
+Please consult the :class:`GraphStage` documentation (:ref:`graphstage-scala`) and the `previous migration guide`_
+on migrating from :class:`AsyncStage` to :class:`GraphStage`.
+
+.. _`previous migration guide`: http://doc.akka.io/docs/akka-stream-and-http-experimental/2.0.2/scala/migration-guide-1.0-2.x-scala.html#AsyncStage_has_been_replaced_by_GraphStage

akka-stream/src/main/scala/akka/stream/stage/Stage.scala

@@ -29,6 +29,7 @@ import scala.util.control.NonFatal
  * @see [[akka.stream.scaladsl.Flow#transform]]
  * @see [[akka.stream.javadsl.Flow#transform]]
  */
+@deprecated("Please use GraphStage instead.", "2.4.2")
 sealed trait Stage[-In, +Out]
 
 /**
@@ -185,6 +186,7 @@ private[stream] object AbstractStage {
     extends PushPullGraphStageWithMaterializedValue[In, Out, Ext, NotUsed]((att: Attributes) ⇒ (_factory(att), NotUsed), _stageAttributes)
 }
 
+@deprecated("Please use GraphStage instead.", "2.4.2")
 abstract class AbstractStage[-In, Out, PushD <: Directive, PullD <: Directive, Ctx <: Context[Out], LifeCtx <: LifecycleContext] extends Stage[In, Out] {
 
   /**
@@ -331,11 +333,13 @@ abstract class AbstractStage[-In, Out, PushD <: Directive, PullD <: Directive, C
  * @see [[StatefulStage]]
  * @see [[PushStage]]
  */
+@deprecated("Please use GraphStage instead.", "2.4.2")
 abstract class PushPullStage[In, Out] extends AbstractStage[In, Out, SyncDirective, SyncDirective, Context[Out], LifecycleContext]
 
 /**
  * `PushStage` is a [[PushPullStage]] that always perform transitive pull by calling `ctx.pull` from `onPull`.
  */
+@deprecated("Please use GraphStage instead.", "2.4.2")
 abstract class PushStage[In, Out] extends PushPullStage[In, Out] {
   /**
    * Always pulls from upstream.
@@ -365,6 +369,7 @@ abstract class PushStage[In, Out] extends PushPullStage[In, Out] {
  *
  * @see [[PushPullStage]]
  */
+@deprecated("Please use GraphStage instead.", "2.4.2")
 abstract class DetachedStage[In, Out]
   extends AbstractStage[In, Out, UpstreamDirective, DownstreamDirective, DetachedContext[Out], LifecycleContext] {
   private[stream] override def isDetached = true