WebCream installation, setup and application configuration guide

WebCream is a unique product that allows your Java applications to be accessible as a dynamic HTML web site, in other words, to be web-enabled practically without changes to your program. 

Web enabling of your application requires installing WebCream and specifying deployment and configuration properties for your application. WebCream provides WebCream Console, a wizard-driven GUI to configure your application settings, and a built-in web server which is pre-configured for WebCream and can be used immediately to test your application execution. Please read the instructions carefully to ensure the proper installation and setup of the software. Once configured, you can test WebCream using built-in demo application and finally test run your application.

This document explains how to install WebCream and make your Swing or AWT application web-enabled. If you want to read more about WebCream please read WebCream White Paper. We suggest you to read this document entirely especially if this is your first time.

Requirements on installation and running

Quick Start

Installing WebCream
Testing the installation and viewing demos
Configuring and deploying your applet or application

Advanced Topics

Creating application properties file manually
Customizing style-sheets and creating your own theme
Installing WebCream as web application
Installing WebCream on UNIX
Monitoring and troubleshooting




Requirements on installation and running

Platform Any platform that has Sun JDK 1.2.2 or higher. Tested on Windows Vista/XP/NT/2000, Linux, HP UX, Sun Solaris, IBM AIX
JDK 1.2.2, 1.3.2, 1.4.2, 1.5, 1.6. Tested with JDKs from Sun
Servlet Container Any application or web server that supports Servlet 2.2 or higher API.
Disk space 25 MB

Installing WebCream on your server

WebCream installation is packaged in multiple formats which include a .jar file that can be used on any platform and .exe file that is a GUI self installer for Windows platforms. WebCream comes with built-in web server, Apache Tomcat that gives you everything you need to deploy and run your applications. The simplest and fastest way to get started with WebCream is to get a self installer and just follow the instructions. This type of installation is recommended for most users.

Important. Make sure your installation path doesn't have spaces, e.g. C:\Program Files\WebCream may result in an error when you will try to configure the servlet later. C:\Java\WebCream is a valid installation path. If installing on UNIX, please read UNIX installation instructions.

It is highly recommended to define an environment variable JAVA_HOME that points to JDK installation directory. WebCream will try to autodetect the location of JDK but it is safer to define it explicitly. You can set this variable in setEnv.bat (setEnv.sh on UNIX) as follows:
         set JAVA_HOME=C:\JDK1.5

Enabling the right JDK version. WebCream closely integrates with the JVM and because the internal classes of JVM change from release to release. WebCream is shipped with several versions of its libraries. You have to ensure that the libraries in <WebCreamRoot>\lib and <WebCreamRoot>\lib\boot directories match the version of JDK that you use to run WebCream. After the installation is completed, execute enableJdkXX.bat (enableJdkXX.sh on UNIX) file where XX is 14 for JDK 1.4.x, 15 for JDK 1.5.x and so on. You can always switch to a different version of WebCream libraries by executing the appropriate script.

Testing installation and viewing demos

Once you have successfully installed WebCream, you are ready for a preview. To test whether your configuration is correct, start the bundled Tomcat server and view the demo programs provided with WebCream. All demo programs are pre-configured so no extra configuration is necessary. The easiest way to test the installation is to run the WebCream Console and click on WindowsThemeDemo button in the toolbar. This automatically starts the server and loads WindowsThemeDemo into your browser. You can view the same demo as Java GUI application by selecting View/WindowsThemeDemo from the WebCream Console menu. Although WebCream Console is the fastest and most convenient way, you can start web-enabled application manually: Once the demo application is working you can try to web-enable your application as described below. If the demo application is not working, making sure that Tomcat has actually started and check the log files in WebCream/logs and WebCream/tomcat/logs for errors.

Configuring and deploying your applet or application

The first thing to do is to is create an application properties file and decide on the deployment method and directory structure.

