8. Configuration Points

A configuration point is either a list or map that other packages may contribute values to. You can then have Copland automatically wire that configuration point into a service.

Why would you want to do this? Various reasons. One is so that you can allow other packages to configure the behavior of a particular service. The copland.remote.DRbServer service, for example, does this, to allow applications to configure the host and port that should be listened to, and whether or not the service should be automatically started.

Values are added to a configuration point via the “contributions” section of a package descriptor.

8.1. Descriptor Syntax

Every configuration point must be defined as part of the “configuration-points” section of a package descriptor. The id (or name) of the configuration 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 configuration name in quotes.

The allowed attributes of a configuration point are:

description This is an (optional) description of what the configuration point describes. Where a schema (see below) is insufficient, the description may also be used for describing what kinds of values the configuration point expects.
type This is the type of the configuration point. By default, only list and map are supported, but you can add your own configuration point types.
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 used to restrict the values that can be contributed to the configuration point. If the configuration point is of type list, then the schema applies to each element of the configuration point. Otherwise, the schema describes the format of the map.

Of these attributes, only type is required.

8.2. FactoryDefaults

One of the core pre-defined configuration points is the map copland.FactoryDefaults. Although you will rarely access this configuration point directly, it is integrated tightly with Copland. Any value you add to it becomes available as a substitution symbol.

Substitution symbols will look familiar to those of you coming from a Java background; utilities like ant and maven make heavy use of them. What they are, is this: any time Copland encounters a value that contains a certain pattern, it replaces that pattern with the value of the same name from the FactoryDefaults. The pattern is a dollar sign, followed by curly braces that contain the name of the symbol.

For example, suppose you want to allow the application to configure which class gets used when a particular service point is instantiated. You can do this by pulling the name of the class from the FactoryDefaults as a substitution symbol:

  SomeServicePoint:
    implementor: ${the.class.to.use}

Then, the application would contribute a value named the.class.to.use to copland.FactoryDefaults, and when SomeServicePoint is instantiated, it would use the value thus provided.

8.3. ApplicationDefaults

The copland.ApplicationDefaults configuration point works together with the FactoryDefaults configuration point to provide a flexible way to override default values of substitution symbols.

When a substitution symbol is requested, the ApplicationDefaults configuration point is searched first. If the requested symbol is not found there, the FactoryDefaults configuration point is searched. This allows package developers to define default values (in FactoryDefaults), and allow clients of the packages to override those defaults as needed (in ApplicationDefaults).