Troubleshooting JSONStore

Overview

Find information to help resolve issues that you might encounter when you use the JSONStore API.

Provide information when you ask for help

It is better to provide more information than to risk not providing enough information. The following list is a good starting point for the information that is required to help with JSONStore issues.

• Operating system and version. For example, Windows XP SP3 Virtual Machine or Mac OSX 10.8.3.
• Eclipse version. For example, Eclipse Indigo 3.7 Java EE.
• JDK version. For example, Java SE Runtime Environment (build 1.7).
• Mobile Foundation version. For example, IBM Worklight V5.0.6 Developer Edition.
• iOS version. For example, iOS Simulator 6.1 or iPhone 4S iOS 6.0 (deprecated, see Deprecated features and API elements).
• Android version. For example, Android Emulator 4.1.1 or Samsung Galaxy Android 4.0 API Level 14.
• Windows version. For example, Windows 8, Windows 8.1, or Windows Phone 8.1.
• adb version. For example, Android Debug Bridge version 1.0.31.
• Logs, such as Xcode output on iOS or logcat output on Android.

Try to isolate the issue

Follow these steps to isolate the issue to more accurately report a problem.

1. Reset the emulator (Android) or simulator (iOS) and call the destroy API to start with a clean system.
2. Ensure that you are running on a supported production environment.
   • Android >= 2.3 ARM v7/ARM v8/x86 emulator or device
   • iOS >= 6.0 simulator or device (deprecated)
   • Windows 8.1/10 ARM/x86/x64 simulator or device
3. Try to turn off encryption by not passing a password to the init or open APIs.

4. Look at the SQLite database file that is generated by JSONStore. Encryption must be turned off.

   • Android emulator:

   $ adb shell
   $ cd /data/data/com.<app-name>/databases/wljsonstore
   $ sqlite3 jsonstore.sqlite
   

   • iOS Simulator:

   $ cd ~/Library/Application Support/iPhone Simulator/7.1/Applications/<id>/Documents/wljsonstore
   $ sqlite3 jsonstore.sqlite
   

   • Windows 8.1 Universal / Windows 10 UWP simulator

   $ cd C:\Users\<username>\AppData\Local\Packages\<id>\LocalState\wljsonstore
   $ sqlite3 jsonstore.sqlite
   

   • Note: JavaScript only implementation that runs on a web browser (Firefox, Chrome, Safari, Internet Explorer) does not use an SQLite database. The file is stores in HTML5 LocalStorage.
   • Look at the searchFields with .schema and select data with SELECT * FROM <collection-name>;. To exit sqlite3, type .exit. If you pass a user name to the init method, the file is called the-username.sqlite. If you do not pass a user name, the file is called jsonstore.sqlite by default.

5. (Android only) Enable verbose JSONStore.

   adb shell setprop log.tag.jsonstore-core VERBOSE
   adb shell getprop log.tag.jsonstore-core
   

6. Use the debugger.

Common issues

Understanding the following JSONStore characteristics can help resolve some of the common issues that you might encounter.

• The only way to store binary data in JSONStore is to first encode it in base64. Store file names or paths instead of the actual files in JSONStore.
• Accessing JSONStore data from native code is possible only in IBM Worklight Foundation V6.2.0.
• There is no limit on how much data you can store inside JSONStore, beyond limits that are imposed by the mobile operating system.
• JSONStore provides persistent data storage. It is not only stored in memory.
• The init API fails when the collection name starts with a digit or symbol. IBM Worklight V5.0.6.1 and later returns an appropriate error: 4 BAD\_PARAMETER\_EXPECTED\_ALPHANUMERIC\_STRING
• There is a difference between a number and an integer in search fields. Numeric values like 1 and 2 are stored as 1.0 and 2.0 when the type is number. They are stored as 1 and 2 when the type is integer.
• If an application is forced to stop or crashes, it always fails with error code -1 when the application is started again and the init or open API is called. If this problem happens, call the closeAll API first.
• The JavaScript implementation of JSONStore expects code to be called serially. Wait for an operation to finish before you call the next one.
• Transactions are not supported in Android 2.3.x for Cordova applications.
• When you use JSONStore on a 64-bit device, you might see the following error: java.lang.UnsatisfiedLinkError: dlopen failed: "..." is 32-bit instead of 64-bit
• This error means that you have 64-bit native libraries in your Android project, and JSONStore does not currently work when you use these libraries. To confirm, go to src/main/libs or src/main/jniLibs under your Android project, and check whether you have the x86_64 or arm64-v8a folders. If you do, delete these folders, and JSONStore can work again.