Creating application properties file
Your first step is to create application properties file, and the easiest way to do so is by using WebCream Console. You can run the console either through the WebCream program group on Windows, or using the wcConsole.bat (wcConsole.sh script on UNIX) in <WebCreamRoot>/bin directory. Follow AppWizard to specify application and/or applet parameters. You can create the application properties file manually as described in Creating application properties file manually. You can configure additional properties directly in the .properties file, which can be found in the <WebCreamRoot>/conf directory. Please take your time to examine the parameters available and the meaning of them as described in Customizing WebCream. If WebCream is already configured, you can preview your application when prompted from AppWizard, otherwise say "No" and proceed with the deployment according to the approach you have selected. For applets you may have to specify all applet.* properties as described in default.properties and Customizing WebCream document. Note that changes to the application properties require restarting of the web server.

Deployment options
  1. Using WebCream's preconfigured servlet container (recommended)
     In this approach you configure or copy your libraries, classes and images into WebCream directory structure and use built-in Tomcat server. This is the quickest approach that will work for most of the thin clients such as applets and applications.
  2. Deploying WebCream as web application into external servlet container
    This approach requires more configuration work and a thorough understanding of your application server and web application directory structure. It gives you the flexibility to use your servlet container at the expense of extra setup work.

Using WebCream's preconfigured servlet container (recommended)

  1. Configuring environment
    If your application needs environement variables, additional CLASSPATH entries or JVM parameters set via -D option to Java invocation line you need to add them to <WebCream>/bin/setEnv.bat (setEnv.sh on UNIX). This file is executed when a built-in web server is started and when an emulated applications is run.

  2. Copying images
    If your application uses images and icons you have to copy them to directory visible to the browser. Assuming you are using default Windows theme, copy them to <WebCreamRoot>/tomcat/webapps/webcream/Windows_docs/images directory. If the directory doesn't exist yet, run the server and view WindowsThemeDemo application which will make the web server create the directory structure for WebCream web application. If using a different theme, use <Theme>_docs as the target directory.

  3. Viewing your application in a browser
    Once all configuration steps are accomplished, restart the servlet container that is running WebCream. If using built-in Tomcat, execute stopServer.bat and startServer.bat (or stopServer.sh and startServer.sh on UNIX). When the server has started, run the browser and view your application using a URL similar to the one shown below:

    http://localhost:8040/webcream/apps/myapp

    The name of the host (localhost), port (8040) and the application name (myapp) should match your environment.

 

 

 

 

Advanced Topics

Creating application properties file manually

As alternative to WebCream Console you can create properties file manually. If you wish to do so, follow these instructions.

  1. Create your application properties file in <WebCreamRoot>/conf directory. Each application web enabled through WebCream must have a properties file that configures the way how WebCream handles the application and renders HTML. The easiest way to create your properties file is to copy WindowsThemeDemo.properties and rename it to your application name, e.g. OnlineStore.properties.
  2. Specify agent.appStartClass as the class that contains main function of your application and acts as the entry point. This class's main() function will be executed when a new web client requests the application. The agent.appStartClass is optional if you derive your properties from other application. In this case you should specify your parent in the property parent. 
  3. Optionally, in the application properties file you can configure other parameters of your application, such as the default width of text components and how disabled components are handled. For complete list of all available properties read Customizing Application Properties.

Customizing style-sheets and creating your own theme

Depending on edition WebCream has up to four themes: Windows, Blue, Fancy, and WebCream. They are defined in the corresponding directories with _docs appended to the theme name. Take a look at their content. Each theme has several style sheets, Java scripts and images. The property html.theme allows to select one of existing theme for your application. You can create your own theme. This is the easiest way how to start: 

  1. Copy any existing theme folder, let's say Windows_docs, to MyNewTheme_docs. 
  2. Change theme in the application property file: 
    html.theme=MyNewTheme (note: there is no _docs here, it will be appended automatically by WebCream)
  3. Change something in css file, for example background color to red
    .window {background-color:red}
  4. Start WebServer and your application and make sure that your theme was read properly by WebCream. In this example, you should see windows with red background. 

Installing WebCream as web application

