pt.ptcris.utils

Class ORCIDHelper

java.lang.Object

pt.ptcris.utils.ORCIDHelper

public class ORCIDHelper
extends java.lang.Object

An helper to simplify the use of the low-level ORCID client. Provides support for asynchronous communication with ORCID although it is only active for GET requests due to resource limitations.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ORCIDHelper.EIdType

Field Summary

Fields

Modifier and Type	Field and Description
ORCIDClient	client The client used to communicate with ORCID.
static java.lang.String	INVALID_EXTERNALIDENTIFIERS
static java.lang.String	INVALID_PUBLICATIONDATE
static java.lang.String	INVALID_TITLE
static java.lang.String	INVALID_TYPE
static java.lang.String	INVALID_YEAR

Constructor Summary

Constructors

Constructor and Description
ORCIDHelper(ORCIDClient orcidClient) Initializes the helper with a given ORCID client.

Method Summary

Modifier and Type	Method and Description
java.math.BigInteger	addWork(org.um.dsi.gavea.orcid.model.work.Work work) Synchronously adds a work to an ORCID profile.
static org.um.dsi.gavea.orcid.model.work.Work	clone(org.um.dsi.gavea.orcid.model.work.Work work) Clones a work summary.
static org.um.dsi.gavea.orcid.model.work.WorkSummary	clone(org.um.dsi.gavea.orcid.model.work.WorkSummary work) Clones a work summary.
void	deleteAllSourcedWorks() Deletes the entire set of work summaries in the ORCID profile whose source is the Member API id defined in the ORCID client.
void	deleteWork(java.math.BigInteger putcode) Synchronously deletes a work in an ORCID profile.
static java.math.BigInteger	getActivityLocalKey(org.um.dsi.gavea.orcid.model.common.ElementSummary act) Retrieves the local key of an activity, currently assumed to be stored in the put-code field.
java.util.List<org.um.dsi.gavea.orcid.model.work.WorkSummary>	getAllWorkSummaries() Retrieves the entire set of work summaries from the set ORCID profile that have at least an external identifier set.
static java.util.Map<org.um.dsi.gavea.orcid.model.work.Work,ExternalIdsDiff>	getExternalIdsDiff(org.um.dsi.gavea.orcid.model.work.WorkSummary work, java.util.Collection<org.um.dsi.gavea.orcid.model.work.Work> works) Calculates the symmetric difference of external identifiers between a work and a set of works.
org.um.dsi.gavea.orcid.model.work.Work	getFullWork(org.um.dsi.gavea.orcid.model.work.WorkSummary mergedWork) Synchronously gets a full work from an ORCID profile.
void	getFullWork(org.um.dsi.gavea.orcid.model.work.WorkSummary mergedWork, java.util.Map<java.math.BigInteger,java.lang.Object> cb) Asynchronously gets a full work from an ORCID profile.
java.util.List<org.um.dsi.gavea.orcid.model.work.WorkSummary>	getSourcedWorkSummaries() Retrieves the entire set of work summaries in the ORCID profile whose source is the Member API id defined in the ORCID client.
static boolean	hasNewIDs(org.um.dsi.gavea.orcid.model.work.Work preWork, org.um.dsi.gavea.orcid.model.work.WorkSummary posWork) Checks whether a work is already up to date regarding another one, i.e., whether a work has the same external identifiers as another one.
static boolean	isUpToDate(org.um.dsi.gavea.orcid.model.work.Work preWork, org.um.dsi.gavea.orcid.model.work.Work posWork) Checks whether a work is already up to date regarding another one, considering the external identifiers and additional meta-data.
static boolean	isUpToDate(org.um.dsi.gavea.orcid.model.work.Work preWork, org.um.dsi.gavea.orcid.model.work.WorkSummary posWork) Checks whether a work is already up to date regarding another one, considering the external identifiers and additional meta-data.
static void	setWorkLocalKey(org.um.dsi.gavea.orcid.model.common.ElementSummary act, java.math.BigInteger key) Retrieves the local key of an activity, currently assumed to be stored in the put-code field.
static java.util.Set<java.lang.String>	testMinimalQuality(org.um.dsi.gavea.orcid.model.work.Work work) Tests whether a work has minimal quality to be synchronized, by inspecting its meta-data, returns the detected invalid fields.
static java.util.Set<java.lang.String>	testMinimalQuality(org.um.dsi.gavea.orcid.model.work.WorkSummary work) Tests whether a work has minimal quality to be synchronized, by inspecting its meta-data, returns the detected invalid fields.
static void	tryMinimalQuality(org.um.dsi.gavea.orcid.model.work.Work work) Tests whether a work has minimal quality to be synchronized, by inspecting its meta-data.
static void	tryMinimalQuality(org.um.dsi.gavea.orcid.model.work.WorkSummary work) Tests whether a work has minimal quality to be synchronized, by inspecting its meta-data.
void	updateWork(java.math.BigInteger remotePutcode, org.um.dsi.gavea.orcid.model.work.Work updatedWork) Synchronously updates a work in an ORCID profile.
boolean	waitWorkers() Waits for all active asynchronous workers communicating with ORCID to finish (if multi-threading is enabled, otherwise it is always true).

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