• In some cases (or environments), the flow enters wlCommonInit() before JSONStore plugin is initialized. This causes JSONStore related API calls to fail. The cordova-plugin-mfp bootstrap calls WL.Client.init automatically which triggers the wlCommonInit function when it is completed. This initialization process is different for the JSONStore plugin. The JSONStore plugin does not have a way to halt the WL.Client.init call. Across different environments, it may happen that the flow enters wlCommonInit() before mfpjsonjslloaded completes. To ensure the ordering of mfpjsonjsloaded and mfpjsloaded events, the developer has the option of calling WL.CLient.init manually. This will remove the need for having platform specific code.

  Follow the steps below to configure calling of WL.CLient.init manually:

  1. In config.xml, change the clientCustomInit property to true.
  • In index.js file:
    • add the following line at the beginning of the file:

      document.addEventListener('mfpjsonjsloaded', initWL, false);
      

    • leave the WL.JSONStore.init call in wlCommonInit()

    • add the following function:

      function initWL(){                                                     
        var options = typeof wlInitOptions !== 'undefined' ? wlInitOptions
        : {};                                                                
        WL.Client.init(options);                                           
      }                                                                      
      

  This will wait for the mfpjsonjsloaded event (outside of wlCommonInit), this will ensure that the script has been loaded and will subsequently call WL.Client.init which will trigger wlCommonInit, this will then call WL.JSONStore.init.

Store internals

See an example of how JSONStore data is stored.

The key elements in this simplified example:

• _id is the unique identifier (for example, AUTO INCREMENT PRIMARY KEY).
• json contains an exact representation of the JSON object that is stored.
• name and age are search fields.
• key is an extra search field.

When you search by using one of the following queries or a combination of them: {_id : 1}, {name: 'carlos'}, {age: 99}, {key: 'c'}, the returned document is {_id: 1, json: {name: 'carlos', age: 99} }.

The other internal JSONStore fields are:

• _dirty: Determines whether the document was marked as dirty or not. This field is useful to track changes to the documents.
• _deleted: Marks a document as deleted or not. This field is useful to remove objects from the collection, to later use them to track changes with your backend and decide whether to remove them or not.
• _operation: A string that reflects the last operation to be performed on the document (for example, replace).

JSONStore errors

JavaScript

JSONStore uses an error object to return messages about the cause of failures.

When an error occurs during a JSONStore operation (for example the find, and add methods in the JSONStoreInstance class) an error object is returned. It provides information about the cause of the failure.

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.
}

Not all the key/value pairs are part of every error object. For example, the doc value is only available when the operation failed because of a document (for example the remove method in the JSONStoreInstance class) failed to remove a document.

Objective-C

All of the APIs that might fail take an error parameter that takes an address to an NSError object. If you don not want to be notified of errors, you can pass in nil. When an operation fails, the address is populated with an NSError, which has an error and some potential userInfo. The userInfo might contain extra details (for example, the document that caused the failure).

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

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

Java

All of the Java API calls throw a certain exception, depending on the error that happened. You can either handle each exception separately, or you can catch JSONStoreException as an umbrella for all JSONStore exceptions.

try {
  WL.JSONStore.closeAll();
}

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

List of error codes

List of common error codes and their description: