Package pt.ptcris.utils

Class ORCIDHelper<E extends org.um.dsi.gavea.orcid.model.common.ElementSummary,S extends org.um.dsi.gavea.orcid.model.common.ElementSummary,G,T extends java.lang.Enum<T>>

java.lang.Object

pt.ptcris.utils.ORCIDHelper<E,S,G,T>

Type Parameters:

E - The class of ORCID activities being synchronized

S - The class of ORCID activity summaries

G - The class of ORCID activity groups

T - The class of ORCID activity types

Direct Known Subclasses:

ORCIDFundingHelper, ORCIDWorkHelper

public abstract class ORCIDHelper<E extends org.um.dsi.gavea.orcid.model.common.ElementSummary,S extends org.um.dsi.gavea.orcid.model.common.ElementSummary,G,T extends java.lang.Enum<T>>
extends java.lang.Object

An abstract helper to help manage ORCID activities and simplify the usage of the low-level ORCID client. Supports bulk requests when available. The concrete ORCID activities to be managed by the helper are expected to support external identifiers. Provides support for asynchronous communication with ORCID although it is only active for GET requests due to resource limitations.

Field Summary

Fields

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

Constructor Summary

Constructors

Constructor	Description
ORCIDHelper(ORCIDClient orcidClient, int bulk_size_add, int bulk_size_get)	Initializes the helper with a given ORCID client, which defines whether asynchronous calls will be performed, and sets whether bulk ORCID commands are available and with which size.

Method Summary

Modifier and Type	Method	Description
java.util.List<PTCRISyncResult<E>>	add(java.util.List<E> activities, ProgressHandler handler)	Synchronously adds a list of activities to an ORCID profile, either through atomic or bulk calls if available.
static void	cleanWorkLocalKey(org.um.dsi.gavea.orcid.model.common.ElementSummary activity)	Clears (sets to null) the local key of an activity, currently assumed to be stored in the put-code field.
abstract E	createUpdate(E original, ExternalIdsDiff diff)	Creates an update to an activity given the difference on meta-data.
PTCRISyncResult<E>	delete(java.math.BigInteger putcode)	Synchronously deletes an activity from an ORCID profile.
void	deleteAllSourced()	Deletes the entire set of activity summaries in the ORCID profile whose source is the Member API id defined in the ORCID client.
static ORCIDHelper<org.um.dsi.gavea.orcid.model.funding.Funding,org.um.dsi.gavea.orcid.model.funding.FundingSummary,org.um.dsi.gavea.orcid.model.activities.FundingGroup,org.um.dsi.gavea.orcid.model.funding.FundingType>	factoryStaticFundings()	Creates a static (i.e., no server connection) ORCID helper to manage funding activities.
static ORCIDHelper<org.um.dsi.gavea.orcid.model.work.Work,org.um.dsi.gavea.orcid.model.work.WorkSummary,org.um.dsi.gavea.orcid.model.activities.WorkGroup,org.um.dsi.gavea.orcid.model.work.WorkType>	factoryStaticWorks()	Creates a static (i.e., no server connection) ORCID helper to manage work activities.
static java.math.BigInteger	getActivityLocalKey(org.um.dsi.gavea.orcid.model.common.ElementSummary activity)	Retrieves the local key of an activity, currently assumed to be stored in the put-code field.
static java.math.BigInteger	getActivityLocalKey(org.um.dsi.gavea.orcid.model.common.ElementSummary activity, java.math.BigInteger defaultValue)	Retrieves the local key of an activity, currently assumed to be stored in the put-code field.
java.util.List<S>	getAllTypedSummaries(java.util.Collection<T> types)	Retrieves the entire set of activity summaries of given types from the set ORCID profile that have at least an external identifier set.
void	getFulls(java.util.List<S> summaries, java.util.Map<java.math.BigInteger,PTCRISyncResult<E>> cb, ProgressHandler handler)	Reads a full ORCID activity from an ORCID profile and adds it to a callback map.
abstract org.um.dsi.gavea.orcid.model.common.ExternalIds	getNonNullExternalIdsE(E activity)	Returns the non-null external identifiers of an activity (null becomes empty list).
abstract org.um.dsi.gavea.orcid.model.common.ExternalIds	getNonNullExternalIdsS(S summary)	Returns the non-null external identifiers of an activity summary (null becomes empty list).
org.um.dsi.gavea.orcid.model.common.ExternalIds	getPartOfExternalIdsE(E activity)	Returns the non-null part-of external identifiers of an activity (null becomes empty list).
java.util.Map<E,ExternalIdsDiff>	getSelfExternalIdsDiffS(S summary, java.util.Collection<E> activities)	Calculates the symmetric difference of self external identifiers between an activity summary and a set of activities.
org.um.dsi.gavea.orcid.model.common.ExternalIds	getSelfExternalIdsE(E activity)	Returns the non-null self external identifiers of an activity (null becomes empty list).
java.util.List<S>	getSourcedSummaries()	Retrieves the entire set (i.e., not merged) of activity summaries in the ORCID profile whose source is the Member API id defined in the ORCID client.
T	getTypeE(E activity)	Retrieves the type of an activity.
boolean	hasNewSelfIDs(E preElement, S posElement)	Checks whether an activity is already up to date regarding another one regarding self external identifiers.
boolean	isUpToDateE(E preElement, E posElement)	Checks whether an activity is already up to date regarding another one, considering the self external identifiers and additional meta-data.
boolean	isUpToDateS(E preElement, S posElement)	Checks whether an activity is already up to date regarding another one, considering the self external identifiers and additional meta-data.
abstract void	setExternalIdsE(E activity, org.um.dsi.gavea.orcid.model.common.ExternalIds eids)	Assigns a set of external identifiers to an activity.
abstract void	setExternalIdsS(S summary, org.um.dsi.gavea.orcid.model.common.ExternalIds eids)	Assigns a set of external identifiers to an activity summary.
java.util.Set<java.lang.String>	testMinimalQuality(S summary)	Tests whether an activity summary has minimal quality to be synchronized, by inspecting its meta-data and that of coexisting activities, and returns the detected invalid fields.
void	tryMinimalQualityE(E activity, java.util.Collection<E> others)	Tests whether an activity has minimal quality to be synchronized, by inspecting its meta-data.
PTCRISyncResult<E>	update(java.math.BigInteger remotePutcode, E updated)	Synchronously updates an activity to an ORCID profile.

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

