For up-to-date product documentation, see the IBM MobileFirst Foundation Developer Center.


Java API examples

We can use JSONStore for Cordova applications that use the MobileFirst plug-in.

The following sections contain example implementations for Android devices with JSONStore APIs. Other helpful topics include:


Initialize and open connections, get an Accessor, and add data

// Fill in the blank to get the Android application context. Context ctx = getContext(); try { List<JSONStoreCollection> collections = new LinkedList<JSONStoreCollection>(); // Create the collections object that will be initialized. JSONStoreCollection peopleCollection = new JSONStoreCollection("people"); peopleCollection.setSearchField("name", SearchFieldType.STRING); peopleCollection.setSearchField("age", SearchFieldType.INTEGER); collections.add(peopleCollection); // Optional options object. JSONStoreInitOptions initOptions = new JSONStoreInitOptions(); // Optional username, default 'jsonstore'. initOptions.setUsername("carlos"); // Optional password, default no password. initOptions.setPassword("123"); // Open the collection. WLJSONStore.getInstance(ctx).openCollections(collections, initOptions); // Add data to the collection. JSONObject newDocument = new JSONObject("{name: 'carlos', age: 10}"); JSONStoreAddOptions addOptions = new JSONStoreAddOptions(); addOptions.setMarkDirty(true); peopleCollection.addData(newDocument, addOptions); } catch (JSONStoreException ex) { // Handle failure for any of the previous JSONStore operations (init, add). throw ex; } catch (JSONException ex) { // Handle failure for any JSON parsing issues. throw ex; }


Initialize with a secure random token from the server

// Fill in the blank to get the Android application context. Context ctx = getContext(); // Do an AsyncTask because networking cannot occur inside the activity. AsyncTask<Context, Void, Void> aTask = new AsyncTask<Context, Void, Void>() { protected Void doInBackground(Context... params) { final Context context = params[0]; // Create the request listener that will have the // onSuccess and onFailure callbacks: WLRequestListener listener = new WLRequestListener() { public void onFailure(WLFailResponse failureResponse) { // Handle Failure. } public void onSuccess(WLResponse response) { String secureRandom = response.getResponseText(); try { List<JSONStoreCollection> collections = new LinkedList<JSONStoreCollection>(); // Create the collections object that will be initialized. JSONStoreCollection peopleCollection = new JSONStoreCollection("people"); peopleCollection.setSearchField("name", SearchFieldType.STRING); peopleCollection.setSearchField("age", SearchFieldType.INTEGER); collections.add(peopleCollection); // Optional options object. JSONStoreInitOptions initOptions = new JSONStoreInitOptions(); // Optional username, default 'jsonstore'. initOptions.setUsername("carlos"); // Optional password, default no password. initOptions.setPassword("123"); initOptions.setSecureRandom(secureRandom); // Open the collection. WLJSONStore.getInstance(context).openCollections(collections, initOptions); // Other JSONStore operations (e.g. add, remove, replace, etc.) go here. } catch (JSONStoreException ex) { // Handle failure for any of the previous JSONStore operations (init, add). ex.printStackTrace(); } } }; // Get the secure random from the server: // The length of the random string, in bytes (maximum is 64 bytes). int byteLength = 32; SecurityUtils.getRandomStringFromServer(byteLength, context, listener); return null; } }; aTask.execute(ctx);


Find - locate documents inside the Store

// Fill in the blank to get the Android application context. Context ctx = getContext(); try { // Get the already initialized collection. JSONStoreCollection peopleCollection = WLJSONStore.getInstance(ctx).getCollectionByName("people"); JSONStoreQueryParts findQuery = new JSONStoreQueryParts(); JSONStoreQueryPart part = new JSONStoreQueryPart(); part.addLike("name", "carlos"); part.addLessThan("age", 99); findQuery.addQueryPart(part); // Add additional find options (optional). JSONStoreFindOptions findOptions = new JSONStoreFindOptions(); // Returns a maximum of 10 documents, default no limit. findOptions.setLimit(10); // Skip 0 documents, default no offset. findOptions.setOffset(0); // Search fields to return, default: ['_id', 'json']. findOptions.addSearchFilter("_id"); findOptions.addSearchFilter("json"); // How to sort the returned values, default no sort. findOptions.sortBySearchFieldAscending("name"); findOptions.sortBySeachFieldDescending("age"); // Find documents that match the query. List<JSONObject> results = peopleCollection.findDocuments(findQuery, findOptions); } catch (JSONStoreException ex) { // Handle failure for any of the previous JSONStore operations throw ex; }


