Merge pull request #1877 from akka/wip-3667-deprecate-stm-agents-patriknw

=age #3667 Deprecate stm support in agents

akka-agent/src/main/scala/akka/agent/Agent.scala

@@ -107,12 +107,6 @@ object Agent {
  * potentially interleaved with actions dispatched to the same agent from
  * other sources.
  *
- * If an Agent is used within an enclosing transaction, then it will
- * participate in that transaction. Agents are integrated with the STM -
- * any dispatches made in a transaction are held until that transaction
- * commits, and are discarded if it is retried or aborted.
- * <br/><br/>
- *
  * Example of usage:
  * {{{
  * val agent = Agent(5)
@@ -150,6 +144,15 @@ object Agent {
  * } yield value1 + value2
  *
  * }}}
+ *
+ * ==DEPRECATED STM SUPPORT==
+ *
+ * Agents participating in enclosing STM transaction is a deprecated feature in 2.3.
+ *
+ * If an Agent is used within an enclosing transaction, then it will
+ * participate in that transaction. Agents are integrated with the STM -
+ * any dispatches made in a transaction are held until that transaction
+ * commits, and are discarded if it is retried or aborted.
  */
 abstract class Agent[T] {
 

akka-docs/rst/java/agents.rst

@@ -23,10 +23,6 @@ each Agent is being executed. Actions dispatched to an agent from another thread
 will occur in the order they were sent, potentially interleaved with actions
 dispatched to the same agent from other threads.
 
-If an Agent is used within an enclosing transaction, then it will participate in
-that transaction. Agents are integrated with Scala STM - any dispatches made in
-a transaction are held until that transaction commits, and are discarded if it
-is retried or aborted.
 
 
 Creating Agents
@@ -97,8 +93,10 @@ See :ref:`futures-java` for more information on ``Futures``.
    :include: import-future,import-function,alter-off
    :language: java
 
-Transactional Agents
+Deprecated Transactional Agents
-====================
+===============================
+
+Agents participating in enclosing STM transaction is a deprecated feature in 2.3.
 
 If an Agent is used within an enclosing ``Scala STM transaction``, then it will participate in
 that transaction. If you send to an Agent within a transaction then the dispatch

akka-docs/rst/project/migration-guide-2.2.x-2.3.x.rst

@@ -113,6 +113,11 @@ tools to support reliable messaging.
 Read more about ``akka-persistence`` in the :ref:`documentation for Scala <persistence-scala>` and 
 :ref:`documentation for Java <persistence-java>`.
 
+Deprecated STM Support for Agents
+=================================
+
+Agents participating in enclosing STM transaction is a deprecated feature.
+
 Removed Deprecated Features
 ===========================
 
@@ -122,4 +127,3 @@ The following, previously deprecated, features have been removed:
  * `API changes to FSM and TestFSMRef <http://doc.akka.io/docs/akka/2.2.3/project/migration-guide-2.1.x-2.2.x.html#API_changes_to_FSM_and_TestFSMRef>`_
  * DefaultScheduler superseded by LightArrayRevolverScheduler
  
-

akka-docs/rst/scala/agents.rst

@@ -24,11 +24,6 @@ each Agent is being executed. Actions dispatched to an agent from another thread
 will occur in the order they were sent, potentially interleaved with actions
 dispatched to the same agent from other threads.
 
-If an Agent is used within an enclosing transaction, then it will participate in
-that transaction. Agents are integrated with Scala STM - any dispatches made in
-a transaction are held until that transaction commits, and are discarded if it
-is retried or aborted.
-
 .. note::
 
   Agents are local to the node on which they are created. This implies that you
@@ -99,17 +94,6 @@ currently queued updates have completed:
 
 See :ref:`futures-scala` for more information on ``Futures``.
 
-Transactional Agents
-====================
-
-If an Agent is used within an enclosing transaction, then it will participate in
-that transaction. If you send to an Agent within a transaction then the dispatch
-to the Agent will be held until that transaction commits, and discarded if the
-transaction is aborted. Here's an example:
-
-.. includecode:: code/docs/agent/AgentDocSpec.scala#transfer-example
-
-
 Monadic usage
 =============
 
@@ -121,3 +105,15 @@ as-is. They are so-called 'persistent'.
 Example of monadic usage:
 
 .. includecode:: code/docs/agent/AgentDocSpec.scala#monadic-example
+
+Deprecated Transactional Agents
+===============================
+
+Agents participating in enclosing STM transaction is a deprecated feature in 2.3.
+
+If an Agent is used within an enclosing transaction, then it will participate in
+that transaction. If you send to an Agent within a transaction then the dispatch
+to the Agent will be held until that transaction commits, and discarded if the
+transaction is aborted. Here's an example:
+
+.. includecode:: code/docs/agent/AgentDocSpec.scala#transfer-example