xiaomi-Notes/Note.java

/*
 * 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;//声明了当前代码所在的包（package）名为net.micode.notes.model
import android.content.ContentProviderOperation;//导入Android框架中的ContentProviderOperation类。
import android.content.ContentProviderResult;//导入ContentProviderResult类。
import android.content.ContentUris;//导入ContentUris类。这个类提供了用于处理URI（统一资源标识符）和ID之间转换的实用方法。
import android.content.ContentValues;//导入ContentValues类。这个类用于存储一组键值对，通常用于传递给内容提供者（ContentProvider）进行插入或更新操作。
import android.content.Context;//导入Context类。在Android中，Context是一个抽象类，它允许访问特定资源和应用级操作，如启动活动、广播和接收意图等。
import android.content.OperationApplicationException;//导入OperationApplicationException类。这个异常在尝试应用一个操作到内容提供者时，如果内容提供者报告了一个错误，就会被抛出。
import android.net.Uri;//导入Uri类。这个类表示统一资源标识符（URI），用于唯一标识内容提供者中的数据。
import android.os.RemoteException;//导入RemoteException类。这个异常是在尝试与远程对象（如另一个应用中的服务）进行通信时，如果通信失败就会被抛出。
import android.util.Log;//导入Log类。这个类提供了用于记录日志信息的静态方法，帮助开发者在开发过程中调试应用。

import net.micode.notes.data.Notes;//导入Notes类。
import net.micode.notes.data.Notes.CallNote;//导入Notes类中的CallNote内部类。
import net.micode.notes.data.Notes.DataColumns;//导入Notes类中的DataColumns内部类
import net.micode.notes.data.Notes.NoteColumns;//导入Notes类中的NoteColumns内部类。
import net.micode.notes.data.Notes.TextNote;//导入Notes类中的TextNote内部类。

import java.util.ArrayList;//导入Java的ArrayList类。
//这段代码主要是导入了一些必要的类，用于后续操作数据库中的笔记数据。通过导入这些类，开发者可以使用Android框架提供的API来执行数据库操作、处理URI、记录日志等。

// 定义一个名为Note的公开类
public class Note {
    // 定义一个私有的ContentValues对象，用于存储要插入数据库的数据差异
    private ContentValues mNoteDiffValues;
    // 定义一个私有的NoteData对象，可能用于存储笔记的特定数据
    private NoteData mNoteData;
    // 定义一个私有的静态常量TAG，用于日志记录
    private static final String TAG = "Note";
 
    /**
     * 创建一个新的笔记ID，用于向数据库添加新笔记
     */
    // 定义一个公开的静态同步方法，该方法接受一个Context对象和一个文件夹ID作为参数，并返回一个long类型的笔记ID
    public static synchronized long getNewNoteId(Context context, long folderId) {
        // 创建一个新的ContentValues对象，用于存储要插入数据库的新笔记的数据
        ContentValues values = new ContentValues();
        // 获取当前系统时间（毫秒）
        long createdTime = System.currentTimeMillis();
        // 将创建时间和修改时间设置为当前时间，并存储到values对象中
        values.put(NoteColumns.CREATED_DATE, createdTime);
        values.put(NoteColumns.MODIFIED_DATE, createdTime);
        // 设置笔记类型为普通笔记，并存储到values对象中
        values.put(NoteColumns.TYPE, Notes.TYPE_NOTE);
        // 设置本地修改标志为1，并存储到values对象中（可能表示笔记已被本地修改）
        values.put(NoteColumns.LOCAL_MODIFIED, 1);
        // 设置父文件夹ID，并存储到values对象中
        values.put(NoteColumns.PARENT_ID, folderId);
        // 使用ContentResolver向数据库插入新笔记，并返回新笔记的Uri
        Uri uri = context.getContentResolver().insert(Notes.CONTENT_NOTE_URI, values);
 
        // 定义一个long类型的变量noteId，用于存储新笔记的ID
        long noteId = 0;
        try {
            // 从返回的Uri中提取新笔记的ID（假设ID是Uri路径段的第二个元素）
            noteId = Long.valueOf(uri.getPathSegments().get(1));
        } catch (NumberFormatException e) {
            // 如果提取ID时发生数字格式异常，则记录错误日志，并将noteId设置为0
            Log.e(TAG, "Get note id error :" + e.toString());
            noteId = 0;
        }
        // 如果noteId为-1（尽管在正常情况下不太可能，因为Long.valueOf不会返回-1），则抛出异常
        if (noteId == -1) {
            throw new IllegalStateException("Wrong note id:" + noteId);
        }
        // 返回新笔记的ID
        return noteId;
    }
 
    // Note类的无参构造函数
    public Note() {
        // 在构造函数中初始化mNoteDiffValues和mNoteData对象
        mNoteDiffValues = new ContentValues();
        mNoteData = new NoteData();
    }


    // 定义一个公开的方法，用于设置笔记的某个键值对，并标记笔记为已修改和更新修改时间
