From ec96a844bd1cb5142b1888890f41ca89444b4dd5 Mon Sep 17 00:00:00 2001
From: nikinagy <61757742+nikinagy@users.noreply.github.com>
Date: Tue, 28 Apr 2020 09:35:47 +0100
Subject: [PATCH] CORDA-3659 - adding kdoc for RestrictedEntityManager and
 RestrictedConnection (#6179)

* adding kdoc for RestrictedEntityManager and RestrictedConnection

* adding kdoc for RestrictedEntityManager and RestrictedConnection
---
 .../kotlin/net/corda/core/node/ServiceHub.kt  | 31 +++++++++++++++++++
 .../net/corda/node/internal/AbstractNode.kt   |  3 ++
 2 files changed, 34 insertions(+)

diff --git a/core/src/main/kotlin/net/corda/core/node/ServiceHub.kt b/core/src/main/kotlin/net/corda/core/node/ServiceHub.kt
index 0e500dd4bb..bc25183d4d 100644
--- a/core/src/main/kotlin/net/corda/core/node/ServiceHub.kt
+++ b/core/src/main/kotlin/net/corda/core/node/ServiceHub.kt
@@ -380,6 +380,26 @@ interface ServiceHub : ServicesForResolution {
      * When used within a flow, this session automatically forms part of the enclosing flow transaction boundary,
      * and thus queryable data will include everything committed as of the last checkpoint.
      *
+     * We want to make sure users have a restricted access to administrative functions, this function will return a [RestrictedConnection] instance.
+     * The blocked methods are the following:
+     * - abort(executor: Executor?)
+     * - clearWarnings()
+     * - close()
+     * - commit()
+     * - setSavepoint()
+     * - setSavepoint(name : String?)
+     * - releaseSavepoint(savepoint: Savepoint?)
+     * - rollback()
+     * - rollback(savepoint: Savepoint?)
+     * - setCatalog(catalog : String?)
+     * - setTransactionIsolation(level: Int)
+     * - setTypeMap(map: MutableMap<String, Class<*>>?)
+     * - setHoldability(holdability: Int)
+     * - setSchema(schema: String?)
+     * - setNetworkTimeout(executor: Executor?, milliseconds: Int)
+     * - setAutoCommit(autoCommit: Boolean)
+     * - setReadOnly(readOnly: Boolean)
+     *
      * @throws IllegalStateException if called outside of a transaction.
      * @return A [Connection]
      */
@@ -393,6 +413,17 @@ interface ServiceHub : ServicesForResolution {
      * NOTE: Suspendable flow operations such as send, receive, subFlow and sleep, cannot be called within the lambda.
      *
      * @param block a lambda function with access to an [EntityManager].
+     *
+     * We want to make sure users have a restricted access to administrative functions.
+     * The blocked methods are the following:
+     * - close()
+     * - clear()
+     * - getMetamodel()
+     * - getTransaction()
+     * - joinTransaction()
+     * - lock(entity: Any?, lockMode: LockModeType?)
+     * - lock(entity: Any?, lockMode: LockModeType?, properties: MutableMap<String, Any>?)
+     * - setProperty(propertyName: String?, value: Any?)
      */
     fun <T : Any?> withEntityManager(block: EntityManager.() -> T): T
 
diff --git a/node/src/main/kotlin/net/corda/node/internal/AbstractNode.kt b/node/src/main/kotlin/net/corda/node/internal/AbstractNode.kt
index 9b85295f46..ed6bf6e5eb 100644
--- a/node/src/main/kotlin/net/corda/node/internal/AbstractNode.kt
+++ b/node/src/main/kotlin/net/corda/node/internal/AbstractNode.kt
@@ -1186,6 +1186,9 @@ abstract class AbstractNode<S>(val configuration: NodeConfiguration,
             return flowManager.getFlowFactoryForInitiatingFlow(initiatingFlowClass)
         }
 
+        /**
+         * Exposes the database connection as a [RestrictedConnection] to the users.
+         */
         override fun jdbcSession(): Connection = RestrictedConnection(database.createSession())
 
         override fun <T : Any?> withEntityManager(block: EntityManager.() -> T): T {