代码精精读报告

doc/标注/210340069_申佃东/GTaskASyncTask.java

@@ -0,0 +1,136 @@
+
+/*
+ * 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;
+/*异步操作类，实现GTask的异步操作过程
+ * 主要方法：
+ * private void showNotification(int tickerId, String content) 向用户提示当前同步的状态，是一个用于交互的方法
+ * protected Integer doInBackground(Void... unused) 此方法在后台线程执行，完成任务的主要工作，通常需要较长的时间
+ * protected void onProgressUpdate(String... progress)  可以使用进度条增加用户体验度。 此方法在主线程执行，用于显示任务执行的进度。
+ * protected void onPostExecute(Integer result)  相当于Handler 处理UI的方式，在这里面可以使用在doInBackground 得到的结果处理操作UI
+ */
+public class GTaskASyncTask extends AsyncTask<Void, String, Integer> {
+//扩展了“AsyncTask”类,用于异步执行后台任务，并使用进度更新更新 UI 线程。
+    private static int GTASK_SYNC_NOTIFICATION_ID = 5234235;
+//用于标识与此 AsyncTask 相关的通知。
+    public interface OnCompleteListener {
+        void onComplete();
+    }
+
+    private Context mContext;
+
+    private NotificationManager mNotifiManager;
+
+    private GTaskManager mTaskManager;
+
+    private OnCompleteListener mOnCompleteListener;
+//提供了一种在单独线程中执行长时间运行的操作的便捷方法，同时保持 UI 响应并在工作完成时通知调用代码。
+    public GTaskASyncTask(Context context, OnCompleteListener listener) {
+        mContext = context;
+        mOnCompleteListener = listener;
+        mNotifiManager = (NotificationManager) mContext
+                .getSystemService(Context.NOTIFICATION_SERVICE);
+        mTaskManager = GTaskManager.getInstance();
+    }
+//调用实例变量“mTaskManager”的“cancelSync（）”方法，取消同步任务
+    public void cancelSync() {
+        mTaskManager.cancelSync();
+    }
+//发布进度单位，系统会调用onProgressUpdate()方法更新这些值
+    public void publishProgess(String message) {
+        publishProgress(new String[] {
+            message
+        });
+    }
+
+    private void showNotification(int tickerId, String content) {
+        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.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=builder.getNotification();
+        mNotifiManager.notify(GTASK_SYNC_NOTIFICATION_ID, notification);
+    }
+
+
+
+    @Override
+    protected Integer doInBackground(Void... unused) {
+        publishProgess(mContext.getString(R.string.sync_progress_login, NotesPreferenceActivity
+                .getSyncAccountName(mContext)));//利用getString
+        // 把 NotesPreferenceActivity.getSyncAccountName(mContext))的字符串内容传进sync_progress_login中
+
+        return mTaskManager.sync(mContext, this);//进行后台同步具体操作
+    }
+
+    @Override
+    protected void onProgressUpdate(String... progress) {
+        showNotification(R.string.ticker_syncing, progress[0]);
+        if (mContext instanceof GTaskSyncService) {//instanceof判断mContext是否是GTaskSyncService的实例
+            ((GTaskSyncService) mContext).sendBroadcast(progress[0]);
+        }
+    }
+
+    @Override
+    protected void onPostExecute(Integer result) {//用于在执行完后台任务后更新UI，显示结果
+        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();
+                }//完成后的操作，使用onComplete()将所有值都重新初始化，相当于完成一次操作
+            }).start();
+        }
+    }
+}

doc/标注/210340069_申佃东/NoteEditText.java

