Lifecycle event model of PlayMorphia and Morphia

The content of this chapter is only valid for PlayMorphia v1.2.4 or later.

In this chapter we will explorer the lifecycle event model of PlayMorphia (start from v1.2.4) and Morphia.

Create events

PlayMorphia create events

Event implementation

Morphia create events

Morphia does not provide specific create events, however you could use PrePersist, PreSave and PostPerist to simulate create events and use this.isNew() to identify if current model instance is an new entity or existing entity. See Morphia update events for detail about PrePersist, PreSave and PostPerist events.

Update events

PlayMorphia update events

Event implementation

¹ see more about annotation based PlayMorphia lifecycle event handling

² see more about event handler based PlayMorphia lifecycle event handling

Morphia update events

Morphia annotation enable you do define methods that accept parameters and return result. Click here for examples.

Load events

PlayMorphia load events

OnLoad event is seldom used as when this event triggered, the entity is still empty and waiting for the fields to be filled

Event implementation

Morphia load events

Delete events

PlayMorphia delete events

Event implementation

Morphia delete events

Morphia does not support delete events

Batch delete events

PlayMorphia batch delete events

Event implementation

Morphia batch delete events

Morphia does not support batch delete events

Additional notes

PlayMorphia annotated lifecycle event handler signature

No return object and method parameters should be defined for the following annotation based event handler: @OnLoad, @Loaded, @OnAdd, @Added, @OnUpdate, @Updated, @OnDelete, @Deleted:

@Entity MyMode extends Model {
    // correct signature 
    @OnLoad void onLoad() {}
    @Loaded void loaded() {}
    @OnAdd void onAdd() {}
    @Added void added() {}
    @OnUpdate void onUpdate() {}
    @Updated void updated() {}
    @OnDelete void onDelete() {}
    @Deleted void deleted() {}
    // the following method's signatures are not correct and they will not be triggered at all
    @OnLoad Model myOnLoad() {...}
    @Loaded void myLoaded(String xx) {...}
    @OnAdd String myOnAdd(Model xx) {...}
}

You could make those methods static or non-static, but it’s highly recommend to use non-static methods for the above event handling as you get the access to the entity which is experiencing the lifecycle events via “this” pointer.

There is completely no requirements on method scope, you can make it either one of “public”, “protected”, “private” or default package level, the functionality will not impact by changing the method scope.

Unlike the above events, the two batch events (@OnBatchDelete and @BatchDeleted) have a bit different method signature:

@Entity MyModel extends Model {
    @OnBatchDelete static void onBatchDelete(MorphiaQuery q) {...}
    @BatchDeleted static void BatchDeleted(MorphiaQuery q) {...}
}

As you could see, we have 2 differences in the batch event handler definition compare to that of the other event handlers:

1. A MorphiaQuery type parameter is required. This is mandatory, otherwise your method will not be called when the batch delete event triggered.
2. the batch event handling methods are defined as static methods. This is optional but recommended practice.

There are different method signature requirements when you are writing Morphia annotation marked lifecycle event handlers, please refer to this page for detail.

More on BatchDeleted event

A common error is to use the MorphiaQuery argument passed into BatchDeleted event handler to query for which models has been deleted. However that will always return an empty list as all those entities has been removed from MongoDB already. One way to get the deleted entities is to remember them in the OnBatchDelete event handler:

@Entity MyModel extends Model {
    private Map<MorphiaQuery, List<MyModel>> deleteModels_ = new HashMap<MorphiaQuery, List<MyModel>>();
    @OnBatchDelete static void onBatchDelete(MorphiaQuery q) {
        List<MyModel> list = q.asList();
        deleteModels_.put(q, list);
    }
    @BatchDeleted static void batchDeleted(MorphiaQuery q) {
        List<MyModel> list = deleteModels_.get(q);
        // do whatever you want on the deleted models
        ...
    }
}

Why do you prefer PlayMorphia event handling framework to Morphia one

1. More clear. PlayMorphia events distiguish between add (new) and update (existing) entities while Morphia events don’t
2. Performance. There are very little performance gain if you choose PlayMorphia event handling model. PlayMorphia code enhancer will burn the relevant code into final byte code so at runtime there is no reflection at all. While Morphia needs one time reflection for event handler call and then cache it to hash map for later on calls.
3. More complete. PlayMorphia support delete and batch delete events while Mophia doesn’t.

Performance consideration

You are NOT required to do the same thing as shown in the above code. Calling to the event handler methods is executed in the current thread, the more logic you put into the event handlers the more performance is impact. So please do as simple as possible in any of the event handlers. Implement only the logic you need. If you don’t need to bother with batch delete events then you shouldn’t add batch delete event handler. Actually in most cases you don’t need to implement any lifecycle event handlers. This is ture for both PlayMorphia and Morphia event handling model.

See also

1. Lifecycle handling introduction
2. PlayMorphia model introduction
3. Use of PlayMorphia model: crud