Setup for MBIV1.0 Web-based Applet

  1. Intro
  2. Java Support
  3. MySQL Connector/J (JDBC)
  4. Running Applet

1. Introduction

The mouse brain visualizer is available as an applet that executes within the context of a web browser or a downloadable jar file. This page describes what is needed to get the tool running as an applet under Unix/Linux OSes and Windows using the Netscape or MS Internet Explorer browsers. For the downloadable version, goto the download page . Most Java applets can run "as is", that is, without the installation of additional libraries beyond those that come with the JRE or SDK or any extra parameters to the JVM. In order to use web-based mouse brain visualizer, there are some additional steps that the user must take that are described below.

2. Java support

Make sure the latest version of Java 1.4.2 is installed; either SDK Version 1.4.2_02+ or JRE Version 1.4.2_02+ would suffice. Note, the applet is NOT compatible with version 1.5.0. If 1.5.0 is the only version installed, the user must install 1.4.2_0X, where X=2+. There is a relatively easy way to make 1.4.2_0X your current JRE execution environment. Refer to Sun's plugin help which describes using the control panel to choose your JRE environment.

A version of JRE 1.4.2_03 for Windows is available for download as a compressed tarball or a WinZIP file

On XP systems with version 1.5.0 installed, the current control panel may not allow you to change the JRE version used to launch applets. What you can do is, run the control panel from a 1.4.2_0X installation of Java. Find the installation of JRE on your machine using Windows Explorer or "cd" (change directory) via the Command Prompt. Typically, the installation directory is c:\Program Files\Java\jre1.4.2_0X. Change directory bin and run (double-click) jcpnl. Select the "Browser" tab and deselect all of the browsers for which you want to enable java version 1.4.2_06 and "Apply" changes. Next, select the "Advanced" tab and choose the most current 1.4.2 version of Java then go back to "Browser" and reselect the browsers you want to run the browser applet in, then "Apply". This should set the JRE for the selected browser to 1.4.2.

2.1 Memory Considerations

The images uploaded via the browser range in sizes from 35MB to 64MB. If several images are uploaded, in addition to the corresponding atlases (the actual atlas data set is not uploaded, a set of polygonal vertices is generated from the atlas on the server, so about 1/10 of the 35MB atlas size is uploaded), quite a bit of memory can be consumed in the JVM. Since the JVM has a default setting for the amount of memory it can allocate, this maybe too small to accomodate a reasonable number of datasets. It is recommended that the user increase the default heap size of the JVM.

This can be done using the Java Plugin Control Panel, which can be found in the Control Panel directory under My Computer. Select the Advanced tab in the panel. At the bottom of the Advanced panel, there should be a text box labelled Java Runtime Parameters. It's recommended that the heap size is set to 250MB; of course, this value will be a function of the amount of memory in the local system and how many applications are currently running. The user can opt to allocated more than 250MB. In the text box, enter the following: -Xmx<#MB>, where #MB is the amount of memory in MBs. Click on Apply to apply the changes. It's possible that the browser might have to be closed and reoped for the changed to take effect.

2.2 Security Considerations

Note: If you download the JRE that we provide (Version 1.4.2_03) a version of the policy file with the proper modifications is provided with the JRE, so the user does not have to download the policy file.

Java's security policy is designed to prevent malicious applets and applications from damaging local computer systems. For example, by default, a TCP/IP socket cannot be established between a users system and a remote system unless the Java application trying to open the socket has "permission". A detailed description of Java Security is beyond the scope of this page, but if the curious user is interested, she can visit Sun's Java Security page for more information. There are several permissions that are needed by the visualization applet tool: 1) socket permissions (accept, connect, listen, resolve) and 2) file encoding permission (read). The user can either add these permissions by editing the security policy file in the JRE on their local machine or download a copy of a security file, which contains ONLY the needed modifications and install it in the appropriate JRE directory.

2.2.1 Modifications to java.policy

Using Windows Explorer or the Command Prompt (or Cygwin bash shell), navigate to the security directory of the active Java Runtime Environment (JRE), i.e., C:\Program Files\Java\jre1.4.2_02\lib\security. Open the policy file, java.policy using your favorite editor, i.e., XEmacs, NotePad, etc. Locate the second "grant" keyword, which should have the line

\\default permissions granted to all domains 

preceeding it. Find the last (maybe first an only on some systems) line with the keyword SocketPermission in it. On systems with an unmodified policy file, the first/last line with this keyword should be:

permission "localhost:1024-", "accept, 
connect, listen, revolve"

Add the following line of text AFTER this line:

permission "", "accept, 
connect, listen, resolve"

Note, there shouldn't be any linebreaks in the inserted text. Essentially, this permission allows both the MySQL server and image data server to connect via "sockets" to the client machine.

Next, locate the last PropertyPermission line in the file:

permission java.util.PropertyPermission "", "read";

Insert the following line of text after this line:

permission java.util.PropertyPermission "file.encoding", "read";

Save the file.

2.2.2 Download java.policy File

It would be prudent to backup your current policy file before saving this file. Open the modified file in your browser. The best approach is to cut and paste the contents into a file called java.policy in the appropriate JRE directory, i.e. C:\Program Files\Java\jre1.4.2_02\lib\security. If you attempt to use "Save As" to save the file as a "Text file", the browser will append a .txt extension to the file name.

3. MySQL Connector/J JDBC

Note: If you download the JRE that we provide (Version 1.4.2_03), the correct version of the MYSQL Connector/J JDBC is already bundled with the JRE, so a separate download and installation of the Connector/J JDBC is not necessary.

MySQL Connector/J, a JDBC (Java Database Connector), is required for the applet to interface with the Mouse Brain Database. We have experienced problems using more current versions available via the MySQL website. The version that is known to work with our visualization tool can be downloaded from here as the jar file, mysql-connector-java-3.0.9-stable-bin.jar.

Using Windows Explorer or a Command Prompt, navigate to the java runtime installation directory. It should be in a directory like: c:\Program Files\Java\jre1.4.* You need to save (or copy) the jar file into c:\Program Files\Java\jre1.4.*\lib\ext. If you have more than one version of jre installed -- i.e., jre1.4.2, jre1.4.2_0X, save the jar file in the JRE installations choosen in the Java Support section . Note: Don't use JRE Version 1.5.0!

4. Running Web-based Visualization Tool as Applet

The mouse brain visualization tool can be launch using the link below. Before launching the applet, be sure to go through the setup instructions, otherwise, the applet will more than likely not work correctly.

Launch mouse brain visualizer here