Cougaar12_4

Client plugins can register sensors ({@link org.cougaar.core.adaptivity.Condition}s) and control "knobs" ({@link org.cougaar.core.adaptivity.OperatingMode}s) with the adaptivity engine. The adaptivity engine plugin uses policy and a rule file ({@link org.cougaar.core.adaptivity.Playbook}) to change the control settings, adapting the configuration to match the sensor data.

For more detail, see the Cougaar Developers' Guide.

The top-level JVM {@link org.cougaar.core.node.Node} loads the {@link org.cougaar.core.agent.AgentManager}, which will contain all the agents on the JVM. The AgentManager loads the configuration service ({@link org.cougaar.core.node.ComponentInitializerService}) and the node agent {@link org.cougaar.core.agent.AgentImpl}, which is an agent named after the "-Dorg.cougaar.node.name" system property. Like all agents, the node agent's AgentImpl loads a single {@link org.cougaar.core.agent.Bootstrap} component that specifies the agent's initial component list. The bootstrap loads the minimal number of components necessary to read the XML configuration file and/or persistence snapshot, which will fill in the full agent configuration. The node agent's {@link org.cougaar.core.node.AgentLoader} then instructs the AgentManager to load the other agents that should run on the node.

Many of the components in this package are not required by the bootstrap but are used in the standard agent XML/XSL template ($CIP/configs/common/SimpleAgent.xsl) to load basic services. For example, the {@link org.cougaar.core.agent.MessageSwitch} component is used to provide a common message transport service interface for components within the agent.

Also note that many of the components and services in this package act as "glue" to coordinate agent bootstrapping and mobility. For example, the {@link org.cougaar.core.agent.MessageSwitch} component is loaded early to allow other agent components to register {@link org.cougaar.core.agent.service.MessageSwitchService} handlers, such as the blackboard's {@link org.cougaar.core.agent.QueueHandler}. However, message delivery must wait until all components have loaded and had a chance to register their handlers, otherwise these early messages will be dropped. The MessageSwitch advertises a "glue" {@link org.cougaar.core.agent.MessageSwitchUnpendService} with an "unpendMessages()" method that will release the queued messages. A trivial {@link org.cougaar.core.agent.MessageSwitchUnpend} component is loaded late in the agent, after all the other components have been loaded, just to invoke the "unpendMessages()" method at the right time.

For more detail, see the Cougaar Developers' Guide.

The standard agent contains a {@link org.cougaar.core.blackboard.StandardBlackboard} component that provides the {@link org.cougaar.core.service.BlackboardService}, which is a wrapper around the {@link org.cougaar.core.blackboard.Subscriber} class. The StandardBlackboard creates the {@link org.cougaar.core.blackboard.Distributor}, which manages the subscribers, and the special {@link org.cougaar.core.blackboard.Blackboard} subscriber to maintain a view of all blackboard objects and invoke {@link org.cougaar.core.domain.Domain} {@link org.cougaar.core.domain.LogicProvider}s. Each subscriber has a set of {@link org.cougaar.core.blackboard.Subscription}s that are known only to that subscriber. A subscriber registers with the distributor to receive blackboard add/change/remove notification "tuples". When a subscriber wishes to modify the blackboard contents, it must start a distributor transaction, fill an envelope with add/change/remove tuples, and finish the distributor transaction. The distributor also coordinates periodic persistence and ensures that blackboard updates are thread-safe.

For more detail, see the Cougaar Developers' Guide.

A {@link org.cougaar.core.domain.Domain} provides problem-specific support for blackboard objects, such as an object {@link org.cougaar.core.domain.Factory} and {@link org.cougaar.core.domain.LogicProvider}s to automate object behaviors and communicate with remote agents. The {@link org.cougaar.core.blackboard.Blackboard} single-threadedly invokes the {@link org.cougaar.core.domain.Domain}s at the end of every blackboard transaction and incoming message delivery.

For more detail, see the Cougaar Developers' Guide.

The mobility infrastructure is loaded into the node agent by the {@link org.cougaar.core.mobility.service.RootMobilityPlugin}, which requires the {@link org.cougaar.core.mobility.ldm.MobilityDomain}'s {@link org.cougaar.core.mobility.ldm.MobilityFactory}. Agents register with the {@link org.cougaar.core.mobility.MobilityService} as {@link org.cougaar.core.mobility.MobilityClient}s to be told when they are moved, which requires them to suspend and capture their persistence state. {@link org.cougaar.core.mobility.service.RootMobilityPlugin}s in the source and target nodes communicate through {@link org.cougaar.core.relay.Relay}s to transmit the agent and make sure it is started on the target node before being removed from the source node.

Plugins request agent mobility by interact with the {@link org.cougaar.core.mobility.service.RootMobilityPlugin} through blackboard {@link org.cougaar.core.mobility.ldm.AgentControl} objects that specify the requested {@link org.cougaar.core.mobility.Ticket} command, such as a {@link org.cougaar.core.mobility.MoveTicket} to move an agent. Additional tickets exist for adding and removing agents.

For more detail, see the Cougaar Developers' Guide.

The standard message transport implementation is the org.cougaar.mts.base.MessageTransportServiceProvider component.

For more detail, see the Cougaar Developers' Guide.

The {@link org.cougaar.core.node.Node} contains the top-level

  public static void main(String[] args) {..}

The node creates the root {@link org.cougaar.core.component.ServiceBroker} and {@link org.cougaar.core.agent.AgentContainer}. Additional details can be found in the agent package javadoc.

This package also contains the {@link org.cougaar.core.node.ComponentInitializerService} provider components:

1. The standard XML-based configuration reader, which supports XSL templates ({@link org.cougaar.core.node.XMLComponentInitializerServiceComponent}).
2. The deprecated INI-based configuration reader ({@link org.cougaar.core.node.FileComponentInitializerServiceComponent}).
3. The deprecated database configuration reader ({@link org.cougaar.core.node.DBComponentInitializerServiceComponent}).

Another notable component is the {@link org.cougaar.core.node.AgentLoader}, which loads the node's child agents.

For more detail, see the Cougaar Developers' Guide.

The primary client is the {@link org.cougaar.core.blackboard.StandardBlackboard}, which uses persistence to periodically capture the agent's blackboard state, and rehydrate that state when the agent is restarted (either from a crash or mobility).

A modified {@link java.io.ObjectOutputStream} and {@link java.io.ObjectInputStream} is used to support persistence deltas, where references to unchanged objects are serialized instead of the full objects. This requires Cougaar to override these JVM classes on the Java command line, by using:

 -Xbootclasspath/p:$COUGAAR_INSTALL_PATH/lib/javaiopatch.jar

Additional {@link org.cougaar.core.persist.PersistenceService} clients include the agent's component model manager, which saves the agent's list of components in the persistence snapshot.

For more detail, see the Cougaar Developers' Guide.

For more detail, see the Cougaar Developers' Guide.

Coordination Artifacts are designed to separate out an abstract communication pattern, on the one hand, and the domain-specific clients of the communication on the other. The internal parts of the Artifact are concerned with organizing Communities, Relays and other COUGAAR infrastructure in a structured way in order to represent a pattern of inter-Agent chatter. Each kind of Artifact completes this by supplying Community names, data types etc.

Coordination Artifacts are specifically designed to operate across Plugins. At first glance this might appear to violate one of the design principles of COUGAAR. But on further reflection it can be seen that the Coordination approach is analagous to a cross-cut in Aspect Oriented Programming. Just as an Aspect cross-cuts the dominant Object Oriented decomposition, so a Coordination Artifact cross-cuts the Plugin "decomposition" of a COUGAAR Agent.

