简介

Bmob平台为您的移动应用提供了一个完整的后端解决方案，我们提供轻量级的SDK开发包，让开发者以最小的配置和最简单的方式使用Bmob平台提供的服务，进而完全消除开发者编写服务器代码以及维护服务器的操作。

快速入门

建议您在阅读本开发文档之前，先阅读我们提供的 Android快速入门文档，便于您后续的开发。

如果开发者想使用不同历史版本的SDK，可以移步历史版本的github仓库，选择使用各个历史版本。

模板代码

在使用SDK过程中，如果一些Api如查询是高频代码，可以把一些重复的样板代码抽出来，并在AndroidStudio中设置模板，即可实现快速输入，能提高编码效率，效果如下：

数据迁移

从v3.5.5开始，数据SDK新增了能重新设置请求域名的Api，类似数据迁移，调用方式如下：

    Bmob.resetDomain("http://demo.bmob.cn/");

其中，参数为开发者的域名，调用后的所有请求都指向新的域名。

统计SDK

从v3.5.2开始，把统计SDK集成到了数据服务SDK，上传应用不再需要额外集成统计SDK，低于此版本的可以去控制台的应用官网下载。

添加方法

• 确保项目有INTERNET和READ_PHONE_STATE权限

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />

• 在初始化方法中传一个渠道参数(不传默认没开启统计功能)

    Bmob.initialize(this,APPID,"Bmob");

• 将libs文件夹内的BmobStat.jar文件添加进项目（AS选择远程依赖可以忽略，本地依赖需要指定libs文件夹，Eclipse中放进libs即可）；

兼容Android6.0系统

自v3.4.6版本开始，Bmob提供了一些新的方法和工具类来帮助开发者为自己的应用兼容Android6.0系统。

添加对Apache的HTTP-client支持

Android6.0版本移除了对Appache的HTTP client的支持，因此，需要添加org.apache.http.legacy.jar包，请参照如下方式添加：

1.Eclipse

你需要在Eclipse工程的项目根目录中新建libs文件夹，将org.apache.http.legacy.jar包，添加到libs文件夹中

2.AndroidStudio

你需要在app的build.gradle文件添加配置信息useLibrary ‘org.apache.http.legacy’声明编译时依赖

    android {
        compileSdkVersion 23
        buildToolsVersion "23.0.2"
        useLibrary 'org.apache.http.legacy'
    }

注：如果在build.gradle文件中useLibrary 'org.apache.http.legacy'这句话报错，可将该jar直接放到libs目录下即可。

运行时权限管理

Android6.0中对特定的权限进行了动态授权的方式，需要在运行时用户手动授予，如果用户拒绝后再次申请还可以向用户弹框说明权限的作用，用户点击确认后再去申请。

因此，我们提供了一个权限管理的工具类PermissionManager(cn.bmob.v3.helper)，具体使用如下：

注：在v3.4.6的BmobSDK内部集成PermissionManager类，自v3.4.7以后的SDK内部将不再提供该类，开发者可以在下载的配套官方Demo的com.example.bmobexample.permission包下面查看该类源码。

1.构建PermissionManager对象

PermissionManager helper;
helper = PermissionManager.with(MainActivity.this)
        //添加权限请求码
        .addRequestCode(MainActivity.REQUEST_CODE_CAMERA)
        //设置权限，可以添加多个权限
        .permissions(Manifest.permission.CAMERA)
        //设置权限监听器
        .setPermissionsListener(new PermissionListener() {
            @Override
            public void onGranted() {
                //当权限被授予时调用
               Toast.makeText(MainActivity.this, "Camera Permission granted",Toast.LENGTH_LONG).show();
            }
            @Override
            public void onDenied() {
                //用户拒绝该权限时调用
               Toast.makeText(MainActivity.this, "Camera Permission denied",Toast.LENGTH_LONG).show();
            }
            @Override
            public void onShowRationale(String[] permissions) {
                //当用户拒绝某权限时并点击`不再提醒`的按钮时，下次应用再请求该权限时，需要给出合适的响应（比如,给个展示对话框来解释应用为什么需要该权限）
                Snackbar.make(btn_camera, "需要相机权限去拍照", Snackbar.LENGTH_INDEFINITE)
                        .setAction("ok", new View.OnClickListener() {
                            @Override
                            public void onClick(View v) {
                                //必须调用该`setIsPositive(true)`方法
                                helper.setIsPositive(true);
                                helper.request();
                            }
                        }).show();
            }
        })
        //请求权限
        .request();

注：

• with方法可以传入Activity或者Fragment；
• addRequestCode方法传入请求码，用于区分各种不同的权限申请；
• permissions方法传入的是你所要请求的权限，支持可变参数，可以批量申请权限；
• PermissionListener接口回调的三个方法：
  • onGranted()会在权限申请通过后被调用；
  • onDenied()在权限申请被拒绝时被调用
  • onShowRationale()方法中你可以弹对话框向用户解释权限的作用，不过记得要调用setIsPositive(true)。
• request方法用来请求权限申请

2.覆写onRequestPermissionsResult方法

@Override
public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults);
    switch (requestCode) {
        case REQUEST_CODE_CAMERA:
            helper.onPermissionResult(permissions, grantResults);
            break;
    }
}

Notification变更

Android6.0中，Notification.setLatestEventInfo()方法被移除，替代的方案是用Notification.Builder来构建通知，对此SDK提供了NotificationCompat(cn.bmob.v3.helper)类来做版本兼容（与android.support.v4.app包下的NotificationCompat用法一样）。

参照代码如下：

    NotificationManager notificationManager = (NotificationManager) mContext
            .getSystemService(Context.NOTIFICATION_SERVICE);
    PendingIntent pi = PendingIntent.getActivity(mContext, 0,
            new Intent(MainActivity.this, MainActivity.class), 0);
    NotificationCompat.Builder builder = new NotificationCompat.Builder(mContext)
            .setTicker("更新啦")
            .setContentTitle("标题")
            .setContentText("内容")
            .setSmallIcon(R.drawable.ic_launcher);
    Notification notification = builder.build();
    notificationManager.notify(0, notification);