public void setNoteValue(String key, String value) {
    // 将键值对存储到mNoteDiffValues中，这通常用于记录要同步到数据库的数据变化
    mNoteDiffValues.put(key, value);
    // 将LOCAL_MODIFIED字段设置为1，表示笔记已被本地修改
    mNoteDiffValues.put(NoteColumns.LOCAL_MODIFIED, 1);
    // 更新MODIFIED_DATE字段为当前时间，表示笔记的最后修改时间
    mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis());
}
 
// 定义一个公开的方法，用于设置文本数据的某个键值对
public void setTextData(String key, String value) {
    // 调用mNoteData的setTextData方法，将键值对存储到文本数据中
    mNoteData.setTextData(key, value);
}
 
// 定义一个公开的方法，用于设置文本数据的ID
public void setTextDataId(long id) {
    // 调用mNoteData的setTextDataId方法，设置文本数据的ID
    mNoteData.setTextDataId(id);
}
 
// 定义一个公开的方法，用于获取文本数据的ID
public long getTextDataId() {
    // 返回mNoteData中存储的文本数据ID
    return mNoteData.mTextDataId;
}
 
// 定义一个公开的方法，用于设置通话数据的ID
public void setCallDataId(long id) {
    // 调用mNoteData的setCallDataId方法，设置通话数据的ID
    mNoteData.setCallDataId(id);
}
 
// 定义一个公开的方法，用于设置通话数据的某个键值对
public void setCallData(String key, String value) {
    // 调用mNoteData的setCallData方法，将键值对存储到通话数据中
    mNoteData.setCallData(key, value);
}
 
// 定义一个公开的方法，用于检查笔记是否已被本地修改
public boolean isLocalModified() {
    // 如果mNoteDiffValues中有数据变化，或者mNoteData也被标记为已修改，则返回true
    return mNoteDiffValues.size() > 0 || mNoteData.isLocalModified();
}
 