Coordination Artifacts are created by a CoordinationArtifactProvider, via requests made to the CoordinationArtifactBroker. A CoordinationArtifactProvider is like a COUGAAR ServiceProvider: its primary job is to find or make CoordinationArtifacts of some particular kind. But it also defines a set of Roles that describe the functions performed by clients of this kind of Artifact. For example in Artifacts that implement a multicast request (one request, multiple replies), the two Roles are queryer and responder. A Provider also implicitly defines a set of parameters that distinguish the individual instances of that kind of Artifact from one another.

Every Role in an Artifact can be seen from two perspectives: that of the Artifact and that of a Role player. Borrowing some terminology from the CORBA Component Model, we refer to these as Facets and Receptacles, respectively. The analogy is only approximate, however. Unlike CCM, both Facets and Receptacles are interfaces, and typically these interfaces overlap without being identical. On the other hand, a Receptacle is always bound to exactly one Facet, as in CCM, and is the client's only handle into the Artifact (which in this analogy is like a Component in CCM), also as in CCM.

This leads to the following Java interfaces:

• RolePlayer: From the Artifact's perspective, each client plays one of the Artifact's defined roles. This interface specifies that abstracion.
• Facet: The generic viewport that any given RolePlayer has into the Artifact is specified by a Facet, which is effectively a definition of the role.
• Receptacle: The RolePlayer's handle on a Facet.
• CoordinationArtifact: The creation of Facets and the linkage between Facets RolePlayers is handled at this layer.
• CoordinationArtifactProvider: The main job of the Provider is to define the logical Roles and parameters, and to create and manage CoordinationArtifacts as needed.
• CoordinationArtifactBroker: This interface defines a COUGAAR service that provides the top-level entry point into CAs.

Given these definitions, we can see that a Coordination Artifact is essentially coordinating communication between Role Players. But the Role Players as well implement a kind of coordination of their own, a dual of the Coordination Artifact: the Players coordinate the operation of the various Artifacts in which they play. Although the purposes and structure of these two sorts of coordination differ, they share one important feature: the logical structure of both can be described declaratively as set of dependencies between and actions among the parts. Furthermore, the interactions between a Role Player and an Artifact can be expressed as assertions, retractions or modifications of facts.

Rule languages are particularly good at expressing facts and dependencies, and the Coordination Artifact code is explicitly designed to work with rule systems, though it's written in a language neutral way. The assumption is that a collection of implementation classes of the abstract Artifacts and Role Players can be written to use a specific rule language and rule engine, while the common infrastructure can deal in general with facts, assertions, etc.

In this scenario, the rule engine is owned by the Role Player, and its collection of facts at runtime is partitioned by the Artifacts with which it interacts. Once a Player is bound to an Artifact, the primary means of interaction between them by means of facts: a given Player sends fact assertions, modifications and retractions into its Receptacle for a given Artifact in order to propogate those assertions etc to other Player's in the same Artifact; the Artifact in turn propogates assertions, retractions etc by sending them to the appropriate Player. Thus the RolePlayer and Receptacle interfaces are very similar, precisely because of this duality.

Frames and FrameSets

A {@link org.cougaar.core.qos.frame.DataFrame} is a unit of knowledge, consisting of a type specification (what kind of entity or relationship itr represents) and a set of name-value pairs representing its current state. The of any given DataFrame is fixed for the lifetime of the Frame. The pairs, also known as slots, can change dynamically at runtime. Types are organized as a (single inheritance) hierarchy in which each type inherits the slots defined by its parent. A second form of read-only inheritance is described below.

DataFrames can be treated as beans, more or less, with the standard form of accessor methods and with support for property-change notifications. This allows DataFrames to be shadowed in Jess, which in turn means that rules can use slot values of DataFrames.

A DataFrame can represent either an entity or a binary relationship between other DataFrames. In the latter case, each of two parts of the binary relation are specified by a type/slot/value triple which is expected to match at most one DataFrame (i.e., at most one frame of the given type should have the given value in the given slot). NB: In the current release we assume that slots used in relationship matching are immutable.

The meta-data in the Cougaar frame system is derived from prototypes described in xml. These prototypes correspond to the types of the DataFrames, and are organized as a single-inheritance hierarchy. Prototypes include declarations of the slots they include, with optional default values.

Prototype meta-data is used for several purposes. First, it's used to generate Java classes for the types. DataFrame instances at run time will be instances of one of these generated classes. In addition, the prototypes are also accessible at runtime as frames themselves, in particular as {@link org.cougaar.core.qos.frame.PrototypeFrame} instances.

A {@link org.cougaar.core.qos.frame.FrameSet} is simply an organized collection of PrototypeFrames and DataFrames. PrototypeFrames are associated with the FrameSet when it's made and are fixed for the life of the FrameSet. DateFrames, on the other hand, come and go dynamically. The main jobs of a FrameSet are to provide a well-defined subspace for a collection of Frames, and to cache relationships.

FrameSets can be created and populated via xml using the {@link org.cougaar.core.qos.frame.FrameSetService}, which can also be used to find existing FrameSets. [more?]

One of the novel features of the Cougaar frame system is that it supports two independent hierarchies. In addition to the prototype hierarchy, the Cougaar frame system a second single-inheritance hierarchy known as containment. Containment is a special relationship used to augment slot value lookup at runtime. As one might expect, DataFrames can include a frame-specific value for any given slot. If it does, no further work is required. If it doesn't, the prototype hierarchy is searched for a default value or for a path specification (see below for more on paths). If this fails as well, the containment hierarchy can then be searched. This allows a DataFrame to have virtual access to slots defined by its logical container. The containment relation is defined as part of FrameSet and fixed when the FrameSet is created. This relation is an example of caching handled by the FrameSet.

Another novel features of the Cougaar frame system is the {@link org.cougaar.core.qos.frame.Path} specification. The description of any given slot in a prototype can indicate that the value of that slot for some frame F is determined by following a particular path from F a runtime. A Path represents a kind of encapsulated visitor pattern. It consists of an ordered series of Forks and a slot. Each Fork refers to a relation and a role. This allows any given frame to follow a path, one relationship at a time, to any related frame, arbitrarily far away. When the final frame in the path is reached, the given slot value is returned as the value of the original slot reference. NB: Although DataFrames generally act like beans, including property-change support, Path-valued slots are an exception at the moment: if the value of Path-valued slot changes, listeners will not be notified. We hope to deal with this in a future release.

XML Specification

FrameSets and Frames can be loaded into Cougaar via xml files. This section describes the XML elements and attributes for PrototypeFrames. The formal description is in framesets.dtd. The DTD format for the DataFrames of any particular domain is generated from the PrototypeFrames. Those are not described in detail here, but in general each Prototype has a corresponding element that can contains elements for the slots in that Prototype. Slot elements have only PCDATA for the value of the slot. For an example, see cougaar-topology.dtd and test-frames.xml.

frameset

A frameset element is used to describe a FrameSet. It has four required attributes. The frame-inheritance describes the prototype inheritance structure. The only supported value right now is "single" (i.e., single inheritance). The container-relation attribute specifies which relation prototype defines the containment hierarchy. Any defined relation prototype can be specified here. The package attribute is used by the code generator: the classes generated for this frameset's prototypes will be put in the given package and the files will be written to the corresponding directory stucture, following standard Java conventions. Finally, the domain attribute specifies a name for whatever logical domain the framset's prototypes are describing. This name should be the root element in xml data files for this domain.

prototypes

A prototypes element can be used to group prototype elements. It has no attributes and is not required. Ordinarily a prototypes element would be within a frameset element in an XML file. But it can also be at the top level if the file is being read in to an existing FrameSet.

prototype

