de.uni_jena.cs.fusion.client.worms

Class WormsClient

java.lang.Object

de.uni_jena.cs.fusion.client.worms.WormsClient

public class WormsClient
extends Object

A client for the World Register of Marine Species REST API. Please refer to the terms of use.

Acknowledgments: The development of the WoRMS Client was funded by DFG in the scope of the LakeBase project within the Scientific Library Services and Information Systems (LIS) program.

Since:

1.0.0

Author:

Jan Martin Keil

Constructor Summary

Constructors

Constructor and Description
WormsClient() Constructs a WormsClient with a default CloseableHttpClient configured to a maximum number of 10 connections.
WormsClient(org.apache.http.impl.client.CloseableHttpClient httpClient) Constructs a WormsClient using the specified CloseableHttpClient.

Method Summary

Modifier and Type	Method and Description
Collection<AttributeKey>	aphiaAttributeKeysById(long id, boolean includeChildren) Get attribute definitions.
Collection<Attribute>	aphiaAttributesByAphiaId(long aphiaId, boolean includeChildren) Get a list of attributes for a given AphiaID
Collection<AttributeValue>	aphiaAttributeValuesByCategoryId(long id) Get list values that are grouped by an CateogryID
Collection<AphiaRecord>	aphiaChildrenByAphiaId(long aphiaId, boolean marineOnly) Get the direct children for a given AphiaID.
Collection<AphiaRecord>	aphiaChildrenByAphiaId(long aphiaId, boolean marineOnly, long offset) Get the direct children (max.
Classification	aphiaClassificationByAphiaId(long aphiaId) Get the complete classification for one taxon.
Collection<Distribution>	aphiaDistributionsByAphiaId(long aphiaId) Get all distributions for a given AphiaID External Identifiers
Collection<String>	aphiaExternalIdByAphiaId(long aphiaId, ExternalIdentifierSource type) Get any external identifier(s) for a given AphiaID
Long	aphiaIdByName(String scientificName) Get the AphiaID for a given name
Collection<AphiaAttributeSets>	aphiaIdsByAttributeKeyId(long id) Get a list of AphiaIDs with attribute tree for a given attribute definition ID Distributions.
Collection<AphiaAttributeSets>	aphiaIdsByAttributeKeyId(long id, long offset) Get a list of AphiaIDs (max 50) with attribute tree for a given attribute definition ID Distributions.
String	aphiaNameByAphiaId(long aphiaId) Get the name for a given AphiaID
AphiaRecord	aphiaRecordByAphiaId(long aphiaId) Get the complete AphiaRecord for a given AphiaID
AphiaRecord	aphiaRecordByExternalId(String id, ExternalIdentifierSource type) Get the Aphia Record for a given external identifier Sources
Collection<AphiaRecord>	aphiaRecordsByDate(java.time.temporal.TemporalAccessor statdate, java.time.temporal.TemporalAccessor enddate, boolean marineOnly) Lists all AphiaRecords (max.
Collection<AphiaRecord>	aphiaRecordsByDate(java.time.temporal.TemporalAccessor statdate, java.time.temporal.TemporalAccessor enddate, boolean marineOnly, long offset) Lists all AphiaRecords (max.
List<Collection<AphiaRecord>>	aphiaRecordsByMatchNames(List<String> scientificNames, boolean marineOnly) For each given scientific name (may include authority), try to find one or more AphiaRecords, using the TAXAMATCH fuzzy matching algorithm by Tony Rees.
Collection<AphiaRecord>	aphiaRecordsByName(String scientificName, boolean like, boolean marineOnly) Get one or more matching AphiaRecords for a given name.
Collection<AphiaRecord>	aphiaRecordsByName(String scientificName, boolean like, boolean marineOnly, long offset) Get one or more matching AphiaRecords (max.
List<Collection<AphiaRecord>>	aphiaRecordsByNames(List<String> scientificNames, boolean like, boolean marineOnly) For each given scientific name, try to find one or more AphiaRecords (max.
Collection<AphiaRecord>	aphiaRecordsByVernacular(String vernacular, boolean like) Get one or more Aphia Records for a given vernacular.
Collection<AphiaRecord>	aphiaRecordsByVernacular(String vernacular, boolean like, long offset) Get one or more Aphia Records (max.
Collection<Source>	aphiaSourcesByAphiaId(long aphiaId) Get one or more sources/references including links, for one AphiaID
Collection<AphiaRecord>	aphiaSynonymsByAphiaId(long aphiaId) Get all synonyms for a given AphiaID.
Collection<Vernacular>	aphiaVernacularsByAphiaId(long aphiaId) Get all vernaculars for a given AphiaID

Methods inherited from class java.lang.Object

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

Constructor Detail

WormsClient

public WormsClient()

Constructs a WormsClient with a default CloseableHttpClient configured to a maximum number of 10 connections.

Since:

1.0.0

WormsClient

public WormsClient(org.apache.http.impl.client.CloseableHttpClient httpClient)

Constructs a WormsClient using the specified CloseableHttpClient.

Parameters:

httpClient - CloseableHttpClient to use

Since:

1.0.0

Method Detail

aphiaAttributeKeysById

public Collection<AttributeKey> aphiaAttributeKeysById(long id,
                                                       boolean includeChildren)
                                                throws WormsClientException

Get attribute definitions. To refer to root items specify ID = ‘0’.

Parameters:

id - The attribute definition id to search for

includeChildren - Include the tree of children.

Throws:

WormsClientException

Since:

1.0.0

aphiaAttributesByAphiaId

public Collection<Attribute> aphiaAttributesByAphiaId(long aphiaId,
                                                      boolean includeChildren)
                                               throws WormsClientException

Get a list of attributes for a given AphiaID

Parameters:

aphiaId - The AphiaID to search for

includeChildren - Include attributes inherited from the taxon its parent(s).

Throws:

WormsClientException

Since:

1.0.0

aphiaAttributeValuesByCategoryId

public Collection<AttributeValue> aphiaAttributeValuesByCategoryId(long id)
                                                            throws WormsClientException

Get list values that are grouped by an CateogryID

Parameters:

id - The CateogryID to search for

Throws:

WormsClientException

Since:

1.0.0

aphiaChildrenByAphiaId

public Collection<AphiaRecord> aphiaChildrenByAphiaId(long aphiaId,
                                                      boolean marineOnly)
                                               throws WormsClientException

Get the direct children for a given AphiaID.

Note: This methods might cause multiple calls of aphiaChildrenByAphiaId(long, boolean, long) to receive all records in chunks of 50 records.

Parameters:

aphiaId - The AphiaID to search for

marineOnly - Limit to marine taxa.

Returns:

Throws:

WormsClientException

Since:

1.0.0

aphiaChildrenByAphiaId

public Collection<AphiaRecord> aphiaChildrenByAphiaId(long aphiaId,
                                                      boolean marineOnly,
                                                      long offset)
                                               throws WormsClientException

Get the direct children (max. 50) for a given AphiaID.

Parameters:

aphiaId - The AphiaID to search for

marineOnly - Limit to marine taxa.

offset - Starting recordnumber, when retrieving next chunk of 50 records. First record has number 1.

Returns:

Throws:

WormsClientException

Since:

1.0.0

aphiaClassificationByAphiaId

public Classification aphiaClassificationByAphiaId(long aphiaId)
                                            throws WormsClientException

Get the complete classification for one taxon. This also includes any sub or super ranks.

Parameters:

aphiaId - The AphiaID to search for

Returns:

classification of the taxon

Throws:

WormsClientException

Since:

1.0.0

aphiaDistributionsByAphiaId

public Collection<Distribution> aphiaDistributionsByAphiaId(long aphiaId)
                                                     throws WormsClientException

Get all distributions for a given AphiaID External Identifiers

Parameters:

aphiaId - The AphiaID to search for

Returns:

all distributions

Throws:

WormsClientException

Since:

1.0.0

aphiaExternalIdByAphiaId

public Collection<String> aphiaExternalIdByAphiaId(long aphiaId,
                                                   ExternalIdentifierSource type)
                                            throws WormsClientException

Get any external identifier(s) for a given AphiaID

Parameters:

aphiaId - The AphiaID to search for

type - Type of external identifier to return.

Returns:

Throws:

WormsClientException

Since:

1.0.0

aphiaIdByName

public Long aphiaIdByName(String scientificName)
                   throws WormsClientException

Get the AphiaID for a given name

Parameters:

scientificName -

Returns:

Throws:

WormsClientException

Since:

1.0.0

aphiaIdsByAttributeKeyId

public Collection<AphiaAttributeSets> aphiaIdsByAttributeKeyId(long id)
                                                        throws WormsClientException

Get a list of AphiaIDs with attribute tree for a given attribute definition ID Distributions.

Note: This methods might cause multiple calls of aphiaIdsByAttributeKeyId(long, long) to receive all records in chunks of 50 records.

Parameters:

id - The attribute definition id to search for

Returns:

Throws:

WormsClientException

Since:

1.0.0

aphiaIdsByAttributeKeyId

public Collection<AphiaAttributeSets> aphiaIdsByAttributeKeyId(long id,
                                                               long offset)
                                                        throws WormsClientException

Get a list of AphiaIDs (max 50) with attribute tree for a given attribute definition ID Distributions.

Parameters:

id - The attribute definition id to search for

offset - Starting record number, when retrieving next chunk of (50) records. First record has number 1.

Throws:

WormsClientException

Since:

1.0.0

aphiaNameByAphiaId

public String aphiaNameByAphiaId(long aphiaId)
                          throws WormsClientException

Get the name for a given AphiaID

Parameters:

aphiaId -

Returns:

Throws:

WormsClientException

Since:

1.0.0

aphiaRecordByAphiaId

public AphiaRecord aphiaRecordByAphiaId(long aphiaId)
                                 throws WormsClientException

Get the complete AphiaRecord for a given AphiaID

Parameters:

aphiaId -

Returns:

Throws:

WormsClientException

Since:

1.0.0

aphiaRecordByExternalId

public AphiaRecord aphiaRecordByExternalId(String id,
                                           ExternalIdentifierSource type)
                                    throws WormsClientException

Get the Aphia Record for a given external identifier Sources

Parameters:

id -

type -

Returns:

Throws:

WormsClientException

Since:

1.0.0

aphiaRecordsByDate

public Collection<AphiaRecord> aphiaRecordsByDate(java.time.temporal.TemporalAccessor statdate,
                                                  java.time.temporal.TemporalAccessor enddate,
                                                  boolean marineOnly)
                                           throws WormsClientException

Lists all AphiaRecords (max. 50) modified or added between a specific time interval

Note: This methods might cause multiple request to receive all records in chunks of 50 records.

Parameters:

statdate -

enddate -

marineOnly - Limit to marine taxa.

Returns:

Throws:

WormsClientException

Since:

1.0.0

aphiaRecordsByDate

public Collection<AphiaRecord> aphiaRecordsByDate(java.time.temporal.TemporalAccessor statdate,
                                                  java.time.temporal.TemporalAccessor enddate,
                                                  boolean marineOnly,
                                                  long offset)
                                           throws WormsClientException

Lists all AphiaRecords (max. 50) modified or added between a specific time interval

Parameters:

statdate -

enddate -

marineOnly - Limit to marine taxa.

offset - Starting record number, when retrieving next chunk of (50) records. First record has number 1.

Returns:

Throws:

WormsClientException

Since:

1.0.0

aphiaRecordsByMatchNames

public List<Collection<AphiaRecord>> aphiaRecordsByMatchNames(List<String> scientificNames,
                                                              boolean marineOnly)
                                                       throws WormsClientException

For each given scientific name (may include authority), try to find one or more AphiaRecords, using the TAXAMATCH fuzzy matching algorithm by Tony Rees. This allows you to (fuzzy) match multiple names in one call.

Note: This methods might cause multiple service request.

Parameters:

scientificNames - Names to search for

marineOnly - Limit to marine taxa.

Returns:

Throws:

WormsClientException

Since:

1.0.0

aphiaRecordsByName

public Collection<AphiaRecord> aphiaRecordsByName(String scientificName,
                                                  boolean like,
                                                  boolean marineOnly)
                                           throws WormsClientException

Get one or more matching AphiaRecords for a given name.

Note: This methods might cause multiple calls of aphiaRecordsByName(String, boolean, boolean, long) to receive all records in chunks of 50 records.

Parameters:

scientificName - Name to search for

like - Add a "%"-sign added after the ScientificName (SQL LIKE function).

marineOnly - Limit to marine taxa.

Returns:

Throws:

WormsClientException

Since:

1.0.0

aphiaRecordsByName

public Collection<AphiaRecord> aphiaRecordsByName(String scientificName,
                                                  boolean like,
                                                  boolean marineOnly,
                                                  long offset)
                                           throws WormsClientException

Get one or more matching AphiaRecords (max. 50) for a given name.

Parameters:

scientificName - Name to search for

like - Add a "%"-sign added after the ScientificName (SQL LIKE function).

marineOnly - Limit to marine taxa.

offset - Starting record number, when retrieving next chunk of (50) records. First record has number 1.

Returns:

Throws:

WormsClientException

Since:

1.0.0

aphiaRecordsByNames

public List<Collection<AphiaRecord>> aphiaRecordsByNames(List<String> scientificNames,
                                                         boolean like,
                                                         boolean marineOnly)
                                                  throws WormsClientException

For each given scientific name, try to find one or more AphiaRecords (max. 50). This allows you to match multiple names in one call. Limited to 500 names at once for performance reasons.

Parameters:

scientificNames - Collection of names to search for

like - Add a "%"-sign added after the ScientificName (SQL LIKE function).

marineOnly - Limit to marine taxa.

Returns:

Throws:

WormsClientException

Since:

1.0.0

aphiaRecordsByVernacular

public Collection<AphiaRecord> aphiaRecordsByVernacular(String vernacular,
                                                        boolean like)
                                                 throws WormsClientException

Get one or more Aphia Records for a given vernacular.

Note: This methods might cause multiple request to receive all records in chunks of 50 records.

Parameters:

vernacular - The vernacular to find records for

like - Add a "%"-sign before and after the input (SQL LIKE ‘%vernacular%’ function).

Returns:

Throws:

WormsClientException

Since:

1.0.0

aphiaRecordsByVernacular

public Collection<AphiaRecord> aphiaRecordsByVernacular(String vernacular,
                                                        boolean like,
                                                        long offset)
                                                 throws WormsClientException

Get one or more Aphia Records (max. 50) for a given vernacular.

Parameters:

vernacular - The vernacular to find records for

like - Add a "%"-sign before and after the input (SQL LIKE ‘%vernacular%’ function).

offset - Starting record number, when retrieving next chunk of (50) records. First record has number 1.

Returns:

Throws:

WormsClientException

Since:

1.0.0

aphiaSourcesByAphiaId

public Collection<Source> aphiaSourcesByAphiaId(long aphiaId)
                                         throws WormsClientException

Get one or more sources/references including links, for one AphiaID

Parameters:

aphiaId - The AphiaID to search for

Throws:

WormsClientException

Since:

1.0.0

aphiaSynonymsByAphiaId

public Collection<AphiaRecord> aphiaSynonymsByAphiaId(long aphiaId)
                                               throws WormsClientException

Get all synonyms for a given AphiaID.

Parameters:

aphiaId - The AphiaID to search for

Throws:

WormsClientException

Since:

1.0.0

aphiaVernacularsByAphiaId

public Collection<Vernacular> aphiaVernacularsByAphiaId(long aphiaId)
                                                 throws WormsClientException

Get all vernaculars for a given AphiaID

Parameters:

aphiaId - The AphiaID to search for

Returns:

Throws:

WormsClientException

Since:

1.0.0