diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 42009925af..df9d399f9e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,8 +59,10 @@ Akka uses [Scalariform](https://github.com/mdr/scalariform) to enforce some of t ##Contributing Modules## -For external contributions of entire modules, the normal way is to establish it as a stand-alone module first, - to show that there is a need for the module. The next step would be to add it to Akka as an "experimental module" (in the akka-contrib subproject), - then when the module is hardened, well documented and tested it becomes an officially supported Akka module. +For external contributions of entire features, the normal way is to establish it +as a stand-alone feature first, to show that there is a need for the feature. The +next step would be to add it to Akka as an "experimental feature" (in the +akka-contrib subproject), then when the feature is hardened, well documented and +tested it becomes an officially supported Akka feature. -[List of experimental Akka modules](http://doc.akka.io/docs/akka/current/experimental/index.html) +[List of experimental Akka features](http://doc.akka.io/docs/akka/current/experimental/index.html) diff --git a/akka-contrib/README.md b/akka-contrib/README.md index ced22e74f3..e17362112e 100644 --- a/akka-contrib/README.md +++ b/akka-contrib/README.md @@ -1,25 +1,52 @@ # External Contributions -This subproject provides a home to modules contributed by external developers which may or may not move into the officially supported code base over time. The conditions under which this transition can occur include: +This subproject provides a home to modules contributed by external developers +which may or may not move into the officially supported code base over time. +The conditions under which this transition can occur include: * there must be enough interest in the module to warrant inclusion in the standard distribution, * the module must be actively maintained and * code quality must be good enough to allow efficient maintenance by the Akka core development team -If a contributions turns out to not “take off” it may be removed again at a later time. +If a contributions turns out to not “take off” it may be removed again at a +later time. ## Caveat Emptor -A module in this subproject doesn't have to obey the rule of staying binary compatible between minor releases. Breaking API changes may be introduced in minor releases without notice as we refine and simplify based on your feedback. A module may be dropped in any release without prior deprecation. The Typesafe subscription does not cover support for these modules. +A module in this subproject doesn't have to obey the rule of staying binary +compatible between micro releases. Breaking API changes may be introduced in +minor releases without notice as we refine and simplify based on your feedback. +A module may be dropped in any release without prior deprecation. The Typesafe +subscription does not cover support for these modules. ## Suggested Format of Contributions -Each contribution should be a self-contained unit, consisting of one source file or one exclusively used package, without dependencies to other modules in this subproject; it may depend on everything else in the Akka distribution, though. This ensures that contributions may be moved into the standard distribution individually. The module shall be within a subpackage of `akka.contrib`. +Each contribution should be a self-contained unit, consisting of one source +file or one exclusively used package, without dependencies to other modules in +this subproject; it may depend on everything else in the Akka distribution, +though. This ensures that contributions may be moved into the standard +distribution individually. The module shall be within a subpackage of +`akka.contrib`. -Each module must be accompanied by a test suite which verifies that the provided features work, possibly complemented by integration and unit tests. The tests should follow the [Developer Guidelines](http://doc.akka.io/docs/akka/current/dev/developer-guidelines.html#testing) and go into the `src/test/scala` or `src/test/java` directories (with package name matching the module which is being tested). As an example, if the module were called `akka.contrib.pattern.ReliableProxy`, then the test suite should be called `akka.contrib.pattern.ReliableProxySpec`. +Each module must be accompanied by a test suite which verifies that the +provided features work, possibly complemented by integration and unit tests. +The tests should follow the [Developer +Guidelines](http://doc.akka.io/docs/akka/current/dev/developer-guidelines.html#testing) +and go into the `src/test/scala` or `src/test/java` directories (with package +name matching the module which is being tested). As an example, if the module +were called `akka.contrib.pattern.ReliableProxy`, then the test suite should be +called `akka.contrib.pattern.ReliableProxySpec`. -Each module must also have proper documentation in [reStructured Text format](http://sphinx.pocoo.org/rest.html). The documentation should be a single `.rst` file in the `akka-contrib/docs` directory, including a link from `index.rst`. +Each module must also have proper documentation in [reStructured Text +format](http://sphinx.pocoo.org/rest.html). The documentation should be a +single `.rst` file in the `akka-contrib/docs` directory, including a +link from `index.rst`. ## Suggested Way of Using these Contributions -Since the Akka team does not restrict updates to this subproject even during otherwise binary compatible releases, and modules may be removed without deprecation, it is suggested to copy the source files into your own code base, changing the package name. This way you can choose when to update or which fixes to include (to keep binary compatibility if needed) and later releases of Akka do not potentially break your application. +Since the Akka team does not restrict updates to this subproject even during +otherwise binary compatible releases, and modules may be removed without +deprecation, it is suggested to copy the source files into your own code base, +changing the package name. This way you can choose when to update or which +fixes to include (to keep binary compatibility if needed) and later releases of +Akka do not potentially break your application. diff --git a/akka-contrib/docs/conf.py b/akka-contrib/docs/conf.py deleted file mode 100644 index 41d7ef783a..0000000000 --- a/akka-contrib/docs/conf.py +++ /dev/null @@ -1,85 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Akka documentation build configuration file. -# - -import sys, os - -# -- General configuration ----------------------------------------------------- - -sys.path.append(os.path.abspath('../../akka-docs/_sphinx/exts')) -extensions = ['sphinx.ext.todo', 'includecode'] - -templates_path = ['_templates'] -source_suffix = '.rst' -master_doc = 'index' -exclude_patterns = ['_build', 'pending', 'disabled'] - -project = u'Akka' -copyright = u'2011, Typesafe Inc' -version = '@version@' -release = '@version@' - -pygments_style = 'simple' -highlight_language = 'scala' -add_function_parentheses = False -show_authors = True - -# -- Options for HTML output --------------------------------------------------- - -html_theme = 'akka' -html_theme_path = ['../../akka-docs/_sphinx/themes'] -html_favicon = '../../akka-docs/_sphinx/static/favicon.ico' - -html_title = 'Akka Documentation' -html_logo = '../../akka-docs/_sphinx/static/logo.png' -#html_favicon = None - -html_static_path = ['../../akka-docs/_sphinx/static'] - -html_last_updated_fmt = '%b %d, %Y' -#html_sidebars = {} -#html_additional_pages = {} -html_domain_indices = False -html_use_index = False -html_show_sourcelink = False -html_show_sphinx = False -html_show_copyright = True -htmlhelp_basename = 'Akkadoc' -html_use_smartypants = False -html_add_permalinks = '' - -html_context = { - 'include_analytics': 'online' in tags -} - -# -- Options for EPUB output --------------------------------------------------- -epub_author = "Typesafe Inc" -epub_language = "en" -epub_publisher = epub_author -epub_identifier = "http://doc.akka.io/docs/akka/snapshot/" -epub_scheme = "URL" -epub_cover = ("../../akka-docs/_sphinx/static/akka.png", "") - -# -- Options for LaTeX output -------------------------------------------------- - -def setup(app): - from sphinx.util.texescape import tex_replacements - tex_replacements.append((u'⇒', ur'\(\Rightarrow\)')) - -latex_paper_size = 'a4' -latex_font_size = '10pt' - -latex_documents = [ - ('index', 'Akka.tex', u' Akka Documentation', - u'Typesafe Inc', 'manual'), -] - -latex_elements = { - 'classoptions': ',oneside,openany', - 'babel': '\\usepackage[english]{babel}', - 'fontpkg': '\\PassOptionsToPackage{warn}{textcomp} \\usepackage{times}', - 'preamble': '\\definecolor{VerbatimColor}{rgb}{0.935,0.935,0.935}' - } - -# latex_logo = '_sphinx/static/akka.png' diff --git a/akka-contrib/docs/reliable-proxy.rst b/akka-contrib/docs/reliable-proxy.rst index af87255a2f..74470aaf3f 100644 --- a/akka-contrib/docs/reliable-proxy.rst +++ b/akka-contrib/docs/reliable-proxy.rst @@ -90,3 +90,32 @@ From Scala it would look like so: .. includecode:: @contribSrc@/src/test/scala/akka/contrib/pattern/ReliableProxyDocSpec.scala#demo-transition +The Actor Contract +------------------ + +Message it Processes +^^^^^^^^^^^^^^^^^^^^ + +* :class:`FSM.SubscribeTransitionCallBack` and :class:`FSM.UnsubscribeTransitionCallBack`, see :ref:`fsm-scala` +* internal messages declared within :obj:`ReliableProxy`, *not for external use* +* any other message is transferred through the reliable tunnel and forwarded to the designated target actor + +Messages it Sends +^^^^^^^^^^^^^^^^^ + +* :class:`FSM.CurrentState` and :class:`FSM.Transition`, see :ref:`fsm-scala` + +Exceptions it Escalates +^^^^^^^^^^^^^^^^^^^^^^^ + +* no specific exception types +* any exception encountered by either the local or remote end-point are escalated (only fatal VM errors) + +Arguments it Takes +^^^^^^^^^^^^^^^^^^ + +* *target* is the :class:`ActorRef` to which the tunnel shall reliably deliver + messages, ``B`` in the above illustration. +* *retryAfter* is the timeout for receiving ACK messages from the remote + end-point; once it fires, all outstanding message sends will be retried. + diff --git a/akka-contrib/src/test/java/akka/contrib/pattern/ReliableProxyTest.java b/akka-contrib/src/test/java/akka/contrib/pattern/ReliableProxyTest.java index 9522155d81..afb0c34378 100644 --- a/akka-contrib/src/test/java/akka/contrib/pattern/ReliableProxyTest.java +++ b/akka-contrib/src/test/java/akka/contrib/pattern/ReliableProxyTest.java @@ -50,8 +50,6 @@ public class ReliableProxyTest { //#demo-proxy final ActorRef proxy = getContext().actorOf( new Props(new UntypedActorFactory() { - private static final long serialVersionUID = 1L; - public Actor create() { final FiniteDuration retry = Duration.create(100, "millis"); return new ReliableProxy(target, retry); @@ -83,8 +81,6 @@ public class ReliableProxyTest { //#demo-transition final ActorRef proxy = getContext().actorOf( new Props(new UntypedActorFactory() { - private static final long serialVersionUID = 1L; - public Actor create() { final FiniteDuration retry = Duration.create(100, "millis"); return new ReliableProxy(target, retry); diff --git a/akka-docs/rst/experimental/index.rst b/akka-docs/rst/experimental/index.rst index 9a62d3e035..a0870ed588 100644 --- a/akka-docs/rst/experimental/index.rst +++ b/akka-docs/rst/experimental/index.rst @@ -11,9 +11,9 @@ experimental, is to make them easily available and improve based on feedback, or even discover that the module wasn't useful. An experimental module doesn't have to obey the rule of staying binary -compatible between minor releases. Breaking API changes may be introduced +compatible between micro releases. Breaking API changes may be introduced in minor releases without notice as we refine and simplify based on your -feedback. An experimental module may be dropped in major releases without +feedback. An experimental module may be dropped in minor releases without prior deprecation. .. toctree:: diff --git a/project/AkkaBuild.scala b/project/AkkaBuild.scala index f6c84e6f29..9e25beebd1 100644 --- a/project/AkkaBuild.scala +++ b/project/AkkaBuild.scala @@ -64,7 +64,7 @@ object AkkaBuild extends Build { generatePdf in Sphinx <<= generatePdf in Sphinx in LocalProject(docs.id) map identity ), - aggregate = Seq(actor, testkit, actorTests, dataflow, remote, remoteTests, camel, cluster, slf4j, agent, transactor, mailboxes, zeroMQ, kernel, akkaSbtPlugin, osgi, osgiAries, docs) + aggregate = Seq(actor, testkit, actorTests, dataflow, remote, remoteTests, camel, cluster, slf4j, agent, transactor, mailboxes, zeroMQ, kernel, akkaSbtPlugin, osgi, osgiAries, docs, contrib) ) lazy val actor = Project( @@ -356,14 +356,14 @@ object AkkaBuild extends Build { sphinxPackages in Sphinx <+= baseDirectory { _ / "_sphinx" / "pygments" }, // copy akka-contrib/docs into our rst_preprocess/contrib (and apply substitutions) preprocess in Sphinx <<= (preprocess in Sphinx, - sourceDirectory in contrib in Sphinx, + baseDirectory in contrib, target in preprocess in Sphinx, cacheDirectory, preprocessExts in Sphinx, preprocessVars in Sphinx, streams) map { (orig, src, target, cacheDir, exts, vars, s) => val contribSrc = Map("contribSrc" -> "../../../akka-contrib") - simplePreprocess(src, target / "contrib", cacheDir / "sphinx" / "preprocessed-contrib", exts, vars ++ contribSrc, s.log) + simplePreprocess(src / "docs", target / "contrib", cacheDir / "sphinx" / "preprocessed-contrib", exts, vars ++ contribSrc, s.log) orig }, enableOutput in generatePdf in Sphinx := true, @@ -378,16 +378,9 @@ object AkkaBuild extends Build { id = "akka-contrib", base = file("akka-contrib"), dependencies = Seq(remote, remoteTests % "compile;test->test"), - settings = defaultSettings ++ multiJvmSettings ++ SphinxSupport.settings ++ sphinxPreprocessing ++ Seq( + settings = defaultSettings ++ multiJvmSettings ++ Seq( libraryDependencies ++= Dependencies.contrib, testOptions += Tests.Argument(TestFrameworks.JUnit, "-v"), - preprocessVars in Sphinx <<= (preprocessVars in Sphinx) { (old) => - old ++ Map( - "contribSrc" -> ".." - ) - }, - sourceDirectory in Sphinx <<= baseDirectory / "docs", - sphinxPackages in Sphinx <+= baseDirectory { _ / ".." / "akka-docs" / "_sphinx" / "pygments" }, description := """| |This subproject provides a home to modules contributed by external |developers which may or may not move into the officially supported code