Release 0.12

20 views
Skip to first unread message

Stéphane Galland

unread,
May 28, 2021, 2:41:10 AM5/28/21
to sarl

1. Major Changes

Number of major changes: 4.

1.1. Enable static and instance features in the parameters' default values

SARL allows you to specify a default value for a formal parameter of a function or a constructor. When a default value is specified, it means that the caller of the action can skip passing a value for the corresponding argument. And, when the function is called, the default value is given to the skipped argument.

Up to the version 0.11 of SARL, the expressions that constitute the default values must reference static or constant expressions, and these features must not have border effect.

Since the version 0.12 of SARL, the first restriction is no more applied. Consequently, the default value expression could reference either static and instance features (1, 2). The constraint on the feature's border effects is still valid.

For example, the following code is valid in SARL:

agent A {

    var aField : int

    def aFunction(p : int = aField) {
    }

}

It means that the value of the p parameter is the value of the aField field when the aFunction function is invoked.

1.2. Add "abstract" into the modifiers for events

The abstract modifier is added into the list of the accepted modifiers for a SARL event (details). For example, the following code defines an abstract event with name A:

abstract event A

An abstract event is an event that cannot be instantiated, but it can be derived. When an abstract event is derived, the subtype usually provides constructors that are compatible with the super type's constructor.

1.3. Agent Error Handling

In SARL, as for the Akka actor framework, there is an important distinction between failures and validation errors:

  • A validation error means that the data of a command sent to an agent is not valid, e.g. an unexpected event according to a communication protocol. This should rather be modelled as a part of the agent protocol than make the agent throw exceptions.
  • A failure is instead something unexpected or outside the control of the agent itself, for example a database connection that brokes. Opposite to validation errors, it is seldom useful to model such as parts of the protocol as a sending agent very seldom can do anything useful about it.

In order to make the agent able to react to failures, the SARL API defines a specific event that is representing any failure or validation error that the agent could handle if it is interested by: Failure. Each time an agent needs to be notified about a fault (into its agent tasks for example), an occurrence of this event type is fired in the internal context of the agent.

Several failure events are pre-defined in the SARL API:

  • AgentKillFailure: when the agent killing cannot be realized (the major cause of a killing failure is the fact that the agent to be killed contains sub-agents).
  • TaskFailure: when an agent task (managed by the Schedules capacity) has failed.

Also, the AgentKilled event has been updated in order to provide the cause of the agent's killing.

Finally, the SARL API provides tools for propagating failures in the hierarchy of agents, to the parents and to the children.

1.4. Agent Observation and Probing

The multi-agent system is composed of multiple elements, including agents, behaviors, contexts and spaces, but not limited to. Organizational models in multi-agent systems usually position agents as actors-observers within environments shared by multiple agents and organizational structures at different levels of granularity. Then, the agents may have the capacity to observe the environment and the other agents, without directly interacting with them. The observing agent is able to extract information from another agent or from a society of agents, that could be opaque according to a possible holonic architecture of the system.

Observation means that data or information could be extracted from the observed object without filtering from this latter. The observer is not intrusive from the agent point of view. In other words, the observed agent has no knowledge about the fact it is observed or not. In this case, it cannot adapt its behavior on its observation status.

An observation mecanism was defined into the Janus SRE. Since the version 0.12 of SARL, this observation mecanism is moved into the SARL SDK and transformed as an API that is independent to the SRE (1, 2, 3). In the same set of commits, the naming service for the multiagent system components has been moved from the Janus SRE to the SARL DSK.

Because an agent is defined as an autonomous entity, the agent is supposed to be able to specify if a part of itself is observable or not, i.e. to specify the access rights to its fields. The concepts of "observable" and "not observable" field are introduced in SARL 0.12 (1, 2).

This observability flag could be defined statically by annotating the observable field, or one of its enclosing type, with the @Observable annotation. The second method is to implement a dedicated agent skill implementing the capacity FieldAccessValidationCapacity that enables the agent to manage the access rights to its fields dynamically.

2. Other Changes

2.1. SARL Programming Language

2.1.1. SARL Language