INVALID_ORGANIZATION

public static final java.lang.String INVALID_ORGANIZATION

See Also:

Constant Field Values

OVERLAPPING_EIDs

public static final java.lang.String OVERLAPPING_EIDs

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 activities.

Constructor Detail

ORCIDHelper

public ORCIDHelper(ORCIDClient orcidClient,
                   int bulk_size_add,
                   int bulk_size_get)

Initializes the helper with a given ORCID client, which defines whether asynchronous calls will be performed, and sets whether bulk ORCID commands are available and with which size.

Parameters:

orcidClient - the ORCID client

bulk_size_add - number of activities per bulk add request

bulk_size_get - number of activities per bulk get request

Method Detail

factoryStaticWorks

public static ORCIDHelper<org.um.dsi.gavea.orcid.model.work.Work,org.um.dsi.gavea.orcid.model.work.WorkSummary,org.um.dsi.gavea.orcid.model.activities.WorkGroup,org.um.dsi.gavea.orcid.model.work.WorkType> factoryStaticWorks()

Creates a static (i.e., no server connection) ORCID helper to manage work activities.

Returns:

the ORCID work helper

factoryStaticFundings

public static ORCIDHelper<org.um.dsi.gavea.orcid.model.funding.Funding,org.um.dsi.gavea.orcid.model.funding.FundingSummary,org.um.dsi.gavea.orcid.model.activities.FundingGroup,org.um.dsi.gavea.orcid.model.funding.FundingType> factoryStaticFundings()

Creates a static (i.e., no server connection) ORCID helper to manage funding activities.

Returns:

the ORCID funding helper

getAllTypedSummaries

public final java.util.List<S> getAllTypedSummaries(java.util.Collection<T> types)
                                             throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException

Retrieves the entire set of activity summaries of given types from the set ORCID profile that have at least an external identifier set. Merges each ORCID group into a single summary, following group(Object).

Parameters:

types - the ORCID types of the activities to be retrieved (may be null)

Returns:

the set of ORCID activity summaries in the defined ORCID profile

Throws:

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

getSourcedSummaries

public final java.util.List<S> getSourcedSummaries()
                                            throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException

Retrieves the entire set (i.e., not merged) of activity summaries in the ORCID profile whose source is the Member API id defined in the ORCID client.

Returns:

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

Throws:

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

