zhushi

src/王焱铂的注释/GTaskASyncTask.java

@@ -0,0 +1,150 @@
+/*
+ * 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.app.Notification;
+import android.app.NotificationManager;
+import android.app.PendingIntent;
+import android.content.Context;
+import android.content.Intent;
+import android.os.AsyncTask;
+
+import net.micode.notes.R;
+import net.micode.notes.ui.NotesListActivity;
+import net.micode.notes.ui.NotesPreferenceActivity;
+
+// GTaskASyncTask类继承自AsyncTask，用于在后台执行与GTask相关的异步任务，
+// 任务执行过程中可发布进度信息，完成后返回一个整数结果表示任务状态
+public class GTaskASyncTask extends AsyncTask<Void, String, Integer> {
+
+    // 用于标识GTask同步相关通知的唯一ID，在整个应用中用于区分不同的通知
+    private static int GTASK_SYNC_NOTIFICATION_ID = 5234235;
+
+    // 定义一个接口，用于在异步任务完成时进行回调，外部类可以实现该接口来处理任务完成后的逻辑
+    public interface OnCompleteListener {
+        void onComplete();
+    }
+
+    // 保存当前上下文环境，用于获取系统服务、资源等操作
+    private Context mContext;
+
+    // 用于管理和显示通知的系统服务对象，通过它可以发送各种通知给用户
+    private NotificationManager mNotifiManager;
+
+    // 负责管理GTask相关操作的对象，例如执行同步任务等，通过单例模式获取实例
+    private GTaskManager mTaskManager;
+
+    // 保存外部传入的任务完成监听器，以便在任务结束后执行相应回调逻辑
+    private OnCompleteListener mOnCompleteListener;
+
+    // 构造函数，用于初始化GTaskASyncTask实例
+    // 参数context为当前上下文，listener为任务完成监听器
+    public GTaskASyncTask(Context context, OnCompleteListener listener) {
+        mContext = context;
+        mOnCompleteListener = listener;
+        // 获取系统的通知服务，用于后续显示通知相关操作
+        mNotifiManager = (NotificationManager) mContext
+                .getSystemService(Context.NOTIFICATION_SERVICE);
+        // 获取GTaskManager的单例实例，以便调用其相关方法来处理GTask任务
+        mTaskManager = GTaskManager.getInstance();
+    }
+
+    // 用于取消正在进行的同步任务，实际调用GTaskManager中的取消同步方法
+    public void cancelSync() {
+        mTaskManager.cancelSync();
+    }
+
+    // 对外提供的方法，用于发布任务进度信息，将传入的消息包装成数组后调用父类的publishProgress方法
+    public void publishProgess(String message) {
+        publishProgress(new String[]{message});
+    }
+
+    // 私有方法，用于显示通知
+    // 参数tickerId用于区分不同类型的通知提示文本，content为通知的具体内容
+    private void showNotification(int tickerId, String content) {
+        PendingIntent pendingIntent;
+        // 根据通知类型（是否是成功的通知）来设置不同的点击意图（PendingIntent）
+        if (tickerId!= R.string.ticker_success) {
+            // 如果不是成功通知，点击后跳转到NotesPreferenceActivity
+            pendingIntent = PendingIntent.getActivity(mContext, 0, new Intent(mContext,
+                    NotesPreferenceActivity.class), PendingIntent.FLAG_IMMUTABLE);
+        } else {
+            // 如果是成功通知，点击后跳转到NotesListActivity
+            pendingIntent = PendingIntent.getActivity(mContext, 0, new Intent(mContext,
+                    NotesListActivity.class), PendingIntent.FLAG_IMMUTABLE);
+        }
+
+        // 创建Notification.Builder对象，用于构建通知的各项属性
+        Notification.Builder builder = new Notification.Builder(mContext)
+                .setAutoCancel(true)  // 设置点击通知后自动取消通知
+                .setContentTitle(mContext.getString(R.string.app_name))  // 设置通知的标题为应用名称
+                .setContentText(content)  // 设置通知的具体内容文本
+                .setContentIntent(pendingIntent)  // 设置点击通知后的意图
+                .setWhen(System.currentTimeMillis())  // 设置通知的触发时间为当前时间
+                .setOngoing(true);  // 设置通知为正在进行的状态（通常用于表示持续进行的任务相关通知）
+
+        // 获取最终构建好的Notification对象
+        Notification notification = builder.getNotification();
+        // 通过通知管理器发送通知，使用之前定义的通知ID来标识该通知
+        mNotifiManager.notify(GTASK_SYNC_NOTIFICATION_ID, notification);
+    }
+
+    // 在后台线程中执行的任务逻辑，首先发布登录进度信息，然后调用GTaskManager的sync方法执行同步任务，
+    // 并返回同步任务的结果（以整数表示不同的状态）
+    @Override
+    protected Integer doInBackground(Void... unused) {
+        publishProgess(mContext.getString(R.string.sync_progress_login, NotesPreferenceActivity
+                .getSyncAccountName(mContext)));
+        return mTaskManager.sync(mContext, this);
+    }
+
+    // 当在后台任务执行过程中有进度更新时调用该方法，会显示相应的通知来告知用户进度情况，
+    // 如果当前上下文是GTaskSyncService类型，还会发送广播传递进度信息
+    @Override
+    protected void onProgressUpdate(String... progress) {
+        showNotification(R.string.ticker_syncing, progress[0]);
+        if (mContext instanceof GTaskSyncService) {
+            ((GTaskSyncService) mContext).sendBroadcast(progress[0]);
+        }
+    }
+
+    // 在后台任务执行完成后调用该方法，根据返回的结果（不同的状态码）来显示不同类型的通知，
+    // 如果有设置任务完成监听器（mOnCompleteListener不为空），则在新线程中执行监听器的onComplete方法
+    @Override
+    protected void onPostExecute(Integer result) {
+        if (result == GTaskManager.STATE_SUCCESS) {
+            showNotification(R.string.ticker_success, mContext.getString(
+                    R.string.success_sync_account, mTaskManager.getSyncAccount()));
+            NotesPreferenceActivity.setLastSyncTime(mContext, System.currentTimeMillis());
+        } else if (result == GTaskManager.STATE_NETWORK_ERROR) {
+            showNotification(R.string.ticker_fail, mContext.getString(R.string.error_sync_network));
+        } else if (result == GTaskManager.STATE_INTERNAL_ERROR) {
+            showNotification(R.string.ticker_fail, mContext.getString(R.string.error_sync_internal));
+        } else if (result == GTaskManager.STATE_SYNC_CANCELLED) {
+            showNotification(R.string.ticker_cancel, mContext
+                    .getString(R.string.error_sync_cancelled));
+        }
+        if (mOnCompleteListener!= null) {
+            new Thread(new Runnable() {
+
+                public void run() {
+                    mOnCompleteListener.onComplete();
+                }
+            }).start();
+        }
+    }
+}

src/王焱铂的注释/GTaskClient.java

@@ -0,0 +1,401 @@
+/*
+ * 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;
+import android.accounts.AccountManager;
+import android.accounts.AccountManagerFuture;
+import android.app.Activity;
+import android.os.Bundle;
+import android.text.TextUtils;
+import android.util.Log;
+
+import net.micode.notes.gtask.data.Node;
+import net.micode.notes.gtask.data.Task;
+import net.micode.notes.gtask.data.TaskList;
+import net.micode.notes.gtask.exception.ActionFailureException;
+import net.micode.notes.gtask.exception.NetworkFailureException;
+import net.micode.notes.tool.GTaskStringUtils;
+import net.micode.notes.ui.NotesPreferenceActivity;
+
+import org.apache.http.HttpEntity;
+import org.apache.http.HttpResponse;
+import org.apache.http.client.ClientProtocolException;
+import org.apache.http.client.entity.UrlEncodedFormEntity;
+import org.apache.http.client.methods.HttpGet;
+import org.apache.http.client.methods.HttpPost;
+import org.apache.http.cookie.Cookie;
+import org.apache.http.impl.client.BasicCookieStore;
+import org.apache.http.impl.client.DefaultHttpClient;
+import org.apache.http.message.BasicNameValuePair;
+import org.apache.http.params.BasicHttpParams;
+import org.apache.http.params.HttpConnectionParams;
+import org.apache.http.params.HttpParams;
+import org.apache.http.params.HttpProtocolParams;
+import org.json.JSONArray;
+import org.json.JSONException;
+import org.json.JSONObject;
+
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.util.LinkedList;
+import java.util.List;
+import java.util.zip.GZIPInputStream;
+import java.util.zip.Inflater;
+import java.util.zip.InflaterInputStream;
+
+// GTaskClient类主要负责与Google Tasks服务进行交互，包括登录验证、获取任务列表、创建任务、更新任务等各种操作，是实现与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数据的GET请求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";
+    // 采用单例模式，保存GTaskClient的唯一实例
+    private static GTaskClient mInstance = null;
+    // 用于发送HTTP请求的HttpClient对象，用于执行与Google Tasks服务的网络通信
+    private DefaultHttpClient mHttpClient;
+    // 当前用于获取数据的GET请求URL，可能会根据登录情况等因素进行调整
+    private String mGetUrl;
+    // 当前用于提交数据的POST请求URL，可能会根据登录情况等因素进行调整
+    private String mPostUrl;
+    // 客户端版本号，用于与Google Tasks服务交互时标识客户端的版本情况
+    private long mClientVersion = -1;
+    // 标记当前是否已登录到Google Tasks服务
+    private boolean mLoggedin = false;
+    // 记录上次登录的时间戳，用于判断是否需要重新登录（例如基于登录有效期等逻辑）
+    private long mLastLoginTime = 0;
+    // 用于生成每个操作的唯一ID，每次操作后自增，确保每个操作在请求中有唯一标识
+    private int mActionId = 1;
+    // 关联的Google账户对象，用于登录验证以及与账户相关的操作
+    private Account mAccount;
+    // 用于存储待提交的更新操作相关的JSON数据数组，批量提交更新时使用
+    private JSONArray mUpdateArray;
+
+    // 私有构造函数，初始化GTaskClient实例的各个成员变量
+    private GTaskClient() {
+        mHttpClient = null;
+        mGetUrl = GTASK_GET_URL;
+        mPostUrl = GTASK_POST_URL;
+        mClientVersion = -1;
+        mLoggedin = false;
+        mLastLoginTime = 0;
+        mActionId = 1;
+        mAccount = null;
+        mUpdateArray = null;
+    }
+
+    // 静态方法，用于获取GTaskClient的单例实例，如果实例不存在则创建一个新的实例
+    public static synchronized GTaskClient getInstance() {
+        if (mInstance == null) {
+            mInstance = new GTaskClient();
+        }
+        return mInstance;
+    }
+
+    // 执行登录到Google Tasks服务的方法，处理登录逻辑，包括判断是否需要重新登录、获取授权令牌、根据账户类型尝试不同的登录方式等
+    public boolean login(Activity activity) {
+        // 假设登录的Cookie有效期为5分钟，超过这个时间间隔则需要重新登录
+        final long interval = 1000 * 60 * 5;
+        if (mLastLoginTime + interval < System.currentTimeMillis()) {
+            mLoggedin = false;
+        }
+
+        // 如果账户切换了，也需要重新登录
+        if (mLoggedin
+                &&!TextUtils.equals(getSyncAccount().name, NotesPreferenceActivity
+                      .getSyncAccountName(activity))) {
+            mLoggedin = false;
+        }
+
+        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;
+        }
+
+        // 如果账户不是以"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/");
+            int index = mAccount.name.indexOf('@') + 1;
+            String suffix = mAccount.name.substring(index);
+            url.append(suffix + "/");
+            mGetUrl = url.toString() + "ig";
+            mPostUrl = url.toString() + "r/ig";
+
+            if (tryToLoginGtask(activity, authToken)) {
+                mLoggedin = true;
+            }
+        }
+
+        // 如果使用自定义域名登录失败，尝试使用Google官方的URL进行登录
+        if (!mLoggedin) {
+            mGetUrl = GTASK_GET_URL;
+            mPostUrl = GTASK_POST_URL;
+            if (!tryToLoginGtask(activity, authToken)) {
+                return false;
+            }
+        }
+
+        mLoggedin = true;
+        return true;
+    }
+
+    // 登录Google账户获取授权令牌的方法，通过AccountManager查找合适的Google账户，并获取对应的授权令牌
+    private String loginGoogleAccount(Activity activity, boolean invalidateToken) {
+        String authToken;
+        AccountManager accountManager = AccountManager.get(activity);
+        Account[] accounts = accountManager.getAccountsByType("com.google");
+
+        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;
+                break;
+            }
+        }
+        if (account!= null) {
+            mAccount = account;
+        } else {
+            Log.e(TAG, "unable to get an account with the same name in the settings");
+            return null;
+        }
+
+        // 获取授权令牌
+        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);
+            }
+        } catch (Exception e) {
+            Log.e(TAG, "get auth token failed");
+            authToken = null;
+        }
+
+        return authToken;
+    }
+
+    // 尝试登录到Google Tasks服务的方法，内部可能会处理授权令牌过期等情况，多次尝试登录操作
+    private boolean tryToLoginGtask(Activity activity, String authToken) {
+        if (!loginGtask(authToken)) {
+            // 如果登录失败，可能是授权令牌过期了，先使其无效然后重新获取令牌再尝试登录
+            authToken = loginGoogleAccount(activity, true);
+            if (authToken == null) {
+                Log.e(TAG, "login google account failed");
+                return false;
+            }
+
+            if (!loginGtask(authToken)) {
+                Log.e(TAG, "login gtask failed");
+                return false;
+            }
+        }
+        return true;
+    }
+
+    // 实际执行登录到Google Tasks服务的具体操作，发送HTTP GET请求进行登录验证，获取相关的Cookie和客户端版本号等信息
+    private boolean loginGtask(String authToken) {
+        int timeoutConnection = 10000;
+        int timeoutSocket = 15000;
+        HttpParams httpParameters = new BasicHttpParams();
+        HttpConnectionParams.setConnectionTimeout(httpParameters, timeoutConnection);
+        HttpConnectionParams.setSoTimeout(httpParameters, timeoutSocket);
+        mHttpClient = new DefaultHttpClient(httpParameters);
+        BasicCookieStore localBasicCookieStore = new BasicCookieStore();
+        mHttpClient.setCookieStore(localBasicCookieStore);
+        HttpProtocolParams.setUseExpectContinue(mHttpClient.getParams(), false);
+
+        // 发送登录的GET请求
+        try {
+            String loginUrl = mGetUrl + "?auth=" + authToken;
+            HttpGet httpGet = new HttpGet(loginUrl);
+            HttpResponse response = null;
+            response = mHttpClient.execute(httpGet);
+
+            // 获取登录后返回的Cookie，检查是否包含认证相关的Cookie（例如查找名称包含"GTL"的Cookie）
+            List<Cookie> cookies = mHttpClient.getCookieStore().getCookies();
+            boolean hasAuthCookie = false;
+            for (Cookie cookie : cookies) {
+                if (cookie.getName().contains("GTL")) {
+                    hasAuthCookie = true;
+                }
+            }
+            if (!hasAuthCookie) {
+                Log.w(TAG, "it seems that there is no auth cookie");
+            }
+
+            // 从登录响应中获取客户端版本号，通过解析返回的HTML内容（提取其中包含版本号的JSON数据部分）来获取
+            String resString = getResponseContent(response.getEntity());
+            String jsBegin = "_setup(";
+            String jsEnd = ")}</script>";
+            int begin = resString.indexOf(jsBegin);
+            int end = resString.lastIndexOf(jsEnd);
+            String jsString = null;
+            if (begin!= -1 && end!= -1 && begin < end) {
+                jsString = resString.substring(begin + jsBegin.length(), end);
+            }
+            JSONObject js = new JSONObject(jsString);
+            mClientVersion = js.getLong("v");
+        } catch (JSONException e) {
+            Log.e(TAG, e.toString());
+            e.printStackTrace();
+            return false;
+        } catch (Exception e) {
+            // 简单捕获所有可能出现的异常情况，记录日志并返回登录失败
+            Log.e(TAG, "httpget gtask_url failed");
+            return false;
+        }
+
+        return true;
+    }
+
+    // 获取下一个操作的唯一ID，每次调用后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");
+        httpPost.setHeader("AT", "1");
+        return httpPost;
+    }
+
+    // 从给定的HttpEntity中获取响应内容的方法，处理内容的编码（如gzip、deflate等解压情况）并读取内容返回为字符串
+    private String getResponseContent(HttpEntity entity) throws IOException {
+        String contentEncoding = null;
+        if (entity.getContentEncoding()!= null) {
+            contentEncoding = entity.getContentEncoding().getValue();
+            Log.d(TAG, "encoding: " + contentEncoding);
+        }
+
+        InputStream input = entity.getContent();
+        if (contentEncoding!= null && contentEncoding.equalsIgnoreCase("gzip")) {
+            input = new GZIPInputStream(entity.getContent());
+        } else if (contentEncoding!= null && contentEncoding.equalsIgnoreCase("deflate")) {
+            Inflater inflater = new Inflater(true);
+            input = new InflaterInputStream(entity.getContent(), inflater);
+        }
+
+        try {
+            InputStreamReader isr = new InputStreamReader(input);
+            BufferedReader br = new BufferedReader(isr);
+            StringBuilder sb = new StringBuilder();
+
+            while (true) {
+                String buff = br.readLine();
+                if (buff == null) {
+                    return sb.toString();
+                }
+                sb = sb.append(buff);
+            }
+        } finally {
+            input.close();
+        }
+    }
+
+    // 发送POST请求并将响应内容转换为JSONObject的方法，处理请求发送、响应读取以及JSON解析等操作，若出现问题则抛出相应异常
+    private JSONObject postRequest(JSONObject js) throws NetworkFailureException {
+        if (!mLoggedin) {
+            Log.e(TAG, "please login first");
+            throw new ActionFailureException("not logged in");
+        }
+
+        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);
+
+            // 执行POST请求并获取响应
+            HttpResponse response = mHttpClient.execute(httpPost);
+            String jsString = getResponseContent(response.getEntity());
+            return new JSONObject(jsString);
+
+        } catch (ClientProtocolException e) {
+            Log.e(TAG, e.toString());
+            e.printStackTrace();
+            throw new NetworkFailureException("postRequest failed");
+        } catch (IOException e) {
+            Log.e(TAG, e.toString());
+            e.printStackTrace();
+            throw new NetworkFailureException("postRequest failed");
+        } catch (JSONException e) {
+            Log.e(TAG, e.toString());
+            e.printStackTrace();
+            throw new ActionFailureException("unable to convert response content to jsonobject");
+        } catch (Exception e) {
+            Log.e(TAG, e.toString());
+            e.printStackTrace();
+            throw new ActionFailureException("error occurs when posting request");
+        }
+    }
+
+    // 创建一个新的任务（Task）并提交到Google Tasks服务的方法，构建相应的请求JSON数据，发送请求后获取新任务的唯一ID并设置到任务对象中
+    public void createTask(Task task) throws NetworkFailureException {
+        commitUpdate();
+        try {
+            JSONObject jsPost = new JSONObject();
+            JSONArray actionList = new JSONArray();
+
+            // 添加创建任务的操作信息到操作列表中，使用任务对象生成对应的创建操作JSON数据
+            actionList.put(task.getCreateAction(getActionId()));
+            jsPost.put(GTaskStringUtils.GTASK_JSON_ACTION_LIST, actionList);
+
+            // 设置客户端版本号到请求JSON数据中
+            jsPost.put(GTaskStringUtils.GTASK_JSON_CLIENT_VERSION, mClientVersion);
+
+            // 发送POST请求并处理响应，获取新任务的ID并设置到任务对象中
+            JSONObject jsResponse = postRequest(jsPost);
+            JSONObject jsResult = (JSONObject) jsResponse.getJSONArray(
+                    GTaskStringUtils.GTASK_JSON_RESULTS).get(0);
+            task.setGid(jsResult.getString(GTaskStringUtils.GTASK_JSON_NEW_ID));
+
+        } catch (JSONException e) {
+            Log.e(TAG, e.toString());
+            e.printStackTrace();
+            throw new ActionFailureException("create task: handing jsonobject failed");
+        }
+    }
+
+    // 创建一个新的任务列表（TaskList）并提交到Google Tasks服务的方法，与创建任务类似，构建请求JSON数据，发送请求后获取新任务列表的唯一ID并设置到任务列表对象中
+    public void createTask

src/王焱铂的注释/GTaskManager.java

@@ -0,0 +1,385 @@
+/*
+ * 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.app.Activity;
+import android.content.ContentResolver;
+import android.content.ContentUris;
+import android.content.ContentValues;
+import android.content.Context;
+import android.database.Cursor;
+import android.util.Log;
+
+import net.micode.notes.R;
+import net.micode.notes.data.Notes;
+import net.micode.notes.data.Notes.DataColumns;
+import net.micode.notes.data.Notes.NoteColumns;
+import net.micode.notes.gtask.data.MetaData;
+import net.micode.notes.gtask.data.Node;
+import net.micode.notes.gtask.data.SqlNote;
+import net.micode.notes.gtask.data.Task;
+import net.micode.notes.gtask.data.TaskList;
+import net.micode.notes.gtask.exception.ActionFailureException;
+import net.micode.notes.gtask.exception.NetworkFailureException;
+import net.micode.notes.tool.DataUtils;
+import net.micode.notes.tool.GTaskStringUtils;
+
+import org.json.JSONArray;
+import org.json.JSONException;
+import org.json.JSONObject;
+
+import java.util.HashMap;
+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;
+    // 表示内部错误（如数据处理、JSON解析等错误）导致同步失败的状态码
+    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;
+
+    // 采用单例模式，保存GTaskManager的唯一实例
+    private static GTaskManager mInstance = null;
+
+    // 关联的Activity对象，可能用于获取授权令牌等相关操作
+    private Activity mActivity;
+    // 当前上下文环境，用于获取内容解析器等操作
+    private Context mContext;
+    // 用于与内容提供器进行交互，操作本地数据（如数据库查询、更新等）
+    private ContentResolver mContentResolver;
+    // 标记当前是否正在进行同步操作
+    private boolean mSyncing;
+    // 标记当前同步操作是否已被取消
+    private boolean mCancelled;
+    // 以任务列表的GID为键，存储从Google Tasks获取的任务列表对象的映射表
+    private HashMap<String, TaskList> mGTaskListHashMap;
+    // 以任务或任务列表等节点的GID为键，存储对应的节点对象的映射表
+    private HashMap<String, Node> mGTaskHashMap;
+    // 以相关GID为键，存储元数据对象的映射表，用于管理和同步元数据信息
+    private HashMap<String, MetaData> mMetaHashMap;
+    // 用于存储特定的元数据列表对象（可能是有特殊用途的元数据集合）
+    private TaskList mMetaList;
+    // 用于记录本地已删除的记录的ID集合，在同步过程中处理本地删除数据的相关逻辑时使用
+    private HashSet<Long> mLocalDeleteIdMap;
+    // 以任务或任务列表等节点的GID为键，映射到本地数据库中对应的记录ID的映射表
+    private HashMap<String, Long> mGidToNid;
+    // 以本地数据库中记录的ID为键，映射到对应的任务或任务列表等节点的GID的映射表
+    private HashMap<Long, String> mNidToGid;
+
+    // 私有构造函数，初始化GTaskManager实例的各个成员变量
+    private GTaskManager() {
+        mSyncing = false;
+        mCancelled = false;
+        mGTaskListHashMap = new HashMap<String, TaskList>();
+        mGTaskHashMap = new HashMap<String, Node>();
+        mMetaHashMap = new HashMap<String, MetaData>();
+        mMetaList = null;
+        mLocalDeleteIdMap = new HashSet<Long>();
+        mGidToNid = new HashMap<String, Long>();
+        mNidToGid = new HashMap<Long, String>();
+    }
+
+    // 静态方法，用于获取GTaskManager的单例实例，如果实例不存在则创建一个新的实例
+    public static synchronized GTaskManager getInstance() {
+        if (mInstance == null) {
+            mInstance = new 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");
+            return STATE_SYNC_IN_PROGRESS;
+        }
+        mContext = context;
+        mContentResolver = mContext.getContentResolver();
+        mSyncing = true;
+        mCancelled = false;
+        // 清除之前同步过程中缓存的数据结构，准备新的同步操作
+        mGTaskListHashMap.clear();
+        mGTaskHashMap.clear();
+        mMetaHashMap.clear();
+        mLocalDeleteIdMap.clear();
+        mGidToNid.clear();
+        mNidToGid.clear();
+
+        try {
+            GTaskClient client = GTaskClient.getInstance();
+            client.resetUpdateArray();
+
+            // 登录Google Tasks服务，如果取消标记为true则跳过登录操作，登录失败则抛出异常
+            if (!mCancelled) {
+                if (!client.login(mActivity)) {
+                    throw new NetworkFailureException("login google task failed");
+                }
+            }
+
+            // 发布同步进度信息，提示正在初始化任务列表
+            asyncTask.publishProgess(mContext.getString(R.string.sync_progress_init_list));
+            // 初始化从Google Tasks获取的任务列表相关数据
+            initGTaskList();
+
+            // 发布同步进度信息，提示正在进行内容同步
+            asyncTask.publishProgess(mContext.getString(R.string.sync_progress_syncing));
+            // 执行具体的内容同步操作，处理本地数据与远程数据的同步逻辑
+            syncContent();
+        } catch (NetworkFailureException e) {
+            Log.e(TAG, e.toString());
+            return STATE_NETWORK_ERROR;
+        } catch (ActionFailureException e) {
+            Log.e(TAG, e.toString());
+            return STATE_INTERNAL_ERROR;
+        } catch (Exception e) {
+            Log.e(TAG, e.toString());
+            e.printStackTrace();
+            return STATE_INTERNAL_ERROR;
+        } finally {
+            // 无论同步是否成功，最终都清除缓存的数据结构，并标记同步操作结束
+            mGTaskListHashMap.clear();
+            mGTaskHashMap.clear();
+            mMetaHashMap.clear();
+            mLocalDeleteIdMap.clear();
+            mGidToNid.clear();
+            mNidToGid.clear();
+            mSyncing = false;
+        }
+
+        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();
+
+            // 先初始化元数据列表相关数据，查找特定名称的元数据列表
+            mMetaList = null;
+            for (int i = 0; i < jsTaskLists.length(); i++) {
+                JSONObject object = jsTaskLists.getJSONObject(i);
+                String gid = object.getString(GTaskStringUtils.GTASK_JSON_ID);
+                String name = object.getString(GTaskStringUtils.GTASK_JSON_NAME);
+
+                if (name
+                        .equals(GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_META)) {
+                    mMetaList = new TaskList();
+                    mMetaList.setContentByRemoteJSON(object);
+
+                    // 加载元数据列表中的具体元数据对象
+                    JSONArray jsMetas = client.getTaskList(gid);
+                    for (int j = 0; j < jsMetas.length(); j++) {
+                        object = (JSONObject) jsMetas.getJSONObject(j);
+                        MetaData metaData = new MetaData();
+                        metaData.setContentByRemoteJSON(object);
+                        if (metaData.isWorthSaving()) {
+                            mMetaList.addChildTask(metaData);
+                            if (metaData.getGid()!= null) {
+                                mMetaHashMap.put(metaData.getRelatedGid(), metaData);
+                            }
+                        }
+                    }
+                }
+            }
+
+            // 如果元数据列表不存在，则创建一个新的元数据列表
+            if (mMetaList == null) {
+                mMetaList = new TaskList();
+                mMetaList.setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX
+                        + GTaskStringUtils.FOLDER_META);
+                GTaskClient.getInstance().createTaskList(mMetaList);
+            }
+
+            // 初始化普通任务列表相关数据，遍历任务列表JSON数据，创建任务列表对象并加载其中的任务对象
+            for (int i = 0; i < jsTaskLists.length(); i++) {
+                JSONObject object = jsTaskLists.getJSONObject(i);
+                String gid = object.getString(GTaskStringUtils.GTASK_JSON_ID);
+                String name = object.getString(GTaskStringUtils.GTASK_JSON_NAME);
+
+                if (name.startsWith(GTaskStringUtils.MIUI_FOLDER_PREFFIX)
+                        &&!name.equals(GTaskStringUtils.MIUI_FOLDER_PREFFIX
+                        + GTaskStringUtils.FOLDER_META)) {
+                    TaskList tasklist = new TaskList();
+                    tasklist.setContentByRemoteJSON(object);
+                    mGTaskListHashMap.put(gid, tasklist);
+                    mGTaskHashMap.put(gid, tasklist);
+
+                    // 加载任务列表中的具体任务数据
+                    JSONArray jsTasks = client.getTaskList(gid);
+                    for (int j = 0; j < jsTasks.length(); j++) {
+                        object = (JSONObject) jsTasks.getJSONObject(j);
+                        gid = object.getString(GTaskStringUtils.GTASK_JSON_ID);
+                        Task task = new Task();
+                        task.setContentByRemoteJSON(object);
+                        if (task.isWorthSaving()) {
+                            task.setMetaInfo(mMetaHashMap.get(gid));
+                            tasklist.addChildTask(task);
+                            mGTaskHashMap.put(gid, task);
+                        }
+                    }
+                }
+            }
+        } catch (JSONException e) {
+            Log.e(TAG, e.toString());
+            e.printStackTrace();
+            throw new ActionFailureException("initGTaskList: handing JSONObject failed");
+        }
+    }
+
+    // 执行具体的内容同步操作，处理本地数据与远程数据的同步逻辑，包括处理本地删除、文件夹同步、已有数据同步等多个方面
+    private void syncContent() throws NetworkFailureException {
+        int syncType;
+        Cursor c = null;
+        String gid;
+        Node node;
+
+        mLocalDeleteIdMap.clear();
+
+        if (mCancelled) {
+            return;
+        }
+
+        // 处理本地已删除的笔记数据，查询本地垃圾桶文件夹中的数据，根据与远程数据的对比进行相应的同步操作（如删除远程对应数据等）
+        try {
+            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)
+                    }, null);
+            if (c!= null) {
+                while (c.moveToNext()) {
+                    gid = c.getString(SqlNote.GTASK_ID_COLUMN);
+                    node = mGTaskHashMap.get(gid);
+                    if (node!= null) {
+                        mGTaskHashMap.remove(gid);
+                        doContentSync(Node.SYNC_ACTION_DEL_REMOTE, node, c);
+                    }
+
+                    mLocalDeleteIdMap.add(c.getLong(SqlNote.ID_COLUMN));
+                }
+            } else {
+                Log.w(TAG, "failed to query trash folder");
+            }
+        } finally {
+            if (c!= null) {
+                c.close();
+                c = null;
+            }
+        }
+
+        // 同步文件夹相关数据，包括根文件夹、通话记录文件夹以及本地存在的其他文件夹等与远程数据的同步操作
+        syncFolder();
+
+        // 处理本地数据库中存在的笔记数据，根据与远程数据的对比情况（如是否存在、是否有新增或删除等）进行相应的同步操作
+        try {
+            c = mContentResolver.query(Notes.CONTENT_NOTE_URI, SqlNote.PROJECTION_NOTE,
+                    "(type=? AND parent_id<>?)", new String[] {
+                            String.valueOf(Notes.TYPE_NOTE), String.valueOf(Notes.ID_TRASH_FOLER)
+                    }, NoteColumns.TYPE + " DESC");
+            if (c!= null) {
+                while (c.moveToNext()) {
+                    gid = c.getString(SqlNote.GTASK_ID_COLUMN);
+                    node = mGTaskHashMap.get(gid);
+                    if (node!= null) {
+                        mGTaskHashMap.remove(gid);
+                        mGidToNid.put(gid, c.getLong(SqlNote.ID_COLUMN));
+                        mNidToGid.put(c.getLong(SqlNote.ID_COLUMN), gid);
+                        syncType = node.getSyncAction(c);
+                    } else {
+                        if (c.getString(SqlNote.GTASK_ID_COLUMN).trim().length() == 0) {
+                            // 本地新增的情况
+                            syncType = Node.SYNC_ACTION_ADD_REMOTE;
+                        } else {
+                            // 远程已删除的情况
+                            syncType = Node.SYNC_ACTION_DEL_LOCAL;
+                        }
+                    }
+                    doContentSync(syncType, node, c);
+                }
+            } else {
+                Log.w(TAG, "failed to query existing note in database");
+            }
+
+        } finally {
+            if (c!= null) {
+                c.close();
+                c = null;
+            }
+        }
+
+        // 处理剩余的远程数据（在前面的同步过程中未处理到的远程存在但本地可能不存在的任务或任务列表等数据），进行相应的同步操作（如添加到本地等）
+        Iterator<Map.Entry<String, Node>> iter = mGTaskHashMap.entrySet().iterator();
+        while (iter.hasNext()) {
+            Map.Entry<String, Node> entry = iter.next();
+            node = entry.getValue();
+            doContentSync(Node.SYNC_ACTION_ADD_LOCAL, node, null);
+        }
+
+        // 由于取消操作可能在其他线程中设置，所以再次检查是否已取消，若未取消则清除本地已删除的数据记录
+        if (!mCancelled) {
+            if (!DataUtils.batchDeleteNotes(mContentResolver, mLocalDeleteIdMap)) {
+                throw new ActionFailureException("failed to batch-delete local deleted notes");
+            }
+        }
+
+        // 刷新本地同步ID相关信息，提交更新并进行相关的本地同步ID更新操作（基于远程最新数据来更新本地记录的同步ID）
+        if (!mCancelled) {
+            GTaskClient.getInstance().commitUpdate();
+            refreshLocalSyncId();
+        }
+
+    }
+
+    // 同步文件夹相关数据的具体方法，包括根文件夹、通话记录文件夹以及本地存在的其他文件夹等与远程数据的同步操作，处理添加、更新等不同情况
+    private void syncFolder() throws NetworkFailureException {
+        Cursor c = null;
+        String gid;
+        Node node;
+        int syncType;
+
+        if (mCancelled) {
+            return;
+        }
+
+        // 处理根文件夹的同步情况，查询本地根文件夹数据，根据与远程数据的对比进行相应的同步操作（如添加、更新等）
+        try {
+            c = mContentResolver.query(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI,
+                    Notes.ID_ROOT_FOLDER), SqlNote.PROJECTION_NOTE, null, null, null);
+            if (c!= null) {
+                c.moveToNext();
+                gid = c.getString(SqlNote.GTASK_ID_COLUMN);
+                node = mGTaskHashMap.get(gid);

src/王焱铂的注释/GTaskSyncService.java

@@ -0,0 +1,143 @@
+/*
+ * 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.app.Activity;
+import android.app.Service;
+import android.content.Context;
+import android.content.Intent;
+import android.os.Bundle;
+import android.os.IBinder;
+
+// GTaskSyncService类是一个Android服务，主要用于管理与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 = "";
+
+    // 私有方法，用于启动同步任务。如果当前没有正在执行的同步任务，则创建一个新的GTaskASyncTask实例，并设置任务完成监听器，然后执行该任务并发送广播通知同步开始
+    private void startSync() {
+        if (mSyncTask == null) {
+            mSyncTask = new GTaskASyncTask(this, new GTaskASyncTask.OnCompleteListener() {
+                // 当同步任务完成时的回调方法，在任务完成后将mSyncTask置为null，表示同步任务结束，发送一个空消息的广播，然后停止该服务自身
+                public void onComplete() {
+                    mSyncTask = null;
+                    sendBroadcast("");
+                    stopSelf();
+                }
+            });
+            sendBroadcast("");
+            mSyncTask.execute();
+        }
+    }
+
+    // 私有方法，用于取消正在进行的同步任务。如果当前存在正在执行的同步任务，则调用其cancelSync方法来取消任务
+    private void cancelSync() {
+        if (mSyncTask!= null) {
+            mSyncTask.cancelSync();
+        }
+    }
+
+    // 服务创建时调用的方法，在这里将mSyncTask初始化为null，准备后续的同步任务操作
+    @Override
+    public void onCreate() {
+        mSyncTask = null;
+    }
+
+    // 当服务接收到启动命令时调用的方法，根据传入的Intent中的额外数据（Extras）来判断同步操作类型，并执行相应的操作（启动或取消同步），最后返回服务的启动模式（START_STICKY表示服务在意外终止后会尝试重新启动）
+    @Override
+    public int onStartCommand(Intent intent, int flags, int startId) {
+        Bundle bundle = intent.getExtras();
+        if (bundle!= null && bundle.containsKey(ACTION_STRING_NAME)) {
+            switch (bundle.getInt(ACTION_STRING_NAME, ACTION_INVALID)) {
+                case ACTION_START_SYNC:
+                    startSync();
+                    break;
+                case ACTION_CANCEL_SYNC:
+                    cancelSync();
+                    break;
+                default:
+                    break;
+            }
+            return START_STICKY;
+        }
+        return super.onStartCommand(intent, flags, startId);
+    }
+
+    // 当系统内存不足时调用的方法，在这里如果存在正在执行的同步任务，则取消该任务，以释放内存资源
+    @Override
+    public void onLowMemory() {
+        if (mSyncTask!= null) {
+            mSyncTask.cancelSync();
+        }
+    }
+
+    // 用于绑定服务的方法，在这个服务中返回null，表示不支持绑定操作
+    public IBinder onBind(Intent intent) {
+        return null;
+    }
+
+    // 用于发送广播的方法，更新同步进度消息文本，创建一个包含同步是否正在进行以及进度消息的Intent，并通过系统发送广播，以便其他组件可以接收到同步相关的状态和进度信息
+    public void sendBroadcast(String msg) {
+        mSyncProgress = msg;
+        Intent intent = new Intent(GTASK_SERVICE_BROADCAST_NAME);
+        intent.putExtra(GTASK_SERVICE_BROADCAST_IS_SYNCING, mSyncTask!= null);
+        intent.putExtra(GTASK_SERVICE_BROADCAST_PROGRESS_MSG, msg);
+        sendBroadcast(intent);
+    }
+
+    // 静态方法，用于从外部（如Activity）启动同步任务。首先设置GTaskManager的Activity上下文，然后创建一个启动该服务并指定同步操作为启动同步的Intent，最后通过Activity启动该服务
+    public static void startSync(Activity activity) {
+        GTaskManager.getInstance().setActivityContext(activity);
+        Intent intent = new Intent(activity, GTaskSyncService.class);
+        intent.putExtra(GTaskSyncService.ACTION_STRING_NAME, GTaskSyncService.ACTION_START_SYNC);
+        activity.startService(intent);
+    }
+
+    // 静态方法，用于从外部（如其他组件）取消同步任务。创建一个启动该服务并指定同步操作为取消同步的Intent，然后通过上下文启动该服务来执行取消同步操作
+    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);
+    }
+
+    // 静态方法，用于查询当前是否正在进行同步任务，通过判断mSyncTask是否为null来返回同步是否正在进行的状态（true表示正在进行，false表示未进行）
+    public static boolean isSyncing() {
+        return mSyncTask!= null;
+    }
+
+    // 静态方法，用于获取当前的同步进度消息文本，返回保存同步进度信息的mSyncProgress变量的值
+    public static String getProgressString() {
+        return mSyncProgress;
+    }
+}

src/王焱铂的注释/Note.java

@@ -0,0 +1,362 @@
+/*
+ * 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.model;
+
+import android.content.ContentProviderOperation;
+import android.content.ContentProviderResult;
+import android.content.ContentUris;
+import android.content.ContentValues;
+import android.content.Context;
+import android.content.OperationApplicationException;
+import android.net.Uri;
+import android.os.RemoteException;
+import android.util.Log;
+
+import net.micode.notes.data.Notes;
+import net.micode.notes.data.Notes.CallNote;
+import net.micode.notes.data.Notes.DataColumns;
+import net.micode.notes.data.Notes.NoteColumns;
+import net.micode.notes.data.Notes.TextNote;
+
+import java.util.ArrayList;
+
+// Note类用于表示笔记相关的数据和操作，包括创建新笔记、设置笔记的各种属性值以及将笔记数据同步到内容提供器（通常对应数据库存储）等功能
+public class Note {
+    // 用于存储笔记中发生变化的内容值，通过ContentValues来表示，方便后续更新操作时使用
+    private ContentValues mNoteDiffValues;
+    // 内部类NoteData的实例，用于管理笔记中更具体的数据部分（如文本数据、通话数据等）
+    private NoteData mNoteData;
+    // 用于日志记录的标签，方便在日志中识别该类相关的输出信息，值为"Note"
+    private static final String TAG = "Note";
+
+    /**
+     * 静态方法，用于创建一个新的笔记ID并在数据库中插入一条新笔记记录，返回新创建笔记的ID。
+     * 插入的笔记记录会设置一些初始的属性值，如创建时间、修改时间、笔记类型等。
+     *
+     * @param context 上下文环境，用于获取内容解析器来操作数据库
+     * @param folderId 新笔记所属的文件夹ID，用于设置笔记的父文件夹关系
+     * @return 新创建笔记的ID，如果创建过程出现问题可能返回0或抛出异常
+     */
+    public static synchronized long getNewNoteId(Context context, long folderId) {
+        // 创建一个ContentValues对象，用于存储要插入数据库的笔记记录的初始值
+        ContentValues values = new ContentValues();
+        long createdTime = System.currentTimeMillis();
+        // 设置笔记的创建时间
+        values.put(NoteColumns.CREATED_DATE, createdTime);
+        // 设置笔记的修改时间，初始值与创建时间相同
+        values.put(NoteColumns.MODIFIED_DATE, createdTime);
+        // 设置笔记的类型为普通笔记（Notes.TYPE_NOTE应该是定义好的表示普通笔记类型的常量）
+        values.put(NoteColumns.TYPE, Notes.TYPE_NOTE);
+        // 标记笔记在本地有修改（初始设置为1，后续根据实际情况更新）
+        values.put(NoteColumns.LOCAL_MODIFIED, 1);
+        // 设置笔记所属的父文件夹ID
+        values.put(NoteColumns.PARENT_ID, folderId);
+
+        // 通过内容解析器将新笔记记录插入到指定的数据库表中（Notes.CONTENT_NOTE_URI应该是对应笔记表的内容URI）
+        Uri uri = context.getContentResolver().insert(Notes.CONTENT_NOTE_URI, values);
+
+        long noteId = 0;
+        try {
+            // 从插入后返回的URI中提取出笔记的ID（假设URI的路径段中包含了笔记ID信息）
+            noteId = Long.valueOf(uri.getPathSegments().get(1));
+        } catch (NumberFormatException e) {
+            Log.e(TAG, "Get note id error :" + e.toString());
+            noteId = 0;
+        }
+        if (noteId == -1) {
+            throw new IllegalStateException("Wrong note id:" + noteId);
+        }
+        return noteId;
+    }
+
+    // 构造函数，用于初始化Note类的实例，创建用于存储笔记变化值的ContentValues对象和NoteData对象
+    public Note() {
+        mNoteDiffValues = new ContentValues();
+        mNoteData = new NoteData();
+    }
+
+    /**
+     * 设置笔记的某个属性值，将给定的键值对存入mNoteDiffValues中，并同时更新笔记的本地修改标记和修改时间。
+     * 表示该属性值发生了变化，后续可能需要同步到数据库中。
+     *
+     * @param key 要设置的属性键，对应数据库表中的列名等
+     * @param value 要设置的属性值
+     */
+    public void setNoteValue(String key, String value) {
+        mNoteDiffValues.put(key, value);
+        mNoteDiffValues.put(NoteColumns.LOCAL_MODIFIED, 1);
+        mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis());
+    }
+
+    /**
+     * 设置笔记的文本数据部分的某个属性值，实际上是调用内部类NoteData的相应方法来设置。
+     * 同时也会更新笔记的本地修改标记和修改时间，表明文本数据有变化。
+     *
+     * @param key 文本数据的属性键，对应相关数据表中的列名等
+     * @param value 要设置的文本数据属性值
+     */
+    public void setTextData(String key, String value) {
+        mNoteData.setTextData(key, value);
+    }
+
+    /**
+     * 设置笔记的文本数据部分的ID，通过调用内部类NoteData的相应方法来设置。
+     *
+     * @param id 要设置的文本数据ID
+     */
+    public void setTextDataId(long id) {
+        mNoteData.setTextDataId(id);
+    }
+
+    /**
+     * 获取笔记的文本数据部分的ID，返回内部类NoteData中存储的文本数据ID值。
+     *
+     * @return 笔记的文本数据ID
+     */
+    public long getTextDataId() {
+        return mNoteData.mTextDataId;
+    }
+
+    /**
+     * 设置笔记的通话数据部分的ID，通过调用内部类NoteData的相应方法来设置。
+     *
+     * @param id 要设置的通话数据ID
+     */
+    public void setCallDataId(long id) {
+        mNoteData.setCallDataId(id);
+    }
+
+    /**
+     * 设置笔记的通话数据部分的某个属性值，实际上是调用内部类NoteData的相应方法来设置。
+     * 同时也会更新笔记的本地修改标记和修改时间，表明通话数据有变化。
+     *
+     * @param key 通话数据的属性键，对应相关数据表中的列名等
+     * @param value 要设置的通话数据属性值
+     */
+    public void setCallData(String key, String value) {
+        mNoteData.setCallData(key, value);
+    }
+
+    /**
+     * 判断笔记是否在本地有修改，通过检查mNoteDiffValues（存储笔记属性变化值）和mNoteData（存储更具体数据部分变化情况）是否有变化来确定。
+     * 如果二者中任意一个有变化，则表示笔记在本地有修改。
+     *
+     * @return true表示笔记在本地有修改，false表示没有修改
+     */
+    public boolean isLocalModified() {
+        return mNoteDiffValues.size() > 0 || mNoteData.isLocalModified();
+    }
+
+    /**
+     * 将笔记数据同步到内容提供器（通常对应数据库）中，根据笔记是否有本地修改以及传入的笔记ID来执行相应的更新操作。
+     * 如果笔记没有本地修改则直接返回true，表示无需同步；如果更新笔记属性或相关数据操作失败则返回false，表示同步失败。
+     *
+     * @param context 上下文环境，用于获取内容解析器来操作数据库
+     * @param noteId 要同步的笔记的ID
+     * @return true表示同步成功，false表示同步失败
+     */
+    public boolean syncNote(Context context, long noteId) {
+        if (noteId <= 0) {
+            throw new IllegalArgumentException("Wrong note id:" + noteId);
+        }
+
+        if (!isLocalModified()) {
+            return true;
+        }
+
+        /**
+         * 在理论上，一旦笔记数据发生变化，应该在{@link NoteColumns#LOCAL_MODIFIED}和
+         * {@link NoteColumns#MODIFIED_DATE}字段上进行更新。为了数据安全，即使更新笔记操作失败，我们也要更新笔记数据信息。
+         */
+        if (context.getContentResolver().update(
+                ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId), mNoteDiffValues, null,
+                null) == 0) {
+            Log.e(TAG, "Update note error, should not happen");
+            // 即使更新笔记操作失败，也不直接返回，继续执行后续的数据更新操作（比如更新文本数据、通话数据等相关操作）
+        }
+        mNoteDiffValues.clear();
+
+        if (mNoteData.isLocalModified()
+                && (mNoteData.pushIntoContentResolver(context, noteId) == null)) {
+            return false;
+        }
+
+        return true;
+    }
+
+    // 内部类NoteData，用于管理笔记中更具体的数据部分，包括文本数据和通话数据的相关属性值、ID以及操作这些数据与内容提供器交互的方法等
+    private class NoteData {
+        // 存储文本数据部分的ID
+        private long mTextDataId;
+        // 用于存储文本数据的属性值，对应数据库表中的相关列，方便后续插入或更新操作
+        private ContentValues mTextDataValues;
+        // 存储通话数据部分的ID
+        private long mCallDataId;
+        // 用于存储通话数据的属性值，对应数据库表中的相关列，方便后续插入或更新操作
+        private ContentValues mCallDataValues;
+        // 用于日志记录的标签，方便在日志中识别该内部类相关的输出信息，值为"NoteData"
+        private static final String TAG = "NoteData";
+
+        // 构造函数，用于初始化NoteData类的实例，创建用于存储文本数据和通话数据属性值的ContentValues对象，并将数据ID初始化为0
+        public NoteData() {
+            mTextDataValues = new ContentValues();
+            mCallDataValues = new ContentValues();
+            mTextDataId = 0;
+            mCallDataId = 0;
+        }
+
+        /**
+         * 判断文本数据或通话数据是否有本地修改，通过检查相应的ContentValues对象是否有值来确定。
+         * 如果二者中任意一个ContentValues对象有值，则表示对应的数据有本地修改。
+         *
+         * @return true表示有本地修改，false表示没有修改
+         */
+        boolean isLocalModified() {
+            return mTextDataValues.size() > 0 || mCallDataValues.size() > 0;
+        }
+
+        /**
+         * 设置文本数据部分的ID，同时进行参数合法性检查，如果传入的ID小于等于0则抛出异常。
+         *
+         * @param id 要设置的文本数据ID
+         */
+        void setTextDataId(long id) {
+            if (id <= 0) {
+                throw new IllegalArgumentException("Text data id should larger than 0");
+            }
+            mTextDataId = id;
+        }
+
+        /**
+         * 设置通话数据部分的ID，同时进行参数合法性检查，如果传入的ID小于等于0则抛出异常。
+         *
+         * @param id 要设置的通话数据ID
+         */
+        void setCallDataId(long id) {
+            if (id <= 0) {
+                throw new IllegalArgumentException("Call data id should larger than 0");
+            }
+            mCallDataId = id;
+        }
+
+        /**
+         * 设置通话数据部分的某个属性值，将给定的键值对存入mCallDataValues中，并同时更新笔记的本地修改标记和修改时间。
+         * 表示通话数据的该属性值发生了变化，后续可能需要同步到数据库中。
+         *
+         * @param key 要设置的通话数据属性键，对应数据库表中的列名等
+         * @param value 要设置的通话数据属性值
+         */
+        void setCallData(String key, String value) {
+            mCallDataValues.put(key, value);
+            mNoteDiffValues.put(NoteColumns.LOCAL_MODIFIED, 1);
+            mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis());
+        }
+
+        /**
+         * 设置文本数据部分的某个属性值，将给定的键值对存入mTextDataValues中，并同时更新笔记的本地修改标记和修改时间。
+         * 表示文本数据的该属性值发生了变化，后续可能需要同步到数据库中。
+         *
+         * @param key 要设置的文本数据属性键，对应数据库表中的列名等
+         * @param value 要设置的文本数据属性值
+         */
+        void setTextData(String key, String value) {
+            mTextDataValues.put(key, value);
+            mNoteDiffValues.put(NoteColumns.LOCAL_MODIFIED, 1);
+            mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis());
+        }
+
+        /**
+         * 将文本数据和通话数据（如果有变化）通过内容提供器操作批量应用到数据库中，根据数据的ID情况进行插入或更新操作。
+         * 如果数据ID为0则表示是新数据，执行插入操作；如果数据ID不为0则执行更新操作。
+         *
+         * @param context 上下文环境，用于获取内容解析器来操作数据库
+         * @param noteId 要操作的笔记的ID，用于关联数据与笔记的关系（设置外键等）
+         * @return 如果操作成功且有结果返回，返回对应笔记的内容URI（通过ContentUris.withAppendedId生成），否则返回null表示操作失败
+         */
+        Uri pushIntoContentResolver(Context context, long noteId) {
+            /**
+             * 进行参数合法性检查，如果笔记ID小于等于0则抛出异常，因为无法确定要操作的笔记对象。
+             */
+            if (noteId <= 0) {
+                throw new IllegalArgumentException("Wrong note id:" + noteId);
+            }
+
+            ArrayList<ContentProviderOperation> operationList = new ArrayList<ContentProviderOperation>();
+            ContentProviderOperation.Builder builder = null;
+
+            if (mTextDataValues.size() > 0) {
+                mTextDataValues.put(DataColumns.NOTE_ID, noteId);
+                if (mTextDataId == 0) {
+                    mTextDataValues.put(DataColumns.MIME_TYPE, TextNote.CONTENT_ITEM_TYPE);
+                    Uri uri = context.getContentResolver().insert(Notes.CONTENT_DATA_URI,
+                            mTextDataValues);
+                    try {
+                        setTextDataId(Long.valueOf(uri.getPathSegments().get(1)));
+                    } catch (NumberFormatException e) {
+                        Log.e(TAG, "Insert new text data fail with noteId" + noteId);
+                        mTextDataValues.clear();
+                        return null;
+                    }
+                } else {
+                    builder = ContentProviderOperation.newUpdate(ContentUris.withAppendedId(
+                            Notes.CONTENT_DATA_URI, mTextDataId));
+                    builder.withValues(mTextDataValues);
+                    operationList.add(builder.build());
+                }
+                mTextDataValues.clear();
+            }
+
+            if (mCallDataValues.size() > 0) {
+                mCallDataValues.put(DataColumns.NOTE_ID, noteId);
+                if (mCallDataId == 0) {
+                    mCallDataValues.put(DataColumns.MIME_TYPE, CallNote.CONTENT_ITEM_TYPE);
+                    Uri uri = context.getContentResolver().insert(Notes.CONTENT_DATA_URI,
+                            mCallDataValues);
+                    try {
+                        setCallDataId(Long.valueOf(uri.getPathSegments().get(1)));
+                    } catch (NumberFormatException e) {
+                        Log.e(TAG, "Insert new call data fail with noteId" + noteId);
+                        mCallDataValues.clear();
+                        return null;
+                    }
+                } else {
+                    builder = ContentProviderOperation.newUpdate(ContentUris.withAppendedId(
+                            Notes.CONTENT_DATA_URI, mCallDataId));
+                    builder.withValues(mCallDataValues);
+                    operationList.add(builder.build());
+                }
+                mCallDataValues.clear();
+            }
+
+            if (operationList.size() > 0) {
+                try {
+                    ContentProviderResult[] results = context.getContentResolver().applyBatch(
+                            Notes.AUTHORITY, operationList);
+                    return (results == null || results.length == 0 || results[0] == null)? null
+                            : ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId);
+                } catch (RemoteException e) {
+                    Log.e(TAG, String.format("%s: %s", e.toString(), e.getMessage()));
+                    return null;
+                } catch (OperationApplicationException e) {
+                    Log.e(TAG, String.format("%s: %s", e.toString(), e.getMessage()));
+                    return null;
+                }
+            }
+            return null;
+        }
+    }
+}