new DataONEService()
Extensible base class for DataONE API services, e.g. the System Metadata
service. It includes in-memory and persistent caching scoped by user
authentication, deduplication of in-flight requests handled by the
DataONEHttpClient, and utility methods for making requests. This class
always uses singleton instances of DataONEHttpClient and PersistentStorage
to ensure that deduplication and caching work properly across all service
instances with the same configuration.
- Since:
- Source:
Methods
clearCache() → {Promise.<void>}
Clear the cache for the current user scope.
- Source:
Returns:
Promise resolving when the cache is cleared.
-
Type
-
Promise.<void>
download(path, optionsopt) → {Promise.<*>}
Download data from a path with optional caching.
Parameters:
| Name |
Type |
Attributes |
Description |
path |
string
|
|
Path relative to baseUrl. |
options |
object
|
<optional>
|
Options passed to
DataONEHttpClient#request (except `path`), plus cache controls.
Properties
| Name |
Type |
Attributes |
Description |
auth |
boolean
|
<optional>
|
Whether to resolve a token automatically. |
useCache |
boolean
|
<optional>
|
Whether to cache responses, default
true. |
cacheKey |
string
|
<optional>
|
Cache key override. |
cacheTtlMs |
number
|
null
|
<optional>
|
Cache TTL override. |
|
- Source:
Returns:
Promise resolving to response data.
-
Type
-
Promise.<*>
getCached(key) → {Promise.<*>}
Get a cached value scoped by the current user.
Parameters:
| Name |
Type |
Description |
key |
string
|
Cache key. |
- Source:
Returns:
Promise resolving to the cached value.
-
Type
-
Promise.<*>
Get a PersistentStorage instance automatically scoped by the logged in
user, using the configuration options provided to the constructor.
- Source:
Returns:
Storage instance.
-
Type
-
PersistentStorage
getToken() → {Promise.<string>}
Resolve an auth token from MetacatUI when available.
- Source:
Returns:
Promise resolving to an auth token.
-
Type
-
Promise.<string>
getUserName() → {Promise.<(string|null)>}
Resolve the current username from the MetacatUI app user model.
- Source:
Returns:
Promise resolving to the username, or
null if unavailable.
-
Type
-
Promise.<(string|null)>
isCached(key) → {Promise.<boolean>}
Check whether a value exists in the cache for the current user scope.
Parameters:
| Name |
Type |
Description |
key |
string
|
Cache key. |
- Source:
Returns:
Promise resolving to whether the value is
cached.
-
Type
-
Promise.<boolean>
removeCached(key) → {Promise.<void>}
Remove a cached value for the current user scope.
Parameters:
| Name |
Type |
Description |
key |
string
|
Cache key. |
- Source:
Returns:
Promise resolving when removal completes.
-
Type
-
Promise.<void>
Send a request via the DataONEHttpClient.
Parameters:
| Name |
Type |
Attributes |
Description |
options |
object
|
<optional>
|
Request options passed to
DataONEHttpClient#request, plus auth controls.
Properties
| Name |
Type |
Attributes |
Description |
path |
string
|
|
Path relative to baseUrl. |
auth |
boolean
|
<optional>
|
Whether to resolve a token automatically. |
|
- Source:
Returns:
Promise resolving to the
response.
-
Type
-
Promise.<DataONEHttpResponse>
resolveToken(authopt) → {Promise.<(string|null)>}
Determine the token to use, if any, for a request.
Parameters:
| Name |
Type |
Attributes |
Description |
auth |
boolean
|
<optional>
|
Whether to use authentication for this request.
If set to false, no token will be used. If true, getToken() will be
called. When undefined, defaultAuth is used. |
- Source:
Returns:
Promise resolving to the token, or null
if no auth.
-
Type
-
Promise.<(string|null)>
scopeKey() → {Promise.<string>}
If user is logged in, get a key based on their username; otherwise,
return a "public" scope key.
- Source:
Returns:
Promise resolving to the scope key.
-
Type
-
Promise.<string>
setCached(key, value, optionsopt) → {Promise.<*>}
Store a value in the cache for the current user scope.
Parameters:
| Name |
Type |
Attributes |
Description |
key |
string
|
|
Cache key. |
value |
*
|
|
Value to store. |
options |
object
|
<optional>
|
Cache scope options.
Properties
| Name |
Type |
Attributes |
Description |
ttlMs |
number
|
null
|
<optional>
|
Override cache TTL in ms. |
|
- Source:
Returns:
Promise resolving to the stored value.
-
Type
-
Promise.<*>
shouldUseCache() → {Promise.<boolean>}
Determine whether caching is allowed for the current user scope.
- Source:
Returns:
Promise resolving to whether caching is
allowed.
-
Type
-
Promise.<boolean>
upload(path, optionsopt) → {Promise.<DataONEHttpResponse>}
Upload data to a path.
Parameters:
| Name |
Type |
Attributes |
Description |
path |
string
|
|
Path relative to baseUrl. |
options |
object
|
<optional>
|
Options passed to
DataONEHttpClient#request (except `path`), plus cache controls.
Properties
| Name |
Type |
Attributes |
Description |
auth |
boolean
|
<optional>
|
Whether to resolve a token automatically. |
cacheKey |
string
|
<optional>
|
Cache key override. |
|
- Source:
Returns:
Promise resolving to the
response.
-
Type
-
Promise.<DataONEHttpResponse>
awaitUserModel() → {Promise.<Backbone.Model>}
Wait for the MetacatUI app user model to be available, and return it.
- Source:
Returns:
Promise resolving to the user model.
-
Type
-
Promise.<Backbone.Model>
normalizeOptions(options) → {object}
Normalize the options used to construct a new instance.
Parameters:
| Name |
Type |
Description |
options |
object
|
Options paseed to the constructor. |
- Source:
Returns:
Normalized options.
-
Type
-
object
resolveCacheKey(path, cacheKeyopt) → {string}
Use the path as the cache key by default, but allow an override if
desired.
Parameters:
| Name |
Type |
Attributes |
Description |
path |
string
|
|
Path relative to baseUrl. |
cacheKey |
string
|
null
|
undefined
|
<optional>
|
Cache key override. |
- Source:
Returns:
Resolved cache key.
-
Type
-
string