Skip to content

0 Get Started

Jang Rush edited this page May 5, 2019 · 17 revisions

平台与 SDK 对应关系

LeanCloud Java SDK 主要包含以下几个 library,其层次结构以及平台对应关系如下:

基础包(可以在纯 Java 环境下调用)

  • storage-core:包含所有数据存储的功能,如
    • 结构化数据(AVObject)
    • 内建账户系统(AVUser)
    • 查询(AVQuery)
    • 文件存储(AVFile)
    • 社交关系(AVFriendship,当前版本暂不提供)
    • 朋友圈(AVStatus,当前版本暂不提供)
    • 短信(AVSMS)
    • 等等
  • realtime-core:部分依赖 storage-core library,实现了 LiveQuery 以及即时通讯功能,如:
    • LiveQuery
    • AVIMClient
    • AVIMConversation 以及多种场景对话
    • AVIMMessage 以及多种子类化的多媒体消息
    • 等等

云引擎使用的包

  • engine-core:是 LeanCloud 云引擎项目需要依赖的包。

Android 特有的包

  • storage-android:是 storage-core 在 Android 平台的定制化实现,接口与 storage-core 完全相同。
  • realtime-android:是 realtime-core 在 Android 平台的定制化实现,并且增加 Android 推送相关接口。
  • mixpush-android:是 LeanCloud 混合推送的 library,支持华为、小米、魅族的官方推送。
  • leancloud-fcm:是 Firebase Cloud Messaging 的封装 library,供美国节点的 app 使用推送服务。

模块依赖关系

Java SDK 一共包含如下几个模块:

目录 模块名 适用平台 依赖关系
./core storage-core,存储核心 library java 无,它是 LeanCloud 最核心的 library
./realtime realtime-core,LiveQuery 与实时通讯核心 library java storage-core
./leanengine engine-core,云引擎 library java storage-core
./android-sdk/storage-android storage-android,Android 存储 library Android storage-core
./android-sdk/realtime-android realtime-android,Android 推送、LiveQuery、即时通讯 library Android storage-android, realtime-core
./android-sdk/mixpush-android Android 混合推送 library Android realtime-android
./android-sdk/leancloud-fcm Firebase Cloud Messaging library Android realtime-android

获取 SDK

获取 SDK 有多种方式,较为推荐的方式是通过包依赖管理工具下载最新版本。

包依赖管理工具安装

  • 纯 Java 环境下运行的库(storage-core, realtime-core, engine-core)已经发布到 maven central repo
  • Android 平台使用的库(storage-android, realtime-android, mixpush-android, leancloud-fcm)也已经发布到 maven central repo

开发者可以从线上直接获取。

使用存储功能

Example for Maven:

<dependency>
    <groupId>cn.leancloud</groupId>
    <artifactId>storage-core</artifactId>
    <version>{currentVersion}</version>
</dependency>

and for Ivy:

<dependency org="cn.leancloud" name="storage-core" rev="{currentVersion}" />

and for SBT:

libraryDependencies += "cn.leancloud" %% "storage-core" % "{currentVersion}"

and for Gradle:

implementation('cn.leancloud:storage-android:{currentVersion}')
implementation 'io.reactivex.rxjava2:rxandroid:2.1.0'
implementation 'com.alibaba:fastjson:1.1.70.android'

请注意:{currentVersion} 指当前最新版本,可以从maven central repository查询获得。

使用即时通讯 / 推送服务

Example for Maven:

<dependency>
    <groupId>cn.leancloud</groupId>
    <artifactId>realtime-core</artifactId>
    <version>{currentVersion}</version>
</dependency>

and for Ivy:

<dependency org="cn.leancloud" name="realtime-core" rev="{currentVersion}" />

and for SBT:

libraryDependencies += "cn.leancloud" %% "realtime-core" % "{currentVersion}"

and for Gradle:

    implementation('cn.leancloud:realtime-android:{currentVersion}') {
        exclude group: 'com.alibaba', module: 'fastjson'
        exclude group: 'org.ligboy.retrofit2', module: 'converter-fastjson'
    }
    implementation 'io.reactivex.rxjava2:rxandroid:2.1.0'
    implementation 'com.alibaba:fastjson:1.1.70.android'

请注意:{currentVersion} 指当前最新版本,可以从maven central repository查询获得。

使用混合推送服务

Example for Gradle:

implementation('cn.leancloud:mixpush-android:{currentVersion}')
implementation 'io.reactivex.rxjava2:rxandroid:2.1.0'
implementation 'com.alibaba:fastjson:1.1.70.android'

请注意:{currentVersion} 指当前最新版本,可以从maven central repository查询获得。

云引擎项目

Example for Maven:

<dependency>
    <groupId>cn.leancloud</groupId>
    <artifactId>engine-core</artifactId>
    <version>{currentVersion}</version>
</dependency>

请注意:{currentVersion} 指当前最新版本,可以从maven central repository查询获得。

手动安装

从源码编译

To check out and build the LeanCloud Java SDK source, issue the following commands:

$ git clone git@github.com:leancloud/java-sdk-all.git
$ cd java-sdk-all/
$ mvn clean install

To build Android SDK source, issue the following commands:

$ cd java-sdk-all/
$ cd android-sdk/
$ gradle clean assemble

初始化

假设已经设置好了 SDK 依赖关系,可以开始功能接入了,我们首先看一下如何进行 SDK 的初始化。