对象

一个数据对象（APP中创建的BmobObject类的子类）对应于Bmob后台的一个数据表。

数据对象

Bmob存储的数据是建立在BmobObject基础上的，所以任何要保存的数据对象必须继承自BmobObject类(不建议用抽象类去继承BmobObject或者定义父类然后在子类中写bean，这样也解析不了，一般不会这么用，一个bean类对应一张表，类似使用ORM库)。BmobObject类本身包含objectId、createdAt、updatedAt、ACL四个默认的属性，objectId是数据的唯一标示，相当于数据库中表的主键，createdAt是数据的创建时间，updatedAt是数据的最后修改时间，ACL是数据的操作权限。

如，你的游戏中使用GameScore表来记录玩家的比分信息，其中表的字段有：score（分数）、playerName（玩家名字）、isPay(是否付费玩家)、pic（玩家头像）属性，那么这个数据对象为如下定义：

//必须要继承自BmobObject类
public class GameScore extends BmobObject{
    private String playerName;
    private Integer score;
    private Boolean isPay;
    private BmobFile pic;
    public String getPlayerName() {
        return playerName;
    }
    public void setPlayerName(String playerName) {
        this.playerName = playerName;
    }
    public Integer getScore() {
        return score;
    }
    public void setScore(Integer score) {
        this.score = score;
    }
    public Boolean getIsPay() {
        return isPay;
    }
    public void setIsPay(Boolean isPay) {
        this. isPay = isPay;
    }
    public BmobFile getPic() {
        return pic;
    }
    public void setPic(BmobFile pic) {
        this.pic = pic;
    }
}

需要注意的是：

• JavaBean不需要对objectId、createdAt、updatedAt、ACL四个属性进行定义。
• 不少开发者会没有注意到createdAt和updatedAt属性中的字母d，写成createAt和updateAt。
• 尽可能使用Integer、Boolean，而不是int、boolean，也就是选择包装类，而不是使用基本数据类型（这两者的区别大家可以看这篇文章：http://www.cnblogs.com/shenliang123/archive/2011/10/27/2226903.html）

特殊对象

为了提供更好的服务，BmobSDK中提供了BmobUser、BmobInstallation、BmobRole三个特殊的BmobObject对象来完成不同的功能，在这里我们统一称为特殊对象。

• BmobUser对象主要是针对应用中的用户功能而提供的，它对应着web端的User表，使用BmobUser对象可以很方便的在应用中实现用户的注册、登录、邮箱验证等功能，具体的使用方法可查看文档的用户管理部分。

• BmobInstallation对象主要用于应用的安装设备管理中，它对应着web端的Installation表，任何安装了你应用的设备都会在此表中产生一条数据标示该设备。结合Bmob提供的推送功能，还可以实现将自定义的消息推送给不同的设备终端，具体的使用方法可查看文档的消息推送部分。

• BmobRole对象主要用于角色管理，对应用于Web端的Role表，具体的使用方法可查看文档的ACL和角色部分。

数据类型

目前为止，Bmob支持的数据类型：String、Integer、Float、Short、Byte、Double、Character、Boolean、Object、Array。
同时也支持BmobObject、BmobDate、BmobGeoPoint、BmobFile特有的数据类型。

以下为Web端类型与SDK端支持的JAVA类型对应表：

注：不能使用int、float、short byte、double、character等基本数据类型。

类名和表名的关系

• Bmob官方推荐类名和表名完全一致的映射使用方式， 即如，上面的GameScore类，它在后台对应的表名也是GameScore（区分大小写）。
• 如果你希望表名和类名并不相同，如表名为T_a_b，而类名还是GameScore，那么你可以使用BmobObject提供的setTableName(“表名”)的方法，

示例代码如下：

//这时候实际操作的表是T_a_b
public class GameScore extends BmobObject{
    private String playerName;
    private Integer score;
    private Boolean isPay;
    private BmobFile pic;
    public GameScore() {
        this.setTableName("T_a_b");
    }
    public String getPlayerName() {
        return playerName;
    }
    //其他方法，见上面的代码
}

当然了，除了在构造函数中直接调用setTableName方法之外，你还可以在GameScore的实例中动态调用setTableName方法。

查询自定义表名的数据

如果您使用了setTableName方法来自定义表名，那么在对该表进行数据查询的时候必须使用以下方法。需要注意的是查询的结果是JSONArray,需要自行解析JSONArray中的数据。

/**
 * 查询数据
 */
public void queryData(){
    BmobQuery query =new BmobQuery("Person");
    query.addWhereEqualTo("age", 25);
    query.setLimit(2);
    query.order("createdAt");
    //v3.5.0版本提供`findObjectsByTable`方法查询自定义表名的数据
    query.findObjectsByTable(new QueryListener<JSONArray>() {
        @Override
        public void done(JSONArray ary, BmobException e) {
            if(e==null){
                Log.i("bmob","查询成功："+ary.toString());
            }else{
                Log.i("bmob","失败："+e.getMessage()+","+e.getErrorCode());
            }
        }
    });
}

自定义表名情况下的更新、删除数据和普通的更新、删除数据方式一样，没有变化。为方便大家了解学习，我们提供了一个关于自定义表名情况下增删改查数据的Demo，下载地址是：https://github.com/bmob/bmob-android-demo-dynamic-tablename。

添加数据

添加数据使用BmobObject对象的save方法，就可以将当前对象的内容保存到Bmob服务端。
例如，你现在要保存一条游戏分数的记录，代码如下：

GameScore gameScore = new GameScore();
//注意：不能调用gameScore.setObjectId("")方法
gameScore.setPlayerName("比目");
gameScore.setScore(89);
gameScore.setIsPay(false);
gameScore.save(new SaveListener<String>() {
    @Override
    public void done(String objectId, BmobException e) {
        if(e==null){
            toast("创建数据成功：" + objectId);
        }else{
            Log.i("bmob","失败："+e.getMessage()+","+e.getErrorCode());
        }
    }
})

运行以上代码，如果添加成功，你可以在Bmob提供的后台的数据浏览中看到类似这样的结果：

