This chapter describes how to put your SilverStream application into production by deploying the server and client objects you've developed. You'll learn about the deployment tasks needed to:
While building and testing an application, you typically work on a development version of your application's SilverStream database. When the application is complete, you need to copy the appropriate objects from that development database to a production version of it. This process is called publishing.
SilverStream provides a couple of ways to publish. You can use:
For details, see the Main Designer chapter in the online Tools Guide.
For details, see the SilverCmd reference chapter in the online Tools Guide.
Either way you publish, you can:
Publishing lets you copy forms, views, business objects, pages, and media. If the destination database has objects with the same name and type as those being copied, publishing overwrites those objects. For example, publishing a page named pgOrder overwrites the existing pgOrder page in the destination database.
For first-time publishing, you should publish all referenced objects. For example, if one of your forms references an image, make sure you publish that image too. For subsequent modifications, you can simply publish new or changed objects.
When you ask to publish tables, SilverStream modifies the schema of the destination database to incorporate all of the tables from the source database (you can't select individual tables to publish). It tries to synchronize the destination database with the source database by:
Publishing tables does not copy table data or elements that the SilverStream Designer can't build. For example, it doesn't copy indexes or stored procedures from the source database to the destination database. Also, you must manage any database inconsistencies (such as data type and auto-increment support) across database platforms.
The synchronization process doesn't affect existing components of the destination database. For example, if the destination database contains tables unknown to the source database, the unknown tables are retained. This also applies to columns.
If you get an error while publishing tables, the destination database might be left in a state that is not fully in synch with the source database. That's because SQL DDL actions are not atomic. The publishing process issues all DDL changes and caches any errors until all DDL actions are attempted.
The SilverStream Management Console (SMC) provides a schema synchronization facility that you can use in this situation to clean up certain aspects of the destination database. (Note however that this facility does not roll back any tables already created by a failed publishing process.)
For details on synchronizing database schema with the SMC, see the chapter on database configuration in the Administrator's Guide.
This section provides information about specific issues you may encounter when publishing.
Publishing across server versions
You can publish only among SilverStream servers of the same major version. For example, you can publish from a Version 3.x server to another Version 3.x server, but not to a Version 2.x server.
Setting security for the published database
Publishing does not copy permissions set in the development or test environments to the production environment. You need to set these permissions after publishing is complete.
For details, see the chapter on setting security in the Administrator's Guide.
Defining users and groups for the published database
Publishing does not copy users and groups from the development or test environments to the production environment. You need to define any appropriate users and groups yourself.
For details, see the chapter on setting up users and groups in the Administrator's Guide.
Maintaining valid references across SilverMaster databases
If your application references objects (such as images) from your local SilverMaster database, make sure the production SilverMaster has the same name. Otherwise, those references won't be valid once you publish to the production environment and you'll need to change them manually.
For example, if your development environment has a SilverMaster database named MySilverMaster, then the production environment should also have one named MySilverMaster.
Maintaining valid references across other databases
If your application references objects (such as subpages, subforms, or views) from another database in your development environment, make sure that database is also present in your production environment. Otherwise, those references won't be valid once you publish to production.
For example, suppose frmCust (a parent form) from database Mydb1 references frmOrder (a subform) from database Mydb2. If you publish frmCust to a database on your production server, Mydb2 will also have to be available on that server to enable the parent form to access the frmOrder subform.
In some cases, you might choose to avoid this database reference issue by publishing the child object to the parent's database and adjusting your application accordingly.
Publishing across database types
If you choose to publish across different database platforms (such as Adaptive Server Anywhere to Oracle), you may need to handle certain database incompatibilities yourself. For instance:
You might also encounter problems resulting from different column lengths, different column naming conventions, or incompatible data types. In these cases, publishing does not alter the table and generates an error when you try to.
Problems can occur when you publish from a database that uses mixed-case identifiers to a database that supports only uppercase or only lowercase. Some identifiers may change case, making them inaccessible from your application.
To avoid this, edit the platforms.dbl file (a SilverStream file for database platform configuration settings) and set the QuoteIdentifiers option to true for the destination database. Once you restart the server, that setting will double-quote all identifiers and preserve their case. (platforms.dbl is located in the Resources directory of your installed SilverStream files.)
platforms.dbl file is set to true for SQL Anywhere and Adaptive Server Anywhere databases. This enables users to create tables whose identifiers are reserved words (such as date) or contain special characters, because the double quotes prevent syntax errors on parsing. Such identifiers can cause problems when you publish to databases that don't have QuoteIdentifiers set to true. Some databases (such as Sybase SQL Server and Microsoft SQL Server) require special options to parse double quotes correctly. These options will be turned on automatically if you set the QuoteIdentifiers option in platforms.dbl to true before starting the server and publishing to it.
If you've developed or acquired Enterprise JavaBeans (EJBs) for use in your applications, you'll need to deploy them into your production server environment. This involves:
For details, see
Publishing to a production database.
For details, see
Deploying EJBs.
If you access SilverStream Enterprise Data Connectors (EDCs) in your applications, you'll need to deploy them into your production server environment. The deployment steps to perform depend on the kind of EDC you're using:
See the Lotus Notes Data Connector chapter in the online Tools Guide.
See the PeopleSoft Data Connector chapter in the online Tools Guide.
See the SAP Data Connector chapter in the online Tools Guide.
If your production environment includes SilverStream forms that you want to run in the context of a Java application (instead of in a browser), the client machines using those forms will need to install and use SilverJRunner. SilverJRunner is a low-administration Java client that hosts your forms with support for the full set of form features, as well as encryption and application file caching.
The following sections describe how to set up SilverJRunner clients, including:
SilverJRunner is self-updating, so you just need to install it once per client machine. To minimize administration effort, the SilverStream Server provides an installer that clients can download to set up the current version of SilverJRunner. It also provides a SilverJRunner install page that users can browse to for easy selection of the appropriate installer flavor (Windows, UNIX, or Linux).
By default, the SilverJRunner install page is available from your SilverStream server at the following URL:
http://servername/SilverStream/Pages/SilverJRunner.html
You can instruct users to type this URL directly in their browsers, or you can supply a page that links to it for easier access.
Using the install page
Once displayed, the SilverJRunner install page provides links that users can click to download:
This page also includes instructions for using the installers and for starting SilverJRunner once installed.
Customizing the install page
By default, the SilverJRunner install page is named SilverJRunner.html and stored in the SilverMaster database under Pages. You're free to customize this page as necessary to suit the requirements of your environment and user audience.
If you need to restrict access to the SilverJRunner installers, you can secure this page or even delete it from the server.
Providing direct access to the installers
You may want to let users download a SilverJRunner installer directly, without going to the SilverJRunner install page first. In that case, you can instruct them to type one of the following URLs, or you can link to it from your own pages. These URLs all begin with:
http://servername/SilverStream/silverJRunnerInstall/
Once you download the Windows version of the SilverJRunner installer, you'll have the following file on your local machine:
SilverJRunnerInstall.exe
Run this file to install SilverJRunner and the supporting components it requires.
What gets installed
When the installer is done, you'll have a directory for SilverJRunner on your local machine that contains:
SilverJRunner.exe)
SilverJRunner should now be ready to use on this machine.
Once you download a UNIX or Linux version of the SilverJRunner installer, you'll have the following file on your local machine: SilverJRunnerInstallPlatform.sh. Run this file to install SilverJRunner and the supporting components it requires.
What gets installed
When the installer is done, you'll have a directory for SilverJRunner on your local machine that contains:
SilverJRunner)
SilverJRunner should now be ready to use on this machine.
For detailed information about UNIX or Linux platform support, see the SilverStream Release Notes.
Another way to install SilverJRunner is to use the SilverStream installation (Setup) program from your SilverStream product CD. It provides choices to install SilverJRunner (and supporting files) alone or along with other SilverStream components.
Installing SilverJRunner this way is primarily for developers. The result is the same as accessing the SilverJRunner install page (SilverJRunner.html) from the SilverStream Server to do the installation.
For more information on using the SilverStream installation program, see these chapters in the Installation Guide:
You can start SilverJRunner in several different ways, depending on the platform you're using (Windows, UNIX, or Linux).
In Windows, you can start SilverJRunner by doing either of the following:
Using the SilverJRunner executable
You can start SilverJRunner from the command prompt by invoking the executable program SilverJRunner.exe. Type:
installdirectory\bin\SilverJRunner [options] [protocol://]hostname[:port] databasename formname [appargs]
c:\SilverJRunner\bin\SilverJRunner -ss_username=sam -ss_password=icecream http://corporate:8080 sales frmMonthlyQuota myarg -myswitch -y 2001
If you don't want to type this command every time, you can create a batch (BAT) file to issue it.
Using SJR files
Another alternative to starting SilverJRunner from the command prompt is to use SJR files. SJRs are SilverJRunner application files in which you store all the arguments you'd otherwise type. Opening an SJR file automatically invokes the SilverJRunner executable SilverJRunner.exe and uses those arguments. (The association between the SJR file extension and SilverJRunner.exe is automatically set up in Windows when you install SilverJRunner.)
[options] [protocol://]hostname[:port] databasename formname [appargs]
For example:
-ss_username=sam -ss_password=icecream http://corporate:8080 sales frmMonthlyQuota myarg -myswitch -y 2001
quota.sjr
Once you have an SJR file, you can:
<a href="quota.sjr">Monthly Quota Form</a>
In UNIX or Linux, you can start SilverJRunner by doing either of the following:
Using the SilverJRunner script
You can start SilverJRunner from the command prompt by invoking the executable script SilverJRunner. Type:
installdirectory/bin/SilverJRunner [options] [protocol://]hostname[:port] databasename formname [appargs]
/export/home/sam/SilverJRunner/bin/SilverJRunner -ss_username=sam -ss_password=icecream http://corporate:8888 sales frmMonthlyQuota myarg -myswitch -y 2001
If you prefer to work in the desktop environment, you can start the SilverJRunner script from your file manager or you can set up an icon to issue the entire command.
Executing the JRunner class yourself
When you invoke the SilverJRunner script, it sets some environment variables and executes the class com.sssw.jrunner.JRunner (from the SilverJRunner.zip file in your SilverJRunner lib directory). An alternative way to start SilverJRunner is to execute this class yourself, either from the command prompt or in your own script.
The recommended approach for doing this is to copy the statements from the SilverJRunner script and then modify them to fit your situation:
To create an SJR file:
#!/usr/bin/sh
#
# this script is generated by the SilverStream installation
#
SILVERSTREAMROOT="/export/home/sam/SilverJRunner"
JRE_HOME=$SILVERSTREAMROOT/jre ; export JRE_HOME
JBROKER_HOME=$SILVERSTREAMROOT/jbroker ; export JBROKER_HOME
PATH="$JRE_HOME/bin:$PATH"
$SILVERSTREAMROOT/jre/bin/java \
-cp "$SILVERSTREAMROOT/lib/SilverJRunner.zip:$SILVERSTREAMROOT/lib/ejb.jar:$SILVERSTREAMROOT/lib/javax_trans.zip" \
com.sssw.jrunner.JRunner \
-ss_root="$SILVERSTREAMROOT" \
-ss_noconsole \
"$@"
SilverJRunner.zip file to the user's classpath. Make sure it's the only one of the SilverStream Silver*.zip files on the classpath.
JRunner class from the command prompt, be sure to type those arguments directly.
Normally, SilverJRunner displays windows only for the forms (and views) that make up your application. But when necessary, you can force it to display a Java console window as well. The console enables you to see the System.out and System.err output from your application, which can be particularly useful if you need to debug a problem on the client.
Include the option -ss_showconsole when starting SilverJRunner if you want to display the console window.
For details, see
Using startup options below.
Coding forms to display the console
When developing a form in the SilverStream Form Designer, you can use the showConsole() method of the agGeneral instance variable (com.sssw.rt.form.PvHelperGeneral class) to display the Java console programmatically. In that case, you won't need the -ss_showconsole option when starting SilverJRunner.
Using the console version of SilverJRunner
The SilverStream development environment on Windows NT provides another way to display standard output and error messages from SilverJRunner. SilverJRunner_c.exe (in the SilverStream35\bin directory) is a console version of SilverJRunner that you can invoke instead of the usual end-user executable (SilverJRunner.exe). You can start it from the command prompt by typing:
silverstream35directory\bin\SilverJRunner_c [options] [protocol://]hostname[:port] databasename formname [appargs]
c:\SilverStream35\bin\SilverJRunner_c -ss_username=sam -ss_password=icecream http://corporate:8080 sales frmMonthlyQuota myarg -myswitch -y 2001
Any standard output and error messages from SilverJRunner then display in the command prompt window you're running from. An advantage of this approach is that you can see messages related to startup issues.
There are two kinds of options you can provide when starting SilverJRunner:
The following table describes the - options you can provide when starting SilverJRunner:
Specifies the username to use when logging in to a SilverStream server. For example: -ss_username=sam If you don't supply this option and user authentication is required, the application will display a dialog prompting for username and password. | |
Specifies the password to use when logging in to a SilverStream server. For example: -ss_password=icecream If you don't supply this option and user authentication is required, the application will display a dialog prompting for username and password. | |
Specifies a proxy server that you want SilverJRunner to use. Include the proxy server name and, optionally, its port number (the default is 80). Examples: -ss_proxy=corpproxy -ss_proxy=corpproxy:8080 Using SSL To use SSL with a proxy server, simply specify the HTTPS protocol for your SilverStream server: SilverJRunner -ss_proxy=corpproxy https://finance payroll frmSalary
| |
Displays a Java console window for the SilverJRunner session.
| |
Specifies the size (in bytes) of the SilverJRunner disk cache. This cache is used to hold any downloaded JAR files needed to run a form (or view). You can type the size in any of the following formats: -c 2000000 -c 2000K -c 2M | |
Required to run a view. This option tells SilverJRunner that the If you omit -v, SilverJRunner won't find your view (because it will look for a form with that name). | |
Displays usage information about SilverJRunner and how to start it. |
The following table describes the SilverStream + options you can provide when starting SilverJRunner in Windows:
Turns on profiling of SilverJRunner applications. HotSpot troubleshooting If you're running a version of the Sun HotSpot JVM that doesn't support the Java Virtual Machine Profiler Interface (JVMPI), you'll need to turn off HotSpot to do profiling. Specify the following additional option to turn off HotSpot and use the classic JVM instead: +classic
| |
Tells SilverJRunner to output only startup options to the console (if displayed), without all the other information generated in verbose mode. |
You can also pass standard VM options directly to the Java interpreter by specifying them as + options. The + character is automatically converted to - as the option is passed.
+verbose
passes this option to the Java interpreter as:
-verbose
When developing a form, you can code it to look for one or more application-specific arguments at runtime and then perform some processing based on those arguments. To help you do that, this section describes how to:
When starting SilverJRunner, add any application arguments to the end of the command (after the name of the form to run). For instance, to pass the arguments -dollars and 2 to the frmRates form (in the service database on the custserv server), you specify:
SilverJRunner custserv service frmRates -dollars 2
Here are some additional rules to keep in mind:
For more information on SilverJRunner command syntax, see
Starting SilverJRunner.
You can access the application arguments that SilverJRunner passes by coding the agGeneral.getArguments() method on your form. (agGeneral is a variable that's automatically included on your form to provide an instance of the PvHelperGeneral class from com.sssw.rt.form.) The getArguments() method returns a string array containing the passed application arguments.
For example, you might code the following for the form's formActivate event:
// Get the arguments passed in from SilverJRunner
String[] passedArgs;
passedArgs = agGeneral.getArguments();
// Check those arguments, then use them
if (passedArgs != null && passedArgs.length == 2) {
Field1.setText(passedArgs[0]);
Field2.setText(passedArgs[1]);
}
else {
agDialog.showMessage("Please supply exactly 2 args");
}
NOTE Including forms or views in pages is not supported in SilverStream Version 3.0 due to limitations of the Sun Java 1.2 browser plug-in. We hope to re-enable this support in SilverStream in the future. See the release notes for updated information.
If your application displays any pages that include SilverStream forms or views (or your own custom applets), you need to make sure all client machines have Java-enabled browsers installed. You must also make sure those browsers have an appropriate level of JVM (Java virtual machine) support, depending on how you've designed your pages:
For more information, see
Including Java forms and views in a page (in
Programming Pages).
If your application includes Java clients built outside of the SilverStream development environment, you'll need to set up each client machine with:
For details, see
Writing External Java Clients.
Before launching the production use of your deployed application, you should review its security requirements. Then you can set security options in the SilverStream Management Console (SMC) to meet those requirements, ensuring the integrity of your application, the server, and the data sources they access.
For details, see the chapter on setting security in the Administrator's Guide.
You can also use the SMC to adjust the performance of your SilverStream server and the applications you've deployed there. It enables you to monitor server activity, set performance options, and scale your production environment to meet demand.
To find the performance tuning features you need, see the quick reference chapter in the Administrator's Guide.
Profiling performance
An additional performance tool you can use is the SilverStream Profiler. It enables you to study processes running on your server or clients to identify and analyze performance bottlenecks in your Java code.
To learn about using this tool, see the SilverStream Profiler chapter in the online Tools Guide.