SmartClient開發環境搭建

This overview serves as a how-to for installing SmartClient into your web application. Evaluators are urged to use the SmartClient 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 materials is recommended to get an overview.

SmartClient 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 SmartClient, 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 SmartClient with a Java back-end, see below for the list of J2SE application servers supported by the Java implementation of the SmartClient server.

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

Client integration

To install the client-side portion of SmartClient, simply copy the isomorphic directory from the smartclientRuntime webroot to the webroot of your application. Having done this you can use SmartClient 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 Client-Server Integration section for more information.

Server integration

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

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

 

• Copy all files from the WEB-INF/lib directory of the smartclientRuntime to your WEB-INF/lib. SmartClient leverages a number of third-party libraries - if there are conflicts with the versions you want to use, use the versions you want - SmartClient has minimal dependencies on these libraries. Contact Isomorphic with any specific questions about compatibility. See the "Java Module Dependencies" section below for a dependency tree that will help you select a minimal set of JARs to deploy.
• Copy the WEB-INF/classes/log4j.isc.config.xml from the smartclientRuntime to your WEB-INF/classes directory. This file contains the SmartClient server log configuration.
• Copy the WEB-INF/classes/server.properties from the smartclientRuntime to your WEB-INF/classes directory. This file contains settings for basic file locations such the location of webroot, the SmartClient SQL engine and DMI. The version under smartclientRuntime has a basic, secure configuration. See the version of server.properties under the smartclientSDK directory for sample SQL and other settings.
• Copy the WEB-INF/iscTaglib.xml from the smartclientRuntime to your WEB-INF directory. This file enables the use of custom SmartClient tags in your JSPs.
• Merge portions of the WEB-INF/web.xml into your application's web.xml. To use SmartClient JSP tags like <loadISC>, you'll need to merge the <jsp-config> section from web.xml. Also there are some mandatory and optional servlets and filters to merge - see below.
• Power and Enterprise Editions only. Copy the shared/ds/batchUpload.ds.xml file to the same location in your target webapp directory. This file is a utility DataSource that is used to provide the initial upload functionality of the BatchUploader component - strictly speaking, you only need to perform this step if you intend to use that component.

See Core and Optional SmartClient 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 SmartClient 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 SmartClient in your environment, please post on the SmartClient 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 SmartClient 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 SmartClient 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.

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