Package nl.knaw.dans.lib.dataverse

Class DatasetApi

java.lang.Object

nl.knaw.dans.lib.dataverse.DatasetApi

public class DatasetApi
extends Object

API end-points dealing with a single dataset.

See Also:

• Dataverse documentation

Field Summary

Fields

Modifier and Type	Field	Description
protected final Map<String,String>	extraHeaders
protected final nl.knaw.dans.lib.dataverse.HttpClientWrapper	httpClientWrapper
protected final String	id
protected static final String	invocationIdHeaderName
protected final boolean	isPersistentId
protected static final String	MDKEY_PARAM_NAME_PREFIX
protected static final String	persistendId
protected static final String	publish
protected final Path	targetBase

Method Summary

Modifier and Type	Method	Description
DataverseHttpResponse<FileList>	addFile(Path file, String metadata)
DataverseHttpResponse<FileList>	addFile(Path file, FileMeta fileMeta)
DataverseHttpResponse<RoleAssignmentReadOnly>	assignRole(String roleAssignment)
DataverseHttpResponse<RoleAssignmentReadOnly>	assignRole(RoleAssignment roleAssignment)
void	awaitLock(String lockType)	The same as awaitLock(String, int, int) but with defaults for number of tries and time between tries.
void	awaitLock(String lockType, int maxNumberOfRetries, int waitTimeInMilliseconds)	Utility function that lets you wait until a specified lock type is set.
void	awaitUnlock()	The same
void	awaitUnlock(int maxNumberOfRetries, int waitTimeInMilliseconds)	Utility function that lets you wait until all locks are cleared before proceeding.
protected Path	buildPath(Path base, String... components)
DataverseHttpResponse<DataMessage>	deleteDraft()
DataverseHttpResponse<DataMessage>	deleteRoleAssignment(int roleAssignmentId)
DataverseHttpResponse<DatasetVersion>	editMetadata(String s)	Edits the current draft's metadata, adding the fields that do not exist yet.
DataverseHttpResponse<DatasetVersion>	editMetadata(String s, Boolean replace)	Edits the current draft's metadata, adding the fields that do not exist yet.
DataverseHttpResponse<DatasetVersion>	editMetadata(String s, Boolean replace, Map<String,String> metadataKeys)	Edits the current draft's metadata, adding the fields that do not exist yet.
DataverseHttpResponse<DatasetVersion>	editMetadata(String s, Map<String,String> metadataKeys)	Edits the current draft's metadata, adding the fields that do not exist yet.
DataverseHttpResponse<DatasetVersion>	editMetadata(FieldList fields)	Edits the current draft's metadata, adding the fields that do not exist yet.
DataverseHttpResponse<DatasetVersion>	editMetadata(FieldList fields, Boolean replace)	Edits the current draft's metadata, adding the fields that do not exist yet.
DataverseHttpResponse<DatasetVersion>	editMetadata(FieldList fields, Boolean replace, Map<String,String> metadataKeys)	Edits the current draft's metadata, adding the fields that do not exist yet.
DataverseHttpResponse<DatasetVersion>	editMetadata(FieldList fields, Map<String,String> metadataKeys)	Edits the current draft's metadata, adding the fields that do not exist yet.
DataverseHttpResponse<List<DatasetVersion>>	getAllVersions()
DataverseHttpResponse<List<FileMeta>>	getFiles(String version)
DataverseHttpResponse<DatasetLatestVersion>	getLatestVersion()
DataverseHttpResponse<List<Lock>>	getLocks()
protected Map<String,List<String>>	getQueryParamsFromMetadataKeys(Map<String,String> metadataKeys)
DataverseHttpResponse<DatasetVersion>	getVersion()	Retrieves that latest version of a dataset.
DataverseHttpResponse<DatasetVersion>	getVersion(String version)
DataverseHttpResponse<List<RoleAssignmentReadOnly>>	listRoleAssignments()
protected Map<String,List<String>>	params(Map<String,List<String>> queryParams)
DataverseHttpResponse<DatasetPublicationResult>	publish()
DataverseHttpResponse<DataMessage>	publish(UpdateType updateType, boolean assureIsIndexed)
DataverseHttpResponse<DatasetPublicationResult>	releaseMigrated(String publicationDateJsonLd, boolean assureIsIndexed)
DataverseHttpResponse<HashMap>	setEmbargo(String json)
DataverseHttpResponse<HashMap>	setEmbargo(Embargo embargo)
DataverseHttpResponse<HashMap>	setRetentionPeriod(String json)
DataverseHttpResponse<HashMap>	setRetentionPeriod(RetentionPeriod retentionPeriod)
DataverseHttpResponse<SubmitForReviewResult>	submitForReview()
protected Path	subPath(String endPoint)
String	toString()
DataverseHttpResponse<DatasetVersion>	updateMetadata(String s)
DataverseHttpResponse<DatasetVersion>	updateMetadata(String s, Map<String,String> metadataKeys)
DataverseHttpResponse<DatasetVersion>	updateMetadata(DatasetVersion version)	Note that not all the attributes of the DatasetVersion object are writable.
DataverseHttpResponse<DatasetVersion>	updateMetadata(DatasetVersion version, Map<String,String> metadataKeys)
DataverseHttpResponse<Object>	updateMetadataFromJsonLd(String metadata, boolean replace)
DataverseHttpResponse<Object>	updateMetadataFromJsonLd(String metadata, boolean replace, Map<String,String> metadataKeys)
protected Path	versionedSubPath(String endPoint, String version)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details

persistendId

protected static final String persistendId

See Also:

• Constant Field Values

publish

protected static final String publish

See Also:

• Constant Field Values

invocationIdHeaderName

protected static final String invocationIdHeaderName

See Also:

• Constant Field Values

targetBase

protected final Path targetBase

id

protected final String id

isPersistentId

protected final boolean isPersistentId

extraHeaders

protected final Map<String,String> extraHeaders

MDKEY_PARAM_NAME_PREFIX

protected static final String MDKEY_PARAM_NAME_PREFIX

See Also:

• Constant Field Values

httpClientWrapper

protected final nl.knaw.dans.lib.dataverse.HttpClientWrapper httpClientWrapper

Method Details

toString

public String toString()

Overrides:

toString in class Object

getLatestVersion

public DataverseHttpResponse<DatasetLatestVersion> getLatestVersion()
                                                             throws IOException,
DataverseException

Returns:

a JSON object that starts at the dataset level, most fields are replicated at the dataset version level.

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

getVersion

public DataverseHttpResponse<DatasetVersion> getVersion()
                                                 throws IOException,
DataverseException

Retrieves that latest version of a dataset. The difference with getLatestVersion() is that the latter returns a different type of object. It is not clear why these variants exist.

Returns:

object containing the dataset version metadata

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

getVersion

public DataverseHttpResponse<DatasetVersion> getVersion(String version)
                                                 throws IOException,
DataverseException

Parameters:

version - version to retrieve

Returns:

object containing the dataset version metadata

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

getAllVersions

public DataverseHttpResponse<List<DatasetVersion>> getAllVersions()
                                                           throws IOException,
DataverseException

Returns:

list of objects containing dataset version metadata

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

getFiles

public DataverseHttpResponse<List<FileMeta>> getFiles(String version)
                                               throws IOException,
DataverseException

Parameters:

version - version to get file metadata from

Returns:

a list of file metas

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

publish

public DataverseHttpResponse<DatasetPublicationResult> publish()
                                                        throws IOException,
DataverseException

Returns:

dataset publication result

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

publish

public DataverseHttpResponse<DataMessage> publish(UpdateType updateType,
 boolean assureIsIndexed)
                                           throws IOException,
DataverseException

Parameters:

updateType - major or minor version update

assureIsIndexed - To make sure that indexing has already happened the `assureIsIndexed` is set to `true`, it will then cause Dataverse to fail fast if indexing is still pending. In this case the publish request will be retried a number of times.

Returns:

dataset publication result

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

releaseMigrated

public DataverseHttpResponse<DatasetPublicationResult> releaseMigrated(String publicationDateJsonLd,
 boolean assureIsIndexed)
                                                                throws IOException,
DataverseException

Throws:

IOException

DataverseException

editMetadata

public DataverseHttpResponse<DatasetVersion> editMetadata(String s)
                                                   throws IOException,
DataverseException

Edits the current draft's metadata, adding the fields that do not exist yet. If `replace` is set to `false`, all specified fields must be either currently empty or allow multiple values.

Parameters:

s - JSON document containing the edits to perform

Returns:

DatasetVersion

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

editMetadata

public DataverseHttpResponse<DatasetVersion> editMetadata(String s,
 Map<String,String> metadataKeys)
                                                   throws IOException,
DataverseException

Edits the current draft's metadata, adding the fields that do not exist yet. If `replace` is set to `false`, all specified fields must be either currently empty or allow multiple values.

Parameters:

s - JSON document containing the edits to perform

metadataKeys - the HashMap maps the names of the metadata blocks to their 'secret' key values.

Returns:

DatasetVersion

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

editMetadata

public DataverseHttpResponse<DatasetVersion> editMetadata(String s,
 Boolean replace)
                                                   throws IOException,
DataverseException

Edits the current draft's metadata, adding the fields that do not exist yet. If `replace` is set to `false`, all specified fields must be either currently empty or allow multiple values.

Parameters:

s - JSON document containing the edits to perform

replace - whether to replace existing values

Returns:

DatasetVersion

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

editMetadata

