WebCream Troubleshooting

I have downloaded WebCream installer and tried running it, but it fails
If native platform installer (.exe for Windows or .bin for UNIX) failed, please report the details of the problem to us. You can download WebCream as a .jar or .zip file and simply unjar or unzip it. It is equivalent to running the installer, and the only difference is that shortcuts are not created. Use wcconsole.bat on Windows or wcconsole on UNIX to run the console.

ClassNotFound exception is displayed when I try to access my application
If the class name begins with creamtec double check that WebCream is installed and configured properly. If you have deployed WebCream to your own servlet container verify that webcream.war was properly deployed and you have added -Xbootclasspath parameter pointing to wcboot.jar. Read the Installation and Setup instructions for details.
If the class name does not begin with creamtec, make sure that the specified class is accessible to WebCream. For inProcess execution this class should be accessible to the JVM that executes WebCreamRouter servlet. For stand-alone execution it should be available through CLASSPATH. Note that if you are using the Start menu shortcut or .exe file on Windows platform then the changes in the CLASSPATH will not be reflected after you install WebCream (this is a known problem with InstallAnywhere). Therefore the best solution is to run the console through wcconsole.bat or to invoke the web server manually using it's startup script startserver.bat

WebCream crashes on UNIX
Most likely you have forgotten to specify fonts directory to JVM that is running WebCream. Please read the section on UNIX in Setup and Installation instructions. 

Images did not load, colors and fonts are not right, and/or the browser displays an error saying that JavaScript is not loaded
WebCream documents directory is not accessible to the browser. Make sure that you have followed the instructions on configuring WebCream and you copied the webcream_docs directory to your web server HTML directory. Double check that your application configuration contains the correct path to your webcream_docs directory using either Wizard or by opening the .properties file directly. The easiest way to find out where to copy the images is to look at the page source (View->Source in IE) and see what URLs are being requested for .css files and image (.gif or .jpeg). For example, the following line specifies the stylesheet for a page generated by WebCream:
<link rel=stylesheet href="http://www.creamtec.com/wcdocs/WebCream_docs/scripts/WebCream.css">
Here you can see that WebCream.css is expected to be in /wcdocs/WebCream_docs/scripts directory in your web server. You can either copy the files to their expected location, or set the value of application property html.docsURL as described in Customizing WebCream.

Application is running but no windows are displayed on the page; the page does not display the right dialog that is displayed to the user when run as a GUI
Most likely the problem is caused by multithreading used in your application. The easiest way to check this is to click on Refresh button of WebCream page (but not the Refresh button of the browser). If after refreshing you saw the right window, then it can be easily corrected. Follow the link for information on multithreading in WebCream.

Standard images are loading but my application images are not
You need to copy your application images to webcream_docs/images directory. The directory structure should correspond to the directory structure that your application expects, so for example if you are loading image as "myicons/logo.gif" then you should copy "logo.gif" to webcream_docs/images/myicons/logo.gif.

My application fails to load its files. Where do I copy my files so that my application can find it?
It depends on how you are loading your files. If you rely on the files being in the current directory, then you need to copy them to the directory that is current when you run WebCream. For inProcess execution that will be the servlet engine startup directory. For stand-alone execution that will be the servlet engine directory too.

"No windows are visible" message or "Changing look and feel is unnecessary when WebCream is used" messages are displayed when I try to run my application
Check the console output or the log file to see what exception has caused this problem, this error is usually reported when the application fails to initialize. One of the reasons can be an attempt to change the look and feel. WebCream is optimized to work with default Metal Look and Feel. If your application tries to set a different Look and Feel, comment out that line and try again. Another possible reason is a call to JFrame's setDefaultCloseOperation(EXIT_ON_CLOSE). JFrame calls the SecurityManager's checkExit(0) method and because the JVM shutdown is not allowed by WebCream setDefaultCloseOperation() fails. Instead of using EXIT_ON_CLOSE add an event listener or override dispose() method and call System.exit() from there. You can also get "No windows are visible" message if the application uses extensive multithreading where the windows are displayed on a background thread. See the next section for more information.

