From 2a08914bf61ecff58dac35f471568ff814e923a3 Mon Sep 17 00:00:00 2001 From: kun <1913494853@qq.com> Date: Thu, 11 May 2023 22:14:46 +0800 Subject: [PATCH 1/2] add comment --- .../net/micode/notes/gtask/data/MetaData.java | 65 ++++++++++++++++--- .../net/micode/notes/gtask/data/Node.java | 27 +++++++- .../net/micode/notes/gtask/data/SqlData.java | 36 +++++++--- 3 files changed, 108 insertions(+), 20 deletions(-) diff --git a/app/src/main/java/net/micode/notes/gtask/data/MetaData.java b/app/src/main/java/net/micode/notes/gtask/data/MetaData.java index 3a2050b..dac87f7 100644 --- a/app/src/main/java/net/micode/notes/gtask/data/MetaData.java +++ b/app/src/main/java/net/micode/notes/gtask/data/MetaData.java @@ -26,29 +26,61 @@ import org.json.JSONObject; public class MetaData extends Task { + /*功能描述：得到类的简写名称并存入字符串TAG中 + *实现过程：调用getSimpleName()函数 + */ private final static String TAG = MetaData.class.getSimpleName(); + /* + * 功能描述：设置数据，即生成元数据库 + * 实现过程：调用JSONObject库函数put ()，Task类中的setNotes ()和setName ()函数 + * 参数注解： + */ + private String mRelatedGid; - private String mRelatedGid = null; - + { + mRelatedGid = null; + } + /* + * 功能描述：设置数据，即生成元数据库 + * 实现过程：调用JSONObject库函数put ()，Task类中的setNotes ()和setName ()函数 + * 参数注解： + */ public void setMeta(String gid, JSONObject metaInfo) { + //对函数块进行注释 try { metaInfo.put(GTaskStringUtils.META_HEAD_GTASK_ID, gid); + /* + * 将这对键值放入metaInfo这个jsonobject对象中 + */ } catch (JSONException e) { Log.e(TAG, "failed to put related gid"); + /* + *输出错误信息 + */ } setNotes(metaInfo.toString()); setName(GTaskStringUtils.META_NOTE_NAME); } - + //获取相关联的Gid + public String getRelatedGid() { + return mRelatedGid; } - + /* + * 功能描述：判断当前数据是否为空，若为空则返回真即值得保存 + * Made By CuiCan + */ @Override public boolean isWorthSaving() { + return getNotes() != null; } - + /* + * 功能描述：使用远程json数据对象设置元数据内容 + * 实现过程：调用父类Task中的setContentByRemoteJSON ()函数，并 + * 参数注解： + */ @Override public void setContentByRemoteJSON(JSONObject js) { super.setContentByRemoteJSON(js); @@ -58,25 +90,42 @@ public class MetaData extends Task { mRelatedGid = metaInfo.getString(GTaskStringUtils.META_HEAD_GTASK_ID); } catch (JSONException e) { Log.w(TAG, "failed to get related gid"); + //输出警告信息 mRelatedGid = null; } } } - + //使用本地json数据对象设置元数据内容，使用时则谁抛出异常 + //Made By CuiCan @Override public void setContentByLocalJSON(JSONObject js) { // this function should not be called throw new IllegalAccessError("MetaData:setContentByLocalJSON should not be called"); + //传递非法参数 } - + /* + * 功能描述：从元数据内容中获取本地json对象，一般不会用到，若用到，则抛出异常 + * Made By CuiCan + */ @Override public JSONObject getLocalJSONFromContent() { throw new IllegalAccessError("MetaData:getLocalJSONFromContent should not be called"); + /* + * 传递非法参数异常 + * Made By Cui Can + */ } - + /* + * 功能描述：获取同步动作状态，一般不会用到，若用到，则抛出异常 + * Made By CuiCan + */ @Override public int getSyncAction(Cursor c) { throw new IllegalAccessError("MetaData:getSyncAction should not be called"); + /* + * 传递非法参数异常 + * Made By Cui Can + */ } } diff --git a/app/src/main/java/net/micode/notes/gtask/data/Node.java b/app/src/main/java/net/micode/notes/gtask/data/Node.java index 63950e0..ee24559 100644 --- a/app/src/main/java/net/micode/notes/gtask/data/Node.java +++ b/app/src/main/java/net/micode/notes/gtask/data/Node.java @@ -20,33 +20,48 @@ import android.database.Cursor; import org.json.JSONObject; +/** + * 应该是同步操作的基础数据类型，定义了相关指示同步操作的常量 + * 关键字：abstract + */ public abstract class Node { + //定义了各种用于表征同步状态的常量 + public static final int SYNC_ACTION_NONE = 0; + // 本地和云端都无可更新内容（即本地和云端内容一致） public static final int SYNC_ACTION_ADD_REMOTE = 1; + // 需要在远程云端增加内容 public static final int SYNC_ACTION_ADD_LOCAL = 2; + // 需要在本地增加内容 public static final int SYNC_ACTION_DEL_REMOTE = 3; + // 需要在远程云端删除内容 public static final int SYNC_ACTION_DEL_LOCAL = 4; + // 需要在本地删除内容 public static final int SYNC_ACTION_UPDATE_REMOTE = 5; + // 需要将本地内容更新到远程云端 public static final int SYNC_ACTION_UPDATE_LOCAL = 6; + // 需要将远程云端内容更新到本地 public static final int SYNC_ACTION_UPDATE_CONFLICT = 7; + // 同步出现冲突 public static final int SYNC_ACTION_ERROR = 8; + // 同步出现错误 private String mGid; private String mName; private long mLastModified; - + //记录最后一次修改时间 private boolean mDeleted; - + //表征是否被删除 public Node() { mGid = null; mName = ""; @@ -67,34 +82,42 @@ public abstract class Node { public abstract int getSyncAction(Cursor c); public void setGid(String gid) { + this.mGid = gid; } public void setName(String name) { + this.mName = name; } public void setLastModified(long lastModified) { + this.mLastModified = lastModified; } public void setDeleted(boolean deleted) { + this.mDeleted = deleted; } public String getGid() { + return this.mGid; } public String getName() { + return this.mName; } public long getLastModified() { + return this.mLastModified; } public boolean getDeleted() { + return this.mDeleted; } diff --git a/app/src/main/java/net/micode/notes/gtask/data/SqlData.java b/app/src/main/java/net/micode/notes/gtask/data/SqlData.java index d3ec3be..c6b59da 100644 --- a/app/src/main/java/net/micode/notes/gtask/data/SqlData.java +++ b/app/src/main/java/net/micode/notes/gtask/data/SqlData.java @@ -13,7 +13,10 @@ * See the License for the specific language governing permissions and * limitations under the License. */ - +/* + * Description：用于支持小米便签最底层的数据库相关操作，和sqlnote的关系上是子集关系，即data是note的子集（节点）。 + * SqlData其实就是也就是所谓数据中的数据 + */ package net.micode.notes.gtask.data; import android.content.ContentResolver; @@ -36,10 +39,13 @@ import org.json.JSONObject; public class SqlData { + //调用getSimpleName ()函数，得到类的简写名称存入字符串TAG中 private static final String TAG = SqlData.class.getSimpleName(); private static final int INVALID_ID = -99999; + //为mDataId赋初始值-99999 + //集合了interface DataColumns中所有的SF常量 public static final String[] PROJECTION_DATA = new String[] { DataColumns.ID, DataColumns.MIME_TYPE, DataColumns.CONTENT, DataColumns.DATA1, DataColumns.DATA3 @@ -54,9 +60,9 @@ public class SqlData { public static final int DATA_CONTENT_DATA_1_COLUMN = 3; public static final int DATA_CONTENT_DATA_3_COLUMN = 4; - + //以上五个变量作为sql表中五列的编号 private ContentResolver mContentResolver; - + //用来判断是否直接用content生成，是为true，否则false private boolean mIsCreate; private long mDataId; @@ -70,25 +76,33 @@ public class SqlData { private String mDataContentData3; private ContentValues mDiffDataValues; - + /*mContentResolver用于获取ContentProvider提供的数据 + *mIsCreate表征当前数据是用哪种方式创建（两种构造函数的参数不同） + * 构造函数，并且用于初始化 + */ public SqlData(Context context) { mContentResolver = context.getContentResolver(); mIsCreate = true; mDataId = INVALID_ID; + //mDataId赋予初始值-99999 mDataMimeType = DataConstants.NOTE; mDataContent = ""; mDataContentData1 = 0; mDataContentData3 = ""; mDiffDataValues = new ContentValues(); } - + /*mContentResolver用于获取ContentProvider提供的数据 + * mIsCreate表征当前数据是用哪种方式创建（两种构造函数的参数不同） + * 构造函数，初始化数据 + */ public SqlData(Context context, Cursor c) { mContentResolver = context.getContentResolver(); mIsCreate = false; loadFromCursor(c); mDiffDataValues = new ContentValues(); } - + //从光标处加载数据 + //从当前的光标处将五列的数据加载到该类的对象 private void loadFromCursor(Cursor c) { mDataId = c.getLong(DATA_ID_COLUMN); mDataMimeType = c.getString(DATA_MIME_TYPE_COLUMN); @@ -96,8 +110,9 @@ public class SqlData { mDataContentData1 = c.getLong(DATA_CONTENT_DATA_1_COLUMN); mDataContentData3 = c.getString(DATA_CONTENT_DATA_3_COLUMN); } - + //设置用于共享的数据，并提供异常抛出与处理机制 public void setContent(JSONObject js) throws JSONException { + //如果传入的JSONObject对象中有DataColumns.ID这一项，则设置，否则设为INVALID_ID long dataId = js.has(DataColumns.ID) ? js.getLong(DataColumns.ID) : INVALID_ID; if (mIsCreate || mDataId != dataId) { mDiffDataValues.put(DataColumns.ID, dataId); @@ -129,12 +144,13 @@ public class SqlData { } mDataContentData3 = dataContentData3; } - + //获取共享的数据内容，并提供异常抛出与处理机制 public JSONObject getContent() throws JSONException { if (mIsCreate) { Log.e(TAG, "it seems that we haven't created this in database yet"); return null; } + //创建JSONObject对象。并将相关数据放入其中，并返回。 JSONObject js = new JSONObject(); js.put(DataColumns.ID, mDataId); js.put(DataColumns.MIME_TYPE, mDataMimeType); @@ -143,7 +159,7 @@ public class SqlData { js.put(DataColumns.DATA3, mDataContentData3); return js; } - + //commit函数用于把当前造作所做的修改保存到数据库 public void commit(long noteId, boolean validateVersion, long version) { if (mIsCreate) { @@ -182,7 +198,7 @@ public class SqlData { mDiffDataValues.clear(); mIsCreate = false; } - + //获取当前的id public long getId() { return mDataId; } From ea3b1a5657b65d7798f9292e0457365c0b908707 Mon Sep 17 00:00:00 2001 From: kun <1913494853@qq.com> Date: Thu, 11 May 2023 22:32:34 +0800 Subject: [PATCH 2/2] add comment --- .../net/micode/notes/gtask/data/SqlNote.java | 39 +++++++++++++++++-- .../net/micode/notes/gtask/data/Task.java | 12 +++--- .../net/micode/notes/gtask/data/TaskList.java | 23 ++++++++--- 3 files changed, 60 insertions(+), 14 deletions(-) diff --git a/app/src/main/java/net/micode/notes/gtask/data/SqlNote.java b/app/src/main/java/net/micode/notes/gtask/data/SqlNote.java index 79a4095..0a70e4d 100644 --- a/app/src/main/java/net/micode/notes/gtask/data/SqlNote.java +++ b/app/src/main/java/net/micode/notes/gtask/data/SqlNote.java @@ -13,6 +13,10 @@ * See the License for the specific language governing permissions and * limitations under the License. */ +/* + * Description：用于支持小米便签最底层的数据库相关操作，和sqldata的关系上是父集关系，即note是data的子父集。 + * 和SqlData相比，SqlNote算是真正意义上的数据了。 + */ package net.micode.notes.gtask.data; @@ -39,10 +43,11 @@ import java.util.ArrayList; public class SqlNote { + //调用getSimpleName()函数，得到类的简写名称存入字符串TAG中 private static final String TAG = SqlNote.class.getSimpleName(); private static final int INVALID_ID = -99999; - + // 集合了interface NoteColumns中所有SF常量（17个） 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, @@ -52,6 +57,7 @@ public class SqlNote { NoteColumns.VERSION }; + //以下设置17个列的编号 public static final int ID_COLUMN = 0; public static final int ALERTED_DATE_COLUMN = 1; @@ -86,6 +92,7 @@ public class SqlNote { public static final int VERSION_COLUMN = 16; + //一下定义了17个内部的变量，其中12个可以由content中获得，5个需要初始化为0或者new private Context mContext; private ContentResolver mContentResolver; @@ -122,6 +129,7 @@ public class SqlNote { private ArrayList mDataList; + //mIsCreate用于标示构造函数，并且进行构造函数，同时构造函数只有context，对所有变量进行初始化 public SqlNote(Context context) { mContext = context; mContentResolver = context.getContentResolver(); @@ -143,6 +151,8 @@ public class SqlNote { mDataList = new ArrayList(); } + //mIsCreate用于标示构造方式 + //构造函数有context和一个数据库的cursor，多数变量通过cursor指向的一条记录直接进行初始化 public SqlNote(Context context, Cursor c) { mContext = context; mContentResolver = context.getContentResolver(); @@ -154,6 +164,7 @@ public class SqlNote { mDiffNoteValues = new ContentValues(); } + //mIsCreate用于标示构造方式 public SqlNote(Context context, long id) { mContext = context; mContentResolver = context.getContentResolver(); @@ -166,16 +177,20 @@ public class SqlNote { } + //通过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); + }, null);//通过id获得对应的ContentResolver中的cursor if (c != null) { c.moveToNext(); - loadFromCursor(c); + loadFromCursor(c);/*然后加载数据进行初始化，这样函数SqlNote(Context context, long id) + *与SqlNote(Context context, long id)的实现方式基本相同 + */ + } else { Log.w(TAG, "loadFromCursor: cursor = null"); } @@ -185,7 +200,9 @@ public class SqlNote { } } + //通过游标从光标处加载数据 private void loadFromCursor(Cursor c) { + //直接从一条记录中的获得以下变量的初始值 mId = c.getLong(ID_COLUMN); mAlertDate = c.getLong(ALERTED_DATE_COLUMN); mBgColorId = c.getInt(BG_COLOR_ID_COLUMN); @@ -200,6 +217,7 @@ public class SqlNote { mVersion = c.getLong(VERSION_COLUMN); } + //通过content机制获取共享数据并加载到数据库当前游标处 private void loadDataContent() { Cursor c = null; mDataList.clear(); @@ -226,6 +244,7 @@ public class SqlNote { } } + //设置通过content机制用于共享的数据信息 public boolean setContent(JSONObject js) { try { JSONObject note = js.getJSONObject(GTaskStringUtils.META_HEAD_NOTE); @@ -359,6 +378,7 @@ public class SqlNote { return true; } + //获取content机制提供的数据并加载到note中 public JSONObject getContent() { try { JSONObject js = new JSONObject(); @@ -370,6 +390,7 @@ public class SqlNote { 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); @@ -393,6 +414,7 @@ public class SqlNote { } 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); @@ -407,39 +429,48 @@ public class SqlNote { 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); } + //给当前id设置同步id 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)) { @@ -458,6 +489,7 @@ public class SqlNote { } if (mType == Notes.TYPE_NOTE) { + //直接使用sqldata中的实现 for (SqlData sqlData : mDataList) { sqlData.commit(mId, false, -1); } @@ -471,6 +503,7 @@ public class SqlNote { mVersion ++; int result = 0; if (!validateVersion) { + //构造字符串 result = mContentResolver.update(Notes.CONTENT_NOTE_URI, mDiffNoteValues, "(" + NoteColumns.ID + "=?)", new String[] { String.valueOf(mId) diff --git a/app/src/main/java/net/micode/notes/gtask/data/Task.java b/app/src/main/java/net/micode/notes/gtask/data/Task.java index 6a19454..a990f29 100644 --- a/app/src/main/java/net/micode/notes/gtask/data/Task.java +++ b/app/src/main/java/net/micode/notes/gtask/data/Task.java @@ -35,22 +35,22 @@ import org.json.JSONObject; public class Task extends Node { private static final String TAG = Task.class.getSimpleName(); - private boolean mCompleted; + private boolean mCompleted;//是否完成 private String mNotes; - private JSONObject mMetaInfo; + private JSONObject mMetaInfo;//将在实例中存储数据的类型 - private Task mPriorSibling; + private Task mPriorSibling;//对应的优先兄弟Task的指针 - private TaskList mParent; + private TaskList mParent;//所在的任务列表的指针 public Task() { super(); mCompleted = false; mNotes = null; - mPriorSibling = null; - mParent = null; + mPriorSibling = null;//TaskList中当前Task前面的Task的指针 + mParent = null;//当前Task所在的TaskList mMetaInfo = null; } diff --git a/app/src/main/java/net/micode/notes/gtask/data/TaskList.java b/app/src/main/java/net/micode/notes/gtask/data/TaskList.java index 4ea21c5..eff210d 100644 --- a/app/src/main/java/net/micode/notes/gtask/data/TaskList.java +++ b/app/src/main/java/net/micode/notes/gtask/data/TaskList.java @@ -31,11 +31,11 @@ import java.util.ArrayList; public class TaskList extends Node { - private static final String TAG = TaskList.class.getSimpleName(); + private static final String TAG = TaskList.class.getSimpleName();//tag标记 - private int mIndex; + private int mIndex;//当前TaskList的指针 - private ArrayList mChildren; + private ArrayList mChildren;//类中主要的保存数据的单元，用来实现一个以Task为元素的ArrayList public TaskList() { super(); @@ -43,6 +43,7 @@ public class TaskList extends Node { mIndex = 1; } + //生成并返回一个包含了一定数据的JSONObject实体 public JSONObject getCreateAction(int actionId) { JSONObject js = new JSONObject(); @@ -74,6 +75,7 @@ public class TaskList extends Node { return js; } + //生成并返回一个包含了一定数据的JSONObject实体 public JSONObject getUpdateAction(int actionId) { JSONObject js = new JSONObject(); @@ -216,10 +218,13 @@ public class TaskList extends Node { return SYNC_ACTION_ERROR; } + //获得TaskList的大小，即mChildren的大小 public int getChildTaskCount() { return mChildren.size(); } + //返回值为是否成功添加任务 + //在当前任务表末尾添加新的任务 public boolean addChildTask(Task task) { boolean ret = false; if (task != null && !mChildren.contains(task)) { @@ -229,11 +234,13 @@ public class TaskList extends Node { task.setPriorSibling(mChildren.isEmpty() ? null : mChildren .get(mChildren.size() - 1)); task.setParent(this); + //每一次ArrayList的变化都要紧跟相关Task中PriorSibling的更改，接下来几个函数都有相关操作 } } return ret; } + //在当前任务表的指定位置添加新的任务 public boolean addChildTask(Task task, int index) { if (index < 0 || index > mChildren.size()) { Log.e(TAG, "add child task: invalid index"); @@ -260,6 +267,7 @@ public class TaskList extends Node { return true; } + //删除TaskList中的一个Task public boolean removeChildTask(Task task) { boolean ret = false; int index = mChildren.indexOf(task); @@ -281,6 +289,7 @@ public class TaskList extends Node { return ret; } + //将当前TaskList中含有的某个Task移到index位置 public boolean moveChildTask(Task task, int index) { if (index < 0 || index >= mChildren.size()) { @@ -297,8 +306,10 @@ public class TaskList extends Node { if (pos == index) return true; return (removeChildTask(task) && addChildTask(task, index)); + //利用已实现好的功能完成当下功能 } + //返回寻找结果，按gid寻找task public Task findChildTaskByGid(String gid) { for (int i = 0; i < mChildren.size(); i++) { Task t = mChildren.get(i); @@ -309,10 +320,11 @@ public class TaskList extends Node { return null; } + //返回指定task的index public int getChildTaskIndex(Task task) { return mChildren.indexOf(task); } - + //返回指定index的Task public Task getChildTaskByIndex(int index) { if (index < 0 || index >= mChildren.size()) { Log.e(TAG, "getTaskByIndex: invalid index"); @@ -321,8 +333,9 @@ public class TaskList extends Node { return mChildren.get(index); } + //返回指定gid的Task public Task getChilTaskByGid(String gid) { - for (Task task : mChildren) { + for (Task task : mChildren) {//常见的ArrayList的遍历方法 if (task.getGid().equals(gid)) return task; }