README

Brahms Agent Environment version 1.2.7

5/28/2008
Copyright (c) 1998-2008 NASA Ames Research Center. All Rights Reserved.


Table of Contents:

I. Welcome
II. Installation Notes
III. What's New
IV. Known Problems
V. Revision History
VI. Important Notes
VII. Contacting the Brahms development team for Technical Support

I. Welcome!

Welcome to NASA's Brahms Agent Environment 1.2.7 for Windows 2000, Windows XP, Linux, Sparc/Solaris and Mac OS X. Please take a few minutes to read this file, which contains the latest information regarding this release.

II. Installation Notes

In order to use the software you will need a license file (brahms.lic). Without the license file you will be able to install the software but you will not be able to use the Brahms virtual machine. If you have registered before to download previous versions of Brahms you can request a license file by sending an e-mail to register@agentisolutions.com. Include your name in the e-mail and we will send you a license file. If you registered to download this current version of Brahms then you will have received a user name and password to download this software as well as a license key. Place the license key in the AgentEnvironment directory.

If you have a previous version of Brahms installed you must first uninstall that version. Before uninstalling the version or upgrading the Brahms Agent Environment to this latest version make sure you copy your configuration files in case you want to use the same settings with the new version. You can copy the configuration files to the new version of Brahms once the new version is installed. The new version installs new configuration files and note that new configuration properties are supported in the virtual machine's configuration file. So make sure to check out the newly installed vm.cfg file before overwriting it with your own.

Start the setup program. It will start an installation program that will guide you through the steps to install the Brahms Agent Environment. The installation will install a minimum of six scripts/executables in the bin directory, one for the compiler (bc), one for the virtual machine (bvm), one for the Brahms Hosting Environment (HostingEnvironment), one for the Brahms Integrated Development Environment (Composer), and one to generate an encrypted password for use with SSL (encpwd). On certain platforms also a process manager and wrapper script/executable are installed.  The hosting environment, process manager, and password encryption scripts are used for the server component of Brahms to run Brahms models in distributed mode. For more information on running Brahms in distributed mode see the ReadmeDistributedVM file.

In the bc batch/script file two values have to be passed at a minimum, the first one being the library path, the second one being the source file to be compiled, it is highly recommended to also pass the DTD referencing the local file system for efficiency.

The installation software will automatically install the appropriate version of Sun's JRE 6, except on Mac OS X where the appropriate version of Java must already be installed (JSE 5.0) and be the default Java virtual machine. The virtual machine requires at a minimum JRE 5.

The various components use some configuration files. These files are generated during the installation and contain the appropriate default settings. The configuration files generated by the installation program are (depending on the chosen installation):

The configuration files contain comments on how to use or set their properties. Make sure to verify the vm.cfg, you might have to change your library path and/or working directory.

In order to use the compiler and virtual machine from other places on your machine, make sure to add the Brahms Agent Environment directory to your system PATH environment variable.

III. What's New

Fixed the following issues:

- Fixed an issue where a shutdown of the hosting environment could be initiated twice as part of the same shutdown cycle causing an improper shutdown order of components.
- Modified the deadlock monitor in the virtual machine to now dump a stack trace in the log file for all threads that are involved in a deadlock. This allows us to use the log information for deadlock analysis.
- Fixed an issue in the virtual machine in the way tokens with statements were processed in the reasoning state network. After testing an attribute node, the token first used to go to collection index nodes, then to object nodes for those statement without a collection index. However if the attribute was of a map type and both preconditions existed in which a collection index was used and where none was used (known/unknown) then residual matches from testing collection indices were still remaining causing potential VM exceptions to be raised. Now first testing object nodes after attribute nodes, then the collection index nodes.
- Fixed an issue in the collaborative infrastructure where it was possible for an actor to be shutdown more than once during a shutdown cycle. Now ensuring that while a shutdown is in progress any subsequent shutdown calls are no-ops.
-  Fixed an issue in the collaborative infrastructure in the reliable endpoints where stale endpoint connections would not be refreshed when attempting to communicate to that endpoint.
- Fixed an issue in the collaborative infrastructure with a concurrent access issue in the transmission of a DataRegistry by the DDS. We now clone the DataRegistry in a synchronized block prior to transmission. This allows the DataRegistry to be updated while the DataRegistry is being transmitted. Any concurrent update will be transmitted on the next publication.
- Added explicit search for file resources in the class path in the FileLocator utility class, before trying to use the resource loader provided by Java. Java's resource loader attempts to find files in directories not in the class path making it hard to impossible to control the loading of a file with a filename that can be found in multiple places, but of which only one can be found in the classpath.

The Agent Viewer now supports MySQL 5.0 as the database server to store and manage history databases. In addition the Agent Viewer now requires a user account on the MySQL server to make access to MySQL more secure and to eliminate the need for the anonymous user. For more details see the Agent Viewer Readme. It is now also possible to have a single MySQL server hosted on a different machine and to have different users use it to manage their history databases.

