Customizing AjaxSwing using application properties and initialization parameters

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.

Configuration Property

parent

Router Servlet properties

router.inProcess
router.preloadApp
router.preloadWaitForApp
router.agentWaitTimeout
router.sessionTimeout
router.updateInterval
router.registryPort
router.registryPortRange
router.characterEncoding
router.clientsPerJVM
router.retireJVMAfterClients
router.requestFilterClass
router.jvmFactoryClass
router.httpRequestDataLevel

Client Agent Properties

agent.appStartClass
agent.appParams
agent.classPath
agent.requestTimeout
agent.allowLFChange
agent.useAjaxSwingFontsConfigFile
agent.runAsApplet
agent.requestFilterClass
agent.usePlatformGraphicsEnvironment
agent.usePlatformFontConfiguration
agent.productionMode
agent.defaultLocale
agent.forceJvmLocale
agent.useBrowserLocale
agent.monitorAsynchronousUpdates.duration
agent.monitorAsynchronousUpdates.interval
agent.monitorAsynchronousUpdates.updateOnRepaint
http.url.locale

Applet specific properties

applet.title
applet.codeBase
applet.documentBase
applet.width
applet.height
applet.param.<name>

HTML generation and display properties

html.docsURL
html.docsRealPath
html.submitURL
html.humanComponentNames
html.exitPageURL
html.errorPageURL
html.initializationPageURL
html.pageTitle

Rendering and Window customization properties

window.*.autoRefresh
window.*.autoSubmit
window.*.session.keepAlive
renderer.<class name>
updater.<class name>

Component properties

component.<class_name>.browseClient
component.<class_name>.isClientSideScrolling
component.<class_name>.emulateKeyType
component.<class_name>.emulateKeyTypeLimited
component.<class_name>.richTextEditor

Passing Dynamic Initialization Parameters

Property Name
Type
Description
Example

parent

text

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, default.properties is used as a parent configuration. Only the name should be given, ".properties" extension will be added automatically

Example: parent=AppBase


 
Router Servlet properties

router.inProcess

boolean

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

router.preloadApp

boolean

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.

Important: you may have to enable security in Tomcat by adding "-security" to AjaxSwing/bin/startServer.bat[.sh] to prevent conflicts between AjaxSwing and Tomcat. In this case you would also have to grant appropriate permission to your application code base by adding entries toAjaxSwing/Tomcat/conf/catalina.policy file.

Example: router.preloadApp=true

router.preloadWaitForApp

boolean

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

router.agentWaitTimeout

integer

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

router.sessionTimeout

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

router.updateInterval

time in seconds

Specifies how often the browser should ping the server to see if it needs to update the page. Swing application deployed on the server can request an update using ClientAgent.getCurrentInstance().setUpdateBrowser(true) method. If router.updateInterval is set to non-zero value and setUpdateBrowser() method is called, then the browser state will be updated to reflect any changes on the server since the last browser interaction (e.g. if new windows were shown or text changed, these changes will be show in the browser).

router.registryPort

integer

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 default.properties

Example: router.registryPort=1100

router.registryPortRange

integer

Defines the number of ports that AjaxSwing will try to create the RMI registry on. The actual port numbers will be between router.registryPort and router.registryPort + router.registryPortRange

Example: router.registryPortRange=10

router.characterEncoding

text

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 default.properties

Example: router.characterEncoding=ISO8859_1

router.clientsPerJVM

integer

For inProcess=false mode, specifies how many concurrent client sessions should be emulated by one JVM. Used to fine tune scalability. The greater is the number of clients handled by one JVM, the less server resources will be consumed by AjaxSwing. However, depending on the complexity of the client code putting too many clients into the same JVM may degrade the response time for each of the clients. Generally a value between 5 and 50 is recommended and the best way to find out what should it be for an application is to run a load test. It also depends on the scalability requirements for the server. If a server needs to handle 500 concurrent users, then setting clientsPerJVM to 50 would mean that there will be 10 JVMs executing on the server. As the number of users increases, AjaxSwing will launch new JVMs to handle the traffic. The JVM is started in the background so that when a client request comes, there is always a JVM ready to handle it.

