Blog

Lazy Properties and Property Observers in ColdBox 7

Michael Born July 05, 2023

Spread the word

Michael Born

July 05, 2023

Spread the word


Share your thoughts

ColdBox 7 is a big release for many reasons, but probably the most significant updates center around Wirebox, ColdBox's built-in dependency injection framework.

This article will focus on two smaller but still wildly useful new Wirebox features: Lazy Properties and Property Observers. With these new DI features, developers have access to speed boosts and automatic locking around object construction with lazy properties, better logging and debugging capabilities (among many other uses) with property observers, and much much more.

I personally believe delegation is the most significant new feature in Coldbox 7. But as Jon Clausen has already written an excellent post on ColdBox 7's new Delegates functionality, I will not be covering delegates here.

Lazy Properties

Lazy Properties, contrary to popular belief, are not "conducive to inactivity or indolence", but are wirebox properties that are configured to only inject or "build" the object once called. Since not every request may use the property, the app benefits from a speed gain as it does not need to waste time constructing dependencies that it does not need.

Let's look at an example. Here we have a ShoppingCart object which can store and check out cart items. This cart uses a PaymentProcessor to purchase the items when purchase() is called:

// ShoppingCart.cfc
component{
    property name="paymentProcessor";

    public component function init(){
        variables.paymentProcessor = new models.PaymentProcessor();
        return this;
    }

    public function purchase(){
        paymentProcessor.makePayment( getTotalCartPrice() )
    }

    // ...
}

This is all fine and good, but if the PaymentProcessor builds a payment connection or authentication upon creation, it is a fairly time-consuming object to create. This is egregious when we consider how many times this ShoppingCart will be rendered before the payment is made... if it is made at all.

To avoid the time cost of building the PaymentProcessor, then, we can use lazy properties to only build once the getter is called.

First, we need to add the lazy annotation to the property to inform Wirebox that we will be using a lazy constructor:

 property name="paymentProcessor" lazy;

Next, we need to move creation of the PaymentProcessor instance outside of the init() method and into a buildPaymentProcessor() method:

// painfully construct the payment processor
 private function buildPaymentProcessor(){
     return new models.PaymentProcessor();
 }

Note the method name is buildPaymentProcessor(), which matches the default build{propertyName} method name that Wirebox looks for when calling the builder method. If we wish to use a custom method name, we could set that in the property lazy annotation:

property name="paymentProcessor" lazy="setupPaymentProcessor";

private function setupPaymentProcessor(){
     return new models.PaymentProcessor();
 }

Finally, our direct reference to the property name (i.e. variables.paymentProcessor) needs to be replaced with a getter method call in order for Wirebox to call the property constructor:

 public function purchase(){
     getPaymentProcessor().makePayment( getTotalCartPrice() )
 }

Putting it all together, our minimal ShoppingCart component looks something like this:

// ShoppingCart.cfc
component{
    property name="paymentProcessor" lazy="setupPaymentProcessor";

    public component function init(){
        return this;
    }

    public function purchase(){
        getPaymentProcessor().makePayment( getTotalCartPrice() )
    }

    private function setupPaymentProcessor(){
        return new models.PaymentProcessor();
    }
}

By using ColdBox 7's lazy property syntax, usage of the ShoppingCart object does not need to wait for construction or validation of the PaymentProcessor object. This will make cart rendering or access quicker, while still keeping purchase logic in the cart object.

For more information on lazy properties, I highly recommend the Wirebox Lazy Properties reference documentation.

Property Observers

Property Observers, quite simply, are a means to observe value changes upon a component property.

Let's take our ShoppingCart example, and add a totalPrice property:

// ShoppingCart.cfc
component{
    property name="totalPrice" type="numeric";

    public component function init(){
        variables.totalPrice = 0;
        return this;
    }
}

With this syntax, developers can call cart.getTotalPrice() to see the total cost of all cart items.

But say we wish to log each time the total price changes.

We could do this within the addItem() method. However, the Separation of Concerns principle recommends we avoid co-locating one concern (debugging and logging) with another concern (the business logic of adding items to a cart). Thus, we can use property observers to note and log changes from a separate method, without cluttering our cart addition functionality.

First, we add the observed annotation to the totalPrice property declaration:

property name="totalPrice" observed;

This will instruct Wirebox to call totalPriceObserver() each time setTotalPrice() is called. (This method name follows the {propertyName}Observer syntax, i.e. totalPrice + Observer = totalPriceObserver().) So now we add our observer method:

function totalPriceObserver( newValue, oldValue, property ){
    log.info( "Cart price changed to #newValue#" );
}

We can now log each time the cart price changes! The real power, though, comes from a custom observer used for observing multiple properties simultaneously:

// ShoppingCart.cfc
component{
    property name="totalPrice" type="numeric" observed="cartObserver";
    property name="subtotal" type="numeric" observed="cartObserver";
    property name="user" type="struct" observed="cartObserver";

    public component function init(){
        variables.totalPrice = 0;
        variables.subtotal = 0;
        return this;
    }

    function cartObserver( newValue, oldValue, property ){
        log.info( "Cart #property# changed:", newValue );
    }
    // ...
}

Our cartObserver can now be used to log or track multiple types of cart changes to help drive better business decisions by knowing what the customers are spending on, or which items just sit in the cart, unpurchased. And that's money. 🤑

For more information on property observers, I highly recommend the excellent Wirebox documentation covering property observers.

Add Your Comment

Recent Entries

Unveiling the Future of CFML Development - 3rd Round of Sessions

Unveiling the Future of CFML Development - 3rd Round of Sessions

Welcome back to our journey into the future of CFML development! As excitement continues to build for Into the Box 2024, we're thrilled to bring you the latest updates on what promises to be a transformative event. Continuing our blog post series, let's delve deeper into the third wave of session releases and discover the key surprises awaiting attendees. Learn More

Maria Jose Herrera
Maria Jose Herrera
March 01, 2024
Elevate Your ColdBox Experience and Skills

Elevate Your ColdBox Experience and Skills

We're thrilled to announce a significant overhaul of our ColdBox training experience to ensure it's nothing short of extraordinary! We've listened closely to your feedback and made significant improvements geared towards transforming you into a ColdBox superhero. Learn What's New!

Maria Jose Herrera
Maria Jose Herrera
February 20, 2024
Ortus Redis Extension v3.3.0 Released!

Ortus Redis Extension v3.3.0 Released!

We are very excited to bring you another release for our Redis Lucee Extension. The most significant feature in this release is the addition of the `` and `redisLock{}` tag, which allows you perform a lock across all instances in a cluster.

Ortus Redis Extension v3.3.0 gives you greater control over concurrent modifications in a distributed environment, utilizing your distributed cache to prevent overlaps!

Jon Clausen
Jon Clausen
February 16, 2024