getFulls

public final void getFulls(java.util.List<S> summaries,
                           java.util.Map<java.math.BigInteger,PTCRISyncResult<E>> cb,
                           ProgressHandler handler)
                    throws java.lang.InterruptedException

Reads a full ORCID activity from an ORCID profile and adds it to a callback map. The resulting activity contains every external identifier set in the input activity summary, because the summary resulted from the merging of a group, but the retrieved full activity is a single activity. It also clears the put-code, since at this level they represent the local identifier. If possible the number of threads is higher than 1, process is asynchronous. If the list is not a singleton, a bulk request will be performed if supported for the concrete ORCID activity type. If the communication with ORCID fails for any activity, the exceptions are embedded in failed PTCRISyncResult.

Parameters:

summaries - the ORCID activity summaries representing the merged groups

cb - the callback object

handler - the handler to report progress

Throws:

java.lang.InterruptedException - if the asynchronous GET process is interrupted

See Also:

readClient(List)

add

public final java.util.List<PTCRISyncResult<E>> add(java.util.List<E> activities,
                                                    ProgressHandler handler)

Synchronously adds a list of activities to an ORCID profile, either through atomic or bulk calls if available. A list of results is returned, one for each input activity. The OK result includes the newly assigned put-code. If the communication with ORCID fails, the exception is embedded in a failed PTCRISyncResult. If the overall communication fails, the result is replicated for each input.

Parameters:

activities - the new ORCID activities to be added

handler - the handler to report progress

Returns:

the results of the ORCID call for each input activity

update

public final PTCRISyncResult<E> update(java.math.BigInteger remotePutcode,
                                       E updated)

Synchronously updates an activity to an ORCID profile. If the communication with ORCID fails, the exception is embedded in a failed PTCRISyncResult.

Parameters:

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

updated - the new state of the activity that will be updated

Returns:

the result of the ORCID call

See Also:

updateClient(BigInteger, ElementSummary)

delete

public final PTCRISyncResult<E> delete(java.math.BigInteger putcode)

Synchronously deletes an activity from an ORCID profile. If the communication with ORCID fails, the exception is embedded in a failed PTCRISyncResult.

Parameters:

putcode - the remote put-code of the ORCID activity to be deleted

Returns:

the outcome of the delete request

See Also:

deleteClient(BigInteger)

deleteAllSourced

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

Deletes the entire set of activity 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

getNonNullExternalIdsE

public abstract org.um.dsi.gavea.orcid.model.common.ExternalIds getNonNullExternalIdsE(E activity)

Returns the non-null external identifiers of an activity (null becomes empty list). Cannot rely on getNonNullExternalIdsS(ElementSummary) because summarize(ElementSummary) itself calls this method.

Parameters:

activity - the ORCID activity from which to retrieve the external identifiers

Returns:

the non-null external identifiers

getNonNullExternalIdsS

public abstract org.um.dsi.gavea.orcid.model.common.ExternalIds getNonNullExternalIdsS(S summary)

Returns the non-null external identifiers of an activity summary (null becomes empty list).

Parameters:

summary - the ORCID activity summary from which to retrieve the external identifiers

Returns:

the non-null external identifiers

setExternalIdsE

public abstract void setExternalIdsE(E activity,
                                     org.um.dsi.gavea.orcid.model.common.ExternalIds eids)

Assigns a set of external identifiers to an activity.

Parameters:

activity - the ORCID activity to which to assign the external identifiers

eids - the external identifiers to be assigned

setExternalIdsS

public abstract void setExternalIdsS(S summary,
                                     org.um.dsi.gavea.orcid.model.common.ExternalIds eids)

Assigns a set of external identifiers to an activity summary.

Parameters:

summary - the ORCID activity summary to which to assign the external identifiers

eids - the external identifiers to be assigned

createUpdate

public abstract E createUpdate(E original,
                               ExternalIdsDiff diff)

Creates an update to an activity given the difference on meta-data. Essentially creates an activity with the same put-code as the original activity and with the new meta-data that must be assigned to it. Currently, only new external identifiers are considered.

Parameters:

original - the original ORCID activity

diff - the difference on external identifiers

Returns:

the update to be applied to the ORCID activity

getActivityLocalKey

public static java.math.BigInteger getActivityLocalKey(org.um.dsi.gavea.orcid.model.common.ElementSummary activity)

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

Parameters:

activity - the ORCID activity from which to get the local key

