What’s New in this Release?

Cougaar 12.6 is a major release.

Contents

For documentation on the various zip, jar, and config files included in this release, please see Release Structure.

Git info

The release is on branch origin/B12_6 and tagged with R12_6.

Changes:

• Cougaar repository converted from CVS to Git with the retention of all checkin messages, tags, and branches. cougaar.org hosts external Git repositories.
• Annotations for easy specification of Plugin Parameters, Subscriptions, Service Bindings and Queries. Annotations work in both in plugins and in non-plugin servlets. Some tutorials have been updated to use annotations. See Annotations. The @Arg annotation now allows you to omit the name parameter if it’s the same as the field name.
• Generics support for black board subscriptions and predicates that reduces runtime checking of instanceof and subsequent casting. See Generics.
• Updated tutorials and examples.
  The tutorials have been modified to use the new APIs. See examples:
  • ping/src/org/cougaar/demo/ping/*.java
  • hello/src/org/cougaar/demo/hello/HelloClassicSubscribePlugin.java
  • mesh/src/org/cougaar/demo/mesh/MeshPlugin.java
  • mesh/src/org/cougaar/demo/mesh/MeshServlet.java

  The Hello tutorial now includes examples of logging plugin, society, and run commands. See src/org/cougaar/demo/hello/HelloPLogginglugin.java. It shows: usage for different levels; when to use isXxxEnabled; configuring the run/log.config; and controlling Servlets.

• Core modules, examples, and end-user application are eclipse projects.
• Cougaar now requires Java 6 to compile and execute. Cougaar now works with JDBC 4.0.
• The Agent lifecycle was enhance to delay setupSubscriptions() to be strictly after all plugins have run start(). This guarantees that intra-agent services can be looked up in start() and used in setupSubscriptions(). This also allows plugins to be specified and loaded in any order without conflict. Intra-agent services should be provided at load() time, looked up at start(), and only then are blackboard operations triggered that can use these services.
• Service lookup has annotation support that binds the service at start()-time. Example:

  @Cougaar.ObtainService
  public HelloService helloService;

  At load()-time and again at start()-time the service is looked up and bound to the variable. This replaces the old reflective scheme which is only tested at load()-time

  public HelloService helloService;
  public setHelloService(HelloService service) {
          this.helloService = service;
  }

• All of the source is now stored with a single linefeed as the line terminator character. There is a special setting to use for Git to convert to Window’s carriage-return/linefeed format upon checkout. See here.
• The use of the code generator (ant target “asset.codegen“) has been deprecated. Any current modules that used code generation have had that code explicitly generated and committed to Git, and the xx.def file was renamed to xx.def-obsolete. This corrects a bug in the eclipse build process.
• End-developers can now rebuild all of Cougaar. The build script can now execute from remote or local Git repositories.
• The build script now generates TrimCougaar.zip with contents downloaded from cougaar.org. We distribute that TrimCougaar.zip file.
• The javaiopatch has been removed as Java 6 does not have the underlying bug in it that had necessitated the patch in older versions of Java. The build define -Dorg.cougaar.core.persistence.verifyJavaIOPatch is no longer needed and has been removed from the source.
• Various parts of the off-line html documentation that is distributed with Cougaar have been updated to remove references to non-current parts of Cougaar. The most up to date documentation is on cougaar.org
• Additional data types are available for plug-in arguments: Boolean, INET_ADDR and URL.
• Configuration files of type .iml and .ipr for the long unsupported IDEA IDE have been deleted.
• Eclipse launchers were added for the Pizza tutorial.

Release notes for older Cougaar revisions can be found in the Release History.

Requirements

Cougaar requires Java version 1.6 (aka Java 6). For details, please see the Installation Guide.

Installation

Please see the Installation Guide and Overview Slides.

Documentation

For additional details, please review the following documentation:

• The Cougaar FAQ
• The Cougaar Tutorials Page contains:
  • Training Slides and example source code on how to implement planning applications using Task/Allocation agent interactions.
  • The Pizza planning application.
• The Documentation Page contains:
  • Cougaar Overview Slides
  • The Cougaar Developers’ Guide v11.4
  • The Cougaar Architecture Document v11.4
  • Many additional Conference Papers.
• Detailed documentation on several core services, such as the ThreadPool and Metrics services.
• Javadoc is available:
  • In the “cougaar-api.zip” as ” javadoc/module/doc/api” files, such as the Core Javadoc.
  • Online under Documentation.

Known Limitations and Features

• The change to use Java generics may require modifying existing applications.
• Cougaar will not build with Java 7 due to its JDBC 4.1 being incompatible with JDBC 4.0. Code changes necessary for JDBC 4.1 are present in the source, but commented-out.
• Please note that if you change SimpleAgent.xsl do not change the value of threadService from full to trivial unless you also change to metrics=trivial. The values must be in sync for consistent use of dependent libraries.
• We have started work on using the Jenkins continuous integration server for Cougaar builds, but it is not ready for release.
• As stated above, the build script generates TrimCougaar.zip by downloading it during the build. For this release, it is one code generation behind the running build. We will fix this.

Support

For information on problems that were detected after this Cougaar version was released, please see the Online errata page.

Contents of this Cougaar Release

This file documents the contents of this release and the general layout of Cougaar software modules. When you download a Cougaar release, there are several logical pieces.

BUILD ORGANIZATION

Cougaar is divided into modules, from the various cougaar.org projects that make up CougaarSE. This is a list of the various zip files available from releases.

Notes:

• You’ll need cougaar.zip and cougaar-support.zip (the first time) to get a runnable system. The rest are extras. Furthermore, the cougaar-support contents do not change very often.
• The zips are designed to be unpacked in the same directory, e.g. on UNIX:

   mkdir cougaar
   cd cougaar
   unzip /tmp/cougaar.zip
   unzip /tmp/cougaar-support.zip
   setenv COUGAAR_INSTALL_PATH `pwd`

• The zips include version information in their respective “Manifest/” directories. The content looks something like:

   NAME=cougaar-support
   COMMENT=cougaar thirdparty jars
   REPOSITORY_TAG=V10_0 # branch
   REPOSITORY_TIME=1/28/2003 13:00:08 # checkout time
   ARCHIVE_TIME=1/28/2003 13:29:27 # zip time

  All your zips should have the same REPOSITORY_TAG and REPOSITORY_TIME. Each generated “lib/*.jar” file also contains its version information.

MODULE LIST

The Cougaar software distribution (cougaar.zip) contains a number of separate modules of related classes with supporting documentation and sources. The modules roughly correspond to separate Cougaar projects, though some projects contain multiple modules. Also see Modules in GIT Repositories.

Each module typically produces a single Jar file in “lib/”, as well as a directory “COUGAAR_INSTALL_PATH/” which contains data files, scripts, documentation, etc. Here is a list of those modules, in approximate order of compilation dependency or extra functionality. For detailed dependency information, see “build/data/default.build”.

DEPRECATED MODULE LIST

The following modules are deprecated in this release.

INTRA-MODULE ORGANIZATION

Each module subdirectory is organized in a similar way in the source repository:

 src/ integration sources
 doc/ integrations notes, etc
 data/
 configs/
 ...

PACKAGE ORGANIZATION

Software intended to replace core functionality should match the below package layout (or provide detailed arguments why it should be changed).

Software intended to augment the core and/or provide optional core functionality, but is not intended to replace the “standard” software suite, should mirror the above layout rooted in a new “organization/project/product-specific” package rather than override the core’s “org.cougaar” package names. For example, an alternate implementation of the agent base class

    core/org.cougaar.core.agent.AgentImpl

which was optimized for small devices might be delivered as part of company “foo”‘s module as

    fooco/com.foo.cougaar.palmtop.agent.EmbeddedAgent

where:

    "fooco/" is the module
    "com.foo." is the company package prefix
    "cougaar.palmtop." is the project's root
    "agent" is the parallel to the core's package.
    "EmbeddedAgent" is the class name

None-core functionality should follow standard java package arrangement standards and so should not intersect with any core packages. In particular, “org.cougaar” may only be used by core cougaar software.