JBuilder Integration

From Seapine Labs

Contents 1 Backgound 2 Installing the Plug In 3 Configuring Surround SCM integration 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 Diffing files 4.9 Renaming files 4.10 Refreshing file status 4.11 Removing files 5 Advanced Surround SCM tasks 5.1 Posting a project to Surround SCM 5.2 Pulling a project from Surround SCM 6 Using the Commit Browser 6.1 Using the Status Browser 7 Troubleshooting JBuilder and Surround SCM integration

[edit] Backgound

As stated in the Surround SCM Third-Party Integrations article, the version of JBuilder that are currently supported are JBuilder 4 through 10, 2005 and 2006.

The integration only works with the Enterprise edition of JBuilder, since this is the only version that supports the MSSCI integration.

This article was written using JBuilder 2006 Enterprise Edition and Surround SCM 5.0.4. The project used in this article is one whose files have not been added to Surround SCm and its project directory is not associated with any repository in Surround SCM (is not a working directory).

[edit] Installing the Plug In

The JBuilder extension is installed during the Surround SCM installation.

NOTE: Stop JBuilder before you install the plug-in.

1. Run the Surround SCM installation program.

2. You will be prompted to select Surround SCM Integration options.

Select Install JBuilder plug-in.

NOTE: The installation looks for registry key to make the JBuilder plug-in available for install. If you do not have this available, then the install did not find the specific registry key it is looking for.

3 Finish the installation.

You are now ready to begin using JBuilder with Surround SCM.

[edit] Configuring Surround SCM integration

First, you need to associate a JBuilder project with Surround SCM.

1 Open the JBuilder project.

2 Choose Team > Select Project VCS.

The Select Project VCS dialog box opens.

3. Select Surround SCM and click OK.

NOTE: If Surround SCM is not displayed in the list of version control systems you did not install the plug-in correctly. Refer to the Troubleshooting JBuilder and Surround SCM integration section of this article.

A prompt is displayed indicating that there is no association between the project directory and a repository in Surround SCM.

4. Click on "Fix".

The repository browser opens.

You must either select an existing repository or create a new repository.

Unless you have a repository already associated with the project folder, it is recommended that a new repository be created.

If you desire to select an existing repository, you should first right click on the desired repository and select "Set Working Directory..." and change the working directory for that repository to be the project folder.

Selecting an existing repository from the repository browser will not change the working directory to the project folder automatically and if the working directory is a directory other than the project folder, the integration will not work properly.

