    001    /* ===========================================================
    002     * JFreeChart : a free chart library for the Java(tm) platform
    003     * ===========================================================
    004     *
    005     * (C) Copyright 2000-2008, 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     * OutlierListCollection.java
    029     * --------------------------
    030     * (C) Copyright 2003-2008, by David Browning and Contributors.
    031     *
    032     * Original Author:  David Browning (for Australian Institute of Marine
    033     *                   Science);
    034     * Contributor(s):   -;
    035     *
    036     * Changes
    037     * -------
    038     * 05-Aug-2003 : Version 1, contributed by David Browning (DG);
    039     * 01-Sep-2003 : Made storage internal rather than extending ArrayList (DG);
    040     * ------------- JFREECHART 1.0.x ---------------------------------------------
    041     * 02-Feb-2007 : Removed author tags from all over JFreeChart sources (DG);
    042     *
    043     */
    044
    045    package org.jfree.chart.renderer;
    046
    047    import java.util.ArrayList;
    048    import java.util.Iterator;
    049    import java.util.List;
    050
    051    /**
    052     * A collection of outlier lists for a box and whisker plot. Each collection is
    053     * associated with a single box and whisker entity.
    054     *
    055     * Outliers are grouped in lists for each entity. Lists contain
    056     * one or more outliers, determined by whether overlaps have
    057     * occurred. Overlapping outliers are grouped in the same list.
    058     *
    059     * @see org.jfree.chart.renderer.OutlierList
    060     */
    061    public class OutlierListCollection {
    062
    063        /** Storage for the outlier lists. */
    064        private List outlierLists;
    065
    066        /**
    067         * Unbelievably, outliers which are more than 2 * interquartile range are
    068         * called far outs...  See Tukey EDA  (a classic one of a kind...)
    069         */
    070        private boolean highFarOut = false;
    071
    072        /**
    073         * A flag that indicates whether or not the collection contains low far
    074         * out values.
    075         */
    076        private boolean lowFarOut = false;
    077
    078        /**
    079         * Creates a new empty collection.
    080         */
    081        public OutlierListCollection() {
    082            this.outlierLists = new ArrayList();
    083        }
    084
    085        /**
    086         * A flag to indicate the presence of one or more far out values at the
    087         * top end of the range.
    088         *
    089         * @return A <code>boolean</code>.
    090         */
    091        public boolean isHighFarOut() {
    092            return this.highFarOut;
    093        }
    094
    095        /**
    096         * Sets the flag that indicates the presence of one or more far out values
    097         * at the top end of the range.
    098         *
    099         * @param farOut  the flag.
    100         */
    101        public void setHighFarOut(boolean farOut) {
    102            this.highFarOut = farOut;
    103        }
    104
    105        /**
    106         * A flag to indicate the presence of one or more far out values at the
    107         * bottom end of the range.
    108         *
    109         * @return A <code>boolean</code>.
    110         */
    111        public boolean isLowFarOut() {
    112            return this.lowFarOut;
    113        }
    114
    115        /**
    116         * Sets the flag that indicates the presence of one or more far out values
    117         * at the bottom end of the range.
    118         *
    119         * @param farOut  the flag.
    120         */
    121        public void setLowFarOut(boolean farOut) {
    122            this.lowFarOut = farOut;
    123        }
    124        /**
    125         * Appends the specified element as a new <code>OutlierList</code> to the
    126         * end of this list if it does not overlap an outlier in an existing list.
    127         *
    128         * If it does overlap, it is appended to the outlier list which it overlaps
    129         * and that list is updated.
    130         *
    131         * @param outlier  element to be appended to this list.
    132         *
    133         * @return <tt>true</tt> (as per the general contract of Collection.add).
    134         */
    135        public boolean add(Outlier outlier) {
    136
    137            if (this.outlierLists.isEmpty()) {
    138                return this.outlierLists.add(new OutlierList(outlier));
    139            }
    140            else {
    141                boolean updated = false;
    142                for (Iterator iterator = this.outlierLists.iterator();
    143                     iterator.hasNext();) {
    144                    OutlierList list = (OutlierList) iterator.next();
    145                    if (list.isOverlapped(outlier)) {
    146                        updated = updateOutlierList(list, outlier);
    147                    }
    148                }
    149                if (!updated) {
    150                    //System.err.print(" creating new outlier list ");
    151                    updated = this.outlierLists.add(new OutlierList(outlier));
    152                }
    153                return updated;
    154            }
    155
    156        }
    157
    158        /**
    159         * Returns an iterator for the outlier lists.
    160         *
    161         * @return An iterator.
    162         */
    163        public Iterator iterator() {
    164            return this.outlierLists.iterator();
    165        }
    166
    167
    168        /**
    169         * Updates the outlier list by adding the outlier to the end of the list and
    170         * setting the averaged outlier to the average x and y coordinnate values
    171         * of the outliers in the list.
    172         *
    173         * @param list  the outlier list to be updated.
    174         * @param outlier  the outlier to be added
    175         *
    176         * @return <tt>true</tt> (as per the general contract of Collection.add).
    177         */
    178        private boolean updateOutlierList(OutlierList list, Outlier outlier) {
    179            boolean result = false;
    180            result = list.add(outlier);
    181            list.updateAveragedOutlier();
    182            list.setMultiple(true);
    183            return result;
    184        }
    185
    186    }