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();
}