【Cocos2d-x源码分析】 UserDefault如何保存本地数据

最新推荐文章于 2018-07-13 11:10:50 发布

弗莱德笔记

最新推荐文章于 2018-07-13 11:10:50 发布

阅读量3.6k

点赞数

本文链接：https://blog.youkuaiyun.com/Xiejingfa/article/details/50580793

版权

原创作品，转载请标明：http://blog.youkuaiyun.com/Xiejingfa/article/details/50580793

Cocos2d-x提供了UserDefault类来在本地保存简单的游戏数据。今天我们的目标就是分析UserDefault是如何工作的。

本文的分析的是Cocosd2-x 3.8版本的源码，使用Vistual Studio2013。

1、初探UserDefualt

熟悉Coco2d-x的童鞋应该都知道，UserDefault类主要提供了以下接口来保存数据。

代码1：

    // 获取bool类型数据
    bool    getBoolForKey(const char* key);
    virtual bool getBoolForKey(const char* key, bool defaultValue);
    // 获取int类型数据
    int     getIntegerForKey(const char* key);
    virtual int getIntegerForKey(const char* key, int defaultValue);
    // 获取float类型数据
    float    getFloatForKey(const char* key);
    virtual float getFloatForKey(const char* key, float defaultValue);
    // 获取double类型数据
    double  getDoubleForKey(const char* key);
    virtual double getDoubleForKey(const char* key, double defaultValue);
    // 获取string类型数据
    std::string getStringForKey(const char* key);
    virtual std::string getStringForKey(const char* key, const std::string & defaultValue);
    // 获取Data类型数据，从CCData.h中我们可以看到Data其实保存的是
    // unsigned char* _bytes类型数据
    Data getDataForKey(const char* key);
    virtual Data getDataForKey(const char* key, const Data& defaultValue);

    // 获取bool类型数据
    virtual void setBoolForKey(const char* key, bool value)
    // 获取int类型数据
    virtual void setIntegerForKey(const char* key, int value);
    // 获取float类型数据
    virtual void setFloatForKey(const char* key, float value);
    // 获取double类型数据
    virtual void setDoubleForKey(const char* key, double value);
    // 获取string类型数据
    virtual void setStringForKey(const char* key, const std::string & value);
    // 获取Data类型数据
    virtual void setDataForKey(const char* key, const Data& value);

    static UserDefault* getInstance();

其中，UserDefault在实现上使用了单例模式，getInstance方法返回唯一的实例。setXXXForKey用来设置指定类型的数据，getXXXForKey用来获取指定类型的数据。这几个接口简单易懂，那接下来，我们就到源码里面看看UserDefault是如何保存本地数据的。

2、UserDefault::getInstance()实现

首先，我们肯定要先看看UserDefault是如何初始化的，我们找到UserDefault::getInstance()函数。

代码2：

UserDefault* UserDefault::getInstance()
{
    if (!_userDefault)
    {
        initXMLFilePath();

        // only create xml file one time
        // the file exists after the program exit
        if ((!isXMLFileExist()) && (!createXMLFile()))
        {
            return nullptr;
        }

        _userDefault = new (std::nothrow) UserDefault();
    }

    return _userDefault;
}

代码2是getInstance的实现代码，里面出现了“XMLFilePath”和“XMLFile”字样，我们是不是可以大胆地猜测：UserDefault会不会将数据保存在XML文件中？带着这个猜测，我们继续往下分析。在代码2中，_userDefault的定义如下：

UserDefault* UserDefault::_userDefault = nullptr;

当用户第一次调用getInstance函数时候，！ _userDefault判断必然为真，所以执行了if语句里面的代码。其实这就是单例模式的典型实现方式。Cocos2d-x采用了“懒汉式”的单例模式实现，当用户真正需要使用时再进行初始化。该初始化过程主要做了下面三件事：

initXMLFilePath()
isXMLFileExist()
createXMLFile()

我们先来看看initXMLFilePath函数的实现：

代码3：

void UserDefault::initXMLFilePath()
{
    if (! _isFilePathInitialized)
    {
        _filePath += FileUtils::getInstance()->getWritablePath() + XML_FILE_NAME;
        _isFilePathInitialized = true;
    }    
}

