Akka Documentation(Scala) Introduction

---

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 scalable, resilient and responsive applications—see the Reactive Manifesto for more details. 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就是为了改变这种状况而生的。通过使用Actor模型我们提升了抽象级别，提供了一个更好的平台-构建可扩展、弹性的、响应式的应用(了解更多可见响应式编程宣言)。在容错性方面我们采取了“let it crash”（让它崩溃）模型，人们已经将这种模型用在了电信行业，构建出“自愈合”的应用和永不停机的系统，取得了巨大成功。Actor还为透明的分布式系统以及真正的可扩展高容错应用的基础进行了抽象。)

Akka is Open Source and available under the Apache 2 License.

Download from http://akka.io/downloads.

Please note that all code samples compile, so if you want direct access to the sources, have a look over at the Akka Docs subproject on github: for Java and Scala.

Akka implements a unique hybrid (Akka实现了独特的混合模型)

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 (several million actors per GB of heap memory). (非常轻量级的事件驱动处理进程(1G内存可容纳几百万的actors))

See the chapter for Actors(Scala) or Actors(Java).

Fault Tolerance (容错性)

• Supervisor hierarchies with “let-it-crash” semantics. (使用“让它崩溃”语义的监视者(树形)层级结构)
• Supervisor hierarchies can span over multiple JVMs to provide truly fault-tolerant systems. (监管者(树形)层级结构可以跨多个JVM来提供真正的高容错系统)
• Excellent for writing highly fault-tolerant systems that self-heal and never stop. (对编写高容错、可自愈、永不宕机的系统是非常优秀的)

See Fault Tolerance (Scala) and Fault Tolerance (Java).

Location Transparency (位置透明性)

Everything in Akka is designed to work in a distributed environment: all interactions of actors use pure message passing and everything is asynchronous.
(Akka的所有元素都为分布式环境而设计：所有actor都仅通过发送消息进行互操作，所有操作都是异步的)

For an overview of the cluster support see the Java and Scala documentation chapters.

Persistence

Messages received by an actor can optionally be persisted and replayed when the actor is started or restarted. This allows actors to recover their state, even after JVM crashes or when being migrated to another node.

You can find more details in the respective chapter for Java or Scala.

Scala and Java APIs

Akka has both a Scala Documentation and a Java Documentation.

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. (以库的形式：在web应用中使用，放到 WEB-INF/lib 中或者作为一个普通的Jar包放进classpath)
• As a microkernel: stand-alone kernel to drop your application into. (以微内核的形式：你可以将应用放进一个独立的内核)

See the Use-case and Deployment Scenarios for details.

---

Why Akka?

What features can the Akka platform offer, over the competition? (Akka平台将提供哪些有竞争力的功能)

Akka provides scalable real-time transaction processing. (Akka提供可扩展的实时事务处理)

Akka is an unified runtime and programming model for: (Akka是一个运行与编程统一的模型系统，为以下目标设计)

• Scale up (Concurrency) (垂直扩展(并行))
• Scale out (Remoting) (水平扩展(远程))
• Fault tolerance (容错性)

One thing to learn and admin, with high cohesion and coherent semantics. (在Akka的世界里，只有一个内容需要学习和管理，具有高内聚和高一致的语义)

Akka is a very scalable piece of software, not only in the context of performance but also 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.
(Akka是一种高度可扩展的软件，这不仅仅表现在性能方面，也表现在它所适用的应用的大小。Akka的核心，Akka-actor是非常小的，可以非常方便地放进你的应用中，提供你需要的异步无锁并行功能，不会有任何困扰)

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 users to choose the right tool for the job.
(你可以任意选择Akka的某些部分集成到你的应用中，也可以使用完整的包——Akka 微内核，它是一个独立的容器，可以直接部署你的Akka应用。随着CPU核数越来越多，即使你只使用一台电脑，Akka也可作为一种提供卓越性能的选择。Akka还同时提供多种并发范型，允许用户选择正确的工具来完成工作)

What’s a good use-case for Akka? (什么场景下特别适合使用Akka)

We see Akka being adopted by many large organizations in a big range of industries: (我们看到Akka被众多行业的大企业采用)

• Investment and Merchant Banking (投资和商业银行)
• Retail (零售业)
• Social Media (社交媒体)
• Simulation (仿真)
• Gaming and Betting (游戏和赌博)
• Automobile and Traffic Systems (汽车和交通系统)
• Health Care (医疗保健)
• Data Analytics (数据分析)

and much more. Any system with the need for high-throughput and low latency is a good candidate for using Akka. (任何需要高吞吐率和低延迟的系统都是使用Akka的候选)

Actors let you manage service failures (Supervisors), load management (back-off strategies, timeouts and processing-isolation), as well as both horizontal and vertical scalability (add more cores and/or add more machines).
(Actor使你能够进行服务失败管理（监管者），负载管理（缓和策略、超时和隔离），水平和垂直方向上的可扩展性（增加cpu核数和/或增加更多的机器）管理)

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

---

Getting Started

Prerequisites

Akka requires that you have Java 1.6 or later installed on you machine.

Getting Started Guides and Template Projects

The best way to start learning Akka is to download Typesafe Activator and try out one of Akka Template Projects.

Download

There are several ways to download Akka. You can download it as part of the Typesafe Platform (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非常模块化，不同的JARs包含不同的功能)