objectId: "0c6db13c", score: 89, playerName: "比目", isPay: false,createdAt:"2013-09-27 10:32:54", updatedAt:"2013-09-27 10:32:54"

这里需要注意的是：

1. 如果服务器端不存在GameScore表，那么系统将自动建表，并插入数据。

2. 如果服务器端已经存在GameScore表，和相应的score、playerName、isPay字段，那么你此时添加的数据和数据类型也应该和服务器端的表结构一致，否则会保存数据失败。

3. 每个BmobObject对象都有几个默认的键(数据列)是不需要开发者指定的，objectId是每个保存成功数据的唯一标识符。createdAt和updatedAt代表每个对象(每条数据)在服务器上创建和最后修改的时间。这些键(数据列)的创建和数据内容是由服务器端自主来完成的。因此，使用save和insert方法时,不需要调用setObjectId方法，否则会出现提示：“It is a reserved field: objectId(105)”--表明objectId为系统保留字段，不允许修改。。

更新数据

更新一个对象也是非常简单。例如：将GameScore表中objectId为0c6db13c的游戏分数修改为77.

GameScore gameScore = new GameScore();
gameScore.setScore(77);
gameScore.update("0c6db13c", new UpdateListener() {
    @Override
    public void done(BmobException e) {
        if(e==null){
            Log.i("bmob","更新成功");
        }else{
            Log.i("bmob","更新失败："+e.getMessage()+","+e.getErrorCode());
        }
    }
});

自V3.4.4版本开始，SDK提供了另一种方法来更新数据，通过调用Bmobobject类中的setValue（key，value）方法，只需要传入key及想要更新的值即可

举例，说明如下：

public class Person extends BmobObject {
    private BmobUser user;    //BmobObject类型
    private BankCard cards;    //Object类型
    private Integer age;    //Integer类型
    private Boolean gender; //Boolean类型
    ...
    getter、setter方法
}
其中BankCard类结构如下：
public class BankCard{
    private String cardNumber;
    private String bankName;
    public BankCard(String bankName, String cardNumber){
        this.bankName = bankName;
        this.cardNumber = cardNumber;
    }
    ...
    getter、setter方法
}

Person p2=new Person();
//更新BmobObject的值
//    p2.setValue("user", BmobUser.getCurrentUser(this, MyUser.class));
//更新Object对象
p2.setValue("bankCard",new BankCard("农行", "农行账号"));
//更新Object对象的值
//p2.setValue("bankCard.bankName","建行");
//更新Integer类型
//p2.setValue("age",11);
//更新Boolean类型
//p2.setValue("gender", true);
p2.update(objectId, new UpdateListener() {
    @Override
    public void done(BmobException e) {
        if(e==null){
            Log.i("bmob","更新成功");
        }else{
            Log.i("bmob","更新失败："+e.getMessage()+","+e.getErrorCode());
        }
    }
});

注意：修改数据只能通过objectId来修改，目前不提供查询条件方式的修改方法。

原子计数器

很多应用可能会有计数器功能的需求，比如文章点赞的功能，如果大量用户并发操作，用普通的更新方法操作的话，会存在数据不一致的情况。

为此，Bmob提供了原子计数器来保证原子性的修改某一数值字段的值。注意：原子计数器只能对应用于Web后台的Number类型的字段，即JavaBeans数据对象中的Integer对象类型（不要用int类型）。

gameScore.increment("score"); // 分数递增1
gameScore.update(updateListener);

您还可以通过increment(key, amount)方法来递增或递减任意幅度的数字

gameScore.increment("score", 5); // 分数递增5
//gameScore.increment("score", -5); // 分数递减5
gameScore.update(updateListener);

删除数据

从服务器删除对象。例如：将GameScore表中objectId为dd8e6aff28的数据删除。

GameScore gameScore = new GameScore();
gameScore.setObjectId("dd8e6aff28");
gameScore.delete(new UpdateListener() {
    @Override
    public void done(BmobException e) {
        if(e==null){
            Log.i("bmob","成功");
        }else{
            Log.i("bmob","失败："+e.getMessage()+","+e.getErrorCode());
        }
    }
});

注意：删除数据只能通过objectId来删除，目前不提供查询条件方式的删除方法。

删除字段的值

你可以在一个对象中删除一个字段的值，通过remove操作：

GameScore gameScore = new GameScore();
gameScore.setObjectId("dd8e6aff28");
gameScore.remove("score");    // 删除GameScore对象中的score字段
gameScore.update(new UpdateListener() {
    @Override
    public void done(BmobException e) {
        if(e==null){
            Log.i("bmob","成功");
        }else{
            Log.i("bmob","失败："+e.getMessage()+","+e.getErrorCode());
        }
    }
});

批量数据操作

自2017年04月起，为了提供更稳定的服务，后端启用了QPS限制，所以推荐采用批量数据操作来解决如果需要在循环里多次提交请求但是后端返回QPS达到限制的报错。

自v3.5.0开始,新增BmobBatch批量操作类，支持批量添加、批量更新、批量删除的三种操作的同步提交，且批量添加的请求返回objectId字段。

在BmobObject对象中提供了三种用于批量操作的方法，分别是insertBatch、updateBatch、deleteBatch,批量添加、更新、删除。

批量添加

List<BmobObject> persons = new ArrayList<BmobObject>();
for (int i = 0; i < 3; i++) {
    Person person = new Person();
    person.setName("张三 "+i);
    persons.add(person);
}
//第一种方式:v3.5.0之前的版本
new BmobObject().insertBatch(this, persons, new SaveListener() {
    @Override
    public void onSuccess() {
        toast("批量添加成功");
    }
    @Override
    public void onFailure(int code, String msg) {
        toast("批量添加失败:"+msg);
    }
});
//第二种方式：v3.5.0开始提供
new BmobBatch().insertBatch(persons).doBatch(new QueryListListener<BatchResult>() {
    @Override
    public void done(List<BatchResult> o, BmobException e) {
        if(e==null){
            for(int i=0;i<o.size();i++){
                BatchResult result = o.get(i);
                BmobException ex =result.getError();
                if(ex==null){
                    log("第"+i+"个数据批量添加成功："+result.getCreatedAt()
                    +","+result.getObjectId()+","+result.getUpdatedAt());
                }else{
                    log("第"+i+"个数据批量添加失败："+ex.getMessage()+","+ex.getErrorCode());
                }
            }
        }else{
            Log.i("bmob","失败："+e.getMessage()+","+e.getErrorCode());
        }
    }
});