// 定义一个公开的方法，用于同步笔记数据到数据库
public boolean syncNote(Context context, long noteId) {
    // 检查传入的noteId是否有效（大于0）
    if (noteId <= 0) {
        // 如果noteId无效，则抛出异常
        throw new IllegalArgumentException("Wrong note id:" + noteId);
    }
 
    // 检查笔记是否已被本地修改
    if (!isLocalModified()) {
        // 如果笔记没有被修改，则直接返回true，表示同步成功（因为没有需要同步的变化）
        return true;
    }

        /**
         * In theory, once data changed, the note should be updated on {@link NoteColumns#LOCAL_MODIFIED} and
         * {@link NoteColumns#MODIFIED_DATE}. For data safety, though update note fails, we also update the
         * note data info
         */
       // 定义一个名为NoteData的私有内部类，用于管理笔记的文本数据和通话数据
private class NoteData {
    // 文本数据的ID
    private long mTextDataId;
    // 存储文本数据的ContentValues对象
    private ContentValues mTextDataValues;
    // 通话数据的ID
    private long mCallDataId;
    // 存储通话数据的ContentValues对象
    private ContentValues mCallDataValues;
    // 用于日志记录的标签
    private static final String TAG = "NoteData";
 
    // NoteData的构造函数，初始化成员变量
    public NoteData() {
        mTextDataValues = new ContentValues();
        mCallDataValues = new ContentValues();
        mTextDataId = 0;
        mCallDataId = 0;
    }
 
    // 检查文本数据或通话数据是否已被修改
    boolean isLocalModified() {
        return mTextDataValues.size() > 0 || mCallDataValues.size() > 0;
    }
 
    // 设置文本数据的ID，并检查ID是否有效
    void setTextDataId(long id) {
        if(id <= 0) {
            throw new IllegalArgumentException("Text data id should larger than 0");
        }
        mTextDataId = id;
    }
 
    // 设置通话数据的ID，并检查ID是否有效
    void setCallDataId(long id) {
        if (id <= 0) {
            throw new IllegalArgumentException("Call data id should larger than 0");
        }
        mCallDataId = id;
    }

        void setCallData(String key, String value) {
    // 将键值对放入mCallDataValues中，用于存储通话数据
    mCallDataValues.put(key, value);
    // 标记笔记在本地已被修改
    mNoteDiffValues.put(NoteColumns.LOCAL_MODIFIED, 1);
    // 更新笔记的修改日期
    mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis());
        }
        void setTextData(String key, String value) {
    // 将键值对放入mTextDataValues中，用于存储文本数据
    mTextDataValues.put(key, value);
    // 标记笔记在本地已被修改
    mNoteDiffValues.put(NoteColumns.LOCAL_MODIFIED, 1);
    // 更新笔记的修改日期
    mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis());
        }
        Uri pushIntoContentResolver(Context context, long noteId) {
    // 检查传入的noteId是否有效
    if (noteId <= 0) {
        throw new IllegalArgumentException("Wrong note id:" + noteId);
    }
 
    // 创建一个操作列表，用于批量操作内容提供者
    ArrayList<ContentProviderOperation> operationList = new ArrayList<ContentProviderOperation>();
    // 初始化一个操作构建器，初始值为null，后面会根据需要赋值
    ContentProviderOperation.Builder builder = null;
 
    // 如果mTextDataValues中有数据需要插入或更新
    if(mTextDataValues.size() > 0) {
        // 将noteId放入mTextDataValues中，以便与特定的笔记关联
        mTextDataValues.put(DataColumns.NOTE_ID, noteId);
        // 如果mTextDataId为0，表示需要插入新数据
        if (mTextDataId == 0) {
            // 设置MIME类型，表示这是文本笔记数据
            mTextDataValues.put(DataColumns.MIME_TYPE, TextNote.CONTENT_ITEM_TYPE);
            // 插入新数据到内容提供者，并获取返回的Uri
            Uri uri = context.getContentResolver().insert(Notes.CONTENT_DATA_URI, mTextDataValues);
            // 尝试从Uri中提取新插入数据的ID，并设置到mTextDataId中
            try {
                setTextDataId(Long.valueOf(uri.getPathSegments().get(1)));
            } catch (NumberFormatException e) {
                // 如果提取ID失败，记录错误日志，并清空mTextDataValues
                Log.e(TAG, "Insert new text data fail with noteId" + noteId);
                mTextDataValues.clear();
                // 返回null表示操作失败
                return null;
            }
        } else {
            // 如果mTextDataId不为0，表示需要更新现有数据
            builder = ContentProviderOperation.newUpdate(ContentUris.withAppendedId(
                    Notes.CONTENT_DATA_URI, mTextDataId));
            builder.withValues(mTextDataValues);
            operationList.add(builder.build());
        }
        // 清空mTextDataValues，因为它已经被处理
        mTextDataValues.clear();
    }
 
    // 如果mCallDataValues中有数据需要插入或更新，处理逻辑与mTextDataValues相同
    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);
            // 如果结果数组为空、长度为0或第一个结果为null，表示操作失败，返回null
            // 否则，返回与noteId关联的笔记URI
            return (results == null || results.length == 0 || results[0] == null) ? null
                    : ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId);
        } catch (RemoteException e) {
            // 如果发生远程异常，记录错误日志，并返回null
            Log.e(TAG, String.format("%s: %s", e.toString(), e.getMessage()));
            return null;
        } catch (OperationApplicationException e) {
            // 如果发生操作应用异常，记录错误日志，并返回null
            Log.e(TAG, String.format("%s: %s", e.toString(), e.getMessage()));
            return null;
        }
    }
    // 如果没有任何数据需要处理，返回null
    return null;
}