Control and Observation in Distributed Environments (CODE)
                     Version 1.0 Beta 1
                        01/26/2004

This directory contains a version of the CODE software. CODE consists
of a relatively simple distributed event management framework and
supports the observation and management of resources, services, and
applications using this event management framework.

The documentation for CODE is pretty much pathetic at this
point. There are several papers in the docs/ directory that provide an
overview of CODE, but they are not entirely up to date. But, below is
a little more detailed information that will hopefully help you get
started. Feel free to contact us if you have any questions.

The level of testing of this version of CODE is also not all that
wonderful. Please report any bugs you find and expect new beta
versions to be released frequently.

1. Building

CODE is currently compiled using Gnu Make. In the past, CODE had full
Java and C++ implementations but the version of CODE provided here
only includes Java code because the C++ version has fallen out of
date. We used Make for our compilation so that we could support C++ in
addition to Java.

CODE requires the following software:
  - Java 1.3 or better (we develop and test with version 1.4.x)
  - Xerces Java XML Parser version 2.x
    - available from http://xml.apache.org
  - The Globus Java CoG version 1.1a
    - available from http://www.globus.org/cog/java
  - Log4J
    - available from http://jakarta.apache.org/log4j
  - JUnit (for running the tests)
    - available from http://www.junit.org

After obtaining and building the above software, compile CODE by:
  1. The code/ base directory contains a makefile.header. Edit this
     file so that it points to the software libraries above.
  2. Execute "make"
  3. Include <path_to_code>/code/code.jar in your CLASSPATH

2. Quick Start

  1. cd to the code/example/java directory
  2. run: java gov.nasa.nas.code.observe.Observer example_observer.props
     This will start an observer using the properties specified in
     example_observer.props and will print out a URL where the
     observer is listening.
  3. Try the following programs:
     java GetEventDescriptions <observer url>
       - this will retrieve the events provided by the observer and print them
     java QueryProcesses <observer url>
       - this will query the observer which will run the
         ProcessesSensor to determine which processes are running the
         host and print out these processes
    java SubscribeHeartBeat <observer url>
       - this will subscribe for heart beat events, receive 10 events
         that are pushed to it by the observer every 2 seconds, print
         each one, and then exit
    java SubscribeDiskSpace <observer url>
       - this will subscribe for disk space events describing the disk
         holding the "/" directory, periodically pull events from the
         observer, and exit after receiving at least 10 events

    The other examples in the code/example/java directory are probably
    confusing and may not be worth looking at.

3. Definitions

Event - An event is a description of something that has occurred. An
event is represented with the class gov.nasa.nas.code.event.Event. An
Event is a gov.nasa.nas.code.data.ListData that contains a list of
data classes that are in the gov.nasa.nas.code.data package.

EventId - A <name, name space> pair that uniquely identifies an
event. Defined in the gov.nasa.nas.code.event.EventId class.

EventSchema - A schema that describes what information may and must be
contained in an event of a specific type. Defined in the
gov.nasa.nas.code.event.EventSchema and gov.nasa.nas.code.data.*Schema
classes.

Producer - A service that produces events. An interface defined in
gov.nasa.nas.code.event.

Consumer - A service that consumes (receives) events. An interface
defined in gov.nasa.nas.code.event.

Parameters - Parameters supplied when asking for event(s) to be
created. For example, the identifier of a process to monitor. Defined
in gov.nasa.nas.code.event.

ParametersSchema - A schema that describes what information may and
must be provided in Parameters. Defined in gov.nasa.nas.code.event.

Subscription - A representation of a subscription for events from a
producer. A subscription includes the parameters to use to generate
events, how often events should be generated, whether events should be
pushed to a consumer or a consumer will periodically pull events,
where events should be pushed (if they are being pushed), and an event
filter to decide which of the generated events should actually be sent
(not yet implemented). Defined in gov.nasa.nas.code.event.

Sensor - A sensor is used to measure something from a host and produce
an event that describes the result of the measurement. The Sensor base
class is defined in gov.nasa.nas.code.observe and a basic set of
sensors are defined in gov.nasa.code.observe.sensor and sub-packages.

Sensor Manager - Manages a set of sensors, decides when to run them to
generate events to service queries and subscriptions. Defined in
gov.nasa.nas.code.observe.

Observer - A configurable service that produces events using a Sensor
Manager and Sensors. Defined in gov.nasa.nas.code.observe.

Actuator (not currently implemented) - Essentially a Sensor, but used
to perform an action that modifies something from the host it is run
from.

Actuator Manager (not currently implemented) - A Sensor Manager for
Actuators.

Actor (not currently implemented) - Analagous to an Observer.

HostingEnvironment - Allows local Producers and Consumers to be made
available to remote clients and allows local Consumers and Producers
to contact remote Producers and Consumers.

4. Contact Information

If you have any questions, suggestions, bug reports, etc. please
contact:

Warren Smith
Computer Sciences Corporation
NASA Ames Research Center
wwsmith@nas.nasa.gov