Team development using JBuilder
JBuilder 4 provides team development features that allow you to maintain file revisions with or without an integrated version control system. You can refer to prior backup versions in any edition of JBuilder by using the history view. In JBuilder Enterprise edition, you can use the seamless Concurrent Versions System (CVS) interface or you can integrate another version control system using the OpenTools API. For more information on using the OpenTools API, see the samples
directory of your JBuilder installation and "Developing Open Tools" from the Help Contents page.
Team development means safe development when you use effective version control. Version control prevents accidental loss of information while it enables effective version tracking and revision. The two most important reasons to use version control are:
- It makes it possible for several developers to work on the same set of files without overwriting each others' changes.
- It provides logs and version tracking information so that any user can find when any change was made. If you need to backtrack or refer to old work for any reason, version control makes it feasible.
Using the history view
The history view lets you see prior versions of a file using any available file version type, including multiple backup versions, saved local changes, and the buffer of an active file.
Since the history view is in the content pane, its pages reflect the currently active file. Double-click a closed file in the project pane to open it and make it active. Click an open file's file tab in the content pane to make it active.
There are three pages in the history view. They provide the following features:
- The Contents page, available in all editions of JBuilder, displays current and previous versions of the file.
- The Diff page, available in JBuilder Professional and Enterprise, displays differences between selected versions of the file.
- The Info page, available in JBuilder Enterprise, displays all labels and comments on the active file.
Using version control
Version control systems (VCSs) require a repository and a workspace. The repository keeps the current master version of each file and maintains a record of all the changes that have been made to each file. The workspace keeps only the version of each file that an individual user has most recently updated and modified. Some VCSs let only one user at a time use a file, while others let multiple users use the same file simultaneously.
When revisions are posted from the workspace to the repository, the version control system stores only the changed parts of the master copy. The rest of the file is unchanged. The part that was revised is stored in the repository, along with information about where it came from and when it was changed.
To benefit from version control, users must:
- Retrieve files or groups of files from the repository and post them to their individual workspaces.
- Post the revised files back to the repository when they have finished working on the files.
When users use this process, all changes are available to every developer who has access to that repository.
Definitions
These are words that have specific meanings in the context of version management:
- Workspace
- The area you affect directly, and which you must maintain yourself. When you make changes to a file, you make them and save them in the workspace first.
- Update
- Retrieves changes from the repository and applies them to your workspace.
- Repository
- Where the modules and revision records that you have put into version control are kept. This may be on your local machine or on a remote server.
- Remove
- Removes a file from the repository. The file must first be deleted from your workspace.
- Project
- Refers both to the files and settings that make up one body of work, and to the organizational file used in JBuilder that manages the list of those files and settings.
- Module
- A container for a group of associated files that are stored together in the repository for better file management and user convenience.
- Merge
- CVS and some other systems don't lock files when they are being used. To preserve all changes, these systems use the merge command: it combines changes from the repository with changes in the workspace. Saved workspace changes are not overwritten, and textual conflicts are preserved and flagged to be reconciled by the user. In CVS, an update includes a merge.
- Commit
- Applies changes from your workspace to the repository. You must commit file changes, file additions, and file deletions to the version control system in order to make them available to other users.
- Checkout
- Posts a module from the repository to your workspace. When using CVS, this should only be done the first time. After that, files can be synchronized by updating them.
- Add
- Adds a file to the project module.
Version control in the JBuilder IDE
The following are features of JBuilder Enterprise edition
JBuilder 4, Enterprise edition seamlessly integrates with CVS, a widely used Open Source version control system. JBuilder has a responsive interface that provides context-sensitive access to the most common CVS commands from within the AppBrowser. You can create modules, check out projects, add or remove files, check the CVS status of any file, and commit changes from within the JBuilder interface. You can view and sort file revisions for a whole project at a time.
JBuilder also provides an OpenTools API that allows you to integrate other version control systems into JBuilder. JBuilder includes a sample of version control integration code and a Concept Document describing how version control integration works in the OpenTools API.
The version control sample is in the samples
directory of your JBuilder installation. To see the OpenTools documentation, select Help | Help Topics, look in the Contents page, and select Developing OpenTools.
Note that CVS stores files in modules, while JBuilder organizes projects within project files. While files referred to in a JBuilder project can reside in different directory trees, files in a CVS module must reside in a single tree.
Both JBuilder projects and CVS modules provide the means to track certain functions and maintain the changes you make. Both have fail-safes that help you avoid committing certain basic mistakes. In both cases, these fail-safes require you to follow certain procedures in order to maintain the integrity of what you have created, while allowing you to manipulate it safely.
When you create a CVS module in JBuilder, several things happen:
- JBuilder creates a module to put a project into. If the project uses a
.jpx
project file, it puts the project file into the module. Note that the action of importing a project into CVS doesn't change any file in the directory tree and doesn't transform the tree into a workspace. This is done to preserve the integrity of the original files.
- In order to allow you to work with the repository immediately, the module is checked out into your workspace right after the project file is put into the repository. JBuilder checks the project back out of the module using the name of the original directory, but it changes the name of the original directory itself by adding
.precvs
as a suffix.
This extra step gives you the opportunity to verify that all of the files you wanted to include in the module are present and correct.
Note: If JBuilder does not yet recognize a binary file type in CVS, you must specifically include the file's extension in JBuilder's list of Generic Binary file types. To include it, select Tools|IDE Options and choose the File Types tab. Select the Generic Binary file type, click Add, and enter the new extension. If necessary, you can use the file stored in the .precvs
directory to restore the original binary file.
To learn how to install CVS on your machine and to configure the connection for JBuilder, see "Installing and configuring CVS." See "CVS from the command line" for additional CVS commands that you can use from the command line.
Configuring the CVS connection
Configuring your connection to CVS within JBuilder allows JBuilder to access the repository. See the "Configuring CVS in JBuilder" topic in "Installing and configuring CVS" to learn how to configure this connection.
If you install and configure CVS, all types of file revisions (buffer, backup, and repository) and all version control commands become available.
All of the file-level and project-level commands are available from the Team menu. File-level commands are also available from the right-click menu in the project pane. You can select multiple files in the project pane and then use the right-click menu to perform CVS commands on the group of selected files.
File-level Team menu commands
These commands work on the file that is active in the content pane:
-
CVS Update (Merge) File
CVS automatically performs a merge when you update. Select Team | CVS Update (Merge) "[file name]" to update and merge the active file.
When different changes are made to the same area of text, CVS registers a conflict and will not let the later user commit changes to that file. When JBuilder finds a merge conflict, it displays a conflict message in the message pane and it adds @merge
tags to the conflicting areas of your file:
Note: CVS recognizes only textual conflicts, not logical ones. A textual conflict is a region of overlapping text: different characters written into exactly the same space. A logical conflict is a programmatic event, when incompatible or problematic programming elements are used in the same program. CVS is not designed to handle logical evaluations of programs, only physical assessments of files.
Update before trying to reconcile merge conflicts. Updating a file with conflicts gives JBuilder the chance to flag the conflicts and sets the features that make resolving merge conflicts much easier.
You can reconcile merge conflicts manually or automatically from within the AppBrowser:
- To reconcile a conflict manually,
- Double-click the merge conflict message in the message pane. This will put your cursor in the first merge conflict within the source editor.
- Type and manipulate the text as you normally would until the conflict is resolved.
- Select and delete the
@merge
tags and any extraneous text.
- Save the file and commit the changes.
- To reconcile conflicts automatically,
- Double-click the first merge conflict message in the message pane. This will put your cursor in the first merge conflict within the source editor.
- Right-click in the merge conflict source to display the editor menu.
- Choose to keep either the workspace or the repository version.
- Double-click the next merge conflict message to go to the next conflict, if there is more than one.
Note: Once conflicts are tagged, CVS no longer sees them as conflicts.
Tip: The compiler will tell you if it finds merge conflict tags when it compiles. Therefore, if you postpone resolving a set of conflicts, you can compile and then double-click the compiler's message to find the conflicts in the editor.
When all merge conflicts have been resolved, commit the changes and update normally.
-
CVS Commit File
Commit all changes you want to keep. This keeps the repository current. Select Team | CVS Commit "[filename]" to commit the active file.
-
CVS Add File
Select the file in the content pane and select Team | CVS Add "[filename]" to add the file to the repository. You will be prompted to commit the change.
-
CVS Remove File
Select the file in the content pane and select Team | CVS Remove "[filename]" to remove the file from the repository. You will be prompted to commit the change.
Project-level Team menu commands
These commands work on all the files in the active project:
-
CVS Project Update
This updates all the files in the active project. Select Team | CVS Project Update to update the active project.
-
CVS Project Commit
The CVS Project Commit dialog provides a number of features. You can:
- View the paths and status of project files.
- Sort the list in four ways.
- View local file changes, remote file changes, and all changes.
Select Team | CVS Project Commit to commit all the files in your active project and to access these context-sensitive features:
- List Of Changes
- This page displays the current status of all the files in the active project. It allows you to sort the files in ascending or descending order by clicking the heading of the column you want to sort by: Execution, Status, File Name, or Path. In the Execution column, check a file to commit it when you click OK, and uncheck it to leave it uncommitted.
- Diff
- Select a file in the List Of Changes page then select the Diff page to view all differences between the local and remote revisions of the file.
- Local Diff
- Select a file in the List Of Changes page then select the Local Diff page to view all the local changes to the file that you have made locally but have not yet committed to the repository.
- Remote Diff
- Select a file in the List of Changes page then select the Remote Diff page to view the changes in the file that have been committed to the repository.
The diff pages of the CVS Project Commit dialog are a convenient way to examine merge conflicts. See the "CVS Update (Merge) File" topic to learn how to resolve merge conflicts.
-
CVS Project Create Module
A module must be created to put a project into a new part of the repository. To create a module,
- Make sure you have configured your connection. See "Configuring CVS in JBuilder" in "Installing and Configuring CVS" to learn how to do so.
- Select Team | CVS Project Create Module. If you didn't include the name of a module, JBuilder will prompt you to do so.
When you create a module, files that are in the backup and output paths will be automatically excluded from the repository, but will be preserved in your workspace.
-
CVS Project Checkout
Checking out a project posts the project from the repository to your workspace for the first time. Thereafter, use the CVS Project Update option to keep your files synchronized with the current version in the CVS repository.
JBuilder requires you to use a project to work from, so you check out a project module from an empty project.
To check a project out from a CVS module,
- Select File | New Project and click Finish in the first page of the Project wizard to create an empty project to use.
- Select Team | Configure Version Control to configure your connection. Remember to include the name of the module you want to check out.
- Select Team | CVS Project Check Out and click OK.
JBuilder may rename the project file you checked the project module into:
- When you check out a project module that has a
.jpx
project file, JBuilder keeps the name of that .jpx
project file for the project you checked out and discards the name of the empty project file. JBuilder uses the information in the new .jpx
file to organize the files as you see them in the project pane.
- When you check out a project module that doesn't have a
.jpx
project file, JBuilder keeps the name of the empty project you checked the module into. JBuilder uses its automatic packaging capability to organize the files in the project as you see them in the project pane.
See "Configuring CVS in JBuilder" in "Installing and Configuring CVS" to learn how to configure your connection in JBuilder.
CVS from the command line
These are additional CVS commands which you may find useful. These instructions assume you already have CVS installed and configured on your machine. If not, see "Installing and configuring CVS".
- UNIX path conventions are used unless otherwise specified. For information on documentation conventions, including home directory paths for different platforms, please see "JBuilder documentation conventions."
- The path to the workspace file we will use in our examples will be:
home/thisproject/thisfile.java
- To apply a command to a specific file, type the command, a space, then the filename. Using our examples, it would look like this:
home/thisproject/$ cvs [command] thisfile.java
- To apply a command to several specific files, type the command, then a space, then type each filename with a space between each one. With three files, it would look like this:
home/thisproject/$ cvs [command] thisfile.java thatfile.java theotherfile.java
Note that you can use wildcards when applying CVS commands to files.
- Open your command line interface and change to the working directory. In our example, this would be
home/thisproject
. Then you can execute CVS commands from the command line interface.
Creating a CVS repository
- At the command line, type:
cvs -d :local:[target drive or root]/repo init
- Press Enter. CVS will create the repository for you and return you to the prompt.
Adding a directory
- Put the command line at the target directory level and type:
cvs add [directoryname]
- Commit the changes.
Adding several files to a directory
- Put the command line at the applicable directory level and type:
cvs add thisfile.java thatfile.java theotherfile.java
- Commit the changes.
Removing a directory
- Put the command line at the parent directory level and type:
cvs remove -f directoryname
- Commit the changes.
You can substitute delete
for remove
.
Removing several files from a directory
- Put the command line at the applicable directory level and type:
cvs remove -f thisfile.java thatfile.java theotherfile.java
- Commit the changes.
You can substitute delete
for remove
.
Removing all the files from a directory
- Put the command line at the applicable directory level and type:
cvs remove -f *
- Commit the changes.
You can substitute delete
for remove
.
Getting command help in CVS
- To see a list of CVS commands, put the command line at the working directory level and type:
cvs --help-commands
- To get a list of options that you can apply to CVS commands, type:
cvs --help-options
There are many online references that provide extensive CVS documentation. At the time of publication, these include: