Upgrading Legacy Projects to StreamBase 10+

< Previous		Next >

Invoking the Upgrade Wizard

The upgrade wizard runs in two ways:

Manually

When you use File>Import to import a project from another workspace or from an archive file, the upgrade wizard is not triggered. In this case, as soon as the project is imported into the Project Explorer view, right-click the project name and run Upgrade StreamBase Project from the context menu. This menu item only appears for legacy, pre-Maven projects.

Use the same procedure for projects you import from the StreamBase Component Exchange dialog.

Automatically

Every time StreamBase Studio starts, the current workspace is scanned for projects in the non-Maven format of a previous release. If any older format projects are found, the wizard prompts with a dialog like the following that offers to upgrade the project.

The wizard also runs automatically when you import an unconverted project using the Import Samples and Community Content dialog.

If many legacy projects are found, the wizard instead presents a list of the projects that need upgrading, with instructions on running the wizard manually. The list of projects also offers to run a Studio Quick Fix for all projects shown. This fix updates features in the pom.xml file for those projects. After running these Quick Fixes, run a Maven Update on all projects in your workspace, as follows:

Select the name of any StreamBase 10 Maven project in the Project Explorer view.
Right-click and select Maven>Update Project.
In the Update Maven Project dialog, click Select All.
Click OK.

Running the Upgrade Wizard

When you click the wizard's Upgrade Project button, the wizard invokes the New StreamBase Project procedure, with the project type determination (StreamBase Fragment or LiveView Fragment) already determined from inspection of the legacy project files.

The wizard shows its proposed name for the upgraded project, which is the name of the legacy project with _sb10 appended. You can change this to any name consistent with Maven naming standards (such as no hyphens), as long as your chosen name does not conflict with existing project names.

Remember that the project name you choose becomes the Artifact ID portion of the package name for the project, and the package name determines the directory structure of your project. See General Notes for further details on selecting a project name.

If you click Finish now, the upgraded project is created using the last Group ID you entered in the last New Project or Upgrade Project wizard you ran. To inspect or change the Group ID, instead click Next.

The next screen shows you the current Group ID selection, and allows you to specify a new one. See General Notes for further details on selecting an appropriate Group ID.

The generated package name is now your specified Group ID plus the project's Artifact ID.

You can click Finish now to create the upgraded project folder, or click Next to inspect the properties for the new project.

You can use this screen to change the pathname of the designated folder that contains EventFlow files if you have a significant, tested reason to do so. Do not change the repository setting except under the direction of product Support.

Click Finish to create the upgrade project folder in Maven format. See What Goes Where in Project Folders for a description of each folder.

The wizard leaves the legacy project in place for reference, with its original project name. When you have the upgraded project running to your satisfaction, you can delete the legacy project from the workspace.

Where Files Are Copied

The upgrade wizard copies files from the legacy project to the newly created project as follows:

EventFlow module files with .sbapp, .sblayout, .sbint, and .ssql extensions from the root of the legacy project are copied into the packagename folder under src/main/eventflow (such as com.example.deptname.projname).
Any EventFlow files found in subfolders of the legacy project are copied into matching subfolders in src/main/eventflow/packagename, which creates a subordinate package name such as com.example.deptname.projname.feature.
For LiveView projects, any LiveView configuration files with .lvconf extension at the root of the legacy project are copied to the root of src/main/liveview.
Any LiveView configuration files in subfolders of the legacy project are copied to matching subfolders in src/main/liveview.
All other files at the root of the legacy project are copied to the root of src/main/resources.
Other files in subfolders of the legacy project are copied to a matching subfolder in src/main/resources.

The New StreamBase Project wizard called by the upgrade wizard creates an empty EventFlow module file and matching layout file in src/main/eventflow/packagename, whose basename is the same as the project name. Since the upgrade wizard also copies the module files from your legacy project, this empty module file is not needed and can be deleted.

Adapter Dependencies

The upgrade wizard examines all EventFlow and StreamSQL module files for references to StreamBase adapters. If found, those adapters are added to the new project as Maven dependencies. This ensures that the appropriate JAR files that implement the adapters are loaded into the project.

Refactoring Performed

StreamBase 10 requires that references to EventFlow modules and interfaces must be made using fully qualified name (FQN) format. References to these files are made without the filename extension.

The upgrade wizard examines each EventFlow-related file to look for such references and converts them to FQN format without extension. The wizard examines the following locations:

Import specifications
Module references
Interface references, including references to an interface that a module implements
Extension Point references

References to resource files are made by pathname relative to the src/main/resources folder, and do include their filename extensions. The wizard looks for references to resource files and updates them to reflect their new location. The wizard examines the following locations, among others:

In Query Table data constructs, the name of a file used to preload the table
Module parameter values
Java operator instance variables

When refactoring, the upgrade wizard keeps track of where it copies resource files. If a resource was copied into a subfolder of src/main/resouces, then the replaced pathname includes the subfolder name.

It is possible for projects to have name collisions, in which two file names differ only by extension. For example, it is common for legacy projects to have same basename files such as DataFilter.sbapp and DataFilter.sbint.

The upgrade wizard resolves name collisions by appending a qualifier to one of the files. For example:

DataFilter.sbint resolves to DataFilter_sbint.sbint

DataFilter.ssql resolves to DataFilter_ssql.ssql

These resolutions occur in the order sbapp, ssql, sbint. This preserves the EventFlow module's legacy name, but corrects Interface and StreamSQL file names.

Manual Corrections

After the upgrade wizard runs, you may have to manually correct unhandled file and module name references in the upgraded project folder. Look for cases like the following:

The New StreamBase Project wizard called by the upgrade wizard creates a template TestCase.java file in src/test/java. This file references the empty EventFlow module file also created by the wizard in src/main/eventflow/packagename. To turn TestCase.java into a valid test file for the upgraded project, edit the file to specify the FQN of the top-level EventFlow module in the upgraded src/main/eventflow/packagename folder.
Update the path to any icon file specified for a Module Reference or Extension Point operator. The file itself is copied to src/main/resources, or to a subfolder thereof. However, you must open the module and locate the icon file again in the General tab of its Properties view. Studio then stores the icon file path relative to the src/main/resources folder, including any file name extension.

Configuration File Migration

The upgrade wizard examines the sbd.sbconf file in the legacy project, including all imported sbconf files that resolve to a top-level sbd.sbconf, and migrates the following features to the new project:

Any <adapter-configurations> section in the sbconf file is copied verbatim to a file named adapter-configurations.xml in src/main/resources.
Any JDBC data source definitions are migrated to HOCON format and placed in individual files, one per data source, in src/main/configurations.
Any operator parameters are re-specified in HOCON format in the file src/main/configurations/engine.conf. If a parameter's value can be mapped to a FQN, that is done.
Any custom function specifications are re-specified in HOCON format and also placed in src/main/configurations/engine.conf.

All other sbconf settings are your responsibility to migrate to HOCON configuration files, if those settings still apply to the upgraded project.

Multiple Project Configurations

Legacy StreamBase and Live Datamart projects can take the form of multiple Studio project folders with project references from one project to other supporting projects. The upgrade wizard supports the migration of such projects as follows:

Always upgrade a referenced project before a referencing project. Each project must be referenced with its FQN, which does not exist until the referenced project is upgraded.
When upgrading a project, the wizard records the name of a referenced project, then scans the current workspace for that name in FQN format.
- If the referenced project is located by FQN, then the reference in the referencing project is resolved.
- If referenced projects are not located by FQN, the wizard presents a list of those project names, and strongly recommends performing upgrades on those projects first.