info.bioinfweb.libralign.model

Interface AlignmentModel<T>

Type Parameters:

T - the type of sequence elements (tokens) the implementing model object works with

All Known Subinterfaces:

AlignmentModelView<T,U>, ConcatenatedAlignmentModel, SequenceAccessAlignmentModel<S,T>

All Known Implementing Classes:

AbstractAlignmentModel, AbstractAlignmentModelDecorator, AbstractListAlignmentModel, AbstractMapBasedAlignmentModel, AbstractTokenReplacementAlignmentModelDecorator, AbstractUndecoratedAlignmentModel, AbstractUnmodifyableAlignmentModel, ArrayListAlignmentModel, BioJava3SequenceAlignmentModel, CharSequenceAlignmentModel, DelegatedAlignmentModelView, DNAAlignmentModelDecorator, PackedAlignmentModel, RNAAlignmentModelDecorator, SwingUndoAlignmentModel

public interface AlignmentModel<T>

Interface that allows LibrAlign GUI elements to access different types of alignment data sources. Classes implementing this interface act as a model for the sequence names and tokens (e.g. nucleotide or amino acid compounds).

All sequences stored are identified by an string ID and not by their names that are possibly displayed to an application user, because these names might change during runtime. Subclasses must ensure that these IDs are unique and do not change during runtime. Additionally IDs of deleted sequences should not be reused, because other objects might have stored references to these using its ID and therefore would not be able to determine that the sequence became deleted, if a new sequence with the same ID is present.

The ordering of sequences in an AlignmentContentArea is not defined by the model implementation but by the instance returned by AlignmentContentArea#getSequenceOrder().

Note that this interface leaves it up to the implementation if the alignment data is organized in objects storing whole sequences (rows) or another storage pattern. If your implementation uses sequence objects consider implementing SequenceAccessAlignmentModel.

Since:

0.0.0

Author:

Ben Stöver

See Also:

SequenceAccessAlignmentModel, AbstractUndecoratedAlignmentModel, AbstractMapBasedAlignmentModel, AbstractBasicAlignmentModelView, DelegatedAlignmentModelView

Method Summary

Modifier and Type	Method and Description
java.lang.String	addSequence(java.lang.String sequenceName) Adds a new empty sequence to the underlying data source and generates an ID for it.
java.lang.String	addSequence(java.lang.String sequenceName, java.lang.String sequenceID) Adds a new empty sequence to the underlying data source assigning the specified ID to it.
void	appendToken(java.lang.String sequenceID, T token) Appends a token at the end of the sequence.
void	appendTokens(java.lang.String sequenceID, java.util.Collection<? extends T> tokens) Appends a sequence of tokens starting at the end of the current sequence.
boolean	containsSequence(java.lang.String sequenceID) Checks if a sequence associated with the specified unique identifier is contained in this model.
java.util.Set<AlignmentModelChangeListener>	getChangeListeners() Returns all change listeners currently attached to this object.
java.lang.String	getID() Some implementations may specify string identifying an alignment, which is then returned by this method.
java.lang.String	getLabel() Returns a string labeling this alignment.
int	getMaxSequenceLength() Returns the length of the longest sequence in the alignment which is equivalent to the length of the alignment.
int	getSequenceCount() Returns the number of sequences in the underlying data source.
int	getSequenceLength(java.lang.String sequenceID) Returns the length of the specified sequence.
T	getTokenAt(java.lang.String sequenceID, int index) Returns the token at the specified position.
TokenSet<T>	getTokenSet() Returns the token set which is supported by the implementation.
AlignmentModelWriteType	getWriteType() Returns a value that specifies if whole sequences or single tokens can be edited in the underlying data source.
void	insertTokenAt(java.lang.String sequenceID, int index, T token) Inserts a token at the specified position.
void	insertTokensAt(java.lang.String sequenceID, int beginIndex, java.util.Collection<? extends T> tokens) Inserts a sequence of tokens starting at the specified position.
boolean	isSequencesReadOnly() Checks of whole sequences can be changed in the underlying data source
boolean	isTokensReadOnly() Checks of tokens can be changed in the underlying data source
boolean	removeSequence(java.lang.String sequenceID) Removes the specified sequence from the underlying data source.
void	removeTokenAt(java.lang.String sequenceID, int index) Removes the token at the specified position from the underlying data source.
void	removeTokensAt(java.lang.String sequenceID, int beginIndex, int endIndex) Removes the token inside the specified interval from the underlying data source.
java.lang.String	renameSequence(java.lang.String sequenceID, java.lang.String newSequenceName) Renames a sequence in the underlying data source.
java.util.Iterator<java.lang.String>	sequenceIDIterator() Returns an iterator over unique IDs of all sequences contained in the underlying data source in the order they are stored in this model.
java.util.Set<java.lang.String>	sequenceIDsByName(java.lang.String sequenceName) Returns the set of unique sequence IDs associated with the specified name.
java.lang.String	sequenceNameByID(java.lang.String sequenceID) Returns the sequence name (that would be visible to the application user) associated with the specified unique ID.
void	setID(java.lang.String id) Allows to specify a new ID for this alignment.
void	setLabel(java.lang.String label) Allows to specify a new label for this alignment.
void	setTokenAt(java.lang.String sequenceID, int index, T token) Replaces the token at the specified position by the passed token.
void	setTokensAt(java.lang.String sequenceID, int beginIndex, java.util.Collection<? extends T> tokens) Replaces a sequence of tokens starting at the specified position.
void	setTokenSet(TokenSet<T> set) Replaces the current token set with the specified one.