• akka-actor – Classic Actors, Typed Actors, IO Actor etc. (标准Actors，类型化Actors，IO Actors 等等)
• akka-agent – Agents, integrated with Scala STM (代理，集成了Scala的STM(software transactional memory))
• akka-camel – Apache Camel integration (集成 Apache Camel)
• akka-cluster – Cluster membership management, elastic routers. (集群成员管理，弹性的路由器)
• akka-kernel – Akka microkernel for running a bare-bones mini application server (Akka微内核，可运行一个基本的小型应用服务器)
• akka-osgi – base bundle for using Akka in OSGi containers, containing the akka-actor classes (在OSGi容器中使用Akka的基本捆绑包，包含了akka-actor类)
• akka-osgi-aries – Aries blueprint for provisioning actor systems (提供Actor系统的Aries蓝图)
• akka-remote – Remote Actors (远程 Actors)
• akka-slf4j – SLF4J Logger (event bus listener)
• akka-testkit – Toolkit for testing Actor systems (测试工具包)
• akka-zeromq – ZeroMQ integration (集成 ZeroMQ)

In addition to these stable modules there are several which are on their way into the stable core but are still marked “experimental” at this point. This does not mean that they do not function as intended, it primarily means that their API has not yet solidified enough in order to be considered frozen. You can help accelerating this process by giving feedback on these modules on our mailing list.
(除了稳定版的模块之外，还有一些实验性的模块，以它们自己的方式引入稳定版核心。这并不意味着它们是一开始就没被考虑功能，而是主要意味着它们的API没有足够稳定。可以通过邮件反馈意见来促进我们改善这些模块。)
- akka-contrib – an assortment of contributions which may or may not be moved into core modules, see External Contributions for more details. (可能引入核心模块的投稿分类)

The filename of the actual JAR is for example akka-actor_2.10-2.3.9.jar (and analog for the other modules).

How to see the JARs dependencies of each Akka module is described in the 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.

Warning
The use of Akka SNAPSHOTs, nightlies and milestone releases is discouraged unless you know what you are doing.

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.
(Akka发布版包括微内核版。要运行微内核，将你的应用的jar包放到 deploy 目录下并运行 bin 目录下的脚本)
More information is available in the documentation of the Microkernel (Scala) / Microkernel (Java).

Using a build tool (使用build工具)

Akka can be used with build tools that support Maven repositories.

Maven repositories

For Akka version 2.1-M2 and onwards:
Maven Central

For previous Akka versions:
Akka Repo Typesafe Repo

Using Akka with Maven

The simplest way to get started with Akka and Maven is to check out the Typesafe Activator tutorial named Akka Main in Java.

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:

<dependency>
    <groupId>com.typesafe.akka</groupId>
    <artifactId>akka-actor_2.10</artifactId>
    <version>2.3.9</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 project.

Summary of the essential parts for using Akka with SBT:

SBT installation instructions on https://github.com/harrah/xsbt/wiki/Setup

build.sbt file:

    name := "My Project"

    version := "1.0"

    scalaVersion := "2.10.4"

    resolvers += "Typesafe Repository" at "http://repo.typesafe.com/typesafe/releases/"

    libraryDependencies +=
    "com.typesafe.akka" %% "akka-actor" % "2.3.9"

Note: the libraryDependencies setting above is specific to SBT v0.12.x and higher. If you are using an older version of SBT, the libraryDependencies should look like this:

    libraryDependencies +=
    "com.typesafe.akka" % "akka-actor_2.10" % "2.3.9"

Using Akka with Gradle

Requires at least Gradle 1.4 Uses the Scala plugin

    apply plugin: 'scala'

    repositories {
    mavenCentral()
    }

    dependencies {
    compile 'org.scala-lang:scala-library:2.10.4'
    }

    tasks.withType(ScalaCompile) {
    scalaCompileOptions.useAnt = false
    }

    dependencies {
    compile group: 'com.typesafe.akka', name: 'akka-actor_2.10', version: '2.3.9'
    compile group: 'org.scala-lang', name: 'scala-library', version: '2.10.4'
    }

Using Akka with Eclipse

Setup SBT project and then use sbteclipse to generate a Eclipse project.

Using Akka with IntelliJ IDEA

Setup SBT project and then use sbt-idea to generate a IntelliJ IDEA project.

Using Akka with NetBeans

Setup SBT project and then use nbsbt to generate a NetBeans project.

You should also use nbscala for general scala support in the IDE.

Do not use -optimize Scala compiler flag
Warning
Akka has not been compiled or tested with -optimize Scala compiler flag. Strange behavior has been reported by users that have tried it.(不要用带优化参数的Scala编译器编译Akka。有尝试过的用户报道说会有奇怪的现象)

Build from sources

Akka uses Git and is hosted at Github.

• Akka: clone the Akka repository from http://github.com/akka/akka

Continue reading the page on Building Akka

Need help?

If you have questions you can get help on the Akka Mailing List.

You can also ask for commercial support.

Thanks for being a part of the Akka community.

---

The Obligatory Hello World

The actor based version of the tough problem of printing a well-known greeting to the console is introduced in a Typesafe Activator tutorial named Akka Main in Scala.
(在Typesafe Activator指南中的Akka Main in Scala介绍了基于打印清晰的问候到控制台版这个艰难问题的actor)
The tutorial illustrates the generic launcher class akka.Main which expects only one command line argument: the class name of the application’s main actor. This main method will then create the infrastructure needed for running the actors, start the given main actor and arrange for the whole application to shut down once the main actor terminates.
(指南举例说明了只需要一行指令行参数的通用启动类 akka.Main，参数为: 应用的main actor的class name。这个main方法会创建运行actors的基础结构，启动main actor，当main actor停止时关闭应用。)
There is also another Typesafe Activator tutorial in the same problem domain that is named Hello Akka!. It describes the basics of Akka in more depth.

---

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 Microkernel (Scala) / 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.
(Web App应用Akka最可能的方式。)
Using Akka as a stand alone microkernel
Akka can also be run as a stand-alone microkernel. See Microkernel (Scala) / Microkernel (Java) for more information.

---

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
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