org.biojavax.bio.seq
Class CompoundRichLocation

java.lang.Object
  org.biojava.utils.AbstractChangeable
      org.biojavax.bio.seq.SimpleRichLocation
          org.biojavax.bio.seq.CompoundRichLocation

All Implemented Interfaces:

Comparable, Annotatable, Location, Changeable, RichLocation, RichAnnotatable

Direct Known Subclasses:

MultiSourceCompoundRichLocation

public class CompoundRichLocation
extends SimpleRichLocation
implements RichLocation

An implementation of RichLocation which covers multiple locations, but on the same strand of the same (optionally circular) sequence.

Since:

1.5

Author:

Richard Holland, Mark Schreiber

Nested Class Summary

Nested classes/interfaces inherited from interface org.biojavax.bio.seq.RichLocation

RichLocation.Strand, RichLocation.Tools

Nested classes/interfaces inherited from interface org.biojava.bio.Annotatable

Annotatable.AnnotationForwarder

Field Summary

protected List	members
protected int	size

Fields inherited from class org.biojavax.bio.seq.SimpleRichLocation

circularLength, term

Fields inherited from interface org.biojavax.bio.seq.RichLocation

CIRCULAR, EMPTY_LOCATION, FEATURE, NOTE, RANK, TERM

Fields inherited from interface org.biojava.bio.symbol.Location

empty, full, naturalOrder

Fields inherited from interface org.biojava.bio.Annotatable

ANNOTATION

Constructor Summary

protected	CompoundRichLocation()
	CompoundRichLocation(Collection members) Constructs a CompoundRichLocation from the given set of members, with the default term of "join".
	CompoundRichLocation(ComparableTerm term, Collection members) Constructs a CompoundRichLocation from the given set of members.

Method Summary

