uk.ac.ebi.miriam.lib
Class MiriamLink

java.lang.Object
  extended by uk.ac.ebi.miriam.lib.MiriamLink

public class MiriamLink
extends Object

Library for using MIRIAM Registry Web Services easily (via a Java program).

MIRIAM Registry is an online resource created to catalogue biological data collections, their URIs and the corresponding physical URLs, whether these are controlled vocabularies or databases.

See MIRIAM Resources, for more information.

Copyright:
Copyright (C) 2006-2012 BioModels.net (EMBL - European Bioinformatics Institute)
This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

Version:
20120214
Author:
Camille Laibe

Constructor Summary
MiriamLink()
          Default constructor: initialisation of some parameters
 
Method Summary
 boolean checkRegExp(String identifier, String datatype)
          Checks if the identifier given follows the regular expression of its data collection (also provided).
 String convertURL(String url)
          Converts an Identifiers.org URL into its equivalent MIRIAM URN.
 String[] convertURLs(String[] urls)
          Converts a list of Identifiers.org URLs into their equivalent MIRIAM URNs.
 String convertURN(String urn)
          Converts a MIRIAM URN into its equivalent Identifiers.org URL.
 String[] convertURNs(String[] urns)
          Converts a list of MIRIAM URNs into their equivalent Identifiers.org URLs.
 String getAddress()
          Getter of the address of the web services (endPoint).
 String[] getDataEntries(String uri)
          Deprecated. Use getLocations(String) instead.
 String[] getDataEntries(String nickname, String id)
          Deprecated. Use getLocations(String, String) instead.
 String getDataEntry(String uri, String resource)
          Deprecated. Use getLocation(String, String) instead.
 String[] getDataResources(String nickname)
          Retrieves all the physical locations (URLs) of the services providing the data collection (web page).
 String[] getDataTypeAllURIs(String name)
          Deprecated. Use getDataTypeURIs(String) instead.
 String getDataTypeDef(String nickname)
          Retrieves the definition of a data collection.
 String getDataTypePattern(String nickname)
          Retrieves the pattern (regular expression) used by the identifiers within a data collection.
 String[] getDataTypesId()
          Retrieves the internal identifier (stable and perennial) of all the data collections (for example: "MIR:00000005").
 String[] getDataTypesName()
          Retrieves the list of names of all the data collections available.
 String[] getDataTypeSynonyms(String name)
          Retrieves all the synonym names of a data collection (this list includes the original name).
 String getDataTypeURI(String name)
          Retrieves the unique (official) URI of a data collection (example: "urn:miriam:uniprot").
 String getDataTypeURI(String name, String type)
          Deprecated. URLs are not used any more as identifiers in MIRIAM. A new scheme as been released based on URNs. Use getDataTypeURI(String) instead.
 String[] getDataTypeURIs(String name)
          Retrieves all the URIs of a data collection, including all the deprecated ones (examples: "urn:miriam:uniprot", "http://www.uniprot.org/", "urn:lsid:uniprot.org:uniprot", ...).
 String[] getDataTypeURIs(String name, String type)
          Deprecated. URLs are not used any more as identifiers in MIRIAM. A new scheme as been released based on URNs. Use getDataTypeURIs(String) instead.
 String getDataTypeURL(String name)
          Deprecated. URLs are not used any more as identifiers in MIRIAM. A new scheme as been released based on URNs. Use getDataTypeURI(String) instead.
 String[] getDataTypeURLs(String name)
          Deprecated. URLs are not used any more as identifiers in MIRIAM. A new scheme as been released based on URNs. You can use getDataTypeURIs(String) instead.
 String getDataTypeURN(String name)
          Deprecated. Use getDataTypeURI(String) instead.
 String[] getDataTypeURNs(String name)
          Deprecated. Use getDataTypeURIs(String) instead.
 String getLibraryVersion()
          Retrieves the current version of MIRIAM Web Services Library.
 String getLocation(String uri, String resource)
          Retrieves the physical location (URL) of a web page providing knowledge about a specific entity, using a specific resource.
 String[] getLocations(String uri)
          Retrieves the physical locationS (URLs) of web pageS providing knowledge about a specific entity.
 String[] getLocations(String nickname, String id)
          Retrieves the physical locationS (URLs) of web pageS providing knowledge about an entity.
 String[] getLocationsWithToken(String nickname, String token)
          Retrieves the list of (non obsolete) generic physical locations (URLs) of web pageS providing the dataset of a given data collection.
 String getMiriamURI(String uri)
          Transforms a MIRIAM URI into its official equivalent (to transform obsolete URIs into current valid ones).
 String getName(String uri)
          Retrieves the common name of a data collection.
 String[] getNames(String uri)
          Retrieves all the names (with synonyms) of a data collection.
 String getOfficialDataTypeURI(String uri)
          Retrieves the official URI (it will always be URN) of a data collection corresponding to the deprecated one.
 String getOfficialURI(String uri)
          Deprecated. Use getOfficialDataTypeURI(String) instead.
 String getResourceInfo(String id)
          Retrieves the information about a resource.
 String getResourceInstitution(String id)
          Retrieves the institution which manages a resource (example: "European Bioinformatics Institute").
 String getResourceLocation(String id)
          Retrieves the location (or country) of a resource (example: "United Kingdom").
 String getServicesInfo()
          Retrieves some information about these Web Services.
 String getServicesVersion()
          Retrieves the current version of MIRIAM Web Services.
 String getURI(String name, String id)
          Retrieves the unique MIRIAM URI of a specific entity (example: "urn:miriam:obo.go:GO%3A0045202").
 String getURI(String name, String id, String type)
          Deprecated. Use getURI(String, String) instead.
 String[] getURIs(String[] names, String[] ids)
          Retrieves the unique URIs for a list of specific entities (example: "urn:miriam:obo.go:GO%3A0045202").
 String getURL(String name, String id)
          Deprecated. Use getURI(String, String) instead.
 String getURN(String name, String id)
          Deprecated. Use getURI(String, String) instead.
 boolean isDeprecated(String uri)
          To know if a URI of a data collection is deprecated.
 boolean isLibraryUpdated()
          Tests if the Java library used is the latest available.
 void setAddress(String address)
          Setter of the address of the web services (endPoint).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MiriamLink