Replace - change the documents that are already stored inside a Collection

// Fill in the blank to get the Android application context. Context ctx = getContext(); try { // Get the already initialized collection. JSONStoreCollection peopleCollection = WLJSONStore.getInstance(ctx).getCollectionByName("people"); // Documents will be located with their '_id' field //and replaced with the data in the 'json' field. JSONObject replaceDoc = new JSONObject("{_id: 1, json: {name: 'carlitos', age: 99}}"); // Mark data as dirty (true = yes, false = no), default true. JSONStoreReplaceOptions replaceOptions = new JSONStoreReplaceOptions(); replaceOptions.setMarkDirty(true); // Replace the document. peopleCollection.replaceDocument(replaceDoc, replaceOptions); } catch (JSONStoreException ex) { // Handle failure for any of the previous JSONStore operations. throw ex; }


Remove - delete all documents that match the query

// Fill in the blank to get the Android application context. Context ctx = getContext(); try { // Get the already initialized collection. JSONStoreCollection peopleCollection = WLJSONStore.getInstance(ctx).getCollectionByName("people"); // Documents will be located with their '_id' field. int id = 1; JSONStoreRemoveOptions removeOptions = new JSONStoreRemoveOptions(); // Mark data as dirty (true = yes, false = no), default true. removeOptions.setMarkDirty(true); // Replace the document. peopleCollection.removeDocumentById(id, removeOptions); } catch (JSONStoreException ex) { // Handle failure for any of the previous JSONStore operations throw ex; } catch (JSONException ex) { // Handle failure for any JSON parsing issues. throw ex; }


Count - gets the total number of documents that match a query

// Fill in the blank to get the Android application context. Context ctx = getContext(); try { // Get the already initialized collection. JSONStoreCollection peopleCollection = WLJSONStore.getInstance(ctx).getCollectionByName("people"); // Count all documents that match the query. JSONStoreQueryParts countQuery = new JSONStoreQueryParts(); JSONStoreQueryPart part = new JSONStoreQueryPart(); // Exact match. part.addEqual("name", "carlos"); countQuery.addQueryPart(part); // Replace the document. int resultCount = peopleCollection.countDocuments(countQuery); JSONObject doc = peopleCollection.findDocumentById(resultCount); peopleCollection.replaceDocument(doc); } catch (JSONStoreException ex) { throw ex; }


Destroy - wipes data for all users, destroys the internal storage, and clears security artifacts

// Fill in the blank to get the Android application context. Context ctx = getContext(); try { // Destroy the Store. WLJSONStore.getInstance(ctx).destroy(); } catch (JSONStoreException ex) { // Handle failure for any of the previous JSONStore operations throw ex; }


Security - close access to all opened Collections for the current user

// Fill in the blank to get the Android application context. Context ctx = getContext(); try { // Close access to all collections. WLJSONStore.getInstance(ctx).closeAll(); } catch (JSONStoreException ex) { // Handle failure for any of the previous JSONStore operations. throw ex; }


Security - change the password that is used to access a Store

// The password should be user input. // It is hard-coded in the example for brevity. String username = "carlos"; String oldPassword = "123"; String newPassword = "456"; // Fill in the blank to get the Android application context. Context ctx = getContext(); try { WLJSONStore.getInstance(ctx).changePassword(oldPassword, newPassword, username); } catch (JSONStoreException ex) { // Handle failure for any of the previous JSONStore operations. throw ex; } finally { // It is good practice to not leave passwords in memory oldPassword = null; newPassword = null; }


Push - get all documents that are marked as dirty, send them to a MobileFirst adapter, and mark them clean

// Fill in the blank to get the Android application context. Context ctx = getContext(); try { // Get the already initialized collection. JSONStoreCollection peopleCollection = WLJSONStore.getInstance(ctx).getCollectionByName("people"); // Check if document with _id 3 is dirty. List<JSONObject> allDirtyDocuments = peopleCollection.findAllDirtyDocuments(); // Handle the dirty documents here (e.g. calling an adapter). peopleCollection.markDocumentsClean(allDirtyDocuments); } catch (JSONStoreException ex) { // Handle failure for any of the previous JSONStore operations throw ex; }


Pull - get new data from a MobileFirst adapter

