Update README.

Author: David Pratt

README.markdown

@@ -3,28 +3,80 @@ Janus
 
 
 Janus is a library focused on simple data access with the ability to interleave database transactions
-with asynchronous Future-based invocations.
+with asynchronous Future-based invocations. Classic transactional models on the JVM typically rely on a single
+thread-bound transaction context or connection, but this can prove difficult when dealing with asychronous
+external resources. To work around this you either need to implement your external (or otherwise Future based) calls
+as blocking, which tends to be not as robust and elegant. Janus does not utilize the concept of a thread bound
+transaction, but rather the convention is to source a Session implicitly.
 
 A quick example -
 
 ```scala
 
-def externalCall(id: String) : Future[String]
+import akka.dispatch.Future
+import janus.{Session, Database}
+import javax.sql.DataSource
 
-val db = Database(dataSource)
-db.withSession { session =>
-  session.withTransaction { transaction =>
-    session.executeSql("insert into test (id, name) VALUES (1, 'Test Value')")
-    externalCall("Test Value")
+trait ExternalRepositorySupport {
+  def addUser(id: Long, password: String): Future[String]
+  def deleteUser(id: Long): Future[Boolean]
+}
+
+trait DataSourceSupport {
+  def dataSource: DataSource
+}
+
+case class User(id: Long, name: String)
+
+object User {
+  def insertUser(user: User)(implicit session: Session): User = {
+    session.withTransaction { transaction =>
+      session.withPreparedStatement("insert into test (id, name) VALUES (?, ?)") { ps =>
+        ps.setParam[Long](1, user.id)
+        ps.setParam[String](2, user.name)
+        if(ps.executeUpdate() != 1) {
+          throw new RuntimeException("Could not insert user!")
+        }
+      }
+      user
+    }
   }
 }
+
+trait UserRepository {
+  this: ExternalRepositorySupport with DataSourceSupport =>
+  val db = Database(dataSource)
+
+  def createUser(id: Long, name: String, password: String): Future[User] = {
+    db.withSession { implicit session =>
+      session.withTransaction { transaction =>
+        val user = User.insertUser(User(id, name))
+        addUser(id, password) recoverWith {
+          //handle the manual rollback of the external call.
+          case e: Throwable => {
+            //External call failed - clean it up
+            deleteUser(id)
+            //re-throw the error
+            throw e
+          }
+        } map { passwordResult =>
+          //Dont' care about the String returned from the external service - just return the User
+          user
+        }
+      }
+    }
+  }
+}
+
+
 ```
 
 The code above creates a connection to a database, and then opens a Session (the logical equivalent to a connection)
 against this database. We then open a new transactional boundary and then invoke an external, asynchronous Future-based
 web service. Since the return value of the transaction block is Future based, we do not immediately commit the transaction.
 Instead, Janus notices this case, and will then either roll back or commit the transaction only after the Future
-itself completes.
+itself completes. We do have to handle non-database rollbacks by ourselves, typically using the 'recover' or 'recoverWith'
+methods on the ultimate returned Future.
 
 Note - if the return value of the transaction block isn't Future based, the transaction is immediately comitted when
 the block is evaluated. Of course, the transaction is rolled back if the block either throws an exception or rollback()