Deployment wizard (WAR export)

The build-in localhost server is only supposed for development usage. To run the W4 Toolkit application on your servlet container you will have to deploy it. W4T Eclipse provides a special export wizard to deal with this task.

The wizard creates a web application archive (WAR) which is used for installing the application on the server. This document describes the features and the usage of the wizard and is divided into seven sections:

Wizard Selection

To open the export wizard select File > Export.

Select WAR file (W4 Toolkit) and click next.

Resources Selection

In the first page of the deployment wizard you select the resources you wish to export. There is only the possibility to select content of one project per deployment, since a project created by the W4T Plugin represents one W4 Toolkit web application.

Either you select the whole project (if you in a hurry and do not care about deploying unused resources) or you choose properly resources by checking folders of the tree viewer or items of the list viewer.

Note: this page is not intended for selecting source or class files since they are covered by the next wizard page.

Select the destination of the deployment archive. Ensure that the file extension is '.war'. After setting the options continue by clicking next.

Classes Selection

According to the servlet specification libraries (*.jar files) which are nessecary to run your application have to reside in the '<web-app-root>/WEB-INF/lib' directory ('web-app-root' describes the document root of your application context on the server). Within this page you specify all class/source files which should be exported. The wizard creates a library with all selections and copy it to the above mentioned directory into the WAR.

If you first open the page the source directories of the selected project are expanded in the treeviewer. You may want to uncheck some resources which should not be deployed (suggest that you have some test classes for development). You can do this in the list viewer on the right.

In most cases you will deploy class files and resources for running the application. You may want to export the source files sometimes too, maybe for debugging purposes. Occasionally you want to create a WAR without classes but only a source archive to export it to another IDE or whatever - make your choice and click next.

Application configuration

Within this page the configuration settings of your W4 Toolkit application are specified. The items of each tab are explained in the following sections. Ensure that at least the startupForm entry is set to the WebForm implementation, which should be shown on the first request of a user session.

Initialisation