a) Detection of pure functions
  • The following function names are considered as standard names for pure functions (1, 2): abs,acos, cos, asin, sin, atan, atan2, cbrt, ceil, compare, compareTo, cosh, empty*, exp, floor, hypot, log, log10, log1p, max, min, pow, random, rint, round, signum, signh, sqrt, tan, tanh, ulp.
  • The functions toString(JsonBuffer) was marked as pure but it has border effects. The Pure annotation is removed from the function (details).
b) Detection of immutable objects
  • SARL compiler knows that objects of specific types are immutables, i.e. they cannot be modified. This immutability of objects is used in order to determine if an code expression has border effects or not, and possibly generate an error message when a border effect cannot be accepted.
  • The following types have been added into the list of the immutable types (1, 2): Annotation, Boolean, Byte, Character, Clock, Double, Duration, Event, Float, Instant, Integer, LocalDate, LocalDateTime, Long, MonthDay, OffsetDataTime, OffsetTime, Pair, Period, Permission, Short, Year, YearMonth, ZoneDataTime, ZoneId, ZoneOffset.
  • Any type that is marked with the @Data annotation is implicitly considered as immutable (details).
c) Automatic object conversions
  • An Unique Universal IDentifier (UUID) may be represented by a string of characters or by an instance of the SARL/Java type UUID. The SARL compiler is able to do an automatic conversion from a string of characters to UUID, and from an UUID to a string of characters (details).
  • The SARL compiler is able to do an automatic conversion from a string of characters to a number and from a number to a string of characters (details).
d) Annotations of code
  • Add the annotation @SarlAsynchronousExecution into the language API in order to help the SARL editor to show up the calls to functions that are run asynchronously (details). This annotation has no effect at run-time by itself. It is only a marker for the SARL code editing purpose.
  • Replace the annotation @IssueOnCall by @ErrorOnCall, @WarningOnCall and @InfoOnCall (details). These annotations are used by the SARL compiler for generating an error, warning or information message when the annoted feature is invoked.

2.1.2. SARL Validator

  • Generate an error when a generic-type parameter is hiding another generic-type parameter (details).
  • Do not warn if a called feature on occurrence is considered as an immutable object (details).

2.1.3. Java Model Inferrer

a) Polymorphic event dispatching
  • Event dispatching mechanism is an internal tool that enables to reproduce the operational semantic of the on behavior units in a Java program. The original event dispatching mechanism (that becomes the default mechanism) is based on Java reflection. For each on behavior unit, an hidden Java method is generated. This method is called by reflection when an event should be dispatched.
  • Add a novel event dispatching mechanism based on polymorphic method calls (details). Hidden polymorphic functions are generated into the Java code in order to dispatch the event along the full object hierarchy. This new event dispatching mecanism is available into the API and could be activated into the Janus SRE configuration.
  • Add the hidden function '$isSupportedEvent' in the generated Java code (details). This function replies if the object contains a behavior unit for the given event that could be invoked with the polymorphic event dispatching mechanism.
b) Value casting
  • Generate a valid Java code when a null value is casted, e.g. null as Type (details).
c) Automatic annotations
  • Create the annotation @Injectable for types for which fields should be injected according to the inversion of control design pattern. This annotation is automatically added by the SARL compiler when the @Inject annotation is found into a type declaration (details). This annotation may be used by the SRE for managing the injection of the objects when it is needed.
d) Bug fixes
  • Do not generate the local/anonymous classes in the constructor code in order to avoid inconsitencies into the generated Java code (details).
  • Add a Java cast operator to the returned value of the synthetic functions for the default-valued parameters in order to avoid Java type conversion error (details).
  • Update the processor of the @Accessors annotation for adding the variadic parameter marker (...) to the setter functions when it has been found in an inherited prototype (details).
  • Avoid internal NPE into the JVM model inferrer (details).