A prototype element defines a PrototypeFrame. It has one required attribute, name, which is the name of the prototype. It also supports three optional attributes: prototype, which specifies the "super" of this one; container, which specifies the prototype of frames that can act as containers for frames of this prototype; and doc, which will be used as javadoc in the generated class. The remaining structure of a prototype is specified by the slot elements it contains.

relation-prototype

A relation-prototype element defines a PrototypeFrame representing a relationship. The attributes are a superset of the attributes of prototype elements. The additional attributes, all optional, are parent-prototype, parent-slot, child-prototype and child-slot

path

A path element defines a Path. It has one required attribute, name. The elements it contains are any number of forks (order is significant) followed by an optional slot-reference.

fork

A fork element defines a "hop" in its enclosing path, where a hop consists of a relation prototype and a role the next object on the path should play in that relationshoip. Correspondingly, a element has two required attributes: relation (the relation prototype name) and role ("parent" or "child").

slot

A slot element is used within prototype element to define one of the prototype's named fields. It has one required attribute, name, which is the name of the slot, and a range of optional attributes:

doc

This attribute provides optional documentation for the slot and is used as javadoc for the public accessor. It's included in the slot metadata.

immutable

This boolean valued attribute indicates whether or not the value of the slot in any given DataFrame can be chaged after initialization. The default is "false" (ie, values can be changed after initialization).

member

This boolean valued attribute indicates whether or not the generated code for this slot treats it as a data member or as a property. The former is more efficient for slots whose value is usually frame-specific, the latter is more efficient for slots whose value is usually defaulted. The default for this attribute is "true".

Other slot attributes can render this one irrelevant. In particular, if a slot has a path, it will never be a data member, regardless of the setting of this attribute. Conversely, if the slot is declared to have a simple type, or if it's declared to be transient, it will always be a data member, regardless of the setting of this attribute.

notify-blackboard

This attribute specifies whether or not a change should be published on the Blackboard when the slot value changes. The default is "true".

notify-listeners

This attribute specifies whether or not PropertyChange listeners should be notified when the slot value changes. The default is "true".

path

The presence of this attribute indicates that the default value for this slot is computed by following a path. The value of the attribute is the name of path. If a path attribute is present, the slot cannot be a member.

transient

This boolean valued attribute indicates whether or not the corresponding data member in the generated class will be declared transient. The default is "false". Transient slots are always members.

type

This attribute is used to specify the Java type of values of this slot. The default is "String". Other possible values are "int", "long", "float", "double", "boolean", "Integer", "Long", "Float", "Double", "Boolean" and "Metric". Slots with simple types must be members. See below for more on slot types.

units

This attribute provides optional units for the slot. It's included in the slot metadata but currently isn't used for anything else.

default-value

This attribute gives a default value of the slot. The value can be any string. If a slot has neither a value nor a path attribute, then the slot has no default value. In this case, the generated accessor code will issue a warning if it has no frame-specific value for this slot.

warn

This boolean valued attribute indicates whether or not a warning is generated at runtime if the slot has no value. The default for this attribute is "true".

slot-reference

A slot-reference element can only be used within a path element, and if present, must be the last element in the path. It simply names a slot. As such it has one required attribute, name.

Code Generation

{@link org.cougaar.core.qos.metrics.MetricsService} documentation is in:
$COUGAAR_INSTALL_PATH/doc/OnlineManual/MetricsService/index.html

For more detail, see the Cougaar Developers' Guide.

The simplest configuration option is to profile the aggregate "messages per second" throughput. Add the following components to all nodes:

  <!-- required profiler-management component -->
  <component
      class='org.cougaar.core.qos.profile.ProfilerCoordinator'
      priority='HIGH'
      insertionpoint='Node.AgentManager.Agent.Component'>
    <!-- optional period between logs, defaults to 60000 millis -->
    <argument>period=10000</argument>
  </component>

      <!-- message transport sensor -->
      <component
          class='org.cougaar.mts.std.StatisticsAspect'
          insertionpoint='Node.AgentManager.Agent.MessageTransport.Aspect'/>

  <!-- messaging throughput profiler -->
  <component
      class='org.cougaar.core.qos.profile.Throughput'/>

2005-04-29 13:23:39,297 SHOUT [throughput] - NodeA: #agent_send_count_per_second, total_send_count_per_second, agent_send_count, total_send_count,
2005-04-29 13:23:39,362 SHOUT [throughput] - NodeA: 0.00, 0.00, 0, 3
2005-04-29 13:23:49,103 SHOUT [throughput] - NodeA: 0.56, 1.78, 5, 19
2005-04-29 13:23:59,101 SHOUT [throughput] - NodeA: 27.22, 27.22, 250, 264
2005-04-29 13:24:09,102 SHOUT [throughput] - NodeA: 121.50, 121.50, 1465, 1479
2005-04-29 13:24:19,101 SHOUT [throughput] - NodeA: 160.89, 161.11, 2913, 2929

For more detailed profiling, add the following components to all nodes:

  <!-- required profiler-management component -->
  <component
      class='org.cougaar.core.qos.profile.ProfilerCoordinator'
      priority='HIGH'
      insertionpoint='Node.AgentManager.Agent.Component'/>

  <!-- mts components -->
      <component
          class='org.cougaar.mts.std.StatisticsAspect'
          insertionpoint='Node.AgentManager.Agent.MessageTransport.Aspect'/>
      <component
          class='org.cougaar.core.qos.tmatrix.AgentFlowAspect'
          insertionpoint='Node.AgentManager.Agent.MessageTransport.Aspect'/>

  <!-- optional mts-internal profilers (select none, any, or all) -->
  <component
      class='org.cougaar.core.qos.profile.LocalTraffic'
      insertionpoint='Node.AgentManager.Agent.MessageTransport.Component'/>
  <component
      class='org.cougaar.core.qos.profile.RemoteTraffic'
      insertionpoint='Node.AgentManager.Agent.MessageTransport.Component'/>
  <component
      class='org.cougaar.core.qos.profile.Throughput'
      insertionpoint='Node.AgentManager.Agent.MessageTransport.Component'/>
  <component
      class='org.cougaar.core.qos.profile.TrafficMatrix'
      insertionpoint='Node.AgentManager.Agent.MessageTransport.Component'/>

  <!-- metrics components and plugins -->
      <component
          class='org.cougaar.core.qos.rss.AgentHostUpdaterComponent'
          insertionpoint='Node.AgentManager.Agent.MetricsServices.Component'/>
      <component
          class='org.cougaar.lib.mquo.SyscondFactory'
          insertionpoint='Node.AgentManager.Agent.MetricsServices.Component'/>
      <component
          class='org.cougaar.core.qos.rss.ConfigFinderDataFeedComponent'
          insertionpoint='Node.AgentManager.Agent.MetricsServices.Component'>
        <argument>name=sites</argument>
        <argument>url=cougaarconfig:TIC-Sites.conf</argument>
      </component>
      <component
          class='org.cougaar.core.qos.rss.ConfigFinderDataFeedComponent'
          insertionpoint='Node.AgentManager.Agent.MetricsServices.Component'>
        <argument>name=hosts</argument>
        <argument>url=cougaarconfig:TIC-Hosts.conf</argument>
      </component>

      <component
          class='org.cougaar.core.qos.tmatrix.AgentFlowRatePlugin'/>
      <component
          class='org.cougaar.core.qos.metrics.AgentStatusRatePlugin'/>
      <component
          class='org.cougaar.core.thread.AgentLoadSensorPlugin'/>
      <component
          class='org.cougaar.core.thread.AgentLoadRatePlugin'/>
      <component
          class='org.cougaar.mts.std.StatisticsPlugin'/>
  
  <!-- optional profilers (select none, any, or all) -->
  <component
      class='org.cougaar.core.qos.profile.BlackboardSize'/>
  <component
      class='org.cougaar.core.qos.profile.JvmHeapSize'/>
  <component
      class='org.cougaar.core.qos.profile.Load'/>
  <component
      class='org.cougaar.core.qos.profile.NodeTraffic'/>
  <component
      class='org.cougaar.core.qos.profile.PersistSize'/>
  <component
      class='org.cougaar.core.qos.profile.ProcLoadAvg'/>
  <component
      class='org.cougaar.core.qos.profile.ProcNetDev'/>
  <component
      class='org.cougaar.core.qos.profile.ProcMemInfo'/>
  <component
      class='org.cougaar.core.qos.profile.ProcStat'/>
  <component
      class='org.cougaar.core.qos.profile.ProcStatus'/>
  <component
      class='org.cougaar.core.qos.profile.Resources'/>
  <component
      class='org.cougaar.core.qos.profile.VmStat'/>

  <!-- optional, required if above BlackboardSize is loaded -->
  <component
      class='org.cougaar.core.qos.profile.BlackboardSizeInAgent'/>

  <!-- optional, required if above PersistSize is loaded -->
  <component 
      class='org.cougaar.core.qos.metrics.PersistenceAdapterPlugin'/>

  <!-- optional, required if above BlackboardSize is loaded -->
  <component
      class='org.cougaar.core.qos.profile.BlackboardSizeInAgent'/>