Fixed issues in using secure communications when running Brahms in distributed mode with secure endpoints configured for the transport and data distribution services. Added a connection pool to the transport layer to keep transport connections open instead of re-establishing a new connection for every communication.

Added new ConverterManager made available through the JAPI class. This ConverterManager can convert Java objects to Brahms objects and back. There are a couple of guidelines to follow to have the converter work properly:

  1. Only Brahms objects can be converted, not agents, conceptual objects, or areas.
  2. Java classes and Brahms classes that are converted to one another must have the same package and class names.
  3. Java classes to be converted must comply with the Java Bean specification, i.e. each property is identified by its getters and setters: get<Property Name>, set<Property Name> and for boolean values the getter is: is<Property Name>. In the Brahms classes the attribute/relation names must match the Property Names.
  4. Java classes for which no conversion is possible are ignored and not mapped to attributes of a Java type at the moment.
The converter converts the following special types:
  1. Instances of java.util.Map are translated to Brahms map type attributes.
  2. Instances of java.util.Collection containing non-primitive values are translated to Brahms relations with the name of the collection properties.
  3. Instances of java.util.Collection containing only primitive values or a mix of primitive values and Java objects are translated to Brahms map type attributes with the collection index serving as the key.
  4. Arrays containing non-primitive values are translated to Brahms relations.
  5. Arrays containing only primitive values or a mix of primitive values and Java objects are translated to Brahms map type attributes with the array index serving as the key.
  6. Java Enumerations are translated to Brahms symbols.
You can write and register your own converters in case you need to convert your classes in a different way than is supported. The ConverterManager accessible via the gov.nasa.arc.brahms.vm.api.JAPI allows you to register converter types and converters.
To convert a Java object to Brahms or vice versa:
  // create a conversion context (used to ensure that we
  // don't get into cycles with nested objects and don't
  // reconvert an already converted reference
  ConverterManager oCM = JAPI.getConverterManager();
  ConversionContext oContext = new ConversionContext();
  oContext.setBrahmsContext(getContext()); 

  // convert to Brahms
  MyJavaClass oJavaObject = ...
  IObject oConvertedBrahmsObject = oCM.toBrahms(oJavaObject, oContext);
  // clear the conversion cache
  oContext.clearBrahmsConverted();
  oContext.clearJavaConverted();

  // convert to Java
  IObject oBrahmsObject = ...
  MyJavaClass oConvertedJavaObject = (MyJavaClass)oCM.toJava(oBrahmsObject, oContext);
  // clear the conversion cache
  oContext.clearBrahmsConverted();
  oContext.clearJavaConverted();

For the converter manager we added a BrahmsClassDescriptor class (in gov.nasa.arc.brahms.vm.api.common) that allows you to wrap a Brahms class, obtain attributes/relations and have them cached and to allow you to easily get and set attribute/relation values. Relation values are set and returned using Collections. Map type attribute values are set and returned using java.util.Maps.

Removed the KAoS infrastructure used in previous releases for the transport layer when running distributed and that provided a directory service. The KAoS infrastructure is now replaced with the Collaborative Infrastructure (CI). The CI provides transport, directory, data distribution, management, time, and logging services. Brahms agents/objects are now made available as CI actors. We now have a distributed directory service that is used to register and lookup agents/objects. The single point of failure using a single naming and directory service has now been eliminated. The CI release now also provides an Actor Service Provider. The Brahms Hosting Environment wrapper for the VM now uses this ASP. Related templates have been modified (hosting environment, process manager) and an ASP template has been added.

Added a timems attribute to the Calendar class and the Calendar activities now generate a belief for this attribute with the time in milliseconds since epoch (January 1st, 1970, 00:00:00.000 UTC). The timems attribute will make it much easier to reason with time since that time is timezone independent and a single numeric long value that can easily be compared in preconditions.

Made a small modification to the JAPI. The getName method in IConcept no longer raises an ExternalException. The getName method was moved into IType.

Fixed an issue where with the use of the communication library the behavior of the VM would differ on subsequent runs when run from the Composer without restarting the Composer. Static variables would not be reset.

Added the activities:

to the:

These activities allow you to convert a string form of the primitive types into their actual types. The success return value indicates if the parsing was successful.

Updated the CI Process Manager with support for displaying a tray icon for the process manager in the System Tray (supported only on JSE 6 supporting platforms).

The previous release added an enhanced Agent Viewer that includes two new communication views used to analyze communications between actors. A start communication view and a directed communication view. These views are linked to the timeline view. For more information see the Agent Viewer's readme.

In addition to the Composer as a Brahms IDE we now also publish a Brahms Eclipse plug-in. See the download page for instructions on how to download and install it.

