Installation, setup and application configuration guide

AjaxSwing is a unique product that provides runtime conversion of Java Swing applications into dynamic HTML web site with AJAX functionality. Web enabling requires installing AjaxSwing and specifying deployment and configuration properties for the Swing application. AjaxSwing provides AjaxSwing Console, a simple wizard-driven GUI to configure your application settings, and a pre-configured Tomcat web server that be used immediately to test your application execution.

To find out more about AjaxSwing architecture please read AjaxSwing White Paper. It is highly recommended to read this setup guide entirely to avoid configuration errors.

Requirements on installation and running

Quick Start

Step 1. Installing AjaxSwing
Step 2. Testing the installation and viewing demos
Step 3. Configuring and deploying your applet or application

Advanced Topics

Creating application properties file manually
Installing AjaxSwing as a web application
Installing AjaxSwing on UNIX
Applying JRE compatibility patches
Monitoring and troubleshooting

Requirements on installation and running

Platform Any platform supported by JDKs listed below. Tested on Windows, Linux, HP UX, Sun Solaris, IBM AIX
JDK 1.5, 1.6 or 1.7 from Sun Microsystems
Servlet Container Any application or web server that supports Servlet 2.2 or higher API.
Disk space 25 MB

Step 1. Installing AjaxSwing on your server

AjaxSwing is packaged in multiple formats which include a cross-platform .zip and a Windows GUI installer. Built-in Apache Tomcat web server gives you everything you need to deploy and run your applications. The fastest way to get started is to use the preconfigured Tomcat even if the target production environment runs on a different servlet container.

If installing on UNIX, please read UNIX installation instructions.

Throughout this document AJAXSWING_HOME refers to the directory that AjaxSwing was installed.

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

Step 2. Testing installation and viewing demos

Once you have successfully installed AjaxSwing, you are ready for a preview. To test whether your configuration is correct, run the AjaxSwing Console using AJAXSWING_HOME/ajaxswing_console.bat [bin/asConsole.sh] script and click on AjaxSwingDemo button in the toolbar. This automatically starts the web server and loads AjaxSwingDemo into your browser. Although AjaxSwing Console is the fastest and most convenient way, you can start web-enabled application manually: If the demo application is working it means the setup was successful and you can proceed to web-enabling 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 AjaxSwing/logs and AjaxSwing/tomcat/logs for errors.

Step 3. 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
The easiest way to do to create application properties file is by using AjaxSwing Console. You can run the console either through the AjaxSwing program group on Windows, or using the asConsole.bat (asConsole.sh script on UNIX) in AJAXSWING_HOME/bin directory. Follow AppWizard to specify application and/or applet parameters. You can also create the application properties file manually as described in Creating application properties file manually. Additional properties can be added directly to the generated application .properties file, which can be found in the AJAXSWING_HOME/conf directory. Please take your time to examine the parameters available and the meaning of them as described in Customizing AjaxSwing.  For applets you may have to specify all applet.* properties as described in default.properties and Customizing AjaxSwing document. Note that changes to the application properties require restarting of the web server.

Deployment options
  1. Using AjaxSwing's preconfigured servlet container (recommended)
    In this approach you configure or copy your libraries, classes and images into AjaxSwing directory structure and use built-in Tomcat server. This is the quickest approach that is highly recommended for product evaluation.

  2. Deploying AjaxSwing 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 AjaxSwing's preconfigured servlet container (recommended)

  1. Configuring environment If your application needs environment variables, additional CLASSPATH entries or JVM parameters set via -D option of Java invocation line you need to add them to AJAXSWING_HOME/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.

    All application classes and third party libraries must be available to AjaxSwing classloader. The best option is to list .jar files in agent.classPath application property, either by manually editing your application properties file in AjaxSwing/conf or in the AppWizard of AjaxSwing console. Another option is to copy all your .jar files to AjaxSwing/wcapps/lib and your .class files to AjaxSwing/wcapps/lib/classes directory. Note that all classes loaded from wcapps directory are shared between the virtual users, whereas classes loaded from agent.classPath jars are user-specific.

  2. Copying images If your application uses images and icons you have to copy them to a web server directory visible to the browser. Assuming you are using default Light AjaxSwing theme, copy image files to AJAXSWING_HOME/tomcat/webapps/ajaxswing/Light_docs/images directory. If the directory doesn't exist yet, run the server and view SwingSet2 application which will make the web server unpack AjaxSwing web application. If using a different theme, use <Theme>_docs as the target directory for copying.

  3. Viewing your application in a browser Once all configuration steps are accomplished, restart the servlet container that is running AjaxSwing. 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/ajaxswing/apps/myapp

    The name of the host (localhost), port (8040) and the application name (myapp) should match your environment. AjaxSwing will attempt to load and execute application defined by AJAXSWING_HOME/conf/myapp.properties file.


Advanced Topics