Some useful system properties:

  <!-- enable persistence, for PersistSize activity -->
  <vm_parameter>
    -Dorg.cougaar.core.persistence.enable=true
  </vm_parameter>

  <!-- disable the "NodeA: " logging prefix -->
  <vm_parameter>
    -Dorg.cougaar.core.logging.addAgentPrefix=false
  </vm_parameter>

  <!-- turn off +/- logging on message activity -->
  <vm_parameter>
    -Dorg.cougaar.core.agent.quiet=true
  </vm_parameter>

  <!-- reduce naming & mts startup time -->
  <vm_parameter>
    -Dorg.cougaar.core.wp.resolver.rmi.minLookup=500
  </vm_parameter>
  <vm_parameter>
    -Dorg.cougaar.core.wp.resolver.rmi.maxLookup=2000
  </vm_parameter>
  <vm_parameter>
    -Dorg.cougaar.core.wp.server.failTTD=1000
  </vm_parameter>
  <vm_parameter>
    -Dorg.cougaar.core.mts.destq.retry.maxTimeout=30000
  </vm_parameter>

The {@link org.cougaar.core.relay.RelayLP} is included in the {@link org.cougaar.core.domain.RootDomain}, which is loaded by default. The {@link org.cougaar.core.relay.Relay} API is divided into a sender-side {@link org.cougaar.core.relay.Relay.Source} and destination-side {@link org.cougaar.core.relay.Relay.Target}, although most relay implementations implement both APIs. A source specifies one or more target agents, the content, and a {@link org.cougaar.core.relay.Relay.TargetFactory} factory for creating the target-side representation of the relay. Each target-side relay specifies an optional response to send back to the source. A relay with an {@link org.cougaar.multicast.AttributeBasedAddress} target will be sent to all members of the community and dynamically added/removed as community members are added/removed.

The relay API is complex to allow maximal flexability. A simple example is included: {@link org.cougaar.core.relay.SimpleRelayExample} is a plugin that publishes a {@link org.cougaar.core.relay.SimpleRelay} to send a "ping" object to a target agent, and the target sends back an "echo-ping" acknowledgement. See the {@link org.cougaar.core.relay.SimpleRelayExample} javadoc for details.

For more detail, see the Cougaar Developers' Guide.

The general rule is to place service APIs in "org.cougaar.core.service" if they are used by many clients (e.g. the {@link org.cougaar.core.service.BlackboardService}) or if the implementation is defined in an external module (e.g. the {@link org.cougaar.core.service.MessageTransportService}).

However, for legacy reasons, there are several exceptions to this rule that could be refactored, such as the commonly-used {@link org.cougaar.core.node.NodeControlService} and restricted {@link org.cougaar.core.service.DomainForBlackboardService}.

For more detail, see the Cougaar Developers' Guide.

For most {@link org.cougaar.core.service.ThreadService} clients, the only public APIs are the {@link org.cougaar.core.thread.Schedulable} and perhaps {@link org.cougaar.core.thread.SchedulableStatus}.

{@link org.cougaar.core.service.ThreadService} documentation is in:
$COUGAAR_INSTALL_PATH/doc/OnlineManual/ThreadService/index.html

For more detail, see the Cougaar Developers' Guide.

For more detail, see the Cougaar Developers' Guide.

The implementation is divided into:

• {@link org.cougaar.core.wp.resolver}:
  The client-side naming cache, lease manager, and server-selection,
• {@link org.cougaar.core.wp.server}:
  The servers, which can be replicated,
• {@link org.cougaar.core.wp.bootstrap}:
  Shared bootstrap components for clients to discover servers (e.g. cache the server address from either {@link org.cougaar.core.wp.bootstrap.ConfigReader} config file or website) and for servers to advertise their addresses (e.g. through an HTTP {@link javax.servlet.Servlet}).

For more detail, see the Cougaar Developers' Guide.

Please see the accompanying "Cougaar Mandelbrot" slides:
  http://cougaar.org/docman/view.php/17/201/cougaar_mandelbrot.ppt

Each "v*" package is a different implementation of the "Mandelbrot Set" application:

• "v0" {@link org.cougaar.demo.mandelbrot.v0.MandelbrotPopup}
  A simple command-line test that runs without Cougaar. This can be run from Ant, using "ant test-popup" or "ant test-file".
• "v1" {@link org.cougaar.demo.mandelbrot.v1.MandelbrotServlet}
  This servlet, and all the following "v*" servlets, are invoked by the "/mandebrot" {@link org.cougaar.demo.mandelbrot.FrontPageServlet}.

  This "v1" implementation performs the image calculation in the servlet "doGet" method. It is nearly cut-n-paste from the above "v0" code.

  Usage is documented in the doc/README.html.

• "v2" {@link org.cougaar.demo.mandelbrot.v2.FractalServlet}
  In this version, a generic FractalServlet obtains a FractalService. There are two service implementations:
  1. {@link org.cougaar.demo.mandelbrot.v2.MandelbrotCalculator}
  2. {@link org.cougaar.demo.mandelbrot.v2.JuliaCalculator}
  The choice of calculator implementation is defined in:
     ../configs/MandelbrotSociety_v2.xml
  
• "v3"
  TODO proposed blackboard request hand-off.
• "v4"
  TODO proposed non-servlet blackboard request, with no odd wait/notify.
• "v5"
  TODO proposed minor variation of "v4" to separate the request/response blackboard objects.
• "v6"
  TODO proposed use of a relay to send the request to a remote agent.
• "v7"
  TODO proposed variation of "v6" to add a "dispatcher" plugin, to specify the remote agent.
• "v8"
  TODO proposed more complex dipatcher, to select between multiple remote agent "workers".
• "v9"
  TODO proposed task decomposition and parallel computation.
• "v10"
  TODO proposed policies and QoS adaptive behavior.

Introduction: This document introduces the existing COUGAAR filtering predicate, UnaryPredicate, and the new language for expressing these filters as comparable Operators. Examples are given, followed by a BNF specification.

