Comparing EventFlow Modules

< Previous		Next >

EventFlow Compare Overview

Eclipse provides a basic Compare Editor that provides side-by-side comparison of text-based source files. StreamBase Studio extends the Compare Editor to provide the following features:

Side-by-side comparison of two EventFlow files, or two versions of the same file, in graphical or XML text forms.
Side-by-side comparison of differences in Property settings for individual components in an EventFlow module.
Automatic display in XML text form of component types that cannot be shown in graphical form.
The ability to compare two selected files in the Project Explorer view, or the currently open file and earlier versions stored in the Eclipse local editing history.
Integration with supported version control systems (CVS, Subversion, and Git), allowing you to graphically compare the current version of an EventFlow module with a version from its version-controlled history.
For files compared from the Project Explorer view or from Eclipse local history, there is automatic support for separate layout files. If you select two files, or one file and an earlier version, Studio knows to also load the associated .sblayout file for each version, if available. Studio provides automatic layout file loaders that add knowledge of .sblayout file association to those version control systems.

The Compare Editor View

The Compare Editor view has two panels, top and bottom. The upper border of the bottom panel includes a compare mode control and a toolbar.

Top Navigation Panel

When you select two EventFlow module files to compare, or one file and an earlier version, the top panel shows a tree view. This tree is similar to the Outline view, but only the components with differences.

The top panel's tree view is organized as follows:

The root node is Application. Double-clicking this node shows a graphical comparison of the selected files or file versions in the bottom panel.
The next tree categories represent the tabs of the EventFlow Editor: Editor, Definitions, Parameters, Dynamic Variables, Annotations, and Metadata, in that order.
The Diagram tree shows categories in the same order as the Outline view: Operators, Data Constructs, Streams, Adapters, References, and Dynamic Variables.
The Definitions tree shows the following categories: Constants, Named Schemas, Table Schemas, Imports, Implements, and Arcs.

Use this tree view to select individual components or the application module as a whole for display in the bottom panel. Double-click the component of interest, or the Application node itself.

For files that can only be compared in XML text format, such as two StreamBase deployment files, or two server configuration files, the top panel is not shown.

Bottom Panel's Toolbar

The top margin of the bottom panel has a compare mode control on the left and a toolbar on the right.

Compare Mode Control

For files or file versions that can be compared graphically, the compare mode control lets you switch between graphical or XML text comparison modes. Default Compare, the default selection for this control, specifies automatic selection of graphical or XML text comparison modes based on each file's extension.

Toolbar

The bottom panel's toolbar has the buttons shown here, described in order below:

Some buttons are dimmed and inactive, depending on context. Use these buttons to step through the comparison's differences sequentially, or to merge changes from one side to the other.

Copy All from Left to Right: Merge all changes from the left side to the right side. Be careful to notice which comparison side has the newer file or file version.
Copy All Non-Conflicting Changes from Right to Left: For comparing version-controlled files or file versions, merge the non-conflicting changes from the right side to the left side. Again, be careful to notice which comparison side is newer and which is older.
Copy Current Change from Left to Right: Copy only the selected change.
Copy Current Change from Right to Left: Copy only the selected change.
Next Difference, Previous Difference: A difference is a region of one or more lines in the comparison that contain one or more changes.
Next Change, Previous Change: A change is an edit within a line or set of adjacent lines.

Bottom Comparison Panel

For files that can only be compared in XML text format, such as two StreamBase deployment files or two server configuration files, the bottom panel is the only panel shown.

For files that can be compared graphically, the bottom panel shows a side-by-side comparison in graphical form, XML text form, or Properties view form, depending on context.

Launching a Comparison

There are several ways to start an EventFlow Compare session for two modules, or a module and an earlier version. These include:

Compare Two Files

Compare two EventFlow module files:

In the Project Explorer, select two different EventFlow files with .sbapp extension. The two selected files can be in the same project or in different projects in your workspace.
Right-click and select Compare With>Each Other from the context menu, which opens the Compare Editor.

Compare One File To Its Eclipse Local History

Compare two versions of one EventFlow module file with the following steps:

In the Project Explorer, right-click a single EventFlow module file that has been previously modified in Studio, and select Compare With>Local History or Replace With>Local History from the context menu.
Or, for the currently open EventFlow file, right-click anywhere on the canvas background and select Compare With>Local History or Replace With>Local History from the context menu.
This opens the History view at the bottom of the Studio window, with a list of revision date and times for the selected file. Double-click the selected date and time of interest to open the Compare Editor view.

Compare Files in Version Control Views

You can open the Compare Editor view in several ways in your version control system's Eclipse plug-in views. Using the Subclipse plug-in as an example, you can:

Select two files in the SVN Repositories view, and select Compare With>Each Other from the context menu.
Select one file in the SVN Repositories view, and select Compare With>URL (Branch or Tag), then browse to select the file version from the repository.
Open the Subversion history for a file, select two versions in the history list, then select Compare with Each Other from the context menu.

You can compare StreamBase files of several types using the Compare Editor, not just EventFlow module files. This includes HOCON configuration files, feed simulation files, deployment files, and interface files.

Graphical Versus XML Text Comparison

For EventFlow modules, the following node types in the top panel cannot be compared graphically and automatically open a side-by-side text or XML comparison:

Constants
Imports
Implements
Parameters
Dynamic variables
Annotations tab
Metadata tab

Some items in the top panel do not open a comparison bottom panel, including many of the category nodes. Arcs cannot be individually compared, except for arcs that declare an explicit schema.