public DataverseHttpResponse<DatasetVersion> editMetadata(String s,
 Boolean replace,
 Map<String,String> metadataKeys)
                                                   throws IOException,
DataverseException

Edits the current draft's metadata, adding the fields that do not exist yet. If `replace` is set to `false`, all specified fields must be either currently empty or allow multiple values. Whenever there are metadata field from a block that is protected by a 'key', the corresponding keys must be provided.

Parameters:

s - JSON document containing the edits to perform

replace - whether to replace existing values

metadataKeys - the HashMap maps the names of the metadata blocks to their 'secret' key values.

Returns:

DatasetVersion

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

editMetadata

public DataverseHttpResponse<DatasetVersion> editMetadata(FieldList fields,
 Boolean replace)
                                                   throws IOException,
DataverseException

Edits the current draft's metadata, adding the fields that do not exist yet. If `replace` is set to `false`, all specified fields must be either currently empty or allow multiple values.

Parameters:

fields - list of fields to edit

replace - whether to replace existing values

Returns:

DatasetVersion

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

editMetadata

public DataverseHttpResponse<DatasetVersion> editMetadata(FieldList fields,
 Boolean replace,
 Map<String,String> metadataKeys)
                                                   throws IOException,
DataverseException

Edits the current draft's metadata, adding the fields that do not exist yet. If `replace` is set to `false`, all specified fields must be either currently empty or allow multiple values.

Parameters:

fields - list of fields to edit

replace - whether to replace existing values

metadataKeys - the HashMap maps the names of the metadata blocks to their 'secret' key values.

Returns:

DatasetVersion

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

editMetadata

public DataverseHttpResponse<DatasetVersion> editMetadata(FieldList fields)
                                                   throws IOException,
DataverseException

Edits the current draft's metadata, adding the fields that do not exist yet.

Parameters:

fields - list of fields to edit

Returns:

DatasetVersion

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

editMetadata

public DataverseHttpResponse<DatasetVersion> editMetadata(FieldList fields,
 Map<String,String> metadataKeys)
                                                   throws IOException,
DataverseException

Edits the current draft's metadata, adding the fields that do not exist yet.

Parameters:

fields - list of fields to edit

metadataKeys - the HashMap maps the names of the metadata blocks to their 'secret' key values.

Returns:

DatasetVersion

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

updateMetadataFromJsonLd

public DataverseHttpResponse<Object> updateMetadataFromJsonLd(String metadata,
 boolean replace)
                                                       throws IOException,
DataverseException

Parameters:

metadata - JSON document describing the metadata

replace - replace existing metadata

Returns:

a generic DataverseHttpResponse

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

updateMetadataFromJsonLd

public DataverseHttpResponse<Object> updateMetadataFromJsonLd(String metadata,
 boolean replace,
 Map<String,String> metadataKeys)
                                                       throws IOException,
DataverseException

Parameters:

metadata - JSON document describing the metadata

replace - replace existing metadata

metadataKeys - maps the names of the metadata blocks to their 'secret' key values

Returns:

a generic DataverseResponse

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

updateMetadata

public DataverseHttpResponse<DatasetVersion> updateMetadata(String s)
                                                     throws IOException,
DataverseException

Parameters:

s - JSON document containing the new metadata

Returns:

DatasetVersion

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

updateMetadata

public DataverseHttpResponse<DatasetVersion> updateMetadata(String s,
 Map<String,String> metadataKeys)
                                                     throws IOException,
DataverseException

Parameters:

s - JSON document containing the new metadata

metadataKeys - maps the names of the metadata blocks to their 'secret' key values

Returns:

DatasetVersion

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

updateMetadata

public DataverseHttpResponse<DatasetVersion> updateMetadata(DatasetVersion version)
                                                     throws IOException,
DataverseException

Note that not all the attributes of the DatasetVersion object are writable. Dataverse may ignore some (e.g., license) or return an error if some are filled in (e.g., files). However, for a few attributes, such as fileAccessRequest and termsOfAccess, it is necessary to pass the whole version object instead of only the metadata blocks (as is done in the example of the API documentation).

Parameters:

version - a version object containing the new metadata

Returns:

DatasetVersion

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

updateMetadata

public DataverseHttpResponse<DatasetVersion> updateMetadata(DatasetVersion version,
 Map<String,String> metadataKeys)
                                                     throws IOException,
DataverseException

Parameters:

version - a version object containing the new metadata

metadataKeys - maps the names of the metadata blocks to their 'secret' key values

Returns:

DatasetVersion

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

deleteDraft

public DataverseHttpResponse<DataMessage> deleteDraft()
                                               throws IOException,
DataverseException

Returns:

a data message

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

listRoleAssignments

public DataverseHttpResponse<List<RoleAssignmentReadOnly>> listRoleAssignments()
                                                                        throws IOException,