An introduction to UnaryPredicates
A UnaryPredicate is a simple filtering predicate defined in Java:

  public interface UnaryPredicate {
    public boolean execute(Object o);
  }

  public class MyStringPred implements UnaryPredicate {
    public boolean execute(Object o) {
      return (o instanceof String);
    }
  }

  {
    MyStringPred strPred = new MyStringPred();
    boolean b1 = strPred.execute("someString");   // true
    boolean b2 = strPred.execute(null);           // false
    boolean b3 = strPred.execute(new Integer(3)); // false
    // etc..
  }

An introduction to Operators
An Operator is an extension to UnaryPredicate:

  public interface Operator extends UnaryPredicate {
    // .. more methods here defined below ..
  }

The goal of the language is to expose a tree-like structure of the filtering predicates. One benefit of this representation is the ability to pretty-print the behavior of the predicate as the tree-structure in XML or Lisp-style parenthesis form.

The tree-structure can then be used to compare Operators with other Operators to compare their behavior. There are two comparisons that can be performed, "implies" and "allows":

  For any two Operators, A and B:
    if "A implies B" then, for all Objects "o":
      if (A.execute(o) == true) then (B.execute(o) == true).

  For any two Operators, A and B:
    if "A allows B" then there exists an Object "o" such that:
      ((A.execute(o) == true) and (B.execute(o) == true)).

These analysis features will be used to specify the input/output behavior of Plugins and determine when the output (publish) of one Plugin matches the input (subscription) of another Plugin or Plugins.

The langauge supports type checks (instanceof), basic logical operators (and/or/not), some set operators (exists/all/empty), and support for Java reflection-based method calls on an arbitrary Object (e.g, for String, one can call "equals", "toLowerCase", etc). Further syntatic details are defined below in BNF form.

The choice of language primitives was partially guided by the analysis goal -- the Operator language is not a "complete" programming language. While the exclusion of some language constructs might limit the expressibility of the Operators (i.e., no if/while/variables/functions), this mini-language lends itself to better automated reasoning and can always defer back to Java by using reflection.

List of Operator language primitives:
The Operator language defines it's primitives as Operators themselves. Many of these primitives can contain other primitives as arguments, forming a tree structure. Examples and full BNF specification of the language is defined in later sections of this document.

The language primitives/keywords are:

  Logical Operators:
    true 
    false
    not
    and 
    or 
  List Operators:
    all 
    empty
    exists
  Reflective Operators:
    is:[Not:][Null|classname]
      -- e.g. is:Null, is:Not:Null, is:List, is:Not:String, etc.
    [classname:]fieldname
      -- e.g. Integer:MAX_VALUE, java.awt.Dimension:width, etc.
    [classname:]methodname[-method_argument_decl]
      -- e.g. equals, toLowerCase, etc.  One rarely needs to specify
         the optional type-declarations for the arguments; see the
         notes on method resolution.
    apply
      -- typically only used by the parser.
  Constant Operators:
    "constant"
      -- e.g. "SomeTestString", "5", etc.
    const
      -- allows one to define a constant of a non-String type.  
         This is rarely used in practice.
    get
      -- fetch an Operator.setConst(String name, Object value) constant,
         which allows the Operator to act as a simple template.

Examples:
A full BNF specification is provided later in this document -- this section provides illustrative examples of the predicate language, many based on ALP data structures. These examples are formatted in XML, one of many representation formats.

"Always true"
<true/>
-- note the Operator.execute(Object) method will always
  return true for this Operator; it is equivalent to:
    public class MyTruePred implements UnaryPredicate {
      public boolean execute(Object o) {
        return true;
      }
    }

"A Task"
<is:Task/>
-- note the short-hand use of a default package prefix
  for "Task", which is short for "org.cougaar.planning.ldm.plan.Task".

"A URL"
<is:java.net.URL/>
-- note "java.net" is not one of the default package prefixes,
  so one must specify the full classname.

"An Asset that is not an Organization"
<and>
  <is:Asset/>
  <is:Not:Organization/>
</and>
-- note these instance checks are done in sequence 
  (left-to-right) and lazily (if not an Asset, the Organization check 
  is not performed).  If both instance checks are true, then the top-level
  "and" returns true.


"A Task with a non-null Verb"
<and>
  <is:Task/>
  <getVerb>
    <is:Not:Null/>
  </getVerb>
</and>
-- note once the Object has been cast to a 
  Task, the method "[Task.]getVerb" is called.  The
  result, a Verb, is then passed down to the "is:Not:Null"
  check.  As explained in the notes on method resolution 
  and the "apply" primitive, this is actually equivalent to:
    <and>
      <is:Task/>
      <apply>
        <getVerb/>
        <is:Not:Null/>
      </apply>
    </and>
  but the short-hand helps keep the predicates terse.

  Another way to visualize this predicate is to imagine writing
  a Java UnaryPredicate without using any variables:
    public class MyPred implements UnaryPredicate {
      pubic boolean execute(Object o) {
        return 
          ((o instanceof Task) &&
           (((Task)o).getVerb() != null));
      }
    }

"An Allocation to an Organization"
<and>
  <is:Allocation/>
  <getAsset>
    <is:Organization/>
  </getAsset>
</and>
-- note this is very similar to the prior example.

"A String equal to 'TEST'"
<and>
  <is:String/>
  <equals>
    <const value="TEST"/>
  </equals>
</and>
-- note this is different than the prior example!
  Once the type has been cast to String, the call to 
  "equals" is resolved to:
    In class String:
      "public boolean equals(String s) {..}"
  Note that the parser selected the "equals(String)" method, not
  the less-specific:
    In class Object:
      "public boolean equals(Object o) {..}"

  In this example the "const" operator was used explicitly; one
  could also write <equals>Test</equals> since
  this constant is a String with no leading/trailing
  whitespace.

  Here's a look at the equivalent Java UnaryPredicate:
    public class MyPred implements UnaryPredicate {
      pubic boolean execute(Object o) {
        return 
          ((o instanceof String) &&
           ((String)o).equals("TEST"));
      }
    }

"An Asset with a type-id of 'MAINTENANCE'"
<and>
  <is:Asset/>
  <getTypeIdentificationPG>
    <getTypeIdentification>
      <equals>
        <const value="MAINTENANCE"/>
      </equals>
    </getTypeIdentification>
  </getTypeIdentificationPG>
</and>
-- note the use of nested method calls, each separately defined
  to take zero arguments:
    In class Asset: 
      "public TypeIdentificationPG getTypeIdentificationPG() {..}"
   In class TypeIdentificationPG:
      "public String getTypeIdentification() {..}"
  then the final call to "equals", which is similar to the previous
  example's resolution.  A key difference here is that there is no 
  "equals(String)" method in TypeIdentification, so the basic:
    In class Object:
      "public boolean equals(Object o) {..}"
  is used.

"An AssetTransfer of a Task with a verb matching the field-constant ReportForDuty"
<and>
  <is:AssetTransfer/>
  <getTask>
    <getVerb>
      <equals>
        <org.cougaar.glm.Constants.Verb:ReportForDuty/>
      </equals>
    </getVerb>
  </getTask>
</and>
-- note this is very similar to the prior example, but with a
   static field reference to "ReportForDuty".  Also note that this
   class is not a default package, so the full classname must 
   be specified.

"A task which, in it's workflow, contains a subtask with a null plan element"
<and>
  <is:Task/>
  <getWorkflow>
    <getTasks>
      <exists>
        <and>
          <is:Task/>
          <getPlanElement>
            <is:Null/>
          </getPlanElement>
        </and>
      </exists>
    </getTasks>
  </getWorkflow>
</and>
-- note that "getTasks" returns an Enumeration, and the
  "exists" operator will test each element of the Enumeration to
  see if it's "a subtask with a null plan element".

