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
Home |
WebCream |
Contact
|