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 WebCream/bin/startServer.bat[.sh] to prevent conflicts between WebCream and Tomcat. In this case you would also have to grant appropriate permission to your application code base by adding entries toWebCream/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. WebCream does not rely on web server session timeout because it needs fine control over the session tracking and resource cleanup. Therefore if WebCream is deployed with an external servlet container the session timeout for the WebCreamRouter servlet should be greater then the sessionTimeout specified in the application properties file. The default value is 300 seconds

Example: router.sessionTimeout=600

router.registryPort

integer

Used to tell WebCream the port on which the RMI registry is or should be running. WebCream uses RMI registry to communicate with client agents that run in stand alone mode. If the registry is already running on the given port, WebCream 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 WebCream 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 WebCream servlet will use when creating HTML pages. By default WebCream 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 WebCream. 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, WebCream 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 WebCream 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, WebCream 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=creamtec.webcream.examples.RouterRequestFilterExample

router.jvmFactoryClass

text

Specifies the name of the class that extends creamtec.webcream.core.JVMFactory. JVMFactory is responsible for launching the standalone JVMs and registering them in an internal hash map. If set, WebCream 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=creamtec.webcream.core.JVMFactory

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=creamtec.webcream.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 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.

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

agent.appStartWindow

text

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, WebCream 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

agent.requestTimeout

time in seconds

Specifies the maximum time WebCream should wait for an operation to complete. Most useful when debugging and fine tuning an application with WebCream, 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 WebCream will allow applications to change the look and feel using UIManager. It is not recommended to allow the change because it may prevent WebCream from working correctly. This property should be used for testing purposes only

Example: agent.allowLFChange=false

agent.useWebCreamFontsConfigFile

boolean

Allows you to override the default JVM logic loading the fonts. If set to true, WebCream will use its own font.properties file from WebCream/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.useWebCreamFontsConfigFile=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 WebCream loads a start class it first checks if it has a public void main(String[]) method. If it does WebCream treats it as an application and executes the method. If there is no main() method, then WebCream 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, WebCream 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

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.

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.

agent.requestFilterClass

text

Specifies the name of the class that implements AgentRequestFilter interface. If set, WebCream 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=creamtec.webcream.examples.AgentRequestFilterExample

agent.ignoreUnsupportedActions

boolean

If set to true, WebCream will not report an error when unsupported action is detected. This is useful to suppress errors in applications that use dynamic events.

Example: agent.ignoreUnsupportedActions=true

HTML generation and display properties

html.docsURL

text

Can be used to override the default URL determined by WebCream router servlet. This URL where WebCream will look for application images, WebCream 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 WebCream will look for logo.gif using URL http://localhost/myapp/images/logo.gif.

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

html.docsRealPath

text

WebCream may generates images and other temporary documents that are written to a directory that needs to be accessible to a web browser. WebCream 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 WebCream 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 WebCream documents URL (see html.docsURL). For example, if the WWW root is mapped to /opt/web/public_html directory and WebCream docsURL is http://localhost/webcream then html.docsRealPath should be set to /opt/web/public_html/webcream

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

html.submitURL

text

Can be used to override the default URL determined by WebCream router servlet. URL through which WebCreamRouter servlet can be accessed. By default the WebCreamRouter 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.

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 WebCream, Windows, Fancy and Blue. You can create your own themes as well as customize the predefined ones.

html.ignoreDisabledState

boolean

Determines how disabled controls are rendered in HTML. If set to true, WebCream 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.

html.ignoreBackgroundColors

boolean

If set to true instructs WebCream 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 WebCream will render background colors

html.dynamicEventsEnabled

boolean

Determines how responsive HTML page is to the user input, and how events are emulated for the Swing/AWT components. If set to true, WebCream 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 WebCream.

html.snapshotRenderer.enable

boolean

If set to true instructs WebCream to use SnapshotRenderer for unsupported and unknown components.

html.humanComponentNames

boolean

If set to true, WebCream will generate human-readable component names. By default WebCream 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 WebCream will use Login_Dialog as the name. This is not recommended for production environments because there is a possibility of duplicate component names.

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 WebCream 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

html.defaultTextComponentColumns