INVALID_EXTERNALIDENTIFIERS

public static final java.lang.String INVALID_EXTERNALIDENTIFIERS

See Also:

Constant Field Values

INVALID_TITLE

public static final java.lang.String INVALID_TITLE

See Also:

Constant Field Values

INVALID_PUBLICATIONDATE

public static final java.lang.String INVALID_PUBLICATIONDATE

See Also:

Constant Field Values

INVALID_YEAR

public static final java.lang.String INVALID_YEAR

See Also:

Constant Field Values

INVALID_TYPE

public static final java.lang.String INVALID_TYPE

See Also:

Constant Field Values

client

public final ORCIDClient client

The client used to communicate with ORCID. Defines the ORCID user profile being managed and the Member API id being user to source works.

Constructor Detail

ORCIDHelper

public ORCIDHelper(ORCIDClient orcidClient)

Initializes the helper with a given ORCID client.

Parameters:

orcidClient - the ORCID client

Method Detail

getAllWorkSummaries

public java.util.List<org.um.dsi.gavea.orcid.model.work.WorkSummary> getAllWorkSummaries()
                                                                                  throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException

Retrieves the entire set of work summaries from the set ORCID profile that have at least an external identifier set. Merges each ORCID group into a single summary, following groupToWork(org.um.dsi.gavea.orcid.model.activities.WorkGroup).

Returns:

the set of work summaries in the set ORCID profile

Throws:

org.um.dsi.gavea.orcid.client.exception.OrcidClientException - if the communication with ORCID fails

getSourcedWorkSummaries

public java.util.List<org.um.dsi.gavea.orcid.model.work.WorkSummary> getSourcedWorkSummaries()
                                                                                      throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException

Retrieves the entire set of work summaries in the ORCID profile whose source is the Member API id defined in the ORCID client.

Returns:

the set of work summaries in the ORCID profile for the defined source

Throws:

org.um.dsi.gavea.orcid.client.exception.OrcidClientException - if the communication with ORCID fails

getFullWork

public void getFullWork(org.um.dsi.gavea.orcid.model.work.WorkSummary mergedWork,
                        java.util.Map<java.math.BigInteger,java.lang.Object> cb)
                 throws java.lang.NullPointerException

Asynchronously gets a full work from an ORCID profile. The resulting work contains every external identifier set in the input work summary, because the summary resulted from the merging of a group, but the retrieve full work is a single work. It also clears the put-code, since at this level they represent the local identifier.

Parameters:

mergedWork - the work summary representing a merged group

cb - the callback object

Throws:

java.lang.NullPointerException - if the merged work is null

See Also:

ORCIDClient.getWork(BigInteger)

getFullWork

public org.um.dsi.gavea.orcid.model.work.Work getFullWork(org.um.dsi.gavea.orcid.model.work.WorkSummary mergedWork)
                                                   throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                                                          java.lang.NullPointerException

Synchronously gets a full work from an ORCID profile. The resulting work contains every external identifier set in the input work summary, because the summary resulted from the merging of a group, but the retrieve full work is a single work. It also clears the put-code, since at this level they represent the local identifier.

Parameters:

mergedWork - the work summary representing a merged group

Returns:

the full work retrieved from ORCID

