Package pt.ptcris

Class PTCRISync

java.lang.Object

pt.ptcris.PTCRISync

public final class PTCRISync
extends java.lang.Object

An implementation of the PTCRISync synchronization service based on the version 0.4.3 of the specification, enhanced with minimal quality criteria. This service allows CRIS services to maintain their repositories synchronized with ORCID. This requires the CRIS service to have access to the ORCID Member API.

The service has two main functionalities: to keep a set of local activities updated in an ORCID user profile through an export procedure, and import activities not known locally from the ORCID profile, either through the import for completely new activities or through the import for new information for already known entries. Activities must meet certain quality criteria to be imported (the set of invalid activities can be retrieved as well through importInvalidBase(ORCIDHelper, List, Collection, ProgressHandler).

The implementation of the service assumes that the local CRIS communicates the local activities following the established ORCID schema, according to the ORCID Member API 2.0. This uniforms the API and simplifies the synchronization process. The current version focuses on synchronizing research productions and funding entries, which must be encoded as ORCID works and funding activities.

The communication with ORCID is encapsulated in an ORCID client that contains information regarding the CRIS Member API and the ORCID profile that is to be managed. An helper provides utility methods for the synchronization of activities.

The procedures do not currently consider the contributors (authors) of activities when assessing the quality criteria nor when assessing whether they are up-to-date, as this information is not available in ORCID summaries and would require additional calls to the ORCID API.

See https://ptcris.pt/hub-ptcris/.

Constructor Summary

Constructors

Constructor	Description
PTCRISync()

Method Summary

Modifier and Type	Method	Description
static java.util.Map<java.math.BigInteger,PTCRISyncResult<org.um.dsi.gavea.orcid.model.work.Work>>	export(ORCIDClient client, java.util.List<org.um.dsi.gavea.orcid.model.work.Work> locals, ProgressHandler handler)	Deprecated. Replaced by exportWorks(ORCIDClient, List, ProgressHandler)
static java.util.Map<java.math.BigInteger,PTCRISyncResult<org.um.dsi.gavea.orcid.model.work.Work>>	exportForce(ORCIDClient client, java.util.List<org.um.dsi.gavea.orcid.model.work.Work> locals, ProgressHandler handler)	Deprecated. Replaced by exportWorksForced(ORCIDClient, List, ProgressHandler)
static java.util.Map<java.math.BigInteger,PTCRISyncResult<org.um.dsi.gavea.orcid.model.funding.Funding>>	exportFundings(ORCIDClient client, java.util.List<org.um.dsi.gavea.orcid.model.funding.Funding> locals, java.util.Collection<org.um.dsi.gavea.orcid.model.funding.FundingType> types, ProgressHandler handler)	Exports a list of local CRIS funding entries to an ORCID profile and keeps them up-to-date.
static java.util.Map<java.math.BigInteger,PTCRISyncResult<org.um.dsi.gavea.orcid.model.work.Work>>	exportWorks(ORCIDClient client, java.util.List<org.um.dsi.gavea.orcid.model.work.Work> locals, ProgressHandler handler)	Exports a list of local CRIS productions to an ORCID profile and keeps them up-to-date.
static java.util.Map<java.math.BigInteger,PTCRISyncResult<org.um.dsi.gavea.orcid.model.work.Work>>	exportWorksForced(ORCIDClient client, java.util.List<org.um.dsi.gavea.orcid.model.work.Work> locals, ProgressHandler handler)	Exports a list of local CRIS productions to an ORCID profile and keeps them up-to-date.
static java.lang.Integer	importCounter(ORCIDClient client, java.util.List<org.um.dsi.gavea.orcid.model.work.Work> locals, ProgressHandler handler)	Deprecated. Replaced by importWorkCounter(ORCIDClient, List, ProgressHandler)
static java.lang.Integer	importFundingCounter(ORCIDClient client, java.util.List<org.um.dsi.gavea.orcid.model.funding.Funding> locals, java.util.Collection<org.um.dsi.gavea.orcid.model.funding.FundingType> types, ProgressHandler handler)	Counts new valid funding activities in an ORCID profile given a set of known local CRIS funding entries, following the criteria of importFundings(ORCIDClient, List, Collection, ProgressHandler) but is more efficient, generating less API calls.
static java.util.List<org.um.dsi.gavea.orcid.model.funding.Funding>	importFundings(ORCIDClient client, java.util.List<org.um.dsi.gavea.orcid.model.funding.Funding> locals, java.util.Collection<org.um.dsi.gavea.orcid.model.funding.FundingType> types, ProgressHandler handler)	Discovers new valid funding activities in an ORCID profile given a set of known local CRIS funding entries.
static java.util.List<org.um.dsi.gavea.orcid.model.funding.Funding>	importFundingUpdates(ORCIDClient client, java.util.List<org.um.dsi.gavea.orcid.model.funding.Funding> locals, java.util.Collection<org.um.dsi.gavea.orcid.model.funding.FundingType> types, ProgressHandler handler)	Discovers updates to existing local CRIS funding activities in an ORCID profile.
static java.util.Map<org.um.dsi.gavea.orcid.model.work.Work,java.util.Set<java.lang.String>>	importInvalid(ORCIDClient client, java.util.List<org.um.dsi.gavea.orcid.model.work.Work> locals, ProgressHandler handler)	Deprecated. Replaced by importInvalidWorks(ORCIDClient, List, ProgressHandler)
static java.util.Map<org.um.dsi.gavea.orcid.model.funding.Funding,java.util.Set<java.lang.String>>	importInvalidFundings(ORCIDClient client, java.util.List<org.um.dsi.gavea.orcid.model.funding.Funding> locals, java.util.Collection<org.um.dsi.gavea.orcid.model.funding.FundingType> types, ProgressHandler handler)	Discovers new invalid funding activities (that do not pass the quality criteria, see ORCIDHelper.testMinimalQuality(ElementSummary)) in an ORCID profile given a set of known local CRIS entries, as well as the causes for invalidity (defined at ORCIDFundingHelper).
static java.util.Map<org.um.dsi.gavea.orcid.model.work.Work,java.util.Set<java.lang.String>>	importInvalidWorks(ORCIDClient client, java.util.List<org.um.dsi.gavea.orcid.model.work.Work> locals, ProgressHandler handler)	Discovers new invalid works (that do not pass the quality criteria, see ORCIDHelper.testMinimalQuality(ElementSummary)) in an ORCID profile given a set of known local CRIS entries, as well as the causes for invalidity (defined at ORCIDWorkHelper).
static java.util.List<org.um.dsi.gavea.orcid.model.work.Work>	importUpdates(ORCIDClient client, java.util.List<org.um.dsi.gavea.orcid.model.work.Work> locals, ProgressHandler handler)	Deprecated. Replaced by importWorkUpdates(ORCIDClient, List, ProgressHandler)
static java.lang.Integer	importWorkCounter(ORCIDClient client, java.util.List<org.um.dsi.gavea.orcid.model.work.Work> locals, ProgressHandler handler)	Counts new valid works in an ORCID profile given a set of known local CRIS productions, following the criteria of importWorks(ORCIDClient, List, ProgressHandler) but is more efficient, generating less API calls.
static java.util.List<org.um.dsi.gavea.orcid.model.work.Work>	importWorks(ORCIDClient client, java.util.List<org.um.dsi.gavea.orcid.model.work.Work> locals, ProgressHandler handler)	Discovers new valid works in an ORCID profile given a set of known local CRIS productions.
static java.util.List<org.um.dsi.gavea.orcid.model.work.Work>	importWorkUpdates(ORCIDClient client, java.util.List<org.um.dsi.gavea.orcid.model.work.Work> locals, ProgressHandler handler)	Discovers updates to existing local CRIS productions in an ORCID profile.

Methods inherited from class java.lang.Object

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

Constructor Detail

PTCRISync

public PTCRISync()

Method Detail

exportWorks

public static java.util.Map<java.math.BigInteger,PTCRISyncResult<org.um.dsi.gavea.orcid.model.work.Work>> exportWorks(ORCIDClient client,
                                                                                                                      java.util.List<org.um.dsi.gavea.orcid.model.work.Work> locals,
                                                                                                                      ProgressHandler handler)
                                                                                                               throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                                                                                                                      java.lang.IllegalArgumentException

Exports a list of local CRIS productions to an ORCID profile and keeps them up-to-date. This procedure manages the work activities in the ORCID user profile that are sourced by the CRIS, both previously specified in the client.

The procedure detects every CRIS sourced work in the ORCID profile that matches any local entry that is being exported; if there is no matching local entry, the ORCID activity is deleted from the profile. Otherwise it will be updated with the meta-data of one of the matching local entries. Finally, for local entries without any matching ORCID activity, new ones are created. The matching is performed by detecting shared external identifiers (see ORCIDHelper.getSelfExternalIdsDiffS(ElementSummary, Collection) ).

Activities are only updated if the meta-data is not up-to-date. Currently, the title, the publication year and the publication are considered (see ORCIDHelper.isUpToDateE(ElementSummary, ElementSummary)).

The procedure expects the CRIS service to provide the local works in the ORCID schema, in particular encoding them as works. Thus, the meta-data of the CRIS sourced entries in the ORCID profile is exactly that of the provided local entries that are to be exported. The put-code of these local entries is assumed to be used as local key identifiers, and are disregarded during the update of the ORCID profile (new entries are assigned fresh put-codes and updated entries use the put-code of the existing ORCID entry).

The provided local activities must pass a quality criteria to be kept synchronized in ORCID. Currently, this forces the existence of external identifiers, the title, the publication year and the publication type (see ORCIDHelper.testMinimalQuality(ElementSummary).

The procedure reports the status for each of the input local activities, identifying them by the provided local put-code, including the ORCID error if the process failed. See PTCRISyncResult for the codes. If the local put-code is empty, returns a default value, which currently is the put-code remotely assigned by ORCID.

Parameters:

client - the ORCID client defining the CRIS Member API and user the profile to be managed

locals - the list of local productions to be exported that should be kept synchronized in the ORCID user profile

handler - the progress handler responsible for receiving progress updates

Returns:

the result of the synchronization of each of the provided local work

Throws:

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

java.lang.IllegalArgumentException - if null arguments

export

@Deprecated
public static java.util.Map<java.math.BigInteger,PTCRISyncResult<org.um.dsi.gavea.orcid.model.work.Work>> export(ORCIDClient client,
                                                                                                                 java.util.List<org.um.dsi.gavea.orcid.model.work.Work> locals,
                                                                                                                 ProgressHandler handler)
                                                                                                          throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                                                                                                                 java.lang.IllegalArgumentException

Deprecated. Replaced by exportWorks(ORCIDClient, List, ProgressHandler)

Parameters:

client - the ORCID client defining the CRIS Member API and user the profile to be managed

locals - the list of local productions to be exported that should be kept synchronized in the ORCID user profile

handler - the progress handler responsible for receiving progress updates

Returns:

the result of the synchronization of each of the provided local work

Throws:

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

java.lang.IllegalArgumentException - if null arguments

exportWorksForced

public static java.util.Map<java.math.BigInteger,PTCRISyncResult<org.um.dsi.gavea.orcid.model.work.Work>> exportWorksForced(ORCIDClient client,
                                                                                                                            java.util.List<org.um.dsi.gavea.orcid.model.work.Work> locals,
                                                                                                                            ProgressHandler handler)
                                                                                                                     throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                                                                                                                            java.lang.IllegalArgumentException

Exports a list of local CRIS productions to an ORCID profile and keeps them up-to-date. This procedure manages the work activities in the ORCID user profile that are sourced by the CRIS, both previously specified in the client.

The procedure detects every CRIS sourced work in the ORCID profile that matches any local entry that is being exported; if there is no matching local entry, the ORCID activity is deleted from the profile. Otherwise it will be updated with the meta-data of one of the matching local entries. Finally, for local entries without any matching ORCID activity, new ones are created. The matching is performed by detecting shared external identifiers (see ORCIDHelper.getSelfExternalIdsDiffS(ElementSummary, Collection) ).

Activities are always updated, even if already up-to-date (no test is performed). The caller of this method should guarantee that the input local productions have been effectively updated, otherwise there will be unnecessary calls to the ORCID API.

The procedure expects the CRIS service to provide the local works in the ORCID schema, in particular encoding them as works. Thus, the meta-data of the CRIS sourced entries in the ORCID profile is exactly that of the provided local entries that are to be exported. The put-code of these local entries is assumed to be used as local key identifiers, and are disregarded during the update of the ORCID profile (new entries are assigned fresh put-codes and updated entries use the put-code of the existing ORCID entry).

The provided local activities must pass a quality criteria to be kept synchronized in ORCID. Currently, this forces the existence of external identifiers, the title, the publication year and the publication type (see ORCIDHelper.testMinimalQuality(ElementSummary).

The procedure reports the status for each of the input local activities, identifying them by the provided local put-code, including the ORCID error if the process failed. See PTCRISyncResult for the codes. If the local put-code is empty, returns a default value, which currently is the put-code remotely assigned by ORCID.

Parameters:

client - the ORCID client defining the CRIS Member API and user the profile to be managed

locals - the list of local productions to be exported that should be kept synchronized in the ORCID user profile

handler - the progress handler responsible for receiving progress updates

Returns:

the result of the synchronization of each of the provided local work

Throws:

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

java.lang.IllegalArgumentException - if null arguments

exportForce

@Deprecated
public static java.util.Map<java.math.BigInteger,PTCRISyncResult<org.um.dsi.gavea.orcid.model.work.Work>> exportForce(ORCIDClient client,
                                                                                                                      java.util.List<org.um.dsi.gavea.orcid.model.work.Work> locals,
                                                                                                                      ProgressHandler handler)
                                                                                                               throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                                                                                                                      java.lang.IllegalArgumentException

Deprecated. Replaced by exportWorksForced(ORCIDClient, List, ProgressHandler)

Parameters:

client - the ORCID client defining the CRIS Member API and user the profile to be managed

locals - the list of local productions to be exported that should be kept synchronized in the ORCID user profile

handler - the progress handler responsible for receiving progress updates

Returns:

the result of the synchronization of each of the provided local work

Throws:

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

java.lang.IllegalArgumentException - if null arguments

exportFundings

public static java.util.Map<java.math.BigInteger,PTCRISyncResult<org.um.dsi.gavea.orcid.model.funding.Funding>> exportFundings(ORCIDClient client,
                                                                                                                               java.util.List<org.um.dsi.gavea.orcid.model.funding.Funding> locals,
                                                                                                                               java.util.Collection<org.um.dsi.gavea.orcid.model.funding.FundingType> types,
                                                                                                                               ProgressHandler handler)
                                                                                                                        throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                                                                                                                               java.lang.IllegalArgumentException

Exports a list of local CRIS funding entries to an ORCID profile and keeps them up-to-date. This procedure manages the funding activities in the ORCID user profile that are sourced by the CRIS, both previously specified in the client.

The procedure detects every CRIS sourced funding activity in the ORCID profile that matches any local entry that is being exported; if there is no matching local entry, the ORCID activity is deleted from the profile. Otherwise it will be updated with the meta-data of one of the matching local entries. Finally, for local entries without any matching ORCID activity, new ones are created. The matching is performed by detecting shared external identifiers (see ORCIDHelper.getSelfExternalIdsDiffS(ElementSummary, Collection) ).

Activities are only updated if the meta-data is not up-to-date. Currently, the title, the start year, the funding type and the funding organization are considered (see ORCIDHelper.isUpToDateE(ElementSummary, ElementSummary)).

The procedure expects the CRIS service to provide the local funding entries in the ORCID schema, in particular encoding them as funding activities. Thus, the meta-data of the CRIS sourced entries in the ORCID profile is exactly that of the provided local entries that are to be exported. The put-code of these local entries is assumed to be used as local key identifiers, and are disregarded during the update of the ORCID profile (new entries are assigned fresh put-codes and updated entries use the put-code of the existing ORCID entry).

The provided local activities must pass a quality criteria to be kept synchronized in ORCID. Currently, this forces the existence of external identifiers, the title, the start year, the funding type and the funding organization (see ORCIDHelper.testMinimalQuality(ElementSummary).

*

A set of funding types can be provided to allow the independent synchronization of different types of entries. Local and remote activities outside the provided types are simply ignored (they are not considered invalid).

The procedure reports the status for each of the input local activities, identifying them by the provided local put-code, including the ORCID error if the process failed. See PTCRISyncResult for the codes. If the local put-code is empty, returns a default value, which currently is the put-code remotely assigned by ORCID.

Parameters:

client - the ORCID client defining the CRIS Member API and user the profile to be managed

locals - the list of local productions to be exported that should be kept synchronized in the ORCID user profile

types - the types of ORCID funding entries that should be considered (others are simply ignored).

handler - the progress handler responsible for receiving progress updates

Returns:

the result of the synchronization of each of the provided local funding entry

Throws:

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

java.lang.IllegalArgumentException - if null arguments

importWorks

public static java.util.List<org.um.dsi.gavea.orcid.model.work.Work> importWorks(ORCIDClient client,
                                                                                 java.util.List<org.um.dsi.gavea.orcid.model.work.Work> locals,
                                                                                 ProgressHandler handler)
                                                                          throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                                                                                 java.lang.InterruptedException,
                                                                                 java.lang.IllegalArgumentException

Discovers new valid works in an ORCID profile given a set of known local CRIS productions. Creates creation notifications for each work group at ORCID (merged into as a single work by the helper ) without matching local productions (i.e., those without shared external identifiers). To import updates for works with shared external identifiers importWorkUpdates(ORCIDClient, List, ProgressHandler) should be used instead.

Currently, these creation notifications simply take the shape of ORCID works themselves (representing a merged work group). The group merging selects the meta-data of the preferred activity and the external identifiers of the whole group (see ORCIDHelper.group(Object)). The selection of the meta-data from a group could be changed without affecting the correction of the procedure.

Since the put-code attribute is used as a local key of each activity, it is null for these creation notifications (and not the put-code of the remote ORCID activity that gave origin to it). Since only the external identifiers of the local productions are used to search for matches, the remainder meta-data of the input local activities could be left null.

ORCID activities without minimal quality are ignored by this procedure. Currently, the quality criteria forces the existence of external identifiers, the title, publication year and publication type (see ORCIDHelper.testMinimalQuality(ElementSummary)). Works that do not match the criteria can be imported with importInvalid(ORCIDClient, List, ProgressHandler). Note that currently group merging simply collects the meta-data (other than the external identifiers) from the preferred activity, which is used in the quality assessment.

Parameters:

client - the ORCID client defining the CRIS Member API and user the profile to be managed

locals - the full list of local productions

handler - the progress handler responsible for receiving progress updates

Returns:

the list of new valid works found in the ORCID profile

Throws:

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

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

java.lang.IllegalArgumentException - if null arguments

importFundings

public static java.util.List<org.um.dsi.gavea.orcid.model.funding.Funding> importFundings(ORCIDClient client,
                                                                                          java.util.List<org.um.dsi.gavea.orcid.model.funding.Funding> locals,
                                                                                          java.util.Collection<org.um.dsi.gavea.orcid.model.funding.FundingType> types,
                                                                                          ProgressHandler handler)
                                                                                   throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                                                                                          java.lang.InterruptedException,
                                                                                          java.lang.IllegalArgumentException

Discovers new valid funding activities in an ORCID profile given a set of known local CRIS funding entries. Creates creation notifications for each funding group at ORCID (merged into as a single funding entry by the helper ) without matching local entries (i.e., those without shared external identifiers). To import updates for funding activities with shared external identifiers importFundingUpdates(ORCIDClient, List, Collection, ProgressHandler) should be used instead.

Currently, these creation notifications simply take the shape of ORCID funding activities themselves (representing a merged activity group). The group merging selects the meta-data of the preferred activity and the external identifiers of the whole group (see ORCIDHelper.group(Object)). The selection of the meta-data from a group could be changed without affecting the correction of the procedure.

Since the put-code attribute is used as a local key of each activity, it is null for these creation notifications (and not the put-code of the remote ORCID activity that gave origin to it). Since only the external identifiers of the local funding entries are used to search for matches, the remainder meta-data of the input local activities could be left null.

ORCID activities without minimal quality are ignored by this procedure. Currently, the quality criteria forces the existence of external identifiers, the title, publication year and publication type (see ORCIDHelper.testMinimalQuality(ElementSummary)). Funding entries that do not match the criteria can be imported with importInvalid(ORCIDClient, List, ProgressHandler). Note that currently group merging simply collects the meta-data (other than the external identifiers) from the preferred activity, which is used in the quality assessment.

A set of funding types can be provided to allow the independent synchronization of different types of entries. Local and remote activities outside the provided types are simply ignored (they are not considered invalid).

*

Parameters:

client - the ORCID client defining the CRIS Member API and user the profile to be managed

locals - the full list of local funding entries

handler - the progress handler responsible for receiving progress updates

types - the types of ORCID funding activities that should be considered (others are simply ignored)

Returns:

the list of new valid funding activities found in the ORCID profile

Throws:

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

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

java.lang.IllegalArgumentException - if null arguments

importWorkCounter

public static java.lang.Integer importWorkCounter(ORCIDClient client,
                                                  java.util.List<org.um.dsi.gavea.orcid.model.work.Work> locals,
                                                  ProgressHandler handler)
                                           throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                                                  java.lang.IllegalArgumentException

Counts new valid works in an ORCID profile given a set of known local CRIS productions, following the criteria of importWorks(ORCIDClient, List, ProgressHandler) but is more efficient, generating less API calls.

Parameters:

client - the ORCID client defining the CRIS Member API and user the profile to be managed

locals - the full list of local productions

handler - the progress handler responsible for receiving progress updates

Returns:

the number of new valid works found in the ORCID profile

Throws:

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

java.lang.IllegalArgumentException - if null arguments

See Also:

importWorks(ORCIDClient, List, ProgressHandler)

importCounter

@Deprecated
public static java.lang.Integer importCounter(ORCIDClient client,
                                              java.util.List<org.um.dsi.gavea.orcid.model.work.Work> locals,
                                              ProgressHandler handler)
                                       throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                                              java.lang.IllegalArgumentException

Deprecated. Replaced by importWorkCounter(ORCIDClient, List, ProgressHandler)

Parameters:

client - the ORCID client defining the CRIS Member API and user the profile to be managed

locals - the full list of local productions

handler - the progress handler responsible for receiving progress updates

Returns:

the number of new valid works found in the ORCID profile

Throws:

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

java.lang.IllegalArgumentException - if null arguments

importFundingCounter

public static java.lang.Integer importFundingCounter(ORCIDClient client,
                                                     java.util.List<org.um.dsi.gavea.orcid.model.funding.Funding> locals,
                                                     java.util.Collection<org.um.dsi.gavea.orcid.model.funding.FundingType> types,
                                                     ProgressHandler handler)
                                              throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                                                     java.lang.IllegalArgumentException

Counts new valid funding activities in an ORCID profile given a set of known local CRIS funding entries, following the criteria of importFundings(ORCIDClient, List, Collection, ProgressHandler) but is more efficient, generating less API calls.

Parameters:

client - the ORCID client defining the CRIS Member API and user the profile to be managed

locals - the full list of local funding entries

types - the types of ORCID funding entries that should be considered (others are simply ignored)

handler - the progress handler responsible for receiving progress updates

Returns:

the number of new valid funding activities found in the ORCID profile

Throws:

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

java.lang.IllegalArgumentException - if null arguments

See Also:

importFundings(ORCIDClient, List, Collection, ProgressHandler)

importInvalidWorks

public static java.util.Map<org.um.dsi.gavea.orcid.model.work.Work,java.util.Set<java.lang.String>> importInvalidWorks(ORCIDClient client,
                                                                                                                       java.util.List<org.um.dsi.gavea.orcid.model.work.Work> locals,
                                                                                                                       ProgressHandler handler)
                                                                                                                throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                                                                                                                       java.lang.InterruptedException,
                                                                                                                       java.lang.IllegalArgumentException

Discovers new invalid works (that do not pass the quality criteria, see ORCIDHelper.testMinimalQuality(ElementSummary)) in an ORCID profile given a set of known local CRIS entries, as well as the causes for invalidity (defined at ORCIDWorkHelper). Other than the criteria, the behavior is similar to that of importWorks(ORCIDClient, List, ProgressHandler). Note that currently group merging simply collects the meta-data (other than the external identifiers) from the preferred activity, which is used in the quality assessment.

Parameters:

client - the ORCID client defining the CRIS Member API and user the profile to be managed

locals - the full list of local works

handler - the progress handler responsible for receiving progress updates

Returns:

the list of new invalid works found in the ORCID profile

Throws:

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

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

java.lang.IllegalArgumentException - if null arguments

See Also:

importWorks(ORCIDClient, List, ProgressHandler)

importInvalid

@Deprecated
public static java.util.Map<org.um.dsi.gavea.orcid.model.work.Work,java.util.Set<java.lang.String>> importInvalid(ORCIDClient client,
                                                                                                                  java.util.List<org.um.dsi.gavea.orcid.model.work.Work> locals,
                                                                                                                  ProgressHandler handler)
                                                                                                           throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                                                                                                                  java.lang.InterruptedException,
                                                                                                                  java.lang.IllegalArgumentException

Deprecated. Replaced by importInvalidWorks(ORCIDClient, List, ProgressHandler)

Parameters:

client - the ORCID client defining the CRIS Member API and user the profile to be managed

locals - the full list of local works

handler - the progress handler responsible for receiving progress updates

Returns:

the list of new invalid works found in the ORCID profile

Throws:

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

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

java.lang.IllegalArgumentException - if null arguments

importInvalidFundings

public static java.util.Map<org.um.dsi.gavea.orcid.model.funding.Funding,java.util.Set<java.lang.String>> importInvalidFundings(ORCIDClient client,
                                                                                                                                java.util.List<org.um.dsi.gavea.orcid.model.funding.Funding> locals,
                                                                                                                                java.util.Collection<org.um.dsi.gavea.orcid.model.funding.FundingType> types,
                                                                                                                                ProgressHandler handler)
                                                                                                                         throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                                                                                                                                java.lang.InterruptedException,
                                                                                                                                java.lang.IllegalArgumentException

Discovers new invalid funding activities (that do not pass the quality criteria, see ORCIDHelper.testMinimalQuality(ElementSummary)) in an ORCID profile given a set of known local CRIS entries, as well as the causes for invalidity (defined at ORCIDFundingHelper). Other than the criteria, the behavior is similar to that of importFundings(ORCIDClient, List, Collection, ProgressHandler). Note that currently group merging simply collects the meta-data (other than the external identifiers) from the preferred activity, which is used in the quality assessment.

Parameters:

client - the ORCID client defining the CRIS Member API and user the profile to be managed

locals - the full list of local funding activities

types - the types of ORCID funding activities that should be considered (others are simply ignored)

handler - the progress handler responsible for receiving progress updates

Returns:

the list of new invalid funding activities found in the ORCID profile

Throws:

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

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

java.lang.IllegalArgumentException - if null arguments

See Also:

importFundings(ORCIDClient, List, Collection, ProgressHandler)

importWorkUpdates

public static java.util.List<org.um.dsi.gavea.orcid.model.work.Work> importWorkUpdates(ORCIDClient client,
                                                                                       java.util.List<org.um.dsi.gavea.orcid.model.work.Work> locals,
                                                                                       ProgressHandler handler)
                                                                                throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                                                                                       java.lang.IllegalArgumentException

Discovers updates to existing local CRIS productions in an ORCID profile. For each work group at ORCID (merged into as a single activity by the helper), finds matching local entries (i.e., those with shared external identifiers) and creates update notifications if not already up to date. To import works without shared external identifiers, importWorks(ORCIDClient, List, ProgressHandler) should be used instead.

These update notifications simply take the shape of ORCID activities themselves (representing a matching activity group). These works contain only the meta-data that needs to be updated locally. Currently, only the introduction of newly found external identifiers is considered (i.e., those that were already present in the local entry that is being updated are removed from the returned update). Thus, the remainder fields are returned null. Since only external identifiers are considered the quality criteria is not enforced on the remote ORCID activities.

The local entries are tested to be up-to-date by simply checking whether they contain every external identifiers in the ORCID group (see ORCIDHelper.hasNewSelfIDs(ElementSummary, ElementSummary). Thus the remainder meta-data of the local entries can be currently left null.

The put-code attribute is used as a local key of each CRIS production. This means that the returned activities representing the updates have the put-code of the local entry that is to be updated (and not the put-code of the ORCID activity that gave origin to it).

Parameters:

client - the ORCID client defining the CRIS Member API and user the profile to be managed

locals - the full list of local productions

handler - the progress handler responsible for receiving progress updates

Returns:

the list of work updates found in the ORCID profile, pointing to the respective local activity

Throws:

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

java.lang.IllegalArgumentException - if null arguments

importUpdates

@Deprecated
public static java.util.List<org.um.dsi.gavea.orcid.model.work.Work> importUpdates(ORCIDClient client,
                                                                                   java.util.List<org.um.dsi.gavea.orcid.model.work.Work> locals,
                                                                                   ProgressHandler handler)
                                                                            throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                                                                                   java.lang.IllegalArgumentException

Deprecated. Replaced by importWorkUpdates(ORCIDClient, List, ProgressHandler)

Parameters:

client - the ORCID client defining the CRIS Member API and user the profile to be managed

locals - the full list of local productions

handler - the progress handler responsible for receiving progress updates

Returns:

the list of work updates found in the ORCID profile, pointing to the respective local activity

Throws:

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

java.lang.IllegalArgumentException - if null arguments

importFundingUpdates

public static java.util.List<org.um.dsi.gavea.orcid.model.funding.Funding> importFundingUpdates(ORCIDClient client,
                                                                                                java.util.List<org.um.dsi.gavea.orcid.model.funding.Funding> locals,
                                                                                                java.util.Collection<org.um.dsi.gavea.orcid.model.funding.FundingType> types,
                                                                                                ProgressHandler handler)
                                                                                         throws org.um.dsi.gavea.orcid.client.exception.OrcidClientException,
                                                                                                java.lang.IllegalArgumentException

Discovers updates to existing local CRIS funding activities in an ORCID profile. For each funding activity group at ORCID (merged into as a single activity by the helper), finds matching local entries (i.e., those with shared external identifiers) and creates update notifications if not already up to date. To import funding activities without shared external identifiers, importFundings(ORCIDClient, List, Collection, ProgressHandler) should be used instead.

These update notifications simply take the shape of ORCID activities themselves (representing a matching activity group). These works contain only the meta-data that needs to be updated locally. Currently, only the introduction of newly found external identifiers is considered (i.e., those that were already present in the local entry that is being updated are removed from the returned update). Thus, the remainder fields are returned null. Since only external identifiers are considered the quality criteria is not enforced on the remote ORCID activities.

The local entries are tested to be up-to-date by simply checking whether they contain every external identifiers in the ORCID group (see ORCIDHelper.hasNewSelfIDs(ElementSummary, ElementSummary). Thus the remainder meta-data of the local entries can be currently left null.

A set of activity types can be provided to allow the independent synchronization of different types of entries. Local and remote activities outside the provided types are simply ignored (they are not considered invalid).

The put-code attribute is used as a local key of each CRIS funding entry. This means that the returned activities representing the updates have the put-code of the local entry that is to be updated (and not the put-code of the ORCID activity that gave origin to it).

Parameters:

client - the ORCID client defining the CRIS Member API and user the profile to be managed

locals - the full list of local funding activities

types - the types of ORCID funding activities that should be considered (others are simply ignored)

handler - the progress handler responsible for receiving progress updates

Returns:

the list of funding updates found in the ORCID profile, pointing to the respective local activity

Throws:

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

java.lang.IllegalArgumentException - if null arguments