Example: router.clientsPerJVM=20

router.retireJVMAfterClients

integer

For inProcess=false mode, specifies how many client sessions should be emulated by one JVM before it is shutdown. Shutting down a JVM helps to release any lingering resources and memory that might not have been cleaned up by the client code. It is a good practice and will have virtually no effect on performance as long as the number of emulations is kept reasonably high. For example, if the value is set to 100 this means that after a JVM has processed 100 sessions (whether they were concurrent or sequential) it will be shutdown by AjaxSwing and the new client connections will be redirected to other JVMs. See clientsPerJVM for more information.

Example: router.retireJVMAfterClients=100

router.requestFilterClass

text

Specifies the name of the class that implements RouterRequestFilter interface. If set, AjaxSwing will load the class, create and instance and call the methods of the interface. NOTE: this property can only be specified in default.properties. For more information see Using Request Filters to Customize Behavior and HTML Generation

Example: router.requestFilterClass=com.creamtec.ajaxswing.examples.RouterRequestFilterExample

router.jvmFactoryClass

text

Specifies the name of the class that extends com.creamtec.ajaxswing.core.JVMFactory. JVMFactory is responsible for launching the standalone JVMs and registering them in an internal hash map. If set, AjaxSwing will load the class, create and instance and call the methods of the class. NOTE: this property can only be specified in default.properties. For more information see JVMFactory JavaDoc

Example: router.jvmFactoryClass=com.creamtec.ajaxswing.core.JVMFactory

router.httpRequestDataLevel

none | info | debug

Since HttpServletRequest data is available from ClientAgent's requestData it sets how many data will be copied to serializable HttpServletRequestImpl object when each client will get its own JVM (router.inProcess=false). For performance reason the data level is set to "none" and HTTP request data is not available by default. Set it to info or debug to have AjaxSwing populate the values of the request. For more information see HttpRequestData JavaDoc

Example usage: HttpServletRequest httpRequest = (HttpServletRequest)clientAgent.getRequestData().getHttpRequest()

agent.productionMode

boolean

If set to true, it won't show exception messages and stack trace in user browser, instead showing "Internal error, please contact administrator ..."

agent.productionMode=true


Client Agent Properties (applies to both applications and applets)

agent.appStartClass

text

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

agent.appParams

text

If your application receives command line parameters, put them here just as you would pass them to main(). Applicable only to applications. If you application needs to receive a command line dynamically depending on the user, read Passing Dynamic Initialization Parameters.

Example: agent.appParams=-port 8000 –silent

agent.classPath

text