批量更新

List<BmobObject> persons = new ArrayList<BmobObject>();
Person p1 = new Person();
p1.setObjectId("e51d651c22");
p1.setAge(25);
Person p2 = new Person();
p2.setObjectId("3f70a922c4");
p2.setAge(26);
p2.setGender(false);
Person p3 = new Person();
p3.setObjectId("08fdd55765");
p3.setAge(27);
persons.add(p1);
persons.add(p2);
persons.add(p3);
//第一种方式：v3.5.0之前的版本
new BmobObject().updateBatch(this, persons, new UpdateListener() {
    @Override
    public void onSuccess() {
        toast("批量更新成功");
    }
    @Override
    public void onFailure(int code, String msg) {
        toast("批量更新失败:"+msg);
    }
});
//第二种方式：v3.5.0开始提供
new BmobBatch().updateBatch(persons).doBatch(new QueryListListener<BatchResult>() {
    @Override
    public void done(List<BatchResult> o, BmobException e) {
        if(e==null){
            for(int i=0;i<o.size();i++){
                BatchResult result = o.get(i);
                BmobException ex =result.getError();
                if(ex==null){
                    log("第"+i+"个数据批量更新成功："+result.getUpdatedAt());
                }else{
                    log("第"+i+"个数据批量更新失败："+ex.getMessage()+","+ex.getErrorCode());
                }
            }
        }else{
            Log.i("bmob","失败："+e.getMessage()+","+e.getErrorCode());
        }
    }
});

批量删除

List<BmobObject> persons = new ArrayList<BmobObject>();
Person p1 = new Person();
p1.setObjectId("38ea274d0c");
Person p2 = new Person();
p2.setObjectId("01e29165bc");
Person p3 = new Person();
p3.setObjectId("d8226c4828");
persons.add(p1);
persons.add(p2);
persons.add(p3);
//第一种方式：v3.5.0之前的版本
new BmobObject().deleteBatch(this, persons, new DeleteListener() {
    @Override
    public void onSuccess() {
        toast("批量删除成功");
    }
    @Override
    public void onFailure(int code, String msg) {
        toast("批量删除失败:"+msg);
    }
});
//第二种方式：v3.5.0开始提供
new BmobBatch().deleteBatch(persons).doBatch(new QueryListListener<BatchResult>() {
            @Override
            public void done(List<BatchResult> o, BmobException e) {
                if(e==null){
                    for(int i=0;i<o.size();i++){
                        BatchResult result = o.get(i);
                        BmobException ex =result.getError();
                        if(ex==null){
                            log("第"+i+"个数据批量删除成功");
                        }else{
                            log("第"+i+"个数据批量删除失败："+ex.getMessage()+","+ex.getErrorCode());
                        }
                    }
                }else{
                    Log.i("bmob","失败："+e.getMessage()+","+e.getErrorCode());
                }
            }
        });

批量添加、批量更新、批量删除同步提交（v3.5.0开始提供）

BmobBatch batch =new BmobBatch();
//批量添加
List<BmobObject> persons = new ArrayList<BmobObject>();
Person person = new Person();
person.setName("张三 ");
persons.add(person);
batch.insertBatch(persons);
//批量更新
List<BmobObject> persons1=new ArrayList<BmobObject>();
Person p1 = new Person();
p1.setObjectId("3388eb6caf");
p1.setAge(35);
persons1.add(p1);
batch.updateBatch(persons1);
//批量删除
List<BmobObject> persons2 = new ArrayList<BmobObject>();
Person p2 = new Person();
p2.setObjectId("9af452ebd");
persons2.add(p2);
batch.deleteBatch(persons2);
//执行批量操作
batch.doBatch(new QueryListListener<BatchResult>(){
    @Override
    public void done(List<BatchResult> results, BmobException ex) {
        if(ex==null){
            //返回结果的results和上面提交的顺序是一样的，请一一对应
            for(int i=0;i<results.size();i++){
                BatchResult result= results.get(i);
                if(result.isSuccess()){//只有批量添加才返回objectId
                    log("第"+i+"个成功："+result.getObjectId()+","+result.getUpdatedAt());
                }else{
                    BmobException error= result.getError();
                    log("第"+i+"个失败："+error.getErrorCode()+","+error.getMessage());
                }
            }
        }else{
            Log.i("bmob","失败："+e.getMessage()+","+e.getErrorCode());
        }
    }
});

注：

1. 批量操作每次只支持最大50条记录的操作。
2. 批量操作不支持对User表的操作。

查询数据

数据的查询可能是每个应用都会频繁使用到的，BmobSDK中提供了BmobQuery类，它提供了多样的方法来实现不同条件的查询，同时它的使用也是非常的简单和方便的。

查询单条数据

当我们知道某条数据的objectId时，就可以根据objectId直接获取单条数据对象。例如：查询objectId为a203eba875的人员信息。

BmobQuery<GameScore> query = new BmobQuery<GameScore>();
query.getObject("a203eba875", new QueryListener<GameScore>() {
    @Override
    public void done(GameScore object, BmobException e) {
        if(e==null){
            //获得playerName的信息
            object.getPlayerName();
            //获得数据的objectId信息
            object.getObjectId();
            //获得createdAt数据创建时间（注意是：createdAt，不是createAt）
            object.getCreatedAt();
        }else{
            Log.i("bmob","失败："+e.getMessage()+","+e.getErrorCode());
        }
    }
});

查询多条数据

查询某个数据表中的所有数据是非常简单的查询操作，例如：查询GameScore表中playerName为“比目”的50条数据记录。

