6. Service Points

A service point is a definition of a service. It describes how and when the service should be instantiated, what parameters should be passed to it when it is created and what properties assigned, what other services it should listen to, and so forth. You could say that a service point is to a service, as a class is to an object. That is to say, a service point is simply a template for how a service should be created.

6.1. Descriptor Syntax

Every service point must be defined as part of the “service-points” section of a package descriptor. The id (or name) of the service point will be the key used in that section to reference it, and it may contain any character you wish except for a ”.”. Also, if you use any character that YAML treats specially (like commas, or colons), you’ll need to put the service name in quotes.

Whenever the name of a class is required (for a service, for instance), it must be in a particular format. The name of the class must be prefixed with the path that must be required (ie, the file that contains the class), followed by a forward slash (”/”), followed by the complete name of the class (including any modules that it is defined inside of). For example:

  some/special/service/MyServices::MyService

The above example indicates a class named MyService, defined inside of a module called MyServices, and which is contained in a file called some/special/service.rb.

The allowed attributes of a service point are:

description this (optional) attribute is useful for documentation purposes, but has no use at all inside Copland.
model This describes how (and when) the service will actually be instantiated. It must be either simple, simple-deferred, singleton, singleton-deferred, threaded, or pooled (or, if you’ve defined a custom service model, the name of that custom service model). If this attribute is not specified, it defaults to singleton-deferred. (See the chapter on “Service Models” for more information.)
implementor This describes how the service should be implemented. If the value of this attribute is a string, then it must be the name of the class to instantiate. (If the class includes the Singleton mixin, then the singleton instance will be returned; otherwise a new instance of the class will be created.) If this value is a map, then it may contain at the key factory. This must identify a factory service which will be used to create the new service. (If omitted, it defaults to copland.BuilderFactory.) In addition to the factory attribute, the hash should contain any other attributes required by the service factory that was specified. See the documentation for the corresponding service factory for a description of which attributes are available.
interceptors This must be an array of interceptor definitions, each of which is a hash. The only required key in each hash is service, which names the interceptor factory service to use when instantiating the corresponding interceptor. The other allowed attributes are before and after, which may be used to define the order in which the interceptors are applied. Besides those two attributes, some interceptors may allow additional attributes to be specified in order to configure them. See the documentation for those interceptors for more information.
schema This must be either a string or a hash. If it is a string, then it references another schema (either in this package or a different one). Otherwise, it’s format is described in more detail in the chapter “Schemas”. This is only needed by services that define service or interceptor factories.
listen-to This must be an array of service point names. If the referrenced service points are not defined in the same package as the current service point, their full names (including package) must be given, otherwise the package name may be omitted. Every time the current service point is instantiated, the new instance will be added as a listener to each of the service points listed here, to be notified when some service-specific event is triggered. See the chapter on “Listeners and Event Producers” for more information.
visibility This must be either the value “public” or “private”. It defaults to “public”. If it is “private”, then the service point is not visible outside of its containing package. it is often the case that a particular package will have a few public services that are facades for multiple private services. See the copland.webrick package for an example.

Of these attributes, only implementor is required.