Iterator	blockIterator() Return an Iterator over the set of maximal contiguous sub-locations. Given any location, it can be considered to contain zero or more maximal contiguous blocks of width 1 or greater. The empty location is composed from nothing. A contiguous location is composed from itself. A non-contiguous location is composed from contiguous blocks seperated by gaps. This method should return an Iterator over these maximally contiguous blocks starting with the left-most block, and finishing at the right-most block.
int	compareTo(Object o) Locations are sorted first by rank, then crossref, then strand, then term, then min, then max.
boolean	contains(int p) Checks if this location contains a point. Recursively applies this call to all members.
boolean	contains(Location l) Checks if this location contains the other. Abstractly, a location contains another if every point in the other location is contained within this one. A location contains another location if it overlaps it, and the coordinates enclose those of the other location at both ends, and they fall on the same strand. Recursively applies this call to all members.
boolean	equals(Object o) Checks if this location is equivalent to the other. Abstractly, a location is equal to another if for every point in one it is also in the other. This is equivalent to a.contains(b) && b.contains(a). You should call LocationTools.areEqual after casting l to Location. Locations are equal if their term, min, max, strand, and crossref are the same, and if their rank is the same too. Compound locations are only equal to other Locations if all their components are equal.
Annotation	getAnnotation() Should return the associated annotation object. ALWAYS RETURNS THE EMPTY ANNOTATION
Location	getDecorator(Class decoratorClass) Checks the decorator chain for an instance of decoratorClass and return it if found. The default behavior is to return null. If the current object is a decorator and is an instance of decoratorClass it should return itself. Otherwise, the decorator should chain this method onto the instance it wraps. ALWAYS RETURNS NULL
static ComparableTerm	getJoinTerm() Getter for the "join" term
Set	getNoteSet() Returns the set of notes associated with this object. Would normally delegate call to internal RichAnnotation instance. Warning this method gives access to the original Collection not a copy. ALWAYS RETURNS THE EMPTY ANNOTATION NOTE SET
static ComparableTerm	getOrderTerm() Getter for the "order" term
RichAnnotation	getRichAnnotation() Return the associated annotation object. ALWAYS RETURNS THE EMPTY ANNOTATION
int	hashCode()
Location	intersection(Location l) Returns a Location that contains all points common to both ranges. If the locations overlap and are on the same strand, the intersection is returned. If passed a Location which is not a RichLocation, it converts it first using RichLocation.Tools.enrich().
boolean	isContiguous() Determine if a Location is contiguous. ALWAYS RETURNS FALSE
Location	newInstance(Location loc) Create a new instance of Location with all of the same decorators as this instance but with the data stored in loc. The default behavior is to return loc unchanged. If the class is a location decorator then it should instantiate an instance of the same type that decorates loc. ALWAYS RETURNS SELF
boolean	overlaps(Location l) Checks if these two locations overlap, using this location's concept of overlapping. Abstractly, two locations overlap if they both contain any point. A location overlaps another location if it is on the same sequence, and the coordinates overlap, and both are of the same circularity. Recursively applies this call to all members.
void	setCircularLength(int sourceSeqLength) Sets the circular length of this location. If it is 0, the location is not circular. If it is not zero, then the number refers to the wrapping length of the location. eg. 100 would signify that a position of 112 would actually be a position of 112-100 = 12. RECURSIVELY APPLIES CALL TO ALL MEMBERS
void	setCrossRefResolver(CrossReferenceResolver r) Sets the cross ref resolver to use when retrieving remote symbols. If none is given, then the default from RichObjectFactory.getDefaultCrossRefResolver() is used. Recursively applies this call to all members.
void	setFeature(RichFeature feature) Sets the feature this location is associated with. If null, that's fine, but you won't be able to persist it to the database until you give it a not-null value. Passes the call on to each of its members in turn.
void	setNoteSet(Set notes) Clears the notes associated with this object and replaces them with the contents of this set. Would normally delegate call to internal RichAnnotation instance. Warning this method gives access to the original Collection not a copy. NOT IMPLEMENTED
void	setTerm(ComparableTerm term) Sets the term for this location.
void	sort() Sorts the member locations of a compound location. Does nothing for non-compound locations. Sorting depends on the compareTo() method of the member locations - usually they will be sorted by their start position. This might be useful when used with the location returned by a union or intersection, or when setting the term of a compound location to ORDER_TERM.
SymbolList	symbols(SymbolList seq) Return the symbols in a sequence that fall within this range. If the location is circular but the sequence is not, or they are both circular but of different circular lengths, an exception is thrown. This function concatenates the symbols of all its child locations.
String	toString() Form: "start..end" or just "point" for point locations Form: "term:[location,location...]"
Location	translate(int dist) Create a location that is a translation of this location. Recursively translates all members of this location.
Location	union(Location l) Return a Location containing all points in either ranges. A merged SimpleRichLocation is returned if the two locations overlap and are on the same strand. If passed a Location which is not a RichLocation, it converts it first using RichLocation.Tools.enrich().

Methods inherited from class org.biojavax.bio.seq.SimpleRichLocation

getCircularLength, getCrossRef, getFeature, getId, getMax, getMaxPosition, getMin, getMinPosition, getRank, getStrand, getTerm, posmax, posmin, setCrossRef, setId, setMaxPosition, setMinPosition, setPositionResolver, setRank, setStrand

Methods inherited from class org.biojava.utils.AbstractChangeable

addChangeListener, addChangeListener, generateChangeSupport, getChangeSupport, hasListeners, hasListeners, isUnchanging, removeChangeListener, removeChangeListener

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.biojavax.bio.seq.RichLocation

getCircularLength, getCrossRef, getFeature, getMaxPosition, getMinPosition, getRank, getStrand, getTerm, setPositionResolver, setRank

Methods inherited from interface org.biojava.bio.symbol.Location

getMax, getMin

Methods inherited from interface org.biojava.utils.Changeable

addChangeListener, addChangeListener, isUnchanging, removeChangeListener, removeChangeListener

Field Detail

members

protected List members

size

protected int size

Constructor Detail

CompoundRichLocation

public CompoundRichLocation(Collection members)

