XNAT uses applets for a number of functions, mostly involving transferring data between the XNAT server and client applications. Signed and secure Java applets have a lots of capabilities that are required for managing DICOM data between the server and client, but they also have some unfortunate issues that can cause them to function improperly or not function at all depending on how your system is configured. Differences in browser, Java plugin version, and client operating system further complicates diagnosis of applet issues. This troubleshooting guide is intended to help you identify common issues that can be easily resolved and, in more complex cases, gather information that the XNAT team can use to help you diagnose the root problem.

Accessing the Java Control Panel

Unlike most browser plugins, the Java plugin has its own control panel that you have to access outside of the browser. How you access this control panel depends on what operating system you're on and what version of the Java plugin you have installed.

On Windows platforms, the Java control panel is accessible through the main Windows Control Panel:

• On Windows XP:
  
  1. Click on the Start Menu in the lower-left side of your desktop.
  2. Go to Settings->Control Panel. Your Control Panel folder should open. 
  3. Click on Java in the Control Panel. The Java control panel should open in a separate window from the Control Panel.
• On Windows Vista or 7:
  
  1. Click on the Start Menu in the lower-left side of your desktop.
  2. Click on Control Panel on the right-hand side of the Start Menu. Your Control Panel folder should open.
  3. In the Search Control Panel text box in the upper-right corner, type "Java".
  4. Click the Java icon that appears in the Control Panel. The Java control panel should open in a separate window from the Control Panel.

On OS X, the Java control panel is accessible through the System Preferences application:

1. Click System Preferences on the OS X Dock or via the Launchpad.
2. In the search text box in the upper-right corner, type "Java".
3. Click the highlighted Java icon.

On Linux, the control panel is accessed through the installed JRE or JVM:

1. Ensure that $JAVA_HOME/bin is on your shell path. The value of JAVA_HOME depends on where your Java installation is located, which in turns depends on what Linux distribution and Java version you have.
2. Type ControlPanel at the shell command line.

First Steps

The first steps in understanding issues related to applet functionality are pretty easy:

• Clear the applet cache
• Turn on debug and trace logging
• Show the Java plugin console

Clear the Applet Cache

The applet cache is a mechanism by which the Java plugin increases performance. Once downloaded, Java libraries are saved in the cache to be used in subsequent calls to the applet. In theory, new versions of those libraries should replace the cached versions, but this doesn't always work properly. To ensure that you're getting the latest version of the libraries and clear out any possibly corrupted or invalid code, you can forcibly clear the Java applet cache.

1. If it's not already open, open the Java control panel.
2. On the General tab, click the Settings... button. The Temporary File Settings dialog will pop up.
3. Click the Delete Files... button. The Delete Files and Applications dialog will pop up.
4. Make sure that all checkboxes on the dialog are checked.
5. Click OK. There may be a small delay while the cached data is deleted.

Turn On Debug and Trace Logging

If clearing the cache does not solve your applet execution problem, debug and trace logging can help give the XNAT support staff and development team better insight as to the particular issue occurring on your client.

1. If it's not already open, open the Java control panel.
2. Click on the Advanced tab.
3. Click on the Debugging item in the Settings box.
4. Check the Enable tracing and Enable logging checkboxes. In difficult cases, you may also need to check the Show applet lifecycle exceptions checkbox, but this can generate a very large amount of data so you should only do that if other options have proven insufficient.
5. Click the OK or Apply button to make your settings changes take effect.

Show the Java Plugin Console

You can view the log and trace data generated by turning on debug and trace logging by going to the log files that are written out to the system. This can often be difficult to locate, however, and varies greatly by operating system. An easier way to view the debug and trace logging is to show the Java plugin console when the plugin starts up. This provides the ability to view the logs as they're generated in real time.

1. If it's not already open, open the Java control panel.
2. Click on the Advanced tab.
3. Click on the Java console item in the Settings box.
4. Check the Show console radio button.
5. Click the OK or Apply button to make your settings changes take effect.

Once you reload the applet, the console should open up simultaneously (or even a little before!). Once you've recreated any problems in the applet execution, you can just click the Copy button on the Java plugin console to copy all of the log data out, then paste it into a text file, email, or data transfer web site such as pastebin.

The console can become very annoying very quickly when you're not debugging. To turn it off, just follow the same procedure, but click Hide console instead.