Arakhnê Foundation Classes

Java classes for writing complex applications (version: 17.0)

Authors or contributors: Stéphane Galland, Nicolas Gaud, Olivier Lamotte, Alexandre Willaume, Thomas Piotrowski, Maxime Grolleau, Hamza Jaffali, Fevzi Ozgul

The Arakhnê.org Foundation Classes (AFC) is a Java library that provides a collection of utilities that are not provided in the standard Java API.

1. Compatibility with other Languages than Java

AFC is a Java library that provides extensions for being used with other programming languages.

For example, Vector2D provides overloading function for operator +. In this way, this operator may be used by typing v1 + 1 instead of v1.add(1).

SARL agent-oriented programming language

AFC library is compatible with the SARL agent-oriented programming language, which is a Xtext-based language (see below). Indeed, AFC classes use the specific annotations: @Pure for making pure functions, and @Inline for inline functions. AFC also provides the overridings of the operators (operator_plus, operator_minus, etc.) for vectors, matrices, etc.

Scala object-oriented programming language

AFC library is compatible with the Scala object-oriented programming language. Indeed, the AFC classes provide the overridings of the operators ($plus, $minus, etc.) for vectors, matrices, etc.

Xtend object-oriented programming language

AFC library is compatible with the Xtend object-oriented programming language, which is a Xtext-based language (see below). Indeed, the AFC classes use the specific annotations: @Pure for making pure functions, and @Inline for inline functions. AFC also provides the overridings of the operators (operator_plus, operator_minus, etc.) for vectors, matrices, etc.

Other Xtext-base languages

AFC library is compatible with all the languages that are defined upon the Xtext framework for development of programming languages and domain-specific languages. Indeed, AFC classes use the specific annotations: @Pure for making pure functions, and @Inline for inline functions. AFC also provides the overridings of the operators (operator_plus, operator_minus, etc.) for vectors, matrices, etc.

2. Maintained Modules

AFC library contains the following modules that are actively maintained:

Deprecated and Dead Modules

AFC library contains the following deprecated modules (deprecated modules are subject to removal in future version). The table presents the modules, the version from which they are deprecated, and the version at which they will be totaly removed from.

3. Requirements

For AFC version 17.0 or higher

• Java Development Toolkit (JDK) 11 or higher.

For AFC prior to version 17.0

• Java Development Toolkit (JDK) 8.

4. Using AFC in a Maven project

Recommendations

For making your experience with AFC the best, we recommend you:

• to enable the assertions at development time (with the -ea command line option).

Use the stable version

The lastest stable version of AFC is available on Maven Central. Consequently, you could directly include the AFC module that you want to use into the Maven dependencies of your project. For example, if you want to use the "vmutils" module:

<dependencies>
   <dependency>
      <groupId>org.arakhne.core</groupId>
      <artifactId>vmutils</artifactId>
      <version>17.0</version>
   </dependency>
</dependencies>

Please, replace Version 17.0in the previous snipset by the number of the version you want to use (12.0 is the first version that is available on Maven Central).

Use of the development version

New features, enhancements and bug fixes are available in the SNAPSHOT (development) version of AFC. For using this version, you must add the Maven Repository Server of AFC in your pom file:

<dependencies>
   <dependency>
      <groupId>org.arakhne.core</groupId>
      <artifactId>vmutils</artifactId>
      <version>18.0-SNASPHOT</version>
   </dependency>
<dependencies>
...
<repositories>
   <repository>
      <id>org.arakhne-maven</id>
      <name>Arakhnê.org Snapshots</name>
      <url>https://arakhne.org/download/maven/</url>
   </repository>
</repositories>
<pluginRepositories>
   <pluginRepository>
      <id>org.arakhne-maven</id>
      <name>Arakhnê.org Snapshots</name>
      <url>https://arakhne.org/download/maven/</url>
      <snapshots>
         <enabled>true</enabled>
      </snapshots>
   </pluginRepository>
</pluginRepositories>

5. Issues

Issues related to the AFC are tracked on GitHub. You must use this issue tracker to report and follow your issues.

6. Contributions

Any contribution to the AFC library is welcome.

Installing the Development Environment

For setting up the development environment, you should follow the steps:

• Download and install "Eclipse for Java Developers".
• Download the contributors.p2f file that specifies the Eclipse plugins for the development environment.
• Install the Eclipse plugins by selecting in Eclipse: File > Import > Install > Install software items from file.
• Download the \contributors.epf\ file that contains the Eclipse general preferences related to the AFC project.
• Import the general preferences: File > Import > General > Preferences

Obtaining the AFC Source Code

For obtaining the code of the AFC library, you must clone it from the Git:

git clone https://github.com/gallandarakhneorg/afc

Caution: due to an issue in the Eclipse Checkstyle plugin, it is mandatory to install the build-tools module in the your .m2 repository prior to the first launch of the Eclipse IDE:

mvn clean install -Dcheckstyle.skip=true

Compiling the AFC Source Code

Maven is the standard tool for compiling the AFC library. It is recommended to launch the Maven compilation process on the command at least before submitting a pull request. The command line is:

mvn clean install

Sending the Contribution

For sending your contribution to the AFC master repositoty, you must request a pull (PR) to the GitHub repository.

For being merged, your PR must:

• be compilable with Maven;
• pass the compilation process successfully, including the code compilation, unit testing, and code style checking. This process is supported by Travis-CI;
• sign the Contributor License Agreement on GitHub. It is supported by cla-assistant;
• be reviewed by one or more of the main contributors for ensure your PR is following the development rules and philosophy related to the AFC.

If the CI process is failing on your PR, please follows the steps:

• Go on the Travis-CI output for obtaining the cause of the failure.
• Fix the code of your PR on your local copy.
• Commit on your local repository, and push the changes on the same PR. Do not create a new PR for the fix.
• The GitHub platform will relaunch the CI process automatically.

7. License of AFC

The Arakhnê Foundation Classes are distributed under the Apache License 2, and is copyrigthed to the original authors and the other authors, as expressed in the NOTICE.

8. Success Stories

The following projects have sucessfully used a module of the AFC:

• FLO Project
• Jaak Simulation Library
• Janus agent platform
• Metro-B
• NetEditor
• SARL agent-programming language