Creating application properties file manually

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

  1. Create your application properties file in AJAXSWING_HOME/conf directory. Each application web enabled through AjaxSwing must have a properties file that configures the way AjaxSwing handles the application and renders HTML. The easiest way to create your properties file is to copy MailDemo.properties and rename it to your application name, e.g. OnlineStore.properties.
  2. Specify agent.appStartClass as the class that acts as the entry point to your Swing application. This class's main() function will be executed when a new web client requests the application.
  3. Optionally, in the application properties file you can configure other parameters of your application, for complete list of all available properties read Customizing Application Properties.

Installing AjaxSwing as web application

  1. Important. Make sure that the path to AjaxSwing installation directory doesn't have spaces, as required in installation instructions. Examples below assume that AjaxSwing was installed to C:\AjaxSwing.
  2. If you are running all AjaxSwing applications with router.inProcess=false, you do not have to modify any web/application server startup scripts. The only thing you have to do is to tell AjaxSwing it's home directory by specifying initial parameter to AppRouter servlet as follows:
        <init-param>
          <param-name>ajaxswing.home</param-name>
          <param-value>c:/AjaxSwing402</param-value>
        </init-param>
        
  3. If you are using router.inProcess=true mode, locate and edit the batch file/shell script/configuration file that for 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
    • add asboot.jar to boot CLASSPATH using -X parameter to java, for example
      -Xbootclasspath/p:C:\AjaxSwing402\lib\boot\asboot.jar
    • add ajaxswing.home parameter specifying the directory where AjaxSwing was installed, for example -Dajaxswing.home=C:\AjaxSwing402
    In the end your java invocation line should look something like this:
    java -Xbootclasspath/p:C:\AjaxSwing402\lib\boot\asboot.jar -Dajaxswing.home=C:\AjaxSwing402 org.apache.tomcat.startup.Tomcat
  4. Follow your app/web server documentation to deploy a web application. Typically, you would use a console or simply copy AJAXSWING_HOME/tomcat/webapps/ajaxswing.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.
  5. If not using a console you may have to define AjaxSwing 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.
  6. Run your app/web server and try to access AjaxSwing using the URL similar to http://hostname:port/ajaxswing/index.html, assuming that you installed AjaxSwing on your local host, your web server is running on port <port> and you used "ajaxswing" as the context name for web application. If it is configured correctly, you'll see a Welcome page and will be able to run MailDemo application. (For SwingSet2 you need to add SwingSet2.jar to agent.classPath in SwingSet2.properties)
  7. Assuming that you have followed the steps on configuring your application and created a "myapp.properties" file in AjaxSwing/conf you can access your application using the URL similar to
    http://localhost:8080/ajaxswing/apps/myapp

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

Web Server Required changes
Tomcat 7
  1. Created bin\setenv.bat[sh]. The easiest way is to set CATALINA_OPTS environment variable that it used by the script already. Assuming that AjaxSwing is in C:\AjaxSwing402
    set CATALINA_OPTS= -Xbootclasspath/p:c:\AjaxSwing402\lib\boot\asboot.jar -Dajaxswing.home=c:/AjaxSwing402/  
              
  2. Copy AJAXSWING_HOME\tomcat\webapps\ajaxswing.war to your tomcat\webapps
  3. Take care of current working directory along with images and other file resources as described above
  4. Grant permissions AjaxSwing and your application libraries in the security policy (see AjaxSwing/tomcat/conf/catalina.policy)
WebLogic
  1. Assuming that you will deploy AjaxSwing 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 AjaxSwing. The changed line should start like this
    "%JAVA_HOME%\bin\java" -Xbootclasspath/p:C:\AjaxSwing\lib\boot\asboot.jar -Dajaxswing.home=C:\AjaxSwing -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:\AjaxSwing\tomcat\webapps\ajaxswing.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 AjaxSwing. Open the configuration file for the server where you are planning to run AjaxSwing 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 asboot.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 ajaxswing.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:\AjaxSwing\lib\boot\asboot.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="ajaxswing.home" value="C:\AjaxSwing"/>
    </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 AjaxSwing as a web application.
  5. In the Application Installation Wizard browse for the ajaxswing.war file (it should be in AjaxSwing/Tomcat/webapps directory), specify "AjaxSwing" as application name and "ajaxswing" as context root. Click Next and finish the installation.