[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.

[edit] Adding files

1. Select the file(s) you want to add to source control.

2. Choose Team > Add or right-click the file and choose Surround SCM > 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.

[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. Choose Team > Get or right-click the file and choose Surround SCM > Get.

The Advanced Get 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 to get the file(s).

Surround SCM copies the files into the working directory.

[edit] Checking out files

Check out files when you need to modify the files.

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

2. Choose Team > Check Out or right-click the file and choose Surround SCM > 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 in 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. Choose Team > Undo Check Out or right-click the file and choose Surround SCM > Undo Check Out.

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

3. Click OK.

The file is no longer checked out.

[edit] Checking in files

Check in updates files with changes, removes the lock on the files, makes changes available to other users, and increments the version number by one.

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

2. Choose Team > Check In or right-click the file and choose Surround SCM > Check In.

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

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. Choose Team > History or right-click the file and choose Surround SCM > History.

The History dialog box opens. This dialog box includes a summary of historic version information. Please refer to the Surround SCM User Guide for details on all of the options given in the History dialog box.

3. Click Close to close the file history.

If a file is open in the JBuilder editor click the History tab to view the history including labels, comments, and author information. You can also compare historic revisions of the file or compare the local file against historic revisions.

[edit] Viewing file properties

File properties include general and check out information about the selected file.

1. Select the file. 2. Choose Team > Properties or right-click the file and choose Surround SCM > Properties.

The Properties dialog box opens. Please refer to the Surround SCM User Guide for details on all of the options given in the Properties dialog box.

5 Click OK to close the Properties dialog box.

NOTE: A Shared tab is also available if the file is shared in Surround SCM.

[edit] Diffing files

You can diff files to compare, accept, or reject differences between two files.

1. Select the file.

2. Choose Team > Differences or right-click the file and choose Surround SCM > Differences.

The differences utility launches. For additional information about the utility refer to the application’s documentation.

[edit] Renaming files

1. Select the file you want to rename. 2. Choose Team > Rename or right-click the file and choose Surround SCM > 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 JBuilder 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 JBuilder unless you refresh the file status.

1. Select the file.

2. Choose Team > Refresh File Status or right-click the file and choose Surround SCM > 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. Choose Team > Remove or right-click the file and choose Surround SCM > 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] Advanced Surround SCM tasks

[edit] Posting a project to Surround SCM

You can add (post) all files in a JBuilder project to Surround SCM at the same time.

1. Select the project.

2. Choose Team > Post Project to SCM or right-click the project and choose Surround SCM > Post Project to SCM.

The Post Project to Surround SCM - Step 1 of 2 dialog box opens.

3. Select any add options.

4. Click Next.

The Post Project to Surround SCM - Step 2 of 2 dialog box opens.

5. Select the files you want to add to Surround SCM. T he file location and the project's Surround SCM configuration determine where files are added to Surround SCM.

6. Click Finish.

The Adding files to Surround SCM dialog box opens.

7. Click Close after the files are added to Surround SCM.

Note: Click Stop if you are adding a large number of files and want to stop the add operation.

[edit] Pulling a project from Surround SCM

Pulling a project from Surround SCM retrieves all files to the project’s working directory. You can get (pull) all files in a JBuilder project at the same time.

1. Select the project. 2. Choose Team > Pull Project from SCM or right-click the project and choose Surround SCM > Pull Project from SCM.

The Pull Project from Surround SCM - Step 1 of 2 dialog box opens.

3. Select any get options.

4. Click Next.

The Pull Project from Surround SCM - Step 2 of 2 dialog box opens.

5. This read-only dialog box displays where the files are being retrieved from.

Files are retrieved to the repository’s working directory.

NOTE: Make sure the working directory and the project’s local directory are the same before proceeding.

6. Click Finish.

The Getting files dialog box opens.

7. Click Close after the files are retrieved from Surround SCM.

[edit] Using the Commit Browser

The Commit Browser allows you to easily see which files are out of sync with Surround SCM and perform actions on those files. It provides status messages and actions for each file in the project.

1. Choose Team > Commit Browser or right-click a project and choose Surround SCM > Commit Browser.

The Commit Browser opens with the Commits tab selected.

The File Include Lists tab allows you to include/exclude specific files or directories from Surround SCM actions.

2. Select a file in the top right pane.

3. Select an Action from the dropdown menu.

The available commands change based on the file’s status.

􀂄 Add – Add the file to Surround SCM

􀂄 Remove from SCM – Remove the file from Surround SCM

􀂄 Remove from Project – Remove the file from the JBuilder project

􀂄 Rename in SCM – Rename the file in Surround SCM

􀂄 Rename in Project – Rename the file in the JBuilder project

􀂄 Get – Retrieve the latest copy of the file from Surround SCM

􀂄 Check Out – Check out the file from Surround SCM

􀂄 Check In – Check in the local copy of the file to Surround SCM

􀂄 Undo Check Out – Undo the check out operation

􀂄 No Action – Skip the file

4. Click a tab to view the selected file’s source.

􀂄 The Workspace Source tab displays the source of the local file. This tab is disabled if the local file does not exist.

􀂄 The Repository Source tab displays the source of the latest revision in Surround SCM. This tab is disabled if the file is not in Surround SCM.

􀂄 The Workspace Diff tab displays the differences between the local file and the latest revision in Surround SCM. This tab is disabled if the local file does not exist or has not changed.

􀂄 The Repository Diff tab displays the differences between the latest revision in Surround SCM and the local file. This tab is disabled if the file does not exist in Surround SCM or has not changed.

􀂄 The Complete Diff tab displays the complete differences between the local file and the latest revision in Surround SCM. This tab is only enabled if both the local and repository files have changed.

5. Optionally enter a Summary comment.

This is the default comment used for each action. Note: Click the Individual Comment tab to enter a comment for the selected file and override the summary comment.

6. Click Commit.

This starts the process of committing all of your selected changes.

7. Click Close when the version control operations are complete.

[edit] Using the Status Browser

The Status Browser is used to check version control status.

1. Choose Team > Status Browser or right-click a project and choose Surround SCM > Status Browser.

The Status Browser opens with the Changes tab selected. The File Include Lists tab allows you to include/exclude specific files or directories.

2. Select a file in the top right pane.

3. Click a tab to view the selected file’s source.

􀂄 The Workspace Source tab displays the source of the local file. This tab is disabled if the local file does not exist.

􀂄 The Repository Source tab displays the source of the latest revision in Surround SCM. This tab is disabled if the file is not in Surround SCM.

􀂄 The Workspace Diff tab displays the differences between the local file and the latest revision in Surround SCM. This tab is disabled if the local file does not exist or has not changed.

􀂄 The Repository Diff tab displays the differences between the latest revision in Surround SCM and the local file. This tab is disabled if the file does not exist in Surround SCM or has not changed.

􀂄 The Complete Diff tab displays the complete differences between the local file and the latest revision in Surround SCM. This tab is only enabled if both the local and repository files have changed.

4. Click Close to close the Status Browser.

[edit] Troubleshooting JBuilder and Surround SCM integration

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

Surround SCM is not included in the Project VCS list

Surround SCM is not listed when you select a project version control system (Team > Select Project VCS). Please check the following for possible causes and resolutions.

􀂄 The Surround SCM plug-in is not installed. For more information see Installing the Plug In section of this article. The plug-in must be installed for each version of JBuilder you are running.

􀂄 You are running an unsupported version of JBuilder. Please refer to the Background section of this article for more information.

􀂄 The Surround SCM JAR file was not properly installed. Go to <JBuilder install directory>/lib/ext 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 JBuilder install directory then restart JBuilder.

􀂄 The Surround SCM library file was not properly installed. Find the Surround SCM SCCI.dll file (.so on Unix/Solaris). 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 JBuilder. Please check the following for possible causes and resolutions.

􀂄 The JBuilder 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.

􀂄 JBuilder 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. JBuilder 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 JBuilder

You cannot add files to Surround SCM from within JBuilder. Please check the following for possible causes and resolutions.

􀂄 The Surround SCM integration is not configured correctly for the JBuilder 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 JBuilder project configuration points to the wrong branch.

This can be an issue if you maintain the JBuilder 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 JBuilder to point to the correct branch then add the files to Surround SCM.