dataone (version 2.2.2)

getDataObject: Download a file (and it's associated system metadata) from the DataONE Federation as a DataObject.

Description

A convenience method to download a data object and its associated SystemMetadata, wrapped in a DataObject class.

Usage

getDataObject(x, identifier, ...)
# S4 method for D1Client
getDataObject(
  x,
  identifier,
  lazyLoad = FALSE,
  limit = "1MB",
  quiet = TRUE,
  checksumAlgorithm = as.character(NA)
)

Arguments

x

A D1Client object.

identifier

The identifier of the object to get.

...

(not yet used)

lazyLoad

A logical value. If TRUE, then only package member system metadata is downloaded and not data.

limit

A character value specifying maximum package member size to download. Specified with "KB", "MB" or "TB" for example: "100KB", "10MB", "20GB", "1TB". The default is "1MB". Only takes effect if 'lazyLoad=FALSE'.

quiet

A 'logical'. If TRUE (the default) then informational messages will not be printed.

checksumAlgorithm

A character value specifying the algorithm to use to re-calculate (after download) the system metadata checksum for the object's data bytes for example: "SHA-256". The default is "NA", which specifies that this re-calculation will not be performed.

Value

A DataObject or NULL if the object was not found in DataONE

Details

This method performs multiple underlying calls to the DataONE repository network. CN.resolve() is called to locate the object on one or more repositories, and then each of these is accessed until the associated SystemMetadata and data bytes are successfully downloaded. This data is then used to construct the returned DataObject. This function replaces the previous getD1Object() method in the version 1 dataone library. The lazyLoad parameter controls whether the data byes for a DataONE item are downloaded (the system metadata is always downloaded). When lazyLoad=FALSE,the limit parameter can be used to specify the maximum size of a data file that will be downloaded. If lazyLoad is TRUE, then limit is ignored. The lazyLoad and limit can be used together in the following ways:

	'lazyLoad'	'limit'	result	comments
	----------	-------	------	---------------------
	TRUE	Any value	Data bytes are not downloaded	The 'limit' parameter is ignored
	FALSE	Not specified	Data bytes are download if less than 1MB	The default 'limit' of 1MB is used
	FALSE	10MB	Data bytes are downloaded if less than 10MB	The specified 'limit' values is used

Note that DataONE system metadata is always downloaded and populated into the resulting DataObject, regardless of the 'lazyLoad' and 'limit' values specified in the call to 'getDataObject()'.

See Also

D1Client class description.

Examples

# NOT RUN {
library(dataone)
d1c <- D1Client("PROD", "urn:node:KNB")
pid <- "solson.5.1"
obj <- getDataObject(d1c, pid)
data <- getData(obj)
# }