对 JSONStore 进行故障诊断

improve this page | report issue


概述

请查找相关信息来帮助解决在使用 JSONStore API 时可能遇到的问题。

在寻求帮助时提供信息

请尽量提供足够的信息,避免承受因未提供足够信息而产生的风险。 为获取解决 JSONStore 问题所需的信息,以下列表是不错的起点。

  • 操作系统和版本。 例如,Windows XP SP3 Virtual Machine 或 Mac OSX 10.8.3。
  • Eclipse 版本。 例如,Eclipse Indigo 3.7 Java EE。
  • JDK 版本。 例如,Java SE Runtime Environment 1.7 版本。
  • Mobile Foundation 版本。 例如,IBM Worklight V5.0.6 Developer Edition。
  • iOS 版本。 例如,iOS Simulator 6.1 或 iPhone 4S iOS 6.0(不推荐,请参阅“不推荐使用的功能和 API 元素”)。
  • Android 版本。 例如,Android Emulator 4.1.1 或 Samsung Galaxy Android 4.0 API Level 14。
  • Windows 版本。 例如,Windows 8、Windows 8.1 或 Windows Phone 8.1。
  • adb 版本。 例如,Android Debug Bridge V1.0.31。
  • 日志,例如,iOS 上的 Xcode 输出或 Android 上的 logcat 输出。

尝试隔离问题

请遵循以下步骤来隔离问题以便更准确地报告问题。

  1. 重置仿真器 (Android) 或模拟器 (iOS) 并调用 destroy API 以从干净的系统开始。
  2. 确保在受支持的生产环境中运行。
    • Android >= 2.3 ARM v7/ARM v8/x86 仿真器或设备
    • iOS >= 6.0 模拟器或设备(不推荐)
    • Windows 8.1/10 ARM/x86/x64 模拟器或设备
  3. 通过不向 init 或 open API 传递密码来尝试关闭加密。
  4. 查看 JSONStore 生成的 SQLite 数据库文件。 必须关闭加密。

    • Android 仿真器:
    $ adb shell
    $ cd /data/data/com.<app-name>/databases/wljsonstore
    $ sqlite3 jsonstore.sqlite
    
    • iOS 模拟器:
    $ cd ~/Library/Application Support/iPhone Simulator/7.1/Applications/<id>/Documents/wljsonstore
    $ sqlite3 jsonstore.sqlite
    
    • Windows 8.1 Universal / Windows 10 UWP 模拟器
    $ cd C:\Users\<username>\AppData\Local\Packages\<id>\LocalState\wljsonstore
    $ sqlite3 jsonstore.sqlite
    
    • 注:在 Web 浏览器(Firefox、Chrome、Safari、Internet Explorer)上运行的“仅 JavaScript”实现不使用 SQLite 数据库。 该文件存储在 HTML5 LocalStorage 中。
    • 查看带有 .schemasearchFields,并通过 SELECT * FROM <collection-name>; 来选择数据。 要退出 sqlite3,请输入 .exit。 如果将用户名传递至 init 方法,那么该文件名为 the-username.sqlite。 如果不传递用户名,那么缺省情况下该文件名为 jsonstore.sqlite
  5. (仅限 Android)启用详细 JSONStore。

    adb shell setprop log.tag.jsonstore-core VERBOSE
    adb shell getprop log.tag.jsonstore-core
    
  6. 使用调试器。

常见问题

