iatomcontainer.java

化学图形处理软件

/* $Revision: 7996 $ $Author: egonw $ $Date: 2007-02-24 17:48:55 +0100 (Sat, 24 Feb 2007) $
 *
 * Copyright (C) 2006-2007  Egon Willighagen <[e-mail]>
 *
 * Contact: [e-mail]
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation; either version 2.1
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 */
package org.openscience.cdk.interfaces;

import java.util.Iterator;
import java.util.List;

/**
 *  Base class for all chemical objects that maintain a list of Atoms and
 *  ElectronContainers. <p>
 *
 *  Looping over all <code>IBond</code>s in the <code>IAtomContainer</code>
 *  is typically done like:
 *  <pre>
 *  Iterator bonds = atomContainer.bonds();
 *  while (bonds.hasNext()) {
 *      IBond b = (IBond)bonds.next();
 *  }
 *  </pre>
 *
 * @cdk.module interfaces
 *
 * @author     steinbeck
 * @cdk.created    2000-10-02
 */
public interface IAtomContainer extends IChemObject, IChemObjectListener {

    /**
     * Adds an AtomParity to this container. If a parity is already given for the
     * affected Atom, it is overwritten.
     *
     * @param parity The new AtomParity for this container
     * @see   #getAtomParity
     */
    public void addAtomParity(IAtomParity parity);

    /**
     * Returns the atom parity for the given Atom. If no parity is associated
     * with the given Atom, it returns null.
     *
     * @param  atom   Atom for which the parity must be returned
     * @return The AtomParity for the given Atom, or null if that Atom does
     *         not have an associated AtomParity
     * @see    #addAtomParity
     */
    public IAtomParity getAtomParity(IAtom atom);
    
	/**
	 * Sets the array of atoms of this AtomContainer.
	 *
	 * @param  atoms  The array of atoms to be assigned to this AtomContainer
	 * @see           #atoms
	 */
	public void setAtoms(IAtom[] atoms);
	
	/**
	 * Sets the array of bonds of this AtomContainer.
	 *
	 * @param  bonds  The array of bonds to be assigned to
	 *                             this AtomContainer
	 * @see  #bonds
	 */
	public void setBonds(IBond[] bonds);
	
	/**
	 * Set the atom at position <code>number</code> in [0,..].
	 *
	 * @param  number  The position of the atom to be set.
	 * @param  atom    The atom to be stored at position <code>number</code>
	 * @see            #getAtom
	 */
	public void setAtom(int number, IAtom atom);

	/**
	 * Get the atom at position <code>number</code> in [0,..].
	 *
	 * @param  number  The position of the atom to be retrieved.
	 * @return         The atom number
	 * @see            #setAtom
	 */
	public IAtom getAtom(int number);

	/**
	 *  Get the bond at position <code>number</code> in [0,..].
	 *
	 *@param  number  The position of the bond to be retrieved.
	 *@return         The bond number
	 */
	public IBond getBond(int number);

	/**
	 *  Get the lone pair at position <code>number</code> in [0,..].
	 *
	 *@param  number  The position of the LonePair to be retrieved.
	 *@return         The lone pair number
	 */
	public ILonePair getLonePair(int number);
	
	/**
	 *  Get the single electron at position <code>number</code> in [0,..].
	 *
	 *@param  number  The position of the SingleElectron to be retrieved.
	 *@return         The single electron number
	 */
	public ISingleElectron getSingleElectron(int number);

	/**
	 *  Returns an Iterator for looping over all atoms in this container.
	 *
	 *@return    An Iterator with the atoms in this container
	 */
	public Iterator atoms();

	/**
	 *  Returns an Iterator for looping over all bonds in this container.
	 *
	 *@return    An Iterator with the bonds in this container
	 */
	public Iterator bonds();
	
	/**
	 *  Returns an Iterator for looping over all lone pairs in this container.
	 *
	 *@return    An Iterator with the lone pairs in this container
	 */
	public Iterator lonePairs();
	
	/**
	 *  Returns an Iterator for looping over all single electrons in this container.
	 *
	 *@return    An Iterator with the single electrons in this container
	 */
	public Iterator singleElectrons();
	
	/**
	 *  Returns an Iterator for looping over all electron containers in this container.
	 *
	 *@return    An Iterator with the electron containers in this container
	 */
	public Iterator electronContainers();
	
	/**
	 *  Returns the atom at position 0 in the container.
	 *
	 *@return    The atom at position 0 .
	 */
	public IAtom getFirstAtom();