Throws:

org.um.dsi.gavea.orcid.client.exception.OrcidClientException - if communication with the ORCID API fails

java.lang.NullPointerException - if the merged work is null

See Also:

ORCIDClient.getWork(BigInteger)

addWork

public java.math.BigInteger addWork(org.um.dsi.gavea.orcid.model.work.Work work)
                             throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                                    java.lang.NullPointerException

Synchronously adds a work to an ORCID profile.

Parameters:

work - the new work to be added

Returns:

the put-code assigned to the new work by ORCID

Throws:

org.um.dsi.gavea.orcid.client.exception.OrcidClientException - if communication with the ORCID API fails

java.lang.NullPointerException - if the work is null

See Also:

ORCIDClient.addWork(Work)

updateWork

public void updateWork(java.math.BigInteger remotePutcode,
                       org.um.dsi.gavea.orcid.model.work.Work updatedWork)
                throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                       java.lang.NullPointerException

Synchronously updates a work in an ORCID profile.

Parameters:

remotePutcode - the put-code of the remote ORCID work that will be updated

updatedWork - the new state of the work that will be updated

Throws:

org.um.dsi.gavea.orcid.client.exception.OrcidClientException - if communication with the ORCID API fails

java.lang.NullPointerException - if either parameter is null

See Also:

ORCIDClient.updateWork(BigInteger, Work)

deleteAllSourcedWorks

public void deleteAllSourcedWorks()
                           throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException

Deletes the entire set of work summaries in the ORCID profile whose source is the Member API id defined in the ORCID client.

Throws:

org.um.dsi.gavea.orcid.client.exception.OrcidClientException - if the communication with ORCID fails

deleteWork

public void deleteWork(java.math.BigInteger putcode)
                throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                       java.lang.NullPointerException

Synchronously deletes a work in an ORCID profile.

Parameters:

putcode - the remote put-code of the work to be deleted

Throws:

org.um.dsi.gavea.orcid.client.exception.OrcidClientException - if the communication with ORCID fails

java.lang.NullPointerException - if the put-code is null

See Also:

ORCIDClient.deleteWork(BigInteger)

waitWorkers

public boolean waitWorkers()
                    throws java.lang.InterruptedException

Waits for all active asynchronous workers communicating with ORCID to finish (if multi-threading is enabled, otherwise it is always true).

Returns:

whether the workers finished before the timeout

Throws:

java.lang.InterruptedException - if the process was interrupted

getActivityLocalKey

public static java.math.BigInteger getActivityLocalKey(org.um.dsi.gavea.orcid.model.common.ElementSummary act)
                                                throws java.lang.NullPointerException

Retrieves the local key of an activity, currently assumed to be stored in the put-code field.

Parameters:

act - the activity from which to get the local key

Returns:

the local key

Throws:

java.lang.NullPointerException - if the activity is null

setWorkLocalKey

public static void setWorkLocalKey(org.um.dsi.gavea.orcid.model.common.ElementSummary act,
                                   java.math.BigInteger key)
                            throws java.lang.NullPointerException

Retrieves the local key of an activity, currently assumed to be stored in the put-code field.

Parameters:

act - the activity to which to set the local key

key - the local key

Throws:

java.lang.NullPointerException - if the activity is null

getExternalIdsDiff

public static java.util.Map<org.um.dsi.gavea.orcid.model.work.Work,ExternalIdsDiff> getExternalIdsDiff(org.um.dsi.gavea.orcid.model.work.WorkSummary work,
                                                                                                       java.util.Collection<org.um.dsi.gavea.orcid.model.work.Work> works)
                                                                                                throws java.lang.NullPointerException

Calculates the symmetric difference of external identifiers between a work and a set of works. Works that do not match (i.e., no identifier is common) are ignored.

Parameters:

work - the work summary to be compared with other works

works - the set of works against which the work summary is compared

Returns:

The symmetric difference of external identifiers between work and works

Throws:

java.lang.NullPointerException - if either of the parameters is null

hasNewIDs

public static boolean hasNewIDs(org.um.dsi.gavea.orcid.model.work.Work preWork,
                                org.um.dsi.gavea.orcid.model.work.WorkSummary posWork)

