NetBeans Integration

From Seapine Labs

This article explains how to integrate NetBeans with Surround SCM.

The version of NetBeans used is 6.0.1 and the version of Surround SCM is 2008.1.0.

Please refer to the knowledgebase article on Surround SCM integrations for the updated list of supported versions.

Contents 1 Installing the plug-in 2 Adding the plug-in 3 About the NetBeans Project 4 Adding/Connecting the project 5 Performing File Actions 5.1 Accessing file actions 5.2 Synchronize Project 5.3 Adding files and packages to source control 5.4 Getting files and packages 5.5 Checking out files and packages 5.6 Checking in files and packages 5.7 Undoing check out 5.8 Removing files 5.9 Viewing file differences 5.10 Viewing file history 5.11 Viewing file properties 5.12 Refreshing file status 6 Surround SCM settings 7 About License Usage 8 Troubleshooting NetBeans and Surround SCM integration 8.1 Surround SCM plug in is found in the Surround SCM installation directory 8.2 Surround SCM files are not displayed correctly in NetBeans

[edit] Installing the plug-in

The plug-in is installed optionally with Surround SCM. During the installation an option is given to also install the plug in. Figure 1 below shows the available option in the Windows client installer:

The plug-in is installed to the Surround SCM installation directory.

[edit] Adding the plug-in

Once the plug-in has been installed, it must be added to NetBeans.

1. Open NetBeans.
2. Choose Tools > Plugins.
3. Select the Downloaded tab.
4. Click on the Add Plugins... button.
5. Browse to the Surround SCM installation directory.
6. Select the subdirectory appropriate to the version of NetBeans you are running and select the plugin.
   
   Figure 2 below shows the plugin downloaded:
   
   
   

   

   Figure 2: Plugin Downloaded
7. Click on the Install button.
8. Follow the prompts to install the plugin.
   
   Note: The plugin is unsigned as of the time of this writing, so you will get a message about this.
   
   
9. Select to restart NetBeans to make the plugin available.

[edit] About the NetBeans Project

The project used in this article resides on a workstation and it is called "Jazzy". The project is located in C:\Documents and Settings\<username>\My Documents\NetBeansProjects\Jazzy. It is a new java desktop application.

Figure 3 below illustrates the project and its components in the "Files" explorer:

Figure 4 shows the same project under the Project view:

[edit] Adding/Connecting the project

The steps required to add the project to Surround SCM or connect it with an existing repository and branch in Surround SCM are basically the same.

If the files already exist in Surround SCM, get the files to your workstation and open them using NetBeans.

In any case, you need to have the project open in NetBeans.

1. Open the NetBeans project. Make sure you have the Project window active (Figure 4 above).
2. Right-click on the project and select Surround SCM > Enable Surround SCM
   
   
   

   

   Figure 5:Enable Surround SCM
   
   
   Prompt appears stating that Surround SCM was unable to establish a connection with the project directory.
3. Click on "Fix".
   
   
   

   

   Figure 6: Surround SCM Prompt
   
   
   Note: If the project already exists in Surround SCM and you did a get and opened the project from the Surround SCM working directory you may not get this prompt. Information in the .MySCMServerInfo file will be used to establish the connection to the branch and repository in Surround SCM.
   
   
   The Surround SCM Repository Browser opens.
4. Select the Branch and Repository to add the files to.
5. Click on Create Repository to create a repository for this project.
   
   
   

   

   Figure 7:Repository Browser
   
   
   Surround SCM automatically uses the project name for the repository (editable) and the project folder as the working directory (non-editable).
   
   
   

   

   Figure 8:Create Repository
6. Click OK to accept the repository name and create it.
   
   Note: Make sure the created repository is selected before clicking OK on the repository browser window to close it.

[edit] Performing File Actions

Once the connection between the NetBeans project has been established you can start performing Surround SCM actions on the files.

When invoking most files actions, a Surround SCM dialog will open. Please refer to the Surround SCM user guidefor more information on the options available in the each dialog.

[edit] Accessing file actions

The Surround SCM integration with NetBeans provides the user with three ways to access most file actions.

Surround SCM menu bar

Automatically becomes available and visible after the plugin is installed. Most file specific commands become available once an applicable file is selected.

Surround SCM toolbar

Automatically becomes available after the plugin is installed. May not become automatically visible, however. Select View > Toolbars > Surround SCM to make toolbar visible. Most file specific commands become available once an applicable file is selected.

You can customize the toolbar as well. Select View > Toolbars > Customize. Scroll down to the Surround SCM toolbar.

Surround SCM context menu

Becomes available when an applicable file is selected.

[edit] Synchronize Project

In the example above, the project files are not automatically added to Surround SCM. Use the synchronize project feature to add all the files to Surround SCM. This will only add those files that are recommended to be controlled. As with any other IDE integration, compiled binaries are excluded.

[edit] Adding files and packages to source control

Depending on your settings, when you add a new file to your NetBeans projects you may not be prompted to automatically add it to Surround SCM. You can add the files manually.

1. Select the file to be added.
2. Click on the Add Files button on the Surround SCM toolbar or Add Files from the Surround SCM menu bar or the Surround SCM context menu.

You can add a single file or a selected group of files. You can also add an entire package with all of its contents.

1. Select the package to be added.
2. Click on the Add Folders button on the Surround SCM toolbar or Add Folders from the Surround SCM menu or the Surround SCM context menu.

[edit] Getting files and packages

Get files when you want to view a file but do not need to make any changes. You can get do this at the package level or at the file level.