If you want to learn more about web applications please go to JavaSoft's Web Site. If you installed web applications before then you should not have problem with WebCream. Here is your generic check list as well as specific instructions for some popular Web Servers.

  1. Important. Make sure that the path to WebCream installation directory doesn't have spaces, as required in installation instructions. Examples below assume that WebCream was installed to C:\WebCream.
  2. Locate and edit the batch file/shell script that is used to start your application server. This is the file that runs "java" with your app server main class. Many modern servers such as WebLogic and Tomcat have a separate file often called setEnv.bat that can be used to setup the local environment, and if such file exists it is a better choice then the server invocation script. The table below gives examples for some of the common web/app servers. Find a line where java is invoked and In the end your java invocation line should look something like this:
    java -Xbootclasspath/p:C:\WebCream\lib\boot\wcboot.jar -Dwebcream.home=C:\WebCream org.apache.tomcat.startup.Tomcat
  3. Follow your app/web server documentation to deploy a web application. Typically, you would use a console or simply copy <WebCreamRoot>/tomcat/webapps/webcream.war to the webapps directory of your web server. Although most web servers do have webapps directory, some web servers might not have it. In that case read carefully the next step.
  4. If not using a console you may have to define WebCream as a web application in the server's configuration file. Some web servers like Tomcat will "pick up" any web application that has been copied to webapps.
  5. Run your app/web server and try to access WebCream using the URL similar to http://hostname:port/webcream/index.html, assuming that you installed WebCream on your local host, your web server is running on port <port> and you used "webcream" as the context name for web application. If it is configured correctly, you'll see a Welcome page and will be able to run WindowsThemeDemo.
  6. Assuming that you have followed the steps on configuring your application and created a "myapp.properties" file in WebCream/conf you can access your application using the URL similar to
    http://localhost:8040/webcream/apps/myapp

Below are examples of confugration for some of the popular application servers.

Web Server Required changes
Tomcat
  1. Edit bin\catalina.bat[.sh]. The easiest way is to set JAVA_OPTS environment variable that it used by the script already. Assuming that WebCream is in C:\WebCream 
              set WEBCREAM_HOME=C:\WebCream
          set JAVA_OPTS=-Xbootclasspath/p:"%WEBCREAM_HOME%\lib\boot\wcboot.jar" -Dwebcream.home="%WEBCREAM_HOME%" %JAVA_OPTS%
  2. Copy <WebCreamRoot>\tomcat\webapps\webcream.war to your tomcat\webapps
  3. Take care of current working directory along with images and other file resources as described above
  4. Copy your application .jar files to tomcat\webapps\webcream\WEB-INF\lib or add them to CLASSPATH in catalina.bat
  5. Grant permissions WebCream and your application libraries in the security policy (see WebCream/tomcat/conf/catalina.policy)
WebLogic
  1. Assuming that you will deploy WebCream to the default server, edit config\startWebLogic.cmd. Almost at the end of the file find "java" invocation line that starts with %JAVA_HOME%\bin\java and add parameters required to run WebCream. The changed line should start like this
    "%JAVA_HOME%\bin\java" -Xbootclasspath/p:C:\WebCream\lib\boot\wcboot.jar -Dwebcream.home=C:\WebCream -hotspot -ms64m -mx512m ...
  2. Run WebLogic console and go to mydomain\Deployments\Web Applications
  3. Click on Install a new Web Application and select C:\WebCream\tomcat\webapps\webcream.war
  4. Take care of current working directory along with images and other file resources as described above
