WebSphere 5.1 Integration

From Seapine Labs

Contents 1 Background 2 Installing the WebSphere plug-in 3 Sharing projects 4 Basic Surround SCM tasks 4.1 Adding files 4.2 Getting files 4.3 Checking out files 4.4 Undoing check out 4.5 Checking in files 4.6 Viewing file history 4.7 Viewing file properties 4.8 Comparing file versions 4.9 Replacing file versions 4.10 Renaming files 4.11 Refreshing file status 4.12 Removing files 4.13 Disconnecting a project 5 Advanced Surround SCM tasks 5.1 Configuring Surround SCM preferences 6 Troubleshooting WebSphere and Surround SCM integration

[edit] Background

This article was written using Surround SCM 5.0.4 and WebSphere Studio Application Developer Integration Edition (Windows) version 5.1.1.

[edit] Installing the WebSphere plug-in

1. Start WebSphere.

2. Choose Window > Open Perspective > Install/Update to open the Install/Update Perspective.

NOTE: You may need to first select "Other" in the "Open Perspective" menu to get the "Install/Update" option.

3. Right-click in the Features Update pane and select New > Site Bookmark.

4. Enter a name for the new bookmark and set the URL to http://downloads.seapine.com/pub/eclipse/surround/.

5. Select Eclipse update site.

6. Click Finish.

The site folder you created is displayed in the Feature Updates window.

7. Expand the site folder and select the Surround SCM WebSphere Team plug-in you want to install.

The Preview pane displays information about the Surround SCM plug-in.

8. Click Install Now in the Preview pane to begin the installation.

Follow the on-screen instructions to install the plug-in.

9. Click Yes when you are prompted to restart WebSphere.

The plug-in is installed and ready to use.

Next you need to share the project and set up the integration. For this article, a project whose files have not been added to Surround SCM is used. Also the directory where the project exists on the local machine is not associated as a working directory with any repository in Surround SCM.

[edit] Sharing projects

First, you need to associate an WebSphere project with Surround SCM.

1. Open the WebSphere project.

2. Select the project and choose Team > Share Project.

The Share Project dialog box opens.

3. Select Surround SCM.

Note: If Surround SCM is not displayed in the list of version control systems you did not install the plug-in correctly.

4. Click Finish.

Since the directory where the project is running from is not associated with a repository, a prompt appears indicating this.

5. Click on "Fix". This brings up the Surround SCM repository browser.

You must either select an existing repsitory or click on the "Create Repository" to create a new one. If you select an existing repository, its working directory must be the direcotry where the project is running from. Otherwise, the integration will not work. Selecting an existing repository will not automatically change the working directory, this must be done manually by right clicking on the repository and selecting "Set Working Directory...".

Creating a new repository will automatically assign the project directory as the working directory for the new repository.

Figure below shows the repository browser with the "Set Working Directory..." menu from a repository's context menu.

9 Click OK.

You return to the Surround SCM Login dialog box.

10 Select Always login with this username and password to automatically login to Surround SCM.

11 Click Connect.

You are now logged in and ready to start using Surround SCM. Start with the Basic Surround SCM tasks if the project and its files currently exist in Surround SCM.

[edit] Basic Surround SCM tasks

Please refer to the Surround SCM User Guide for details on all of the options given for all of the Surround SCM tasks.

You can display Surround SCM action messages in WebSphere.

Choose Team > Show Messages. The Surround SCM Messages pane opens. File status information and error messages are displayed in this pane as you work with files.

[edit] Adding files

1. Select the file(s) you want to add to source control. 2. Right-click the file and choose Team > Add.

The Advanced Add Options dialog box opens.

Please refer to the Surround SCM User Guide for details on all of the options given in the Advanced Add Options dialog box.

3. Click OK.

The files are added to Surround SCM.

NOTE: Except for the "(default package)" you can right click on a package, and select "Team">"Add Folder". This will create a subrepository in Surround SCM with the name of the package and all of the files inside the package will be added to this repository.

[edit] Getting files

Get files when you want to view a file but do not need to make any changes.

1. Select the file(s) you want to get. 2. Right-click the file and choose and choose Team > Get. The Advanced Get Options dialog box opens.