@@ -0,0 +1,270 @@
+package net.micode.notes.ui;
+ 
+import android.content.Context;
+import android.graphics.Rect;
+import android.text.Layout;
+import android.text.Selection;
+import android.text.Spanned;
+import android.text.TextUtils;
+import android.text.style.URLSpan;
+import android.util.AttributeSet;
+import android.util.Log;
+import android.view.ContextMenu;
+import android.view.KeyEvent;
+import android.view.MenuItem;
+import android.view.MenuItem.OnMenuItemClickListener;
+import android.view.MotionEvent;
+import android.widget.EditText;
+ 
+import net.micode.notes.R;
+ 
+import java.util.HashMap;
+import java.util.Map;
+ 
+//继承edittext，设置便签设置文本框
+public class NoteEditText extends EditText {  
+    private static final String TAG = "NoteEditText";
+    private int mIndex;
+    private int mSelectionStartBeforeDelete;
+ 
+    private static final String SCHEME_TEL = "tel:" ;
+    private static final String SCHEME_HTTP = "http:" ;
+    private static final String SCHEME_EMAIL = "mailto:" ;
+    
+    ///建立一个字符和整数的hash表，用于链接电话，网站，还有邮箱
+    private static final Map<String, Integer> sSchemaActionResMap = new HashMap<String, Integer>();
+    static {
+        sSchemaActionResMap.put(SCHEME_TEL, R.string.note_link_tel);
+        sSchemaActionResMap.put(SCHEME_HTTP, R.string.note_link_web);
+        sSchemaActionResMap.put(SCHEME_EMAIL, R.string.note_link_email);
+    }
+ 
+    /**
+     * Call by the {@link NoteEditActivity} to delete or add edit text
+     */
+   //在NoteEditActivity中删除或添加文本的操作，可以看做是一个文本是否被变的标记，英文注释已说明的很清楚
+    public interface OnTextViewChangeListener {
+        /**
+         * Delete current edit text when {@link KeyEvent#KEYCODE_DEL} happens
+         * and the text is null
+         */
+    	//处理删除按键时的操作
+        void onEditTextDelete(int index, String text);
+ 
+        /**
+         * Add edit text after current edit text when {@link KeyEvent#KEYCODE_ENTER}
+         * happen
+         */
+        //处理进入按键时的操作
+        void onEditTextEnter(int index, String text);
+ 
+        /**
+         * Hide or show item option when text change
+         */
+        void onTextChange(int index, boolean hasText);
+    }
+ 
+    private OnTextViewChangeListener mOnTextViewChangeListener;
+ 
+    //根据context设置文本
+    public NoteEditText(Context context) {
+        super(context, null);//用super引用父类变量
+        mIndex = 0;
+    }
+ 
+    //设置当前光标
+    public void setIndex(int index) {
+        mIndex = index;
+    }
+    
+    //初始化文本修改标记
+    public void setOnTextViewChangeListener(OnTextViewChangeListener listener) {
+        mOnTextViewChangeListener = listener;
+    }
+ 
+    //AttributeSet 百度了一下是自定义空控件属性，用于维护便签动态变化的属性
+    //初始化便签
+    public NoteEditText(Context context, AttributeSet    attrs) {
+        super(context, attrs, android.R.attr.editTextStyle);
+    }
+ 
+    // 根据defstyle自动初始化
+    public NoteEditText(Context context, AttributeSet attrs, int defStyle) {
+        super(context, attrs, defStyle);
+        // TODO Auto-generated construct or stub
+    } 
+ 
+    @Override
+    //view里的函数，处理手机屏幕的所有事件
+    /*参数event为手机屏幕触摸事件封装类的对象，其中封装了该事件的所有信息，
+                例如触摸的位置、触摸的类型以及触摸的时间等。该对象会在用户触摸手机屏幕时被创建。*/
+    public boolean onTouchEvent(MotionEvent event) {
+        switch (event.getAction()) {
+        //重写了需要处理屏幕被按下的事件
+            case MotionEvent.ACTION_DOWN:
+            	//跟新当前坐标值
+                int x = (int) event.getX();
+                int y = (int) event.getY();
+                x -= getTotalPaddingLeft();
+                y -= getTotalPaddingTop();
+                x += getScrollX();
+                y += getScrollY();
+                
+                //用布局控件layout根据x,y的新值设置新的位置
+                Layout layout = getLayout();
+                int line = layout.getLineForVertical(y);
+                int off = layout.getOffsetForHorizontal(line, x);
+                
+                //更新光标新的位置
+                Selection.setSelection(getText(), off);
+                break;
+        }
+ 
+        return super.onTouchEvent(event);
+    }
+ 
+    @Override
+    /*
+     * 函数功能：处理用户按下一个键盘按键时会触发 的事件
+     * 实现过程：如下注释
+     */
+    public boolean onKeyDown(int keyCode, KeyEvent event) {
+        switch (keyCode) {
+           //根据按键的 Unicode 编码值来处理
+            case KeyEvent.KEYCODE_ENTER:
+            	//“进入”按键
+                if (mOnTextViewChangeListener != null) {
+                    return false;
+                }
+                break;
+            case KeyEvent.KEYCODE_DEL:
+            	//“删除”按键
+                mSelectionStartBeforeDelete = getSelectionStart();
+                break;
+            default:
+                break;
+        }
+      //继续执行父类的其他点击事件
+        return super.onKeyDown(keyCode, event);
+    }
+ 
+    @Override
+    /*
+     * 函数功能：处理用户松开一个键盘按键时会触发 的事件
+     * 实现方式：如下注释
+     */
+    public boolean onKeyUp(int keyCode, KeyEvent event) {
+        switch(keyCode) {
+        //根据按键的 Unicode 编码值来处理，有删除和进入2种操作
+            case KeyEvent.KEYCODE_DEL:
+                if (mOnTextViewChangeListener != null) {
+                	//若是被修改过
+                    if (0 == mSelectionStartBeforeDelete && mIndex != 0) {
+                    	//若之前有被修改并且文档不为空
+                        mOnTextViewChangeListener.onEditTextDelete(mIndex, getText().toString());
+                        //利用上文OnTextViewChangeListener对KEYCODE_DEL按键情况的删除函数进行删除
+                        return true;
+                    }
+                } else {
+                    Log.d(TAG, "OnTextViewChangeListener was not seted");
+                    //其他情况报错，文档的改动监听器并没有建立
+                }
+                break;
+            case KeyEvent.KEYCODE_ENTER:
+            	//同上也是分为监听器是否建立2种情况
+                if (mOnTextViewChangeListener != null) {
+                    int selectionStart = getSelectionStart();
+                    //获取当前位置
+                    String text = getText().subSequence(selectionStart, length()).toString();
+                    //获取当前文本
+                    setText(getText().subSequence(0, selectionStart));
+                    //根据获取的文本设置当前文本
+                    mOnTextViewChangeListener.onEditTextEnter(mIndex + 1, text);
+                    //当{@link KeyEvent#KEYCODE_ENTER}添加新文本 
+                } else {
+                    Log.d(TAG, "OnTextViewChangeListener was not seted");
+                  //其他情况报错，文档的改动监听器并没有建立
+                }
+                break;
+            default:
+                break;
+        }
+        //继续执行父类的其他按键弹起的事件
+        return super.onKeyUp(keyCode, event);
+    }
+ 
+    @Override
+    /*
+     * 函数功能：当焦点发生变化时，会自动调用该方法来处理焦点改变的事件
+     * 实现方式：如下注释
+     * 参数：focused表示触发该事件的View是否获得了焦点，当该控件获得焦点时，Focused等于true，否则等于false。
+           direction表示焦点移动的方向，用数值表示
+           Rect：表示在触发事件的View的坐标系中，前一个获得焦点的矩形区域，即表示焦点是从哪里来的。如果不可用则为null
+     */
+    protected void onFocusChanged(boolean focused, int direction, Rect previouslyFocusedRect) {
+    	if (mOnTextViewChangeListener != null) {
+    		//若监听器已经建立
+            if (!focused && TextUtils.isEmpty(getText())) {
+            	//获取到焦点并且文本不为空
+                mOnTextViewChangeListener.onTextChange(mIndex, false);
+                //mOnTextViewChangeListener子函数，置false隐藏事件选项
+            } else {
+                mOnTextViewChangeListener.onTextChange(mIndex, true);
+              //mOnTextViewChangeListener子函数，置true显示事件选项
+            }
+        }
+    	//继续执行父类的其他焦点变化的事件
+        super.onFocusChanged(focused, direction, previouslyFocusedRect);
+    }
+ 
+    @Override
+    /*
+     * 函数功能：生成上下文菜单
+     * 函数实现：如下注释
+     */
+    protected void onCreateContextMenu(ContextMenu menu) {
+        if (getText() instanceof Spanned) {
+        	//有文本存在
+            int selStart = getSelectionStart();
+            int selEnd = getSelectionEnd();
+            //获取文本开始和结尾位置
+ 
+            int min = Math.min(selStart, selEnd);
+            int max = Math.max(selStart, selEnd);
+            //获取开始到结尾的最大值和最小值
+            
+            final URLSpan[] urls = ((Spanned) getText()).getSpans(min, max, URLSpan.class);
+            //设置url的信息的范围值
+            if (urls.length == 1) {
+                int defaultResId = 0;
+                for(String schema: sSchemaActionResMap.keySet()) {
+                	//获取计划表中所有的key值
+                    if(urls[0].getURL().indexOf(schema) >= 0) {
+                    	//若url可以添加则在添加后将defaultResId置为key所映射的值
+                        defaultResId = sSchemaActionResMap.get(schema);
+                        break;
+                    }
+                }
+ 
+                if (defaultResId == 0) {
+                	//defaultResId == 0则说明url并没有添加任何东西，所以置为连接其他SchemaActionResMap的值
+                    defaultResId = R.string.note_link_other;
+                }
+ 
+                //建立菜单
+                menu.add(0, 0, 0, defaultResId).setOnMenuItemClickListener(
+                        new OnMenuItemClickListener() {
+                        	//新建按键监听器
+                            public boolean onMenuItemClick(MenuItem item) {
+                                // goto a new intent
+                                urls[0].onClick(NoteEditText.this);
+                                //根据相应的文本设置菜单的按键
+                                return true;
+                            }
+                        });
+            }
+        }
+      //继续执行父类的其他菜单创建的事件
+        super.onCreateContextMenu(menu);
+    }
+}

