Changes in 0.11.0

Release date: 2020-05-31.

1. Major Changes

Number of major changes: 4.

1.1. Janus version 3

Janus is the official SARL run-time environment (aka. SARL virtual machine). This release of SARL provides a MAJOR NEW IMPLEMENTATION of Janus with its version 3.

In the past, the change from version 1 to version 2 was due to a total re-implementation of Janus in order to follow and support the SARL metamodel. This time, Version 3 of Janus is a total re-implementation with the SARL language, i.e. we have written the code with SARL not anymore with Java.

The major benefits of the new implementation with the SARL language are:

• Direct usage of the SARL concepts and statements;
• Ability to generate the same SRE to different target platforms (Java, Python, etc.);
• Proof-of-concept related to the capabilities of the SARL language to cover complex application’s implementation.

In addition to the total re-implementation with SARL language, the software architecture of Janus was re-thinking and optimized in order to improve the global run-time performances of the SRE, and to be more modular in order to extend modules of Janus with new third-party modules (based on Bootique modules).

1.2. New types of participants in spaces

From the SARL metamodel, spaces are entities in which the agents are able to interact or communicate. The agents that are part of a space are named participants.

From our experience during the past years, different types of participants may be involved into a space. First, the agents constitute the largest part of these participants. Second, external software, such as an graphical user interface (GUI), may have to listen for events or emit them into a space in order to setup an interaction with the agents.

Nevertheless, having only a single type of participant defined causes issues into the SARL run-time environment (SRE) when it is time to decide if a space should be destroyed or not. Indeed, the SRE is in charge of destroying the spaces when they are not used anymore (usually when there is no more agent inside).

A problem occurs when all the agents have leaved the space, and only GUI remain. In this case, the SRE was not able to detect this case and to destroy the space. This issue could be seen because the SRE never stops to run, even when all the agents were killed.

In order to solve this issue, two types of participants are defined:

• Strong Participant: it corresponds to the regular meaning of a participant (and the default one). When a strong participant is involved into a space, the SRE cannot destroy the space. Typical strong participants are the application agents.
• Weak Participant: it is a participant that is considered as optional by the SRE. In other words, when a space has only weak participants, it is considered as releasable by the SRE. Typical weak participants are GUI objects.

Whatever the type of participant, they have the same level of abilities for using the space. For example, in the case of an event space, the strong and weak participants have all the abilities to emit events, and receive them.

1.3. New agent spawning API

The spawning functions of the agents have encountered a big change: they are not replying anymore the unique identifier of the just spawned agents. Now, the spawning functions return void.

This change was forced by the need to execute in parallel the different spawning processes when multiple agents are spawned at the same time. In this case, it is almost impossible to retreive the unique identifiers of the agents before returning from the spawning function.

In order to use the unique identifier of the just spawned agent after the call to the spawning function, the new guideline is to generate the identifier, give it to the spawning function, and use it after, as illustrated by the following example:

var agentIdentifier = UUID::randomUUID
typeof(MyAgentType).spawnInContextWithID(defaultContext, agentIdentifier)
doSomething(agentIdentifier)

1.4. New tool for SARL contributors: an Eclipse DSL with embedded SARL

In past, it was not so easy to install and set-up an complete and working development environment for the SARL contributors. It was due to the usage of different technologies such as Eclipse DSL, Java, Maven and Xtext.

In order to have a ready-to-use environment, as much as possible, a specific Eclipse product is now available into the SARL project: sarl-dsl. This new product includes:

• Regular Eclipse framework for domain specific language implementation, that includes:
  • Eclipse environment,
  • Java development environment,
  • Maven integration into Eclipse, and
  • Xtext libraries;
• SARL compiler integration into Eclipse;
• Janus run-time environment;
• Eclipse Checkstyle.

2. Detailed Changes

2.1. SARL Language

2.1.1. SARL Language Grammar

• Add specific Java cast into the generated Java code for avoiding compilation error (1, 2).
• Remove any reference to Eclipse JDT from io.sarl.lang module (1, 2).
• Change the generation of hashCode and equals to avoid null pointer exception when running them into the SRE (details).

2.1.2. SARL Core Library

• All:
  • Removing all locks and synchronized collections (1, 2, 3, 4, 5)