在代码3中，我们可以看到，initXMLFilePath函数主要功能就是初始化文件的存放路径。文件的名字XML_FILE_NAME被定义为：

#define XML_FILE_NAME "UserDefault.xml"

到这里我们是不是几乎可以确定，UserDefault就是利用xml文件来保存本地数据，而且这个文件的名称就叫“UserDefault.xml”！那这个文件又被存放在哪里呢？这又依赖于FileUtils类来根据不同的平台来确定不同的目录。关于这一点，大家可以看看我的另一篇博客【Cocos2d-x源码分析】 FileUtils如何跨平台查找文件，在这里就不再一一分析了。

对于_filePath 的值，我们可以将其输出，看看它具体的值。我在win32中调用UserDefault::getInstance()->getXMLFilePath()函数输出如下：

C:/Users/fred/AppData/Local/CocosTest/UserDefault.xml

接下来isXMLFileExist方法判断_filePath 路径上的xml文件是否存在，如果不存在则调用createXMLFile方法创建一个新的xml文件。

代码4：

// create new xml file
bool UserDefault::createXMLFile()
{
    bool bRet = false;  
    tinyxml2::XMLDocument *pDoc = new tinyxml2::XMLDocument(); 
    if (nullptr==pDoc)  
    {  
        return false;  
    }  
    tinyxml2::XMLDeclaration *pDeclaration = pDoc->NewDeclaration(nullptr);  
    if (nullptr==pDeclaration)  
    {  
        return false;  
    }  
    pDoc->LinkEndChild(pDeclaration); 
    tinyxml2::XMLElement *pRootEle = pDoc->NewElement(USERDEFAULT_ROOT_NAME);  
    if (nullptr==pRootEle)  
    {  
        return false;  
    }  
    pDoc->LinkEndChild(pRootEle);  
    bRet = tinyxml2::XML_SUCCESS == pDoc->SaveFile(FileUtils::getInstance()->getSuitableFOpen(_filePath).c_str());

    if(pDoc)
    {
        delete pDoc;
    }

    return bRet;
}

在代码4中，我们可以捕捉到两个重要信息：

一是Cocos2d-x使用tinyxml2来操作xml文件。由于本文只是分析UserDefault的实现机制，对于tinyxml2就不展开介绍，需要进一步了解的童鞋可以移步官网或者GitHub

二是createXMLFile函数创建了一个xml文件并设置了头节点，然后保存在_filePath指定的路径上。我们找到该xml文件，可以看到初始化后的xml文件内容如下：

<?xml version="1.0" encoding="UTF-8"?>
<userDefaultRoot/>

3、setXXXForKey和getXXXForKey的实现

通过前面的分析，我们知道UserDefault通过xml文件来保存本地数据。如果你在平时编程时有使用过xml文件，是不是很容易猜到setXXXForKey和getXXXForKey是如何实现的？没错，其实就是创建 or 查找结点，然后读写该结点。由于不同类型的setXXXForKey和getXXXForKey方法有很大的相似性，这里我们就挑比较典型的setStringForKey和getStringForKey方法来讲解一下。

getStringForKey的实现如下：

代码5：

std::string UserDefault::getStringForKey(const char* pKey)
{
    return getStringForKey(pKey, "");
}

string UserDefault::getStringForKey(const char* pKey, const std::string & defaultValue)
{
    const char* value = nullptr;
    tinyxml2::XMLElement* rootNode;
    tinyxml2::XMLDocument* doc;
    tinyxml2::XMLElement* node;
    node =  getXMLNodeForKey(pKey, &rootNode, &doc);
    // find the node
    if (node && node->FirstChild())
    {
        value = (const char*)(node->FirstChild()->Value());
    }

    string ret = defaultValue;

    if (value)
    {
        ret = string(value);
    }

    if (doc) delete doc;

    return ret;
}

在代码5中，我们可以看到getStringForKey(const char* pKey)实际上调用了getStringForKey(const char* pKey, const std::string & defaultValue)来实现数据保存，这对于其他类型的getter方法也差不多如此。getStringForKey方法中最重要的是getXMLNodeForKey函数。从它的命名我们可以看出，该函数在xml文件中查找指定key的xml结点然后返回，这样getStringForKey方法就直接从目标结点中读取保存的数据然后返回。我们进一步跟踪，看看getXMLNodeForKey函数的实现。

