## 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 <class>decoratorClass</class> and return it if found. The default behavior is to return null. If the current object is a decorator and is an instance of <class>decoratorClass</class> 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>loc</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 <class>decoratorClass</class> and return it if found.

  The default behavior is to return null. If the current object is a decorator and is an instance of <class>decoratorClass</class> 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>loc</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`