Constructs a CompoundRichLocation from the given set of members, with the default term of "join". Note that you really shouldn't use this if you are unsure if your members set contains overlapping members. Use RichLocation.Tools.construct() instead. The members collection must only contain Location instances. Any that are not RichLocations will be converted using RichLocation.Tools.enrich(). All members must come from the same strand of the same sequence with the same circular length.

Parameters:

members - the members to put into the compound location.

See Also:

RichLocation.Tools

CompoundRichLocation

public CompoundRichLocation(ComparableTerm term,
                            Collection members)

Constructs a CompoundRichLocation from the given set of members. Note that you really shouldn't use this if you are unsure if your members set contains overlapping members. Use RichLocation.Tools.construct(members) instead. The members collection must only contain Location instances. Any that are not RichLocations will be converted using RichLocation.Tools.enrich().

Parameters:

term - the term to use when describing the group of members.

members - the members to put into the compound location.

See Also:

RichLocation.Tools

CompoundRichLocation

protected CompoundRichLocation()

Method Detail

getJoinTerm

public static ComparableTerm getJoinTerm()

Getter for the "join" term

Returns:

the "join" term

getOrderTerm

public static ComparableTerm getOrderTerm()

Getter for the "order" term

Returns:

the "order" term

sort

public void sort()

Sorts the member locations of a compound location. Does nothing for non-compound locations. Sorting depends on the compareTo() method of the member locations - usually they will be sorted by their start position. This might be useful when used with the location returned by a union or intersection, or when setting the term of a compound location to ORDER_TERM.

Specified by:

sort in interface RichLocation

Overrides:

sort in class SimpleRichLocation

setFeature

public void setFeature(RichFeature feature)
                throws ChangeVetoException

Sets the feature this location is associated with. If null, that's fine, but you won't be able to persist it to the database until you give it a not-null value. Passes the call on to each of its members in turn.

Specified by:

setFeature in interface RichLocation

Overrides:

setFeature in class SimpleRichLocation

Parameters:

feature - the feature.

Throws:

ChangeVetoException

getAnnotation

public Annotation getAnnotation()

Should return the associated annotation object. ALWAYS RETURNS THE EMPTY ANNOTATION

Specified by:

getAnnotation in interface Annotatable

Overrides:

getAnnotation in class SimpleRichLocation

Returns:

an Annotation object, never null

getRichAnnotation

public RichAnnotation getRichAnnotation()

Return the associated annotation object. ALWAYS RETURNS THE EMPTY ANNOTATION

Specified by:

getRichAnnotation in interface RichAnnotatable

Overrides:

getRichAnnotation in class SimpleRichLocation

Returns:

a RichAnnotation object, never null

getNoteSet

public Set getNoteSet()

Returns the set of notes associated with this object. Would normally delegate call to internal RichAnnotation instance. Warning this method gives access to the original Collection not a copy. This is required by Hibernate. If you modify the object directly the behaviour may be unpredictable. ALWAYS RETURNS THE EMPTY ANNOTATION NOTE SET

Specified by:

getNoteSet in interface RichAnnotatable

Overrides:

getNoteSet in class SimpleRichLocation

Returns:

set a set of Note objects.

See Also:

Note

setNoteSet

public void setNoteSet(Set notes)
                throws ChangeVetoException

Clears the notes associated with this object and replaces them with the contents of this set. Would normally delegate call to internal RichAnnotation instance. Warning this method gives access to the original Collection not a copy. This is required by Hibernate. If you modify the object directly the behaviour may be unpredictable. NOT IMPLEMENTED

Specified by:

setNoteSet in interface RichAnnotatable

Overrides:

setNoteSet in class SimpleRichLocation

Parameters:

notes - the set of Note objects to replace the existing ones with.

Throws:

ChangeVetoException - ALWAYS

See Also:

Note

setCircularLength

public void setCircularLength(int sourceSeqLength)
                       throws ChangeVetoException

