Setup isac-java

Setting up the development environment for the ISAC Front-end follows these steps. The rare differences between Windows and Linux are mentioned specifically:

Install Software
console> java -version
 * (1.1) Java 8 is usually installed on all computers; convince yourself that this Java version is installed, which is required by ISAC:
 * (1.2) java.policy determines the rights for Java RMI (which are still liberal for prototyping). In Linux this file resides in the home-directory and the filename starts with '.' (i.e. '.java.policy' is a hidden file), in Windows this file resides in the Java installation.
 * (1.3) Scala IDE for Eclipse integrated development environment; the interface between Isabelle and Isac's front-end is Scala, the front-end itself is Java. Scala is integrated in the IDE bundle.
 * (1.4) Mercurial source control management tool. Here the integration of Mercurial into Eclipse is not described, since Mercurial is handy also on the command line. In case of problems with the Mercurial installations see  here. Usage of the repository see  here.

Required only by specific development tasks: Change the permissions to the installer chmod 755 xampp-linux-*-installer.run Run the installer sudo ./xampp-linux-*-installer.run
 * (1.5) log4j chainsaw logger for distributed systems
 * (1.6) XAMPP for Linux containing a SQL database, in case you want to log users' steps in problem solving. Below we assume you follow the standard installation into the '/opt/lampp directory':
 * (1.7) A diff-tool of your choice (called DIFF-TOOL in the sequel), for instance meld.

Download and install the Isac kernel
http://www.ist.tugraz.at/projects/isac/www/download/isac2018.tgz tmp$ tar xvfz isac2018.tgz which gives ... libisabelle-protocol ROOTS src/ tmp$ cp ROOTS / tmp$ cp src/Pure/thm.ML /src/Pure/       # ISAC's hooks in Isabelle tmp$ cp -r libisabelle-protocol /        # the interface isac-java --- kernel tmp$ cp -r src/Tools/isac/ /src/Tools/   # ISAC's code in Tools/isac $ export ISABELLE_VERSION=2018 $ ./bin/isabelle jedit -l libisabelle_Isac &
 * (2.1) Download Isabelle 2018 following the respective instructions for Linux or Windows. In Windows klick Isabelle2018.exe.
 * (2.2) Download ISAC's code and hooks into a temporary directory tmp using a browser with the url ...
 * (2.3) Unpack it ...
 * (2.4) Copy the ISAC code into the Isabelle code (where '/' denotes the directory where you installed Isabelle2018 -- in Windows this is located in Cygwin), where the first two files overwrite existing files:
 * (2.5) Create the Isabelle/Isac session including the Isabelle-side of the interface between isac-java and Isac-kernel libisabelle by ( for Windows with these preparations) ...

The java side of libisabelle is established by a library (setup-assembly-XXX.jar) declared to Eclipse in a subsequent step.

Download the ISAC tutor
Warning: in Linux avoid problems by rigorously have your username as owner for all files, including the software installed. For instance, from NetBeans started with sudo ./netbeans & (sudo required, if you are not the owner) you get errors which are really hard to track like ... try to bind as //localhost/BridgeRMI RemoteException RemoteException occurred in server thread; nested exception is: java.rmi.UnmarshalException: error unmarshalling arguments; nested exception is: java.lang.ClassNotFoundException: isac.bridge.IBridgeRMI ... while all setup of NetBeans is perfect (Java RMI involves TCP/IP which changes with the owner).

console> mkdir proto4 cd proto4/ console\proto4> hg clone --insecure https://intra.ist.tugraz.at/hg/isac/ repos [ui] username = n.n.  merge = MY-DIFFTOOL editor = MY-EDITOR [extensions] hgext.fetch = [defaults] fetch = -m "merged"
 * (4.1) Prepare a directory, say 'proto4' for an Eclipse project:
 * (4.2) Into this directory clone the ISAC repository (sysadmin enforces "--insecure" now):
 * (4.3) Adapt the Mercurial settings in 'MYPATH\proto4\repos\.hg\hgrc' as follows:
 * 1) this enables the command 'hg fetch'
 * (4.4) Download kbase i.e. ISAC's knowledge in html format (which has been generated automatically from respective files in repos/xmldata/* in a separate batch process, see Extend_ISAC_Knowledge) in the directory 'MYPATH\proto4\' and unpack it (for instance, 7-zip can do this).