public MiriamLink()
Default constructor: initialisation of some parameters

Method Detail

setAddress

public void setAddress(String address)
Setter of the address of the web services (endPoint).

Parameters:
address - whole address of the web services

getAddress

public String getAddress()
Getter of the address of the web services (endPoint).

Returns:
whole address of the web services

getLibraryVersion

public String getLibraryVersion()
Retrieves the current version of MIRIAM Web Services Library.

Returns:
Current version of the Library

isLibraryUpdated

public boolean isLibraryUpdated()
Tests if the Java library used is the latest available.

Returns:
is the Java library currently used is the latest or not?

getServicesInfo

public String getServicesInfo()
Retrieves some information about these Web Services.

Returns:
information about the Web Services

getServicesVersion

public String getServicesVersion()
Retrieves the current version of MIRIAM Web Services.

Returns:
Current version of the Web Services

getDataTypeURN

@Deprecated
public String getDataTypeURN(String name)
Deprecated. Use getDataTypeURI(String) instead.

Retrieves the unique official URN of a data collection (example: urn:miriam:uniprot).

Parameters:
name - name primary name (or synonym) of a data collection (examples: "ChEBI", "UniProt", "GO")
Returns:
unique (official) URN of the data collection

getDataTypeURNs

@Deprecated
public String[] getDataTypeURNs(String name)
Deprecated. Use getDataTypeURIs(String) instead.

Retrieves the unique (official) URN of the data collection (example: "urn:miriam:uniprot") and all the deprecated ones.

Parameters:
name - name or synonym of a data collection (examples: "ChEBI", "UniProt")
Returns:
unique URN and all the deprecated ones

getDataTypeURL

@Deprecated
public String getDataTypeURL(String name)
Deprecated. URLs are not used any more as identifiers in MIRIAM. A new scheme as been released based on URNs. Use getDataTypeURI(String) instead.

Retrieves the unique (official) URL (not a physical URL but a URI) of the data collection (example: "http://www.taxonomy.org/").

Parameters:
name - name of a data collection (examples: "ChEBI", "UniProt")
Returns:
unique URL of the data collection

getDataTypeURLs

@Deprecated
public String[] getDataTypeURLs(String name)
Deprecated. URLs are not used any more as identifiers in MIRIAM. A new scheme as been released based on URNs. You can use getDataTypeURIs(String) instead.

Retrieves the unique (official) URL (not a physical URL but a URI) of the data collection (example: "http://www.taxonomy.org/") and all the deprecated ones.

Parameters:
name - name of a data collection (examples: "ChEBI", "UniProt")
Returns:
unique URL of the data collection and all the deprecated ones

getDataTypeURI

@Deprecated
public String getDataTypeURI(String name,
                                        String type)
Deprecated. URLs are not used any more as identifiers in MIRIAM. A new scheme as been released based on URNs. Use getDataTypeURI(String) instead.

Retrieves the unique (official) URL or URN of the data collection (example: "http://www.taxonomy.org/", "urn:lsid:uniprot.org").

