readme.md with links to 1.x and a quick guide

Author: akarnokd

README.md

@@ -8,6 +8,15 @@ RxJava is a Java VM implementation of [Reactive Extensions](http://reactivex.io)
 
 It extends the [observer pattern](http://en.wikipedia.org/wiki/Observer_pattern) to support sequences of data/events and adds operators that allow you to compose sequences together declaratively while abstracting away concerns about things like low-level threading, synchronization, thread-safety and concurrent data structures.
 
+#### Version 1.x
+
+Looking for version 1.x? Jump [to the 1.x branch](https://github.com/ReactiveX/RxJava/tree/1.x).
+
+Timeline plans for the 1.x line:
+
+  - **June 1, 2017** - feature freeze (no new operators), only bugfixes
+  - **March 31, 2018** - end of life, no further development
+
 #### Version 2.x
 
 - single dependency: [Reactive-Streams](https://github.com/reactive-streams/reactive-streams-jvm)  
@@ -23,6 +32,129 @@ Version 2.x and 1.x will live side-by-side for several years. They will have dif
 
 See the differences between version 1.x and 2.x in the wiki article [What's different in 2.0](https://github.com/ReactiveX/RxJava/wiki/What's-different-in-2.0). Learn more about RxJava in general on the <a href="https://github.com/ReactiveX/RxJava/wiki">Wiki Home</a>.
 
+## Getting started
+
+The first step is to include RxJava 2 into your project, for example, as a Gradle compile dependency:
+
+```groovy
+compile "io.reactivex.rxjava2:rxjava:2.x.y"
+```
+
+The second is to write the **Hello World** program:
+
+```java
+package rxjava.examples;
+
+import io.reactivex.*;
+
+public class HelloWorld {
+    public static void main(String[] args) {
+        Flowable.just("Hello world").subscribe(System.out::println);
+    }
+}
+```
+
+If your platform doesn't support Java 8 lambdas (yet), you have to create an inner class of `Consumer` manually:
+
+```java
+        Flowable.just("Hello world")
+        .subscribe(new Consumer<String>() {
+            @Override public void accept(String s) {
+                System.out.println(s);
+            }
+        );
+```
+
+RxJava 2 features several base classes you can discover operators on:
+
+  - `io.reactivex.Flowable` : 0..N flows, supporting Reactive-Streams and backpressure
+  - `io.reactivex.Observable`: 0..N flows, no backpressure
+  - `io.reactivex.Single`: a flow of exactly 1 item or an error
+  - `io.reactivex.Completable`: a flow without items but only a completion or error signal
+  - `io.reactivex.Maybe`: a flow with no items, exactly one item or an error
+
+One of the common use cases for RxJava is to run some computation, network request on a background thread and show the results (or error) on the UI thread:
+
+```java
+Flowable.fromCallable(() -> {
+    Thread.sleep(1000); //  imitate expensive computation
+    return "Done";
+})
+.subscribeOn(Schedulers.io())
+.observeOn(Schedulers.single())
+.subscribe(System.out::println, Throwable::printStackTrace);
+
+Thread.sleep(2000); // <--- wait for the flow to finish
+```
+
+This style of chaining methods is called a **fluent API** which resembles the **builder pattern**. However, RxJava's reactive types are immutable; each of the method calls returns a new `Flowable` with added behavior. To illustrate, the example can be rewritten as follows:
+
+```java
+Flowable<String> source = Flowable.fromCallable(() -> {
+    Thread.sleep(1000); //  imitate expensive computation
+    return "Done";
+});
+
+Flowabe<String> runBackground = source.subscribeOn(Schedulers.io());
+
+Flowable<String> showForeground = runBackground.observeOn(Schedulers.single());
+
+showForeground.subscribe(System.out::println, Throwable::printStackTrace);
+
+Thread.sleep(2000);
+```
+
+Typically, you can move computations or blocking IO to some other thread via `subscribeOn`. Once the data is ready, you can make sure they get processed on the foreground or GUI thread via `observeOn`. 
+
+RxJava operators don't work `Thread`s or `ExecutorService`s directly but with so called `Scheduler`s that abstract away sources of concurrency behind an uniform API. RxJava 2 features several standard schedulers accessible via `Schedulers` utility class. These are available on all JVM platforms but some specific platforms, such as Android, have their own typical `Scheduler`s defined: `AndroidSchedulers.mainThread()`, `SwingScheduler.instance()` or `JavaFXSchedulers.gui()`.
+
+The `Thread.sleep(2000);` at the end is no accident. In RxJava the default `Scheduler`s run on daemon threads, which means once the Java main thread exits, they all get stopped and background computations may never happen. Sleeping for some time in this example situations let's you see the output of the flow on the console with time to spare.
+
+Flows in RxJava are sequential in nature split into processing stages that may run **concurrently** with each other:
+
+```java
+Flowable.range(1, 10)
+.observeOn(Schedulers.computation())
+.map(v -> v * v)
+.blockingSubscribe(System.out::println);
+```
+
+This example flow squares the numbers from 1 to 10 on the **computation** `Scheduler` and consumes the results on the "main" thread (more precisely, the caller thread of `blockingSubscribe`). However, the lambda `v -> v * v` doesn't run in parallel for this flow; it receives the values 1 to 10 on the same computation thread one after the other.
+
+Processing the numbers 1 to 10 in parallel is a bit more involved:
+
+```java
+Flowable.range(1, 10)
+.flatMap(v ->
+    Flowable.just(v)
+    .subscribeOn(Schedulers.computation())
+    .map(v -> v * v)
+)
+.blockingSubscribe(System.out::println);
+```
+
+Practically, paralellism in RxJava means running independent flows and merging their results back into a single flow. The operator `flatMap` does this by first mapping each number from 1 to 10 into its own individual `Flowable`, runs them and merges the computed squares.
+
+`flatMap` is a powerful operator and helps in a lot of situations. For example, given a service that returns a `Flowable`, we'd like to call another service with values emitted by the first service:
+
+```java
+Flowable<Inventory> inventorySource = warehouse.getInventoryAsync();
+
+inventorySource.flatMap(inventoryItem ->
+    erp.getDemandAsync(inventoryItem.getId())
+    .map(demand 
+        -> System.out.println("Item " + inventoryItem.getName() + " has demand " + demand));
+)
+.subscribe();
+```
+
+Note, however, that `flatMap` doesn't guarantee any order and the end result from the inner flows may end up interleaved. There are alternative operators:
+
+  - `concatMap` that maps and runs one inner flow at a time and
+  - `concatMapEager` which runs all inner flows "at once" but the output flow will be in the order those inner flows were created.
+
+For further details, consult the [wiki](https://github.com/ReactiveX/RxJava/wiki).
+
 ## Communication
 
 - Google Group: [RxJava](http://groups.google.com/d/forum/rxjava)
@@ -130,4 +262,4 @@ See the License for the specific language governing permissions and
 limitations under the License.
 
 [beta source link]: https://github.com/ReactiveX/RxJava/blob/master/src/main/java/rx/annotations/Beta.java
-[experimental source link]: https://github.com/ReactiveX/RxJava/blob/master/src/main/java/rx/annotations/Experimental.java
+[experimental source link]: https://github.com/ReactiveX/RxJava/blob/master/src/main/java/rx/annotations/Experimental.java