sdk/R/R/Arvados.R

   1 source("./R/RESTService.R")
   2 source("./R/HttpRequest.R")
   3 source("./R/HttpParser.R")
   4
   5 #' Arvados
   6 #'
   7 #' Arvados class gives users ability to manipulate collections and projects.
   8 #'
   9 #' @section Usage:
  10 #' \preformatted{arv = Arvados$new(authToken = NULL, hostName = NULL, numRetries = 0)}
  11 #'
  12 #' @section Arguments:
  13 #' \describe{
  14 #'   \item{authToken}{Authentification token. If not specified ARVADOS_API_TOKEN environment variable will be used.}
  15 #'   \item{hostName}{Host name. If not specified ARVADOS_API_HOST environment variable will be used.}
  16 #'   \item{numRetries}{Number which specifies how many times to retry failed service requests.}
  17 #' }
  18 #'
  19 #' @section Methods:
  20 #' \describe{
  21 #'   \item{getToken()}{Returns authentification token currently in use.}
  22 #'   \item{getHostName()}{Returns host name currently in use.}
  23 #'   \item{getNumRetries()}{Returns number which specifies how many times to retry failed service requests.}
  24 #'   \item{setNumRetries(newNumOfRetries)}{Sets number which specifies how many times to retry failed service requests.}
  25 #'   \item{getCollection(uuid)}{Get collection with specified UUID.}
  26 #'   \item{listCollections(filters = NULL, limit = 100, offset = 0)}{Returns list of collections based on filters parameter.}
  27 #'   \item{listAllCollections(filters = NULL)}{Lists all collections, based on filters parameter, even if the number of items is greater than maximum API limit.}
  28 #'   \item{deleteCollection(uuid)}{Deletes collection with specified UUID.}
  29 #'   \item{updateCollection(uuid, newContent)}{Updates collection with specified UUID.}
  30 #'   \item{createCollection(content)}{Creates new collection.}
  31 #'   \item{getProject(uuid)}{Get project with specified UUID.}
  32 #'   \item{listProjects(filters = NULL, limit = 100, offset = 0)}{Returns list of projects based on filters parameter.}
  33 #'   \item{listAllProjects(filters = NULL)}{Lists all projects, based on filters parameter, even if the number of items is greater than maximum API limit.}
  34 #'   \item{deleteProject(uuid)}{Deletes project with specified UUID.}
  35 #'   \item{updateProject(uuid, newContent)}{Updates project with specified UUID.}
  36 #'   \item{createProject(content)}{Creates new project.}
  37 #' }
  38 #'
  39 #' @name Arvados
  40 #' @examples
  41 #' \dontrun{
  42 #' arv <- Arvados$new("your Arvados token", "example.arvadosapi.com")
  43 #'
  44 #' collection <- arv$getCollection("uuid")
  45 #'
  46 #' collectionList <- arv$listCollections(list(list("name", "like", "Test%")))
  47 #' collectionList <- arv$listAllCollections(list(list("name", "like", "Test%")))
  48 #'
  49 #' deletedCollection <- arv$deleteCollection("uuid")
  50 #'
  51 #' updatedCollection <- arv$updateCollection("uuid", list(name = "New name",
  52 #'                                                        description = "New description"))
  53 #'
  54 #' createdCollection <- arv$createCollection(list(name = "Example",
  55 #'                                                description = "This is a test collection"))
  56 #' }
  57 NULL
  58
  59 #' @export
  60 Arvados <- R6::R6Class(
  61
  62     "Arvados",
  63
  64     public = list(
  65
  66         initialize = function(authToken = NULL, hostName = NULL, numRetries = 0)
  67         {
  68             if(!is.null(hostName))
  69                Sys.setenv(ARVADOS_API_HOST = hostName)
  70
  71             if(!is.null(authToken))
  72                 Sys.setenv(ARVADOS_API_TOKEN = authToken)
  73
  74             hostName  <- Sys.getenv("ARVADOS_API_HOST");
  75             token     <- Sys.getenv("ARVADOS_API_TOKEN");
  76
  77             if(hostName == "" | token == "")
  78                 stop(paste("Please provide host name and authentification token",
  79                            "or set ARVADOS_API_HOST and ARVADOS_API_TOKEN",
  80                            "environment variables."))
  81
  82             private$numRetries  <- numRetries
  83             private$REST  <- RESTService$new(token, hostName,
  84                                              HttpRequest$new(), HttpParser$new(),
  85                                              numRetries)
  86
  87             private$token <- private$REST$token
  88             private$host  <- private$REST$hostName
  89         },
  90
  91         getToken          = function() private$REST$token,
  92         getHostName       = function() private$REST$hostName,
  93         getWebDavHostName = function() private$REST$getWebDavHostName(),
  94         getRESTService    = function() private$REST,
  95         setRESTService    = function(newRESTService) private$REST <- newRESTService,
  96
  97         getNumRetries = function() private$REST$numRetries,
  98         setNumRetries = function(newNumOfRetries)
  99         {
 100             private$REST$setNumRetries(newNumOfRetries)
 101         },
 102
 103         getCollection = function(uuid)
 104         {
 105             collection <- private$REST$getResource("collections", uuid)
 106             collection
 107         },
 108
 109         listCollections = function(filters = NULL, limit = 100, offset = 0)
 110         {
 111             if(!is.null(filters))
 112                 names(filters) <- c("collection")
 113
 114             collections <- private$REST$listResources("collections", filters,
 115                                                       limit, offset)
 116             collections
 117         },
 118
 119         listAllCollections = function(filters = NULL)
 120         {
 121             if(!is.null(filters))
 122                 names(filters) <- c("collection")
 123
 124             collectionURL <- paste0(private$host, "collections")
 125             allCollection <- private$REST$fetchAllItems(collectionURL, filters)
 126             allCollection
 127         },
 128
 129         deleteCollection = function(uuid)
 130         {
 131             removedCollection <- private$REST$deleteResource("collections", uuid)
 132             removedCollection
 133         },
 134
 135         updateCollection = function(uuid, newContent)
 136         {
 137             body <- list(list())
 138             names(body) <- c("collection")
 139             body$collection <- newContent
 140
 141             updatedCollection <- private$REST$updateResource("collections",
 142                                                              uuid, body)
 143             updatedCollection
 144         },
 145
 146         createCollection = function(content)
 147         {
 148             body <- list(list())
 149             names(body) <- c("collection")
 150             body$collection <- content
 151
 152             newCollection <- private$REST$createResource("collections", body)
 153             newCollection
 154         },
 155
 156         getProject = function(uuid)
 157         {
 158             project <- private$REST$getResource("groups", uuid)
 159             project
 160         },
 161
 162         createProject = function(content)
 163         {
 164             body <- list(list())
 165             names(body) <- c("group")
 166             body$group <- c("group_class" = "project", content)
 167
 168             newProject <- private$REST$createResource("groups", body)
 169             newProject
 170         },
 171
 172         updateProject = function(uuid, newContent)
 173         {
 174             body <- list(list())
 175             names(body) <- c("group")
 176             body$group <- newContent
 177
 178             updatedProject <- private$REST$updateResource("groups", uuid, body)
 179             updatedProject
 180         },
 181
 182         listProjects = function(filters = NULL, limit = 100, offset = 0)
 183         {
 184             if(!is.null(filters))
 185                 names(filters) <- c("groups")
 186
 187             filters[[length(filters) + 1]] <- list("group_class", "=", "project")
 188
 189             projects <- private$REST$listResources("groups", filters, limit, offset)
 190             projects
 191         },
 192
 193         listAllProjects = function(filters = NULL)
 194         {
 195             if(!is.null(filters))
 196                 names(filters) <- c("groups")
 197
 198             filters[[length(filters) + 1]] <- list("group_class", "=", "project")
 199
 200             projectURL <- paste0(private$host, "groups")
 201
 202             result <- private$REST$fetchAllItems(projectURL, filters)
 203             result
 204         },
 205
 206         deleteProject = function(uuid)
 207         {
 208             removedProject <- private$REST$deleteResource("groups", uuid)
 209             removedProject
 210         }
 211     ),
 212
 213     private = list(
 214
 215         token      = NULL,
 216         host       = NULL,
 217         REST       = NULL,
 218         numRetries = NULL
 219     ),
 220
 221     cloneable = FALSE
 222 )
 223
 224 #' print.Arvados
 225 #'
 226 #' Custom print function for Arvados class
 227 #'
 228 #' @param x Instance of Arvados class
 229 #' @param ... Optional arguments.
 230 #' @export
 231 print.Arvados = function(x, ...)
 232 {
 233     cat(paste0("Type:  ", "\"", "Arvados",       "\""), sep = "\n")
 234     cat(paste0("Host:  ", "\"", x$getHostName(), "\""), sep = "\n")
 235     cat(paste0("Token: ", "\"", x$getToken(),    "\""), sep = "\n")
 236 }