Many of these predicates are similar to the ones defined in the examples section above.

  totals:
    lines of formatted XML:                 811
    total number of "composed" Operators:    95
    total number of primitives used:        522 

  average primitives per Operator:            5.5

  frequency of primitives:
    primitive                #occurences out of 522           notes
    ---------------------------------------------------------------------
    ..methodname..            204 (39%)                 173 (33%) "get"-ers
                                                         54 (10%) "equals"  
    is:..                     173 (33%)                  31 ( 6%) "is:Null" 
    and                        74 (14%)
    ..fieldname..              45 ( 8%)                 all static-finals
    exists                     16 ( 3%)
    const                       9 ( 2%)
    not                         1 ( 0.2%)

This previously seen example:

  <and>
    <is:Task/>
    <getVerb>
      <is:Not:Null/>
    </getVerb>
  </and>

  (and (is:Task) (getVerb (is:Not:Null)))

  "<?>" becomes " (?" 
  "</?>" becomes ")" 
  "<?/>" becomes " (?)" 

Some users might prefer the XML representation, some the parenthesis representation -- they are equivalent.

Language specification:
XML is an awkward format for defining a language BNF, so the parenthesized format is used here. These representations are equivalent.

Operators may contain other Operators as children, generating a tree structure with arbitrary branching. The result is somewhat similar to a decision tree that only specifies the TRUE leaves, considering everything else to be FALSE.

Here are the BNF rules with detailed notes:

-- start here at S

S := OPERATOR

OPERATOR := (logicalOp | listOp | reflectOp | constantOp)

logicalOp := (trueOp | falseOp | andOp | orOp | notOp)
listOp := (allOp | emptyOp | existsOp)
reflectOp := (instanceOp | methodOp | fieldOp | applyOp)
constantOp := (constOp | getOp)

-- these are definitions of OPERATOR that return a boolean:

boolOp := (logicalOp | listOp | boolReflectOp | boolConstantOp)
boolReflectOp := (instanceOp | boolFieldOp | boolMethodOp | applyOp)
boolConstantOp := (boolConstOp | boolGetOp)
boolFieldOp := fieldOp      -- where the field type is "boolean"
boolMethodOp := methodOp    -- where the method return type is "boolean"
boolConstOp := constOp      -- where the type is "boolean"
boolGetOp := getOp          -- where the type is "boolean"

-- these are the operators:

trueOp := "(true)"          -- returns boolean TRUE

falseOp := "(false)"        -- returns boolean FALSE

andOp := "(and" ((" " boolOp)+) ")"  
                            -- returns boolean logical-AND of each
                               boolOp, evaluated lazily from left to right

orOp := "(or" ((" " boolOp)+) ")"    
                            -- returns boolean logical-OR of each
                               boolOp, evaluated lazily from left to right

allOp := "(all " boolOp ")" -- only applicable when the passed Object
                               is a "ConceptualList"; an instance of:
                                 java.util.Collection
                                 java.util.Iterator
                                 java.util.Enumeration
                                 Java_primitive_array
                               Returns the boolean TRUE if the 
                               boolOp.execute(Object) returns TRUE
                               for all elements in the list.

emptyOp := "(empty)"        -- only applicable when the passed Object
                               is a "ConceptualList", as defined in allOp.
                               Returns the boolean TRUE if the list has
                               zero elements.

existsOp := "(exists " boolOp ")"
                            -- only applicable when the passed Object
                               is a "ConceptualList", as defined in allOp.
                               Returns the boolean TRUE if the 
                               boolOp.execute(Object) returns TRUE
                               for any element in the list.

instanceOp := "(is:" ["Not:"] classname ")"  
                            -- returns boolean if passed
                               Object is/is-not
                               an instance of the classname.  If the
                               given Object passes the
                               instance test then this type information
                               can be used by methodOp

fieldOp := "(" [classname ":"] fieldname ")"
                            -- if the field is non-static then
                               the passed Object must
                               be cast by a prior instanceOp to a
                               class that defines this field.  The fact
                               that this is a field and not a method is
                               determined by Java reflection; in the 
                               case that both a field and method with
                               the same name exist, the method is taken.


methodOp := "(" [classname ":"] methodname [methodargdecls] OPERATOR* ")"
                            -- if the method is non-static then
                               the passed Object must
                               be cast by a prior instanceOp to a
                               class that defines this method.  If
                               the method is defined to take zero
                               arguments but a single argument  is 
                               specified then this is shorthand for 
                                 "(apply " ..method.. " " OPERATOR ")"
                               otherwise the number of specified arguments
                               must match the method declaration.  See
                               the notes on method resolution.

applyOp := "(apply " OPERATOR " " boolOp ")"
                           -- takes the results of the OPERATOR and 
                              passes it to the boolOp; the result
                              is the boolOp's boolean.  Note that
                              methodOp uses shorthand for the applyOp.

constOp := (("\"" value "\"") | ("(const " [constOp " "] constOp ")"))
                           -- the value defaults to a 
                              String.  In the "(const " format,
                              if the first optional argument is given then
                              the type is cast to that type.  For example,
                                "(const \"int\" 5)"
                              In XML this can be formatted as
                                "<const type=\"int\">5</const>

getOp := "(get " [constOp " "] constOp ")"
                           -- similar to a regular constOp, but the
                              last constOp argument is used as an identifier
                              "variable", as set by the external Operator
                              user.  For example, one can set the value using:
                                Operator.set(String key, Object value)
                              and use this to make the Operator act as a
                              template.

-- these are some Java-related class specifications

classname := [packagename "."] name_of_a_Java_class
                           -- for example, "List" or "java.net.URL".

                              The default packages "imported" by the parser
                              are currently:
                                java.lang
                                java.util
                                org.cougaar.planning.ldm.plan
                                org.cougaar.planning.ldm.asset
                                org.cougaar.planning.ldm.measure
                                org.cougaar.glm.asset
                              references to other packages must
                              use the full classname, such as
                              "(is:java.net.URL)"

packagename := name_of_a_Java_package
                           -- for example, "java.net"

methodname := name_of_a_method_in_the_current_Object
                           -- the method

type := (classname | Java_primitive)
                           -- for example, "List" or "int"


methodargdecls := "-" ((type ":")*)
                           -- rarely used to clear up 
                              methodOp/applyOp ambiguity; see the
                              notes on method resolution.

-- these are approximations of the Java specifications:

char := ("a" | .. | "z" | "A" | .. | "Z" | "0" | .. | "9")

value := (char | "." | "-" | "_" | ":" | "\" | "\"")*

name_of_a_Java_class := (char | "_")+

name_of_a_Java_package := char (["."] char)*

name_of_a_method_in_the_current_Object := char (["_"] char)*

Java_primitive := ("boolean" | "byte" | "char" | "short" | 
                   "int" | "float" | "double" | "long")
                           -- this is ambiguous with the classname rule,
                              but you get the idea...


-- I'm not so sure this BNF would be accepted by a parser tool like YACC,
   but they are close.

First, note that this explanation uses the parenthesized format,
matching the formal BNF specification.

If the methodOp has N arguments and a corresponding method of N
type-compatable parameters exists, this is the match.  If there are
multiple matches then this is ambiguous and would require the full
method definition with the method-type-declarations.

If the multi-parameter method is found, then the current Object
is passed to all the arguments.

The methodOp quietly uses applyOp when the resolved method has zero 
arguments but one argument is specified.  For example,
  "(and (is:Exception) (getMessage (is:Null)))"
actually means
  "(and (is:Exception) (apply (getMessage) (is:Null)))"
This is a useful shorthand that saves many "(apply " wrappings.

The ambiguity arrives in method polymorphism and is rare in practice. 
For example, suppose class "X" had two methods:
  "boolean getY()" and "boolean getY(boolean)".  
The Operator
  "(and (is:X) (getY (is:Null)))"