Parameters:
name - name of the data collection (examples: "ChEBI", "UniProt")
type - type of the URI the user wants to retrieve ('URN' or 'URL')
Returns:
unique URL or URN of the data collection

getDataTypeURI

public String getDataTypeURI(String name)
Retrieves the unique (official) URI of a data collection (example: "urn:miriam:uniprot").

Parameters:
name - name or synonym of a data collection (examples: "UniProt")
Returns:
unique URI of the data collection

getDataTypeURIs

@Deprecated
public String[] getDataTypeURIs(String name,
                                           String type)
Deprecated. URLs are not used any more as identifiers in MIRIAM. A new scheme as been released based on URNs. Use getDataTypeURIs(String) instead.

Retrieves all the URLs or URNs of the data collection (examples: "urn:miriam:uniprot", "http://www.taxonomy.org/") including all the deprecated ones.

Parameters:
name - name of the data collection (examples: "ChEBI", "UniProt")
type - type of the URI the user wants to recover ('URN' or 'URL')
Returns:
all the URIs (URLs or URNs) of the data collection including all the deprecated ones

getDataTypeAllURIs

@Deprecated
public String[] getDataTypeAllURIs(String name)
Deprecated. Use getDataTypeURIs(String) instead.

Retrieves all the URIs (URNs and URLs) of the data collection

Parameters:
name - name of a data collection (examples: "ChEBI", "UniProt")
Returns:
all the URIs (URLs and URNs) of the data collection including all the deprecated ones

getDataTypeURIs

public String[] getDataTypeURIs(String name)
Retrieves all the URIs of a data collection, including all the deprecated ones (examples: "urn:miriam:uniprot", "http://www.uniprot.org/", "urn:lsid:uniprot.org:uniprot", ...).

Parameters:
name - name (or synonym) of the data collection (examples: "ChEBI", "UniProt")
Returns:
all the URIs of a data collection (including the deprecated ones)

getResourceLocation

public String getResourceLocation(String id)
Retrieves the location (or country) of a resource (example: "United Kingdom").

Parameters:
id - identifier of a resource (example: "MIR:00100009")
Returns:
the location (the country) where the resource is managed

getResourceInstitution

public String getResourceInstitution(String id)
Retrieves the institution which manages a resource (example: "European Bioinformatics Institute").

Parameters:
id - identifier of a resource (example: "MIR:00100009")
Returns:
the institution managing the resource

getResourceInfo

public String getResourceInfo(String id)
Retrieves the information about a resource.

Parameters:
id - identifier of a resource (example: "MIR:00100009")
Returns:
some information about the resource

getURN

@Deprecated
public String getURN(String name,
                                String id)
Deprecated. Use getURI(String, String) instead.

Retrieves the unique URN of the data-entry (example: "urn:miriam:uniprot:P62158").

Parameters:
name - name of a data collection (examples: "ChEBI", "UniProt")
id - identifier of an element (examples: "GO:0045202", "P62158")
Returns:
unique URN of the data-entry

getURL

@Deprecated
public String getURL(String name,
                                String id)
Deprecated. Use getURI(String, String) instead.

Retrieves unique URL of the data-entry (example: "urn:miriam:obo.go:GO%3A0045202").

Parameters:
name - name of a data collection (examples: "ChEBI", "UniProt")
id - identifier of an element (examples: "GO:0045202", "P62158")
Returns:
unique URN of the data-entry

getURI

@Deprecated
public String getURI(String name,
                                String id,
                                String type)
Deprecated. Use getURI(String, String) instead.

Retrieves the unique URI (URL or URN) of the data-entry (example: "urn:miriam:obo.go:GO%3A0045202").

Parameters:
name - name of a data collection (examples: "ChEBI", "UniProt")
id - identifier of an element (examples: "GO:0045202", "P62158")
type - type of the URI the user wants to recover ('URN' or 'URL')
Returns:
unique URI of the data-entry

getURI

public String getURI(String name,
                     String id)
Retrieves the unique MIRIAM URI of a specific entity (example: "urn:miriam:obo.go:GO%3A0045202"). If the data collection does not exist (or is not recognised), an empty String is returned. If the identifier is invalid for the given data collection, 'null' is returned.

Parameters:
name - name of a data collection (examples: "ChEBI", "UniProt")
id - identifier of an entity within the data collection (examples: "GO:0045202", "P62158")
Returns:
unique MIRIAM URI of a given entity

getURIs

public String[] getURIs(String[] names,
                        String[] ids)
