基础支持层——缓存模块

public interface Cache {

  /**
   * 返回该缓存对应的id
   * @return The identifier of this cache
   */
  String getId();

  /**
   * 向缓存中添加数据，一般情况下Key是CacheKey，value是查询结果
   * @param key Can be any object but usually it is a {@link CacheKey}
   * @param value The result of a select.
   */
  void putObject(Object key, Object value);

  /**
   * 从缓存中获取数据
   * @param key The key
   * @return The object stored in the cache.
   */
  Object getObject(Object key);

  /**
   * 删除Key对应的缓存
   * As of 3.3.0 this method is only called during a rollback 
   * for any previous value that was missing in the cache.
   * This lets any blocking cache to release the lock that 
   * may have previously put on the key.
   * A blocking cache puts a lock when a value is null 
   * and releases it when the value is back again.
   * This way other threads will wait for the value to be 
   * available instead of hitting the database.
   *
   * 
   * @param key The key
   * @return Not used
   */
  Object removeObject(Object key);

  /**
   * 清空缓存
   * Clears this cache instance
   */  
  void clear();

  /**
   * 缓存项的个数，不会被MyBatis核心代码调用
   * Optional. This method is not called by the core.
   * 
   * @return The number of elements stored in the cache (not its capacity).
   */
  int getSize();

  /** 
   * 获取读写锁，不会被MyBatis核心代码调用
   * Optional. As of 3.2.6 this method is no longer called by the core.
   *  
   * Any locking needed by the cache must be provided internally by the cache provider.
   * 
   * @return A ReadWriteLock 
   */
  ReadWriteLock getReadWriteLock();

}

public class PerpetualCache implements Cache {

  private final String id;

  private Map<Object, Object> cache = new HashMap<Object, Object>();

  public PerpetualCache(String id) {
    this.id = id;
  }

  @Override
  public String getId() {
    return id;
  }

  @Override
  public int getSize() {
    return cache.size();
  }

  @Override
  public void putObject(Object key, Object value) {
    cache.put(key, value);
  }

  @Override
  public Object getObject(Object key) {
    return cache.get(key);
  }

  @Override
  public Object removeObject(Object key) {
    return cache.remove(key);
  }

  @Override
  public void clear() {
    cache.clear();
  }

  @Override
  public ReadWriteLock getReadWriteLock() {
    return null;
  }

  @Override
  public boolean equals(Object o) {
    if (getId() == null) {
      throw new CacheException("Cache instances require an ID.");
    }
    if (this == o) {
      return true;
    }
    if (!(o instanceof Cache)) {
      return false;
    }

    Cache otherCache = (Cache) o;
    return getId().equals(otherCache.getId());
  }

  @Override
  public int hashCode() {
    if (getId() == null) {
      throw new CacheException("Cache instances require an ID.");
    }
    return getId().hashCode();
  }

}

// 阻塞超时时间
private long timeout;
// 被装饰的底层Cache对象
private final Cache delegate;
// 每个Key都有对应的ReentrantLock对象
private final ConcurrentHashMap<Object, ReentrantLock> locks;

public Object getObject(Object key) {
  // 获取key对应的锁
  acquireLock(key);
  Object value = delegate.getObject(key);
  if (value != null) {
    // 如果缓存有key对应的缓存项，则释放锁	
    releaseLock(key);
  }        
  return value;
}

private void acquireLock(Object key) {
  // 获取ReentrantLock对象
  Lock lock = getLockForKey(key);
  if (timeout > 0) {
    try {
      // 获取锁，带超时时间的那种
      boolean acquired = lock.tryLock(timeout, TimeUnit.MILLISECONDS);
      if (!acquired) {
        // 如果超时，则抛出异常
        throw new CacheException("...");  
      }
    } catch (InterruptedException e) {
      throw new CacheException("...");
    }
  } else {
    lock.lock();
  }
}

private ReentrantLock getLockForKey(Object key) {
  ReentrantLock lock = new ReentrantLock(); // 创建ReentrantLock对象
  // 试添加到locks集合中，如果locks集合中已经有了相应的ReentrantLock对象，则使用locks集合
  // 中的ReentrantLock对象
  ReentrantLock previous = locks.putIfAbsent(key, lock);
  return previous == null ? lock : previous;
}

@Override
public void putObject(Object key, Object value) {
  try {
    // 向缓存中添加缓存项
    delegate.putObject(key, value);
  } finally {
    releaseLock(key);// 释放锁
  }
}

private void releaseLock(Object key) {
  ReentrantLock lock = locks.get(key);
  if (lock.isHeldByCurrentThread()) { // 判断锁是否被当前线程持有
    // 释放锁
    lock.unlock();
  }
}

// 被装饰的底层Cache对象
private final Cache delegate;
// 用于记录key进入缓存的先后顺序，使用的是LinkedList<Object>类型的几个对象	
private final Deque<Object> keyList;
// 记录缓存项的上限，如果超过，则清理最老的缓存
private int size;

public void putObject(Object key, Object value) {
  // 检测并清理缓存
  cycleKeyList(key);
  // 添加缓存项
  delegate.putObject(key, value);
}

private void cycleKeyList(Object key) {
  // 记录key
  keyList.addLast(key);
  if (keyList.size() > size) { // 如果达到缓存上限，则清理最老的缓存项
    Object oldestKey = keyList.removeFirst();
    delegate.removeObject(oldestKey);
  }
}