// Fill in the blank to get the Android application context. Context ctx = getContext(); try { // Get the already initialized collection. JSONStoreCollection peopleCollection = WLJSONStore.getInstance(ctx).getCollectionByName("people"); // Pull data here and place in newDocs. For this example, it is hard-coded. List<JSONObject> newDocs = new ArrayList<JSONObject>(); JSONObject doc = new JSONObject("{id: 1, ssn: '111-22-3333', name: 'carlos'}"); newDocs.add(doc); JSONStoreChangeOptions changeOptions = new JSONStoreChangeOptions(); // Data that does not exist in the collection will be added, default false. changeOptions.setAddNew(true); // Mark data as dirty (true = yes, false = no), default false. changeOptions.setMarkDirty(true); // The following example assumes that 'id' and 'ssn' are search fields, // default will use all search fields // and are part of the data that is received. changeOptions.addSearchFieldToCriteria("id"); changeOptions.addSearchFieldToCriteria("ssn"); int changed = peopleCollection.changeData(newDocs, changeOptions); } catch (JSONStoreException ex) { // Handle failure for any of the previous JSONStore operations. throw ex; } catch (JSONException ex) { // Handle failure for any JSON parsing issues. throw ex; }


Check whether a document is dirty

// Fill in the blank to get the Android application context. Context ctx = getContext(); try { // Get the already initialized collection. JSONStoreCollection peopleCollection = WLJSONStore.getInstance(ctx).getCollectionByName("people"); // Check if document with id '3' is dirty. boolean isDirty = peopleCollection.isDocumentDirty(3); } catch (JSONStoreException ex) { // Handle failure for any of the previous JSONStore operations. throw ex; }


Check the number of dirty documents

// Fill in the blank to get the Android application context. Context ctx = getContext(); try { // Get the already initialized collection. JSONStoreCollection peopleCollection = WLJSONStore.getInstance(ctx).getCollectionByName("people"); // Get the count of all dirty documents in the people collection. int totalDirty = peopleCollection.countAllDirtyDocuments(); } catch (JSONStoreException ex) { // Handle failure for any of the previous JSONStore operations. throw ex; }


Remove a Collection

// Fill in the blank to get the Android application context. Context ctx = getContext(); try { // Get the already initialized collection. JSONStoreCollection peopleCollection = WLJSONStore.getInstance(ctx).getCollectionByName("people"); // Remove the collection. The collection object is // no longer usable. peopleCollection.removeCollection(); } catch (JSONStoreException ex) { // Handle failure for any of the previous JSONStore operations. throw ex; }


Clear all data that is inside a Collection

// Fill in the blank to get the Android application context. Context ctx = getContext(); try { // Get the already initialized collection. JSONStoreCollection peopleCollection = WLJSONStore.getInstance(ctx).getCollectionByName("people"); // Clear the collection. peopleCollection.clearCollection(); } catch (JSONStoreException ex) { // Handle failure for any of the previous JSONStore operations. throw ex; }


Start a transaction, add some data, remove a document, commit the transaction and roll back the transaction if there is a failure

// Fill in the blank to get the Android application context. Context ctx = getContext(); try { // Get the already initialized collection. JSONStoreCollection peopleCollection = WLJSONStore.getInstance(ctx).getCollectionByName("people"); WLJSONStore.getInstance(ctx).startTransaction(); JSONObject docToAdd = new JSONObject("{name: 'carlos', age: 99}"); // Find documents that match query. peopleCollection.addData(docToAdd); //Remove added doc. int id = 1; peopleCollection.removeDocumentById(id); WLJSONStore.getInstance(ctx).commitTransaction(); } catch (JSONStoreException ex) { // Handle failure for any of the previous JSONStore operations. // An exception occured. Take care of it to prevent further damage. WLJSONStore.getInstance(ctx).rollbackTransaction(); throw ex; } catch (JSONException ex) { // Handle failure for any JSON parsing issues. // An exception occured. Take care of it to prevent further damage. WLJSONStore.getInstance(ctx).rollbackTransaction(); throw ex; }


Get file information

Context ctx = getContext(); List<JSONStoreFileInfo> allFileInfo = WLJSONStore.getInstance(ctx).getFileInfo(); for(JSONStoreFileInfo fileInfo : allFileInfo) { long fileSize = fileInfo.getFileSizeBytes(); String username = fileInfo.getUsername(); boolean isEncrypted = fileInfo.isEncrypted(); }

Parent topic: JSONStore examples