v2.1

java/net/micode/notes/gtask/remote/GTaskClient.java

@@ -1,4 +1,4 @@
-/*
+ /*
  * Copyright (c) 2010-2011, The MiCode Open Source Community (www.micode.net)
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -61,15 +61,18 @@ import java.util.zip.Inflater;
 import java.util.zip.InflaterInputStream;
 
 
+/**
+ * GTaskClient 类负责与 Google Tasks API 进行通信，
+ * 处理 HTTP 请求、JSON 解析和认证令牌管理，
+ * 是 Google 任务同步功能的核心网络交互层。
+ */
 public class GTaskClient {
     private static final String TAG = GTaskClient.class.getSimpleName();
-
     private static final String GTASK_URL = "https://mail.google.com/tasks/";
-
     private static final String GTASK_GET_URL = "https://mail.google.com/tasks/ig";
-
     private static final String GTASK_POST_URL = "https://mail.google.com/tasks/r/ig";
 
+
     private static GTaskClient mInstance = null;
 
     private DefaultHttpClient mHttpClient;
@@ -90,6 +93,9 @@ public class GTaskClient {
 
     private JSONArray mUpdateArray;
 
+    /**
+     * 私有构造函数，确保该类只能通过单例模式创建实例
+     */
     private GTaskClient() {
         mHttpClient = null;
         mGetUrl = GTASK_GET_URL;
@@ -102,6 +108,11 @@ public class GTaskClient {
         mUpdateArray = null;
     }
 
+    /**
+     * 获取 GTaskClient 的单例实例
+     *
+     * @return GTaskClient 的单例实例
+     */
     public static synchronized GTaskClient getInstance() {
         if (mInstance == null) {
             mInstance = new GTaskClient();
@@ -109,34 +120,42 @@ public class GTaskClient {
         return mInstance;
     }
 
+    /**
+     * 用户登录 Google Tasks 服务
+     *
+     * @param activity 当前活动实例，用于获取账户管理器和认证令牌
+     * @return 登录成功返回 true，失败返回 false
+     */
     public boolean login(Activity activity) {
-        // we suppose that the cookie would expire after 5 minutes
+        // 假设 cookie 有效期为 5 分钟，超过该时间需要重新登录
-        // then we need to re-login
         final long interval = 1000 * 60 * 5;
         if (mLastLoginTime + interval < System.currentTimeMillis()) {
             mLoggedin = false;
         }
 
-        // need to re-login after account switch
+        // 如果用户切换了账户，需要重新登录
         if (mLoggedin
                 && !TextUtils.equals(getSyncAccount().name, NotesPreferenceActivity
                         .getSyncAccountName(activity))) {
             mLoggedin = false;
         }
 
+        // 如果已经登录，直接返回 true
         if (mLoggedin) {
             Log.d(TAG, "already logged in");
             return true;
         }
 
+        // 更新最后登录时间
         mLastLoginTime = System.currentTimeMillis();
+        // 登录 Google 账户并获取认证令牌
         String authToken = loginGoogleAccount(activity, false);
         if (authToken == null) {
             Log.e(TAG, "login google account failed");
             return false;
         }
 
-        // login with custom domain if necessary
+        //  如果使用的是自定义域名的 Google 账户，需要特殊处理登录 URL
         if (!(mAccount.name.toLowerCase().endsWith("gmail.com") || mAccount.name.toLowerCase()
                 .endsWith("googlemail.com"))) {
             StringBuilder url = new StringBuilder(GTASK_URL).append("a/");
@@ -151,7 +170,7 @@ public class GTaskClient {
             }
         }
 
-        // try to login with google official url
+        //尝试使用自定义域名 URL 登录 Google Tasks
         if (!mLoggedin) {
             mGetUrl = GTASK_GET_URL;
             mPostUrl = GTASK_POST_URL;
@@ -164,18 +183,28 @@ public class GTaskClient {
         return true;
     }
 
+    /**
+     * 登录 Google 账户并获取认证令牌
+     *
+     * @param activity        当前活动实例，用于获取账户管理器
+     * @param invalidateToken 是否使现有认证令牌失效
+     * @return 认证令牌，如果获取失败则返回 null
+     */
     private String loginGoogleAccount(Activity activity, boolean invalidateToken) {
         String authToken;
         AccountManager accountManager = AccountManager.get(activity);
         Account[] accounts = accountManager.getAccountsByType("com.google");
 
+        // 如果没有可用的 Google 账户，返回 null
         if (accounts.length == 0) {
             Log.e(TAG, "there is no available google account");
             return null;
         }
 
+        // 获取用户设置的同步账户名
         String accountName = NotesPreferenceActivity.getSyncAccountName(activity);
         Account account = null;
+        // 遍历所有账户，找到与设置中相同名称的账户
         for (Account a : accounts) {
             if (a.name.equals(accountName)) {
                 account = a;
@@ -189,7 +218,7 @@ public class GTaskClient {
             return null;
         }
 
-        // get the token now
+        // 获取认证令牌
         AccountManagerFuture<Bundle> accountManagerFuture = accountManager.getAuthToken(account,
                 "goanna_mobile", null, activity, null, null);
         try {
@@ -197,6 +226,7 @@ public class GTaskClient {
             authToken = authTokenBundle.getString(AccountManager.KEY_AUTHTOKEN);
             if (invalidateToken) {
                 accountManager.invalidateAuthToken("com.google", authToken);
+                // 使现有令牌失效后，重新获取令牌
                 loginGoogleAccount(activity, false);
             }
         } catch (Exception e) {
@@ -207,16 +237,23 @@ public class GTaskClient {
         return authToken;
     }
 
+    /**
+     * 尝试登录 Google Tasks 服务
+     *
+     * @param activity  当前活动实例，用于重新获取认证令牌
+     * @param authToken 认证令牌
+     * @return 登录成功返回 true，失败返回 false
+     */
     private boolean tryToLoginGtask(Activity activity, String authToken) {
         if (!loginGtask(authToken)) {
-            // maybe the auth token is out of date, now let's invalidate the
+            //如果登录失败，可能是认证令牌过期，使令牌失效并重新获取
-            // token and try again
             authToken = loginGoogleAccount(activity, true);
             if (authToken == null) {
                 Log.e(TAG, "login google account failed");
                 return false;
             }
 
+            // 再次尝试登录 Google Tasks
             if (!loginGtask(authToken)) {
                 Log.e(TAG, "login gtask failed");
                 return false;
@@ -225,25 +262,32 @@ public class GTaskClient {
         return true;
     }
 
+    /**
+     * 使用认证令牌登录 Google Tasks 服务
+     *
+     * @param authToken 认证令牌
+     * @return 登录成功返回 true，失败返回 false
+     */
     private boolean loginGtask(String authToken) {
         int timeoutConnection = 10000;
         int timeoutSocket = 15000;
         HttpParams httpParameters = new BasicHttpParams();
         HttpConnectionParams.setConnectionTimeout(httpParameters, timeoutConnection);
         HttpConnectionParams.setSoTimeout(httpParameters, timeoutSocket);
+        // 创建一个新的 HttpClient 实例
         mHttpClient = new DefaultHttpClient(httpParameters);
         BasicCookieStore localBasicCookieStore = new BasicCookieStore();
         mHttpClient.setCookieStore(localBasicCookieStore);
         HttpProtocolParams.setUseExpectContinue(mHttpClient.getParams(), false);
 
-        // login gtask
+        //  尝试登录 Google Tasks
         try {
             String loginUrl = mGetUrl + "?auth=" + authToken;
             HttpGet httpGet = new HttpGet(loginUrl);
             HttpResponse response = null;
             response = mHttpClient.execute(httpGet);
 
-            // get the cookie now
+            // 获取 cookie 信息
             List<Cookie> cookies = mHttpClient.getCookieStore().getCookies();
             boolean hasAuthCookie = false;
             for (Cookie cookie : cookies) {
@@ -255,7 +299,7 @@ public class GTaskClient {
                 Log.w(TAG, "it seems that there is no auth cookie");
             }
 
-            // get the client version
+            // 解析响应内容，获取客户端版本号
             String resString = getResponseContent(response.getEntity());
             String jsBegin = "_setup(";
             String jsEnd = ")}</script>";
@@ -272,7 +316,7 @@ public class GTaskClient {
             e.printStackTrace();
             return false;
         } catch (Exception e) {
-            // simply catch all exceptions
+            //  捕获所有异常，记录错误日志并返回 false
             Log.e(TAG, "httpget gtask_url failed");
             return false;
         }
@@ -280,10 +324,18 @@ public class GTaskClient {
         return true;
     }
 
+    /**
+      获取下一个操作 ID
+      @return 操作 ID
+     **/
     private int getActionId() {
         return mActionId++;
     }
 
+    /**
+      创建一个 HttpPost 请求对象
+      @return HttpPost 请求对象
+     **/
     private HttpPost createHttpPost() {
         HttpPost httpPost = new HttpPost(mPostUrl);
         httpPost.setHeader("Content-Type", "application/x-www-form-urlencoded;charset=utf-8");
@@ -291,6 +343,12 @@ public class GTaskClient {
         return httpPost;
     }
 
+    /**
+      从 HTTP 响应实体中获取响应内容
+      @param entity HTTP 响应实体
+      @return 响应内容的字符串表示
+      @throws IOException 读取响应内容时可能抛出的异常
+     */
     private String getResponseContent(HttpEntity entity) throws IOException {
         String contentEncoding = null;
         if (entity.getContentEncoding() != null) {
@@ -299,6 +357,7 @@ public class GTaskClient {
         }
 
         InputStream input = entity.getContent();
+        // 如果响应内容使用 gzip 压缩，使用 GZIPInputStream 进行解压缩
         if (contentEncoding != null && contentEncoding.equalsIgnoreCase("gzip")) {
             input = new GZIPInputStream(entity.getContent());
         } else if (contentEncoding != null && contentEncoding.equalsIgnoreCase("deflate")) {
@@ -323,6 +382,12 @@ public class GTaskClient {
         }
     }
 
+    /**
+      发送 POST 请求并返回响应的 JSON 对象
+      @param js 要发送的 JSON 请求对象
+      @return 响应的 JSON 对象
+     @throws NetworkFailureException 网络请求失败时抛出的异常
+     */
     private JSONObject postRequest(JSONObject js) throws NetworkFailureException {
         if (!mLoggedin) {
             Log.e(TAG, "please login first");
@@ -336,7 +401,7 @@ public class GTaskClient {
             UrlEncodedFormEntity entity = new UrlEncodedFormEntity(list, "UTF-8");
             httpPost.setEntity(entity);
 
-            // execute the post
+            // 执行 POST 请求
             HttpResponse response = mHttpClient.execute(httpPost);
             String jsString = getResponseContent(response.getEntity());
             return new JSONObject(jsString);
@@ -360,23 +425,30 @@ public class GTaskClient {
         }
     }
 
+    /**
+      创建一个新的任务
+      @param task 要创建的任务对象
+      @throws NetworkFailureException 网络请求失败时抛出的异常
+     */
     public void createTask(Task task) throws NetworkFailureException {
+        // 提交之前的更新操作
         commitUpdate();
         try {
             JSONObject jsPost = new JSONObject();
             JSONArray actionList = new JSONArray();
 
-            // action_list
+            //添加创建任务的操作到操作列表
             actionList.put(task.getCreateAction(getActionId()));
             jsPost.put(GTaskStringUtils.GTASK_JSON_ACTION_LIST, actionList);
 
-            // client_version
+            // 设置客户端版本号
             jsPost.put(GTaskStringUtils.GTASK_JSON_CLIENT_VERSION, mClientVersion);
 
-            // post
+            //发送 POST 请求
             JSONObject jsResponse = postRequest(jsPost);
             JSONObject jsResult = (JSONObject) jsResponse.getJSONArray(
                     GTaskStringUtils.GTASK_JSON_RESULTS).get(0);
+            // 设置任务的 Google ID
             task.setGid(jsResult.getString(GTaskStringUtils.GTASK_JSON_NEW_ID));
 
         } catch (JSONException e) {
@@ -386,23 +458,29 @@ public class GTaskClient {
         }
     }
 
+    /**
+      创建一个新的任务列表
+      @param tasklist 要创建的任务列表对象
+      @throws NetworkFailureException 网络请求失败时抛出的异常
+     */
     public void createTaskList(TaskList tasklist) throws NetworkFailureException {
         commitUpdate();
         try {
             JSONObject jsPost = new JSONObject();
             JSONArray actionList = new JSONArray();
 
-            // action_list
+            // 添加创建任务列表的操作到操作列表
             actionList.put(tasklist.getCreateAction(getActionId()));
             jsPost.put(GTaskStringUtils.GTASK_JSON_ACTION_LIST, actionList);
 
-            // client version
+            // 设置客户端版本号
             jsPost.put(GTaskStringUtils.GTASK_JSON_CLIENT_VERSION, mClientVersion);
 
-            // post
+            //发送 POST 请求
             JSONObject jsResponse = postRequest(jsPost);
             JSONObject jsResult = (JSONObject) jsResponse.getJSONArray(
                     GTaskStringUtils.GTASK_JSON_RESULTS).get(0);
+            // 设置任务列表的 Google ID
             tasklist.setGid(jsResult.getString(GTaskStringUtils.GTASK_JSON_NEW_ID));
 
         } catch (JSONException e) {
@@ -412,17 +490,22 @@ public class GTaskClient {
         }
     }
 
+    /**
+      提交更新操作
+      @throws NetworkFailureException 网络请求失败时抛出的异常
+     */
     public void commitUpdate() throws NetworkFailureException {
         if (mUpdateArray != null) {
             try {
                 JSONObject jsPost = new JSONObject();
 
-                // action_list
+                //  添加更新操作列表到请求对象
                 jsPost.put(GTaskStringUtils.GTASK_JSON_ACTION_LIST, mUpdateArray);
 
-                // client_version
+                // 设置客户端版本号
                 jsPost.put(GTaskStringUtils.GTASK_JSON_CLIENT_VERSION, mClientVersion);
 
+                // 发送 POST 请求
                 postRequest(jsPost);
                 mUpdateArray = null;
             } catch (JSONException e) {
@@ -433,20 +516,32 @@ public class GTaskClient {
         }
     }
 
+    /**
+     * 添加一个更新节点到更新数组中
+     * @param node 要更新的节点对象
+     * @throws NetworkFailureException 网络请求失败时抛出的异常
+     */
     public void addUpdateNode(Node node) throws NetworkFailureException {
         if (node != null) {
-            // too many update items may result in an error
+            //如果更新数组中的操作数量超过 10 个，先提交更新操作
-            // set max to 10 items
             if (mUpdateArray != null && mUpdateArray.length() > 10) {
                 commitUpdate();
             }
 
             if (mUpdateArray == null)
                 mUpdateArray = new JSONArray();
+            // 将节点的更新操作添加到更新数组中
             mUpdateArray.put(node.getUpdateAction(getActionId()));
         }
     }
 
+    /**
+     * 移动一个任务到另一个任务列表中
+     * @param task     要移动的任务对象
+     * @param preParent 任务原来所在的任务列表
+     * @param curParent 任务要移动到的任务列表
+     * @throws NetworkFailureException 网络请求失败时抛出的异常
+     */
     public void moveTask(Task task, TaskList preParent, TaskList curParent)
             throws NetworkFailureException {
         commitUpdate();
@@ -455,26 +550,25 @@ public class GTaskClient {
             JSONArray actionList = new JSONArray();
             JSONObject action = new JSONObject();
 
-            // action_list
+            // 设置操作类型为移动任务
             action.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
                     GTaskStringUtils.GTASK_JSON_ACTION_TYPE_MOVE);
             action.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, getActionId());
             action.put(GTaskStringUtils.GTASK_JSON_ID, task.getGid());
             if (preParent == curParent && task.getPriorSibling() != null) {
-                // put prioring_sibing_id only if moving within the tasklist and
+                // 如果在同一个任务列表中移动且不是第一个任务，设置前置兄弟任务的 ID
-                // it is not the first one
                 action.put(GTaskStringUtils.GTASK_JSON_PRIOR_SIBLING_ID, task.getPriorSibling());
             }
             action.put(GTaskStringUtils.GTASK_JSON_SOURCE_LIST, preParent.getGid());
             action.put(GTaskStringUtils.GTASK_JSON_DEST_PARENT, curParent.getGid());
             if (preParent != curParent) {
-                // put the dest_list only if moving between tasklists
+                // 如果在不同的任务列表中移动，设置目标任务列表的 Google ID
                 action.put(GTaskStringUtils.GTASK_JSON_DEST_LIST, curParent.getGid());
             }
             actionList.put(action);
             jsPost.put(GTaskStringUtils.GTASK_JSON_ACTION_LIST, actionList);
 
-            // client_version
+            // 设置客户端版本号
             jsPost.put(GTaskStringUtils.GTASK_JSON_CLIENT_VERSION, mClientVersion);
 
             postRequest(jsPost);
@@ -486,21 +580,28 @@ public class GTaskClient {
         }
     }
 
+    /**
+     * 删除一个节点（任务或任务列表）
+     * @param node 要删除的节点对象
+     * @throws NetworkFailureException 网络请求失败时抛出的异常
+     */
     public void deleteNode(Node node) throws NetworkFailureException {
         commitUpdate();
         try {
             JSONObject jsPost = new JSONObject();
             JSONArray actionList = new JSONArray();
 
-            // action_list
+            // 标记节点为已删除
             node.setDeleted(true);
+            // 添加节点的更新操作到操作列表
             actionList.put(node.getUpdateAction(getActionId()));
             jsPost.put(GTaskStringUtils.GTASK_JSON_ACTION_LIST, actionList);
 
-            // client_version
+            // 设置客户端版本号
             jsPost.put(GTaskStringUtils.GTASK_JSON_CLIENT_VERSION, mClientVersion);
 
             postRequest(jsPost);
+            //清空更新数组
             mUpdateArray = null;
         } catch (JSONException e) {
             Log.e(TAG, e.toString());
@@ -509,6 +610,11 @@ public class GTaskClient {
         }
     }
 
+    /**
+     * 获取所有任务列表
+     * @return 包含所有任务列表信息的 JSON 数组
+     * @throws NetworkFailureException 网络请求失败时抛出的异常
+     */
     public JSONArray getTaskLists() throws NetworkFailureException {
         if (!mLoggedin) {
             Log.e(TAG, "please login first");
@@ -520,7 +626,7 @@ public class GTaskClient {
             HttpResponse response = null;
             response = mHttpClient.execute(httpGet);
 
-            // get the task list
+            //获取响应内容
             String resString = getResponseContent(response.getEntity());
             String jsBegin = "_setup(";
             String jsEnd = ")}</script>";
@@ -531,6 +637,7 @@ public class GTaskClient {
                 jsString = resString.substring(begin + jsBegin.length(), end);
             }
             JSONObject js = new JSONObject(jsString);
+            // 从响应中提取任务列表信息
             return js.getJSONObject("t").getJSONArray(GTaskStringUtils.GTASK_JSON_LISTS);
         } catch (ClientProtocolException e) {
             Log.e(TAG, e.toString());
@@ -547,6 +654,12 @@ public class GTaskClient {
         }
     }
 
+    /**
+     * 获取指定任务列表中的所有任务
+     * @param listGid 任务列表的 Google ID
+     * @return 包含指定任务列表中所有任务信息的 JSON 数组
+     * @throws NetworkFailureException 网络请求失败时抛出的异常
+     */
     public JSONArray getTaskList(String listGid) throws NetworkFailureException {
         commitUpdate();
         try {
@@ -554,7 +667,7 @@ public class GTaskClient {
             JSONArray actionList = new JSONArray();
             JSONObject action = new JSONObject();
 
-            // action_list
+            // 设置操作类型为获取所有任务
             action.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
                     GTaskStringUtils.GTASK_JSON_ACTION_TYPE_GETALL);
             action.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, getActionId());
@@ -563,7 +676,7 @@ public class GTaskClient {
             actionList.put(action);
             jsPost.put(GTaskStringUtils.GTASK_JSON_ACTION_LIST, actionList);
 
-            // client_version
+            //设置客户端版本号
             jsPost.put(GTaskStringUtils.GTASK_JSON_CLIENT_VERSION, mClientVersion);
 
             JSONObject jsResponse = postRequest(jsPost);
@@ -575,10 +688,15 @@ public class GTaskClient {
         }
     }
 
+    /**
+      获取当前同步的 Google 账户
+      @return 当前同步的 Google 账户对象
+     */
     public Account getSyncAccount() {
         return mAccount;
     }
 
+//    重置更新数组
     public void resetUpdateArray() {
         mUpdateArray = null;
     }