org.bridgedb

Class IDMapperStack

java.lang.Object

org.bridgedb.IDMapperStack

All Implemented Interfaces:

AttributeMapper, IDMapper

public class IDMapperStack
extends Object
implements IDMapper, AttributeMapper

combines multiple IDMapper's in a stack.

The behavior of the IDMapper interface implementations differs per method: if the method returns a single result, usually it is from the first child database that has a sensible result. This also means that the child databases have a definitive ordering: the first one shadows the second one for some results.

If the method returns a list, IDMapperStack joins the result from all connected child databases together.

Transitive maps are deduced from the IDMappers, added to this IDMapperStack. Transitive maps are enabled as soon as the transitivity is set to be true.

In order to calculate the deduced transitive mappings, we build a graph that represents the possible mappings supported by the IDMappers in this IDMapperStack. The nodes of this graph are DataSources, the Edges are IDMappers. Possible mappings are loop free paths in this graph. We consider a path p to be loop free if no data source in p is reached twice by the same IDMapper.

The mapping graph for transitive maps is retained and re-calculated whenever an IDMapper is added or removed from this IDMapperStack.

Field Summary

Fields inherited from interface org.bridgedb.AttributeMapper

MATCH_ID

Constructor Summary

Constructors

Constructor and Description
IDMapperStack()

Method Summary

Modifier and Type	Method and Description
void	addIDMapper(IDMapper idMapper) Add an existing IDMapper to the stack.
IDMapper	addIDMapper(String connectionString) Create a fresh IDMapper from a connectionString and add it to the stack.
void	close() closes all child databases.
Map<Xref,String>	freeAttributeSearch(String query, String attrType, int limit) free text search for matching attributes.
Map<Xref,Set<String>>	freeAttributeSearchEx(String query, String attrType, int limit) Improved version of free text search for matching attributes.
Set<Xref>	freeSearch(String text, int limit) free text search for matching symbols or identifiers.
Map<String,Set<String>>	getAttributes(Xref ref) Get all attributes for an entity.
Set<String>	getAttributes(Xref ref, String attrname) Get attributes for an entity, such as gene Symbol.
Set<String>	getAttributeSet() Set of attributes provided by this AttributeMapper.
Map<String,Set<String>>	getAttributesForAllMappings(Xref ref, DataSource... dataSources)
Set<String>	getAttributesForAllMappings(Xref ref, String attrname, DataSource... dataSources)
IDMapperCapabilities	getCapabilities()
IDMapper	getIDMapperAt(int index)
List<IDMapper>	getMappers() get all mappers
int	getSize()
boolean	getTransitive()
boolean	isConnected() Use this method to check if the IDMapper is still valid.
boolean	isFreeAttributeSearchSupported()
Map<Xref,Set<Xref>>	mapID(Collection<Xref> srcXrefs, DataSource... tgtDataSources) Get all cross-references for a set of entities, restricting the result to contain only references from the given set of data sources.
Set<Xref>	mapID(Xref ref, DataSource... resultDs) Get all cross-references for the given entity, restricting the result to contain only references from the given set of data sources.
void	removeIDMapper(IDMapper idMapper) Remove an idMapper from the stack.
void	setTransitive(boolean value) Set Transitivity mode, where all mappings are combined to infer second degree mappings.
String	toString()
boolean	xrefExists(Xref xref) Check whether an Xref is known by the given mapping source.

Methods inherited from class java.lang.Object

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

Constructor Detail

IDMapperStack

public IDMapperStack()

Method Detail

addIDMapper

public IDMapper addIDMapper(String connectionString)
                     throws IDMapperException

Create a fresh IDMapper from a connectionString and add it to the stack.

Parameters:

connectionString - connectionString for configuring the new IDMapper

Returns:

the newly created IDMapper

Throws:

IDMapperException - when the connection failed.

addIDMapper

public void addIDMapper(IDMapper idMapper)

Add an existing IDMapper to the stack.

Parameters:

idMapper - IDMapper to be added.

setTransitive

public void setTransitive(boolean value)

Set Transitivity mode, where all mappings are combined to infer second degree mappings.

Parameters:

value - true or false

getTransitive

public boolean getTransitive()

Returns:

true if the stack is in transitive mode

removeIDMapper

public void removeIDMapper(IDMapper idMapper)

Remove an idMapper from the stack. Automatically rebuilds the mapping graph.

Parameters:

idMapper - IDMapper to be removed.

close

public void close()
           throws IDMapperException

closes all child databases.

Specified by:

close in interface IDMapper

Throws:

IDMapperException - when closing failed for one of the databases. It will still try to close all child databases even if one throws an exception. However, only the last exception will be thrown.

xrefExists

public boolean xrefExists(Xref xref)
                   throws IDMapperException

Check whether an Xref is known by the given mapping source. This is an optionally supported operation.

Specified by:

xrefExists in interface IDMapper

Parameters:

xref - reference to check

Returns:

if the reference exists, false if not

Throws:

IDMapperException - if failed, UnsupportedOperationException if it's not supported by the Driver.

isConnected

public boolean isConnected()

Description copied from interface: IDMapper

Use this method to check if the IDMapper is still valid.

Specified by:

isConnected in interface IDMapper

Returns:

true if at least one of the child services are connected.

getCapabilities

public IDMapperCapabilities getCapabilities()

Specified by:

