com.smartgwt.client.docs
Interface IscInstall


public interface IscInstall

Deploying Smart GWT

This overview serves as a how-to for installing Smart GWT into your web application. Evaluators are urged to use the Smart GWT 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.

Smart GWT 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 Smart GWT, 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 Smart GWT with a Java back-end, see below for the list of J2SE application servers supported by the Java implementation of the Smart GWT 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 Smart GWT product - use the contents of this directory when deploying Smart GWT into your application environment.

Client integration

To install the client-side portion of Smart GWT, simply copy the isomorphic directory from the smartclientRuntime webroot to the webroot of your application. Having done this you can use Smart GWT 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

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

To integrate the server portion of Smart GWT, you need to follow the steps below for each application (WAR) that uses Smart GWT. Note that, if installing into an environment that uses multiple WARs, installation of Smart GWT JARs into a directory shared by multiple applications is not supported. Installation of a separate WAR with client-side Smart GWT 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.

See 'Core and Optional Smart GWT servlets' for details of additional changes you may need to make to your applications web.xml file. See 'Java Module Dependencies' for details of the .JAR files that comprise the Smart GWT Server, and their dependencies on various third-party libraries.

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 Smart GWT in your environment, please post on the Smart GWT 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 Incorrect URLs to Smart GWT 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

Caching Considerations

When upgrading from one Smart GWT 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.

Smart GWT 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 Smart GWT. Installation in these containers is supported for deployment by Isomorphic. If your application server is not on this list, please contact us at the Smart GWT 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