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.
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.7, 1.8 from Oracle |
Servlet Container | Any application or web server that supports Servlet 2.2 or higher API. |
Disk space | 25 MB |
Browser | We support only the latest versions of GoogleChrome, Firefox, Safari, Internet Explorer |
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.7
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:- Start the web server
using startServer.bat (startServer.sh) script from AJAXSWING_HOME/bin directory. - Start the browser
and open AjaxSwing index page by typing http://localhost:8040/ajaxswing - View a demo application
by clicking on Run Demo button or typing URL http://localhost:8040/ajaxswing/apps/SwingSet2
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.-
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. - 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)
- 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.
- 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.
- 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:
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.
- 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.
- 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.
- 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
- 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.
- 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>
- 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
java -Xbootclasspath/p:C:\AjaxSwing402\lib\boot\asboot.jar -Dajaxswing.home=C:\AjaxSwing402 org.apache.tomcat.startup.Tomcat
- add asboot.jar to boot CLASSPATH using -X parameter to java, for example
- 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.
- 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.
- 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)
- 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 |
|
WebLogic |
|
WebSphere |
|
JBoss EAP 6.1.0 |
|
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.7 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:
- Set JAVA_HOME in AjaxSwing/bin/setEnv.bat [.sh] to point to the JRE that will be used to run AjaxSwing
- Run AjaxSwing/bin/setup/enableJdk1X.bat [.sh] where X matches the JRE version
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..
- WindowsThemeDemo. Use this link to test the correctness of installation
- 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.