doc/标注/210340069_申佃东/NoteItemData.java

@@ -0,0 +1,214 @@
+package net.micode.notes.ui;
+ 
+import android.content.Context;
+import android.database.Cursor;
+import android.text.TextUtils;
+ 
+import net.micode.notes.data.Contact;
+import net.micode.notes.data.Notes;
+import net.micode.notes.data.Notes.NoteColumns;
+import net.micode.notes.tool.DataUtils;
+ 
+ 
+public class NoteItemData {
+    static final String [] PROJECTION = new String [] {
+        NoteColumns.ID,
+        NoteColumns.ALERTED_DATE,
+        NoteColumns.BG_COLOR_ID,
+        NoteColumns.CREATED_DATE,
+        NoteColumns.HAS_ATTACHMENT,
+        NoteColumns.MODIFIED_DATE,
+        NoteColumns.NOTES_COUNT,
+        NoteColumns.PARENT_ID,
+        NoteColumns.SNIPPET,
+        NoteColumns.TYPE,
+        NoteColumns.WIDGET_ID,
+        NoteColumns.WIDGET_TYPE,
+    };
+    //常量标记和数据就不一一标记了，意义翻译基本就知道
+    private static final int ID_COLUMN                    = 0;
+    private static final int ALERTED_DATE_COLUMN          = 1;
+    private static final int BG_COLOR_ID_COLUMN           = 2;
+    private static final int CREATED_DATE_COLUMN          = 3;
+    private static final int HAS_ATTACHMENT_COLUMN        = 4;
+    private static final int MODIFIED_DATE_COLUMN         = 5;
+    private static final int NOTES_COUNT_COLUMN           = 6;
+    private static final int PARENT_ID_COLUMN             = 7;
+    private static final int SNIPPET_COLUMN               = 8;
+    private static final int TYPE_COLUMN                  = 9;
+    private static final int WIDGET_ID_COLUMN             = 10;
+    private static final int WIDGET_TYPE_COLUMN           = 11;
+ 
+    private long mId;
+    private long mAlertDate;
+    private int mBgColorId;
+    private long mCreatedDate;
+    private boolean mHasAttachment;
+    private long mModifiedDate;
+    private int mNotesCount;
+    private long mParentId;
+    private String mSnippet;
+    private int mType;
+    private int mWidgetId;
+    private int mWidgetType;
+    private String mName;
+    private String mPhoneNumber;
+ 
+    private boolean mIsLastItem;
+    private boolean mIsFirstItem;
+    private boolean mIsOnlyOneItem;
+    private boolean mIsOneNoteFollowingFolder;
+    private boolean mIsMultiNotesFollowingFolder;
+    //初始化NoteItemData，主要利用光标cursor获取的东西
+    public NoteItemData(Context context, Cursor  cursor) {
+    	//getxxx为转换格式
+        mId = cursor.getLong(ID_COLUMN);
+        mAlertDate = cursor.getLong(ALERTED_DATE_COLUMN);
+        mBgColorId = cursor.getInt(BG_COLOR_ID_COLUMN);
+        mCreatedDate = cursor.getLong(CREATED_DATE_COLUMN);
+        mHasAttachment = (cursor.getInt(HAS_ATTACHMENT_COLUMN) > 0) ? true : false;
+        mModifiedDate = cursor.getLong(MODIFIED_DATE_COLUMN);
+        mNotesCount = cursor.getInt(NOTES_COUNT_COLUMN);
+        mParentId = cursor.getLong(PARENT_ID_COLUMN);
+        mSnippet = cursor.getString(SNIPPET_COLUMN);
+        mSnippet = mSnippet.replace(NoteEditActivity.TAG_CHECKED, "").replace(
+                NoteEditActivity.TAG_UNCHECKED, "");
+        mType = cursor.getInt(TYPE_COLUMN);
+        mWidgetId = cursor.getInt(WIDGET_ID_COLUMN);
+        mWidgetType = cursor.getInt(WIDGET_TYPE_COLUMN);
+ 
+        //初始化电话号码的信息
+        mPhoneNumber = "";
+        if (mParentId == Notes.ID_CALL_RECORD_FOLDER) {
+            mPhoneNumber = DataUtils.getCallNumberByNoteId(context.getContentResolver(), mId);
+            if (!TextUtils.isEmpty(mPhoneNumber)) {//mphonenumber里有符合字符串，则用contart功能连接
+                mName = Contact.getContact(context, mPhoneNumber);
+                if (mName == null) {
+                    mName = mPhoneNumber;
+                }
+            }
+        }
+ 
+        if (mName == null) {
+            mName = "";
+        }
+        checkPostion(cursor);
+    }
+    ///根据鼠标的位置设置标记，和位置
+    private void checkPostion(Cursor cursor) {
+    	//初始化几个标记，cursor具体功能笔记中已提到，不一一叙述
+        mIsLastItem = cursor.isLast() ? true : false;
+        mIsFirstItem = cursor.isFirst() ? true : false;
+        mIsOnlyOneItem = (cursor.getCount() == 1);
+        //初始化“多重子文件”“单一子文件”2个标记
+        mIsMultiNotesFollowingFolder = false;
+        mIsOneNoteFollowingFolder = false;
+ 
+        //主要是设置上诉2标记
+        if (mType == Notes.TYPE_NOTE && !mIsFirstItem) {//若是note格式并且不是第一个元素
+            int position = cursor.getPosition();
+            if (cursor.moveToPrevious()) {//获取光标位置后看上一行
+                if (cursor.getInt(TYPE_COLUMN) == Notes.TYPE_FOLDER
+                        || cursor.getInt(TYPE_COLUMN) == Notes.TYPE_SYSTEM) {//若光标满足系统或note格式
+                    if (cursor.getCount() > (position + 1)) {
+                        mIsMultiNotesFollowingFolder = true;//若是数据行数大于但前位置+1则设置成正确
+                    } else {
+                        mIsOneNoteFollowingFolder = true;//否则单一文件夹标记为true
+                    }
+                }
+                if (!cursor.moveToNext()) {//若不能再往下走则报错
+                    throw new IllegalStateException("cursor move to previous but can't move back");
+                }
+            }
+        }
+    }
+///以下都是获取标记没什么好说的，不过倒数第二个需要说明下，很具体看下面
+    public boolean isOneFollowingFolder() {
+        return mIsOneNoteFollowingFolder;
+    }
+ 
+    public boolean isMultiFollowingFolder() {
+        return mIsMultiNotesFollowingFolder;
+    }
+ 
+    public boolean isLast() {
+        return mIsLastItem;
+    }
+ 
+    public String getCallName() {
+        return mName;
+    }
+ 
+    public boolean isFirst() {
+        return mIsFirstItem;
+    }
+ 
+    public boolean isSingle() {
+        return mIsOnlyOneItem;
+    }
+ 
+    public long getId() {
+        return mId;
+    }
+ 
+    public long getAlertDate() {
+        return mAlertDate;
+    }
+ 
+    public long getCreatedDate() {
+        return mCreatedDate;
+    }
+ 
+    public boolean hasAttachment() {
+        return mHasAttachment;
+    }
+ 
+    public long getModifiedDate() {
+        return mModifiedDate;
+    }
+ 
+    public int getBgColorId() {
+        return mBgColorId;
+    }
+ 
+    public long getParentId() {
+        return mParentId;
+    }
+ 
+    public int getNotesCount() {
+        return mNotesCount;
+    }
+ 
+    public long getFolderId () {
+        return mParentId;
+    }
+ 
+    public int getType() {
+        return mType;
+    }
+ 
+    public int getWidgetType() {
+        return mWidgetType;
+    }
+ 
+    public int getWidgetId() {
+        return mWidgetId;
+    }
+ 
+    public String getSnippet() {
+        return mSnippet;
+    }
+ 
+    public boolean hasAlert() {
+        return (mAlertDate > 0);
+    }
+ 
+    //若数据父id为保存至文件夹模式的id且满足电话号码单元不为空，则isCallRecord为true
+    public boolean isCallRecord() {
+        return (mParentId == Notes.ID_CALL_RECORD_FOLDER && !TextUtils.isEmpty(mPhoneNumber));
+    }
+ 
+    public static int getNoteType(Cursor cursor) {
+        return cursor.getInt(TYPE_COLUMN);
+    }
+}