My application uses multithreading and asynchronous updates but WebCream fails to correctly detect when to render windows
The symptoms of this problem can be prematurely rendered windows, "No windows are visible" message or incorrect top level window displayed on the page. For details please refer to this document on multithreading with WebCream.

"Unsupported component XXX" text is written where a component should be in HTML page
This means that the given component is not supported by default by WebCream. You can write your own renderers for nonstandard components as explained in the Frequently Asked Questions document. Alternatively, you can use SnapshotRenderer to render the component as an image.

The component is not rendered on the page, is rendered as blank, or some parts of it are missing
There are several possibilities. If the component is is a container and you have overridden paint() method to implement custom drawing, you can write a custom renderer or use SnapshotRenderer to render the component as an image.

I get Session Closed page when I try to connect to my application through WebCream (AccessControlException is reported in the log file)
This typically occurs when the application's main() method has called System.exit(). Often the standalone GUI applications call System.exit() if they fail to initialize. Check the log files for any exceptions and make sure that the client application has been configured properly. WebCream writes the following trace when it intercepts an attempt to shutdown a JVM:
   Exit attempt intercepted
WebCream throws java.security.AccessControlException to intercept the exit attempt. Another reason why AccessControlException may be thrown by WebCream is if the application tries to call setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE) for a frame. Because WebCream controls the lifecycle of the JVM, it prevents the applications from being able to forcefully exit it. Replace EXIT_ON_CLOSE with DISPOSE_ON_CLOSE to get around this issue.

Another reason for access control exception can be that your code is not granted permissions to execute the operation in web server security policy. If you haven't copied your .jar files into wcapps/lib folder during the setup you can explicitly grant permissions to your .jar files in WebCream/tomcat/catalina.policy

When users select Exit form my application and I do System.exit this shuts down the servlet engine
WebCream intercepts System.exit by using its own SecurityManager. If your application installs it's own security manager it may prevent WebCream from handling System.exit() properly. Comment out installation of your own SecurityManager. If using RMI you still don't need RMISecurityManager because your client and server are running on the same machine. Contact CreamTec for further support.

Component sizes appear to be inconsistent depending on the platform where I deploy WebCream. Text field sizes are too small on UNIX
Most likely the problem is causes by the emulated Java graphics environment not finding the right fonts. WebCream emulates the graphics environment but it still lets JVM load fonts in order to properly calculate the sizes of labels, text fiends and other text components. On UNIX platforms WebCream requires properly configured fonts directory. WebCream is shipped with default fonts that are located in <WebCreamHome>/lib/fonts directory, and a mapping file lib/fonts.properties. Built-in webserver is preconfigured to correctly specify the fonts directory to the JVM via java.awt.fonts directive so you shouldn't experience this problem. If you do, check your log file for errors and tracing and then please contact CreamTec with information on your platform, JDK version and all relevant information. If you are deploying WebCream into your application server, be sure to follow the installation instructions and replicate the passing of parameters as found in WebCream's tomcat.sh. You can also play with the agent.useWebCreamFontsConfigFile property of your application as described in the customization document.

IllegalAccessException is thrown when I try to access my application through WebCream
Make sure that your start class is declared as public and it's main() function is public.

OutOfMemory Error is reported in the log files when the application runs under WebCream
WebCream engine has a fairly light memory footprint. It does not allocate a lot of objects and most memory is consumed by the HTML page being rendered. However, Swing is a known memory hog so the user application must be very dilligent about releasing unused objects to avoid memory leaks. First, make sure that there is enough memory allocated for the JVM that hosts the application emulated by WebCream. For in-process client execution mode it is the web container JVM such as Tomcat. For stand-alone client execution it is the JVM launched by WebCream. Use -Xmx JVM parameter to increase the amount of maximum memory it can allocate. Even though increasing the maximum memory may help, in the long run it may only delay the OutOfMemory error if the application is not releasing the memory. During the execution of the user application in WebCream, and after the session is cloased, the application is responsible for releasing any memory it has allocated. When the user exits the application WebCream will dispose of all application windows but if the application still has direct or indirect references to windows the memory is not going to be released. Use JProbe or another Java profiler to find and fix the memory leaks in the application. Another option is to switch WebCream to standalone execution mode where each client gets its own JVM. By recycling the JVMs often the leaks from the application will be irrelevent because all memory is released when the JVM shuts down.

