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 * Created on 28.04.2004
021 * @author Andreas Prlic
022 *
023 */
024package org.biojava.nbio.structure;
025
026import java.util.List;
027
028import javax.vecmath.Point3d;
029
030/**
031 * A simple interface for an Atom.
032 * The coordinates can be accessed via the
033 * {@link #getCoords()}, or the
034 * {@link #getX()}, {@link #getY()}, {@link #getZ()} methods.
035 * There are a few additional methods here to provide some PDB specific information.
036 *
037
038 * @author Andreas Prlic
039 * @author Horvath Tamas
040 * @version %I% %G%
041 * @since 1.4
042 *
043 */
044public interface Atom extends Cloneable, PDBRecord {
045
046        /**
047         * Set atom name, e.g. "CA".
048         * @param s  a trimmed String specifying the name value
049         * @see #getName
050         */
051        public void   setName(String s);
052
053        /**
054         * Get atom name, e.g. "CA".
055         * Beware that some PDB atom names are ambiguous (e.g. CA, which means C-alpha or Calcium),
056         * the ambiguity can simply be resolved by also checking the element with {@link #getElement()}
057         * @return a trimmed String representing the name value
058         * @see #setName
059         */
060        public String getName();
061
062        /**
063         * Set element of the atom name, e.g. {@link Element#Fe}
064         * @param e  an Element enumeration
065         * @see #getElement
066         */
067        public void   setElement(Element e);
068
069        /**
070         * Get element of the atom, e.g. {@link Element#Ca}
071         * @return an Element enumeration
072         * @see #setElement
073         */
074        public Element getElement();
075
076        /**
077         * Set PDB atom number.
078         * @param i  an int specifying the PDBserial value
079         * @see #getPDBserial
080         */
081        public void setPDBserial(int i) ;
082
083        /**
084         * Get PDB atom number.
085         * @return an int representing the PDBserial value
086         * @see #setPDBserial
087         */
088        public int  getPDBserial() ;
089
090        /**
091         * Set the coordinates.
092         * @param c  an array of doubles specifying the coords value
093         * @see #getCoords
094         */
095        public void    setCoords(double[] c);
096
097        /**
098         * Get the coordinates.
099         * @return a new array of doubles representing the coords value
100         * @see #setCoords
101         * @see #getCoordsAsPoint3d()
102         */
103        public double[] getCoords() ;
104        
105        /**
106         * Get the coordinates.
107         * <p> 
108         * Internally the coordinates are represented as Point3d so this 
109         * is recommended over {@link #getCoords()}
110         * @return a reference to the Point3d coordinates
111         * @see #getCoords()
112         */
113        public Point3d getCoordsAsPoint3d();    
114
115        /**
116         * Set the X coordinate.
117         * @param x  a double
118         * @see #getX()
119         */
120        public void setX(double x);
121
122        /**
123         * Set the Y coordinate.
124         * @param y  a double
125         * @see #getY()
126         */
127        public void setY(double y);
128
129        /**
130         * Set the Z coordinate.
131         * @param z  a double
132         * @see #getZ()
133         */
134        public void setZ(double z);
135
136        /**
137         * Get coordinate X.
138         * @return a double
139         * @see #setX(double)
140         */
141        public double getX() ;
142
143        /**
144         * Get coordinate Y.
145         * @return a double
146         * @see #setY(double)
147         */
148        public double getY() ;
149
150        /**
151         * Get coordinate Z.
152         * @return a double
153         * @see #setZ(double)
154         */
155        public double getZ() ;
156
157        /**
158         * Set alternate Location.
159         * @param c  a Character object specifying the alt loc value
160         * @see #getAltLoc
161         */
162        public void setAltLoc(Character c);
163
164        /**
165         * Get alternate Location.
166         * @return a Character object representing the alt loc value
167         * @see #setAltLoc
168         */
169        public Character getAltLoc();
170
171        /**
172         * Set occupancy.
173         * @param occupancy  a float specifying the occupancy value
174         * @see #getOccupancy
175         */
176        public void setOccupancy(float occupancy) ;
177
178        /**
179         * Get occupancy.
180         * @return a float representing the occupancy value
181         * @see #setOccupancy
182         */
183        public float getOccupancy();
184
185        /**
186         * Set temp factor .
187         * @param temp  a float specifying the temp factor value
188         * @see #getTempFactor
189         */
190        public void   setTempFactor(float temp) ;
191
192        /**
193         * Get temp factor.
194         * @return a float representing the temp factor value
195         * @see #setTempFactor
196         */
197        public float getTempFactor() ;
198
199        /**
200         * Return an identical copy of this  object .
201         * @return  an identical copy of this  object
202         */
203        public Object clone();
204
205        /**
206         * Set the back-reference to its parent Group.
207         * @param parent the parent Group
208         * @see #getGroup()
209         */
210
211        public void setGroup(Group parent);
212
213        /**
214         * Return the parent Group of the Atom.
215         * returns null if the referenced object is not Group
216         * @return Group the parent Group of the Atom, or null
217         * @see #setGroup(Group)
218         */
219        public Group getGroup();
220
221        /**
222         * Add a bond
223         * @param bond to be added
224         * @see #getBonds()
225         */
226        public void addBond(Bond bond);
227
228        /**
229         * Get all {@link Bond}s this atom is part of.
230         *
231         * @return a list of {@link Bond}s or null if no bonds exist for this Atom
232         */
233        public List<Bond> getBonds();
234
235        /**
236         * Sets the bonds
237         * @param bonds
238         */
239        public void setBonds(List<Bond> bonds);
240
241
242        /** Test if another atom has a bond to this atom
243         *
244         * @param other
245         * @return
246     */
247        public boolean hasBond(Atom other);
248
249        /**
250         * Get the charge of this atom
251         *
252         * @return a the integer charge.
253         */
254        public short getCharge();
255
256        /**
257         * Set the charge of this atom
258         *
259         * @return void.
260         */
261        public void setCharge(short charge);
262}