Akka Java Documentation Release 2.4.20 Lightbend Inc August 10, 2017 CONTENTS 1 Security Announcements1 1.1 Receiving Security Advisories....................................1 1.2 Reporting Vulnerabilities.......................................1 1.3 Security Related Documentation...................................1 1.4 Fixed Security Vulnerabilities....................................1 2 Introduction 4 2.1 What is Akka?............................................4 2.2 Why Akka?..............................................5 2.3 Getting Started............................................6 2.4 The Obligatory Hello World..................................... 10 2.5 Use-case and Deployment Scenarios................................. 10 2.6 Examples of use-cases for Akka................................... 11 3 General 13 3.1 Terminology, Concepts........................................ 13 3.2 Actor Systems............................................ 15 3.3 What is an Actor?.......................................... 17 3.4 Supervision and Monitoring..................................... 19 3.5 Actor References, Paths and Addresses............................... 24 3.6 Location Transparency........................................ 30 3.7 Akka and the Java Memory Model.................................. 31 3.8 Message Delivery Reliability.................................... 33 3.9 Configuration............................................. 38 4 Actors 102 4.1 Actors................................................ 102 4.2 Typed Actors............................................. 122 4.3 Fault Tolerance............................................ 131 4.4 Dispatchers.............................................. 146 4.5 Mailboxes.............................................. 149 4.6 Routing................................................ 156 4.7 Building Finite State Machine Actors................................ 176 4.8 Persistence.............................................. 179 4.9 Persistence - Schema Evolution................................... 210 4.10 Persistence Query.......................................... 224 4.11 Persistence Query for LevelDB................................... 234 4.12 Testing Actor Systems........................................ 237 5 Actors (Java with Lambda Support) 254 5.1 Actors (Java with Lambda Support)................................. 254 5.2 Fault Tolerance (Java with Lambda Support)............................ 274 5.3 FSM (Java with Lambda Support).................................. 288 5.4 Persistence (Java with Lambda Support)............................... 297 i 6 Futures and Agents 330 6.1 Futures................................................ 330 6.2 Agents................................................ 337 7 Networking 340 7.1 Cluster Specification......................................... 340 7.2 Cluster Usage............................................. 346 7.3 Cluster Singleton........................................... 366 7.4 Distributed Publish Subscribe in Cluster............................... 369 7.5 Cluster Client............................................. 373 7.6 Cluster Sharding........................................... 378 7.7 Cluster Metrics Extension...................................... 389 7.8 Distributed Data........................................... 396 7.9 Remoting............................................... 416 7.10 Remoting (codename Artery).................................... 427 7.11 Serialization............................................. 442 7.12 I/O.................................................. 448 7.13 Using TCP.............................................. 450 7.14 Using UDP.............................................. 461 7.15 Camel................................................. 465 8 Utilities 478 8.1 Event Bus............................................... 478 8.2 Logging................................................ 485 8.3 Scheduler............................................... 492 8.4 Duration............................................... 494 8.5 Circuit Breaker............................................ 496 8.6 Akka Extensions........................................... 500 8.7 Use-case and Deployment Scenarios................................. 503 9 Streams 505 9.1 Introduction............................................. 505 9.2 Quick Start Guide.......................................... 506 9.3 Reactive Tweets........................................... 508 9.4 Design Principles behind Akka Streams............................... 513 9.5 Basics and working with Flows................................... 516 9.6 Working with Graphs......................................... 523 9.7 Modularity, Composition and Hierarchy............................... 535 9.8 Buffers and working with rate.................................... 546 9.9 Dynamic stream handling...................................... 549 9.10 Custom stream processing...................................... 554 9.11 Integration.............................................. 574 9.12 Error Handling............................................ 588 9.13 Working with streaming IO..................................... 590 9.14 Pipelining and Parallelism...................................... 593 9.15 Testing streams............................................ 596 9.16 Overview of built-in stages and their semantics........................... 599 9.17 Streams Cookbook.......................................... 624 9.18 Configuration............................................. 638 9.19 Migration Guide 1.0 to 2.x...................................... 640 9.20 Migration Guide 2.0.x to 2.4.x.................................... 640 10 Akka HTTP Documentation (Java) moved! 644 11 HowTo: Common Patterns 645 11.1 Scheduling Periodic Messages.................................... 645 11.2 Single-Use Actor Trees with High-Level Error Reporting...................... 646 12 Experimental Modules 650 ii 12.1 Multi Node Testing.......................................... 650 12.2 Actors (Java with Lambda Support)................................. 655 12.3 FSM (Java with Lambda Support).................................. 675 12.4 Persistence Query.......................................... 684 12.5 External Contributions........................................ 694 13 Information for Akka Developers 716 13.1 Building Akka............................................ 716 13.2 Multi JVM Testing.......................................... 718 13.3 I/O Layer Design........................................... 721 13.4 Developer Guidelines........................................ 723 13.5 Documentation Guidelines...................................... 724 14 Project Information 727 14.1 Migration Guides........................................... 727 14.2 Issue Tracking............................................ 745 14.3 Licenses............................................... 746 14.4 Sponsors............................................... 746 14.5 Project................................................ 746 15 Additional Information 749 15.1 Binary Compatibility Rules..................................... 749 15.2 Frequently Asked Questions..................................... 752 15.3 Books................................................. 755 15.4 Videos................................................ 755 15.5 Akka in OSGi............................................ 755 iii CHAPTER ONE SECURITY ANNOUNCEMENTS 1.1 Receiving Security Advisories The best way to receive any and all security announcements is to subscribe to the Akka security list. The mailing list is very low traffic, and receives notifications only after security reports have been managed by the core team and fixes are publicly available. 1.2 Reporting Vulnerabilities We strongly encourage people to report such problems to our private security mailing list first, before disclosing them in a public forum. Following best practice, we strongly encourage anyone to report potential security vulnerabilities to secu- [email protected] before disclosing them in a public forum like the mailing list or as a Github issue. Reports to this email address will be handled by our security team, who will work together with you to ensure that a fix can be provided without delay. 1.3 Security Related Documentation • disable-java-serializer-scala • remote-deployment-whitelist-scala • remote-security-scala 1.4 Fixed Security Vulnerabilities 1.4.1 Java Serialization, Fixed in Akka 2.4.17 Date 10 Feburary 2017 Description of Vulnerability An attacker that can connect to an ActorSystem exposed via Akka Remote over TCP can gain remote code execution capabilities in the context of the JVM process that runs the ActorSystem if: • JavaSerializer is enabled (default in Akka 2.4.x) 1 Akka Java Documentation, Release 2.4.20 • and TLS is disabled or TLS is enabled with akka.remote.netty.ssl.security.require-mutual-authentication = false (which is still the default in Akka 2.4.x) • or if TLS is enabled with mutual authentication and the authentication keys of a host that is allowed to connect have been compromised, an attacker gained access to a valid certificate (e.g. by compromising a node with certificates issued by the same internal PKI tree to get access of the certificate) • regardless of whether untrusted mode is enabled or not Java deserialization is known to be vulnerable to attacks when attacker can provide arbitrary types. Akka Remoting uses Java serialiser as default configuration which makes it vulnerable in