1. Select the file or package you want to get.
2. Choose Get Files to get files or choose Get Folders to get an entire package.
   
   The Get Files dialog box opens. Click on Advanced to access more options.
   
   
3. Click OK to get the file(s) or package.

[edit] Checking out files and packages

Check out files when you need to modify the files. You can check out a single file, a group of files or an entire package.

1. Select the file(s) or package you want to check out.
2. Select Check Out Files to check out files or Check Out Folders to check out a package.
   
   The Check Out dialog box opens. Click on Advanced to access more options.
   
   
3. Click OK to check out the file(s) or package.

[edit] Checking in files and packages

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) or package you want to check in.
2. Select Check In Files to check in files or Check in Folders to check in a package.
   
   The Check in File(s) dialog box opens. Click on Advanced to access more options.
   
   
3. Click OK to check in the file(s) or package.

[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 or package.
2. Select Undo Check Out Files or Undo Check Out Folders.
   
   The Undo Check Out File dialog box opens. Choose the appropriate option for the local file(s).
   
   
3. Click OK.

The file is no longer checked out.

[edit] Removing files

You have three options when it comes to removing files. You can:

1. Remove a file from both the project and source control.
2. Remove a file from the project only.
3. Remove a file from source control only.

Remove a file from both the project and source control

1. Select the file you want to remove.
2. Right click on the item and select Delete or Refactor > Safe Delete from the context menu.
   
   Once you go through the NetBeans dialogs you will get the Surround SCM Remove Files dialog.
   
   
3. Click OK to remove the files.

The file is now removed from the project and source control.

Remove a file from the project only

1. Select the file you want to remove.
2. Right click on the item and select Delete or Refactor > Safe Delete from the context menu.
   
   Once you go through the NetBeans dialogs you will get the Surround SCM Remove Files dialog.
   
   
3. Click Cancel on the Surround SCM dialog.

The file is now removed from the project but still under source control.

Remove a file from source control only

1. Select the file you want to remove.
2. Select Remove Files.
   
   The Remove File dialog appears.
3. Click OK to remove the file.

The file is now removed from source control but is still exists in the project.

[edit] Viewing file differences

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

1. Select the file you want to diff.
2. Select Differences.
   
   The Surround SCM Differences dialog opens.
   
   
3. Optionally, click on Advanced for more options.
4. Click on Differences to launch the diff utility to view the differences.

Note: The diff utility will be the one specified in the Surround SCM client. The differences dialog will only appear if the local file is different that the latest version on the Surround SCM server. To view differences between the local file (latest version) and another version, go through the History dialog.

[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 you wish to view its history.
2. Select History.
   
   The History dialog box opens. This dialog box includes a summary of historic version information.
   
   
3. Click Close to close the history dialog.

[edit] Viewing file properties

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

1. Select a file.

1. Select Properties.....
   
   The Properties dialog box opens. The General tab includes read-only information about the file. Depending on your security permissions you may also be able to Expand keywords or select a File type. If the file is checked out you can click the Check Out tab to view check out information. This tab includes read-only check out information about the file.
   
   
2. Click OK to close the Properties dialog box.

Use the information in this dialog to see which branch and repository the file/target is associated with.

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

[edit] Refreshing file status

If you make changes to a file or files outside of NetBeans you can refresh the file or entire package 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 NetBeans unless you refresh the file status or until the automatic refresh takes place.

1. Choose a file or package you wish to refresh its status.
2. Right-click on the item and select Refresh Files or Refresh Folders.

Note: Select Refresh All to refresh the status of the entire project.

[edit] Surround SCM settings

Some settings are provided with the Surround SCM plug in to customize the environment to your preferences. Set this settings to enable Text and Icon Annotations. These can help in determining which files are under source control and their status. Keep in mind, however, that using these annotations in large projects can cause NetBeans to slow down.

In NetBeans select Tools > Options. Click on the Miscellaneous and then select the Surround SCM tab.

[edit] About License Usage

Surround SCM floating licenses can timeout and be released after a period of inactivity. Certain actions do not require to re acquire a license, such as viewing a file's properties, history, or refreshing its status. Actions that require modification of the file's content, file's metadata or anything else on the Surround SCM server will require a license.

[edit] Troubleshooting NetBeans and Surround SCM integration

The following information is provided to help you troubleshoot common issues.

[edit] Surround SCM plug in is found in the Surround SCM installation directory

If Surround SCM plug in is not found in the Surround SCM directory, it was not installed. Run the installation again and make sure to choose to install the NetBeans plug in.

[edit] Surround SCM files are not displayed correctly in NetBeans

You added files to Surround SCM but the Surround SCM menu items are not enabled when the files are viewed from NetBeans. Check the following for possible causes and resolutions.

• The NetBeans project is configured incorrectly.

Make sure the project points to a Surround SCM branch/repository that exists on the Surround SCM server you are connecting to. To check this information, select a file, and choose Properties from the Surround SCM menu or toolbar.

• The branch/repository points to an invalid working directory.

Make sure the working directory for the repository associated with the project is the same folder that the NetBeans has opened the project from. You may experience integration problems if you set up the working directory to point to a different location.

• The local .MySCMServerInfo file is out of sync.

NetBeans may not be able to determine where Surround SCM files are located if the .MySCMServerInfo file is out of sync. Go to the directory where the Surround SCM files are located and open the .MySCMServerInfo file with Notepad. Make sure it points to the correct branch/repository. If it does not, delete the file and refresh it from NetBeans to regenerate it with the proper data.