SmartClient™ SDK Server Installation Version 5.2 evaluation (04/10/2005) Java server edition

Overview

SmartClient .zip and .tar.gz packages include an embedded Tomcat server for rapid stand-alone development, but SmartClient is tested and supported on many leading application servers. SmartClient .war and .ear packages without Tomcat are also provided for deployment in existing server environments.

The SmartClient SDK includes an embedded HSQL database for rapid prototyping and evaluation using the SmartClient object-relational connector. This connector is also tested against many leading relational database systems.

To get started immediately with the SmartClient SDK, we recommend using the embedded server and database. These notes describe server-specific configuration to deploy the SmartClient SDK in a different application server and/or to run the examples against a different database.
 

If your specific application server or version is not listed above, please contact support@isomorphic.com for assistance.
 

You will need a JDBC driver for your specific database. The MM.MySQL driver for MySQL and the JDBC driver for PostgresSQL are included in the evaluation SDK for your convenience. Licensing restrictions prevent us from including DB2, SQL Server, Oracle, and more recent MySQL JDBC drivers (MySQL Connector/J) with this distribution. However, you can download these drivers for free from the vendors' websites.

If your specific database server or version is not listed above, please contact support@isomorphic.com for assistance.
 

Server-specific installation notes

The instructions below have been fully tested on Windows servers. Installation and use of SmartClient on Unix, Linux, or Solaris server platforms is also supported, but is not specifically documented in these notes. These notes use Windows-format paths (with backslash rather than forward-slash delimiters) for installation files and directories.

Download SmartClient SDK

The latest SDK is available at http://www.isomorphic.com/devcenter/download/index.jsp.

Unzip or unzip/untar the downloaded file if your web browser does not do so automatically. Locate the directory named isomorphicSDK. This is the SmartClient SDK "home directory".

Note: If you are installing on an IBM WebSphere application server, download isomorphicSDK.war instead of the .zip or .tar.gz files.

Tomcat 4.x, Tomcat 5.x

1. Shut down Tomcat.
    
2. Move or copy the isomorphicSDK directory into <Tomcat home>\webapps.
    
3. Start Tomcat.
    
4. Open a web browser and go to http://<your server>:<your port (default 8080)>/isomorphicSDK.

Resin 2.x, 3.x

• Same procedure as Tomcat, but replace <Tomcat home> with <Resin home>.

BEA WebLogic (all versions)

The WebLogic server must be running in developer mode for the SmartClient SDK administrative tools to function. These tools edit configuration files inside the isomorphicSDK directory. Developer mode is not required for production deployment of SmartClient-enabled applications.

To enable developer mode, edit the startup script for your WebLogic server, set the STARTMODE variable to FALSE, and restart the WebLogic server. Note that developer mode is the default for the examples and the default 'mydomain' domain in Weblogic 7.0 and 8.1. For more information on the developer mode, see the README file in the applications directory of your Weblogic server.

BEA WebLogic 6.1

1. Shut down WebLogic.
    
2. Enable developer mode (see above).
    
3. Move or copy the isomorphicSDK directory into <beaRoot>\wlserver6.1\config\<domain (default is mydomain)>\applications.
    
4. Start WebLogic.
    
5. Open a new browser and go to http://<your server>:<your port (default 7001)>/isomorphicSDK.

BEA WebLogic 7.0 (direct deployment, recommended)

1. Shut down WebLogic.
    
2. Enable developer mode (see above).
    
3. Move or copy the isomorphicSDK directory into <beaRoot>\user_projects\<domain (default is mydomain)>\applications.
    
4. Start WebLogic.
    
5. Open a new browser and go to http://<your server>:<your port (default 7001)>/isomorphicSDK.

BEA WebLogic 7.0 (deployment via web interface)

1. Start WebLogic.
    
2. Enable developer mode (see above).
    
3. Open WebLogic console at http://<your server>:<your port (default 7001)>/console.
    
4. In the tree on the left, navigate to <your domain>->Deployments->Web Applications.
    
5. Select 'Configure a new Web Application'.
    
6. Use the navigation at the bottom of the page to navigate to the directory containing your isomorphicSDK directory.
    
7. Click the [select] link next to the isomorphicSDK directory.
    
8. Move the relevant 'Available Servers' into the 'Target Servers' box.
    
9. Click 'Configure and Deploy'.
    
10. Open a new browser and go to http://<your server>:<your port (default 7001)>/isomorphicSDK.

BEA WebLogic 8.1

Same as WebLogic 7.0, except:

• In step 4, 'Web Applications' are called 'Web Application Modules'.
   
• In step 5, 'Configure a new Web Application' is instead 'Deploy a new Web Application Module'.
   
• In step 7, instead of clicking [select], click the radio button next to the file and then click 'Target Module' at the bottom right of the page.

IBM WebSphere 5.0

1. Start WebSphere.
    
2. In the tree on the left, navigate to Applications->Install New Application.
    
3. Make sure isomorphicSDK.war resides on the system from which you're running the administrative console. Enter the Local path to isomorphicSDK.war only (you can use the Browse button to locate the file interactively).
    
4. In the 'Context Root' dialog enter: isomorphicSDK.
    
