新的Javadoc标签@apiNote,@implSpec和@implNote

本文详细介绍了JDK中引入的一些新特性,包括并发地图的实现细节、对象类中有趣的方法注释以及抽象类Clock的实现规范说明。这些内容对于理解JDK内部工作原理及其最新改进具有重要意义。

摘要生成于 C知道 ,由 DeepSeek-R1 满血版支持, 前往体验 >

JDK广泛使用新的标签。一些例子:

  • 并发地图

    • 几个@implSpec定义了默认实现的行为,例如 replaceAll 

    • 有趣的@impl注意 getOrDefault和 forEach 

    • 重复@impl注意在Map中默认实现的抽象方法,记录“本实施方案有意地重新提取Map中提供的不正确的默认值”,例如 替换 

  • 对象使用@apiNote解释为什么看似无用的方法的isNull非空加。 

  • 抽象类Clock在其类注释中使用@implSpec@implNote来区分必须注意的实现以及现有方法的实现方式。 


package com.example.kucun2.entity.data; import android.os.Handler; import android.os.Looper; import android.util.Log; import java.util.ArrayList; import java.util.Collections; import java.util.HashMap; import java.util.List; import java.util.Map; import java.util.concurrent.CopyOnWriteArrayList; import java.util.concurrent.ExecutorService; import java.util.concurrent.Executors; /** 线程安全的异步操作列表 @param 列表元素类型,需继承自 SynchronizableEntity @apiNote 提供异步添加/移除元素功能,支持UI监听器通知 @threadSafe 内部使用 CopyOnWriteArrayList 保证线程安全 */ public class SynchronizedList { private static final String TAG = “SynchronizedList”; // 使用静态线程池提高效率 private static final ExecutorService ASYNC_EXECUTOR = Executors.newFixedThreadPool(4); // 主线程处理器 private final Handler mainHandler = new Handler(Looper.getMainLooper()); // 内部存储(线程安全) private final List internalList = new CopyOnWriteArrayList<>(); // 列表变更监听器 private final List listeners = new ArrayList<>(); private Class type; /** 构造方法 @param type 列表元素类型(用于反射) */ public SynchronizedList(Class type) { this.type = type; } /** 获取列表元素类型 @return 元素类型Class对象 */ public Class getType() { return type; } //================ 监听器接口 ================// /** 列表变更监听器接口 @param 元素类型 / public interface ListChangeListener { /* 元素添加事件 @param item 添加的元素 @param position 添加位置 */ void onItemAdded(T item, int position); /** 元素移除事件 @param item 移除的元素 @param position 移除位置 */ void onItemRemoved(T item, int position); /** 元素更新事件 @param item 更新的元素 @param position 更新位置 */ void onItemUpdated(T item, int position); /** 同步开始事件 @param item 正在同步的元素 */ void onSyncStarted(T item); /** 同步成功事件 @param item 同步成功的元素 */ void onSyncSuccess(T item); /** 同步失败事件 @param item 同步失败的元素 @param error 错误信息 */ void onSyncFailure(T item, String error); /** 列表整体变更事件 */ void onListChanged(); } /** 操作回调接口 @param 元素类型 / public interface OperationCallback { /* 操作成功回调 @param item 操作的元素 */ void onSuccess(T item); /** 操作失败回调 @param item 操作的元素 @param error 错误信息 */ void onFailure(T item, String error); } //================ 监听器管理 ================// /** 添加列表变更监听器 @param listener 要添加的监听器 */ public void addListChangeListener(ListChangeListener listener) { if (listener != null) { listeners.add(listener); } } /** 移除列表变更监听器 @param listener 要移除的监听器 */ public void removeListChangeListener(ListChangeListener listener) { listeners.remove(listener); } /** 通知所有监听器(在主线程执行) @param action 要执行的通知动作 */ private void notifyListeners(Runnable action) { mainHandler.post(() -> { for (ListChangeListener listener : listeners) { action.run(); } }); } //================ 列表合并操作 ================// /** 合并外部列表到当前列表(不触发同步) @param externalList 外部列表集合 @apiNote 根据元素的id属性进行合并: 如果id存在则更新数据 如果id不存在则添加新元素 不会触发任何同步操作 */ public void mergeList(List externalList) { if (externalList == null || externalList.isEmpty()) { return; } // 创建ID映射表用于快速查找 Map<Integer, T> idMap = new HashMap<>(); for (T item : internalList) { idMap.put(item.getId(), item); } // 记录需要通知的变化 List changeNotifications = new ArrayList<>(); for (T externalItem : externalList) { Integer id = externalItem.getId(); if (idMap.containsKey(id)) { // ID存在 - 更新现有元素 T existingItem = idMap.get(id); int position = internalList.indexOf(existingItem); // 更新元素数据(保留原始对象的引用) if (existingItem != null) { existingItem.updateFrom(externalItem); } // 记录更新通知 changeNotifications.add(() -> { for (ListChangeListener listener : listeners) { listener.onItemUpdated(existingItem, position); } }); } else { // ID不存在 - 添加新元素 int position = internalList.size(); internalList.add(externalItem); // 记录添加通知 changeNotifications.add(() -> { for (ListChangeListener listener : listeners) { listener.onItemAdded(externalItem, position); } }); // 添加到ID映射表 idMap.put(id, externalItem); } } // 批量通知变化 if (!changeNotifications.isEmpty()) { notifyListeners(() -> { for (Runnable notification : changeNotifications) { notification.run(); } // 最后通知列表整体变化 for (ListChangeListener listener : listeners) { listener.onListChanged(); } }); } } /** 异步合并外部列表到当前列表 @param externalList 外部列表集合 @apiNote 在后台线程执行合并操作,完成后在主线程通知UI */ public void mergeListAsync(List externalList) { ASYNC_EXECUTOR.execute(() -> mergeList(externalList)); } //================ 异步操作 ================// /** 异步添加元素 @param item 要添加的元素 @param callback 操作结果回调 @implNote 1. 立即添加元素到列表(UI可见) 后台执行同步操作 根据同步结果更新状态 */ public void addAsync(T item, OperationCallback callback) { if (item == null || internalList.contains(item)) return; // 1. 预添加状态(UI可立即显示) int position = internalList.size(); internalList.add(item); // 通知UI元素添加同步开始 notifyListeners(() -> { for (ListChangeListener listener : listeners) { listener.onItemAdded(item, position); listener.onSyncStarted(item); } }); // 2. 后台执行同步 ASYNC_EXECUTOR.execute(() -> { // 使用"create"操作类型进行同步 item.sync(“add”, new SynchronizableEntity.SyncCallback() { @Override public void onSyncSuccess(SynchronizableEntity entity) { // 同步成功,通知监听器 notifyListeners(() -> { for (ListChangeListener listener : listeners) { listener.onSyncSuccess((T) entity); listener.onListChanged(); } }); // 执行成功回调 if (callback != null) callback.onSuccess((T) entity); } @Override public void onSyncFailure(String error) { // 同步失败,回滚列表 internalList.remove(item); // 通知UI元素移除同步失败 notifyListeners(() -> { for (ListChangeListener listener : listeners) { listener.onSyncFailure((T) item, error); listener.onItemRemoved((T) item, position); } }); // 执行失败回调 if (callback != null) callback.onFailure((T) item, error); } }); }); } /** 异步移除元素 @param item 要移除的元素 @param callback 操作结果回调 @implNote 1. 立即从列表移除元素(UI可见) 后台执行同步操作 根据同步结果决定是否回滚 */ public void removeAsync(T item, OperationCallback callback) { if (!internalList.contains(item)) return; // 记录位置用于可能的回滚 int position = internalList.indexOf(item); internalList.remove(item); // 通知UI元素移除同步开始 notifyListeners(() -> { for (ListChangeListener listener : listeners) { listener.onItemRemoved(item, position); listener.onSyncStarted(item); } }); // 后台执行同步 ASYNC_EXECUTOR.execute(() -> { // 使用"delete"操作类型进行同步 item.sync(“delete”, new SynchronizableEntity.SyncCallback() { @Override public void onSyncSuccess(SynchronizableEntity entity) { // 同步成功,通知监听器 notifyListeners(() -> { for (ListChangeListener listener : listeners) { listener.onSyncSuccess((T) entity); } }); // 执行成功回调 if (callback != null) callback.onSuccess((T) entity); } @Override public void onSyncFailure(String error) { // 同步失败,回滚列表 internalList.add(position, item); // 通知UI元素添加回同步失败 notifyListeners(() -> { for (ListChangeListener listener : listeners) { listener.onSyncFailure((T) item, error); listener.onItemAdded(item, position); } }); // 执行失败回调 if (callback != null) callback.onFailure((T) item, error); } }); }); } //================ 列表访问 ================// /** 获取不可修改的列表视图 @return 不可修改的列表视图 @apiNote 用于RecyclerView等UI组件 */ public List getViewList() { return Collections.unmodifiableList(internalList); } /** 获取列表大小 @return 列表元素数量 */ public int size() { return internalList.size(); } /** 获取指定位置的元素 @param index 元素位置 @return 指定位置的元素 @throws IndexOutOfBoundsException 如果索引越界 */ public T get(int index) { return internalList.get(index); } } 确保进入集合的实体类的 state属性都为1(已加入集合,关联实体不用懒加载),新建为0(未加入集合,关联实体要在集合中查找并关联),外界的所有同步都是经过该集合,这个state是为了区分依赖的,一个实体类被api加载新建时关联对象都没有确定关系,只有在该集合中的 数据才算,其他不用管
最新发布
06-29
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值