Revamping of seed template into a "Hello World" Akka tutorial. Completely new sample code and docs.
diff --git a/.travis.yml b/.travis.yml
index 64235ba..94d7ccf 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -1,4 +1,7 @@
language: scala
+scala:
+ - 2.11.11
+ - 2.12.2
# These directories are cached to S3 at the end of the build
cache:
diff --git a/COPYING b/COPYING
new file mode 100644
index 0000000..0e259d4
--- /dev/null
+++ b/COPYING
@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+ CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+ LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+ ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+ INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+ REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+ PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+ THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+ HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+ i. the right to reproduce, adapt, distribute, perform, display,
+ communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+ likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+ subject to the limitations in paragraph 4(a), below;
+ v. rights protecting the extraction, dissemination, use and reuse of data
+ in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+ European Parliament and of the Council of 11 March 1996 on the legal
+ protection of databases, and under any national implementation
+ thereof, including any amended or successor version of such
+ directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+ world based on applicable law or treaty, and any national
+ implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+ surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+ warranties of any kind concerning the Work, express, implied,
+ statutory or otherwise, including without limitation warranties of
+ title, merchantability, fitness for a particular purpose, non
+ infringement, or the absence of latent or other defects, accuracy, or
+ the present or absence of errors, whether or not discoverable, all to
+ the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+ that may apply to the Work or any use thereof, including without
+ limitation any person's Copyright and Related Rights in the Work.
+ Further, Affirmer disclaims responsibility for obtaining any necessary
+ consents, permissions or other rights required for any use of the
+ Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+ party to this document and has no duty or obligation with respect to
+ this CC0 or use of the Work.
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..874bcd3
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,10 @@
+Giter8 Template by Lightbend, Inc.
+
+Licensed under Public Domain (CC0)
+
+To the extent possible under law, the person who associated CC0 with
+this Activator Tempate has waived all copyright and related or neighboring
+rights to this Activator Template.
+
+You should have received a copy of the CC0 legalcode along with this
+work. If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
diff --git a/build.sbt b/build.sbt
index 45e985f..bccb967 100644
--- a/build.sbt
+++ b/build.sbt
@@ -1,11 +1,18 @@
// This build is for this Giter8 template.
// To test the template run `g8` or `g8Test` from the sbt session.
// See http://www.foundweekends.org/giter8/testing.html#Using+the+Giter8Plugin for more details.
-lazy val root = (project in file(".")).
- settings(
+lazy val root = (project in file("."))
+ .settings(
+ name := "akka-scala-seed",
test in Test := {
val _ = (g8Test in Test).toTask("").value
},
scriptedLaunchOpts ++= List("-Xms1024m", "-Xmx1024m", "-XX:ReservedCodeCacheSize=128m", "-XX:MaxPermSize=256m", "-Xss2m", "-Dfile.encoding=UTF-8"),
resolvers += Resolver.url("typesafe", url("http://repo.typesafe.com/typesafe/ivy-releases/"))(Resolver.ivyStylePatterns)
)
+
+// Documentation for this project:
+// sbt "project docs" "~ paradox"
+// open docs/target/paradox/site/main/index.html
+lazy val docs = (project in file("docs"))
+ .enablePlugins(ParadoxPlugin)
diff --git a/docs/build.sbt b/docs/build.sbt
new file mode 100644
index 0000000..7222d72
--- /dev/null
+++ b/docs/build.sbt
@@ -0,0 +1,10 @@
+// Uses the out of the box generic theme.
+paradoxTheme := Some(builtinParadoxTheme("generic"))
+
+scalaVersion := "2.12.2"
+
+paradoxProperties in Compile ++= Map(
+ "snip.g8root.base_dir" -> "../../../../src/main/g8",
+ "snip.g8src.base_dir" -> "../../../../src/main/g8/src/main/",
+ "snip.g8srctest.base_dir" -> "../../../../src/main/g8/src/test/"
+)
diff --git a/docs/src/main/paradox/communicate-with-actors.md b/docs/src/main/paradox/communicate-with-actors.md
new file mode 100644
index 0000000..b85466a
--- /dev/null
+++ b/docs/src/main/paradox/communicate-with-actors.md
@@ -0,0 +1,17 @@
+Communicate with Actors
+-----------------------
+
+All communication with Actors is done through asynchronous message passing. This is what makes Actors reactive and message driven. An Actor doesn't do anything unless it's been told to do something, and we tell it to do something by sending the message. Sending a message asynchronously means that the sender does not stick around waiting for the message to be processed by the recipient actor. Instead, the Actor hands the message off by putting it on the recipient's mailbox and is then free to do something more important than waiting for the recipient to react on the message. The Actor's mailbox is essentially a
+message queue and has ordering semantics, this guarantees that the ordering of multiple messages sent from the same Actor is preserved, while they can be interleaved with the messages sent by another actor.
+
+You might be wondering what the Actor is doing when it is not processing messages, i.e. doing actual work? It is in a suspended state in which it does not consume any resources apart from memory.
+
+You tell an Actor to do something by passing a message into the `!` (bang) method on the `ActorRef`. This method puts the message on the Actor's mailbox.
+
+In the main class we send messages to the `Greeter` Actor:
+
+@@snip [AkkaQuickstart.scala]($g8src$/scala/com/lightbend/akka/sample/AkkaQuickstart.scala) { #main-send-messages }
+
+The `Greeter` Actor also sends a message to the `Printer` Actor:
+
+@@snip [AkkaQuickstart.scala]($g8src$/scala/com/lightbend/akka/sample/AkkaQuickstart.scala) { #greeter-send-message }
diff --git a/docs/src/main/paradox/create-actors.md b/docs/src/main/paradox/create-actors.md
new file mode 100644
index 0000000..f1cec5e
--- /dev/null
+++ b/docs/src/main/paradox/create-actors.md
@@ -0,0 +1,28 @@
+Create the Actors
+-----------------
+
+So far we have defined our Actors and its messages. Now let's create instances of the actors.
+
+### The Power of Location Transparency
+
+In Akka you *can't* create an instance of an Actor the regular way using `new`, instead, you create it using a factory. What is returned from this factory is not an instance of the Actor itself but an `akka.actor.ActorRef` pointing to the actor instance. This level of indirection adds a lot of power and flexibility. It enables for example location transparency
+meaning that the `ActorRef` can, while retaining the same semantics, represent an instance of the running actor
+in-process or on a remote machine. _In Akka location doesn't matter_. This also means that the runtime can if needed to
+optimize the system by changing an Actor's location or the application's topology while it is running. Another
+thing that this level of indirection enables is the "let it crash" model of failure management in which the
+system can heal itself by crashing and restarting faulty Actors.
+
+### The Akka ActorSystem
+
+This factory used to create Actors in Akka is called an `akka.actor.ActorSystem` and is, to some extent, similar to Spring's `BeanFactory` in that it also acts as a container for your Actors, managing their life-cycles etc. We create an Actor through the `actorOf` factory method. This method takes a configuration object called `Props` and a name.
+Actor (and ActorSystem) names are important in Akka, you use them for example when looking up Actors. One advice is to try to keep the names in accordance with your domain model as this makes things easier to reason about down the road.
+
+In the previous section we defined two actors; `Greeter` and `Printer`. Let's go ahead and create instances of these:
+
+@@snip [AkkaQuickstart.scala]($g8src$/scala/com/lightbend/akka/sample/AkkaQuickstart.scala) { #create-actors }
+
+As you can see we start off by creating the `Printer` Actor using the `actorOf` method on the `ActorSystem`. Note that we are using the `props` method of the `Printer` companion object to get the `Props` value (as we discussed in the previous section).
+
+Once we have a reference, i.e. `ActorRef`, to the `Printer` Actor we can create the `Greeter` actor instances. In this case, we create three Actor instances each with its specific greeting message. The `Greeter` Actors will all use the same `Printer` instance, but we could have created multiple instances of the `Printer` Actor if we would have wanted to. In this sample, we use one because we want to illustrate an important concept of message passing. More about this later.
+
+Now that we have running instances of `Printer` and `Greeter` actors we will look at how to communicate with actors.
diff --git a/docs/src/main/paradox/define-actors.md b/docs/src/main/paradox/define-actors.md
new file mode 100644
index 0000000..a24073a
--- /dev/null
+++ b/docs/src/main/paradox/define-actors.md
@@ -0,0 +1,48 @@
+Define the Actors
+-----------------
+
+The Actor is the unit of execution in Akka. Actors are object-oriented in the sense that they encapsulate state and behavior, but they have much stronger isolation than regular objects in Scala.
+
+The Actor model prevents sharing state between Actors and the only way to observe another actor's state is by sending it a message asking for it. Actors are extremely lightweight, they are only constrained by the memory of which they consume only a few hundred bytes each — this means you can easily create millions of concurrent Actors in a single application. Their strong isolation principles together with the event-driven model (that we will talk about later on) and location transparency makes it easy to solve hard concurrency and scalability problems in an intuitive way.
+
+In this example application, we will define two actors: `Greeter` and `Printer`.
+
+### The Greeter Actor
+
+The `Greeter` Actor handles the creation of greeting messages and communicates with the `Printer` actor when instructed to. Let's take a look at its companion object and implementation to get a better understanding of what it looks like.
+
+#### The Greeter Actor's Companion Object
+
+Let's start by looking at the companion object of `Greeter` (which we have already have seen some parts of in the previous section):
+
+@@snip [AkkaQuickstart.scala]($g8src$/scala/com/lightbend/akka/sample/AkkaQuickstart.scala) { #greeter-companion }
+
+Apart from containing the messages, the `Greeter` actor expects the companion object also contains a `props` method. To create a `props` method in the companion object of an Actor is a very common pattern. Think of a `props` method as the factory method for how to create instances of this Actor. The `props` method creates and returns a `Props` instance. `Props` is a configuration class to specify options for the creation of actors, think of it as an immutable and thus freely shareable recipe for creating an actor including associated deployment information. In this example, we just pass on the parameters that the Actor requires when being constructed. We will see the `props` method in action later in this tutorial.
+
+#### The Greeter Actor Implementation
+
+Here below is the `Greeter` Actor implementation:
+
+@@snip [AkkaQuickstart.scala]($g8src$/scala/com/lightbend/akka/sample/AkkaQuickstart.scala) { #greeter-actor }
+
+We create an Actor by defining a class that extends `akka.actor.Actor` trait and implements the `receive` method. It is in the `receive` method that we define the behavior; how the Actor should react to the different messages it receives. An Actor can have state and accessing or mutating the internal state of an Actor is fully thread safe since it is protected by the Actor model. The `Greeter` Actor implementation keeps a state in its variable `greeting` which by default is set to `""`.
+
+Actors can, like every other class, have constructors that define parameters. The constructor of `Greeter` accepts two parameters: `message: String` which will be used when building greeting messages and `printerActor: ActorRef` which is a reference to the Actor handling the outputting of the greeting.
+
+The `receive` method should handle the messages the actor expects. In the case of `Greeter`, it expects two types of messages: `WhoToGreet` and `Greet`. The former will update the `greeting` state of the Actor and the latter will trigger a sending of the `greeting` to the `Printer` Actor.
+
+### The Printer Actor
+
+Instead of rehashing all the explanations in the sections above we will just look at the source code of the `Printer` Actor.
+
+#### Companion Object
+
+As expected, the companion object of `Printer` defines a `props` method and the message that the Actor expects:
+
+@@snip [AkkaQuickstart.scala]($g8src$/scala/com/lightbend/akka/sample/AkkaQuickstart.scala) { #printer-companion }
+
+#### Implementation
+
+The `Printer` implementation is very simple. It just handles one type of message, `Greeting`, and logs the content of that message. One thing to highlight is that by extending `akka.actor.ActorLogging` we automatically get a reference to a logger. By doing this we can write `log.info()` in the `receive` method without any additional importing, wiring, etc.
+
+@@snip [AkkaQuickstart.scala]($g8src$/scala/com/lightbend/akka/sample/AkkaQuickstart.scala) { #printer-actor }
diff --git a/docs/src/main/paradox/define-messages.md b/docs/src/main/paradox/define-messages.md
new file mode 100644
index 0000000..b5a64d0
--- /dev/null
+++ b/docs/src/main/paradox/define-messages.md
@@ -0,0 +1,28 @@
+
+Define the Messages
+-------------------
+
+An Actor does not have a public API in terms of methods that you can invoke. Instead its public
+API is defined through messages that the actor handles. Messages can be of arbitrary type (any subtype of `Any`).
+This means that we can send boxed primitive values (such as `String`, `Integer`, `Boolean` etc.) as messages as well as plain data structures like arrays and collection types.
+
+However, since the messages are the Actor's public API, you should define messages with good names and rich semantic and domain specific meaning, even if it's just wrapping your data type. This will make it easier to use, understand and debug actor-based systems.
+
+Case classes and case objects make excellent messages since they are immutable and have support for pattern matching,
+something we will take advantage of in the Actor when matching on the messages it has received.
+
+_A pattern that we apply when building actor based systems is that we try to put the associated message into the companion object of the actor_. This way it is easier to understand what messages the actor expects and handles.
+
+In this example we will define three different messages:
+
+- `WhoToGreet`: who the actor should greet
+- `Greet`: instruction to execute greeting
+- `Greeting`: message containing the greeting
+
+Messages handled by the `Greeter` Actor (defined in its companion object):
+
+@@snip [AkkaQuickstart.scala]($g8src$/scala/com/lightbend/akka/sample/AkkaQuickstart.scala) { #greeter-messages }
+
+Message handled by the `Printer` Actor (defined in its companion object):
+
+@@snip [AkkaQuickstart.scala]($g8src$/scala/com/lightbend/akka/sample/AkkaQuickstart.scala) { #printer-messages }
diff --git a/docs/src/main/paradox/full-example.md b/docs/src/main/paradox/full-example.md
new file mode 100644
index 0000000..eec94bc
--- /dev/null
+++ b/docs/src/main/paradox/full-example.md
@@ -0,0 +1,8 @@
+Full Example Code
+-----------------
+
+Here below is the complete source code of the sample application:
+
+@@snip [AkkaQuickstart.scala]($g8src$/scala/com/lightbend/akka/sample/AkkaQuickstart.scala)
+
+Let's move on to try this out but before we run the application we should ensure that we have some test coverage as the astute developers we are.
diff --git a/docs/src/main/paradox/images/hello-akka-architecture.png b/docs/src/main/paradox/images/hello-akka-architecture.png
new file mode 100644
index 0000000..0237557
--- /dev/null
+++ b/docs/src/main/paradox/images/hello-akka-architecture.png
Binary files differ
diff --git a/docs/src/main/paradox/images/hello-akka-messages.png b/docs/src/main/paradox/images/hello-akka-messages.png
new file mode 100644
index 0000000..09d705e
--- /dev/null
+++ b/docs/src/main/paradox/images/hello-akka-messages.png
Binary files differ
diff --git a/docs/src/main/paradox/images/intellij-open-project.png b/docs/src/main/paradox/images/intellij-open-project.png
new file mode 100644
index 0000000..5844cba
--- /dev/null
+++ b/docs/src/main/paradox/images/intellij-open-project.png
Binary files differ
diff --git a/docs/src/main/paradox/images/intellij-run-output.png b/docs/src/main/paradox/images/intellij-run-output.png
new file mode 100644
index 0000000..1aeb8a8
--- /dev/null
+++ b/docs/src/main/paradox/images/intellij-run-output.png
Binary files differ
diff --git a/docs/src/main/paradox/images/intellij-test-output.png b/docs/src/main/paradox/images/intellij-test-output.png
new file mode 100644
index 0000000..2337d64
--- /dev/null
+++ b/docs/src/main/paradox/images/intellij-test-output.png
Binary files differ
diff --git a/docs/src/main/paradox/index.md b/docs/src/main/paradox/index.md
new file mode 100644
index 0000000..142964f
--- /dev/null
+++ b/docs/src/main/paradox/index.md
@@ -0,0 +1,76 @@
+Akka Quickstart with Scala
+==========================
+
+[Akka](http://akka.io) is a toolkit and runtime for building highly concurrent,
+distributed, and fault-tolerant event-driven applications on the JVM. Akka can be used with both Java
+and Scala.
+
+This tutorial will guide you through the some basic but fundamental Akka building blocks.
+
+The sample project for this tutorial is called `akka-scala-seed` and can be found in [Get started with Lightbend technologies](http://dev.lightbend.com/start/?group=akka&project=akka-scala-seed). Unzip the zip file and, if wanted, rename the directory to your preference:
+
+OSX
+: ```
+$ unzip akka-scala-seed.zip
+$ cd akka-scala-seed
+Note: If you unzip with Archiver instead of via the Terminal you also have to make the sbt files executable:
+$ chmod u+x ./sbt
+$ chmod u+x ./sbt-dist/bin/sbt
+```
+
+Linux
+: ```
+$ unzip akka-scala-seed.zip
+$ cd akka-scala-seed
+```
+
+Windows
+: ```
+Unzip the zip file and then open a Command Line window and change directory into the unzipped project:
+$ cd akka-scala-seed
+```
+
+If you prefer to use Akka with Java you can find its tutorial [here](http://developer.lightbend.com/start/?group=akka&project=akka-java-seed).
+
+## The Sample Application
+
+The code in this example is intentionally kept simple. This is a getting started tutorial for someone who has no,
+or very little, previous knowledge about Akka. Since this tutorial is using [Scala](http://scala-lang.org/) it is good if the reader has a basic understanding thereof.
+
+The aim of this tutorial is to show the interested reader some core concepts of Akka that will not take more than approximately 30 minutes. It will get our feet wet and, hopefully, inspire us to dive deeper into the wonderful sea of Akka!
+
+### Design
+
+We will create a main class from which we create an `akka.actor.ActorSystem` (think of this as a container in which your Actors run). Once we have created an `ActorSystem` we create a couple of Actors; 3 instances of a `Greeter` Actor and 1 instance of a `Printer` Actor. We will thereafter send messages to the `Greeter` Actor instances which will keep these messages internally. Finally, we send instruction messages to our `Greeter` Actors that will trigger them to send messages to the `Printer` Actor for output.
+
+Let's take a look at the architecture. As said above, we will run everything from the main class. The main class will create and interact with the Actors:
+
+
+
+Once we have created the Actors we will send messages to them:
+
+
+
+Don't worry if this doesn't make complete sense at this point! This tutorial will describe all the core concepts you need to build an Akka application.
+
+## The 3 Minute Exploration
+
+If you don't want to go through all the steps of this tutorial you can jump straight @ref:[full example](full-example.md) to see the source code and then to @ref:[running the application](running-the-application.md). This way you can look at the code and the output and get a very brief introduction to Akka. It is, however, recommended that you follow this tutorial step-by-step to gain a good understanding of the core concepts of Akka.
+
+If you are interested in an more in-depth understanding of the core concepts we recommend the [Getting Started Guide](http://doc.akka.io/docs/akka/2.5/scala.html).
+
+Next, let's dive into the tutorial and its individual building blocks.
+
+@@@index
+
+* [Define the Messages](define-messages.md)
+* [Define the Actors](define-actors.md)
+* [Create the Actors](create-actors.md)
+* [Communicate with Actors](communicate-with-actors.md)
+* [The Main Class](main-class.md)
+* [Full Example](full-example.md)
+* [Testing Actors](testing-actors.md)
+* [Running the Application](running-the-application.md)
+* [IntelliJ](intellij-idea.md)
+
+@@@
diff --git a/docs/src/main/paradox/intellij-idea.md b/docs/src/main/paradox/intellij-idea.md
new file mode 100644
index 0000000..c49d581
--- /dev/null
+++ b/docs/src/main/paradox/intellij-idea.md
@@ -0,0 +1,28 @@
+IntelliJ IDEA
+-------------
+
+[IntelliJ](https://www.jetbrains.com/idea/) from JetBrains is one of the leading IDEs in the Java/Scala community and it has excellent support for Akka. This section will guide you through setting up, testing and running the sample project.
+
+### Setting up the Project
+
+Open IntelliJ and select `File -> Open...` and point to the directory where you have installed the sample project. A dialogue like this will pop up:
+
+
+
+Fill out the settings according to the above and press `OK` to import the project. When IntelliJ will warn about missing Scala SDK it is only to follow the instructions to add support.
+
+### Inspecting Project Code
+
+If we open up the file `src/main/scala/com/lightbend/akka/sample/AkkaQuickstart.scala` we will see a lot of lines beginning with `//# ...`. These lines are used as directives for this documentation. To get rid of these lines from the source code we can utilize the awesome Find/Replace functionality in IntelliJ. Select `Edit -> Find -> Replace in Path...`. Check the `Regex` box and add the following regex `[//#].*` and click on `Replace in Find Window...`. Select to replace all occurrences and voila the lines are gone!
+
+### Testing and Running
+
+For testing we simply right click on the file `src/test/scala/com/lightbend/akka/sample/AkkaQuickstartSpec.scala` and select `Run 'AkkaQuickstartSpec'`:
+
+
+
+Similarly to run the application we right click on the file `src/main/scala/com/lightbend/akka/sample/AkkaQuickstart.scala` and select `Run 'AkkaQuickstart'`:
+
+
+
+For more detailed information about please see the @ref:[running the application](running-the-application.md) section.
diff --git a/docs/src/main/paradox/main-class.md b/docs/src/main/paradox/main-class.md
new file mode 100644
index 0000000..25a3ea7
--- /dev/null
+++ b/docs/src/main/paradox/main-class.md
@@ -0,0 +1,8 @@
+The Main Class
+--------------
+
+The main class is where we, in this example, create and control the actors. As previously explained we need an `ActorSystem` in which we can create the Actor instances. To create actors we use the `actorOf` method available in the `ActorSystem`. Once we have created the Actors the next thing we do is to send messages to them.
+
+@@snip [AkkaQuickstart.scala]($g8src$/scala/com/lightbend/akka/sample/AkkaQuickstart.scala) { #main-class }
+
+We will look and dissect the output when running this main class in the @ref:[Running the Application](running-the-application.md) section. Before we get there it is time to look at the complete source code of this sample application.
diff --git a/docs/src/main/paradox/running-the-application.md b/docs/src/main/paradox/running-the-application.md
new file mode 100644
index 0000000..7b535b3
--- /dev/null
+++ b/docs/src/main/paradox/running-the-application.md
@@ -0,0 +1,83 @@
+Running the Application
+-----------------------
+
+Before we run the application we have to first build it. Let's take a look at the build tool in action for this project: [sbt](http://www.scala-sbt.org). _If you prefer to run the application from an IDE instead of a Terminal window you should look at the @ref:[IntelliJ IDEA](intellij-idea.md) section._
+
+### The Build Files
+
+sbt uses a `build.sbt` file to handle the project. This project's `build.sbt` file looks like this:
+
+@@snip [build.sbt]($g8root$/build.sbt)
+
+This build file is very simple. In essence, it creates one project `hello-akka-scala` and declares the dependencies for this project. We must also declare what version of sbt to use and this is done in the file `project/build.properties`:
+
+@@snip [build.properties]($g8root$/project/build.properties)
+
+Now we are ready to build and run the project.
+
+### Compiling the Project
+
+We will use sbt to handle the compilation and run. We open a Terminal window and, from inside the project directory, type the following:
+
+```
+$ sbt
+> compile
+```
+
+The above should render an output _similar_ to this one:
+
+```
+[info] Loading global plugins from /Users/x/.sbt/0.13/plugins
+[info] Loading project definition from /Users/x/akka-quickstart-scala/project
+[info] Updating {file:/Users/x/hello-akka-scala/project/}akka-quickstart-scala-build...
+[info] Resolving org.fusesource.jansi#jansi;1.4 ...
+[info] Done updating.
+[info] Set current project to hello-akka-scala (in build file:/Users/x/akka-quickstart-scala/)
+[info] Updating {file:/Users/x/hello-akka-scala/}akka-quickstart--scala...
+[info] Resolving jline#jline;2.14.3 ...
+[info] Done updating.
+[info] Compiling 1 Scala source and 1 Java source to /Users/x/akka-quickstart-scala/target/scala-2.12/classes...
+[success] Total time: 5 s, completed May 9, 2017 9:52:34 AM
+```
+
+### Running the Project
+
+Now it is time to run the project. We will run it using `sbt` by issuing the following command in a Terminal window:
+
+```
+$ sbt
+> run
+```
+
+The output should look _something_ like this (scroll all the way to the right to see the Actor output):
+
+```
+[info] Loading global plugins from /Users/x/.sbt/0.13/plugins
+[info] Loading project definition from /Users/x/akka-quickstart-scala/project
+[info] Set current project to hello-akka-scala (in build file:/Users/x/akka-quickstart-scala)
+[info] Running com.lightbend.akka.sample.AkkaQuickstart
+>>> Press ENTER to exit <<<
+[INFO] [05/09/2017 09:57:15.979] [helloAkka-akka.actor.default-dispatcher-2] [akka://helloAkka/user/printerActor] Greeting received (from Actor[akka://helloAkka/user/howdyGreeter#-1854995773]): Howdy, Akka
+[INFO] [05/09/2017 09:57:15.980] [helloAkka-akka.actor.default-dispatcher-2] [akka://helloAkka/user/printerActor] Greeting received (from Actor[akka://helloAkka/user/helloGreeter#-1072877049]): Hello, Scala
+[INFO] [05/09/2017 09:57:15.980] [helloAkka-akka.actor.default-dispatcher-2] [akka://helloAkka/user/printerActor] Greeting received (from Actor[akka://helloAkka/user/goodDayGreeter#1972065097]): Good day, Play
+[INFO] [05/09/2017 09:57:15.980] [helloAkka-akka.actor.default-dispatcher-2] [akka://helloAkka/user/printerActor] Greeting received (from Actor[akka://helloAkka/user/howdyGreeter#-1854995773]): Howdy, Lightbend
+```
+
+Remember that we set our `Printer` Actor to use the Logger from Akka? This is why there is a lot of extra information when we log things. The log output contains information like when and from what actor it was logged. Let's focus on the output from the `Printer` Actor for a while:
+
+```
+... Howdy, Akka
+... Hello, Scala
+... Good day, Play
+... Howdy, Lightbend
+```
+
+This is the result of our code that sends messages to the `Greeter` Actor:
+
+@@snip [AkkaQuickstart.scala]($g8src$/scala/com/lightbend/akka/sample/AkkaQuickstart.scala) { #main-send-messages }
+
+Try running the code a couple of more times and make sure to notice the order of the logging. Does it remain the same or does it change? As you can see it changes sometimes when you run. What's happening here? For the sake of brevity, we will not explain this in detail. For now, it is enough to say that when you send messages to Actors this happens asynchronously and we have to design our program with this in mind. This is a new mindset but rest assured that it is not rocket science and once you get it everything will become clear; just like for <a href="https://en.wikipedia.org/wiki/Neo_(The_Matrix)">Neo in the Matrix</a>.
+
+### The Next Step
+
+This tutorial just scratches the surface of the functionality of Akka. The next natural step would be to continue with the [Getting Started Guide](http://doc.akka.io/docs/akka/2.5/scala.html) and the more detailed information about Akka and actor systems.
diff --git a/docs/src/main/paradox/testing-actors.md b/docs/src/main/paradox/testing-actors.md
new file mode 100644
index 0000000..413a742
--- /dev/null
+++ b/docs/src/main/paradox/testing-actors.md
@@ -0,0 +1,32 @@
+Testing Actors
+--------------
+
+We will use the [ScalaTest](http://www.scalatest.org/) framework to conduct the testing of our sample. The test coverage is not complete in this example. We leave that as an exercise for the interested reader. Instead, the test code is there to showcase how how easy it is to test actor code and also to provide some basic concepts.
+
+### Test Class Definition
+
+Let's start by looking at the test class definition:
+
+@@snip [AkkaQuickstartSpec.scala]($g8srctest$/scala/com/lightbend/akka/sample/AkkaQuickstartSpec.scala) { #test-classes }
+
+The test class extends `akka.test.TestKit` which is a module for integration testing of actors and actor systems. The showcased test class only uses a fraction of the functionality provided by [TestKit](http://doc.akka.io/docs/akka/2.5/scala/testing.html). The rest of the classes extended are from ScalaTest and the provide syntax and functionality that we use in our test cases. We will use `FlatSpecLike` with with we can write test specifications in the format of "X should Y", like this for example:
+
+@@snip [AkkaQuickstartSpec.scala]($g8srctest$/scala/com/lightbend/akka/sample/AkkaQuickstartSpec.scala) { #specification-example }
+
+### Test Methods
+
+Now that we know some of the basic concepts it is time to look at the implemented test methods.
+
+When working with Actors everything is asynchronous and as such we need to ensure that we can test this asynchronous behavior. This is where integration testing comes in handy. In this test we will create a so-called `TestProbe` that we can interrogate to verify the expected behavior. Once we have a reference to this `TestProbe` we pass it to `Greeter` as part of the constructor arguments. We thereafter send two messages to `Greeter`; one to set the greeting person to greet and another to trigger the sending of a `Greeting`. It is this sending that we then verify took place with the `expectMsg` method on the `TestProbe`. Let's look at the source code for this:
+
+@@snip [AkkaQuickstartSpec.scala]($g8srctest$/scala/com/lightbend/akka/sample/AkkaQuickstartSpec.scala) { #first-test }
+
+### Full Test Code
+
+@@snip [AkkaQuickstartSpec.scala]($g8srctest$/scala/com/lightbend/akka/sample/AkkaQuickstartSpec.scala) { #full-example }
+
+### Just the Surface
+
+The above code is just scratching the surface of the available functionality in `TestKit`. A complete overview can be found [here](http://doc.akka.io/docs/akka/2.5/scala/testing.html).
+
+Now that we are done writing all the code we should of course look at the output of it. The next section is all about running the code and it also analyzes the output thereof.
diff --git a/project/build.properties b/project/build.properties
index 27e88aa..64317fd 100644
--- a/project/build.properties
+++ b/project/build.properties
@@ -1 +1 @@
-sbt.version=0.13.13
+sbt.version=0.13.15
diff --git a/project/default.properties b/project/default.properties
index 8091e62..cf78f73 100644
--- a/project/default.properties
+++ b/project/default.properties
@@ -1,3 +1,2 @@
-name=My Something Project
-description=This is a seed project which creates a basic build for an Akka with Scala application.
-akka_version=2.4.16
+name=hello-akka-scala
+description=This is a seed project and tutorial which creates a basic Scala based Akka application.
diff --git a/project/paradox.sbt b/project/paradox.sbt
new file mode 100644
index 0000000..01bcc5c
--- /dev/null
+++ b/project/paradox.sbt
@@ -0,0 +1,2 @@
+// sbt-paradox, used for documentation
+addSbtPlugin("com.lightbend.paradox" % "sbt-paradox" % "0.2.11")
diff --git a/src/main/g8/build.sbt b/src/main/g8/build.sbt
index c84f6ec..83668b8 100644
--- a/src/main/g8/build.sbt
+++ b/src/main/g8/build.sbt
@@ -1,11 +1,13 @@
-import Dependencies._
+name := "akka-quickstart-scala"
-lazy val root = (project in file(".")).
- settings(
- inThisBuild(List(
- organization := "com.example",
- scalaVersion := "2.12.1"
- )),
- name := "$name$",
- libraryDependencies ++= Seq(akkaActor, akkaTestkit % Test, scalaTest % Test)
- )
+version := "1.0"
+
+scalaVersion := "2.12.2"
+
+lazy val akkaVersion = "2.5.1"
+
+libraryDependencies ++= Seq(
+ "com.typesafe.akka" %% "akka-actor" % akkaVersion,
+ "com.typesafe.akka" %% "akka-testkit" % akkaVersion,
+ "org.scalatest" %% "scalatest" % "3.0.1" % "test"
+)
diff --git a/src/main/g8/default.properties b/src/main/g8/default.properties
new file mode 100644
index 0000000..392d0bb
--- /dev/null
+++ b/src/main/g8/default.properties
@@ -0,0 +1,3 @@
+name = akka-quickstart-scala
+description = Akka is a toolkit and runtime for building highly concurrent, distributed, and fault tolerant event-driven apps. This simple application will get you started building Actor based systems with Scala. This app uses Akka, Scala, and ScalaTest.
+verbatim = *.scala
diff --git a/src/main/g8/project/Dependencies.scala b/src/main/g8/project/Dependencies.scala
deleted file mode 100644
index 00379e2..0000000
--- a/src/main/g8/project/Dependencies.scala
+++ /dev/null
@@ -1,8 +0,0 @@
-import sbt._
-
-object Dependencies {
- lazy val akkaVersion = "$akka_version$"
- lazy val akkaActor = "com.typesafe.akka" %% "akka-actor" % akkaVersion
- lazy val akkaTestkit = "com.typesafe.akka" %% "akka-testkit" % akkaVersion
- lazy val scalaTest = "org.scalatest" %% "scalatest" % "3.0.0"
-}
diff --git a/src/main/g8/project/build.properties b/src/main/g8/project/build.properties
index 27e88aa..64317fd 100644
--- a/src/main/g8/project/build.properties
+++ b/src/main/g8/project/build.properties
@@ -1 +1 @@
-sbt.version=0.13.13
+sbt.version=0.13.15
diff --git a/src/main/g8/src/main/scala/com/example/ApplicationMain.scala b/src/main/g8/src/main/scala/com/example/ApplicationMain.scala
deleted file mode 100644
index f834c11..0000000
--- a/src/main/g8/src/main/scala/com/example/ApplicationMain.scala
+++ /dev/null
@@ -1,12 +0,0 @@
-package com.example
-
-import akka.actor.ActorSystem
-
-object ApplicationMain extends App {
- val system = ActorSystem("MyActorSystem")
- val pingActor = system.actorOf(PingActor.props, "pingActor")
- pingActor ! PingActor.Initialize
- // This example app will ping pong 3 times and thereafter terminate the ActorSystem -
- // see counter logic in PingActor
- system.awaitTermination()
-}
\ No newline at end of file
diff --git a/src/main/g8/src/main/scala/com/example/PingActor.scala b/src/main/g8/src/main/scala/com/example/PingActor.scala
deleted file mode 100644
index aec4774..0000000
--- a/src/main/g8/src/main/scala/com/example/PingActor.scala
+++ /dev/null
@@ -1,27 +0,0 @@
-package com.example
-
-import akka.actor.{Actor, ActorLogging, Props}
-
-class PingActor extends Actor with ActorLogging {
- import PingActor._
-
- var counter = 0
- val pongActor = context.actorOf(PongActor.props, "pongActor")
-
- def receive = {
- case Initialize =>
- log.info("In PingActor - starting ping-pong")
- pongActor ! PingMessage("ping")
- case PongActor.PongMessage(text) =>
- log.info("In PingActor - received message: {}", text)
- counter += 1
- if (counter == 3) context.system.shutdown()
- else sender() ! PingMessage("ping")
- }
-}
-
-object PingActor {
- val props = Props[PingActor]
- case object Initialize
- case class PingMessage(text: String)
-}
\ No newline at end of file
diff --git a/src/main/g8/src/main/scala/com/example/PongActor.scala b/src/main/g8/src/main/scala/com/example/PongActor.scala
deleted file mode 100644
index be2419b..0000000
--- a/src/main/g8/src/main/scala/com/example/PongActor.scala
+++ /dev/null
@@ -1,18 +0,0 @@
-package com.example
-
-import akka.actor.{Actor, ActorLogging, Props}
-
-class PongActor extends Actor with ActorLogging {
- import PongActor._
-
- def receive = {
- case PingActor.PingMessage(text) =>
- log.info("In PongActor - received message: {}", text)
- sender() ! PongMessage("pong")
- }
-}
-
-object PongActor {
- val props = Props[PongActor]
- case class PongMessage(text: String)
-}
diff --git a/src/main/g8/src/main/scala/com/lightbend/akka/sample/AkkaQuickstart.scala b/src/main/g8/src/main/scala/com/lightbend/akka/sample/AkkaQuickstart.scala
new file mode 100644
index 0000000..17c81f6
--- /dev/null
+++ b/src/main/g8/src/main/scala/com/lightbend/akka/sample/AkkaQuickstart.scala
@@ -0,0 +1,101 @@
+//#full-example
+package com.lightbend.akka.sample
+
+import akka.actor.{ Actor, ActorLogging, ActorRef, ActorSystem, Props }
+import scala.io.StdIn
+
+//#greeter-companion
+//#greeter-messages
+object Greeter {
+ //#greeter-messages
+ def props(message: String, printerActor: ActorRef): Props = Props(new Greeter(message, printerActor))
+ //#greeter-messages
+ final case class WhoToGreet(who: String)
+ case object Greet
+}
+//#greeter-messages
+//#greeter-companion
+
+//#greeter-actor
+class Greeter(message: String, printerActor: ActorRef) extends Actor {
+ import Greeter._
+ import Printer._
+
+ var greeting = ""
+
+ def receive = {
+ case WhoToGreet(who) =>
+ greeting = s"$message, $who"
+ case Greet =>
+ //#greeter-send-message
+ printerActor ! Greeting(greeting)
+ //#greeter-send-message
+ }
+}
+//#greeter-actor
+
+//#printer-companion
+//#printer-messages
+object Printer {
+ //#printer-messages
+ def props: Props = Props[Printer]
+ //#printer-messages
+ final case class Greeting(greeting: String)
+}
+//#printer-messages
+//#printer-companion
+
+//#printer-actor
+class Printer extends Actor with ActorLogging {
+ import Printer._
+
+ def receive = {
+ case Greeting(greeting) =>
+ log.info(s"Greeting received (from ${sender()}): $greeting")
+ }
+}
+//#printer-actor
+
+//#main-class
+object AkkaQuickstart extends App {
+ import Greeter._
+
+ // Create the 'helloAkka' actor system
+ val system: ActorSystem = ActorSystem("helloAkka")
+
+ try {
+ //#create-actors
+ // Create the printer actor
+ val printer: ActorRef = system.actorOf(Printer.props, "printerActor")
+
+ // Create the 'greeter' actors
+ val howdyGreeter: ActorRef =
+ system.actorOf(Greeter.props("Howdy", printer), "howdyGreeter")
+ val helloGreeter: ActorRef =
+ system.actorOf(Greeter.props("Hello", printer), "helloGreeter")
+ val goodDayGreeter: ActorRef =
+ system.actorOf(Greeter.props("Good day", printer), "goodDayGreeter")
+ //#create-actors
+
+ //#main-send-messages
+ howdyGreeter ! WhoToGreet("Akka")
+ howdyGreeter ! Greet
+
+ howdyGreeter ! WhoToGreet("Lightbend")
+ howdyGreeter ! Greet
+
+ helloGreeter ! WhoToGreet("Scala")
+ helloGreeter ! Greet
+
+ goodDayGreeter ! WhoToGreet("Play")
+ goodDayGreeter ! Greet
+ //#main-send-messages
+
+ println(">>> Press ENTER to exit <<<")
+ StdIn.readLine()
+ } finally {
+ system.terminate()
+ }
+}
+//#main-class
+//#full-example
diff --git a/src/main/g8/src/test/scala/com/example/PingPongActorSpec.scala b/src/main/g8/src/test/scala/com/example/PingPongActorSpec.scala
deleted file mode 100644
index a76e759..0000000
--- a/src/main/g8/src/test/scala/com/example/PingPongActorSpec.scala
+++ /dev/null
@@ -1,36 +0,0 @@
-package com.example
-
-import akka.actor.ActorSystem
-import akka.actor.Actor
-import akka.actor.Props
-import akka.testkit.{ TestActors, TestKit, ImplicitSender }
-import org.scalatest.WordSpecLike
-import org.scalatest.Matchers
-import org.scalatest.BeforeAndAfterAll
-
-class PingPongActorSpec(_system: ActorSystem) extends TestKit(_system) with ImplicitSender
- with WordSpecLike with Matchers with BeforeAndAfterAll {
-
- def this() = this(ActorSystem("MySpec"))
-
- override def afterAll {
- TestKit.shutdownActorSystem(system)
- }
-
- "A Ping actor" must {
- "send back a ping on a pong" in {
- val pingActor = system.actorOf(PingActor.props)
- pingActor ! PongActor.PongMessage("pong")
- expectMsg(PingActor.PingMessage("ping"))
- }
- }
-
- "A Pong actor" must {
- "send back a pong on a ping" in {
- val pongActor = system.actorOf(PongActor.props)
- pongActor ! PingActor.PingMessage("ping")
- expectMsg(PongActor.PongMessage("pong"))
- }
- }
-
-}
diff --git a/src/main/g8/src/test/scala/com/lightbend/akka/sample/AkkaQuickstartSpec.scala b/src/main/g8/src/test/scala/com/lightbend/akka/sample/AkkaQuickstartSpec.scala
new file mode 100644
index 0000000..d961c13
--- /dev/null
+++ b/src/main/g8/src/test/scala/com/lightbend/akka/sample/AkkaQuickstartSpec.scala
@@ -0,0 +1,39 @@
+//#full-example
+package com.lightbend.akka.sample
+
+import org.scalatest.{ BeforeAndAfterAll, FlatSpecLike, Matchers }
+import akka.actor.{ Actor, Props, ActorSystem }
+import akka.testkit.{ ImplicitSender, TestKit, TestActorRef, TestProbe }
+import scala.concurrent.duration._
+import Greeter._
+import Printer._
+
+//#test-classes
+class AkkaQuickstartSpec(_system: ActorSystem)
+ extends TestKit(_system)
+ with Matchers
+ with FlatSpecLike
+ with BeforeAndAfterAll {
+ //#test-classes
+
+ def this() = this(ActorSystem("AkkaQuickstartSpec"))
+
+ override def afterAll: Unit = {
+ shutdown(system)
+ }
+
+ //#first-test
+ //#specification-example
+ "A Greeter Actor" should "pass on a greeting message when instructed to" in {
+ //#specification-example
+ val testProbe = TestProbe()
+ val helloGreetingMessage = "hello"
+ val helloGreeter = system.actorOf(Greeter.props(helloGreetingMessage, testProbe.ref))
+ val greetPerson = "Akka"
+ helloGreeter ! WhoToGreet(greetPerson)
+ helloGreeter ! Greet
+ testProbe.expectMsg(500 millis, Greeting(s"$helloGreetingMessage, $greetPerson"))
+ }
+ //#first-test
+}
+//#full-example
