简介

随着云计算和服务化的快速发展,使得移动应用开发者的精力聚焦在业务的开发及交付方面,但与此同时,开发者也面临三个新的挑战:

  1. 服务的扩展及资源的维护正逐渐占据开发者大量的时间和精力;
  2. 端侧设备的多样化,使多设备间的用户体验难以达到一致;
  3. 资源使用无法按照业务负载按需伸缩,资源利用率低、成本高昂;

AppGallery Connect中基于端云协同打造的Serverless开发服务,助力开发者以高效、低成本、零运维的方式聚焦创新。本codelab主要介绍Serverless中的Cloud DB和Cloud Functions服务。

本体验将围绕AppGallery Connect的Serverless核心能力,通过一个教育场景案例,带您体验基于端云协同的Serverless极速开发能力。

在这个codelab中,您将基于Cloud DB和Cloud Functions创建一款端云协同、离线可用的Android答题应用程序。答题应用的主要功能如下:

  1. 【考试】页面将显示试卷列表。

  1. 单击某个试卷条目上的【进入考试】按钮开始答题,答题中途退出时,应用将会保存已解答题目的答案信息。

  1. 单击【交卷】,计算并显示答题结果。

  1. 交卷后,应用程序计算并保存排行积分,可以在【排行榜】页面中查看排行结果。

您将会学到什么

硬件要求

软件要求

AppGallery Connect提供了代码托管服务,本体验中的代码都已经在代码托管服务中托管,在开始体验之前,请您按照以下内容还原和更新本地代码。

更新代码

  1. 进入答题应用的源码目录,本例源码路径为: D:\HDCServerlessDemo。
  2. 右键选择TortoiseGit->Revert...菜单。
  3. 在弹出的对话框中单击Select/deselect all,然后单击OK
  4. 单击OK,关闭对话框。
  5. 右键选择TortoiseGit->Pull...菜单。
  6. 在弹出的对话框中单击OK
  7. 单击Close,关闭对话框。

试卷列表的UI代码已经基本开发完毕,但需要您补充从Cloud DB中查询试卷信息的代码,这样才能在界面上显示具体的试卷信息,以下内容将指导您完成这个任务。

初始化数据库表元数据

在使用SDK访问Cloud DB前,您需要执行初始化操作,使得SDK获得您要操作的Cloud DB对象元数据信息。打开Android Studio,请在com.huawei.naturalbasedemo.DataRepositoryinit()方法中添加如下代码完成初始化。

public boolean init(long versionCode) { if (versionCode <= 0) { return false; } try { //初始化Cloud DB的NaturalBase对象 naturalBase = NaturalBase.initialize(DB_USER_ID, APP_ID); ArrayList<Class> classes = new ArrayList<>(); classes.add(Student.class); classes.add(ExamPaper.class); classes.add(ExamAnswer.class); classes.add(ExamAnswerResult.class); classes.add(ScoreBoard.class); //加载数据对象的元数据(一个数据对象可理解为一张数据库表) int isSuccess = naturalBase.loadObjectType(versionCode, classes); if (isSuccess == 0) { NaturalStoreContext context = new NaturalStoreContext(DB_USER_ID, APP_ID, DATABASE_NAME); //打开一个Cloud DB数据库(一个NaturalStore可以理解为一个数据库) database = naturalBase.openNaturalStore(context, true); //创建数据对象(可理解为创建表,如果表已存在,此处将返回true) int isStudentSuccess = database.createObjectType(Student.class, versionCode); int isPaperSuccess = database.createObjectType(ExamPaper.class, versionCode); int isAnswerSuccess = database.createObjectType(ExamAnswer.class, versionCode); int isAnswerResultSuccess = database.createObjectType(ExamAnswerResult.class, versionCode); int isScoreBoardSuccess = database.createObjectType(ScoreBoard.class, versionCode); if (isStudentSuccess == 0 && isPaperSuccess == 0 && isAnswerSuccess == 0 && isAnswerResultSuccess == 0 && isScoreBoardSuccess == 0) { isDBCreated.postValue(true); return true; } } return false; } catch (NaturalBaseException exception) { Log.d(TAG, exception.toString()); return false; } }

查询试卷信息

试卷列表界面会调用com.huawei.naturalbasedemo.DataRepositorygetAllPapers()方法从Cloud DB中查询试卷信息,请在getAllPapers()添加如下代码实现数据查询。

public List<ExamPaper> getAllPapers() { if (database == null) { return null; } try { //构造查询条件对象 NaturalStoreQuery query = NaturalStoreQuery.where(ExamPaper.class); //查询Cloud DB中的试卷数据 List<NaturalStoreObject> list = database.executeQuery(query); return list.stream().map((naturalStoreObject -> { return (ExamPaper) naturalStoreObject; })).collect(Collectors.toList()); } catch (NaturalBaseException exception) { Log.d(TAG, exception.toString()); return null; } }

现在,【考试】页面就能够展示从Cloud DB中查询到的试卷信息了。

答题中途退出时,答题应用将会把已经解答的题目答案保存到Cloud DB中,从而避免下次继续答题时需要重复答题。以下内容将指导您如何通过SDK将答案信息保存到Cloud DB中。

在数据库中添加/更新记录

请在com.huawei.naturalbasedemo.DataRepositoryinsert()方法和update()方法添加如下代码实现在Cloud DB中添加和更新记录。

public <T extends NaturalStoreObject> boolean insert(T data) { Log.d(TAG, "insert:" + data); if (database == null) { return false; } try { //将记录添加到Cloud DB中 int isSuccess = database.executeInsert(data); return isSuccess == 0; } catch (NaturalBaseException exception) { Log.d(TAG, exception.toString()); return false; } } public <T extends NaturalStoreObject> boolean update(T data) { Log.d(TAG, "update:" + data); if (database == null) { return false; } try { //更新Cloud DB中的记录 int isSuccess = database.executeUpdate(data); return isSuccess == 0; } catch (NaturalBaseException exception) { Log.d(TAG, exception.toString()); return false; } }

保存答案信息

请将如下代码添加到com.huawei.naturalbasedemo.viewmodel.QuestionViewModelsavePaper()方法,该方法将调用com.huawei.naturalbasedemo.DataRepositoryinsert()/update()方法将答案信息保存到Cloud DB中。

public void savePaper() { boolean isInsert = answeredPaper.getAnswer() == null; ExamAnswer answer = new ExamAnswer(); answer.setStudentID(DataRepository.getInstance().getCurrentStudentId()); answer.setPaperID(answeredPaper.getPaper().getId()); answer.setTime(dealLineTime); answer.setCurrentNum(currentIndex); answeredPaper.setAnswer(answer); answeredPaper.setSelectedOptions(selectedOptions); if (isInsert) { //将记录添加到Cloud DB中 DataRepository.getInstance().insert(answeredPaper.getAnswer()); } else { //更新Cloud DB中的记录 DataRepository.getInstance().update(answeredPaper.getAnswer()); } }

当答题完毕交卷时,答题应用将会计算出答题得分,将得分信息保存到Cloud DB中,并在界面展示结果。以下内容将指导您如何将答题结果保存到Cloud DB中。

保存答题结果信息

请将如下代码添加到com.huawei.naturalbasedemo.viewmodel.QuestionViewModelcommitPaper()方法中,从而实现将答题结果保存到Cloud DB中的目的。

public void commitPaper() { //将答案保存到Cloud DB中 savePaper(); //计算得分 int score = Function.calculatePaperScore(answeredPaper); ExamAnswerResult result = new ExamAnswerResult(); result.setStudentID(DataRepository.getInstance().getCurrentStudentId()); result.setPaperID(answeredPaper.getPaper().getId()); result.setScore(score); result.setTime(dealLineTime); answeredPaper.setResult(result); //将答题结果保存到Cloud DB中 DataRepository.getInstance().insert(result); }

答题应用会根据每次答题的耗时以及得分计算出排行积分,同时将排行积分保存到Cloud DB中,然后通过答题应用的【排行榜】界面展示当前的排行情况。以下内容将指导您如何借助Cloud Functions开发云函数计算排行积分。

实现计算排行积分云函数

您可以订阅Cloud DB表的数据变更(增删改)事件,并开发一个云函数处理这些事件,在云函数中您可以通过上下文对象获取到变更的数据库记录,同时您可以使用SDK在云函数中访问Cloud DB。
在答题应用中,我们订阅了ExamAnswerResult表的新增记录事件,交卷后答题结果记录被插入到Cloud DB中时,将会执行下面的云函数,云函数将根据答题结果记录中的耗时和得分计算出排行积分,最后将积分保存到Cloud DB中。
请将如下代码添加到源码目录下的FaaS/exam.js中。

//引用Cloud DB SDK var naturalBaseAPI = require("./NaturalBaseApi"); var exam = function (event, context) { //数据库名称 var DATABASE_NAME = "demodatabase"; //数据库的APPID var APP_ID = "agcnaturalbasedemo"; //使用的数据库版本 var SCHEMA_VERSION = "1"; //数据库的用户ID var DB_USER_ID = "public"; //排行榜表的名字 var SCOREBOARD_TABLE_NAME = "scoreboard"; //排行榜表的学生ID字段 var SCOREBOARD_STUDENT_ID = "studentID"; //排行榜表的积分字段 var SCOREBOARD_SCORE = "score"; var scoreBoardObjectType = new naturalBaseAPI.NaturalStoreObjectType( SCOREBOARD_TABLE_NAME, SCHEMA_VERSION ); scoreBoardObjectType.addField( SCOREBOARD_STUDENT_ID, naturalBaseAPI.FieldType.STRING, true ); scoreBoardObjectType.addField( SCOREBOARD_SCORE, naturalBaseAPI.FieldType.INT, false ); var naturalStoreObjectTypeList = []; naturalStoreObjectTypeList[0] = scoreBoardObjectType; var log = context.logger; var myNaturalBase = new naturalBaseAPI.NaturalBase(APP_ID, SCHEMA_VERSION, DB_USER_ID); //初始化Cloud DB的NaturalBase对象 myNaturalBase.initialize(); var myNaturalStore; var init = function () { return new Promise(function (resolve, reject) { myNaturalStore = myNaturalBase.openNaturalStore(DATABASE_NAME, naturalBaseAPI.AccessProperty.PUBLIC, openNaturalStoreCallBack); //打开Cloud DB数据库(可理解为打开一个数据库) function openNaturalStoreCallBack(result, data) { if (result == true) { resolve(); } else { reject("openNaturalStoreCallBack failed"); } } }); } var err = function (msg) { log.error(msg) } init().then(() => loadObjectTypes(), msg => err(msg)).then(() => query(), msg => err(msg)); var loadObjectTypes = function () { return new Promise(function (resolve, reject) { log.debug("loadObjectTypes"); //加载数据对象的元数据(一个数据对象类型可以理解为一张数据库表) myNaturalStore.loadObjectType(naturalStoreObjectTypeList, loadObjectTypesCallback); function loadObjectTypesCallback(result, data) { if (result == true) { resolve(); } else { reject("loadObjectTypesCallback failed"); } } }); } var query = function () { return new Promise(function (resolve, reject) { var resultList = event.records; for (var i = 0; i < resultList.length; i++) { var record = resultList[i]; if (record.operation_type == "INSERT_DATA") { log.debug(record); var score = count(record.score, record.time); handleRecord(record.studentID, score); } } }); }; var count = function (score, time) { var v = 10 if (time < 300) { v = 20 } return score * v / 10; }; var handleRecord = function (sid, val) { var naturalStoreQuery = new naturalBaseAPI.NaturalStoreQuery(); naturalStoreQuery.equalTo(SCOREBOARD_STUDENT_ID, sid); var queryConditions = naturalStoreQuery.getQueryCondtions(); //查询Cloud DB中的积分记录 myNaturalStore.executeQuery(SCOREBOARD_TABLE_NAME, queryConditions, function (success, data) { if (success == true) { log.debug("query score success"); if (data.length == 0) { //当数据库中不存在该学生的排行积分时,添加排行积分 insertScore(sid, val); } else { //当数据库中已存在该学生的排行积分时,更新排行积分 for (var i = 0; i < data.length; i++) { log.debug(data[i]); var student = data[i]; var newScore = student.score + val; updateScore(sid, newScore); } } } else { log.debug("query score failed"); } }); } var updateScore = function (sid, val) { console.log("updateScore: sid= " + sid + ", val=" + val); var scores = [ { studentID: sid, score: val } ]; //更新Cloud DB中的排行积分 myNaturalStore.executeUpdate(SCOREBOARD_TABLE_NAME, scores, function (status) { console.log("executeUpdate callback" + status); }); }; var insertScore = function (sid, val) { log.debug("insert score: sid= " + sid + ", val=" + val); var scores = [ { studentID: sid, score: val } ]; //在Cloud DB中添加排行积分 myNaturalStore.executeInsert(SCOREBOARD_TABLE_NAME, scores, function (status) { log.debug("executeInsert callback" + status); }); }; } module.exports.myHandler = exam;

部署和配置云函数

云函数开发完后,您需要通过开发者联盟的控制台将函数部署到云上,并配置云函数的触发执行条件。
以下内容将指导您完成云函数的部署和配置操作。

  1. 登录华为开发者联盟
  2. 单击我的应用

  1. 单击HDCServerlessDemo

  1. 依次单击开发 > Serverless > 云函数

  1. 单击创建函数

  1. 填写函数基本信息(只需填写如下必填项,非必填项保持缺省值即可)并上传函数源码压缩包后单击保存

  1. 单击添加触发器

  1. 填写触发器的基本信息,单击添加,再单击保存

现在只要在答题应用中执行交卷动作,计算排行积分的云函数就会被触发执行了。

查询排行榜信息

请将如下代码添加到com.huawei.naturalbasedemo.DataRepositorygetScoreBoardList(int count)方法中,答题APP界面将调用此方法查询Cloud DB中的排行记录并展示。

public List<ScoreBoard> getScoreBoardList(int count) { if (database == null) { return null; } try { //构造查询条件对象 NaturalStoreQuery query = NaturalStoreQuery.where(ScoreBoard.class) .orderByDesc(SCORE_FIELD) .limit(count); //查询Cloud DB中的排行数据 List<NaturalStoreObject> list = database.executeQuery(query); return list.stream().map((naturalStoreObject -> { return (ScoreBoard) naturalStoreObject; })).collect(Collectors.toList()); } catch (NaturalBaseException exception) { Log.d(TAG, exception.toString()); return null; } }

到此您已经完成答题应用的所有编码,可以查看您的开发成果,以下内容将指导您完成答题应用的编译以及在手机上的运行。

编译运行

  1. 在Android Studio工具栏中选择app并单击运行按钮:

  1. 在设备列表中,选择实际运行程序的手机;
  2. 在手机上单击【趣答题】,运行应用;

  1. 用华为账号登录后开始体验;

干得好,您已经成功完成了本codelab并学到了:

Class NaturalBase

NaturalBase 类是Cloud DB(端云数据协同管理平台)的入口类,采用单实例模式,即每个进程都有且仅有一个NaturalBase实例。通过NaturalBase实例,可实现新建、打开、关闭或者删除NaturalStore的功能。

initialize

接口定义:

public static NaturalBase initialize(String userId, String appId);

功能描述

NaturalBase的静态实例初始化方法,采用单实例模式。

参数说明

userId:字符串,用户ID,华为账户或者本地用户。

appId:字符串,应用ID,一个具体的进程或者进程里面的一个Service。

返回值

一个NaturalBase实例。

异常说明

注意事项

loadObjectType

接口定义:

public int loadObjectType(long appVersion, List clazzes) throws NaturalBaseException;

功能描述

将开发人员定义的所有实体类(即数据库表)加载到NaturalStore中。

参数说明

appVersion:APP的版本。

clazzes:Class的一个集合,包含开发人员定义的所有实体类。

返回值

int类型。如果成功,则返回OPERATION_SUCCESS;操作失败抛出异常。

异常说明

NaturalBaseException:NaturalBase异常基类,当创建或者打开失败时会抛出异常,用户需要捕捉该异常,并做相应的处理。

注意事项

该接口需要在调用initialize接口之后,调用openNaturalStore接口之前,进行调用。

openNaturalStore

接口定义:

public NaturalStore openNaturalStore(NaturalStoreContext context, boolean allowCreate) throws NaturalBaseException;

功能描述

打开一个NaturalStore对象,一个NaturalStore对象对应一个数据库。在Android系统上,数据库文件默认存放在APP数据目录下的databases子目录下面。

参数说明

context:NaturalStoreContext 对象,表示NaturalStore的上下文环境,用于创建时初始化NaturalStore环境,或者打开指定的NaturalStore。

allowCreate:布尔值,true、false。

返回值

一个NaturalStore实例,用户可通过该实例实现数据的增、删、改、查和注册数据订阅功能。

异常说明

NaturalBaseException:NaturalBase异常基类,当创建或者打开失败时会抛出异常,用户需要捕捉该异常,并做相应的处理。

注意事项

closeNaturalStore

接口定义:

public void closeNaturalStore(NaturalStore nStore) throws NaturalBaseException;

功能描述

关闭已打开的NaturalStore对象,并释放相关的资源。

参数说明

nStore:NaturalStore 对象,表示要关闭的NaturalStore对象。

返回值

无;

异常说明

NaturalBaseException:NaturalBase异常基类,当关闭失败时会抛出异常,用户需要捕捉该异常,并做相应的处理。

Class NaturalStoreContext

NaturalStoreContext用于构造NaturalStore对象。

构造方法

接口定义:

public NaturalStoreContext(String userId, String appId, String naturalStoreName);

功能描述

NaturalStoreContext的构造方法。

参数说明

userId:字符串,用户ID。当用户输入参数为"PUBLIC"时,使用该NaturalStoreContext对象创建的NaturalStore是public的,否则创建的NaturalStore均为private的。

appId:字符串,应用ID,可表示一个具体的进程或者进程里面的一个Service。

naturalStoreName:字符串,用户指定的数据库名称。

NaturalStore使用userId + appId + naturalStoreName作为标识。 同一个终端设备上,会有多个App用到端云协同数据库,其中NaturalBase是单实例,在每个App下只会初始化一个NaturalBase。在一个NaturalBase下可以有多个用户,每个用户可以创建多个NaturalStore,云侧保存所有App创建的NaturalStore,因此NaturalStore需通过指定AppID+UserID+ naturalStoreName来标识唯一性。

返回值

一个NaturalStoreContext对象

异常说明

注意事项

AppID、UserID、naturalStoreName长度不能超过20个字符,且可用字符集限制为[0-9A-Za-z],否则new NaturalStoreContext 对象时会抛异常。

getUserId()

接口定义:

String getUserId();

功能描述

获取 NaturalStoreContext 中 userId 的值。

参数说明

返回值

userId 值,字符串类型。

异常说明

注意事项

getAppId()

接口定义:

String getAppId();

功能描述

获取 NaturalStoreContext 中 appId 的值。

参数说明

返回值

appId 值,字符串类型。

异常说明

注意事项

getNaturalStoreName

接口定义:

publicString getNaturalStoreName()

功能描述

获取 NaturalStoreContext 中 naturalStoreName的值。

参数说明

返回值

naturalStoreName的值,字符串类型。

异常说明

注意事项

Class NaturalStore

createObjectType

接口定义:

public int createObjectType(Class clazz, long appVersion) throws NaturalBaseException;

功能描述

用于创建NaturalStore中存储特定NaturalStoreObject对象的容器(可理解为数据库表)。

参数说明

clazz:Class类型,用户定义的实体类,该实体类需要继承NaturalStoreObject,类中定义了数据成员变量,每一个成员变量都有set/get方法。NaturalStoreObject介绍详见"Class NaturalStoreObject"章节。

appVersion:long型,App的当前版本。

返回值

int类型。如果成功,则返回OPERATION_SUCCESS;操作失败抛出异常。

异常说明

NaturalBaseException:NaturalBase异常基类,当创建对象失败时会抛出异常,用户需要捕捉该异常,并做相应的处理;操作失败返回异常。

注意事项

executeInsert

接口定义:

public int executeInsert(NaturalStoreObject naturalStoreObject) throws NaturalBaseException;

功能描述

将单个NaturalStoreObject对象插入到NaturalStore中,NaturalStoreObject介绍详见"Class NaturalStoreObject"章节。

参数说明

naturalStoreObject: NaturalStoreObject对象。

返回值

int类型。如果成功,则返回OPERATION_SUCCESS;如果传入的对象为null,则返回1;操作失败抛出异常。

异常说明

NaturalBaseException:NaturalBase异常基类,当插入对象失败时会抛出异常,用户需要捕捉该异常,并做相应的处理。

注意事项

executeInsert

接口定义:

public int executeInsert(List naturalStoreObjectList) throws NaturalBaseException;

功能描述

将List中NaturalStoreObject对象插入到NaturalStore对应的容器中,这些对象会在一个事务中插入到容器中,要么全部插入成功,要么全部都未插入成功,不存在部分插入成功的情况。

参数说明

naturalStoreObjectList:List<NaturalStoreObject>;

返回值

int类型。如果成功,则返回OPERATION_SUCCESS;如果集合为空,则返回1;操作失败返回异常。

异常说明

NaturalBaseException:NaturalBase异常基类,当插入对象失败时会抛出异常,用户需要捕捉该异常,并做相应的处理。

注意事项

executeUpdate

接口定义:

public int executeUpdate (NaturalStoreObject naturalStoreObject) throws NaturalBaseException;

功能描述

将单个NaturalStoreObject对象更新到NaturalStore对应的容器中。

参数说明

naturalStoreObject: NaturalStoreObject对象。

返回值

int类型。如果成功,则返回OPERATION_SUCCESS;如果传入的对象为null,则返回1;操作失败返回异常。

异常说明

NaturalBaseException:NaturalBase异常基类,当更新对象失败时会抛出异常,用户需要捕捉该异常,并做相应的处理。

注意事项

executeUpdate

接口定义:

public int executeUpdate(List naturalStoreObjectList) throws NaturalBaseException;

功能描述

将List中的NaturalStoreObject对象更新到NaturalStore对应的容器中,这些对象会在一个事务中更新到容器中,要么全部更新成功,要么全部都未更新成功,不存在部分更新成功的情况。

参数说明

naturalStoreObjectList:List<NaturalStoreObject>;

返回值

int类型。如果成功,OPERATION_SUCCESS;如果集合为空,则返回1。操作失败返回异常。

异常说明

NaturalBaseException:NaturalBase异常基类,当更新对象失败时会抛出异常,用户需要捕捉该异常,并做相应的处理。

注意事项

executeDelete

接口定义:

public int executeDelete(List naturalStoreObjectList) throws NaturalBaseException;

功能描述

将List中的NaturalStoreObject对象从NaturalStore中删除,这些对象在一个事务中从容器中删除,要么全部删除成功,要么全部都未删除成功,不存在部分删除成功的情况。

参数说明

naturalStoreObjectList:List<NaturalStoreObject>;

返回值

int类型。如果成功,则返回OPERATION_SUCCESS,如果集合为空,则返回1。操作失败抛出异常。

异常说明

NaturalBaseException:NaturalBase异常基类,当删除对象失败时会抛出异常,用户需要捕捉该异常,并做相应的处理。

注意事项

executeDeleteAll

接口定义:

public int executeDeleteAll(Class clazz) throws NaturalBaseException;

功能描述

将clazz在NaturalStore对应NaturalStoreObject容器中的全部记录删除。

参数说明

clazz:用户定义的某个实体类。

返回值

int类型。如果成功,则返回OPERATION_SUCCESS;操作失败返回异常。

异常说明

NaturalBaseException:NaturalBase异常基类,当删除对象失败时会抛出异常,用户需要捕捉该异常,并做相应的处理。

注意事项

executeQuery

接口定义:

public List executeQuery(NaturalStoreQuery naturalStoreQuery) throws NaturalBaseException;

功能描述

根据用户指定的NaturalStoreQuery,从NaturalStore中查询得到一个NaturalStoreObject集合。NaturalStoreQuery介绍详见"Class NaturalStoreQuery"章节。

参数说明

naturalStoreQuery:用于查询的对象,该对象中将会指定查询所需的要素,包含表名、查询字段、过滤条件、排序规则、限定查询个数等。

返回值

List<NaturalStoreObject>。如果成功,则返回NaturalStoreObject对象集合;操作失败抛出异常。

异常说明

NaturalBaseException:NaturalBase异常基类,当查询对象失败时会抛出异常,用户需要捕捉该异常,并做相应的处理。

注意事项

registerChangeCallBack

接口定义:

public void registerChangeCallBack (InterestedStatus interestedStatus, string objectTypeName, OnChangeCallBack callback) throws NaturalBaseException;

功能描述

注册感兴趣的数据,并订阅到该NaturalStore对象。当NaturalStore中数据发生变化时,NaturalBase会自动调用该接口,并作为参数传入callback对象中的onStatusChange方法。

参数说明

interestedStatus:枚举类型,表示所关注的回调状态类型,通过NaturalStore的静态常量控制,目前有如下几个常量:

这两种状态可支持通过"|"进行连接,表示同时关心这两种状态变化。

objectTypeName:String类型,注册回调时所关注的数据变化的对象类型名称。

callback:OnChangeCallBack对象,待注册的回调对象,底层可通过该对象来通知用户数据发生了哪些变化。

返回值

无。操作失败抛出异常。

异常说明

NaturalBaseException:NaturalBase异常基类,当注册回调失败时会抛出异常,用户需要捕捉该异常,并做相应的处理。

注意事项

registerChangeCallBack与unRegisterChangeCallBack是搭配使用的,同一个Callback在一个objectTypeName上面只能registerChangeCallBack注册一次,要关注其他的回调状态类型,需要调用unRegisterChangeCallBack将上一次注册的回调进行注销,注销注册时的三个参数与registerChangeCallBack时保持一致。

unRegisterChangeCallBack

接口定义:

public void unRegisterChangeCallBack(InterestedStatus interestedStatus, string objectTypeName, OnChangeCallBack callback) throws NaturalBaseException;

功能描述

注销注册数据订阅回调,不再关注底层特定类型数据的变化。

参数说明

interestedStatus:所关注的回调状态类型。

objectTypeName:String类型,注销注册回调时所关注的数据变化的对象类型名称。

callback:OnChangeCallBack对象,要注销注册的回调对象。

返回值

无。操作失败抛出异常。

异常说明

NaturalBaseException:NaturalBase异常基类,当注销注册回调失败时会抛出异常,用户需要捕捉该异常,并做相应的处理;

注意事项

在所有已注册的回调中,三个参数均需匹配才能注销注册成功。

Class OnChangeCallBack

接口定义:

public interface OnChangeCallBack { void onStatusChange(List<NaturalStoreObject> added, List<NaturalStoreObject> modified, List<NaturalStoreObject> deleted); };

功能描述

接口类,用户需要继承该接口,并重载onStatusChange方法。

参数说明

added:NaturalStoreObject对象集合,用于存放在NaturalStore新增的对象。

modified:NaturalStoreObject对象集合,用于存放在NaturalStore修改之后的对象。

deleted:NaturalStoreObject对象集合,用于存放在NaturalStore删除的对象。

返回值

异常说明

注意事项

Class NaturalBaseException

异常类,继承Exception类,当前无特殊方法。

Class NaturalStoreObject

该类是一个抽象类,用户定义的所有实体类都必须继承该类。

getObjectTypeName

接口定义:

publicString getObjectTypeName()

功能描述:

获取具体的实体类的类名,作为NaturalStore中存放该类对象的容器名。每一个继承NaturalStoreObject抽象类的实体类对象可以直接调用父类的该方法,获取该实体类类名。示例如下:

public class Student extends NaturalStoreObject { private Integer id; private String name; private String gender; private String stringType; private Integer integerType; private Short shortType; private Long longType; private Float floatType; private Double doubleType; private Boolean booleanType; private Byte byteType; private Date dateType; private byte[] byteArray; public Student(int id) { super(); id = id; } public Student(int id, String name, String gender) { this.id = id; this.name = name; this.gender = gender; } public int getId() { return id; } public String getName() { return name; } public String getGender() { return gender; } public void setId(int id) { this.id = id; } public void setName(String name) { this.name = name; } public void setGender(String gender) { this.gender = gender; } ........ }

注意事项

getPackageName

接口定义:

publicString getPackageName();

功能描述

获取该类的全路径类名。

参数说明

返回值

字符串类型,类的全路径,例如com.huawei.naturalbase.api.object.Student。

异常说明

注意事项

Class NaturalStoreQuery

该类在用户需要做查询操作时使用,用户通过调用该类中的一系列接口,将查询所需的要素封装在对象中,作为executeQuery接口的入参。

where

public static NaturalStoreQuery where(Class <T> entityClass) throws NullNaturalStoreObjectException

功能描述

该接口是一个静态方法,用户指定查询的实体类(包含对应的表名,以及所有字段名),并且返回一个NaturalStoreQuery对象,用于添加其他的查询条件。

参数说明

entityClass:用户定义的某个实体类。

返回值

NaturalStoreQuery,如果成功,则返回NaturalStoreQuery对象;操作失败抛出异常。

异常说明

NullNaturalStoreObjectException:当用户指定入参为空时会抛出异常,用户需要捕捉该异常,并做相应的处理。

注意事项

equalTo

接口定义:

public NaturalStoreQuery equalTo(String field, Byte value) public NaturalStoreQuery equalTo(String field, Short value) public NaturalStoreQuery equalTo(String field, Integer value) public NaturalStoreQuery equalTo(String field, Long value) public NaturalStoreQuery equalTo(String field, Double value) public NaturalStoreQuery equalTo(String field, Float value) public NaturalStoreQuery equalTo(String field, String value)

功能描述

用于添加过滤条件,即表中的某个字段等于某个值。

参数说明

field:实体类中的某个字段名。

value:某个特定的值,当前支持的数据类型包含Byte、Short、Integer、Long、Double、Float、String。

返回值

NaturalStoreQuery,如果成功,则返回NaturalStoreQuery对象,用于添加其他的查询条件。

异常说明

注意事项

notEqualTo

接口定义:

public NaturalStoreQuery notEqualTo(String field, Byte value) public NaturalStoreQuery notEqualTo (String field, Short value) public NaturalStoreQuery notEqualTo (String field, Integer value) public NaturalStoreQuery notEqualTo (String field, Long value) public NaturalStoreQuery notEqualTo (String field, Double value) public NaturalStoreQuery notEqualTo (String field, Float value) public NaturalStoreQuery notEqualTo (String field, String value)

功能描述

用于添加过滤条件,即表中的某个字段不等于某个值。

参数说明

field:实体类中的某个字段名。

value:某个特定的值,当前支持的数据类型包含Byte、Short、Integer、Long、Double、Float、String。

返回值

NaturalStoreQuery,如果成功,则返回NaturalStoreQuery对象,用于添加其他的查询条件。

异常说明

注意事项

greaterThan

接口定义:

public NaturalStoreQuery greaterThan(String field, Byte value) public NaturalStoreQuery greaterThan (String field, Short value) public NaturalStoreQuery greaterThan (String field, Integer value) public NaturalStoreQuery greaterThan (String field, Long value) public NaturalStoreQuery greaterThan (String field, Double value) public NaturalStoreQuery greaterThan (String field, Float value) public NaturalStoreQuery greaterThan (String field, String value)

功能描述

用于添加过滤条件,即表中的某个字段大于某个值。

参数说明

field:实体类中的某个字段名。

value:某个特定的值,当前支持的数据类型包含Byte、Short、Integer、Long、Double、Float、String。

返回值

NaturalStoreQuery,如果成功,则返回NaturalStoreQuery对象,用于添加其他的查询条件。

异常说明

注意事项

greaterThanOrEqualTo

接口定义:

public NaturalStoreQuery greaterThanOrEqualTo(String field, Byte value) public NaturalStoreQuery greaterThanOrEqualTo (String field, Short value) public NaturalStoreQuery greaterThanOrEqualTo (String field, Integer value) public NaturalStoreQuery greaterThanOrEqualTo (String field, Long value) public NaturalStoreQuery greaterThanOrEqualTo (String field, Double value) public NaturalStoreQuery greaterThanOrEqualTo (String field, Float value) public NaturalStoreQuery greaterThanOrEqualTo (String field, String value)

功能描述

用于添加过滤条件,即表中的某个字段大于等于某个值。

参数说明

field:实体类中的某个字段名。

value:某个特定的值,当前支持的数据类型包含Byte、Short、Integer、Long、Double、Float、String。

返回值

NaturalStoreQuery,如果成功,则返回NaturalStoreQuery对象,用于添加其他的查询条件。

异常说明

注意事项

lessThan

接口定义:

public NaturalStoreQuery lessThan(String field, Byte value) public NaturalStoreQuery lessThan (String field, Short value) public NaturalStoreQuery lessThan (String field, Integer value) public NaturalStoreQuery lessThan (String field, Long value) public NaturalStoreQuery lessThan (String field, Double value) public NaturalStoreQuery lessThan (String field, Float value) public NaturalStoreQuery lessThan (String field, String value)

功能描述

用于添加过滤条件,即表中的某个字段小于某个值。

参数说明

field:实体类中的某个字段名。

value:某个特定的值,当前支持的数据类型包含Byte、Short、Integer、Long、Double、Float、String。

返回值

NaturalStoreQuery,如果成功,则返回NaturalStoreQuery对象,用于添加其他的查询条件。

异常说明

注意事项

lessThanOrEqualTo

接口定义:

public NaturalStoreQuery lessThanOrEqualTo(String field, Byte value) public NaturalStoreQuery lessThanOrEqualTo (String field, Short value) public NaturalStoreQuery lessThanOrEqualTo (String field, Integer value) public NaturalStoreQuery lessThanOrEqualTo (String field, Long value) public NaturalStoreQuery lessThanOrEqualTo (String field, Double value) public NaturalStoreQuery lessThanOrEqualTo (String field, Float value) public NaturalStoreQuery lessThanOrEqualTo (String field, String value)

功能描述

用于添加过滤条件,即表中的某个字段小于等于某个值。

参数说明

field:实体类中的某个字段名。

value:某个特定的值,当前支持的数据类型Byte、Short、Integer、Long、Double、Float、String。

返回值

NaturalStoreQuery,如果成功,则返回NaturalStoreQuery对象,用于添加其他的查询条件。

异常说明

注意事项

in

接口定义:

public NaturalStoreQuery in(String field, Byte[] value) public NaturalStoreQuery in (String field, Short[] value) public NaturalStoreQuery in (String field, Integer[] value) public NaturalStoreQuery in (String field, Long[] value) public NaturalStoreQuery in (String field, Double[] value) public NaturalStoreQuery in (String field, Float[] value)

功能描述

用于添加过滤条件,即表中的某个字段在某一个值之中。

参数说明

field:实体类中的某个字段名。

value:某个特定的值,当前支持的数据类型Byte、Short、Integer、Long、Double、Float、String。

返回值

NaturalStoreQuery,如果成功,则返回NaturalStoreQuery对象,用于添加其他的查询条件。

异常说明

注意事项

beginsWith

接口定义:

publicNaturalStoreQuery beginsWith(String fieldName, String value)

功能描述

用于添加过滤条件,即某个string类型的字段以特定的字符串开始。

参数说明

field:实体类中的某个字段名。

value:string类型,一个特定的字符串。

返回值

NaturalStoreQuery,如果成功,则返回NaturalStoreQuery对象,用于添加其他的查询条件。

异常说明

注意事项

endsWith

接口定义:

publicNaturalStoreQuery endsWith(String fieldName, String value)

功能描述

用于添加过滤条件,即某个string类型的字段以特定的字符串结束。

参数说明

field:实体类中的某个字段名。

value:String类型,一个特定的字符串。

返回值

NaturalStoreQuery,如果成功,则返回NaturalStoreQuery对象,用于添加其他的查询条件。

异常说明

注意事项

contains

接口定义:

publicNaturalStoreQuery contains(String fieldName, String value)

功能描述

用于添加过滤条件,即某个string类型的字段包含特定的字符串。

参数说明

field:实体类中的某个字段名。

value:String类型,一个特定的字符串。

返回值

NaturalStoreQuery,如果成功,则返回NaturalStoreQuery对象,用于添加其他的查询条件。

异常说明

注意事项

orderByAsc

接口定义:

publicNaturalStoreQuery orderByAsc(String field)

功能描述

用于添加查询条件,即按照表中的某个字段升序排序。

参数说明

field:实体类中的某个字段名。

返回值

NaturalStoreQuery。如果成功,则返回NaturalStoreQuery对象,用于添加其他的查询条件。

异常说明

注意事项

该查询接口应该放在查询接口limit之前,其他接口之后。

orderByDesc

接口定义:

publicNaturalStoreQuery orderByDesc(String field)

功能描述

用于添加查询条件,即按照表中的某个字段降序排序。

参数说明

field:实体类中的某个字段名。

返回值

NaturalStoreQuery,如果成功,则返回NaturalStoreQuery对象,用于添加其他的查询条件。

异常说明

注意事项

该查询接口应该放在查询接口limit之前,其他接口之后。

limit

接口定义:

publicNaturalStoreQuery limit(int count)

功能描述

用于添加过滤条件,即查询count条数;

参数说明

count:指定查询count条记录。

返回值

NaturalStoreQuery,如果成功,则返回NaturalStoreQuery对象,用于添加其他的查询条件。

异常说明

注意事项

该查询接口应该放在所有查询接口的最后。

average

接口定义:

publicNaturalStoreQuery average(String fieldName)

功能描述

用于添加过滤条件,即查询某个数值类型字段的平均值。

参数说明

field:实体类中的某个字段名。

返回值

NaturalStoreQuery,如果成功,则返回NaturalStoreQuery对象,用于添加其他的查询条件。

异常说明

注意事项

该查询接口通常只与"where"一起使用,使用该接口之后返回的NaturalStoreQuery只能在

executeAverageQuery接口中作为参数使用。

Annotations

给用户提供的注解,用于用户的实体类中的字段注解,指定一些建表时所需的schema信息,包含PrimaryKey、DefaultValue、NotNull、IsIndex,示例如下:

public class Student extends NaturalStoreObject { @PrimaryKey @DefaultValue(intValue = 0) private int id; @NotNull @DefaultValue(stringValue = "huawei") @IsIndex private String name; @NotNull private String gender; public Student(int id) { super(); id = id; } public Student(int id, String name, String gender) { this.id = id; this.name = name; this.gender = gender; } @Override public String getEntityName() { return super.getEntityName(); } }

PrimaryKey

按照常规注解使用在实体类某个字段上即可,代表该字段为主键,如下:

@PrimaryKey

由于主键的唯一性,所以当只有一个字段上有@PrimaryKey注解时,表示这是一个单字段主键,当有多个字段上有@PrimaryKey注解时,表示这是一个复合主键。

DefaultValue

按照常规注解使用在实体类某个字段上,为该字段指定默认值,根据字段类型设置不同类型的值,如下:

byte型:@DefaultValue(byteValue = 0)

short型:@DefaultValue(shortValue = 0)

int型:@DefaultValue(intValue = 0)

long型:@DefaultValue(longValue = 0L)

double型:@DefaultValue(doubleValue = 0D)

float型:@DefaultValue(floatValue = 0.0F)

String型:@DefaultValue(stringValue = "")

boolean型:@DefaultValue(booleanValue = true)

NotNull

按照常规注解使用在实体类某个字段上即可,代表该字段为非空字段,如下:

@NotNull

IsIndex

按照常规注解使用在实体类某个字段上,然后加上方法indexName用于指定索引名,代表该字段为索引,如下:

@IsIndex(indexName = "index1")

需要强调的是:索引名长度不能超过 64个字符,并且要以字母开头,只能包含字母、数字以及下划线。

该注解不仅支持单字段索引,而且支持复合索引,当多个字段的indexName一样时,表示这几个字段组成一个复合索引,例如:

@PrimaryKey private Integer id; @IsIndex(indexName = "index0") private String name; @IsIndex(indexName = "index1") private String gender; @IsIndex(indexName = "index1") private String stringType; @IsIndex(indexName = "index1") private Integer integerType; @IsIndex(indexName = "index2") private Short shortType; @IsIndex(indexName = "index2") private Long longType;

它表示index0建在name字段,index1建在(gender,integerTyp, stringType)这3个字段,index2建在 (longType,shortType)这两个字段。

已复制代码