Method Detail

getID

java.lang.String getID()

Some implementations may specify string identifying an alignment, which is then returned by this method. Such string IDs will usually be unique in some context and immutable.

Returns:

the ID of this alignment or null if none is assigned

setID

void setID(java.lang.String id)

Allows to specify a new ID for this alignment.

Parameters:

id - the new ID

Throws:

java.lang.UnsupportedOperationException - if this implementation does not allow to change IDs

getLabel

java.lang.String getLabel()

Returns a string labeling this alignment.

Returns:

the name or title of this alignment

setLabel

void setLabel(java.lang.String label)
       throws java.lang.UnsupportedOperationException

Allows to specify a new label for this alignment.

Parameters:

label - the new label

Throws:

java.lang.UnsupportedOperationException - if this implementation does not allow to change labels

getTokenSet

TokenSet<T> getTokenSet()

Returns the token set which is supported by the implementation.

Returns:

a token set containing all valid tokens

setTokenSet

void setTokenSet(TokenSet<T> set)
          throws java.lang.UnsupportedOperationException,
                 java.lang.IllegalArgumentException

Replaces the current token set with the specified one.

Parameters:

set - the new token set to be used

Throws:

java.lang.UnsupportedOperationException - if this implementation does not support changing token sets during runtime

java.lang.IllegalArgumentException - if the specified token set is not a valid replacement for the previous one (in some does way does not fulfill the needs of the implementation)

getSequenceLength

int getSequenceLength(java.lang.String sequenceID)

Returns the length of the specified sequence.

Parameters:

sequenceID - the identifier the sequence in the alignment

Returns:

the length of the sequence or -1 if no sequence with the specified name exists

getMaxSequenceLength

int getMaxSequenceLength()

Returns the length of the longest sequence in the alignment which is equivalent to the length of the alignment.

Note that this value represents the number of compounds of the specified data type. If e.g. a DNA data source is viewed as amino acid data this method would still return the number of nucleotides in the longest sequence.

Returns:

the number of columns in the alignment or 0 if there are not sequences contained in the underlying data source

getWriteType

AlignmentModelWriteType getWriteType()

Returns a value that specifies if whole sequences or single tokens can be edited in the underlying data source. s

Returns:

the write type of this data source

isTokensReadOnly

boolean isTokensReadOnly()

Checks of tokens can be changed in the underlying data source

Returns:

true if token can be written or removed, false otherwise

isSequencesReadOnly

boolean isSequencesReadOnly()

Checks of whole sequences can be changed in the underlying data source

Returns:

true if sequences can be written, renamed or removed, false otherwise

containsSequence

boolean containsSequence(java.lang.String sequenceID)

Checks if a sequence associated with the specified unique identifier is contained in this model.

Parameters:

sequenceID - the ID of the sequence to checked on

Returns:

true if an according sequence was found, false otherwise

sequenceIDsByName

java.util.Set<java.lang.String> sequenceIDsByName(java.lang.String sequenceName)

Returns the set of unique sequence IDs associated with the specified name.

Parameters:

sequenceName - the name of the sequence that would be visible to the application user

Returns:

the set of sequence IDs (The returned set maybe unmodifiable (depending on the implementation) and empty if no sequence with the specified name is present in this model.)

sequenceNameByID

java.lang.String sequenceNameByID(java.lang.String sequenceID)

Returns the sequence name (that would be visible to the application user) associated with the specified unique ID.

Parameters:

sequenceID - the unique unmodifiable ID the sequence is identified by

Returns:

the sequence name or null if no sequence with this ID is contained in this model

addSequence

java.lang.String addSequence(java.lang.String sequenceName)
                      throws AlignmentSourceNotWritableException

Adds a new empty sequence to the underlying data source and generates an ID for it.

Parameters:

sequenceName - the name of the new sequence

Returns:

the unique ID of the new sequence

Throws:

AlignmentSourceNotWritableException - if the underlying data source is not writable for sequences

addSequence

java.lang.String addSequence(java.lang.String sequenceName,
                             java.lang.String sequenceID)
                      throws AlignmentSourceNotWritableException,
                             java.lang.IllegalArgumentException

Adds a new empty sequence to the underlying data source assigning the specified ID to it.

Parameters:

sequenceName - the name of the new sequence

sequenceID - the ID the new sequence shall have

Returns:

the unique ID of the new sequence (identical with sequenceID)

Throws:

AlignmentSourceNotWritableException - if the underlying data source is not writable for sequences

java.lang.IllegalArgumentException - if a sequence with the specified ID is already present in this model

removeSequence

boolean removeSequence(java.lang.String sequenceID)
                throws AlignmentSourceNotWritableException

Removes the specified sequence from the underlying data source.

Parameters:

sequenceID - the unique ID of the sequence to be removed

Returns:

true if an sequence with the specified ID was removed, false if no sequence with the specified ID was contained in this model

Throws:

AlignmentSourceNotWritableException - if the underlying data source is not writable for sequences

renameSequence

java.lang.String renameSequence(java.lang.String sequenceID,
                                java.lang.String newSequenceName)
                         throws AlignmentSourceNotWritableException,
                                SequenceNotFoundException

Renames a sequence in the underlying data source.

Parameters:

sequenceID - the ID of the sequence to be renamed

newSequenceName - the new name the sequence shall have

Returns:

the name the sequence had until now

Throws:

AlignmentSourceNotWritableException - if the underlying data source is not writable for sequences

DuplicateSequenceNameException - if a sequence with the specified new name is already present in the underlying data source

SequenceNotFoundException - if a sequence with the specified ID is not present the underlying data source

sequenceIDIterator

java.util.Iterator<java.lang.String> sequenceIDIterator()

Returns an iterator over unique IDs of all sequences contained in the underlying data source in the order they are stored in this model.

Returns:

an iterator over the IDs

getSequenceCount

int getSequenceCount()

Returns the number of sequences in the underlying data source.

getChangeListeners

java.util.Set<AlignmentModelChangeListener> getChangeListeners()

Returns all change listeners currently attached to this object. This collection is writable and should also be used to add or remove listeners.

This method returns the same object in every call. Therefore changes made to different references always affect all references.

Returns:

a collection object containing the listeners

getTokenAt

T getTokenAt(java.lang.String sequenceID,
             int index)

Returns the token at the specified position.

Parameters:

sequenceID - the identifier the sequence where the token is contained

index - the index of the element contained in the specified sequence (The first element has the index 0.)

Returns:

the token to be displayed in the GUI alignment view

Throws:

SequenceNotFoundException - if no according sequence to the specified ID was found in this model

java.lang.IndexOutOfBoundsException - if the specified index is below zero or greater or equal to the length of the specified sequence

setTokenAt

void setTokenAt(java.lang.String sequenceID,
                int index,
                T token)
         throws AlignmentSourceNotWritableException

Replaces the token at the specified position by the passed token.

Parameters:

sequenceID - the identifier the sequence where the token is contained

index - the index of the element to be replaced (The first element has the index 0.)

token - the new token for the specified position

Throws:

AlignmentSourceNotWritableException - if the underlying data source is not writable for tokens

SequenceNotFoundException - if no according sequence to the specified ID was found in this model

java.lang.IndexOutOfBoundsException - if the specified index is below zero or greater or equal to the length of the specified sequence (Note that not all implementations will throw this exception for indices above zero. Some may also elongate the sequence accordingly and will up the new positions with e.g. gaps.)

