sdk/R/R/ArvadosFile.R

   1 # Copyright (C) The Arvados Authors. All rights reserved.
   2 #
   3 # SPDX-License-Identifier: Apache-2.0
   4
   5 #' R6 Class Representing a ArvadosFile
   6 #'
   7 #' @description
   8 #' ArvadosFile class represents a file inside Arvados collection.
   9
  10 #' @export
  11 ArvadosFile <- R6::R6Class(
  12
  13     "ArvadosFile",
  14
  15     public = list(
  16
  17         #' @description
  18         #' Initialize new enviroment.
  19         #' @param name Name of the new enviroment.
  20         #' @return A new `ArvadosFile` object.
  21         #' @examples
  22         #' myFile   <- ArvadosFile$new("myFile")
  23         initialize = function(name)
  24         {
  25             if(name == "")
  26                 stop("Invalid name.")
  27
  28             private$name <- name
  29         },
  30
  31         #' @description
  32         #' Returns name of the file.
  33         #' @examples
  34         #' arvadosFile$getName()
  35         getName = function() private$name,
  36
  37         #' @description
  38         #' Returns collections file content as character vector.
  39         #' @param fullPath Checking if TRUE.
  40         #' @examples
  41         #' arvadosFile$getFileListing()
  42         getFileListing = function(fullpath = TRUE)
  43         {
  44             self$getName()
  45         },
  46
  47         #' @description
  48         #' Returns collections content size in bytes.
  49         #' @examples
  50         #' arvadosFile$getSizeInBytes()
  51         getSizeInBytes = function()
  52         {
  53             if(is.null(private$collection))
  54                 return(0)
  55
  56             REST <- private$collection$getRESTService()
  57
  58             fileSize <- REST$getResourceSize(self$getRelativePath(),
  59                                              private$collection$uuid)
  60             fileSize
  61         },
  62
  63         get = function(fileLikeObjectName)
  64         {
  65             return(NULL)
  66         },
  67
  68         getFirst = function()
  69         {
  70             return(NULL)
  71         },
  72
  73         #' @description
  74         #' Returns collection UUID.
  75         getCollection = function() private$collection,
  76
  77         #' @description
  78         #' Sets new collection.
  79         setCollection = function(collection, setRecursively = TRUE)
  80         {
  81             private$collection <- collection
  82         },
  83
  84         #' @description
  85         #' Returns file path relative to the root.
  86         getRelativePath = function()
  87         {
  88             relativePath <- c(private$name)
  89             parent <- private$parent
  90
  91             while(!is.null(parent))
  92             {
  93                 relativePath <- c(parent$getName(), relativePath)
  94                 parent <- parent$getParent()
  95             }
  96
  97             relativePath <- relativePath[relativePath != ""]
  98             paste0(relativePath, collapse = "/")
  99         },
 100
 101         #' @description
 102         #' Returns project UUID.
 103         getParent = function() private$parent,
 104
 105         #' @description
 106         #' Sets project collection.
 107         setParent = function(newParent) private$parent <- newParent,
 108
 109         #' @description
 110         #' Read file content.
 111         #' @param contentType Type of content. Possible is "text", "raw".
 112         #' @param offset Describes the location of a piece of data compared to another location
 113         #' @param length Length of content
 114         #' @examples
 115         #' collection <- Collection$new(arv, collectionUUID)
 116         #' arvadosFile <- collection$get(fileName)
 117         #' fileContent <- arvadosFile$read("text")
 118         read = function(contentType = "raw", offset = 0, length = 0)
 119         {
 120             if(is.null(private$collection))
 121                 stop("ArvadosFile doesn't belong to any collection.")
 122
 123             if(offset < 0 || length < 0)
 124                 stop("Offset and length must be positive values.")
 125
 126             REST <- private$collection$getRESTService()
 127
 128             fileContent <- REST$read(self$getRelativePath(),
 129                                      private$collection$uuid,
 130                                      contentType, offset, length)
 131             fileContent
 132         },
 133
 134         #' @description
 135         #' Get connection opened in "read" or "write" mode.
 136         #' @param rw Type of connection.
 137         #' @examples
 138         #' collection <- Collection$new(arv, collectionUUID)
 139         #' arvadosFile <- collection$get(fileName)
 140         #' arvConnection <- arvadosFile$connection("w")
 141         connection = function(rw)
 142         {
 143             if (rw == "r" || rw == "rb")
 144             {
 145                 REST <- private$collection$getRESTService()
 146                 return(REST$getConnection(self$getRelativePath(),
 147                                           private$collection$uuid,
 148                                           rw))
 149             }
 150             else if (rw == "w")
 151             {
 152                 private$buffer <- textConnection(NULL, "w")
 153
 154                 return(private$buffer)
 155             }
 156         },
 157
 158         #' @description
 159         #' Write connections content to a file or override current content of the file.
 160         #' @examples
 161         #' collection <- Collection$new(arv, collectionUUID)
 162         #' arvadosFile <- collection$get(fileName)
 163         #' myFile$write("This is new file content")
 164         #' arvadosFile$flush()
 165         flush = function()
 166         {
 167             v <- textConnectionValue(private$buffer)
 168             close(private$buffer)
 169             self$write(paste(v, collapse='\n'))
 170         },
 171
 172         #' @description
 173         #' Write to file or override current content of the file.
 174         #' @param content File to write.
 175         #' @param contentType Type of content. Possible is "text", "raw".
 176         #' @examples
 177         #' collection <- Collection$new(arv, collectionUUID)
 178         #' arvadosFile <- collection$get(fileName)
 179         #' myFile$write("This is new file content")
 180         write = function(content, contentType = "text/html")
 181         {
 182             if(is.null(private$collection))
 183                 stop("ArvadosFile doesn't belong to any collection.")
 184
 185             REST <- private$collection$getRESTService()
 186
 187             writeResult <- REST$write(self$getRelativePath(),
 188                                       private$collection$uuid,
 189                                       content, contentType)
 190             writeResult
 191         },
 192
 193         #' @description
 194         #' Moves file to a new location inside collection.
 195         #' @param destination Path to new folder.
 196         #' @examples
 197         #' arvadosFile$move(newPath)
 198         move = function(destination)
 199         {
 200             if(is.null(private$collection))
 201                 stop("ArvadosFile doesn't belong to any collection.")
 202
 203             destination <- trimFromEnd(destination, "/")
 204             nameAndPath <- splitToPathAndName(destination)
 205
 206             newParent <- private$collection$get(nameAndPath$path)
 207
 208             if(is.null(newParent))
 209                 stop("Unable to get destination subcollection.")
 210
 211             childWithSameName <- newParent$get(nameAndPath$name)
 212
 213             if(!is.null(childWithSameName))
 214                 stop("Destination already contains content with same name.")
 215
 216             REST <- private$collection$getRESTService()
 217             REST$move(self$getRelativePath(),
 218                       paste0(newParent$getRelativePath(), "/", nameAndPath$name),
 219                       private$collection$uuid)
 220
 221             private$dettachFromCurrentParent()
 222             private$attachToNewParent(self, newParent)
 223
 224             private$parent <- newParent
 225             private$name <- nameAndPath$name
 226
 227             self
 228         },
 229
 230         #' @description
 231         #' Copies file to a new location inside collection.
 232         #' @param destination Path to new folder.
 233         #' @examples
 234         #' arvadosFile$copy("NewName.format")
 235         copy = function(destination)
 236         {
 237             if(is.null(private$collection))
 238                 stop("ArvadosFile doesn't belong to any collection.")
 239
 240             destination <- trimFromEnd(destination, "/")
 241             nameAndPath <- splitToPathAndName(destination)
 242
 243             newParent <- private$collection$get(nameAndPath$path)
 244
 245             if(is.null(newParent))
 246                 stop("Unable to get destination subcollection.")
 247
 248             childWithSameName <- newParent$get(nameAndPath$name)
 249
 250             if(!is.null(childWithSameName))
 251                 stop("Destination already contains content with same name.")
 252
 253             REST <- private$collection$getRESTService()
 254             REST$copy(self$getRelativePath(),
 255                       paste0(newParent$getRelativePath(), "/", nameAndPath$name),
 256                       private$collection$uuid)
 257
 258             newFile <- self$duplicate(nameAndPath$name)
 259             newFile$setCollection(self$getCollection())
 260             private$attachToNewParent(newFile, newParent)
 261             newFile$setParent(newParent)
 262
 263             newFile
 264         },
 265
 266         #' @description
 267         #' Duplicate file and gives it a new name.
 268         #' @param newName New name for duplicated file.
 269         duplicate = function(newName = NULL)
 270         {
 271             name <- if(!is.null(newName)) newName else private$name
 272             newFile <- ArvadosFile$new(name)
 273             newFile
 274         }
 275     ),
 276
 277     private = list(
 278
 279         name       = NULL,
 280         size       = NULL,
 281         parent     = NULL,
 282         collection = NULL,
 283         buffer     = NULL,
 284
 285         attachToNewParent = function(content, newParent)
 286         {
 287             # We temporary set parents collection to NULL. This will ensure that
 288             # add method doesn't post this file on REST.
 289             # We also need to set content's collection to NULL because
 290             # add method throws exception if we try to add content that already
 291             # belongs to a collection.
 292
 293             parentsCollection <- newParent$getCollection()
 294             #parent$.__enclos_env__$private$children <- c(parent$.__enclos_env__$private$children, self)
 295             #private$parent <- parent
 296             content$setCollection(NULL, setRecursively = FALSE)
 297             newParent$setCollection(NULL, setRecursively = FALSE)
 298             newParent$add(content)
 299             content$setCollection(parentsCollection, setRecursively = FALSE)
 300             newParent$setCollection(parentsCollection, setRecursively = FALSE)
 301         },
 302
 303         dettachFromCurrentParent = function()
 304         {
 305             # We temporary set parents collection to NULL. This will ensure that
 306             # remove method doesn't remove this file from REST.
 307
 308             #private$parent$.__enclos_env__$private$removeChild(private$name)
 309             #private$parent <- NULL
 310             parent <- private$parent
 311             parentsCollection <- parent$getCollection()
 312             parent$setCollection(NULL, setRecursively = FALSE)
 313             parent$remove(private$name)
 314             parent$setCollection(parentsCollection, setRecursively = FALSE)
 315         }
 316     ),
 317
 318     cloneable = FALSE
 319 )
 320
 321 #' print.ArvadosFile
 322 #'
 323 #' Custom print function for ArvadosFile class
 324 #'
 325 #' @param x Instance of ArvadosFile class
 326 #' @param ... Optional arguments.
 327 #' @export
 328 print.ArvadosFile = function(x, ...)
 329 {
 330     collection   <- NULL
 331     relativePath <- x$getRelativePath()
 332
 333     if(!is.null(x$getCollection()))
 334     {
 335         collection <- x$getCollection()$uuid
 336         relativePath <- paste0("/", relativePath)
 337     }
 338
 339     cat(paste0("Type:          ", "\"", "ArvadosFile", "\""), sep = "\n")
 340     cat(paste0("Name:          ", "\"", x$getName(),   "\""), sep = "\n")
 341     cat(paste0("Relative path: ", "\"", relativePath,  "\""), sep = "\n")
 342     cat(paste0("Collection:    ", "\"", collection,    "\""), sep = "\n")
 343 }