了解以下 JSONStore 特征可帮助解决一些可能遇到的常见问题。

  • 在 JSONStore 中存储二进制数据的唯一方法是首先以 base64 格式对该数据进行编码。 将文件名或路径(而不是实际文件)存储在 JSONStore 中。
  • 只能在 IBM Worklight Foundation V6.2.0 中从本机代码访问 JSONStore 数据。
  • 除了移动操作系统施加的限制之外,不会限制 JSONStore 可存储的数据量。
  • JSONStore 提供持久数据存储。 这不只是存储在内存中。
  • 如果集合名称以数字或符号开头,那么 init API 将失败。 IBM Worklight V5.0.6.1 和更高版本会返回相应的错误:4 BAD\_PARAMETER\_EXPECTED\_ALPHANUMERIC\_STRING
  • 在搜索字段中,数字与整数是有区别的。 如果类型为 number,那么数字值 12 将存储为 1.02.0。 如果类型为 integer,它们将存储为 12
  • 如果应用程序被强制停止或崩溃,那么在该应用程序重新启动并调用 initopen API 时,该应用程序总是失败,并返回错误代码 -1。 如果发生此问题,请首先调用 closeAll API。
  • JSONStore 的 JavaScript 实现期望串行调用代码。 等待操作完成,然后再调用下一个操作。
  • 在 Android 2.3.x 中,Cordova 应用程序不支持事务。
  • 在 64 位设备上使用 JSONStore 时,您可能会看到以下错误:java.lang.UnsatisfiedLinkError: dlopen failed: "..." is 32-bit instead of 64-bit
  • 此错误意味着您的 Android 项目中有 64 位本机库,而在使用这些库时,JSONStore 当前无法运行。 要进行确认,请转至 Android 项目下的 src/main/libssrc/main/jniLibs,并检查是否存在 x86_64 或 arm64-v8a 文件夹。 如果存在,请删除这些文件夹,这样 JSONStore 便可以恢复运行。
  • 在某些情况(或环境)下,在初始化 JSONStore 插件前,此流程会进入 wlCommonInit()。 这会导致 JSONStore 相关 API 调用失败。 cordova-plugin-mfp 引导程序会自动调用 WL.Client.init,这样会在调用完成时触发 wlCommonInit 函数。 对于 JSONStore 插件,此初始化过程会有所不同。 JSONStore 插件无法_停止_ WL.Client.init 调用。 根据环境不同,此流程可能在 mfpjsonjslloaded 完成之前进入 wlCommonInit()。 为确保 mfpjsonjsloadedmfpjsloaded 事件的顺序正确,开发人员可以选择手动调用 WL.CLient.init。 这样可避免使用特定于平台的代码。

    请遵循以下步骤以配置为手动调用 WL.CLient.init

    1. config.xml 中,将 clientCustomInit 属性更改为 true
    • index.js 文件中:
      • 在该文件开头添加以下行:
        document.addEventListener('mfpjsonjsloaded', initWL, false);
        
      • WL.JSONStore.init 调用保留在 wlCommonInit()

      • 添加以下函数:
        function initWL(){                                                     
          var options = typeof wlInitOptions !== 'undefined' ? wlInitOptions
          : {};                                                                
          WL.Client.init(options);                                           
        }                                                                      
        

    这会等待 mfpjsonjsloaded 事件(在 wlCommonInit 外部)以确保已装入脚本,随后调用 WL.Client.init 以触发 wlCommonInit,然后调用 WL.JSONStore.init

Store internals

请参阅有关如何存储 JSONStore 数据的示例。

此简化示例中包含以下关键元素:

  • _id 是唯一标识(例如,AUTO INCREMENT PRIMARY KEY)。
  • json 包含已存储的 JSON 对象的确切说明。
  • name 和 age 是搜索字段。
  • key 是额外的搜索字段。
_id key name age JSON
1 c carlos 99 {name: ‘carlos’, age: 99}
2 t tim 100 {name: ‘tim’, age: 100}

使用 {_id : 1}、{name: 'carlos'}{age: 99}、{key: 'c'} 查询或者这些查询的组合进行搜索时,返回的文档为 {_id: 1,json: {name: 'carlos', age: 99} }

其他内部 JSONStore 字段包括:

  • _dirty:确定文档是否标记为脏文档。 此字段用于跟踪文档更改。
  • _deleted:是否将文档标记为已删除。 此字段用于从集合中移除对象,其稍后用于跟踪后端更改以及确定是否移除这些对象。
  • _operation:用于反映要对文档执行的最后一项操作(例如,replace)的字符串。

