diff --git a/src/Notes-master/src/net/micode/notes/gtask/remote/GTaskASyncTask.java b/src/Notes-master/src/net/micode/notes/gtask/remote/GTaskASyncTask.java index b3b61e7..7669523 100644 --- a/src/Notes-master/src/net/micode/notes/gtask/remote/GTaskASyncTask.java +++ b/src/Notes-master/src/net/micode/notes/gtask/remote/GTaskASyncTask.java @@ -1,18 +1,15 @@ - /* * Copyright (c) 2010-2011, The MiCode Open Source Community (www.micode.net) * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at + * 根据Apache License, Version 2.0（以下简称“许可证”）授权； + * 除非遵守许可证，否则不得使用此文件。 + * 你可以在以下网址获得许可证的副本： * * http://www.apache.org/licenses/LICENSE-2.0 * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. + * 除非适用法律要求或书面同意，否则按“原样”提供软件 + * 在许可证下分发，不附带任何明示或暗示的保证或条件。 + * 请参阅许可证，了解有关权限和限制的具体语言。 */ package net.micode.notes.gtask.remote; @@ -28,23 +25,27 @@ import net.micode.notes.R; import net.micode.notes.ui.NotesListActivity; import net.micode.notes.ui.NotesPreferenceActivity; - +// 异步任务类，用于执行GTask同步操作 public class GTaskASyncTask extends AsyncTask { + // 定义GTASK同步通知的ID private static int GTASK_SYNC_NOTIFICATION_ID = 5234235; + // 定义完成监听接口 public interface OnCompleteListener { void onComplete(); } + // 上下文对象 private Context mContext; - + // 通知管理器 private NotificationManager mNotifiManager; - + // 任务管理器 private GTaskManager mTaskManager; - + // 完成监听器 private OnCompleteListener mOnCompleteListener; + // 构造函数，初始化上下文、通知管理器、任务管理器和完成监听器 public GTaskASyncTask(Context context, OnCompleteListener listener) { mContext = context; mOnCompleteListener = listener; @@ -53,35 +54,42 @@ public class GTaskASyncTask extends AsyncTask { mTaskManager = GTaskManager.getInstance(); } + // 取消同步的方法 public void cancelSync() { mTaskManager.cancelSync(); } + // 发布进度消息的方法 public void publishProgess(String message) { publishProgress(new String[] { - message + message }); } + // 显示通知的方法 private void showNotification(int tickerId, String content) { + // 创建通知对象 Notification notification = new Notification(R.drawable.notification, mContext .getString(tickerId), System.currentTimeMillis()); notification.defaults = Notification.DEFAULT_LIGHTS; notification.flags = Notification.FLAG_AUTO_CANCEL; + // 根据tickerId创建不同的PendingIntent 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); } + // 后台执行同步操作的方法 @Override protected Integer doInBackground(Void... unused) { publishProgess(mContext.getString(R.string.sync_progress_login, NotesPreferenceActivity @@ -89,6 +97,7 @@ public class GTaskASyncTask extends AsyncTask { return mTaskManager.sync(mContext, this); } + // 更新进度的方法 @Override protected void onProgressUpdate(String... progress) { showNotification(R.string.ticker_syncing, progress[0]); @@ -97,8 +106,10 @@ public class GTaskASyncTask extends AsyncTask { } } + // 执行完毕后的方法 @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())); @@ -111,6 +122,7 @@ public class GTaskASyncTask extends AsyncTask { showNotification(R.string.ticker_cancel, mContext .getString(R.string.error_sync_cancelled)); } + // 如果存在完成监听器，则通知监听器任务完成 if (mOnCompleteListener != null) { new Thread(new Runnable() { @@ -120,4 +132,4 @@ public class GTaskASyncTask extends AsyncTask { }).start(); } } -} +} \ No newline at end of file diff --git a/src/Notes-master/src/net/micode/notes/gtask/remote/GTaskClient.java b/src/Notes-master/src/net/micode/notes/gtask/remote/GTaskClient.java index c67dfdf..db1a192 100644 --- a/src/Notes-master/src/net/micode/notes/gtask/remote/GTaskClient.java +++ b/src/Notes-master/src/net/micode/notes/gtask/remote/GTaskClient.java @@ -1,19 +1,3 @@ -/* - * Copyright (c) 2010-2011, The MiCode Open Source Community (www.micode.net) - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - package net.micode.notes.gtask.remote; import android.accounts.Account; @@ -60,36 +44,39 @@ import java.util.zip.GZIPInputStream; import java.util.zip.Inflater; import java.util.zip.InflaterInputStream; - +// GTaskClient类用于与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/"; - + // 用于获取Google Tasks数据的URL private static final String GTASK_GET_URL = "https://mail.google.com/tasks/ig"; - + // 用于向Google Tasks发送POST请求的URL private static final String GTASK_POST_URL = "https://mail.google.com/tasks/r/ig"; private static GTaskClient mInstance = null; + // 用于发送HTTP请求的HttpClient对象 private DefaultHttpClient mHttpClient; - + // 获取数据的具体URL private String mGetUrl; - + // 发送POST请求的具体URL private String mPostUrl; - + // 客户端版本号 private long mClientVersion; - + // 标记是否已登录 private boolean mLoggedin; - + // 上次登录的时间戳 private long mLastLoginTime; - + // 用于标识操作的ID，每次操作自增 private int mActionId; - + // 当前使用的账户 private Account mAccount; - + // 用于暂存更新操作相关数据的JSON数组 private JSONArray mUpdateArray; + // 私有构造函数，初始化相关成员变量 private GTaskClient() { mHttpClient = null; mGetUrl = GTASK_GET_URL; @@ -102,6 +89,7 @@ public class GTaskClient { mUpdateArray = null; } + // 获取GTaskClient的单例实例 public static synchronized GTaskClient getInstance() { if (mInstance == null) { mInstance = new GTaskClient(); @@ -109,15 +97,15 @@ public class GTaskClient { return mInstance; } + // 执行登录操作 public boolean login(Activity activity) { - // we suppose that the cookie would expire after 5 minutes - // then we need to re-login + // 假设Cookie在5分钟后过期，若距离上次登录时间超过5分钟，则需要重新登录 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))) { @@ -130,13 +118,14 @@ public class GTaskClient { } 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 + // 如果账户不是以gmail.com或googlemail.com结尾（可能是自定义域名），则使用自定义域名相关的URL进行登录 if (!(mAccount.name.toLowerCase().endsWith("gmail.com") || mAccount.name.toLowerCase() .endsWith("googlemail.com"))) { StringBuilder url = new StringBuilder(GTASK_URL).append("a/"); @@ -151,7 +140,7 @@ public class GTaskClient { } } - // try to login with google official url + // 如果使用自定义域名登录失败，则尝试使用Google官方URL登录 if (!mLoggedin) { mGetUrl = GTASK_GET_URL; mPostUrl = GTASK_POST_URL; @@ -164,9 +153,12 @@ public class GTaskClient { return true; } + // 登录Google账户获取授权令牌 private String loginGoogleAccount(Activity activity, boolean invalidateToken) { String authToken; + // 获取账户管理器 AccountManager accountManager = AccountManager.get(activity); + // 获取所有Google类型的账户 Account[] accounts = accountManager.getAccountsByType("com.google"); if (accounts.length == 0) { @@ -174,6 +166,7 @@ public class GTaskClient { return null; } + // 获取设置中的同步账户名称 String accountName = NotesPreferenceActivity.getSyncAccountName(activity); Account account = null; for (Account a : accounts) { @@ -189,13 +182,14 @@ public class GTaskClient { return null; } - // get the token now + // 获取授权令牌 AccountManagerFuture 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 +201,10 @@ public class GTaskClient { return authToken; } + // 尝试登录Google Tasks 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 + // 如果登录失败，可能是授权令牌过期，先使令牌失效再重新尝试登录Google账户获取新令牌，然后再次登录Google Tasks authToken = loginGoogleAccount(activity, true); if (authToken == null) { Log.e(TAG, "login google account failed"); @@ -225,9 +219,11 @@ public class GTaskClient { return true; } + // 实际执行登录Google Tasks的操作，获取相关信息（如客户端版本号等） private boolean loginGtask(String authToken) { int timeoutConnection = 10000; int timeoutSocket = 15000; + // 设置HTTP请求的参数，包括连接超时和读取超时时间 HttpParams httpParameters = new BasicHttpParams(); HttpConnectionParams.setConnectionTimeout(httpParameters, timeoutConnection); HttpConnectionParams.setSoTimeout(httpParameters, timeoutSocket); @@ -236,14 +232,14 @@ public class GTaskClient { mHttpClient.setCookieStore(localBasicCookieStore); HttpProtocolParams.setUseExpectContinue(mHttpClient.getParams(), false); - // login gtask + // 登录Google Tasks，发送带有授权令牌的GET请求 try { String loginUrl = mGetUrl + "?auth=" + authToken; HttpGet httpGet = new HttpGet(loginUrl); HttpResponse response = null; response = mHttpClient.execute(httpGet); - // get the cookie now + // 获取登录后的Cookie信息，检查是否包含认证相关的Cookie（名称包含"GTL"） List cookies = mHttpClient.getCookieStore().getCookies(); boolean hasAuthCookie = false; for (Cookie cookie : cookies) { @@ -255,7 +251,7 @@ public class GTaskClient { Log.w(TAG, "it seems that there is no auth cookie"); } - // get the client version + // 从响应中获取客户端版本号等信息，通过解析返回的JavaScript代码中的相关数据 String resString = getResponseContent(response.getEntity()); String jsBegin = "_setup("; String jsEnd = ")}"; @@ -272,7 +268,7 @@ 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 +276,12 @@ public class GTaskClient { return true; } + // 获取下一个操作的ID private int getActionId() { return mActionId++; } + // 创建用于发送POST请求的HttpPost对象，并设置相关请求头 private HttpPost createHttpPost() { HttpPost httpPost = new HttpPost(mPostUrl); httpPost.setHeader("Content-Type", "application/x-www-form-urlencoded;charset=utf-8"); @@ -291,6 +289,7 @@ public class GTaskClient { return httpPost; } + // 从HTTP实体中获取响应内容，根据内容编码（如gzip、deflate等）进行相应的解压处理 private String getResponseContent(HttpEntity entity) throws IOException { String contentEncoding = null; if (entity.getContentEncoding() != null) { @@ -323,6 +322,7 @@ public class GTaskClient { } } + // 发送POST请求，将JSON数据发送到Google Tasks服务器，并处理响应返回的JSON数据 private JSONObject postRequest(JSONObject js) throws NetworkFailureException { if (!mLoggedin) { Log.e(TAG, "please login first"); @@ -336,7 +336,7 @@ public class GTaskClient { UrlEncodedFormEntity entity = new UrlEncodedFormEntity(list, "UTF-8"); httpPost.setEntity(entity); - // execute the post + // 执行POST请求并获取响应，然后解析响应内容为JSONObject返回 HttpResponse response = mHttpClient.execute(httpPost); String jsString = getResponseContent(response.getEntity()); return new JSONObject(jsString); @@ -360,20 +360,21 @@ public class GTaskClient { } } + // 创建一个任务并发送到Google Tasks服务器 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请求并处理响应，获取新创建任务的ID并设置到任务对象中 JSONObject jsResponse = postRequest(jsPost); JSONObject jsResult = (JSONObject) jsResponse.getJSONArray( GTaskStringUtils.GTASK_JSON_RESULTS).get(0); @@ -386,20 +387,21 @@ public class GTaskClient { } } + // 创建一个任务列表并发送到Google Tasks服务器 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请求并处理响应，获取新创建任务列表的ID并设置到任务列表对象中 JSONObject jsResponse = postRequest(jsPost); JSONObject jsResult = (JSONObject) jsResponse.getJSONArray( GTaskStringUtils.GTASK_JSON_RESULTS).get(0); @@ -412,15 +414,16 @@ public class GTaskClient { } } + // 提交更新操作，将暂存的更新操作数组发送到服务器 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 +436,24 @@ public class GTaskClient { } } + // 添加一个节点的更新操作到暂存的更新操作数组中，限制最多10个更新项 + // 将节点的更新操作添加到更新数组中，如果更新数组中的元素超过10个，则先提交更新 public void addUpdateNode(Node node) throws NetworkFailureException { if (node != null) { - // too many update items may result in an error - // set max to 10 items + // 过多的更新项可能会导致错误，所以设置最大更新项数量为10个 if (mUpdateArray != null && mUpdateArray.length() > 10) { commitUpdate(); } + // 如果更新数组为空，则创建一个新的JSONArray对象用于存放更新操作 if (mUpdateArray == null) mUpdateArray = new JSONArray(); + // 将节点的更新操作（通过节点获取，操作ID使用当前的操作ID）添加到更新数组中 mUpdateArray.put(node.getUpdateAction(getActionId())); } } + // 移动任务，将任务从一个任务列表移动到另一个任务列表（可能是同一个列表内移动位置） public void moveTask(Task task, TaskList preParent, TaskList curParent) throws NetworkFailureException { commitUpdate(); @@ -455,60 +462,77 @@ 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); + // 设置操作的唯一ID，通过获取下一个可用的操作ID来赋值 action.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, getActionId()); + // 设置要移动的任务的全局唯一ID action.put(GTaskStringUtils.GTASK_JSON_ID, task.getGid()); + // 如果移动前后的父任务列表相同（即在同一个任务列表内移动），并且任务不是该列表中的第一个任务， + // 则设置其前一个兄弟任务的ID，用于确定移动后的顺序 if (preParent == curParent && task.getPriorSibling() != null) { - // put prioring_sibing_id only if moving within the tasklist and - // it is not the first one action.put(GTaskStringUtils.GTASK_JSON_PRIOR_SIBLING_ID, task.getPriorSibling()); } + // 设置任务原来所在的任务列表的全局唯一ID（源列表） action.put(GTaskStringUtils.GTASK_JSON_SOURCE_LIST, preParent.getGid()); + // 设置任务要移动到的目标任务列表的父级任务列表的全局唯一ID（目标父列表） action.put(GTaskStringUtils.GTASK_JSON_DEST_PARENT, curParent.getGid()); + // 如果移动是在不同的任务列表之间进行，则设置目标任务列表的全局唯一ID（目标列表） if (preParent != curParent) { - // put the dest_list only if moving between tasklists action.put(GTaskStringUtils.GTASK_JSON_DEST_LIST, curParent.getGid()); } + // 将这个移动操作添加到操作列表中 actionList.put(action); + // 将操作列表添加到要发送的JSON数据对象中，对应预定义的操作列表的JSON键 jsPost.put(GTaskStringUtils.GTASK_JSON_ACTION_LIST, actionList); - // client_version + // 设置客户端版本号，对应预定义的客户端版本号的JSON键 jsPost.put(GTaskStringUtils.GTASK_JSON_CLIENT_VERSION, mClientVersion); + // 发送POST请求，将包含移动任务操作信息的JSON数据发送到服务器进行处理 postRequest(jsPost); } catch (JSONException e) { Log.e(TAG, e.toString()); e.printStackTrace(); + // 如果JSON处理出现异常，抛出操作失败异常，并说明是移动任务时处理JSON对象失败 throw new ActionFailureException("move task: handing jsonobject failed"); } } + // 删除节点（比如任务、任务列表等），通过设置节点的删除标记为true，并将其更新操作发送到服务器来实现删除 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())); + // 将操作列表添加到要发送的JSON数据对象中，对应预定义的操作列表的JSON键 jsPost.put(GTaskStringUtils.GTASK_JSON_ACTION_LIST, actionList); - // client_version + // 设置客户端版本号，对应预定义的客户端版本号的JSON键 jsPost.put(GTaskStringUtils.GTASK_JSON_CLIENT_VERSION, mClientVersion); + // 发送POST请求，将包含删除节点操作信息的JSON数据发送到服务器进行处理 postRequest(jsPost); + // 发送成功后，将更新数组置空，因为相关更新操作已提交完成 mUpdateArray = null; } catch (JSONException e) { Log.e(TAG, e.toString()); e.printStackTrace(); + // 如果JSON处理出现异常，抛出操作失败异常，并说明是删除节点时处理JSON对象失败 throw new ActionFailureException("delete node: handing jsonobject failed"); } } + // 获取所有的任务列表信息，前提是已经登录成功，否则会抛出异常提示需要先登录 public JSONArray getTaskLists() throws NetworkFailureException { if (!mLoggedin) { Log.e(TAG, "please login first"); @@ -516,11 +540,13 @@ public class GTaskClient { } try { + // 创建一个HTTP GET请求对象，用于获取任务列表数据，请求的URL是之前设置好的获取数据的URL HttpGet httpGet = new HttpGet(mGetUrl); HttpResponse response = null; + // 执行HTTP GET请求，获取服务器的响应 response = mHttpClient.execute(httpGet); - // get the task list + // 从响应的实体中获取内容，并进行处理，提取出包含任务列表信息的JSON数据部分 String resString = getResponseContent(response.getEntity()); String jsBegin = "_setup("; String jsEnd = ")}"; @@ -531,22 +557,27 @@ public class GTaskClient { jsString = resString.substring(begin + jsBegin.length(), end); } JSONObject js = new JSONObject(jsString); + // 从解析后的JSON对象中获取任务列表数组并返回，对应预定义的任务列表的JSON键 return js.getJSONObject("t").getJSONArray(GTaskStringUtils.GTASK_JSON_LISTS); } catch (ClientProtocolException e) { Log.e(TAG, e.toString()); e.printStackTrace(); + // 如果HTTP协议相关操作出现异常，抛出网络失败异常，并说明是获取任务列表时HTTP GET请求失败 throw new NetworkFailureException("gettasklists: httpget failed"); } catch (IOException e) { Log.e(TAG, e.toString()); e.printStackTrace(); + // 如果输入输出操作出现异常，抛出网络失败异常，并说明是获取任务列表时HTTP GET请求失败 throw new NetworkFailureException("gettasklists: httpget failed"); } catch (JSONException e) { Log.e(TAG, e.toString()); e.printStackTrace(); + // 如果JSON处理出现异常，抛出操作失败异常，并说明是获取任务列表时处理JSON对象失败 throw new ActionFailureException("get task lists: handing jasonobject failed"); } } + // 根据给定的任务列表全局唯一ID，获取该任务列表中的任务信息，需要先提交之前暂存的更新操作 public JSONArray getTaskList(String listGid) throws NetworkFailureException { commitUpdate(); try { @@ -554,32 +585,42 @@ 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); + // 设置操作的唯一ID，通过获取下一个可用的操作ID来赋值 action.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, getActionId()); + // 设置要获取任务的任务列表的全局唯一ID action.put(GTaskStringUtils.GTASK_JSON_LIST_ID, listGid); + // 设置是否获取已删除的任务，这里设置为false，表示不获取已删除任务 action.put(GTaskStringUtils.GTASK_JSON_GET_DELETED, false); + // 将这个获取任务操作添加到操作列表中 actionList.put(action); + // 将操作列表添加到要发送的JSON数据对象中，对应预定义的操作列表的JSON键 jsPost.put(GTaskStringUtils.GTASK_JSON_ACTION_LIST, actionList); - // client_version + // 设置客户端版本号，对应预定义的客户端版本号的JSON键 jsPost.put(GTaskStringUtils.GTASK_JSON_CLIENT_VERSION, mClientVersion); + // 发送POST请求，将包含获取任务列表中任务操作信息的JSON数据发送到服务器进行处理 JSONObject jsResponse = postRequest(jsPost); + // 从服务器响应的JSON数据中获取任务数组并返回，对应预定义的任务的JSON键 return jsResponse.getJSONArray(GTaskStringUtils.GTASK_JSON_TASKS); } catch (JSONException e) { Log.e(TAG, e.toString()); e.printStackTrace(); + // 如果JSON处理出现异常，抛出操作失败异常，并说明是获取任务列表时处理JSON对象失败 throw new ActionFailureException("get task list: handing jsonobject failed"); } } + // 获取当前用于同步的账户信息 public Account getSyncAccount() { return mAccount; } - public void resetUpdateArray() { - mUpdateArray = null; - } -} + // 重置更新数组，即将其置为空，一般用于清除之前暂存的更新操作相关数据 +public void resetUpdateArray() { + mUpdateArray = null; +} \ No newline at end of file diff --git a/src/Notes-master/src/net/micode/notes/gtask/remote/GTaskManager.java b/src/Notes-master/src/net/micode/notes/gtask/remote/GTaskManager.java index d2b4082..0df9b30 100644 --- a/src/Notes-master/src/net/micode/notes/gtask/remote/GTaskManager.java +++ b/src/Notes-master/src/net/micode/notes/gtask/remote/GTaskManager.java @@ -47,46 +47,49 @@ import java.util.HashSet; import java.util.Iterator; import java.util.Map; - +// GTaskManager类用于管理与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; + // 关联的Activity，用于获取授权令牌等操作 private Activity mActivity; - + // 应用上下文 private Context mContext; - + // 用于操作内容提供器，进行数据查询、更新等操作 private ContentResolver mContentResolver; - + // 标记是否正在同步 private boolean mSyncing; - + // 标记同步是否被取消 private boolean mCancelled; - + // 存储Google Tasks任务列表的哈希表，以任务列表的全局唯一ID（GID）为键，任务列表对象为值 private HashMap mGTaskListHashMap; - + // 存储Google Tasks节点（任务、任务列表等）的哈希表，以节点的全局唯一ID（GID）为键，节点对象为值 private HashMap mGTaskHashMap; - + // 存储元数据的哈希表，以相关的全局唯一ID为键，元数据对象为值 private HashMap mMetaHashMap; - + // 元数据对应的任务列表 private TaskList mMetaList; - + // 存储本地已删除记录的ID集合，用于后续清理本地数据 private HashSet mLocalDeleteIdMap; - + // 存储从Google Tasks的全局唯一ID（GID）到本地记录ID（NID）的映射关系 private HashMap mGidToNid; - + // 存储从本地记录ID（NID）到Google Tasks的全局唯一ID（GID）的映射关系 private HashMap mNidToGid; + // 私有构造函数，初始化相关成员变量 private GTaskManager() { mSyncing = false; mCancelled = false; @@ -99,6 +102,7 @@ public class GTaskManager { mNidToGid = new HashMap(); } + // 获取GTaskManager的单例实例 public static synchronized GTaskManager getInstance() { if (mInstance == null) { mInstance = new GTaskManager(); @@ -106,11 +110,13 @@ public class GTaskManager { return mInstance; } + // 设置关联的Activity上下文，主要用于获取授权令牌等相关操作 public synchronized void setActivityContext(Activity activity) { // used for getting authtoken mActivity = activity; } + // 执行同步操作，与Google Tasks进行数据同步 public int sync(Context context, GTaskASyncTask asyncTask) { if (mSyncing) { Log.d(TAG, "Sync is in progress"); @@ -120,6 +126,7 @@ public class GTaskManager { mContentResolver = mContext.getContentResolver(); mSyncing = true; mCancelled = false; + // 清除之前同步相关的数据缓存，如任务列表、节点、元数据等的哈希表以及ID映射关系等 mGTaskListHashMap.clear(); mGTaskHashMap.clear(); mMetaHashMap.clear(); @@ -131,18 +138,18 @@ public class GTaskManager { GTaskClient client = GTaskClient.getInstance(); client.resetUpdateArray(); - // login google task + // 登录Google Tasks，如果取消同步则不再进行登录操作，如果登录失败则抛出网络异常 if (!mCancelled) { if (!client.login(mActivity)) { throw new NetworkFailureException("login google task failed"); } } - // get the task list from google + // 发布同步进度信息，初始化任务列表阶段 asyncTask.publishProgess(mContext.getString(R.string.sync_progress_init_list)); initGTaskList(); - // do content sync work + // 发布同步进度信息，进行内容同步阶段 asyncTask.publishProgess(mContext.getString(R.string.sync_progress_syncing)); syncContent(); } catch (NetworkFailureException e) { @@ -156,6 +163,7 @@ public class GTaskManager { e.printStackTrace(); return STATE_INTERNAL_ERROR; } finally { + // 无论同步是否成功，最终都清除同步相关的数据缓存 mGTaskListHashMap.clear(); mGTaskHashMap.clear(); mMetaHashMap.clear(); @@ -168,14 +176,16 @@ public class GTaskManager { return mCancelled ? STATE_SYNC_CANCELLED : STATE_SUCCESS; } + // 初始化Google Tasks任务列表相关信息，包括获取任务列表、元数据列表以及加载任务等操作 private void initGTaskList() throws NetworkFailureException { if (mCancelled) return; GTaskClient client = GTaskClient.getInstance(); try { + // 从Google Tasks获取任务列表信息，返回JSON数组形式的数据 JSONArray jsTaskLists = client.getTaskLists(); - // init meta list first + // 先初始化元数据列表，查找名为特定前缀加上"meta"的任务列表作为元数据列表 mMetaList = null; for (int i = 0; i < jsTaskLists.length(); i++) { JSONObject object = jsTaskLists.getJSONObject(i); @@ -187,7 +197,7 @@ public class GTaskManager { mMetaList = new TaskList(); mMetaList.setContentByRemoteJSON(object); - // load meta data + // 加载元数据，获取元数据列表对应的任务列表中的具体元数据信息 JSONArray jsMetas = client.getTaskList(gid); for (int j = 0; j < jsMetas.length(); j++) { object = (JSONObject) jsMetas.getJSONObject(j); @@ -203,7 +213,7 @@ public class GTaskManager { } } - // create meta list if not existed + // 如果元数据列表不存在，则创建一个新的元数据列表，并发送到Google Tasks服务器创建对应的任务列表 if (mMetaList == null) { mMetaList = new TaskList(); mMetaList.setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX @@ -211,7 +221,7 @@ public class GTaskManager { GTaskClient.getInstance().createTaskList(mMetaList); } - // init task list + // 初始化普通任务列表，遍历获取到的任务列表信息，创建任务列表对象并加载对应的任务信息 for (int i = 0; i < jsTaskLists.length(); i++) { JSONObject object = jsTaskLists.getJSONObject(i); String gid = object.getString(GTaskStringUtils.GTASK_JSON_ID); @@ -225,7 +235,7 @@ public class GTaskManager { mGTaskListHashMap.put(gid, tasklist); mGTaskHashMap.put(gid, tasklist); - // load tasks + // 加载任务，获取当前任务列表对应的任务信息 JSONArray jsTasks = client.getTaskList(gid); for (int j = 0; j < jsTasks.length(); j++) { object = (JSONObject) jsTasks.getJSONObject(j); @@ -247,6 +257,7 @@ public class GTaskManager { } } + // 进行内容同步操作，处理本地与Google Tasks之间的数据同步，包括本地删除、文件夹同步、数据库中已有记录的同步等情况 private void syncContent() throws NetworkFailureException { int syncType; Cursor c = null; @@ -259,7 +270,7 @@ public class GTaskManager { return; } - // for local deleted note + // 处理本地已删除的笔记（记录），查询本地回收站文件夹中的记录，对比Google Tasks中的对应节点进行相应的同步操作 try { c = mContentResolver.query(Notes.CONTENT_NOTE_URI, SqlNote.PROJECTION_NOTE, "(type<>? AND parent_id=?)", new String[] { @@ -286,10 +297,10 @@ public class GTaskManager { } } - // sync folder first + // 同步文件夹相关信息 syncFolder(); - // for note existing in database + // 处理数据库中已存在的笔记（记录），根据其在Google Tasks中的对应情况确定同步类型，然后进行相应的同步操作 try { c = mContentResolver.query(Notes.CONTENT_NOTE_URI, SqlNote.PROJECTION_NOTE, "(type=? AND parent_id<>?)", new String[] { @@ -306,10 +317,10 @@ public class GTaskManager { syncType = node.getSyncAction(c); } else { if (c.getString(SqlNote.GTASK_ID_COLUMN).trim().length() == 0) { - // local add + // 本地新增情况 syncType = Node.SYNC_ACTION_ADD_REMOTE; } else { - // remote delete + // 远程已删除情况 syncType = Node.SYNC_ACTION_DEL_LOCAL; } } @@ -326,7 +337,7 @@ public class GTaskManager { } } - // go through remaining items + // 处理剩余的在Google Tasks中存在但本地未处理的节点，进行相应的同步操作（一般是添加到本地） Iterator> iter = mGTaskHashMap.entrySet().iterator(); while (iter.hasNext()) { Map.Entry entry = iter.next(); @@ -334,16 +345,14 @@ public class GTaskManager { doContentSync(Node.SYNC_ACTION_ADD_LOCAL, node, null); } - // mCancelled can be set by another thread, so we neet to check one by - // one - // clear local delete table + // mCancelled可能被其他线程设置，所以需要逐个检查，清除本地已删除记录的相关数据（如果同步未取消） if (!mCancelled) { if (!DataUtils.batchDeleteNotes(mContentResolver, mLocalDeleteIdMap)) { throw new ActionFailureException("failed to batch-delete local deleted notes"); } } - // refresh local sync id + // 刷新本地同步ID（如果同步未取消），提交更新并进行相关操作来更新本地记录的同步ID if (!mCancelled) { GTaskClient.getInstance().commitUpdate(); refreshLocalSyncId(); @@ -351,6 +360,7 @@ public class GTaskManager { } + // 同步文件夹相关信息，包括根文件夹、通话记录文件夹、本地已存在的文件夹以及远程新增的文件夹等情况的处理 private void syncFolder() throws NetworkFailureException { Cursor c = null; String gid; @@ -361,7 +371,7 @@ public class GTaskManager { return; } - // for root folder + // 处理根文件夹的同步情况，根据其在Google Tasks中的对应情况进行相应的同步操作（添加、更新等） try { c = mContentResolver.query(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, Notes.ID_ROOT_FOLDER), SqlNote.PROJECTION_NOTE, null, null, null); @@ -373,7 +383,7 @@ public class GTaskManager { mGTaskHashMap.remove(gid); mGidToNid.put(gid, (long) Notes.ID_ROOT_FOLDER); mNidToGid.put((long) Notes.ID_ROOT_FOLDER, gid); - // for system folder, only update remote name if necessary + // 对于系统文件夹，仅在必要时更新远程名称 if (!node.getName().equals( GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_DEFAULT)) doContentSync(Node.SYNC_ACTION_UPDATE_REMOTE, node, c); @@ -390,77 +400,101 @@ public class GTaskManager { } } - // for call-note folder + // for call-note文件夹相关的同步操作处理 + // 查询通话记录文件夹在本地数据库中的信息，根据其在Google Tasks中的对应情况进行相应的同步操作（添加、更新等） + // 如果查询到该文件夹信息存在（即游标c不为空且能移动到下一条记录），则进一步处理 try { + // 通过ContentResolver查询本地数据库中通话记录文件夹的记录信息，指定查询条件为_id等于通话记录文件夹的特定ID c = mContentResolver.query(Notes.CONTENT_NOTE_URI, SqlNote.PROJECTION_NOTE, "(_id=?)", new String[] { - String.valueOf(Notes.ID_CALL_RECORD_FOLDER) + String.valueOf(Notes.ID_CALL_RECORD_FOLDER) }, null); if (c != null) { if (c.moveToNext()) { + // 获取该文件夹在Google Tasks中对应的全局唯一ID（GID） gid = c.getString(SqlNote.GTASK_ID_COLUMN); + // 根据GID从存储Google Tasks节点的哈希表中获取对应的节点对象 node = mGTaskHashMap.get(gid); if (node != null) { + // 如果节点存在，从哈希表中移除该节点（表示已处理） mGTaskHashMap.remove(gid); + // 在本地ID到Google Tasks的GID映射表中记录该文件夹的映射关系，键为GID，值为通话记录文件夹的本地ID mGidToNid.put(gid, (long) Notes.ID_CALL_RECORD_FOLDER); + // 在Google Tasks的GID到本地ID映射表中记录映射关系，键为本地ID，值为GID mNidToGid.put((long) Notes.ID_CALL_RECORD_FOLDER, gid); - // for system folder, only update remote name if - // necessary + // 对于系统文件夹，仅在其名称与预期的通话记录文件夹名称不一致时（即可能有更新情况），进行远程更新操作 if (!node.getName().equals( GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_CALL_NOTE)) doContentSync(Node.SYNC_ACTION_UPDATE_REMOTE, node, c); } else { + // 如果节点不存在，则执行添加远程节点的操作（意味着本地有该文件夹记录，但在Google Tasks中还未创建对应节点） doContentSync(Node.SYNC_ACTION_ADD_REMOTE, node, c); } } } else { + // 如果查询失败，打印警告日志 Log.w(TAG, "failed to query call note folder"); } } finally { + // 无论查询是否成功，最终都要关闭游标，释放资源，并将游标置空 if (c != null) { c.close(); c = null; } } - // for local existing folders + // 处理本地已存在的文件夹的同步情况 + // 查询本地除回收站外的文件夹记录信息，根据其在Google Tasks中的对应情况进行相应的同步操作 try { + // 通过ContentResolver查询本地数据库中符合条件的文件夹记录信息，条件为类型是文件夹且父ID不等于回收站文件夹的ID c = mContentResolver.query(Notes.CONTENT_NOTE_URI, SqlNote.PROJECTION_NOTE, "(type=? AND parent_id<>?)", new String[] { String.valueOf(Notes.TYPE_FOLDER), String.valueOf(Notes.ID_TRASH_FOLER) }, NoteColumns.TYPE + " DESC"); if (c != null) { while (c.moveToNext()) { + // 获取文件夹在Google Tasks中对应的全局唯一ID（GID） gid = c.getString(SqlNote.GTASK_ID_COLUMN); + // 根据GID从存储Google Tasks节点的哈希表中获取对应的节点对象 node = mGTaskHashMap.get(gid); if (node != null) { + // 如果节点存在，从哈希表中移除该节点（表示已处理） mGTaskHashMap.remove(gid); + // 在本地ID到Google Tasks的GID映射表中记录该文件夹的映射关系，键为GID，值为文件夹的本地ID mGidToNid.put(gid, c.getLong(SqlNote.ID_COLUMN)); + // 在Google Tasks的GID到本地ID映射表中记录映射关系，键为本地ID，值为GID mNidToGid.put(c.getLong(SqlNote.ID_COLUMN), gid); + // 获取该节点对应的同步操作类型（根据节点和游标信息判断是添加、更新、删除等哪种类型） syncType = node.getSyncAction(c); } else { + // 如果节点不存在，根据其GID是否为空字符串判断是本地新增还是远程删除情况，进而确定同步类型 if (c.getString(SqlNote.GTASK_ID_COLUMN).trim().length() == 0) { - // local add + // 本地新增情况，同步类型设置为添加远程节点 syncType = Node.SYNC_ACTION_ADD_REMOTE; } else { - // remote delete + // 远程删除情况，同步类型设置为删除本地节点 syncType = Node.SYNC_ACTION_DEL_LOCAL; } } + // 根据确定的同步类型执行相应的内容同步操作 doContentSync(syncType, node, c); } } else { + // 如果查询失败，打印警告日志 Log.w(TAG, "failed to query existing folder"); } } finally { + // 无论查询是否成功，最终都要关闭游标，释放资源，并将游标置空 if (c != null) { c.close(); c = null; } } - // for remote add folders + // 处理远程新增文件夹的同步情况 + // 遍历存储Google Tasks任务列表的哈希表，对于在Google + // Tasks中存在但本地未处理（还在mGTaskHashMap中）的文件夹，进行添加本地节点的同步操作 Iterator> iter = mGTaskListHashMap.entrySet().iterator(); while (iter.hasNext()) { Map.Entry entry = iter.next(); @@ -472,10 +506,12 @@ public class GTaskManager { } } + // 如果同步未被取消，提交Google Tasks客户端的更新操作（将之前暂存的更新操作发送到服务器执行） if (!mCancelled) GTaskClient.getInstance().commitUpdate(); } + // 根据给定的同步类型执行具体的内容同步操作 private void doContentSync(int syncType, Node node, Cursor c) throws NetworkFailureException { if (mCancelled) { return; @@ -483,12 +519,16 @@ public class GTaskManager { MetaData meta; switch (syncType) { + // 同步类型为添加本地节点，调用相应方法进行本地节点添加操作 case Node.SYNC_ACTION_ADD_LOCAL: addLocalNode(node); break; + // 同步类型为添加远程节点，调用相应方法进行远程节点添加操作，并传入节点和游标信息 case Node.SYNC_ACTION_ADD_REMOTE: addRemoteNode(node, c); break; + // 同步类型为删除本地节点，先从元数据哈希表中获取对应的元数据，若存在则调用Google Tasks客户端删除该元数据节点， + // 同时将本地记录的ID添加到本地已删除记录集合中 case Node.SYNC_ACTION_DEL_LOCAL: meta = mMetaHashMap.get(c.getString(SqlNote.GTASK_ID_COLUMN)); if (meta != null) { @@ -496,6 +536,8 @@ public class GTaskManager { } mLocalDeleteIdMap.add(c.getLong(SqlNote.ID_COLUMN)); break; + // 同步类型为删除远程节点，先从元数据哈希表中获取对应节点的元数据，若存在则调用Google Tasks客户端删除该元数据节点， + // 然后再删除该节点本身 case Node.SYNC_ACTION_DEL_REMOTE: meta = mMetaHashMap.get(node.getGid()); if (meta != null) { @@ -503,51 +545,66 @@ public class GTaskManager { } GTaskClient.getInstance().deleteNode(node); break; + // 同步类型为更新本地节点，调用相应方法进行本地节点更新操作，并传入节点和游标信息 case Node.SYNC_ACTION_UPDATE_LOCAL: updateLocalNode(node, c); break; + // 同步类型为更新远程节点，调用相应方法进行远程节点更新操作，并传入节点和游标信息 case Node.SYNC_ACTION_UPDATE_REMOTE: updateRemoteNode(node, c); break; + // 同步类型为更新冲突，目前简单采用本地更新的方式（可能后续可以考虑合并修改等更好的处理方式），调用远程节点更新方法 case Node.SYNC_ACTION_UPDATE_CONFLICT: // merging both modifications maybe a good idea // right now just use local update simply updateRemoteNode(node, c); break; + // 同步类型为无操作，直接跳过不做任何处理 case Node.SYNC_ACTION_NONE: break; + // 同步类型为错误或其他未知类型，抛出操作失败异常，表示遇到了未知的同步操作类型 case Node.SYNC_ACTION_ERROR: default: throw new ActionFailureException("unkown sync action type"); } } + // 添加本地节点的操作方法 private void addLocalNode(Node node) throws NetworkFailureException { if (mCancelled) { return; } SqlNote sqlNote; + // 如果节点是任务列表类型（TaskList） if (node instanceof TaskList) { + // 如果节点名称是默认根文件夹的名称，创建一个对应根文件夹的SqlNote对象，传入上下文和根文件夹的本地ID if (node.getName().equals( GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_DEFAULT)) { sqlNote = new SqlNote(mContext, Notes.ID_ROOT_FOLDER); } else if (node.getName().equals( GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_CALL_NOTE)) { + // 如果节点名称是通话记录文件夹的名称，创建一个对应通话记录文件夹的SqlNote对象，传入上下文和通话记录文件夹的本地ID sqlNote = new SqlNote(mContext, Notes.ID_CALL_RECORD_FOLDER); } else { + // 其他普通任务列表情况，创建一个新的SqlNote对象，传入上下文 sqlNote = new SqlNote(mContext); + // 设置SqlNote的内容为节点的本地JSON格式内容（从节点获取） sqlNote.setContent(node.getLocalJSONFromContent()); + // 设置父ID为根文件夹的本地ID sqlNote.setParentId(Notes.ID_ROOT_FOLDER); } } else { + // 如果节点是普通任务（Task）类型，创建一个新的SqlNote对象，传入上下文 sqlNote = new SqlNote(mContext); JSONObject js = node.getLocalJSONFromContent(); try { + // 如果节点的本地JSON数据中包含特定的笔记头部信息（META_HEAD_NOTE） if (js.has(GTaskStringUtils.META_HEAD_NOTE)) { JSONObject note = js.getJSONObject(GTaskStringUtils.META_HEAD_NOTE); if (note.has(NoteColumns.ID)) { long id = note.getLong(NoteColumns.ID); + // 检查该笔记ID在本地笔记数据库中是否已存在，如果存在则移除该ID（可能需要重新生成新的ID） if (DataUtils.existInNoteDatabase(mContentResolver, id)) { // the id is not available, have to create a new one note.remove(NoteColumns.ID); @@ -555,12 +612,14 @@ public class GTaskManager { } } + // 如果节点的本地JSON数据中包含特定的数据头部信息（META_HEAD_DATA） if (js.has(GTaskStringUtils.META_HEAD_DATA)) { JSONArray dataArray = js.getJSONArray(GTaskStringUtils.META_HEAD_DATA); for (int i = 0; i < dataArray.length(); i++) { JSONObject data = dataArray.getJSONObject(i); if (data.has(DataColumns.ID)) { long dataId = data.getLong(DataColumns.ID); + // 检查该数据ID在本地数据数据库中是否已存在，如果存在则移除该ID（可能需要重新生成新的ID） if (DataUtils.existInDataDatabase(mContentResolver, dataId)) { // the data id is not available, have to create // a new one @@ -574,36 +633,43 @@ public class GTaskManager { Log.w(TAG, e.toString()); e.printStackTrace(); } + // 设置SqlNote的内容为处理后的JSON数据 sqlNote.setContent(js); + // 获取任务节点的父节点在本地ID到Google Tasks的GID映射表中的对应父ID，如果不存在则抛出异常表示找不到本地父ID Long parentId = mGidToNid.get(((Task) node).getParent().getGid()); if (parentId == null) { Log.e(TAG, "cannot find task's parent id locally"); throw new ActionFailureException("cannot add local node"); } + // 设置SqlNote的父ID为获取到的父节点的本地ID sqlNote.setParentId(parentId.longValue()); } - // create the local node + // 设置SqlNote的Google Tasks全局唯一ID（GID）为节点的GID sqlNote.setGtaskId(node.getGid()); + // 将SqlNote对象提交保存到本地数据库（传入参数false可能表示不触发某些额外的相关操作） sqlNote.commit(false); - // update gid-nid mapping + // 在本地ID到Google Tasks的GID映射表中记录该节点的映射关系，键为节点的GID，值为SqlNote的本地ID mGidToNid.put(node.getGid(), sqlNote.getId()); + // 在Google Tasks的GID到本地ID映射表中记录映射关系，键为SqlNote的本地ID，值为节点的GID mNidToGid.put(sqlNote.getId(), node.getGid()); - // update meta + // 更新远程元数据，传入节点的GID和对应的SqlNote对象 updateRemoteMeta(node.getGid(), sqlNote); } + // 更新本地节点的操作方法 private void updateLocalNode(Node node, Cursor c) throws NetworkFailureException { if (mCancelled) { return; } SqlNote sqlNote; - // update the note locally + // 根据传入的上下文和游标信息创建一个新的SqlNote对象，用于更新本地节点信息 sqlNote = new SqlNote(mContext, c); + // 设置SqlNote的内容为节点的本地JSON格式内容（从节点获取） sqlNote.setContent(node.getLocalJSONFromContent()); Long parentId = (node instanceof Task) ? mGidToNid.get(((Task) node).getParent().getGid()) @@ -612,13 +678,16 @@ public class GTaskManager { Log.e(TAG, "cannot find task's parent id locally"); throw new ActionFailureException("cannot update local node"); } + // 设置SqlNote的父ID为获取到的父节点的本地ID sqlNote.setParentId(parentId.longValue()); + // 将更新后的SqlNote对象提交保存到本地数据库（传入参数true可能表示触发某些额外的相关操作） sqlNote.commit(true); - // update meta info + // 更新远程元数据，传入节点的GID和对应的SqlNote对象 updateRemoteMeta(node.getGid(), sqlNote); } + // 添加远程节点的操作方法 private void addRemoteNode(Node node, Cursor c) throws NetworkFailureException { if (mCancelled) { return; @@ -627,9 +696,10 @@ public class GTaskManager { SqlNote sqlNote = new SqlNote(mContext, c); Node n; - // update remotely + // 如果SqlNote对应的是笔记类型（即普通任务） if (sqlNote.isNoteType()) { Task task = new Task(); + // 设置任务的内容为从本地SqlNote获取的JSON格式内容 task.setContentByLocalJSON(sqlNote.getContent()); String parentGid = mNidToGid.get(sqlNote.getParentId()); @@ -637,17 +707,20 @@ public class GTaskManager { Log.e(TAG, "cannot find task's parent tasklist"); throw new ActionFailureException("cannot add remote task"); } + // 将任务添加到对应的父任务列表中（通过本地ID到Google Tasks的GID映射表找到父任务列表） mGTaskListHashMap.get(parentGid).addChildTask(task); + // 通过Google Tasks客户端创建该任务（发送到服务器创建对应的任务节点） GTaskClient.getInstance().createTask(task); n = (Node) task; - // add meta + // 更新远程元数据，传入任务的GID和对应的SqlNote对象 updateRemoteMeta(task.getGid(), sqlNote); } else { TaskList tasklist = null; - // we need to skip folder if it has already existed + // 构建文件夹名称，先添加特定的前缀，然后根据SqlNote的本地ID判断是否是根文件夹或通话记录文件夹，添加相应的后缀名称， + // 否则添加SqlNote的摘要信息作为后缀 String folderName = GTaskStringUtils.MIUI_FOLDER_PREFFIX; if (sqlNote.getId() == Notes.ID_ROOT_FOLDER) folderName += GTaskStringUtils.FOLDER_DEFAULT; @@ -656,121 +729,166 @@ public class GTaskManager { else folderName += sqlNote.getSnippet(); + // 遍历存储Google Tasks任务列表的哈希表（mGTaskListHashMap）的迭代器 Iterator> iter = mGTaskListHashMap.entrySet().iterator(); while (iter.hasNext()) { + // 获取哈希表中的每一个键值对，键是任务列表的全局唯一ID（GID），值是对应的任务列表对象（TaskList） Map.Entry entry = iter.next(); String gid = entry.getKey(); TaskList list = entry.getValue(); + // 判断当前任务列表的名称是否与之前构建的文件夹名称（folderName）相等 if (list.getName().equals(folderName)) { + // 如果相等，说明找到了对应的任务列表，将其赋值给tasklist变量 tasklist = list; + // 如果在存储Google Tasks节点的哈希表（mGTaskHashMap）中包含该任务列表的GID，说明已经处理过，将其移除 if (mGTaskHashMap.containsKey(gid)) { mGTaskHashMap.remove(gid); } + // 找到匹配的任务列表后就可以结束循环了 break; } } - // no match we can add now + // 如果经过上述查找没有找到匹配的任务列表（tasklist仍为null），则创建一个新的任务列表对象 if (tasklist == null) { tasklist = new TaskList(); + // 设置新任务列表的内容为从本地SqlNote获取的JSON格式内容 tasklist.setContentByLocalJSON(sqlNote.getContent()); + // 通过Google Tasks客户端创建该任务列表（发送到服务器创建对应的任务列表节点） GTaskClient.getInstance().createTaskList(tasklist); + // 将新创建的任务列表添加到存储Google Tasks任务列表的哈希表中，键为任务列表的GID，值为任务列表对象 mGTaskListHashMap.put(tasklist.getGid(), tasklist); } + // 将创建或找到的任务列表对象转换为Node类型并赋值给n（因为Node是更通用的节点类型，TaskList是一种特殊的Node） n = (Node) tasklist; } - // update local note + // 更新本地笔记相关信息 + // 设置本地SqlNote的Google Tasks全局唯一ID（GID）为n的GID，即与远程任务列表或任务对应的GID保持一致 sqlNote.setGtaskId(n.getGid()); + // 将SqlNote对象提交保存到本地数据库（传入参数false可能表示不触发某些额外的相关操作，此处用于保存基本的关联信息等） sqlNote.commit(false); + // 重置本地修改标志（可能表示将本地记录标记为已与远程同步，不再是本地修改状态） sqlNote.resetLocalModified(); + // 再次提交保存SqlNote对象到本地数据库（传入参数true可能表示触发一些更新相关的额外操作，确保修改标志等信息更新成功） sqlNote.commit(true); - // gid-id mapping + // gid-id映射更新 + // 在本地ID到Google Tasks的GID映射表（mGidToNid）中记录该节点（n）的映射关系，键为节点的GID，值为SqlNote的本地ID mGidToNid.put(n.getGid(), sqlNote.getId()); + // 在Google Tasks的GID到本地ID映射表（mNidToGid）中记录映射关系，键为SqlNote的本地ID，值为节点的GID mNidToGid.put(sqlNote.getId(), n.getGid()); } + // 更新远程节点的操作方法 private void updateRemoteNode(Node node, Cursor c) throws NetworkFailureException { if (mCancelled) { return; } + // 根据传入的上下文和游标信息创建一个新的SqlNote对象，用于后续操作 SqlNote sqlNote = new SqlNote(mContext, c); - // update remotely + // 远程更新操作 + // 设置远程节点（node）的内容为从本地SqlNote获取的JSON格式内容，即将本地修改同步到远程节点 node.setContentByLocalJSON(sqlNote.getContent()); + // 通过Google Tasks客户端将更新后的节点添加到更新队列中（后续会批量提交更新到服务器） GTaskClient.getInstance().addUpdateNode(node); - // update meta + // 更新远程元数据，传入节点的GID和对应的SqlNote对象 updateRemoteMeta(node.getGid(), sqlNote); - // move task if necessary + // 如果SqlNote对应的是笔记类型（即普通任务），则可能需要处理任务移动相关操作 if (sqlNote.isNoteType()) { Task task = (Task) node; + // 获取任务当前的父任务列表 TaskList preParentList = task.getParent(); + // 通过本地ID到Google Tasks的GID映射表，根据本地记录的父ID获取当前任务在远程对应的父任务列表的GID String curParentGid = mNidToGid.get(sqlNote.getParentId()); if (curParentGid == null) { Log.e(TAG, "cannot find task's parent tasklist"); throw new ActionFailureException("cannot update remote task"); } + // 根据获取到的GID从存储Google Tasks任务列表的哈希表中获取当前任务在远程对应的父任务列表对象 TaskList curParentList = mGTaskListHashMap.get(curParentGid); + // 如果当前任务的前后父任务列表不一致，说明任务需要在远程进行移动操作 if (preParentList != curParentList) { + // 先从原父任务列表中移除该任务 preParentList.removeChildTask(task); + // 将任务添加到新的父任务列表中 curParentList.addChildTask(task); + // 通过Google Tasks客户端执行任务移动操作，告知服务器任务在远程的位置变更 GTaskClient.getInstance().moveTask(task, preParentList, curParentList); } } - // clear local modified flag + // 清除本地修改标志，标记本地记录已同步到远程，不再处于本地修改状态 sqlNote.resetLocalModified(); + // 将更新后的SqlNote对象提交保存到本地数据库（传入参数true可能表示触发一些更新相关的额外操作，确保修改标志等信息更新成功） sqlNote.commit(true); } + // 更新远程元数据的操作方法 private void updateRemoteMeta(String gid, SqlNote sqlNote) throws NetworkFailureException { if (sqlNote != null && sqlNote.isNoteType()) { + // 从存储元数据的哈希表（mMetaHashMap）中根据GID获取对应的元数据对象（MetaData） MetaData metaData = mMetaHashMap.get(gid); if (metaData != null) { + // 如果元数据对象存在，设置其元数据内容，传入GID和从本地SqlNote获取的JSON格式内容 metaData.setMeta(gid, sqlNote.getContent()); + // 通过Google Tasks客户端将更新后的元数据添加到更新队列中（后续会批量提交更新到服务器） GTaskClient.getInstance().addUpdateNode(metaData); } else { + // 如果元数据对象不存在，则创建一个新的元数据对象 metaData = new MetaData(); + // 设置新元数据对象的元数据内容，传入GID和从本地SqlNote获取的JSON格式内容 metaData.setMeta(gid, sqlNote.getContent()); + // 将新创建的元数据对象添加到元数据列表（mMetaList）中作为子任务（从逻辑上关联起来） mMetaList.addChildTask(metaData); + // 将新创建的元数据对象添加到存储元数据的哈希表中，键为GID，值为元数据对象 mMetaHashMap.put(gid, metaData); + // 通过Google Tasks客户端创建该元数据任务（发送到服务器创建对应的元数据节点） GTaskClient.getInstance().createTask(metaData); } } } + // 刷新本地同步ID的操作方法 private void refreshLocalSyncId() throws NetworkFailureException { if (mCancelled) { return; } - // get the latest gtask list + // 为了获取最新的Google Tasks列表信息，先清空之前存储相关信息的哈希表 mGTaskHashMap.clear(); mGTaskListHashMap.clear(); mMetaHashMap.clear(); + // 重新初始化Google Tasks列表信息（重新获取任务列表、元数据等相关内容） initGTaskList(); Cursor c = null; try { + // 通过ContentResolver查询本地数据库中除系统类型且不在回收站的笔记记录信息，按照类型降序排列 c = mContentResolver.query(Notes.CONTENT_NOTE_URI, SqlNote.PROJECTION_NOTE, "(type<>? AND parent_id<>?)", new String[] { String.valueOf(Notes.TYPE_SYSTEM), String.valueOf(Notes.ID_TRASH_FOLER) }, NoteColumns.TYPE + " DESC"); if (c != null) { while (c.moveToNext()) { + // 获取笔记在Google Tasks中对应的全局唯一ID（GID） String gid = c.getString(SqlNote.GTASK_ID_COLUMN); + // 根据GID从存储Google Tasks节点的哈希表中获取对应的节点对象 Node node = mGTaskHashMap.get(gid); if (node != null) { + // 如果节点存在，从哈希表中移除该节点（表示已处理） mGTaskHashMap.remove(gid); + // 创建一个ContentValues对象用于存放要更新的数据，此处将同步ID设置为节点的最后修改时间 ContentValues values = new ContentValues(); values.put(NoteColumns.SYNC_ID, node.getLastModified()); + // 通过ContentResolver更新本地数据库中对应笔记的记录，设置同步ID字段的值 mContentResolver.update(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, c.getLong(SqlNote.ID_COLUMN)), values, null, null); } else { @@ -783,6 +901,7 @@ public class GTaskManager { Log.w(TAG, "failed to query local note to refresh sync id"); } } finally { + // 无论查询是否成功，最终都要关闭游标，释放资源，并将游标置空 if (c != null) { c.close(); c = null; @@ -790,10 +909,12 @@ public class GTaskManager { } } + // 获取同步账户名称的方法，通过Google Tasks客户端获取同步账户对象，并返回其名称 public String getSyncAccount() { return GTaskClient.getInstance().getSyncAccount().name; } + // 取消同步的方法，将表示同步是否取消的标志（mCancelled）设置为true，其他相关操作可以根据该标志来判断是否停止执行 public void cancelSync() { mCancelled = true; } diff --git a/src/Notes-master/src/net/micode/notes/gtask/remote/GTaskSyncService.java b/src/Notes-master/src/net/micode/notes/gtask/remote/GTaskSyncService.java index cca36f7..054b9da 100644 --- a/src/Notes-master/src/net/micode/notes/gtask/remote/GTaskSyncService.java +++ b/src/Notes-master/src/net/micode/notes/gtask/remote/GTaskSyncService.java @@ -23,69 +23,101 @@ import android.content.Intent; import android.os.Bundle; import android.os.IBinder; +// GTaskSyncService类继承自Service，用于管理与Google Tasks的同步相关操作，包括启动同步、取消同步以及广播同步状态等功能 public class GTaskSyncService extends Service { + + // 用于在Intent中传递同步操作类型的字符串常量，作为键来标识具体的操作类型信息 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; + // 用于广播同步服务相关状态信息的Intent的动作名称，其他组件可以通过注册监听该动作来接收同步服务的广播消息 public final static String GTASK_SERVICE_BROADCAST_NAME = "net.micode.notes.gtask.remote.gtask_sync_service"; + // 在广播Intent中用于传递是否正在同步状态的键名，对应的值为布尔类型，表示同步操作是否正在进行 public final static String GTASK_SERVICE_BROADCAST_IS_SYNCING = "isSyncing"; + // 在广播Intent中用于传递同步进度消息的键名，对应的值为字符串类型，可用于展示同步操作的进度相关文本信息 public final static String GTASK_SERVICE_BROADCAST_PROGRESS_MSG = "progressMsg"; + // 静态变量，用于存储正在执行的同步任务对象（GTaskASyncTask类型），方便在不同方法中对同步任务进行控制和判断状态 private static GTaskASyncTask mSyncTask = null; + // 静态变量，用于存储同步进度相关的消息字符串，可通过广播传递给其他关注同步进度的组件 private static String mSyncProgress = ""; + // 启动同步的私有方法，用于创建并执行同步任务 private void startSync() { + // 如果当前没有正在执行的同步任务（mSyncTask为null） if (mSyncTask == null) { + // 创建一个新的GTaskASyncTask对象，传入当前服务上下文（this）以及一个完成监听器（OnCompleteListener） mSyncTask = new GTaskASyncTask(this, new GTaskASyncTask.OnCompleteListener() { + // 当同步任务完成时会调用的回调方法 public void onComplete() { + // 将正在执行的同步任务对象置为null，表示同步已结束 mSyncTask = null; + // 发送一个空消息的广播（可能用于通知其他组件同步已完成等状态变化） sendBroadcast(""); + // 停止当前服务（因为同步任务已完成，服务的主要工作完成，可以停止自身运行） stopSelf(); } }); + // 发送一个空消息的广播（可能在创建任务后就先通知其他组件同步即将开始等情况） sendBroadcast(""); + // 执行同步任务，开始真正的同步操作流程 mSyncTask.execute(); } } + // 取消同步的私有方法，用于取消正在执行的同步任务（如果存在的话） private void cancelSync() { if (mSyncTask != null) { mSyncTask.cancelSync(); } } + // 服务创建时调用的方法，在这里将正在执行的同步任务对象初始化为null，确保服务启动时处于初始状态 @Override public void onCreate() { mSyncTask = null; } + // 当服务通过startService()方法启动时会调用此方法，用于处理传入的Intent并根据不同的操作意图执行相应操作 @Override public int onStartCommand(Intent intent, int flags, int startId) { + // 从传入的Intent中获取附加的Bundle数据（通常用于传递额外的参数信息） Bundle bundle = intent.getExtras(); + // 如果获取到的Bundle不为null且包含表示操作类型的键（ACTION_STRING_NAME） if (bundle != null && bundle.containsKey(ACTION_STRING_NAME)) { + // 根据操作类型的值进行不同的操作分支判断 switch (bundle.getInt(ACTION_STRING_NAME, ACTION_INVALID)) { + // 如果操作类型是启动同步（ACTION_START_SYNC） case ACTION_START_SYNC: startSync(); break; + // 如果操作类型是取消同步（ACTION_CANCEL_SYNC） case ACTION_CANCEL_SYNC: cancelSync(); break; + // 其他未知或不处理的操作类型，直接跳过不做操作 default: break; } + // 返回START_STICKY表示服务在被系统意外终止后会尝试重新创建并保持启动状态（常用于需要持续运行的服务场景） return START_STICKY; } + // 如果不符合上述条件或者操作类型无效等情况，调用父类的onStartCommand方法进行默认处理 return super.onStartCommand(intent, flags, startId); } + // 当系统内存不足时会调用此方法，在这里用于取消正在执行的同步任务（如果存在的话），释放内存资源 @Override public void onLowMemory() { if (mSyncTask != null) { @@ -93,10 +125,13 @@ public class GTaskSyncService extends Service { } } + // 用于服务绑定操作的方法，这里返回null表示不支持绑定操作（如果需要支持绑定，需要返回一个有效的IBinder对象） + @Override public IBinder onBind(Intent intent) { return null; } + // 发送广播的公共方法，用于向其他组件广播同步服务的相关状态信息，包括同步进度消息、是否正在同步等 public void sendBroadcast(String msg) { mSyncProgress = msg; Intent intent = new Intent(GTASK_SERVICE_BROADCAST_NAME); @@ -105,24 +140,29 @@ public class GTaskSyncService extends Service { sendBroadcast(intent); } + // 静态公共方法，用于在外部（比如Activity中）启动同步服务进行同步操作，需要传入对应的Activity作为上下文来启动服务 public static void startSync(Activity activity) { + // 设置GTaskManager的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); } + // 静态公共方法，用于在外部（比如其他组件中）取消正在进行的同步操作，需要传入上下文（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); } + // 静态公共方法，用于判断当前是否正在进行同步操作，通过检查正在执行的同步任务对象是否为null来返回相应的布尔值结果 public static boolean isSyncing() { return mSyncTask != null; } + // 静态公共方法，用于获取当前的同步进度相关的字符串消息，返回存储同步进度消息的静态变量的值 public static String getProgressString() { return mSyncProgress; } -} +} \ No newline at end of file