is ambiguous without specifying if this means:
  "(and (is:X) (apply (getY-) (is:Null)))"
or
  "(and (is:X) (getY-boolean (is:Null)))"

The "arch" package defines generic APIs and support classes for the {@link org.cougaar.lib.web.arch.server.ServletEngine} and "root/leaf" servlets. In Cougaar, the "root" is the node-level servlet that forwards "/$" requests to local agents or redirects the client to the appropriate remote host, and the "leaf" is the per-agent servlet that forwards requests to that agent's servlets. For example, the path "/$x/y" is received by the {@link org.cougaar.lib.web.arch.server.ServletEngine}'s "gateway" and passed to the {@link org.cougaar.lib.web.arch.root.RootServlet}, which sees the "/$x" and forwards to local agent "x"'s {@link org.cougaar.lib.web.arch.leaf.LeafServlet}, which forwards to that agent's "/y" servlet.

The "arch" only depends upon "javax.servlet.*"; all the service details and {@link org.cougaar.lib.web.arch.server.ServletEngine} implementation are in {@link org.cougaar.lib.web.service}.

For more detail, see the Cougaar Developers' Guide.

The {@link org.cougaar.lib.web.axis.WebServicesProvider} advertises the {@link org.cougaar.core.service.WebServicesService}, allowing plugins to register their WSDL to receive SOAP calls.

The examples are:

• Cougaar-to-External "Distance"
  An example of a Cougaar plugin that sends an external SOAP call, in this case to a service that calculates the distance between any two ZIP codes. The {@link org.cougaar.lib.web.axis.distance.DistanceQueryPlugin} listens for blackboard {@link org.cougaar.lib.web.axis.distance.DistanceQuery} objects, invokes the external service, and sets the {@link org.cougaar.lib.web.axis.distance.DistanceQuery} distance field. In this example, the {@link org.cougaar.lib.web.axis.distance.DistanceQuery} objects are created by a simple {@link org.cougaar.lib.web.axis.distance.DistanceQueryTest} plugin. This example also illustrates how to make synchronous v.s. asynchronous SOAP calls.
• External-to-Cougaar "BlackboardCount"
  An example of a Cougaar plugin that receives external SOAP calls, in this case a query for a table of blackboard object classnames to their count on the node-agent's blackboard. The {@link org.cougaar.lib.web.axis.blackboardCount.BlackboardCountPlugin} registers a WSDL in the {@link org.cougaar.core.service.WebServicesService} for "BlackboardCount" SOAP requests. A simple external command-line {@link org.cougaar.lib.web.axis.blackboardCount.BlackboardCountClient} can be used to test the "BlackboardCount" service.
• Cougaar-to-Cougaar "SOAPLinkProtocol"
  A Cougaar Message Transport {@link org.cougaar.lib.web.axis.mts.SOAPLinkProtocol} that illustrates both of the above example uses:
  • A Cougaar-to-External SOAP caller to send Cougaar agent-to-agent messages
  • An External-to-Cougaar SOAP listener to receive Cougaar agent-to-agent messages

For more detail, see the Cougaar Developers' Guide.

The engine uses a {@link org.cougaar.lib.web.micro.base.ServerFactory} to listen for incoming connections. The API has been designed to support both socket and non-socket backends.

Also of interest is the {@link org.cougaar.lib.web.micro.base.ServletTunnel}, which is a utility class for tunnelling servlet requests through a generic connection API.

Note that this package only depends upon the JDK and Servlet APIs. There are no Cougaar dependencies.

For more detail, see the Cougaar Developers' Guide.

The engine is a simple component wrapper around the {@link org.cougaar.lib.web.micro.base.ServletEngineImpl} implementation. It is sufficient for most servlet-based UIs.

The tunnel is primarily a proof-of-concept. In general, it's better to redirect a browser to the correct URL than it is to tunnel HTTP requests for that browser.

For more detail, see the Cougaar Developers' Guide.

The only way into this mts-engine is through a remote mts-tunnel. The local engine and remote tunnel coordinate by passing "pipe-messages" between one another.

Together, the mts-engine and mts-tunnel can be used to tunnel remote servlet requests to nodes that are only reachable through the message transport. For example:

  Node A is running the http-engine, http-redirector, and mts-tunnel
  Node B is running the mts-engine 

  http-engine, mts-engine, http-redirector, mts-tunnel

  http://host_a:1234/$(mts_tunnel)NodeB/some_path

For more information about URL-line options, see {@link org.cougaar.lib.web.arch.util.PathParser}.

The "pipe" and "factory" class are generic utilities that create a stream wrapper on top of Cougaar's package-oriented messaging support. These classes could be used to support other, non-servlet, stream-oriented applications.

Instead of using the "base" ServletEngineImpl, it might be feasible to create a Tomcat "connector" backend.

For more detail, see the Cougaar Developers' Guide.

This package defines the node-level {@link org.cougaar.lib.web.service.RootServletServiceComponent}, which creates the {@link org.cougaar.lib.web.arch.server.ServletEngine} and advertises the {@link org.cougaar.lib.web.service.RootServletService}. The standard {@link org.cougaar.lib.web.arch.server.ServletEngine} implementation is based on Tomcat and is defined in the "webtomcat" module ("org.cougaar.lib.web.tomcat") to avoid compile dependencies and allow for non-Tomcat implementations. From the {@link org.cougaar.lib.web.arch.server.ServletEngine}'s point of view, there is just one "gateway" servlet, the {@link org.cougaar.lib.web.arch.root.RootServlet}. Agents are loaded with the {@link org.cougaar.lib.web.service.LeafServletServiceComponent}, which obtains the {@link org.cougaar.lib.web.service.RootServletService}, registers the agent's "/$name" path, and advertises the {@link org.cougaar.core.service.ServletService} for component use.

For more detail, including configuration options and example servlets, see the Cougaar Developers' Guide.

This package contains the core software components and infrastructure for the the full Message Transport Service, including key Aspects and LinkProtocols but excluding optional Aspects and LinkProtocols.

For a more complete description of the MTS, see Message Transport Service online manual .

For a more complete description of the MTS, see Message Transport Service online manual .

This module follows a typical package structure for Cougaar applications. Here at the root is the Domain, the Factory if any, and a {@link org.cougaar.pizza.Constants} file.

Below this package, are packages for utilities, assets (sometimes called "ldm" with "asset" as a sub-package), plugins, servlets, and perhaps others (in our case, relays).

These LDM classes are all machine generated by the classes in the Build module, following the definitions in the two .def files here. See the Ant "defrunner" target.

The pizza application makes a relatively trivial use of Assets and Prototypes. It could instead just publish (Serializable) Objects direct to the Blackboard, rather than going through the process of creating and using Assets and Prototypes.

There is a Pizza asset (with Meat and/or Veggie PGs possible) used by Alice to indicate what she is Ordering. The Kitchen Assets also get a Meat and/or Veggie PG, indicating the kinds of pizza that they can make.

The Meat and Veggie PGs are trivial - they have no data slots, and are just used as markers. If the PG is there on the Kitchen, then they can make that kid of pizza. On the Pizza, they indicate the kind of Pizza being ordered.

The {@link org.cougaar.pizza.plugin.PizzaPrototypePlugin} and {@link org.cougaar.pizza.plugin.KitchenPrototypePlugin}s give Alice, Joes, and Dominoes access to Asset Prototypes. The KitchenPrototypePlugin also creates the single Kitchen Asset, with the correct PGs indicating whether that Pizza Provider serves meat and/or veggie pizzas.

