com.smartgwt.client.docs
Interface IscInstall


public interface IscInstall

This overview serves as a how-to for installing SmartGWT into your web application. Evaluators are urged to use the SmartGWT SDK with the embedded tomcat servlet engine during evaluation rather than pursue installation into an existing web application up front, however, reading this document and the related 'server integration' materials is recommended to get an overview.

SmartGWT has two pieces - the client components that run in the browser and the server components that run in a J2SE compatible container. You don't need to use a Java back-end to use SmartGWT, but the SDK comes with some examples that assume the presence of the Java back-end and, for some examples, a SQL Database. If you will be using SmartGWT with a Java back-end, see below for the list of J2SE application servers supported by the Java implementation of the SmartGWT server.

The SDK contains two top-level directories: smartclientSDK and smartclientRuntime. The smartclientSDK directory contains the membedded servlet engine, embedded database, examples, and documentation. The smartclientRuntime directory contains just the client and server components of the SmartGWT product - use the contents of this directory when deploying SmartGWT into your application environment.

Client integration

To install the client-side portion of SmartGWT, simply copy the isomorphic directory from the smartclientRuntime webroot to the webroot of your application. Having done this you can use SmartGWT components on your pages regardless of the technologies used on your back-end and you can bind to server-side componentry backed by arbitrary technology - see the Data Integration section of the ClientServerIntegration section for more information.

Server integration

SmartGWT can be 'integrated with any backend' without installing the SmartGWT Java server. However, the SmartGWT server accelerates Java integration and provides other useful facilities, including server-push and network performance enhancements. See the 'SmartGWT Server summary' for details.

To integrate the server portion of SmartGWT, you need to follow the steps below for each application (WAR) that uses SmartGWT. Note that, if installing into an environment that uses multiple WARs, installation of SmartGWT JARs into a directory shared by multiple applications is not supported. Installation of a separate WAR with client-side SmartGWT modules for maintaining cache coherence across applications using the same version of ISC is supported - contact Isomorphic support for more details on how to set that up.

Note: Some of the instructions below ask you to copy files into the WEB-INF/classes folder. If you're using an IDE such as Eclipse that attempts to manage the WEB-INF/classes folder, we recommend that you copy these files to the src/ directory of your project (next to the top-level folder for your java namespace) such that your IDE auto-deploys them to the WEB-INF/classes folder. We have seen cases of tools like Eclipse periodically deleting files that are checked into to WEB-INF/classes directly.

Merging web.xml

The following is a description of the servlets and filters you'll find in the web.xml file contained in the smartclientRuntime and what they do:

Core Functionality

Optional Functionality

Note that not all of the servlets and filters listed under Optional Functionality above are present in the web.xml that ships with the smartclientRuntime - if you need to use any of these, copy their configuration from the web.xml available under the WEB-INF directory of smartclientSDK. Other servlets, filters and configuration files from the smartclientSDK should not be copied to your deployment, simply because the SDK includes many developer tools that are not extensively audited from a security standpoint.

Troubleshooting

This section covers some common problems with possible solutions. You may also need to refer to the documentation for your specific application server, web server, or database. If you experience any problems installing and configuring SmartGWT in your environment, please post on the SmartGWT forums for assistance.

Problem Possible Causes Solution
Browser displays a generic "page cannot be displayed" or "unable to locate the server" message. Servlet engine not started. Start your application server.
Missing/incorrect port for servlet engine in URL. Check the startup messages, logs, or documentation for the servlet engine to determine what port it is using.
Host name is incorrect. Check whether other pages on the host can be accessed. Try the base URL http://[host name]:[port number] to see whether the servlet engine or webserver is functioning.
Browser displays a 404 or other page/file not found error. Incorrect URL. Check for errors in the URL, including capitalization.
Server error: taglib not defined Missing iscTaglib.xml or iscTaglib.xml not referenced in web.xml Copy WEB-INF/iscTaglib.xml from smartclientRuntime to your deployment WEB-INF directory and make sure that you have merged the <jsp-config> section from the smartclientRuntime web.xml
ClassNotFound or other Java Exceptions in the server log. Missing JAR files Verify every .jar from the smartclientRuntime WEB-INF/lib directory has been copied to your deployment WEB-INF/lib. Although you might later be able to remove some .jars, for initial installation testing, copy every .jar
"isc" is not defined JS error Incorreect URLs to SmartGWT modules use View Source to look at SCRIPT includes (e.g. for ISC_Core.js), try those URLs directly in the browser to verify the files are correctly deployed

Java Module Dependencies

The following is a description of what functionality is contained in each SmartGWT JAR file, and which other SmartGWT JARs and third party libraries are required to enable that functionality. Note that actual filenames in WEB-INF/lib will typically contain the version number of the library, whereas the library names below simply list the base name.

Caching Considerations

When upgrading from one SmartGWT release to the next you want to make sure that the user picks up the new version on next access, but you also want to keep the ISC modules cacheable so they're not refetched on every access.

SmartGWT deals with this problem by appending a version string as a query parameter to each module load directive. This is done by the <isomorphic:loadISC> and <isomorphic:loadModules> tags automatically. As long as you make sure that the file that contains these tags is non-cacheable, you will get the desired behavior.

Supported J2SE Containers

Below is the list of J2SE containters that have been tested to be compatible with this version of SmartGWT. Installation in these containers is supported for deployment by Isomorphic. If your application server is not on this list, please contact us at the SmartGWT forums to see if we can support your deployment. In general, the Java portion of ISC should work on servlet containers that comply with servlet specification version 2.3 and up and utilize a JVM no older than version 1.4.

Supported J2SE Containers:

Apache Tomcat 4.0.x, 4.1.x, 5.0.x, 5.5x, 6.0.x
Apache Geronimo 1.x, 2.x
BEA WebLogic 6.x, 7x, 8.x, 9.x, 10.x
Caucho Resin 2.1.x, 3.0.x, 3.1.x
IBM WebSphere 5.x, 6.x
IBM WebSphere Community Edition 1.x
JBoss 3.2.x, 4.0.x, 4.2.x
Mortbay Jetty 4.x, 5.x, 6.x
Oracle Containers for J2EE (OC4J) 9.x, 10.x, 11.x
Oracle Application Server 10g 9.x, 10.x
Sun Application Server 8.x, 9.x