Expose JPA to flows (#4140)

* First pass
* Update test.
* Address review comments.
* Added docs and kdocs.
* Clean-up.
* Add extra test.
* Changes to docsite.
* Added try/catch block as recommended by Andras.
* Removed try catch block. It's not required as the checkpoint serialiser deals with this.
* Re-used existing DB session instead of creating a new session.
* Entity manager auto flushes.
* Added java friendly api.
* Addressed review comments.

node-api/src/main/kotlin/net/corda/nodeapi/internal/persistence/DatabaseTransaction.kt

@@ -7,6 +7,7 @@ import org.hibernate.Transaction
 import rx.subjects.PublishSubject
 import java.sql.Connection
 import java.util.*
+import javax.persistence.EntityManager
 
 fun currentDBSession(): Session = contextTransaction.session
 private val _contextTransaction = ThreadLocal<DatabaseTransaction>()
@@ -59,6 +60,12 @@ class DatabaseTransaction(
         session
     }
 
+    // Returns a delegate which overrides certain operations that we do not want CorDapp developers to call.
+    val restrictedEntityManager: RestrictedEntityManager by lazy {
+        val entityManager = session as EntityManager
+        RestrictedEntityManager(entityManager)
+    }
+
     val session: Session by sessionDelegate
     private lateinit var hibernateTransaction: Transaction
 
@@ -101,3 +108,4 @@ class DatabaseTransaction(
         boundary.filter { !it.success }.subscribe { callback() }
     }
 }
+

node-api/src/main/kotlin/net/corda/nodeapi/internal/persistence/RestrictedEntityManager.kt

@@ -0,0 +1,19 @@
+package net.corda.nodeapi.internal.persistence
+
+import javax.persistence.EntityManager
+
+/**
+ * A delegate of [EntityManager] which disallows some operations.
+ */
+class RestrictedEntityManager(private val delegate: EntityManager) : EntityManager by delegate {
+
+    override fun close() {
+        throw UnsupportedOperationException("This method cannot be called via ServiceHub.withEntityManager.")
+    }
+
+    override fun clear() {
+        throw UnsupportedOperationException("This method cannot be called via ServiceHub.withEntityManager.")
+    }
+
+    // TODO: Figure out which other methods on EntityManager need to be blocked?
+}