JBoss EAP 6.1.0
  1. Let's assume that AjaxSwing and JBoss downloaded and unpacked at:
    C:\WebClient\AjaxSwing
    C:\WebClient\jboss-eap-6.1
                
  2. Copy [C:\WebClient\AjaxSwing\tomcat\webapps\ajaxswing.war] to [C:\WebClient\jboss-eap-6.1\standalone\deployments]
  3. Open [C:\WebClient\jboss-eap-6.1\bin\standalone.conf.bat] Add this line after the :JAVA_OPTS_SET
    set "JAVA_OPTS=%JAVA_OPTS% -Xbootclasspath/p:C:\WebClient\AjaxSwing\lib\boot\asboot.jar -Dajaxswing.home=C:/WebClient/AjaxSwing/"
                 
    Comment out the line [set "JAVA_OPTS=-Xms1303M -Xmx1303M -XX:MaxPermSize=256M"] or make sure that the memory settings specified there do not conflict with the specified in [C:\WebClient\AjaxSwing\bin\setEnv.bat]
  4. Open [C:\WebClient\AjaxSwing\conf] and add the lines listed below into SwingSet2.properties and MailDemo.properties
    router.clientsPerJVM=1
    router.retireJVMAfterClients=1
    router.inProcess=false
    router.preloadApp=false
    router.preloadWaitForApp=false
              
  5. Run [C:\WebClient\jboss-eap-6.1\bin\standalone.bat]
  6. The applications could be found here:
    http://localhost:8080/ajaxswing/apps/MailDemo
    http://localhost:8080/ajaxswing/apps/SwingSet2

Installing AjaxSwing on UNIX

You should manually install AjaxSwing by unzipping the downloaded .zip file to a directory that we will refer to as AJAXSWING_HOME. The only additional step is to grant "execute" permissions on setup shell script in AJAXSWING_HOME/bin/setup directory and to run it. This can be done using the following command lines in AjaxSwing's bin/setup directory:

chmod 777 setup.sh
./setup.sh

Configuring Graphics Environment

UNIX systems, unlike Windows, may or may not provide Java with a runtime graphics environment. The graphics environment is used to load and obtain font metrics, display native windows and perform other graphical operations. Client applications that use Swing and AWT applications must have a graphics environment to execute. Server-side web applications that use servlets and JSP files do not need a graphics environment. Since AjaxSwing bridges client side and server side technologies, it provides several alternatives to executing on the operating system that does not guarantee the availability of a graphics environment.

AjaxSwing provides a virtual graphics environment that allows Swing and AWT run on an OS that does not have a native graphics environment available. The default configuration uses that graphics environment and should work out of the box. If after installing AjaxSwing on UNIX you are able to run WindowsThemeDemo in the browser that means that the default configuration is suitable for the local OS.

Some UNIX configurations may not be running X-Window daemon process or may not grant access to it to the user that is running AjaxSwing. If the security policy allows it, contact the system administrator about enabling access to X-Window (they need to run X daemon and possibly grant permissions using xhost command). If the security policy does not allow a graphics environment, the best approach is to install and run a virtual X frame buffer using xvfb command and set DISPLAY variable to point to the display number supported by xvfb.

Some versions of JDK (e.g. JDK 1.5 on Ubuntu) may expect a Motif-derived graphics environment, which would result in a ClassCastException when starting up the default configuration of AjaxSwing. In that case set agent.usePlatformGraphicsEnvironment configuration property to true to force AjaxSwing to use the native graphics environment.

Configuring fonts on UNIX

In order for AjaxSwing to run correctly on some flavors of UNIX, an additional configuration of Java environment may be needed.  AjaxSwing 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. AjaxSwing is shipped with true type fonts to ensure that the application appears the same on all platforms. AjaxSwing uses java.awt.fonts property to tell JVM where to load the fonts from. AjaxSwing also has its own font.properties file that provides font mapping for JVM, and to use it you need to set "agent.useAjaxSwingFontsConfigFile" property to "true" in AjaxSwing/conf/default.properties.

If "java.awt.fonts" system property it is not specified correctly, JVM may crash at the startup giving a core dump. AjaxSwing/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.6.0 then the invocation should be as follows

java -Djava.awt.fonts=/opt/jdk1.6.0/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 AjaxSwing/lib/fonts and see if it fixed the problem.

You can also set agent.usePlatformFontConfiguration configuration property to "true" to force using the platform native configuration class.

After installing proceed to Testing the installation and viewing demos

Applying JRE compatibility patches

Because AjaxSwing closely integrates with JRE it is always recommended to run AjaxSwing on the same JRE that was used to build AjaxSwing, down to the minor version number. To ensure this compatibility it is recommended to run a script in the target environment to make AjaxSwing libraries compatible with the locally installed JRE. Follow the steps below:

Patches are applied to AjaxSwing/lib/asboot.jar file any time you run enableJdk1X script.

When AjaxSwing built-in webserver is used, it automatically applies the compatibility script if the version of AjaxSwing libraries doesn't match the currently running JRE.

Monitoring and troubleshooting

AjaxSwing index JSP page

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

  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 AjaxSwing. You need to include this page when contacting CreamTec Support.

AjaxSwing Logging

AjaxSwing supports logging of operations progress. You can control the level of details using file AJAXSWING_HOME/conf/TraceMgr.properties. The main gauge used to control the level is com.creamtec.core.TraceMgr.level, which can be set to 0 for no tracing, 1 to the least detail logging and 10 for the most detailed logging. 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 AjaxSwing, please search our Technical Support Forum and if post your questions there.