Source Code Cross Referenced for Comparator.java in  » Database-DBMS » perst » org » garret » perst » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Java Source Code / Java Documentation
1. 6.0 JDK Core
2. 6.0 JDK Modules
3. 6.0 JDK Modules com.sun
4. 6.0 JDK Modules com.sun.java
5. 6.0 JDK Modules sun
6. 6.0 JDK Platform
7. Ajax
8. Apache Harmony Java SE
9. Aspect oriented
10. Authentication Authorization
11. Blogger System
12. Build
13. Byte Code
14. Cache
15. Chart
16. Chat
17. Code Analyzer
18. Collaboration
19. Content Management System
20. Database Client
21. Database DBMS
22. Database JDBC Connection Pool
23. Database ORM
24. Development
25. EJB Server geronimo
26. EJB Server GlassFish
27. EJB Server JBoss 4.2.1
28. EJB Server resin 3.1.5
29. ERP CRM Financial
30. ESB
31. Forum
32. GIS
33. Graphic Library
34. Groupware
35. HTML Parser
36. IDE
37. IDE Eclipse
38. IDE Netbeans
39. Installer
40. Internationalization Localization
41. Inversion of Control
42. Issue Tracking
43. J2EE
44. JBoss
45. JMS
46. JMX
47. Library
48. Mail Clients
49. Net
50. Parser
51. PDF
52. Portal
53. Profiler
54. Project Management
55. Report
56. RSS RDF
57. Rule Engine
58. Science
59. Scripting
60. Search Engine
61. Security
62. Sevlet Container
63. Source Control
64. Swing Library
65. Template Engine
66. Test Coverage
67. Testing
68. UML
69. Web Crawler
70. Web Framework
71. Web Mail
72. Web Server
73. Web Services
74. Web Services apache cxf 2.0.1
75. Web Services AXIS2
76. Wiki Engine
77. Workflow Engines
78. XML
79. XML UI
Java
Java Tutorial
Java Open Source
Jar File Download
Java Articles
Java Products
Java by API
Photoshop Tutorials
Maya Tutorials
Flash Tutorials
3ds-Max Tutorials
Illustrator Tutorials
GIMP Tutorials
C# / C Sharp
C# / CSharp Tutorial
C# / CSharp Open Source
ASP.Net
ASP.NET Tutorial
JavaScript DHTML
JavaScript Tutorial
JavaScript Reference
HTML / CSS
HTML CSS Reference
C / ANSI-C
C Tutorial
C++
C++ Tutorial
Ruby
PHP
Python
Python Tutorial
Python Open Source
SQL Server / T-SQL
SQL Server / T-SQL Tutorial
Oracle PL / SQL
Oracle PL/SQL Tutorial
PostgreSQL
SQL / MySQL
MySQL Tutorial
VB.Net
VB.Net Tutorial
Flash / Flex / ActionScript
VBA / Excel / Access / Word
XML
XML Tutorial
Microsoft Office PowerPoint 2007 Tutorial
Microsoft Office Excel 2007 Tutorial
Microsoft Office Word 2007 Tutorial
Java Source Code / Java Documentation » Database DBMS » perst » org.garret.perst 
Source Cross Referenced  Class Diagram Java Document (Java Doc) 