Note: You can also select a project and choose Team > Synchronize with Repository to get a copy of all files in the project.

Please refer to the Surround SCM User Guide for details on all of the options given in Advanced Get Options dialog box.

3. Click OK to get the file(s).

Surround SCM copies the files into the working directory.

[edit] Checking out files

Check out files when you want to modify them.

1. Select the file(s) you want to check out. 2. Right-click the file and choose Team > Check Out.

The Advanced Check Out Options dialog box opens.

Please refer to the Surround SCM User Guide for details on all of the options given for the Advanced Check Out Options dialog box.

3. Click OK.

The files are checked out.

[edit] Undoing check out

If you check out and modify a file then decide you do not want to save the changes, you can undo the check out. This discards any changes made to the file and checks it back into the server.

1. Select the file(s).

2. Right-click the file and choose Team > Undo Check Out.

The Advanced Undo Check Out Options dialog box opens.

3. Click OK.

The file is no longer checked out.

[edit] Checking in files

Check in updates the file with changes and makes it available to other users.

1. Select the file(s) you want to check in.

2. Right-click the file and choose Team > Check In.

The Advanced Check in Options dialog box opens.

3. Click OK.

The files are checked in.

[edit] Viewing file history

File history provides a way to view a source file’s history and work with a historical file version.

1. Select the file. 2. Right-click the file and choose Team > History.

The History dialog box opens. This dialog box includes a summary of historic version information.

3. Click Close to close the file history.

You can also select a file and choose Team > Show History in View to open the Surround SCM History pane. You can view historic information and Diff or Get versions of the file.

[edit] Viewing file properties

You can view Surround SCM file properties from WebSphere.

1. Select the file. 2. Right-click the file and choose Team > Properties.

The Properties dialog box opens.

3. Select Surround SCM to view file information.

You can also view Surround SCM project properties from WebSphere. Right-click a Project Node, select Properties, then select Surround SCM.

[edit] Comparing file versions

You can compare a local file with the latest revision in Surround SCM.

1. Right-click the file and choose Team > Compare with > Latest Version.

The compare editor displays any differences between the files.

[edit] Replacing file versions

You can replace a local file with the latest revision from Surround SCM.

1. Right-click the file and choose Team > Replace with > Latest Version.

The local file is replaced with the latest version from Surround SCM.

[edit] Renaming files

1. Select the file you want to rename.

2. Right-click the file and choose Team > Rename.

The Rename File dialog box opens.

3. Enter a New Name.

4. Enter any optional Comments.

5. Click OK.

The file is renamed in Surround SCM.

Note: After the file is renamed in Surround SCM you are prompted to rename the file in the project. Click Yes to rename the file and update your project to point to the new file. If you do not rename the project file you cannot work with it unless you add it to Surround SCM or manually rename it.

[edit] Refreshing file status

If you make changes to a file outside of WebSphere you can refresh the file to update its status. For example, if you check out a file from the Surround SCM client it will not be displayed as checked out in WebSphere unless you refresh the file status.

1. Select the file.

2. Right-click the file and choose Team > Refresh File Status.

The file status is refreshed.

[edit] Removing files

You can remove files from Surround SCM control.

1. Select the file you want to remove.

2. Right-click the file and choose Team > Remove.

The Advanced Remove Options dialog box opens.

3. Select Destroy to delete the selected files from Surround SCM.

4. Enter any optional Comments.

5. Click OK.

The file is removed.

[edit] Disconnecting a project

You can disconnect, or remove, the Surround SCM association from the WebSphere project. After the project is disconnected, you cannot use Surround SCM with the project unless you share the project again.

1. Right-click the project and choose Team > Disconnect.

The project is disconnected from Surround SCM.

[edit] Advanced Surround SCM tasks

[edit] Configuring Surround SCM preferences

You can configure various functional and display options for the Surround SCM integration.

1. Choose Window > Preferences.

The Preferences dialog box opens.

2. Expand the Team node and select Surround SCM.

3. Select a Save modified files before Surround SCM actions option.

This option determines how modified buffers are handled when a Surround SCM action is initiated.