WebSphere
  1. Edit server configuration file to include Java parameters required to run WebCream. Open the configuration file for the server where you are planning to run WebCream from WebSphere/AppServer/config directory. The configuration file for the default server is server-cfg.xml. Once opened, locate "processDefinition" tag in the file.
  2. Set/add the full path to wcboot.jar to the value of attribute bootClassPath of jvmSettings element
  3. Add a systemProperty element as a child element to jvmSettings element, and specify the correct path as the value of webcream.home property. See the example below

      <processDefinition xmi:type="server:JavaProcessDef" xmi:id="ProcessDef_1"
                     executableName="${JAVA_HOME}/bin/java" commandLineArguments="" 
                     workingDirectory="${WAS_ROOT}/bin" executableTargetKind="JAVA_CLASS" 
                     executableTarget="com.ibm.ws.bootstrap.WSLauncher">
     <executionSettings xmi:id="ProcessExecution_1" umask="777" runAsUser="root"/>
     <ioRedirect xmi:id="OutputRedirect_1" stdoutFilename="${LOG_ROOT}/default_server_stdout.log" 
                 stderrFilename="${LOG_ROOT}/default_server_stderr.log"/>
     <jvmSettings xmi:id="JavaVirtualMachine_1" 
                  classpath="" bootClasspath="C:\Program Files\WebCream\lib\boot\wcboot.jar" 
                  verboseModeClass="false" verboseModeGarbageCollection="false" 
                  verboseModeJNI="false" initialHeapSize="0" maximumHeapSize="256" 
                  runHProf="false" hprofArguments="" debugMode="false" 
                  debugArgs="" genericCommandLineArgs="com.ibm.ws.runtime.StandardServer" 
                  disableJIT="false">
        <systemProperties xmi:id="SystemProperty_1" name="webcream.home" value="C:\Program Files\WebCream"/>
     </jvmSettings>
  </processDefinition>
  4. Run the Administrative Console for the server you wish to deploy to, select the node and click on Enterprise Applications. Click Install to install WebCream as a web application.
  5. In the Application Installation Wizard browse for the webcream.war file (it should be in WebCream/Tomcat/webapps directory), specify "WebCream" as application name and "webcream" as context root. Click Next and finish the installation.

Installing WebCream on UNIX

You should manually install WebCream by unjarring the downloaded .jar file. The only additional step is to grant "execute" permissions on setup shell script in <WebCreamRoot>/bin/setup directory and to run it. This can be done using the following command lines in WebCream's bin directory:

chmod 777 setup.sh
./setup.sh

Configuring fonts on UNIX

In order for WebCream to run correctly on some flavors of UNIX, an additional configuration of Java environment may be needed.  WebCream is preconfigured to run correctly on all supported UNIX platforms, but if the font sizes and text-based control sizes are incorrect, of if the web server core dumps even on the built-in demo application, some experimenting with font loading parameters can lead to a solution. WebCream is shipped with true type fonts to ensure that the application appears the same on all platforms. WebCream uses java.awt.fonts property to tell JVM where to load the fonts from. WebCream also has its own font.properties file that provides font mapping for JVM, and to use it you need to set "agent.useWebCreamFontsConfigFile" property to "true" in WebCream/conf/default.properties.

If "java.awt.fonts" system property it is not specified correctly, JVM may crash at the startup giving a core dump. WebCream/bin/setEnv.sh is written to pass this parameter to JVM by autodetecting your JVM installation directory. However, you may have to set JAVA_HOME environment variable explicitly to point to the installation directory of the JDK. Ultimately, you must make sure that the java invocation line has a parameter java.awt.fonts that is set to the full path to the fonts directory. As an example, if you JDK is installed in /opt/jdk1.2.2 then the invocation should be as follows

java -Djava.awt.fonts=/opt/jdk1.2.2/jre/lib/fonts

Make sure that you are pointing to the right directory. It should contain files with .ttf extension. The second system property to experiment with is "java2d.font.usePlatformFont". Try setting it to "true" and setting "java.awt.fonts" property to WebCream/lib/fonts and see if it fixed the problem.

After installing proceed to Testing the installation and viewing demos

Monitoring and troubleshooting

WebCream index JSP page

Once you typed in http://localhost:8040/webcream the WebCream index.jsp will be displayed in your browser. It shows the most useful links for troubleshooting WebCream..

  1. WindowsThemeDemo. Use this link to test the correctness of installation
  2. Environment Page. Displays a comprehensive list of all environment settings and parameters that are used by WebCream. You need to include this page when contacting CreamTec Support.

WebCream tracing

WebCream supports tracing of operations progress. You can control the level of details using file <WebCreamRoot>/conf/TraceMgr.properties. The main gauge used to control the level is creamtec.core.TraceMgr.level, which can be set to 0 for no tracing, 1 to the lowest tracing and 10 for the highest level of traces. Note that the higher is the level, the more overhead will it add which can become significant in production environments.

For more info read the troubleshooting page.

If you need further assistance or if you are having problems with configuring and running WebCream, please search our Technical Support Forum and if post your questions there.