Added support for serializing (conceptual) objects when running Brahms in distributed mode by introducing the SerializableObject in the Brahms base library. If a class/object extends/is an instance of the brahms.io.SerializableObject class then those instances or instances of those classes are marked as serializable(provided they and/or any of their parents don't declare any frames). The compiler will generate a warning if such a class/object declares any frames (including if frames are declared for any of the parents). In that case the class/object cannot be serializable. All conceptual classes/objects are by default serializable. Any serializable concept is *not* registered in the directory service. When beliefs are communicated to a remote actor in a remote Brahms VM any references to serializable concepts result in the serialization of that concept and causes those serialized concepts to be attached to the communication. Serialization means that a concept is stringified encoding its fully qualified name, type of concept, the fully qualified name of its parent and the list of beliefs held by that concept (in case of an object, not in case of a conceptual object). On receipt of a communication all communicated beliefs are recreated. Any references to serialized concepts result in the deserialization of those concepts. This means that the VM will check whether a concept with that qualified name already exists in the model, if not it will create it and populate it with the serialized beliefs, if the concept did exist then its belief set is updated with the beliefs that were transmitted as part of the serialization. The object identities will be considered the same for both concepts in the source and destination virtual machine.

The Brahms Agent Environment now supports a delete operation that can be invoked for agents, objects and conceptual objects that are created at runtime/simulation time. The delete operation allows the modeler to reclaim memory for those objects and associated information maintained in the Brahms virtual machine. The language specification included with this release provides details on how the delete operation works.

The Brahms Agent Environment now includes a communications library allowing modelers to formalize the agent communications using structured messages defined as objects that are instances of the brahms.communication.CommunicativeAct class. This class uses the new map attribute type to specify an envelope and payload for the message each containing a set of attribute/value pairs. The brahms.communication.Communicator group specifies a set of activities to create, manipulate, read, send and retract the CommunicativeAct. The language specification has been modified to now permit the declaration of a CommunicativeAct as the contents of a transfer definition in a communicate activity. A transfer definition still allows you to define a condition that is to be matched to the beliefs that need to be transferred. When a CommunicativeAct is declared the Brahms virtual machine will retrieve all beliefs in the belief set of the CommunicativeAct and transfer those beliefs to the recipient defined in the communicate activity. The virtual machine ensures that the 'enveloper("sender")' belief is always received last by the recipient to allow the recipient to wait for all beliefs to have been received by testing for the availability of this sender belief. The Brahms Agent Viewer has been updated to now show communications of these CommunicativeActs. The communication lines in the agent viewer now show each CommunicativeAct as 1 message and does not show each belief inside of the CommunicativeAct as a message if the transfer definition was a condition it will still show each belief that was communicated as a message. Opening the contents of the communication shows the beliefs that were transferred.

As part of the communications library the Brahms Agent Environment now includes an abstract external agent implementation that hides most of the complexities for having external agents interact with other agents using CommunicativeActs. The class to extend is brahms.communication.AbstractCommunicationAgent. It handles memory management for CommunicativeActs and supports both simulation and real-time modes. See the class documentation for more details. 

IV. Known Problems

  1. Compiler: All brahms files need to have the extension '.b'. The Brahms Compiler will not be able to find imported files that have other extensions like for example '.txt'.
  2. Virtual Machine: The distributed virtual machine does not yet distribute the areas. All areas must therefore remain local on each virtual machine they are references. This will also result in agents  running in different virtual machines not being able to automatically detect one another when in the same area. 

V. Revision History

The revision history for the Brahms Composer, Agent Monitor, Agent Viewer, Compiler and Virtual Machine can be found in the file named Changes.

VI. Important Notes

  1. To run the Brahms Agent Environment installer and the Agent Environment components on Mac OS X you must install JSE 5.0 from Apple and make it the default Java virtual machine for your OS X. The installer will not function correctly and the components will not function at all if JSE 5.0 is not installed and is not the default Java virtual machine.
  2. This new version can cause problems when compiling models that use a non-approved base library with custom added attributes. These models are required to be updated in order to use them with this version. The best way to update those models is to create model specific base classes that will automatically inherit from the base classes and in which the model builder specifies any customizations that were made to the base classes. The base library is included in the installation and can be found in the Models directory. Make sure to have this base library available in your library path when compiling your models.
  3. If you use external activities or external agents as part of your Brahms models, make sure to package them up as jar files using Sun's jar tool and place the jar files in the AgentEnvironment\deploy directory. The compiler and virtual machine will in that case be able to find those external activities and agents, not placing them in that directory will cause the compiler and virtual machine to generate errors that they are unable to find the appropriate class files. If you wish to place these jar files into a different directory make sure to update the bc and bvm scripts to include them in the classpath/extensions directories.
  4. The Composer is able to reload Java classes from Java archives for external activities and external agents when running the compiler multiple times, allowing you to drop updates of these archives in the Agents directory and recompile the model with the updates. However the virtual machine is not yet capable of doing this. So if you need to rerun your model with updated Java archives you must restart the Composer if you want to run the virtual machine from the Composer.

VII. Contacting the Brahms project team for Technical Support

In case you have problems with the installation or questions and problems with the use of the Brahms Composer, Agent Viewer, Compiler or Virtual Machine you can reach Technical Support at:

E-mail: support@agentisolutions.com
www: http://www.agentisolutions.com/support/support.htm

Thank you for trying the Brahms Agent Environment. We hope you find it useful in your modeling and agent development efforts.

Sincerely,

The Brahms Development Team