获取 appId 与 appKey

首先进入 控制台 > 设置 > 应用 Key 来获取 App ID 以及 App Key。

Java 平台初始化代码

在程序执行之初,执行如下代码即可完成初始化:

AVOSCloud.initialize("{your_appId}","{your_appKey}");

将上述代码中的 App ID 以及 App Key 替换成从控制台复制粘贴的对应的数据即可。

云引擎项目初始化

ServletContextListener 子类的 contextInitialized 方法中,按照如下流程进行初始化:

@Override
public void contextInitialized(ServletContextEvent arg0) {
  // 注册子类化
  AVObject.registerSubclass(Todo.class);

  // 可选步骤,设置访问云引擎实例的开发版标志
  if ("development".equals(appEnv) && "true".equals(haveStaging) || "stage".equals(appEnv)) {
    AVCloud.setProductionMode(false);
  }
  // 初始化AVOSCloud,请保证在整个项目中间只初始化一次
  LeanEngine.initialize(”{your_appId}“, ”{your_appKey}“, ”{your_appMasterKey}“);
  // 在请求签名中使用masterKey以激活云代码的最高权限
  JavaRequestSignImplementation.instance().setUseMasterKey(true);
  // 向云引擎注册云函数
  LeanEngine.register(Cloud.class);
}

Android 平台初始化

在 Application 类的 onCreate 函数中,加入如下代码:

import cn.leancloud.AVOSCloud;

public class MyLeanCloudApp extends Application {

    @Override
    public void onCreate() {
        super.onCreate();

        // 初始化参数依次为 this, AppId, AppKey
        // 注意这里千万不要调用 cn.leancloud.core.AVOSCloud 的 initialize 方法,否则会出现 NetworkOnMainThread 等错误。
        AVOSCloud.initialize(this,"{your_appId}}","{your_appKey}");
    }
}

然后打开 AndroidManifest.xml 文件来配置 SDK 所需要的手机的访问权限以及声明刚才我们创建的 MyLeanCloudApp 类:

<!-- 基础模块(必须加入以下声明)START -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<!-- 基础模块 END -->

<application
  ...
  android:name=".MyLeanCloudApp" >

  <!-- 实时通信模块、推送(均需要加入以下声明) START -->
  <!-- 实时通信模块、推送都要使用 PushService -->
  <service android:name="com.avos.avoscloud.PushService"/>
  <receiver android:name="com.avos.avoscloud.AVBroadcastReceiver">
    <intent-filter>
      <action android:name="android.intent.action.BOOT_COMPLETED"/>
      <action android:name="android.intent.action.USER_PRESENT"/>
      <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
    </intent-filter>
  </receiver>
  <!-- 实时通信模块、推送 END -->

  <!-- 反馈组件(需要加入以下声明)START -->
  <activity
     android:name="com.avos.avoscloud.feedback.ThreadActivity" >
  </activity>
  <!-- 反馈组件 END -->
</application>

开启调试日志

在应用开发阶段,你可以选择开启 SDK 的调试日志(debug log)来方便追踪问题。调试日志开启后,SDK 会把网络请求、错误消息等信息输出到 IDE 的日志窗口,或是浏览器 Console 或是 LeanCloud 控制台的 云引擎日志 中。

// 在 AVOSCloud.initialize 之前调用
AVOSCloud.setLogLevel(AVLogger.Level.DEBUG);// or AVOSCloud.setLogLevel(AVLogger.Level.VERBOSE);

指定服务节点

SDK 的初始化方法默认使用中国华北节点,如需切换到 其他可用节点,请参考如下用法:

// 在 AVOSCloud.initialize 之前调用
// 可选的节点有:
//    REGION.NorthChina - 华北节点,默认节点
//    REGION.EastChina  - 华东节点
//    REGION.NorthAmerica - 北美节点
AVOSCloud.setRegion(AVOSCloud.REGION.NorthChina);

同步/异步调用

新版本 SDK 主要提供两类接口,接口签名对 Java 和 Android 平台的接口来说都是一样的,一般而言:

  1. xxxInBackground(例如 saveInBackground/findInBackground/deleteInBackground) 是异步接口,统一会返回 Observable 实例,后续需要调用 RxJava 的 subscribe/consumer 等方法来处理实际执行结果。
  2. xxx 是同步接口(AVUser#logIn 除外),会直接返回操作的结果(或者为空)。

注意:xxxInBackground 系列接口在 Java 平台会自动变为同步接口(即同样的函数在 Android 平台调用是异步的,但是在 Java 平台调用是同步的)。

Android SDK 老版本迁移

如果你已经在使用我们老版本 Android SDK,要迁移到当前新版本,函数接口方面新版 SDK 尽可能沿用老版 SDK 的命名方式,所以要做的改动主要是Callback 回调机制的修改。

Observable 接口

例如老的方式保存一个 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 配置是否正确
    }
  }
});

而新版本 SDK 里 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() {
  }
});

ObserverBuilder 工具类

这个改动比较大,考虑到尽量降低迁移成本,我们准备了一个工具类 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 配置是否正确
    }
  }
}));

处理异步调用结果的两种方式,可供大家自由选择。

另外,在新版 SDK 中我们统一将包名的 root 目录由 com.avos.avoscloud 改成了 cn.leancloud,也需要大家做一个全局替换。

You can’t perform that action at this time.