$Id: ConfiguringCCE.txt,v 1.1 2000/03/16 00:23:27 jmayer Exp $

Configuring CCE

1.0 Abstract

This spec defines the configuration files that CCE relies on.  There
are three essential elements of CCE that must be configured:
	- data types
	- schemas (class definitions)
	- event actuators

All of this configuration information is controlled by a collection
of text configuration files in a special CCE configuration directory.
These files are parsed when the CCE server is started, or when a HUP
signal is issued to the CCE.

FIXME: this document is a bit rough and hurried, so it needs some
clean-up.

2.0 Discussion

Further examination of IDL revealed that IDL is a poor match for
describing CCE schemas.  For more information on the IDL grammar,
see: ftp://www.omg.org/pub/docs/formal/98-03-01.idl

2.0 Configuration Directory

All files that configure CCE go into the $(CCEHOME)/conf directory.

Installation or removal of data types, schema, or event actuators is
performed by simply adding or removing files from this directory.

Each config file may contain one or more elements (definitions of
datatypes, schema, or handlers).  Related elements do not necessarily
need to be in the same file, nor is ordering important.


3.0 Configuration File Format

Like everything else designed since 1999, the configuration file format
used by CCE is XML. 

3.1 A quick sample

A sample config file:

<?xml version="1.0"?>
<cce version="1.0">   <!-- indicates what version grammar to use -->
  <datatype name="integer">
	regex:[0-9]+
  </datatype>
  <datatype name="dayofweek">
	extern:/usr/local/bin/test_isdayofweek
  </datatype>
  <schema name="MyClass" isa="ParentClass">
	<scalar type="integer">5</scalar>
	<reference type="ServiceClass"/>
  </schema>
  <handler exec="/usr/local/bin/handler_adduser">
	<on>UserClass._new</on>
	<on>UserClass.name</on>
	<on>UserClass.*</on>
	<on>UserClass._destroy</on>
  </handler>
</cce>

3.2 Definitions

Element: cce
Attributes: version
Contains: zero or more of { datatype | schema | handler }

Declares a CCE configuration block.  "version" specifies the
version of the grammar to use within the block.

Element: datatype
Attributes: name
Contains: no sub-elements (just a value)

Declares a new CCE datatype.  The name of the data type is
specified by the 'name' attribute, and the value of this tag
is a specially formatted string parsed by odb_datatyper that
specifies how to evaluate the validity of a datatype.

Element: schema
Attributes: name, isa
Contains: zero or more of scalar, ref

Declares a new CCE schema (class).  The name of the class is 
defined by "name", and "isa" indicates what class to inherit
from.  All classes must name a valid classname in the "isa"
attribute (ie. a class defined elsewhere, or the special "Object"
class).

Element: scalar
Attributes: name, type, default
Contains: no sub-elements

Declares a new scalar property of a schema (class).  "name" specifies
the name of the property, and "type" indicates a named datatype
(declared elsewhere).

The default tag comprises the default value for this
property.

Element: ref
Attributes: name, type
Contains: nothing

Declares a new ref-list property of a schema (class).  "name" specifies
the name of the property, and "type" indicates the name of a class
(or base class) for object instances allowed to be listed in this
reference list.

Element: handler
Attributes: exec
Contains: zero or more "on" elements

The "exec" attribute of the handler declaration specifies what action
should occur when the handler is invoked.

Element: on
Attributes: none
Contains: an event string

The "on" element of a handler specifies an event for which the
handler is a handler for.  Event descriptions typically consist
of a class name, followed by a dot, followed by a property name
or a special.  Valid specials include: "_new" and "_destroy".



