001/*
002 *                    BioJava development code
003 *
004 * This code may be freely distributed and modified under the
005 * terms of the GNU Lesser General Public Licence.  This should
006 * be distributed with the code.  If you do not have a copy,
007 * see:
008 *
009 *      http://www.gnu.org/copyleft/lesser.html
010 *
011 * Copyright for this code is held jointly by the individual
012 * authors.  These should be listed in @author doc comments.
013 *
014 * For more information on the BioJava project and its aims,
015 * or to join the biojava-l mailing list, visit the home page
016 * at:
017 *
018 *      http://www.biojava.org/
019 *
020 */
021package org.biojava.nbio.structure;
022
023import java.io.Serializable;
024
025/**
026 * A simple bond -- it stores information about two atoms as well as information
027 * about its bond order.
028 *
029 * @author Jules Jacobsen <jacobsen@ebi.ac.uk>
030 * @author Ulysse Carion
031 */
032public interface Bond extends Serializable {
033
034        /**
035         * Gets atom 'A' of this bond. There is no meaning to which atom is 'A' and
036         * which is 'B'; the atoms are labeled 'A' or 'B' based on the order in
037         * which they are passed to this class's constructor.
038         *
039         * @see #getAtomB()
040         * @return one of the two atoms in this bond
041         */
042        public Atom getAtomA();
043
044        /**
045         * Gets atom 'B' of this bond. There is no meaning to which atom is 'A' and
046         * which is 'B'; the atoms are labeled 'A' or 'B' based on the order in
047         * which they are passed to this class's constructor.
048         *
049         * @see #getAtomA()
050         * @return one of the two atoms in this bond
051         */
052        public Atom getAtomB();
053
054        /**
055         * A utility method to get the other atom in a bond, given one of its atoms.
056         * If the atom passed is one of the atoms in this bond, then this method is
057         * essentially equivalent to saying
058         * <code>atom == bond.getAtomA() ? bond.getAtomB() : bond.getAtomA()</code>.
059         * <p>
060         * <i>Note:</i> Comparison of atoms in this method is done with
061         * <code>==</code>, not <code>equals</code>.
062         *
063         * @param exclude
064         *            the atom of the bond to not return
065         * @throws IllegalArgumentException
066         *             if the passed atom is not in this bond
067         * @return the atom in this bond that was not passed as an argument
068         */
069        public Atom getOther(Atom exclude);
070
071        /**
072         * Gets the bond order of this bond. A return value of '1' corresponds to a
073         * single bond, '2' to a double bond, etc.
074         *
075         * @return this bond's bond order
076         */
077        public int getBondOrder();
078
079        /**
080         * Gets the distance between the two atoms of this bond.
081         * <p>
082         * This distance is calculated by {@link Calc#getDistance(Atom, Atom)}, but
083         * this method will suppress the empty threat of a
084         * {@link StructureException} that method makes.
085         *
086         * @return the distance between the two atoms of this bond.
087         */
088        public double getLength();
089}