• Spaces:
  • Add the concepts of strong and weak participants into the spaces (1, 2, 3, 4). Both of these types correspond to participants into a space. When a space has at least one strong participant, it cannot be destroyed and removed from the ststem. When a space has only weak participants, it could be removed from the system. A typical strong participants may be a regular agent. And, a typical weak participants may be an user interface that is interacting with agents.
  • Remove the deprecated spaces implementation (details).
• Bootstrap:
  • Add observer on the SRE start and stop (details).
  • Remove the function getBootAgentId from the SARL programmatic bootstrap (details).
  • Add a timeout parameter to the shutdown function of the SRE bootstrap (details).
• Events:
  • Fixing the invalid value for the field parentContentId of the MemberJoined event (details).
  • Fixing the invalid value of the Memberleft source (details).
• Agent:
  • Add the function setSkillIfAbsent into the Agent API (details).
  • When the skill references were cleared from any part of the agent, the getSkill function of the agent does not thrown UnimplementedCapacityException exception anymore (details).
  • Updating skill management with a conccurent set/queue instead of a non-thread safe implementation (details).
• Skill:
  • Tuning the skill uninstallation process to prevent null pointer exception (details).
  • Introduce a new class for representing a skill containe, and update the skill lifecycle accordingly (details).
• Agent Tasks:
  • Force the agent tasks to have a not-empty name (details).
  • Tuning the every tasks stopping process (details).
• Address:
  • Rename the field agentId to participantId into the Address class (details).
• Others:
  • Make as volatile the field that may contain internal SRE data into the SRESpecificDataContainer class (details). This change enables a better synchronization of the attached SRE data’s field when it is accessed from multiple threads.
  • Make the ClearableReference atomic (details).

2.2. SARL Development Toolkit (SDK)

2.2.1 Core Library

• Remove the returned addresses from the spawning functions (details). The spawning functions are now returning nothing. It means that it is not any more possible to retrieve the UUID of a just spawned agent from the spawning function itself. A better practise is to computer the UUID before calling the spawning function, and pass the UUID to this function.

2.2.2 Utility Library

• Remove deprecated classes (details).

2.3. SARL User Interface

2.3.1. UI Components

• General:
  • Avoid to reply extra-language output configurations from the project’s preferences when the general SARL output configuration is requested (details).
• Module eclipse-slf4j:
  • Create the Eclipse bundle eclipseslf4j that provides a correct integration of SLF4J (old API version and new API version) into the Eclipse product (1, 2).
  • Use the SLF4J API for formatting the messages intead of Java API (details).

2.3.2. Eclipse Product

2.3.2.1. Launching Configurations

• Rename StandardSREInstall to ManifestBasedSREInstall (details).
• Update the run configuration in order to show the SRE command line options into the wizard (details).

2.3.2.2. UI Components

• Fixing the splash screen (1, 2, 3).

2.3.2.3. Wizards

• New Project:
  • Avoid null pointer exception when creating a new empty project (details).
  • Add support for test generation folder (details).
• Code templates:
  • Do not add extends Object into the class’s code template (details).
  • Add the function prepareUnistallation into the code template of the skills (details).
  • Remove 32bit platforms from the template (details)
• Export to runnable Jar:
  • Restrict the selectable launch configurations to the selected projects when exporting to a SARL runnable JAR (details).
  • Disable the “export into runnable JAR file” for an ‘SARL Agent’ launch configuration (details). In other word, it will not be possible to generate a runnable Jar based on the launch configuration of an agent. It is possible to create a runnable jar from a ‘SARL Application’ launch configuration.

2.3.2.4. Maven Integration in Eclipse (m2e)

• Support of Eclipse bundles:
  • The m2e connector supports the Eclipse Bundle projects (details).
  • When compiling a SARL project that is also an Eclipse plugin, the m2e plugin should apply a specific compilation sequence to properly compile the project (details).
• Test source code in SARL project:
  • Goal testCompile is defined into the Maven plugin for SARL. This goal was missed into the m2e plugin, and it is added by this commit (1, 2).
• General changes:
  • Rename StandardSREInstall to ManifestBasedSREInstall (details).
  • Change the configuration of the source folders (1, 2).
  • Delete any previous declaration of the source folders prior to its addition into the classpath (details).

2.4. External Contributions to SARL

2.4.1. Examples

• Fixing the syntax errors due to the recent changes in the spawning and space API (1, 2).
• Add a test about the specification of the wizard classname into the file plugin.xml in order to validate that the provided classname exists (details).
• Add the missed injection factory for the Boids example (details).
• Add the launch configuration for the Boids example (details).
• Enable compilation on OpenJDK 8 (details).
• Do not specify in hard-coded constant the command line for launching maven tool (details).
• Sovling the bug in Ping-Pong demo where an event was not correctly sent due to a problem of weak reference (details).