5. Click Next.
    
6. Unless you want to change the defaults on the screens that follow, you can simply click 'Next' through all the screens and 'Finish' on the final screen. Note: Isomorphic recommends that you set the 'Classloader Mode' to 'PARENT_LAST'. This can be configured on one of the installation screens or later by selecting the already-deployed application and changing its configuration.
    
7. After clicking 'Finish' you will get the 'Installing...' screen. Click the 'Save to master Configuration' link on this screen and click 'Save' on the screen that follows.
    
8. In the tree to the left, navigate to Applications->Enterprise Applications.
    
9. You should see an application named isomorphicSDK_war in the list on the right.
    
10. Select the checkbox next to this application and click the 'Start' button above.
     
11. Open a new browser and go to http://<your server>:<your port (default 9090)>/isomorphicSDK.

Oracle 10g (9.0.4)

1. Edit <oc4j9.0.4 home>\j2ee\home\config\application.xml: make a copy of the web-module definition with id "dms" - in the new entry change the id to "isomorphicSDK" and change dms.war in the path attribute to isomorphicSDK.war.
   
   Also, add a library path directive that points to the tools.jar of your JDK (this enables in-process jsp compilation - SmartClient has only been tested in this mode). The new entry should read e.g.:
   
   <library path="C:\Program Files\Java\jdk1.5.0\lib\tools.jar"/>
    
2. Edit <oc4j9.0.4 home>\j2ee\home\config\http-web-site.xml: copy the web-app entry with name "dms" - in the new entry change the name to "isomorphicSDK" and the root attribute to "/isomorphicSDK".
    
3. Edit <oc4j9.0.4 home>\j2ee\home\config\global-web-application.xml: in the orion-web-app tag, add: jsp-cache-tlds="false". This disables tld caching and is currently necessary for SmartClient jsps to work correctly under this servlet engine.
    
4. Move or copy the isomorphicSDK.war into <oc4j9.0.4 home>\j2ee\home\applications
    
5. Start OC4J 9.0.4
    
6. Open a new browser and go to http://<your server>:<your port (default 8888)>/isomorphicSDK.

Sun AS 8.0

1. Start Sun AS 8.0.
    
2. Move or copy the isomorphicSDK.war into the Sun AS 8.0 autodeploy directory. If you used defaults during the AS 8.0 install this should be C:\Sun\AppServer8.0\domains\domain1\autodeploy
    
3. Open a new browser and go to http://<your server>:<your port (default 8080)>/isomorphicSDK.
    

Custom database configuration

The SmartClient object-relational connector supports rapid end-to-end application prototyping and SDK evaluation. To configure this connector for use against a database other than the embedded HSQLDB instance:

1. Install JDBC driver

To install a JDBC driver, copy the downloaded .jar file, or unzip the downloaded .zip file, into your isomorphicSDK\WEB-INF\classes directory.

2. Create 'isomorphic' database

By default, the example applications provided in the SmartClient SDK look for their data in a database named isomorphic. You must create this database and import the sample data in order to use the example applications. Follow your database vendor's instructions for creating new databases and tablespaces.

Alternatively, you may edit the parameters in isomorphicSDK\WEB-INF\classes\server.properties to use an existing database. If you choose to do this, you must edit and save server.properties and restart your servlet container before attempting to import the sample data.

3. Configure SmartClient object-relational connector

The instructions in this section explain how to manually edit your configuration settings. Alternatively, you may use the graphical SmartClient Admin Console to edit these settings. If you are viewing this page from your application server, click here to open the Admin Console. Otherwise, open the console from: http://<your server>:<your port>/isomorphicSDK/tools/adminConsole.jsp.

To manually edit your configuration, open isomorphicSDK\WEB-INF\classes\server.properties in a text editor. This file contains configuration blocks for HSQLDB, MySQL, Oracle, PostgreSQL, and DB2. The sql.defaultDatabase variable controls which block is actually used by the system. To use a database other than the embedded HSQLDB, comment out the line that reads sql.defaultDatabase: HSQLDB and uncomment the line that reads sql.defaultDatabase: <your database type>.

After you have selected the database type, ensure that other configuration parameters in this file are set appropriately for your system. For a custom installation, you may need to change the values of the following variables:

Refer to the comments in server.properties for more information.

Note: You must restart your servlet engine whenever changes have been made to server.properties.

4. Import SDK sample data

To import the sample data:

1. Open the SmartClient Admin Console.

2. Click Import DataSources in the options tree at top left.

3. Click/shift-click or right-click to select all datasources in the list at top right.

4. Click on the Import button.

Importing all sample data may take more than 10 seconds. A dialog will appear when the import operation has completed.

If you get an out of memory error when importing a very large data set (e.g. the productRevenue sample data), you will need to increase the maximum heap size of your JVM (e.g. java.exe -Xmx128M).

5. Test an example application

Launch SmartClient Demo Application to test your complete SDK installation.
 

Troubleshooting

This section covers some common problems with possible solutions. You may also need to refer to the documentation for your specific application server or database. If you experience any problems installing and configuring SmartClient in your environment, please contact support@isomorphic.com for assistance.