sdk/R/R/Collection.R

   1 # Copyright (C) The Arvados Authors. All rights reserved.
   2 #
   3 # SPDX-License-Identifier: Apache-2.0
   4
   5 #' Collection
   6 #'
   7 #' Collection class provides interface for working with Arvados collections.
   8 #'
   9 #' @section Usage:
  10 #' \preformatted{collection = Collection$new(arv, uuid)}
  11 #'
  12 #' @section Arguments:
  13 #' \describe{
  14 #'   \item{arv}{Arvados object.}
  15 #'   \item{uuid}{UUID of a collection.}
  16 #' }
  17 #'
  18 #' @section Methods:
  19 #' \describe{
  20 #'   \item{add(content)}{Adds ArvadosFile or Subcollection specified by content to the collection.}
  21 #'   \item{create(files)}{Creates one or more ArvadosFiles and adds them to the collection at specified path.}
  22 #'   \item{remove(fileNames)}{Remove one or more files from the collection.}
  23 #'   \item{move(content, destination)}{Moves ArvadosFile or Subcollection to another location in the collection.}
  24 #'   \item{copy(content, destination)}{Copies ArvadosFile or Subcollection to another location in the collection.}
  25 #'   \item{getFileListing()}{Returns collections file content as character vector.}
  26 #'   \item{get(relativePath)}{If relativePath is valid, returns ArvadosFile or Subcollection specified by relativePath, else returns NULL.}
  27 #' }
  28 #'
  29 #' @name Collection
  30 #' @examples
  31 #' \dontrun{
  32 #' arv <- Arvados$new("your Arvados token", "example.arvadosapi.com")
  33 #' collection <- Collection$new(arv, "uuid")
  34 #'
  35 #' createdFiles <- collection$create(c("main.cpp", lib.dll), "cpp/src/")
  36 #'
  37 #' collection$remove("location/to/my/file.cpp")
  38 #'
  39 #' collection$move("folder/file.cpp", "file.cpp")
  40 #'
  41 #' arvadosFile <- collection$get("location/to/my/file.cpp")
  42 #' arvadosSubcollection <- collection$get("location/to/my/directory/")
  43 #' }
  44 NULL
  45
  46 #' @export
  47 Collection <- R6::R6Class(
  48
  49     "Collection",
  50
  51     public = list(
  52
  53                 uuid = NULL,
  54
  55                 initialize = function(api, uuid)
  56         {
  57             private$REST <- api$getRESTService()
  58             self$uuid <- uuid
  59         },
  60
  61         add = function(content, relativePath = "")
  62         {
  63             if(is.null(private$tree))
  64                 private$generateCollectionTreeStructure()
  65
  66             if(relativePath == ""  ||
  67                relativePath == "." ||
  68                relativePath == "./")
  69             {
  70                 subcollection <- private$tree$getTree()
  71             }
  72             else
  73             {
  74                 relativePath <- trimFromEnd(relativePath, "/")
  75                 subcollection <- self$get(relativePath)
  76             }
  77
  78             if(is.null(subcollection))
  79                 stop(paste("Subcollection", relativePath, "doesn't exist."))
  80
  81             if("ArvadosFile"   %in% class(content) ||
  82                "Subcollection" %in% class(content))
  83             {
  84                 if(!is.null(content$getCollection()))
  85                     stop("Content already belongs to a collection.")
  86
  87                 if(content$getName() == "")
  88                     stop("Content has invalid name.")
  89
  90                 subcollection$add(content)
  91                 content
  92             }
  93             else
  94             {
  95                 stop(paste0("Expected AravodsFile or Subcollection object, got ",
  96                             paste0("(", paste0(class(content), collapse = ", "), ")"),
  97                             "."))
  98             }
  99         },
 100
 101         create = function(files)
 102         {
 103             if(is.null(private$tree))
 104                 private$generateCollectionTreeStructure()
 105
 106             if(is.character(files))
 107             {
 108                 sapply(files, function(file)
 109                 {
 110                     childWithSameName <- self$get(file)
 111                     if(!is.null(childWithSameName))
 112                         stop("Destination already contains file with same name.")
 113
 114                     newTreeBranch <- private$tree$createBranch(file)
 115                     private$tree$addBranch(private$tree$getTree(), newTreeBranch)
 116
 117                     private$REST$create(file, self$uuid)
 118                     newTreeBranch$setCollection(self)
 119                     newTreeBranch
 120                 })
 121             }
 122             else
 123             {
 124                 stop(paste0("Expected character vector, got ",
 125                             paste0("(", paste0(class(files), collapse = ", "), ")"),
 126                             "."))
 127             }
 128         },
 129
 130         remove = function(paths)
 131         {
 132             if(is.null(private$tree))
 133                 private$generateCollectionTreeStructure()
 134
 135             if(is.character(paths))
 136             {
 137                 sapply(paths, function(filePath)
 138                 {
 139                     filePath <- trimFromEnd(filePath, "/")
 140                     file <- self$get(filePath)
 141
 142                     if(is.null(file))
 143                         stop(paste("File", filePath, "doesn't exist."))
 144
 145                     parent <- file$getParent()
 146
 147                     if(is.null(parent))
 148                         stop("You can't delete root folder.")
 149
 150                     parent$remove(file$getName())
 151                 })
 152
 153                 "Content removed"
 154             }
 155             else
 156             {
 157                 stop(paste0("Expected character vector, got ",
 158                             paste0("(", paste0(class(paths), collapse = ", "), ")"),
 159                             "."))
 160             }
 161         },
 162
 163         move = function(content, destination)
 164         {
 165             if(is.null(private$tree))
 166                 private$generateCollectionTreeStructure()
 167
 168             content <- trimFromEnd(content, "/")
 169
 170             elementToMove <- self$get(content)
 171
 172             if(is.null(elementToMove))
 173                 stop("Content you want to move doesn't exist in the collection.")
 174
 175             elementToMove$move(destination)
 176         },
 177
 178         copy = function(content, destination)
 179         {
 180             if(is.null(private$tree))
 181                 private$generateCollectionTreeStructure()
 182
 183             content <- trimFromEnd(content, "/")
 184
 185             elementToCopy <- self$get(content)
 186
 187             if(is.null(elementToCopy))
 188                 stop("Content you want to copy doesn't exist in the collection.")
 189
 190             elementToCopy$copy(destination)
 191         },
 192
 193         refresh = function()
 194         {
 195             if(!is.null(private$tree))
 196             {
 197                 private$tree$getTree()$setCollection(NULL, setRecursively = TRUE)
 198                 private$tree <- NULL
 199             }
 200         },
 201
 202         getFileListing = function()
 203         {
 204             if(is.null(private$tree))
 205                 private$generateCollectionTreeStructure()
 206
 207             content <- private$REST$getCollectionContent(self$uuid)
 208             content[order(tolower(content))]
 209         },
 210
 211         get = function(relativePath)
 212         {
 213             if(is.null(private$tree))
 214                 private$generateCollectionTreeStructure()
 215
 216             private$tree$getElement(relativePath)
 217         },
 218
 219         getRESTService = function() private$REST,
 220         setRESTService = function(newRESTService) private$REST <- newRESTService
 221     ),
 222
 223     private = list(
 224
 225         REST        = NULL,
 226         tree        = NULL,
 227         fileContent = NULL,
 228
 229         generateCollectionTreeStructure = function()
 230         {
 231             if(is.null(self$uuid))
 232                 stop("Collection uuid is not defined.")
 233
 234             if(is.null(private$REST))
 235                 stop("REST service is not defined.")
 236
 237             private$fileContent <- private$REST$getCollectionContent(self$uuid)
 238             private$tree <- CollectionTree$new(private$fileContent, self)
 239         }
 240     ),
 241
 242     cloneable = FALSE
 243 )
 244
 245 #' print.Collection
 246 #'
 247 #' Custom print function for Collection class
 248 #'
 249 #' @param x Instance of Collection class
 250 #' @param ... Optional arguments.
 251 #' @export
 252 print.Collection = function(x, ...)
 253 {
 254     cat(paste0("Type: ", "\"", "Arvados Collection", "\""), sep = "\n")
 255     cat(paste0("uuid: ", "\"", x$uuid,               "\""), sep = "\n")
 256 }