<class registry
  on_key      ="_name"
  merge_method=registry.merge
  of          =opt
/>

See also: register

registry is a class which maintains uniqueness of instances with respect to particular fields. A registry is characterized by a 'on_key' field and a 'merge_method' field and used through the register, lookup, and ref methods. Registries are transparently used in Water by the register method defined for any class.

A registry's register method takes an object and returns either the object or an "equivalent" object which had been previously registered. Equivalence is determined by equality of the fields specified by the registry's on_key field (either a field name or a vector of field names). If an equivalent object had been previously registered, the registry's merge_method is called on the previous object and the current object and its result is returned from register and becomes the new registered object in the registry.

For example, the following example uses a registry to construct a simple symbol table.

<class symbol pname=req value=opt></class>
  <set symbol_table=<registry on_key='pname'/>/>
  symbol_table.<register <symbol "car"/>/>.
		  <is symbol_table.<register <symbol "car"/>/>/>

true

The is_registered method takes keyed fields uniquely identifying an object and returns the instance in the registry registered with those values, returning false otherwise.

For example, the following fragment extends on the previous example by testing whether a symbol has been registered in the symbol table.

symbol_table.<is_registered pname='cdr'/>

false

When the is_registered method is given a single positional argument, it checks whether the argument is an instance registered in the registry. If it is, it returns the instance; otherwise, it returns false. For example:

symbol_table.<is_registered <symbol "car"/>/>

false

symbol_table.<is_registered symbol_table.<register <symbol "car"/>/>/>

true

The ref method is used to create "placeholder" references to objects which are not yet loaded. The arguments to ref are the unique ids for the registry; it returns either a previously registered instance or creates an empty <thing/> and registers it with the corresponding unique id information. Later, when a new object is created and registered, it is merged with the placeholder reference, which is (according to the register semantics) returned by the call to register.

For example, this call to ref creates a thing:

symbol_table.<ref pname="cxr"/>._parent

thing

<set cxr_symbol=symbol_table.<ref pname="cxr"/>/>

ignore

cxr_symbol.<is symbol_table.<register <symbol "cxr"/>/>/>

true

The ref method is useful when registries are used to maintain objects which may be defined out of order or loaded on demand in some manner.

a wob

Parameter key	Default value	Type
on_key	"_name"	string

The 'on_key' field indicates the field or combination of fields which uniquely identify an object; the 'merge_method' field specifies how to merge instances which, according to their field values, should be identical.

The 'on_key' field is either a string (naming a field), a method (which can be called to get a value), or a vector of fields or methods indicating a combination which should be unique for instances.

In practice, the fields specified in the on_key field should be read-only and not subject to change (since that would corrupt the registry), but registries do not currently check that this is so.

a wob

Parameter key	Default value	Type
merge_method	merge	method

The 'merge_method' field indicates a method to be called to combine logically equivalent instances in the registry. It is called on the existing and new instances and returns the instance to be maintained in the registry and returned by register. It is also called where there is no existing instance, binding the existing instance to opt.

The default value of merge_method is registry.merge_overlay, which keeps the older instance but overwrites any conflicting fields with values from the new instance. Any method which takes two parameters and returns an instance can be used as a merge_method. A handful of built-in merge methods are provided on the registry class.

registry.merge_overwrite uses the older instance but makes it exactly identical to the new instance, removing fields if necessary;

registry.merge_replace uses the new instance, replacing the value stored in the registry (this may break some business logic relying on object identity);

© Copyright 2007 Clear Methods, Inc.