2.1.4. SARL Core Library

  • Deprecate the function register in the Space type, and provide the functions registerStrongParticipant and registerWeakParticipant (details). These functions permit to make a difference between a strong participant and a weak participant. A space could be destroyed only if there is no more strong participants inside. If a space has only weak participants, it could be destroyed.
  • Rename the functions with the name getUUID to getID accross the entire API (details).
  • Major bug fix in the dynamic skill creator attached to the @DefaultSkill annotation (details). This creator generates a NPE whatever the capacity or skill.
  • The interface SREBootstrap provides tools for starting the SARL run-time environment programmatically. Several functions were added in this interface for starting the run-time environment as it is started from the command-line (details): setCommandLineArguments(String[]), startWithoutAgent(boolean).
  • Make cloneable the types Address and SpaceID (details).

2.1.5. SARL Formatter

  • Into the LaTeX style, add the macro \ignorespaces at the end of the macro\code (details).

2.1.6. SARL Batch Compiler

  • Since Java 11, the classpath is no more the single way for specifying the Java libraries to be loaded into the program. Indeed, the introduction of the Java modules in the Java specification causes the creation of a "module path". This module path specifies the list of the Java libraries that must be loaded as modules. In order to be used with a version of Java that is higher than or equal to 9, the SARL compilers (batch compiler and embedded in Eclipse) supports both the classpath and the module path, depending on the version of the Java execution framework that is used (details).

  • According to the SARL toolchain, the SARL compiler generates Java code. Then, this Java code is compiled by a standard Java compiler. Two major standard compilers are available: Eclipse compiler (a.k.a. ecl or Java Development Toolkit - JDT), and Oracle compiler (a.k.a. javac). Up to the version 0.11 of SARL, the JDT compiler is used by default. In order to prepare future move from the version 8 to the version 11 of Java, javac becomes the default Java compiler (details). Indeed, this compiler provides a complete support of the Java 11 (or higher) specifications.

  • Environment variables are now supported by the Maven-based batch compiler, a.k.a. maven-sarl-plugin (details):

    • maven.test.skip: it is an environment variable that is already know for Maven plugins. maven-sarl-plugin disables all the tests when this variable is set to true.
    • sarl.test.skip: same effect as maven.test.skip.
    • sarl.compile.skip: when this environment variable is set to true, maven-sarl-plugin does not run the JVM element generator, SARL validator on the SARL source code, and does not run the Java compiler on the generated Java code.
    • sarl.jvminferrer.skip : when this environment variable is set to true, maven-sarl-plugin does not run the JVM element generator, SARL validator on the SARL source code. The other components of maven-sarl-plugin are run, e.g. the Java compiler.
    • sarl.clean.skip: when this environment variable is set to true, maven-sarl-plugin does nothing at cleaning stage.

    All these environment variables must be defined from the shell command line, or with the -D option of the maven tool.

2.2. SARL Development Toolkit (SDK)

2.2.1. Agent Context

  • Add the function isRootContext() into the AgentContext type in order to determine if the agent context is the root context or not (details).

2.2.2. Agent Behaviors

  • The Behavior type permits to specify an agent behavior. The life-cycle of a behavior is enhanced in order to have callbacks when the behavior is installed into and uninstalled from its agent (details):
    1. Behavior construction: the construction function of the behavior is invoked in order to create the behavior in the computer memory.
    2. Behavior registration: the behavior is registered into the agent with one of the functions of the Behaviors capacity. Then, the protected function install() of the behavior itself is invoked.
    3. Behavior initialization: the on Initialize handlers of the behavior are activated.
    4. Behavior's life
    5. Behavior unregistration: the behavior is unregistered from the agent with one of the functions of the Behaviors capacity. Then, the on Destroy handlers of the behavior are activated.
    6. Behavior uninstallation: the protected function uninstall() of the behavior is invoked.
  • Add two wake functions for waking up a specific agent behavior that is passed as argument (details). These functions enable to provide an event to a specific behavior, and this event it provided neither to the other behaviors nor the agent itself.

2.2.3. Agent Skills

  • The Skill type permits to specify an agent skill. The life-cycle of a skill is enhanced in order to have a callback when a skill is installed into its agent (details). This callback function may be defined and provided by the SRE's implementation in order to react to the installation of a skill into an agent.

