Android 应用程序中的 JSONStore

improve this page | report issue


先决条件

跳转至：

添加 JSONStore

  1. 在 Android → Gradle 脚本中，选择 build.gradle（模块：应用程序）文件。

  2. 将以下代码添加到现有 dependencies 部分：

compile 'com.ibm.mobile.foundation:ibmmobilefirstplatformfoundationjsonstore:8.0.+'
  1. 将以下内容添加到 build.gradle 文件的“DefaultConfig”部分。 
      ndk {
     abiFilters "armeabi", "armeabi-v7a", "x86", "mips"
   }

    注：我们将添加 abiFilters 以确保具有 JSONStore 的应用程序将在上述指定的任何体系结构中运行。 由于 JSONStore 依赖于仅支持这些体系结构的第三方库，因此需要此项。

基本用法

打开

使用 openCollections 打开一个或多个 JSONStore 集合。

启动或供应集合意味着创建包含集合和文档的持久存储（如果不存在）。 如果持久存储已加密且传递了正确密码，那么将运行必需的安全过程才能访问数据。

有关可在初始化时启用的可选功能，请参阅本教程第二部分中的安全性、多用户支持和 MobileFirst 适配器集成。

Context context = getContext();
try {
  JSONStoreCollection people = new JSONStoreCollection("people");
  people.setSearchField("name", SearchFieldType.STRING);
  people.setSearchField("age", SearchFieldType.INTEGER);
  List<JSONStoreCollection> collections = new LinkedList<JSONStoreCollection>();
  collections.add(people);
  WLJSONStore.getInstance(context).openCollections(collections);
  // handle success
} catch(JSONStoreException e) {
  // handle failure
}

获取

使用 getCollectionByName 来创建集合存取器。 必须先调用 openCollections，然后才能调用 getCollectionByName。

Context context = getContext();
try {
  String collectionName = "people";
  JSONStoreCollection collection = WLJSONStore.getInstance(context).getCollectionByName(collectionName);
  // handle success
} catch(JSONStoreException e) {
  // handle failure
}

变量 collection 现在可用于在 people 集合上执行操作，例如，add、find 和 replace

添加

使用 addData 将数据存储为集合中的文档

Context context = getContext();
try {
  String collectionName = "people";
  JSONStoreCollection collection = WLJSONStore.getInstance(context).getCollectionByName(collectionName);
  //Add options.
  JSONStoreAddOptions options = new JSONStoreAddOptions();
  options.setMarkDirty(true);
  JSONObject data = new JSONObject("{age: 23, name: 'yoel'}")
  collection.addData(data, options);
  // handle success
} catch(JSONStoreException e) {
  // handle failure
}

查找

使用 findDocuments 来通过查询查找集合中的文档。 使用 findAllDocuments 来检索集合中的所有文档。 使用 findDocumentById 来按文档唯一标识进行搜索。

Context context = getContext();
try {
  String collectionName = "people";
  JSONStoreQueryPart queryPart = new JSONStoreQueryPart();
  // fuzzy search LIKE
  queryPart.addLike("name", name);
  JSONStoreQueryParts query = new JSONStoreQueryParts();
  query.addQueryPart(queryPart);
  JSONStoreFindOptions options = new JSONStoreFindOptions();
  // returns a maximum of 10 documents, default: returns every document
  options.setLimit(10);
  JSONStoreCollection collection = WLJSONStore.getInstance(context).getCollectionByName(collectionName);
  List<JSONObject> results = collection.findDocuments(query, options);
  // handle success
} catch(JSONStoreException e) {
  // handle failure
}

替换

使用 replaceDocument 来修改集合中的文档。 用于执行替换的字段是文档唯一标识 _id。

Context context = getContext();
try {
  String collectionName = "people";
  JSONStoreCollection collection = WLJSONStore.getInstance(context).getCollectionByName(collectionName);
  JSONStoreReplaceOptions options = new JSONStoreReplaceOptions();
  // mark data as dirty
  options.setMarkDirty(true);
  JSONStore replacement = new JSONObject("{_id: 1, json: {age: 23, name: 'chevy'}}");
  collection.replaceDocument(replacement, options);
  // handle success
} catch(JSONStoreException e) {
  // handle failure
}