Non-EventFlow files are also compared automatically as text or XML.

For EventFlow module files, you can view the comparison graphically or as XML text.

Local History Comparisons

When viewing differences between versions of a file in Eclipse local history:

There are never any file conflicts.
File versions can only be added, removed, or changed.
Changes are not denoted by an icon in the tree, but they are marked in the graph in blue and have a delta icon.
Changes can only be copied from the historical version to the current version of the file, and not the reverse.
Additions are marked with a plus sign in the tree and are marked in purple and with a plus sign in the version in which they were added.
Deletions are marked with a minus sign in the tree and in the graph, and a minus sign and gray shading are used on the version in which they are still present (they cannot be marked in the version in which they have been deleted).

Compare Two Files

When viewing differences between two files, the difference markup is similar to a local history comparison described in the previous section.

The primary difference when comparing two files is that changes can be copied in either direction.

Compare from Version Control

When comparing file or version differences of files managed by a supported version control system, conflicts can be seen. When comparing a file with a different version of the same file managed by version control, items in the selection tree in the top panel can be decorated with icons representing different states:

Type of change	Navigation tree decoration	Description	Graph: Color Shading	Graph: Icon
Outgoing change	Right arrow	The current, local version has a change that the repository version does not.	Blue on local version	Delta icon on local version
Outgoing add	Right arrow with plus sign	The current version has an added feature that does not exist in the repository version.	Purple on local version	Plus icon on local version
Outgoing deletion	Right arrow with minus sign	The current version has removed something that still exists in the repository version.	Gray on repository version	Minus icon on repository version
Incoming change	Left arrow	The repository version has changed something, but the local version does not have that change.	Blue on repository version	Delta icon on repository version
Incoming add	Left arrow with plus sign	The repository version has added something the local version does not have.	Purple on repository version	Plus icon on the repository version
Incoming deletion	Left arrow with minus sign	The repository version has deleted something that the local version still has.	Gray on local version	Minus icon on local version
Conflict	Red arrow	Local and repository versions have made a change on the same operator, but not the same change.	—	—
Pseudo conflict	Pink arrow	Local and repository versions are the same, but they are both different than the ancestor version.	—	—

Layout File Handling

By default, EventFlow XML elements that describe the placement of components on the canvas (using elements with parameter names beginning with gui:) are stored in a separate .sblayout file with the same basename as the EventFlow file with extension .sbapp. When the layout changes are restricted to a separate layout file, layout changes are not reported in the Compare Editor. You can open two layout files or file versions separately in the Compare Editor.

Files migrated from earlier StreamBase releases may have the logical and presentation elements combined in the same .sbapp file. In this case, layout changes are flagged as differences in the Compare Editor along with functionality changes. See EventFlow Layout Options for instructions on moving layout information to a separate layout file.

When using a supported version control system, StreamBase includes a layout file handler that makes the version control system aware that it must open the layout file associated with each EventFlow module file in order to display the graphical comparison of the files or file versions. Layout file loaders are provided for CVS and Subclipse, which provides Subversion support.

If you install the Studio plug-ins into your own copy of Eclipse, you must install the Subclipse layout file loader at the same time, as described on Studio Eclipse Update Site.

Application Node Comparison

To see a graphical side-by-side comparison of two related EventFlow files, or between two versions of the same file, select the Application node at the top of the tree in the top navigation panel.

To see the underlying XML of the EventFlow module side by side, use the Compare Mode control at the top of the bottom panel, and select Text Compare:

Properties Comparison of Components

When you double-click an individual component in the top panel, the comparison in the bottom panel is now between two Properties views for that component. Named schemas and table schemas are also compared using the Properties view.

In Properties view comparisons:

If an item has been added or removed, that feature is highlighted in the Properties view on one side. The other side shows a note saying the item was added to or does not exist on that side.
If an item exists on both sides, it is visible in the Properties view on each side, with the information icon on the tabs that contain differences. The same coloring for changes in the graph is used in the Properties view: blue for changes, purple for additions, gray for removals. A hyperlink on each tab that contains a change allows you to see what changed and jump directly to the widget with the change. No conflicts are shown in the Properties view, so if the same widget has a change on both sides, it is not marked with red, but with blue.
Use the Next Change and Previous Change buttons in the bottom panel's toolbar to navigate through each change in the same Properties view. At the end, navigation wraps to the first or last change in the view and continues.

Editing and Merging While Comparing

The side-by-side graphical view is editable. For a two-file comparison, you can edit the canvas on either side. For a current version compared to an earlier version, you can edit the current version only. You can also edit by using the Apply All Changes or Apply Non-Conflicting Changes buttons in the toolbar. When you invoke Apply All Changes, if an operator exists in the destination but not the source, that operator is not affected. If you use Copy Non-Conflicting Changes, if the current operator exists in the destination and not the source, that operator is removed from the destination.

The side-by-side Properties view is also editable, following the same rules as for graphical view editing. You can edit changes directly on an editable side of the comparison, or you can use the Apply buttons as above. In the Properties view case, you must save all editing changes before leaving the Properties view comparison for each operator.

Tips and Limitations

Be aware of the following tips and limitations when using the Compare Editor:

Resolve conflicts in layout files as soon as you see them, but always before resolving conflicts in the associated EventFlow files.
Text merges using the Apply toolbar buttons do not operate when viewing a side-by-side XML comparison of an operator.
In EventFlow modules consisting of only a Note or Group, the Note or Group can continue to appear in the tree in the top panel even after both sides of the comparison are reconciled and are now identical.