2.2.4. DefaultContextInteractions Capacity

  • In order to make easier the interaction between an agent and its parent agent, several functions are added (details): getDefaultParentID, getDefaultParentScope, emitToParent.

2.2.5. Lifecycle Capacity

  • Add the function spawnWithID(type, id, parameters) in the Lifecycle capacity in order to spawn an agent with a given identifier into the default context (details). This function complements the existing function spawnInContextWithID(type, context, id, parameters) that needs to give the receiving agent context and the identifier.
  • The killMe(cause) function takes the cause of the agent killing. Before SARL 0.12, this reason must be of type Throwable, that indicates the cause is an error. Since SARL 0.12, the cause of the killing becomes of type Object (details). It enables to provide a killing cause that is not an error from the computer programming point-of-view.

2.2.6. InnerContextAccess Capacity

  • Add the function getInnerDefaultSpace into the InnerContextAccess capacity (details). This function is an helper for obtaining the default space of the inner context of the agent.

2.2.7. ExternalContextAccess Capacity

  • Replace the returned value of the join function from boolean to AgentContext (details). The agent is now able to access the joined agent context directly after joining it.

2.2.8. Naming API

  • Move the naming API from the Janus SRE to the SARL SDK (details).
  • Add the support for the observability of fields (details). See the description of the major changes above for details.
  • Remove the NameScheme enumeration in order to add new schemes from API extensions (details).

2.2.9. Coding Style with the SARL SDK

  • Replace all the direct references to the implements of concurrent collections to equivalent interfaces (1, 2, 3).

2.2.10. New Modules

  • Create the module io.sarl.api.bootiquebase (details) that provides the abstract types for implementing a bootique-based application. Bootique is a library for launching and configuring an application.

2.3. SARL User Interface

2.3.1. UI Components

  • When a method call cannot be resolved and linked to a method implementation, an compilation error is output. The called method could be provided by a capacity that is not "used" in the SARL code. Add a quick fix that automatically adds the statement uses for the relevant capacities that are providing the missed method (details).
  • In the SARL editor, display with a specific style, the names of the functions that were marked as asynchronuous (1, 2). According to the specification of SARL, these functions are supposed to be run in parallel to their callers, e.g. emit an event. In order to help the editor to show up this specific status of these functions, they are annoted with the @SarlAsynchronousExecution annotation.
  • In the SARL editor, a code (mining) decoration that shows up the names of the formal parameters just before the values that are passed to a function call (details). For example, if the function f(a : int, b : String) is defined, and in your code you have the call f(5, "a"), then this call will be displaye by the editor as f(a:5, b:"a") in order to show the names of the arguments to you.
  • Display an error message when the code mining mecanism has crashed (details).
  • Fixing the NPE when accessing the Eclipse platform logger (details).
  • Deprecate the eclipse-slf4j module (details).

2.3.3. Eclipse Product

c) Launch Configurations
  • In the launch configuration of a SARL agent or a SARL application, the classpath provider was implemented for supported the classpath only. It is the standard mechanism for Java applications up to Java version 8. Since the version 9 of Java, modules are introduced, as well as a specific module-path for the specification of the modules' libraries. The previous implementation of the SARL classpath provider did not support the module-path. It is fixed in SARL 0.12 (1, 2, 3).
  • In the launch configuration of a SARL agent or a SARL application, a combo box is added in order to select the log level of the run application (details).
  • In the launch configuration of a SARL agent or a SARL application, a check box is added in order to enable or disable the printing out of the launching arguments on the Eclipse console (details).
  • In the launch configuration of a SARL agent or a SARL application, it is now possible to specify extra arguments for the Java Run-time Environment (details), in addition to the program arguments, and the SRE arguments.
  • Fixing the rendering bug in the main tab of the SARL launch configuration related to the wrong rendering of the parentheses (details).
  • The launch configuration window contains panels for configuring the application to be launched. The plugins and extensions of the SARL Run-time Environment may need to be configured. In order to inject specific configuration panels into the launch configuration, an Eclipse extension point is created (1, 2). This extension point could be implemented by SRE extensions for providing a configuration panel.
  • Automatic binding of the main launch configuration panel and the SRE selection panel (1, 2).
  • Update the SARL embedded runner able to use the -D definitions from the command-line (details).