Configure components
console\proto4> cd repos\isac-java\src\java\ console\proto4> mkdir properties console\proto4> repos\isac-java\src\java$ copy properties-templates.windows/* properties/ and in Linux console/proto4> cd repos\isac-java\src\java\ console/proto4> mkdir properties console/proto4$ repos/isac-java/src/java$ cp properties-templates.linux/* properties/
 * (5.1) Prepare a directory and adapt ISAC's property files to your file structure (this is the reason for that they are not in the repository); if you have followed the directory structure so far, you just have to copy the six files from the -templates and to replace MYUSERNAME by your user name in these files:


 * (5.2) Adapt the paths in the files in properties to your computer (GenHTMLsingle.properties can be omitted).

Configure the Eclipse project
Since changeset fefb6d28aa46 the files defining project setup are tracked. So several of the steps below are not necessary any more. However we kept them in order not to track Eclipse's automation and mark these steps with double parentheses ((6.*)).


 * (6.0) The number of eclipse's crashes diminish by adding -XX:-UseLoopPredicate to  eclipse.ini in the eclipse installation.

File > New > Project > Java Project: Project name: isac-java Location:    ... search "proto4/repos/isac-java" from the download Sometimes Eclipse misinterprets JavaScript in isac/util/genhtml. Determine the correct structure manually.
 * (6.1) Give the project the name 'isac-java' and tell the source files at 'proto4/repos/isac-java/src/java':


 * (6.2a) Check via PackageExplorer > isac-java >RIGHT MOUSE> Properties > Scala (or Configure), that the Scala Nature is set.


 * (6.2b) Libraries of isac-java are in the repository at isac-java/lib, click them into Eclipse one by one.

For instance, check the Java-side of libisabelle (3.1)..(3.2): the respective setup-assembly-0.jar should be ed to the libraries in isac-java's  (found in the  of isac-java). This jar has been created during update to a new Isabelle version. This is a screenshot of the window with all libraries required (in 2014):



NB 'Project'-view > RIGHTMOUSE on isac-java > Properties > Libraries
 * (6.2b) Libraries of isac-web: Since 2013 the respective file ./isac-web/lib/nblibraries.properties is tracked in the repository and thus netbeans includes all required libraries automatically. What you see in the screenshot below can be seen by


 * (6.3) Define run configurations for each of the 4 modules, which run in different JVMs (probably on different computers, see properties (5.1)) by Eclipse-menu  Run Configurations > Arguments: edit the Program arguments and the VM arguments with these program-arguments-for-linux and  program-arguments-for-windows respectively.

$ cd proto4/repos/isac-java/build/ $ mkdir sml $ mkdir sml/BridgeLog $ chmod a+x sml/BridgeLog BridgeLog/ contains a protocol of the communication between ISAC's mathematics engine and ISAC's frontend via stdin - stdout.
 * (6.4)..(6.5) DROPPED, but Eclipse (version?) sometimes treats ~/proto4/repos/isac-java/src/java/isac/util/genhtml in a strange way. Thus it is  in Package Explorer > RIGHTMOUSE on isac-java > Properties > Java Build Path > Source. Respective code is only required for  generating representations for ISAC Knowledge.
 * (6.6) Create the directory 'sml/BridgeLog/' in the directory where the classes are built to and make them executable, for instance

Projects > isac-java (RM) > Project Properties > Application > Web Start und uncheck [] Enable Web Start. See isac-web (3.3). This changes ~/proto4/repos/isac-java/nbproject/project.properties, which is tracked in Mercurial: this change should not be pushed!
 * (6.7) In case you want to run isac-java without  isac-web, you can speedup compilation time tremendously by selecting

Run ISAC educational math assistant
Now the system should run: Linux$  rmiregistry 1099 -J-classpath -J/home/MYUSERNAME/proto4/repos/isac-java/bin & Windows$ rmiregistry.exe -J-classpath -JC:\MYUSERNAME\proto4\repos\isac-java\bin 1099 & BridgeMain       (wraps the ISAC core) KEStore          (reads the knowledge from 'proto4/repos/xmldata/*') ObjectManager    (the multi-user session management) WindowApplication (the GUI, probably several from different computers) Username: x Password: x   ISAC Menu > Examples > select what you want, probably from: Examples > IsacCore > Simplification
 * (7.0) Start the registry of remote objects called by the WindowApplication from the isac server (and vice versa; between the server's modules as well; since f08fda5672a0 the classpath is required for unknown reasons)
 * (7.1) Start the Java modules exactly in this sequence (due to respective dependencies):
 * (7.2) The WindowApplication calls for identification (in order to be able for personalised user guidance, 'y' and 'y' enters a slightly different dialog mode):
 * (7.3) Select an example by opening the 'Examples'-window and clicking into the hierarchy on the left:
 * (7.4) Start an example by clicking a link on the right in the 'Examples'-window. A 'Worksheet'-window appears, and also two buttons  and  in the ISAC Menu; the former proposes the next step, the latter calculates the result. You also might propose the next formula by input into the respective line in the 'Worksheet' (1st click: select the line, 2nd double-click: activate edit mode)

Log users' steps in problem solving

 * (8.1) ***** Ask users for permission to log their interaction with ISAC ! *****

LOGGER_DATABASE_ENABLED = true Restart ISAC according to (7.1).
 * (8.2) Switch on the 'UserLogger' by un-commenting (use '#') in proto4/repos/isac-java/src/java/properties/ObjectManager.properties:
 * 1) LOGGER_DATABASE_ENABLED = false

$ /opt/lampp/lampp start $ sudo /opt/lampp/lampp start You should now see something like this on your screen: Starting XAMPP 1.7.7... LAMPP: Starting Apache... LAMPP: Starting MySQL... LAMPP started.
 * (8.3) To start the database MySQL simply type one of these commands into a shell:


 * (8.4) View steps using a standard web-browser (Mozilla, Firefox are recommended):
 * Type 'http://localhost' into the browser as a web-address: you get a web-page with 'phpMyAdmin' in a menu (probably on the left margin).
 * The menu item 'phpMyAdmin' leads you to a web-page with the item 'userlogger(1)' in a menu (probably on the left margin).
 * The menu item 'userlogger(1)' leads you to a web-page which contains several tools for inspecting the steps recorded in the database.
 * In 'proto4/repos/isac-java/src/sql/queries.sql' you find some examples how to select specific data from the database.
 * You might ask google for 'phpmyadmin tutorial'.

Make jUnit tests run
ISAC follows test-driven development. The file-structure of the production code in repos/isac-java/src/java/isac is mirrored in repos/isac-java/src/java-tests/isac: each class in the production code should have regression tests in the respective test code.

***** A commit to the repository is only allowed if all tests are successful *****

jUnit tests are run by opening the file Test Packages/isac/Testall.java and by selecting  from the context menue (left mouse button).

In order to keep development as simple as possible, we make mock-objects by hand. Tests are also useful for understanding specific features of ISAC isolated in respective tests.

Debug using log4j
Debugging across the 4 modules (BridgeMain, KEStore, ObjectManager, WindowApplication) gets stuck in the RMI-connection inbetween. So ISAC is prepared to optionally use log4j. repos/isac-java/src/java$ cp log4j_browser.properties log4j.properties name  | isac port  | 4445 Leave the field of the port number with the  key in order to keep the input. Root Logger isac and by a new item  in the main menu. You might want to get an overview on the interactions between ISAC's modules by selecting on Chainsaw's panel Refine focus on: LEVEL >= INFO where the modules are abbreviated as follows: WS: Worksheet on the GUI DG: DialogGuide, i.e. the WorksheetDialog etc BR: Bridge to the mathematics engine KN: Kernel, i.e. the mathematics engine
 * (9.1) Check the file ~/src/java/log4j.properties for the settings, in particular log4j.appender.Chainsaw.port=4445. You might want to
 * (9.2) Start the Chainsaw logger (by  from here or from installation)
 * (9.3) In the logger left/top right-click Receivers > New Receiver > New Socketreceiver which opens a setup window
 * (9.4) In the setup determine
 * (9.5) Start isac according to (7.1)
 * isac is detected by Chainsaw, indicated by




 * (9.6) If this does not work Clean and build the NetBeans project and restart isac (while Chainsaw is running already with a Receiver listening to port 4445).

Coding standards for Java
within the ISAC project have been established by Klaus Schmaranz and are documented in the Rules of the ISAC - Developers on p.9-13 (the other pages in this document are not up-to-date). in