LeanCloud Java SDK(兼容 Android)
LeanCloud Unified SDK 包含 LeanCloud 平台全部功能的客户端接口,适用于 Java 和 Android 两个平台。
SDK 中所有存储 API 接口与 LeanCloud 云端交互严格遵循 LeanCloud REST API 规范,并且全部采用了 Reactive 函数式编程风格来设计(同时也兼容老的 Callback 方式)。
要想了解更多使用信息,请查看 Wiki.
注意:此 SDK 当前还在开发中,我们会逐步提供全平台的功能。最新进度如下:
从 8.x 版本开始,我们把公开类名字前缀由 AV
改为了 LC
,同时也删除了一些长期处于 deprecated
状态的接口。开发者升级到 8.x 版本,要做的主要改动包括:
AV
改为了 LC
,例如:AVDate
-> LCDate
,AVClassName
-> LCClassName
,AVGeoPoint
-> LCGeoPoint
AVObject
-> LCObject
,AVUser
-> LCUser
,AVFile
-> LCFile
AVQuery
-> LCQuery
,AVCloud
-> LCCloud
,AVException
-> LCException
AVOSCloud
-> LeanCloud
AVIMClient
-> LCIMClient
, AVIMMessage
-> LCIMMessage
AVIMMessage#AVIMMessageIOType
to LCIMMessage#MessageIOType
, and redefined values:TypeIn
(formal AVIMMessageIOTypeIn
)TypeOut
(formal AVIMMessageIOTypeOut
)AVIMMessage#AVIMMessageStatus
to LCIMMessage#MessageStatus
, and redefined values:StatusNone
(formal AVIMMessageStatusNone
)StatusSending
(formal AVIMMessageStatusSending
)StatusSent
(formal AVIMMessageStatusSent
)StatusReceipt
(formal AVIMMessageStatusReceipt
)StatusFailed
(formal AVIMMessageStatusFailed
)StatusRecalled
(formal AVIMMessageStatusRecalled
)AVIMMessageQueryDirection
to LCIMMessageQueryDirection
and redefined values:DirectionUnknown
(formal AVIMMessageQueryDirectionUnknown
),DirectionFromNewToOld
(formal AVIMMessageQueryDirectionFromNewToOld
),DirectionFromOldToNew
(formal AVIMMessageQueryDirectionFromOldToNew
);change inner class AVIMMessageInterval#AVIMMessageIntervalBound
to LCIMMessageInterval#MessageIntervalBound
.
如果开发者通过 SDK 提供的辅助类 ObserverBuilder
将 FindCallback 实例转为了订阅者实例,就需要将原来的 ObserverBuilder#buildSingleObserver
变为 ObserverBuilder#buildCollectionObserver
(因为 ObserverBuilder#buildSingleObserver(FindCallback)
已经被移除了)。
如果开发者使用了 CQL 查询,那么需要将原来的 AVQuery#doCloudQueryInBackground
调用改为 LCCloudQuery#executeInBackground
。
从 7.0.0 版本开始,我们将 Java Unified SDK 底层的 JSON 解析模块完全切换到了 Gson,开发者在业务层使用 Java Unified SDK 与 JSON 解析库,主要有如下三种情形:
com.alibaba.fastjson
替换成 cn.leancloud.json
即可,例如://import com.alibaba.fastjson.JSON
//import com.alibaba.fastjson.JSONObject
//import com.alibaba.fastjson.JSONArray
import cn.leancloud.json.JSON
import cn.leancloud.json.JSONObject
import cn.leancloud.json.JSONArray
7.0.0-SNAPSHOT
之后,Android Studio 打包时出现 RuntimeException,出错信息如下:java.lang.RuntimeException
at org.objectweb.asm.ClassVisitor.visitModule(ClassVisitor.java:148)
at org.objectweb.asm.ClassReader.readModule(ClassReader.java:731)
at org.objectweb.asm.ClassReader.accept(ClassReader.java:632)
at com.google.firebase.perf.plugin.instrumentation.Instrument.instrument(Instrument.java:151)
at com.google.firebase.perf.plugin.instrumentation.Instrument.instrumentClassesInJar(Instrument.java:100)
按照这里的解释,可以通过升级 Android Gradle plugin -> 3.5.3, Gradle -> v5.5
解决。
我们有计划将 Java Unified SDK 核心代码和 JSON 解析库分开,以后开发者可以根据自己的需求配置使用 Gson 或者 fastjson,类似于 retrofit2 的 converter factory,开发排期则要视开发者的需求而定。
与老版本 SDK 相比,6.x 的主要改进有两点:
老版本 SDK 因为历史原因,Android 平台和纯 Java 平台(在云引擎中使用)是两套完全分开的代码,接口不统一,维护也比较困难。新的 SDK 则对此进行了修改,使用一套代码来适配多个平台。
老版本 SDK 所有的网络请求都是通过 Callback 方式实现的,在有多次前后依赖的请求时会导致代码嵌套层级过多,影响阅读,同时在 Java 开发环境下这种异步的方式也不友好。故而新版本 SDK 完全基于 RxJava 来构建,满足函数式编程要求,可以非常方便地支持这种扩展。
6.x 的函数接口尽可能沿用了老版 SDK 的命名方式,所以要做的改动主要是 Callback
回调机制的修改。
例如老的方式保存一个 AVObject 的代码如下(Callback 方式):
final AVObject todo = new AVObject("Todo");
todo.put("title", "工程师周会");
todo.put("content", "每周工程师会议,周一下午2点");
todo.put("location", "会议室");// 只要添加这一行代码,服务端就会自动添加这个字段
todo.saveInBackground(new SaveCallback() {
@Override
public void done(AVException e) {
if (e == null) {
// 存储成功
Log.d(TAG, todo.getObjectId());// 保存成功之后,objectId 会自动从服务端加载到本地
} else {
// 失败的话,请检查网络环境以及 SDK 配置是否正确
}
}
});
而 6.x 里 AVObject#saveInBackground
方法,返回的是一个 Observable<? extends AVObject>
实例,我们需要 subscribe 才能得到结果通知,新版本的实现方式如下:
final AVObject todo = new AVObject("Todo");
todo.put("title", "工程师周会");
todo.put("content", "每周工程师会议,周一下午2点");
todo.put("location", "会议室");// 只要添加这一行代码,服务端就会自动添加这个字段
todo.saveInBackground().subscribe(new Observer<AVObject>() {
public void onSubscribe(Disposable disposable) {
}
public void onNext(AVObject avObject) {
System.out.println("remove field finished.");
}
public void onError(Throwable throwable) {
}
public void onComplete() {
}
});
将所有的 Callback 改为 Observer 形式的改动会比较大,考虑到尽量降低迁移成本,我们准备了一个工具类 cn.leancloud.convertor.ObserverBuilder
,该类有一系列的 buildSingleObserver
方法,来帮我们由原来的 Callback 回调函数生成 Observable
实例,上面的例子按照这种方法可以变为:
final AVObject todo = new AVObject("Todo");
todo.put("title", "工程师周会");
todo.put("content", "每周工程师会议,周一下午2点");
todo.put("location", "会议室");// 只要添加这一行代码,服务端就会自动添加这个字段
todo.saveInBackground().subscribe(ObserverBuilder.buildSingleObserver(new SaveCallback() {
@Override
public void done(AVException e) {
if (e == null) {
// 存储成功
Log.d(TAG, todo.getObjectId());// 保存成功之后,objectId 会自动从服务端加载到本地
} else {
// 失败的话,请检查网络环境以及 SDK 配置是否正确
}
}
}));
处理异步调用结果的两种方式,可供大家自由选择。
在 6.x 中我们统一将包名的 root 目录由 com.avos.avoscloud
改成了 cn.leancloud
,也需要大家做一个全局替换。
大家使用中发现 Bug、或者有任何疑问或建议,请使用 GitHub Issues 来告知我们,非常感谢大家的反馈。
Copyright (c) 2017-present, Meiwei Shuqian(Beijing) Information Technology Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.