b) Commands
  • Add the command "Generate Element Document" for adding a documentation for the selected element (details).
c) Preferences
  • Add check boxes for enabling and disabling the code mining components that add decorations in the SARL editor (details).
  • Change the label of the code mining components in the SARL preference window (details).
d) Other Changes
  • Enabling the support of JDK 12, 13 and 14 for the SARL users (details), i.e. the SARL products are updated in order to be run on these versions of the Java environment.
  • Provide programmatic tools for formatting the command-line options in the messages that are displayed in the Eclipse SARL product (details).
  • Update the launching script for MacOS in order to automatically detect and configure the Java environment (1, 2).
  • Update the Linux launching scripts to make them more robust to the different versions of the Linux environments (details).

2.4. Examples of SARL projects

2.4.1. Example code

  • Fixing the code of the boids and fireworks examples to follow the new space API (details).

2.4.2. JDK support

  • The JDK version of the user is injected into the pom files of the examples (details).
  • Ensure that the JDK used for creating the example projects is compliant with the minimum JDK for SARL (details).

2.4.3. JavaFX support

  • Ensure that JavaFX is included as dependencies when JDK is 11 or higher (details).

2.4.4. Windows OS support

  • The example wizard needs to find executable files (such as Maven) on the operating system in order to use them. The wizard code is refactored in order to search correctly the executable files on all the operating systems, and specifically on Windows OS (1, 2).

2.5. Janus Run-time Environment

2.5.1. Bug fixes

  • Major bug fix in the dynamic skill creator attached to the @DefaultSkill annotation (details). This creator generates a NPE whatever the capacity or skill.
  • Avoid NPE into the JUL formatter (1, 2).

2.5.2. Entity Creation

  • In relation with the @Injectable annotation that is supported by the SARL compiler, the Janus SRE is updated in order to inject objects when they are annoted with @Injectable. If they are not annoted, the objects are created without injection in order to obtain a faster run (details).
  • Remove the interface BuiltinCapacitiesProvider (details).

2.5.3. Context Service

  • Refactor the context service by putting back the locks in order to avoid issues related to the parallel execution of the service (1, 2).

2.5.4. Executor Service

  • The prototype of the neverReturn function is changed in order to make its argument mandatory (details).
  • Fire an occurrence of the TaskFailure event when a background task has thrown an exception (details).
  • Add implementation of the toString function for the executor services (details).

2.5.5. Lifecycle Service

  • The initialization process of the agent into AgentLife is refactoring in order to avoid the receiving of events before the initialization stage is finished (1, 2).
  • Fixing the locks into the stop function of the agent (details).
  • Add a protected access to the executor service into the Lifecycle service (details).
  • In the agent spawn process, the logging and the forwarding of exception from the parallel tasks are fixed in order to output them properly (details).
  • Add the firing of an AgentSpawnFailure occurrence when an agent spawn cannot succeed (details).

2.5.6. Naming and Probing Services

  • Move the naming API from Janus SRE to the SARL SDK (details).
  • Move the probing API from Janus SRE to the SARL SDK (details).

2.5.7. Logging Service

  • The Janus SRE modules are now able to log their messages into dedicated loggers (details).

2.5.8. Space Implementation

  • Change the visibility of the function getScopedParticipants in the event space in order to be used by extensions of Janus, e.g. the networking module (details).
  • The function for firring the events is changed in order to fire the event to a provided listener, even if it was not registered to on the agent's event bus (details). It enables to propagate events to specific objects without receiving the events that are fired through the agent's event bus.

2.5.9. Internal API

  • Replace Guice by Guice NO-AOP (details).
  • Upgrade to Guice 4.2.3 (details).
  • Remove io.janusproject.eclipse from the classpath of the applications when they are launched in the Eclipse SARL environment (details).
  • Rewrite the Janus classpath provider for supporting Java 11 (2, 2).
  • Remove the dependency to Gson library because the Jackson library is included by the Bootique library, and it provides the same features for reading a Json file (details).
  • Fixing the injection definition of the Janus commands (details).
  • Update the message that shows up the version of the janus command line tool (details).
  • Avoid NPE related to the message of CannotSpawnException (details).
  • Clean the dependency tree of the Janus SRE (1, 2, 3).

