Package com.biomatters.geneious.publicapi.plugin

Class DocumentSelectionSignature

  • All Implemented Interfaces:
    XMLSerializable
    public final class DocumentSelectionSignature
extends java.lang.Object
implements XMLSerializable
    Several plugin components (Viewers, Exporters, Operations, Actions) operate on one (or a set of) Geneious documents. DocumentSelectionSignature specifies which subsets of document types are valid for specific operations/viewers etc. For example an alignment operation may specify it requires 2 or more nucleotide sequences using DocumentSelectionSignature.forNucleotideSequences(2,Integer.MAX_VALUE).

    Geneious then handles correctly enabled/disabling the operation depending on what is selected and only invoking the operation with a valid selection of documents.

    • Constructor Detail

      • DocumentSelectionSignature

        public DocumentSelectionSignature​(org.jdom.Element element)
                           throws XMLSerializationException
        XML deserialization constructor
        Parameters:
        element - an element returned from a previous call to toXML()
        Throws:
        XMLSerializationException
        Since:
        API 4.600 (Geneious 6.0.0)

      • DocumentSelectionSignature

        public DocumentSelectionSignature​(DocumentSelectionSignature.DocumentSelectionSignatureAtom[] atoms)
        construct signature from given atoms. The signature only matches a set of class if the requirements of all atoms are met and if every class in the set matches at least 1 of the atoms.
        Parameters:
        atoms - signature parts.

      • DocumentSelectionSignature

        public DocumentSelectionSignature​(java.lang.Class classOfSelected,
                                  int from,
                                  int to)
        convenience constructor for accepting a single class repeated a certain number of times. (say a set of 2 sequences or more - for alignment)
        Parameters:
        classOfSelected - class of selected documents
        from - lower bound of number of documents (from 0 to Integer.MAX_VALUE)
        to - upper bound of number of documents (from 0 to Integer.MAX_VALUE, must be greater than or equal to from)

    • Method Detail

      • toXML

        public org.jdom.Element toXML()
        Description copied from interface: XMLSerializable
        Convert object to a JDOM element. The representation should be complete so that XMLSerializable.fromXML(org.jdom.Element) can completely restore the object's representation.

        It is recommended that the returned element use XMLSerializable.ROOT_ELEMENT_NAME as its name, in which case it must not define an attribute called "type". In this case, fromXML, will be called with an element whose name may differ from the element return from this function. This recommendation allows a more compact representation of the XML can be stored.

        This method generally should not be called directly. Instead, you should usually call XMLSerializer.classToXML(String, XMLSerializable) which calls this method internally.

        PluginDocument implementations of this method may choose to throw an XMLSerializationException, enclosed in a RuntimeException.

        Specified by:
        toXML in interface XMLSerializable
        Returns:
        object encoded as a JDOM element

      • fromXML

        public void fromXML​(org.jdom.Element element)
             throws XMLSerializationException
        Description copied from interface: XMLSerializable
        Restore the object from the JDOM Element returned by XMLSerializable.toXML().

        This method generally should not be called directly. Instead, you should usually call XMLSerializer.classFromXML(org.jdom.Element) or XMLSerializer.classFromXML(org.jdom.Element, Class) which calls this method internally.

        It is optional to implement this method. Instead of implementing an empty constructor and implementing this method properly, the implementation may instead throw an UnsupportedOperationException and implement a constructor that takes a single Element as a parameter. This allows for cleaner code such as support for final fields in the XMLSerializable class.

        The element parameter should not be modified since it may be reused. If you need a modified version of it, take a copy with Element.clone().

        Specified by:
        fromXML in interface XMLSerializable
        Parameters:
        element - representation from a previous call to XMLSerializable.toXML()
        Throws:
        XMLSerializationException - if the Element can't be converted into this type of object

      • forNucleotideSequences

        public static DocumentSelectionSignature forNucleotideSequences​(int minimumNumberOfSequences,
                                                                int maximumNumberOfSequences)
        Creates a selection signature that matches any combination of SequenceListDocument and NucleotideSequenceDocument such that the total number of nucleotide sequences they contain is within the given range. If an operation uses this selection signature, it must be prepared to accept SequenceListDocuments as input (i.e. Geneious won't split the sequence list into stand-alone sequences for input to the operation).
        Parameters:
        minimumNumberOfSequences - the minimum (inclusive) number of nucleotide sequences to match.
        maximumNumberOfSequences - the maximum (inclusive) number of nucleotide sequences to match.
        Returns:
        a selection signature that matches the specified number of nucleotide sequences.

      • forNucleotideSequences

        public static DocumentSelectionSignature forNucleotideSequences​(int minimumNumberOfSequences,
                                                                int maximumNumberOfSequences,
                                                                boolean allowSequencesInAlignments)
        Creates a selection signature that matches any combination of SequenceListDocument, SequenceAlignmentDocument (if allowSequencesInAlignments is true) and NucleotideSequenceDocument such that the total number of nucleotide sequences they contain is within the given range, and there are no protein sequences.
        Parameters:
        minimumNumberOfSequences - the minimum (inclusive) number of nucleotide sequences to match.
        maximumNumberOfSequences - the maximum (inclusive) number of nucleotide sequences to match.
        allowSequencesInAlignments - whether to allow sequences in alignments as well as stand-alone sequences. If you want a signature that just matches an alignment, use forNucleotideAlignment(int, int) instead.
        Returns:
        a selection signature that matches the specified number of nucleotide sequences.

      • isNucleotideSequenceSignature

        public boolean isNucleotideSequenceSignature()
        get whether this signature was created using forNucleotideSequences() or forNucleotideAndProteinSequences()
        Returns:
        whether this signature was created using forNucleotideSequences() or forNucleotideAndProteinSequences()
        Since:
        API 4.600 (Geneious 6.0.0)

      • isProteinSequenceSignature

        public boolean isProteinSequenceSignature()
        get whether this signature was created using forProteinSequences() or forNucleotideAndProteinSequences()
        Returns:
        whether this signature was created using forProteinSequences() or forNucleotideAndProteinSequences()
        Since:
        API 4.600 (Geneious 6.0.0)

      • getNucleotideSequenceMinimum

        public int getNucleotideSequenceMinimum()
        get the minimum number of nucleotide sequences this signature accepts, if it is a signature created using forNucleotideSequences() or forNucleotideAndProteinSequences()
        Returns:
        the minimum number of nucleotide sequences this signature accepts, if it is a signature created using forNucleotideSequences() or forNucleotideAndProteinSequences()
        Throws:
        java.lang.IllegalStateException - if the signature was not created using forNucleotideSequences() or forNucleotideAndProteinSequences();
        Since:
        API 4.600 (Geneious 6.0.0)

      • getNucleotideSequenceMaximum

        public int getNucleotideSequenceMaximum()
        get the maximum number of nucleotide sequences this signature accepts, if it is a signature created using forNucleotideSequences() or forNucleotideAndProteinSequences()
        Returns:
        the maximum number of nucleotide sequences this signature accepts, if it is a signature created using forNucleotideSequences() or forNucleotideAndProteinSequences()
        Throws:
        java.lang.IllegalStateException - if the signature was not created using forNucleotideSequences() or forNucleotideAndProteinSequences();
        Since:
        API 4.600 (Geneious 6.0.0)

      • getProteinSequenceMinimum

        public int getProteinSequenceMinimum()
        get the minimum number of protein sequences this signature accepts, if it is a signature created using forProteinSequences() or forNucleotideAndProteinSequences()
        Returns:
        the minimum number of nucleotide sequences this signature accepts, if it is a signature created using forProteinSequences() or forNucleotideAndProteinSequences()
        Throws:
        java.lang.IllegalStateException - if the signature was not created using forProteinSequences() or forNucleotideAndProteinSequences();
        Since:
        API 4.600 (Geneious 6.0.0)

      • getProteinSequenceMaximum

        public int getProteinSequenceMaximum()
        get the maximum number of protein sequences this signature accepts, if it is a signature created using forProteinSequences() or forNucleotideAndProteinSequences()
        Returns:
        the maximum number of nucleotide sequences this signature accepts, if it is a signature created using forProteinSequences() or forNucleotideAndProteinSequences()
        Throws:
        java.lang.IllegalStateException - if the signature was not created using forProteinSequences() or forNucleotideAndProteinSequences();
        Since:
        API 4.600 (Geneious 6.0.0)

      • isAllowSequencesInNucleotideAlignments

        public boolean isAllowSequencesInNucleotideAlignments()
        get whether a signature created forNucleotideSequences() or forNucleotideAndProteinSequences() allows sequences in alignments as well as from stand-alone sequences
        Returns:
        true if a signature created using forNucleotideSequences() or forNucleotideAndProteinSequences() allows sequences in alignments as well as from stand-alone sequences
        Throws:
        java.lang.IllegalStateException - if the signature was not created using forNucleotideSequences() or forNucleotideAndProteinSequences();
        Since:
        API 4.600 (Geneious 6.0.0)

      • isAllowSequencesInProteinAlignments

        public boolean isAllowSequencesInProteinAlignments()
        get whether a signature created using forProteinSequences() or forNucleotideAndProteinSequences() allows sequences in alignments as well as from stand-alone sequences
        Returns:
        true if a signature created using forProteinSequences() or forNucleotideAndProteinSequences() allows sequences in alignments as well as from stand-alone sequences
        Throws:
        java.lang.IllegalStateException - if the signature was not created using forProteinSequences() or forNucleotideAndProteinSequences();
        Since:
        API 4.600 (Geneious 6.0.0)

      • forNucleotideSequencesAndAlignments

        public static DocumentSelectionSignature forNucleotideSequencesAndAlignments​(int minimumNumberOfSequences,
                                                                             int maximumNumberOfSequences,
                                                                             int minimumNumberOfAlignments,
                                                                             int maximumNumberOfAlignments)
        Creates a selection signature that matches any combination of SequenceListDocument, and NucleotideSequenceDocument such that the total number of nucleotide sequences they contain is within the given range, and there are no protein sequences. plus a number of nucleotide SequenceAlignmentDocuments within the given range
        Parameters:
        minimumNumberOfSequences - the minimum (inclusive) number of nucleotide sequences to match.
        maximumNumberOfSequences - the maximum (inclusive) number of nucleotide sequences to match.
        minimumNumberOfAlignments - the minimum (inclusive) number of nucleotide alignments to match.
        maximumNumberOfAlignments - the maximum (inclusive) number of nucleotide alignments to match.
        Returns:
        a selection signature that matches the specified number of nucleotide sequences and alignments.

      • forMatching

        public static DocumentSelectionSignature forMatching​(java.util.function.Function<java.util.List<? extends AnnotatedPluginDocument>,​java.lang.Boolean> customMatcher)
        Creates a selection signature with the provided custom matcher.
        Parameters:
        customMatcher - A function taking in a list of APD's and returning a boolean. This function is expected to return quickly and thus should not load plugin documents within the APD's.
        Returns:
        A selection signature that matches withe the provided matching function.
        Since:
        API 4.202220 (Geneious 2022.2.0)

      • forProteinSequences

        public static DocumentSelectionSignature forProteinSequences​(int minimumNumberOfSequences,
                                                             int maximumNumberOfSequences,
                                                             boolean allowSequencesInAlignments)
        Creates a selection signature that matches any combination of SequenceListDocument, SequenceAlignmentDocument (if allowSequencesInAlignments is true) and AminoAcidSequenceDocument such that the total number of protein sequences they contain is within the given range, and there are no nucleotide sequences.
        Parameters:
        minimumNumberOfSequences - the minimum (inclusive) number of protein sequences to match.
        maximumNumberOfSequences - the maximum (inclusive) number of protein sequences to match.
        allowSequencesInAlignments - whether to allow sequences in alignments as well as stand-alone sequences. If you want a signature that just matches an alignment, use forProteinAlignment(int, int) instead
        Returns:
        a selection signature that matches the specified number of protein sequences.

      • forProteinSequences

        public static DocumentSelectionSignature forProteinSequences​(int minimumNumberOfSequences,
                                                             int maximumNumberOfSequences)
        Creates a selection signature that matches any combination of SequenceListDocument and AminoAcidSequenceDocument such that the total number of protein sequences they contain is within the given range. If an operation uses this selection signature, it must be prepared to accept SequenceListDocuments as input (i.e. Geneious won't split the sequence list into stand-alone sequences for input to the operation).
        Parameters:
        minimumNumberOfSequences - the minimum (inclusive) number of protein sequences to match.
        maximumNumberOfSequences - the maximum (inclusive) number of protein sequences to match.
        Returns:
        a selection signature that matches the specified number of protein sequences.

      • forProteinSequencesAndAlignments

        public static DocumentSelectionSignature forProteinSequencesAndAlignments​(int minimumNumberOfSequences,
                                                                          int maximumNumberOfSequences,
                                                                          int minimumNumberOfAlignments,
                                                                          int maximumNumberOfAlignments)
        Creates a selection signature that matches any combination of SequenceListDocument, and AminoAcidSequenceDocument such that the total number of protein sequences they contain is within the given range, and there are no nucleotide sequences, plus a number of protein SequenceAlignmentDocuments within the given range
        Parameters:
        minimumNumberOfSequences - the minimum (inclusive) number of protein sequences to match.
        maximumNumberOfSequences - the maximum (inclusive) number of protein sequences to match.
        minimumNumberOfAlignments - the minimum (inclusive) number of protein alignments to match.
        maximumNumberOfAlignments - the maximum (inclusive) number of protein alignments to match.
        Returns:
        a selection signature that matches the specified number of protein sequences and alignments.

      • forProteinAlignments

        public static DocumentSelectionSignature forProteinAlignments​(int minimumNumberOfAlignments,
                                                              int maximumNumberOfAlignments)
        Creates a selection signature that matches a number of protein SequenceAlignmentDocuments within the given range
        Parameters:
        minimumNumberOfAlignments - the minimum (inclusive) number of protein alignments to match.
        maximumNumberOfAlignments - the maximum (inclusive) number of protein alignments to match.
        Returns:
        a selection signature that matches the specified number of proteine alignments.

      • forNucleotideAndProteinSequences

        public static DocumentSelectionSignature forNucleotideAndProteinSequences​(int minimumNumberOfNucleotideSequences,
                                                                          int maximumNumberOfNucleotideSequences,
                                                                          int minimumNumberOfProteinSequences,
                                                                          int maximumNumberOfProteinSequences,
                                                                          boolean allowSequencesInAlignments)
        Creates a selection signature that matches any combination of SequenceListDocument, SequenceAlignmentDocument (if allowSequencesInAlignments is true), NucleotideSequenceDocument and AminoAcidSequenceDocument such that the total number of nucleotide sequences they contain is within the given range and the total number of protein sequences is also within the range.
        Parameters:
        minimumNumberOfNucleotideSequences - the minimum (inclusive) number of nucleotide sequences to match. May be 0.
        maximumNumberOfNucleotideSequences - the maximum (inclusive) number of nucleotide sequences to match.
        minimumNumberOfProteinSequences - the minimum (inclusive) number of protein sequences to match. May be 0.
        maximumNumberOfProteinSequences - the maximum (inclusive) number of protein sequences to match.
        allowSequencesInAlignments - whether to allow sequences in alignments SequenceListDocuments that are not of the right type
        Returns:
        a selection signature that matches the specified number of nucleotide and protein sequences.

      • forNucleotideAlignment

        public static DocumentSelectionSignature forNucleotideAlignment​(int minimumNumberOfSequences,
                                                                int maximumNumberOfSequences)
        Creates a selection signature that matches a single alignment that contains a specified range of nucleotide sequences.
        Parameters:
        minimumNumberOfSequences - the minimum (inclusive) number of sequences the alignment must contain
        maximumNumberOfSequences - the maximum (inclusive) number of sequences the alignment must contain
        Returns:
        a selection signature that matches a single alignment that contains a specified range of nucleotide sequences.

      • forProteinAlignment

        public static DocumentSelectionSignature forProteinAlignment​(int minimumNumberOfSequences,
                                                             int maximumNumberOfSequences)
        Creates a selection signature that matches a single alignment that contains a specified range of protein sequences.
        Parameters:
        minimumNumberOfSequences - the minimum (inclusive) number of sequences the alignment must contain
        maximumNumberOfSequences - the maximum (inclusive) number of sequences the alignment must contain
        Returns:
        a selection signature that matches a single alignment that contains a specified range of protein sequences.

      • matches

        public boolean matches​(java.util.List<? extends AnnotatedPluginDocument> documents)
        Check whether this selection signature matches these documents.
        Parameters:
        documents - the documents to check against. null is equivalent to an empty document list.
        Returns:
        true if this selection signature matches these documents.

      • matches

        public static boolean matches​(DocumentSelectionSignature[] signatures,
                              java.util.List<? extends AnnotatedPluginDocument> documents)
        Parameters:
        signatures - the signatures to be matched
        documents - the documents to be matched. null is equivalent to an empty document list.
        Returns:
        true if at least one of the document selection signatures match the given documents

      • isMoreGeneral

        public static boolean isMoreGeneral​(DocumentSelectionSignature[] potentiallyMoreGeneralSignatures,
                                    DocumentSelectionSignature[] potentiallyMoreSpecificSignatures)
        Returns true if all possible documents accepted by potentiallyMoreSpecificSignatures will also be accepted by potentiallyMoreGeneralSignatures.

        Note that this method does not cover all possible scenarios so it may return false in some cases even where the documents accepted by potentiallyMoreSpecificSignatures are also accepted by potentiallyMoreGeneralSignatures. For example cases where signatures contain more than 1 atom are not covered. And generic handling of sequence lists comparing with specific SequenceDocument classes are not covered.

        Parameters:
        potentiallyMoreGeneralSignatures - the signatures to see if they are more general than the other ones
        potentiallyMoreSpecificSignatures - the signatures to see if they are more specific than the other ones
        Returns:
        true if all possible documents accepted by potentiallyMoreSpecificSignatures will also be accepted by potentiallyMoreGeneralSignatures.
        Since:
        API 4.600 (Geneious 6.0.0)

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • getAlignmentSequenceType

        public jebl.evolution.sequences.SequenceType getAlignmentSequenceType()
        Returns:
        the type of alignment this signature for if it was created using forNucleotideAlignment(int, int) or forProteinAlignment(int, int) or null if it was created using neither of these signatures
        Since:
        API 4.610 (Geneious 6.1.0)