Retrieves the unique URIs for a list of specific entities (example: "urn:miriam:obo.go:GO%3A0045202"). If a data collection does not exist (or is not recognised), an empty String is returned for this data collection. If an identifier is invalid for the given data collection, 'null' is returned for this data collection. If the provided lists do not have the same size, 'null' is returned. If the size of any list exceed 200, 'null' is returned.

Parameters:
names - list of data collection names (examples: "ChEBI", "UniProt")
ids - list of entities identifiers (examples: "GO:0045202", "P62158")
Returns:
list of MIRIAM URIs

getDataTypeDef

public String getDataTypeDef(String nickname)
Retrieves the definition of a data collection.

Parameters:
nickname - name or URI (URN or URL) of a data collection
Returns:
definition of the data collection

getDataEntries

@Deprecated
public String[] getDataEntries(String nickname,
                                          String id)
Deprecated. Use getLocations(String, String) instead.

Retrieves the physical locationS (URLs) of web pageS about the data-entry.

Parameters:
nickname - name (can be a synonym) or URN or URL of a data collection (examples: "ChEBI", "UniProt")
id - identifier of an element (examples: "GO:0045202", "P62158")
Returns:
physical locationS of web pageS about the data-entry

getDataEntries

@Deprecated
public String[] getDataEntries(String uri)
Deprecated. Use getLocations(String) instead.

Retrieves the physical locationS (URLs) of web pageS about the data-entry.

Parameters:
uri - MIRIAM URI of an element (example: 'urn:miriam:obo.go:GO%3A0045202')
Returns:
physical locationS of web pageS about the data-entry

getDataEntry

@Deprecated
public String getDataEntry(String uri,
                                      String resource)
Deprecated. Use getLocation(String, String) instead.

Retrieves the physical location (URL) of a web page about the data-entry, using a specific resource.

Parameters:
uri - MIRIAM URI of an element (example: 'urn:miriam:obo.go:GO%3A0045202')
resource - internal identifier of a resource (example: 'MIR:00100005')
Returns:
physical location of a web page about the data-entry, using a specific resource

getLocation

public String getLocation(String uri,
                          String resource)
Retrieves the physical location (URL) of a web page providing knowledge about a specific entity, using a specific resource. All special characters in the data entry part of the URL are properly encoded.

Parameters:
uri - MIRIAM URI of an entity (example: 'urn:miriam:obo.go:GO%3A0045202')
resource - internal identifier of a resource (example: 'MIR:00100005')
Returns:
physical location of a web page providing knowledge about the given entity, using a specific resource

getLocations

public String[] getLocations(String uri)
Retrieves the physical locationS (URLs) of web pageS providing knowledge about a specific entity. If the URI is not recognised or the data collection does not exist, an empty array is returned. If the identifier is invalid for the data collection, 'null' is returned. All special characters in the data entry part of the URLs are properly encoded.

Parameters:
uri - MIRIAM URI of an entity (example: 'urn:miriam:obo.go:GO%3A0045202')
Returns:
physical locationS of web pageS providing knowledge about the given entity

getLocations

public String[] getLocations(String nickname,
                             String id)
Retrieves the physical locationS (URLs) of web pageS providing knowledge about an entity. If the URI is not recognised or the data collection does not exist, an empty array is returned. If the identifier is invalid for the data collection, 'null' is returned. All special characters in the data entry part of the URLs are properly encoded.

Parameters:
nickname - name (can be a synonym) or URI of a data collection (examples: "Gene Ontology", "UniProt")
id - identifier of an entity within the given data collection (examples: "GO:0045202", "P62158")
Returns:
physical locationS of web pageS providing knowledge about the given entity

getLocationsWithToken

public String[] getLocationsWithToken(String nickname,
                                      String token)
Retrieves the list of (non obsolete) generic physical locations (URLs) of web pageS providing the dataset of a given data collection. Warning: those URLs cannot be directly used! They contain a token which needs to be replaced by an actual data entry identifier. If the data collection is not recognised or does not exist, 'null' is returned. All special characters in the data entry part of the URLs are properly encoded.

Parameters:
nickname - name (can be a synonym) or URI of a data collection (examples: "Gene Ontology", "UniProt", "urn:miriam:biomodels.db")
token - placeholder which will be put in the URLs at the location of the data entry identifier (default: $id).
Returns:
physical locationS of web pageS providing knowledge about the given entity

getMiriamURI

public String getMiriamURI(String uri)
Transforms a MIRIAM URI into its official equivalent (to transform obsolete URIs into current valid ones). The parameter can be an obsolete URI (URN or URL), but the returned one will always be a URN. This process involve a percent-encoding of all reserved characters (like ':').

