注释1

src/net/micode/notes/data/Contact.java

@@ -24,50 +24,75 @@ import android.telephony.PhoneNumberUtils;
 import android.util.Log;
 
 import java.util.HashMap;
-
+/**
+ * 一个用于管理联系人信息的工具类。
+ * 主要功能是通过电话号码查询对应的联系人姓名，并缓存查询结果以提高性能。
+ */
 public class Contact {
-    private static HashMap<String, String> sContactCache;
-    private static final String TAG = "Contact";
-
-    private static final String CALLER_ID_SELECTION = "PHONE_NUMBERS_EQUAL(" + Phone.NUMBER
-    + ",?) AND " + Data.MIMETYPE + "='" + Phone.CONTENT_ITEM_TYPE + "'"
-    + " AND " + Data.RAW_CONTACT_ID + " IN "
-            + "(SELECT raw_contact_id "
-            + " FROM phone_lookup"
-            + " WHERE min_match = '+')";
-
-    public static String getContact(Context context, String phoneNumber) {
-        if(sContactCache == null) {
-            sContactCache = new HashMap<String, String>();
-        }
-
-        if(sContactCache.containsKey(phoneNumber)) {
-            return sContactCache.get(phoneNumber);
-        }
-
-        String selection = CALLER_ID_SELECTION.replace("+",
-                PhoneNumberUtils.toCallerIDMinMatch(phoneNumber));
-        Cursor cursor = context.getContentResolver().query(
-                Data.CONTENT_URI,
-                new String [] { Phone.DISPLAY_NAME },
-                selection,
-                new String[] { phoneNumber },
-                null);
+     // 静态缓存，用于存储电话号码与联系人姓名的映射关系
+     private static HashMap<String, String> sContactCache;
 
-        if (cursor != null && cursor.moveToFirst()) {
-            try {
-                String name = cursor.getString(0);
-                sContactCache.put(phoneNumber, name);
-                return name;
-            } catch (IndexOutOfBoundsException e) {
-                Log.e(TAG, " Cursor get string error " + e.toString());
-                return null;
-            } finally {
-                cursor.close();
-            }
-        } else {
-            Log.d(TAG, "No contact matched with number:" + phoneNumber);
-            return null;
-        }
-    }
-}
+     // 日志标签，用于调试和错误日志输出
+     private static final String TAG = "Contact";
+ 
+     // SQL 查询条件字符串，用于匹配指定电话号码的联系人信息
+     private static final String CALLER_ID_SELECTION = "PHONE_NUMBERS_EQUAL(" + Phone.NUMBER
+             + ",?) AND " + Data.MIMETYPE + "='" + Phone.CONTENT_ITEM_TYPE + "'"
+             + " AND " + Data.RAW_CONTACT_ID + " IN "
+             + "(SELECT raw_contact_id "
+             + " FROM phone_lookup"
+             + " WHERE min_match = '+')";
+ 
+     /**
+      * 根据电话号码获取对应的联系人姓名。
+      *
+      * @param context       应用程序上下文
+      * @param phoneNumber   要查询的电话号码
+      * @return              如果找到匹配的联系人，则返回其姓名；否则返回 null
+      */
+     public static String getContact(Context context, String phoneNumber) {
+         // 如果缓存为空，初始化缓存
+         if (sContactCache == null) {
+             sContactCache = new HashMap<String, String>();
+         }
+ 
+         // 检查缓存中是否已存在该电话号码的联系人信息
+         if (sContactCache.containsKey(phoneNumber)) {
+             return sContactCache.get(phoneNumber);
+         }
+ 
+         // 构造查询条件，将电话号码替换为匹配格式
+         String selection = CALLER_ID_SELECTION.replace("+",
+                 PhoneNumberUtils.toCallerIDMinMatch(phoneNumber));
+ 
+         // 执行数据库查询，查询与电话号码匹配的联系人姓名
+         Cursor cursor = context.getContentResolver().query(
+                 Data.CONTENT_URI,
+                 new String[]{Phone.DISPLAY_NAME},
+                 selection,
+                 new String[]{phoneNumber},
+                 null);
+ 
+         // 如果查询结果不为空且有数据
+         if (cursor != null && cursor.moveToFirst()) {
+             try {
+                 // 获取查询结果中的联系人姓名
+                 String name = cursor.getString(0);
+                 // 将电话号码与联系人姓名存入缓存
+                 sContactCache.put(phoneNumber, name);
+                 return name;
+             } catch (IndexOutOfBoundsException e) {
+                 // 如果发生索引越界异常，记录错误日志并返回 null
+                 Log.e(TAG, "Cursor get string error " + e.toString());
+                 return null;
+             } finally {
+                 // 关闭游标以释放资源
+                 cursor.close();
+             }
+         } else {
+             // 如果没有找到匹配的联系人，记录调试日志并返回 null
+             Log.d(TAG, "No contact matched with number:" + phoneNumber);
+             return null;
+         }
+     }
+ }