2.4.2. Experience Index Plugin

• The project structure of io.sarl.experienceindex.plugin is rearrange to fit the SARL standard (details).

2.5. Janus Run-time Environment

2.5.1. General

• Janus 3 is released and included into the SARL framework (1, 2, 3, 4, 5). Janus 3 is fully implemented in SARL. This new SRE was the result of the redesign of the previous version of Janus in order to obtain better performances and stability.
• Remove references to Hazelcast and ZeroMQ (details).
• New function is provided to shutdown the whole kernel (details).

2.5.2. Event Spaces

• Creation of a factory for the space specifications (details).
• The abstract implementation of the event spaces has been fixed in order to really remove a participant to a space when its event listener is unregistered from the space (details).
• Ensure that a event listener is not registered as weak and strong participant to a space (details).
• Add configuration for the space repository (details).

2.5.3. Events

• Parallel execution of the “on” handlers is now done through the agent’s InternalSchedules capacity: in EventBus, the ad-hoc implementation is replaced by calls to the executeBlockingTasks function of InternalSchedules capacity (1, 2).
• Move the guard evaluator into the SRE internal package from the io.sarl.util module (details).
• Correcting the bug preventing ParticpantLeft to be fired in the default space of the default context. The particular case of the default space of the default context haven’t been managed, since it is the first space created its parent (1, 2).
• Fixing the invalid emitting of ParticipantJoined events (details).
• Fixing the source of the MemberLeft and MemberJoined events (details).
• Fixing implementation of and calls to BehaviorGuardEvaluatorRegistry (1, 2, 3)
• Tuning the function compareTo into the BehaviorGuardEvaluator and the management of the registry concerning inherited ancestors methods (details).
• Fixing the filtering of the event handlers when dispatching events (details).
• Avoid the use of Java streams for looping (details).

2.5.4. Tasks

• Set the default maximal number of threads to 512 (details).
• InternalSchedules capacity provides the executeBlockingTasks function (details).
• Changing the conditions to stop a task by testing if the task was registered previously (details).
• Changing Task ID generation to save performances: Adding a specific uuid generator in place of the standard Java generator because it is too much time costly (1, 2, 3).
• Homogenizing task execution, generalizing the use of SRERunnable (details).
• Removing ThreadExecutorService’s purge that was too costly (details).
• Correcting exception management in Janus boot that was preventing some exception to be seen (details).
• Start the thread pool purge depending on the executor configuration when shuting down the executor service (details).

2.5.5. Skills

• Re-implement DynamicSkillProvider classes to create skills and not install them (details).
• Do not uninstall the same skill multiple times when it registered for mutiple capacities (details).

2.5.6. Agent Lifecycle

• Multiple agent spawning is now run in parallel for each agent (details).
• Avoid null pointer exception on the event bus listener when stoping the agent (details).
• Schedules and EventBus skills must be released after all the other skills (details).
• Change the prototype of the protected spawnAgent function (details).
• Adding a double lock in agent spawn function. It fixes a bug where the number of effectively spawn agents was different than the number of spawn calls (details).
• Changing weak reference to normal reference in order to avoid null pointer exception: AgentLife (1); ScheduleSkill (2).
• Add the output of warning messages when an agent cannot be killed (details).
• Rearrange the code of the dying stage in order to be consistant with the expected agent state (details).
• Avoid the skipping of the agent stopping process when an exception occurs in on Initialize (details).

2.5.7. Probe Service

• Avoid synchronization problems into the probe service (details).
• Avoid NPE in probe service when the agent is not yet alive (details).
• Add findObject functions with string of characters as parameter for representing the URI (details).

2.5.8. Logging Service

• The SRE loggers are now named (details).
• Move all the JUL implementation into a dedicated package (details).
• Rearrange JUL to uses the proper formatting (details).

2.5.9. Infrastructure

• General:
  • Update of the SRE main that was actively waiting the termination of all running commands before do a system exit. The active wait has been removed as well as the system exit (details).
  • Shutdown of the SRE is killing agents asynchronously (details).
  • Add a timeout parameter to the shutdown function of the SRE bootstrap (details).
  • Apply GNU standards regarding the naming of the CLI options (details).
  • Add the lifecycle configuration command line option --Xinjectagents (details).
  • Provide the Janus command-line options to the Eclipse wizards (details).
