001    /* ===========================================================
002     * JFreeChart : a free chart library for the Java(tm) platform
003     * ===========================================================
004     *
005     * (C) Copyright 2000-2006, 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-2006, 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.2 2006/12/01 11:22:03 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     * ------------- JFREECHART 1.0.x ---------------------------------------------
048     * 01-Dec-2006 : Implemented PublicCloneable and fixed clone() method (DG);
049     *
050     */
051    
052    package org.jfree.chart.entity;
053    
054    import java.io.Serializable;
055    import java.util.Collection;
056    import java.util.Collections;
057    import java.util.Iterator;
058    import java.util.List;
059    
060    import org.jfree.util.ObjectUtilities;
061    import org.jfree.util.PublicCloneable;
062    
063    /**
064     * A standard implementation of the {@link EntityCollection} interface.
065     */
066    public class StandardEntityCollection implements EntityCollection, 
067            Cloneable, PublicCloneable, Serializable {
068    
069        /** For serialization. */
070        private static final long serialVersionUID = 5384773031184897047L;
071        
072        /** Storage for the entities. */
073        private List entities;
074    
075        /**
076         * Constructs a new entity collection (initially empty).
077         */
078        public StandardEntityCollection() {
079            this.entities = new java.util.ArrayList();
080        }
081    
082        /**
083         * Returns the number of entities in the collection.
084         * 
085         * @return The entity count.
086         */
087        public int getEntityCount() {
088            return this.entities.size();
089        }
090        
091        /**
092         * Returns a chart entity from the collection.
093         * 
094         * @param index  the entity index.
095         * 
096         * @return The entity.
097         * 
098         * @see #add(ChartEntity)
099         */
100        public ChartEntity getEntity(int index) {
101            return (ChartEntity) this.entities.get(index);
102        }
103        
104        /**
105         * Clears all the entities from the collection.
106         */
107        public void clear() {
108            this.entities.clear();
109        }
110    
111        /**
112         * Adds an entity to the collection.
113         *
114         * @param entity  the entity (<code>null</code> not permitted).
115         */
116        public void add(ChartEntity entity) {
117            if (entity == null) {
118                throw new IllegalArgumentException("Null 'entity' argument.");
119            }
120            this.entities.add(entity);
121        }
122        
123        /**
124         * Adds all the entities from the specified collection.
125         * 
126         * @param collection  the collection of entities (<code>null</code> not
127         *     permitted).
128         */
129        public void addAll(EntityCollection collection) {
130            this.entities.addAll(collection.getEntities());
131        }
132    
133        /**
134         * Returns the last entity in the list with an area that encloses the 
135         * specified coordinates, or <code>null</code> if there is no such entity.
136         *
137         * @param x  the x coordinate.
138         * @param y  the y coordinate.
139         *
140         * @return The entity (possibly <code>null</code>).
141         */
142        public ChartEntity getEntity(double x, double y) {
143            int entityCount = this.entities.size();
144            for (int i = entityCount - 1; i >= 0; i--) {
145                ChartEntity entity = (ChartEntity) this.entities.get(i);
146                if (entity.getArea().contains(x, y)) {
147                    return entity;
148                }
149            }
150            return null;
151        }
152    
153        /**
154         * Returns the entities in an unmodifiable collection.
155         * 
156         * @return The entities.
157         */
158        public Collection getEntities() {
159            return Collections.unmodifiableCollection(this.entities);
160        }
161        
162        /**
163         * Returns an iterator for the entities in the collection.
164         *
165         * @return An iterator.
166         */
167        public Iterator iterator() {
168            return this.entities.iterator();
169        }
170        
171        /**
172         * Tests this object for equality with an arbitrary object.
173         * 
174         * @param obj  the object to test against (<code>null</code> permitted).
175         * 
176         * @return A boolean.
177         */
178        public boolean equals(Object obj) {
179            if (obj == this) {
180                return true;   
181            }
182            if (obj instanceof StandardEntityCollection) {
183                StandardEntityCollection that = (StandardEntityCollection) obj;
184                return ObjectUtilities.equal(this.entities, that.entities);
185            }
186            return false;
187        }
188    
189        /**
190         * Returns a clone of this entity collection.
191         * 
192         * @return A clone.
193         * 
194         * @throws CloneNotSupportedException if the object cannot be cloned.
195         */
196        public Object clone() throws CloneNotSupportedException {
197            StandardEntityCollection clone 
198                    = (StandardEntityCollection) super.clone();
199            clone.entities = new java.util.ArrayList(this.entities.size());
200            for (int i = 0; i < this.entities.size(); i++) {
201                ChartEntity entity = (ChartEntity) this.entities.get(i);
202                clone.entities.add(entity.clone());
203            }
204            return clone;   
205        }
206    
207    }