注释

app/src/main/java/net/micode/notes/gtask/remote/GTaskASyncTask.java

@@ -1,4 +1,3 @@
-
 /*
  * Copyright (c) 2010-2011, The MiCode Open Source Community (www.micode.net)
  *
@@ -29,110 +28,133 @@ import net.micode.notes.ui.NotesListActivity;
 import net.micode.notes.ui.NotesPreferenceActivity;
 
 
+/**
+ * Google Tasks同步异步任务类
+ * 负责在后台执行Google Tasks数据同步操作，并通过通知栏显示同步状态
+ */
 public class GTaskASyncTask extends AsyncTask<Void, String, Integer> {
 
-    private static int GTASK_SYNC_NOTIFICATION_ID = 5234235;
+    private static int GTASK_SYNC_NOTIFICATION_ID = 5234235; // 同步通知的唯一标识
 
+    /**
+     * 同步完成监听器接口
+     * 用于在同步任务完成后回调通知上层应用
+     */
     public interface OnCompleteListener {
         void onComplete();
     }
 
-    private Context mContext;
+    private Context mContext;                             // 上下文对象
-
+    private NotificationManager mNotifiManager;           // 通知管理器
-    private NotificationManager mNotifiManager;
+    private GTaskManager mTaskManager;                    // Google Tasks管理实例
-
+    private OnCompleteListener mOnCompleteListener;       // 同步完成监听器
-    private GTaskManager mTaskManager;
-
-    private OnCompleteListener mOnCompleteListener;
 
+    /**
+     * 构造函数
+     * @param context 上下文对象
+     * @param listener 同步完成监听器
+     */
     public GTaskASyncTask(Context context, OnCompleteListener listener) {
         mContext = context;
         mOnCompleteListener = listener;
-        mNotifiManager = (NotificationManager) mContext
+        mNotifiManager = (NotificationManager) mContext.getSystemService(Context.NOTIFICATION_SERVICE);
-                .getSystemService(Context.NOTIFICATION_SERVICE);
         mTaskManager = GTaskManager.getInstance();
     }
 
+    /**
+     * 取消同步操作
+     */
     public void cancelSync() {
         mTaskManager.cancelSync();
     }
 
+    /**
+     * 发布同步进度消息
+     * @param message 进度提示信息
+     */
     public void publishProgess(String message) {
-        publishProgress(new String[] {
+        publishProgress(new String[] { message });
-            message
-        });
     }
 
-    //private void showNotification(int tickerId, String content) {
+    /**
-    //    Notification notification = new Notification(R.drawable.notification, mContext
+     * 显示同步状态通知
-    //            .getString(tickerId), System.currentTimeMillis());
+     * @param tickerId 通知标题资源ID
-    //notification.defaults = Notification.DEFAULT_LIGHTS;
+     * @param content 通知内容
-    //    notification.flags = Notification.FLAG_AUTO_CANCEL;
+     */
-    //    PendingIntent pendingIntent;
-    //    if (tickerId != R.string.ticker_success) {
-    //        pendingIntent = PendingIntent.getActivity(mContext, 0, new Intent(mContext,
-    //                NotesPreferenceActivity.class), 0);
-
-    //    } else {
-    //        pendingIntent = PendingIntent.getActivity(mContext, 0, new Intent(mContext,
-    //                NotesListActivity.class), 0);
-    //    }
-    //    notification.setLatestEventInfo(mContext, mContext.getString(R.string.app_name), content,
-    //            pendingIntent);
-    //    mNotifiManager.notify(GTASK_SYNC_NOTIFICATION_ID, notification);
-    //}
     private void showNotification(int tickerId, String content) {
         PendingIntent pendingIntent;
+        // 根据同步结果类型设置不同的点击跳转页面
         if (tickerId != R.string.ticker_success) {
-            pendingIntent = PendingIntent.getActivity(mContext, 0, new Intent(mContext,
+            pendingIntent = PendingIntent.getActivity(mContext, 0,
-                    NotesPreferenceActivity.class), PendingIntent.FLAG_IMMUTABLE);
+                    new Intent(mContext, NotesPreferenceActivity.class),
+                    PendingIntent.FLAG_IMMUTABLE);
         } else {
-            pendingIntent = PendingIntent.getActivity(mContext, 0, new Intent(mContext,
+            pendingIntent = PendingIntent.getActivity(mContext, 0,
-                    NotesListActivity.class), PendingIntent.FLAG_IMMUTABLE);
+                    new Intent(mContext, NotesListActivity.class),
+                    PendingIntent.FLAG_IMMUTABLE);
         }
+        // 构建通知对象
         Notification.Builder builder = new Notification.Builder(mContext)
-                .setAutoCancel(true)
+                .setAutoCancel(true)                // 点击后自动取消通知
-                .setContentTitle(mContext.getString(R.string.app_name))
+                .setContentTitle(mContext.getString(R.string.app_name)) // 通知标题
-                .setContentText(content)
+                .setContentText(content)             // 通知内容
-                .setContentIntent(pendingIntent)
+                .setContentIntent(pendingIntent)      // 点击通知后的跳转意图
-                .setWhen(System.currentTimeMillis())
+                .setWhen(System.currentTimeMillis())  // 通知时间
-                .setOngoing(true);
+                .setOngoing(true);                    // 设置为正在进行的通知
-        Notification notification=builder.getNotification();
+        Notification notification = builder.getNotification();
         mNotifiManager.notify(GTASK_SYNC_NOTIFICATION_ID, notification);
     }
 
+    /**
+     * 后台执行同步任务
+     * @param unused 未使用的参数
+     * @return 同步结果状态码（来自GTaskManager）
+     */
     @Override
     protected Integer doInBackground(Void... unused) {
-        publishProgess(mContext.getString(R.string.sync_progress_login, NotesPreferenceActivity
+        // 发布登录进度通知
-                .getSyncAccountName(mContext)));
+        publishProgess(mContext.getString(R.string.sync_progress_login,
+                NotesPreferenceActivity.getSyncAccountName(mContext)));
+        // 调用GTaskManager执行同步操作并返回状态
         return mTaskManager.sync(mContext, this);
     }
 
+    /**
+     * 处理进度更新
+     * @param progress 进度消息数组
+     */
     @Override
     protected void onProgressUpdate(String... progress) {
+        // 显示同步中通知
         showNotification(R.string.ticker_syncing, progress[0]);
+        // 向服务发送广播（如果上下文是GTaskSyncService）
         if (mContext instanceof GTaskSyncService) {
             ((GTaskSyncService) mContext).sendBroadcast(progress[0]);
         }
     }
 
+    /**
+     * 同步任务完成后的处理
+     * @param result 同步结果状态码
+     */
     @Override
     protected void onPostExecute(Integer result) {
+        // 根据不同的同步结果显示对应的通知
         if (result == GTaskManager.STATE_SUCCESS) {
             showNotification(R.string.ticker_success, mContext.getString(
                     R.string.success_sync_account, mTaskManager.getSyncAccount()));
+            // 保存最后同步时间
             NotesPreferenceActivity.setLastSyncTime(mContext, System.currentTimeMillis());
         } else if (result == GTaskManager.STATE_NETWORK_ERROR) {
             showNotification(R.string.ticker_fail, mContext.getString(R.string.error_sync_network));
         } else if (result == GTaskManager.STATE_INTERNAL_ERROR) {
             showNotification(R.string.ticker_fail, mContext.getString(R.string.error_sync_internal));
         } else if (result == GTaskManager.STATE_SYNC_CANCELLED) {
-            showNotification(R.string.ticker_cancel, mContext
+            showNotification(R.string.ticker_cancel, mContext.getString(R.string.error_sync_cancelled));
-                    .getString(R.string.error_sync_cancelled));
         }
+        // 在新线程中回调完成监听器（避免UI线程阻塞）
         if (mOnCompleteListener != null) {
             new Thread(new Runnable() {
-
                 public void run() {
                     mOnCompleteListener.onComplete();
                 }

app/src/main/java/net/micode/notes/gtask/remote/GTaskSyncService.java

@@ -23,54 +23,63 @@ import android.content.Intent;
 import android.os.Bundle;
 import android.os.IBinder;
 
+/**
+ * Google Tasks同步服务
+ * 负责管理Google Tasks的同步操作，支持启动、取消同步，并通过广播通知UI更新
+ */
 public class GTaskSyncService extends Service {
+    // 服务操作类型常量
     public final static String ACTION_STRING_NAME = "sync_action_type";
+    public final static int ACTION_START_SYNC = 0;      // 启动同步
+    public final static int ACTION_CANCEL_SYNC = 1;     // 取消同步
+    public final static int ACTION_INVALID = 2;         // 无效操作
 
-    public final static int ACTION_START_SYNC = 0;
+    // 广播相关常量
-
-    public final static int ACTION_CANCEL_SYNC = 1;
-
-    public final static int ACTION_INVALID = 2;
-
     public final static String GTASK_SERVICE_BROADCAST_NAME = "net.micode.notes.gtask.remote.gtask_sync_service";
-
     public final static String GTASK_SERVICE_BROADCAST_IS_SYNCING = "isSyncing";
-
     public final static String GTASK_SERVICE_BROADCAST_PROGRESS_MSG = "progressMsg";
 
-    private static GTaskASyncTask mSyncTask = null;
+    private static GTaskASyncTask mSyncTask = null;    // 当前同步任务
-
+    private static String mSyncProgress = "";          // 当前同步进度消息
-    private static String mSyncProgress = "";
 
+    /**
+     * 启动同步操作
+     */
     private void startSync() {
         if (mSyncTask == null) {
             mSyncTask = new GTaskASyncTask(this, new GTaskASyncTask.OnCompleteListener() {
+                @Override
                 public void onComplete() {
+                    // 同步完成后清理资源
                     mSyncTask = null;
-                    sendBroadcast("");
+                    sendBroadcast("");  // 发送同步完成广播
-                    stopSelf();
+                    stopSelf();         // 停止服务
                 }
             });
-            sendBroadcast("");
+            sendBroadcast("");          // 发送同步开始广播
-            mSyncTask.execute();
+            mSyncTask.execute();        // 执行同步任务
         }
     }
 
+    /**
+     * 取消同步操作
+     */
     private void cancelSync() {
         if (mSyncTask != null) {
-            mSyncTask.cancelSync();
+            mSyncTask.cancelSync();     // 调用异步任务取消同步
         }
     }
 
     @Override
     public void onCreate() {
-        mSyncTask = null;
+        mSyncTask = null;               // 服务创建时初始化同步任务
     }
 
     @Override
     public int onStartCommand(Intent intent, int flags, int startId) {
         Bundle bundle = intent.getExtras();
         if (bundle != null && bundle.containsKey(ACTION_STRING_NAME)) {
+            // 根据传入的操作类型执行相应操作
             switch (bundle.getInt(ACTION_STRING_NAME, ACTION_INVALID)) {
                 case ACTION_START_SYNC:
                     startSync();
@@ -81,47 +90,71 @@ public class GTaskSyncService extends Service {
                 default:
                     break;
             }
-            return START_STICKY;
+            return START_STICKY;        // 服务被杀死后自动重启
         }
         return super.onStartCommand(intent, flags, startId);
     }
 
     @Override
     public void onLowMemory() {
+        // 系统内存不足时取消同步任务
         if (mSyncTask != null) {
             mSyncTask.cancelSync();
         }
     }
 
+    @Override
     public IBinder onBind(Intent intent) {
-        return null;
+        return null;                    // 不支持绑定
     }
 
+    /**
+     * 发送同步状态广播
+     * @param msg 同步进度消息
+     */
     public void sendBroadcast(String msg) {
         mSyncProgress = msg;
         Intent intent = new Intent(GTASK_SERVICE_BROADCAST_NAME);
         intent.putExtra(GTASK_SERVICE_BROADCAST_IS_SYNCING, mSyncTask != null);
         intent.putExtra(GTASK_SERVICE_BROADCAST_PROGRESS_MSG, msg);
-        sendBroadcast(intent);
+        sendBroadcast(intent);          // 发送包含同步状态的广播
     }
 
+    // ----------------- 静态方法：外部调用入口 -----------------
+
+    /**
+     * 静态方法：启动同步服务
+     * @param activity 调用的Activity上下文
+     */
     public static void startSync(Activity activity) {
         GTaskManager.getInstance().setActivityContext(activity);
         Intent intent = new Intent(activity, GTaskSyncService.class);
         intent.putExtra(GTaskSyncService.ACTION_STRING_NAME, GTaskSyncService.ACTION_START_SYNC);
-        activity.startService(intent);
+        activity.startService(intent);  // 启动服务并传递启动同步的指令
     }
 
+    /**
+     * 静态方法：取消同步服务
+     * @param context 上下文
+     */
     public static void cancelSync(Context context) {
         Intent intent = new Intent(context, GTaskSyncService.class);
         intent.putExtra(GTaskSyncService.ACTION_STRING_NAME, GTaskSyncService.ACTION_CANCEL_SYNC);
-        context.startService(intent);
+        context.startService(intent);   // 启动服务并传递取消同步的指令
     }
 
+    /**
+     * 静态方法：检查是否正在同步
+     * @return 是否正在同步
+     */
     public static boolean isSyncing() {
         return mSyncTask != null;
     }
 
+    /**
+     * 静态方法：获取当前同步进度消息
+     * @return 同步进度消息
+     */
     public static String getProgressString() {
         return mSyncProgress;
     }