此示例假定文档 {_id: 1, json: {name: 'yoel', age: 23} } 位于集合中。

除去

使用 removeDocumentById 以删除集合中的文档。 在调用 markDocumentClean 之前，不会从集合中擦除文档。 有关更多信息，请参阅本教程后面的 MobileFirst 适配器集成部分。

Context context = getContext();
try {
  String collectionName = "people";
  JSONStoreCollection collection = WLJSONStore.getInstance(context).getCollectionByName(collectionName);
  JSONStoreRemoveOptions options = new JSONStoreRemoveOptions();
  // Mark data as dirty
  options.setMarkDirty(true);
  collection.removeDocumentById(1, options);
  // handle success
} catch(JSONStoreException e) {
  // handle failure
}

除去集合

使用 removeCollection 以删除集合中存储的所有文档。 此操作类似于数据库术语中的删除表。

Context context = getContext();
try {
  String collectionName = "people";
  JSONStoreCollection collection = WLJSONStore.getInstance(context).getCollectionByName(collectionName);
  collection.removeCollection();
  // handle success
} catch(JSONStoreException e) {
  // handle failure
}

销毁

使用 destroy 以除去以下数据：

  • 所有文档
  • 所有集合
  • 所有存储区 - 请参阅本教程后面的多用户支持。
  • 所有 JSONStore 元数据和安全工件 - 请参阅本教程后面的安全性
Context context = getContext();
try {
  WLJSONStore.getInstance(context).destroy();
  // handle success
} catch(JSONStoreException e) {
  // handle failure
}

高级用法

安全性

您可以通过将包含密码的 JSONStoreInitOptions 对象传递到 openCollections 函数来保护存储区中的所有集合。 如果未传递密码，那么将不会加密存储区中所有集合的文档。

某些安全元数据存储在共享首选项中 (Android)。
此存储利用 256 位高级加密标准 (AES) 密钥进行加密。 所有密钥通过基于密码的密钥派生功能 2 (PBKDF2) 进行增强。

使用 closeAll 以锁定对所有集合的访问，直至再次调用 openCollections。 如果将 openCollections 当作登录函数，那么可将 closeAll 当作对应的注销函数。

使用 changePassword 来更改密码。

Context context = getContext();
try {
  JSONStoreCollection people = new JSONStoreCollection("people");
  people.setSearchField("name", SearchFieldType.STRING);
  people.setSearchField("age", SearchFieldType.INTEGER);
  List<JSONStoreCollection> collections = new LinkedList<JSONStoreCollection>();
  collections.add(people);
  JSONStoreInitOptions options = new JSONStoreInitOptions();
  options.setPassword("123");
  WLJSONStore.getInstance(context).openCollections(collections, options);
  // handle success
} catch(JSONStoreException e) {
  // handle failure
}

多用户支持

您可以在单个 MobileFirst 应用程序中创建包含不同集合的多个存储。 openCollections 函数可使用包含用户名的选项对象。 如果未指定用户名，那么缺省用户名为“jsonstore”。

Context context = getContext();
try {
  JSONStoreCollection people = new JSONStoreCollection("people");
  people.setSearchField("name", SearchFieldType.STRING);
  people.setSearchField("age", SearchFieldType.INTEGER);
  List<JSONStoreCollection> collections = new LinkedList<JSONStoreCollection>();
  collections.add(people);
  JSONStoreInitOptions options = new JSONStoreInitOptions();
  options.setUsername("yoel");
  WLJSONStore.getInstance(context).openCollections(collections, options);
  // handle success
} catch(JSONStoreException e) {
  // handle failure
}

MobileFirst 适配器集成

此部分假定您熟悉适配器。 适配器集成为可选，其支持将数据从集合发送到适配器以及从适配器将数据获取到集合。 如果需要提高灵活性，可以使用 WLResourceRequest 之类的函数或者自己的 HttpClient 实例来实现这些目标。

适配器实现