setTokensAt

void setTokensAt(java.lang.String sequenceID,
                 int beginIndex,
                 java.util.Collection<? extends T> tokens)
          throws AlignmentSourceNotWritableException

Replaces a sequence of tokens starting at the specified position. If the specified collection contains more tokens than the currently present in the sequence at the specified start position the additional tokens are appended.

Parameters:

sequenceID - the identifier the sequence where the token is contained

beginIndex - the index of the first element to be replaced (The first element in the sequence has the index 0.)

tokens - the new tokens for the specified position

Throws:

AlignmentSourceNotWritableException - if the underlying data source is not writable for tokens

SequenceNotFoundException - if no according sequence to the specified ID was found in this model

See Also:

AlignmentModelUtils.charSequenceToTokenList(CharSequence, TokenSet)

appendToken

void appendToken(java.lang.String sequenceID,
                 T token)
          throws AlignmentSourceNotWritableException

Appends a token at the end of the sequence.

Parameters:

sequenceID - the identifier the sequence in the alignment

token - the token to be inserted

Throws:

SequenceNotFoundException - if no according sequence to the specified ID was found in this model

AlignmentSourceNotWritableException - if the underlying data source is not writable for tokens

appendTokens

void appendTokens(java.lang.String sequenceID,
                  java.util.Collection<? extends T> tokens)
           throws AlignmentSourceNotWritableException

Appends a sequence of tokens starting at the end of the current sequence.

Parameters:

sequenceID - the identifier the sequence where the token is contained

tokens - the new tokens for the specified position

Throws:

SequenceNotFoundException - if no according sequence to the specified ID was found in this model

AlignmentSourceNotWritableException - if the underlying data source is not writable for tokens

See Also:

AlignmentModelUtils.charSequenceToTokenList(CharSequence, TokenSet)

insertTokenAt

void insertTokenAt(java.lang.String sequenceID,
                   int index,
                   T token)
            throws AlignmentSourceNotWritableException

Inserts a token at the specified position. All tokens located behind the specified index are moved by 1.

Parameters:

sequenceID - the identifier the sequence in the alignment

index - the new index the inserted element will have (0 <= elementIndex < sequenceLength)

token - the token to be inserted

Throws:

SequenceNotFoundException - if no according sequence to the specified ID was found in this model

AlignmentSourceNotWritableException - if the underlying data source is not writable for tokens

insertTokensAt

void insertTokensAt(java.lang.String sequenceID,
                    int beginIndex,
                    java.util.Collection<? extends T> tokens)
             throws AlignmentSourceNotWritableException

Inserts a sequence of tokens starting at the specified position. All tokens located behind the specified index are moved by the number of tokens that are contained in tokens.

Parameters:

sequenceID - the identifier the sequence where the token is contained

beginIndex - the index of the first element to be replaced (The first element in the sequence has the index 0.)

tokens - the new tokens for the specified position

Throws:

SequenceNotFoundException - if no according sequence to the specified ID was found in this model

AlignmentSourceNotWritableException - if the underlying data source is not writable for tokens

See Also:

AlignmentModelUtils.charSequenceToTokenList(CharSequence, TokenSet)

removeTokenAt

void removeTokenAt(java.lang.String sequenceID,
                   int index)
            throws AlignmentSourceNotWritableException

Removes the token at the specified position from the underlying data source.

Parameters:

sequenceID - the identifier the sequence in the alignment

index - the index of the element to be removed (The first element has the index 0.)

Throws:

SequenceNotFoundException - if no according sequence to the specified ID was found in this model

AlignmentSourceNotWritableException - if the underlying data source is not writable for tokens

removeTokensAt

void removeTokensAt(java.lang.String sequenceID,
                    int beginIndex,
                    int endIndex)
             throws AlignmentSourceNotWritableException

Removes the token inside the specified interval from the underlying data source. The subsequence to be removed begins at the specified beginIndex and extends to the token at index endIndex - 1). Thus the length of the subsequence is {@code endIndex - beginIndex}.

Parameters:

sequenceID - the identifier the sequence in the alignment

beginIndex - the beginning index, inclusive

endIndex - the ending index, exclusive

Throws:

SequenceNotFoundException - if no according sequence to the specified ID was found in this model

AlignmentSourceNotWritableException - if the underlying data source is not writable for tokens