快速开始：
@Entity
public class Hotel {
@Id private ObjectId id;
private String name;
private int stars;
@Embedded
private Address address;
}
@Embedded
public class Address {
private String street;
private String city;
private String postCode;
private String country;
}
main方法：
Mongo mongo=new Mongo();
Morphia morphia = new Morphia();
morphia.map(Hotel.class).map(Address.class);
Datastore ds = morphia.createDatastore(mongo, "my_database");
//保存
ds.save(hotelToSave);
//查询四星级酒店
//List<Hotel> fourStarHotels = ds.find(Hotel.class, "stars >=", 4).asList();
List<Hotel> fourStarHotels = ds.find(Hotel.class).field("stars").greaterThanOrEq(4).asList();
-------------------------------------------------
Datastore创建后index和capped collections的初始化：
ds.ensureIndexes(); ///creates all defined with @Indexed
ds.ensureCaps(); //creates all collections for @Entity(cap=@CappedAt(...))
这两个方法应该在你把实体注册到morphia之后(morphia.map(Hotel.class).map(Address.class))来调用，它默认会同步的创建index和capped collections，这可以在每次系统启动时确保索引存在(包括第一次运行的时候)。
查询一条记录：
MyEntity e = ds.find(MyEntity.class).get(); //get the first one by type
MyEntity e = ds.find(MyEntity.class).field("name").equal("someName").get(); //get the first one where name = "someName"
-------------------------------------------------
Datastore接口介绍：
-------------------------
get方法：其实就是find方法的快捷方式，根据ID返回一个实体，或者返回null。
Hotel hotel = ds.get(Hotel.class, hotelId);
-------------------------
find方法：会返回一个Query对象，支持迭代器和QueryResults接口。
//use in a loop
for(Hotel hotel : ds.find(Hotel.class, "stars >", 3))
print(hotel);
//get back as a list
List<Hotel> hotels = ds.find(Hotel.class, "stars >", 3).asList();
//sort the results
List<Hotel> hotels = ds.find(Hotel.class, "stars >", 3).sort("-stars").asList();
//get the first matching hotel, by querying with a limit(1)
Hotel gsHotel = ds.find(Hotel.class, "name", "Grand Sierra").get();
//same as
Hotel gsHotel = ds.find(Hotel.class, "name =", "Grand Sierra").get();
可用的操作符列表： ["=", "==","!=", "<>", ">", "<", ">=", "<=", "in", "nin", "all", "size", "exists"]
-------------------------
save方法：
Hotel hotel = new Hotel();
ds.save(hotel);
//@Id field is filled in for you (after the save), if you didn't set it.
ObjectId id = hotel.getId();
-------------------------
delete方法：根据一个ID或者查询对象来删除
ds.delete(Hotel.class, "Grand Sierra Resort");
//use a query
ds.delete(ds.createQuery(Hotel.class).filter("pendingDelete", true));
-------------------------
FindAndDelete方法：删除并返回记录的原子操作
Hotel grandSierra = ds.findAndDelete(ds.get(Hotel.class, "Grand Sierra Resort"));
-------------------------
Update方法：更新部分信息时比整体save一次要高效的多，例如更新用户的最后登录时间：
@Entity
class User
{
@Id private ObjectId id;
private long lastLogin;
//... other members
private Query<User> queryToFindMe()
{
return datastore.createQuery(User.class).field(Mapper.ID_KEY).equal(id);
}
public void loggedIn()
{
long now = System.currentTimeMillis();
UpdateOperations<User> ops = datastore.createUpdateOperations(User.class).set("lastLogin", now);
ds.update(queryToFindMe(), ops);
lastLogin = now;
}
}
有关update方法的更多高级操作：
http://code.google.com/p/morphia/wiki/Updating
-------------------------------------------------
Query接口介绍：
可以添加查询条件，排序，限定返回结果条数和位置。实现了QueryResults接口。
-------------------------
Filter方法：
Query q = ds.createQuery(MyEntity.class).filter("foo >", 12);
第一个参数是属性名和比较符，第二个参数是比较值。
多个fileter直接的关系是“与(and)”
Query q = ds.createQuery(MyEntity.class).filter("foo >", 12).filter("foo <", 30);
可用操作符列表：
["=", "==","!=", "<>", ">", "<", ">=", "<=", "in", "nin", "all", "size", "exists"]
-------------------------
Fluent接口：
与Fileter接口差不多，英文呢方法名，更符合使用习惯：
Query q = ds.createQuery(MyEntity.class).field("foo").equal(1);
可用方法列表：
[exists,doesNotExist,greaterThan,greaterThanOrEq,lessThan,lessThanOrEq,equal,notEqual,hasThisOne,hasAllOf,hasAnyOf,hasNoneOf,hasThisElement,sizeEq]
使用Fluent接口，可以使用or条件：
Query<Person> q = ad.createQuery(Person.class);
q.or(
q.criteria("firstName").equal("scott"),
q.criteria("lastName").equal("scott")
);
-------------------------
Geo-spatial：mongoDB的地理位置操作
-------------------------
Fields方法：
类似与mongo本身的query，可以用“点号”指定属性。
Query q = ds.createQuery(Person.class).field("addresses.city").equal("San Francisco");
//or with filter, or with this helper method
Query q = ds.find(Person.class, "addresses.city", "San Francisco");
-------------------------
Validation：如果查询时属性名找不到，则会抛出异常。如果用到“点号”指定属性，则表达式每一部分都必须匹配类的结构图。
如果服务器可以强制转换数据，则数据类型的错误会被作为警告记录下来。
上述校验特性可以在任何一个查询或查询的一部分处被关闭：
Query q = ds.createQuery(MyEntity.class).disableValidation();
//or it can be disabled for just one filter
Query q = ds.createQuery(MyEntity.class).disableValidation().filter("someOldField", value).enableValidation().filter("realField", otherVal);
-------------------------
Sort方法：排序
Query q = ds.createQuery(MyEntity.class).filter("foo >", 12).order("dateAdded");
... // desc order
Query q = ds.createQuery(MyEntity.class).filter("foo >", 12).order("-dateAdded");
... // asc dateAdded, desc foo
Query q = ds.createQuery(MyEntity.class).filter("foo >", 12).order("dateAdded, -foo");
-------------------------
Limit方法：
Query q = ds.createQuery(MyEntity.class).filter("foo >", 12).limit(100);
-------------------------
offset(skip)方法：要求服务器跳过一部分记录，这么做效率不如使用一些属性的range filter，比如pagination。
Query q = ds.createQuery(MyEntity.class).filter("foo >", 12).offset(1000);
-------------------------
只返回指定的属性：这么做会导致不完整的对象，小心使用。
MyEntity e = ds.createQuery(MyEntity.class).retrievedFields(true, "foo").get();
val = e.getFoo(); // 仅返回这个字段
MyEntity e = ds.createQuery(MyEntity.class).retrievedFields(false, "foo").get();
val = e.getFoo(); // 仅不返回这个字段
指定字段名的参数可以是字符串list或者数组：
MyEntity e = ds.createQuery(MyEntity.class).retrievedFields(true, "foo", "bar").get();
-------------------------
取数据：
使用QueryResults接口的方法即可取到数据，这些方法不会影响Query对象本身（返回的是副本），所以可以反复调用。
get() 使用limit(1)，返回一条记录
asList() 返回所有记录，大数据量时可能较慢
fetch() 明确要求返回一个可迭代的对象
asKeyList() 返回记录的Key<T>，只从server取id字段
fetchEmptyEntities() 与fetch类似，但只取id字段
Query q = ds.createQuery(MyEntity.class).filter("foo >", 12);
MyEntity e = q.get();
e = q.sort("foo").get();
for (MyEntity e : q) print(e);
List<MyEntity> entities = q.asList();
-------------------------------------------------
生命周期方法注解：
@PrePersist - 在save之前调用，可以返回一个DBObject以替代一个空值
@PostPersist - 在save之后调用
@PreLoad - 在将数据映射到POJO之前调用，DBObject作为参数传入，你可以手动修改其中的值
@PostLoad - 在将数据映射到POJO之后调用
测试类例子：
http://code.google.com/p/morphia/source/browse/trunk/morphia/src/test/java/com/google/code/morphia/TestDatastore.java
//这个例子保存前将最后登录时间更新为当前时间
class BankAccount {
@Id String id;
Date lastUpdated = new Date();
@PrePersist void prePersist() {lastUpdated = new Date();}
}
下面的这个例子中，通过EntityListerners注解，将生命周期事件的实现放到外部类当中：
@EntityListeners(BackAccountWatcher.class)
class BankAccount {
@Id String id;
Date lastUpdated = new Date();
}
class BankAccountWatcher{
@PrePersist void prePersist(BankAccount act) {act.lastUpdated = new Date();}
}
注意：没有delete操作相关的生命周期事件。
-------------------------------------------------
类注解：
-------------------------
@Entity
标记一个要被映射的类。此注解为可选，一般写上没坏处。
@Entity("collectionName")
指定对应的collection的名称，这种情况POJO里必须有无参构造方法
@Entity(noClassnameStored = true)
注解不要存储类名。
默认是存储类名的，因为可以把不同的类(特别是相互继承的类)存入同一个collection,例如：
@Entity("animals") abstract class Animal { String name; }
@Entity("animals") Cat extends Animal { ... }
@Entity("animals") Dog extends Animal { ... }
@Entity(cap = @CappedAt(...)) 指定为Capped
-------------------------
@Indexes 索引注解可以标记在类上，这样就可以建立多列索引
@Entity
@Indexes( @Index("user, -date") )
public class ChangeLog{
Date date;
String user;
Record changedRecord;
}
注："date"前面的负号表示日期降序排列，便于查找最近的用户
还可以添加多个多列索引：
@Indexes({
@Index("user, -cs"),
@Index("changedRecord, -cs")})
注：也可以(但不建议)在这里定义单列索引，但最好还是注解在具体的列上
-------------------------------------------------
字段注解：
-------------------------
@Id 标记字段为数据库主键
POJO里的对应字段可以是任意支持持久化的类型，例如int,uuid,Object
使用ObjectId可以实现自动生成，否则在每次存储前需要指定此值
-------------------------
@Indexed 注解索引
每次调用datastore.ensureIndexes()时，这些索引就会被应用。
注：如果在一个已经存在数据和索引的系统上，调用datastore.ensureIndexes()方法，将不会产生任何操作，所以可以放心的调用。
@Indexed(value=IndexDirection.ASC, name="upc", unique=true, dropDups=true)
value：索引方向，默认是IndexDirection.ASC，还可以是IndexDirection.DESC和IndexDirection.BOTH
name：索引名，默认是mongoDB自动生成
unique：是否唯一索引，默认为flase
dropDups：通知唯一索引静默删除已有的重复元素，只保留第一个，默认为false
-------------------------
@Embedded 注解需要嵌入的对象(形成一个对象树来读取/写入)
被嵌入的对象将嵌套在父对象里，被存入同一个collection中，所以被嵌入的对象里不允许出现@Id注解。
也可以指定被嵌入对象在mongoDB里的属性名：
@Embedded("blog_comments")
-------------------------
@Property POJO属性注解
在POJO中，java原生类型和基本类型默认是不需要注解即可完成读取和写入的(除非注解了@Transient)。
mongoDB只支持四种数据类型：Integer，Long，Double，String
morphia会自动映射java基本数据类型和String，这些类型的数组，以及List,Set,Map到mongoDB中。
另外，以下对象也会被自动转换和读取/写入：
enum 转为String存储
java.util.Date 转为毫秒数存储
java.util.Locale 转为String存储
com.mongodb.DBRef
com.mongodb.ObjectId
注：morphia默认使用POJO属性名作为collection里的字段名，这个行为可以被覆盖：
@Property("my_integer")
private int myInt;
-------------------------
@Reference 引用注解，标记某一个字段存在另一个collection中。
该注解有三种属性：
lazy：懒汉模式，被调用时才从数据库获取此字段
ignoreMissing：读取引用失败时不产生异常
concreteClass：产生的实例的类类型
例子：
@Entity public class BlogEntry { @Id private ObjectId id; @Reference private Author author;}
@Entity public class Author { @Id private ObjectId id;}
注：被引用的对象必须存在于mongoDB中，然后才能存储引用其的对象。
注：morphia默认使用POJO里引用的属性名作为collection里的字段名，这个行为可以被覆盖：
@Reference("blog_authors")
private List<Author> authors;
-------------------------
集合类相关的属性注解：
morphia支持Collection（List,Set,Map）：
private Set<String> tags;
private Map<String,Translation> translations;
@Reference private List<Article> relatedArticles;
默认情况下，morphia读取数据创建实例时会使用以下实现类：
java.util.ArrayList
java.util.HashSet
java.util.HashMap
这个行为可以被覆盖：
@Property(concreteClass = java.util.TreeSet.class)
private Set<String> tags;
@Embedded(concreteClass = java.util.TreeMap.class)
private Map<String,Translation> translations;
@Reference(concreteClass = java.util.Vector.class)
private List<Article> relatedArticles;
-------------------------
@Transient 标记字段被忽略，包括读取/写入
@Serialized 字段被转为二进制后储存
@NotSaved 字段可以被读取，但在写入时忽略
@AlsoLoad 字段可以被任何支持的名字所读取
@Version 版本号标记，自动实现乐观锁，标记后修改操作时可能会抛出ConcurrentModificationException
-------------------------------------------------
Morphia的扩展：
-------------------------
校验扩展ValidationExtension：
符合JSR303，可以直接调用Hibernate validation。
对JSR303 API的轻量级的包装：new ValidationExtension(morphia);
import org.hibernate.validator.constraints.Email;
@Entity
public class Userlike {
@Id ObjectId id;
@Email String email;
}
-------------------------
日志重定向扩展：SLF4JExtension
将morphia的运行日志重定向到SLF4J中，引入morphia-logging-slf4j-0.99.jar，在系统启动时执行一次：
MorphiaLoggerFactory.registerLogger(SLF4JLoggerImplFactory.class);
-------------------------------------------------
手动映射对象到DBObjects（以便传递给底层的driver）：
-------------------------
创建Morphia实例（建议只创建一次，然后重用它）：
Morphia morphia = new Morphia();
morphia.map(BlogEntry.class).map(Author.class);
每一个这样手动映射的类都会被检查，如果失败会抛出MappingException。
也可以让morphia自动扫描某个包，并自动映射：
morphia.mapPackage("my.package.with.only.mongo.entities");
-------------------------
高级使用：从morphia里直接调用底层的java driver存储数据(手动)：
Morphia morphia = ...;
Mongo mongo = ...;
DB db = mongo.getDB("BlogSite");
//这是注解过的POJO
BlogEntry blogEntry = ...;
//让morphia将POJO转为java driver需要的DBObject
DBObject blogEntryDbObj = morphia.toDBObject(blogEntry);
//用java driver将其写入mongodb
db.getCollection("BlogEntries").save(blogEntryDbObj);
-------------------------
高级使用：从morphia里直接调用底层的java driver读取数据(手动)：
Morphia morphia = ...;
Mongo mongo = ...;
DB db = mongo.getDB("BlogSite");
//要读取的ID
String blogEntryId = ...;
//调用java driver从mongdoDB取出一个DBObject
BasicDBObject blogEntryDbObj = (BasicDBObject) db.getCollection("BlogEntries").findOne(new BasicDBObject("_id", new ObjectId(blogEntryId));
//让morphia将DBObject转为POJO
BlogEntry blogEntry = morphia.fromDBObject(BlogEntry.class, blogEntryDbObj);
-------------------------------------------------
DAO层的封装：
morphia已经提供了一个DAO接口和一个BasicDAO类。
我们只要继承BasicDAO类，覆盖其中的构造方法，将mongo和morphia对象传入即可：
public class BlogEntryDAO extends BasicDAO<BlogEntry, ObjectId> {
public BlogEntryDAO( Morphia morphia, Mongo mongo,String dbName) {
super(mongo, morphia, dbName);
}
}
然后就可以实现大部分操作：
BlogEntryDAO blogEntryDAO = new BlogEntryDAO(...);
ObjectId blogEntryId = ...;
BlogEntry myBlogEntry = blogEntryDAO.get(blogEntryId);//查询
myBlogEntry.setTitle("My Blog Entry");
blogEntryDAO.save(myBlogEntry);//保存
blogEntryDAO.deleteById(myBlogEntry.getId());//删除
然后还需要自定义一些查询方法（注意这里用了正则匹配文章标题）：
public List<BlogEntry> findByTitle( String title ) {
Pattern regExp = Pattern.compile(title + ".*", Pattern.CASE_INSENSITIVE);
return ds.find(entityClazz).filter("title", regExp).sort("title").asList();
}
星游注：话说，加入DAO层不就是为了与morphia解耦么？现在DAO层的父类本身就在morphia包里，“这不科学呀。。。”
建议参照其BasicDAO，自己写一个，这才实现了与持久层解耦：
http://code.google.com/p/morphia/source/browse/trunk/morphia/src/main/java/com/google/code/morphia/dao/BasicDAO.java