View Javadoc
1   /*
2    * Copyright 2015 The Netty Project
3    *
4    * The Netty Project licenses this file to you under the Apache License,
5    * version 2.0 (the "License"); you may not use this file except in compliance
6    * with the License. You may obtain a copy of the License at:
7    *
8    *   http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13   * License for the specific language governing permissions and limitations
14   * under the License.
15   */
16  package io.netty.util;
17  
18  /**
19   * Abstraction for hash code generation and equality comparison.
20   */
21  public interface HashingStrategy<T> {
22      /**
23       * Generate a hash code for {@code obj}.
24       * <p>
25       * This method must obey the same relationship that {@link java.lang.Object#hashCode()} has with
26       * {@link java.lang.Object#equals(Object)}:
27       * <ul>
28       * <li>Calling this method multiple times with the same {@code obj} should return the same result</li>
29       * <li>If {@link #equals(Object, Object)} with parameters {@code a} and {@code b} returns {@code true}
30       * then the return value for this method for parameters {@code a} and {@code b} must return the same result</li>
31       * <li>If {@link #equals(Object, Object)} with parameters {@code a} and {@code b} returns {@code false}
32       * then the return value for this method for parameters {@code a} and {@code b} does <strong>not</strong> have to
33       * return different results results. However this property is desirable.</li>
34       * <li>if {@code obj} is {@code null} then this method return {@code 0}</li>
35       * </ul>
36       */
37      int hashCode(T obj);
38  
39      /**
40       * Returns {@code true} if the arguments are equal to each other and {@code false} otherwise.
41       * This method has the following restrictions:
42       * <ul>
43       * <li><i>reflexive</i> - {@code equals(a, a)} should return true</li>
44       * <li><i>symmetric</i> - {@code equals(a, b)} returns {@code true} iff {@code equals(b, a)} returns
45       * {@code true}</li>
46       * <li><i>transitive</i> - if {@code equals(a, b)} returns {@code true} and {@code equals(a, c)} returns
47       * {@code true} then {@code equals(b, c)} should also return {@code true}</li>
48       * <li><i>consistent</i> - {@code equals(a, b)} should return the same result when called multiple times
49       * assuming {@code a} and {@code b} remain unchanged relative to the comparison criteria</li>
50       * <li>if {@code a} and {@code b} are both {@code null} then this method returns {@code true}</li>
51       * <li>if {@code a} is {@code null} and {@code b} is non-{@code null}, or {@code a} is non-{@code null} and
52       * {@code b} is {@code null} then this method returns {@code false}</li>
53       * </ul>
54       */
55      boolean equals(T a, T b);
56  
57      /**
58       * A {@link HashingStrategy} which delegates to java's {@link Object#hashCode()}
59       * and {@link Object#equals(Object)}.
60       */
61      @SuppressWarnings("rawtypes")
62      HashingStrategy JAVA_HASHER = new HashingStrategy() {
63          @Override
64          public int hashCode(Object obj) {
65              return obj != null ? obj.hashCode() : 0;
66          }
67  
68          @Override
69          public boolean equals(Object a, Object b) {
70              return (a == b) || (a != null && a.equals(b));
71          }
72      };
73  }