创建一个适配器并将其命名为“JSONStoreAdapter”。 将其过程定义为 addPerson、getPeople、pushPeople、removePerson 和 replacePerson。

function getPeople() {
	var data = { peopleList : [{name: 'chevy', age: 23}, {name: 'yoel', age: 23}] };
	WL.Logger.debug('Adapter: people, procedure: getPeople called.');
	WL.Logger.debug('Sending data: ' + JSON.stringify(data));
	return data;
}
function pushPeople(data) {
	WL.Logger.debug('Adapter: people, procedure: pushPeople called.');
	WL.Logger.debug('Got data from JSONStore to ADD: ' + data);
	return;
}
function addPerson(data) {
	WL.Logger.debug('Adapter: people, procedure: addPerson called.');
	WL.Logger.debug('Got data from JSONStore to ADD: ' + data);
	return;
}
function removePerson(data) {
	WL.Logger.debug('Adapter: people, procedure: removePerson called.');
	WL.Logger.debug('Got data from JSONStore to REMOVE: ' + data);
	return;
}
function replacePerson(data) {
	WL.Logger.debug('Adapter: people, procedure: replacePerson called.');
	WL.Logger.debug('Got data from JSONStore to REPLACE: ' + data);
	return;
}

从 MobileFirst 适配器装入数据

要从适配器装入数据，请使用 WLResourceRequest。

WLResponseListener responseListener = new WLResponseListener() {
  @Override
  public void onFailure(final WLFailResponse response) {
    // handle failure
  }
  @Override
  public void onSuccess(WLResponse response) {
    try {
      JSONArray loadedDocuments = response.getResponseJSON().getJSONArray("peopleList");
    } catch(Exception e) {
      // error decoding JSON data
    }
  }
};

try {
  WLResourceRequest request = new WLResourceRequest(new URI("/adapters/JSONStoreAdapter/getPeople"), WLResourceRequest.GET);
  request.send(responseListener);
} catch (URISyntaxException e) {
  // handle error
}

需要推送（脏文档）

调用 findAllDirtyDocuments 将返回名为“脏文档”的数组，这些是包含后端系统上不存在的本地修订的文档。

Context  context = getContext();
try {
  String collectionName = "people";
  JSONStoreCollection collection = WLJSONStore.getInstance(context).getCollectionByName(collectionName);
  List<JSONObject> dirtyDocs = collection.findAllDirtyDocuments();
  // handle success
} catch(JSONStoreException e) {
  // handle failure
}

要阻止 JSONStore 将文档标记为“脏”，请将选项 options.setMarkDirty(false) 传递到 add、replace 和 remove。

推送更改

要将更改推送到适配器，请调用 findAllDirtyDocuments 以获取包含修订的文档列表，然后使用 WLResourceRequest。 在发送数据并且收到成功响应后，确保调用 markDocumentsClean。

WLResponseListener responseListener = new WLResponseListener() {
  @Override
  public void onFailure(final WLFailResponse response) {
    // handle failure
  }
  @Override
  public void onSuccess(WLResponse response) {
    // handle success
  }
};
Context context = getContext();

try {
  String collectionName = "people";
  JSONStoreCollection collection = WLJSONStore.getInstance(context).getCollectionByName(collectionName);
  List<JSONObject> dirtyDocuments = people.findAllDirtyDocuments();

  JSONObject payload = new JSONObject();
  payload.put("people", dirtyDocuments);

  WLResourceRequest request = new WLResourceRequest(new URI("/adapters/JSONStoreAdapter/pushPeople"), WLResourceRequest.POST);
  request.send(payload, responseListener);
} catch(JSONStoreException e) {
  // handle failure
} catch (URISyntaxException e) {
  // handle error
}

样本应用程序的图像

示例应用程序

JSONStoreAndroid 项目包含利用 JSONStore API 集合的本机 Android 应用程序。
随附一个 JavaScript 适配器 Maven 项目。

单击以下载本机 Android 项目。
单击以下载适配器 Maven 项目。

样本用法

遵循样本的 README.md 文件以获取指示信息。

▲
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