The idea is to filter the sources, replacing @<var>@ occurrences with the mapping for <var> (which is currently hard-coded). @@ -> @. In order to make this work, I had to move the doc sources one directory down (into akka-docs/rst) so that the filtered result could be in a sibling directory so that relative links (to _sphinx plugins or real code) would continue to work. While I was at it I also changed it so that WARNINGs and ERRORs are not swallowed into the debug dump anymore but printed at [warn] level (minimum). One piece of fallout is that the (online) html build is now run after the normal one, not in parallel.
This commit is contained in:
Roland
parent
c0f60da8cc
commit
9bc01ae265
266 changed files with 270 additions and 182 deletions
32
akka-docs/rst/intro/deployment-scenarios.rst
Normal file
32
akka-docs/rst/intro/deployment-scenarios.rst
Normal file
|
|
@ -0,0 +1,32 @@
|
|||
.. _deployment-scenarios:
|
||||
|
||||
###################################
|
||||
Use-case and Deployment Scenarios
|
||||
###################################
|
||||
|
||||
How can I use and deploy Akka?
|
||||
==============================
|
||||
|
||||
Akka can be used in different ways:
|
||||
|
||||
- As a library: used as a regular JAR on the classpath and/or in a web app, to
|
||||
be put into ``WEB-INF/lib``
|
||||
|
||||
- As a stand alone application by instantiating ActorSystem in a main class or
|
||||
using the :ref:`microkernel-scala` / :ref:`microkernel-java`
|
||||
|
||||
|
||||
Using Akka as library
|
||||
---------------------
|
||||
|
||||
This is most likely what you want if you are building Web applications. There
|
||||
are several ways you can use Akka in Library mode by adding more and more
|
||||
modules to the stack.
|
||||
|
||||
|
||||
Using Akka as a stand alone microkernel
|
||||
----------------------------------------
|
||||
|
||||
Akka can also be run as a stand-alone microkernel. See
|
||||
:ref:`microkernel-scala` / :ref:`microkernel-java` for
|
||||
more information.
|
||||
164
akka-docs/rst/intro/getting-started.rst
Normal file
164
akka-docs/rst/intro/getting-started.rst
Normal file
|
|
@ -0,0 +1,164 @@
|
|||
Getting Started
|
||||
===============
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
Akka requires that you have `Java 1.6 <http://www.oracle.com/technetwork/java/javase/downloads/index.html>`_ or
|
||||
later installed on you machine.
|
||||
|
||||
Getting Started Guides and Template Projects
|
||||
--------------------------------------------
|
||||
|
||||
The best way to start learning Akka is to download the Typesafe Stack and either try out
|
||||
the Akka Getting Started Tutorials or check out one of Akka Template Projects. Both comes
|
||||
in several flavours depending on your development environment preferences.
|
||||
|
||||
- `Download Typesafe Stack <http://typesafe.com/stack/download>`_
|
||||
- `Getting Started Tutorials <http://typesafe.com/resources/getting-started>`_
|
||||
- `Template Projects <http://typesafe.com/stack/download#template>`_
|
||||
|
||||
Download
|
||||
--------
|
||||
|
||||
There are several ways to download Akka. You can download it as part of the Typesafe Stack
|
||||
(as described above). You can download the full distribution with microkernel, which includes
|
||||
all modules. Or you can use a build tool like Maven or SBT to download dependencies from the
|
||||
Akka Maven repository.
|
||||
|
||||
Modules
|
||||
-------
|
||||
|
||||
Akka is very modular and consists of several JARs containing different features.
|
||||
|
||||
- ``akka-actor`` -- Classic Actors, Typed Actors, IO Actor etc.
|
||||
- ``akka-remote`` -- Remote Actors
|
||||
- ``akka-testkit`` -- Toolkit for testing Actor systems
|
||||
- ``akka-kernel`` -- Akka microkernel for running a bare-bones mini application server
|
||||
- ``akka-transactor`` -- Transactors - transactional actors, integrated with Scala STM
|
||||
- ``akka-agent`` -- Agents, integrated with Scala STM
|
||||
- ``akka-camel`` -- Apache Camel integration
|
||||
- ``akka-zeromq`` -- ZeroMQ integration
|
||||
- ``akka-slf4j`` -- SLF4J Event Handler Listener
|
||||
- ``akka-filebased-mailbox`` -- Akka durable mailbox (find more among community projects)
|
||||
|
||||
The filename of the actual JAR is for example ``@jarName@`` (and analog for
|
||||
the other modules).
|
||||
|
||||
How to see the JARs dependencies of each Akka module is described in the
|
||||
:ref:`dependencies` section.
|
||||
|
||||
Using a release distribution
|
||||
----------------------------
|
||||
|
||||
Download the release you need from http://akka.io/downloads and unzip it.
|
||||
|
||||
Using a snapshot version
|
||||
------------------------
|
||||
|
||||
The Akka nightly snapshots are published to http://repo.akka.io/snapshots/ and are
|
||||
versioned with both ``SNAPSHOT`` and timestamps. You can choose a timestamped
|
||||
version to work with and can decide when to update to a newer version. The Akka
|
||||
snapshots repository is also proxied through http://repo.typesafe.com/typesafe/snapshots/
|
||||
which includes proxies for several other repositories that Akka modules depend on.
|
||||
|
||||
Microkernel
|
||||
-----------
|
||||
|
||||
The Akka distribution includes the microkernel. To run the microkernel put your
|
||||
application jar in the ``deploy`` directory and use the scripts in the ``bin``
|
||||
directory.
|
||||
|
||||
More information is available in the documentation of the
|
||||
:ref:`microkernel-scala` / :ref:`microkernel-java`.
|
||||
|
||||
Using a build tool
|
||||
------------------
|
||||
|
||||
Akka can be used with build tools that support Maven repositories. The Akka
|
||||
Maven repository can be found at http://repo.akka.io/releases/ and Typesafe provides
|
||||
http://repo.typesafe.com/typesafe/releases/ that proxies several other
|
||||
repositories, including akka.io.
|
||||
|
||||
Using Akka with Maven
|
||||
---------------------
|
||||
|
||||
The simplest way to get started with Akka and Maven is to check out the
|
||||
`Akka/Maven template <http://typesafe.com/resources/getting-started/typesafe-stack/downloading-installing.html#template-projects-for-scala-akka-and-play>`_
|
||||
project.
|
||||
|
||||
Since Akka is published to Maven Central (for versions since 2.1-M2), is it
|
||||
enough to add the Akka dependencies to the POM. For example, here is the
|
||||
dependency for akka-actor:
|
||||
|
||||
.. code-block:: xml
|
||||
|
||||
<dependency>
|
||||
<groupId>com.typesafe.akka</groupId>
|
||||
<artifactId>akka-actor_@binVersion@</artifactId>
|
||||
<version>@version@</version>
|
||||
</dependency>
|
||||
|
||||
**Note**: for snapshot versions both ``SNAPSHOT`` and timestamped versions are published.
|
||||
|
||||
|
||||
Using Akka with SBT
|
||||
-------------------
|
||||
|
||||
The simplest way to get started with Akka and SBT is to check out the
|
||||
`Akka/SBT template <http://typesafe.com/resources/getting-started/typesafe-stack/downloading-installing.html#template-projects-for-scala-akka-and-play>`_
|
||||
project.
|
||||
|
||||
Summary of the essential parts for using Akka with SBT:
|
||||
|
||||
SBT installation instructions on `https://github.com/harrah/xsbt/wiki/Setup <https://github.com/harrah/xsbt/wiki/Setup>`_
|
||||
|
||||
``build.sbt`` file:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
name := "My Project"
|
||||
|
||||
version := "1.0"
|
||||
|
||||
scalaVersion := "@scalaVersion@"
|
||||
|
||||
resolvers += "Typesafe Repository" at "http://repo.typesafe.com/typesafe/releases/"
|
||||
|
||||
libraryDependencies +=
|
||||
"com.typesafe.akka" %% "akka-actor" % "@version@" @crossString@
|
||||
|
||||
|
||||
Using Akka with Eclipse
|
||||
-----------------------
|
||||
|
||||
Setup SBT project and then use `sbteclipse <https://github.com/typesafehub/sbteclipse>`_ to generate a Eclipse project.
|
||||
|
||||
Using Akka with IntelliJ IDEA
|
||||
-----------------------------
|
||||
|
||||
Setup SBT project and then use `sbt-idea <https://github.com/mpeltonen/sbt-idea>`_ to generate a IntelliJ IDEA project.
|
||||
|
||||
Using Akka with NetBeans
|
||||
------------------------
|
||||
|
||||
Setup SBT project and then use `sbt-netbeans-plugin <https://github.com/remeniuk/sbt-netbeans-plugin>`_ to generate a NetBeans project.
|
||||
|
||||
Build from sources
|
||||
------------------
|
||||
|
||||
Akka uses Git and is hosted at `Github <http://github.com>`_.
|
||||
|
||||
* Akka: clone the Akka repository from `<http://github.com/akka/akka>`_
|
||||
|
||||
Continue reading the page on :ref:`building-akka`
|
||||
|
||||
Need help?
|
||||
----------
|
||||
|
||||
If you have questions you can get help on the `Akka Mailing List <http://groups.google.com/group/akka-user>`_.
|
||||
|
||||
You can also ask for `commercial support <http://typesafe.com>`_.
|
||||
|
||||
Thanks for being a part of the Akka community.
|
||||
|
||||
12
akka-docs/rst/intro/index.rst
Normal file
12
akka-docs/rst/intro/index.rst
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
Introduction
|
||||
============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
what-is-akka
|
||||
why-akka
|
||||
getting-started
|
||||
deployment-scenarios
|
||||
use-cases
|
||||
|
||||
59
akka-docs/rst/intro/use-cases.rst
Normal file
59
akka-docs/rst/intro/use-cases.rst
Normal file
|
|
@ -0,0 +1,59 @@
|
|||
|
||||
.. _use-cases:
|
||||
|
||||
################################
|
||||
Examples of use-cases for Akka
|
||||
################################
|
||||
|
||||
We see Akka being adopted by many large organizations in a big range of industries
|
||||
all from investment and merchant banking, retail and social media, simulation,
|
||||
gaming and betting, automobile and traffic systems, health care, data analytics
|
||||
and much more. Any system that have the need for high-throughput and low latency
|
||||
is a good candidate for using Akka.
|
||||
|
||||
There is a great discussion on use-cases for Akka with some good write-ups by production
|
||||
users `here <http://stackoverflow.com/questions/4493001/good-use-case-for-akka/4494512#4494512>`_
|
||||
|
||||
Here are some of the areas where Akka is being deployed into production
|
||||
=======================================================================
|
||||
|
||||
Transaction processing (Online Gaming, Finance/Banking, Trading, Statistics, Betting, Social Media, Telecom)
|
||||
------------------------------------------------------------------------------------------------------------
|
||||
Scale up, scale out, fault-tolerance / HA
|
||||
|
||||
Service backend (any industry, any app)
|
||||
---------------------------------------
|
||||
Service REST, SOAP, Cometd, WebSockets etc
|
||||
Act as message hub / integration layer
|
||||
Scale up, scale out, fault-tolerance / HA
|
||||
|
||||
Concurrency/parallelism (any app)
|
||||
---------------------------------
|
||||
Correct
|
||||
Simple to work with and understand
|
||||
Just add the jars to your existing JVM project (use Scala, Java, Groovy or JRuby)
|
||||
|
||||
Simulation
|
||||
----------
|
||||
Master/Worker, Compute Grid, MapReduce etc.
|
||||
|
||||
Batch processing (any industry)
|
||||
-------------------------------
|
||||
Camel integration to hook up with batch data sources
|
||||
Actors divide and conquer the batch workloads
|
||||
|
||||
Communications Hub (Telecom, Web media, Mobile media)
|
||||
-----------------------------------------------------
|
||||
Scale up, scale out, fault-tolerance / HA
|
||||
|
||||
Gaming and Betting (MOM, online gaming, betting)
|
||||
------------------------------------------------
|
||||
Scale up, scale out, fault-tolerance / HA
|
||||
|
||||
Business Intelligence/Data Mining/general purpose crunching
|
||||
-----------------------------------------------------------
|
||||
Scale up, scale out, fault-tolerance / HA
|
||||
|
||||
Complex Event Stream Processing
|
||||
-------------------------------
|
||||
Scale up, scale out, fault-tolerance / HA
|
||||
121
akka-docs/rst/intro/what-is-akka.rst
Normal file
121
akka-docs/rst/intro/what-is-akka.rst
Normal file
|
|
@ -0,0 +1,121 @@
|
|||
.. _what-is-akka:
|
||||
|
||||
###############
|
||||
What is Akka?
|
||||
###############
|
||||
|
||||
**Scalable real-time transaction processing**
|
||||
|
||||
We believe that writing correct concurrent, fault-tolerant and scalable
|
||||
applications is too hard. Most of the time it's because we are using the wrong
|
||||
tools and the wrong level of abstraction. Akka is here to change that. Using the
|
||||
Actor Model we raise the abstraction level and provide a better platform to build
|
||||
correct, concurrent, and scalable applications. For fault-tolerance we adopt the
|
||||
"Let it crash" model which the telecom industry has used with great success to
|
||||
build applications that self-heal and systems that never stop. Actors also provide
|
||||
the abstraction for transparent distribution and the basis for truly scalable and
|
||||
fault-tolerant applications.
|
||||
|
||||
Akka is Open Source and available under the Apache 2 License.
|
||||
|
||||
Download from http://akka.io/downloads/
|
||||
|
||||
|
||||
Akka implements a unique hybrid
|
||||
===============================
|
||||
|
||||
Actors
|
||||
------
|
||||
|
||||
Actors give you:
|
||||
|
||||
- Simple and high-level abstractions for concurrency and parallelism.
|
||||
- Asynchronous, non-blocking and highly performant event-driven programming model.
|
||||
- Very lightweight event-driven processes (approximately 2.7 million actors per GB RAM).
|
||||
|
||||
See :ref:`actors-scala` and :ref:`untyped-actors-java`
|
||||
|
||||
Fault Tolerance
|
||||
---------------
|
||||
|
||||
Fault tolerance through supervisor hierarchies with "let-it-crash"
|
||||
semantics. Excellent for writing highly fault-tolerant systems that never stop,
|
||||
systems that self-heal. Supervisor hierarchies can span over multiple JVMs to
|
||||
provide truly fault-tolerant systems.
|
||||
|
||||
See :ref:`fault-tolerance-scala` and :ref:`fault-tolerance-java`
|
||||
|
||||
Location Transparency
|
||||
---------------------
|
||||
Everything in Akka is designed to work in a distributed environment: all
|
||||
interactions of actors use purely message passing and everything is asynchronous.
|
||||
|
||||
For an overview of the remoting see :ref:`remoting`
|
||||
|
||||
Transactors
|
||||
-----------
|
||||
|
||||
Transactors combine actors and STM (Software Transactional Memory) into transactional actors.
|
||||
It allows you to compose atomic message flows with automatic retry and rollback.
|
||||
|
||||
See :ref:`transactors-scala` and :ref:`transactors-java`
|
||||
|
||||
|
||||
Scala and Java APIs
|
||||
===================
|
||||
|
||||
Akka has both a :ref:`scala-api` and a :ref:`java-api`.
|
||||
|
||||
|
||||
Akka can be used in two different ways
|
||||
======================================
|
||||
|
||||
- As a library: used by a web app, to be put into ``WEB-INF/lib`` or as a regular
|
||||
JAR on your classpath.
|
||||
|
||||
- As a microkernel: stand-alone kernel to drop your application into.
|
||||
|
||||
See the :ref:`deployment-scenarios` for details.
|
||||
|
||||
What happened to Cloudy Akka?
|
||||
=============================
|
||||
|
||||
The commercial offering was earlier referred to as Cloudy Akka. This offering
|
||||
consisted of two things:
|
||||
|
||||
- Cluster support for Akka
|
||||
- Monitoring & Management (formerly called Atmos)
|
||||
|
||||
Cloudy Akka have been discontinued and the Cluster support is now being moved into the
|
||||
Open Source version of Akka (the upcoming Akka 2.1), while the Monitoring & Management
|
||||
(Atmos) is now rebranded into Typesafe Console and is part of the commercial subscription
|
||||
for the Typesafe Stack (see below for details).
|
||||
|
||||
Typesafe Stack
|
||||
==============
|
||||
|
||||
Akka is now also part of the `Typesafe Stack <http://typesafe.com/stack>`_.
|
||||
|
||||
The Typesafe Stack is a modern software platform that makes it easy for developers
|
||||
to build scalable software applications. It combines the Scala programming language,
|
||||
Akka, the Play! web framework and robust developer tools in a simple package that
|
||||
integrates seamlessly with existing Java infrastructure.
|
||||
|
||||
The Typesafe Stack is all fully open source.
|
||||
|
||||
Typesafe Console
|
||||
================
|
||||
|
||||
On top of the Typesafe Stack we also have a commercial product called Typesafe
|
||||
Console which provides the following features:
|
||||
|
||||
#. Slick Web UI with real-time view into the system
|
||||
#. Management through Dashboard, JMX and REST
|
||||
#. Dapper-style tracing of messages across components and remote nodes
|
||||
#. Real-time statistics
|
||||
#. Very low overhead monitoring agents (should always be on in production)
|
||||
#. Consolidation of statistics and logging information to a single node
|
||||
#. Storage of statistics data for later processing
|
||||
#. Provisioning and rolling upgrades
|
||||
|
||||
Read more `here <http://typesafe.com/products/typesafe-subscription>`_.
|
||||
47
akka-docs/rst/intro/why-akka.rst
Normal file
47
akka-docs/rst/intro/why-akka.rst
Normal file
|
|
@ -0,0 +1,47 @@
|
|||
Why Akka?
|
||||
=========
|
||||
|
||||
What features can the Akka platform offer, over the competition?
|
||||
----------------------------------------------------------------
|
||||
|
||||
Akka provides scalable real-time transaction processing.
|
||||
|
||||
Akka is an unified runtime and programming model for:
|
||||
|
||||
- Scale up (Concurrency)
|
||||
- Scale out (Remoting)
|
||||
- Fault tolerance
|
||||
|
||||
One thing to learn and admin, with high cohesion and coherent semantics.
|
||||
|
||||
Akka is a very scalable piece of software, not only in the performance sense,
|
||||
but in the size of applications it is useful for. The core of Akka, akka-actor,
|
||||
is very small and easily dropped into an existing project where you need
|
||||
asynchronicity and lockless concurrency without hassle.
|
||||
|
||||
You can choose to include only the parts of akka you need in your application
|
||||
and then there's the whole package, the Akka Microkernel, which is a standalone
|
||||
container to deploy your Akka application in. With CPUs growing more and more
|
||||
cores every cycle, Akka is the alternative that provides outstanding performance
|
||||
even if you're only running it on one machine. Akka also supplies a wide array
|
||||
of concurrency-paradigms, allowing for users to choose the right tool for the
|
||||
job.
|
||||
|
||||
|
||||
What's a good use-case for Akka?
|
||||
--------------------------------
|
||||
|
||||
We see Akka being adopted by many large organizations in a big range of industries
|
||||
all from investment and merchant banking, retail and social media, simulation,
|
||||
gaming and betting, automobile and traffic systems, health care, data analytics
|
||||
and much more. Any system that have the need for high-throughput and low latency
|
||||
is a good candidate for using Akka.
|
||||
|
||||
Actors lets you manage service failures (Supervisors), load management (back-off
|
||||
strategies, timeouts and processing-isolation), both horizontal and vertical
|
||||
scalability (add more cores and/or add more machines).
|
||||
|
||||
Here's what some of the Akka users have to say about how they are using Akka:
|
||||
http://stackoverflow.com/questions/4493001/good-use-case-for-akka
|
||||
|
||||
All this in the ApacheV2-licensed open source project.
|
||||
Loading…
Add table
Add a link
Reference in a new issue