• Windows Operating System:
  • Fixing issue on Windows operating system when there are spaces in the path of the SRE (details).
• Networking:
  • A first implementation of the networking module of Janus 3 is added into the source code repository (1, 2, 3). This module is not yet activated and included into the SARL products because it is still under development and testing.

2.6. Maven Tools

2.6.1. SARL Batch Compiler

• Move the batch compiler from the io.sarl.lang Eclipse plugin into the io.sarl.maven.batchcompiler module. (1, 2).

2.6.2. Maven SARL Compiler

• Add the support of the skip flag and of the system property maven.test.skip in order to enable or disable the tests that were written with SARL (1, 2).
• The version of the Maven compiler (linked to Java compiler) is injected from the pom configuration into the Java code of the maven-sarl-plugin module (1, 2).
• Updating pom file to prevent tycho compiler from being executed before the sarl compilation (details).

2.6.3. JavaFX Module

• Enable the JavaFX UI controller to emit an event into the dedicated communication space (between the JavaFX UI and any application agent), and to emit an event into the global communication space (shared by all root agents) (details).
• Remove the returned addresses from the spawning functions (details).

2.6.4. Bootique Utilities

• Enable the overriding of the bootique “version” command by moving the most usefull peace of code into protected functions (details).

2.7. Command-Line Tools

2.7.1 sarlc

• Apply GNU standards regarding the naming of the CLI options (1, 2).
• Force the use of version 2.10 of Jackson lib (details).
• Fixing errors in the help text (details).

2.7.2 sarldoc

• Fixing errors in the help text (details).
• Fixing code for passing tests (details).

2.7.3 VIM Syntax Highlighting

• Add the link to the vim Operator syntax color (details).

2.8. SARL Documentation

2.8.1. Documentation of the SARL Language

• Add the CIAD’s CI badge into README file (details).
• Fixing the generation of the Javadoc (details).

2.8.2. Documentation of the SARL Core Library

• Fixing the javadoc generation in order to generate it for all the bundles published on Maven Central (details).
• Move the properties files within JavaFX Maven project to be included into the Jar file (details).
• Fixing the code in order to fullfil the changes in the SARL API (1, 2, 3, 4).
• Remove the references to the restricted spaces (details).
• Tuning the documentation on the newly introduced concept of weak/strong participants of a space (details).

2.8.3. Documentation of the Janus SRE

• Fixing the documentation of Janus (details).

2.8.4. Documentation Generators

• Fixing the generation of the section heading keys into the documentation in order to be parsable by a Markdown transcoder (details).
• Update the name of the tests to see the name and path of the tested page (details).

2.9. Tools for SARL Contributors

2.9.1. Coding Convention and Changes

• Using ConcurrentMap interface instead of its implementation (details).
• Updating and improving the code of evaluateGuard when a single evaluator is present, that represents a lot of cases (1, 2).
• Converting a weak reference into a normal one into the SRE’s AgentLife in order to avoid null pointer exception (details).
• Using the Java path separator instead of an hard-coded : when building paths (details).

2.9.2. New Eclipse DSL with embedded SARL

• Create a specific product that is dedicated to the SARL contributors. This Eclipse DSL product for SARL includes Eclipse, Java, Xtext, and SARL (1, 2, 3, 4)

2.9.3. Regular SARL Eclipse Product

• Remove references to local folders into the templates of Eclipse preferences (details).
• Removing all the product customizations that were specific to sgalland (details).

2.9.4. Generic User Interface

• Re-enable the tests of the formatter’s facade (details).

2.9.5. Tests

• Upgrade JUnit to version 5 (details).
• Enable Surefire to display the value of DisplayName for tests (details)
• Deep cleaning of the tests (1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22).

2.9.6. Continuous Integration

• Fixing the release scripts for CI (1, 2, 3, 4, 5, 6).

2.9.7. Dependencies

• Upgrade to Eclipse 2019-12 (details).
• Remove references to SLF4J when it is not mandatory by code (details).
• Upgrade to Xtext 2.20 (details).
• Updating mockito version (details).
• Updating target platform to integrate Janus v3 new p2 dependencies from arakhne (details).
• Remove logback dependencies (1, 2).
• Updating dependencies and provided packages (details)
• Updating checkstyle version, config and adapting the code to respect new introduced rules (details).

3. Changes in the Previous Versions

• Changes in the version 0.10.1