The {@link org.cougaar.pizza.plugin.InvitePlugin} is used at Alice to send an invitation to all her friends on her buddy list, "FriendsOfMark" -- a Community. Her invitation is an {@link org.cougaar.pizza.relay.RSVPRelaySource} that asks "Meat or Veggie". Each member of the Community receives the Relay, and responds using the {@link org.cougaar.pizza.plugin.RSVPPlugin}. They then use the {@link org.cougaar.pizza.plugin.util.PizzaPreferenceHelper} to look at the local self Entity, looking for the {@link org.cougaar.pizza.Constants.Roles#CARNIVORE} or {@link org.cougaar.pizza.Constants.Roles#VEGETARIAN} Roles, to decide what kind of pizza they eat. They then set that {@link org.cougaar.pizza.relay.RSVPReply} Response on the {@link org.cougaar.pizza.relay.RSVPRelayTarget} Relay, which the infrastructure forwards back to Alice. At Alice, the infrastructure collects all the RSVPs on a {@link org.cougaar.pizza.plugin.PizzaPreferences} object, and after waiting to give everyone a chance to responsd, the InvitePlugin, publishes the PizzaPreferences object summarizing what pizza Alice wants to order.

At this point, you might use the "/pizza" ({@link org.cougaar.pizza.servlet.PizzaPreferenceServlet}) servlet to see who responded and what kinds of pizza Alice needs to order. Keep watching this servlet to see Alice order her pizza, and whether it succeeds.

There are then 2 options. In the non ServiceDiscovery version, the {@link org.cougaar.pizza.plugin.PlaceOrderPlugin} at Alice acts next. In the ServiceDiscovery version, it is the {@link org.cougaar.pizza.plugin.SDPlaceOrderPlugin}, which is a simple extension of the PlaceOrderPlugin. The PlaceOrderPlugin sees the PizzaPreferences on its Subscription, and prepares to order the pizza. First it looks to see if it has a Relationship on the self Entity to any PizzaProviders. In the SD version it does not, and must now do ServiceDiscovery. In the non-SD version, it does. So it then creates an {@link org.cougaar.pizza.Constants.Verbs#ORDER} Task, ordering {@link org.cougaar.pizza.Constants#PIZZA}. It then expands that - one for meat pizza (with an appropriate number of servings depending on RSVPs) and one for veggie. It Allocates those child tasks to the pizza provider it found on its self Entity (Joes in our example).

In the SD version, the SDPlaceOrderPlugin kicks off ServiceDiscovery by publishing a {@link org.cougaar.pizza.Constants.Verbs#FIND_PROVIDERS} Task, with an IndirectObject indicating it wants a PizzaProvider. The {@link org.cougaar.servicediscovery.plugin.SDClientPlugin} subscribes to those Tasks, and then publishes an MMQueryRequest, including an MMRoleQuery that specifies it wants a PizzaProvider, and includes the service scoring function ({@link org.cougaar.pizza.plugin.util.RoleWithBlacklistScorer}) to use in weighing different possible providers.

The {@link org.cougaar.pizza.plugin.MatchmakerPlugin} picks up the MMQueryRequest, and issues an asynchronous query to the Yellow Pages, asking it to walk up the hierarchy of Yellow Pages Communities as necessary, to find providers matching the query (so it finds Cambridge first, and then MA, as necessary). On getting a callback with a provider, it publishChanges the MMQueryRequest.

The {@link org.cougaar.pizza.plugin.SDClientPlugin} picks up the answer to its request, and sends a ServiceContractRelay to the named provider Agent, asking for a Relationship. Our example uses the {@link org.cougaar.servicediscovery.plugin.AgreeableProviderPlugin} from the servicediscovery module, which will immediately say yes (a more complex plugin might for example check capacity). The infrastructure then establishes the needed Relationship.

Once the SDClientPlugin sees that it has a Contract for the Role it was looking for, it marks the FindProviders Task with a confident Success Disposition. The SDPlaceOrderPlugin sees the change to the Disposition, and uses that to grab the new PizzaProvider. Then it continues just like the PlaceOrderPlugin, issuing Order Tasks that it allocates to the provider.

OK, so now, in both SD and non-SD versions, the PlaceOrderPlugin has allocated Pizza Order tasks to the Pizza Provider. In both cases, this should be Joes. The infrastructure copies the Order tasks to Joes Blackboard (because they were Allocated to the Joes Entity).

At Joes, the {@link org.cougaar.pizza.plugin.ProcessOrderPlugin} sees the new Order Tasks. It matches the PGs on the Task's Indirect Object Pizza Asset indicating the kind of pizza needed, with the PGs on its local KitchenAsset, and responds with Success or Fail, depending on whether it makes the kind of pizza needed. Joes does not make Veggie pizza, so will Fail that particular Task.

The PlaceOrderPlugin propagates that result up to its root Order Task, and logs the results. In the non-SD world, this is the end of the line. Alice only knows about Joes, so can't make her Vegetarian guests happy. :-(

In the SD version of the application, the SDPlaceOrderPlugin sees the failure on the order, and decides to find a new provider. It publishes a new FindProviders task, specifying that the previous provider (Joes) should be excluded - since Joes cant satisfy the Order. From there, it continues as before. The SD Plugins look for the next provider that meets the (stricter) criteria. They walk up from the Cambridge YP Community and find Dominos in the MA community. The SDPlaceOrderPlugin issues all new Orders to Dominos, which can meet Alices needs.

The party is on!

Note the use of separate Classes for the Source (created by the sender, Alice), Target (the version of the Relay seen by the recipients of the invitation), and TargetRelayFactory (creates the Target objects in the destination agent blackboards). This makes the code easier to read and slightly less error-prone. Many implementations however will use a single class for all of these. The {@link org.cougaar.pizza.relay.RSVPReply} is the Response object set on the Relay.Targets.

The {@link org.cougaar.pizza.servlet.HistoryServlet} is a generic servlet for monitoring changes to the blackboard. Use the {@link org.cougaar.pizza.servlet.HistoryServletFriendly} interface to allow the servlet to show meaningful information about your blackboard objects.

The {@link org.cougaar.pizza.servlet.PizzaPreferenceServlet} is the main UI for the pizza party app. It shows what the application is about, what has happened so far, how guests have RSVPed, and the status of the pizza orders.

Notes on the app-server

The "App-Server" is an application server (daemon) that allows remote clients to:

1. launch and kill processes, plus listen for the output of those processes
2. access the file system to read and write files
3. list running processes on the system ("ps")

As of Cougaar 9.0 there is little security built into the server, so use at your own risk. If the machines are behind a firewall then you're probably okay...

The AppServer is the "main" program to launch the server. The default port address is 8484. ".props" filenames that are specified as arguments are loaded by the server and used to set default process properties.

The RemoteHostRegistry allows a remote client to lookup an app-server on a specified (host:port) address.

There are several example app-server clients:

• The "org.cougaar.tools.server.examples" package, with source under "server/examples/*", contains two example consoles:
  • "MinConsole", which is a command-line test rig
  • "GuiConsole", which is simple Swing-based UI
  • The "CSMARTConsole", which is integrated into CSMART.
  • The "Manager", which is in the "manager" module.

  FIXME:
  The interfaces have a lot of "throws Exception" in them, which is messy. With a little work most of these methods could probably become something more specific, such as "throws IOException".

org.cougaar.tools.server.system package overview

In this package are system-level access API for:

• Creating a process command-line that will provide the process-id -- see ProcessLauncher
• Listing the running processes in a structured format -- see ProcessStatusReader
• Triggering a JVM Thread-Dump -- see JavaThreadDumper
• Force the kill of a running process -- see ProcessKiller

See SystemAccessFactor for details and Operating System dependencies.

See org.cougaar.tools.server.examples.SystemAccess in the server's "examples/" directory for sample usage.