GUI application responds to events such as mouse clicks but it does not work in WebCream
WebCream emulates some but not all events. Because the user interacts with an HTML page and not the GUI application events such as mouse movements, mouse clicks, focus changes and key presses most likely are not going to be emulated for your application. However, the events that reflect data and selection changes are emulated. Thus, in order for your application to work correctly you need to make sure that you are listening for the right events. For example, if you have a JTree and you want to do something whenever a user selects a different node you need to add a TreeSelectionListener. For a complete list of listeners see the FAQ page.

Standard Copy/Cut/Paste do not work through WebCream
Most likely this is the problem of the focus. Standard implementation of Copy/Cut/Paste works with the currently focused component. When your application runs as a GUI client it works fine, but when it runs through HTML the data for the application is sent as one batch so no focus operations are emulated. A workaround is to tie in the toolbar and menu commands with specific controls.

How do I turn on tracing and troubleshoot my application under WebCream?
WebCream is built with traces that display informative messages about the progress of loading your application and emulation of its environment. If anything goes wrong, you need to look at the traces for clues. The first place to check is the output on web server console window or the log file. You should see a stack trace and trace messages for the error. If the messages are not informative enough, you can increase the level of tracing by editing conf/TraceMgr.properties file and setting the trace level to 10 for all classes. If you are using a jit compiler, which is the default option for recent versions of JDK the stack traces are not going to have line numbers. To make stack traces more useful you need to disable jit by adding -Djava.compiler=none to the command line invoking java. For built-in server you just need to add this parameter to TOMCAT_OPS definition in tomcat.bat (tomcat.sh on UNIX) script. If you need further help or if you believe the problem is caused by a bug in WebCream, please send us the web server output traces and the stack trace. You can turn on tracing to a file by uncommenting creamtec.core.TraceMgr.logfile setting and specifying a path to the log file. This will instruct WebCream Trace Manager to write output to that file which you can mail to CreamTec Technical Support.

In the log file I see: "WARNING: unable to find the current instance of client agent. This can be due to multithreading in the GUI application."
This warning message is written when WebCream is not able to locate the instance of the current client agent. To improve scalability and to provide independent execution environments for emulated applications inside a shared JVM WebCream assigns each virtual client its own graphics context and AWT event dispatch thread. If during an operation the application or AWT/Swing framework attempts to locate a resource that is application-specific, WebCream has to determine the current client agent. WebCream maintains the association between the executing threads and the client agent, so most of the times it can correctly determine the agent that is executing the operation. However, if the application spawns background threads using custom thread groups, this association may be broken. Swing can also use threads to execute certain operations such as repaints in the background. Seeing this warning does not necessarily indicate that there is an error. It does however require attention to the operation that caused the warning in order to make sure that the functionality of the emulated application is preserved. If the functionality is not impaired, the warning can be ignored. To turn off this warning the cutoff level in TraceMgr.properties should be set to a value less then 10. Alternatively, the tracing level for creamtec.webcream.core.ClientAgent can be sent to a value less then 3.

I have a problem that is not listed here. Where do I go for help?
First read through the list of common problems and solutions on this page. If there is no solution for your problem in this document then try searching our website. If you are still missing the information you are looking for, contact CreamTec's support. Make sure that you have turned on the highest level of tracing as described in the previous section. Send us an email giving the following information (this is a must): your name, your organization, what platform you are running on, what version of WebCream do you have, what is your servlet engine and specifically what is the problem and how to reproduce it. We will be glad to give you help. Support can be contacted at support@creamtec.com.

<< back to Documentation

Copyright © CreamTec, LLC. All rights reserved


Home |  WebCream |  Contact