KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jgrapht > experimental > equivalence > EquivalenceSet


1 /* ==========================================
2  * JGraphT : a free Java graph-theory library
3  * ==========================================
4  *
5  * Project Info: http://jgrapht.sourceforge.net/
6  * Project Creator: Barak Naveh (http://sourceforge.net/users/barak_naveh)
7  *
8  * (C) Copyright 2003-2006, by Barak Naveh and Contributors.
9  *
10  * This library is free software; you can redistribute it and/or modify it
11  * under the terms of the GNU Lesser General Public License as published by
12  * the Free Software Foundation; either version 2.1 of the License, or
13  * (at your option) any later version.
14  *
15  * This library is distributed in the hope that it will be useful, but
16  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
17  * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
18  * License for more details.
19  *
20  * You should have received a copy of the GNU Lesser General Public License
21  * along with this library; if not, write to the Free Software Foundation,
22  * Inc.,
23  * 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
24  */
25 /* -----------------
26  * EquivalenceSet.java
27  * -----------------
28  * (C) Copyright 2005-2006, by Assaf Lehr and Contributors.
29  *
30  * Original Author: Assaf Lehr
31  * Contributor(s): -
32  *
33  * $Id: EquivalenceSet.java 504 2006-07-03 02:37:26Z perfecthash $
34  *
35  * Changes
36  * -------
37  */
38 package org.jgrapht.experimental.equivalence;
39
40 import java.util.*;
41
42
43 /**
44  * EquivalenceSet is a Set of elements which have been determined to be
45  * equivalent using EquivalenceComparator. The class makes sure the set size
46  * will be one or more.
47  * <li>The group can only be created using the factory method
48  * createGroupWithElement().
49  * <li>The equals and hashcode of a group uses the EquivalenceComparator on one
50  * of the group members, thus it is actually checking whether the "other" is in
51  * the same group.
52  *
53  * @param <E> the type of the elements in the set
54  * @param <C> the type of the context the element is compared against, e.g. a
55  * Graph
56  *
57  * @author Assaf
58  * @since Jul 21, 2005
59  */
60 public class EquivalenceSet<E, C>
61 {
62
63     //~ Instance fields -------------------------------------------------------
64
65     /**
66      * The comparator used to define the group
67      */
68     protected EquivalenceComparator<? super E, ? super C> eqComparator;
69     protected C comparatorContext;
70
71     /**
72      * Contains the current elements of the group
73      */
74     protected Set<E> elementsSet;
75
76     //~ Constructors ----------------------------------------------------------
77
78     /**
79      * Private constructor. An empty group cannot be created as a group does not
80      * have meaning without an element, because the equal and hashcode methods
81      * cannot work.
82      */
83     private EquivalenceSet()
84     {
85     }
86
87     /**
88      * Constructs a new EquivalenceSet, filled with the aElement parameter and a
89      * reference to the comparator which is used.
90      */
91     public EquivalenceSet(
92         E aElement,
93         EquivalenceComparator<? super E, ? super C> aEqComparator,
94         C aComparatorContext)
95     {
96         this.eqComparator = aEqComparator;
97         this.comparatorContext = aComparatorContext;
98
99         this.elementsSet = new HashSet<E>();
100         this.elementsSet.add(aElement);
101     }
102
103     //~ Methods ---------------------------------------------------------------
104
105     /**
106      * Returns an arbitrary object from the group. There is no guarantee as to
107      * which will be returned, and whether the same will be returned on the next
108      * call.
109      */
110     public E getRepresentative()
111     {
112         return elementsSet.iterator().next();
113     }
114
115     public C getContext()
116     {
117         return this.comparatorContext;
118     }
119
120     public int size()
121     {
122         return elementsSet.size();
123     }
124
125     /**
126      * Adds an element to the group. It does not check it for equivalance . You
127      * must make sure it does, using equals().
128      */
129     public void add(E element)
130     {
131         this.elementsSet.add(element);
132     }
133
134     public boolean equivalentTo(E aOther, C aOtherContext)
135     {
136         boolean result =
137             this.eqComparator.equivalenceCompare(
138                 this.getRepresentative(),
139                 aOther,
140                 this.comparatorContext,
141                 aOtherContext);
142         return result;
143     }
144
145     /**
146      * Uses the equivalenceCompare() of the comparator to compare a
147      * representation of this group, taken using this.getRepresentative(), and
148      * a representation of the other object, which may be the object itself, or,
149      * if it is an equivalence group too, other.getRepresentative()
150      */
151     // FIXME REVIEW hb 26-Jan-2006: I think throwing the exception is kind of
152 // odd,
153 // - it feels like violating the contract of Object.equals()
154 // From what I understand, comparing any object to any other object should
155 // be
156 // possible at all times and simply return false if they are not equal.
157 // Uncomparable objects beeing unequal.
158 // Suggestion: remove the exception, at best, test on this specific class
159 // and
160 // write a warning or some such.
161
162     @SuppressWarnings JavaDoc("unchecked")
163     public boolean equals(Object JavaDoc other)
164     {
165         E otherRepresentative = null;
166         C otherContext = null;
167         if (other instanceof EquivalenceSet) {
168             otherRepresentative =
169                 ((EquivalenceSet<E, C>) other).getRepresentative();
170             otherContext = ((EquivalenceSet<E, C>) other).getContext();
171         } else {
172             throw new ClassCastException JavaDoc(
173                 "can check equal() only of EqualityGroup");
174         }
175
176         boolean result =
177             this.eqComparator.equivalenceCompare(
178                 this.getRepresentative(),
179                 otherRepresentative,
180                 this.comparatorContext,
181                 otherContext);
182         return result;
183     }
184
185     /**
186      * Uses a representative to calculate the group hashcode using
187      * equivalenceHashcode().
188      *
189      * @see java.lang.Object#hashCode()
190      */
191     public int hashCode()
192     {
193         int result =
194             this.eqComparator.equivalenceHashcode(
195                 this.getRepresentative(),
196                 this.comparatorContext);
197         return result;
198     }
199
200     public String JavaDoc toString()
201     {
202         return "Eq.Group=" + this.elementsSet.toString();
203     }
204
205     /**
206      * Returns the elements of the group. The order of the elements in the
207      * returned array is not guaranteed. In other words, two calls to the same
208      * object may return different order.
209      */
210     public Object JavaDoc [] toArray()
211     {
212         return this.elementsSet.toArray();
213     }
214 }
215
Popular Tags