getCapabilities in interface IDMapper

Returns:

an object describing the capabilities of the combined stack of services.

freeSearch

public Set<Xref> freeSearch(String text,
                            int limit)
                     throws IDMapperException

free text search for matching symbols or identifiers.

Specified by:

freeSearch in interface IDMapper

Parameters:

text - text to search

limit - up limit of number of hits

Returns:

a set of hit references

Throws:

IDMapperException - if failed

mapID

public Map<Xref,Set<Xref>> mapID(Collection<Xref> srcXrefs,
                                 DataSource... tgtDataSources)
                          throws IDMapperException

Get all cross-references for a set of entities, restricting the result to contain only references from the given set of data sources. Supports one-to-one mapping and one-to-many mapping.

Specified by:

mapID in interface IDMapper

Parameters:

srcXrefs - source Xref, containing ID and ID type/data source

tgtDataSources - target ID types/data sources. Set this to null if you want to retrieve all results.

Returns:

a map from source Xref to target Xref's. The map is not guaranteed to contain a result for each srcXrefs you pass in. This method will never return null however.

Throws:

IDMapperException - if the mapping service is (temporarily) unavailable

getAttributes

public Set<String> getAttributes(Xref ref,
                                 String attrname)
                          throws IDMapperException

Get attributes for an entity, such as gene Symbol.

Specified by:

getAttributes in interface AttributeMapper

Parameters:

ref - the entity to get the attribute for

attrname - the attribute to look for, e.g. 'Symbol' or 'Description'.

Returns:

the attribute, or null if nothing was found

Throws:

IDMapperException - if the mapping service is (temporarily) unavailable

getAttributesForAllMappings

public Set<String> getAttributesForAllMappings(Xref ref,
                                               String attrname,
                                               DataSource... dataSources)
                                        throws IDMapperException

Throws:

IDMapperException

isFreeAttributeSearchSupported

public boolean isFreeAttributeSearchSupported()

Specified by:

isFreeAttributeSearchSupported in interface AttributeMapper

Returns:

true if free attribute search is supported by one of the children

freeAttributeSearch

public Map<Xref,String> freeAttributeSearch(String query,
                                            String attrType,
                                            int limit)
                                     throws IDMapperException

free text search for matching attributes.

Specified by:

freeAttributeSearch in interface AttributeMapper

Parameters:

query - The text to search for

attrType - the attribute to look for, e.g. 'Symbol' or 'Description'. If you use the special MATCH_ID constant, it will query the identifier instead.

limit - The number of results to limit the search to

Returns:

map references and attribute values that match the query

Throws:

IDMapperException - if the mapping service is (temporarily) unavailable

freeAttributeSearchEx

public Map<Xref,Set<String>> freeAttributeSearchEx(String query,
                                                   String attrType,
                                                   int limit)
                                            throws IDMapperException

Description copied from interface: AttributeMapper

Improved version of free text search for matching attributes. Unlike freeAttributeSearch, this method may return multiple results per xref.

Specified by:

freeAttributeSearchEx in interface AttributeMapper

Parameters:

query - The text to search for

attrType - the attribute to look for, e.g. 'Symbol' or 'Description'. If you use the special MATCH_ID constant, it will query the identifier instead.

limit - The number of results to limit the search to

Returns:

map of references and attribute values that match the query

Throws:

IDMapperException - if the mapping service is (temporarily) unavailable

toString

public String toString()

Overrides:

toString in class Object

Returns:

concatenation of toString of each child

getSize

public int getSize()

Returns:

number of child databases

getIDMapperAt

public IDMapper getIDMapperAt(int index)

Parameters:

index - in the range 0 <= index < getSize()

Returns:

the IDMapper at the given position

mapID

public Set<Xref> mapID(Xref ref,
                       DataSource... resultDs)
                throws IDMapperException

Get all cross-references for the given entity, restricting the result to contain only references from the given set of data sources.

Specified by:

mapID in interface IDMapper

Parameters:

ref - the entity to get cross-references for.

resultDs - target ID types/data sources. Set this to null if you want to retrieve all results.

Returns:

A Set containing the cross references, or an empty Set when no cross references could be found. This method does not return null.

Throws:

IDMapperException - if the mapping service is (temporarily) unavailable

getAttributeSet

public Set<String> getAttributeSet()
                            throws IDMapperException

Set of attributes provided by this AttributeMapper. There is no guarantee that a specific Xref has these attributes.

Specified by:

getAttributeSet in interface AttributeMapper

Returns:

set of available attributes in this AttributeMapper. If there are none available, returns an empty set.

Throws:

IDMapperException - if the mapping service is (temporarily) unavailable

getAttributes

public Map<String,Set<String>> getAttributes(Xref ref)
                                      throws IDMapperException

Get all attributes for an entity. Usually this method is more efficient if you want to query several attributes in a sequence.

Specified by:

getAttributes in interface AttributeMapper

Parameters:

ref - the entity to get the attributes for

Returns:

a Map where attribute names are the keys and attribute values are the values.

Throws:

IDMapperException - if the mapping service is (temporarily) unavailable

getAttributesForAllMappings

public Map<String,Set<String>> getAttributesForAllMappings(Xref ref,
                                                           DataSource... dataSources)
                                                    throws IDMapperException

Throws:

IDMapperException

getMappers

public List<IDMapper> getMappers()

get all mappers