Service models are used to specify when a service point should be instantiated. There are five pre-defined service models, and you can easily define more yourself should you need them.

The service model for a service point is specified using the model attribute in the service point definition. This attribute is optional, defaulting to singleton-deferred, but if given it must refer to either one of the five standard service models, or to a custom service model you have defined.

The five standard service models are:

Using one of the “deferred” service models (prototype-deferred, singleton-deferred, or threaded) can be very useful, but there are side-effects that you ought to be aware of. Otherwise, you may spend a lot of time debugging some difficult-to-track-down problems.

In particular, it is important to keep in mind that the service is not actually instantiated until a method is invoked on it. This means that if the service’s initialization routine raises an error, the exception will not occur where the reference to the service was obtained, but will occur where the method call was made. The service will also not have been properly instantiated, so if you try to inoke any of its methods again, you’ll get nil back every time.

For example, consider the following scenario.

Suppose you are writing a web-application framework, using Copland to modularize the various components. One of the services you create is a “page manager”, which will broker all requests for page objects. When an application needs a page, it queries the page manager, which will look up the page and return it.

You make the page manager service singleton-deferred.

Now, inside the controller for your architecture, you grab a reference to the page manager. (Note, however, that the object you are given is not the page manager—instead, it is a proxy object that will instantiate the page manager the first time a method is invoked on it.) Some time later you invoke #get_page on the page manager, which you expect to go grab a page object and return it.

However. What actually happens is this: the proxy object intercepts the method call and tries to instantiate the page manager service, since it hasn’t been instantiated yet. During the page manager initialization, however, something goes wrong. Perhaps one of the page classes doesn’t exist, or there is a syntax error in one of the files that the page manager needs to require. Whatever it is, the page manager cannot be initialized and an exception is thrown.

The controller code catches the exception.

Problem. Inside the rescue clause for the exception, the controller queries the page manager for the error page, so that it can display a coherent error to the client. However, since there was an error instantiating the page manager, future queries to the proxy object always return nil. This may result in an “undefined method `x’ for nil:NilClass” error down the road.

To avoid problems like this, you can do one of two things. One, you can use the singleton model, instead of singleton-deferred. This way, Copland will never deliver you a reference to a proxy. The other solution is to create a method in your class that always returns non-nil. Then, if it ever does return nil, you can be pretty sure that the service was not instantiated correctly. This, unfortunately, requires your code to know that the service was deferred.

Creating your own service models is very straight-forward. In general, all you need to do is create a class. The class should extend the Copland::Instantiator::Abstract class, and must override the instantiate method. The instantiate method should accept a no parameters. The method should then return an object that represents the instantiated service.

After creating the class, you need to register it with the Copland::ClassFactory class by calling it’s register method, passing the name to want for this new model, and a reference to the class that implements it.

To return a deferred version of the service, return a new instance of Copland::Instantiator::Proxy. The proxy’s constructor accepts a single parameter: the service point to instantiate.

To create a singleton service, the instantiate method should cache the new service, returning it (if it exists) instead of instantiating a new service.

Lastly, be aware that you may need to do some synchronization via mutexes to make your new service model thread-safe. Multiple threads could call it concurrently, which may cause problems if your model stores any state (as is the case with models that enforce a singleton model of service instantiation).

Here’s a brief example of a custom service model, pulled off the top of my head:

  class FiveMinuteServiceModel < Copland::Instantiator::Abstract
    CachedService = Struct.new( :service, :time )

    def initialize( point, definition )
      super
      @mutex = Mutex.new
      @service_cache = Hash.new
    end

    def instantiate
      @mutex.synchronize do
        svc = @service_cache[ point ]

        if svc.nil? || Time.now - svc.time > 300
          svc = CachedService.new( point.instantiate, Time.now )
          @service_cache[ point ] = svc
        end

        return svc.service
      end
    end

    register_as "custom.five-minutes" 
  end

This (contrived) example will result in a singleton-style model (non-deferred), which will instantiate the requested service point if it has been more than five minutes (300 seconds) since the point was last instantiated. It can be referenced in a service point definition under the model attribute, as “custom.five-minutes”.