CORDA-3659 - adding kdoc for RestrictedEntityManager and RestrictedConnection (#6179)

* adding kdoc for RestrictedEntityManager and RestrictedConnection

* adding kdoc for RestrictedEntityManager and RestrictedConnection

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
 

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 {