diff --git a/src/net/micode/notes/gtask/data/MetaData.java b/src/net/micode/notes/gtask/data/MetaData.java index 3a2050b..b8f9fad 100644 --- a/src/net/micode/notes/gtask/data/MetaData.java +++ b/src/net/micode/notes/gtask/data/MetaData.java @@ -24,7 +24,15 @@ import net.micode.notes.tool.GTaskStringUtils; import org.json.JSONException; import org.json.JSONObject; - +/** + * MetaData 类用于表示与 Google Tasks 同步相关的元数据信息。 + * 它继承自 Task 类，并封装了与任务同步相关的 GID（Google 任务 ID）信息。 + * + * 主要职责包括： + * - 存储与 Google Task 关联的 GID + * - 提供将元数据转换为 JSON 格式并保存到笔记内容的方法 + * - 从远程 JSON 数据中解析出 GID 并保存到本地 + */ public class MetaData extends Task { private final static String TAG = MetaData.class.getSimpleName(); diff --git a/src/net/micode/notes/gtask/remote/GTaskASyncTask.java b/src/net/micode/notes/gtask/remote/GTaskASyncTask.java index b3b61e7..076b716 100644 --- a/src/net/micode/notes/gtask/remote/GTaskASyncTask.java +++ b/src/net/micode/notes/gtask/remote/GTaskASyncTask.java @@ -28,7 +28,16 @@ import net.micode.notes.R; import net.micode.notes.ui.NotesListActivity; import net.micode.notes.ui.NotesPreferenceActivity; - +/** + * GTaskASyncTask 是一个继承自 AsyncTask 的异步任务类， + * 用于在后台执行与 Google Tasks 的同步操作，并提供进度更新和完成回调。 + * + * 主要职责包括： + * - 启动 Google Tasks 同步流程 + * - 显示同步状态通知（如登录中、同步成功/失败等） + * - 处理同步过程中的进度更新 + * - 在同步完成后通过接口回调通知调用者 + */ public class GTaskASyncTask extends AsyncTask { private static int GTASK_SYNC_NOTIFICATION_ID = 5234235; diff --git a/src/net/micode/notes/gtask/remote/GTaskClient.java b/src/net/micode/notes/gtask/remote/GTaskClient.java index c67dfdf..76ecdbe 100644 --- a/src/net/micode/notes/gtask/remote/GTaskClient.java +++ b/src/net/micode/notes/gtask/remote/GTaskClient.java @@ -60,7 +60,16 @@ import java.util.zip.GZIPInputStream; import java.util.zip.Inflater; import java.util.zip.InflaterInputStream; - +/** + * GTaskClient 是用于与 Google Tasks 远程服务进行交互的核心类。 + * 它封装了与 Google Tasks API 的 HTTP 请求通信逻辑，包括登录认证、任务创建、更新、删除、移动等操作。 + * + * 主要职责包括： + * - 登录 Google 账户并获取授权 Token + * - 与 Google Tasks 服务端进行 HTTP 请求交互（GET/POST） + * - 发送任务相关的 JSON 请求并解析响应 + * - 提供同步操作支持，如创建、更新、删除任务和任务列表 + */ public class GTaskClient { private static final String TAG = GTaskClient.class.getSimpleName(); diff --git a/src/net/micode/notes/gtask/remote/GTaskManager.java b/src/net/micode/notes/gtask/remote/GTaskManager.java index d2b4082..203c112 100644 --- a/src/net/micode/notes/gtask/remote/GTaskManager.java +++ b/src/net/micode/notes/gtask/remote/GTaskManager.java @@ -48,17 +48,36 @@ import java.util.Iterator; import java.util.Map; +/** + * GTaskManager 类负责管理与 Google 任务（Google Tasks）的同步操作。 + * 它提供了同步本地笔记与远程任务的功能，并处理同步过程中的各种状态和异常。 + */ public class GTaskManager { private static final String TAG = GTaskManager.class.getSimpleName(); + /** + * 同步成功状态码 + */ public static final int STATE_SUCCESS = 0; + /** + * 网络错误状态码 + */ public static final int STATE_NETWORK_ERROR = 1; + /** + * 内部错误状态码 + */ public static final int STATE_INTERNAL_ERROR = 2; + /** + * 同步进行中状态码 + */ public static final int STATE_SYNC_IN_PROGRESS = 3; + /** + * 同步取消状态码 + */ public static final int STATE_SYNC_CANCELLED = 4; private static GTaskManager mInstance = null; @@ -87,6 +106,9 @@ public class GTaskManager { private HashMap mNidToGid; + /** + * 私有构造函数，初始化同步状态和相关数据结构。 + */ private GTaskManager() { mSyncing = false; mCancelled = false; @@ -99,6 +121,10 @@ public class GTaskManager { mNidToGid = new HashMap(); } + /** + * 获取 GTaskManager 的单例实例。 + * @return GTaskManager 的单例实例 + */ public static synchronized GTaskManager getInstance() { if (mInstance == null) { mInstance = new GTaskManager(); @@ -106,11 +132,20 @@ public class GTaskManager { return mInstance; } + /** + * 设置当前活动的上下文，用于获取认证令牌。 + * @param activity 当前活动 + */ public synchronized void setActivityContext(Activity activity) { - // used for getting authtoken mActivity = activity; } + /** + * 执行同步操作，处理本地笔记与 Google 任务的双向同步。 + * @param context 上下文 + * @param asyncTask 异步任务对象 + * @return 同步结果状态码 + */ public int sync(Context context, GTaskASyncTask asyncTask) { if (mSyncing) { Log.d(TAG, "Sync is in progress"); @@ -168,6 +203,10 @@ public class GTaskManager { return mCancelled ? STATE_SYNC_CANCELLED : STATE_SUCCESS; } + /** + * 初始化 Google 任务列表，从服务器获取任务列表并建立元数据列表。 + * @throws NetworkFailureException 网络异常 + */ private void initGTaskList() throws NetworkFailureException { if (mCancelled) return; @@ -247,6 +286,10 @@ public class GTaskManager { } } + /** + * 核心同步方法，处理本地数据库与 Google 任务的双向同步。 + * @throws NetworkFailureException 网络异常 + */ private void syncContent() throws NetworkFailureException { int syncType; Cursor c = null; @@ -351,6 +394,10 @@ public class GTaskManager { } + /** + * 文件夹同步方法，处理根文件夹和特殊文件夹的同步逻辑。 + * @throws NetworkFailureException 网络异常 + */ private void syncFolder() throws NetworkFailureException { Cursor c = null; String gid; @@ -476,6 +523,13 @@ public class GTaskManager { GTaskClient.getInstance().commitUpdate(); } + /** + * 执行具体的同步操作。 + * @param syncType 同步类型（定义在 Node 中的 SYNC_ACTION 常量） + * @param node 对应的 Google 任务节点 + * @param c 本地数据库游标 + * @throws NetworkFailureException 网络异常 + */ private void doContentSync(int syncType, Node node, Cursor c) throws NetworkFailureException { if (mCancelled) { return; @@ -522,6 +576,11 @@ public class GTaskManager { } } + /** + * 在本地添加节点。 + * @param node 要添加的节点 + * @throws NetworkFailureException 网络异常 + */ private void addLocalNode(Node node) throws NetworkFailureException { if (mCancelled) { return; @@ -596,6 +655,12 @@ public class GTaskManager { updateRemoteMeta(node.getGid(), sqlNote); } + /** + * 在本地更新节点。 + * @param node 要更新的节点 + * @param c 本地数据库游标 + * @throws NetworkFailureException 网络异常 + */ private void updateLocalNode(Node node, Cursor c) throws NetworkFailureException { if (mCancelled) { return; @@ -619,6 +684,12 @@ public class GTaskManager { updateRemoteMeta(node.getGid(), sqlNote); } + /** + * 在远程添加节点。 + * @param node 要添加的节点 + * @param c 本地数据库游标 + * @throws NetworkFailureException 网络异常 + */ private void addRemoteNode(Node node, Cursor c) throws NetworkFailureException { if (mCancelled) { return; @@ -692,6 +763,12 @@ public class GTaskManager { mNidToGid.put(sqlNote.getId(), n.getGid()); } + /** + * 在远程更新节点。 + * @param node 要更新的节点 + * @param c 本地数据库游标 + * @throws NetworkFailureException 网络异常 + */ private void updateRemoteNode(Node node, Cursor c) throws NetworkFailureException { if (mCancelled) { return; @@ -730,6 +807,12 @@ public class GTaskManager { sqlNote.commit(true); } + /** + * 更新远程元数据。 + * @param gid Google 任务 ID + * @param sqlNote 对应的本地笔记对象 + * @throws NetworkFailureException 网络异常 + */ private void updateRemoteMeta(String gid, SqlNote sqlNote) throws NetworkFailureException { if (sqlNote != null && sqlNote.isNoteType()) { MetaData metaData = mMetaHashMap.get(gid); @@ -746,6 +829,10 @@ public class GTaskManager { } } + /** + * 刷新本地同步 ID，确保本地与远程的同步状态一致。 + * @throws NetworkFailureException 网络异常 + */ private void refreshLocalSyncId() throws NetworkFailureException { if (mCancelled) { return; @@ -790,10 +877,17 @@ public class GTaskManager { } } + /** + * 获取当前同步账户的名称。 + * @return 同步账户名称 + */ public String getSyncAccount() { return GTaskClient.getInstance().getSyncAccount().name; } + /** + * 取消当前同步操作。 + */ public void cancelSync() { mCancelled = true; } diff --git a/src/net/micode/notes/gtask/remote/GTaskSyncService.java b/src/net/micode/notes/gtask/remote/GTaskSyncService.java index cca36f7..edb096e 100644 --- a/src/net/micode/notes/gtask/remote/GTaskSyncService.java +++ b/src/net/micode/notes/gtask/remote/GTaskSyncService.java @@ -23,6 +23,16 @@ import android.content.Intent; import android.os.Bundle; import android.os.IBinder; +/** + * GTaskSyncService 是一个 Android Service，用于在后台执行 Google Tasks 同步任务。 + * 它封装了同步任务的启动、取消、进度广播等逻辑，并通过 Intent 与 Activity 通信。 + * + * 主要职责包括： + * - 管理 GTaskASyncTask 异步任务（启动/取消） + * - 提供静态接口供外部调用启动或取消同步 + * - 在同步过程中发送广播更新 UI 进度 + * - 在系统低内存时自动取消同步 + */ public class GTaskSyncService extends Service { public final static String ACTION_STRING_NAME = "sync_action_type";