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
023/**
024 * A simple bond -- it stores information about two atoms as well as information
025 * about its bond order.
026 *
027 * @author Jules Jacobsen <jacobsen@ebi.ac.uk>
028 * @author Ulysse Carion
029 */
030public interface Bond {
031
032        /**
033         * Gets atom 'A' of this bond. There is no meaning to which atom is 'A' and
034         * which is 'B'; the atoms are labeled 'A' or 'B' based on the order in
035         * which they are passed to this class's constructor.
036         *
037         * @see #getAtomB()
038         * @return one of the two atoms in this bond
039         */
040        public Atom getAtomA();
041
042        /**
043         * Gets atom 'B' of this bond. There is no meaning to which atom is 'A' and
044         * which is 'B'; the atoms are labeled 'A' or 'B' based on the order in
045         * which they are passed to this class's constructor.
046         *
047         * @see #getAtomA()
048         * @return one of the two atoms in this bond
049         */
050        public Atom getAtomB();
051
052        /**
053         * A utility method to get the other atom in a bond, given one of its atoms.
054         * If the atom passed is one of the atoms in this bond, then this method is
055         * essentially equivalent to saying
056         * <code>atom == bond.getAtomA() ? bond.getAtomB() : bond.getAtomA()</code>.
057         * <p>
058         * <i>Note:</i> Comparison of atoms in this method is done with
059         * <code>==</code>, not <code>equals</code>.
060         *
061         * @param exclude
062         *            the atom of the bond to not return
063         * @throws IllegalArgumentException
064         *             if the passed atom is not in this bond
065         * @return the atom in this bond that was not passed as an argument
066         */
067        public Atom getOther(Atom exclude);
068
069        /**
070         * Gets the bond order of this bond. A return value of '1' corresponds to a
071         * single bond, '2' to a double bond, etc.
072         *
073         * @return this bond's bond order
074         */
075        public int getBondOrder();
076
077        /**
078         * Gets the distance between the two atoms of this bond.
079         * <p>
080         * This distance is calculated by {@link Calc#getDistance(Atom, Atom)}, but
081         * this method will suppress the empty threat of a
082         * {@link StructureException} that method makes.
083         *
084         * @return the distance between the two atoms of this bond.
085         */
086        public double getLength();
087}