Guava 源碼分析之 Beta, GwtCompatible, GwtIncompatible, Charset, HashCode

com.google.common.annotations.Beta

/**
 * 代表一個公用API的將來版本是受不兼容變動或刪除限制的
 * 擁有這個註釋標誌的API不受任何兼容性保證
 *
 */
@Retention(RetentionPolicy.CLASS)
@Target({
        ElementType.ANNOTATION_TYPE,
        ElementType.CONSTRUCTOR,
        ElementType.FIELD,
        ElementType.METHOD,
        ElementType.TYPE})
@Documented
@GwtCompatible
public @interface Beta {}

 

com.google.common.annotations.GwtCompatible

/**
 * 代表一個類型可能會與 Google Web Toolkit 一塊兒使用.
 * 若是一個方法使用這個註釋,說明這個方法的返回值是 GWT 兼容的
 *
 */
@Retention(RetentionPolicy.CLASS)
@Target({ ElementType.TYPE, ElementType.METHOD })
@Documented
@GwtCompatible
public @interface GwtCompatible {

    /**
     * 說明一個類型或者方法的返回值是否支持 GWT 序列化
     *
     */
    boolean serializable() default false;

    /**
     * 說明一個類型是否在 GWT 被模擬.
     * 被模擬的源(父源)和JVM的實現不同
     *
     */
    boolean emulated() default false;
}

 

com.google.common.annotations.GwtIncompatible

/**
 * 說明一個方法可能沒法與 GWT 一塊兒使用
 * 他只能用於被 @GwtCompatible 標誌的類的字段,方法和內部類
 *
 */
@Retention(RetentionPolicy.CLASS)
@Target({
        ElementType.TYPE, ElementType.METHOD,
        ElementType.CONSTRUCTOR, ElementType.FIELD })
@Documented
@GwtCompatible
public @interface GwtIncompatible {
    /**
     * 用於表示不兼容 GWT 的緣由
     * 
     */
    String value();
}

 

 

com.google.common.base.Charsets

/**
 * 定義了一些字符編碼常量
 *
 */
@GwtCompatible(emulated = true)
public final class Charsets {
    private Charsets() {}

    /**
     * US-ASCII: seven-bit ASCII, the Basic Latin block of the Unicode character set (ISO646-US).
     */
    @GwtIncompatible("Non-UTF-8 Charset")
    public static final Charset US_ASCII = Charset.forName("US-ASCII");

    /**
     * ISO-8859-1: ISO Latin Alphabet Number 1 (ISO-LATIN-1).
     */
    @GwtIncompatible("Non-UTF-8 Charset")
    public static final Charset ISO_8859_1 = Charset.forName("ISO-8859-1");

    /**
     * UTF-8: eight-bit UCS Transformation Format.
     */
    public static final Charset UTF_8 = Charset.forName("UTF-8");

    /**
     * UTF-16BE: sixteen-bit UCS Transformation Format, big-endian byte order.
     */
    @GwtIncompatible("Non-UTF-8 Charset")
    public static final Charset UTF_16BE = Charset.forName("UTF-16BE");

    /**
     * UTF-16LE: sixteen-bit UCS Transformation Format, little-endian byte order.
     */
    @GwtIncompatible("Non-UTF-8 Charset")
    public static final Charset UTF_16LE = Charset.forName("UTF-16LE");

    /**
     * UTF-16: sixteen-bit UCS Transformation Format, byte order identified by an optional byte-order
     * mark.
     */
    @GwtIncompatible("Non-UTF-8 Charset")
    public static final Charset UTF_16 = Charset.forName("UTF-16");

  /*
   * Please do not add new Charset references to this class, unless those character encodings are
   * part of the set required to be supported by all Java platform implementations! Any Charsets
   * initialized here may cause unexpected delays when this class is loaded. See the Charset
   * Javadocs for the list of built-in character encodings.
   */
}

 

 

com.google.common.hash.HashCode

/**
 * 任意長度的不可變 HashCode*/
@Beta
public abstract class HashCode {
    HashCode() {}

    /**
     * 返回 hashCode 的前4個字節並以小端形式存儲
     * 他的實現有Byte, Int, Long轉化爲Int的形式
     * 實現方式很簡單,Byte轉Int的小端的方法:
     * 1) 先對hashCode前4個字節分別與0xFF(1111 1111)作&,目的是固定每一個字節的code長度吧
     * 2) 將各個字節作<<運算,使得hashCode以低位字節開頭,轉爲小端
     * 3) 將各個字節作|,合成最後的int返回
     * 而Int, Long轉Int都是直接返回原值
     */
    public abstract int asInt();

    /**
     * 實現方法同asInt
     */
    public abstract long asLong();

    /**
     * 返回hashCode的Byte數組形式,以小端方式返回
     * 實現方法是對hashCode作>>運算後將低位字節強制轉型爲byte
     */
    public abstract byte[] asBytes();

    /**
     * 將hashCode寫入指定的byte[]數組
     * 寫入位置從目標byte[]的offset開始
     * 寫入長度爲maxLength
     */
    public int writeBytesTo(byte[] dest, int offset, int maxLength) {
        byte[] hash = asBytes();
        maxLength = Ints.min(maxLength, hash.length);
        Preconditions.checkPositionIndexes(offset, offset + maxLength, dest.length);
        System.arraycopy(hash, 0, dest, offset, maxLength);
        return maxLength;
    }

    /**
     * 返回hashCode的位數長度
     */
    public abstract int bits();

    /**
     * 使用hashCode的字節數組形式來比較兩個HashCode是否相等
     */
    @Override public boolean equals(Object object) {
        if (object instanceof HashCode) {
            HashCode that = (HashCode) object;
            // Undocumented: this is a non-short-circuiting equals(), in case this is a cryptographic
            // hash code, in which case we don't want to leak timing information
            return MessageDigest.isEqual(this.asBytes(), that.asBytes());
        }
        return false;
    }

    /**
     * Returns a "Java hash code" for this {@code HashCode} instance; this is well-defined
     * (so, for example, you can safely put {@code HashCode} instances into a {@code
     * HashSet}) but is otherwise probably not what you want to use.
     */
    @Override public int hashCode() {
    /*
     * As long as the hash function that produced this isn't of horrible quality, this
     * won't be of horrible quality either.
     */
        return asInt();
    }

    /**
     * 將hashCode按照byte[](小端)的形式轉爲16進制數字符串
     * 其中每一個byte轉爲兩個16進制數,這個byte按照大端存儲,而整個字符串仍是按照小端存儲
     */
    @Override public String toString() {
        byte[] bytes = asBytes();
        // TODO(user): Use c.g.common.base.ByteArrays once it is open sourced.
        StringBuilder sb = new StringBuilder(2 * bytes.length);
        for (byte b : bytes) {
            sb.append(hexDigits[(b >> 4) & 0xf]).append(hexDigits[b & 0xf]);
        }
        return sb.toString();
    }

    private static final char[] hexDigits = "0123456789abcdef".toCharArray();
}