startUpForm the fully qualified class name of the WebForm that is displayed when the web application starts.
compatibilityMode the working mode for the W4T engine. Can be "Classic" (old W4 Toolkit compatible) or "Standard". Should be left to "Standard" on most W4 Toolkit applications.
errorPage the fully qualified class name of a WebForm that displays Exceptions that broke the control flow within the web application. If user-defined, this must be a subclass of com.w4t.WebForm and must implement the com.w4t.WebErrorForm interface.
messagePage the fully qualified class name of a WebForm that displays messages that were created within the web application. If user-defined, this must be a subclass of com.w4t.WebForm and must implement the com.w4t.MessageForm interface.
workDirectory the path to a writeable directory, used for temporary files.
closingTimeout maximum time till the closing of a WebForm on the client is recognized at server side. Time interval, in ms.
skimmerFrequency time interval between scans for closed WebForm at the server side. This value should not be greater than half of the closingTimeout value. Time interval, in ms.
directMonitoringAccess whether the w4t administration pages are accessible via the admin.html page. (Shoud be 'false' for productive versions.) Can be 'true' or 'false'.
visibleIndent whether the html output of the web appliction is formatted with indents and newlines. (Shoud be 'false' for productive versions, to save network traffic and shorten loading time.) Can be 'true' or 'false'.
compression whether the html output of the web appliction is sent gzipped to browsers that support gzipped network communication. (Should be 'true' for productive versions to save network traffic and shorten loading time.) Can be 'true' or 'false'.
processTime whether the server-side processing time of the html page is displayed (on the bottom of the page). This may be useful for application tuning. (Will be 'false' for productive versions.) Can be 'true' or 'false'.
noscriptSubmitters whether special submitter images are used for browsers that have javascript disabled. Possible values are:
- none
If set to 'None', a standard submitter image is rendered in addition to the labels on link buttons, tree nodes etc.;
- create
If set to 'Create', a special image is created automatically with the appropriate text and colors. Images created only once and buffered on harddisk in the webapplications image directory. Setting this to 'create' requires an available X server on Unixes, however.
- use
If set to 'Use' earlier generated images are used but no new images are generated. If no image is available from disk, a standard submitter image is rendered in addition to the labels on link buttons, tree nodes etc.;
Can be 'None', 'Create' or 'Use'.
jsLibraries whether the js libraries are written to disk and delivered as static files by a webserver or delivered directly by the servlet engine. Should be 'deliverFromDisk' in most cases. Can be 'deliverFromDisk' or 'deliverByServlet'
maxSessionUnboundToForceGC this is a special option for certain environments, where the gc algorithm comes too late to unload classes. If set to a number > 0, this will enforce a gc after the specified number of sessions has been invalidated.
globalClassesList names a file that lists fully qualified names of classes to be loaded in a classloader namespace global for all sessions (relative to the web application's root path).
handleMissingI18NResource W4 Toolkit supports i18n by accepting values like property://someKey@some.package.SomePropertiesFile which are resolved on rendering, so that the specified property is displayed in the HTML output that the user sees. This attribute specifies the behaviour of the resolver when the specifed resource could not be found as expected. (For development, it may be convenient to set this to "Fail", whereas probably in productive environments the most sensible setting would be "Empty" here.)

Possible values are:
- Fail
behaves like a failed assertion, that is a runtime exception is fired.
- Empty
does nothing and renders an empty String into the component's output.
- Explicit
does nothing and renders the property URI literally into the component's output.

Preloader Buffer

usePreloaderBuffer whether the PreloaderBuffer is used. Can be 'true' or 'false'. If set to 'true' the library will preload all classes needed for starting up a new session with its own classloader and buffer it . If a new session is requested, the buffered session content is handed to the new session. This reduces the libraries startup time for a new session. If set to 'false' the session is initialised on demand.
maxSize the maximum amount of preloaded sessions. Note: Be careful with the size, because preloaded sessions consume memory.
minThreshold the minimum amount of preloaded sessions in the cache. If this amount is undercut the cache will be filled up to its maximum.
preloadStartupForm whether an instance of the StartupFormluar (see 'initialisation') is preloaded. Setting this to 'true' will speed up the request answering time of a newly created session.
preloadList whether classes are preloaded from a fixed size list or a dynamically growing list. This list is located in the webapplications working directory on hard disk (w4t_lcf.tmp). The classes to preload are specified with their fully qualified classname seperated by linefeeds.
- fix
the list is not changed during the lifecycle of a W4 Toolkit webapplication.
-dynamic
the list grows dynamically with classes loaded the first time during the lifecycle of a W4 Toolkit application. The list grows over multiple lifecycles.

DataBase Pools

If your W4 Toolkit application requires database access and you have configured the database pools in the database pool preference page you can add these pool configuration to your application configurations.

For each pool added another tabfolder is shown, to adjust the settings if nessecary. Note: these changes do not have any effects to the local pool settings, they only appear in the WAR.

The database driver library of the specified pool is automatically added to the exported library list. The configuration of the libraries to export is done in the next wizard page.

If you are done with this page click next to continue.

Library Export

In the last page of the export wizard you can specify which libraries the wizard should pack into the WAR. If you first open the page the wizard may has added some library automatically to the library list as a proposal.

If you are not satisfied with the proposals you can modify the list with the buttons on the right side of the page. After your library selection is completed you nearly brought home the bacon.

Note: the export of the libraries follows the rules of the servlet specifications, which means that all libraries added in the list viewer will be packed into the '<web-app-root>/WEB-INF/lib' directory of the deployment WAR, regardless where the libraries are located at the local file system.

Note: If your destination server use another version of the xerces library than the version shipped with W4 Toolkit conflicts may arise. But then the server already uses xerces on its classpath and there's no need for including xerces into the WAR.

Run Export

The last step is to create the WAR by pressing the finish button. The wizard may asks for the permissions to overwrite already existing WARs or to create some internal deployment directories for temporary files. After affirming these questions first the JAR with the classes is packed, then the nessecary W4 Toolkit resources are copied to a temporary folder. Afterwards the JAR, the configuration and the libraries are also copied to this folder. Last but not least the packer creates the deployment WAR at the specified location.

After the creation of the WAR the wizard closes automatically and you are ready to install your W4 Toolkit application on your server. For deploying a WAR to the servlet container see the documentation of the your server.

Troubleshooting

If the export fails have a look at the following list:

Copyright (c) 2003 by Innoopract Informationssysteme GmbH. All rights reserved.