Sets the circular length of this location. If it is 0, the location is not circular. If it is not zero, then the number refers to the wrapping length of the location. eg. 100 would signify that a position of 112 would actually be a position of 112-100 = 12. RECURSIVELY APPLIES CALL TO ALL MEMBERS

Specified by:

setCircularLength in interface RichLocation

Overrides:

setCircularLength in class SimpleRichLocation

Parameters:

sourceSeqLength - the circular length of this location

Throws:

ChangeVetoException - if it doesn't want to change.

blockIterator

public Iterator blockIterator()

Return an Iterator over the set of maximal contiguous sub-locations.

Given any location, it can be considered to contain zero or more maximal contiguous blocks of width 1 or greater. The empty location is composed from nothing. A contiguous location is composed from itself. A non-contiguous location is composed from contiguous blocks seperated by gaps.

This method should return an Iterator over these maximally contiguous blocks starting with the left-most block, and finishing at the right-most block.

Specified by:

blockIterator in interface Location

Overrides:

blockIterator in class SimpleRichLocation

Returns:

an Iterator over Location objects that are the maximally contiguous set of locations contained within this location

isContiguous

public boolean isContiguous()

Determine if a Location is contiguous. ALWAYS RETURNS FALSE

Specified by:

isContiguous in interface Location

Overrides:

isContiguous in class SimpleRichLocation

Returns:

true if and only if this Location contains every point from min to max inclusive.

contains

public boolean contains(int p)

Checks if this location contains a point. Recursively applies this call to all members.

Specified by:

contains in interface Location

Overrides:

contains in class SimpleRichLocation

Parameters:

p - the point to check

Returns:

true if this contains p, otherwise false

getDecorator

public Location getDecorator(Class decoratorClass)

Checks the decorator chain for an instance of decoratorClass and return it if found.

The default behavior is to return null. If the current object is a decorator and is an instance of decoratorClass it should return itself. Otherwise, the decorator should chain this method onto the instance it wraps. ALWAYS RETURNS NULL

Specified by:

getDecorator in interface Location

Overrides:

getDecorator in class SimpleRichLocation

Parameters:

decoratorClass - the Class to check

Returns:

a Location if an instance of this class is present in the decorator chain and null otherwise.

newInstance

public Location newInstance(Location loc)

Create a new instance of Location with all of the same decorators as this instance but with the data stored in loc.

The default behavior is to return loc unchanged. If the class is a location decorator then it should instantiate an instance of the same type that decorates loc. ALWAYS RETURNS SELF

Specified by:

newInstance in interface Location

Overrides:

newInstance in class SimpleRichLocation

Parameters:

loc - the Location to use as template

Returns:

a Location instance based on loc with the same decorators as the current instance

translate

public Location translate(int dist)

Create a location that is a translation of this location. Recursively translates all members of this location.

Specified by:

translate in interface Location

Overrides:

translate in class SimpleRichLocation

Parameters:

dist - the distance to translate (to the right)

contains

public boolean contains(Location l)

Checks if this location contains the other.

Abstractly, a location contains another if every point in the other location is contained within this one. A location contains another location if it overlaps it, and the coordinates enclose those of the other location at both ends, and they fall on the same strand. Recursively applies this call to all members. If passed a Location which is not a RichLocation, it converts it first using RichLocation.Tools.enrich().

Specified by:

contains in interface Location

Overrides:

contains in class SimpleRichLocation

Parameters:

l - the Location to check

Returns:

true if an only if one of the members of this Location wholey contains l.

See Also:

RichLocation.Tools

overlaps

public boolean overlaps(Location l)

Checks if these two locations overlap, using this location's concept of overlapping.

Abstractly, two locations overlap if they both contain any point. A location overlaps another location if it is on the same sequence, and the coordinates overlap, and both are of the same circularity. Recursively applies this call to all members.

Specified by:

overlaps in interface Location

Overrides:

overlaps in class SimpleRichLocation

Parameters:

l - the Location to check

Returns:

true if and only if at least on of the members overlaps l

union

