This document describes how to migrate a SilverStream application database from Version 2 to Version 3. It includes the following sections:
It is important that you correctly set your expectations concerning migration. Migrating your application requires planning, organization, and effort. Make sure that you schedule enough time.
SilverStream recommends that you do not migrate a production application without first practicing the migration in your test or pilot environment. This allows you to identify problems and test your applications thoroughly without risk.
Before you start the migration process, you should set up an environment in which to do the migration. You perform these preparatory steps in the Version 2 environment.
To prepare your migration environment:
Although the database schemas are compatible between Version 2 and Version 3, the metadata formats for objects are not. Once you modify an object in Version 3, you can no longer modify it in Version 2. For this reason, SilverStream recommends that you work with a published version of the database and not the production database.
If you copy the database and create a new ODBC DSN entry instead of publishing it, then you lose:
NOTE If you are using SilverStream users and groups, you should upgrade your existing SilverMaster at install rather than creating a new one.
You can recompile them by choosing File>Build>Database for each database that you want to migrate.
These objects will not recompile in Version 3 either. Consider fixing these objects before migrating them.
Using SQL Anywhere 5.5
If your application database is a Sybase SQL Anywhere 5.5 database, consider upgrading the database to a Sybase Adaptive Server Anywhere 6 database.
SilverStream Version 3 includes an authenticated version of Sybase Adaptive Server Anywhere (ASA) 6 and uses it for its online help and sample applications. However, you can still use SQL Anywhere 5.5 for your application database.
If you do upgrade your SQL Anywhere 5.5 database, be sure that you specify the correct LDSKEY when you add the database to the server. The correct LDSKEY for Sybase Adaptive Server Anywhere 6 databases is SybAdaptiveV6AgBridge.
If you run both SQL Anywhere 5.5 and ASA 6.x databases on the same machine, you might encounter an authentication violation error. SQL Anywhere 5.5 and ASA 6.x both use the dbl50t.dll. If the path includes references to ASA 6.x before SQL Anywhere 5.5, you will encounter an authentication violation when you start SQL Anywhere 5.5. If the path references SQL Anywhere 5.5 first, you do not encounter this error.
For more information, see the chapter on Sybase SQL Anywhere and Adaptive Server Anywhere in the Installation Guide.
Once you have set up the appropriate migration environment and installed Version 3, you can migrate the test database.
To migrate an application database:
When you start the SilverStream Server, you will see the following message:
...Starting AutoUpgrade...
followed by a number of messages that indicate which databases are being upgraded. This message indicates that any pre-2.5 databases are being updated to the correct Version 2.5 and Version 3 format. If you are upgrading from Version 2.5 to Version 3, the databases are already in the correct format.
This autoupgrade occurs each time you start the server. You can shut it off by setting the following property to false:
http-server.com.sssw.srv.autoupgrade.25
This property is located in the httpds.props file.
When you open a page for the first time, even after rebuilding, the following message is displayed:
PageConverter::updgradeToCurrentVersion from 1.0 to 1.1
Upgrading MetaData from version 1.0 to version 1.1
This message is displayed because the metadata format for pages changed between Version 2 and Version 3.
The recommended action is to choose OK to upgrade the metadata and then to resave the object. If you do not want to upgrade to the new metadata version, click the close button (in the upper right corner of the dialog). Your page should still run as expected assuming that there are no other migration issues associated with it.
For Java applications, Version 3 of SilverJRunner must be installed on the client machine, along with the Sun Java 2 VM. Java applications that have only been recompiled should behave and look the same in Version 3 as they did in Version 2.5.
Some of the controls, such as checkboxes, may look slightly different than they did in Version 2.5; this is not a bug. The layout, spacing, and sizing of Java forms and views should look the same as in Version 2.5 under SilverJRunner.
If you have shortcuts assigned to existing Version 2.5 applications, when you install SilverStream Version 3, the file associations are automatically modified to the most recently installed version.
The underlying technology of the SAP R/3 EDC has changed. For this reason, you will need to re-create your SAP DSO objects. This does not require coding. It requires that you re-run the SAP DSO wizard once for each object. So that existing forms and pages that call the DSO do not need to be changed, you must give the object the same name as it had in earlier versions.
SilverStream Version 3 now supports the JBroker ORB. It no longer supports the Visibroker ORB. To make an existing CORBA application work in Version 3, you must:
For more information about writing new CORBA objects that use the JBroker ORB, see the chapter on using CORBA objects in the Programmer's Guide.
The migration from Version 2 to Version 3 includes a VM upgrade. The VM upgrade includes changes to fonts, font metrics, changes in the Java API, and so on. This document does not list every issue. You must test each form to understand how these changes might affect your application.
This section describes changes that:
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.
In Version 2, you specified how to load the data to your form or page through the Property Inspector. The default was "First Record" which caused SilverStream to download all of the rows that met the search criteria.
In Version 3, the form and page wizards now require that you specify how to load the data. If you cancel the wizard, the default is "No Automatic Query". You can still change this value using the Property Inspector.
The setEnabled(false) method on the tab control AgcTabControl and on a subform works differently in Version 3 than it does in Version 2.5. In Version 2.5, setEnabled(false) disables all of the controls on the container. In Version 3, setEnabled(false) does not disable the controls.
In SilverStream Version 2, a JAR file that contained JavaBeans was not required to include a manifest file. In SilverStream Version 3, JAR files that contain JavaBeans must include a manifest file indicating which classes are JavaBeans.
You can no longer run a form in the browser by typing in the form's URL, or clicking on the form's link. Although this was never a documented feature; users would often navigate through the URL hierarchy in the browser by clicking on the database name, then SilverStream, then Meta, then Forms, and then clicking on the form's name to run the form.
Java's JDBC 2.0 API added methods to the java.sql.ResultSet API. DSOs that use java.sql.ResultSet must be updated to include implementations for the new methods.
Please refer to the Java Core API section of the SilverStream online API Reference for all of the methods that need to be defined in an object that implements java.sql.ResultSet.
DSOs that have not been updated display the following error message on a build, compile or save.
xxxxxx must be declared abstract. It does not define boolean absolute(int) from java.sql.ResultSet ....
The Servlet API in JDK1.2 includes a new getSession() method on the HttpServletRequest interface. SilverStream Version 2 included a getSession() method. The new HttpServletRequest.getSession() method returns an HttpSession object while the SilverStream getSession() method returns an AgiSession. You will see the following error message when trying to build, save, or compile:
Incompatible type for vardeclaration. Explicit cast needed to convert javax.servlet.http.HttpSession to com.sssw.srv.api.AgiSession at line number 22.
To make your Version 2 servlets work in Version 3, you must cast the returned value (an HttpSession) to an AgiSession. The following example shows how to do it:
AgiSession s = ((AgoHttpRequestEvent)req).getSession();
AgoHttpRequestEvent hreq = (AgoHttpRequestEvent)req;
AgiSession s =(AgiSession)hreq.getSession();
Because SilverStream Version 3 supports Sun's Servlet 2.1 specification, SilverStream's AgiSession.getSession() method can no longer be supported.
The 2.1 Servlet API includes the following getSession() method:
HttpSession getSession()
SilverStream's AgoBusinessObjectEvent also included this getSession() method:
AgiSession getSession()
Since Java does not allow two methods with the same signature, but different return types, SilverStream must change the getSession() method that returns the AgiSession.
What you need to change
evt.getSession();
and expects an AgiSession must be changed to do an explicit cast to AgiSession.
The session object returned by SilverStream will still implement both interfaces.
This change affects all triggered business objects because the getSession() method appears on the AgoBusinessObjectEvent base class which is the parent of all triggered business objects.
SilverStream added the following new methods to the AgiServerListener interface in Version 3:
SilverStream automatically adds these methods to your server listener objects when you open and resave the objects. If you do not open and save the Server Listener objects, you get the following error when you try to build, compile, or save.
xxxxxxxx must be declared abstract. It does not define void serverDeactivating(com.sssw.srv.busobj.AgoServerDeactivatingEvent) from com.sssw.srv.busobj.AgiServerListener at line number 2.
EDC DSO objects (SAP, PeopleSoft, Notes) reference a JAR file contained in the SilverMaster database. If you are using a SilverMaster database with a new name, you will have to add the JAR file from the new SilverMaster database and re-compile these existing objects.
Because of the change in VM some of the date/time/timestamp formats have changed as outlined below:
In Version 2, if you called AgiDatabaseMgr.getDatabase(dbname) and dbname had not been added to the server, the method returned null. In Version 3, the method throws com.sssw.rt.util.AgoApplicationException in this situation.