BmobQuery<GameScore> query = new BmobQuery<GameScore>();
//查询playerName叫“比目”的数据
query.addWhereEqualTo("playerName", "比目");
//返回50条数据，如果不加上这条语句，默认返回10条数据
query.setLimit(50);
//执行查询方法
query.findObjects(new FindListener<GameScore>() {
    @Override
    public void done(List<GameScore> object, BmobException e) {
        if(e==null){
            toast("查询成功：共"+object.size()+"条数据。");
            for (GameScore gameScore : object) {
               //获得playerName的信息
               gameScore.getPlayerName();
               //获得数据的objectId信息
               gameScore.getObjectId();
               //获得createdAt数据创建时间（注意是：createdAt，不是createAt）
               gameScore.getCreatedAt();
            }
        }else{
            Log.i("bmob","失败："+e.getMessage()+","+e.getErrorCode());
        }
    }
});

查询的结果不需要进行任何处理，BmobSDK已经为你封装成相应的JavaBean集合了，你直接使用即可。

注：

1. 通过setLimit方法设置返回的记录数量。更多细节可查看下一节(查询条件)中的分页查询。
   

2. v3.5.2开始可以对查询条件等提供链式调用的写法，如下：
   

   BmobQuery<Book> query = new BmobQuery<>();
   query.setLimit(8).setSkip(1).order("-createdAt")
        .findObjects(new FindListener<Book>() {
            @Override
            public void done(List<Book> object, BmobException e) {
                if (e == null) {
                    // ...
                } else {
                    // ...
                }
            }
        });

查询条件

在查询的使用过程中，基于不同条件的查询是非常常见的，BmobQuery同样也支持不同条件的查询。

比较查询

如果要查询特定键的特定值，可以使用addWhereEqualTo方法，如果要过滤掉特定键的值可以使用addWhereNotEqualTo方法。

比如需要查询playerName不等于“Barbie”的数据时可以这样写：

query.addWhereNotEqualTo("playerName", "Barbie");

当然，你可以在你的查询操作中添加多个约束条件，来查询符合要求的数据。

query.addWhereNotEqualTo("playerName", "Barbie");     //名字不等于Barbie
query.addWhereGreaterThan("score", 60);                //条件：分数大于60岁

各种不同条件的比较查询：

// 分数 < 50
query.addWhereLessThan("score", 50);
//分数 <= 50
query.addWhereLessThanOrEqualTo("score", 50);
//分数 > 50
query.addWhereGreaterThan("score", 50);
//分数 >= 50
query.addWhereGreaterThanOrEqualTo("score", 50);

子查询

如果你想查询匹配几个不同值的数据，如：要查询“Barbie”,“Joe”,“Julia”三个人的成绩时，你可以使用addWhereContainedIn方法来实现。

String[] names = {"Barbie", "Joe", "Julia"};
query.addWhereContainedIn("playerName", Arrays.asList(names));

相反，如果你想查询排除“Barbie”,“Joe”,“Julia”这三个人的其他同学的信息，你可以使用addWhereNotContainedIn方法来实现。

String[] names = {"Barbie", "Joe", "Julia"};
query.addWhereNotContainedIn("playerName", Arrays.asList(names));

时间查询

时间查询比较特殊，我们需要结合BmobDate这个类来查询某个指定日期时间前后的数据，这里也给出示例供大家参考：

比如:

如果想查询指定日期之前的数据，则可以使用addWhereLessThan或者addWhereLessThanOrEqualTo（包含当天）来查询。

如果想查询指定日期之后的数据，则可以使用addWhereGreaterThan或addWhereGreaterThanOrEqualTo（包含当天）来查询。

如果想查询指定时间当天的数据，则需要使用复合与查询来查询，例如，想查询2015年5月1号当天的Person数据,示例代码如下：

BmobQuery<Person> query = new BmobQuery<Person>();
List<BmobQuery<Person>> and = new ArrayList<BmobQuery<Person>>();
//大于00：00：00
BmobQuery<Person> q1 = new BmobQuery<Person>();
String start = "2015-05-01 00:00:00";  
SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");  
Date date  = null;
try {
date = sdf.parse(start);
} catch (ParseException e) {
e.printStackTrace();
}  
q1.addWhereGreaterThanOrEqualTo("createdAt",new BmobDate(date));
and.add(q1);
//小于23：59：59
BmobQuery<Person> q2 = new BmobQuery<Person>();
String end = "2015-05-01 23:59:59"; 
SimpleDateFormat sdf1 = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");  
Date date1  = null;
try {
date1 = sdf1.parse(end);
} catch (ParseException e) {
e.printStackTrace();
}  
q2.addWhereLessThanOrEqualTo("createdAt",new BmobDate(date1));
and.add(q2);
//添加复合与查询
query.and(and);

注：

由于createdAt、updatedAt是服务器自动生成的时间，在服务器保存的是精确到微秒值的时间，所以，基于时间类型的比较的值要加1秒。

数组查询

对于字段类型为数组的情况，需要查找字段中的数组值包含有xxx的对象，可以使用addWhereContainsAll方法：

比如我想查询有阅读和唱歌爱好的人，可以这样：

BmobQuery<Person> query = new BmobQuery<Person>();
String [] hobby = {"阅读","唱歌"};
query.addWhereContainsAll("hobby", Arrays.asList(hobby));
query.findObjects(new FindListener<Person>() {
    @Override
    public void done(List<Person> object, BmobException e) {
        if(e==null){
            ...
        }else{
            ...
        }
    }
});

模糊查询

对字符串值的模糊查询 比如 查询包含字符串的值，有几种方法。

你可以使用任何正确的正则表达式来检索相匹配的值，使用addWhereMatches方法：