doc/标注/210340069_申佃东/SqlNote.java

@@ -0,0 +1,521 @@
+/*
+ * 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.data;
+
+import android.appwidget.AppWidgetManager;
+import android.content.ContentResolver;
+import android.content.ContentValues;
+import android.content.Context;
+import android.database.Cursor;
+import android.net.Uri;
+import android.util.Log;
+
+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.exception.ActionFailureException;
+import net.micode.notes.tool.GTaskStringUtils;
+import net.micode.notes.tool.ResourceParser;
+
+import org.json.JSONArray;
+import org.json.JSONException;
+import org.json.JSONObject;
+
+import java.util.ArrayList;
+
+
+public class SqlNote {//功能：得到类的简写名称存到字符串TAG中，通过调用getSimpleName()函数实现
+    private static final String TAG = SqlNote.class.getSimpleName();
+
+    private static final int INVALID_ID = -99999;
+//集合了interface NoteColumns中17个SF常量
+    public static final String[] PROJECTION_NOTE = new String[] {
+            NoteColumns.ID, NoteColumns.ALERTED_DATE, NoteColumns.BG_COLOR_ID,
+            NoteColumns.CREATED_DATE, NoteColumns.HAS_ATTACHMENT, NoteColumns.MODIFIED_DATE,
+            NoteColumns.NOTES_COUNT, NoteColumns.PARENT_ID, NoteColumns.SNIPPET, NoteColumns.TYPE,
+            NoteColumns.WIDGET_ID, NoteColumns.WIDGET_TYPE, NoteColumns.SYNC_ID,
+            NoteColumns.LOCAL_MODIFIED, NoteColumns.ORIGIN_PARENT_ID, NoteColumns.GTASK_ID,
+            NoteColumns.VERSION
+    };
+//设置17个列的编号
+    public static final int ID_COLUMN = 0;
+
+    public static final int ALERTED_DATE_COLUMN = 1;
+
+    public static final int BG_COLOR_ID_COLUMN = 2;
+
+    public static final int CREATED_DATE_COLUMN = 3;
+
+    public static final int HAS_ATTACHMENT_COLUMN = 4;
+
+    public static final int MODIFIED_DATE_COLUMN = 5;
+
+    public static final int NOTES_COUNT_COLUMN = 6;
+
+    public static final int PARENT_ID_COLUMN = 7;
+
+    public static final int SNIPPET_COLUMN = 8;
+
+    public static final int TYPE_COLUMN = 9;
+
+    public static final int WIDGET_ID_COLUMN = 10;
+
+    public static final int WIDGET_TYPE_COLUMN = 11;
+
+    public static final int SYNC_ID_COLUMN = 12;
+
+    public static final int LOCAL_MODIFIED_COLUMN = 13;
+
+    public static final int ORIGIN_PARENT_ID_COLUMN = 14;
+
+    public static final int GTASK_ID_COLUMN = 15;
+
+    public static final int VERSION_COLUMN = 16;
+    //定义了17个内部的变量，其中12个可以由content中获得，5个需要初始化为0或者new
+    private Context mContext;
+
+    private ContentResolver mContentResolver;
+
+    private boolean mIsCreate;
+
+    private long mId;
+
+    private long mAlertDate;
+
+    private int mBgColorId;
+
+    private long mCreatedDate;
+
+    private int mHasAttachment;
+
+    private long mModifiedDate;
+
+    private long mParentId;
+
+    private String mSnippet;
+
+    private int mType;
+
+    private int mWidgetId;
+
+    private int mWidgetType;
+
+    private long mOriginParent;
+
+    private long mVersion;
+
+    private ContentValues mDiffNoteValues;
+
+    private ArrayList<SqlData> mDataList;
+/*
+功能：构造函数
+参数mIsCreate用于标示构造方式
+ */
+    //构造函数只有Context对所有的变量进行初始化
+    public SqlNote(Context context) {
+        mContext = context;
+        mContentResolver = context.getContentResolver();
+        mIsCreate = true;
+        mId = INVALID_ID;
+        mAlertDate = 0;
+        mBgColorId = ResourceParser.getDefaultBgId(context);
+        mCreatedDate = System.currentTimeMillis();//调用系统函数获得创建时间
+        mHasAttachment = 0;
+        mModifiedDate = System.currentTimeMillis();//最后一次修改时间初始化为创建时间
+        mParentId = 0;
+        mSnippet = "";
+        mType = Notes.TYPE_NOTE;
+        mWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID;
+        mWidgetType = Notes.TYPE_WIDGET_INVALIDE;
+        mOriginParent = 0;
+        mVersion = 0;
+        mDiffNoteValues = new ContentValues();
+        mDataList = new ArrayList<SqlData>();
+    }
+/*
+构造函数
+参数mIsCreate用于标示构造方式
+ */
+    //构造函数有Context和一个数据库的Cursor，多数变量通过cursor指向的一条记录直接进行初始化
+    public SqlNote(Context context, Cursor c) {
+        mContext = context;
+        mContentResolver = context.getContentResolver();
+        mIsCreate = false;
+        loadFromCursor(c);
+        mDataList = new ArrayList<SqlData>();
+        if (mType == Notes.TYPE_NOTE)
+            loadDataContent();
+        mDiffNoteValues = new ContentValues();
+    }
+/*
+构造函数
+mIsCreate 用于标示构造方式
+ */
+    public SqlNote(Context context, long id) {
+        mContext = context;
+        mContentResolver = context.getContentResolver();
+        mIsCreate = false;
+        loadFromCursor(id);
+        mDataList = new ArrayList<SqlData>();
+        if (mType == Notes.TYPE_NOTE)
+            loadDataContent();
+        mDiffNoteValues = new ContentValues();
+
+    }
+//通过ID从光标处加载数据
+    private void loadFromCursor(long id) {
+        Cursor c = null;
+        try {
+            c = mContentResolver.query(Notes.CONTENT_NOTE_URI, PROJECTION_NOTE, "(_id=?)",
+                    new String[] {
+                        String.valueOf(id)
+                    }, null);//通过id获得对应的ContentResolver中的cursor
+            if (c != null) {
+                c.moveToNext();
+                loadFromCursor(c);
+                /*然后加载数据进行初始化
+                这样函数SqlNote(Context context, long id)
+                与SqlNote(Context context, long id)的实现方式基本相同
+                 */
+            } else {
+                Log.w(TAG, "loadFromCursor: cursor = null");
+            }
+        } finally {
+            if (c != null)
+                c.close();
+        }
+    }
+//通过游标从光标处加载数据
+    private void loadFromCursor(Cursor c) {
+        //从一条记录中获得以下变量的初始值
+        mId = c.getLong(ID_COLUMN);
+        mAlertDate = c.getLong(ALERTED_DATE_COLUMN);
+        mBgColorId = c.getInt(BG_COLOR_ID_COLUMN);
+        mCreatedDate = c.getLong(CREATED_DATE_COLUMN);
+        mHasAttachment = c.getInt(HAS_ATTACHMENT_COLUMN);
+        mModifiedDate = c.getLong(MODIFIED_DATE_COLUMN);
+        mParentId = c.getLong(PARENT_ID_COLUMN);
+        mSnippet = c.getString(SNIPPET_COLUMN);
+        mType = c.getInt(TYPE_COLUMN);
+        mWidgetId = c.getInt(WIDGET_ID_COLUMN);
+        mWidgetType = c.getInt(WIDGET_TYPE_COLUMN);
+        mVersion = c.getLong(VERSION_COLUMN);
+    }
+//通过content机制获取共享数据并加载到数据库当前游标处
+    private void loadDataContent() {
+        Cursor c = null;
+        mDataList.clear();
+        try {
+            c = mContentResolver.query(Notes.CONTENT_DATA_URI, SqlData.PROJECTION_DATA,
+                    "(note_id=?)", new String[] {
+                        String.valueOf(mId)
+                    }, null);
+            if (c != null) {
+                if (c.getCount() == 0) {
+                    Log.w(TAG, "it seems that the note has not data");
+                    return;
+                }
+                while (c.moveToNext()) {
+                    SqlData data = new SqlData(mContext, c);
+                    mDataList.add(data);
+                }
+            } else {
+                Log.w(TAG, "loadDataContent: cursor = null");
+            }
+        } finally {
+            if (c != null)
+                c.close();
+        }
+    }
+//设置通过content机制用于共享的数据信息
+    public boolean setContent(JSONObject js) {
+        try {
+            JSONObject note = js.getJSONObject(GTaskStringUtils.META_HEAD_NOTE);
+            if (note.getInt(NoteColumns.TYPE) == Notes.TYPE_SYSTEM) {
+                Log.w(TAG, "cannot set system folder");
+            } else if (note.getInt(NoteColumns.TYPE) == Notes.TYPE_FOLDER) {
+                // for folder we can only update the snnipet and type
+                String snippet = note.has(NoteColumns.SNIPPET) ? note
+                        .getString(NoteColumns.SNIPPET) : "";
+                if (mIsCreate || !mSnippet.equals(snippet)) {
+                    mDiffNoteValues.put(NoteColumns.SNIPPET, snippet);
+                }
+                mSnippet = snippet;
+
+                int type = note.has(NoteColumns.TYPE) ? note.getInt(NoteColumns.TYPE)
+                        : Notes.TYPE_NOTE;
+                if (mIsCreate || mType != type) {
+                    mDiffNoteValues.put(NoteColumns.TYPE, type);
+                }
+                mType = type;
+            } else if (note.getInt(NoteColumns.TYPE) == Notes.TYPE_NOTE) {
+                JSONArray dataArray = js.getJSONArray(GTaskStringUtils.META_HEAD_DATA);
+                long id = note.has(NoteColumns.ID) ? note.getLong(NoteColumns.ID) : INVALID_ID;
+                if (mIsCreate || mId != id) {
+                    mDiffNoteValues.put(NoteColumns.ID, id);
+                }
+                mId = id;
+
+                long alertDate = note.has(NoteColumns.ALERTED_DATE) ? note
+                        .getLong(NoteColumns.ALERTED_DATE) : 0;
+                if (mIsCreate || mAlertDate != alertDate) {
+                    mDiffNoteValues.put(NoteColumns.ALERTED_DATE, alertDate);
+                }
+                mAlertDate = alertDate;
+
+                int bgColorId = note.has(NoteColumns.BG_COLOR_ID) ? note
+                        .getInt(NoteColumns.BG_COLOR_ID) : ResourceParser.getDefaultBgId(mContext);
+                if (mIsCreate || mBgColorId != bgColorId) {
+                    mDiffNoteValues.put(NoteColumns.BG_COLOR_ID, bgColorId);
+                }
+                mBgColorId = bgColorId;
+
+                long createDate = note.has(NoteColumns.CREATED_DATE) ? note
+                        .getLong(NoteColumns.CREATED_DATE) : System.currentTimeMillis();
+                if (mIsCreate || mCreatedDate != createDate) {
+                    mDiffNoteValues.put(NoteColumns.CREATED_DATE, createDate);
+                }
+                mCreatedDate = createDate;
+
+                int hasAttachment = note.has(NoteColumns.HAS_ATTACHMENT) ? note
+                        .getInt(NoteColumns.HAS_ATTACHMENT) : 0;
+                if (mIsCreate || mHasAttachment != hasAttachment) {
+                    mDiffNoteValues.put(NoteColumns.HAS_ATTACHMENT, hasAttachment);
+                }
+                mHasAttachment = hasAttachment;
+
+                long modifiedDate = note.has(NoteColumns.MODIFIED_DATE) ? note
+                        .getLong(NoteColumns.MODIFIED_DATE) : System.currentTimeMillis();
+                if (mIsCreate || mModifiedDate != modifiedDate) {
+                    mDiffNoteValues.put(NoteColumns.MODIFIED_DATE, modifiedDate);
+                }
+                mModifiedDate = modifiedDate;
+
+                long parentId = note.has(NoteColumns.PARENT_ID) ? note
+                        .getLong(NoteColumns.PARENT_ID) : 0;
+                if (mIsCreate || mParentId != parentId) {
+                    mDiffNoteValues.put(NoteColumns.PARENT_ID, parentId);
+                }
+                mParentId = parentId;
+
+                String snippet = note.has(NoteColumns.SNIPPET) ? note
+                        .getString(NoteColumns.SNIPPET) : "";
+                if (mIsCreate || !mSnippet.equals(snippet)) {
+                    mDiffNoteValues.put(NoteColumns.SNIPPET, snippet);
+                }
+                mSnippet = snippet;
+
+                int type = note.has(NoteColumns.TYPE) ? note.getInt(NoteColumns.TYPE)
+                        : Notes.TYPE_NOTE;
+                if (mIsCreate || mType != type) {
+                    mDiffNoteValues.put(NoteColumns.TYPE, type);
+                }
+                mType = type;
+
+                int widgetId = note.has(NoteColumns.WIDGET_ID) ? note.getInt(NoteColumns.WIDGET_ID)
+                        : AppWidgetManager.INVALID_APPWIDGET_ID;
+                if (mIsCreate || mWidgetId != widgetId) {
+                    mDiffNoteValues.put(NoteColumns.WIDGET_ID, widgetId);
+                }
+                mWidgetId = widgetId;
+
+                int widgetType = note.has(NoteColumns.WIDGET_TYPE) ? note
+                        .getInt(NoteColumns.WIDGET_TYPE) : Notes.TYPE_WIDGET_INVALIDE;
+                if (mIsCreate || mWidgetType != widgetType) {
+                    mDiffNoteValues.put(NoteColumns.WIDGET_TYPE, widgetType);
+                }
+                mWidgetType = widgetType;
+
+                long originParent = note.has(NoteColumns.ORIGIN_PARENT_ID) ? note
+                        .getLong(NoteColumns.ORIGIN_PARENT_ID) : 0;
+                if (mIsCreate || mOriginParent != originParent) {
+                    mDiffNoteValues.put(NoteColumns.ORIGIN_PARENT_ID, originParent);
+                }
+                mOriginParent = originParent;
+
+                for (int i = 0; i < dataArray.length(); i++) {
+                    JSONObject data = dataArray.getJSONObject(i);
+                    SqlData sqlData = null;
+                    if (data.has(DataColumns.ID)) {
+                        long dataId = data.getLong(DataColumns.ID);
+                        for (SqlData temp : mDataList) {
+                            if (dataId == temp.getId()) {
+                                sqlData = temp;
+                            }
+                        }
+                    }
+
+                    if (sqlData == null) {
+                        sqlData = new SqlData(mContext);
+                        mDataList.add(sqlData);
+                    }
+
+                    sqlData.setContent(data);
+                }
+            }
+        } catch (JSONException e) {
+            Log.e(TAG, e.toString());
+            e.printStackTrace();
+            return false;
+        }
+        return true;
+    }
+//获取content机制提供的数据并加载到note中
+    public JSONObject getContent() {
+        try {
+            JSONObject js = new JSONObject();
+
+            if (mIsCreate) {
+                Log.e(TAG, "it seems that we haven't created this in database yet");
+                return null;
+            }
+
+            JSONObject note = new JSONObject();
+            if (mType == Notes.TYPE_NOTE) {//当类型为note时
+                note.put(NoteColumns.ID, mId);
+                note.put(NoteColumns.ALERTED_DATE, mAlertDate);
+                note.put(NoteColumns.BG_COLOR_ID, mBgColorId);
+                note.put(NoteColumns.CREATED_DATE, mCreatedDate);
+                note.put(NoteColumns.HAS_ATTACHMENT, mHasAttachment);
+                note.put(NoteColumns.MODIFIED_DATE, mModifiedDate);
+                note.put(NoteColumns.PARENT_ID, mParentId);
+                note.put(NoteColumns.SNIPPET, mSnippet);
+                note.put(NoteColumns.TYPE, mType);
+                note.put(NoteColumns.WIDGET_ID, mWidgetId);
+                note.put(NoteColumns.WIDGET_TYPE, mWidgetType);
+                note.put(NoteColumns.ORIGIN_PARENT_ID, mOriginParent);
+                js.put(GTaskStringUtils.META_HEAD_NOTE, note);
+
+                JSONArray dataArray = new JSONArray();
+                for (SqlData sqlData : mDataList) {
+                    JSONObject data = sqlData.getContent();
+                    if (data != null) {
+                        dataArray.put(data);
+                    }
+                }
+                js.put(GTaskStringUtils.META_HEAD_DATA, dataArray);
+            } else if (mType == Notes.TYPE_FOLDER || mType == Notes.TYPE_SYSTEM) {
+                note.put(NoteColumns.ID, mId);
+                note.put(NoteColumns.TYPE, mType);
+                note.put(NoteColumns.SNIPPET, mSnippet);
+                js.put(GTaskStringUtils.META_HEAD_NOTE, note);
+            }
+
+            return js;
+        } catch (JSONException e) {
+            Log.e(TAG, e.toString());
+            e.printStackTrace();
+        }
+        return null;
+    }
+//给当前ID设置父ID
+    public void setParentId(long id) {
+        mParentId = id;
+        mDiffNoteValues.put(NoteColumns.PARENT_ID, id);
+    }
+//给当前ID设计GtaskId
+    public void setGtaskId(String gid) {
+        mDiffNoteValues.put(NoteColumns.GTASK_ID, gid);
+    }
+
+    public void setSyncId(long syncId) {
+        mDiffNoteValues.put(NoteColumns.SYNC_ID, syncId);
+    }
+//初始化本地修改，即撤销所有当前修改
+    public void resetLocalModified() {
+        mDiffNoteValues.put(NoteColumns.LOCAL_MODIFIED, 0);
+    }
+//获得当前ID
+    public long getId() {
+        return mId;
+    }
+//获得当前ID的父ID
+    public long getParentId() {
+        return mParentId;
+    }
+//获取小片段即用于显示的部分便签内容
+    public String getSnippet() {
+        return mSnippet;
+    }
+//判断是否是便签类型
+    public boolean isNoteType() {
+        return mType == Notes.TYPE_NOTE;
+    }
+//commit函数用于把当前造作所做的修改保存到数据库
+    public void commit(boolean validateVersion) {
+        if (mIsCreate) {
+            if (mId == INVALID_ID && mDiffNoteValues.containsKey(NoteColumns.ID)) {
+                mDiffNoteValues.remove(NoteColumns.ID);
+            }
+
+            Uri uri = mContentResolver.insert(Notes.CONTENT_NOTE_URI, mDiffNoteValues);
+            try {
+                mId = Long.valueOf(uri.getPathSegments().get(1));
+            } catch (NumberFormatException e) {
+                Log.e(TAG, "Get note id error :" + e.toString());
+                throw new ActionFailureException("create note failed");
+            }
+            if (mId == 0) {
+                throw new IllegalStateException("Create thread id failed");
+            }
+
+            if (mType == Notes.TYPE_NOTE) {
+                for (SqlData sqlData : mDataList) {//直接用SqlData中的实现
+                    sqlData.commit(mId, false, -1);
+                }
+            }
+        } else {
+            if (mId <= 0 && mId != Notes.ID_ROOT_FOLDER && mId != Notes.ID_CALL_RECORD_FOLDER) {
+                Log.e(TAG, "No such note");
+                throw new IllegalStateException("Try to update note with invalid id");
+            }
+            if (mDiffNoteValues.size() > 0) {
+                mVersion ++;
+                int result = 0;
+                if (!validateVersion) {//构造字符串
+                    result = mContentResolver.update(Notes.CONTENT_NOTE_URI, mDiffNoteValues, "("
+                            + NoteColumns.ID + "=?)", new String[] {
+                        String.valueOf(mId)
+                    });
+                } else {
+                    result = mContentResolver.update(Notes.CONTENT_NOTE_URI, mDiffNoteValues, "("
+                            + NoteColumns.ID + "=?) AND (" + NoteColumns.VERSION + "<=?)",
+                            new String[] {
+                                    String.valueOf(mId), String.valueOf(mVersion)
+                            });
+                }
+                if (result == 0) {
+                    Log.w(TAG, "there is no update. maybe user updates note when syncing");
+                }
+            }
+
+            if (mType == Notes.TYPE_NOTE) {
+                for (SqlData sqlData : mDataList) {
+                    sqlData.commit(mId, validateVersion, mVersion);
+                }
+            }
+        }
+
+        // refresh local info
+        loadFromCursor(mId);
+        if (mType == Notes.TYPE_NOTE)
+            loadDataContent();
+
+        mDiffNoteValues.clear();
+        mIsCreate = false;
+    }
+}