|
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. Built-in
demo applications can be used to test the setup and to see how Swing
components are represented in AJAX version of the application.
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
Installing AjaxSwing
Testing the installation and viewing demos
Configuring and deploying your applet or application
Advanced Topics
Creating application properties file manually
Installing AjaxSwing as a web application
Installing AjaxSwing 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 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.
Important. Make sure your installation path doesn't have spaces, e.g. C:\Program
Files\AjaxSwing may result in an error when you will try to configure the
servlet later. C:\Java\AjaxSwing is a valid installation
path. 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
Enabling the right JDK version.
AjaxSwing closely integrates with the JVM and because the internal classes of JVM
change from release to release AjaxSwing is shipped with several versions of its
libraries. You have to ensure that the libraries in AJAXSWING_HOME\lib and
AJAXSWING_HOME\lib\boot directories
match the selected version of JDK. After the installing AjaxSwing and settting
JAVA_HOME,
execute AJAXSWING_HOME/bin/setup/enableJdkXX.bat (enableJdkXX.sh on UNIX) script 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 JDK version of AjaxSwing
libraries by executing the appropriate script.
Testing installation and viewing demos
Once you have successfully installed AjaxSwing, 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 AjaxSwing. Run
the AjaxSwing
Console using AJAXSWING_HOME/bin/asConsole.bat [.sh] script and click on WindowsThemeDemo button in the toolbar. This automatically
starts the web server and loads WindowsThemeDemo into your browser. You can view the
same demo as Java GUI application by selecting View/WindowsThemeDemo from the AjaxSwing
Console menu. 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 WindowsThemeDemo link
or typing URL http://localhost:8040/ajaxswing/apps/WindowsThemeDemo
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.
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
-
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.
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 Windows
AjaxSwing
theme, copy image files to AJAXSWING_HOME/tomcat/webapps/ajaxswing/Windows_docs/images
directory. If the directory doesn't exist yet, run the server and view
WindowsThemeDemo 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:
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.
- 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 WindowsThemeDemo.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. 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.
- 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.
Installing AjaxSwing 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 AjaxSwing. Here is your generic check list as well as specific instructions for
some popular Web Servers.
- 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.
- 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
- add asboot.jar to boot CLASSPATH using -X parameter to java, for example
-Xbootclasspath/p:C:\AjaxSwing\lib\boot\asboot.jar
- add ajaxswing.home parameter specifying the directory where AjaxSwing was
installed, for example
-Dajaxswing.home=C:\AjaxSwing
In the end your java invocation line should look something like this:
java -Xbootclasspath/p:C:\AjaxSwing\lib\boot\asboot.jar -Dajaxswing.home=C:\AjaxSwing
org.apache.tomcat.startup.Tomcat
- 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 WindowsThemeDemo.
- 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:8040/ajaxswing/apps/myapp
Below are examples of confugration for some of the popular application servers.
| Web Server |
Required changes |
| Tomcat |
- Edit bin\catalina.bat[.sh]. The easiest way is to set JAVA_OPTS
environment variable that it used by the script already. Assuming that AjaxSwing
is in C:\AjaxSwing
set AJAXSWING_HOME=C:\AjaxSwing
set JAVA_OPTS=%JAVA_OPTS% -Xbootclasspath/p:"%AJAXSWING_HOME%\lib\boot\asboot.jar"
set JAVA_OPTS=%JAVA_OPTS% -Dajaxswing.home="%AJAXSWING_HOME%"
- Copy AJAXSWING_HOME\tomcat\webapps\ajaxswing.war to your
tomcat\webapps
- Take care of current working directory along
with images and other file resources as described above
- Copy your application .jar files to
tomcat\webapps\ajaxswing\WEB-INF\lib or add them to CLASSPATH in
catalina.bat
- Grant permissions AjaxSwing and your application libraries in the security policy (see AjaxSwing/tomcat/conf/catalina.policy)
|
| WebLogic |
- 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 ...
- Run WebLogic console and go to
mydomain\Deployments\Web Applications
- Click on Install a new Web Application and
select C:\AjaxSwing\tomcat\webapps\ajaxswing.war
- Take care of current working directory along with images and other file
resources as described above
|
| WebSphere |
- 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.
- Set/add the full path to asboot.jar to the
value of attribute bootClassPath of jvmSettings element
- 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>
- 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.
- 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.
|
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.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 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
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.
|