DataverseException

Returns:

role assignment information

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

assignRole

public DataverseHttpResponse<RoleAssignmentReadOnly> assignRole(String roleAssignment)
                                                         throws IOException,
DataverseException

Parameters:

roleAssignment - JSON document describing the assignment

Returns:

role assignment information

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

assignRole

public DataverseHttpResponse<RoleAssignmentReadOnly> assignRole(RoleAssignment roleAssignment)
                                                         throws IOException,
DataverseException

Throws:

IOException

DataverseException

deleteRoleAssignment

public DataverseHttpResponse<DataMessage> deleteRoleAssignment(int roleAssignmentId)
                                                        throws IOException,
DataverseException

Parameters:

roleAssignmentId - Delete the assignment with this id

Returns:

A data information message

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

addFile

public DataverseHttpResponse<FileList> addFile(Path file,
 String metadata)
                                        throws IOException,
DataverseException

Parameters:

file - the file to add

metadata - json document with the file metadata

Returns:

a file list

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

addFile

public DataverseHttpResponse<FileList> addFile(Path file,
 FileMeta fileMeta)
                                        throws IOException,
DataverseException

Parameters:

file - the file to add

fileMeta - json document with the file metadata

Returns:

a file list

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

submitForReview

public DataverseHttpResponse<SubmitForReviewResult> submitForReview()
                                                             throws IOException,
DataverseException

Returns:

todo

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

setEmbargo

public DataverseHttpResponse<HashMap> setEmbargo(Embargo embargo)
                                          throws IOException,
DataverseException

Parameters:

embargo - the embargo data

Returns:

a hash map

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• Dataverse documentation

setEmbargo

public DataverseHttpResponse<HashMap> setEmbargo(String json)
                                          throws IOException,
DataverseException

Throws:

IOException

DataverseException

setRetentionPeriod

public DataverseHttpResponse<HashMap> setRetentionPeriod(RetentionPeriod retentionPeriod)
                                                  throws IOException,
DataverseException

Parameters:

retentionPeriod - the retention period data

Returns:

a hash map

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

setRetentionPeriod

public DataverseHttpResponse<HashMap> setRetentionPeriod(String json)
                                                  throws IOException,
DataverseException

Throws:

IOException

DataverseException

getLocks

public DataverseHttpResponse<List<Lock>> getLocks()
                                           throws IOException,
DataverseException

Returns:

a list of locks

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

See Also:

• ...
• Code example

awaitUnlock

public void awaitUnlock(int maxNumberOfRetries,
 int waitTimeInMilliseconds)
                 throws IOException,
DataverseException

Utility function that lets you wait until all locks are cleared before proceeding. Unlike most other functions in this library, this does not correspond directly with an API call. Rather the getLocks() call is done repeatedly to check if the locks have been cleared. Note that in scenarios where concurrent processes might access the same dataset it is not guaranteed that the locks, once cleared, stay that way.

Parameters:

maxNumberOfRetries - the maximum number the check for unlock is made, defaults to [[awaitLockStateMaxNumberOfRetries]]

waitTimeInMilliseconds - the time between tries, defaults to [[awaitLockStateMillisecondsBetweenRetries]]

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

awaitUnlock

public void awaitUnlock()
                 throws IOException,
DataverseException

The same

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

awaitLock

public void awaitLock(String lockType,
 int maxNumberOfRetries,
 int waitTimeInMilliseconds)
               throws IOException,
DataverseException

Utility function that lets you wait until a specified lock type is set. Unlike most other functions in this library, this does not correspond directly with an API call. Rather the getLocks() call is done repeatedly to check if the locks has been set. A use case is when an http/sr workflow wants to make sure that a dataset has been locked on its behalf, so that it can be sure to have exclusive access via its invocation ID.

Parameters:

lockType - the lock type to wait for

maxNumberOfRetries - the maximum number the check for unlock is made, defaults to #awawaitLockStateMaxNumberOfRetries

waitTimeInMilliseconds - the time between tries, defaults to [[awaitLockStateMillisecondsBetweenRetries]]

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

awaitLock

public void awaitLock(String lockType)
               throws IOException,
DataverseException

The same as awaitLock(String, int, int) but with defaults for number of tries and time between tries.

Parameters:

lockType - the lock type to wait for

Throws:

IOException - when I/O problems occur during the interaction with Dataverse

DataverseException - when Dataverse fails to perform the request

params

protected Map<String,List<String>> params(Map<String,List<String>> queryParams)

subPath

protected Path subPath(String endPoint)

versionedSubPath

protected Path versionedSubPath(String endPoint,
 String version)

buildPath

protected Path buildPath(Path base,
 String... components)

getQueryParamsFromMetadataKeys

protected Map<String,List<String>> getQueryParamsFromMetadataKeys(Map<String,String> metadataKeys)