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 * ComparableObjectItem.java
029 * -------------------------
030 * (C) Copyright 2006-2008, by Object Refinery Limited.
031 *
032 * Original Author:  David Gilbert (for Object Refinery Limited);
033 * Contributor(s):   -;
034 *
035 * Changes
036 * -------
037 * 19-Oct-2006 : New class, based on XYDataItem (DG);
038 *
039 */
040
041package org.jfree.data;
042
043import java.io.Serializable;
044
045import org.jfree.util.ObjectUtilities;
046
047/**
048 * Represents one (Comparable, Object) data item for use in a
049 * {@link ComparableObjectSeries}.
050 *
051 * @since 1.0.3
052 */
053public class ComparableObjectItem implements Cloneable, Comparable,
054        Serializable {
055
056    /** For serialization. */
057    private static final long serialVersionUID = 2751513470325494890L;
058
059    /** The x-value. */
060    private Comparable x;
061
062    /** The y-value. */
063    private Object obj;
064
065    /**
066     * Constructs a new data item.
067     *
068     * @param x  the x-value (<code>null</code> NOT permitted).
069     * @param y  the y-value (<code>null</code> permitted).
070     */
071    public ComparableObjectItem(Comparable x, Object y) {
072        if (x == null) {
073            throw new IllegalArgumentException("Null 'x' argument.");
074        }
075        this.x = x;
076        this.obj = y;
077    }
078
079    /**
080     * Returns the x-value.
081     *
082     * @return The x-value (never <code>null</code>).
083     */
084    protected Comparable getComparable() {
085        return this.x;
086    }
087
088    /**
089     * Returns the y-value.
090     *
091     * @return The y-value (possibly <code>null</code>).
092     */
093    protected Object getObject() {
094        return this.obj;
095    }
096
097    /**
098     * Sets the y-value for this data item.  Note that there is no
099     * corresponding method to change the x-value.
100     *
101     * @param y  the new y-value (<code>null</code> permitted).
102     */
103    protected void setObject(Object y) {
104        this.obj = y;
105    }
106
107    /**
108     * Returns an integer indicating the order of this object relative to
109     * another object.
110     * <P>
111     * For the order we consider only the x-value:
112     * negative == "less-than", zero == "equal", positive == "greater-than".
113     *
114     * @param o1  the object being compared to.
115     *
116     * @return An integer indicating the order of this data pair object
117     *      relative to another object.
118     */
119    public int compareTo(Object o1) {
120
121        int result;
122
123        // CASE 1 : Comparing to another ComparableObjectItem object
124        // ---------------------------------------------------------
125        if (o1 instanceof ComparableObjectItem) {
126            ComparableObjectItem that = (ComparableObjectItem) o1;
127            return this.x.compareTo(that.x);
128        }
129
130        // CASE 2 : Comparing to a general object
131        // ---------------------------------------------
132        else {
133            // consider these to be ordered after general objects
134            result = 1;
135        }
136
137        return result;
138
139    }
140
141    /**
142     * Returns a clone of this object.
143     *
144     * @return A clone.
145     *
146     * @throws CloneNotSupportedException not thrown by this class, but
147     *         subclasses may differ.
148     */
149    public Object clone() throws CloneNotSupportedException {
150        return super.clone();
151    }
152
153    /**
154     * Tests if this object is equal to another.
155     *
156     * @param obj  the object to test against for equality (<code>null</code>
157     *             permitted).
158     *
159     * @return A boolean.
160     */
161    public boolean equals(Object obj) {
162        if (obj == this) {
163            return true;
164        }
165        if (!(obj instanceof ComparableObjectItem)) {
166            return false;
167        }
168        ComparableObjectItem that = (ComparableObjectItem) obj;
169        if (!this.x.equals(that.x)) {
170            return false;
171        }
172        if (!ObjectUtilities.equal(this.obj, that.obj)) {
173            return false;
174        }
175        return true;
176    }
177
178    /**
179     * Returns a hash code.
180     *
181     * @return A hash code.
182     */
183    public int hashCode() {
184        int result;
185        result = this.x.hashCode();
186        result = 29 * result + (this.obj != null ? this.obj.hashCode() : 0);
187        return result;
188    }
189
190}