bugumongo

对象-文档映射

在对象(Object，也称实体Entity)、文档(Document)之间实现自动转换，是BuguMongo的最核心功能，这能让你直接用面向对象的概念来操作MongoDB数据库，而不用去关心底层的数据库细节。

在这方面，BuguMongo提供了：

8个注解：@Entity、@Id、@Property、@Embed、@EmbedList、@Ref、@RefList、@Ignore

1个接口：BuguEntity

BuguEntity接口

要使得某个Java Entity能和MongoDB Document实现相互转换，该Entity需要实现BuguEntity接口，该接口中有2个方法，如下：

public void setId(String id); 
     public String getId();

注解

先看一段示例代码：

import com.bugull.mongo.BuguEntity; import com.bugull.mongo.annotations.Entity; import com.bugull.mongo.annotations.Id; import com.bugull.mongo.annotations.Property; import com.bugull.mongo.annotations.Embed; import com.bugull.mongo.annotations.EmbedList; import com.bugull.mongo.annotations.Ref; import com.bugull.mongo.annotations.RefList; import java.util.List; 
 @Entity public class Foo implements BuguEntity{ 
    @Id 
    private String id; 
    private String name; 
    @Property 
    private int level; 
    @Embed  
    private EmbedFoo embed; 
    @EmbedList 
    private List<EmbedFoo> embedList; 
    @Ref 
    private FatherFoo father; 
    @RefList 
    private List<ChildFoo> children; 
    @Ignore  
    private double sumScore; 
 
    @Override 
    public String getId() { 
        return id; 
    } 
 
    @Override 
    public void setId(String id) { 
        this.id = id; 
    } 
 
    ...other getter and setter... 
 } 
 public class EmbedFoo { 
    private float x; 
    private int y; 
    ...getter and setter } 
 @Entity(name="father") public class FatherFoo implements BuguEntity{ 
    @Id 
    private String id; 
    private Date date; 
    @Ref 
    private FatherFoo father; 
    ...getter and setter... } 
 @Entity(name="child") public class ChildFoo implements BuguEntity{ 
    @Id 
    private String id; 
    private List<String> list; 
    ...getter and setter... }

各个注解的含义如下：

@Entity

表示需要映射到MongoDB中的一个实体。该注解有3个属性：

name——String型，表示其在MongoDB中的collection的名称。name属性可以省略，默认使用类名的全小写。

capped——boolean型，表示该Entity类对应的是Capped Collection，缺省值为false。

capSize——long型，设置Capped Collection的大小，缺省值为10M（10L*1024L*1024L）。

提示：使用@Entity注解的类，必须实现BuguEntity接口。

@Id

映射到MongoDB中的"id"，必须为String类型。

用@Id注解的属性，在MongoDB数据库中，被保存成为一个ObjectId对象，形式如："id" : ObjectId("4eb8beeaeaad0a390144f084")

@Property

该注解可以省略。它用来映射基本数据类型，包括：String、int、long、short、float、double、boolean、char、Date、Timestamp等，以及这些基本数据类型组成的数组、List、Set、Map。

@Property有2个属性：

name——String型，用于指定映射到MongoDB collection中某个field。属性name可以省略，表示采用与Entity的Field相同的名称。

lazy——Boolean型，含义是：取出该实体的列表时，是否取出该field值。如果为true，标识不取出。默认值为false。

对lazy属性的详细讲解，请查看lazy和cascade属性

@Ignore

表示该属性不需要被映射。当保存实体时，该属性不会保存至MongoDB；同样，该属性也不会从MongoDB中取出。

@Embed

表示该属性是一个嵌入的对象。嵌入对象（如EmbedFoo）只是一个普通的POJO，不需要@Entity注解，不需要实现BuguEntity接口，也不需要有@Id。

跟@Property一样，@Embed也有2个属性：name、lazy，含义也是一样的。

嵌入对象的属性，可以用点号“.”来引用，例如查询：

FooDao dao = ... List list = dao.query().is("embed.x", 3.14F).results();  //查询出全部embed.x=3.14的Foo对象

@EmbedList

表示该属性是一组嵌入的对象。

@EmbedList注解支持数组、java.util.List、java.util.Set、java.util.Map，但都必须使用泛型。当使用Map的时候，嵌入对象只能作为Map的value，而不能作为key。

跟@Property一样，@EmbedList也有2个属性：name、lazy，含义也是一样的。

@Ref

表示对另一个对象的引用，在MongoDB中保存的是形如"father" : {"$ref" : "father", "$id" : ObjectId("4dcb4d1d3febc6503e4e5933")}这样的一个DBRef。

@Ref有2个属性：

name——含义与@Property的参数name一样。

cascade——String型，用于指定关联操作。其值可以是C、R、U、D四个字符中的任意一个或多个字符组成。如：cascade="CRUD", cascade="CD", cascade="CR"等等。

C、R、U、D四个字符分别代表的含义如下：

C——Create，创建

R——Retrieve，检索、读取

U——Update，修改、更新

D——Delete，删除

对cascade属性的详细讲解，请查看lazy和cascade属性

@RefList

表示对另一个对象的引用的集合。

@RefList注解支持数组、java.util.List、java.util.Set、java.util.Map，但都必须使用泛型。当使用Map的时候，引用对象只能作为Map的value，而不能作为key。

@RefList有3个属性：

name——含义与@Property的属性name一样。

cascade——含义与@Ref的属性cascade一样。

sort——String型，用于关联取出该List或Set属性时使用的排序规则，其形式是："{'level':1}"，或"{'level':1, 'timestamp':-1}"这样的排序字符串。如果不排序，则不用设置sort值。

排序字符串

排序字符串可以采用标准的JSON格式，如：

@RefList(sort="{'level': -1}")

若有多个排序条件，中间用逗号（,）隔开：

@RefList(sort="{'level':1, 'timestamp':-1}")

也可以省略单引号，使用简化的JSON格式：

@RefList(sort="{level:1}") 
 @RefList(sort="{level:1, timestamp:-1}")

甚至连花括号也省略，简化成下面这样，也是支持的：

@RefList(sort="level:1") 
 @RefList(sort="level:1, timestamp:-1")