JSONStore errors

JavaScript

JSONStore 使用 error 对象返回有关故障原因的消息。

在执行 JSONStore 操作(例如,JSONStoreInstance 类中的 findadd 方法)期间发生错误时,会返回一个 error 对象。 该对象提供与故障原因有关的信息。

var errorObject = {
  src: 'find', // Operation that failed.
  err: -50, // Error code.
  msg: 'PERSISTENT\_STORE\_FAILURE', // Error message.
  col: 'people', // Collection name.
  usr: 'jsonstore', // User name.
  doc: {_id: 1, {name: 'carlos', age: 99}}, // Document that is related to the failure.
  res: {...} // Response from the server.
}

并非每个 error 对象都包含所有键/值对。 例如,仅当操作因未能移除某个文档而失败时(例如,JSONStoreInstance 类中的 remove 方法),doc 值才可用。

Objective-C

所有可能失败的 API 都会接受 error 参数,此参数用于向 NSError 对象传递地址。 如果您不想收到错误通知,可以在 nil 中传递。 操作失败时,使用 NSError(包含一个错误和一些可能的 userInfo)填充此地址。 userInfo 可能包含其他详细信息(例如,引起这次失败的文档)。

// This NSError points to an error if one occurs.
NSError* error = nil;

// Perform the destroy.
[JSONStore destroyDataAndReturnError:&error];

Java

根据发生的错误,所有 Java API 调用都会抛出某个特定异常。 您可以单独处理每个异常,也可以捕获 JSONStoreException 作为所有 JSONStore 异常的保护伞。

try {
  WL.JSONStore.closeAll();
}

catch(JSONStoreException e) {
  // Handle error condition.
}

List of error codes

常见错误代码及其描述的列表:

