Configuration

You must configure the CEC so that it works with your chosen applications and in the environment of your site. Please follow this sequence:

  1. Edit the CEC's "environment" to tell it where to find things.
  2. Edit the "registration-template" document.
  3. Preview the registration document.
  4. Restart the web application to pick up the changed configuration.

Instructions for each step are gven below.

Edit the CEC's environment

The CEC needs to be told where to find things in its operating environment. You do this by editing the "environment entries" (i.e. named properties) using the environment-editor page. There is a link to the editor in the sidebar.

The editor displays descriptions of the uses and proper values of the environment entries. More detail is available in the reference manual for the CEC.

When you save changes in the editor, it first saves them into a file in the CEC's own configuration directory. This makes a safe copy of the environment but doesn't apply the changes. The editor then applies the environment by copying it into Tomcat's configuration directory. At this point, Tomcat should detect the change and restart the web application with the new environment.

The CEC's working directories and configuration files

The CEC uses a fixed directory-structure for its configuration and working files.

		  (base)/
			(base)/temp
			(base)/records
			(base)/config
			(base)/config/registration-template.xml
			(base)/config/(context-name).xml
			

In this structure, (base) is the directory you specify by setting the environment entry cea.base.dir. By changing this entry, you can move the directory structure anywhere you like. However, best thing is usually to leave the structure at the location initially suggested by the web-application. That way, the web-application can find it again when recovering from a software upgrade. Usually, Tomcat and the web-application conspire to put cea.base.dir inside the Tomcat installation.

There are two cases where you'd need to change cea.base.dir.

  1. If the default location is inside Tomcat and you have Tomcat's directories write-locked.
  2. If the default location turns out to be in /tmp and you are running Solaris.

In the latter case, /tmp is no good as it gets wiped when the server reboots. You need the CEC's files to survive server restarts.

The file (base)/config/(context-name).xml (where (context-name) is the name of the web-application context; e.g. CEC-1) is where the environment editor stores the environment.

The file (base)/config/registration-template.xml is the registration-template document.

Edit the registration template

The CEC uses an XML document called a registration template to generate the registration documents that it submits to the IVO resource-registry. You need to edit this template.

To find the registration template, use the show current configuration link in the sidebar. You need to replace the copy at that location with a customized version.

The template initialized by the CEC has extensive comments to tell you what to set; please read them. Note that there are two main sections: one for the applications and another, below, for the service.

Preview the registration document

When you have the environment set, including the entry that leads the URL to your edited copy of the registration template, you should check that the registration documents are coming out satisfactorily. Use the "show registration document" link in the side-bar.

The registration document is what will eventually be sent to the IVO resource registry to identify your CEC and its applications. These documents are public and are read both by human users of your service and by machines. Therefore, they need to be both scientifically useful and technically correct. You need to check them at this stage before going on to registration.

The most important thing to check is the identifier element in the service description. This is the formal name for your service in the registry, and you can't change it once you've registered (changing the name creates a second registration; it doesn't rename the original one). Almost anything else can be patched up by registry updates, but you have to get the identifier right first time. Things to check:

  • Is the authority ID part of the identifier (e.g. the foo.bar in ivo://foo.bar/baz right for the registry where you're publishing? A given registry accepts registrations only under a limited, pre-agreed set of authorities.
  • Is the resource-key part (e.g. the baz in ivo://foo.bar/baz unique within the naming authority?
  • Is the resource key a sensible and memorable name for the service?

Restart the web application

The CEC web-service needs to be restarted to pick up the changed configuration. This means that you have to restart the whole web-application. Either restart Tomcat itself, or use the Tomcat Manager application to restart the current web-application.