	/**
	 *  Returns the atom at the last position in the container.
	 *
	 *@return    The atom at the last position
	 */
	public IAtom getLastAtom();


	/**
	 *  Returns the position of a given atom in the atoms array. It returns -1 if
	 *  the atom atom does not exist.
	 *
	 *@param  atom  The atom to be sought
	 *@return       The Position of the atom in the atoms array in [0,..].
	 */
	public int getAtomNumber(IAtom atom);


	/**
	 *  Returns the position of the bond between two given atoms in the
	 *  electronContainers array. It returns -1 if the bond does not exist.
	 *
	 *@param  atom1  The first atom
	 *@param  atom2  The second atom
	 *@return        The Position of the bond between a1 and a2 in the
	 *               electronContainers array.
	 */
	public int getBondNumber(IAtom atom1, IAtom atom2);


	/**
	 *  Returns the position of a given bond in the electronContainers array. It
	 *  returns -1 if the bond does not exist.
	 *
	 *@param  bond  The bond to be sought
	 *@return       The Position of the bond in the electronContainers array in [0,..].
	 */
	public int getBondNumber(IBond bond);

	/**
	 * Returns the position of a given lone pair in the lone pair array. 
	 * It returns -1 if the lone pair does not exist.
	 *
	 * @param  lonePair The lone pair to be sought
	 * @return          The Position of the lone pair in the array..
	 */
	public int getLonePairNumber(ILonePair lonePair);
	
	/**
	 * Returns the position of a given single electron in the single electron array. 
	 * It returns -1 if the single electron does not exist.
	 *
	 * @param  singleElectron The single electron to be sought
	 * @return                The Position of the single electron in the array.
	 */
	public int getSingleElectronNumber(ISingleElectron singleElectron);
	
	/**
	 *  Returns the ElectronContainer at position <code>number</code> in the
	 *  container.
	 *
	 *@param  number  The position of the ElectronContainer to be returned.
	 *@return         The ElectronContainer at position <code>number</code>.
	 *@see            #setElectronContainerAt
	 */
	public IElectronContainer getElectronContainer(int number);


	/**
	 * Returns the bond that connectes the two given atoms.
	 *
	 * @param  atom1  The first atom
	 * @param  atom2  The second atom
	 * @return        The bond that connectes the two atoms
	 */
	public IBond getBond(IAtom atom1, IAtom atom2);



	/**
	 *  Returns the number of Atoms in this Container.
	 *
	 *@return    The number of Atoms in this Container
	 */
	public int getAtomCount();

	/**
	 *  Returns the number of Bonds in this Container.
	 *
	 *@return    The number of Bonds in this Container
	 */
	public int getBondCount();

	/**
	 *  Returns the number of LonePairs in this Container.
	 *
	 *@return    The number of LonePairs in this Container
	 */
	public int getLonePairCount();

	/**
	 * Returns the number of the single electrons in this container.
	 *
	 * @return       The number of SingleElectron objects of this AtomContainer
	 */
	public int getSingleElectronCount();
	
	/**
	 * Returns the number of ElectronContainers in this Container.
	 *
	 * @return    The number of ElectronContainers in this Container
	 */
	public int getElectronContainerCount();
	
	/**
	 *  Returns an ArrayList of all atoms connected to the given atom.
	 *
	 *@param  atom  The atom the bond partners are searched of.
	 *@return       The ArrayList with the connected atoms
	 */
	public List getConnectedAtomsList(IAtom atom);

	/**
	 *  Returns an ArrayList of all Bonds connected to the given atom.
	 *
	 *@param  atom  The atom the connected bonds are searched of
	 *@return       The ArrayList with connected atoms
	 */
	public List getConnectedBondsList(IAtom atom);

	/**
	 *  Returns the array of lone pairs connected to an atom.
	 *
	 *@param  atom  The atom for which to get lone pairs
	 *@return       The array of LonePairs of this AtomContainer
	 */
	public List getConnectedLonePairsList(IAtom atom);

	/**
	 *  Returns an array of all SingleElectron connected to the given atom.
	 *
	 *@param  atom  The atom on which the single electron is located
	 *@return       The array of SingleElectron of this AtomContainer
	 */
	public List getConnectedSingleElectronsList(IAtom atom);
	
	/**
	 *  Returns an ArrayList of all electronContainers connected to the given atom.
	 *
	 *@param  atom  The atom the connected electronContainers are searched of