Parameters:
uri - deprecated URI (URN or URL), example: "http://www.ebi.ac.uk/chebi/#CHEBI:17891"
Returns:
the official URI corresponding to the deprecated one, example: "urn:miriam:obo.chebi:CHEBI%3A17891"

getDataResources

public String[] getDataResources(String nickname)
Retrieves all the physical locations (URLs) of the services providing the data collection (web page).

Parameters:
nickname - name (can be a synonym) or URL or URN of a data collection name (or synonym) or URI (URL or URN)
Returns:
array of strings containing all the address of the main page of the resources of the data collection

isDeprecated

public boolean isDeprecated(String uri)
To know if a URI of a data collection is deprecated.

Parameters:
uri - (URN or URL) of a data collection
Returns:
answer ("true" or "false") to the question: is this URI deprecated?

getOfficialURI

@Deprecated
public String getOfficialURI(String uri)
Deprecated. Use getOfficialDataTypeURI(String) instead.

Retrieves the official URI (it will always be URN) of a data collection corresponding to the deprecated one.

Parameters:
uri - deprecated URI (URN or URL) of a data collection
Returns:
the official URI corresponding to the deprecated one

getDataTypePattern

public String getDataTypePattern(String nickname)
Retrieves the pattern (regular expression) used by the identifiers within a data collection.

Parameters:
nickname - data collection name (or synonym) or URI (URL or URN)
Returns:
pattern of the data collection

getDataTypeSynonyms

public String[] getDataTypeSynonyms(String name)
Retrieves all the synonym names of a data collection (this list includes the original name).

Parameters:
name - name or synonym of a data collection
Returns:
all the synonym names of the data collection

getName

public String getName(String uri)
Retrieves the common name of a data collection.

Parameters:
uri - URI (URL or URN) of a data collection
Returns:
the common name of the data collection

getNames

public String[] getNames(String uri)
Retrieves all the names (with synonyms) of a data collection.

Parameters:
uri - URI (URL or URN) of a data collection
Returns:
the common name of the data collection and all the synonyms

getDataTypesName

public String[] getDataTypesName()
Retrieves the list of names of all the data collections available.

Returns:
list of names of all the data collections

getDataTypesId

public String[] getDataTypesId()
Retrieves the internal identifier (stable and perennial) of all the data collections (for example: "MIR:00000005").

Returns:
list of the identifier of all the data collections

getOfficialDataTypeURI

public String getOfficialDataTypeURI(String uri)
Retrieves the official URI (it will always be URN) of a data collection corresponding to the deprecated one.

Parameters:
uri - deprecated URI (URN or URL) of a data collection
Returns:
the official URI of a data collection corresponding to the deprecated one

checkRegExp

public boolean checkRegExp(String identifier,
                           String datatype)
Checks if the identifier given follows the regular expression of its data collection (also provided).

Parameters:
identifier - internal identifier used by the data collection
datatype - name, synonym or URI of a data collection
Returns:
"true" if the identifier follows the regular expression, "false" otherwise

convertURN

public String convertURN(String urn)
Converts a MIRIAM URN into its equivalent Identifiers.org URL. This takes care of any necessary conversion, for example in the case the URN provided is obsolete.

Parameters:
urn - a MIRIAM URN
Returns:
the Identifiers.org URL corresponding to the provided URN or 'null' if the provided URN does not exist

convertURNs

public String[] convertURNs(String[] urns)
Converts a list of MIRIAM URNs into their equivalent Identifiers.org URLs. This takes care of any necessary conversion, for example in the case a URN provided is obsolete. If a URN is invalid, 'null' is returned for this URN. If the size of the list of URNs exceeds 200, 'null' is returned.

Parameters:
urns - a list of MIRIAM URNs
Returns:
a list of Identifiers.org URLs corresponding to the provided URNs

convertURL

public String convertURL(String url)
Converts an Identifiers.org URL into its equivalent MIRIAM URN. This performs a check of the identifier based on the recorded regular expression.

Parameters:
url - an Identifiers.org URL
Returns:
the MIRIAM URN corresponding to the provided Identifiers.org URL or 'null' if the provided URL does not exist

convertURLs

public String[] convertURLs(String[] urls)
Converts a list of Identifiers.org URLs into their equivalent MIRIAM URNs. This performs a check of the identifier based on the recorded regular expression. If a URL is invalid, 'null' is returned for this URL. If the size of the list of URLs exceeds 200, 'null' is returned.

Parameters:
urls - a list of Identifiers.org URLs
Returns:
a list of MIRIAM URNs corresponding to the provided Identifiers.org URLs


BioModels.net, EMBL-EBI - Feb 2012