feat: extension for remote R session management

DESCRIPTION

@@ -36,7 +36,7 @@ License: LGPL (>= 2.1)
 URL: https://github.com/datashield/DSI/,
   https://datashield.github.io/DSI/, https://datashield.org/
 BugReports: https://github.com/datashield/DSI/issues
-RoxygenNote: 7.3.2
+RoxygenNote: 7.3.3
 Encoding: UTF-8
 Collate: 
     'DSObject.R'
@@ -45,6 +45,7 @@ Collate:
     'DSI-package.R'
     'DSLoginBuilder.R'
     'DSResult.R'
+    'DSSession.R'
     'datashield.aggregate.R'
     'datashield.assign.R'
     'datashield.connections.R'
@@ -53,6 +54,7 @@ Collate:
     'datashield.list.R'
     'datashield.login.R'
     'datashield.logout.R'
+    'datashield.sessions.R'
     'datashield.status.R'
     'datashield.symbol.R'
     'datashield.workspace.R'

NAMESPACE

@@ -21,6 +21,7 @@ export(datashield.profiles)
 export(datashield.resource_status)
 export(datashield.resources)
 export(datashield.rm)
+export(datashield.sessions)
 export(datashield.symbols)
 export(datashield.table_status)
 export(datashield.tables)
@@ -37,9 +38,11 @@ export(dsDisconnect)
 export(dsFetch)
 export(dsGetInfo)
 export(dsHasResource)
+export(dsHasSession)
 export(dsHasTable)
 export(dsIsAsync)
 export(dsIsCompleted)
+export(dsIsReady)
 export(dsKeepAlive)
 export(dsListMethods)
 export(dsListPackages)
@@ -52,11 +55,14 @@ export(dsRestoreWorkspace)
 export(dsRmSymbol)
 export(dsRmWorkspace)
 export(dsSaveWorkspace)
+export(dsSession)
+export(dsStateMessage)
 export(newDSLoginBuilder)
 exportClasses(DSConnection)
 exportClasses(DSDriver)
 exportClasses(DSObject)
 exportClasses(DSResult)
+exportClasses(DSSession)
 import(R6)
 import(progress)
 importFrom(cli,cli_abort)

R/DSConnection.R