错误代码 描述      
-100 UNKNOWN_FAILURE 无法识别的错误。      
-75 OS_SECURITY_FAILURE 此错误代码与 requireOperatingSystemSecurity 标志相关。 如果 destroy API 未能移除受操作系统安全性保护的安全性元数据(含密码回退的 Touch ID),或者如果 init 或 open API 找不到安全性元数据,那么可能发生此错误。 如果设备不支持操作系统安全性,但请求使用操作系统安全性,那么也可能发生此错误。      
-50 PERSISTENT_STORE_NOT_OPEN JSONStore 已关闭。 尝试首先调用 JSONStore 类中的 open 方法以启用对该存储区的访问。      
-48 TRANSACTION_FAILURE_DURING_ROLLBACK 回滚事务时出现问题。      
-47 TRANSACTION\_FAILURE_DURING_REMOVE_COLLECTION 当正在执行事务时无法调用 removeCollection。      
-46 TRANSACTION_FAILURE_DURING_DESTROY 当正在执行事务时无法调用 destroy。      
-45 TRANSACTION_FAILURE_DURING_CLOSE_ALL 当存在事务时无法调用 closeAll。      
-44 TRANSACTION_FAILURE_DURING_INIT 当正在执行事务时无法初始化该存储区。      
-43 TRANSACTION_FAILURE 事务出现问题。      
-42 NO_TRANSACTION_IN_PROGRESS 当未在执行事务时无法落实回滚的事务。      
-41 TRANSACTION_IN_POGRESS 当正在执行其他事务时无法启动新事务。      
-40 FIPS_ENABLEMENT_FAILURE FIPS 出现问题。      
-24 JSON_STORE_FILE_INFO_ERROR 从文件系统获取文件信息时出现问题。      
-23 JSON_STORE_REPLACE_DOCUMENTS_FAILURE 替换来自集合的文档时出现问题。      
-22 JSON_STORE_REMOVE_WITH_QUERIES_FAILURE 从集合移除文档时出现问题。      
-21 JSON_STORE_STORE_DATA_PROTECTION_KEY_FAILURE 存储数据保护密钥 (DPK) 时出现问题。      
-20 JSON_STORE_INVALID_JSON_STRUCTURE 建立输入数据的索引时出现问题。      
-12 INVALID_SEARCH_FIELD_TYPES 检查要传递到 searchFields 的类型是 string、integer、number 还是 boolean。      
-11 OPERATION_FAILED_ON_SPECIFIC_DOCUMENT 对文档数组执行的操作(例如,replace 方法)在处理特定文档时可能失败。 将返回失败的文档并回滚该事务。 在 Android 上,尝试在不受支持的架构上使用 JSONStore 时也会发生此错误。      
-10 ACCEPT_CONDITION_FAILED 用户提供的 accept 函数返回了 false。      
-9 OFFSET_WITHOUT_LIMIT 要使用偏移量,还必须指定限制。      
-8 INVALID_LIMIT_OR_OFFSET 验证错误,必须是正整数。      
-7 INVALID_USERNAME 验证错误(只能是 [A-Z]、[a-z] 或 [0-9])。      
-6 USERNAME_MISMATCH_DETECTED 要注销,JSONStore 用户必须首先调用 closeAll 方法。 每次只能有一个用户。      
-5 DESTROY_REMOVE_PERSISTENT_STORE_FAILED 当 destroy 方法尝试删除用于保存存储区内容的文件时出现问题。      
-4 DESTROY_REMOVE_KEYS_FAILED 当 destroy 方法尝试清除密钥链 (iOS) 或共享用户首选项 (Android) 时出现问题。      
-3 INVALID_KEY_ON_PROVISION 向加密存储区传递的密码错误。      
-2 PROVISION_TABLE_SEARCH_FIELDS_MISMATCH 搜索字段不是动态字段。 对新搜索字段调用 init 或 open 方法之前,如果不调用 destroy 方法或 removeCollection 方法,那么无法更改搜索字段。 如果更改搜索字段的名称或类型,可能会发生此错误。 例如,将 {key: ‘string’} 更改为 {key: ‘number’},或者将 {myKey: ‘string’} 更改为 {theKey: ‘string’}。      
-1 PERSISTENT_STORE_FAILURE 一般错误。 本机代码出现错误,很可能是在调用 init 方法时。      
0 SUCCESS 在某些情况下,JSONStore 本机代码返回 0 以指示成功。      
1 BAD_PARAMETER_EXPECTED_INT 验证错误。      
2 BAD_PARAMETER_EXPECTED_STRING 验证错误。      
3 BAD_PARAMETER_EXPECTED_FUNCTION 验证错误。      
4 BAD_PARAMETER_EXPECTED_ALPHANUMERIC_STRING 验证错误。      
5 BAD_PARAMETER_EXPECTED_OBJECT 验证错误。      
6 BAD_PARAMETER_EXPECTED_SIMPLE_OBJECT 验证错误。      
7 BAD_PARAMETER_EXPECTED_DOCUMENT 验证错误。      
8 FAILED_TO_GET_UNPUSHED_DOCUMENTS_FROM_DB 用于选择已标记为脏文档的所有文档的查询失败。 在 SQL 中,此查询的示例如下:SELECT * FROM [collection] WHERE _dirty > 0。      
9 NO_ADAPTER_LINKED_TO_COLLECTION 要使用诸如 JSONStoreCollection 类中 push 和 load 方法之类的函数,必须向 init 方法传递适配器。      
10 BAD_PARAMETER_EXPECTED_DOCUMENT_OR_ARRAY_OF_DOCUMENTS 验证错误      
11 INVALID_PASSWORD_EXPECTED_ALPHANUMERIC_STRING_WITH_LENGTH_GREATER_THAN_ZERO 验证错误      
12 ADAPTER_FAILURE 调用 WL.Client.invokeProcedure 时出现问题,尤其是连接到适配器时出现问题。 此错误与尝试调用后端的适配器所发生的故障不同。      
13 BAD_PARAMETER_EXPECTED_DOCUMENT_OR_ID 验证错误      
14 CAN_NOT_REPLACE_DEFAULT_FUNCTIONS 不允许调用 JSONStoreCollection 类中的 enhance 方法来替代现有函数(find 和 add)。      
15 COULD_NOT_MARK_DOCUMENT_PUSHED 推送向适配器发送文档,但 JSONStore 未能将此文档标记为非脏文档。      
16 COULD_NOT_GET_SECURE_KEY 要启动含密码的集合,必须存在到 MobileFirst Server 的连接,因为它会返回“安全的随机令牌”。 IBM Worklight V5.0.6 和更高版本允许开发人员在本地生成安全的随机令牌,以通过 options 对象将 {localKeyGen: true} 传递到 init 方法。      
17 FAILED_TO_LOAD_INITIAL_DATA_FROM_ADAPTER 无法装入数据,因为 WL.Client.invokeProcedure 已调用失败回调。      
18 FAILED_TO_LOAD_INITIAL_DATA_FROM_ADAPTER_INVALID_LOAD_OBJ 传递到 init 方法的 load 对象未通过验证。      
19 INVALID_KEY_IN_LOAD_OBJECT 调用 add 方法时 load 对象中使用的密钥存在问题。      
20 UNDEFINED_PUSH_OPERATION 未定义将脏文档推送至服务器的过程。 例如,调用了 init 方法(新文档为脏文档,操作为“add”)和 push 方法(发现了新文档,操作为“add”),并且未在链接到集合的适配器中找到添加密钥(含添加过程)。 在 init 方法内链接适配器。      
21 INVALID_ADD_INDEX_KEY 额外的搜索字段出现问题。      
22 INVALID_SEARCH_FIELD 某一个搜索字段无效。 请确保传入的搜索字段中不包括 _id、json、_deleted 或 _operation。      
23 ERROR_CLOSING_ALL 一般错误。 本机代码调用 closeAll 方法时发生错误。      
24 ERROR_CHANGING_PASSWORD 无法更改密码。 例如,传递的旧密码错误。      
25 ERROR_DURING_DESTROY 一般错误。 本机代码调用 destroy 方法时发生错误。      
26 ERROR_CLEARING_COLLECTION 一般错误。 当本机代码调用 removeCollection 方法时发生错误。      
27 INVALID_PARAMETER_FOR_FIND_BY_ID 验证错误。      
28 INVALID_SORT_OBJECT 提供的用于排序的数组无效,因为其中一个 JSON 对象无效。 正确的语法是 JSON 对象数组,其中每个对象仅包含单个属性。 此属性将搜索作为排序依据的字段,并指定是升序还是降序。 例如:{searchField1 : “ASC”}。      
29 INVALID_FILTER_ARRAY 提供的用于过滤结果的数组无效。 此数组的正确语法是字符串数组,其中每个字符串是搜索字段或者是内部 JSONStore 字段。 有关更多信息,请参阅“Store internals”。   30 BAD_PARAMETER_EXPECTED_ARRAY_OF_OBJECTS 当数组不是仅含 JSON 对象的数组时发生验证错误。
31 BAD_PARAMETER_EXPECTED_ARRAY_OF_CLEAN_DOCUMENTS 验证错误。      
32 BAD_PARAMETER_WRONG_SEARCH_CRITERIA 验证错误。      
Inclusive terminology note: The Mobile First Platform team is making changes to support the IBM® initiative to replace racially biased and other discriminatory language in our code and content with more inclusive language. While IBM values the use of inclusive language, terms that are outside of IBM's direct influence are sometimes required for the sake of maintaining user understanding. As other industry leaders join IBM in embracing the use of inclusive language, IBM will continue to update the documentation to reflect those changes.
Last modified on June 01, 2020