source("./R/HttpRequest.R")
source("./R/HttpParser.R")
-#' Arvados SDK Object
+#' Arvados
+#'
+#' Arvados class gives users ability to manipulate collections and projects.
+#'
+#' @section Usage:
+#' \preformatted{arv = Arvados$new(authToken, hostName, numRetries = 0)}
#'
-#' All Arvados logic is inside this class
+#' @section Arguments:
+#' \describe{
+#' \item{authToken}{Authentification token. If not specified ARVADOS_API_TOKEN environment variable will be used.}
+#' \item{hostName}{Host name. If not specified ARVADOS_API_HOST environment variable will be used.}
+#' \item{numRetries}{Number which specifies how many times to retry failed service requests.}
+#' }
+#'
+#' @section Methods:
+#' \describe{
+#' \item{getToken()}{Returns authentification token currently in use.}
+#' \item{getHostName()}{Returns host name currently in use.}
+#' \item{getNumRetries()}{Returns number which specifies how many times to retry failed service requests.}
+#' \item{setNumRetries(newNumOfRetries)}{Sets number which specifies how many times to retry failed service requests.}
+#' \item{getCollection(uuid)}{Get collection with specified UUID.}
+#' \item{listCollections(filters = NULL, limit = 100, offset = 0)}{Returns list of collections based on filters parameter.}
+#' \item{listAllCollections(filters = NULL)}{Lists all collections, based on filters parameter, even if the number of items is greater than maximum API limit.}
+#' \item{deleteCollection(uuid)}{Deletes collection with specified UUID.}
+#' \item{updateCollection(uuid, newContent)}{Updates collection with specified UUID.}
+#' \item{createCollection(content)}{Creates new collection.}
+#' \item{getProject(uuid)}{Get project with specified UUID.}
+#' \item{listProjects(filters = NULL, limit = 100, offset = 0)}{Returns list of projects based on filters parameter.}
+#' \item{listAllProjects(filters = NULL)}{Lists all projects, based on filters parameter, even if the number of items is greater than maximum API limit.}
+#' \item{deleteProject(uuid)}{Deletes project with specified UUID.}
+#' \item{updateProject(uuid, newContent)}{Updates project with specified UUID.}
+#' \item{createProject(content)}{Creates new project.}
+#' }
#'
-#' @field token Token represents user authentification token.
-#' @field host Host represents server name we wish to connect to.
-#' @examples arv = Arvados$new("token", "host_name")
-#' @export Arvados
+#' @name Arvados
+#' @examples
+#' \dontrun{
+#' arv <- Arvados$new("your Arvados token", "example.arvadosapi.com")
+#'
+#' collection <- arv$getCollection("uuid")
+#'
+#' collectionList <- arv$listCollections(list(list("name", "like", "Test%")))
+#' collectionList <- arv$listAllCollections(list(list("name", "like", "Test%")))
+#'
+#' deletedCollection <- arv$deleteCollection("uuid")
+#'
+#' updatedCollection <- arv$updateCollection("uuid", list(name = "New name", description = "New description"))
+#'
+#' createdCollection <- arv$createCollection(list(name = "Example", description = "This is a test collection"))
+#' }
+NULL
+
+#' @export
Arvados <- R6::R6Class(
"Arvados",
source("./R/util.R")
-#' ArvadosFile Object
+#' ArvadosFile
+#'
+#' ArvadosFile class represents a file inside Arvados collection.
+#'
+#' @section Usage:
+#' \preformatted{file = ArvadosFile$new(name)}
#'
-#' Update description
+#' @section Arguments:
+#' \describe{
+#' \item{name}{Name of the file.}
+#' }
+#'
+#' @section Methods:
+#' \describe{
+#' \item{getName()}{Returns name of the file}
+#' \item{getRelativePath()}{Returns file path relative to the root.}
+#' \item{read(contentType = "raw", offset = 0, length = 0)}{Read file content.}
+#' \item{write(content, contentType = "text/html")}{Write to file (override current content of the file).}
+#' \item{connection(rw)}{Get connection opened in "read" or "write" mode.}
+#' \item{flush()}{Write content of the connecitons buffer to a file (override current content of the file).}
+#' \item{remove(name)}{Removes ArvadosFile or Subcollection specified by name from the subcollection.}
+#' \item{getSizeInBytes()}{Returns file size in bytes.}
+#' \item{move(newLocation)}{Moves file to a new location inside collection.}
+#' }
#'
-#' @export ArvadosFile
+#' @name ArvadosFile
+#' @examples
+#' \dontrun{
+#' myFile <- ArvadosFile$new("myFile")
+#'
+#' myFile$write("This is new file content")
+#' fileContent <- myFile$read()
+#' fileContent <- myFile$read("text")
+#' fileContent <- myFile$read("raw", offset = 1024, length = 512)
+#'
+#'
+#' #Write a table:
+#' arvConnection <- myFile$connection("w")
+#' write.table(mytable, arvConnection)
+#' arvadosFile$flush()
+#'
+#' #Read a table:
+#' arvConnection <- myFile$connection("r")
+#' mytable <- read.table(arvConnection)
+#'
+#' myFile$move("newFolder/myFile")
+#' }
+NULL
+
+#' @export
ArvadosFile <- R6::R6Class(
"ArvadosFile",
source("./R/RESTService.R")
source("./R/util.R")
-#' Arvados Collection Object
+#' Collection
+#'
+#' Collection class provides interface for working with Arvados collections.
+#'
+#' @section Usage:
+#' \preformatted{collection = Collection$new(arv, uuid)}
#'
-#' Update description
+#' @section Arguments:
+#' \describe{
+#' \item{arv}{Arvados object.}
+#' \item{uuid}{UUID of a collection.}
+#' }
+#'
+#' @section Methods:
+#' \describe{
+#' \item{add(content)}{Adds ArvadosFile or Subcollection specified by content to the collection.}
+#' \item{create(fileNames, relativePath = "")}{Creates one or more ArvadosFiles and adds them to the collection at specified path.}
+#' \item{remove(fileNames)}{Remove one or more files from the collection.}
+#' \item{move(content, newLocation)}{Moves ArvadosFile or Subcollection to another location in the collection.}
+#' \item{getFileListing()}{Returns collections file content as character vector.}
+#' \item{get(relativePath)}{If relativePath is valid, returns ArvadosFile or Subcollection specified by relativePath, else returns NULL.}
+#' }
#'
-#' @examples arv = Collection$new(api, uuid)
-#' @export Collection
+#' @name Collection
+#' @examples
+#' \dontrun{
+#' collection <- Collection$new(arv, "uuid")
+#'
+#' collection$add(existingArvadosFile, "cpp")
+#'
+#' createdFiles <- collection$create(c("main.cpp", lib.dll), "cpp/src/")
+#'
+#' collection$remove("location/to/my/file.cpp")
+#'
+#' collection$move("folder/file.cpp", "file.cpp")
+#'
+#' arvadosFile <- collection$get("location/to/my/file.cpp")
+#' arvadosSubcollection <- collection$get("location/to/my/directory/")
+#' }
+NULL
+
+#' @export
Collection <- R6::R6Class(
"Collection",
source("./R/util.R")
-#' Arvados SubCollection Object
+#' Subcollection
+#'
+#' Subcollection class represents a folder inside Arvados collection.
+#' It is essentially a composite of ArvadosFiles and other Subcollections.
+#'
+#' @section Usage:
+#' \preformatted{subcollection = Subcollection$new(name)}
#'
-#' Update description
+#' @section Arguments:
+#' \describe{
+#' \item{name}{Name of the subcollection.}
+#' }
+#'
+#' @section Methods:
+#' \describe{
+#' \item{getName()}{Returns name of the subcollection.}
+#' \item{getRelativePath()}{Returns subcollection path relative to the root.}
+#' \item{add(content)}{Adds ArvadosFile or Subcollection specified by content to the subcollection.}
+#' \item{remove(name)}{Removes ArvadosFile or Subcollection specified by name from the subcollection.}
+#' \item{get(relativePath)}{If relativePath is valid, returns ArvadosFile or Subcollection specified by relativePath, else returns NULL.}
+#' \item{getFileListing()}{Returns subcollections file content as character vector.}
+#' \item{getSizeInBytes()}{Returns subcollections content size in bytes.}
+#' \item{move(newLocation)}{Moves subcollection to a new location inside collection.}
+#' }
#'
-#' @export Subcollection
+#' @name Subcollection
+#' @examples
+#' \dontrun{
+#' myFolder <- Subcollection$new("myFolder")
+#' myFile <- ArvadosFile$new("myFile")
+#'
+#' myFolder$add(myFile)
+#' myFolder$get("myFile")
+#' myFolder$remove("myFile")
+#'
+#' myFolder$move("newLocation/myFolder")
+#' }
+NULL
+
+#' @export
Subcollection <- R6::R6Class(
"Subcollection",
`collectionList$items_available # count of total number of items (may be more than returned due to paging)`
`collectionList$items # items which match the filter criteria`
-* List all collections even when the number of items is greater than maximum API limit:
+* List all collections even if the number of items is greater than maximum API limit:
`collectionList <- arv$listAllCollections(list(list("name", "like", "Test%")))`
`arvConnection <- arvadosFile$connection("w")`
`write.table(mytable, arvConnection)`
`arvadosFile$flush()`
+
+* Write to existing file (override current content of the file):
+
+ `arvadosFile <- collection$get("location/to/my/file.cpp")`
+ `arvadosFile$write("This is new file content")`
* Read whole file or just a portion of it:
This examples will add file "main.cpp" in "./cpp/src/" folder if folder exists.
If subcollection contains more files or folders they will be added recursively.
-* Write to existing file (override current content of the file):
-
- `arvadosFile <- collection$get("location/to/my/file.cpp")`
- `arvadosFile$write("This is new file content")`
-
* Delete file from a collection:
`collection$remove("location/to/my/file.cpp")`
`projects <- arv$listProjects(list(list("owner_uuid", "=", "aaaaa-j7d0g-ccccccccccccccc"))) # list subprojects of a project`
`arv$listProjects(list(list("name","like","Example%"))) # list projects which have names beginning with Example`
-* List all projects even when the number of items is greater than maximum API limit:
+* List all projects even if the number of items is greater than maximum API limit:
`collectionList <- arv$listAllProjects(list(list("name","like","Example%")))`
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/Arvados.R
-\docType{data}
\name{Arvados}
\alias{Arvados}
-\title{Arvados SDK Object}
-\format{An object of class \code{R6ClassGenerator} of length 24.}
-\usage{
-Arvados
-}
+\title{Arvados}
\description{
-All Arvados logic is inside this class
+Arvados class gives users ability to manipulate collections and projects.
+}
+\section{Usage}{
+
+\preformatted{arv = Arvados$new(authToken, hostName, numRetries = 0)}
}
-\section{Fields}{
+
+\section{Arguments}{
\describe{
-\item{\code{token}}{Token represents user authentification token.}
+ \item{authToken}{Authentification token. If not specified ARVADOS_API_TOKEN environment variable will be used.}
+ \item{hostName}{Host name. If not specified ARVADOS_API_HOST environment variable will be used.}
+ \item{numRetries}{Number which specifies how many times to retry failed service requests.}
+}
+}
-\item{\code{host}}{Host represents server name we wish to connect to.}
-}}
+\section{Methods}{
+
+\describe{
+ \item{getToken()}{Returns authentification token currently in use.}
+ \item{getHostName()}{Returns host name currently in use.}
+ \item{getNumRetries()}{Returns number which specifies how many times to retry failed service requests.}
+ \item{setNumRetries(newNumOfRetries)}{Sets number which specifies how many times to retry failed service requests.}
+ \item{getCollection(uuid)}{Get collection with specified UUID.}
+ \item{listCollections(filters = NULL, limit = 100, offset = 0)}{Returns list of collections based on filters parameter.}
+ \item{listAllCollections(filters = NULL)}{Lists all collections, based on filters parameter, even if the number of items is greater than maximum API limit.}
+ \item{deleteCollection(uuid)}{Deletes collection with specified UUID.}
+ \item{updateCollection(uuid, newContent)}{Updates collection with specified UUID.}
+ \item{createCollection(content)}{Creates new collection.}
+ \item{getProject(uuid)}{Get project with specified UUID.}
+ \item{listProjects(filters = NULL, limit = 100, offset = 0)}{Returns list of projects based on filters parameter.}
+ \item{listAllProjects(filters = NULL)}{Lists all projects, based on filters parameter, even if the number of items is greater than maximum API limit.}
+ \item{deleteProject(uuid)}{Deletes project with specified UUID.}
+ \item{updateProject(uuid, newContent)}{Updates project with specified UUID.}
+ \item{createProject(content)}{Creates new project.}
+}
+}
\examples{
-arv = Arvados$new("token", "host_name")
+\dontrun{
+arv <- Arvados$new("your Arvados token", "example.arvadosapi.com")
+
+collection <- arv$getCollection("uuid")
+
+collectionList <- arv$listCollections(list(list("name", "like", "Test\%")))
+collectionList <- arv$listAllCollections(list(list("name", "like", "Test\%")))
+
+deletedCollection <- arv$deleteCollection("uuid")
+
+updatedCollection <- arv$updateCollection("uuid", list(name = "New name", description = "New description"))
+
+createdCollection <- arv$createCollection(list(name = "Example", description = "This is a test collection"))
+}
}
-\keyword{datasets}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ArvadosFile.R
-\docType{data}
\name{ArvadosFile}
\alias{ArvadosFile}
-\title{ArvadosFile Object}
-\format{An object of class \code{R6ClassGenerator} of length 24.}
-\usage{
-ArvadosFile
-}
+\title{ArvadosFile}
\description{
-Update description
+ArvadosFile class represents a file inside Arvados collection.
+}
+\section{Usage}{
+
+\preformatted{file = ArvadosFile$new(name)}
+}
+
+\section{Arguments}{
+
+\describe{
+ \item{name}{Name of the file.}
+}
+}
+
+\section{Methods}{
+
+\describe{
+ \item{getName()}{Returns name of the file}
+ \item{getRelativePath()}{Returns file path relative to the root.}
+ \item{read(contentType = "raw", offset = 0, length = 0)}{Read file content.}
+ \item{write(content, contentType = "text/html")}{Write to file (override current content of the file).}
+ \item{connection(rw)}{Get connection opened in "read" or "write" mode.}
+ \item{flush()}{Write content of the connecitons buffer to a file (override current content of the file).}
+ \item{remove(name)}{Removes ArvadosFile or Subcollection specified by name from the subcollection.}
+ \item{getSizeInBytes()}{Returns file size in bytes.}
+ \item{move(newLocation)}{Moves file to a new location inside collection.}
+}
+}
+
+\examples{
+\dontrun{
+myFile <- ArvadosFile$new("myFile")
+
+myFile$write("This is new file content")
+fileContent <- myFile$read()
+fileContent <- myFile$read("text")
+fileContent <- myFile$read("raw", offset = 1024, length = 512)
+
+
+#Write a table:
+arvConnection <- myFile$connection("w")
+write.table(mytable, arvConnection)
+arvadosFile$flush()
+
+#Read a table:
+arvConnection <- myFile$connection("r")
+mytable <- read.table(arvConnection)
+
+myFile$move("newFolder/myFile")
+}
}
-\keyword{datasets}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/Collection.R
-\docType{data}
\name{Collection}
\alias{Collection}
-\title{Arvados Collection Object}
-\format{An object of class \code{R6ClassGenerator} of length 24.}
-\usage{
-Collection
-}
+\title{Collection}
\description{
-Update description
+Collection class provides interface for working with Arvados collections.
+}
+\section{Usage}{
+
+\preformatted{collection = Collection$new(arv, uuid)}
+}
+
+\section{Arguments}{
+
+\describe{
+ \item{arv}{Arvados object.}
+ \item{uuid}{UUID of a collection.}
+}
}
+
+\section{Methods}{
+
+\describe{
+ \item{add(content)}{Adds ArvadosFile or Subcollection specified by content to the collection.}
+ \item{create(fileNames, relativePath = "")}{Creates one or more ArvadosFiles and adds them to the collection at specified path.}
+ \item{remove(fileNames)}{Remove one or more files from the collection.}
+ \item{move(content, newLocation)}{Moves ArvadosFile or Subcollection to another location in the collection.}
+ \item{getFileListing()}{Returns collections file content as character vector.}
+ \item{get(relativePath)}{If relativePath is valid, returns ArvadosFile or Subcollection specified by relativePath, else returns NULL.}
+}
+}
+
\examples{
-arv = Collection$new(api, uuid)
+\dontrun{
+collection <- Collection$new(arv, "uuid")
+
+collection$add(existingArvadosFile, "cpp")
+
+createdFiles <- collection$create(c("main.cpp", lib.dll), "cpp/src/")
+
+collection$remove("location/to/my/file.cpp")
+
+collection$move("folder/file.cpp", "file.cpp")
+
+arvadosFile <- collection$get("location/to/my/file.cpp")
+arvadosSubcollection <- collection$get("location/to/my/directory/")
+}
}
-\keyword{datasets}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/Subcollection.R
-\docType{data}
\name{Subcollection}
\alias{Subcollection}
-\title{Arvados SubCollection Object}
-\format{An object of class \code{R6ClassGenerator} of length 24.}
-\usage{
-Subcollection
-}
+\title{Subcollection}
\description{
-Update description
+Subcollection class represents a folder inside Arvados collection.
+It is essentially a composite of ArvadosFiles and other Subcollections.
+}
+\section{Usage}{
+
+\preformatted{subcollection = Subcollection$new(name)}
+}
+
+\section{Arguments}{
+
+\describe{
+ \item{name}{Name of the subcollection.}
+}
+}
+
+\section{Methods}{
+
+\describe{
+ \item{getName()}{Returns name of the subcollection.}
+ \item{getRelativePath()}{Returns subcollection path relative to the root.}
+ \item{add(content)}{Adds ArvadosFile or Subcollection specified by content to the subcollection.}
+ \item{remove(name)}{Removes ArvadosFile or Subcollection specified by name from the subcollection.}
+ \item{get(relativePath)}{If relativePath is valid, returns ArvadosFile or Subcollection specified by relativePath, else returns NULL.}
+ \item{getFileListing()}{Returns subcollections file content as character vector.}
+ \item{getSizeInBytes()}{Returns subcollections content size in bytes.}
+ \item{move(newLocation)}{Moves subcollection to a new location inside collection.}
+}
+}
+
+\examples{
+\dontrun{
+myFolder <- Subcollection$new("myFolder")
+myFile <- ArvadosFile$new("myFile")
+
+myFolder$add(myFile)
+myFolder$get("myFile")
+myFolder$remove("myFile")
+
+myFolder$move("newLocation/myFolder")
+}
}
-\keyword{datasets}
projects / arvados.git / commitdiff