Should Service Layer methods expect instances or id's?

Question

This question arised from my work on a Grails application, but it applies to pretty much every web application developed in layers. Here's a simple example:

class OrderService {

    // Option 1
    def shipOrder(Order order) {
        order.status = OrderStatus.SHIPPED
        emailService.sendShipmentEmail(order)
        // ...
    }

    // Option 2
    def shipOrder(long orderId) {
        def order = Order.get(orderId)
        order.status = OrderStatus.SHIPPED
        emailService.sendShipmentEmail(order)
        // ...
    }

}

Is any of these options documented as being better than the other one?

Answer 1

I tend to prefer ids, since you sometimes want to use pessimistic locking, and then it's easy to change Order.get(orderId) to Order.lock(orderId). Locking has to happen in a transaction, so using the first approach you'd lock after reading, running the small risk of update in-between.

Sometimes it's necessary to load the instance outside of the service, e.g. to test for existence in the controller, so the second approach can feel like it wastes a database call. But you can change the get() call to an exists() call and only check for the existence of the id, rather than loading the entire instance just to see if it's there.

Note that you should use long orderId in your method signature since allowing a null id doesn't make sense.