@@ -29,7 +29,6 @@ setClass("DSConnection", representation(name = "character"), contains = c("DSObj
 #' accessible through this connection.
 #'
 #' @param conn An object that inherits from \code{\link{DSConnection-class}}.
-#'
 #' @return A character vector of table names.
 #' 
 #' @family DSConnection generics
@@ -53,6 +52,7 @@ setGeneric("dsListTables",
 #'
 #' @param conn An object that inherits from \code{\link{DSConnection-class}}.
 #' @param table the table fully qualified name
+#' @return A logical indicating if the table exists.
 #'
 #' @family DSConnection generics
 #' @examples
@@ -73,6 +73,7 @@ setGeneric("dsHasTable",
 #' accessible through this connection.
 #'
 #' @param conn An object that inherits from \code{\link{DSConnection-class}}.
+#' @return A character vector of resource names.
 #'
 #' @family DSConnection generics
 #' @examples
@@ -94,6 +95,7 @@ setGeneric("dsListResources",
 #'
 #' @param conn An object that inherits from \code{\link{DSConnection-class}}.
 #' @param resource the resource fully qualified name
+#' @return A logical indicating if the resource exists.
 #'
 #' @family DSConnection generics
 #' @examples
@@ -108,6 +110,52 @@ setGeneric("dsHasResource",
            def = function(conn, resource) standardGeneric("dsHasResource"),
            valueClass = "logical")
 
+#' Check remote R session exists
+#'
+#' Check if a remote R session exists (not necessarily running and ready to accept 
+#' R commands submissions).
+#'
+#' @param conn An object that inherits from \code{\link{DSConnection-class}}.
+#' @return A logical indicating if a remote R session exists accessible through this connection.
+#'
+#' @family DSConnection generics
+#' @examples
+#' \dontrun{
+#' con <- dsConnect(DSOpal::Opal(), "server1",
+#'   username = "dsuser", password = "password", url = "https://opal-demo.obiba.org")
+#' dsHasSession(con)
+#' dsDisconnect(con)
+#' }
+#' @export
+setGeneric("dsHasSession",
+           def = function(conn) standardGeneric("dsHasSession"),
+           valueClass = "logical")
+
+#' Create a remote R session
+#' 
+#' Create a remote R session if none exists. If a remote R session already exists,
+#' it will be reused. Returns a logical indicating if a remote R session exists
+#' accessible through this connection.
+#' 
+#' @param conn An object that inherits from \code{\link{DSConnection-class}}.
+#' @param async Whether the result of the call should be retrieved asynchronously. When TRUE (default) 
+#' the calls are parallelized over the connections, when the connection supports 
+#' that feature, with an extra overhead of requests.
+#' @return An object of class \code{\link{DSSession-class}} representing the remote R session.
+#' 
+#' @family DSConnection generics
+#' @examples
+#' \dontrun{
+#' con <- dsConnect(DSOpal::Opal(), "server1",
+#'   username = "dsuser", password = "password", url = "https://opal-demo.obiba.org")
+#' dsSession(con, async=TRUE)
+#' dsDisconnect(con)
+#' }
+#' @export
+setGeneric("dsSession",
+           def = function(conn, async=TRUE) standardGeneric("dsSession"),
+           valueClass = "DSSession")
+
 #' Assign a data table
 #'
 #' Assign a data table from the data repository to a symbol in the DataSHIELD R session.
@@ -126,7 +174,8 @@ setGeneric("dsHasResource",
 #'   will be the data frame row names. When specified this column can be used to perform joins between data frames.
 #' @param async Whether the result of the call should be retrieved asynchronously. When TRUE (default) the calls are parallelized over
 #'   the connections, when the connection supports that feature, with an extra overhead of requests.
-#'
+#' @return An object of class \code{\link{DSResult-class}} representing the result of the assignment operation.
+#' 
 #' @family DSConnection generics
 #' @examples
 #' \dontrun{
@@ -150,7 +199,8 @@ setGeneric("dsAssignTable",
 #' @param resource Fully qualified name of a resource reference in the data repository.
 #' @param async Whether the result of the call should be retrieved asynchronously. When TRUE (default) the calls are parallelized over
 #'   the connections, when the connection supports that feature, with an extra overhead of requests.
-#'
+#' @return An object of class \code{\link{DSResult-class}} representing the result of the assignment operation.
+#' 
 #' @family DSConnection generics
 #' @examples
 #' \dontrun{
@@ -174,7 +224,8 @@ setGeneric("dsAssignResource",
 #' @param expr A R expression with allowed assign functions calls.
 #' @param async Whether the result of the call should be retrieved asynchronously. When TRUE (default) the calls are parallelized over
 #'   the connections, when the connection supports that feature, with an extra overhead of requests.
-#'
+#' @return An object of class \code{\link{DSResult-class}} representing the result of the assignment operation.
+#' 
 #' @family DSConnection generics
 #' @examples
 #' \dontrun{
@@ -197,7 +248,8 @@ setGeneric("dsAssignExpr",
 #' @param expr Expression to evaluate.
 #' @param async Whether the result of the call should be retrieved asynchronously. When TRUE (default) the calls are parallelized over
 #'   the connections, when the connection supports that feature, with an extra overhead of requests.
-#'
+#' @return An object of class \code{\link{DSResult-class}} representing the result of the aggregation operation.
+#' 
 #' @family DSConnection generics
 #' @examples
 #' \dontrun{
@@ -217,6 +269,7 @@ setGeneric("dsAggregate",
 #' After assignments have been performed, some symbols live in the DataSHIELD R session on the server side.
 #'
 #' @param conn An object that inherits from \code{\link{DSConnection-class}}.
+#' @return A character vector of symbol names.
 #'
 #' @family DSConnection generics
 #' @examples
@@ -257,8 +310,8 @@ setGeneric("dsRmSymbol",
 #' Get the list of DataSHIELD profiles that have been configured on the remote data repository.
 #'
 #' @param conn An object that inherits from \code{\link{DSConnection-class}}.
-#'
-#' @return A list containing the "available" character vector of profile names and the "current" profile (in case a default one was assigned).
+#' @return A list containing the "available" character vector of profile names and 
+#' the "current" profile (in case a default one was assigned).
 #'
 #' @family DSConnection generics
 #' @examples
@@ -279,7 +332,6 @@ setGeneric("dsListProfiles",
 #'
 #' @param conn An object that inherits from \code{\link{DSConnection-class}}.
 #' @param type Type of the method: "aggregate" (default) or "assign".
-#'
 #' @return A data.frame with columns: name, type ('aggregate' or 'assign'), class ('function' or 'script'), value, package, version.
 #'
 #' @family DSConnection generics
@@ -300,7 +352,6 @@ setGeneric("dsListMethods",
 #' Get the list of DataSHIELD packages with their version, that have been configured on the remote data repository.
 #'
 #' @param conn An object that inherits from \code{\link{DSConnection-class}}.
-#'
 #' @return A data.frame with columns: name, version.
 #'
 #' @family DSConnection generics
@@ -322,7 +373,6 @@ setGeneric("dsListPackages",
 #' Get the list of DataSHIELD workspaces, that have been saved on the remote data repository.
 #'
 #' @param conn An object that inherits from \code{\link{DSConnection-class}}.
-#'
 #' @return A data.frame with columns: name, lastAccessDate, size.
 #'
 #' @family DSConnection generics
@@ -407,10 +457,11 @@ setGeneric("dsRmWorkspace",
 #' When a \code{\link{DSResult-class}} object is returned on aggregation or assignment operation,
 #' the raw result can be accessed asynchronously, allowing parallelization of DataSHIELD calls
 #' over multpile servers. The returned named list of logicals will specify if asynchronicity is supported for:
-#' aggregation operation ('aggregate'), table assignment operation ('assignTable'),
+#' session operation ('session'), aggregation operation ('aggregate'), table assignment operation ('assignTable'),
 #' resource assignment operation ('assignResource') and expression assignment operation ('assignExpr').
 #'
 #' @param conn An object that inherits from \code{\link{DSConnection-class}}.
+#' @return A named list of logicals indicating if asynchronicity is supported for session, aggregation and assignment operations.
 #'
 #' @family DSConnection generics
 #' @examples

R/DSSession.R

@@ -0,0 +1,68 @@
+#' DSSession class
+#'
+#' This virtual class describes the state of the R session.
+#'
+#' The default show method displays a summary of the R session state using other
+#' DS generics.
+#'
+#' @name DSSession-class
+#' @docType class
+#' @family DS classes
+#' @family DSSession generics
+#' @export
+#' @include DSObject.R
+setClass("DSSession", contains = c("DSObject", "VIRTUAL"))
+
+#' Get whether the remote R session is up and running
+#'
+#' Get whether the remote R session is up and running, ready to accept R commands.
+#' The primary use of this function is to know whether the session is ready after it has been
+#' created in an asynchronous way.
+#'
+#' @param session An object inheriting from \code{\link{DSSession-class}}.
+#' @return A logical
+#'
+#' @family DSSession generics
+#' @examples
+#' \dontrun{
+#' con <- dsConnect(DSOpal::Opal(), "server1",
+#'   username = "dsuser", password = "password", url = "https://opal-demo.obiba.org")
+#' session <- dsSession(con, async = TRUE)
+#' ready <- dsIsReady(session)
+#' while (!ready) {
+#'   Sys.sleep(1)
+#'   ready <- dsIsReady(session)
+#'   cat(".")
+#' }
+#' dsDisconnect(con)
+#' }
+#' @export
+setGeneric("dsIsReady",
+           def = function(session) standardGeneric("dsIsReady"))
+
+#' Get the state of the remote R session
+#'
+#' Get a human-readable message that informs about the state of the remote R session.
+#' The primary use of this function is to inform the user about the session state process 
+#' after it has been created in an asynchronous way.
+#'  
+#' @param session An object inheriting from \code{\link{DSSession-class}}.
+#' @return A character string
+#'
+#' @family DSSession generics
+#' @examples
+#' \dontrun{
+#' con <- dsConnect(DSOpal::Opal(), "server1",
+#'   username = "dsuser", password = "password", url = "https://opal-demo.obiba.org")
+#' session <- dsSession(con, async = TRUE)
+#' ready <- dsIsReady(session)
+#' while (!ready) {
+#'   Sys.sleep(1)
+#'   ready <- dsIsReady(session)
+#'   cat(dsStateMessage(session), "\n")
+#' }
+#' dsDisconnect(con)
+#' }
+#' @export
+setGeneric("dsStateMessage",
+           def = function(session) standardGeneric("dsStateMessage"))

R/datashield.aggregate.R

@@ -40,6 +40,7 @@
 #'
 #' @export
 datashield.aggregate <- function(conns, expr, async=TRUE, success=NULL, error=NULL, errors.print = getOption("datashield.errors.print", FALSE)) {
+  datashield.sessions(conns)
   .clearLastErrors()
   rval <- NULL
 

R/datashield.assign.R

@@ -114,6 +114,7 @@ datashield.assign <- function(conns, symbol, value, variables=NULL, missings=FAL
 #' }
 #' @export
 datashield.assign.table <- function(conns, symbol, table, variables=NULL, missings=FALSE, identifiers=NULL, id.name=NULL, async=TRUE, success=NULL, error=NULL, errors.print = getOption("datashield.errors.print", FALSE)) {
+  datashield.sessions(conns)
   .clearLastErrors()
   if (is.null(table) || length(table) == 0) {
     stop("Not a valid table name", call.=FALSE)
@@ -269,6 +270,7 @@ datashield.assign.table <- function(conns, symbol, table, variables=NULL, missin
 #' }
 #' @export
 datashield.assign.resource <- function(conns, symbol, resource, async=TRUE, success=NULL, error=NULL, errors.print = getOption("datashield.errors.print", FALSE)) {
+  datashield.sessions(conns)
   .clearLastErrors()
   if (is.null(resource) || length(resource) == 0) {
     stop("Not a valid resource name", call.=FALSE)
@@ -415,6 +417,7 @@ datashield.assign.resource <- function(conns, symbol, resource, async=TRUE, succ
 #' }
 #' @export
 datashield.assign.expr <- function(conns, symbol, expr, async=TRUE, success=NULL, error=NULL, errors.print = getOption("datashield.errors.print", FALSE)) {
+  datashield.sessions(conns)
   .clearLastErrors()
 
   # prepare expressions as a named list