001:        package org.garret.perst;
002:
003:        /**
004:         * A comparison function, which imposes a <i>total ordering</i> on some
005:         * collection of objects.  Comparators can be passed to a sort method (such as
006:         * <tt>Collections.sort</tt>) to allow precise control over the sort order.
007:         * Comparators can also be used to control the order of certain data
008:         * structures (such as <tt>TreeSet</tt> or <tt>TreeMap</tt>).<p>
009:         *
010:         * The ordering imposed by a Comparator <tt>c</tt> on a set of elements
011:         * <tt>S</tt> is said to be <i>consistent with equals</i> if and only if
012:         * <tt>(compare((Object)e1, (Object)e2)==0)</tt> has the same boolean value as
013:         * <tt>e1.equals((Object)e2)</tt> for every <tt>e1</tt> and <tt>e2</tt> in
014:         * <tt>S</tt>.<p>
015:         *
016:         * Caution should be exercised when using a comparator capable of imposing an
017:         * ordering inconsistent with equals to order a sorted set (or sorted map).
018:         * Suppose a sorted set (or sorted map) with an explicit Comparator <tt>c</tt>
019:         * is used with elements (or keys) drawn from a set <tt>S</tt>.  If the
020:         * ordering imposed by <tt>c</tt> on <tt>S</tt> is inconsistent with equals,
021:         * the sorted set (or sorted map) will behave "strangely."  In particular the
022:         * sorted set (or sorted map) will violate the general contract for set (or
023:         * map), which is defined in terms of <tt>equals</tt>.<p>
024:         * 
025:         * For example, if one adds two keys <tt>a</tt> and <tt>b</tt> such that
026:         * <tt>(a.equals((Object)b) && c.compare((Object)a, (Object)b) != 0)</tt> to a
027:         * sorted set with comparator <tt>c</tt>, the second <tt>add</tt> operation
028:         * will return false (and the size of the sorted set will not increase)
029:         * because <tt>a</tt> and <tt>b</tt> are equivalent from the sorted set's
030:         * perspective.<p>
031:         *
032:         * Note: It is generally a good idea for comparators to implement
033:         * <tt>java.io.Serializable</tt>, as they may be used as ordering methods in
034:         * serializable data structures (like <tt>TreeSet</tt>, <tt>TreeMap</tt>).  In
035:         * order for the data structure to serialize successfully, the comparator (if
036:         * provided) must implement <tt>Serializable</tt>.<p>
037:         *
038:         * For the mathematically inclined, the <i>relation</i> that defines
039:         * the <i>total order</i> that a given comparator <tt>c</tt> imposes on a
040:         * given set of objects <tt>S</tt> is:<pre>
041:         *       {(x, y) such that c.compare((Object)x, (Object)y) &lt;= 0}.
042:         * </pre> The <i>quotient</i> for this total order is:<pre>
043:         *       {(x, y) such that c.compare((Object)x, (Object)y) == 0}.
044:         * </pre>
045:         *
046:         * It follows immediately from the contract for <tt>compare</tt> that the
047:         * quotient is an <i>equivalence relation</i> on <tt>S</tt>, and that the
048:         * natural ordering is a <i>total order</i> on <tt>S</tt>.  When we say that
049:         * the ordering imposed by <tt>c</tt> on <tt>S</tt> is <i>consistent with
050:         * equals</i>, we mean that the quotient for the natural ordering is the
051:         * equivalence relation defined by the objects' <tt>equals(Object)</tt>
052:         * method(s):<pre>
053:         *       {(x, y) such that x.equals((Object)y)}.
054:         * </pre><p>
055:         */
056:
057:        public interface Comparator {
058:            /**
059:             * Compares its two arguments for order.  Returns a negative integer,
060:             * zero, or a positive integer as the first argument is less than, equal
061:             * to, or greater than the second.<p>
062:             *
063:             * The implementor must ensure that <tt>sgn(compare(x, y)) ==
064:             * -sgn(compare(y, x))</tt> for all <tt>x</tt> and <tt>y</tt>.  (This
065:             * implies that <tt>compare(x, y)</tt> must throw an exception if and only
066:             * if <tt>compare(y, x)</tt> throws an exception.)<p>
067:             *
068:             * The implementor must also ensure that the relation is transitive:
069:             * <tt>((compare(x, y)&gt;0) &amp;&amp; (compare(y, z)&gt;0))</tt> implies
070:             * <tt>compare(x, z)&gt;0</tt>.<p>
071:             *
072:             * Finally, the implementer must ensure that <tt>compare(x, y)==0</tt>
073:             * implies that <tt>sgn(compare(x, z))==sgn(compare(y, z))</tt> for all
074:             * <tt>z</tt>.<p>
075:             *
076:             * It is generally the case, but <i>not</i> strictly required that 
077:             * <tt>(compare(x, y)==0) == (x.equals(y))</tt>.  Generally speaking,
078:             * any comparator that violates this condition should clearly indicate
079:             * this fact.  The recommended language is "Note: this comparator
080:             * imposes orderings that are inconsistent with equals."
081:             * 
082:             * @param o1 the first object to be compared.
083:             * @param o2 the second object to be compared.
084:             * @return a negative integer, zero, or a positive integer as the
085:             * 	       first argument is less than, equal to, or greater than the
086:             *	       second. 
087:             * @throws ClassCastException if the arguments' types prevent them from
088:             * 	       being compared by this Comparator.
089:             */
090:            int compare(Object o1, Object o2);
091:
092:            /**
093:             * 
094:             * Indicates whether some other object is &quot;equal to&quot; this
095:             * Comparator.  This method must obey the general contract of
096:             * <tt>Object.equals(Object)</tt>.  Additionally, this method can return
097:             * <tt>true</tt> <i>only</i> if the specified Object is also a comparator
098:             * and it imposes the same ordering as this comparator.  Thus,
099:             * <code>comp1.equals(comp2)</code> implies that <tt>sgn(comp1.compare(o1,
100:             * o2))==sgn(comp2.compare(o1, o2))</tt> for every object reference
101:             * <tt>o1</tt> and <tt>o2</tt>.<p>
102:             *
103:             * Note that it is <i>always</i> safe <i>not</i> to override
104:             * <tt>Object.equals(Object)</tt>.  However, overriding this method may,
105:             * in some cases, improve performance by allowing programs to determine
106:             * that two distinct Comparators impose the same order.
107:             *
108:             * @param   obj   the reference object with which to compare.
109:             * @return  <code>true</code> only if the specified object is also
110:             *		a comparator and it imposes the same ordering as this
111:             *		comparator.
112:             * @see     java.lang.Object#equals(java.lang.Object)
113:             * @see java.lang.Object#hashCode()
114:             */
115:            boolean equals(Object obj);
116:        }
www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.