diff --git a/.github/workflows/R-CMD-check.yaml b/.github/workflows/R-CMD-check.yaml index 197b2a2..cb5ac84 100644 --- a/.github/workflows/R-CMD-check.yaml +++ b/.github/workflows/R-CMD-check.yaml @@ -29,21 +29,21 @@ jobs: R_KEEP_PKG_SOURCE: yes steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 - - uses: r-lib/actions/setup-pandoc@v1 + - uses: r-lib/actions/setup-pandoc@v2 - - uses: r-lib/actions/setup-r@v1 + - uses: r-lib/actions/setup-r@v2 with: r-version: ${{ matrix.config.r }} http-user-agent: ${{ matrix.config.http-user-agent }} use-public-rspm: true - - uses: r-lib/actions/setup-r-dependencies@v1 + - uses: r-lib/actions/setup-r-dependencies@v2 with: extra-packages: rcmdcheck - - uses: r-lib/actions/check-r-package@v1 + - uses: r-lib/actions/check-r-package@v2 - name: Show testthat output if: always() @@ -52,7 +52,7 @@ jobs: - name: Upload check results if: failure() - uses: actions/upload-artifact@main + uses: actions/upload-artifact@v4 with: name: ${{ runner.os }}-r${{ matrix.config.r }}-results path: check diff --git a/DESCRIPTION b/DESCRIPTION index 208e1ca..8551b7f 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: dataone -Version: 2.2.2 -Date: 2022-06-08 +Version: 2.3.0 +Date: 2025-10-08 Title: R Interface to the DataONE REST API Authors@R: c( person("Matthew B.", "Jones", role = c("aut","cre"), email = "jones@nceas.ucsb.edu", comment=c(ORCID = "0000-0003-0077-4738")), person("Peter", "Slaughter", role = "aut", email = "slaughter@nceas.ucsb.edu", comment=c(ORCID = "0000-0002-2192-403X")), @@ -62,4 +62,5 @@ Collate: 'dataone-package.R' Encoding: UTF-8 VignetteBuilder: knitr -RoxygenNote: 7.1.2 +RoxygenNote: 7.3.3 +Roxygen: list(markdown = TRUE) diff --git a/R/AbstractTableDescriber.R b/R/AbstractTableDescriber.R index 3837dfc..6de60a5 100644 --- a/R/AbstractTableDescriber.R +++ b/R/AbstractTableDescriber.R @@ -30,13 +30,13 @@ #' For example, the EMLParser registers itself as a handler for eml v2.0.0 - v2.1.1 #' with the following. #' -#' \code{ +#' ` #' if (!exists("tableDescriber.registry")) tableDescriber.registry <- list() #' tableDescriber.registry[[ "eml://ecoinformatics.org/eml-2.0.0" ]] <- "EMLParser" #' tableDescriber.registry[[ "eml://ecoinformatics.org/eml-2.0.1" ]] <- "EMLParser" #' tableDescriber.registry[[ "eml://ecoinformatics.org/eml-2.1.0" ]] <- "EMLParser" #' tableDescriber.registry[[ "eml://ecoinformatics.org/eml-2.1.1" ]] <- "EMLParser" -#' } +#' ` #' #' Note that the key in the list is the DataONE formatIdentifier that can be #' found at "https://cn.dataone.org/cn/v2/formats". @@ -195,7 +195,7 @@ setGeneric("data.tableAttributeOrientation", function(x, index, ...) { #' @param index - the index of the table within the document #' @param ... Additional parameters #' @return the number of lines to skip -#' @seealso \code{help(read.table)} +#' @seealso `help(read.table)` #' @author rnahf #' @export setGeneric("data.tableSkipLinesHeader", function(x, index, ...) { diff --git a/R/AuthenticationManager.R b/R/AuthenticationManager.R index e0ff653..5472ab2 100644 --- a/R/AuthenticationManager.R +++ b/R/AuthenticationManager.R @@ -29,41 +29,37 @@ #' updating objects on DataONE nodes and reserving identifiers might fail if your #' authorization credentials are missing or expired. #' -#' DataONE version 1.0 identifies you using CILogon-provided x509 certificates. DataONE has -#' partnered with CILogon to provide a widely-accessible certificate issuing mechanism -#' that allows DataONE users to use existing trusted institutional and public accounts. -#' -#' DataONE version 2.0 provides an addition authentication mechanism known as -#' authentication tokens. For information about tokens and instructions for generating +#' DataONE version 2.0 provides an authentication mechanism known using JWT +#' Bearer tokens. For information about tokens and instructions for generating #' a token for use with the dataone R package, view the overview document by -#' entering the command: \code{'vignette("dataone-overview")'}. DataONE authentication -#' tokens can be obtained by signing in to your DataONE account at https://search.dataone.org. +#' entering the command: `'vignette("v01-dataone-overview")'`. DataONE authentication +#' tokens can be obtained by signing in to your DataONE account at https://search.dataone.org +#' and copying the token from your profile settings. +#' +#' Additionally, DataONE API version 1.0 identifies you using CILogon-provided x509 certificates. +#' DataONE partnered with CILogon to provide a widely-accessible certificate issuing mechanism +#' that allows DataONE users to use existing trusted institutional and public accounts, but this method +#' is deprecated and generally users should use JWT Bearer tokens as described above. #' -#' CILogon recognizes many identity providers, including many universities as well as -#' Google, so most times users new to DataONE can get certificates using one -#' of their existing accounts. For more information about the CILogon service, see -#' \url{https://cilogon.org/?skin=DataONE} . -#' @slot obscured Value of type \code{"character"} Is authentication disabled (obscured)? +#' @slot obscured Value of type `"character"` Is authentication disabled (obscured)? #' @rdname AuthenticationManager-class #' @aliases AuthenticationManager-class #' @section Methods: -#' \itemize{ -#' \item{\code{\link{AuthenticationManager}}}{: Create an AuthenticationManager object.} -#' \item{\code{\link{isAuthValid}}}{: Verify authentication for a member node.} -#' \item{\code{\link{getToken}}}{: Get the value of the DataONE Authentication Token, if one exists.} -#' \item{\code{\link{getCert}}}{: Get the DataONE X.509 Certificate location.} -#' \item{\code{\link{getAuthMethod}}}{: Get the current valid authentication mechanism.} -#' \item{\code{\link{getAuthSubject}}}{: Get the authentication subject.} -#' \item{\code{\link{getAuthExpires}}}{: Get the expiration date of the current authentication method.} -#' \item{\code{\link{isAuthExpired}}}{: Check if the currently valid authentication method has reached the expiration time.} -#' \item{\code{\link{obscureAuth}}}{: Temporarily disable DataONE authentication.} -#' \item{\code{\link{restoreAuth}}}{: Restore authentication (after being disabled with \code{obscureAuth}).} -#' \item{\code{\link{showAuth}}}{: Display all authentication information.} -#' \item{\code{\link{getTokenInfo}}}{: Display all authentication token information.} -#' \item{\code{\link{getCertInfo}}}{: Display all X.509 certificate information.} +#' * [AuthenticationManager()]: Create an AuthenticationManager object +#' * [isAuthValid()]: Verify authentication for a member node +#' * [getToken()]: Get the value of the DataONE Authentication Token, if one exists +#' * [getCert()]: Get the DataONE X.509 Certificate location +#' * [getAuthMethod()]: Get the current valid authentication mechanism +#' * [getAuthSubject()]: Get the authentication subject +#' * [getAuthExpires()]: Get the expiration date of the current authentication method +#' * [isAuthExpired()]: Check if the currently valid authentication method has reached the expiration time +#' * [obscureAuth()]: Temporarily disable DataONE authentication +#' * [restoreAuth()]: Restore authentication (after being disabled with `obscureAuth`) +#' * [showAuth()]: Display all authentication information +#' * [getTokenInfo()]: Display all authentication token information +#' * [getCertInfo()]: Display all X.509 certificate information #' -#' } -#' @seealso \code{\link{dataone}}{ package description.} +#' @seealso [dataone()] package description. #' @import base64enc #' @importFrom jsonlite fromJSON #' @include D1Node.R @@ -99,7 +95,7 @@ setMethod("AuthenticationManager", signature=character(), function() { #' via the R options facility, it will be used i.e. available via getOption("dataone_token"). However, #' authentication tokens can only be used for DataONE v2 or higher nodes. X.509 certificates can be used #' with DataONE v1 or higher nodes. -#' See the \emph{"dataone"} vignette \emph{"dataone-overview"} for more information on authentication. +#' See the *"dataone"* vignette *"v01-dataone-overview"* for more information on authentication. #' @param .Object An AuthenticationManager instance #' @param node The node object (MNode or CNode) that authentication is being checked for. #' @param ... additional parameters @@ -181,8 +177,8 @@ setGeneric("getAuthMethod", function(.Object, ...) { }) #' @rdname getAuthMethod -#' @details The current authentication method being used, either an authentication token or an X.509 certificate. The \code{'node'} -#' argument is used to determine the authentication mechanism that is appropriate for the specified \code{'node'}. +#' @details The current authentication method being used, either an authentication token or an X.509 certificate. The `'node'` +#' argument is used to determine the authentication mechanism that is appropriate for the specified `'node'`. #' For example, authentication tokens are supported on DataONE nodes that use the DataONE V2.0 API or higher, so if the #' node uses the V1 API, then only an X.509 certificate can be used. #' @param node A D1Node instance to determine the authentication method for. @@ -203,8 +199,8 @@ setGeneric("getAuthSubject", function(.Object, ...) { #' @rdname getAuthSubject #' @details The authenticated user, aka 'subject' is retrieved from the authentication mechanism -#' currently being used, either an authentication token or an X.509 certificate. The \code{'node'} -#' argument is used to determine the authentication mechanism that is appropriate for the specified \code{'node'}. +#' currently being used, either an authentication token or an X.509 certificate. The `'node'` +#' argument is used to determine the authentication mechanism that is appropriate for the specified `'node'`. #' For example, authentication tokens are supported on DataONE nodes that use the DataONE V2.0 API or higher, so if the #' node uses the V1 API, then only an X.509 certificate can be used. #' @param node A D1Node instance @@ -248,10 +244,10 @@ setMethod("isAuthExpired", signature("AuthenticationManager"), function(.Object, }) #' Temporarily disable DataONE authentication. -#' @description Calling \code{obscureAuth} temporarily disables authentication so that +#' @description Calling `obscureAuth` temporarily disables authentication so that #' @details This method is intended to be used for authentication testing. -#' \code{isAuthValid} will return FALSE. Authentication can be re-enabled by calling -#' \code{restoreAuth}. +#' `isAuthValid` will return FALSE. Authentication can be re-enabled by calling +#' `restoreAuth`. #' @rdname obscureAuth #' @aliases obscureAuth #' @param .Object An AuthenticationManager instance @@ -266,7 +262,7 @@ setMethod("obscureAuth", signature("AuthenticationManager"), function(.Object) { return(.Object) }) -#' Restore authentication (after being disabled with \code{obscureAuth}). +#' Restore authentication (after being disabled with `obscureAuth`). #' @rdname restoreAuth #' @aliases restoreAuth #' @param .Object An AuthenticationManager instance @@ -315,7 +311,7 @@ parseAuthToken <- function(authToken) { #' Evaluate DataONE authentication. #' @description A valid DataONE authentication method is looked for and all #' authentication information is retrieved from it. -#' @details If the node specified in the \code{'node'} parameter is a DataONE v2 node +#' @details If the node specified in the `'node'` parameter is a DataONE v2 node #' or higher, then an authentication token is checked if one exists. If it is readable #' and not expired, then information for the token is returned. If a valid token does #' not exist, then the X.509 certificate is checked, if it exists. If it is valid diff --git a/R/CNode.R b/R/CNode.R index 71165b2..04465be 100644 --- a/R/CNode.R +++ b/R/CNode.R @@ -28,24 +28,23 @@ #' @slot services A data.frame containing the supported service tiers for a CN #' @slot serviceUrls A data.frame contains URL endpoints for certain services #' @section Methods: -#' \itemize{ -#' \item{\code{\link{CNode}}}{: Construct a CNode object.} -#' \item{\code{\link{listFormats}}}{: List all object formats registered in DataONE.} -#' \item{\code{\link{getFormat}}}{: Get information for a single DataONE object format } -#' \item{\code{\link{getChecksum}}}{: Get the checksum for the data object associated with the specified pid.} -#' \item{\code{\link{listNodes}}}{: Get the list of nodes associated with a CN.} -#' \item{\code{\link{reserveIdentifier}}}{: Reserve a identifier that is unique in the DataONE network.} -#' \item{\code{\link{hasReservation}}}{: Checks to determine if the supplied subject is the owner of the reservation of id.} -#' \item{\code{\link{setObsoletedBy}}}{: Set a pid as being obsoleted by another pid} -#' \item{\code{\link{getObject}}}{: Get the bytes associated with an object on this Coordinating Node.} -#' \item{\code{\link{getSystemMetadata}}}{: Get the bytes associated with an object on this Coordinating Node.} -#' \item{\code{\link{describeObject}}}{: Get a list of coordinating nodes holding a given pid.} -#' \item{\code{\link{resolve}}}{: Get a list of coordinating nodes holding a given pid.} -#' \item{\code{\link{getMNode}}}{: Get a reference to a node based on its identifier.} -#' \item{\code{\link{echoCredentials}}}{: Echo the credentials used to make the call.} -#' \item{\code{\link{isAuthorized}}}{: Check if an action is authorized for the specified identifier.} -#' } -#' @seealso \code{\link{dataone}}{ package description.} +#' * [CNode()]: Construct a CNode object +#' * [listFormats()]: List all object formats registered in DataONE +#' * [getFormat()]: Get information for a single DataONE object format +#' * [getChecksum()]: Get the checksum for the data object associated with the specified pid +#' * [listNodes()]: Get the list of nodes associated with a CN +#' * [reserveIdentifier()]: Reserve a identifier that is unique in the DataONE network +#' * [hasReservation()]: Checks to determine if the supplied subject is the owner of the reservation of id +#' * [setObsoletedBy()]: Set a pid as being obsoleted by another pid +#' * [getObject()]: Get the bytes associated with an object on this Coordinating Node +#' * [getSystemMetadata()]: Get the bytes associated with an object on this Coordinating Node +#' * [describeObject()]: Get a list of coordinating nodes holding a given pid +#' * [resolve()]: Get a list of coordinating nodes holding a given pid +#' * [getMNode()]: Get a reference to a node based on its identifier +#' * [echoCredentials()]: Echo the credentials used to make the call +#' * [isAuthorized()]: Check if an action is authorized for the specified identifier +#' +#' @seealso [dataone()] package description. #' @import methods #' @importFrom utils URLencode #' @export @@ -57,13 +56,13 @@ setClass("CNode", slots = c(endpoint = "character"), contains="D1Node") #' Create a CNode object. #' @details For an explanation of DataONE Coordinating Nodes, see the -#' section \emph{"DataONE Environments"} in the overview vignette by entering the R command: \code{vignette("dataone-overview")}. +#' section *"DataONE Environments"* in the overview vignette by entering the R command: `vignette("v01-dataone-overview")`. #' @param x The label for the DataONE environment to be using ('PROD','STAGING', 'STAGING2,'SANDBOX', 'SANDBOX2','DEV', 'DEV2') #' @param ... (not yet used) #' @rdname CNode #' @aliases CNode #' @return the CNode object representing the DataONE environment -#' @seealso \code{\link[=CNode-class]{CNode}}{ class description.} +#' @seealso [`CNode()`][CNode-class] class description. #' @export #' @examples \dontrun{ #' cn <- CNode("PROD") @@ -138,14 +137,14 @@ setMethod("CNode", signature("character"), function(x) { ########################## #' List all object formats registered in DataONE. -#' @description The \link{listFormats} method queries a DataONE Coordinating Node for a +#' @description The [listFormats] method queries a DataONE Coordinating Node for a #' list of all entries in the Object Format Vocabulary. #' @param x a valid CNode object #' @param ... (Not yet used) #' @import httr #' @rdname listFormats #' @aliases listFormats -#' @seealso \code{\link[=CNode-class]{CNode}}{ class description.} +#' @seealso [`CNode()`][CNode-class] class description. #' @return Returns a dataframe of all object formats registered in the DataONE Object Format Vocabulary. #' @examples \dontrun{ #' library(dataone) @@ -207,7 +206,7 @@ setMethod("listFormats", signature("CNode"), function(x) { #' @param x A CNode object instance #' @param ... (Not yet used) #' @return A dataframe of all object formats registered in the DataONE Object Format Vocabulary. -#' @seealso \code{\link[=CNode-class]{CNode}}{ class description.} +#' @seealso [`CNode()`][CNode-class] class description. #' @examples \dontrun{ #' library(dataone) #' cn <- CNode() @@ -275,7 +274,7 @@ setMethod("getChecksum", signature("CNode"), function(x, pid, ...) { #' @param x The coordinating node to query for its registered Member Nodes #' @param ... (Not yet used) #' @return the list of nodes in the DataONE CN environment -#' @seealso \code{\link[=CNode-class]{CNode}}{ class description.} +#' @seealso [`CNode()`][CNode-class] class description. #' @export #' @examples \dontrun{ #' cn <- CNode() @@ -327,7 +326,7 @@ setMethod("listNodes", signature("CNode"), function(x, url=as.character(NA), ... #' @aliases reserveIdentifier #' @param x The coordinating node to query for its registered Member Nodes #' @param ... Additional parameters. -#' @seealso \code{\link[=CNode-class]{CNode}}{ class description.} +#' @seealso [`CNode()`][CNode-class] class description. #' @export #' @examples #' \dontrun{ @@ -365,13 +364,13 @@ setMethod("reserveIdentifier", signature("CNode"), function(x, id) { #' Checks to determine if the supplied subject is the owner of the reservation of id. #' @description The hasReservation method checks the reservation of an identifier that has -#' previously been reserved with the \code{reserveIdentifier} method. The identifier must have -#' been reserved by the specified DataONE user identity (\code{subject}). +#' previously been reserved with the `reserveIdentifier` method. The identifier must have +#' been reserved by the specified DataONE user identity (`subject`). #' @details To determine the DataONE identity that is currently being used for DataONE -#' authentication, use the \code{echoCredentials} method. +#' authentication, use the `echoCredentials` method. #' @param x A CNode instance. #' @param ... Additional parameters. -#' @seealso \code{\link[=CNode-class]{CNode}}{ class description.} +#' @seealso [`CNode()`][CNode-class] class description. #' @export #' @examples #' \dontrun{ @@ -430,8 +429,6 @@ setMethod("hasReservation", signature("CNode"), function(x, pid, subject=as.char #' Set a pid as being obsoleted by another pid #' @description Updates the SystemMetadata 'obsoletedBy' property for an object, indicating that the object #' specified by pid has been obsoleted by the identifier in obsoletedByPid. -#' CILogon \url{https://cilogon.org/?skin=DataONE}. See \code{\link{CertificateManager}} for details. -#' In DataONE version 2.0, authentication tokens can also be used. #' @rdname setObsoletedBy #' @aliases setObsoletedBy #' @param x The CNode instance on which the object will be created @@ -439,7 +436,7 @@ setMethod("hasReservation", signature("CNode"), function(x, pid, subject=as.char #' @param obsoletedByPid The identifier of the object that obsoletes the object identified by pid. #' @param serialVersion The serial version of the system metadata of the pid being obsoleted. #' @param ... (Not yet used) -#' @seealso \code{\link[=CNode-class]{CNode}}{ class description.} +#' @seealso [`CNode()`][CNode-class] class description. #' @export setGeneric("setObsoletedBy", function(x, pid, obsoletedByPid, ...) { .Defunct("updateObject", "dataone") @@ -479,7 +476,7 @@ setMethod("getObject", signature("CNode"), function(x, pid) { #' @details This operation acts as the 'public' anonymous user unless an X.509 certificate is #' present in the default location of the file system, in which case the access will be authenticated. #' @return SystemMetadata for the object -#' @seealso \code{\link[=CNode-class]{CNode}}{ class description.} +#' @seealso [`CNode()`][CNode-class] class description. #' @import datapack #' @export #' @rdname getSystemMetadata @@ -577,13 +574,13 @@ setMethod("resolve", signature("CNode"), function(x, pid){ #' @rdname getMNode #' @aliases getMNode #' @details For an explanation of DataONE Coordinating Nodes and Member Node -#' identifiers, see the section \emph{"DataONE Environments"} in the overview vignette -#' by entering the R command: \code{vignette("dataone-overview")}. +#' identifiers, see the section *"DataONE Environments"* in the overview vignette +#' by entering the R command: `vignette("v01-dataone-overview")`. #' @param x The coordinating node to query for its registered Member Nodes #' @param nodeid The standard identifier string for this node #' @param ... (Not yet used) #' @return the Member Node as an MNode reference, or NULL if not found -#' @seealso \code{\link[=CNode-class]{CNode}}{ class description.} +#' @seealso [`CNode()`][CNode-class] class description. #' @export #' @examples \dontrun{ #' cn <- CNode() diff --git a/R/CertificateManager.R b/R/CertificateManager.R index 25a27fa..3551cf1 100644 --- a/R/CertificateManager.R +++ b/R/CertificateManager.R @@ -52,23 +52,22 @@ #' from the time of issuing. Typically you will want to download a fresh certificate #' the first time you interact with DataONE each day. #' -#' @slot location value of type \code{"character"}, containing a path to a custom certificate location -#' @slot obscuredpath value of type \code{"character"}, containing the path used to temporarily obscure a certificate +#' @slot location value of type `"character"`, containing a path to a custom certificate location +#' @slot obscuredpath value of type `"character"`, containing the path used to temporarily obscure a certificate #' @author Matthew Jones, Rob Nahf #' @rdname CertificateManager-class #' @keywords classes #' @section Methods: -#' \itemize{ -#' \item{\code{\link{CertificateManager}}}{: Create a CertificateManager object.} -#' \item{\code{\link{getCertLocation}}}{: Get the file path on disk of the client certificate file.} -#' \item{\code{\link{showClientSubject}}}{: Get DataONE Identity as Stored in the CILogon Certificate.} -#' \item{\code{\link{isCertExpired}}}{: Determine if an X.509 certificate has expired.} -#' \item{\code{\link{getCertExpires}}}{: Show the date and time when an X.509 certificate expires.} -#' \item{\code{\link{downloadCert}}}{: Open the CILogon Certificate download page in the default browser.} -#' \item{\code{\link{obscureCert}}}{: Obscure the CILogon Client Certificate.} -#' \item{\code{\link{restoreCert}}}{: Restore the CILogon client certificate by renaming it to its original location} -#' } -#' @seealso \code{\link{dataone}}{ package description.} +#' * [CertificateManager()]: Create a CertificateManager object +#' * [getCertLocation()]: Get the file path on disk of the client certificate file +#' * [showClientSubject()]: Get DataONE Identity as Stored in the CILogon Certificate +#' * [isCertExpired()]: Determine if an X.509 certificate has expired +#' * [getCertExpires()]: Show the date and time when an X.509 certificate expires +#' * [downloadCert()]: Open the CILogon Certificate download page in the default browser +#' * [obscureCert()]: Obscure the CILogon Client Certificate +#' * [restoreCert()]: Restore the CILogon client certificate by renaming it to its original location +#' +#' @seealso [dataone()] package description. #' @examples #' \dontrun{ #' cm <- suppressWarnings(CertificateManager()) @@ -87,9 +86,9 @@ setClass("CertificateManager", slots = c( #' Create a CertificateManager object #' @description Construct an instance of CertficateManager to provide mechanisms to obtain, load, verify, and -#' display X509 certificates. If the \code{'location'} field is provided, then that location is interpreted +#' display X509 certificates. If the `'location'` field is provided, then that location is interpreted #' as the fully qualified path to a certificate on the local filesystem, and the default locations will not be -#' searched. If \code{'location'} is missing, then the default Globus Grid Security Infrastructure (GSI) +#' searched. If `'location'` is missing, then the default Globus Grid Security Infrastructure (GSI) #' location is searched, which is \code{'/tmp/x509up_u${UID}'} on Unix #' or \code{'${tmpdir}/x509up_u${UID}'} on Windows or \code{'${tmpdir}/x509up_u${user.name}'} if \code{'${UID}'} #' is not defined. @@ -146,7 +145,7 @@ setMethod("showClientSubject", signature("CertificateManager"), function(x) { }) #' Determine if an X.509 certificate has expired. -#' @description Returns \code{'TRUE'} if the certificate associated with a CertificateManager instance is expired. +#' @description Returns `'TRUE'` if the certificate associated with a CertificateManager instance is expired. #' A certificate is expired if any of the following conditions hold: 1) the current time is before or after the #' certificate validity dates, 2) the certificate is not valid according to a trusted Certificate Authority, or #' 3) no certificate can be found. @@ -178,7 +177,7 @@ setMethod("isCertExpired", signature("CertificateManager"), function(x) { #' Show the date and time when an X.509 certificate expires. #' @description Each X.509 has a range of certificate validity times. This method returns the X.509 -#' \code{'notAfter'} field formatted as a \code{'POSIXct'} date value. +#' `'notAfter'` field formatted as a `'POSIXct'` date value. #' @param x a CertificateManager instance #' @param ... (Not yet used) #' @rdname getCertExpires @@ -207,7 +206,7 @@ setMethod("getCertExpires", signature("CertificateManager"), function(x) { #' "https://cilogon.org/?skin=DataONE. Logging into CILogon will allow #' you to download your X.509 certificate to your local computer. Typically, #' the certificate is saved in the default Globus location for certificates -#' (\code{\link{getCertLocation}}) and once it is there, the \code{'dataone'} +#' ([getCertLocation()]) and once it is there, the `'dataone'` #' package will use the certificate for all authenticated operations. Deleting #' the certificate file is the equivalent of logging out. #' @param x a CertificateManager instance @@ -237,7 +236,7 @@ setMethod("downloadCert", signature("CertificateManager"), function(x) { #' @rdname obscureCert #' @aliases obscureCert #' @return the modified CertificateManager instance -#' @seealso \code{\link{restoreCert}} is this method's inverse operation +#' @seealso [restoreCert()] is this method's inverse operation #' @export setGeneric("obscureCert", function(x, ...) { .Deprecated("obscureAuth", "dataone") @@ -264,7 +263,7 @@ setMethod("obscureCert", signature("CertificateManager"), function(x) { #' @rdname restoreCert #' @aliases restoreCert #' @return the modified CertificateManager instance -#' @seealso \code{\link{obscureCert}} is this method's inverse operation +#' @seealso [obscureCert()] is this method's inverse operation #' @import stringr #' @export setGeneric("restoreCert", function(x, ...) { @@ -297,7 +296,7 @@ setMethod("restoreCert", signature("CertificateManager"), function(x) { #' Get the file path on disk of the client certificate file. #' @description Find the location of the client certificate, which is typically in a default -#' location on disk, unless the \code{'location'} slot has been set with a custom location for +#' location on disk, unless the `'location'` slot has been set with a custom location for #' the certificate. #' @details The default Globus Grid Security Infrastructure (GSI) location is \code{'/tmp/x509up_u${UID}'} #' on Unix or \code{'${tmpdir}/x509up_u${UID}'} on Windows or \code{'${tmpdir}/x509up_u${user.name}'} diff --git a/R/D1Client.R b/R/D1Client.R index d80b3c7..dbb7840 100644 --- a/R/D1Client.R +++ b/R/D1Client.R @@ -20,7 +20,7 @@ #' @title The D1Client class contains methods that perform high level DataONE tasks #' @description The methods in the D1Client class call the low level DataONE API to #' perform involved tasks such as uploading all the packages in a DataPackage (i.e -#' \code{\link{uploadDataPackage}}) +#' [uploadDataPackage()]) #' @include CNode.R #' @include MNode.R #' @include D1Object.R @@ -33,23 +33,22 @@ #' @importFrom stringr str_match str_replace #' @importFrom utils URLencode #' @section Methods: -#' \itemize{ -#' \item{\code{\link{D1Client}}}{: Construct a D1Client object.} -#' \item{\code{\link{convert.csv}}}{: Convert a DataFrame to Standard CSV.} -#' \item{\code{\link{createDataPackage}}}{: Create a DataPackage on a DataONE Member Node.} -#' \item{\code{\link{encodeUrlPath}}}{: Encode the Input for a URL Path Segment.} -#' \item{\code{\link{encodeUrlQuery}}}{: Encode the Input for a URL Query Segment.} -#' \item{\code{\link{getDataObject}}}{: Download a single data object from a DataONE Federation member node.} -#' \item{\code{\link{getDataPackage}}}{: Download a collection of data object from the DataONE Federation member node as a DataPackage.} -#' \item{\code{\link{getEndpoint}}}{: Return the URL endpoint for the DataONE Coordinating Node.} -#' \item{\code{\link{getMetadataMember}}}{: Get the DataObject containing package metadata.} -#' \item{\code{\link{getMNodeId}}}{: Get the member node identifier associated with this D1Client object.} -#' \item{\code{\link{listMemberNodes}}}{: List DataONE Member Nodes.} -#' \item{\code{\link{reserveIdentifier}}}{: Reserve a unique identifier in the DataONE Network.} -#' \item{\code{\link{uploadDataObject}}}{: Upload a DataObject to a DataONE member node.} -#' \item{\code{\link{uploadDataPackage}}}{: Upload a DataPackage to a DataONE member node.} -#' } -#' @seealso \code{\link{dataone}}{ package description.} +#' * [D1Client()]: Construct a D1Client object +#' * [convert.csv()]: Convert a DataFrame to Standard CSV +#' * [createDataPackage()]: Create a DataPackage on a DataONE Member Node +#' * [encodeUrlPath()]: Encode the Input for a URL Path Segment +#' * [encodeUrlQuery()]: Encode the Input for a URL Query Segment +#' * [getDataObject()]: Download a single data object from a DataONE Federation member node +#' * [getDataPackage()]: Download a collection of data object from the DataONE Federation member node as a DataPackage +#' * [getEndpoint()]: Return the URL endpoint for the DataONE Coordinating Node +#' * [getMetadataMember()]: Get the DataObject containing package metadata +#' * [getMNodeId()]: Get the member node identifier associated with this D1Client object +#' * [listMemberNodes()]: List DataONE Member Nodes +#' * [reserveIdentifier()]: Reserve a unique identifier in the DataONE Network +#' * [uploadDataObject()]: Upload a DataObject to a DataONE member node +#' * [uploadDataPackage()]: Upload a DataPackage to a DataONE member node +#' +#' @seealso [dataone()] package description. #' @export #' @import datapack setClass("D1Client", slots = c(cn = "CNode", mn="MNode")) @@ -61,12 +60,12 @@ setClass("D1Client", slots = c(cn = "CNode", mn="MNode")) #' The DataONE client class used to download, update and search for data in the DataONE network. #' @rdname D1Client #' @param x The label for the DataONE environment to be using ('PROD','STAGING','SANDBOX','DEV'). This parameter -#' can alternatively be a \code{\link{CNode}} instance, with the `y` parameter specified as an \code{\link{MNode}} instance. +#' can alternatively be a [CNode()] instance, with the `y` parameter specified as an [MNode()] instance. #' @param y The node Id of the application's 'home' node. Should be already registered to the corresponding 'env'. This -#' parameter can alternatively be an \code{\link{MNode}} instance, with the `x` parameter specified as a \code{\link{CNode}} instance. +#' parameter can alternatively be an [MNode()] instance, with the `x` parameter specified as a [CNode()] instance. #' @param ... (not yet used) #' @return the D1Client object representing the DataONE environment -#' @seealso \code{\link[=D1Client-class]{D1Client}}{ class description.} +#' @seealso [`D1Client()`][D1Client-class] class description. #' @export #' @examples \dontrun{ #' cli <- D1Client("PROD", "urn:node:KNB") @@ -127,7 +126,7 @@ setMethod("D1Client", signature("character", "MNode"), function(x, y, ...) { #' library(dataone) #' d1c <- D1Client("PROD", "urn:node:KNB") #' } -#' @seealso \code{\link[=D1Client-class]{dataone}}{ class description.} +#' @seealso [`dataone()`][D1Client-class] class description. setMethod("initialize", signature = "D1Client", definition = function(.Object, cn=NA, mn=NA, env=as.character(NA), mNodeid=as.character(NA)) { # defaults here if (missing(cn)) { @@ -207,7 +206,7 @@ setMethod("createD1Object", signature("D1Client", "D1Object"), function(x, d1Obj #' @rdname getD1Object #' @aliases getD1Object #' @return A datapack:DataObject -#' @seealso \code{\link[=D1Client-class]{D1Client}}{ class description.} +#' @seealso [`D1Client()`][D1Client-class] class description. #' @export #' @examples \dontrun{ #' library(dataone) @@ -237,10 +236,10 @@ setMethod("getD1Object", "D1Client", function(x, identifier) { #' data is then used to construct the returned DataObject. This function replaces the previous #' getD1Object() method in the version 1 #' dataone library. \cr\cr -#' The \code{lazyLoad} parameter controls whether the data byes for a DataONE item are downloaded (the system -#' metadata is always downloaded). When \code{lazyLoad}=FALSE,the \code{limit} parameter can be used to specify -#' the maximum size of a data file that will be downloaded. If \code{lazyLoad} is TRUE, then \code{limit} -#' is ignored. The \code{lazyLoad} and \code{limit} can be used together in the following ways: +#' 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: #' #' \tabular{lllll}{ #' \tab 'lazyLoad' \tab 'limit' \tab result \tab comments \cr @@ -255,18 +254,18 @@ setMethod("getD1Object", "D1Client", function(x, identifier) { #' #' @param x A D1Client object. #' @param identifier The identifier of the object to get. -#' @param lazyLoad A \code{logical} value. If TRUE, then only package member system metadata is downloaded and not data. -#' @param limit A \code{character} value specifying maximum package member size to download. Specified with "KB", "MB" or "TB" +#' @param lazyLoad A `logical` value. If TRUE, then only package member system metadata is downloaded and not data. +#' @param 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'. -#' @param quiet A \code{'logical'}. If TRUE (the default) then informational messages will not be printed. -#' @param checksumAlgorithm A \code{character} value specifying the algorithm to use to re-calculate (after download) the system metadata checksum +#' @param quiet A `'logical'`. If TRUE (the default) then informational messages will not be printed. +#' @param 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. #' @param ... (not yet used) #' @rdname getDataObject #' @aliases getDataObject #' @return A DataObject or NULL if the object was not found in DataONE -#' @seealso \code{\link[=D1Client-class]{D1Client}}{ class description.} +#' @seealso [`D1Client()`][D1Client-class] class description. #' @export #' @examples \dontrun{ #' library(dataone) @@ -467,10 +466,10 @@ setMethod("getDataObject", "D1Client", function(x, identifier, lazyLoad=FALSE, l #' member. #' @details A 'data package' that resides on a DataONE member node is defined as a collection of #' digital objects that are described by a metadata document. \cr\cr -#' The \code{lazyLoad} parameter controls whether the data bytes for a DataONE package member are downloaded (the system -#' metadata is always downloaded). When \code{lazyLoad}=FALSE, the \code{limit} parameter can be used to specify -#' the maximum size of a data file that will be downloaded. If \code{lazyLoad} is TRUE, then \code{limit} -#' is ignored. The \code{lazyLoad} and \code{limit} parameters can be used together in the following ways: +#' The `lazyLoad` parameter controls whether the data bytes for a DataONE package member 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` parameters can be used together in the following ways: #' #' \tabular{lllll}{ #' \tab 'lazyLoad' \tab 'limit' \tab result \tab comments \cr @@ -483,7 +482,7 @@ setMethod("getDataObject", "D1Client", function(x, identifier, lazyLoad=FALSE, l #' @rdname getDataPackage #' @aliases getDataPackage #' @return A DataPackage or NULL if the package was not found in DataONE -#' @seealso \code{\link[=D1Client-class]{D1Client}}{ class description.} +#' @seealso [`D1Client()`][D1Client-class] class description. #' @export #' @examples \dontrun{ #' library(dataone) @@ -497,12 +496,12 @@ setGeneric("getDataPackage", function(x, identifier, ...) { #' @rdname getDataPackage #' @param identifier The identifier of a package, package metadata or other package member -#' @param lazyLoad A \code{logical} value. If TRUE, then only package member system metadata is downloaded and not data. -#' The default is \code{FALSE}. -#' @param limit A \code{character} value specifying maximum package member size to download. Specified with "KB", "MB" or "TB" +#' @param lazyLoad A `logical` value. If TRUE, then only package member system metadata is downloaded and not data. +#' The default is `FALSE`. +#' @param 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'. -#' @param quiet A \code{'logical'}. If TRUE (the default) then informational messages will not be printed. -#' @param checksumAlgorithm A \code{character} value specifying the algorithm to use to re-calculate (after download) the system metadata checksum +#' @param quiet A `'logical'`. If TRUE (the default) then informational messages will not be printed. +#' @param 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. #' @param ... (not yet used) #' @export @@ -718,7 +717,7 @@ setMethod("getDataPackage", "D1Client", function(x, identifier, lazyLoad=FALSE, #' fl="title,id,abstract,size,dateUploaded,attributeName") #' result <- d1SolrQuery(d1c, queryParams) #' } -#' @seealso \code{\link[=D1Client-class]{D1Client}}{ class description.} +#' @seealso [`D1Client()`][D1Client-class] class description. setGeneric("d1SolrQuery", function(x, solrQuery) { msg <- sprintf("'d1SolrQuewry' is defunct.\nUse 'dataone:query' instead.\nSee help(\"Defunct\") and help(\"dataone-defunct\").") .Defunct("query", "dataone", msg) @@ -751,7 +750,7 @@ setMethod("d1SolrQuery", signature("D1Client", "character"), function(x, solrQue #' client <- new("D1Client") #' result <- d1IdentifierSearch(client,solrQuery="species population diversity") #' } -#' @seealso \code{\link[=D1Client-class]{D1Client}}{ class description.} +#' @seealso [`D1Client()`][D1Client-class] class description. #' @export setGeneric("d1IdentifierSearch", function(x, ...) { msg <- sprintf("'d1IdentifierSearch' is defunct.\nUse 'dataone:query' instead.\nSee help(\"Defunct\") and help(\"dataone-defunct\").") @@ -786,7 +785,7 @@ setMethod("reserveIdentifier", signature("D1Client"), function(x, id) { #' @rdname createDataPackage #' @aliases createDataPackage #' @return The identifier of the uploaded package. -#' @seealso \code{\link[=D1Client-class]{D1Client}}{ class description.} +#' @seealso [`D1Client()`][D1Client-class] class description. #' @export #' @examples \dontrun{ #' library(dataone) @@ -836,7 +835,7 @@ setMethod("createDataPackage", signature("D1Client", "DataPackage"), function(x, #' @return A character vector containing the URL of the Coordinating Node #' @rdname getEndpoint #' @aliases getEndpoint -#' @seealso \code{\link[=D1Client-class]{D1Client}}{ class description.} +#' @seealso [`D1Client()`][D1Client-class] class description. #' @export #' @examples \dontrun{ #' cli <- D1Client("STAGING2", "urn:node:mnTestKNB") @@ -858,7 +857,7 @@ setMethod("getEndpoint", "D1Client", function(x) { #' @return The Member Node identifier as a character vector #' @rdname getMNodeId #' @aliases getMNodeId -#' @seealso \code{\link[=D1Client-class]{D1Client}}{ class description.} +#' @seealso [`D1Client()`][D1Client-class] class description. #' @export #' @examples \dontrun{ #' cli <- D1Client("STAGING2", "urn:node:mnTestKNB") @@ -889,7 +888,7 @@ setMethod("getMNodeId", signature("D1Client"), function(x) { #' @param id A DataONE member node identifier. #' @rdname setMNodeId #' @author setMNodeId -#' @seealso \code{\link[=D1Client-class]{D1Client}}{ class description.} +#' @seealso [`D1Client()`][D1Client-class] class description. #' @export setGeneric("setMNodeId", function(x, id) { standardGeneric("setMNodeId") @@ -915,8 +914,8 @@ setMethod("setMNodeId", signature("D1Client", "character"), function(x, id) { #' @param ... (Not yet used) #' @rdname getMN #' @aliases getMN -#' @note This method has been superceded by \code{\link{getMNodeId}} -#' @seealso \code{\link[=D1Client-class]{D1Client}}{ class description.} +#' @note This method has been superceded by [getMNodeId()] +#' @seealso [`D1Client()`][D1Client-class] class description. #' @export #' @examples \dontrun{ #' cli <- D1Client("STAGING2", "urn:node:mnTestKNB") @@ -952,7 +951,7 @@ setMethod("getMN", signature("D1Client", "character"), function(x, nodeid) { #' @rdname getCN #' @aliases getCN #' @note The method getCN has been deprecated. -#' @seealso \code{\link[=D1Client-class]{D1Client}}{ class description.} +#' @seealso [`D1Client()`][D1Client-class] class description. #' @export #' @examples \dontrun{ #' cli <- D1Client("STAGING2", "urn:node:mnTestKNB") @@ -969,7 +968,7 @@ setMethod("getCN", signature("D1Client"), function(x) { }) #' Upload a DataPackage to a DataONE member node. -#' @description Upload all DataObjects contained in the DataPackage by calling \code{\link{uploadDataObject}} +#' @description Upload all DataObjects contained in the DataPackage by calling [uploadDataObject()] #' on each of the members. Also a resourceMap object is created from the #' recorded relationships between DataObjects, and this is uploaded as well. #' @details The DataPackage describes the collection of data object and their associated @@ -1003,22 +1002,22 @@ setMethod("getCN", signature("D1Client"), function(x) { #' # Upload all members of the DataPackage to DataONE (requires authentication) #' packageId <- uploadDataPackage(d1c, dp, replicate=TRUE, public=TRUE, numberReplicas=2) #' } -#' @seealso \code{\link[=D1Client-class]{D1Client}}{ class description.} +#' @seealso [`D1Client()`][D1Client-class] class description. setGeneric("uploadDataPackage", function(x, ...) { standardGeneric("uploadDataPackage") }) #' @rdname uploadDataPackage #' @param dp The DataPackage instance to be submitted to DataONE for creation. -#' @param replicate A value of type \code{"logical"}, if TRUE then DataONE will replicate this object to other member nodes -#' @param numberReplicas A value of type \code{"numeric"}, for number of supported replicas. -#' @param preferredNodes A list of \code{"character"}, each of which is the node identifier for a node to which a replica should be sent. -#' @param public A \code{'logical'}, if TRUE then all objects in this package will be accessible by any user -#' @param accessRules Access rules of \code{'data.frame'} that will be added to the access policy of each object in the datapackage. -#' @param quiet A \code{'logical'}. If TRUE (the default) then informational messages will not be printed. -#' @param resolveURI A URI to prepend to identifiers (i.e. for use when creating the ResourceMap). See \link[datapack]{serializePackage} -#' @param packageId A value of type \code{"character"} specifying a unique identifier to use for the uploaded package (resource map pid) -#' @param as A value of type \code{"character"} that specifies the return value. Possible values are \code{"character"} (the default) or \code{"DataPackage"}. +#' @param replicate A value of type `"logical"`, if TRUE then DataONE will replicate this object to other member nodes +#' @param numberReplicas A value of type `"numeric"`, for number of supported replicas. +#' @param preferredNodes A list of `"character"`, each of which is the node identifier for a node to which a replica should be sent. +#' @param public A `'logical'`, if TRUE then all objects in this package will be accessible by any user +#' @param accessRules Access rules of `'data.frame'` that will be added to the access policy of each object in the datapackage. +#' @param quiet A `'logical'`. If TRUE (the default) then informational messages will not be printed. +#' @param resolveURI A URI to prepend to identifiers (i.e. for use when creating the ResourceMap). See [serializePackage][datapack::serializePackage] +#' @param packageId A value of type `"character"` specifying a unique identifier to use for the uploaded package (resource map pid) +#' @param as A value of type `"character"` that specifies the return value. Possible values are `"character"` (the default) or `"DataPackage"`. #' @importFrom utils flush.console #' @export setMethod("uploadDataPackage", signature("D1Client"), function(x, dp, replicate=NA, numberReplicas=NA, preferredNodes=NA, public=as.logical(FALSE), @@ -1297,7 +1296,7 @@ setMethod("uploadDataPackage", signature("D1Client"), function(x, dp, replicate= #' @return id The id of the DataObject that was uploaded #' @rdname uploadDataObject #' @aliases uploadDataObject -#' @seealso \code{\link[=D1Client-class]{D1Client}}{ class description.} +#' @seealso [`D1Client()`][D1Client-class] class description. #' @import datapack #' @export #' @examples \dontrun{ @@ -1317,12 +1316,12 @@ setGeneric("uploadDataObject", function(x, ...) { #' @rdname uploadDataObject #' @param do The DataObject instance to be uploaded to DataONE. -#' @param replicate A value of type \code{"logical"}, if TRUE then DataONE will replicate this object to other member nodes -#' @param numberReplicas A value of type \code{"numeric"}, for number of supported replicas. -#' @param preferredNodes A list of \code{"character"}, each of which is the node identifier for a node to which a replica should be sent. -#' @param public A \code{"logical"} value - if TRUE then the uploaded object will be publicly readable. -#' @param accessRules Access rules of \code{'data.frame'} that will be added to the access policy -#' @param quiet A \code{'logical'}. If TRUE (the default) then informational messages will not be printed. +#' @param replicate A value of type `"logical"`, if TRUE then DataONE will replicate this object to other member nodes +#' @param numberReplicas A value of type `"numeric"`, for number of supported replicas. +#' @param preferredNodes A list of `"character"`, each of which is the node identifier for a node to which a replica should be sent. +#' @param public A `"logical"` value - if TRUE then the uploaded object will be publicly readable. +#' @param accessRules Access rules of `'data.frame'` that will be added to the access policy +#' @param quiet A `'logical'`. If TRUE (the default) then informational messages will not be printed. #' @export setMethod("uploadDataObject", signature("D1Client"), function(x, do, replicate=as.logical(FALSE), numberReplicas=NA, preferredNodes=NA, public=as.logical(FALSE), accessRules=NA, @@ -1478,11 +1477,11 @@ setMethod("uploadDataObject", signature("D1Client"), function(x, do, replicate= #' List DataONE Member Nodes. #' @description A D1Client object is associated with a DataONE Coordinating Node. The -#' \code{listMemberNodes} method lists all member nodes associated with a CN. +#' `listMemberNodes` method lists all member nodes associated with a CN. #' @param x A D1Client object. #' @rdname listMemberNodes #' @aliases listMemberNodes -#' @seealso \code{\link[=D1Client-class]{D1Client}}{ class description.} +#' @seealso [`D1Client()`][D1Client-class] class description. #' @export #' @examples \dontrun{ #' d1c <- D1Client("PROD") @@ -1509,7 +1508,7 @@ setMethod("listMemberNodes", signature("D1Client"), function(x) { #' @rdname convert.csv #' @aliases convert.csv #' @return the dataframe serialized as a .csv -#' @seealso \code{\link[=D1Client-class]{D1Client}}{ class description.} +#' @seealso [`D1Client()`][D1Client-class] class description. #' @export #' @importFrom utils write.csv #' @examples \dontrun{ @@ -1542,7 +1541,7 @@ setMethod("convert.csv", signature(x="D1Client"), function(x, df, ...) { #' @rdname encodeUrlQuery #' @aliases encodeUrlQuery #' @return the encoded form of the input -#' @seealso \code{\link[=D1Client-class]{D1Client}}{ class description.} +#' @seealso [`D1Client()`][D1Client-class] class description. #' @examples \dontrun{ #' d1c <- D1Client("STAGING", "urn:node:mnStageUCSB2") #' fullyEncodedQuery <- paste0("q=id:", @@ -1583,7 +1582,7 @@ setMethod("encodeUrlQuery", signature(x="D1Client"), function(x, querySegment, . #' fullyEncodedPath <- paste0("cn/v1/object/", #' encodeUrlPath(d1c, "doi:10.6085/AA/YBHX00_XXXITBDXMMR01_20040720.50.5")) #' } -#' @seealso \code{\link[=D1Client-class]{D1Client}}{ class description.} +#' @seealso [`D1Client()`][D1Client-class] class description. #' @export setGeneric("encodeUrlPath", function(x, ...) { standardGeneric("encodeUrlPath") @@ -1598,15 +1597,15 @@ setMethod("encodeUrlPath", signature(x="D1Client"), function(x, pathSegment, ... #' Add a D1Object containing a data object to a DataPackage #' @rdname addData -#' @description The D1Object \code{do} is added to the data package \code{x}. -#' @details If the optional \code{mo} parameter is specified, then it is assumed that this DataObject is a metadata -#' object that describes the data object that is being added. The DataObject specified in the \code{mo} parameter will -#' also be added to the DataPackage, if it has not already been added. Then the \code{addData} function will add a relationship +#' @description The D1Object `do` is added to the data package `x`. +#' @details If the optional `mo` parameter is specified, then it is assumed that this DataObject is a metadata +#' object that describes the data object that is being added. The DataObject specified in the `mo` parameter will +#' also be added to the DataPackage, if it has not already been added. Then the `addData` function will add a relationship #' to the resource map that indicates that the metadata object describes the science object, using CiTO, the Citation Typing Ontology, -#' \code{documents} and \code{isDocumentedBy} relationships. -#' @param x The \code{"DataPackage"} to which the data object should be added. +#' `documents` and `isDocumentedBy` relationships. +#' @param x The `"DataPackage"` to which the data object should be added. #' @param do A D1Object to add to the DataPackage -#' @param mo A D1Object (containing metadata describing \code{"do"} ) to associate with the data object. +#' @param mo A D1Object (containing metadata describing `"do"` ) to associate with the data object. #' @export #' @examples \dontrun{ #' library(dataone) @@ -1647,7 +1646,7 @@ setGeneric("getMetadataMember", function(x, dp, ...) { #' @export #' @rdname getMetadataMember -#' @param as A value of type \code{"character"} that specifies the return value. Possible values are \code{"character"} (the default) or \code{"DataPackage"}. +#' @param as A value of type `"character"` that specifies the return value. Possible values are `"character"` (the default) or `"DataPackage"`. setMethod("getMetadataMember", signature("D1Client", "DataPackage"), function(x, dp, as="character", ...) { formats <- listFormats(x@cn) if(is.null(formats) || length(formats) == 0) { @@ -1699,7 +1698,7 @@ setMethod("getMetadataMember", signature("D1Client", "DataPackage"), function(x, #' @rdname downloadObject #' @aliases downloadObject #' @return A path where the ouput file is written to. -#' @seealso \code{\link[=D1Client-class]{D1Client}}{ class description.} +#' @seealso [`D1Client()`][D1Client-class] class description. #' @export #' @examples \dontrun{ #' library(dataone) diff --git a/R/D1Node.R b/R/D1Node.R index ed8aef0..37b4ca4 100644 --- a/R/D1Node.R +++ b/R/D1Node.R @@ -38,22 +38,21 @@ #' @slot APIversion A character string indicating version of the DataONE API for this node, e.g. "v2" #' @slot env A character string, either 'prod' if this node is in the production environment, otherwise 'test' #' @section Methods: -#' \itemize{ -#' \item{\code{\link{D1Node-initialize}{initialize}}}{: Initialize a D1Node} -#' \item{\code{\link{D1Node}}}{: Create a MNode object representing a DataONE Member Node repository.} -#' \item{\code{\link{archive}}}{: Change the state of an object so that it is hidden from searches.} -#' \item{\code{\link{describeObject}}}{: Get header information for a given pid.} -#' \item{\code{\link{getChecksum}}}{: Get the checksum for the data object associated with the specified pid.} -#' \item{\code{\link{getObject}}}{: Get the bytes associated with an object on a node.} -#' \item{\code{\link{getQueryEngineDescription}}}{: Query a node for the list of query engines available on the node.} -#' \item{\code{\link{getSystemMetadata}}}{: Get the metadata describing system properties associated with an object on the Node.} -#' \item{\code{\link{listObjects}}}{: Retrieve the list of objects that match the search parameters.} -#' \item{\code{\link{listQueryEngines}}}{: Query a node for the list of query engines available on the node.} -#' \item{\code{\link{ping}}}{: Test if a node is online and accepting DataONE requests.} -#' \item{\code{\link{encodeSolr}}}{: Encode the input for Solr Queries.} -#' \item{\code{\link{query}}}{: Search DataONE for data and metadata objects.} -#' \item{\code{\link{isAuthorized}}}{: Check if an action is authorized for the specified identifier.} -#' } +#' * [D1Node-initialize]: Initialize a D1Node +#' * [D1Node()]: Create a MNode object representing a DataONE Member Node repository +#' * [archive()]: Change the state of an object so that it is hidden from searches +#' * [describeObject()]: Get header information for a given pid +#' * [getChecksum()]: Get the checksum for the data object associated with the specified pid +#' * [getObject()]: Get the bytes associated with an object on a node +#' * [getQueryEngineDescription()]: Query a node for the list of query engines available on the node +#' * [getSystemMetadata()]: Get the metadata describing system properties associated with an object on the Node +#' * [listObjects()]: Retrieve the list of objects that match the search parameters +#' * [listQueryEngines()]: Query a node for the list of query engines available on the node +#' * [ping()]: Test if a node is online and accepting DataONE requests +#' * [encodeSolr()]: Encode the input for Solr Queries +#' * [query()]: Search DataONE for data and metadata objects +#' * [isAuthorized()]: Check if an action is authorized for the specified identifier +#' #' @import methods #' @importFrom utils URLencode #' @export @@ -83,7 +82,7 @@ setClass("D1Node", ######################### #' Create a D1Node object. -#' @param xml An XML object that describes the node to be initialized (see \link{listNodes}). +#' @param xml An XML object that describes the node to be initialized (see [listNodes]). #' @param ... (not yet used) #' @rdname D1Node #' @return the Node object representing the DataONE environment @@ -122,15 +121,16 @@ setMethod("D1Node", signature("XMLInternalElementNode"), function(xml) { #' Archive an object on a Member Node or Coordinating Node, which hides it from casual searches. #' @description This method provides the ability to archive a data or metadata object on the Member Node -#' provided in the \code{'mnode'} parameter. Archiving removes the object from DataONE search functions, +#' provided in the `'mnode'` parameter. Archiving removes the object from DataONE search functions, #' thereby making it more difficult to find without completely removing the object. Archive is intended #' for objects that should not be used by current researchers, but for which there is a desire to maintain #' a historical record, such as when journal articles might cite the object. Users can still obtain the #' contents of archived objects if they have the identifier, but will not discover it through searches. -#' @details This operation requires an X.509 certificate to be present in the default location of the file -#' system. This certificate provides authentication credentials from -#' CILogon \url{https://cilogon.org/?skin=DataONE}. See \code{\link{CertificateManager}} for details. -#' For DataONE Version 2.0, an authentication token can also be used for authentication. +#' @details Methods that perform write operations (such as createObject and updateObject) on the MN generally +#' require authentication. For MNs that have implemented the DataONE API version 2.0 and higher, these operations can utilize an +#' authentication token to provide credentials for write operations in DataONE. +#' The authentication token is obtained from DataONE (see your account profile on https://search.dataone.org). +#' See the `vignette("v01-dataone-overview")` for details. #' Also, administrator privilege is required to run archive() on a DataONE Coordinating Node. #' @param x The MNode or CNode instance on which the object will be created #' @param pid The identifier of the object to be created @@ -138,7 +138,7 @@ setMethod("D1Node", signature("XMLInternalElementNode"), function(xml) { #' @return The pid that was archived if successful, otherwise NULL #' @rdname archive #' @aliases archive -#' @seealso \code{\link[=D1Node-class]{D1Node}}{ class description.} +#' @seealso [`D1Node()`][D1Node-class] class description. #' @export #' @examples \dontrun{ #' library(dataone) @@ -203,7 +203,7 @@ setMethod("archive", signature("D1Node"), function(x, pid) { #' @rdname getObject #' @aliases getObject #' @return the bytes of the object -#' @seealso \code{\link{D1Node-class}{D1Node}}{ class description.} +#' @seealso \code{[D1Node-class]{D1Node}} class description. #' @export #' @examples \dontrun{ #' library(dataone) @@ -219,7 +219,7 @@ setGeneric("getObject", function(x, ...) { #' Get the checksum for the data object associated with the specified pid. #' @description A checksum is calculated for an object when it is uploaded to DataONE and -#' is submitted with the object's system metadata. The \code{'getChecksum'} method retrieves +#' is submitted with the object's system metadata. The `'getChecksum'` method retrieves #' the checksum from the specified coordinating node #' @rdname getChecksum #' @aliases getChecksum @@ -227,7 +227,7 @@ setGeneric("getObject", function(x, ...) { #' @param pid The identifier of the object #' @param ... (Not yet used) #' @return character the checksum value, with the checksum algorithm as the attribute "algorithm" -#' @seealso \code{\link{D1Node-class}{D1Node}}{ class description.} +#' @seealso \code{[D1Node-class]{D1Node}} class description. #' @export #' @examples \dontrun{ #' library(dataone) @@ -337,7 +337,7 @@ setGeneric("getSystemMetadata", function(x, ...) { #' Efficiently get systemmetadata for an object. #' @description This method provides a lighter weight mechanism than getSystemMetadata() for a client to #' determine basic properties of the referenced object. This operation requires read privileges for the -#' object specified by \code{'pid'}, as is granted with a DataONE authentication token or X.509 certificate. +#' object specified by `'pid'`, as is granted with a DataONE authentication token or X.509 certificate. #' @param x The MNode or CNode instance to send request to. #' @param pid Identifier for the object in question. May be either a PID or a SID. Transmitted as #' part of the URL path and must be escaped accordingly. @@ -345,7 +345,7 @@ setGeneric("getSystemMetadata", function(x, ...) { #' @rdname describeObject #' @aliases describeObject #' @return A list of header elements -#' @seealso \url{https://purl.dataone.org/architecture/apis/MN_APIs.html#MNRead.describe} +#' @seealso #' @examples \dontrun{ #' library(dataone) #' mn_uri <- "https://knb.ecoinformatics.org/knb/d1/mn/v1" @@ -373,8 +373,8 @@ setMethod("describeObject", signature("D1Node"), function(x, pid) { }) #' Retrieve the list of objects that match the search parameters -#' @details The list of objects that is returned is paged according to the \code{'start'} and -#' \code{'count'} values, so that large result sets can be returned over multiple calls. +#' @details The list of objects that is returned is paged according to the `'start'` and +#' `'count'` values, so that large result sets can be returned over multiple calls. #' @param x The Node instance from which the SystemMetadata will be downloaded #' @param ... (Not yet used.) #' @rdname listObjects @@ -398,16 +398,16 @@ setGeneric("listObjects", function(x, ...) { standardGeneric("listObjects") }) -#' @param fromDate Entries with a modified date greater than \code{'fromDate'} will be returned. +#' @param fromDate Entries with a modified date greater than `'fromDate'` will be returned. #' This value must be specified in ISO 8601 format, i.e. "YYYY-MM-DDTHH:MM:SS.mmm+00:00" -#' @param toDate Entries with a modified date less than \code{'toDate'} will be returned. +#' @param toDate Entries with a modified date less than `'toDate'` will be returned. #' This value must be specified in ISO 8601 format, i.e. "YYYY-MM-DDTHH:MM:SS.mmm+00:00" #' @param formatId The format to match, for example "eml://ecoinformatics.org/eml-2.1.1" #' @param replicaStatus A logical value that determines if replica (object not on it's origin node) should be returned. Default is TRUE. #' @param start An integer that specifies the first element of the result set that will be returned #' @param count An integer that specifies how many results will be returned #' @return list Objects that met the search criteria -#' @seealso \url{https://purl.dataone.org/architecture/apis/MN_APIs.html#MN_read.listObjects} +#' @seealso #' @import parsedate #' @export #' @rdname listObjects @@ -675,26 +675,26 @@ setMethod("encodeSolr", signature(x="character"), function(x, ...) { #' Search DataONE for data and metadata objects #' @description The DataONE search index is searched for data that matches the specified query parameters. -#' @details The \code{"query"} method sends a query to a DataONE search index that uses the Apache Solr search -#' engine \url{https://solr.apache.org/}. This same Solr search engine is the underlying mechanism used by the -#' DataONE online search tool available at \url{https://search.dataone.org/}. +#' @details The `"query"` method sends a query to a DataONE search index that uses the Apache Solr search +#' engine . This same Solr search engine is the underlying mechanism used by the +#' DataONE online search tool available at . #' -#' The \code{"solrQuery"} argument is used to specify search terms that data of interest must match. This parameter uses +#' The `"solrQuery"` argument is used to specify search terms that data of interest must match. This parameter uses #' Solr query terms, so some familiarity with Solr is helpful, however, fairly simple queries can be effective. This -#' argument can be created as either a single character string containing the Solr query, for example: \code{solrQuery = "q=id:doi*&rows=2&wt=json"}, -#' or as a list of key value pairs: \code{solrQuery = list(q = "id:doi*", rows = "2", wt = "json")}. These two queries produce the same result. +#' argument can be created as either a single character string containing the Solr query, for example: `solrQuery = "q=id:doi*&rows=2&wt=json"`, +#' or as a list of key value pairs: `solrQuery = list(q = "id:doi*", rows = "2", wt = "json")`. These two queries produce the same result. #' -#' As an alternative to specifying the Solr query terms using the \code{"solrquery"} argument, the \code{"searchTerms"} argument +#' As an alternative to specifying the Solr query terms using the `"solrquery"` argument, the `"searchTerms"` argument #' can be specified, which does not require any Solr syntax. This parameter is a list with query field / value pairs, i.e. -#' \code{searchTerms=list(abstract=kelp, attribute=biomass)}. -#' The query fields can be listed for a DataONE node using \code{\link{getQueryEngineDescription}}. -#' Either \code{"searchTerms"} or \code{"solrQuery"} must be specified. +#' `searchTerms=list(abstract=kelp, attribute=biomass)`. +#' The query fields can be listed for a DataONE node using [getQueryEngineDescription()]. +#' Either `"searchTerms"` or `"solrQuery"` must be specified. #' -#' The \code{"as"} argument is used to specify the query result to be returned as: "json", xml", "list", "data.frame". +#' The `"as"` argument is used to specify the query result to be returned as: "json", xml", "list", "data.frame". #' -#' The \code{"parsed"} argument, if specified as TRUE, causes the query result to be converted to appropriate R data types. -#' For example, if \code{ar = "xml"} and \code{parsed = TRUE}, then the query result is returned as an R XMLInternalDocument, or -#' If \code{'parsed = FALSE'} then a character variable with the XML string is returned. Specify \code{as = "list"} to have +#' The `"parsed"` argument, if specified as TRUE, causes the query result to be converted to appropriate R data types. +#' For example, if `ar = "xml"` and `parsed = TRUE`, then the query result is returned as an R XMLInternalDocument, or +#' If `'parsed = FALSE'` then a character variable with the XML string is returned. Specify `as = "list"` to have #' the result parsed to an R list, with each list element containing one Solr query result of the total result set. #' @param x The CNode or MNode instance to send the query to. #' @param ... (Not yet used.) @@ -741,11 +741,11 @@ setGeneric("query", function(x, ...) { #' @rdname query #' @param solrQuery The query search terms, either as a string or as list with named members. -#' @param encode A logical, if \code{TRUE} then the query is URL encoded. The default is \code{TRUE}. +#' @param encode A logical, if `TRUE` then the query is URL encoded. The default is `TRUE`. #' @param as The return type. Possible values: "json", "xml", "list" or "data.frame" with "list" as the default. #' @param parse A logical value. If TRUE, then the result is parsed and converted to appropriate R data types. If FALSE, character values are returned. -#' @param searchTerms A list of name / value pairs (an alternative to \code{solrQuery}). -#' @param encodeReserved A logical, if TRUE then reserved characters in the query are URL encoded (FALSE is default). See \code{URLencode} for details. +#' @param searchTerms A list of name / value pairs (an alternative to `solrQuery`). +#' @param encodeReserved A logical, if TRUE then reserved characters in the query are URL encoded (FALSE is default). See `URLencode` for details. #' @export setMethod("query", signature("D1Node"), function(x, solrQuery=as.character(NA), encode=TRUE, as="list", parse=TRUE, searchTerms=as.character(NA), @@ -887,7 +887,7 @@ setMethod("query", signature("D1Node"), function(x, solrQuery=as.character(NA), }) #' Parse Solr output into an R list -#' @description Solr output that is specified with a writer type of XML \code{'&wt="xml"'} +#' @description Solr output that is specified with a writer type of XML `'&wt="xml"'` #' @param doc The Solr result to parse, in XML format #' @param parse A logical value, if TRUE the result is parsed to appropriate R types. #' @param ... (Not yet used.) @@ -973,10 +973,10 @@ parseSolrField <- function(xNode, parse) { #' or series identifier (sid). #' @rdname isAuthorized #' @aliases isAuthorized -#' @param x The node to send the request to. This is either a \code{"CNode"} or \code{"MNode"} instance. +#' @param x The node to send the request to. This is either a `"CNode"` or `"MNode"` instance. #' @param ... (Not yet used) #' @return a logical, TRUE if the action is authorized, false if not. -#' @seealso \code{\link[=CNode-class]{CNode}}{ class description.} +#' @seealso [`CNode()`][CNode-class] class description. #' @export #' @examples \dontrun{ #' # Send an authorization check to the D1 production CN. diff --git a/R/D1Object.R b/R/D1Object.R index 6418df4..beb021f 100644 --- a/R/D1Object.R +++ b/R/D1Object.R @@ -27,17 +27,16 @@ #' @keywords classes #' @import datapack #' @importFrom utils read.csv +#' @seealso [dataone()] package description #' @section Methods: -#' \itemize{ -#' \item{\code{\link[dataone]{D1Object-initialize}}}{: Initialize a D1Object} -#' \item{\code{\link[dataone]{getData}}}{: Get the data content of a specified D1Object.} -#' \item{\code{\link[dataone]{getIdentifier}}}{: Get the identifier of the D1Object.} -#' \item{\code{\link[dataone]{getFormatId}}}{: Get the formatId of the D1Object} -#' \item{\code{\link[dataone]{setPublicAccess}}}{: Add a Rule to the AccessPolicy to make the object publicly readable.} -#' \item{\code{\link[dataone]{canRead}}}{: Test whether the provided subject can read an object.} -#' \item{\code{\link{asDataFrame}}}{: Return the D1Object as a data.frame.} -#' } -#' @seealso \code{\link{dataone}}{ package description.} +#' * `dataone::D1Object-initialize()`: Initialize a D1Object +#' * `dataone::getData()`: Get the data content of a specified D1Object +#' * `dataone::getIdentifier()`: Get the identifier of the D1Object +#' * `dataone::getFormatId()`: Get the formatId of the D1Object +#' * `dataone::setPublicAccess()`: Add a Rule to the AccessPolicy to make the object publicly readable +#' * `dataone::canRead()`: Test whether the provided subject can read an object +#' * `asDataFrame()`: Return the D1Object as a data.frame +#' #' @export setClass("D1Object", slots = c(dataObject="DataObject") ) @@ -45,13 +44,12 @@ setClass("D1Object", slots = c(dataObject="DataObject") ) ## D1Object constructors ######################## -# #' Create a D1Object instance. #' @param ... (additional arguments) #' @rdname D1Object #' @aliases D1Object #' @return the D1Object instance -#' @seealso \code{\link[=D1Object-class]{D1Object}}{ class description.} +#' @seealso [`D1Object()`][D1Object-class] class description. #' @export setGeneric("D1Object", function(...) { msg <- sprintf("'D1Object' is defunct.\nUse 'datapack:DataPackage' instead.\nSee help(\"Defunct\") and help(\"dataone-defunct\").") @@ -66,7 +64,7 @@ setGeneric("D1Object", function(...) { #' @param format The Object format. #' @param mnNodeId The DataONE node identifier associated with this object, i.e. "urn:node:KNB" #' @rdname D1Object-initialize -#' @seealso \code{\link[=D1Object-class]{D1Object}}{ class description.} +#' @seealso [`D1Object()`][D1Object-class] class description. #' @aliases D1Object-initialize setMethod("initialize", "D1Object", function(.Object, id, data, format, mnNodeId=as.character(NA)) { return(.Object) @@ -123,7 +121,7 @@ setMethod("getFormatId", signature("D1Object"), function(x) { #' the D1Object. #' @param x D1Object #' @return D1Object with modified access rules -#' @seealso \code{\link[=DataObject-class]{DataObject}}{ class description.} +#' @seealso [`DataObject()`][DataObject-class] class description. #' @rdname setPublicAccess #' @export setMethod("setPublicAccess", signature("D1Object"), function(x) { @@ -138,7 +136,7 @@ setMethod("setPublicAccess", signature("D1Object"), function(x) { #' Currently it only uses the AccessPolicy to determine who can read (and not the rightsHolder field, #' which always can read an object). If an object has been granted read access by the #' special "public" subject, then all subjects have read access. -#' @details The subject name used in both the AccessPolicy and in the \code{'subject'} +#' @details The subject name used in both the AccessPolicy and in the `'subject'` #' argument to this method is a string value, but is generally formatted as an X.509 #' name formatted according to RFC 2253. #' @param x D1Object diff --git a/R/MNode.R b/R/MNode.R index 9a66618..eb84fcd 100644 --- a/R/MNode.R +++ b/R/MNode.R @@ -29,10 +29,7 @@ #' require authentication. For MNs that have implemented the DataONE API version 2.0 and higher, these operations can utilize an #' authentication token to provide credentials for write operations in DataONE. #' The authentication token is obtained from DataONE (see your account profile on https://search.dataone.org). -#' See the \code{vignette("dataone-overview")} for details. -#' Alternatively, the version 1.0 approach of using an X.509 certificate in a default location of the file -#' system can also be used. This certificate provides authentication credentials from -#' CILogon \url{https://cilogon.org/?skin=DataONE}. +#' See the `vignette("v01-dataone-overview")` for details. #' @slot endpoint The url to access node services, which is the baseURL plus the version string #' @rdname MNode-class #' @aliases MNode-class @@ -41,17 +38,16 @@ #' @import methods #' @importFrom utils URLencode #' @section Methods: -#' \itemize{ -#' \item{\code{\link{MNode}}}{: Create a MNode object representing a DataONE Member Node repository.} -#' \item{\code{\link{createObject}}}{: Create an object on a Member Node.} -#' \item{\code{\link{getObject}}}{: Get the bytes associated with an object on the Member Node} -#' \item{\code{\link{getCapabilities}}}{: Get the node capabilities description, and store the information in the MNode.} -#' \item{\code{\link{generateIdentifier}}}{: Get a unique identifier that is generated by the Member Node repository and guaranteed to be unique.} -#' \item{\code{\link{getPackage}}}{: Download a data package from a member node.} -#' \item{\code{\link{updateObject}}}{: Update an object to a Member Node, by creating a new object that replaces an original.} -#' \item{\code{\link{updateSystemMetadata}}}{: Update the system metadata associated with an object.} -#' } -#' @seealso \code{\link{dataone}}{ package description.} +#' * [MNode()]: Create a MNode object representing a DataONE Member Node repository +#' * [createObject()]: Create an object on a Member Node +#' * [getObject()]: Get the bytes associated with an object on the Member Node +#' * [getCapabilities()]: Get the node capabilities description, and store the information in the MNode +#' * [generateIdentifier()]: Get a unique identifier that is generated by the Member Node repository and guaranteed to be unique +#' * [getPackage()]: Download a data package from a member node +#' * [updateObject()]: Update an object to a Member Node, by creating a new object that replaces an original +#' * [updateSystemMetadata()]: Update the system metadata associated with an object +#' +#' @seealso [dataone()] package description. #' @export #' @examples \dontrun{ #' library(dataone) @@ -88,14 +84,14 @@ setClass("MNode", slots = c(endpoint = "character"), contains="D1Node") #' Create a MNode object representing a DataONE Member Node repository. #' @description Construct an instance of MNode to provide mechanisms to access, create, and update data and #' metadata objects on the associated Member Node. -#' @details If the \code{'x'} is a string, it is treated as a URI and an attempt to find an associated -#' Member Node at that base URL is attempted. If \code{'x'} is a Node reference, then it is cast to a MNode +#' @details If the `'x'` is a string, it is treated as a URI and an attempt to find an associated +#' Member Node at that base URL is attempted. If `'x'` is a Node reference, then it is cast to a MNode #' instance. This typically is used from the getMNode() function from the CNode class, which is the preferred #' way to retrieve an instance of an MNode. #' @param x a URI representing a base URL (i.e. https://knb.ecoinformatics.org/knb/d1/mn/v2); or a reference to a dataone::Node instance #' @rdname MNode #' @return the MNode object- -#' @seealso \code{\link[=MNode-class]{MNode}}{ class description.} +#' @seealso [`MNode()`][MNode-class] class description. #' @export #' @examples \dontrun{ #' mn <- MNode("https://knb.ecoinformatics.org/knb/d1/mn/v2") @@ -186,7 +182,7 @@ setMethod("MNode", signature("D1Node"), function(x) { #' @param x The node identifier with which this node is registered in DataONE #' @param ... (Not yet used.) #' @return an XMLInternalDocument object representing the DataONE environment -#' @seealso \url{https://purl.dataone.org/architecture/apis/MN_APIs.html#MN_core.getCapabilities} +#' @seealso #' @import XML #' @import httr #' @export @@ -317,21 +313,18 @@ setMethod("getChecksum", signature("MNode"), function(x, pid, checksumAlgorithm= #' Create an object on a Member Node. #' @description This method provides the ability to upload a data or metadata object to the Member Node -#' provided in the \code{'mnode'} parameter. +#' provided in the `'mnode'` parameter. #' @details In the version 2.0 library and higher, this operation can utilize an #' 'dataone_token' option to provide credentials for write operations in DataONE. #' The authentication token is obtained from DataONE (see your profile on https://search.dataone.org). -#' See the \code{vignette("dataone-overview")} for details. -#' Alternatively, the version 1.0 approach of using an X.509 certificate in a default location of the file -#' system can also be used. This certificate provides authentication credentials from -#' CILogon \url{https://cilogon.org/?skin=DataONE}. See \code{vignette("dataone-overview")} for details. +#' See the `vignette("v01-dataone-overview")` for details. #' @rdname createObject #' @aliases createObject #' @param x The MNode instance on which the object will be created #' @param pid The identifier of the object to be created #' @param ... (Not yet used.) -#' @return a \code{character} containing the identifier that was created. -#' @seealso \url{https://purl.dataone.org/architecture/apis/MN_APIs.html#MNStorage.create} +#' @return a `character` containing the identifier that was created. +#' @seealso #' @import datapack #' @export #' @examples \dontrun{ @@ -368,7 +361,7 @@ setGeneric("createObject", function(x, ...) { #' @rdname createObject #' @param file the absolute file location of the object to be uploaded #' @param sysmeta a SystemMetadata instance describing properties of the object -#' @param dataobj a \code{raw} object to use for the upload, instead of the contents of the \code{file} argument. +#' @param dataobj a `raw` object to use for the upload, instead of the contents of the `file` argument. setMethod("createObject", signature("MNode"), function(x, pid, file=as.character(NA), sysmeta, dataobj=NULL, ...) { stopifnot(is.character(pid)) # TODO: need to properly URL-escape the PID @@ -441,24 +434,21 @@ setMethod("createObject", signature("MNode"), function(x, pid, file=as.character #' @rdname updateObject #' @aliases updateObject #' @description This method provides the ability to update a data or metadata object to the Member Node -#' provided in the \code{'x'} parameter. In DataONE, both the original object and the new object are +#' provided in the `'x'` parameter. In DataONE, both the original object and the new object are #' maintained, each with its own persistent identifier, and the 'obsoletes' field in the SystemMetadata is #' used to reflect the fact that the new object replaces the old. Both objects remain accessible. #' @details In the version 2.0 library and higher, this operation can utilize an #' 'dataone_token' option to provide credentials for write operations in DataONE. #' The authentication token is obtained from DataONE (see your profile on https://search.dataone.org). -#' See the \code{vignette("dataone-overview")} for details. -#' Alternatively, the version 1.0 approach of using an X.509 certificate in a default location of the file -#' system can also be used. This certificate provides authentication credentials from -#' CILogon \url{https://cilogon.org/?skin=DataONE}. See \code{vignette("dataone-overview")} for details. +#' See the `vignette("v01-dataone-overview")` for details. #' @param x The MNode instance on which the object will be created #' @param pid The identifier of the object to be updated #' @param ... (Not yet used.) -#' @return A \code{character} containing the identifier if successful. -#' @seealso \url{https://purl.dataone.org/architecture/apis/MN_APIs.html#MNStorage.update} +#' @return A `character` containing the identifier if successful. +#' @seealso #' @import datapack #' @export -#' @note Please see the vignette *upload-data* for an example: \code{vignette("upload-data")} +#' @note Please see the vignette *v05-upload-data* for an example: `vignette("v05-upload-data")` setGeneric("updateObject", function(x, ...) { standardGeneric("updateObject") }) @@ -466,7 +456,7 @@ setGeneric("updateObject", function(x, ...) { #' @param file the absolute file location of the object to be uploaded #' @param newpid The identifier of the new object to be created #' @param sysmeta a SystemMetadata instance describing properties of the object -#' @param dataobj a \code{raw} object to use for the upload, instead of the contents of the \code{file} argument. +#' @param dataobj a `raw` object to use for the upload, instead of the contents of the `file` argument. #' @rdname updateObject setMethod("updateObject", signature("MNode"), function(x, pid, file=as.character(NA), newpid, sysmeta, dataobj=NULL) { stopifnot(is.character(pid)) @@ -540,17 +530,14 @@ setMethod("updateObject", signature("MNode"), function(x, pid, file=as.character #' @details In the version 2.0 library and higher, this operation can utilize an #' 'dataone_token' option to provide credentials for write operations in DataONE. #' The authentication token is obtained from DataONE (see your profile on https://search.dataone.org). -#' See the \code{vignette("dataone-overview")} for details. -#' Alternatively, the version 1.0 approach of using an X.509 certificate in a default location of the file -#' system can also be used. This certificate provides authentication credentials from -#' CILogon \url{https://cilogon.org/?skin=DataONE}. See \code{vignette("dataone-overview")} for details. +#' See the `vignette("v01-dataone-overview")` for details. #' @param x The MNode instance from which the SystemMetadata will be downloaded #' @param ... (Not yet used.) #' @return A logical value, TRUE if the operation was successful, FALSE if there was an error. -#' @seealso \url{https://purl.dataone.org/architecture/apis/MN_APIs.html#MNStorage.updateSystemMetadata} +#' @seealso #' @import datapack #' @export -#' @note Please see the vignette *upload-data* for an example: \code{vignette("upload-data")} +#' @note Please see the vignette *v05-upload-data* for an example: `vignette("v05-upload-data")` setGeneric("updateSystemMetadata", function(x, ...) { standardGeneric("updateSystemMetadata") }) @@ -601,16 +588,13 @@ setMethod("updateSystemMetadata", signature("MNode"), function(x, pid, sysmeta) #' @details In the version 2.0 library and higher, this operation can utilize an #' 'dataone_token' option to provide credentials for write operations in DataONE. #' The authentication token is obtained from DataONE (see your profile on https://search.dataone.org). -#' See the \code{vignette("dataone-overview")} for details. -#' Alternatively, the version 1.0 approach of using an X.509 certificate in a default location of the file -#' system can also be used. This certificate provides authentication credentials from -#' CILogon \url{https://cilogon.org/?skin=DataONE}. See \code{vignette("dataone-overview")} for details. +#' See the `vignette("v01-dataone-overview")` for details. #' @param x The MNode instance on which the object will be created #' @param ... (Not yet used.) #' @rdname generateIdentifier #' @aliases enerateIdentifier #' @return the character string of the generated unique identifier -#' @seealso \url{https://purl.dataone.org/architecture/apis/MN_APIs.html#MNStorage.generateIdentifier} +#' @seealso #' @export #' @examples #' \dontrun{ @@ -655,13 +639,13 @@ setMethod("generateIdentifier", signature("MNode"), function(x, scheme="UUID", f #' Download a data package from a member node. #' @description Given a valid identifier, download a file containing all of the package #' members of the corresponding DataONE data package. -#' @details The default data package file format is a Bagit file (\url{https://tools.ietf.org/html/draft-kunze-bagit-09}). +#' @details The default data package file format is a Bagit file (). #' The downloaded package file is compressed using the ZIP format and will be located in an R session temporary #' file. Other packaging formats can be requested if they have been implemented by the requested member node. #' @param x A MNode instance representing a DataONE Member Node repository. #' @param ... (not yet used) #' @return The location of the package file downloaded from the member node. -#' @seealso \code{\link[=MNode-class]{MNode}}{ class description.} +#' @seealso [`MNode()`][MNode-class] class description. #' @import uuid #' @export #' @examples \dontrun{ diff --git a/R/auth_request.R b/R/auth_request.R index 5ea676d..83932b3 100644 --- a/R/auth_request.R +++ b/R/auth_request.R @@ -202,7 +202,7 @@ auth_put_post_delete <- function(method, url, encode="multipart", body=NULL, nod ) } } else { - stop("Unable to perform the operation as unauthenticated (public) user. See vignette(\"dataone-overview\") for more information") + stop("Unable to perform the operation as unauthenticated (public) user. See vignette(\"v01-dataone-overview\") for more information") } } diff --git a/R/dataone-defunct.R b/R/dataone-defunct.R index 51d17f0..bd339d6 100644 --- a/R/dataone-defunct.R +++ b/R/dataone-defunct.R @@ -4,47 +4,37 @@ #' @name dataone-defunct #' @keywords internal #' @section These S4 methods are defunct: -#' \itemize{ -#' \item{\code{\link{D1Object}}}{: A representation of a DataObject} -#' \itemize{ -#' \item{\code{\link{D1Object-initialize}}}{: Initialize a D1Object} -#' \item{\code{\link{getData}}}{: Get the data content of a specified D1Object.} -#' \item{\code{\link{getIdentifier}}}{: Get the identifier of the D1Object.} -#' \item{\code{\link{getFormatId}}}{: Get the formatId of the D1Object} -#' \item{\code{\link{setPublicAccess}}}{: Add a Rule to the AccessPolicy to make the object publicly readable.} -#' \item{\code{\link{canRead}}}{: Test whether the provided subject can read an object.} -#' \item{\code{\link{asDataFrame}}}{: Return the D1Object as a data.frame.} -#' \item{\code{\link{setObsoletedBy}}}{: Set a pid as being obsoleted by another pid.} -#' } -#' \item{\code{\link{D1Client}}}{: The DataONE client class used to download, update and search for data in the DataONE network} -#' \itemize{ -#' \item{\code{\link{d1SolrQuery}}}{: A method to query the DataONE solr endpoint of the Coordinating Node.} -#' \item{\code{\link{d1IdentifierSearch}}}{: Query the DataONE Solr endpoint of the Coordinating Node.} -#' \item{\code{\link{createDataPackage}}}{: Create a DataPackage on a DataONE Member Node} -#' \item{\code{\link{getMN}}}{: Get a member node client based on its node identifier.} -#' \item{\code{\link{convert.csv}}}{: Convert a DataFrame to Standard CSV.} -#' \item{\code{\link{addData}}}{: Add a D1Object containing a data object to a DataPackage} -#' \item{\code{\link{createD1Object}}}{: Create the Object in the DataONE System} -#' \item{\code{\link{getD1Object}}}{: Download a data object from the DataONE Federation.} -#' } -#' \item{\code{EMLParser}}{: A representation of a DataObject} -#' \itemize{ -#' \item{\code{\link{documented.entityNames}}}{: The entity names associated with each table are returned.} -#' \item{\code{\link{documented.d1Identifiers}}}{: Get the DataONE identifier associated with each table.} -#' \item{\code{\link{documented.sizes}}}{: Get the table size.} -#' } -#' \item{\code{AbstractTableDescriber}}{: Base Class for Specific Metadata Parsers} -#' \itemize{ -#' \item{\code{\link{data.formatFamily}}}{: Get the table format family.} -#' \item{\code{\link{data.tableFieldDelimiter}}}{: Get the table field delimiter.} -#' \item{\code{\link{data.tableQuoteCharacter}}}{: Get the table quote character.} -#' \item{\code{\link{data.characterEncoding}}}{: The character encoding used, for example "UTF-8"} -#' \item{\code{\link{data.tableAttributeOrientation}}}{: Which way to the attribute headers run? Most data has a header row} -#' \item{\code{\link{data.tableSkipLinesHeader}}}{: The specified number of lines are skipped.} -#' \item{\code{\link{data.tableMissingValueCodes}}}{: the missing value codes are defined in the metadata document for} -#' \item{\code{\link{data.tableAttributeNames}}}{: The attribute names are defined in the metadata document for} -#' \item{\code{\link{data.tableAttributeTypes}}}{: The attributes' data types are defined in the metadata document for} -#' \item{\code{\link{data.tableAttributeStorageTypes}}}{: The attributes' data storage types are defined in the metadata document for} -#' } -#' } +#' * [D1Object()]: A representation of a DataObject +#' * `D1Object-initialize()`: Initialize a D1Object +#' * `getData()`: Get the data content of a specified D1Object +#' * `getIdentifier()`: Get the identifier of the D1Object +#' * `getFormatId()`: Get the formatId of the D1Object +#' * `setPublicAccess()`: Add a Rule to the AccessPolicy to make the object publicly readable +#' * `canRead()`: Test whether the provided subject can read an object +#' * `asDataFrame()`: Return the D1Object as a data.frame +#' * `setObsoletedBy()`: Set a pid as being obsoleted by another pid +#' * [D1Client()]: The DataONE client class used to download, update and search for data in the DataONE network +#' * [d1SolrQuery()]: A method to query the DataONE solr endpoint of the Coordinating Node +#' * [d1IdentifierSearch()]: Query the DataONE Solr endpoint of the Coordinating Node +#' * [createDataPackage()]: Create a DataPackage on a DataONE Member Node +#' * [getMN()]: Get a member node client based on its node identifier +#' * [convert.csv()]: Convert a DataFrame to Standard CSV +#' * `addData()`: Add a D1Object containing a data object to a DataPackage +#' * [createD1Object()]: Create the Object in the DataONE System +#' * [getD1Object()]: Download a data object from the DataONE Federation +#' * `EMLParser`: A representation of a DataObject +#' * [documented.entityNames()]: The entity names associated with each table are returned +#' * [documented.d1Identifiers()]: Get the DataONE identifier associated with each table +#' * [documented.sizes()]: Get the table size +#' * `AbstractTableDescriber`: Base Class for Specific Metadata Parsers +#' * [data.formatFamily()]: Get the table format family +#' * [data.tableFieldDelimiter()]: Get the table field delimiter +#' * [data.tableQuoteCharacter()]: Get the table quote character +#' * [data.characterEncoding()]: The character encoding used, for example "UTF-8" +#' * [data.tableAttributeOrientation()]: Which way to the attribute headers run? Most data has a header row +#' * [data.tableSkipLinesHeader()]: The specified number of lines are skipped +#' * [data.tableMissingValueCodes()]: the missing value codes are defined in the metadata document for +#' * [data.tableAttributeNames()]: The attribute names are defined in the metadata document for +#' * [data.tableAttributeTypes()]: The attributes' data types are defined in the metadata document for +#' * [data.tableAttributeStorageTypes()]: The attributes' data storage types are defined in the metadata document for NULL diff --git a/R/dataone-deprecated.R b/R/dataone-deprecated.R index 46cb452..fdb5ed9 100644 --- a/R/dataone-deprecated.R +++ b/R/dataone-deprecated.R @@ -4,15 +4,14 @@ #' @name dataone-deprecated #' @keywords internal #' @section These S4 methods are deprecated: -#' \itemize{ -#' \item{\code{\link{setObsoletedBy}}}{: Set a pid as being obsoleted by another pid.} -#' \item{\code{\link{CertificateManager}}}{: Create a CertificateManager object.} -#' \item{\code{\link{getCertLocation}}}{: Get the file path on disk of the client certificate file.} -#' \item{\code{\link{showClientSubject}}}{: Get DataONE Identity as Stored in the CILogon Certificate.} -#' \item{\code{\link{isCertExpired}}}{: Determine if an X.509 certificate has expired.} -#' \item{\code{\link{getCertExpires}}}{: Show the date and time when an X.509 certificate expires.} -#' \item{\code{\link{downloadCert}}}{: Open the CILogon Certificate download page in the default browser.} -#' \item{\code{\link{obscureCert}}}{: Obscure the CILogon Client Certificate.} -#' \item{\code{\link{restoreCert}}}{: Restore the CILogon client certificate by renaming it to its original location} -#' } -NULL \ No newline at end of file +#' * [setObsoletedBy()]: Set a pid as being obsoleted by another pid +#' * [CertificateManager()]: Create a CertificateManager object +#' * [getCertLocation()]: Get the file path on disk of the client certificate file +#' * [showClientSubject()]: Get DataONE Identity as Stored in the CILogon Certificate +#' * [isCertExpired()]: Determine if an X.509 certificate has expired +#' * [getCertExpires()]: Show the date and time when an X.509 certificate expires +#' * [downloadCert()]: Open the CILogon Certificate download page in the default browser +#' * [obscureCert()]: Obscure the CILogon Client Certificate +#' * [restoreCert()]: Restore the CILogon client certificate by renaming it to its original location +#' +NULL diff --git a/R/dataone-package.R b/R/dataone-package.R index ccca9e7..fe6a149 100644 --- a/R/dataone-package.R +++ b/R/dataone-package.R @@ -16,24 +16,25 @@ # limitations under the License. # #' Search, download and upload data to the DataONE network. -#' @description The R package \emph{dataone} provides read/write access to data and metadata from the -#' \href{https://www.dataone.org/}{DataONE} network of +#' @description The R package *dataone* provides read/write access to data and metadata from the +#' [DataONE](https://www.dataone.org/) network of #' Member Node data repositories. Member Nodes in DataONE are independent data repositories that have adopted the DataONE #' services for interoperability, making each of the repositories accessible to client tools such as the DataONE R Client #' using a standard interface. The DataONE R Client can be used to access data files and to write new data and metadata files #' to nodes in the DataONE network. -#' @docType package #' @rdname dataone #' @aliases dataone #' @name dataone #' @author Matthew B. Jones (NCEAS) and Peter Slaughter (NCEAS) #' @section Classes: -#' \itemize{ -#' \item{\code{\link[=AuthenticationManager-class]{AuthenticationManager}}}{: AuthenticationManager provides methods to validate DataONE authentication.} -#' \item{\code{\link[=CNode-class]{CNode}}}{: A CNode represents a DataONE Coordinating Node and can be used to access its services.} -#' \item{\code{\link[=D1Client-class]{D1Client}}}{: The D1Client class contains methods that perform high level dataone tasks.} -#' \item{\code{\link[=D1Node-class]{D1Node}}}{: A base class for CNode and MNode.} -#' \item{\code{\link[=MNode-class]{MNode}}}{: MNode provides functions interacting with the a DataONE Member Node repository.} -#' } -#' @seealso A description of the \emph{dataone} R package is available with the command: \code{'vignette("dataone-overview")'}. -NULL \ No newline at end of file +#' * [`AuthenticationManager()`][AuthenticationManager-class]: AuthenticationManager provides methods to validate DataONE authentication +#' * [`CNode()`][CNode-class]: A CNode represents a DataONE Coordinating Node and can be used to access its services +#' * [`D1Client()`][D1Client-class]: The D1Client class contains methods that perform high level dataone tasks +#' * [`D1Node()`][D1Node-class]: A base class for CNode and MNode +#' * [`MNode()`][MNode-class]: MNode provides functions interacting with the a DataONE Member Node repository +#' +#' @seealso A description of the *dataone* R package is available with the command: `'vignette("v01-dataone-overview")'`. +#' @keywords internal +"_PACKAGE" + +NULL diff --git a/cran-comments.md b/cran-comments.md index b303188..e8c1c86 100644 --- a/cran-comments.md +++ b/cran-comments.md @@ -1,6 +1,7 @@ ## Test environments - * macOS 12.2: R 4.1.0 + * macOS 13.7.6: R 4.5.1 + * Ubuntu 18.04 R 4.1.3 * Windows (via win-builder): x86_64-w64-mingw32 (64-bit) R Under development (unstable) (2022-06-08 r82470 ucrt) * Windows (via win-builder): x86_64-w64-mingw32 (64-bit) R 4.2.0 (2022-04-22 ucrt) diff --git a/man/AbstractTableDescriber-class.Rd b/man/AbstractTableDescriber-class.Rd index 6b2d330..3b5ae69 100644 --- a/man/AbstractTableDescriber-class.Rd +++ b/man/AbstractTableDescriber-class.Rd @@ -11,26 +11,22 @@ provide read.csv with parsing instructions. \details{ This class defines the generic methods metadata parser classes need to implement to allow proper parsing of tabular data objects. Subclasses should: -1. provide method implementations for all generics -2. register the class to the tableDescriber.registry for the formats they claim to parse. -3. provide a 'constructor' method that accepts a D1Object as the first argument - the +\enumerate{ +\item provide method implementations for all generics +\item register the class to the tableDescriber.registry for the formats they claim to parse. +\item provide a 'constructor' method that accepts a D1Object as the first argument - the D1Object will be the metadata object to be parsed +} For example, the EMLParser registers itself as a handler for eml v2.0.0 - v2.1.1 with the following. -\code{ -if (!exists("tableDescriber.registry")) tableDescriber.registry <- list() -tableDescriber.registry[[ "eml://ecoinformatics.org/eml-2.0.0" ]] <- "EMLParser" -tableDescriber.registry[[ "eml://ecoinformatics.org/eml-2.0.1" ]] <- "EMLParser" -tableDescriber.registry[[ "eml://ecoinformatics.org/eml-2.1.0" ]] <- "EMLParser" -tableDescriber.registry[[ "eml://ecoinformatics.org/eml-2.1.1" ]] <- "EMLParser" -} +\verb{if (!exists("tableDescriber.registry")) tableDescriber.registry <- list() tableDescriber.registry[[ "eml://ecoinformatics.org/eml-2.0.0" ]] <- "EMLParser" tableDescriber.registry[[ "eml://ecoinformatics.org/eml-2.0.1" ]] <- "EMLParser" tableDescriber.registry[[ "eml://ecoinformatics.org/eml-2.1.0" ]] <- "EMLParser" tableDescriber.registry[[ "eml://ecoinformatics.org/eml-2.1.1" ]] <- "EMLParser"} -Note that the key in the list is the DataONE formatIdentifier that can be +Note that the key in the list is the DataONE formatIdentifier that can be found at "https://cn.dataone.org/cn/v2/formats". -Subclass implementers should conform their methods to the behavior defined +Subclass implementers should conform their methods to the behavior defined in the generic. } \author{ diff --git a/man/AuthenticationManager-class.Rd b/man/AuthenticationManager-class.Rd index af13c24..2d7e7db 100644 --- a/man/AuthenticationManager-class.Rd +++ b/man/AuthenticationManager-class.Rd @@ -9,27 +9,24 @@ AuthenticationManager provides mechanisms to validate DataONE authentication, when either a DataONE authentication token or X.509 Certificate is used. } \details{ -Understanding how your identity is managed is important for working with DataONE, especially to +Understanding how your identity is managed is important for working with DataONE, especially to avoid unexpected results. For example, depending your authorization status, searches may -return only public records, or the full set of public and private records. Object and package -retrievals might fail if some or all of the objects being retrieved are private. Creating or -updating objects on DataONE nodes and reserving identifiers might fail if your +return only public records, or the full set of public and private records. Object and package +retrievals might fail if some or all of the objects being retrieved are private. Creating or +updating objects on DataONE nodes and reserving identifiers might fail if your authorization credentials are missing or expired. -DataONE version 1.0 identifies you using CILogon-provided x509 certificates. DataONE has -partnered with CILogon to provide a widely-accessible certificate issuing mechanism -that allows DataONE users to use existing trusted institutional and public accounts. - -DataONE version 2.0 provides an addition authentication mechanism known as -authentication tokens. For information about tokens and instructions for generating +DataONE version 2.0 provides an authentication mechanism known using JWT +Bearer tokens. For information about tokens and instructions for generating a token for use with the dataone R package, view the overview document by -entering the command: \code{'vignette("dataone-overview")'}. DataONE authentication -tokens can be obtained by signing in to your DataONE account at https://search.dataone.org. +entering the command: \code{'vignette("v01-dataone-overview")'}. DataONE authentication +tokens can be obtained by signing in to your DataONE account at https://search.dataone.org +and copying the token from your profile settings. -CILogon recognizes many identity providers, including many universities as well as -Google, so most times users new to DataONE can get certificates using one -of their existing accounts. For more information about the CILogon service, see -\url{https://cilogon.org/?skin=DataONE} . +Additionally, DataONE API version 1.0 identifies you using CILogon-provided x509 certificates. +DataONE partnered with CILogon to provide a widely-accessible certificate issuing mechanism +that allows DataONE users to use existing trusted institutional and public accounts, but this method +is deprecated and generally users should use JWT Bearer tokens as described above. } \section{Slots}{ @@ -40,23 +37,22 @@ of their existing accounts. For more information about the CILogon service, see \section{Methods}{ \itemize{ - \item{\code{\link{AuthenticationManager}}}{: Create an AuthenticationManager object.} - \item{\code{\link{isAuthValid}}}{: Verify authentication for a member node.} - \item{\code{\link{getToken}}}{: Get the value of the DataONE Authentication Token, if one exists.} - \item{\code{\link{getCert}}}{: Get the DataONE X.509 Certificate location.} - \item{\code{\link{getAuthMethod}}}{: Get the current valid authentication mechanism.} - \item{\code{\link{getAuthSubject}}}{: Get the authentication subject.} - \item{\code{\link{getAuthExpires}}}{: Get the expiration date of the current authentication method.} - \item{\code{\link{isAuthExpired}}}{: Check if the currently valid authentication method has reached the expiration time.} - \item{\code{\link{obscureAuth}}}{: Temporarily disable DataONE authentication.} - \item{\code{\link{restoreAuth}}}{: Restore authentication (after being disabled with \code{obscureAuth}).} - \item{\code{\link{showAuth}}}{: Display all authentication information.} - \item{\code{\link{getTokenInfo}}}{: Display all authentication token information.} - \item{\code{\link{getCertInfo}}}{: Display all X.509 certificate information.} - +\item \code{\link[=AuthenticationManager]{AuthenticationManager()}}: Create an AuthenticationManager object +\item \code{\link[=isAuthValid]{isAuthValid()}}: Verify authentication for a member node +\item \code{\link[=getToken]{getToken()}}: Get the value of the DataONE Authentication Token, if one exists +\item \code{\link[=getCert]{getCert()}}: Get the DataONE X.509 Certificate location +\item \code{\link[=getAuthMethod]{getAuthMethod()}}: Get the current valid authentication mechanism +\item \code{\link[=getAuthSubject]{getAuthSubject()}}: Get the authentication subject +\item \code{\link[=getAuthExpires]{getAuthExpires()}}: Get the expiration date of the current authentication method +\item \code{\link[=isAuthExpired]{isAuthExpired()}}: Check if the currently valid authentication method has reached the expiration time +\item \code{\link[=obscureAuth]{obscureAuth()}}: Temporarily disable DataONE authentication +\item \code{\link[=restoreAuth]{restoreAuth()}}: Restore authentication (after being disabled with \code{obscureAuth}) +\item \code{\link[=showAuth]{showAuth()}}: Display all authentication information +\item \code{\link[=getTokenInfo]{getTokenInfo()}}: Display all authentication token information +\item \code{\link[=getCertInfo]{getCertInfo()}}: Display all X.509 certificate information } } \seealso{ -\code{\link{dataone}}{ package description.} +\code{\link[=dataone]{dataone()}} package description. } diff --git a/man/AuthenticationManager.Rd b/man/AuthenticationManager.Rd index 6b63b8c..33f056c 100644 --- a/man/AuthenticationManager.Rd +++ b/man/AuthenticationManager.Rd @@ -16,6 +16,6 @@ AuthenticationManager(...) the AuthenticationManager object } \description{ -Construct an instance of AuthenticationManager to provide mechanisms to load, verify, and +Construct an instance of AuthenticationManager to provide mechanisms to load, verify, and display DataONE authentication information. } diff --git a/man/CNode-class.Rd b/man/CNode-class.Rd index 2c0bf33..83a2f43 100644 --- a/man/CNode-class.Rd +++ b/man/CNode-class.Rd @@ -20,24 +20,24 @@ The CNode class provides methods that interact with a DataONE Coordinating Node. \section{Methods}{ \itemize{ - \item{\code{\link{CNode}}}{: Construct a CNode object.} - \item{\code{\link{listFormats}}}{: List all object formats registered in DataONE.} - \item{\code{\link{getFormat}}}{: Get information for a single DataONE object format } - \item{\code{\link{getChecksum}}}{: Get the checksum for the data object associated with the specified pid.} - \item{\code{\link{listNodes}}}{: Get the list of nodes associated with a CN.} - \item{\code{\link{reserveIdentifier}}}{: Reserve a identifier that is unique in the DataONE network.} - \item{\code{\link{hasReservation}}}{: Checks to determine if the supplied subject is the owner of the reservation of id.} - \item{\code{\link{setObsoletedBy}}}{: Set a pid as being obsoleted by another pid} - \item{\code{\link{getObject}}}{: Get the bytes associated with an object on this Coordinating Node.} - \item{\code{\link{getSystemMetadata}}}{: Get the bytes associated with an object on this Coordinating Node.} - \item{\code{\link{describeObject}}}{: Get a list of coordinating nodes holding a given pid.} - \item{\code{\link{resolve}}}{: Get a list of coordinating nodes holding a given pid.} - \item{\code{\link{getMNode}}}{: Get a reference to a node based on its identifier.} - \item{\code{\link{echoCredentials}}}{: Echo the credentials used to make the call.} - \item{\code{\link{isAuthorized}}}{: Check if an action is authorized for the specified identifier.} +\item \code{\link[=CNode]{CNode()}}: Construct a CNode object +\item \code{\link[=listFormats]{listFormats()}}: List all object formats registered in DataONE +\item \code{\link[=getFormat]{getFormat()}}: Get information for a single DataONE object format +\item \code{\link[=getChecksum]{getChecksum()}}: Get the checksum for the data object associated with the specified pid +\item \code{\link[=listNodes]{listNodes()}}: Get the list of nodes associated with a CN +\item \code{\link[=reserveIdentifier]{reserveIdentifier()}}: Reserve a identifier that is unique in the DataONE network +\item \code{\link[=hasReservation]{hasReservation()}}: Checks to determine if the supplied subject is the owner of the reservation of id +\item \code{\link[=setObsoletedBy]{setObsoletedBy()}}: Set a pid as being obsoleted by another pid +\item \code{\link[=getObject]{getObject()}}: Get the bytes associated with an object on this Coordinating Node +\item \code{\link[=getSystemMetadata]{getSystemMetadata()}}: Get the bytes associated with an object on this Coordinating Node +\item \code{\link[=describeObject]{describeObject()}}: Get a list of coordinating nodes holding a given pid +\item \code{\link[=resolve]{resolve()}}: Get a list of coordinating nodes holding a given pid +\item \code{\link[=getMNode]{getMNode()}}: Get a reference to a node based on its identifier +\item \code{\link[=echoCredentials]{echoCredentials()}}: Echo the credentials used to make the call +\item \code{\link[=isAuthorized]{isAuthorized()}}: Check if an action is authorized for the specified identifier } } \seealso{ -\code{\link{dataone}}{ package description.} +\code{\link[=dataone]{dataone()}} package description. } diff --git a/man/CNode.Rd b/man/CNode.Rd index 8e8f124..6d7c714 100644 --- a/man/CNode.Rd +++ b/man/CNode.Rd @@ -24,8 +24,8 @@ the CNode object representing the DataONE environment Create a CNode object. } \details{ -For an explanation of DataONE Coordinating Nodes, see the -section \emph{"DataONE Environments"} in the overview vignette by entering the R command: \code{vignette("dataone-overview")}. +For an explanation of DataONE Coordinating Nodes, see the +section \emph{"DataONE Environments"} in the overview vignette by entering the R command: \code{vignette("v01-dataone-overview")}. } \examples{ \dontrun{ @@ -33,5 +33,5 @@ cn <- CNode("PROD") } } \seealso{ -\code{\link[=CNode-class]{CNode}}{ class description.} +\code{\link[=CNode-class]{CNode()}} class description. } diff --git a/man/CertificateManager-class.Rd b/man/CertificateManager-class.Rd index 3306f1b..9fda992 100644 --- a/man/CertificateManager-class.Rd +++ b/man/CertificateManager-class.Rd @@ -5,36 +5,36 @@ \alias{CertificateManager-class} \title{CertficateManager provides mechanisms to obtain, load, verify, and display X509 certificates.} \description{ -CertficateManager provides management functions for X.509 certificates that are -used to authenticate connections to DataONE nodes over SSL. The X.509 certificates are issued -by a recognized Certificate Authority, typically CILogon, and include fields that provide -information about the authenticated party, including the distinguished name of the subject, the -dates of validity of the certificate, and other information needed for authorization decisions. -Certificate validity is determined by examining the validity of the certificate signatures for -each certificate in a chain leading to a trusted root certificate. Within DataONE, the current +CertficateManager provides management functions for X.509 certificates that are +used to authenticate connections to DataONE nodes over SSL. The X.509 certificates are issued +by a recognized Certificate Authority, typically CILogon, and include fields that provide +information about the authenticated party, including the distinguished name of the subject, the +dates of validity of the certificate, and other information needed for authorization decisions. +Certificate validity is determined by examining the validity of the certificate signatures for +each certificate in a chain leading to a trusted root certificate. Within DataONE, the current trusted root certificate authorities are CILogon and DataONE itself. } \details{ -Understanding how your identity is managed is important for working with DataONE, especially to -avoid unexpected results. For example, depending your authorization status, searches may or may -return only public records, or the full set of public and private records. Object and package -retrievals might fail if some or all of the objects being retrieved are private. Creating or -updating objects on DataONE nodes and reserving identifiers reservations might fail if your +Understanding how your identity is managed is important for working with DataONE, especially to +avoid unexpected results. For example, depending your authorization status, searches may or may +return only public records, or the full set of public and private records. Object and package +retrievals might fail if some or all of the objects being retrieved are private. Creating or +updating objects on DataONE nodes and reserving identifiers reservations might fail if your authorization certificate is missing or expired. -DataONE identifies you using CILogon-provided x509 certificates. DataONE has -partnered with CILogon to provide a widely-accessible certificate issuing mechanism +DataONE identifies you using CILogon-provided x509 certificates. DataONE has +partnered with CILogon to provide a widely-accessible certificate issuing mechanism that allows DataONE users to use existing trusted institutional and public accounts. CILogon recognizes many identity providers, including many universities as well as Google, so most times users new to DataONE can get certificates using one -of their existing accounts. For more information about the CILogon service, see +of their existing accounts. For more information about the CILogon service, see "https://cilogon.org/?skin=DataONE" . X509 Certificates differ from typical username-password login schemes in that certificates can be used by more than one application, which is very useful when using more than one DataONE-enabled application. The certificates CILogon issues -for DataONE are so-called "short-lived" certificates that currently expire 18 hours +for DataONE are so-called "short-lived" certificates that currently expire 18 hours from the time of issuing. Typically you will want to download a fresh certificate the first time you interact with DataONE each day. } @@ -49,14 +49,14 @@ the first time you interact with DataONE each day. \section{Methods}{ \itemize{ - \item{\code{\link{CertificateManager}}}{: Create a CertificateManager object.} - \item{\code{\link{getCertLocation}}}{: Get the file path on disk of the client certificate file.} - \item{\code{\link{showClientSubject}}}{: Get DataONE Identity as Stored in the CILogon Certificate.} - \item{\code{\link{isCertExpired}}}{: Determine if an X.509 certificate has expired.} - \item{\code{\link{getCertExpires}}}{: Show the date and time when an X.509 certificate expires.} - \item{\code{\link{downloadCert}}}{: Open the CILogon Certificate download page in the default browser.} - \item{\code{\link{obscureCert}}}{: Obscure the CILogon Client Certificate.} - \item{\code{\link{restoreCert}}}{: Restore the CILogon client certificate by renaming it to its original location} +\item \code{\link[=CertificateManager]{CertificateManager()}}: Create a CertificateManager object +\item \code{\link[=getCertLocation]{getCertLocation()}}: Get the file path on disk of the client certificate file +\item \code{\link[=showClientSubject]{showClientSubject()}}: Get DataONE Identity as Stored in the CILogon Certificate +\item \code{\link[=isCertExpired]{isCertExpired()}}: Determine if an X.509 certificate has expired +\item \code{\link[=getCertExpires]{getCertExpires()}}: Show the date and time when an X.509 certificate expires +\item \code{\link[=downloadCert]{downloadCert()}}: Open the CILogon Certificate download page in the default browser +\item \code{\link[=obscureCert]{obscureCert()}}: Obscure the CILogon Client Certificate +\item \code{\link[=restoreCert]{restoreCert()}}: Restore the CILogon client certificate by renaming it to its original location } } @@ -72,7 +72,7 @@ cm <- restoreCert(cm) } } \seealso{ -\code{\link{dataone}}{ package description.} +\code{\link[=dataone]{dataone()}} package description. } \author{ Matthew Jones, Rob Nahf diff --git a/man/CertificateManager.Rd b/man/CertificateManager.Rd index 97474ef..e7a286f 100644 --- a/man/CertificateManager.Rd +++ b/man/CertificateManager.Rd @@ -16,11 +16,11 @@ CertificateManager(...) the CertificateManager object } \description{ -Construct an instance of CertficateManager to provide mechanisms to obtain, load, verify, and +Construct an instance of CertficateManager to provide mechanisms to obtain, load, verify, and display X509 certificates. If the \code{'location'} field is provided, then that location is interpreted as the fully qualified path to a certificate on the local filesystem, and the default locations will not be -searched. If \code{'location'} is missing, then the default Globus Grid Security Infrastructure (GSI) -location is searched, which is \code{'/tmp/x509up_u${UID}'} on Unix -or \code{'${tmpdir}/x509up_u${UID}'} on Windows or \code{'${tmpdir}/x509up_u${user.name}'} if \code{'${UID}'} +searched. If \code{'location'} is missing, then the default Globus Grid Security Infrastructure (GSI) +location is searched, which is \code{'/tmp/x509up_u${UID}'} on Unix +or \code{'${tmpdir}/x509up_u${UID}'} on Windows or \code{'${tmpdir}/x509up_u${user.name}'} if \code{'${UID}'} is not defined. } diff --git a/man/D1Client-class.Rd b/man/D1Client-class.Rd index a240c6b..c790715 100644 --- a/man/D1Client-class.Rd +++ b/man/D1Client-class.Rd @@ -7,7 +7,7 @@ \description{ The methods in the D1Client class call the low level DataONE API to perform involved tasks such as uploading all the packages in a DataPackage (i.e -\code{\link{uploadDataPackage}}) +\code{\link[=uploadDataPackage]{uploadDataPackage()}}) } \section{Slots}{ @@ -20,23 +20,23 @@ perform involved tasks such as uploading all the packages in a DataPackage (i.e \section{Methods}{ \itemize{ - \item{\code{\link{D1Client}}}{: Construct a D1Client object.} - \item{\code{\link{convert.csv}}}{: Convert a DataFrame to Standard CSV.} - \item{\code{\link{createDataPackage}}}{: Create a DataPackage on a DataONE Member Node.} - \item{\code{\link{encodeUrlPath}}}{: Encode the Input for a URL Path Segment.} - \item{\code{\link{encodeUrlQuery}}}{: Encode the Input for a URL Query Segment.} - \item{\code{\link{getDataObject}}}{: Download a single data object from a DataONE Federation member node.} - \item{\code{\link{getDataPackage}}}{: Download a collection of data object from the DataONE Federation member node as a DataPackage.} - \item{\code{\link{getEndpoint}}}{: Return the URL endpoint for the DataONE Coordinating Node.} - \item{\code{\link{getMetadataMember}}}{: Get the DataObject containing package metadata.} - \item{\code{\link{getMNodeId}}}{: Get the member node identifier associated with this D1Client object.} - \item{\code{\link{listMemberNodes}}}{: List DataONE Member Nodes.} - \item{\code{\link{reserveIdentifier}}}{: Reserve a unique identifier in the DataONE Network.} - \item{\code{\link{uploadDataObject}}}{: Upload a DataObject to a DataONE member node.} - \item{\code{\link{uploadDataPackage}}}{: Upload a DataPackage to a DataONE member node.} +\item \code{\link[=D1Client]{D1Client()}}: Construct a D1Client object +\item \code{\link[=convert.csv]{convert.csv()}}: Convert a DataFrame to Standard CSV +\item \code{\link[=createDataPackage]{createDataPackage()}}: Create a DataPackage on a DataONE Member Node +\item \code{\link[=encodeUrlPath]{encodeUrlPath()}}: Encode the Input for a URL Path Segment +\item \code{\link[=encodeUrlQuery]{encodeUrlQuery()}}: Encode the Input for a URL Query Segment +\item \code{\link[=getDataObject]{getDataObject()}}: Download a single data object from a DataONE Federation member node +\item \code{\link[=getDataPackage]{getDataPackage()}}: Download a collection of data object from the DataONE Federation member node as a DataPackage +\item \code{\link[=getEndpoint]{getEndpoint()}}: Return the URL endpoint for the DataONE Coordinating Node +\item \code{\link[=getMetadataMember]{getMetadataMember()}}: Get the DataObject containing package metadata +\item \code{\link[=getMNodeId]{getMNodeId()}}: Get the member node identifier associated with this D1Client object +\item \code{\link[=listMemberNodes]{listMemberNodes()}}: List DataONE Member Nodes +\item \code{\link[=reserveIdentifier]{reserveIdentifier()}}: Reserve a unique identifier in the DataONE Network +\item \code{\link[=uploadDataObject]{uploadDataObject()}}: Upload a DataObject to a DataONE member node +\item \code{\link[=uploadDataPackage]{uploadDataPackage()}}: Upload a DataPackage to a DataONE member node } } \seealso{ -\code{\link{dataone}}{ package description.} +\code{\link[=dataone]{dataone()}} package description. } diff --git a/man/D1Client-initialize.Rd b/man/D1Client-initialize.Rd index c4decef..96f5870 100644 --- a/man/D1Client-initialize.Rd +++ b/man/D1Client-initialize.Rd @@ -34,5 +34,5 @@ d1c <- D1Client("PROD", "urn:node:KNB") } } \seealso{ -\code{\link[=D1Client-class]{dataone}}{ class description.} +\code{\link[=D1Client-class]{dataone()}} class description. } diff --git a/man/D1Client.Rd b/man/D1Client.Rd index 18d7ad9..0d494c6 100644 --- a/man/D1Client.Rd +++ b/man/D1Client.Rd @@ -23,10 +23,10 @@ D1Client(x, y, ...) } \arguments{ \item{x}{The label for the DataONE environment to be using ('PROD','STAGING','SANDBOX','DEV'). This parameter -can alternatively be a \code{\link{CNode}} instance, with the `y` parameter specified as an \code{\link{MNode}} instance.} +can alternatively be a \code{\link[=CNode]{CNode()}} instance, with the \code{y} parameter specified as an \code{\link[=MNode]{MNode()}} instance.} \item{y}{The node Id of the application's 'home' node. Should be already registered to the corresponding 'env'. This -parameter can alternatively be an \code{\link{MNode}} instance, with the `x` parameter specified as a \code{\link{CNode}} instance.} +parameter can alternatively be an \code{\link[=MNode]{MNode()}} instance, with the \code{x} parameter specified as a \code{\link[=CNode]{CNode()}} instance.} \item{...}{(not yet used)} } @@ -45,5 +45,5 @@ cli <- D1Client(cn,mn) } } \seealso{ -\code{\link[=D1Client-class]{D1Client}}{ class description.} +\code{\link[=D1Client-class]{D1Client()}} class description. } diff --git a/man/D1Node-class.Rd b/man/D1Node-class.Rd index 9dbde2f..65f0a2b 100644 --- a/man/D1Node-class.Rd +++ b/man/D1Node-class.Rd @@ -41,20 +41,20 @@ methods that are common between these two child classes. \section{Methods}{ \itemize{ - \item{\code{\link{D1Node-initialize}{initialize}}}{: Initialize a D1Node} - \item{\code{\link{D1Node}}}{: Create a MNode object representing a DataONE Member Node repository.} - \item{\code{\link{archive}}}{: Change the state of an object so that it is hidden from searches.} - \item{\code{\link{describeObject}}}{: Get header information for a given pid.} - \item{\code{\link{getChecksum}}}{: Get the checksum for the data object associated with the specified pid.} - \item{\code{\link{getObject}}}{: Get the bytes associated with an object on a node.} - \item{\code{\link{getQueryEngineDescription}}}{: Query a node for the list of query engines available on the node.} - \item{\code{\link{getSystemMetadata}}}{: Get the metadata describing system properties associated with an object on the Node.} - \item{\code{\link{listObjects}}}{: Retrieve the list of objects that match the search parameters.} - \item{\code{\link{listQueryEngines}}}{: Query a node for the list of query engines available on the node.} - \item{\code{\link{ping}}}{: Test if a node is online and accepting DataONE requests.} - \item{\code{\link{encodeSolr}}}{: Encode the input for Solr Queries.} - \item{\code{\link{query}}}{: Search DataONE for data and metadata objects.} - \item{\code{\link{isAuthorized}}}{: Check if an action is authorized for the specified identifier.} +\item \link{D1Node-initialize}: Initialize a D1Node +\item \code{\link[=D1Node]{D1Node()}}: Create a MNode object representing a DataONE Member Node repository +\item \code{\link[=archive]{archive()}}: Change the state of an object so that it is hidden from searches +\item \code{\link[=describeObject]{describeObject()}}: Get header information for a given pid +\item \code{\link[=getChecksum]{getChecksum()}}: Get the checksum for the data object associated with the specified pid +\item \code{\link[=getObject]{getObject()}}: Get the bytes associated with an object on a node +\item \code{\link[=getQueryEngineDescription]{getQueryEngineDescription()}}: Query a node for the list of query engines available on the node +\item \code{\link[=getSystemMetadata]{getSystemMetadata()}}: Get the metadata describing system properties associated with an object on the Node +\item \code{\link[=listObjects]{listObjects()}}: Retrieve the list of objects that match the search parameters +\item \code{\link[=listQueryEngines]{listQueryEngines()}}: Query a node for the list of query engines available on the node +\item \code{\link[=ping]{ping()}}: Test if a node is online and accepting DataONE requests +\item \code{\link[=encodeSolr]{encodeSolr()}}: Encode the input for Solr Queries +\item \code{\link[=query]{query()}}: Search DataONE for data and metadata objects +\item \code{\link[=isAuthorized]{isAuthorized()}}: Check if an action is authorized for the specified identifier } } diff --git a/man/D1Object-class.Rd b/man/D1Object-class.Rd index 09da529..5983216 100644 --- a/man/D1Object-class.Rd +++ b/man/D1Object-class.Rd @@ -17,17 +17,17 @@ a wrapper for data and associated SystemMetadata. \section{Methods}{ \itemize{ - \item{\code{\link[dataone]{D1Object-initialize}}}{: Initialize a D1Object} - \item{\code{\link[dataone]{getData}}}{: Get the data content of a specified D1Object.} - \item{\code{\link[dataone]{getIdentifier}}}{: Get the identifier of the D1Object.} - \item{\code{\link[dataone]{getFormatId}}}{: Get the formatId of the D1Object} - \item{\code{\link[dataone]{setPublicAccess}}}{: Add a Rule to the AccessPolicy to make the object publicly readable.} - \item{\code{\link[dataone]{canRead}}}{: Test whether the provided subject can read an object.} - \item{\code{\link{asDataFrame}}}{: Return the D1Object as a data.frame.} +\item \code{dataone::D1Object-initialize()}: Initialize a D1Object +\item \code{dataone::getData()}: Get the data content of a specified D1Object +\item \code{dataone::getIdentifier()}: Get the identifier of the D1Object +\item \code{dataone::getFormatId()}: Get the formatId of the D1Object +\item \code{dataone::setPublicAccess()}: Add a Rule to the AccessPolicy to make the object publicly readable +\item \code{dataone::canRead()}: Test whether the provided subject can read an object +\item \code{asDataFrame()}: Return the D1Object as a data.frame } } \seealso{ -\code{\link{dataone}}{ package description.} +\code{\link[=dataone]{dataone()}} package description } \keyword{classes} diff --git a/man/D1Object-initialize.Rd b/man/D1Object-initialize.Rd index 9e112d6..38ecfd7 100644 --- a/man/D1Object-initialize.Rd +++ b/man/D1Object-initialize.Rd @@ -22,5 +22,5 @@ Initialize a D1Object } \seealso{ -\code{\link[=D1Object-class]{D1Object}}{ class description.} +\code{\link[=D1Object-class]{D1Object()}} class description. } diff --git a/man/D1Object.Rd b/man/D1Object.Rd index 7dbb8dc..ea11822 100644 --- a/man/D1Object.Rd +++ b/man/D1Object.Rd @@ -16,5 +16,5 @@ the D1Object instance Create a D1Object instance. } \seealso{ -\code{\link[=D1Object-class]{D1Object}}{ class description.} +\code{\link[=D1Object-class]{D1Object()}} class description. } diff --git a/man/MNode-class.Rd b/man/MNode-class.Rd index de11edf..bf61ba3 100644 --- a/man/MNode-class.Rd +++ b/man/MNode-class.Rd @@ -5,21 +5,18 @@ \alias{MNode-class} \title{Provides R API to DataONE Member Node services.} \description{ -MNode provides functions that interact with a DataONE Member Node (MN). A MN +MNode provides functions that interact with a DataONE Member Node (MN). A MN is a repository that provides access for reading and writing data and metadata using the DataONE MN service API. The MN API includes functions for retrieving data and metadata based on its unique persistent identifier (pid), as well as for creating, updating, and archiving these data and metadata objects. } \details{ -Methods that perform write operations (such as createObject and updateObject) on the MN generally -require authentication. For MNs that have implemented the DataONE API version 2.0 and higher, these operations can utilize an +Methods that perform write operations (such as createObject and updateObject) on the MN generally +require authentication. For MNs that have implemented the DataONE API version 2.0 and higher, these operations can utilize an authentication token to provide credentials for write operations in DataONE. The authentication token is obtained from DataONE (see your account profile on https://search.dataone.org). -See the \code{vignette("dataone-overview")} for details. -Alternatively, the version 1.0 approach of using an X.509 certificate in a default location of the file -system can also be used. This certificate provides authentication credentials from -CILogon \url{https://cilogon.org/?skin=DataONE}. +See the \code{vignette("v01-dataone-overview")} for details. } \section{Slots}{ @@ -30,14 +27,14 @@ CILogon \url{https://cilogon.org/?skin=DataONE}. \section{Methods}{ \itemize{ - \item{\code{\link{MNode}}}{: Create a MNode object representing a DataONE Member Node repository.} - \item{\code{\link{createObject}}}{: Create an object on a Member Node.} - \item{\code{\link{getObject}}}{: Get the bytes associated with an object on the Member Node} - \item{\code{\link{getCapabilities}}}{: Get the node capabilities description, and store the information in the MNode.} - \item{\code{\link{generateIdentifier}}}{: Get a unique identifier that is generated by the Member Node repository and guaranteed to be unique.} - \item{\code{\link{getPackage}}}{: Download a data package from a member node.} - \item{\code{\link{updateObject}}}{: Update an object to a Member Node, by creating a new object that replaces an original.} - \item{\code{\link{updateSystemMetadata}}}{: Update the system metadata associated with an object.} +\item \code{\link[=MNode]{MNode()}}: Create a MNode object representing a DataONE Member Node repository +\item \code{\link[=createObject]{createObject()}}: Create an object on a Member Node +\item \code{\link[=getObject]{getObject()}}: Get the bytes associated with an object on the Member Node +\item \code{\link[=getCapabilities]{getCapabilities()}}: Get the node capabilities description, and store the information in the MNode +\item \code{\link[=generateIdentifier]{generateIdentifier()}}: Get a unique identifier that is generated by the Member Node repository and guaranteed to be unique +\item \code{\link[=getPackage]{getPackage()}}: Download a data package from a member node +\item \code{\link[=updateObject]{updateObject()}}: Update an object to a Member Node, by creating a new object that replaces an original +\item \code{\link[=updateSystemMetadata]{updateSystemMetadata()}}: Update the system metadata associated with an object } } @@ -70,5 +67,5 @@ response <- createObject(mn, newid, csvfile, sysmeta) } } \seealso{ -\code{\link{dataone}}{ package description.} +\code{\link[=dataone]{dataone()}} package description. } diff --git a/man/MNode.Rd b/man/MNode.Rd index 3a01c2b..f6287d1 100644 --- a/man/MNode.Rd +++ b/man/MNode.Rd @@ -19,7 +19,7 @@ MNode(x) the MNode object- } \description{ -Construct an instance of MNode to provide mechanisms to access, create, and update data and +Construct an instance of MNode to provide mechanisms to access, create, and update data and metadata objects on the associated Member Node. } \details{ @@ -34,5 +34,5 @@ mn <- MNode("https://knb.ecoinformatics.org/knb/d1/mn/v2") } } \seealso{ -\code{\link[=MNode-class]{MNode}}{ class description.} +\code{\link[=MNode-class]{MNode()}} class description. } diff --git a/man/addData.Rd b/man/addData.Rd index a63d12d..d244799 100644 --- a/man/addData.Rd +++ b/man/addData.Rd @@ -20,7 +20,7 @@ The D1Object \code{do} is added to the data package \code{x}. If the optional \code{mo} parameter is specified, then it is assumed that this DataObject is a metadata object that describes the data object that is being added. The DataObject specified in the \code{mo} parameter will also be added to the DataPackage, if it has not already been added. Then the \code{addData} function will add a relationship -to the resource map that indicates that the metadata object describes the science object, using CiTO, the Citation Typing Ontology, +to the resource map that indicates that the metadata object describes the science object, using CiTO, the Citation Typing Ontology, \code{documents} and \code{isDocumentedBy} relationships. } \examples{ diff --git a/man/archive.Rd b/man/archive.Rd index 3f7fff9..90d5ad9 100644 --- a/man/archive.Rd +++ b/man/archive.Rd @@ -28,10 +28,11 @@ a historical record, such as when journal articles might cite the object. Users contents of archived objects if they have the identifier, but will not discover it through searches. } \details{ -This operation requires an X.509 certificate to be present in the default location of the file -system. This certificate provides authentication credentials from -CILogon \url{https://cilogon.org/?skin=DataONE}. See \code{\link{CertificateManager}} for details. -For DataONE Version 2.0, an authentication token can also be used for authentication. +Methods that perform write operations (such as createObject and updateObject) on the MN generally +require authentication. For MNs that have implemented the DataONE API version 2.0 and higher, these operations can utilize an +authentication token to provide credentials for write operations in DataONE. +The authentication token is obtained from DataONE (see your account profile on https://search.dataone.org). +See the \code{vignette("v01-dataone-overview")} for details. Also, administrator privilege is required to run archive() on a DataONE Coordinating Node. } \examples{ @@ -66,5 +67,5 @@ archivedId <- archive(mn, newid) } } \seealso{ -\code{\link[=D1Node-class]{D1Node}}{ class description.} +\code{\link[=D1Node-class]{D1Node()}} class description. } diff --git a/man/auth_delete.Rd b/man/auth_delete.Rd index f3c64a8..c20340d 100644 --- a/man/auth_delete.Rd +++ b/man/auth_delete.Rd @@ -19,7 +19,7 @@ auth_delete(url, encode = "multipart", body = as.list(NA), node) the HTTP response from the request } \description{ -DELETE data at a URL using an HTTP DELETE request using authentication credentials +DELETE data at a URL using an HTTP DELETE request using authentication credentials provided in a client certificate. Authenticated access depends on the suggested openssl package. If the openssl package is not installed, then the request fails. } diff --git a/man/auth_get.Rd b/man/auth_get.Rd index 0c8bf20..82d3257 100644 --- a/man/auth_get.Rd +++ b/man/auth_get.Rd @@ -19,7 +19,7 @@ auth_get(url, nconfig = config(), node, path = NULL) the response object from the method } \description{ -Retrieve the data at a URL using an HTTP GET request using authentication credentials +Retrieve the data at a URL using an HTTP GET request using authentication credentials provided in a client certificate. Authenticated access depends on the suggested openssl package. If the openssl package is not installed, then the request falls back to an unauthenticated request, which may fail due to insufficient permissions. diff --git a/man/auth_head.Rd b/man/auth_head.Rd index 78bdc84..1404e14 100644 --- a/man/auth_head.Rd +++ b/man/auth_head.Rd @@ -17,13 +17,13 @@ auth_head(url, nconfig = config(), node) the response object from the method } \description{ -Retrieve http header information for a URL using an HTTP HEAD request -using authentication credentials provided in a client certificate or token. -Authenticated access depends on the suggested openssl package. If the openssl -package is not installed, then the request falls back to an unauthenticated request, +Retrieve http header information for a URL using an HTTP HEAD request +using authentication credentials provided in a client certificate or token. +Authenticated access depends on the suggested openssl package. If the openssl +package is not installed, then the request falls back to an unauthenticated request, which may fail due to insufficient permissions. Configuration options for httr/RCurl can be passed using the normal config() mechanisms to generate a config option. Use httr_options() to see a complete list -of available options. Note: The HEAD method is identical to GET except that the server MUST +of available options. Note: The HEAD method is identical to GET except that the server MUST NOT return a message-body in the response. } diff --git a/man/auth_post.Rd b/man/auth_post.Rd index 9e83476..b365137 100644 --- a/man/auth_post.Rd +++ b/man/auth_post.Rd @@ -19,7 +19,7 @@ auth_post(url, encode = "multipart", body = NULL, node) the HTTP response from the request } \description{ -POST data to a URL using an HTTP POST request using authentication credentials +POST data to a URL using an HTTP POST request using authentication credentials provided in a client certificate. Authenticated access depends on the suggested openssl package. If the openssl package is not installed, then the request fails. } diff --git a/man/auth_put.Rd b/man/auth_put.Rd index 65f87e0..2644fcc 100644 --- a/man/auth_put.Rd +++ b/man/auth_put.Rd @@ -19,7 +19,7 @@ auth_put(url, encode = "multipart", body = NULL, node) the HTTP response from the request } \description{ -PUT data to a URL using an HTTP PUT request using authentication credentials +PUT data to a URL using an HTTP PUT request using authentication credentials provided in a client certificate. Authenticated access depends on the suggested openssl package. If the openssl package is not installed, then the request fails. } diff --git a/man/auth_put_post_delete.Rd b/man/auth_put_post_delete.Rd index 9756850..46240a3 100644 --- a/man/auth_put_post_delete.Rd +++ b/man/auth_put_post_delete.Rd @@ -21,7 +21,7 @@ auth_put_post_delete(method, url, encode = "multipart", body = NULL, node) the response object from the method } \description{ -POST, PUT, or DELETE data to a URL using an HTTP request using authentication credentials +POST, PUT, or DELETE data to a URL using an HTTP request using authentication credentials provided in a client authentication, either via authentication token or certificate. If the user does not have a valid token or certificate, request fails. } diff --git a/man/canRead.Rd b/man/canRead.Rd index 1d2451a..3675dea 100644 --- a/man/canRead.Rd +++ b/man/canRead.Rd @@ -16,7 +16,7 @@ logical TRUE if the subject has read permission, or FALSE otherwise } \description{ Using the AccessPolicy, tests whether the subject has read permission -for the object. This method is meant work prior to submission to a repository, +for the object. This method is meant work prior to submission to a repository, and will show the permissions that would be enforced by the repository on submission. Currently it only uses the AccessPolicy to determine who can read (and not the rightsHolder field, which always can read an object). If an object has been granted read access by the diff --git a/man/convert.csv.Rd b/man/convert.csv.Rd index a9f2999..617b0d5 100644 --- a/man/convert.csv.Rd +++ b/man/convert.csv.Rd @@ -30,5 +30,5 @@ sdf <- convert.csv(d1c, testdf) } } \seealso{ -\code{\link[=D1Client-class]{D1Client}}{ class description.} +\code{\link[=D1Client-class]{D1Client()}} class description. } diff --git a/man/createDataPackage.Rd b/man/createDataPackage.Rd index b08d230..0e04ad9 100644 --- a/man/createDataPackage.Rd +++ b/man/createDataPackage.Rd @@ -46,5 +46,5 @@ resourceMapId <- createDataPackage(d1c, dp, replicate=TRUE, public=TRUE) } } \seealso{ -\code{\link[=D1Client-class]{D1Client}}{ class description.} +\code{\link[=D1Client-class]{D1Client()}} class description. } diff --git a/man/createObject.Rd b/man/createObject.Rd index b46987d..2a073f1 100644 --- a/man/createObject.Rd +++ b/man/createObject.Rd @@ -30,13 +30,10 @@ This method provides the ability to upload a data or metadata object to the Memb provided in the \code{'mnode'} parameter. } \details{ -In the version 2.0 library and higher, this operation can utilize an +In the version 2.0 library and higher, this operation can utilize an 'dataone_token' option to provide credentials for write operations in DataONE. The authentication token is obtained from DataONE (see your profile on https://search.dataone.org). -See the \code{vignette("dataone-overview")} for details. -Alternatively, the version 1.0 approach of using an X.509 certificate in a default location of the file -system can also be used. This certificate provides authentication credentials from -CILogon \url{https://cilogon.org/?skin=DataONE}. See \code{vignette("dataone-overview")} for details. +See the \code{vignette("v01-dataone-overview")} for details. } \examples{ \dontrun{ diff --git a/man/d1IdentifierSearch.Rd b/man/d1IdentifierSearch.Rd index 4182671..2463f11 100644 --- a/man/d1IdentifierSearch.Rd +++ b/man/d1IdentifierSearch.Rd @@ -31,5 +31,5 @@ result <- d1IdentifierSearch(client,solrQuery="species population diversity") } } \seealso{ -\code{\link[=D1Client-class]{D1Client}}{ class description.} +\code{\link[=D1Client-class]{D1Client()}} class description. } diff --git a/man/d1SolrQuery.Rd b/man/d1SolrQuery.Rd index 3bb90a0..ed8de21 100644 --- a/man/d1SolrQuery.Rd +++ b/man/d1SolrQuery.Rd @@ -36,5 +36,5 @@ result <- d1SolrQuery(d1c, queryParams) } } \seealso{ -\code{\link[=D1Client-class]{D1Client}}{ class description.} +\code{\link[=D1Client-class]{D1Client()}} class description. } diff --git a/man/data.tableAttributeNames.Rd b/man/data.tableAttributeNames.Rd index 623bca4..25dc288 100644 --- a/man/data.tableAttributeNames.Rd +++ b/man/data.tableAttributeNames.Rd @@ -10,9 +10,13 @@ data.tableAttributeNames(x, index, ...) \S4method{data.tableAttributeNames}{EMLParser,numeric}(x, index) } \arguments{ -\item{x}{- the TableDescriber instance} +\item{x}{\itemize{ +\item the TableDescriber instance +}} -\item{index}{- the index of the table to get results for} +\item{index}{\itemize{ +\item the index of the table to get results for +}} \item{...}{(not yet used)} } @@ -20,7 +24,7 @@ data.tableAttributeNames(x, index, ...) the attribute (column) names of the data } \description{ -THe attribute names are defined in the metadata document for +THe attribute names are defined in the metadata document for the specified data table } \author{ diff --git a/man/data.tableAttributeOrientation.Rd b/man/data.tableAttributeOrientation.Rd index 4c10db8..ecfd75b 100644 --- a/man/data.tableAttributeOrientation.Rd +++ b/man/data.tableAttributeOrientation.Rd @@ -10,9 +10,13 @@ data.tableAttributeOrientation(x, index, ...) \S4method{data.tableAttributeOrientation}{EMLParser,numeric}(x, index) } \arguments{ -\item{x}{- the TableDescriber} +\item{x}{\itemize{ +\item the TableDescriber +}} -\item{index}{- the index of the table within the document} +\item{index}{\itemize{ +\item the index of the table within the document +}} \item{...}{Additional parameters} } @@ -21,7 +25,7 @@ legal values are "columns" | "rows" } \description{ Which way to the attribute headers run? Most data has a header row -where the attribute names go across "columns", in row in which case, the +where the attribute names go across "columns", in row in which case, the return value for this method should be "columns." } \note{ diff --git a/man/data.tableAttributeStorageTypes.Rd b/man/data.tableAttributeStorageTypes.Rd index 8a177ee..6edc5a2 100644 --- a/man/data.tableAttributeStorageTypes.Rd +++ b/man/data.tableAttributeStorageTypes.Rd @@ -10,9 +10,13 @@ data.tableAttributeStorageTypes(x, index, ...) \S4method{data.tableAttributeStorageTypes}{EMLParser,numeric}(x, index) } \arguments{ -\item{x}{- the TableDescriber instance} +\item{x}{\itemize{ +\item the TableDescriber instance +}} -\item{index}{- the index of the table to get results for} +\item{index}{\itemize{ +\item the index of the table to get results for +}} \item{...}{(not yet used)} } @@ -20,7 +24,7 @@ data.tableAttributeStorageTypes(x, index, ...) the data storage types of the attributes } \description{ -The attributes' data storage types are defined in the metadata document for +The attributes' data storage types are defined in the metadata document for the specified data table } \author{ diff --git a/man/data.tableAttributeTypes.Rd b/man/data.tableAttributeTypes.Rd index 2e3573f..617eb03 100644 --- a/man/data.tableAttributeTypes.Rd +++ b/man/data.tableAttributeTypes.Rd @@ -10,9 +10,13 @@ data.tableAttributeTypes(x, index, ...) \S4method{data.tableAttributeTypes}{EMLParser,numeric}(x, index) } \arguments{ -\item{x}{- the TableDescriber instance} +\item{x}{\itemize{ +\item the TableDescriber instance +}} -\item{index}{- the index of the table to get results for} +\item{index}{\itemize{ +\item the index of the table to get results for +}} \item{...}{(not yet used)} } @@ -20,7 +24,7 @@ data.tableAttributeTypes(x, index, ...) the data types of the attributes } \description{ -The attributes' data types are defined in the metadata document for +The attributes' data types are defined in the metadata document for the specified data table } \author{ diff --git a/man/data.tableMissingValueCodes.Rd b/man/data.tableMissingValueCodes.Rd index 047e86e..db20458 100644 --- a/man/data.tableMissingValueCodes.Rd +++ b/man/data.tableMissingValueCodes.Rd @@ -10,9 +10,13 @@ data.tableMissingValueCodes(x, index, ...) \S4method{data.tableMissingValueCodes}{EMLParser,numeric}(x, index) } \arguments{ -\item{x}{- the TableDescriber instance} +\item{x}{\itemize{ +\item the TableDescriber instance +}} -\item{index}{- the index of the table to get results for} +\item{index}{\itemize{ +\item the index of the table to get results for +}} \item{...}{(not yet used)} } @@ -20,7 +24,7 @@ data.tableMissingValueCodes(x, index, ...) vector of missing value codes } \description{ -the missing value codes are defined in the metadata document for +the missing value codes are defined in the metadata document for the specified data table } \author{ diff --git a/man/data.tableSkipLinesHeader.Rd b/man/data.tableSkipLinesHeader.Rd index 31dc64e..749eca4 100644 --- a/man/data.tableSkipLinesHeader.Rd +++ b/man/data.tableSkipLinesHeader.Rd @@ -10,9 +10,13 @@ data.tableSkipLinesHeader(x, index, ...) \S4method{data.tableSkipLinesHeader}{EMLParser,numeric}(x, index) } \arguments{ -\item{x}{- the TableDescriber} +\item{x}{\itemize{ +\item the TableDescriber +}} -\item{index}{- the index of the table within the document} +\item{index}{\itemize{ +\item the index of the table within the document +}} \item{...}{Additional parameters} } diff --git a/man/dataone-defunct.Rd b/man/dataone-defunct.Rd index 5b93d9b..55f5c13 100644 --- a/man/dataone-defunct.Rd +++ b/man/dataone-defunct.Rd @@ -10,47 +10,47 @@ no longer supported. \section{These S4 methods are defunct}{ \itemize{ - \item{\code{\link{D1Object}}}{: A representation of a DataObject} - \itemize{ - \item{\code{\link{D1Object-initialize}}}{: Initialize a D1Object} - \item{\code{\link{getData}}}{: Get the data content of a specified D1Object.} - \item{\code{\link{getIdentifier}}}{: Get the identifier of the D1Object.} - \item{\code{\link{getFormatId}}}{: Get the formatId of the D1Object} - \item{\code{\link{setPublicAccess}}}{: Add a Rule to the AccessPolicy to make the object publicly readable.} - \item{\code{\link{canRead}}}{: Test whether the provided subject can read an object.} - \item{\code{\link{asDataFrame}}}{: Return the D1Object as a data.frame.} - \item{\code{\link{setObsoletedBy}}}{: Set a pid as being obsoleted by another pid.} - } -\item{\code{\link{D1Client}}}{: The DataONE client class used to download, update and search for data in the DataONE network} - \itemize{ - \item{\code{\link{d1SolrQuery}}}{: A method to query the DataONE solr endpoint of the Coordinating Node.} - \item{\code{\link{d1IdentifierSearch}}}{: Query the DataONE Solr endpoint of the Coordinating Node.} - \item{\code{\link{createDataPackage}}}{: Create a DataPackage on a DataONE Member Node} - \item{\code{\link{getMN}}}{: Get a member node client based on its node identifier.} - \item{\code{\link{convert.csv}}}{: Convert a DataFrame to Standard CSV.} - \item{\code{\link{addData}}}{: Add a D1Object containing a data object to a DataPackage} - \item{\code{\link{createD1Object}}}{: Create the Object in the DataONE System} - \item{\code{\link{getD1Object}}}{: Download a data object from the DataONE Federation.} - } -\item{\code{EMLParser}}{: A representation of a DataObject} - \itemize{ - \item{\code{\link{documented.entityNames}}}{: The entity names associated with each table are returned.} - \item{\code{\link{documented.d1Identifiers}}}{: Get the DataONE identifier associated with each table.} - \item{\code{\link{documented.sizes}}}{: Get the table size.} - } -\item{\code{AbstractTableDescriber}}{: Base Class for Specific Metadata Parsers} - \itemize{ - \item{\code{\link{data.formatFamily}}}{: Get the table format family.} - \item{\code{\link{data.tableFieldDelimiter}}}{: Get the table field delimiter.} - \item{\code{\link{data.tableQuoteCharacter}}}{: Get the table quote character.} - \item{\code{\link{data.characterEncoding}}}{: The character encoding used, for example "UTF-8"} - \item{\code{\link{data.tableAttributeOrientation}}}{: Which way to the attribute headers run? Most data has a header row} - \item{\code{\link{data.tableSkipLinesHeader}}}{: The specified number of lines are skipped.} - \item{\code{\link{data.tableMissingValueCodes}}}{: the missing value codes are defined in the metadata document for} - \item{\code{\link{data.tableAttributeNames}}}{: The attribute names are defined in the metadata document for} - \item{\code{\link{data.tableAttributeTypes}}}{: The attributes' data types are defined in the metadata document for} - \item{\code{\link{data.tableAttributeStorageTypes}}}{: The attributes' data storage types are defined in the metadata document for} - } +\item \code{\link[=D1Object]{D1Object()}}: A representation of a DataObject +\itemize{ +\item \code{D1Object-initialize()}: Initialize a D1Object +\item \code{getData()}: Get the data content of a specified D1Object +\item \code{getIdentifier()}: Get the identifier of the D1Object +\item \code{getFormatId()}: Get the formatId of the D1Object +\item \code{setPublicAccess()}: Add a Rule to the AccessPolicy to make the object publicly readable +\item \code{canRead()}: Test whether the provided subject can read an object +\item \code{asDataFrame()}: Return the D1Object as a data.frame +\item \code{setObsoletedBy()}: Set a pid as being obsoleted by another pid +} +\item \code{\link[=D1Client]{D1Client()}}: The DataONE client class used to download, update and search for data in the DataONE network +\itemize{ +\item \code{\link[=d1SolrQuery]{d1SolrQuery()}}: A method to query the DataONE solr endpoint of the Coordinating Node +\item \code{\link[=d1IdentifierSearch]{d1IdentifierSearch()}}: Query the DataONE Solr endpoint of the Coordinating Node +\item \code{\link[=createDataPackage]{createDataPackage()}}: Create a DataPackage on a DataONE Member Node +\item \code{\link[=getMN]{getMN()}}: Get a member node client based on its node identifier +\item \code{\link[=convert.csv]{convert.csv()}}: Convert a DataFrame to Standard CSV +\item \code{addData()}: Add a D1Object containing a data object to a DataPackage +\item \code{\link[=createD1Object]{createD1Object()}}: Create the Object in the DataONE System +\item \code{\link[=getD1Object]{getD1Object()}}: Download a data object from the DataONE Federation +} +\item \code{EMLParser}: A representation of a DataObject +\itemize{ +\item \code{\link[=documented.entityNames]{documented.entityNames()}}: The entity names associated with each table are returned +\item \code{\link[=documented.d1Identifiers]{documented.d1Identifiers()}}: Get the DataONE identifier associated with each table +\item \code{\link[=documented.sizes]{documented.sizes()}}: Get the table size +} +\item \code{AbstractTableDescriber}: Base Class for Specific Metadata Parsers +\itemize{ +\item \code{\link[=data.formatFamily]{data.formatFamily()}}: Get the table format family +\item \code{\link[=data.tableFieldDelimiter]{data.tableFieldDelimiter()}}: Get the table field delimiter +\item \code{\link[=data.tableQuoteCharacter]{data.tableQuoteCharacter()}}: Get the table quote character +\item \code{\link[=data.characterEncoding]{data.characterEncoding()}}: The character encoding used, for example "UTF-8" +\item \code{\link[=data.tableAttributeOrientation]{data.tableAttributeOrientation()}}: Which way to the attribute headers run? Most data has a header row +\item \code{\link[=data.tableSkipLinesHeader]{data.tableSkipLinesHeader()}}: The specified number of lines are skipped +\item \code{\link[=data.tableMissingValueCodes]{data.tableMissingValueCodes()}}: the missing value codes are defined in the metadata document for +\item \code{\link[=data.tableAttributeNames]{data.tableAttributeNames()}}: The attribute names are defined in the metadata document for +\item \code{\link[=data.tableAttributeTypes]{data.tableAttributeTypes()}}: The attributes' data types are defined in the metadata document for +\item \code{\link[=data.tableAttributeStorageTypes]{data.tableAttributeStorageTypes()}}: The attributes' data storage types are defined in the metadata document for +} } } diff --git a/man/dataone-deprecated.Rd b/man/dataone-deprecated.Rd index 9e8e522..525e31e 100644 --- a/man/dataone-deprecated.Rd +++ b/man/dataone-deprecated.Rd @@ -4,21 +4,21 @@ \alias{dataone-deprecated} \title{Deprecated} \description{ -The following items are deprecated in this release of dataone and will be +The following items are deprecated in this release of dataone and will be removed in a future release } \section{These S4 methods are deprecated}{ \itemize{ - \item{\code{\link{setObsoletedBy}}}{: Set a pid as being obsoleted by another pid.} - \item{\code{\link{CertificateManager}}}{: Create a CertificateManager object.} - \item{\code{\link{getCertLocation}}}{: Get the file path on disk of the client certificate file.} - \item{\code{\link{showClientSubject}}}{: Get DataONE Identity as Stored in the CILogon Certificate.} - \item{\code{\link{isCertExpired}}}{: Determine if an X.509 certificate has expired.} - \item{\code{\link{getCertExpires}}}{: Show the date and time when an X.509 certificate expires.} - \item{\code{\link{downloadCert}}}{: Open the CILogon Certificate download page in the default browser.} - \item{\code{\link{obscureCert}}}{: Obscure the CILogon Client Certificate.} - \item{\code{\link{restoreCert}}}{: Restore the CILogon client certificate by renaming it to its original location} +\item \code{\link[=setObsoletedBy]{setObsoletedBy()}}: Set a pid as being obsoleted by another pid +\item \code{\link[=CertificateManager]{CertificateManager()}}: Create a CertificateManager object +\item \code{\link[=getCertLocation]{getCertLocation()}}: Get the file path on disk of the client certificate file +\item \code{\link[=showClientSubject]{showClientSubject()}}: Get DataONE Identity as Stored in the CILogon Certificate +\item \code{\link[=isCertExpired]{isCertExpired()}}: Determine if an X.509 certificate has expired +\item \code{\link[=getCertExpires]{getCertExpires()}}: Show the date and time when an X.509 certificate expires +\item \code{\link[=downloadCert]{downloadCert()}}: Open the CILogon Certificate download page in the default browser +\item \code{\link[=obscureCert]{obscureCert()}}: Obscure the CILogon Client Certificate +\item \code{\link[=restoreCert]{restoreCert()}}: Restore the CILogon client certificate by renaming it to its original location } } diff --git a/man/dataone.Rd b/man/dataone.Rd index 852aac6..c11dd7e 100644 --- a/man/dataone.Rd +++ b/man/dataone.Rd @@ -2,30 +2,32 @@ % Please edit documentation in R/dataone-package.R \docType{package} \name{dataone} +\alias{dataone-package} \alias{dataone} \title{Search, download and upload data to the DataONE network.} \description{ -The R package \emph{dataone} provides read/write access to data and metadata from the -\href{https://www.dataone.org/}{DataONE} network of -Member Node data repositories. Member Nodes in DataONE are independent data repositories that have adopted the DataONE -services for interoperability, making each of the repositories accessible to client tools such as the DataONE R Client -using a standard interface. The DataONE R Client can be used to access data files and to write new data and metadata files +The R package \emph{dataone} provides read/write access to data and metadata from the +\href{https://www.dataone.org/}{DataONE} network of +Member Node data repositories. Member Nodes in DataONE are independent data repositories that have adopted the DataONE +services for interoperability, making each of the repositories accessible to client tools such as the DataONE R Client +using a standard interface. The DataONE R Client can be used to access data files and to write new data and metadata files to nodes in the DataONE network. } \section{Classes}{ \itemize{ - \item{\code{\link[=AuthenticationManager-class]{AuthenticationManager}}}{: AuthenticationManager provides methods to validate DataONE authentication.} - \item{\code{\link[=CNode-class]{CNode}}}{: A CNode represents a DataONE Coordinating Node and can be used to access its services.} - \item{\code{\link[=D1Client-class]{D1Client}}}{: The D1Client class contains methods that perform high level dataone tasks.} - \item{\code{\link[=D1Node-class]{D1Node}}}{: A base class for CNode and MNode.} - \item{\code{\link[=MNode-class]{MNode}}}{: MNode provides functions interacting with the a DataONE Member Node repository.} +\item \code{\link[=AuthenticationManager-class]{AuthenticationManager()}}: AuthenticationManager provides methods to validate DataONE authentication +\item \code{\link[=CNode-class]{CNode()}}: A CNode represents a DataONE Coordinating Node and can be used to access its services +\item \code{\link[=D1Client-class]{D1Client()}}: The D1Client class contains methods that perform high level dataone tasks +\item \code{\link[=D1Node-class]{D1Node()}}: A base class for CNode and MNode +\item \code{\link[=MNode-class]{MNode()}}: MNode provides functions interacting with the a DataONE Member Node repository } } \seealso{ -A description of the \emph{dataone} R package is available with the command: \code{'vignette("dataone-overview")'}. +A description of the \emph{dataone} R package is available with the command: \code{'vignette("v01-dataone-overview")'}. } \author{ Matthew B. Jones (NCEAS) and Peter Slaughter (NCEAS) } +\keyword{internal} diff --git a/man/downloadCert.Rd b/man/downloadCert.Rd index ee0ae9b..522f70d 100644 --- a/man/downloadCert.Rd +++ b/man/downloadCert.Rd @@ -15,11 +15,11 @@ downloadCert(x, ...) \item{...}{(Not yet used)} } \description{ -A convenience method to take you to the CILogon download page: +A convenience method to take you to the CILogon download page: "https://cilogon.org/?skin=DataONE. Logging into CILogon will allow you to download your X.509 certificate to your local computer. Typically, -the certificate is saved in the default Globus location for certificates -(\code{\link{getCertLocation}}) and once it is there, the \code{'dataone'} -package will use the certificate for all authenticated operations. Deleting +the certificate is saved in the default Globus location for certificates +(\code{\link[=getCertLocation]{getCertLocation()}}) and once it is there, the \code{'dataone'} +package will use the certificate for all authenticated operations. Deleting the certificate file is the equivalent of logging out. } diff --git a/man/downloadObject.Rd b/man/downloadObject.Rd index 7a20b4c..31686b7 100644 --- a/man/downloadObject.Rd +++ b/man/downloadObject.Rd @@ -29,11 +29,11 @@ A path where the ouput file is written to. A convenience method to download an object to disk. } \details{ -This method performs multiple underlying calls to the DataONE repository network. +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 success at downloading the associated SystemMetadata for the object. +is accessed until success at downloading the associated SystemMetadata for the object. The SystemMetadata is used to assign a name to the file that is output to disk. If a fileName is specified in -the SystemMetadata, then the file output to disk will be named according to the SystemMetadata fileName. +the SystemMetadata, then the file output to disk will be named according to the SystemMetadata fileName. If there is not a specified SystemMetadata fileName, the identifier will be used as the file name output to disk. If the identifier is used as the file name, a file name extension will be determined using the SystemMetadata formatID along with information from CNCore.listFormats(). If the SystemMetadata formatID is @@ -48,5 +48,5 @@ path <- downloadObject(d1c, pid) } } \seealso{ -\code{\link[=D1Client-class]{D1Client}}{ class description.} +\code{\link[=D1Client-class]{D1Client()}} class description. } diff --git a/man/echoCredentials.Rd b/man/echoCredentials.Rd index 50016c5..33413ca 100644 --- a/man/echoCredentials.Rd +++ b/man/echoCredentials.Rd @@ -18,7 +18,7 @@ echoCredentials(x, ...) A list containing authentication info. } \description{ -This method can be used to verify the client certificate is valid +This method can be used to verify the client certificate is valid and contains the expected information. } \details{ diff --git a/man/encodeUrlPath.Rd b/man/encodeUrlPath.Rd index 5bf6f91..957f502 100644 --- a/man/encodeUrlPath.Rd +++ b/man/encodeUrlPath.Rd @@ -31,5 +31,5 @@ fullyEncodedPath <- paste0("cn/v1/object/", } } \seealso{ -\code{\link[=D1Client-class]{D1Client}}{ class description.} +\code{\link[=D1Client-class]{D1Client()}} class description. } diff --git a/man/encodeUrlQuery.Rd b/man/encodeUrlQuery.Rd index 3b1f0bc..0014963 100644 --- a/man/encodeUrlQuery.Rd +++ b/man/encodeUrlQuery.Rd @@ -31,5 +31,5 @@ fullyEncodedQuery <- paste0("q=id:", } } \seealso{ -\code{\link[=D1Client-class]{D1Client}}{ class description.} +\code{\link[=D1Client-class]{D1Client()}} class description. } diff --git a/man/generateIdentifier.Rd b/man/generateIdentifier.Rd index fab13e0..64dc01e 100644 --- a/man/generateIdentifier.Rd +++ b/man/generateIdentifier.Rd @@ -24,19 +24,16 @@ the character string of the generated unique identifier } \description{ Creating objects requires use of a unique persistent identifier (pid) when calling the create -function. Member Nodes may optionally provide the generateIdentifier service to issue such identifiers, +function. Member Nodes may optionally provide the generateIdentifier service to issue such identifiers, ensuring that they are unique. Each identifier conforms to an identifier scheme, which determines the syntax and -rules for how the identifier that is generated is formatted. All Member Nodes that implement this method must +rules for how the identifier that is generated is formatted. All Member Nodes that implement this method must support the UUID scheme, but may also support other schemes such as DOI and others. } \details{ -In the version 2.0 library and higher, this operation can utilize an +In the version 2.0 library and higher, this operation can utilize an 'dataone_token' option to provide credentials for write operations in DataONE. The authentication token is obtained from DataONE (see your profile on https://search.dataone.org). -See the \code{vignette("dataone-overview")} for details. -Alternatively, the version 1.0 approach of using an X.509 certificate in a default location of the file -system can also be used. This certificate provides authentication credentials from -CILogon \url{https://cilogon.org/?skin=DataONE}. See \code{vignette("dataone-overview")} for details. +See the \code{vignette("v01-dataone-overview")} for details. } \examples{ \dontrun{ diff --git a/man/getAuthMethod.Rd b/man/getAuthMethod.Rd index b9c8258..8fb8ac4 100644 --- a/man/getAuthMethod.Rd +++ b/man/getAuthMethod.Rd @@ -25,6 +25,6 @@ Get the current valid authentication mechanism. \details{ The current authentication method being used, either an authentication token or an X.509 certificate. The \code{'node'} argument is used to determine the authentication mechanism that is appropriate for the specified \code{'node'}. -For example, authentication tokens are supported on DataONE nodes that use the DataONE V2.0 API or higher, so if the +For example, authentication tokens are supported on DataONE nodes that use the DataONE V2.0 API or higher, so if the node uses the V1 API, then only an X.509 certificate can be used. } diff --git a/man/getAuthSubject.Rd b/man/getAuthSubject.Rd index 96687f0..db8de16 100644 --- a/man/getAuthSubject.Rd +++ b/man/getAuthSubject.Rd @@ -26,6 +26,6 @@ Get the authentication subject. The authenticated user, aka 'subject' is retrieved from the authentication mechanism currently being used, either an authentication token or an X.509 certificate. The \code{'node'} argument is used to determine the authentication mechanism that is appropriate for the specified \code{'node'}. -For example, authentication tokens are supported on DataONE nodes that use the DataONE V2.0 API or higher, so if the +For example, authentication tokens are supported on DataONE nodes that use the DataONE V2.0 API or higher, so if the node uses the V1 API, then only an X.509 certificate can be used. } diff --git a/man/getCN.Rd b/man/getCN.Rd index 08aa836..7053f52 100644 --- a/man/getCN.Rd +++ b/man/getCN.Rd @@ -25,5 +25,5 @@ testCN <- getCN(cli) } } \seealso{ -\code{\link[=D1Client-class]{D1Client}}{ class description.} +\code{\link[=D1Client-class]{D1Client()}} class description. } diff --git a/man/getCertExpires.Rd b/man/getCertExpires.Rd index 34c0bb5..49439c5 100644 --- a/man/getCertExpires.Rd +++ b/man/getCertExpires.Rd @@ -18,6 +18,6 @@ getCertExpires(x, ...) POSIXct value } \description{ -Each X.509 has a range of certificate validity times. This method returns the X.509 +Each X.509 has a range of certificate validity times. This method returns the X.509 \code{'notAfter'} field formatted as a \code{'POSIXct'} date value. } diff --git a/man/getCertLocation.Rd b/man/getCertLocation.Rd index f12cec5..2019aeb 100644 --- a/man/getCertLocation.Rd +++ b/man/getCertLocation.Rd @@ -23,7 +23,7 @@ location on disk, unless the \code{'location'} slot has been set with a custom l the certificate. } \details{ -The default Globus Grid Security Infrastructure (GSI) location is \code{'/tmp/x509up_u${UID}'} -on Unix or \code{'${tmpdir}/x509up_u${UID}'} on Windows or \code{'${tmpdir}/x509up_u${user.name}'} +The default Globus Grid Security Infrastructure (GSI) location is \code{'/tmp/x509up_u${UID}'} +on Unix or \code{'${tmpdir}/x509up_u${UID}'} on Windows or \code{'${tmpdir}/x509up_u${user.name}'} if \code{'${UID}'} is not defined. } diff --git a/man/getChecksum.Rd b/man/getChecksum.Rd index f92a54c..c3324a6 100644 --- a/man/getChecksum.Rd +++ b/man/getChecksum.Rd @@ -45,5 +45,5 @@ chksum <- getChecksum(cn, pid) } } \seealso{ -\code{\link{D1Node-class}{D1Node}}{ class description.} +\code{[D1Node-class]{D1Node}} class description. } diff --git a/man/getD1Object.Rd b/man/getD1Object.Rd index 97fb0e2..bfa2524 100644 --- a/man/getD1Object.Rd +++ b/man/getD1Object.Rd @@ -32,5 +32,5 @@ data <- getData(dataObj) } } \seealso{ -\code{\link[=D1Client-class]{D1Client}}{ class description.} +\code{\link[=D1Client-class]{D1Client()}} class description. } diff --git a/man/getDataObject.Rd b/man/getDataObject.Rd index 43326b4..32b432e 100644 --- a/man/getDataObject.Rd +++ b/man/getDataObject.Rd @@ -30,8 +30,8 @@ for example: "100KB", "10MB", "20GB", "1TB". The default is "1MB". Only takes ef \item{quiet}{A \code{'logical'}. If TRUE (the default) then informational messages will not be printed.} -\item{checksumAlgorithm}{A \code{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 +\item{checksumAlgorithm}{A \code{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{ @@ -42,10 +42,10 @@ A convenience method to download a data object and its associated SystemMetadata in a DataObject class. } \details{ -This method performs multiple underlying calls to the DataONE repository network. +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 +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. \cr\cr The \code{lazyLoad} parameter controls whether the data byes for a DataONE item are downloaded (the system @@ -74,5 +74,5 @@ data <- getData(obj) } } \seealso{ -\code{\link[=D1Client-class]{D1Client}}{ class description.} +\code{\link[=D1Client-class]{D1Client()}} class description. } diff --git a/man/getDataPackage.Rd b/man/getDataPackage.Rd index 25b4b20..48c477a 100644 --- a/man/getDataPackage.Rd +++ b/man/getDataPackage.Rd @@ -31,14 +31,14 @@ for example: "100KB", "10MB", "20GB", "1TB". The default is "1MB". Only takes ef \item{quiet}{A \code{'logical'}. If TRUE (the default) then informational messages will not be printed.} -\item{checksumAlgorithm}{A \code{character} value specifying the algorithm to use to re-calculate (after download) the system metadata checksum +\item{checksumAlgorithm}{A \code{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 DataPackage or NULL if the package was not found in DataONE } \description{ -This is convenience method that will download all the members in a DataONE data package +This is convenience method that will download all the members in a DataONE data package and insert them into a DataPackage, including associated SystemMetadata for each package member. } @@ -67,5 +67,5 @@ pkg <- getDataPackage(d1c, pid) } } \seealso{ -\code{\link[=D1Client-class]{D1Client}}{ class description.} +\code{\link[=D1Client-class]{D1Client()}} class description. } diff --git a/man/getEndpoint.Rd b/man/getEndpoint.Rd index 74e5e27..6ba2955 100644 --- a/man/getEndpoint.Rd +++ b/man/getEndpoint.Rd @@ -30,5 +30,5 @@ cnUrl <- getEndpoint(cli) } } \seealso{ -\code{\link[=D1Client-class]{D1Client}}{ class description.} +\code{\link[=D1Client-class]{D1Client()}} class description. } diff --git a/man/getErrorDescription.Rd b/man/getErrorDescription.Rd index 3e2c9d6..7743f8d 100644 --- a/man/getErrorDescription.Rd +++ b/man/getErrorDescription.Rd @@ -16,10 +16,10 @@ determine what type of response was sent. } \details{ The return types handled by this function are: - o An incorrect url is sent to DataONE and an error is returned by - the web server, not a specified DataONE service url. In this case, - a generic error message may be returned, e.g. status=404, URL not found - o A DataONE service was called, and returned an error message. In this - case the DataONE response is parsed in an attempt to retrieve a - meaningful error message. +o An incorrect url is sent to DataONE and an error is returned by +the web server, not a specified DataONE service url. In this case, +a generic error message may be returned, e.g. status=404, URL not found +o A DataONE service was called, and returned an error message. In this +case the DataONE response is parsed in an attempt to retrieve a +meaningful error message. } diff --git a/man/getFormat.Rd b/man/getFormat.Rd index b41893e..9ae18fa 100644 --- a/man/getFormat.Rd +++ b/man/getFormat.Rd @@ -33,5 +33,5 @@ cat(sprintf("format Id: \%s\n", fmt$id)) } } \seealso{ -\code{\link[=CNode-class]{CNode}}{ class description.} +\code{\link[=CNode-class]{CNode()}} class description. } diff --git a/man/getMN.Rd b/man/getMN.Rd index fb2829d..34759a5 100644 --- a/man/getMN.Rd +++ b/man/getMN.Rd @@ -23,7 +23,7 @@ getMN(x, nodeid, ...) Get a member node client based on its node identifier. } \note{ -This method has been superceded by \code{\link{getMNodeId}} +This method has been superceded by \code{\link[=getMNodeId]{getMNodeId()}} } \examples{ \dontrun{ @@ -32,5 +32,5 @@ testMN <- getMN(cli) } } \seealso{ -\code{\link[=D1Client-class]{D1Client}}{ class description.} +\code{\link[=D1Client-class]{D1Client()}} class description. } diff --git a/man/getMNode.Rd b/man/getMNode.Rd index 99a58c5..ba8898f 100644 --- a/man/getMNode.Rd +++ b/man/getMNode.Rd @@ -24,8 +24,8 @@ Get a reference to a node based on its identifier } \details{ For an explanation of DataONE Coordinating Nodes and Member Node -identifiers, see the section \emph{"DataONE Environments"} in the overview vignette -by entering the R command: \code{vignette("dataone-overview")}. +identifiers, see the section \emph{"DataONE Environments"} in the overview vignette +by entering the R command: \code{vignette("v01-dataone-overview")}. } \examples{ \dontrun{ @@ -34,5 +34,5 @@ mn <- getMNode(cn, "urn:node:KNB") } } \seealso{ -\code{\link[=CNode-class]{CNode}}{ class description.} +\code{\link[=CNode-class]{CNode()}} class description. } diff --git a/man/getMNodeId.Rd b/man/getMNodeId.Rd index 5b24feb..abdad74 100644 --- a/man/getMNodeId.Rd +++ b/man/getMNodeId.Rd @@ -26,5 +26,5 @@ mn <- getMNodeId(cli) } } \seealso{ -\code{\link[=D1Client-class]{D1Client}}{ class description.} +\code{\link[=D1Client-class]{D1Client()}} class description. } diff --git a/man/getObject.Rd b/man/getObject.Rd index 2528f6b..d757e1c 100644 --- a/man/getObject.Rd +++ b/man/getObject.Rd @@ -42,5 +42,5 @@ df <- read.csv(text=rawToChar(obj)) } } \seealso{ -\code{\link{D1Node-class}{D1Node}}{ class description.} +\code{[D1Node-class]{D1Node}} class description. } diff --git a/man/getPackage.Rd b/man/getPackage.Rd index 2d214f4..be256f7 100644 --- a/man/getPackage.Rd +++ b/man/getPackage.Rd @@ -33,7 +33,7 @@ resource map, metadata file, data file, or any other package member.} The location of the package file downloaded from the member node. } \description{ -Given a valid identifier, download a file containing all of the package +Given a valid identifier, download a file containing all of the package members of the corresponding DataONE data package. } \details{ @@ -49,5 +49,5 @@ packageFileName <- getPackage(mn, id="resourceMap_Blandy.76.2") } } \seealso{ -\code{\link[=MNode-class]{MNode}}{ class description.} +\code{\link[=MNode-class]{MNode()}} class description. } diff --git a/man/getSystemMetadata.Rd b/man/getSystemMetadata.Rd index 1310188..9f4ad86 100644 --- a/man/getSystemMetadata.Rd +++ b/man/getSystemMetadata.Rd @@ -54,5 +54,5 @@ sysmeta <- getSystemMetadata(cn, pid) } } \seealso{ -\code{\link[=CNode-class]{CNode}}{ class description.} +\code{\link[=CNode-class]{CNode()}} class description. } diff --git a/man/hasReservation.Rd b/man/hasReservation.Rd index 96e8949..8f2120a 100644 --- a/man/hasReservation.Rd +++ b/man/hasReservation.Rd @@ -14,7 +14,7 @@ hasReservation(x, ...) \item{...}{Additional parameters.} -\item{pid}{The identifier that is being checked for existing as a reserved identifier or is in use as +\item{pid}{The identifier that is being checked for existing as a reserved identifier or is in use as an identifier for an existing object} \item{subject}{The subject of the principal (user) that made the reservation.} @@ -43,5 +43,5 @@ hasRes <- hasReservation(cn, pid, subject=subject) } } \seealso{ -\code{\link[=CNode-class]{CNode}}{ class description.} +\code{\link[=CNode-class]{CNode()}} class description. } diff --git a/man/isAuthValid.Rd b/man/isAuthValid.Rd index 54d91ea..4edc866 100644 --- a/man/isAuthValid.Rd +++ b/man/isAuthValid.Rd @@ -22,8 +22,8 @@ A logical value: TRUE if authentication is valid, false if not. \description{ The currently used DataONE client authentication method (either tokens or X.509 certificates) is checked and verified for the specified node (either CN or MN). If an authentication token is available -via the R options facility, it will be used i.e. available via getOption("dataone_token"). However, -authentication tokens can only be used for DataONE v2 or higher nodes. X.509 certificates can be used -with DataONE v1 or higher nodes. -See the \emph{"dataone"} vignette \emph{"dataone-overview"} for more information on authentication. +via the R options facility, it will be used i.e. available via getOption("dataone_token"). However, +authentication tokens can only be used for DataONE v2 or higher nodes. X.509 certificates can be used +with DataONE v1 or higher nodes. +See the \emph{"dataone"} vignette \emph{"v01-dataone-overview"} for more information on authentication. } diff --git a/man/isAuthorized.Rd b/man/isAuthorized.Rd index 31bb632..ae459a0 100644 --- a/man/isAuthorized.Rd +++ b/man/isAuthorized.Rd @@ -22,7 +22,7 @@ isAuthorized(x, ...) a logical, TRUE if the action is authorized, false if not. } \description{ -Test if the user identified by the provided token has +Test if the user identified by the provided token has authorization for operation on the specified object. } \details{ @@ -47,5 +47,5 @@ canChange <- isAuthorized(mn, pid, "changePermission") } } \seealso{ -\code{\link[=CNode-class]{CNode}}{ class description.} +\code{\link[=CNode-class]{CNode()}} class description. } diff --git a/man/isCertExpired.Rd b/man/isCertExpired.Rd index 7e434c7..2635bf6 100644 --- a/man/isCertExpired.Rd +++ b/man/isCertExpired.Rd @@ -19,7 +19,7 @@ TRUE if the certificate is expired } \description{ Returns \code{'TRUE'} if the certificate associated with a CertificateManager instance is expired. -A certificate is expired if any of the following conditions hold: 1) the current time is before or after the +A certificate is expired if any of the following conditions hold: 1) the current time is before or after the certificate validity dates, 2) the certificate is not valid according to a trusted Certificate Authority, or 3) no certificate can be found. } diff --git a/man/listFormats.Rd b/man/listFormats.Rd index 5b59d7a..7c1153f 100644 --- a/man/listFormats.Rd +++ b/man/listFormats.Rd @@ -18,7 +18,7 @@ listFormats(x, ...) Returns a dataframe of all object formats registered in the DataONE Object Format Vocabulary. } \description{ -The \link{listFormats} method queries a DataONE Coordinating Node for a +The \link{listFormats} method queries a DataONE Coordinating Node for a list of all entries in the Object Format Vocabulary. } \examples{ @@ -29,5 +29,5 @@ formats <- listFormats(cn) } } \seealso{ -\code{\link[=CNode-class]{CNode}}{ class description.} +\code{\link[=CNode-class]{CNode()}} class description. } diff --git a/man/listMemberNodes.Rd b/man/listMemberNodes.Rd index 9c9eb26..553989e 100644 --- a/man/listMemberNodes.Rd +++ b/man/listMemberNodes.Rd @@ -23,5 +23,5 @@ nodelist <- listMemberNodes(d1c) } } \seealso{ -\code{\link[=D1Client-class]{D1Client}}{ class description.} +\code{\link[=D1Client-class]{D1Client()}} class description. } diff --git a/man/listNodes.Rd b/man/listNodes.Rd index 0061260..ecf1320 100644 --- a/man/listNodes.Rd +++ b/man/listNodes.Rd @@ -30,5 +30,5 @@ nodeid <- nodelist[[2]]@identifier } } \seealso{ -\code{\link[=CNode-class]{CNode}}{ class description.} +\code{\link[=CNode-class]{CNode()}} class description. } diff --git a/man/obscureCert.Rd b/man/obscureCert.Rd index a8bff4e..00420bc 100644 --- a/man/obscureCert.Rd +++ b/man/obscureCert.Rd @@ -20,10 +20,10 @@ the modified CertificateManager instance \description{ Obscures the x509 certificate that CILogon installs, effectively making future interactions with the DataONE services public/anonymous. This function simple renames an -existing certificate file to a known location, allowing 'public' operations. Note, when the -client certificate is obscured via the renaming, you will not be able to create objects in +existing certificate file to a known location, allowing 'public' operations. Note, when the +client certificate is obscured via the renaming, you will not be able to create objects in DataONE, or utilize any other methods that require authentication. } \seealso{ -\code{\link{restoreCert}} is this method's inverse operation +\code{\link[=restoreCert]{restoreCert()}} is this method's inverse operation } diff --git a/man/query.Rd b/man/query.Rd index e81a2d8..30bc224 100644 --- a/man/query.Rd +++ b/man/query.Rd @@ -42,7 +42,7 @@ search results as a list, data.frame or XML document The DataONE search index is searched for data that matches the specified query parameters. } \details{ -The \code{"query"} method sends a query to a DataONE search index that uses the Apache Solr search +The \code{"query"} method sends a query to a DataONE search index that uses the Apache Solr search engine \url{https://solr.apache.org/}. This same Solr search engine is the underlying mechanism used by the DataONE online search tool available at \url{https://search.dataone.org/}. @@ -52,16 +52,16 @@ argument can be created as either a single character string containing the Solr or as a list of key value pairs: \code{solrQuery = list(q = "id:doi*", rows = "2", wt = "json")}. These two queries produce the same result. As an alternative to specifying the Solr query terms using the \code{"solrquery"} argument, the \code{"searchTerms"} argument -can be specified, which does not require any Solr syntax. This parameter is a list with query field / value pairs, i.e. +can be specified, which does not require any Solr syntax. This parameter is a list with query field / value pairs, i.e. \code{searchTerms=list(abstract=kelp, attribute=biomass)}. -The query fields can be listed for a DataONE node using \code{\link{getQueryEngineDescription}}. +The query fields can be listed for a DataONE node using \code{\link[=getQueryEngineDescription]{getQueryEngineDescription()}}. Either \code{"searchTerms"} or \code{"solrQuery"} must be specified. The \code{"as"} argument is used to specify the query result to be returned as: "json", xml", "list", "data.frame". The \code{"parsed"} argument, if specified as TRUE, causes the query result to be converted to appropriate R data types. -For example, if \code{ar = "xml"} and \code{parsed = TRUE}, then the query result is returned as an R XMLInternalDocument, or -If \code{'parsed = FALSE'} then a character variable with the XML string is returned. Specify \code{as = "list"} to have +For example, if \code{ar = "xml"} and \code{parsed = TRUE}, then the query result is returned as an R XMLInternalDocument, or +If \code{'parsed = FALSE'} then a character variable with the XML string is returned. Specify \code{as = "list"} to have the result parsed to an R list, with each list element containing one Solr query result of the total result set. } \examples{ diff --git a/man/reserveIdentifier.Rd b/man/reserveIdentifier.Rd index 3602387..73030f9 100644 --- a/man/reserveIdentifier.Rd +++ b/man/reserveIdentifier.Rd @@ -40,5 +40,5 @@ newId <- reserveIdentifier(cn, myId) } } \seealso{ -\code{\link[=CNode-class]{CNode}}{ class description.} +\code{\link[=CNode-class]{CNode()}} class description. } diff --git a/man/restoreCert.Rd b/man/restoreCert.Rd index 6a57519..deae86c 100644 --- a/man/restoreCert.Rd +++ b/man/restoreCert.Rd @@ -19,10 +19,10 @@ the modified CertificateManager instance } \description{ Restores the x509 certificate that CILogon installs, which allows future -interactions with nodes to be authenticated with the certificate. This function simply -renames an obscured certificate file to its original location, allowing authenticated +interactions with nodes to be authenticated with the certificate. This function simply +renames an obscured certificate file to its original location, allowing authenticated operations. } \seealso{ -\code{\link{obscureCert}} is this method's inverse operation +\code{\link[=obscureCert]{obscureCert()}} is this method's inverse operation } diff --git a/man/setMNodeId.Rd b/man/setMNodeId.Rd index f1eb596..aa36951 100644 --- a/man/setMNodeId.Rd +++ b/man/setMNodeId.Rd @@ -24,7 +24,7 @@ One Member Node can be associated with the client as the default to which data and metadata are written. } \seealso{ -\code{\link[=D1Client-class]{D1Client}}{ class description.} +\code{\link[=D1Client-class]{D1Client()}} class description. } \author{ setMNodeId diff --git a/man/setObsoletedBy.Rd b/man/setObsoletedBy.Rd index ad29e6f..efd6497 100644 --- a/man/setObsoletedBy.Rd +++ b/man/setObsoletedBy.Rd @@ -24,11 +24,9 @@ setObsoletedBy(x, pid, obsoletedByPid, ...) TRUE if the pid was obsoleted, otherwise FALSE is returned } \description{ -Updates the SystemMetadata 'obsoletedBy' property for an object, indicating that the object +Updates the SystemMetadata 'obsoletedBy' property for an object, indicating that the object specified by pid has been obsoleted by the identifier in obsoletedByPid. -CILogon \url{https://cilogon.org/?skin=DataONE}. See \code{\link{CertificateManager}} for details. -In DataONE version 2.0, authentication tokens can also be used. } \seealso{ -\code{\link[=CNode-class]{CNode}}{ class description.} +\code{\link[=CNode-class]{CNode()}} class description. } diff --git a/man/setPublicAccess.Rd b/man/setPublicAccess.Rd index 68df0f7..8341e81 100644 --- a/man/setPublicAccess.Rd +++ b/man/setPublicAccess.Rd @@ -13,13 +13,13 @@ D1Object with modified access rules } \description{ -This method should be called prior to creating the object in DataONE. -When called before +This method should be called prior to creating the object in DataONE. +When called before creating the object, adds a rule to the access policy that makes this object publicly readable. If called after creation, it will only change the system metadata locally, and will not have any effect on remotely uploaded copies of the D1Object. } \seealso{ -\code{\link[=DataObject-class]{DataObject}}{ class description.} +\code{\link[datapack:DataObject-class]{DataObject()}} class description. } diff --git a/man/updateObject.Rd b/man/updateObject.Rd index 526956c..b29f6ee 100644 --- a/man/updateObject.Rd +++ b/man/updateObject.Rd @@ -34,16 +34,13 @@ maintained, each with its own persistent identifier, and the 'obsoletes' field i used to reflect the fact that the new object replaces the old. Both objects remain accessible. } \details{ -In the version 2.0 library and higher, this operation can utilize an +In the version 2.0 library and higher, this operation can utilize an 'dataone_token' option to provide credentials for write operations in DataONE. The authentication token is obtained from DataONE (see your profile on https://search.dataone.org). -See the \code{vignette("dataone-overview")} for details. -Alternatively, the version 1.0 approach of using an X.509 certificate in a default location of the file -system can also be used. This certificate provides authentication credentials from -CILogon \url{https://cilogon.org/?skin=DataONE}. See \code{vignette("dataone-overview")} for details. +See the \code{vignette("v01-dataone-overview")} for details. } \note{ -Please see the vignette *upload-data* for an example: \code{vignette("upload-data")} +Please see the vignette \emph{v05-upload-data} for an example: \code{vignette("v05-upload-data")} } \seealso{ \url{https://purl.dataone.org/architecture/apis/MN_APIs.html#MNStorage.update} diff --git a/man/updateSystemMetadata.Rd b/man/updateSystemMetadata.Rd index 724fe25..b2a0ecd 100644 --- a/man/updateSystemMetadata.Rd +++ b/man/updateSystemMetadata.Rd @@ -28,16 +28,13 @@ updating the object that it describes, so that mutable attributes such as access can be updated easily. } \details{ -In the version 2.0 library and higher, this operation can utilize an +In the version 2.0 library and higher, this operation can utilize an 'dataone_token' option to provide credentials for write operations in DataONE. The authentication token is obtained from DataONE (see your profile on https://search.dataone.org). -See the \code{vignette("dataone-overview")} for details. -Alternatively, the version 1.0 approach of using an X.509 certificate in a default location of the file -system can also be used. This certificate provides authentication credentials from -CILogon \url{https://cilogon.org/?skin=DataONE}. See \code{vignette("dataone-overview")} for details. +See the \code{vignette("v01-dataone-overview")} for details. } \note{ -Please see the vignette *upload-data* for an example: \code{vignette("upload-data")} +Please see the vignette \emph{v05-upload-data} for an example: \code{vignette("v05-upload-data")} } \seealso{ \url{https://purl.dataone.org/architecture/apis/MN_APIs.html#MNStorage.updateSystemMetadata} diff --git a/man/uploadDataObject.Rd b/man/uploadDataObject.Rd index 253b403..4cdd54b 100644 --- a/man/uploadDataObject.Rd +++ b/man/uploadDataObject.Rd @@ -58,5 +58,5 @@ newId <- uploadDataObject(d1c, do, replicate=FALSE, preferredNodes=NA , public= } } \seealso{ -\code{\link[=D1Client-class]{D1Client}}{ class description.} +\code{\link[=D1Client-class]{D1Client()}} class description. } diff --git a/man/uploadDataPackage.Rd b/man/uploadDataPackage.Rd index e1caed7..d1203d5 100644 --- a/man/uploadDataPackage.Rd +++ b/man/uploadDataPackage.Rd @@ -41,7 +41,7 @@ uploadDataPackage(x, ...) \item{quiet}{A \code{'logical'}. If TRUE (the default) then informational messages will not be printed.} -\item{resolveURI}{A URI to prepend to identifiers (i.e. for use when creating the ResourceMap). See \link[datapack]{serializePackage}} +\item{resolveURI}{A URI to prepend to identifiers (i.e. for use when creating the ResourceMap). See \link[datapack:serializePackage]{serializePackage}} \item{packageId}{A value of type \code{"character"} specifying a unique identifier to use for the uploaded package (resource map pid)} @@ -51,20 +51,20 @@ uploadDataPackage(x, ...) id The identifier of the resource map for this data package } \description{ -Upload all DataObjects contained in the DataPackage by calling \code{\link{uploadDataObject}} +Upload all DataObjects contained in the DataPackage by calling \code{\link[=uploadDataObject]{uploadDataObject()}} on each of the members. Also a resourceMap object is created from the recorded relationships between DataObjects, and this is uploaded as well. } \details{ -The DataPackage describes the collection of data object and their associated +The DataPackage describes the collection of data object and their associated metadata object, with the relationships and members serialized into a document stored under, and retrievable with, the packageId as it's own distinct object. -Any objects in the data map that have a dateUploaded value are assumed to be +Any objects in the data map that have a dateUploaded value are assumed to be pre-existing in the system, and skipped. } \note{ -Member objects are created serially, and most errors in creating one object will -interrupt the create process for the whole, with the result that some members will +Member objects are created serially, and most errors in creating one object will +interrupt the create process for the whole, with the result that some members will be created, and the remainder not. } \examples{ @@ -85,5 +85,5 @@ packageId <- uploadDataPackage(d1c, dp, replicate=TRUE, public=TRUE, numberRepli } } \seealso{ -\code{\link[=D1Client-class]{D1Client}}{ class description.} +\code{\link[=D1Client-class]{D1Client()}} class description. } diff --git a/tests/testthat/test.AuthenticationManager.R b/tests/testthat/test.AuthenticationManager.R index a52a15a..2171387 100644 --- a/tests/testthat/test.AuthenticationManager.R +++ b/tests/testthat/test.AuthenticationManager.R @@ -67,14 +67,12 @@ test_that("isCertExpired() works", { suppressMessages(authValid <- dataone:::isAuthValid(am, cn)) if(authValid) { expDate <- dataone:::getAuthExpires(am, cn) - # TODO: check token exp date when JWT available. - #ct <- format(Sys.time(), format="%F %H:%M:%S GMT", tz="UTC") - ct <- as.POSIXct(Sys.time(), tz="GMT") + ct <- as.POSIXct(Sys.time(), tz=format(expDate, "%Z")) if(!is.na(expDate) && !is.null(expDate)) { if(dataone:::isAuthExpired(am, cn)) { expect_true(expDate > ct) } else { - expect_false(expDate < ct) + expect_false(expDate < ct) } } }