From 40ac5525421fa2932224048fce76aded3fe3f332 Mon Sep 17 00:00:00 2001
From: Narendra Pathai <narendra.pathai@gmail.com>
Date: Sun, 24 Jul 2016 01:45:49 +0530
Subject: [PATCH] Work on #403, added README

---
 promise/README.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 promise/README.md

diff --git a/promise/README.md b/promise/README.md
new file mode 100644
index 000000000..069a8dbfe
--- /dev/null
+++ b/promise/README.md
@@ -0,0 +1,45 @@
+---
+layout: pattern
+title: Promise
+folder: promise
+permalink: /patterns/promise/
+categories: Structural
+tags:
+ - Java
+ - Concurrency
+ - Difficulty-Intermediate
+---
+
+## Also known as
+CompletableFuture
+
+## Intent
+A Promise represents a proxy for a value not necessarily known when the promise is created. It
+allows you to associate dependent promises to an asynchronous action's eventual success value or 
+failure reason. Promises are a way to write async code that still appears as though it is executing 
+in a synchronous way.
+
+![alt text](./etc/promise.png "Promise")
+
+## Applicability
+Promise pattern is applicable in concurrent programming when some work needs to be done asynchronously
+and:
+
+* code maintainablity and readability suffers due to callback hell.
+* you need to compose promises and need better error handling for asynchronous tasks.
+* you want to use functional style of programming.
+
+
+## Real world examples
+
+* [java.util.concurrent.CompletableFuture](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html)
+* [Guava ListenableFuture](https://github.com/google/guava/wiki/ListenableFutureExplained)
+
+## Related Patterns
+ * Async Method Invocation
+ * Callback
+
+## Credits
+
+* [You are missing the point to Promises](https://gist.github.com/domenic/3889970)
+* [Functional style callbacks using CompleteableFuture](https://www.infoq.com/articles/Functional-Style-Callbacks-Using-CompletableFuture)