query.addWhereMatches(("username", "^[A-Z]\\d");

还可以使用如下方法：

//查询username字段的值含有“sm”的数据
query.addWhereContains("username", "sm");
//查询username字段的值是以“sm“字开头的数据
query.whereStartsWith("username", "sm");
// 查询username字段的值是以“ile“字结尾的数据
query.whereEndsWith("username", "ile");

注:模糊查询只对付费用户开放，付费后可直接使用。

列值是否存在

如果你想查询某个列的值存在，那么可以使用addWhereExists方法：

//查询username有值的数据
query.addWhereExists("username");

如果想查询某个列的值不存在，则可以用addWhereDoesNotExists方法

//查询username字段没有值的数据
query.addWhereDoesNotExists("username");

分页查询

有时，在数据比较多的情况下，你希望查询出的符合要求的所有数据能按照多少条为一页来显示，这时可以使用setLimit方法来限制查询结果的数据条数来进行分页。

默认情况下，Limit的值为100，最大有效设置值1000（设置的数值超过1000还是视为1000）。

query.setLimit(10); // 限制最多10条数据结果作为一页

在数据较多的情况下，在setLimit的基础上分页显示数据是比较合理的解决办法。
setSKip方法可以做到跳过查询的前多少条数据来实现分页查询的功能。默认情况下Skip的值为10。

query.setSkip(10); // 忽略前10条数据（即第一页数据结果）

大家也可以直接下载我们提供的Demo源码（https://github.com/bmob/bmob-android-demo-paging），查看如何使用分页查询，结合ListView开发下拉刷新查看更多内容的应用。

排序

对应数据的排序，如数字或字符串，你可以使用升序或降序的方式来控制查询数据的结果顺序：

// 根据score字段升序显示数据
query.order("score");
// 根据score字段降序显示数据
query.order("-score");
// 多个排序字段可以用（，）号分隔
query.order("-score,createdAt");

说明：多个字段排序时，先按第一个字段进行排序，再按第二个字段进行排序，依次进行。

复合查询

与查询(and)

有些查询需要使用到复合“与”的查询条件，例如：你想查询出Person表中年龄在6-29岁之间且姓名以”y”或者”e”结尾的人，那么，可以采用and查询，示例代码如下：

//查询年龄6-29岁之间的人，每一个查询条件都需要New一个BmobQuery对象
//--and条件1
BmobQuery<Person> eq1 = new BmobQuery<Person>();
eq1.addWhereLessThanOrEqualTo("age", 29);//年龄<=29
//--and条件2
BmobQuery<Person> eq2 = new BmobQuery<Person>();
eq2.addWhereGreaterThanOrEqualTo("age", 6);//年龄>=6
//查询姓名以"y"或者"e"结尾的人--这个需要使用到复合或查询（or）
//--and条件3
BmobQuery<Person> eq3 = new BmobQuery<Person>();
eq3.addWhereEndsWith("name", "y");
BmobQuery<Person> eq4 = new BmobQuery<Person>();
eq4.addWhereEndsWith("name", "e");
List<BmobQuery<Person>> queries = new ArrayList<BmobQuery<Person>>();
queries.add(eq3);
queries.add(eq4);
BmobQuery<Person> mainQuery = new BmobQuery<Person>();
BmobQuery<Person> or = mainQuery.or(queries);
//最后组装完整的and条件
List<BmobQuery<Person>> andQuerys = new ArrayList<BmobQuery<Person>>();
andQuerys.add(eq1);
andQuerys.add(eq2);
andQuerys.add(or);
//查询符合整个and条件的人
BmobQuery<Person> query = new BmobQuery<Person>();
query.and(andQuerys);
query.findObjects(new FindListener<Person>() {
    @Override
    public void done(List<Person> object, BmobException e) {
        if(e==null){
            toast("查询年龄6-29岁之间，姓名以'y'或者'e'结尾的人个数："+object.size());
        }else{
            Log.i("bmob","失败："+e.getMessage()+","+e.getErrorCode());
        }
    }
});

或查询(or)

有些情况，在查询的时候需要使用到复合的“或”的查询条件。例如，你想查出 Person 表中 age 等于 29 或者 age 等于 6 的人，可以这样：

BmobQuery<Person> eq1 = new BmobQuery<Person>();
eq1.addWhereEqualTo("age", 29);
BmobQuery<Person> eq2 = new BmobQuery<Person>();
eq2.addWhereEqualTo("age", 6);
List<BmobQuery<Person>> queries = new ArrayList<BmobQuery<Person>>();
queries.add(eq1);
queries.add(eq2);
BmobQuery<Person> mainQuery = new BmobQuery<Person>();
mainQuery.or(queries);
mainQuery.findObjects(new FindListener<Person>() {
    @Override
    public void done(List<Person> object, BmobException e) {
        if(e==null){
            toast("查询年龄6-29岁之间，姓名以'y'或者'e'结尾的人个数："+object.size());
        }else{
            Log.i("bmob","失败："+e.getMessage()+","+e.getErrorCode());
        }
    }
});

你还可以在此基础上添加更多的约束条件到新创建的 BmobQuery 对象上，表示一个 and 查询操作。

查询结果计数

如果你只是想统计满足查询对象的数量，你并不需要获取所有匹配对象的具体数据信息，可以直接使用count替代findObjects。例如，查询一个特定玩家玩的游戏场数：

BmobQuery<GameSauce> query = new BmobQuery<GameSauce>();
query.addWhereEqualTo("playerName", "Barbie");
query.count(GameSauce.class, new CountListener() {
    @Override
    public void done(Integer count, BmobException e) {
        if(e==null){
            toast("count对象个数为："+count);
        }else{
            Log.i("bmob","失败："+e.getMessage()+","+e.getErrorCode());
        }
    }
});

查询指定列

有的时候，一张表的数据列比较多，而我们只想查询返回某些列的数据时，我们可以使用BmobQuery对象提供的addQueryKeys方法来实现。如下所示：

//只返回Person表的objectId这列的值
BmobQuery<Person> bmobQuery = new BmobQuery<Person>();
bmobQuery.addQueryKeys("objectId");
bmobQuery.findObjects(new FindListener<Person>() {
    @Override
    public void done(List<Person> object, BmobException e) {
        if(e==null){
            toast("查询成功：共" + object.size() + "条数据。");
             //注意：这里的Person对象中只有指定列的数据。
        }else{
            Log.i("bmob","失败："+e.getMessage()+","+e.getErrorCode());
        }
    }
});

指定多列时用,号分隔每列，如：addQueryKeys("objectId,name,age");

统计查询

从BmobSDKV3.3.6开始，Bmob为开发者提供了以下关键字或其组合的统计查询操作,分别用于计算总和、平均值、最大值、最小值，同时支持分组和过滤条件。

注：

1. 为避免和用户创建的列名称冲突，Bmob约定以上查询返回的字段采用_(关键字)+首字母大写的列名 的格式：

例：
计算玩家得分表（GameScore）中列名为score的总和，那么返回的结果集会有一个列名为_sumScore，
若设置了setHasGroupCount（true）,则结果集中会返回_count。

1. 以上方法可自由组合且与之前的查询语句中的where, order, limit, skip等组合一起使用。

2. 因为返回格式不固定，故使用findStatistics来专门处理统计查询。

统计查询方法

例如，如果要计算所有玩家的得分总和，那么代码如下：

BmobQuery<GameScore> query = new BmobQuery<GameScore>();
query.sum(new String[] { "playScore" });
query.findStatistics(GameScore.class,new QueryListener<JSONArray>() {
    @Override
    public void done(JSONArray ary, BmobException e) {
        if(e==null){
            if(ary!=null){//
                try {
                    JSONObject obj = ary.getJSONObject(0);
                    int sum = obj.getInt("_sumPlayScore");//_(关键字)+首字母大写的列名
                    showToast("游戏总得分：" + sum);
                } catch (JSONException e1) {
                    e1.printStackTrace();
                }
            }else{
                showToast("查询成功，无数据");
            }
        }else{    
            Log.i("bmob","失败："+e.getMessage()+","+e.getErrorCode());
        }
    }
});

注：sum方法的参数只能查询Number类型的列名（对应Java的Integer类型），即要计算哪个列的值的总和。

查询平均值、最大、最小和上面的求和类似，在这里也一并提示下：

BmobQuery<GameScore> query = new BmobQuery<GameScore>();
//query.average(new String[]{"playScore"});//查询某列的平均值
query.min(new String[]{"playScore"});//查询最小值
//query.max(new String[]{"playScore"});//查询最大值
query.groupby(new String[]{"createdAt"});
query.findStatistics(GameScore.class, new QueryListener<JSONArray>() {
    @Override
    public void done(JSONArray ary, BmobException e) {
        if(e==null){
            JSONArray ary = (JSONArray) result;
            if (ary!=null) {
                try {
                    JSONObject obj = ary.getJSONObject(0);
    //                int playscore = obj.getInt("_avgPlayScore");
                    int minscore = obj.getInt("_minPlayScore");
    //                int maxscore = obj.getInt("_maxPlayScore");
                    String createDate = obj.getString("createdAt");
                    showToast("minscore = " + minscore+ ",统计时间 = "+ createDate);
                } catch (JSONException e) {
                    e.printStackTrace();
                }
        } else {
            showToast("查询成功，无数据");
        }
        }else{
            loge(e);
        }
    }
});

分组统计

如果你需要对查询结果进行分组，可使用groupby方法，支持根据多个列名进行分组。

//我们以创建时间按天和游戏分别统计玩家的得分，并按时间降序
BmobQuery<GameScore> query = new BmobQuery<GameScore>();
query.sum(new String[] { "playScore", "signScore" });//求多个列的总和
query.groupby(new String[] { "createdAt", "game" });//按照时间和游戏名进行分组
query.order("-createdAt");//降序排列
query.findStatistics(GameScore.class,new QueryListener<JSONArray>() {
    @Override
    public void done(JSONArray ary, BmobException e) {
        if(e==null){
            if(ary!=null){
                int length = ary.length();
                try {
                    for (int i = 0; i < length; i++) {
                        JSONObject obj = ary.getJSONObject(i);
                        int playscore = obj.getInt("_sumPlayScore");
                        int signscore = obj.getInt("_sumSignScore");
                        String createDate = obj.getString("createdAt");
                        String game = obj.getString("game");
                        showToast("游戏总得分：" + playscore + ",签到得分："
                                + signscore + ",时间:" + createDate+",game:"+game);
                    }
                } catch (JSONException e1) {
                    e1.printStackTrace();
                }
            } else {
                showToast("查询成功，无数据");
            }
        }else{
            loge(e);
        }
    }
});

有时候，我们需要知道分组统计时每个分组有多少条记录，可使用setHasGroupCount（true）,如下：

// 查询创建时间按天统计所有玩家的得分和每一天有多少条玩家的得分记录，并按时间降序:
BmobQuery<GameScore> query = new BmobQuery<GameScore>();
query.sum(new String[] { "playScore" });    // 统计总得分
query.groupby(new String[] { "createdAt" });// 按照时间分组
query.order("-createdAt");                  // 降序排列
query.setHasGroupCount(true);              // 统计每一天有多少个玩家的得分记录，默认不返回分组个数
query.findStatistics(GameScore.class,new QueryListener<JSONArray>() {
    @Override
    public void done(JSONArray ary, BmobException e) {
        if(e==null){
            if (ary!=null) {
                int length = ary.length();
                try {
                    for (int i = 0; i < length; i++) {
                        JSONObject obj = ary.getJSONObject(i);
                        int playscore = obj.getInt("_sumPlayScore");
                        String createDate = obj.getString("createdAt");
                        int count = obj.getInt("_count");//setHasGroupCount设置为true时，返回的结果中含有"_count"字段
                        showToast("游戏总得分：" + playscore + ",总共统计了"
                                + count + "条记录,统计时间 = "+ createDate);
                    }
                } catch (JSONException e1) {
                    e1.printStackTrace();
                }
            } else {
                showToast("查询成功，无数据");
            }
        }else{
            loge(e);
        }
    }
});

添加过滤条件

如果需要对分组计算后的结果再进行过滤，可使用having来继续过滤部分结果。

//我们按游戏名统计所有玩家的总得分，并只返回总得分大于100的记录，并按时间降序
BmobQuery<GameScore> query = new BmobQuery<GameScore>();
query.sum(new String[] {"playScore"});//计算总得分数
query.groupby(new String[] {"game"});//分组条件：按游戏名进行分组
query.order("-createdAt");// 降序排列
HashMap<String, Object> map = new HashMap<String, Object>();
JSONObject js = new JSONObject();
try {
    js.put("$gt", 100);
} catch (JSONException e1) {
}
map.put("_sumPlayScore", js);//过滤条件：总得分数大于100
query.having(map);
query.setLimit(100);
query.findStatistics(GameScore.class,new QueryListener<JSONArray>() {
    @Override
    public void done(JSONArray ary, BmobException e) {
        if(e==null){
            if(ary!=null){
                int length = ary.length();
                try {
                    for (int i = 0; i < length; i++) {
                        JSONObject obj = ary.getJSONObject(i);
                        int playscore = obj.getInt("_sumPlayScore");//过滤条件的key是什么，返回的数据中就有什么
                        String game = obj.getString("game");//返回的数据中同样包含groupby里面的列名
                        showToast("游戏得分：" + playscore + ",游戏名 = "+ game);
                    }
                } catch (JSONException e1) {
                    e1.printStackTrace();
                }
            } else {
                showToast("查询成功，无数据");
            }
        }else{
            loge(e);
        }
    }
});

缓存查询

缓存查询通常是将查询结果缓存在磁盘上。
当用户的设备处于离线状态时，就可以从缓存中获取数据来显示。
或者在应用界面刚刚启动，从网络获取数据还未得到结果时，先使用缓存数据来显示。
这样可以让用户不必在按下某个按钮后进行枯燥的等待。
默认的查询操作是没有启用缓存的，开发者可以使用setCachePolicy方法来启用缓存功能。
例如：优先从缓存获取数据，如果获取失败再从网络获取数据。

bmobQuery.setCachePolicy(CachePolicy.CACHE_ELSE_NETWORK);    // 先从缓存获取数据，如果没有，再从网络获取。
bmobQuery.findObjects(new FindListener<Person>() {
    @Override
    public void done(List<Person> object,BmobException e) {
        if(e==null){
            toast("查询成功：共"+object.size()+"条数据。");
        }else{
            toast("查询失败："+msg);
        }
    }
});

缓存策略

Bmob SDK提供了几种不同的缓存策略，以适应不同应用场景的需求：

• IGNORE_CACHE :只从网络获取数据，且不会将数据缓存在本地，这是默认的缓存策略。
• CACHE_ONLY :只从缓存读取数据，如果缓存没有数据会导致一个BmobException,可以忽略不处理这个BmobException.
• NETWORK_ONLY :只从网络获取数据，同时会在本地缓存数据。
• NETWORK_ELSE_CACHE:先从网络读取数据，如果没有，再从缓存中获取。
• CACHE_ELSE_NETWORK:先从缓存读取数据，如果没有，再从网络获取。
• CACHE_THEN_NETWORK:先从缓存取数据，无论结果如何都会再次从网络获取数据。也就是说会产生2次调用。

建议的做法：
第一次进入应用的时候，设置其查询的缓存策略为CACHE_ELSE_NETWORK,当用户执行上拉或者下拉刷新操作时，设置查询的缓存策略为NETWORK_ELSE_CACHE。

缓存方法

如果需要操作缓存内容，可以使用BmobQuery提供的方法做如下操作：

• 检查是否存在当前查询条件的缓存数据

boolean isInCache = query.hasCachedResult(Class<?> clazz);

注：缓存和查询条件有关，此方法必须放在所有的查询条件（where、limit、order、skip、include等）都设置完之后，否则会得不到缓存数据。

• 清除当前查询的缓存数据

query.clearCachedResult(Class<?> clazz);

• 清除所有查询结果的缓存数据

BmobQuery.clearAllCachedResults(Class<?> clazz);

• 设置缓存的最长时间（以毫秒为单位）

query.setMaxCacheAge(TimeUnit.DAYS.toMillis(1));//此表示缓存一天

示例如下：

BmobQuery<Person> query     = new BmobQuery<Person>();
query.addWhereEqualTo("age", 25);
query.setLimit(10);
query.order("createdAt");
//判断是否有缓存，该方法必须放在查询条件（如果有的话）都设置完之后再来调用才有效，就像这里一样。
boolean isCache = query.hasCachedResult(Person.class);
if(isCache){--此为举个例子，并不一定按这种方式来设置缓存策略
    query.setCachePolicy(CachePolicy.CACHE_ELSE_NETWORK);    // 如果有缓存的话，则设置策略为CACHE_ELSE_NETWORK
}else{
    query.setCachePolicy(CachePolicy.NETWORK_ELSE_CACHE);    // 如果没有缓存的话，则设置策略为NETWORK_ELSE_CACHE
}
query.findObjects(new FindListener<Person>() {
    @Override
    public void done(List<Person> object,BmobException e) {
        if(e==null){
            toast("查询成功：共"+object.size()+"条数据。");
        }else{
            toast("查询失败："+msg);
        }
    }
});

注：

1、只有当缓存查询的条件一模一样时才会获取到缓存到本地的缓存数据。

2、设置的默认的最大缓存时长为5小时。

BQL查询

Bmob Query Language（简称 BQL） 是 Bmob 自 BmobSDKV3.3.7 版本开始，为查询 API 定制的一套类似 SQL 查询语法的子集和变种，主要目的是降低大家学习 Bmob 查询API 的成本，可以使用传统的 SQL 语法来查询 Bmob 应用内的数据。

具体的 BQL 语法，请参考 Bmob Query Language 详细指南。

基本BQL查询

可以通过以下方法来进行SQL查询：
例如：需要查询所有的游戏得分记录

String bql ="select * from GameScore";//查询所有的游戏得分记录
new BmobQuery<GameScore>().doSQLQuery(bql,new SQLQueryListener<GameScore>(){
    @Override
    public void done(BmobQueryResult<GameScore> result, BmobException e) {
        if(e ==null){
            List<GameScore> list = (List<GameScore>) result.getResults();
            if(list!=null && list.size()>0){
                ...
            }else{
                Log.i("smile", "查询成功，无数据返回");
            }
        }else{
            Log.i("smile", "错误码："+e.getErrorCode()+"，错误描述："+e.getMessage());
        }
    }
});