代码6：

static tinyxml2::XMLElement* getXMLNodeForKey(const char* pKey, tinyxml2::XMLElement** rootNode, tinyxml2::XMLDocument **doc)
{
    tinyxml2::XMLElement* curNode = nullptr;

    // check the key value
    if (! pKey)
    {
        return nullptr;
    }

    do 
    {
         tinyxml2::XMLDocument* xmlDoc = new tinyxml2::XMLDocument();
        *doc = xmlDoc;

        std::string xmlBuffer = FileUtils::getInstance()->getStringFromFile(UserDefault::getInstance()->getXMLFilePath());

        if (xmlBuffer.empty())
        {
            CCLOG("can not read xml file");
            break;
        }
        xmlDoc->Parse(xmlBuffer.c_str(), xmlBuffer.size());

        // get root node
        *rootNode = xmlDoc->RootElement();
        if (nullptr == *rootNode)
        {
            CCLOG("read root node error");
            break;
        }
        // find the node
        curNode = (*rootNode)->FirstChildElement();
        while (nullptr != curNode)
        {
            const char* nodeName = curNode->Value();
            if (!strcmp(nodeName, pKey))
            {
                break;
            }

            curNode = curNode->NextSiblingElement();
        }
    } while (0);

    return curNode;
}

从代码5中，我们可以看到getXMLNodeForKey的工作就是将xml文件读进内存、解析、遍历节点直至找到参数key对应的目标结点。这里涉及tinyxml2较多的xml操作函数，感兴趣的童鞋可以自动gg一下。

不知道你有没有注意到getXMLNodeForKey并不是UserDefault的成员函数，而是被定义为static函数，这样它的可见性就被限制在仅该文件可见，作者给出了这样做的理由：

/**
 * define the functions here because we don't want to
 * export xmlNodePtr and other types in "CCUserDefault.h"
 */

接下来，再来看看setStringForKey函数的实现。

代码7：

void UserDefault::setStringForKey(const char* pKey, const std::string & value)
{
    // check key
    if (! pKey)
    {
        return;
    }

    setValueForKey(pKey, value.c_str());
}

不用解释，我们继续追踪setValueForKey

代码8：

static void setValueForKey(const char* pKey, const char* pValue)
{
     tinyxml2::XMLElement* rootNode;
    tinyxml2::XMLDocument* doc;
    tinyxml2::XMLElement* node;
    // check the params
    if (! pKey || ! pValue)
    {
        return;
    }
    // find the node
    node = getXMLNodeForKey(pKey, &rootNode, &doc);
    // if node exist, change the content
    if (node)
    {
        if (node->FirstChild())
        {
            node->FirstChild()->SetValue(pValue);
        }
        else
        {
            tinyxml2::XMLText* content = doc->NewText(pValue);
            node->LinkEndChild(content);
        }
    }
    else
    {
        if (rootNode)
        {
            tinyxml2::XMLElement* tmpNode = doc->NewElement(pKey);//new tinyxml2::XMLElement(pKey);
            rootNode->LinkEndChild(tmpNode);
            tinyxml2::XMLText* content = doc->NewText(pValue);//new tinyxml2::XMLText(pValue);
            tmpNode->LinkEndChild(content);
        }    
    }

    // save file and free doc
    if (doc)
    {
        doc->SaveFile(FileUtils::getInstance()->getSuitableFOpen(UserDefault::getInstance()->getXMLFilePath()).c_str());
        delete doc;
    }
}

在代码8中，我们可以根据注释来阅读这段代码。该函数主要做了以下事情：

在xml文件中查找参数key指定的结点
如果找到目标结点，直接修改对应的值；如果没有找到目标结点，则创建一个新结点并链接到xml字符串中。
保存修改后的文件，释放资源

总结：

UserDefault类通过XML文件来将游戏数据保存本地，该文件名称为UserDefault.xml。
每次调用setXXXForKey和getXXXForKey函数时，UserDefault总是需要经历读入解析UserDefault.xml文件，查找参数key指定的结点，进行读/写操作，保存文件（如果前面是写操作）等步骤。
UserDefault虽然提供了flush函数，但是该函数并未进行任何操作。UserDefault在每次的setXXXForKey的最后写回文件