public Location union(Location l)

Return a Location containing all points in either ranges. A merged SimpleRichLocation is returned if the two locations overlap and are on the same strand. Otherwise, a CompoundRichLocation is returned containing the two locations as members. If passed a Location which is not a RichLocation, it converts it first using RichLocation.Tools.enrich(). The resulting location may or may not be a compound location. If it is a compound location, its contents will be a set of simple locations. Regions that overlap will be merged into a single location.

Specified by:

union in interface Location

Overrides:

union in class SimpleRichLocation

Parameters:

l - the Location to union with

Returns:

a CompoundLocation if the components of the union cannot be merged else a SimpleRichLocation

See Also:

RichLocation.Tools

intersection

public Location intersection(Location l)

Returns a Location that contains all points common to both ranges. If the locations overlap and are on the same strand, the intersection is returned. If they overlap but are on different strands, a CompoundRichLocation of the overlapping portions is returned. If they do not overlap, the empty sequence is returned. If passed a Location which is not a RichLocation, it converts it first using RichLocation.Tools.enrich(). The resulting location may or may not be a compound location. If it is a compound location, its contents will be a set of simple locations.

Specified by:

intersection in interface Location

Overrides:

intersection in class SimpleRichLocation

Parameters:

l - the Location to intersect with

Returns:

a CompoundLocation if there is more than one region of intersection that cannot be merged. Else a SimpleRichLocation.

setCrossRefResolver

public void setCrossRefResolver(CrossReferenceResolver r)

Sets the cross ref resolver to use when retrieving remote symbols. If none is given, then the default from RichObjectFactory.getDefaultCrossRefResolver() is used. Recursively applies this call to all members.

Specified by:

setCrossRefResolver in interface RichLocation

Overrides:

setCrossRefResolver in class SimpleRichLocation

Parameters:

r - the resolver to use.

symbols

public SymbolList symbols(SymbolList seq)

Return the symbols in a sequence that fall within this range. If the location is circular but the sequence is not, or they are both circular but of different circular lengths, an exception is thrown. The symbol list passed in is the sequence used to obtain symbols if the cross reference for this location has not been set. If the cross reference has been set, then the symbol list passed in is only used if it has the same accession, namespace and version as the cross reference on this location. Otherwise, the cross referenced symbol list is looked up and used instead. This function concatenates the symbols of all its child locations.

The most obvious application of this method to a CompoundRichLocation is the contatenation of the components of a gene with multiple exons.

Specified by:

symbols in interface Location

Overrides:

symbols in class SimpleRichLocation

Parameters:

seq - the SymbolList to process

Returns:

the SymbolList containing the symbols in seq in this range

setTerm

public void setTerm(ComparableTerm term)
             throws ChangeVetoException

Sets the term for this location.

Specified by:

setTerm in interface RichLocation

Overrides:

setTerm in class SimpleRichLocation

Parameters:

term - the term this location should adopt.

Throws:

ChangeVetoException - in case of error.

hashCode

public int hashCode()

Overrides:

hashCode in class SimpleRichLocation

equals

public boolean equals(Object o)

Checks if this location is equivalent to the other.

Abstractly, a location is equal to another if for every point in one it is also in the other. This is equivalent to a.contains(b) && b.contains(a). You should call LocationTools.areEqual after casting l to Location. Locations are equal if their term, min, max, strand, and crossref are the same, and if their rank is the same too. Compound locations are only equal to other Locations if all their components are equal.

Specified by:

equals in interface Location

Overrides:

equals in class SimpleRichLocation

Parameters:

o - the Object to check

Returns:

true if this equals l, otherwise false

compareTo

public int compareTo(Object o)

Locations are sorted first by rank, then crossref, then strand, then term, then min, then max.

Specified by:

compareTo in interface Comparable

Overrides:

compareTo in class SimpleRichLocation

toString

public String toString()

Form: "start..end" or just "point" for point locations Form: "term:[location,location...]"

Overrides:

toString in class SimpleRichLocation