/*
 *                    BioJava development code
 *
 * This code may be freely distributed and modified under the
 * terms of the GNU Lesser General Public Licence.  This should
 * be distributed with the code.  If you do not have a copy,
 * see:
 *
 *      http://www.gnu.org/copyleft/lesser.html
 *
 * Copyright for this code is held jointly by the individual
 * authors.  These should be listed in @author doc comments.
 *
 * For more information on the BioJava project and its aims,
 * or to join the biojava-l mailing list, visit the home page
 * at:
 *
 *      http://www.biojava.org/
 *
 * Created on 28.04.2004
 * @author Andreas Prlic
 *
 */
package org.biojava.nbio.structure;

import java.util.List;

/**
 * A simple interface for an Atom.
 * The coordinates can be accessed via the
 * {@link #getCoords()}, or the 
 * {@link #getX()}, {@link #getY()}, {@link #getZ()} methods.
 * There are a few additional methods here to provide some PDB specific information.
 * 
 
 * @author Andreas Prlic
 * @author Horvath Tamas
 * @version %I% %G%
 * @since 1.4
 * 
 */
public interface Atom extends Cloneable, PDBRecord {
    
    /** 
     * Set atom name, e.g. "CA". 
     * @param s  a trimmed String specifying the name value
     * @see #getName
     */
    public void   setName(String s);
    
    /** 
     * Get atom name, e.g. "CA".
     * Beware that some PDB atom names are ambiguous (e.g. CA, which means C-alpha or Calcium),
     * the ambiguity can simply be resolved by also checking the element with {@link #getElement()}
     * @return a trimmed String representing the name value 
     * @see #setName
     */
    public String getName();
    
    /** 
     * Set element of the atom name, e.g. {@link Element#Fe}
     * @param e  an Element enumeration
     * @see #getElement
     */
    public void   setElement(Element e);
    
    /** 
     * Get element of the atom, e.g. {@link Element#Ca}
     * @return an Element enumeration 
     * @see #setElement
     */
    public Element getElement();
    
    /** 
     * Set PDB atom number. 
     * @param i  an int specifying the PDBserial value 
     * @see #getPDBserial
     */
    public void setPDBserial(int i) ;
    
    /** 
     * Get PDB atom number.
     * @return an int representing the PDBserial value 
     * @see #setPDBserial
     */
    public int  getPDBserial() ;
    
    /** 
     * Set the coordinates.  
     * @param c  an array of doubles specifying the coords value
     * @see #getCoords
     */    
    public void    setCoords(double[] c);
    
    /** 
     * Get the coordinates. 
     * @return an array of doubles representing the coords value
     * @see #setCoords
     */    
    public double[] getCoords() ;
    
    /** 
     * Set the X coordinate.
     * @param x  a double
     * @see #getX()
     */
    public void setX(double x);
    
    /** 
     * Set the Y coordinate.
     * @param y  a double
     * @see #getY()
     */
    public void setY(double y);
    
    /** 
     * Set the Z coordinate.
     * @param z  a double
     * @see #getZ()     
     */
    public void setZ(double z);
    
    /** 
     * Get coordinate X. 
     * @return a double
     * @see #setX(double)
     */    
    public double getX() ;
    
    /** 
     * Get coordinate Y. 
     * @return a double
     * @see #setY(double)
     */    
    public double getY() ;
    
    /** 
     * Get coordinate Z. 
     * @return a double
     * @see #setZ(double)
     */    
    public double getZ() ;
    
    /** 
     * Set alternate Location.
     * @param c  a Character object specifying the alt loc value 
     * @see #getAltLoc
     */
    public void setAltLoc(Character c);
    
    /** 
     * Get alternate Location. 
     * @return a Character object representing the alt loc value
     * @see #setAltLoc
     */
    public Character getAltLoc();
    
    /** 
     * Set occupancy. 
     * @param occupancy  a double specifying the occupancy value
     * @see #getOccupancy
     */
    public void setOccupancy(double occupancy) ;
    
    /** 
     * Get occupancy. 
     * @return a double representing the occupancy value
     * @see #setOccupancy
     */
    public double getOccupancy();
    
    /** 
     * Set temp factor .
     * @param temp  a double specifying the temp factor value
     * @see #getTempFactor
     */
    public void   setTempFactor(double temp) ;
    
    /** 
     * Get temp factor. 
     * @return a double representing the temp factor value
     * @see #setTempFactor
     */
    public double getTempFactor() ;
    
    /** 
     * Return an identical copy of this  object .
     * @return  an identical copy of this  object 
     */
    public Object clone();
    
    /** 
     * Set the back-reference to its parent Group.
     * @param parent the parent Group
     * @see #getGroup()
     */
    
    public void setGroup(Group parent);
    
    /** 
     * Return the parent Group of the Atom.
     * returns null if the referenced object is not Group 
     * @return Group the parent Group of the Atom, or null
     * @see #setGroup(Group)     
     */
    public Group getGroup();
    
    /** 
     * Add a bond
     * @param bond to be added
     * @see #getBonds()
     */
    public void addBond(Bond bond);
    
    /**
     * Get all {@link Bond}s this atom is part of.
     * 
     * @return a list of {@link Bond}s.
     */
    public List<Bond> getBonds();
}