Specifies a semicolon (";") separated list of .jar and .zip archives (NOT 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. System properties available through System.getProperties() can be used as parameters in the classpath. The syntax is ${property_name}. For instance, if user.home system property is set to c:/users/administrator and agent.classPath is set to ${user.home}/classes then the real path would be expanded to c:/users/administrator/classes

Example: agent.classPath=c:/myApp/myapp.jar;{user.home}/classes

agent.requestTimeout

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

agent.allowLFChange

boolean

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

agent.useAjaxSwingFontsConfigFile

boolean

Allows you to override the default JVM logic loading the fonts. If set to true, AjaxSwing will use its own font.properties file from AjaxSwing/lib directory 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 fonts.properties. This can be helpful for fine-tuning the loading of fonts and to prevent crashes of those occur at application loading. The default value is "true" for Linux and "false" for all other platforms.

Example: agent.useAjaxSwingFontsConfigFile=false

agent.runAsApplet

boolean

Allows you to override the default logic of determining if to run the start class as an application or as an applet. By default when AjaxSwing loads a start class it first checks if it has a public void main(String[]) method. If it does AjaxSwing treats it as an application and executes the method. If there is no main() method, then AjaxSwing checks if the start class is a subclass of java.awt.Applet and if so it loads it as an applet. Setting this parameter to true will change this logic and even if a class that extends an Applet has a main() method, it will still be ran as an applet.

Example: agent.runAsApplet=true


Applet specific properties (applies only to applets)

applet.title

text

Page title for applets. For applications the title of the current window is used. If the value is set to be empty or not specified at all, AjaxSwing will not render the title line with the update, resize and close buttons. The default value is specified in default.properties

Example: applet.title=Welcome to MyApplet

applet.codeBase

text

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

applet.documentBase

text

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

integer

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

applet.param.<name>

text

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 Initialization Parameters.

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

agent.requestFilterClass

text

Specifies the name of the class that implements AgentRequestFilter interface. If set, AjaxSwing will load the class, create and instance and call the methods of the interface. For more information see Using Request Filters to Customize Behavior and HTML Generation

Example: agent.requestFilterClass=com.creamtec.ajaxswing.examples.AgentRequestFilterExample

agent.usePlatformGraphicsEnvironment

boolean

If set to true, AjaxSwing will not replace platform graphics environment with a virtual one. This is useful for running on UNIX platforms that expect a Motif-derived graphics environment (for instance, if you are getting java.lang.ClassCastException on com.creamtec.ajaxswing.gui.AjaxSwingGraphicsEnvironment)

agent.usePlatformFontConfiguration

boolean

If set to true, AjaxSwing will not replace platform font configurtion with a virtual one. This is useful for running on UNIX platforms that expect a Motif-derived graphics environment.

agent.productionMode

boolean

if property is true, WindowUpdater will emulate requestException, instead throwing away, AjaxPageRenderer will not explain exception to the end user.

agent.defaultLocale

text

Defines default agent locale (since AjaxSwing 3.2)

Example: agent.defaultLocale=en_US

agent.forceJvmLocale

boolean

If set to true, AjaxSwing would replace default locale for application JVM to browser detected (or configured in application properties) locale

Example: agent.forceJvmLocale=true

agent.useBrowserLocale

boolean

If agent.useBrowserLocale set to true AjaxSwing will use preferred browser Locale.(since AjaxSwing 3.2)

agent.monitorAsynchronousUpdates.duration

integer

If set to non-0 value, specifies how long should AjaxSwing monitor background updates after each request

Example: agent.monitorAsynchronousUpdates.duration=3

agent.monitorAsynchronousUpdates.interval

integer

Specifies how often the browser should ping the server for updates

Example: agent.monitorAsynchronousUpdates.interval=3

agent.monitorAsynchronousUpdates.updateOnRepaint

boolean

If set to true, causes the browser to update the page whenever RepaintManager detects a dirty component

http.url.locale

string

Defines locale parameter name (since AjaxSwing 3.2)

Example: http.url.locale=Lang

agent.usePlatformFontConfiguration

boolean

If set to true, AjaxSwing will not replace platform font configurtion with a virtual one. This is useful for running on UNIX platforms that expect a Motif-derived graphics environment.


HTML generation and display properties

html.docsURL

text

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

html.docsRealPath

text

AjaxSwing may generates images and other temporary documents that are written to a directory that needs to be accessible to a web browser. AjaxSwing will try to determine the real path (that is path on the local drive) to its documents using Servlet API. However, not all implementations will provide this information so you may see a warning "The path to the AjaxSwing documents within webserver public documents could not be automatically set". In this case you must set the path manually. The path should be the path on disk that corresponds to AjaxSwing documents URL (see html.docsURL). For example, if the WWW root is mapped to /opt/web/public_html directory and AjaxSwing docsURL is http://localhost/ajaxswing then html.docsRealPath should be set to /opt/web/public_html/ajaxswing

Example: html.docsRealPath=/opt/web/public_html/ajaxswing

html.submitURL

text

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.

Example: http://localhost:8040/servlet/com.creamtec.ajaxswing.AjaxSwingRouter/TestApp

html.theme

text

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

html.humanComponentNames

boolean

If set to true, AjaxSwing will generate human-readable component names. By default AjaxSwing uses the class name and the hash code as the name of the component on the generated HTML page. When this parameter is set to true, the name of the component is derived from the component text whenever possible. For instance, instead of using JButton26400260 as the name for 'Login Dialog' button AjaxSwing will use Login_Dialog as the name. This is not recommended for production environments because there is a possibility of duplicate component names.

html.exitPageURL

text

If specified, AjaxSwing will forward the browser to this page when a user ends his session with the application (specifically, when the application calls System.exit() or ends its main thread).

Example: html.exitPageURL=http://www.mycompany.com/ThanksForUsing.html

html.errorPageURL

text

If specified, AjaxSwing will forward the browser to this page when an unhandled exception is thrown by the application or if an internal error occurs. The detailed message is placed into the session as ajaxswing.errorMessage attribute and the URL of the application is placed as ajaxswing.submitURL attribute. See ajaxswing/Windows_docs/error.jsp for an example of error page implementation.

Example: html.errorPageURL=/ajaxswing/Windows_docs/error.jsp

html.initializationPageURL

text

If specified, AjaxSwing will forward the browser to this page during the initialization. If the URL starts with "/" it is considered to be relative, otherwise it is considered to be absolute. See initialization.jsp for a reference on parameters and expected logic. If not specified, AjaxSwing will forward to the default /initialization.jsp page.

Example: html.initializationPageURL=http://www.mycompany.com/initialization

html.pageTitle

text

If specified, the title is used for the generated HTML page instead of the Frame/Dialog title. If not specified, the title for the page is obtained by calling Frame/Dialog getTitle() method for the topmost window. It is highly recommended to set page title for AjaxSwing applications


Rendering and Window customization properties

window.*.autoRefresh

text

Can be used to automatically refresh the page after a specified period of time in seconds. The value of this property is used as the content of "Refresh" HTTP Meta tag. For more information refer to HTTP documentation. Note that automatically refreshing the page does not submit the values entered by the user and will cause any data entry to be overridden by the values from the server. If the values need to be retained, use autoSubmit

Example: window.*.autoRefresh=3
Example:window.*.autoRefresh=5;URL=http://www.acme.com

window.*.autoSubmit

integer

Can be used to automatically submit the page after a specified period of time in seconds.

Example: window.*.autoSubmit=3

window.*.session.keepAlive

boolean

Keeps server session alive by asynchronously pinging the server from the browser as long as the browser window is open

component.<className>.browseClient

boolean

Controls if the JFileChooser of OPEN_DIALOG type will browse the client disk (the machine that is running web browser) or server disk (the machine that is running AjaxSwing). By default, client disk is browsed and the file is uploaded to a server temporary directory. When the client session is closed, the temporary file is removed.

Example: component.javax.swing.JFileChooser.browseClient=false

component.<className>.isClientSideScrolling

boolean

Can be used to specify if viewport should be scrolled on client or on server, in case of server scrolling only visible area is rendered to browser and scrolling submits to server to request additional components.

Example: component.javax.swing.JViewport.isClientSideScrolling=true

component.<className>.emulateKeyType

boolean

AjaxSwing normally generates KeyPressed/KeyTyped/KeyReleased events for the each of symbols in a text field. This property allows to disable such a behaviour.

Example: component.javax.swing.JTextPane.emulateKeyType=false

component.<className>.emulateKeyTypeLimited

boolean

If set to true the AjaxSwing will fire KeyPressed/KeyTyped/KeyReleased for only one character (instead of for the each symbol in this text field)

Example: component.javax.swing.JTextPane.emulateKeyTypeLimited=true

component.<className>.richTextEditor

boolean

If set to true the AjaxSwing will render a JEditorPane using TinyMCE editor

Example: component.javax.swing.JEditorPane.richTextEditor=true

 

Passing Dynamic Initialization Parameters

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. Application command line can also be dynamically generated by a startup script or another application that will invoke it. 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

   http://www.mysite.com:8040/ajaxswing/apps/myapp?user=guest&password=anonymous

For applications, you can pass the command line using a "appParams" parameter to AjaxSwingRouter as shown below

   http://localhost:8040/ajaxswing/apps/myapp?appParams=Test%20Command%20Line
Notice that the space characters are passed as %20 following HTTP protocol requirements. If you are using application preloading, passing dynamic parameters will not work since the main() method is invoked before the request is received by the router servlet.

At any point in time Java application can get HTTP parameters using AjaxSwing API. For example, to get the value of the "user" parameter in the example above the following code can be used:

   String userName = (String) ClientAgent.getCurrentInstance().getRequestData().getParams().get("user");
  
See AgentRequestFilterExample.java for an example.