Customizing and configuring AjaxSwing using application properties files

AjaxSwing is highly customizable and its various parameters can be changed on application basis using the properties files located in the conf directory. Each application is represented with a properties file matching the application name with extension .properties. The application properties file gets created when you use the Application Wizard of AjaxSwing Console. However, you can also create it manually or copy one of the existing files and change its values. The list of possible properties, their meaning and example values is giving the table below.

Note, that the changes to the application properties file will not take effect until you restart the web sever or servlet engine.

Property Name



Specifies the parent configuration file that this properties file is based on. All properties default to the values specified in the parent properties file and can be overridden. If no parent is specified, is used as a parent configuration. Only the name should be given, ".properties" extension will be added automatically

Example: parent=AppBase

Router Servlet properties



inProcess indicates whether the multiple instances of client application will be sharing the same JVM process (value of true), or each client will get its own (value of false).

Example: router.inProcess=true



If set to true, Router will preload the application when the servlet is instantiated. Preloading eliminates the wait during the initialization of the application when the first client connects. Applicable only for inProcess=true mode.

Example: router.preloadApp=true



Used when preloadApp. If set to true, the router will wait during the initialization for the application's initialization to finish (main() function to return). If false, the preloading will be done asynchronously. This is useful if you have an application that takes a long time to start, but the servlet container will timeout the servlet initialization (setting it to false will prevent the timeout). Default is true.

Example: router.preloadWaitForApp=false



Sets how long will the router wait for the newly started client process (JVM) to become available before timing out. Applicable only for inProcess=false mode. Measured in seconds with the default value of 10.

Example: router.agentWaitTimeout=20


time in seconds

Specifies the expiration time for a web session. The session is expired when there is no user activity for at least a period specified by the timeout. AjaxSwing does not rely on web server session timeout because it needs fine control over the session tracking and resource cleanup. Therefore if AjaxSwing is deployed with an external servlet container the session timeout for the AjaxSwingRouter servlet should be greater then the sessionTimeout specified in the application properties file. The default value is 300 seconds

Example: router.sessionTimeout=600



Used to tell AjaxSwing the port on which the RMI registry is or should be running. AjaxSwing uses RMI registry to communicate with client agents that run in stand alone mode. If the registry is already running on the given port, AjaxSwing will use it; otherwise it will attempt to create registry on that port. The default value is 1099. This parameter can not be overriden by application property files, so it always has to be specified in

Example: router.registryPort=1100



Used to override the default character encoding that AjaxSwing servlet will use when creating HTML pages. By default AjaxSwing uses the current character encoding of the platform that it is running on. Character encoding is important for internationalization and typically it should match the encoding of the browser. The value of this parameter is any of the values allowed by Java String class. This parameter can not be overriden by application property files, so it always has to be specified in

Example: router.characterEncoding=ISO8859_1

Client Agent Properties (applies to both applications and applets)



Specifies the class, that has the main function as an entry point for your application. For applications it is the class that has your main() function. For applets, it’s the class that extends JApplet or Applet.

Example: agent.appStartClass=com.creamtec.ajaxswing.ui.DemoFrame



If your application receives command line parameters, put them here just as you would pass them to main(). Applicable only to applications

Example: agent.appParams=-port 8000 –silent



Specifies a list of .jar, .zip archives and directories from which application classes will be loaded. Each client executing within a JVM is going to have a separate copy of all classes loaded from this class path. This ensures that static data is not shared by clients when the JVM is shared. Classes loaded from system CLASSPATH are shared by all client sessions. In order for class loading to work properly you should ensure that classes that have static data are specified in agent.classPath and not specified in the system CLASSPATH.

Example: agent.classPath=c:\myApp\myapp.jar;c:\myApp\classes



Allows specifying the title of the window that should be first displayed to the user when a new session begins. Used for synchronization of multithreaded apps. When this property is specified, AjaxSwing will wait until a window with the given title is displayed before rendering the first HTML page for the new client session. For details refer to the document on multithreading.

Example: agent.appStartWindow=Login


time in seconds

Specifies the maximum time AjaxSwing should wait for an operation to complete. Most useful when debugging and fine tuning an application with AjaxSwing, especially in cases of multithreading. The timeout is implemented to ensure that some feedback is given to the user's browser even if the emulation thread didn't return. The default value is 120 seconds.

Example: agent.requestTimeout=60



Controls whether or not AjaxSwing will allow applications to change the look and feel using UIManager. It is not recommended to allow the change because it may prevent AjaxSwing from working correctly. This property should be used for testing purposes only

Example: agent.allowLFChange=false



Allows you to override the default logic of handling the loading of fonts. If set to true (default), AjaxSwing will use its own file from lib directory on Linux platform in order to ensure proper loading of fonts for text control sizes. Setting this property to false allows overriding this logic to always use JDK's This can be helpful for fine-tuning the loading of fonts and to prevent crashes of those occur at application loading.

Example: agent.useAjaxSwingFontsConfigFile=false

Applet specific properties (applies only to applets)



Page title for applets. For applications the title of the current window is used.

Example: applet.title=Welcome to MyApplet



Allows you to specify what will the applet get when it calls getCodeBase() method of AppletContext.

Example: applet.codeBase=http://localhost:8040/codebase/myapplet.jar



Allows you to specify what will the applet get when it calls getDocumentBase() method of AppletContext