Returns:

the local key

getActivityLocalKey

public static java.math.BigInteger getActivityLocalKey(org.um.dsi.gavea.orcid.model.common.ElementSummary activity,
                                                       java.math.BigInteger defaultValue)

Retrieves the local key of an activity, currently assumed to be stored in the put-code field. If empty, returns a default value.

Parameters:

activity - the ORCID activity from which to get the local key

defaultValue - a default value in case the put-code is empty

Returns:

the local key

cleanWorkLocalKey

public static void cleanWorkLocalKey(org.um.dsi.gavea.orcid.model.common.ElementSummary activity)

Clears (sets to null) the local key of an activity, currently assumed to be stored in the put-code field.

Parameters:

activity - the activity to which to clear the local key

getTypeE

public final T getTypeE(E activity)

Retrieves the type of an activity. Build on getTypeS(ElementSummary).

Parameters:

activity - the ORCID activity

Returns:

the activity's type

getPartOfExternalIdsE

public final org.um.dsi.gavea.orcid.model.common.ExternalIds getPartOfExternalIdsE(E activity)

Returns the non-null part-of external identifiers of an activity (null becomes empty list). Builds on getPartOfExternalIdsS(ElementSummary).

Parameters:

activity - the ORCID activity from which to retrieve the external identifiers

Returns:

the non-null part-of external identifiers

getSelfExternalIdsE

public final org.um.dsi.gavea.orcid.model.common.ExternalIds getSelfExternalIdsE(E activity)

Returns the non-null self external identifiers of an activity (null becomes empty list). Builds on getSelfExternalIdsS(ElementSummary).

Parameters:

activity - the ORCID activity from which to retrieve the external identifiers

Returns:

the non-null self external identifiers

getSelfExternalIdsDiffS

public final java.util.Map<E,ExternalIdsDiff> getSelfExternalIdsDiffS(S summary,
                                                                      java.util.Collection<E> activities)

Calculates the symmetric difference of self external identifiers between an activity summary and a set of activities. Elements that do not match (i.e., no identifier is common) are ignored.

Parameters:

summary - the activity summary to be compared with other activities

activities - the set of activities against which the activity summary is compared

Returns:

The symmetric difference of self external identifiers between the summary and other activities

hasNewSelfIDs

public final boolean hasNewSelfIDs(E preElement,
                                   S posElement)

Checks whether an activity is already up to date regarding another one regarding self external identifiers. This test is expected to be used by the import algorithms, where only new self external identifiers are to be considered.

Parameters:

preElement - the potentially out of date ORCID activity

posElement - the up to date ORCID activity

Returns:

true if all the self external identifiers between the two activities are the same, false otherwise

isUpToDateS

public final boolean isUpToDateS(E preElement,
                                 S posElement)

Checks whether an activity is already up to date regarding another one, considering the self external identifiers and additional meta-data. Only meta-data existent in the activity summaries is conside 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:

preElement - the potentially out of date ORCID activity

posElement - the up to date ORCID activity

Returns:

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

isUpToDateE

public final boolean isUpToDateE(E preElement,
                                 E posElement)

Checks whether an activity is already up to date regarding another one, considering the self external identifiers and additional meta-data. Only meta-data existent in the activity summaries is considered. Builds on isUpToDateS(ElementSummary, ElementSummary). 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:

preElement - the potentially out of date ORCID activity

posElement - the up to date ORCID activity

Returns:

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

tryMinimalQualityE

public final void tryMinimalQualityE(E activity,
                                     java.util.Collection<E> others)
                              throws InvalidActivityException

Tests whether an activity has minimal quality to be synchronized, by inspecting its meta-data. Throws an exception if the test fails. Only meta-data available in activity summaries is considered. TODO: contributors are not being considered as they are not contained in the summaries.

Parameters:

activity - the activity to test for quality

others - other coexisting activities

Throws:

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

testMinimalQuality

public final java.util.Set<java.lang.String> testMinimalQuality(S summary)

Tests whether an activity summary has minimal quality to be synchronized, by inspecting its meta-data and that of coexisting activities, and returns the detected invalid fields. Only uses meta-data available in activity summaries. Builds on testMinimalQuality(ElementSummary, Collection). TODO: contributors are not being considered as they are not contained in the summaries.

Parameters:

summary - the ORCID activity summary to test for quality

Returns:

the set of invalid meta-data, empty if valid