integer

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. WebCream 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.

html.defaultTextComponentRows

integer

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. WebCream 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.

html.minListVisibleRowCount

integer

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. WebCream 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.

html.maxTabsPerRow

integer

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 WebCream when to start wrapping tab headers onto the next line. In Internet Explorer the wrapping occurs automatically.

html.exitPageURL

text

If specified, WebCream 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, WebCream 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 webcream.errorMessage attribute and the URL of the application is placed as webcream.submitURL attribute. See webcream/Windows_docs/error.jsp for an example of error page implementation.

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

Rendering and Window customization properties

window.<window_reference>.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.Login_to_server.autoRefresh=3
Example:window.Login_to_server.autoRefresh=5;URL=http://www.acme.com

window.<window_reference>.autoSubmit

integer

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

Example: window.Login_to_server.autoSubmit=3

window.<window_reference>.keepAlive

boolean

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

window.<window_reference>.notifyBeforeExpiration

boolean

If set to true displays a notification in the browser allowing the user to prevent the session from expiring

window.<window_reference>.notifyBeforeExpirationMessage

text

Message to display in the confirmation dialog before the client session expires

window.<window_reference>.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 WebCream). 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: window.*.browseClient=false

window.<window_reference>.<component_reference>.enabled

boolean

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 Referring to windows and components in WebCream.

Example: window.Login_to_server.button.OK.enabled=true

window.<window_reference>.<component_reference>.action

text

Can be used to override the default action processing when a component sends a command. For example, you can open a new browser window with a given URL when a button is pressed. For details refer to Overriding Actions and Multithreading.

Example: window.Login_to_server.button.OK.action=http://www.acme.com

window.<window_reference>.<component_reference>.listeners

boolean

Can be used to override the default determination of whether the control has listeners. WebCream checks to see if a control has listeners, and if it does, WebCream adds onChange JavaScript event listener that will submit the page to the server thus invoking the listener. For some components such as JTable WebCream may not be able to determine whether there are selection listeners, so an explicit override can be required (WebCream can only discover listeners if the table uses DefaultListSelectionModel). This parameter is currently only supported for tables

Example: window.Login_to_server.component.ItemsTable.listeners=true

window.<window_reference>[.<component_reference>].dynamicEventsEnabled

boolean

Can be used to override the default determination of whether the control should generate dynamic events. WebCream checks to see if a control has listeners, and if it does, WebCream adds onChange or onClick JavaScript event listener that will submit the page to the server and then invoke the listener. This parameter overrides application wide html.dynamicEventsEnabled.

Example: window.Login_to_server.dynamicEventsEnabled=false window.Login_to_server.button.OK.dynamicEventsEnabled=true window.Login_to_server.button.Cancel.dynamicEventsEnabled=true

window.<window_reference>[.<menu_component_reference>].include

string

Used to specify custom HTML content to be included into the menu bar after the menu items

Example: window.*.component.JMenuBar.include=<a href="#" onclick="doSubmit('close')">Exit</a>

emulate.<window_reference>

Class Name

Registers a class that will be called by WebCream to emulate the action for the application. When a WebCream supported event such as button click, menu click or state change occurs in the browser, the HTML form is submitted to the server. In the first step of processing, WebCream updates all controls with data. After the update is done, WebCream calls ActionEmulators to emulate the action for the GUI application running in the web server. For example, WebCream default implementation emulates button click in a GUI app if that button was used to submit the form. Custom emulators can be used to supplement or override the default action processing. See ActionEmulator interface for more details.

Example: emulate.*=creamtec.webcream.examples.CustomControlProcessor

Messages displayed to the user

message.browser_state_resynchronized

text

Specifies the message that WebCream will display when the browser was out of synch with the application. This can happen if users use Back, Next or Refresh buttons.

message.old_browser

text

Specifies the message that WebCream will display to users whose's browser version is too old

message.session_expired

text

Specifies the message that WebCream will display to users when their session has expired

message.session_closed.title

text

Specifies the title of the page displayed when a user exits the application

message.session_closed.text

text

Specifies the body text of the page displayed when a user exits the application

message.session_closed.button

text

Specifies the button label on the page displayed when a user exits the application