001    /* ===========================================================
002     * JFreeChart : a free chart library for the Java(tm) platform
003     * ===========================================================
004     *
005     * (C) Copyright 2000-2005, by Object Refinery Limited and Contributors.
006     *
007     * Project Info:  http://www.jfree.org/jfreechart/index.html
008     *
009     * This library is free software; you can redistribute it and/or modify it 
010     * under the terms of the GNU Lesser General Public License as published by 
011     * the Free Software Foundation; either version 2.1 of the License, or 
012     * (at your option) any later version.
013     *
014     * This library is distributed in the hope that it will be useful, but 
015     * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 
016     * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 
017     * License for more details.
018     *
019     * You should have received a copy of the GNU Lesser General Public
020     * License along with this library; if not, write to the Free Software
021     * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, 
022     * USA.  
023     *
024     * [Java is a trademark or registered trademark of Sun Microsystems, Inc. 
025     * in the United States and other countries.]
026     *
027     * -----------------------------
028     * StandardEntityCollection.java
029     * -----------------------------
030     * (C) Copyright 2001-2005, by Object Refinery Limited.
031     *
032     * Original Author:  David Gilbert (for Object Refinery Limited);
033     * Contributor(s):   -;
034     *
035     * $Id: StandardEntityCollection.java,v 1.8.2.1 2005/10/25 20:41:59 mungady Exp $
036     *
037     * Changes
038     * -------
039     * 23-May-2002 : Version 1 (DG);
040     * 26-Jun-2002 : Added iterator() method (DG);
041     * 03-Oct-2002 : Fixed errors reported by Checkstyle (DG);
042     * 19-May-2004 : Implemented Serializable (DG);
043     * 29-Sep-2004 : Renamed addEntity() --> add() and addEntities() 
044     *               --> addAll() (DG);
045     * 19-Jan-2005 : Changed storage from Collection --> List (DG);
046     * 20-May-2005 : Fixed bug 1113521 - inefficiency in getEntity() method (DG);
047     *
048     */
049    
050    package org.jfree.chart.entity;
051    
052    import java.io.Serializable;
053    import java.util.Collection;
054    import java.util.Collections;
055    import java.util.Iterator;
056    import java.util.List;
057    
058    import org.jfree.util.ObjectUtilities;
059    
060    /**
061     * A standard implementation of the {@link EntityCollection} interface.
062     */
063    public class StandardEntityCollection implements EntityCollection, 
064                                                     Cloneable, Serializable {
065    
066        /** For serialization. */
067        private static final long serialVersionUID = 5384773031184897047L;
068        
069        /** Storage for the entities. */
070        private List entities;
071    
072        /**
073         * Constructs a new entity collection (initially empty).
074         */
075        public StandardEntityCollection() {
076            this.entities = new java.util.ArrayList();
077        }
078    
079        /**
080         * Returns the number of entities in the collection.
081         * 
082         * @return The entity count.
083         */
084        public int getEntityCount() {
085            return this.entities.size();
086        }
087        
088        /**
089         * Returns a chart entity from the collection.
090         * 
091         * @param index  the entity index.
092         * 
093         * @return The entity.
094         */
095        public ChartEntity getEntity(int index) {
096            return (ChartEntity) this.entities.get(index);
097        }
098        
099        /**
100         * Clears the entities.
101         */
102        public void clear() {
103            this.entities.clear();
104        }
105    
106        /**
107         * Adds an entity to the collection.
108         *
109         * @param entity  the entity (<code>null</code> not permitted).
110         */
111        public void add(ChartEntity entity) {
112            if (entity == null) {
113                throw new IllegalArgumentException("Null 'entity' argument.");
114            }
115            this.entities.add(entity);
116        }
117        
118        /**
119         * Adds all the entities from the specified collection.
120         * 
121         * @param collection  the collection of entities.
122         */
123        public void addAll(EntityCollection collection) {
124            this.entities.addAll(collection.getEntities());
125        }
126    
127        /**
128         * Returns the last entity in the list with an area that encloses the 
129         * specified coordinates, or <code>null</code> if there is no such entity.
130         *
131         * @param x  the x coordinate.
132         * @param y  the y coordinate.
133         *
134         * @return The entity (possibly <code>null</code>).
135         */
136        public ChartEntity getEntity(double x, double y) {
137            int entityCount = this.entities.size();
138            for (int i = entityCount - 1; i >= 0; i--) {
139                ChartEntity entity = (ChartEntity) this.entities.get(i);
140                if (entity.getArea().contains(x, y)) {
141                    return entity;
142                }
143            }
144            return null;
145        }
146    
147        /**
148         * Returns the entities in an unmodifiable collection.
149         * 
150         * @return The entities.
151         */
152        public Collection getEntities() {
153            return Collections.unmodifiableCollection(this.entities);
154        }
155        
156        /**
157         * Returns an iterator for the entities in the collection.
158         *
159         * @return An iterator.
160         */
161        public Iterator iterator() {
162            return this.entities.iterator();
163        }
164        
165        /**
166         * Tests this object for equality with an arbitrary object.
167         * 
168         * @param obj  the object to test against (<code>null</code> permitted).
169         * 
170         * @return A boolean.
171         */
172        public boolean equals(Object obj) {
173            if (obj == this) {
174                return true;   
175            }
176            if (obj instanceof StandardEntityCollection) {
177                StandardEntityCollection that = (StandardEntityCollection) obj;
178                return ObjectUtilities.equal(this.entities, that.entities);
179            }
180            return false;
181        }
182    
183        /**
184         * Returns a clone.
185         * 
186         * @return A clone.
187         * 
188         * @throws CloneNotSupportedException if the object cannot be cloned.
189         */
190        public Object clone() throws CloneNotSupportedException {
191            return super.clone();   
192        }
193    
194    }