Introduction

JSoar 5 requires Java 11+. This may have implications for projects that depend on JSoar.

First Steps

Before updating to JSoar 5, see if your project runs on Java 11+ as-is (i.e., don't modularize it or update to JSoar 5 yet). If you are using a version of JSoar from before 4.0.0, we recommend updating to 4.0.0 or later, but not 5.0.0 (the last release before JSoar 5 is 4.1.3). These versions support Java 11 modules and Java 8. Note that in JSoar 4+ some commands were changed to match changes in CSoar 8.6.0, and the JSoar debugger is more sensitive to improper threading in the 4+ (e.g., executing Soar commands off the Soar thread may cause a deadlock), so you may need updates to make things work.

If your application has issues in Java 11+, then those will have to be resolved before updating to JSoar 5. Common gotchas include needing to update build tools like maven and gradle (e.g., for maven you need to use maven-compiler-plugin 3.8.0 or later, and for gradle you need to be on version 5.0 or later) and needing to update other dependencies to versions that support Java 11+.

Updating to JSoar 5

JSoar 5 is fully modularized (i.e., uses module-info.java files). The best long-term approach would be to fully modularize your project. But things can be made to work without doing that, too.

Modularizing your project

This means adding module-info.java to your project (or each of its subprojects). Your IDE can do this for you. E.g., in Eclipse right-click on the project, Configure -> Create module-info.java. You'll need to pick a unique name (e.g., jsoar uses org.jsoar.core, org.jsoar.debugger, etc.). These are the same module names that were included in the JSoar 4.x versions.

Note that the generated module-info.java does not know about resources that may need to be exposed. If you need to expose resources for other projects to use (e.g., your project is a library used by other projects), you may need to manually add opens lines to module-info.java. These specify the "packages" (which may just contain resources) to expose. You can opens to specific other packages (e.g. a dependency) if you wish to limit access.

You may also need to update other dependencies to get ones that work properly with modular java projects (e.g., ideally ones that actually define a proper module name).

The non-modular approach

It may be that modularizing your project is a bridge too far for now. That's ok! Starting in JSoar 5.0.1 things should "just work" like they would with any other dependency. If you're using JSoar 5.0.0, you should update. But otherwise, the biggest issue you'll run into is that your project won't be able to see JSoar's services. E.g., you may get an error like this:

java.lang.IllegalStateException: Could not locate an implementation of ExecutionTimeSource

Prior to JSoar 5 (and again in 5.0.1), JSoar used META-INF/services files to specify implementations of various parts of JSoar (e.g., an execution time source, the interpreter, etc.). These are now specified in JSoar's module-info.java files -- there are no META-INF/services files. But if your project is not modularized, it won't know about these definitions.

As a workaround, you can add the META-INF/services files from the older versions of JSoar directly into your project. If you're using the standard maven/gradle layout, then they would go in src/main/resources/META-INF/services; unzip these files into it: services.zip. Note this will work for both normal execution and tests.

If your project has lots of subprojects that depend on each other, it shouldn't be necessary to add these services files everywhere -- if there is some common dependency that brings in jsoar, and everything else gets it from there, it should be sufficient to add the files to that project.