2.5.10 Network Service for Janus SRE

The service-based architecture of the Janus SRE enables to provide specific services for running SARL agents. The version 0.12 of SARL introduces a service for the communication over a computer network of different instances of the Janus SRE.

By default, Janus does not provide a support for exchanging events over a computer network. If you would like to have benefit of this feature, you should use the extension module, named "Janus Network", that is introduced in SARL 0.12 (1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34). The implementation of this module is based on the Hazelcast library in order to build the clusters of Janus nodes.

Thanks to its implementation, the network service has the following major properties:

  • Share spaces (event-based or not) over the different instances of the Janus SRE.
  • Route events over the computer network.
  • Discover automatically the other instances of the Janus SRE in the local network.

2.6. Maven Tools

2.6.1. Bootique Plugins

  • Split the module io.sarl.maven.bootiqueapp in order to separate the Bootique-based library for building applications, and the SARL batch compiler library (details).
  • Add CLI option --generatemarkdownhelp to the Maven bootique library (details). This option will be available to all the bootique-based applications, e.g. janus and sarlc.
  • Add a command for displaying the configuration parameter of an application, usin a markdown syntax (details).

2.6.2. Documentation Generation Plugin

  • Enable isolated class loaders when evaluating the SARL expressions into the documentation files (details).
  • Add global system properties SARL_DOC_CURRENT_FILE and SARL_DOC_CURRENT_FOLDER that contains the parsing documentation file and its folder (details).

2.7. Command-Line Tools

2.7.1. sarlc

  • Use the new Bootique application framework (details).
  • Enable the reading of the -D parameters (details)
  • Deprecate the Java boot classpath (details).
  • Use the Unix standard for naming the CLI options (1, 2).
  • Add utility functions for accessing to the CLI options programmatically (details).
  • Generate 64 bit executables (details).
  • Force the MacOS X executable to use a version of the JRE that is compatible with the SARL tools (details).

2.7.2. sarldoc

  • Use the new Bootique application framework (details).
  • Enable the reading of the -D parameters (details).
  • Use the Unix standard for naming the CLI options (1, 2).
  • Add utility functions for accessing to the CLI options programmatically (details).
  • Generate 64 bits executable (details).
  • Force the MacOS X executable to use a version of the JRE that is compatible with the SARL tools (details).

2.8. SARL Documentation

2.9. Tools for SARL Contributors

2.9.1. Changes in the SARL Compiler Libraries

a) General Changes
  • Upgrade to Eclipse 2020-06 and Xtext 2.22.0 (details).
b) Pure Functions
  • Fixing the invalid detection of pure status for operations and provides an API for retreiving the side-effect expressions (1, 2).
c) Preparation for Java 11
  • Remove the references to the @Generated annotation that is different between Java 8 and 11 (details).
  • Split the "ui" module into the "ui" and "ide" modules (details). This change is needed for the support of the modules implies by Java 11 in the recent versions of Xtext.
  • Split the Utils class into the "lang-core" plugin and the "lang" plugin (details).
d) Code Mining
  • Add the definition of polymorphic methods for providing the code mining contributions (details).
e) Logging
  • Replace the references to Log4J and SFL4J by equivalent references to JUL (1, 2).
f) Other Changes
  • Exhibit a SARL expression interpreter (details).
  • Add utility functions to convert JVM type references to Lightweight type references (details).
  • Add an utility function for obtaining a valid human readable string for error messages (details).
  • Remove the unaccessible repository for the JBoss Eclipse plugins (details).

2.9.2. Build Tools

  • Add scripts to change the JDK configuration of the SARL products (1, 2, 3, 4, 5, 6, 7).

Sebastian Sardina

unread,
Jun 23, 2021, 7:26:07 PM6/23/21
to sarl
Wow, really lots of positive changes and improvements, congrats!
Reply all
Reply to author
Forward
0 new messages