添加注释

src/Notes-master/app/src/main/java/net/micode/notes/gtask/remote/GTaskClient.java

@@ -61,35 +61,47 @@ import java.util.zip.Inflater;
 import java.util.zip.InflaterInputStream;
 
 
+/**
+ * Google Tasks(GTask)客户端类，用于与Google Tasks服务进行交互
+ * 提供任务和任务列表的创建、更新、删除、查询等功能
+ * 采用单例模式确保全局唯一实例
+ */
 public class GTaskClient {
     private static final String TAG = GTaskClient.class.getSimpleName();
 
+    // Google Tasks服务的基本URL
     private static final String GTASK_URL = "https://mail.google.com/tasks/";
-
+    // 获取数据的URL
     private static final String GTASK_GET_URL = "https://mail.google.com/tasks/ig";
-
+    // 提交数据的URL
     private static final String GTASK_POST_URL = "https://mail.google.com/tasks/r/ig";
 
+    // 单例实例
     private static GTaskClient mInstance = null;
 
+    // HTTP客户端，用于发送请求和接收响应
     private DefaultHttpClient mHttpClient;
-
+    // 获取数据的实际URL（可能根据账户类型调整）
     private String mGetUrl;
-
+    // 提交数据的实际URL（可能根据账户类型调整）
     private String mPostUrl;
-
+    // 客户端版本号，用于与服务器交互
     private long mClientVersion;
-
+    // 登录状态标记
     private boolean mLoggedin;
-
+    // 上次登录时间，用于判断是否需要重新登录
     private long mLastLoginTime;
-
+    // 操作ID生成器，确保每个操作有唯一标识
     private int mActionId;
-
+    // 当前同步的Google账户
     private Account mAccount;
-
+    // 更新操作数组，用于批量提交更新
     private JSONArray mUpdateArray;
 
+    /**
+     * 私有构造函数，初始化客户端状态
+     * 单例模式下不允许外部直接创建实例
+     */
     private GTaskClient() {
         mHttpClient = null;
         mGetUrl = GTASK_GET_URL;
@@ -102,6 +114,10 @@ public class GTaskClient {
         mUpdateArray = null;
     }
 
+    /**
+     * 获取GTaskClient单例实例
+     * @return GTaskClient实例
+     */
     public static synchronized GTaskClient getInstance() {
         if (mInstance == null) {
             mInstance = new GTaskClient();
@@ -109,15 +125,20 @@ public class GTaskClient {
         return mInstance;
     }
 
+    /**
+     * 登录Google账户并认证GTask服务
+     * 处理账户切换和登录过期情况
+     * @param activity 用于获取账户信息的Activity
+     * @return 登录是否成功
+     */
     public boolean login(Activity activity) {
-        // we suppose that the cookie would expire after 5 minutes
+        // 登录凭证有效期为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))) {
@@ -136,7 +157,7 @@ public class GTaskClient {
             return false;
         }
 
-        // login with custom domain if necessary
+        // 处理自定义域名账户（非gmail.com/googlemail.com）
         if (!(mAccount.name.toLowerCase().endsWith("gmail.com") || mAccount.name.toLowerCase()
                 .endsWith("googlemail.com"))) {
             StringBuilder url = new StringBuilder(GTASK_URL).append("a/");
@@ -151,7 +172,7 @@ public class GTaskClient {
             }
         }
 
-        // try to login with google official url
+        // 尝试使用Google官方URL登录
         if (!mLoggedin) {
             mGetUrl = GTASK_GET_URL;
             mPostUrl = GTASK_POST_URL;
@@ -164,6 +185,12 @@ public class GTaskClient {
         return true;
     }
 
+    /**
+     * 登录Google账户获取认证令牌
+     * @param activity 用于获取账户信息的Activity
+     * @param invalidateToken 是否失效现有令牌
+     * @return 认证令牌，失败时返回null
+     */
     private String loginGoogleAccount(Activity activity, boolean invalidateToken) {
         String authToken;
         AccountManager accountManager = AccountManager.get(activity);
@@ -174,6 +201,7 @@ public class GTaskClient {
             return null;
         }
 
+        // 获取设置中选择的同步账户
         String accountName = NotesPreferenceActivity.getSyncAccountName(activity);
         Account account = null;
         for (Account a : accounts) {
@@ -189,13 +217,14 @@ public class GTaskClient {
             return null;
         }
 
-        // get the token now
+        // 获取Google账户认证令牌
         AccountManagerFuture<Bundle> accountManagerFuture = accountManager.getAuthToken(account,
                 "goanna_mobile", null, activity, null, null);
         try {
             Bundle authTokenBundle = accountManagerFuture.getResult();
             authToken = authTokenBundle.getString(AccountManager.KEY_AUTHTOKEN);
             if (invalidateToken) {
+                // 失效现有令牌并重新获取
                 accountManager.invalidateAuthToken("com.google", authToken);
                 loginGoogleAccount(activity, false);
             }
@@ -207,10 +236,16 @@ public class GTaskClient {
         return authToken;
     }
 
+    /**
+     * 尝试使用认证令牌登录GTask服务
+     * 处理令牌失效情况
+     * @param activity 用于重新获取令牌的Activity
+     * @param authToken 认证令牌
+     * @return 登录是否成功
+     */
     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");
@@ -225,10 +260,16 @@ public class GTaskClient {
         return true;
     }
 
+    /**
+     * 使用认证令牌登录GTask服务
+     * @param authToken Google账户认证令牌
+     * @return 登录是否成功
+     */
     private boolean loginGtask(String authToken) {
         int timeoutConnection = 10000;
         int timeoutSocket = 15000;
         HttpParams httpParameters = new BasicHttpParams();
+        // 设置连接超时和Socket超时时间
         HttpConnectionParams.setConnectionTimeout(httpParameters, timeoutConnection);
         HttpConnectionParams.setSoTimeout(httpParameters, timeoutSocket);
         mHttpClient = new DefaultHttpClient(httpParameters);
@@ -236,14 +277,13 @@ public class GTaskClient {
         mHttpClient.setCookieStore(localBasicCookieStore);
         HttpProtocolParams.setUseExpectContinue(mHttpClient.getParams(), false);
 
-        // login gtask
         try {
+            // 构建登录URL
             String loginUrl = mGetUrl + "?auth=" + authToken;
             HttpGet httpGet = new HttpGet(loginUrl);
-            HttpResponse response = null;
+            HttpResponse response = mHttpClient.execute(httpGet);
-            response = mHttpClient.execute(httpGet);
 
-            // get the cookie now
+            // 检查是否获取到认证Cookie
             List<Cookie> cookies = mHttpClient.getCookieStore().getCookies();
             boolean hasAuthCookie = false;
             for (Cookie cookie : cookies) {
@@ -255,7 +295,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 +312,6 @@ public class GTaskClient {
             e.printStackTrace();
             return false;
         } catch (Exception e) {
-            // simply catch all exceptions
             Log.e(TAG, "httpget gtask_url failed");
             return false;
         }
@@ -280,10 +319,19 @@ public class GTaskClient {
         return true;
     }
 
+    /**
+     * 生成唯一操作ID
+     * @return 递增的操作ID
+     */
     private int getActionId() {
         return mActionId++;
     }
 
+    /**
+     * 创建HTTP POST请求
+     * 设置请求头信息
+     * @return 配置好的HttpPost对象
+     */
     private HttpPost createHttpPost() {
         HttpPost httpPost = new HttpPost(mPostUrl);
         httpPost.setHeader("Content-Type", "application/x-www-form-urlencoded;charset=utf-8");
@@ -291,6 +339,13 @@ public class GTaskClient {
         return httpPost;
     }
 
+    /**
+     * 从HTTP实体中获取响应内容
+     * 处理Gzip和Deflate压缩格式
+     * @param entity HTTP响应实体
+     * @return 响应内容字符串
+     * @throws IOException 读取内容时发生的IO异常
+     */
     private String getResponseContent(HttpEntity entity) throws IOException {
         String contentEncoding = null;
         if (entity.getContentEncoding() != null) {
@@ -299,9 +354,12 @@ public class GTaskClient {
         }
 
         InputStream input = entity.getContent();
+        // 处理Gzip压缩响应
         if (contentEncoding != null && contentEncoding.equalsIgnoreCase("gzip")) {
             input = new GZIPInputStream(entity.getContent());
-        } else if (contentEncoding != null && contentEncoding.equalsIgnoreCase("deflate")) {
+        } 
+        // 处理Deflate压缩响应
+        else if (contentEncoding != null && contentEncoding.equalsIgnoreCase("deflate")) {
             Inflater inflater = new Inflater(true);
             input = new InflaterInputStream(entity.getContent(), inflater);
         }
@@ -311,18 +369,22 @@ public class GTaskClient {
             BufferedReader br = new BufferedReader(isr);
             StringBuilder sb = new StringBuilder();
 
-            while (true) {
+            String buff;
-                String buff = br.readLine();
+            while ((buff = br.readLine()) != null) {
-                if (buff == null) {
+                sb.append(buff);
-                    return sb.toString();
-                }
-                sb = sb.append(buff);
             }
+            return sb.toString();
         } finally {
             input.close();
         }
     }
 
+    /**
+     * 发送POST请求并处理响应
+     * @param js 请求的JSON数据
+     * @return 响应的JSON对象
+     * @throws NetworkFailureException 网络错误时抛出
+     */
     private JSONObject postRequest(JSONObject js) throws NetworkFailureException {
         if (!mLoggedin) {
             Log.e(TAG, "please login first");
@@ -331,12 +393,13 @@ public class GTaskClient {
 
         HttpPost httpPost = createHttpPost();
         try {
+            // 构建请求参数
             LinkedList<BasicNameValuePair> list = new LinkedList<BasicNameValuePair>();
             list.add(new BasicNameValuePair("r", js.toString()));
             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 +423,29 @@ 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
+            // 发送请求并处理响应
             JSONObject jsResponse = postRequest(jsPost);
             JSONObject jsResult = (JSONObject) jsResponse.getJSONArray(
                     GTaskStringUtils.GTASK_JSON_RESULTS).get(0);
+            // 从响应中获取服务器生成的任务ID
             task.setGid(jsResult.getString(GTaskStringUtils.GTASK_JSON_NEW_ID));
 
         } catch (JSONException e) {
@@ -386,23 +455,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
+            // 发送请求并处理响应
             JSONObject jsResponse = postRequest(jsPost);
             JSONObject jsResult = (JSONObject) jsResponse.getJSONArray(
                     GTaskStringUtils.GTASK_JSON_RESULTS).get(0);
+            // 从响应中获取服务器生成的任务列表ID
             tasklist.setGid(jsResult.getString(GTaskStringUtils.GTASK_JSON_NEW_ID));
 
         } catch (JSONException e) {
@@ -412,15 +487,19 @@ 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);
 
                 postRequest(jsPost);
@@ -433,20 +512,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 +546,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
+                // 在不同任务列表间移动时，设置目标列表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,18 +576,23 @@ 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);
@@ -509,6 +604,11 @@ public class GTaskClient {
         }
     }
 
+    /**
+     * 获取所有任务列表
+     * @return 任务列表的JSON数组
+     * @throws NetworkFailureException 网络错误时抛出
+     */
     public JSONArray getTaskLists() throws NetworkFailureException {
         if (!mLoggedin) {
             Log.e(TAG, "please login first");
@@ -516,11 +616,11 @@ public class GTaskClient {
         }
 
         try {
+            // 发送GET请求获取任务列表
             HttpGet httpGet = new HttpGet(mGetUrl);
-            HttpResponse response = null;
+            HttpResponse response = mHttpClient.execute(httpGet);
-            response = mHttpClient.execute(httpGet);
 
-            // get the task list
+            // 解析响应获取任务列表数据
             String resString = getResponseContent(response.getEntity());
             String jsBegin = "_setup(";
             String jsEnd = ")}</script>";
@@ -547,6 +647,12 @@ public class GTaskClient {
         }
     }
 
+    /**
+     * 获取指定任务列表中的所有任务
+     * @param listGid 任务列表的Google ID
+     * @return 任务的JSON数组
+     * @throws NetworkFailureException 网络错误时抛出
+     */
     public JSONArray getTaskList(String listGid) throws NetworkFailureException {
         commitUpdate();
         try {
@@ -554,7 +660,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 +669,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,11 +681,19 @@ public class GTaskClient {
         }
     }
 
+    /**
+     * 获取当前同步的Google账户
+     * @return 同步账户对象
+     */
     public Account getSyncAccount() {
         return mAccount;
     }
 
+    /**
+     * 重置更新操作数组
+     * 清空待提交的更新操作
+     */
     public void resetUpdateArray() {
         mUpdateArray = null;
     }
-}
+}