// 被装饰的底层Cache对象
private final Cache delegate;
// LinkedHashMap<Object,Object>类型对象，它是一个有序的HashMap，用于记录key最近的使用情况
private Map<Object, Object> keyMap;
// 记录最少被使用的缓存项的key
private Object eldestKey;

public void setSize(final int size) {
  // 重新设置缓存大小的时候， 会充值keyMap字段
  // LinkedHashMap构造函数的第三个参数，true表示该LinkedHashMap记录的顺序是
  // access-order,也就是说LinkedHashMap.get()方法会改变其记录的顺序
  keyMap = new LinkedHashMap<Object, Object>(size, .75F, true) {
    private static final long serialVersionUID = 4267176411845948333L;

    // 当调用LinkedHashMap.put()方法时，会调用该方法
    @Override
    protected boolean removeEldestEntry(Map.Entry<Object, Object> eldest) {
      boolean tooBig = size() > size;
      if (tooBig) {
        // 如果已到达缓存上限，则更新eldestKey字段，后面会删除该项
        eldestKey = eldest.getKey();
      }
      return tooBig;
    }
  };
}

@Override
public void putObject(Object key, Object value) {
  // 修改LinkedHashMap中记录的顺序
  delegate.putObject(key, value);
  cycleKeyList(key);
}

@Override
public Object getObject(Object key) {
  keyMap.get(key); //touch
  // 删除最久未使用的缓存项
  return delegate.getObject(key);
}

private void cycleKeyList(Object key) {
  keyMap.put(key, key);
  if (eldestKey != null) { // eldestKey不为空，即缓存已达到上限
    // 删除最久未使用的缓存
    delegate.removeObject(eldestKey);
    eldestKey = null;
  }
}

// ReferenceQueue，引用队列，用于记录已经被GC回收的缓存项所对应的SoftEntry对象
private final Deque<Object> hardLinksToAvoidGarbageCollection;
// 在SoftCache中，最近使用的一部分缓存项不会被GC回收，这就是通过将其value添加到
// hardLinksToAvoidGarbageCollection集合中实现的(即有强引用指向其value)
// hardLinksToAvoidGarbageCollection集合是LinkedList<Object>类型
private final ReferenceQueue<Object> queueOfGarbageCollectedEntries;
// 底层被装饰的底层Cache对象
private final Cache delegate;
// 强连接的个数，默认值是256
private int numberOfHardLinks;

private static class SoftEntry extends SoftReference<Object> {
  private final Object key;

  SoftEntry(Object key, Object value, ReferenceQueue<Object> garbageCollectionQueue) {
    super(value, garbageCollectionQueue); // 指向value的引用是软引用，且关联了引用队列
    this.key = key; // 强引用
  }
}

public void putObject(Object key, Object value) {
  // 清除已被GC回收的缓存项
  removeGarbageCollectedItems();
  // 向缓存中添加缓存项
  delegate.putObject(key, new SoftEntry(key, value, queueOfGarbageCollectedEntries));
}

private void removeGarbageCollectedItems() {
  SoftEntry sv;
  // 遍历queueOfGarbageCollectedEntries集合
  while ((sv = (SoftEntry) queueOfGarbageCollectedEntries.poll()) != null) {
    // 将已经被GC回收的value对象对应的缓存项清除
    delegate.removeObject(sv.key);
  }
}

public Object getObject(Object key) {
  Object result = null;
  @SuppressWarnings("unchecked") // assumed delegate cache is totally managed by this cache
  // 从缓存中查找对应的缓存项
  SoftReference<Object> softReference = (SoftReference<Object>) delegate.getObject(key);
  if (softReference != null) { // 检测缓存中是否有对应的缓存项
    result = softReference.get(); // 获取SoftReference引用的value
    if (result == null) {// 已经被GC回收
      delegate.removeObject(key); // 从缓存中清除对应的缓存项
    } else { // 未被GC回收
      // See #586 (and #335) modifications need more than a read lock 
      synchronized (hardLinksToAvoidGarbageCollection) {
        // 缓存项的value添加到hardLinksToAvoidGarbageCollection集合中保存
        hardLinksToAvoidGarbageCollection.addFirst(result);
        if (hardLinksToAvoidGarbageCollection.size() > numberOfHardLinks) {
          // 超过numberOfHardLinks，则将最老的缓存项从hardLinksToAvoidGarbageCollection集合中清除，有点类似于先进先出队列
          hardLinksToAvoidGarbageCollection.removeLast();
        }
      }
    }
  }
  return result;
}

public void clear() {
  synchronized (hardLinksToAvoidGarbageCollection) {
    hardLinksToAvoidGarbageCollection.clear(); // 清理强引用集合
  }
  removeGarbageCollectedItems(); // 清理被GC回收的缓存项
  delegate.clear(); // 清理底层delegate缓存中的缓存项
}

// 参与计算hashcode，默认值37
private final int multiplier;
// CacheKey的hashcode，初始值是37
private int hashcode;
// 校验和
private long checksum;
// updateList集合的个数
private int count;
// 由该集合中的所有对象共同决定两个CacheKey是否相同
private List<Object> updateList;

public void update(Object object) {
  int baseHashCode = object == null ? 1 : ArrayUtil.hashCode(object); 
  // 重新计算count、checksum和hashcode的值
  count++;
  checksum += baseHashCode;
  baseHashCode *= count;

  hashcode = multiplier * hashcode + baseHashCode;
	// 将object添加到updateList集合中
  updateList.add(object);
}