Checks whether a work is already up to date regarding another one, i.e., whether a work has the same external identifiers as another one. This test is expected to be used by the import algorithms, where only new external identifiers are to be considered.

Parameters:

preWork - The potentially out of date work.

posWork - The up to date work.

Returns:

true if all the UIDs between the two works are the same, false otherwise.

isUpToDate

public static boolean isUpToDate(org.um.dsi.gavea.orcid.model.work.Work preWork,
                                 org.um.dsi.gavea.orcid.model.work.WorkSummary posWork)

Checks whether a work is already up to date regarding another one, considering the external identifiers and additional meta-data. This test is expected to be used by the export algorithms, where the meta-data is expected to be up-to-date on the remote profile.

Parameters:

preWork - the potentially out of date work

posWork - the up to date work

Returns:

true if all the external identifiers and the meta-data between the two works are the same, false otherwise.

isUpToDate

public static boolean isUpToDate(org.um.dsi.gavea.orcid.model.work.Work preWork,
                                 org.um.dsi.gavea.orcid.model.work.Work posWork)

Checks whether a work is already up to date regarding another one, considering the external identifiers and additional meta-data.

Parameters:

preWork - the potentially out of date work

posWork - the up to date work

Returns:

true if all the external identifiers and the meta-data between the two works are the same, false otherwise.

testMinimalQuality

public static java.util.Set<java.lang.String> testMinimalQuality(org.um.dsi.gavea.orcid.model.work.Work work)
                                                          throws java.lang.NullPointerException

Tests whether a work has minimal quality to be synchronized, by inspecting its meta-data, returns the detected invalid fields. The considered fields are: external identifiers, title, publication date (year), work type. All these meta-data is available in work summaries. The publication date is not necessary for data sets and research techniques. TODO: contributors are not being considered as they are not contained in the summaries.

Parameters:

work - the work to test for quality

Returns:

the set of invalid fields

Throws:

java.lang.NullPointerException - if the work is null

testMinimalQuality

public static java.util.Set<java.lang.String> testMinimalQuality(org.um.dsi.gavea.orcid.model.work.WorkSummary work)
                                                          throws java.lang.NullPointerException

Tests whether a work has minimal quality to be synchronized, by inspecting its meta-data, returns the detected invalid fields. The considered fields are: external identifiers, title, publication date (year), work type. All these meta-data is available in work summaries. The publication date is not necessary for data sets and research techniques. TODO: contributors are not being considered as they are not contained in the summaries.

Parameters:

work - the work to test for quality

Returns:

the set of invalid fields

Throws:

java.lang.NullPointerException - if the work is null

tryMinimalQuality

public static void tryMinimalQuality(org.um.dsi.gavea.orcid.model.work.Work work)
                              throws InvalidWorkException

Tests whether a work has minimal quality to be synchronized, by inspecting its meta-data. Throws an exception if the test fails. The considered fields are: external identifiers, title, publication date (year), work type. All these meta-data is available in work summaries. TODO: contributors are not being considered as they are not contained in the summaries.

Parameters:

work - the work to test for quality

Throws:

InvalidWorkException - if the quality test fails, containing the reasons for failing

java.lang.NullPointerException - if the work is null

tryMinimalQuality

public static void tryMinimalQuality(org.um.dsi.gavea.orcid.model.work.WorkSummary work)
                              throws InvalidWorkException

Tests whether a work has minimal quality to be synchronized, by inspecting its meta-data. Throws an exception if the test fails. The considered fields are: external identifiers, title, publication date (year), work type. All these meta-data is available in work summaries. TODO: contributors are not being considered as they are not contained in the summaries.

Parameters:

work - the work to test for quality

Throws:

InvalidWorkException - if the quality test fails, containing the reasons for failing

java.lang.NullPointerException - if the work is null

clone

public static org.um.dsi.gavea.orcid.model.work.WorkSummary clone(org.um.dsi.gavea.orcid.model.work.WorkSummary work)

Clones a work summary.

Parameters:

work - the summary to be cloned

Returns:

the clone

clone

public static org.um.dsi.gavea.orcid.model.work.Work clone(org.um.dsi.gavea.orcid.model.work.Work work)

Clones a work summary.

Parameters:

work - the summary to be cloned

Returns:

the clone