refresh: Methods for 'dsmz_keycloak' objects

In BacDive: API Client for BacDive

Methods for ‘dsmz_keycloak’ objects

Description

This package uses ‘dsmz_keycloak’ objects for managing the access to the API services provided by DSMZ.

Usage

  refresh(object, ...)

  ## S3 method for class 'dsmz_keycloak'
 refresh(object, self = TRUE,
    ...)

  ## S3 method for class 'dsmz_keycloak'
 summary(object, ...)

  ## S3 method for class 'dsmz_keycloak'
 print(x, ...)

  retrieve(object, ...)

  ## S3 method for class 'dsmz_keycloak'
 retrieve(object, ...,
    handler = NULL, sleep = 0.5)

Arguments

object	Object of class ‘dsmz_keycloak’.
self	Logical vector of length 1 indicating whether object should itself be modified or a new object returned.
x	Object of class ‘dsmz_keycloak’.
handler	If empty, ignored. Otherwise a function to which each data chunk retrieved from the API is transferred in turn. The function should accept a single argument. retrieve and the handler function may thus best be called within a dedicated enclosing function.
sleep	A waiting period in seconds between successive API requests, if any.
...	Optional arguments passed to other methods.

Details

The actual usage of ‘dsmz_keycloak’ objects is demonstrated by querying a DSMZ API. See the examples for the according functions.

When generating a ‘dsmz_keycloak’ object, the package responds to a system environment variable called ‘DSMZ_API_VERBOSE’. Its primary interpretation is as an integer number. Non-empty values of ‘DSMZ_API_VERBOSE’ that cannot be interpreted as an integer number are treated like 1; the empty character string is treated like 0.

When downloading data from the API, a verbosity of 1 means that the URL of each API request is output; when 2 or larger, more intermediary results may be shown.

Value

refresh returns a new or modified ‘dsmz_keycloak’ object if object still permits refreshing. It is supposed to do so if ‘refresh_expired’ is FALSE, if otherwise an error results.

Refreshing is supposed to be necessary if ‘expired’ is TRUE (although the local estimate may deviate from the actions of the server). Both values are given by summary, which returns a logical vector.

The print method returns x, invisibly.

retrieve combines the functionality of request, fetch and upgrade to download all entries found in the API, traversing all chunks of a paginated result in turn. The resulting list (of class ‘records’) may be huge, hence care should be taken. It may be advisable to use handler. If this function is given, each chunk is passed to handler in turn. The handler function could then store the data in a database or in a file. If handler is given, the number of its calls is returned.

References

https://www.keycloak.org/

https://www.dsmz.de/privacy-statement

See Also

Other common.functions: as.data.frame.dsmz_result, as.data.frame.records, print.dsmz_result, print.records, records, summary.dsmz_result, summary.records

Examples

## Examples are deliberately not given here.

BacDive documentation built on April 29, 2022, 3 a.m.