Example: applet.documentBase= http://localhost:8040/html/myapplet.html

applet.width, applet.height


Specifies the initial size of the applet. Analogous to specifying dimensions in APPLET tag of an HTML page. If not specified, the preferred size of the applet is used, and if no preferred size is returned then the default values of 300 by 200 is used.

Example: applet.width=100



Allows you to specify static parameters to the applet. Just like you would specify them on the HTML page, you need to add each parameter and its value to the properties file. Note, that to pass dynamic parameters you can use the servlet parameters as described in Passing Dynamic Parameters To An Applet.

Example: applet.param.serverPort=8000
Example: applet.param.color=red

HTML generation and display properties



Can be used to override the default URL determined by AjaxSwing router servlet. This URL where AjaxSwing will look for application images, AjaxSwing theme images, scripts and other documents. This is generally the URL you use to access your HTML pages, and all relative paths to images will start from this directory. For example if you set docsURL to http://localhost/myapp and your application will be loading an image using a relative URL of “images/logo.gif” then AjaxSwing will look for logo.gif using URL http://localhost/myapp/images/logo.gif.

Example: html.docsURL=http://localhost:8040/ajaxswing



Can be used to override the default URL determined by AjaxSwing router servlet. URL through which AjaxSwingRouter servlet can be accessed. By default the AjaxSwingRouter will try to determine the URL based on the host name and the port on which it is running. You can use this property to override the default URL composition. Typically you wouldn’t have to provide this property.




Name of the theme that should be used when rendering the application HTML. The theme determines the colors, fonts and appearance of images for the application. The predefined themes are AjaxSwing, Windows, Fancy and Blue. You can create your own themes as well as customize the predefined ones.

Example: html.theme=Fancy



Determines if the resize button in the upper right corner of the window caption is visible. Resize button allows users to set the size of the application window to be the same as the size of the browser window.



Determines if the update button in the upper right corner of the window caption is visible. Update button allows users to submit current values on the page to the server.



Determines how disabled controls are rendered in HTML. If set to true, AjaxSwing will render all controls (enabled or disabled) as enabled. This helps to work around the problem when certain controls are enabled as the user starts typing text in a text field in response to GUI events.



If set to true instructs AjaxSwing to ignore explicitly specifying background colors for components, that have a background color different from default Look and Feel background color. By default is not set which means AjaxSwing will render background colors



Determines how responsive HTML page is to the user input, and how events are emulated for the Swing/AWT components. If set to true, AjaxSwing will automatically submit the HTML page if the user makes changes to the controls that have listeners in the application code. For example, if you have added an itemListener to a checkbox, the value of true will submit the page and emulate the action whenever the user changes the value of this checkbox. Value of false will not trigger any action on user selection changes. This property is global to all events, supported by AjaxSwing.

html.inflate.width, html.inflate.height

integer (percent of original size)

Allows fine-tuning of the size of rendered windows and it's elements. The default sizes are taken from the application, running in emulation mode on the server platform. All component and font sizes are specified in pixels and sometimes in the client browser the elements may appear too small or clipped. To work around this problem inflation property can be used. If inflation of XX is specified AjaxSwing to increase or decrease rendered sizes by XX percent of the original size. Positive values increase sizes, negative values decrease sizes.

Example: html.inflate.width=10



Allows specifying the default width in characters of text fields and text areas. In HTML the width of a text field or text area is determined by the number of visible columns. AjaxSwing first looks if the number of columns is specified in the component itself and uses this value if it is non-0. Otherwise it used the default value as specified by this property.



Allows specifying the default height in lines of TextAreas and JTextAreas. In HTML the height of a text area is determined by the number of specified rows. AjaxSwing first looks if the number of rows is specified in the component itself and uses this value if it is non-0. Otherwise it used the default value as specified by this property.



Allows specifying the minimum height in lines for Lists and JLists. In HTML the height of a list (listbox) is determined by the number of specified rows. AjaxSwing first looks if the number of rows is specified in the component itself and uses this value if it is non-0. Otherwise it used the default value as specified by this property.



Applicable to Netscape browser only. In Netscape the tab pane is rendered as a table. If there is a significant number of tabs, they may not fit well in a single line. This property tells AjaxSwing when to start wrapping tab headers onto the next line. In Internet Explorer the wrapping occurs automatically.

Rendering and Window customization properties



Can be used to override the enabled/disabled state of a component in the window. This is a useful workaround for windows where buttons are enabled/disabled based on the entry in other fields. Since the validation and therefore enabling/disabling is performed in the server, not in the browser, the buttons will stay disabled even after the field that controls the buttons is valid. The names of window and component are described in Multithreading with AjaxSwing.

Example: window.Login_to_server.OK.enabled=true


Passing Dynamic Parameters To An Applet

Sometimes the HTML page containing an applet is generated dynamically by a servlet or some other form of a CGI script in order to pass dynamic parameters to an applet. For exampe, the user may login to a site only once and his name and password would be passed to the applet via "user" and "password" parameters of the APPLET tag in the generated HTML page. Since the application properties file allows you to specify only static parameters that do not change, AjaxSwing router servlet is coded to accept dynamic parameters in its query string. These parameters can be accessed by the applet using reguler getParameter() method. In the example above, in order to pass the user name of "guest" with the password "anonymous" the following initialization URL can be used when forwarding the browser to AjaxSwing application