4. Select a When user attempts to edit a read-only file option.

This option determines what happens when a user tries to edit a local, read-only file in the WebSphere editor.

5. Expand the Surround SCM node and select Label Decorations to set decoration options.

Label decorations display additional information about a file or project by modifying its label or icon.

6. Select any Text decoration options

Text decorations decorate nodes with text based on their status in Surround SCM.

􀂄 Select Decorate files to decorate file nodes based on their existence in Surround SCM.

􀂄 Select Include file check out status to decorate file nodes based on check out status.

􀂄 Select Include file’s local status to decorate file nodes based on local status compared to repository status.

7. Select any Icon decoration options.

Icon decorations decorate nodes with Surround SCM icons based on their status in Surround SCM.

These options require extra processing by Surround SCM and may slow down performance.

􀂄 Select Decorate projects to decorate project nodes based on their sharing status.

􀂄 Select Decorate files to decorate file nodes based on their existence in Surround SCM.

􀂄 Select Include file check out status to decorate file nodes based on check out status.

[edit] Troubleshooting WebSphere and Surround SCM integration

This section can help you troubleshoot more common WebSphere/Surround SCM integration problems.

Surround SCM is not included in the Share Project list Surround SCM is not listed displayed in the Share Project list (Team > Share Project).

􀂄 The Surround SCM plug-in is not installed. For more information see Installing the WebSphere plug-in. The plug-in must be installed for each version of WebSphere you are running.

􀂄 You are running an unsupported version of WebSphere. The Surround SCM plug-in currently supports WebSphere 5.1. The integration does not work if you are running another version of WebSphere.

􀂄 The Surround SCM JAR file was not properly installed. Go to <WebSphere install path>/plugins/com.seapine.surroundscm_<version> and make sure the Surround SCM SCCI.JAR file exists in the directory. Re-install the plug-in to resolve this issue.

You can also copy the JAR file from your Surround SCM install directory (typically c:\Program Files\Seapine\Surround SCM) to the WebSphere install directory then restart WebSphere.

􀂄 The Surround SCM library file was not properly installed. Find the Surround SCM SCCI.dll file (.so on Unix/Solaris, .jnilib on Mac OS X). Make sure the directory where the .dll file resides is in your PATH.

􀂄 Multiple copies/versions of the Surround SCM library file are installed on your system.

The plug-in uses the first library file it finds based on the PATH order. Deleting/uninstalling old copies/versions of the Surround SCM library is the recommended way to resolve this issue.

If you do not want to delete the files edit your PATH and make sure the directory reference to the library you want to use comes first in the PATH.

Most Surround SCM menu commands are not enabled

Add is the only enabled Surround SCM menu command in WebSphere. Please check the following for possible causes and resolutions.

􀂄 The WebSphere project is not configured correctly. Make sure the project is configured to point to a valid branch/repository. The branch/repository must also exist in the Surround SCM server you are connecting to.

􀂄 WebSphere cannot connect to the Surround SCM server. Make sure the Surround SCM server is running and that your username/password are valid.

􀂄 The local .MySCMServerInfo file is out of sync. WebSphere uses the .MySCMServerInfo file to determine where to look for files in Surround SCM.

Go to your project files directory and make sure the .MySCMServerInfo file data points to the correct branch/repository. If it is pointing to an incorrect branch/repository, delete it then refresh the project status to regenerate the .MySCMServerInfo file.

Files cannot be added to Surround SCM from WebSphere You cannot add files to Surround SCM from within WebSphere. Please check the following for possible causes and resolutions.

􀂄 The Surround SCM integration is not configured correctly for the WebSphere project. Make sure the project points to a valid branch/repository. Surround SCM may guess where you want to add the files, based on the information in the .MySCMServerInfo file. However, the add cannot be completed if the .MySCMServerInfo file does not exist.

􀂄 Your WebSphere project configuration points to the wrong branch. This can be an issue if you maintain the WebSphere local project files in Surround SCM then branch the repository that contains the project files. The local files point to the old branch, which is where the files are added. Configure WebSphere to point to the correct branch then add the files to Surround SCM.