In this document we discuss source control management (SCM) procedures in relation to WebSphere Integration Developer (WID) v6.2. We leverage the team development capabilities of WID and Eclipse using Subversion as the mechanism for remote source control management.
We begin with an overview of team development fundamentals and discuss the structure of a WID module. Thorough procedures that demonstrate how to interact with the Subversion server within WID are discussed, including the essential elements of Subversion source control management. Advanced Subversion topics are also examined.
We assume that you have some experience with WID and source control management fundamentals. This article is based strictly on the client-side interaction between WID and Subversion; server configuration is an advanced topic that goes beyond the scope of this discussion.
General overview of a WID project and collaborative development
WID project structure
Every WID application consists of an SCA module and an optional set of service library dependencies. The SCA module contains the core artifacts that are needed to deploy and run the application. Core artifacts may include—but are not limited to—business objects, interfaces, maps, and business processes. When the application is deployed and installed, Java code is generated based on core artifact logic.
Every SCA module also contains a set of generated staging modules. Since the staging modules define the JEE dependencies and optional web content, they generally do not need to be modified by the user. Since the staging modules do not contain authored BPM logic, they are not visible in the Business Integration perspective, but they can be viewed in the JEE or Resource perspective.
Staging module names are based on the SCA module base name. For example, assume that an SCA module, HelloWorld, exists in the WID workspace. After the SCA module is built, the following staging modules will be created:
Figure 1. Staging modules for a WID application
Note that the ModuleNameWeb will only be created if the SCA module has web service endpoint bindings defined in the SCA module. In general, only the SCA module and dependent libraries need to be managed in source control, but in certain cases you also may need to manage the staging modules.
Authored and generated artifacts
Artifacts that are created by the user in WID are said to be authored. If the user creates a new WSDL interface or business object, a corresponding .wsdl or .xsd file will exist in the workspace. In some cases, a single artifact type consists of multiple backing files. For example, when you create a new BPEL process, a few authored files including the .bpel, .bpelex, and Artifacts.wsdl file are created in the workspace. Each of these files is authored, since they are all necessary in order for the module to build successfully.
After a module is built in WID, Java code is generated for the authored artifacts during the deployment process. Generated artifacts are usually Java classes based on the logic defined in the authored BPM artifacts. Since generated WID artifacts are not needed during application development, they do not need to be managed in source control.
In WID v6.0.2 there were many inconsistencies between authored and generated artifacts. Some artifact generation happened during build-time, while other artifacts were generated during application installation. This process has been greatly improved in WID v6.2, as all artifact generation now occurs during application deployment and installation. Therefore, no generated Java files appear in a WID v6.2 SCA module.
Unlike SCA modules, staging modules are somewhat unique. The staging modules appear in the workspace after the SCA module is built. Because of this, staging modules do not need to be managed within SCM, as long as they contain no custom content or changes to the JEE deployment descriptor. If you add authored content to a staging module or make custom JEE deployment changes, then the affected staging modules will also need to be managed in source control so that these changes can be preserved. If you add custom content to the Web staging module, such as a HTML or JSP pages, the ModuleNameWeb module will need to be managed in the remote source control repository. To avoid confusion, consider creating a separate Web module for any custom web content, rather than rely on the ModuleNameWeb staging module.
Derived vs non-derived properties
Closely related to authored and generated artifacts are the derivation properties of an artifact. An artifact can be derived or non-derived, as specified in the file’s derivation properties under the Physical Resources view or Resource perspective, as shown below.
Figure 2. Derivation properties of an artifact
In some SCM products, such as CVS, the derivation properties of a folder or file determine whether or not an artifact is managed in the SCM system. Although CVS ignores all derived artifacts, Subversion does not conform to this pattern. Every file in the workspace, regardless of its derivation properties, will be committed to the repository by default. You can set filters in the Subversion preferences to exclude files from being managed under source control. Fortunately, in WID v6.2 this is usually unnecessary, since artifact generation does not occur until application deployment or installation.
Derived artifacts do not appear in WID v6.2 SCA modules, so an artifact’s derivation properties should never be modified. In previous versions of WID, the derivation properties of an artifact could be changed without too many consequences, but WID v6.2 is less forgiving. Any WPS-specific artifact that has its property changed to derived is immediately deleted from the workspace by the WID builders. This occurs because WID understands that derived artifacts are generated, and generated artifacts should only be present during deployment or install time. Therefore, if an artifact is changed to derived, WID assumes that this file must be generated and, likewise, should not exist in the workspace.
The lesson here is very simple: the derivation properties for WID v6.2 artifacts are strictly enforced in the primary SCA module and they should never be modified.
Module deployment editor (and how it relates to App module)
In early versions of WID, module deployment properties, such as Web services security and JEE deployment descriptor modifications, had to be made in the deployment descriptor of the App staging module.
This caused two problems. For one, module redeployment overwrites any custom modifications made in ModuleNameApp, so custom changes often had to be reconfigured. Second, by making these changes, the App module contained authored changes, and therefore had to be managed under source control. Ideally we want to limit the modules and artifacts under source control to those that are strictly authored.
As of WID v6.2, several deployment properties can now be set through the module deployment editor located in the primary SCA module. The module deployment editor saves changes to ibm-deploy.scaj2ee in the SCA module, which maps to the JEE deployment descriptor during deployment. Although the module deployment editor does not have every deployment descriptor property, in most cases it should be sufficient for your deployment requirements.
The module deployment editor can be opened by right-clicking on the module name and selecting Open Deployment Editor.
Figure 3. Module deployment editor
Team development with WID and Eclipse
WID plugins for Subversion client
To interact with the Subversion server, you need to install a client plugin to your WID environment. There are two Subversion client plugins that can be used within WID: Subclipse and Subversive. Although both plugins have similar feature sets, Subversive is said to be the official strategic path forward for Eclipse; therefore, we use the Subversive plugin for the scenarios discussed in this document.
The Subversion client plugin is not included in the default Eclipse or WID plugin list, so it must be installed. After the plugin is installed, you will be able to fully interact with the Subversion repository from WID.
The Appendix and Reference sections have some information on Subversion client plugin configuration.
Perspectives and views within WID
There are several perspectives and views in WID and Eclipse that are useful for collaborative development. The following four are critical to team development:
- Business Integration
- Team Synchronizing
- SVN Repository Exploring (Note that if you are not using Subversion, this perspective name may vary)
Figure 4. Perspectives used for team development within WID
Business Integration Perspective
The Business Integration perspective is the integral piece of WID, as artifact design, development, and component integration occurs here. Additionally, most team development activities (check out, commit, update) can be accomplished through this view.
Physical Resources view
As part of the Business Integration perspective, the Physical Resources view lists the relevant artifacts and resources for WID modules and libraries. The Physical Resources view is similar to the Project Explorer view under the Resource perspective, except that only SCA modules are shown—staging modules are not shown.
Although not as significant in v6.2, the Business Integration view includes a Show Files option that displays all authored files for an artifact. For example, a BPEL process saves its process flow logic in a .bpel file, but there are other backing files–.bpelex, .mon, and Artifacts.wsdl—that are needed for the BPEL process to build properly. The Show Files option will highlight all four files.
Use the Show Files option as follows:
- From the Business Integration view, right-click on the artifact and select Show Files.
Figure 5. Show files
- Some artifacts, such as BPEL processes, have multiple backing files. When you Show Files you will see the following window. The Artifact Secondary Files filter only shows the main artifact. If you click Yes, this filter will be disabled and all backing files will be highlighted.
Figure 6. Disable filter
- Notice that the files are highlighted in the Physical Resources view.
Figure 7. HelloWorldProcess Resources
The Project Explorer view listed under the Resource perspective is packaged with Eclipse and lists every module and artifact in the workspace, including all staging modules.
Team Synchronizing Perspective
The Synchronize view within the Team Synchronizing perspective allows you to synchronize the workspace with the remote repository. It will display any relevant outgoing or incoming changes and can identify any appropriate merge conflicts.
SVN Repository Exploring Perspective
The SVN Repository Exploring perspective lists all modules or projects that are currently managed under Subversion. If your project uses a different SCM provider, then a similar perspective may exist.
Projects in the SVN Repository Exploring perspective are listed by their most recent revision number, but older module revisions can also be viewed and checked out from source control. Branches or tags that have been defined for a particular module can also be checked out through the SVN Repositories view. You can use the History view to see the series of changes for a module.
SVN Repositories View
This is the main view in the SVN Repository Exploring perspective. The HEAD revision tree is listed by default and contains all of the underlying modules with their respective trunk, branches, and tags listed in the repository.
SVN Repository Browser View
Similar to the SVN Repositories view, this view shows the last modified-by timestamp, artifact owner, and file size.
The History view displays the entire revision history and change log for a given module or artifact. This view is similar to the SVN Repository Browser, except that the artifacts are classified by revision number rather than the module name.
Team development with WESB mediations and modules
When you create a mediation flow in WID v6.2, you have the option to optimize the mediation flow for team development. By default the mediation flow is saved as a single .medflow file for all operations. Thus, if you have a flow with five operations, all logic will exist in a single .medflow file.
If the mediation flow logic is saved as multiple files, a .medflow file will exist for each operation mapping. This is beneficial for collaborative development, since each developer can be assigned an operation flow. Note that if your mediation flow only uses a single operation, there is no benefit in enabling the collaborative development option.
Figure 8. Mediation flow team development options
There are a few stipulations when saving mediations as multiple flows:
- The mediation flow operation mappings must exist in the same module, regardless if the team development option is enabled or not. Do not create a separate module for each operation flow.
- All users should check out the module from source control. Since each operation has its own .medflow file, merge conflicts for the mediation flow logic cannot occur. Merge conflicts can occur, however, if non-mediation flow artifacts are modified by multiple users.
General recommendations when working in a team environment
Managing SCA modules, libraries, and staging modules
- Team development functionality has been greatly enhanced in WID v6.2. Virtually all interaction with the SCM server can be done in the Business Integration perspective. The derived vs non-derived paradigm has also been incredibly simplified. All artifacts in the service module are now authored (non-derived), while all generated artifacts and Java classes—such as those files created from a BPEL application—are generated during deployment or application installation time.
- When using libraries, keep in mind that changing a shared BO or WSDL may have unexpected side effects on other modules or components that also use this library.
- Staging modules are created by the WID builders during deployment, and they usually do not have to be managed in source control.
- The ModuleNameApp staging module may need to be managed under version control in rare cases where the module deployment editor lacks a feature that otherwise exists in the ModuleNameApp JEE deployment descriptor.
- The ModuleNameWeb staging module may also need to be managed under source control if it contains custom code, such as web client interfaces. In cases where custom web content is added, consider creating a separate Web project for custom dynamic web content. Otherwise, the generated ModuleNameWeb module will need to be managed in source control.
Derivation properties of an artifact
- Never explicitly change the derived flag in the artifact properties. Unlike in v6.0.2, the derivation properties are more transparent in v6.2 and should not be modified by the user. In fact, if a non-derived WID artifact (i.e, authored) is changed to derived, WID will permanently delete the file from the SCA module. This occurs because the WID v6.2 builders assume that a derived file is a generated file. From WID's perspective, generated files can only be created during deployment or install time. Therefore, WID assumes this derived artifact is there by mistake and deletes it from the workspace. Note that this behavior only exists for SCA modules; other modules, such as Web or Java projects may contain derived artifacts, which will not be removed during deployment.
- Consider using the Show Files option in the Business Integration view to see a list of backing files for a given component.
Checkout modules from version control
- When working with a module managed in SCM, make sure to check out the entire module from the remote repository. Never check out an individual artifact, such as a single WSDL or XSD file, from a module managed in source control.
- Although a module can be checked out by multiple users simultaneously, only one person should ever have write-access to the module at any one time. Enforcing such practices can prevent tedious merge conflicts. If you need to make changes to a module and want to prevent other users from committing any changes, consider using the locking the module for exclusive write-access.
Synchronizing with the remote repository
- Always synchronize changes with the repository before doing any commits or updates. Although a full synchronization is not strictly required before committing or updating artifacts, doing so will not only provide you with a full list of changes, but may also prevent you from inadvertently overwriting modified artifacts saved by other users.
- If synchronization conflicts do occur, the developers should manually merge the changes rather than rely on the text-based merge techniques that are used in the WID merge tools. Although text-based merging works well with Java code, such practice is not quite as useful for XML-based WID artifacts. If you use the merge tools to combine two BPEL processes, you will be merging raw XML code or plain text, which is contrary to the standard GUI editors that exist for many WID artifacts.
- When an artifact is removed from the local working copy and the module is committed to the repository, it will also be removed from the HEAD revision. However, depending on the SCM feature set, the artifact may still exist in the repository under a previous revision set.
- Beware that modules are only “version-aware” when they are deployed via serviceDeploy. Versioned modules exported as EAR files through WID or added to the UTE via Add/Remove Projects do not observe a module’s versioning properties.
- Consider managing the initial module version (i.e., 1.0.0) under the trunk in source control. All successive versions should be placed in their own branches under the root trunk.
- Understand that WID currently does not enforce an incremental module versioning pattern. Instead the module versioning is completely arbitrary and is assigned by the user. This means that you can theoretically have a module 5.2.5 that contains older content than module 1.0.0.
- When committing versioned modules as branches, specify the module version number in the branch name. Also add appropriate branch comments that identify the version number. This will assist other users, by offering information on the version they are checking out.
- Do not over-abuse module versioning. Ideally, each module version should fulfill a specific purpose—for example, a versioned module that handles traffic during seasonal operations. Module versioning should never take the place of SCM versioning and revision history. Let the source control management system handle the typical day-to-day development changes.
Team development with Subversion
Preferences can be viewed or changed under Window > Preferences > Team > SVN. We used the default Subversive options for the examples discussed in this document, and this should be sufficient for most users. Please review the Subversive documentation for information on the preference settings and options.
Figure 9. Subversive client plugin preferences
Although some preferences may be modified, always keep the default option to use the .project file for the project name, rather than use the folder name. Although this setting can be changed, WID modules rely on the name defined in the .project file, which is also used by sca.module, sca.modulex, and other artifacts in the module. By reading the module name from the .project metadata file, rather than a user-defined folder, module name discrepancies can be avoided. This setting can be found under Preferences > Team > SVN > Repository.
Figure 10. Subversion .project file preference
Subversion project layout and structure
Projects in Subversion are arranged in the repository in a hierarchical tree structure. There are a variety of ways to organize your modules in Subversion depending on your project needs and solution complexity. For the examples presented in this document, we choose to place each module or library in the root directory, but there is no right or wrong way to organize your modules in the Subversion repository. Smaller projects may benefit by placing all modules and versions in a single folder, whereas complex enterprise solutions may require multiple repository locations. In either case, the project layout structure within the repository should be consistent.
Trunk, branches, and tags
Within a managed module, you will have a trunk to hold the base or active version of the module, as well as optional branches and tags. When a module is initially managed in SCM, the artifacts are managed under the trunk. Every WID module or library managed in the repository contains its own trunk.
You may need to make a copy of the trunk in order to maintain a separate development tree. This is where branches are useful. Branches contain an independent development path for a given module, and are often used when you need to manage multiple development streams for a module. Although branch artifacts may morph into something functionally different from the trunk, a branch always begins as a copy of the trunk or another branch. For example, you may create a branch that contains different process logic for handling transactions during the holiday shopping season, perhaps by offering special discounts or shopping incentives. Likewise, branching is often useful in WID when implementing module versioning. However, you should only create branches when you have a separate line of development; branching should never replace the revision history for a given module.
Branches, and similarly tags, have their own managed set of artifacts and revision history. Tags are very similar to branches, except that they manage a snapshot of a project or module and do not allow users to commit changes. The differences between branches and tags are discussed below.
Tagging vs branching
Similar to branching within Subversion is tagging. A tag is a snapshot of a project at a certain point of time. For example, you may want to create a tag for a specific production release once all code development is finalized.
You may be thinking that tags are very similar to branches. In fact if you were to use the command-line Subversion tools to create tags, you would realize that there is no difference in the way a tag or branch is created—fundamentally they are the same. In other words, there are no technical differences between tags and branches—they are merely classified differently per their intended usage. If users do not commit changes to a snapshot, it will remain a tag. However, if changes are committed to the snapshot or tag, then it becomes a branch.
Repository revision numbers
When a module or artifact is committed to the repository, a revision number is assigned to the module and its artifacts, where each revision number represents a historical snapshot of an artifact. By default, the most current revision, or HEAD, will appear in the repository view; however, former revisions can be accessed through the SVN Repository Exploring perspective.
Figure 11. Repository revision numbers for managed artifacts
Adding WID projects to Subversion
Projects can be added to the remote repository through the Business Integration view. Although the procedure discussed here is specific to Subversion, similar concepts apply if another version control system is used, such as CVS or Clearcase. Projects added to Subversion will appear in the repository’s HEAD revision.
To add your local project to source control, do the following:
- From the Business Integration view, right-click on the module name and select Team > Share Project...
Figure 12. Share project
- Select the repository type (in this case we are using Subversion). Click Next.
Figure 13. Share project - SVN
- Create or select the repository under where the module should be managed.
- If no other projects in your current workspace are managed by Subversion, you will need to Create a new repository location. Enter the repository URL and authentication credentials. Under Advanced, ensure that the Enable Structure Detection checkbox is enabled with the following settings:
- Otherwise, select Use existing repository location. Click Next.
Figure 14. Enable Structure Detection
Figure 15. Use existing repository location
- Specify the project layout and location. Note that this is purely subjective—there is no right or wrong way to organize your modules in source control, and you may find that a different organizational pattern, either simpler or more complex, works better for you. We recommend the following configuration:
- Select Advanced Mode.
- Keep the Name on Repository value set to Use project name.
- Change Project Repository Layout to Use single project layout.
- Leave the Use Subversion recommended layout ('trunk', 'branches' and tags) value checked. Your settings should resemble figure 16.
- Click Next.
Figure 16. Specify location
- Enter an optional description in the comment field. A general default comment will be created for you, but you can change it to something more specific. Leave the option Launch the Commit Dialog for the shared resources enabled.
Figure 17. Launch the Commit Dialog for the shared resources
- Click Finish to commit the module to the repository.
- A new comment dialog box will appear. This differs from the previous comment since it applies to the artifacts and not the module. Enter a value and click OK.
- The module is now managed in source control. Notice that there is now a revision number and URI next to the module name in the Business Integration view.
Figure 18. New URI
Managing Integration Solutions in source control
WID introduced integration solutions in v6.2. These are non-deployable projects that allow you to logically reference interworking modules in a workspace, including SCA modules, mediation modules, libraries, and Java projects. The integration solution diagram shows the invocations and relationships between the modules.
Although integration solutions have no deployable logic, they can still be managed in source control like any other WID project. Additionally, there are a few options in integration solutions that allow you to streamline some team development tasks.
To add projects to the integration solution:
- Right-click on Project References and select Add or Remove Project References.
Figure 19. Add or Remove Project References
- A window containing a list of workspace projects appears. Check or uncheck the modules that you want managed in the repository. Click OK to save the changes.
Figure 20. Select Projects
Modules that are referenced in the integration solution can be checked out from source control as follows:
- Right-click on Project References and select Check Out Referenced Shared Projects.
Figure 21. Check Out Referenced Shared Projects
- The projects are checked out from the remote repository and any modules that exist in the workspace will be overwritten.
In most cases it is best to check out the referenced modules directly from the repository, rather than use the integration solution functionality. When you use the integration solution to check out the module, only the trunk from the HEAD revision is checked out. Furthermore, integration solutions can be managed in SCM like any other WID module. At their core integration solutions are very simple, consisting of only projectSet.psf and solution.graphml, which identify the solution module dependencies.
Checkout projects from Subversion
You can checkout modules from Subversion by doing the following:
- Open the SVN Repository Exploring perspective. If necessary, add a New Repository Location to the workspace.
Figure 22. New Repository Location
- Refresh the repository location to view the most recent snapshot in the repository.
Figure 23. Refresh the repository location
- Expand the module or project that you want to check out. If you are using the trunk/branches/tags layout pattern discussed earlier, expand either the appropriate folder. In this case we will check out the trunk copy.
Figure 24. Trunk copy
- Right-click on the trunk folder and select Check Out to import the module into your local workspace.
Figure 25. Check out
Deleting projects and artifacts
There may be times when a specific artifact or entire module is no longer needed in a project. If an artifact is removed from the local working copy, it will no longer appear in the repository’s HEAD revision once the module committed to the remote repository. However, the artifact will still exist in the HEAD revision, so it can be recovered if necessary. Modules and artifacts can also be removed directly from the Subversion repository.
Synchronize changes between the working copy and repository
As you work with modules managed in source control, there may be changes between the local and remote copies of the modules. To keep the artifacts in the local working copy and remote repository in accordance with one another, the local workspace should be synchronized with the remote repository. The Team Synchronizing perspective will synchronize the local and remote copies, and will identify artifacts that need to be committed or updated. If an artifact has been modified and committed by multiple users, a merge conflict warning is shown in the synchronization wizard.
To synchronize the workspace module with the remote repository, do the following:
- In the Business Integration view, right-click on the module name and select Team > Synchronize with Repository.
Figure 26. Synchronize with Repository
- A popup dialog will appear notifying you that the Team Synchronizing perspective will be opened. Click Yes.
Figure 27. Team Synchronizing perspective
- A list of modified artifacts will appear in the Synchronize view. Notice that in this case there are artifacts with outgoing changes, incoming changes, and conflicts.
Figure 28. SourceControlTest
- By default the Incoming/Outgoing Mode is selected, meaning that all changes and conflicts will appear in the synchronization list. As shown below, you can change the filter to show only outgoing changes, incoming changes, or conflicts.
Figure 29. Filter changes
At the bottom of the WID window, the number of incoming, outgoing, and conflicted changes is listed.
Figure 30. Incoming, outgoing, and conflicted changes
- At this point you can commit, update, or merge conflicts through the Synchronize view. Right-click on the module or artifact to make these changes (see subsequent sections for more details on commit, update, or merge).
Although you may update or commit before synchronization, this is highly discouraged. The synchronization wizard will show you a full list of changes that have been made in the local and remote module versions. If you commit or update these changes without synchronization, then you may overwrite critical work from other users. Avoid these problems by always synchronizing first. Furthermore, when you are working with modules that may see frequent revisions, synchronize often to verify that your local working copy is current.
Commit changes to repository
Any changes made to the local working copy must be saved to the remote repository before the changes take effect. This is where the commit comes into play. When the project is added to the repository, an initial commit saves all artifacts from the local working copy to the repository.
Artifacts should be committed to the repository under these circumstances:
- Changes to artifacts that currently exist in the repository. i.e., an existing BO is modified to include new data fields.
- Addition of new artifacts to a module currently in the repository. i.e., a new BPEL process is added to the local working copy.
- Removal of artifacts from the module. i.e., a WSDL file is deleted from the working copy.
If you see a "dirty" flag (>) in your workspace, it suggests that your local copy differs from the remote repository copy. You may want to synchronize or commit your changes to the repository to assure that the remote copy is in concurrence with your local working copy.
Figure 31. Flag denotes that something has changed in the workspace
Commit workspace changes by doing the following:
- Synchronize the workspace with the remote repository. If there are no changes found between the local working copy and remote repository, there is nothing to commit or update.
- Open the Team Synchronizing perspective to view the synchronization summary.
- Commit the changes to the repository. You can either commit all every change in the module or commit individual artifacts. Right-click on either the module name or artifact and select Commit... A commit dialog box will appear.
Figure 32. Commit dialog box
Alternatively, you can click the Commit All Outgoing Changes button at the top of the Synchronize view window.
Figure 33. Commit All Outgoing Changes button
- Enter an optional comment in the commit dialog. Click OK to commit the changes.
Figure 34. Enter commit comment
- After the module is committed and the workspace is synchronized notice that there are no more open changes for the specified module.
Figure 35. No changes in module
- Synchronize often to check for updates from other users. This is especially important for core artifacts that may be used in multiple modules, such as libraries with WSDLs and XSDs.
- If you try to commit items that have been modified by other users you will see a merge conflict. Although there are merge tools within the Team Synchronizing perspective, these tools are designed for traditional code such as Java and do not work well for XML-based WID artifacts. Therefore, merge conflicts should be handled manually.
- The commit operation can only be used for modules that are already managed in source control. If you are creating a new module then use the Share Project... dialog.
- If you make any changes to the local working copy, notice that the dirty flag (>) marker appears next to your module name.
Update changes from repository to the local working copy
We discussed commit in the previous section, which you used when saving your local changes to the repository. However, there are times when other users may have made changes to a module that you have checked out. In this case your local working copy is out of sync, and needs to be updated. An update is effectively the polar opposite of commit—instead of pushing changes from the local workspace to the repository, an update will get any changes from the repository that may have occurred from the time the module was checked out. Since you do not know when a module will need to be updated, you should synchronize your local copy with the remote repository on a periodic basis.
Update your local working copy as follows:
- Synchronize your workspace with the remote repository. If everything is synchronized, then no updates are needed.
- View the synchronization list through the Team Synchronizing perspective.
- Update your local workspace. Similar to the commit operation, you can either update the entire module or individual artifacts. Right-click on either the module or artifact name and click Update...
Figure 36. Update module
Likewise, you can Update All Incoming Changes directly from the Synchronize view button options.
Figure 37. Update All Incoming Changes
- The workspace is now up-to-date.
Suppose there are two users, Joe and Tom, who are working on the same WID project. They each checkout a set of modules from the repository and without telling each other about their plans, each makes a set of changes to a BPEL process in a module ShipOrderModule. Joe makes his changes quickly and synchronizes his copy with the remote repository. There are no conflicts, so he commits the changes and closes his workspace. A few hours later, Tom decides to commit his changes to the process. He synchronizes and immediately notices a conflict—Joe has also been working on the same set of artifacts.
Tom has three options at this point:
- He can force his changes to the repository HEAD, thus overwrite Joe's changes (Joe's artifact will still exist in a preceding revision since it was already committed).
- He can update his local working copy to reflect the changes that Joe made to the repository, but he will lose all of his recent work.
- He can use the merge tooling to merge the changes between Joe’s copy and his own work.
There are a few options you have when merging conflicts. For traditional source code, such as Java, the best and easiest option is to use the merge tooling to assist with integration from both versions of the code. However, this is not quite practical for WID artifacts, since they are XML-based and are usually very difficult to integrate in raw-text format. Most often WID artifacts are developed using GUI tools, so performing text-based integration is risky and error-prone. Currently, there is no way to do a graphical merge-and-compare for WID artifacts.
If a core artifact is improperly merged, the process needed to rectify these problems can be very time consuming and may adversely affect other artifacts or modules. If you absolutely need to merge WID artifacts due to conflict, make sure you keep local copies of both artifacts in case you need to revert to one or the other.
Merge conflicts address the importance of frequent synchronization practices. If Tom had synchronized on a frequent basis rather than wait a few hours, he would have noticed that the BPEL process had been modified by Joe long before he made any significant modifications to the process. He could have then discussed the changes with Joe and perhaps integrated them into his local working copy to avoid ambiguity during commit.
So, what is the best approach? If at all possible, try to avoid merge conflicts altogether. If you know that multiple users will be working with a common module or library, discuss this with your team and make certain that only one person will make changes to an artifact at any given time. You can also use the Lock and Unlock options in the Team menu to lock read or write access to specific modules or artifacts.
Mark as Merged option
The Synchronize view has a Mark as Merged option that allows you to override the conflict markers by marking the artifact as if it is already merged. This is useful when you have manually merged the artifact in question and do not want to use the text-based compare-and-merge tooling to merge conflicts.
To mark the file as merged right-click on module or artifact from the Synchronize view and select Mark as Merged. The merge-conflict indicator will be removed and the artifact can now be committed or updated, accordingly.
Locking and unlocking resources
To avoid merge conflicts, you may want to prevent multiple users from having write-access to a module or resource. You can do this by setting locks on a particular module. When a module or artifact is locked, other users can still check out the module, but they will not be able to commit any changes until after the lock is released.
Lock a module as follows:
- Check out the modules from the repository.
- From the Business Integration view, right-click on the module and select Team > Lock...
Figure 38. Lock module
- Enter an optional comment and check the Lock recursively option. Click OK.
Figure 39. Lock recursively
- The module is now locked for your exclusive use. You will see pink lock icons in your workspace.
Figure 40. Locked modules
- When you no longer need exclusive access, make sure you Unlock the module.
- a. Right-click on the root module name and select Team > Unlock.
- Check the Recursively option and click Yes. The module should now be unlocked in your workspace.
Figure 41. Unlock the modules
Figure 42. Check the Recursively option
- Locking only affects write-access to an artifact. If a module is locked by one user, other users can still check out a locked module, but they will not be allowed to commit any changes until the lock is released.
- Multiple users can attain write-access for a locked module by using the Force lock option. This practice is discouraged, however, since it opens the possibility for merge conflicts.
Figure 43. Force lock option
Working with branches
Branches allow you to create a new development line from an existing module. They are useful when you have a unique code stream that is soundly based on the trunk module. This section describes how you can create and checkout branches from repository.
Create a new branch from the Business Integration view
You can create a branch from an existing module in the Business Integration view. To create a branch, the module must currently exist in Subversion, either as a trunk or different branch, and must be checked out in your local working copy.
- Verify that your local workspace contains the trunk or a branch for the module from which you want to create a branch.
- Right-click on the module name and select Team > Branch... A new window will appear.
- Enter a name for the branch and select the Start working in the branch option. You are also strongly encouraged to enter a comment, since it will provide your team with a means to identify the purpose of the branch. Click OK.
Figure 44. Enter branch location
- The branch will now be created in the remote repository.
Figure 45. Branch created in remote repository
If you selected the option to start working in the branch, then your local working copy will reflect the newly-created branch name.
Figure 46. New branch directory
You can also create branches directly on Subversion within the SVN Repository Exploring view.
- Open the SVN Repository Exploring view and browse to the desired module. In this case, we will branch from the HelloWorldProcess trunk. Right-click on trunk and select New > Branch...
Figure 47. New branch
- A new window will appear. Enter a branch name and optional comment and click OK.
Figure 48. Enter a branch name and optional comment
- The branch will appear in the SVN Repositories view, but it must be checked out before it appears in your local working copy.
Figure 49. Listing of branches
Checkout a branch from the repository
- Locate the module and branch within the SVN Repositories view that you would like to check out. Expand branches to get a list of available branches for a module. For this example we will check out branch03.
- Right-click on the branch name and select Check Out.
Figure 50. Check out branch
- Since the trunk and all branches for a module share the same module name in the repository, you may be notified that the module already exists in the local working copy. Select the module name to overwrite the local working copy and click OK.
Figure 51. Override project
- The selected branch now appears in the local working copy.
Advanced Subversion topics
This section briefly outlines some of the advanced features found in Subversion. For detailed information on these topics, please visit the Subversive help files or the Subversion server documentation.
There are two overriding commands available in the Synchronize view: Override and Commit and Override and Update. These commands will override any changes in the repository (on commit) or local working copy (on update) for a given module or artifact. Take caution when using the override commands—you may inadvertently overwrite changes to your local workspace or remote repository.
It is usually better to use the standard Commit and Update commands in conjunction with Mark as Merged.
Right-click on the module or artifact to access the following override commands.
Figure 52. Override commit and update operations
Revert changes in local working copy
If you make changes to your local working copy, but later decide that these changes were accidental or unnecessary, you can discard the changes by using the Revert option. This will restore the artifact to the state defined in the corresponding repository revision.
To revert a module in your workspace, right-click on the module name and select Team > Revert... A popup menu will appear with a list of modified artifacts. Choose the artifacts that you want to revert and click OK. Notice that the "dirty" flag (>) is removed for said artifacts.
Figure 53. Revert changes made to local working copy
Using the History view
You may want to view the source control revision history for a particular module or artifact. The History view located in the SVN Repository Exploring perspective will show you an artifact’s revision. The revision number, commit time, artifact author, and any available comments are listed in the History view.
View the artifact history as follows:
- Open the SVN Repository Exploring perspective.
- Expand the module and locate the artifact for which you want to view the revision history.
- Right-click on the artifact and select Show History.
Figure 54. Show history
- A list of available revisions will appear in the History view. Click on a revision to see the change history.
Figure 55. History view
Selecting a specific revision in the repository
In most cases you will check out your modules from the repository's HEAD revision, but occasionally you may want to check out a particular revision. The SVN Repositories view allows you to view any revision in the repository, as well as check out the trunk or branches to your local workspace.
You can browse and check out a particular module revision as follows:
- Open the SVN Repository Exploring perspective and fine the SVN Repositories view. Look for the REVISIONS tree under the root repository location.
Figure 56. Revisions tree
- Right-click on REVISIONS and click Select Revision...
- A popup window will appear. You can select an existing revision by Date or Revision number. Click on Browse... to select a revision number. Click OK after selecting a revision.
Figure 57. Select the revision
- To list the modules that exist in the aforementioned revision, expand the REVISIONS tree until you see the trunk, branches, and tags. You can now check out the module revision, just as you did for the HEAD revision.
Figure 58. Revision tree
Switching from one workspace revision to another
In the previous section you learned how to browse and check out previous revisions that exist in the repository. Such practices are convenient when you are importing a module to your workspace, but there may be times when you want to check out an older version of a module that already exists in your workspace. This is where switching is used.
Switch a module to a different revision as follows:
- Open the Business Integration perspective and highlight the module that you want to switch.
- Right-click on the module name and select Team > Switch...
- A new window will appear.
- Click on URL Browse... to select a URL for the module location. Select the appropriate trunk or branch.
Figure 59. Browse
- From the Revision section, choose a revision by Date or Revision number. We chose Revision number for this case. Click on the Revision Browse... button and select a revision.
- Leave Depth at the default Working copy value.
- Your settings should resemble something like this. Click OK.
Figure 60. Revision Browse
Figure 61. Select URL and revision of the repository resource
- The selected module revision will be imported into your workspace. Notice that the revision number has changed based on your selection.
Figure 62. Revision number
Notice that Select Revision and Switch are similar in that they both allow you check out a prior revision in the repository. However, the Select Revision option is only available in the SVN Repository Exploring perspective, while the Switch command is available in the Business Integration perspective via the Team menu. If the module does not exist in your local working copy, you should use Select Revision, whereas Switch should be used for modules that already exist in your local working copy.
Replacing the local working copy with a version from SCM
Similar to switching, you can use the Replace With features to switch between available branches or revisions that exist in the repository. There is no advantage in using this method over switching—it simply provides you another way of doing the same thing.
- From the Business Integration view, right-click on the module name and select Replace With.
- Select the appropriate option below and follow the context menus as you would with the switching. If you select Latest from Repository, the local working copy will be replaced with the latest module version in the repository.
Figure 63. Using the Replace With to switch branches
When you replace a module beware that any unsaved or uncommitted artifacts will be removed from the local workspace. Therefore, you should synchronize before replacing the local working copy.
Module versioning in WID
Module versioning is new to WID v6.2 and it allows you to do a few things. First, you can logically manage modules based on a defined feature-set and can easily deploy a specific version to fulfill a given purpose, if desired. Perhaps more importantly, you can simultaneously install multiple versions to the same runtime target. Modules can only be versioned through the dependency editor in WID.
In order to create a version-aware EAR file, a versioned module must be deployed using serviceDeploy. Modules exported as EAR files from WID will build and install properly, but they will not be version-aware. Likewise, applications added to the UTE via Add/Remove projects are also not version-aware.
The IBM Supplied Version Scheme uses a three-digit numerical version system in the format <MAJOR>.<MINOR>.<SERVICE>. For example, an early version of a module may have a version number 1.0.2. The values for MAJOR, MINOR, and SERVICE are purely subjective and must be modified by the user. The developer must decide when to increment each category, since WID does not keep track of the incremental module versions. Furthermore, successive numerical ordering is strongly encouraged, but not enforced. In other words, there is nothing in WID that will stop you from creating a module version, say 1.0.1, that contains newer content than version 2.1.0. Dependent projects and libraries of a versioned module do not have to be versioned, nor do they have to use the same version number as the referring module. Module versioning properties can be set under the module’s dependency settings.
Figure 64. Module version settings and number
Beware that when modules are versioned, only the module name is uniquely modified. This will allow you to install two or more copies of the same application on a WPS runtime; however, any BPEL processes or human task templates will not be changed, and therefore may prevent you from installing multiple application versions on the same runtime target. The process or task templates must be unique for a given process or task container. If you try to simultaneously install multiple modules versions to the same runtime target without also versioning the human task or BPEL process, the application will fail to install. To resolve this problem you either need to version your BPEL process at design-time, or refactor the BPEL process template name.
Module versioning is disabled by default, but it can be enabled for every module through the Window > Preferences > Business Integration > Module And Library Versions preferences.
How a versioned module is built
There are two WID artifacts that are relevant to module versioning:
- sca.module – The SCA module name is defined in this file. If module versioning is used, the module name will be renamed during deployment, such that the version number is appended to the module name string during deployment. Note that this only works for applications deployed through serviceDeploy and not Add/Remove projects.
- sca.module.attributes – This is only created when module versioning is enabled. The user-specified module number is set here. As a reminder, understand that the version number is only applied when the module is deployed through serviceDeploy.
The module must be deployed through serviceDeploy in order for the module versioning properties to take effect. During deployment, the version number defined in sca.module.attributes will be used to construct the new module name.
The versioned module is identified using the following pattern:
where X, Y, and Z are the major, minor, and service revision numbers.
For example, assume you have a module, HelloWorldProcess, in your WID workspace. You enable versioning and identify the module as version 1.0.1. If the module is deployed through WID, the resulting EAR would be named HelloWorldProcessApp.ear. However, with versioning enabled the module name becomes HelloWorldProcess_v1_0_1App.ear through serviceDeploy.
How module versioning relates to source control management
WID module versioning is closely related to how modules are managed in source control. Ideally, all versions of a module should be managed in source control so that they can be easily retrieved, modified, or installed on the WPS runtime.
Versioned modules should be stored in the same directory tree as the parent module. We recommend that the initial module version (say, 1.0.0), be stored in the trunk, while subsequent module versions are stored in branches under the trunk.
Alternatively, you can keep the latest or most stable version in the trunk and keep all former module versions in branches. There is no right or wrong answer here, so long as the pattern is consistent. For continuity, we recommend that the first version is stored in the trunk, with all subsequent versions stored as branches. If you need to make a core artifact change that will affect all versions, it can be deployed to the trunk and delegated to the branches as needed. Note that trunks and branches are native to Subversions; other SCM products may use different conventions.
Appendix 1: List of WID artifacts managed in source control
Business Object Maps:
- .map, .xsl, .xsl.smap
- .ifm, <IFMapName>_ifm.mon
General WPS artifacts:
- .component, .module, .modulex, .import, .export, .mon, ibm-deploy.scaj2ee
- .settings folder, MANIFEST.MF, .classpath, .project
Data Types (Business Objects):
- .medflow, .mfc, .mfcex
- .bpel, .bpelex, <ProcName>Artifacts.wsdl, <ProcName>_bpel.mon
Business State Machines: (Note that the underlying .bpel file for the state machine is now generated during application installation, and therefore not managed in SCM.)
- .sacl, .saclex, <BSMName>_sacl.mon
- .tel, .itel (inline task only), <HTName>_tel.mon
- .brg, .brgt, <BRGName>_brg.mon, .ruleset
- .sel, .selt, <SelName>_sel.mon
- .rel, .rol
Integration Solution modules:
Appendix 2: Install the Subversive client plugin
In order to connect to a Subversion server within WID or Eclipse, you need to install the proper client plugin. As we discussed in the document, there are two available plugins that work with Subversion—Subclipse and Subversive. For the examples discussed in this document, we used Subversive, however, Subclipse can also be used.
To install the Subversive client plugin, please visit the Subversive install guide: http://www.eclipse.org/subversive/documentation/gettingStarted/aboutSubversive/install.php
We recommend that you refrain from installing both Subclipse and Subversive on the same WID instance. Since both plugins have similar menu systems and SVN Repository Exploring perspectives, it is often difficult to distinguish one plugin from the other.
Install and configure a Subversion server
To use Subversion you will also need a Subversion runtime server. Most often this will be managed by a system administrator. Since this document focuses strictly on WID client programming, Subversion runtime configuration goes beyond the scope of this document. We used the Collabnet distribution for this document.
For further information on Subversion configuration please consult the excellent and free resource, Version Control with Subversion.
Regardless of what Subversion server or client plugin you use, be sure that both the client and server are at the same version level.
- "Team development with WebSphere Integration Developer and WebSphere Process Server: Developing applications using CVS" (developerWorks, Apr 2006) discusses how to develop WebSphere Process Server applications and manage resources in a team-oriented CVS environment using WebSphere Integration Developer.
- Read the WebSphere Business Process Management 6.1 information center.
- Read the WebSphere Business Process Management 6.2 information center.
- Learn more about creating versioned modules and libraries.
- Read further about Subversive in the user guide.
- Read further about Eclipse Subversive – SVN Team Provider.
- In the SOA and Web services area on developerWorks, get the resources you need to advance your skills.
- Browse the technology bookstore for books on these and other technical topics.
Get products and technologies
- Download IBM product evaluation versions or explore the online trials in the IBM SOA Sandbox and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.