= Java in Brainstorm =
''Authors: Martin Cousineau, Raymundo Cassani''

[[https://www.java.com/en/|Java]] is a multi-platform and object-oriented programming language. Matlab supports its execution in order to facilitate writing more complex graphical user interfaces and applications.

<<TableOfContents(2,2)>>

== Java version ==
You have to keep in mind that not every Matlab versions ship with the same version of the Java Virtual Machine (JVM). See this [[https://en.wikipedia.org/wiki/MATLAB#Release_history|Wikipedia page]] for specific JVM versions for each release of Matlab. With the general objective of supporting older Matlab versions (2008 to today), we need therefore to support Java 6 to 8.

== Java repository (bst-java) ==
For the GUI elements Brainstorm uses a compiled '''`.jar`''' file ('''`brainstorm.jar`'''). This '''`.jar`''' is included in the binary Brainstorm distribution of Brainstorm. For the source version of Brainstorm (executed from Matlab) the '''`.jar`''' is automatically downloaded. As the raw Java code is not of use to regular users.

{{{#!wiki tip
More information on compiling Brainstorm in: <<BR>>
https://neuroimage.usc.edu/brainstorm/Tutorials/Scripting#How_to_compile_Brainstorm
}}}
To access to the raw Java code used by Brainstorm, refer to this GitHub repository: <<BR>> https://github.com/brainstorm-tools/bst-java

The repo also includes the project files to open the repository as a project in the popular [[https://netbeans.apache.org/download/archive/index.html|Java IDE NetBeans]] which we recommend for writing and testing your Java code.

The '''`brainstorm`''' java project is compiled with the Java SE Development Kit 7, Update 80 aka '''`JDK 7u80`''' which can be obtained in: <<BR>> https://www.oracle.com/java/technologies/javase/javase7-archive-downloads.html

Once JDK7u80 is installed, add it as platform in NetBeans: <<BR>> '''Tools > Java platforms > Add platform (JSE)''' : `C:\Program Files\Java\jdk1.7.0_80`

(!) The JSE platform must be defined for each project in: <<BR>> Right-click on Project > '''Project properties > Libraries > Java Platform'''. 

== Pushing your changes to Matlab ==
Once you are satisfied with and tested your changes in your Java IDE, you need to push your changes to MATLAB.

 * First, you need to compile a JAR file of your changes. In Netbeans, go to Run -> Clean and build project.
 * You can find your compile JAR file under '''`bst-java/brainstorm/dist/brainstorm.jar`'''

 * Then, you need to make sure Brainstorm and Matlab are shut down.

 * Copy your newly created '''`brainstorm.jar`''' file to overwrite '''`/brainstorm3/java/brainstorm.jar`'''

 * Start Matlab and Brainstorm, and your new Java code is now available.

{{{#!wiki tip
Examples of changes to the `brainstorm` java project (new node types, icons, other GUI, etc.) can be found in the [[https://github.com/brainstorm-tools/bst-java/commits/master/brainstorm/src/org/brainstorm| its commit history]].
}}}
== Calling Java functions in Matlab ==
Calling Java functions is extremely easy from Matlab, as documented here on the official [[https://www.mathworks.com/help/matlab/matlab_external/accessing-your-own-java-classes.html|Mathworks website]].

 * First, make sure the JAR file you need to access is in the Java classpath. If your changes are in the '''`brainstorm.jar`''', this is already loaded when Brainstorm starts.
 {{{
 javaaddpath('my_file.jar');
}}}
 * Then, in the Matlab function are writing, you need to first import all required Java classes you are going to use. You can import all classes of a package using the start (*). Make sure the import process is the line(s) of code of your Matlab function.
 {{{
 import org.brainstorm.dialogs.HotkeyDialog;
 import org.brainstorm.dialogs.*;
}}}
 * You are then free to instanciate and call any public functions of your imported classes in the Matlab code as if this was Java code. Just make sure to feed inputs of the appropriate format to the functions (i.e. if it expects a string, feed it a string).
 {{{
 dialog = HotkeyDialog(12);
 res = dialog.getKey();
}}}

=== Creating Java Swing elements for GUIs ===
To create Java objects for GUIs, Brainstorm already has wrappers in place to simplify and harmonize the process across the program. Refer to the '''`gui_component()`''' function to do this. Also, have a look at the '''`CreatePanel()`''' function of any '''`panel_`''' file to see examples of creating Swing GUI elements in Matlab.