Team Development

Using JBuilder

Borland ®
™
VERSION 7 JBuilder
Borland Software Corporation
100 Enterprise Way, Scotts Valley, CA 95066-3249
www.borland.com
Refer to the file DEPLOY.TXT located in the redist directory of your JBuilder product for a complete list of files that
you can distribute in accordance with the JBuilder License Statement and Limited Warranty.
Borland Software Corporation may have patents and/or pending patent applications covering subject matter in this
document. Please refer to the product CD or the About dialog box for the list of applicable patents. The furnishing of
this document does not give you any license to these patents.
COPYRIGHT © 1997–2002 Borland Software Corporation. All rights reserved. All Borland brand and product names
are trademarks or registered trademarks of Borland Software Corporation in the United States and other countries.
All other marks are the property of their respective owners.
For third-party conditions and disclaimers, see the Release Notes on your JBuilder product CD.
Printed in the U.S.A.
JBE0070WW21001teamdev 4E4R0402
0203040506-9 8 7 6 5 4 3 2 1
PDF
 Contents
Chapter 1 Chapter 4
Welcome to team development Working on a new project in CVS 4-1
using JBuilder 1-1 Placing a new project into CVS . . . . . . . . . . 4-1
Using version control systems . . . . . . . . . . 1-2 Checking in a project for the first time . . . . 4-2
Documentation conventions . . . . . . . . . . . 1-2 Creating a local repository . . . . . . . . . . . . . 4-4
Note to Macintosh users . . . . . . . . . . . . 1-4
Contacting Borland developer support . . . . . 1-5 Chapter 5
Online resources . . . . . . . . . . . . . . . . 1-5 Programmer’s guide to the
World Wide Web . . . . . . . . . . . . . . . . 1-5 CVS integration 5-1
Borland newsgroups . . . . . . . . . . . . . . 1-6 Guide to the CVS integration . . . . . . . . . . . 5-1
Usenet newsgroups . . . . . . . . . . . . . . 1-6 Using CVS as your version control
Reporting bugs . . . . . . . . . . . . . . . . . 1-6 system. . . . . . . . . . . . . . . . . . . . . . 5-2
Selecting CVS. . . . . . . . . . . . . . . . . 5-2
Chapter 2 Configuring the repository
CVS in JBuilder 2-1 connection . . . . . . . . . . . . . . . . . 5-2
CVS glossary . . . . . . . . . . . . . . . . . . . . 2-2 Creating a local repository . . . . . . . . . 5-3
Getting material out of the repository. . . . . 5-3
Chapter 3 Pulling a project . . . . . . . . . . . . . . . 5-3
Working on an existing project Pulling a project file . . . . . . . . . . . . . 5-4
Checking out files . . . . . . . . . . . . . . 5-4
in CVS 3-1 Updating files . . . . . . . . . . . . . . . . 5-4
Checking out an existing project . . . . . . . . . 3-2
Removing files . . . . . . . . . . . . . . . . 5-5
Posting changes . . . . . . . . . . . . . . . . . . 3-4
Getting material into the repository . . . . . . 5-5
Changes in a single file . . . . . . . . . . . . 3-4
Checking in a project . . . . . . . . . . . . 5-5
Changes in the entire project . . . . . . . . . 3-5
Adding new files. . . . . . . . . . . . . . . 5-6
Browsing the project’s CVS status . . . . 3-5
Committing changes . . . . . . . . . . . . 5-6
Choosing files to include. . . . . . . . . . 3-6
Posting a project file . . . . . . . . . . . . . 5-6
Committing the project . . . . . . . . . . . . 3-7
Managing the module . . . . . . . . . . . . . 5-7
Action options. . . . . . . . . . . . . . . . 3-8
Version labeling . . . . . . . . . . . . . . . 5-7
Summary comments . . . . . . . . . . . . 3-9
Using watches . . . . . . . . . . . . . . . . 5-7
Synchronizing with changes in the repository . 3-10
Using the CVS Helper utility . . . . . . . . . . . 5-7
Updating a single file . . . . . . . . . . . . . 3-10
Technical information . . . . . . . . . . . . . . 5-8
Reconciling a merge conflict . . . . . . . . 3-11
Security information . . . . . . . . . . . . . . 5-9
Updating the project . . . . . . . . . . . . . . 3-12
CVS reference . . . . . . . . . . . . . . . . . . . . 5-9
Managing the project file . . . . . . . . . . . 3-13
Handling binary files in CVS. . . . . . . . . . 5-9
Synchronizing the project file . . . . . . . 3-13
Checking and setting user environment
Adding files . . . . . . . . . . . . . . . . . . . . 3-13
variables . . . . . . . . . . . . . . . . . . . . 5-9
Removing files . . . . . . . . . . . . . . . . . . . 3-14
Linux and Solaris . . . . . . . . . . . . . 5-10
Creating a version label . . . . . . . . . . . . . . 3-15
Windows XP . . . . . . . . . . . . . . . . 5-10
Managing file status in CVS . . . . . . . . . . . 3-15
Windows NT . . . . . . . . . . . . . . . . 5-10
Checking a file’s CVS status. . . . . . . . . . 3-15
Windows 2000 . . . . . . . . . . . . . . . 5-11
File access notification . . . . . . . . . . . . . 3-15
CVS Watches . . . . . . . . . . . . . . . . 3-16

i
Chapter 6 Using the Select Empty Target
Directory step . . . . . . . . . . . . . . . . . 9-3
Visual SourceSafe in JBuilder 6-1 Checking out files . . . . . . . . . . . . . . . . . . 9-4
Configuring the connection. . . . . . . . . . . . 6-1
Undoing a checkout . . . . . . . . . . . . . . . 9-4
Chapter 7 Checking in files . . . . . . . . . . . . . . . . . . 9-4
Checking the project file in or out. . . . . . . . . 9-4
Working on an existing project in VSS7-1 Adding and removing files . . . . . . . . . . . . 9-5
Pulling an existing project . . . . . . . . . . . . 7-1 Adding files . . . . . . . . . . . . . . . . . . . 9-5
Selecting the database directory . . . . . . . 7-2 Removing files . . . . . . . . . . . . . . . . . . 9-5
Entering security information. . . . . . . . . 7-3 Checking in the entire project . . . . . . . . . . . 9-6
Selecting a project . . . . . . . . . . . . . . . 7-3 Using the Status Browser . . . . . . . . . . . . 9-6
Choosing a target directory . . . . . . . . . . 7-3 Using the Commit Browser . . . . . . . . . . 9-6
Checking out files . . . . . . . . . . . . . . . . . 7-3 Version labeling . . . . . . . . . . . . . . . . . . . 9-7
Undoing a checkout . . . . . . . . . . . . . . 7-4 Checking in a new project . . . . . . . . . . . . . 9-7
Checking out a project file. . . . . . . . . . . 7-5 Choosing what to include in the checkin . . . 9-7
Checking in files . . . . . . . . . . . . . . . . . . 7-6 Choosing which files to check out . . . . . . . 9-7
Checking in the project file . . . . . . . . . . 7-6 Setting the project root in the database . . . . 9-8
Adding and removing files . . . . . . . . . . . . 7-7
Adding files . . . . . . . . . . . . . . . . . . . 7-7 Chapter 10
Removing files . . . . . . . . . . . . . . . . . 7-8
Checking in the entire project . . . . . . . . . . 7-9
Rational ClearCase in JBuilder 10-1
Selecting ClearCase as your version
Browsing the project’s status . . . . . . . . . 7-9
control system . . . . . . . . . . . . . . . . . . 10-2
Choosing files to include. . . . . . . . . . 7-10
Viewing the connection . . . . . . . . . . . . 10-2
Checking in the project . . . . . . . . . . . . 7-11
Action options. . . . . . . . . . . . . . . . 7-12
Summary comments . . . . . . . . . . . . 7-14
Chapter 11
Version labeling a project . . . . . . . . . . . . . 7-14 Working on an existing project in
ClearCase 11-1
Chapter 8 Pulling an existing project (mounting
Working on a new project in VSS 8-1 a VOB) . . . . . . . . . . . . . . . . . . . . . . 11-1
Placing a new project into Visual SourceSafe . . 8-1 Using the Pull Project From ClearCase
wizard. . . . . . . . . . . . . . . . . . . . . 11-2
Chapter 9 Checking out a file . . . . . . . . . . . . . . . . 11-2
Programmer’s guide to the Undoing a checkout . . . . . . . . . . . . . . 11-3
Posting changes to a single file or set of files . 11-3
VSS integration 9-1 Merging differences between versions . . . 11-4
Configuring the connection. . . . . . . . . . . . 9-1 Adding a new file . . . . . . . . . . . . . . . . . 11-5
Selecting VSS . . . . . . . . . . . . . . . . . . 9-1 Version labeling (tagging) . . . . . . . . . . . . 11-5
Configuring the database connection . . . . 9-1
Runtime location and performance . . . . 9-2 Chapter 12
Pulling an existing project . . . . . . . . . . . . 9-2
Using the Select Visual SourceSafe
Working on a new project in
Database Directory step . . . . . . . . . . . 9-2 ClearCase 12-1
Using the Enter Username And Placing a new project into ClearCase . . . . . . 12-1
Password step. . . . . . . . . . . . . . . . . 9-3 Working with views . . . . . . . . . . . . . . . 12-2
Using the Select Visual SourceSafe Adding new views . . . . . . . . . . . . . . 12-2
Project step . . . . . . . . . . . . . . . . . . 9-3 Editing existing views . . . . . . . . . . . . 12-3

ii
Chapter 13
Version control reference 13-1
General revision management resources . . . . 13-2
Resources for supported tools . . . . . . . . . . 13-2
CVS . . . . . . . . . . . . . . . . . . . . . . . 13-2
Rational ClearCase . . . . . . . . . . . . . . . 13-2
Visual SourceSafe. . . . . . . . . . . . . . . . 13-2

Index I-1

iii
iv
 Chapter

Welcome to team development

Chapter1
1
using JBuilder
These are features of Team development is safe development when you use effective version
JBuilder SE and control. Version control prevents accidental loss of information while it
Enterprise 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 other’s changes.
• It provides logs and version tracking information so that anyone with
suitable access can find when any change was made. If you need to
backtrack or refer to prior versions of files for any reason, version
control makes it feasible.
Many version control systems also provide features for branching (which
allows you to maintain multiple development tracks for the same
product) and version labeling (which allows you to take a snapshot of the
entire file set at any stage of development.)
JBuilder provides revision handling features in the history view that allow
you to maintain file revisions with or without an integrated version
control system. JBuilder SE and Enterprise editions provide interfaces
with Concurrent Versions System (CVS), Visual SourceSafe, and Rational
ClearCase that allow you to perform many version control tasks right
from JBuilder. JBuilder’s integration with these version control systems is
completely context-sensitive. JBuilder’s Version Control OpenTool and
open, extensible architecture allow you to integrate other version control
systems as well.

Welcome to team development using JBuilder 1-1

Using version control systems

Using version control systems

Version control systems (VCSs) provide ways of storing a complete record
of file revisions while allowing developers to continue revising.
Generically, we can call the storage area the repository and the working
area the workspace. Different VCSs are structured differently and each VCS
uses different terminology, but for general conceptual information the
terms “repository” and “workspace” will be used as defined here.
Normally, the repository stores the current master version of each file and
maintains a record of all the changes that have been made to each file. The
workspace has 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 (pessimistic or locking model), some let multiple users use the same
file simultaneously (optimistic or concurrent development model), and
some blend these approaches.
When revisions are posted from the workspace to the repository, the
version control system stores 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 place them in
their individual workspaces.
• Synchronize their local versions of the files with the repository
versions.
• Place the revisions back in the repository when they have finished
working on the files.
When developers use this process, all changes are available to every
developer who has access to that repository.

Documentation conventions
The Borland documentation for JBuilder uses the typefaces and symbols
described in the table below to indicate special text.

1-2 Team Development Using JBuilder

 Documentation conventions

There are special considerations on the Macintosh platform. Please see

“Note to Macintosh users” on page 1-4 for more information.

Table 1.1 Typeface and symbol conventions

Typeface Meaning
Monospace type Monospaced type represents the following:
• text as it appears onscreen
• anything you must type, such as “Enter Hello World in the
Title field of the Application wizard.”
• file names
• path names
• directory and folder names
• commands, such as SET PATH, CLASSPATH
• Java code
• Java data types, such as boolean, int, and long.
• Java identifiers, such as names of variables, classes, interfaces,
components, properties, methods, and events
• package names
• argument names
• field names
• Java keywords, such as void and static
Bold Bold is used for java tools, bmj (Borland Make for Java), bcj
(Borland Compiler for Java), and compiler options. For example:
javac, bmj, -classpath.
Italics Italicized words are used for new terms being defined, for book
titles, and occasionally for emphasis.
Keycaps This typeface indicates a key on your keyboard, such as “Press
Esc to exit a menu.”
[] Square brackets in text or syntax listings enclose optional items.
Do not type the brackets.
<> Angle brackets in text or syntax listings indicate a variable string;
type in a string appropriate for your code. Do not type the angle
brackets.
Angle brackets are also used in HTML tags.
Additionally, angle brackets are used for JBuilder and JDK
directories. For example, <jbuilder> is a placeholder for the
current version of the JBuilder directory, such as jbuilder7, and
<.jbuilder> represents the current JBuilder directory for storing
JBuilder settings, such as .jbuilder7. Also, <jdk> is used as a
placeholder for the current JDK directory.
... In code examples, an ellipsis indicates code that is missing from
the example. On a button, an ellipsis indicates that the button
links to a selection dialog box.

Welcome to team development using JBuilder 1-3

Documentation conventions

JBuilder is available on multiple platforms. See the table below for a

description of platforms and directory conventions used in the
documentation.

Table 1.2 Platform conventions and directories

Item Meaning
Paths All paths in the documentation are indicated with a forward
slash (/).
For Windows platforms, use a backslash (\).
Home directory The location of the home directory varies by platform and is
indicated with a placeholder, <home>.
• For UNIX and Linux, the home directory can vary. For
example, it could be /user/<username> or /home/<username>
• For Windows 95/98, the home directory is C:\Windows
• For Windows NT, the home directory is C:\Winnt\
Profiles\<username>
• For Windows 2000, the home directory is C:\Documents
and Settings\<username>
<jbuilder> directory The <jbuilder> directory contains the JBuilder installation,
including program files, documentation, libraries, JDK,
samples, and other files. This directory is named after the
current version of JBuilder, such as jbuilder7.
<.jbuilder> directory The <.jbuilder> directory, where JBuilder settings are stored,
is located in the home directory. This directory is named
after the current version of JBuilder, such as .jbuilder7.
jbproject directory The jbproject directory, which contains project, class,
source, backup, and other files, is located in the home
directory. JBuilder saves files to this default path.
<jdk> directory The <jdk> directory represents the current Java Development
Kit, for example, jbuilder7/jdk1.3/ would be represented in
the documentation as <jbuilder>/<jdk>/.
Screen shots Screen shots reflect the Metal Look & Feel on various
platforms.

Note to Macintosh users

JBuilder is designed to support Macintosh OS X so seamlessly that
JBuilder will have the look and feel of a native application. The Macintosh
platform has conventions of appearance and style that vary from
JBuilder’s own; where that happens, JBuilder supports the Mac look and
feel. This means that there are some variations between what JBuilder
looks like on the Mac and how it is presented in the documentation. For
instance, this documentation uses the word “directory” where Mac uses
the word “folder.” For further information on Macintosh OS X paths,
terminology, and UI conventions, please consult the documentation that
comes with your OS X installation.

1-4 Team Development Using JBuilder

 Contacting Borland developer support

Contacting Borland developer support

Borland offers a variety of support options. These include free services on
the Internet, where you can search our extensive information base and
connect with other users of Borland products. In addition, you can choose
from several categories of support, ranging from support on installation of
the Borland product to fee-based consultant-level support and extensive
assistance.
For more information about Borland’s developer support services, see our
web site at http://www.borland.com/devsupport/, call Borland Assist at
(800) 523-7070, or contact our Sales Department at (831) 431-1064.
When contacting support, be prepared to provide complete information
about your environment, the version of the product you are using, and a
detailed description of the problem.
For support on third-party tools or documentation, contact the vendor of
the tool.

Online resources
You can get information from any of these online sources:

World Wide Web http://www.borland.com/

FTP ftp.borland.com
Technical documents available by anonymous ftp.
Listserv To subscribe to electronic newsletters, use the
online form at:
http://www.borland.com/contact/listserv.html
or, for Borland’s international listserver,
http://www.borland.com/contact/intlist.html

World Wide Web

Check www.borland.com regularly. The JBuilder Product Team will post
white papers, competitive analyses, answers to frequently asked
questions, sample applications, updated software, updated
documentation, and information about new and existing products.
You may want to check these URLs in particular:
• http://www.borland.com/jbuilder/ (updated software and other files)
• http://www.borland.com/techpubs/jbuilder/ (updated
documentation and other files)

Welcome to team development using JBuilder 1-5

Contacting Borland developer support

• http://community.borland.com/ (contains our web-based news

magazine for developers)

Borland newsgroups
You can register JBuilder and participate in many threaded discussion
groups devoted to JBuilder.
You can find user-supported newsgroups for JBuilder and other Borland
products at http://www.borland.com/newsgroups/

Usenet newsgroups
The following Usenet groups are devoted to Java and related
programming issues:
• news:comp.lang.java.advocacy
• news:comp.lang.java.announce
• news:comp.lang.java.beans
• news:comp.lang.java.databases
• news:comp.lang.java.gui
• news:comp.lang.java.help
• news:comp.lang.java.machine
• news:comp.lang.java.programmer
• news:comp.lang.java.security
• news:comp.lang.java.softwaretools
Note These newsgroups are maintained by users and are not official Borland
sites.

Reporting bugs
If you find what you think may be a bug in the software, please report it in
the Support Programs page at http://www.borland.com/devsupport/
namerica/. Click the “Reporting Defects” link to bring up the Entry Form.
When you report a bug, please include all the steps needed to reproduce
the bug, including any special environmental settings you used and other
programs you were using with JBuilder. Please be specific about the
expected behavior versus what actually happened.
If you have comments (compliments, suggestions, or issues) with the
JBuilder documentation, you may email [email protected]. This is for
documentation issues only. Please note that you must address support
issues to developer support.
JBuilder is made by developers for developers. We really value your
input, because it helps us to improve our product.

1-6 Team Development Using JBuilder

 Chapter

CVS in JBuilder
Chapter2
2
This is a feature of JBuilder SE and Enterprise editions seamlessly integrate CVS, a widely
JBuilder SE and used Open Source version control system. JBuilder has a responsive
Enterprise. interface that provides context-sensitive access to the most common CVS
commands from within the AppBrowser.
On supported platforms, CVS is automatically installed into the
<jbuilder>/bin directory when you install JBuilder.
You can create modules, check out projects, add or remove files, check the
CVS status of any file or project, commit changes from within the JBuilder
interface, use watches and CVS edit, create version labels and access
branches, all from within the JBuilder IDE. If you’re unsure what these or
other CVS terms mean, please check the glossary below.
CVS categorizes all files as either text-based or binary. Code is normally
treated as text-based, and image files and user-defined binary types are
treated as binary. For more information on how CVS handles binary files,
please see “Handling binary files in CVS” on page 5-9.
Note CVS configuration information is automatically requested when you
check out or check in a project.
When a project is in CVS, select Team|Configure CVS to view its
connection configuration. Once the connection has been established, this
display becomes read-only. This configuration can also be viewed in your
project file settings.

CVS in JBuilder 2-1

CVS glossary

CVS glossary
These words have specific meanings in CVS:

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 Can have any of three meanings: the files and settings
that make up one body of work, the organizational file
used in JBuilder that manages the list of those files and
settings, or as a synonym for “module”.
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 necessarily 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 Pulls 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 module.

2-2 Team Development Using JBuilder

 Chapter

Working on an existing
Chapter3
3
project in CVS
A JBuilder project must be under CVS control before CVS menu
commands become available. This means you must either pull a project
from CVS or place an existing project into CVS.
You’ll access CVS most often by pulling an existing project from the CVS
repository.
In order to work on an existing project, it must be checked out into your
workspace first. Checking out a project into your workspace in JBuilder
does three important things:
• Mirrors the current repository version of the project into your
workspace, so that you have the most current version at the time of
checkout.
• Notifies CVS that you have it. This engages version control
management mechanisms, so that records of changes can be kept, new
versions can be generated as necessary, and conflicts can be flagged.
• Notifies JBuilder that you’re using the project under version control.
This engages JBuilder’s support features, activating the Team
development features, allowing you to use the history pane to greater
effect, and providing conflict management assistance.
Note When working under version control, it’s important to use it
appropriately. Consistent version control is easy version control, but, if
used irregularly or inconsistently, it becomes more difficult to use.

Working on an existing project in CVS 3-1

Checking out an existing project

Checking out an existing project

The quickest way to check out a project that’s already in the repository is
to use the Pull Project From CVS wizard available in the object gallery.
1 Select File|New. The object gallery appears.
2 Choose the Project tab.
3 Select Pull Project From CVS.
4 Either click OK, double-click the Pull Project From CVS icon, or press
Enter. The Pull Project From CVS wizard appears.
5 Type or select an empty target directory.
JBuilder offers an empty untitled directory by default. Change the
directory name to something meaningful, as long as that directory
either doesn’t exist yet or is completely empty.
6 Click Next to proceed to Step 2:

Under Connection Type, Local connects to a local repository, PServer

connects to a repository on a server that’s normally
password-protected, and Ext connects to a repository on a secure
server.
The CVSROOT path appears at the bottom of the wizard. It reflects the
information entered in this step. If you’re unsure what you should
enter and you already have a CVS account on an existing server, see
your CVS administrator.
Note JBuilder maintains drop-down lists of prior connections for you to
choose from. These lists are empty when you use the wizard for the
first time, but after that you can select previous entries from the lists
instead of typing them in.

3-2 Team Development Using JBuilder

 Checking out an existing project

7 Make your entries and click Next to proceed to Step 3:

If you see a CVS Helper notation at the bottom of the wizard, it refers to
an administrative tool that your CVS administrator may implement on
the server. It doesn’t affect your use of the CVS integration in any way
and won’t show up in the IDE.
8 Type in or choose the repository path. If you’re using a local repository,
you can click the ellipsis button to browse to it instead.
9 Type in or choose a module name. If you want to work on a branch
other than the main branch, type in or choose the branch from those
that are available in the drop-down list.
10 Click Finish to complete the wizard. The Checking Out CVS Project
dialog box appears and reports on the progress of the checkout.
11 Click OK to close the wizard.
This is the second way to initiate this wizard:
1 Open or create a project that’s not under version control.
Note An existing project will not be overwritten. Opening a project simply
gives you access to the Team menu.
2 Select Team|Select Project VCS. The Select Project VCS dialog box
appears.

Working on an existing project in CVS 3-3

Posting changes

3 Select CVS:

4 Click OK or press Enter to close the dialog.

5 Select Team|Pull Project From CVS.
The Pull Project From CVS wizard appears.

Posting changes
When you post changes, you apply your altered file to the repository. The
repository records where the changes were made and generates a new
master copy of the file. When other users retrieve that file from the
repository, they will get the version that includes the changes you made.
In CVS, posting changes is called either “committing” or “checking in”
changes; these terms are used interchangeably.

Changes in a single file

For the active file, use the Team menu:
1 Select Team|Commit “<filename>”.
For any file available in the project pane, use the context menu:
1 Right-click the file in the project pane.
2 Select CVS|Commit “<filename>”.
This command checks in a single changed file to the repository. This keeps
the repository version of the file current and maintains a good revision
history.
Update before you commit. This significantly reduces the risk of merge
conflicts, and, where they do occur, engages JBuilder’s merge assistance
mechanisms.

3-4 Team Development Using JBuilder

 Posting changes

Changes in the entire project

It’s not always feasible to commit changes to each file as you go. You may
need to test files to make sure your changes work or you might even
forget once in awhile. You may not exactly remember which ones you
changed and how. JBuilder lets you browse the status of all the files in
your project using the Status Browser, and commit as many files as
necessary using the Commit Browser.
Note The current project file is maintained separately.

Browsing the project’s CVS status

Select Team|Status Browser to see all the files in your project and the CVS
status of each one. It has two pages: the Changes page and the File Include
Lists page.
In the Changes page, the project’s directory tree is displayed in the
left-hand pane and the list of files in the right. Select the Full List node to
view a list of all the files in the project. Select a directory node to see a list
of the files in that directory.
The version control status of each file is noted in the Status column of the
list.
Select a file in the file list. The tabbed pane below the file list allows you to
view the source code of the selected file in any way that’s pertinent. If you
choose a file that has been changed locally, then the Workspace Source,
Repository Source, and Workspace Diff tabs become available. If you
choose a file that has been changed on the repository, then the Workspace
Source, Repository Source, Repository Diff, and Complete Diff tabs
become available.

Table 3.1 Changes page source views

Source view Contents
Workspace Source This file’s source code from the current workspace version.
Repository Source This file’s source code from the current repository version.
Workspace Diff This file’s most recent changes in your workspace.
Repository Diff This file’s most recent changes in the repository.
Complete Diff Differences between the current version of this file in the
repository and the current version in your workspace.

Working on an existing project in CVS 3-5

Posting changes

Choosing files to include

The File Include Lists determine which files are under version control.
There are two pages: Team Include List and Personal Include List.

The Team Include List files are tracked by the <projectname>.jpx file. The
information you enter here is stored in that file as well, because this is a
team-wide project setting: the files that are checked here are the files that
everyone needs to be able to use.
The bak files and the <projectname>.local.jpx file are normally excluded
(unchecked). Check your company’s policy about what files should be
included and what should be excluded from a team project checkin.
Caution The shared .jpx file must be included in order to maintain CVS in
JBuilder.
The Personal Include List files are tracked by the <projectname>.local.jpx
file (where the information in this table is stored.) This list is entirely for
your convenience. Since you won’t necessarily be working on every file in
the project, you don’t necessarily want to look at them whenever you do a

3-6 Team Development Using JBuilder

 Posting changes

checkin. This simple chart illustrates the concept of available files as

compared to the files needed by an individual developer.

The Personal Include List page lets you keep in view only the files that
you need. The rest stay hidden until you want to see them again.

Committing the project

The Commit Browser provides meaningful status messages and context
sensitive default actions. It also provides alternative action options in the
form of combo boxes in the Action column. Click a file’s cell in the Action
column to view alternative actions. These vary depending on the status of
the file. The default option varies depending on how the file achieved that
status.
The Commit Browser also allows you to determine which files will be
included under CVS control and which files will remain strictly local. It
has three pages: Commits, Summary Comment, and File Include Lists. It
opens to the Commits page by default.

Working on an existing project in CVS 3-7

Posting changes

An expandable directory tree view is in the left-hand pane and the list of
files is in the right. Use them like this:
• Select the Full List node in the directory tree to view a list of all the files
in the project.
• Expand the module or parent directories in the directory tree to see the
directories inside.
• Select a directory node in the directory tree to see the files in that
directory displayed in the file list.
• Select a file from the file list to see its comment in the tabbed pane
below.
The tabbed pane also displays the selected file’s source in five ways:

Tab Display
Workspace Source This file’s source code from the current workspace version.
Repository Source This file’s source code from the latest repository version.
Workspace Diff This file’s most recent changes in your workspace.
Repository Diff This file’s most recent changes in the repository.
Complete Diff The differences between the current local version of this file
and the latest repository version.

Action options
JBuilder chooses default options to place in the Action column based on
the file’s status as reflected in the Status column. For changes made within
JBuilder, the default actions are chosen not only according to the file’s
status but how it reached that status. For instance, if a file isn’t in the
workspace, it might be because it was removed from the project or
because it has not yet been checked out. JBuilder senses the reason that it’s
not in the workspace and chooses the most likely option to list as the
default: Remove From Repository or Check Out. Additions and removals
made from this browser are automatically committed.
If you want to commit some but not all changed files in the project, select
No Action as the option for the files you don’t want to commit. You can
also auto-select No Action for all of the files in a directory by right-clicking
the directory in the node tree view and selecting Perform No Action For
All In Directory from the context menu.
For the default option to be most intelligent, file additions and deletions
must be performed from within JBuilder. Then JBuilder can perceive the
reason for the changed status of a file and select the most appropriate
default option.

3-8 Team Development Using JBuilder

 Posting changes

Options include:

Commit Commit the change to the CVS repository.

Add Add and commit this file so it’s stored in the repository.
Delete This file is not in the repository; this removes it from your
workspace.
Get This file has been added to the repository; this checks it out
to your workspace.
Revert Update the workspace with the latest repository version of
this file, discarding all changes made since your last
update.
Update This file has changed in the repository; this updates it in
your workspace.
No Action This changed file will not be touched by a CVS operation of
any kind. It will be exactly as you left it before you invoked
the Commit Browser.

If committing a file from the Commit Browser creates a merge conflict,

JBuilder inserts @merge tags into the source. This engages JBuilder’s merge
conflict handling mechanisms. For more information on these, see
“Updating a single file” on page 3-10.
The table below demonstrates a few status notations and associated
options.

Condition Listed status Default option Alternative options

File changed in Changed In Commit to Repository • Revert
the workspace Workspace • No Action
File added to Not In Add to Repository • Delete Locally
CVS Repository • No Action
File deleted Not In If removed from within • Revert
from CVS Workspace JBuilder: • No Action
Remove From
Repository
If removed from outside
JBuilder:
Get From Repository

Summary comments
The Use Summary Comment checkbox at the bottom of the Individual
Comment pane allows you to attach the same summary comment to
multiple files. This summary comment will be maintained along with the
individual comment written for each file. Select the Summary Comment
tab to write a summary comment.

Working on an existing project in CVS 3-9

Synchronizing with changes in the repository

The Summary Comment page offers the option of placing the summary
comment before the individual comments applied to individual files. This
option is on by default. If you deselect this option and select the Use
Summary Comment option on the Commits page, then the summary
comment will be applied to files that don’t have individual comments.

Synchronizing with changes in the repository

Updating pulls the current repository version into your workspace. You
can update individual files or the entire project at once.
Note Project files are updated separately.

Updating a single file

When you update your workspace with changes from the repository, CVS
automatically merges repository changes with your changes. This reduces
merge conflicts when you commit your changes back to the repository.
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, adds @merge tags to the conflicting areas of your file, and
places an Undo button in the gutter. Click the Undo button to choose
which version to keep. By default, the repository version of the diff is
highlighted in green and the workspace version of the diff is highlighted
in red.
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.
CVS is designed to handle text-based files. It treats all other files as binary.
CVS can update or commit binary files, but doesn’t merge them. See
“Handling binary files in CVS” on page 5-9.
Update before committing. It reduces merge conflicts. JBuilder prompts
you to update before committing when necessary. Updating a file with
conflicts gives JBuilder the chance to flag the conflicts and it sets the
features that make finding and resolving merge conflicts much easier.

3-10 Team Development Using JBuilder

 Synchronizing with changes in the repository

Reconciling a merge conflict

JBuilder helps avoid merge conflicts by requiring you to update when
necessary before committing changes. If merge conflicts happen
nonetheless, JBuilder flags them in several ways:
• Notes them in the message pane. Click a merge conflict warning within
the message pane to place your cursor automatically in the merge
conflict within the editor.
• Inserts @merge <source of conflict, either workspace or repository>
Javadoc tags into the source just above the conflict block. This tag is
caught by the compiler, so if you postpone resolving conflicts you can
find them again later by compiling the file and using the message pane.
• Inserts a gutter button next to the @merge tag which provides a way of
resolving the conflict automatically.
• Highlights the line containing the @merge tag. Default highlight is green.
Change the color settings by selecting Tools|Editor Options and
choosing the Color tab.
There are two ways to reconcile merge conflicts in CVS:
• Reconcile it automatically, using the button in the gutter next to a
conflict block to choose between old and new material.
• Reconcile it manually, using the message pane to locate the conflict and
the editor to resolve it. Remember to delete the @merge tags and any
extraneous text when you’re done.
Choose the way that best addresses the conflict.

Finding a tagged conflict block

In order to reconcile a conflict, you must first find the conflict block. There
are three ways to do this, depending on conditions:
• If you’re addressing a conflict as soon as it receives an @merge tag, the
message pane will display a warning about the conflict. Click the
message to put your cursor automatically into the conflict.
• If you’re addressing a conflict after it has been tagged and saved (and
consequently no longer shows up as a conflict), compile the file so the
compiler can catch the merge conflict tag. Then click the merge conflict
message in the message pane to put your cursor automatically into the
conflict.
• If you’re addressing both current and previous unresolved conflicts in
the same session, you can either do both of the above in sequence or
search for @merge through the file.

Working on an existing project in CVS 3-11

Synchronizing with changes in the repository

Reconciling conflicts automatically

JBuilder’s automatic merge conflict handling mechanisms are suitable for
relatively straightforward conflicts where sequential changes were made
to the same block of text.
To choose automatically between old and new versions of a conflicting
area of text,
1 Find the conflict.
2 Click the button in the gutter to the left of the conflict block.
3 Choose the version of the block of text that you want to keep.

Reconciling conflicts manually

1 Generate a merge conflict message in the message pane.
2 Double-click the merge conflict message in the message pane. This puts
your cursor in the first merge conflict within the source editor.
3 Type and manipulate the text as you normally would until the conflict
is resolved.
4 Select and delete the @merge tags and any extraneous text.
5 Save the file and commit the changes.
Note Once conflicts have @merge tags, CVS no longer sees them as conflicts.
Tip The compiler will tell you if it finds @merge tags when it compiles.
Therefore, if you postpone resolving a set of conflicts, you can compile
and then double-click the compiler’s @merge message to find the conflicts in
the editor.
The Team|Status Browser dialog box provides another means of viewing
diffs and conflicts. Note that this is only a view, not a context for change.
When all merge conflicts have been resolved, commit the changes and
update normally.

Updating the project

Updates all the files in your workspace with changes in the repository.
Any differences between the repository version of a file and your
workspace version of that file are automatically merged. Conflicts are
flagged.
For more information on handling merges and merge conflicts, see
“Updating a single file” on page 3-10.

3-12 Team Development Using JBuilder

 Adding files

Managing the project file

Instead of automatically being committed and updated with the rest of the
project, the project file must be committed and updated in a separate
process. This allows you to control when and whether global settings get
posted to the repository.
Important Complex projects may contain other projects within them. This means that
one project may have several project files, at different levels within it.
Only the current, top-level .jpx project file for the currently active project
is handled separately. Other project files in the project are updated with
the rest of the project.

Synchronizing the project file

To commit your local version of the project file to the repository, select
Team|Post Current “<project file name>”.
To update your workspace with the latest repository version of the project
file, select Team|Pull Latest “<project file name>”.
The project file is maintained separately from the rest of the project. There
are two reasons for this:
• Changes made to the project file can include path settings and other
changes that would affect the work of others who share the same
project. Maintaining the project file separately allows you to make
changes to files and paths and to test those changes before you need to
alter the project file.
• Many people may be working on the same project, but using different
files within it. If each of them commits the project file every time they
commit the project, it can create difficulties for the other users of the
same project.

Adding files
Adding a file to the JBuilder project is separate from adding it to the CVS
module. Also, a file that will be added to CVS must be within the project
directory before it gets added to the JBuilder project, or else JBuilder will
have the wrong path for it. Therefore, the sequence of actions before a file
can be added to CVS is:
1 Put the file in the project directory.
2 Add the file to the JBuilder project.
3 Add the file to the CVS module.

Working on an existing project in CVS 3-13

Removing files

The addition of the file must be committed in a separate step. Keeping the
Add and Commit commands separate allows you to work with the
addition locally before deciding whether to commit it to the repository.
To add the active file,
1 Select Team|Add File.
To add an inactive file or multiple files,
1 Select the file nodes in the project pane. Use the Ctrl key or the Shift key
to perform multiple selections.
2 Right-click and select CVS from the context menu.
3 Select Add File from the CVS submenu.
4 Enter a comment to describe the additions, according to your usual
practices.
5 Click OK in the dialog box to accept the files listed.
6 Click OK to close the dialog box.
Caution 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. Therefore, before
you add a file to CVS, make sure you have copied or moved it into the
project directory in your workspace.
Tip If you have trouble adding a file, read the note in the status bar. It will tell
you the source of the trouble.

Removing files
Deleting a file from CVS within JBuilder removes the active file from the
repository, from your workspace, and from the project.
To remove the active file,
1 Select Team|Remove File.
To remove an inactive file or multiple files,
1 Select the file nodes in the project pane. Use the Ctrl key or the Shift key
to perform multiple selections.
2 Right-click and select CVS from the context menu.
3 Select Remove Files from the CVS submenu.
4 Enter a comment to describe the removals, according to your usual
practices.
5 Click OK in the dialog box to accept the files listed.
6 Click OK to close the dialog box.

3-14 Team Development Using JBuilder

 Creating a version label

Creating a version label

Version labels, or tags, allow you to take a snapshot of the entire project at
any point in time. Since different files change at different rates, a project of
100 files can contain 100 different current revision numbers. Version labels
mark the evolution of the entire project without reference to changes in
individual files.
Select Team|Add Version Label To Project to create a version label for the
current project. The Add Version Label To Project dialog box appears.
Name the version label according to your usual practices. Describe the
label’s purpose. Click OK when you’re done. JBuilder applies the label to
every file in the project that resides in the repository.

Managing file status in CVS

Checking a file’s CVS status
Displays the current status of the selected file in CVS: whether changes
have been made locally or remotely, whether conflicts have been found,
and so on.
To check the status of the active file,
1 Select Team|Status For <Filename>.
To check the status of any single file in the project,
• Select the file in the project pane.
• Right click and select CVS from the context menu.
• Select Status For “<Filename>” from the CVS submenu.
• Click OK to close the dialog box.

File access notification

JBuilder supports cvs watch and cvs edit and unedit commands.
Normally, you learn that other developers have changed a file when you
update it or check its status. CVS is an optimistic version control system,
allowing more than one developer to make changes to the same set of files
at the same time. It’s possible to notify each other when you’re working on
common files with CVS by using the CVS Watch functions.
These commands are available from two places: from the Team menu on
the submenu under CVS Watches and from the project pane’s context

Working on an existing project in CVS 3-15

Managing file status in CVS

menu on the submenu under CVS. Select multiple files from the project
pane and use the context menu to put a Watch on or apply CVS Edit to
more than one file at a time.
Note The CVS administrator must put a watch on the files before these
commands are useful.

CVS Watches
CVS Watches provide a way to notify you when someone else is working
on a file that you have checked out. This is especially useful for a large or
geographically dispersed group of users who are collaborating on the
same set of files.
The watch functions are supported in JBuilder to accommodate
environments that use watches. Watch functions, even more than most
version control commands, require good citizenship on every user’s part
in order to be effective.
JBuilder supports the CVS commands watch add, watch remove, cvs edit, and
cvs unedit. The CVS administrator (or someone with appropriate access)
must enable watches before they’re useful in JBuilder.
Select Team|CVS Watches to access the CVS Watches submenu:

A notification is sent to all users when CVS Edit is used on a file—

depending on the server’s configuration, this could be an email, pager call,
or log file entry.
CVS Edit can be terminated in one of two ways, depending on whether
you want to keep the changes you made or not:
1 If you want to keep your changes, commit the file. This will remove the
CVS Edit, while leaving the Watch on the file.

3-16 Team Development Using JBuilder

 Managing file status in CVS

2 If you changed your mind about changing the file, use CVS UnEdit.
This will:
• Cancel all the changes that you made since applying the CVS Edit.
• Remove the CVS Edit.
• Leave the Watch on.
• Generate a log entry.
These are purely menu-driven commands. There are no dialog boxes
associated with them. To view a file’s Watch and Edit status, select Team|
Status For <Filename> with that file active in the content pane, or select
Team|Status Browser and look for the file on the Changes page.

Working on an existing project in CVS 3-17

3-18 Team Development Using JBuilder
 Chapter

Working on a new project in CVS

Chapter4
4
Once JBuilder is notified that you want to put the active project under
version control, it populates the Team menu with applicable CVS
commands. To notify JBuilder,
1 Select Team|Select Project VCS. The Select Project VCS dialog box
appears:

2 Choose CVS from the dialog.

3 Click OK or press Enter to close the dialog box.

Placing a new project into CVS

Checking a project into CVS through JBuilder creates the directory
structure in the repository, adds the files to the repository, and creates the
CVS infrastructure needed to maintain revision management both in the
repository and in your workspace.

Working on a new project in CVS 4-1

Placing a new project into CVS

Checking in a project for the first time

From an open project,
1 Select Team|Place Project Into CVS to bring up the Place Project Into
CVS wizard. The first step of this wizard configures the connection to
the repository:

Under Connection Type, Local connects to a local repository, PServer

connects to a repository that is password-protected, and Ext typically
connects to a repository on a secure server.
2 Under Login Settings, enter the server name. JBuilder fills in the user
name you use on your machine by default. If your username is different
on the server, change this to match it.
3 Under Module Location, enter the path to the repository you want to
place the new module in. If you’re using a local repository, you may
click the ellipsis button to browse to it. Enter a new module name for
the new module.
Note JBuilder maintains lists of prior connections for you to choose from.
These lists are empty when you use the wizard for the first time, but
after that you can select them from the drop-down lists instead of
typing them in.
Tip The CVSROOT path appears at the bottom of the wizard. It reflects the
information entered in this step. If you’re unsure what you should
enter and you already have a CVS account on an existing server, check
your machine’s user environment variables or see your CVS
administrator.
4 Click Next to continue.
5 Step 2 provides space for a comment describing the new module.

4-2 Team Development Using JBuilder

 Placing a new project into CVS

6 Click Next to continue.

7 Step 3 allows you to exclude directories in the project from CVS:

Expand directories to fine-tune which files you want to include in each

directory.
Directories for backup and derived files are excluded by default. Source
directories are included by default.
8 Click Finish to create a CVS module and check the project into it.
Note The project disappears from the AppBrowser while the project is
checked in and then reappears once it’s under CVS control.
When you create a CVS module in JBuilder, several things happen:
• JBuilder creates a module to put a project into.
Note The action of importing a project into CVS doesn’t change any other file
in the existing directory structure.
• 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. No
other change is made to the original directory.
This extra step provides an extra level of safety, as CVS doesn’t always
handle every file type gracefully. JBuilder gives you the opportunity to
verify that all of the files you want to include in the CVS module are
present and correct by providing the .precvs directory to check the
module against.

Working on a new project in CVS 4-3

Creating a local repository

Creating a local repository

JBuilder provides a way to create a local repository. This is ideal for
working on projects that don’t need to be shared but that would still
benefit from revision management. A local repository gives you complete
access and administrative control of the repository.
You can put as many modules as you want to into the repository, up to
system allowances.

Use either an empty directory or enter a new one and JBuilder will create
it for you. CVS’s administrative subdirectory is automatically created in
the repository directory.
Warning Avoid using the directory as anything but a repository. Don’t put files
directly into or take files directly out of the repository. It renders CVS
useless in that repository, since CVS has no way of tracking changes that
were not made through CVS.

4-4 Team Development Using JBuilder

 Chapter

Programmer’s guide to the

Chapter5
5
CVS integration
CVS is installed automatically inside the JBuilder root directory. No
outside settings are made for it until you use the CVS integration. If you
uninstall JBuilder, the version of CVS installed with JBuilder is uninstalled
with it.
Once the integration is used, the environment variables for CVS are set
and must be removed manually (if necessary.) Projects and repositories
created after JBuilder is installed are protected: they will not be
uninstalled with JBuilder.
This document provides in-depth material on the CVS integration and
background information on CVS and configuration. It has three main
sections:
• Guide to the CVS integration: discusses which commands are used by
the JBuilder frontend.
• Using the CVS Helper utility: discusses how to use this server daemon.
• Reference: describes how CVS handles binary files.

Guide to the CVS integration

This guide discusses commands used in the CVS integration, so you can
better understand what to expect from it. This part of the documentation
is structured according to which commands are most closely associated.

Programmer’s guide to the CVS integration 5-1

Guide to the CVS integration

There are four groupings used for these commands:

• Using CVS as your version control system: selecting CVS, configuring
the repository connection, and creating a local repository.
• Getting material out of the repository: pulling a project from CVS,
checking files out of the repository, and updating.
• Getting material into the repository: checking in files, checking in a
project file, checking in an entire project, and committing.
• Managing the repository: adding and removing files, version labeling,
and using watches.
The Status Browser and Commit Browser apply predictable commands,
although they can apply them to many files quickly. The Status Browser
passes cvs status <filename1, filename2, ...> to the command line,
retrieving the status of each file from CVS itself.
The Commit Browser offers a menu of possible CVS commands for each
altered file. It passes each command and its associated files to CVS, then
commits each changed file and appropriately applies the individual and
summary comments specified by the user.
In JBuilder SE and Enterprise, a file’s comments can be viewed in the
History Info page.

Using CVS as your version control system

JBuilder executes CVS commands by passing them to the command line.
This means that JBuilder can take advantage of all of CVS’s commands
and options (depending on how far you want to go with the OpenTools
API) just as, for the most part, JBuilder is bound by CVS’s limitations.

Selecting CVS
When you use Team|Select VCS and choose CVS from the dialog box, it
tells JBuilder which set of Team menu commands to make available. It
doesn’t pass any commands to CVS.

Configuring the repository connection

Repository connection configuration is built into the Pull Project From
CVS and Place Project In CVS wizards. These wizards notify JBuilder of
the connection configuration and, if necessary, write to your environment
variables so CVS can find its administrative files.
If this is the first time CVS is configured on your machine, you can use
CVS from the command line after you have configured a connection
through JBuilder. However, if you do so, then JBuilder will have no way
of being aware of CVS actions performed outside of its own environment.

5-2 Team Development Using JBuilder

 Guide to the CVS integration

The CVS connection is set by environment variables. If the connection is

configured properly in your environment variables before you use
JBuilder’s Pull Project From CVS or Place Project Into CVS wizards, it is
still necessary to use the connection configuration steps in the wizards so
that JBuilder is fully aware of the repository connection used for each
individual project.
When using a repository, it’s important to use it appropriately. Simply
copying a project into your workspace prevents effective version control
and keeps your changes out of the repository, where the project will
continue to evolve regardless.

Creating a local repository

JBuilder uses cvs init <repository_name> at the level you specify in the path
you set for the repository. It’s preferable to keep the repository at or near
the user’s root.
This command is benign, so if you accidentally create the same repository
twice in the same place, no files or data in that repository are overwritten.

Getting material out of the repository

When CVS is properly used, projects are checked in once per project and
checked out once per user. After that initial checkin or checkout, the users
maintain the congruency of workspace and repository versions by
updating and committing changes. Once a project is checked in,
afterwards it can’t be checked in again. Likewise, files can be added only
once.

Pulling a project
The Pull Project wizard checks a module out of the repository and opens it
as a project in JBuilder. Access it either from the Project page of the object
gallery (File|General) or, with a project open and CVS selected as the
version control system, from Team|Pull Project From CVS.
For CVS, the wizard creates an administrative infrastructure and
workspace:
1 If there are no environment variables pointing to the CVS home and
cvsroot directories, it creates them.
2 It copies the project tree from the repository into the workspace.
3 It creates a subdirectory in each directory in the project and names it
cvs. This is where CVS maintains its administrative files for the
directory.
Items 2 and 3 are done using the cvs checkout <modulename> command.

Programmer’s guide to the CVS integration 5-3

Guide to the CVS integration

For JBuilder, the wizard:

1 Records the project’s CVS parameters.
2 Opens the module as an active JBuilder project.
3 Makes the CVS menu items available from the Team menu and the
project pane.
4 Makes CVS versions available in the History pages in the content pane.

Pulling a project file

When you update a project file, JBuilder passes cvs update
<projectfilename> to the command line. The project file is handled by CVS
as a binary file, in order to maintain the validity of the project file values.
When you update or commit the project file, the old settings are
overwritten. There’s no attempt to merge them with the new ones, since
that could result in meaningless values.
As used in the CVS integration, the project file controls path settings:
source, test, output, library, and backup paths. Local project settings, such
as doc author and runtime configurations, are not affected by the
synchronization. JBuilder handles this distinction behind the scenes.
Private settings, such as your running and debugging preferences, are
kept in a local project file called <projectname>.local.jpx. This file is not
affected by CVS. This means your local preferences can’t be overwritten
by another user.
Note Only one project file is treated specially by the version control integration.
By default, JBuilder uses the top-level project file in the current project
directory. Child project files are checked in and out as normal binary files.

Checking out files

When you check out individual files, JBuilder passes cvs checkout
<filename> to the command line at the working directory level. No options
are used by JBuilder.

Updating files
When you update the active file from the Team menu or selected files
from the project pane, JBuilder passes cvs update <filename1>, <filename2>,
... to the command line at the working directory level.
When you update files from the Commit Browser, JBuilder puts the update
command and its list of files in the queue of commands passed from the
Commit Browser to the command line.
Updating is important for two reasons. The more altruistic reason is that it
keeps the repository current, allowing others access to the latest versions
of the files. The immediately practical reason is that it reduces the
occurrence of merge conflicts substantially. Updating before committing

5-4 Team Development Using JBuilder

 Guide to the CVS integration

is the best way to avoid merge conflicts and the subsequent work involved
in resolving them.

Removing files
JBuilder uses the cvs remove <filename> command to remove the file from
CVS and then commits the removal automatically. It also removes the file
from the JBuilder project.
If you don’t have a copy of that file somewhere else, this command will
delete it entirely. You can retrieve it from storage in CVS, if necessary, by
using the appropriate CVS command from the command line and then
adding it to the repository again.

Getting material into the repository

Material is posted to the repository for the first time by checking in or
adding. (Projects are checked in. Files are added.) Changes to existing
material are posted to the repository by committing.

Checking in a project
The Place Project Into CVS wizard configures the connection to the
repository for the project and creates a module for the project. If this is the
first time CVS has been used on the machine, JBuilder writes the necessary
environment variables.
JBuilder first creates a module based on the original project, then renames
the original project by adding the .precvs suffix to the original project
name, then it checks the new module back out into your workspace.
JBuilder creates the module using cvs import -m "<comment text>"
<module_name> <vendor_tag> <release_tag>. Only the files you select in Step 3
of the wizard are checked in as part of the module. By default, JBuilder
selects source material and the project notes file for checkin. JBuilder
excludes generated files and backup files by default, since these files
normally don’t need to be under version control. JBuilder also performs
automatic package discovery so it can create package paths for you.
The project file is required by JBuilder in order to handle the project
correctly. It must be in the project’s root directory. It must be checked in
with the rest of the project initially, but is maintained separately from the
rest of the project after that.
If there’s no project file, JBuilder creates one for you when you check the
project in. If there is more than one project file, JBuilder asks which one
you’d like to use as the top-level project file for version control purposes.
JBuilder adds the .precvs suffix to the original project name, so you have
the opportunity to check the original project against the created module.
This is common practice.

Programmer’s guide to the CVS integration 5-5

Guide to the CVS integration

JBuilder checks out the new module back into your workspace so you can
go to work on it immediately.

Adding new files

JBuilder adds a file to CVS using cvs add <filename>. If more than one file is
added, the files are listed in a comma-separated string.
When you commit a file from the Team or project pane context menu,
JBuilder does not commit the added files at the time, but allows you to
commit them separately, once you’ve had a chance to use them and decide
they should be kept. Use the Commit command, either from the menus or
from the Commit Browser.
When you add a file from the Commit Browser, JBuilder passes cvs add
<filename> to the command line. After adding the file, JBuilder
automatically commits it behind the scenes, using cvs commit <filename> -m
[summary comment] [individual comment].
JBuilder automatically commits added files only from the Commit
Browser. Files added from the menus must be committed in a separate
step.

Committing changes
JBuilder passes cvs commit <filename> -m [summary comment] [individual
comment] to the command line for each file committed, whether committed
from the menus or from the Commit Browser.
Changes are committed behind the scenes for file removals and for files
added from the Commit Browser. Files added from the menus and other
file changes are committed only when the user explicitly uses the commit
command from the IDE.

Posting a project file

JBuilder requires a project file of the .jpx type, for programmatic reasons
that make it easier to work with in a shared development environment.
The .jpx project file is an XML project file type.
To commit a project file, select Team|Sync Project Settings. Select Post
Current from the submenu. JBuilder passes cvs commit
<projectfilename>.jpx to the command line. The project file is treated by
CVS as a binary file, in order to maintain the validity of the project file
values.
As used in the CVS integration, the project file controls path settings:
source, test, output, library, and backup paths. Local project settings, such
as doc author and runtime configurations, are not affected by the
synchronization. JBuilder handles this behind the scenes.

5-6 Team Development Using JBuilder

 Using the CVS Helper utility

When you update or commit the project file, the old shared settings are
overwritten. There’s no attempt to merge them with the new ones, since
that could result in meaningless values.

Managing the module

JBuilder supports two additional CVS features. Version labeling allows
you to mark the evolution of an entire project. CVS Watches keep users
informed about who else is using files.

Version labeling
JBuilder passes cvs tag <tag_name> to the command line from the project’s
root directory. This tags all the files under CVS control that are in that
directory and recursively tags all such files in its subdirectories.

Using watches
JBuilder’s CVS integration supports the use of watches, but it does not
turn them on. The administrator (or someone with suitable access) must
turn the watch on in the usual way, in order to make these commands
meaningful.
JBuilder uses the following console commands for the following menu
items:
• Watches|Add Watch: cvs watch add
• Watches|CVS Edit: cvs edit
• Watches|CVS UnEdit: cvs unedit
• Watches|Remove Watch: cvs watch remove
In order to apply options to the watch and edit commands, it will be
necessary to enter the commands at the command line.
The online Cederqvist CVS manual discusses CVS watches in detail at
http://www.cvshome.org/docs/manual/cvs_10.html#SEC89.

Using the CVS Helper utility

CVS Helper is a native application that queries a remote repository for the
names of its modules and branches. Once installed, JBuilder detects CVS
Helper automatically and presents a drop-down list of the existing
modules and branches when you use File|General|Project tab|Pull
Project From CVS.
To install CVS Helper, copy cvshelper.exe from the JBuilder CD onto the
machine that hosts the PServer CVS repository.

Programmer’s guide to the CVS integration 5-7

Using the CVS Helper utility

To start the program, type nohup cvshelper & at the command line. This
program requires no configuration because it retrieves needed parameters
at runtime.
CVS Helper provides four options:

-h Help
-p Change default port (preset default is 2442)
-d Toggle daemon state (default is on)
-q Quit CVS Helper

Technical information
CVS Helper is a socket-based application that communicates with JBuilder
via TCP/IP on port 2442 (by default: the port number can be changed.) It
can be used by anyone but requires administrator access to restart it if the
server shuts down.
Once a communication channel is established the program waits for
commands. Each command is in the following form:
<command> <optional arguments> \n
Currently, CVS Helper understands only these commands:
about
getVersion
getModules <repository>
getBranches <repository> <module name>
getLabels <repository> <module name>
quit
Where <repository> and <module name> are the absolute path of a CVS
repository on the server and the name of a CVS module, respectively.
The form of the output is:
<text>
line1
ƒ
lineN
</text>
The content of the output is:

about Returns the copyright information about the program.

getVersion Returns a string with the version name and the build date.
getBranches Sends a <feedback> data block.
getLabels CVS Helper reads the branch and label information stored in
the CVS archive files and generates a file containing that
information.This data block returns the name of that file.

5-8 Team Development Using JBuilder

 CVS reference

Security information
CVS Helper is meant to be run side-by-side with a standard CVS PServer
configuration. The program doesn’t provide any way of executing
programs other than CVS Helper, or commands other than CVS Helper’s,
on the server machine.
The services provided by CVS Helper are purely queries. The only data
exposed by this program is the list of CVS modules and related branch
names. If this data can be shared with users of the server on which CVS
Helper runs, it’s appropriate to run CVS Helper.
If you use CVS through a firewall and you want to use CVS Helper, the
firewall must be configured to allow access to CVS Helper as it allows
access to CVS.

CVS reference
This section provides information on binary files in CVS and how to set
environment variables.

Handling binary files in CVS

If JBuilder does not yet recognize a non-text-based file type in CVS, you
must specifically include the file’s extension in JBuilder’s list of Generic
Binary file types. To include it,
1 Select Tools|IDE Options.
2 Choose the File Types tab.
3 Select the Generic Binary file type.
4 Click Add.
5 Enter the new extension.
If necessary, you can use the file stored in the .precvs directory to restore
the original binary file.

Checking and setting user environment variables

The way you access environment variables depends on your platform:
Linux, Solaris, Windows XP, Windows NT, or Windows 2000.
Your variables for CVS should include values for the following names:
• cvs: This is the directory that contains your CVS installation. It’s usually
a top-level directory, so it’s probably at the root of your drive.

Programmer’s guide to the CVS integration 5-9

CVS reference

• cvsroot: This is the path to the server you use. See the table below for
the syntax of this path.
• Once you have used CVS in JBuilder, JBuilder will create a variable
called .cvspass. Please don’t change this variable.
Where needed, CVS wizards contain configuration pages. At the bottom
of these pages, the CVSROOT variable appears, changing as you complete the
configuration fields in the wizard. This is what the CVSROOT variable
consists of in each of the types of server connections that JBuilder
supports:

Connection type CVSROOT syntax

Local :local:<repository path>
PServer :pserver:<user name>@<server name>:<repository path>
Ext :ext:<user name>@<server name>:<repository path>

Linux and Solaris

Edit the PATH environment variable in your shell’s init file. Include:
• The path to the directory that contains your CVS installation.
• The path to the repository on the server.
Remember to separate each PATH variable with a semicolon.

Windows XP
Access your user environment variables from Start|Control Panel|
System (using the Classic view) or Start|Control Panel|Performance And
Maintenance|System (using the Category view.)
Then,
1 Select the Advanced tab.
2 Click the Environment Variables button near the bottom of the dialog
box.
3 Under System Variables, select the variable you want to change.
4 Click Edit to change an existing variable (such as PATH) or New to
create a new one.
5 Confirm or enter a variable name and edit or enter a value for it.
6 Click OK or press Enter when done.

Windows NT
On Windows, your user environment variables are stored in the Settings
directory. You can access this in two ways: from Start|Settings|Control

5-10 Team Development Using JBuilder

 CVS reference

Panel|System, or by right-clicking the My Computer icon on your

desktop and selecting Properties.
In Windows NT,
1 Select the Environment tab.
2 Look under User Variables for the environment variables that pertain
to CVS.
3 Select a variable in order to change it. Type a new variable name and
enter a value for it to create a new variable.
4 Click OK or press Enter when done.

Windows 2000
On Windows, your user environment variables are stored in the Settings
directory. You can access this in two ways: from Start|Settings|Control
Panel|System, or by right-clicking the My Computer icon on your
desktop and selecting Properties.
In Windows 2000,
1 Select the Advanced tab.
2 Click Environment Variables in the middle of the dialog box.
3 Click Edit to change an existing environment variable or New to create
a new one.

Programmer’s guide to the CVS integration 5-11

5-12 Team Development Using JBuilder
 Chapter

Visual SourceSafe in JBuilder

Chapter6
6
This is a feature of JBuilder’s integration of Visual SourceSafe (VSS) allows you to perform
JBuilder Enterprise. the most common version control tasks from within the development
environment.
JBuilder’s integration of VSS is designed and tested on Visual SourceSafe
version 6.0. This integration is supported on Windows NT and 2000.
You must have the Visual SourceSafe client installed on your machine in
order to access the Visual SourceSafe menu commands from within
JBuilder. In order to connect to an existing VSS database, you must have
LAN access to the directory that the VSS database is located on. If you can
see the VSS directory in Windows Explorer, you should be able to access it
in JBuilder.
Visual SourceSafe commands are generally available from two places: the
Team menu from the main menu bar, and the context (right-click) menu in
the project pane.
VSS commands other than those described in this documentation must be
executed from within VSS Explorer or at the command line. Invoke VSS
Explorer from the active project by choosing Team|Visual SourceSafe
Explorer.

Configuring the connection

Place Project Into VSS (available from the Team menu) and Pull Project
From VSS (available from the Team menu or the object gallery) are
wizards that configure your connection for the project you want to work
on. Each project’s configuration is set individually.
When you install JBuilder, it looks for an installation of Visual SourceSafe.
If it finds one, it configures its path to the local VSS installation and to the
Configuring the connection

default database. If not, JBuilder prompts you to enter this information

when you first use either of these wizards.
The wizards guide you through the process of setting the connection to
the database, setting up your working folder, and choosing which files to
keep checked out. Once your connection is configured for that project, you
don’t have to set it again.
Note Performance improves greatly when the VSS client is installed on a local
file system rather than on a local area network (LAN).
View and test the configuration by choosing Team|Configure Visual
SourceSafe. The Configure Visual SourceSafe dialog box appears:

Note The username and password fields are writable. If your username or
password for Visual SourceSafe changes, select Team|Configure Visual
SourceSafe and change these fields to match your current identification
data. Click the Test button to check the configuration before you actually
use it.

6-2 Team Development Using JBuilder

 Chapter

Working on an existing
Chapter7
7
project in VSS
This is a feature of JBuilder supports common VSS tasks and provides features that make
JBuilder Enterprise applying commands to multiple files much easier.

Pulling an existing project

There are two possible ways to pull a project from the database from
within JBuilder: from the object gallery or from the Team menu.
From the object gallery:
1 Select File|New. The object gallery appears.
2 Choose the Project tab.
3 Choose Pull Project From VSS.
4 Double-click the icon, click OK, or press Enter to start the Pull Project
From Visual SourceSafe wizard.
Note This is the only VSS command available from the object gallery.
From the Team menu:
1 Open or create a project in order to activate the Team menu.
2 Select Team|Pull Project From VSS.
Note A project must be active before the Team menu becomes available. Use
any project, as it will not be affected by version control commands that
don’t apply to it.

Working on an existing project in VSS 7-1

Pulling an existing project

Both of these methods bring up the Pull Project From Visual SourceSafe
wizard. This wizard configures your connection and sets up everything
you need to get to work on a project that’s under Visual SourceSafe
control.
When you install JBuilder, it searches for a VSS installation. If it finds one,
it records the location of the local installation and chooses a default
database. If JBuilder doesn’t find these paths, this wizard prompts you for
them. In that case, this wizard has five steps. The first step tells JBuilder
where to find the Visual SourceSafe client runtime directory:

Tip If you happen to choose an invalid directory, a message appears in the

wizard letting you know that the selection is not valid. In that case, click
the ellipsis (...) button and try again.
For every project you put under Visual SourceSafe after that, it will have
four steps:
1 Select Visual SourceSafe Database Directory
2 Enter Username And Password
3 Select Visual SourceSafe Project
4 Select An Empty Target Directory
Note JBuilder does not change your access rights in Visual SourceSafe. You
must have suitable access in order to execute a VSS command from within
JBuilder.

Selecting the database directory

The Select Visual SourceSafe Database Directory step is Step 1 once the
path to the runtime directory is set.

7-2 Team Development Using JBuilder

 Checking out files

The first time you access Visual SourceSafe through JBuilder’s integration,
this field is empty. Click the ellipsis (...) button to browse to the database
directory. The database directory is where the projects are stored.
Once you have accessed a database directory, that becomes your default
database directory. It appears in the box, but you can still select others
either by browsing to them using the ellipsis button or by clicking the
down arrow and selecting from the list of database directories you have
previously used.

Entering security information

The Enter Username And Password step ensures that you have the
necessary access to VSS. This information is not persisted, so you must
enter it each time you use the wizard.

Selecting a project
The Select Visual SourceSafe Project step provides a drop-down list of the
projects that are available in that database directory in a drop-down list.

Choosing a target directory

The Select An Empty Target Directory step asks for an empty directory to
pull the project into. The project is pulled in as a subdirectory of that
directory.

See also
• The Help button in any page of the wizard.
• “Configuring the database connection” on page 9-1 to learn more about
how to maximize performance and how the wizard handles default
paths.

Checking out files

The Check Out command copies the selected file or files from the current
VSS project to the folder in your work area and makes them writable to
you.
To check out the active file:
1 Select Team|Check Out “<Filename>”

Working on an existing project in VSS 7-3

Checking out files

To check out files by using the project pane:

1 Select the file or files in the project pane.
Use the Ctrl key or the Shift key to select more than one file.
2 Right-click on any selected file.
3 Select Visual SourceSafe from the context menu.
The submenu that appears applies to all of the selected files.
4 Select the Check Out Files command from the submenu.
A Check Out Files dialog box appears. Look at the list of files and make
sure it matches what you intended.
5 Click OK to check out the files.
6 Click OK to close the dialog.
You must have the Check Out access right to use this command.

Undoing a checkout
Cancels the checkout of selected files, voiding all changes.
To undo the checkout of the active file:
1 Select Team|Undo Check Out “<Filename>”
To undo the checkout of files by using the project pane:
1 Select the file or files in the project pane.
Use the Ctrl key or the Shift key to select more than one file.
2 Right-click on any selected file.
3 Select Visual SourceSafe from the context menu.
The submenu that appears applies to all of the selected files.
4 Select the Undo Checkout command from the submenu.
An Undo Checkout dialog box appears. Look at the list of files and
make sure it matches what you intended.
5 Click OK to undo the checkout on the files.
6 Click OK to close the dialog.
Whether the latest database version of the file is pulled into your
workspace depends on a Visual SourceSafe variable that your
administrator sets. Undoing a checkout may simply revert any changes
you made, so that the version of the file you see is the same one you
checked out.
You must have the Check Out access right to use this command.

7-4 Team Development Using JBuilder

 Checking out files

See also
• “Undoing a checkout” on page 9-4.

Checking out a project file

Pulling the latest .jpx project file checks out the most current shared .jpx
project file for the active project from the VSS database.
Note Only the active project file in the current project directory is treated
specially by the version control integration. All other project files are
treated by version control as binary files, so that they are overwritten
rather than merged.
To pull the latest project file from the Team menu:
1 Select Team|Pull Latest “<project file name>.jpx”
To pull the latest project file by using the project pane:
1 Right-click the project file node.
2 Select Visual SourceSafe from the context menu.
3 Select Pull Latest “<project file name>.jpx” from the submenu.
4 Click OK to pull the project file.
5 Click OK to close the dialog.
The project file maintains project settings, such as paths and library
configurations. This information is shared by other users of the project.
JBuilder allows you to pull and post this separately in order to keep it
available to other users as much as possible.
JBuilder protects local project settings, such as doc author and runtime
configurations, so you can pull and post the project file as much as
necessary without overwriting local project settings.

See also
• “Creating and managing projects” in Building Applications with JBuilder
to understand project files better.
• “Checking the project file in or out” on page 9-4.

Working on an existing project in VSS 7-5

Checking in files

Checking in files
Updates the database with changes you made to the checked-out file or
files. This dialog offers the option of keeping the file checked out so you
can continue to work on it after checking in your changes. If you decide
not to keep it checked out and you work under a locking VSS system, this
command unlocks the VSS master copy of that file so that someone else
can write to it.
To check in the active file:
1 Select Team|Check In “<File name>”
To check in files by using the project pane:
1 Select the file or files in the project pane.
Use the Ctrl key or the Shift key to select more than one file.
2 Right-click on any selected file.
3 Select Visual SourceSafe from the context menu.
The submenu applies to all of the selected files.
4 Select the Check In Files command from the submenu.
A Check In Files dialog box appears. Look at the list of files and make
sure it matches what you intended.
5 Type a comment describing the changes, according to your usual
practices.
6 Click OK to check in the files.
7 Click OK to close the dialog.
You must have the Check Out access right to use this command.

Checking in the project file

Posting the current .jpx project file checks in the most current shared .jpx
project file for the active project into the VSS database.
Note Only the active project file in the current project directory is treated
specially by the version control integration. Other project files in the
project are treated by version control as binary files, so they are
overwritten rather than merged.
To post the latest project file from the Team menu:
1 Select Team|Post Current “<project file name>”

7-6 Team Development Using JBuilder

 Adding and removing files

To post the current project file by using the project pane:

1 Right-click the project file node.
2 Select Visual SourceSafe from the context menu.
3 Select Post Current “<projectfilename>” from the submenu.
4 Click OK to check in the project file.
5 Click OK to close the dialog.
The project file maintains key project paths and parameters. This
information is shared by other users of the project. JBuilder allows you to
pull and post this separately in order to keep it available to other users as
much as possible.

See also
• “Creating and managing projects” in Building Applications with JBuilder
to understand projects and project files.
• “Checking the project file in or out” on page 9-4 to learn more about
this command.

Adding and removing files

JBuilder supports the Add command and the Remove command.

Adding files
Adds files into the VSS database and logs the comment you type for the
addition.
To add the active file:
1 Select Team|Add “<Filename>”
To add files by using the project pane:
1 Select the file or files in the project pane.
Use the Ctrl key or the Shift key to select more than one file.
2 Right-click on any selected file.
3 Select Visual SourceSafe from the context menu.
The submenu that appears applies to all of the selected files.

Working on an existing project in VSS 7-7

Adding and removing files

4 Select the Add Files command from the submenu.

An Add Files dialog box appears. Look at the list of files and make sure
it matches what you intended.
5 Type a comment describing the additions, according to your usual
practices.
6 Click OK to add the files.
7 Click OK to close the dialog.
VSS uses its AutoDetect feature to specify whether the added files are text
or binary files.
You must have the Add access right to use this command.

Removing files
Removes files from VSS Explorer and marks them as deleted. The items
still exist, however, and can be recovered using the Recover command
(accessible from Visual SourceSafe.)
To remove the active file:
1 Select Team|Remove “<Filename>”.
To remove files by using the project pane:
1 Select the file or files in the project pane.
Use the Ctrl key or the Shift key to select more than one file.
2 Right-click on any selected file.
3 Select Visual SourceSafe from the context menu.
The submenu that appears applies to all of the selected files.
4 Select the Remove Files command from the submenu.
A Remove Files dialog box appears. Look at the list of files and make
sure it matches what you intended.
5 Type a comment describing the additions, according to your usual
practices.
6 Click OK to add the files.
7 Click OK to close the dialog.
You must have the Add access right to use this command.

7-8 Team Development Using JBuilder

 Checking in the entire project

Checking in the entire project

JBuilder provides tools that display the status of all the files you have
altered in a project and that let you apply individual version control
commands to all of the altered files in a project at once.

Browsing the project’s status

To use the Status Browser:
1 Select Team|Status Browser.
The Status Browser displays all the files in your project and the version
control status of each one. It has two pages: the Changes page and the File
Include Lists page.
In the Changes page, the directory tree view is in the left-hand pane and
the list of files is in the right. Select the Full List node to view a list of all
the files in the project. Select a directory node to see a list of the files in that
directory.
The version control status of each file is noted in the Status column of the
list.
Select a file in the file list. The tabbed pane below the file list allows you to
view the source code of the selected file in any way that’s pertinent. For
instance, if you choose a file that has been changed locally, the Workspace
Source, Repository Source, and Workspace Diff tabs become available. If
you choose a file that has been changed on the database, the Workspace
Source, Repository Source, Repository Diff, and Complete Diff tabs
become available.

Table 7.1 Changes page source views

Source view Contents
Workspace Source This file’s source code from the current workspace version.
Repository Source This file’s source code from the current database version.
Workspace Diff This file’s most recent changes in your workspace.
Repository Diff This file’s most recent changes in the database.
Complete Diff Differences between the current version of this file in the
database and the current version in your workspace.

Working on an existing project in VSS 7-9

Checking in the entire project

Choosing files to include

The Status Browser displays and determines which files remain under
version control and which files remain strictly local. It also filters files that
remain under version control but are not necessarily of interest to you. It
has two pages: Team Include List and Personal Include List.

The Team Include List shows which files are under version control and
which are local. These files are tracked by the <projectname>.jpx file. The
information you enter here is stored in that file as well, because this is a
team-wide project setting: the files that are checked here are the files that
everyone needs to be able to use.
The bak files and the <projectname>.local.jpx file are normally excluded
(unchecked). Check your company’s policy about what files should be
included and what should be excluded from a team project checkin.
Caution The shared .jpx file must be included in order to maintain VSS in JBuilder.

7-10 Team Development Using JBuilder

 Checking in the entire project

The Personal Include List filters your personal view, so that only the files
you specify can show up in the Changes page. These files are tracked by
the <projectname>.local.jpx file.
This list is entirely for your convenience. Since you won’t necessarily be
working on every file in the project, you don’t necessarily want to look at all
of them whenever you do a checkin. This simple chart illustrates the concept
of available files as compared to the files needed by an individual developer:

The Personal Include List page lets you keep in view only the files that
you need. The rest stay hidden until you want to see them again.

Checking in the project

To check in the entire project at once,
1 Select Team|Commit Browser
The Commit Browser provides status messages and context-sensitive default
VSS actions for each modified file in the project. It also provides alternative VSS
commands in the form of drop-down menus in the Action column. Click a file’s
cell in the Action column to view alternative VSS commands.
These options are context-sensitive. Available commands vary depending
on the status of the file. The default option varies depending on how the
file achieved that status.

Working on an existing project in VSS 7-11

Checking in the entire project

The Commit Browser has three pages: Commits, Summary Comment, and
File Include Lists. It opens to the Commits page by default.

An expandable directory tree view is in the left-hand pane and the list of
files is in the right. Expand the tree view to display subdirectories and
directory contents.
In the Commits page, tabbed panes display the selected file’s source in
five ways:

Tab Display
Workspace Source This file’s source code from the current workspace version.
Repository Source This file’s source code from the latest database version.
Workspace Diff This file’s most recent changes in your workspace.
Repository Diff This file’s most recent changes in the database.
Complete Diff The differences between the current local version of this file
and the latest database version.

Action options
JBuilder chooses default options to place in the Action column based on
the file’s status as reflected in the Status column. For changes made within
JBuilder, the default actions are chosen not only according to the file’s
status but how it reached that status. For instance, if a file isn’t in the
workspace, it might be because it was removed from the project or
because it has not yet been checked out. JBuilder senses the reason that it’s
not in the workspace and chooses the most likely option to list as the

7-12 Team Development Using JBuilder

 Checking in the entire project

default: Remove From Repository or Check Out. Additions and removals

made from this browser are automatically checked in.
The list of files has a context menu that supports multiple selections. To
apply the same option to several files, select the files you want, using the
Shift key or the Control key to extend the selection beyond the first file
selected. Right-click any of the selected files, then choose the option you
want from the context menu.
If you want to check in some but not all changed files in the project, select
No Action as the option for the files you don’t want to check in. You can
also auto-select No Action for all of the files in a directory by right-clicking
the directory in the node tree view and selecting Perform No Action For
All In Directory from the context menu.
It’s best to add and delete files from within JBuilder, so JBuilder can
perceive the reason for the changed status of the files and select the most
appropriate default option.
Options include:
• Commit: Check in the change to the version control database.
• Add: Add this file so it’s stored in the database.
• Delete: This file has already been removed from the database; this
removes it from your workspace.
• Get: This file has already been added to the database; this checks it out
to your workspace.
• Undo Checkout: Update the workspace with the latest database version
of this file, discarding all changes made since your last update.
• No Action: When you click OK, this file will not be touched by a
version control operation of any kind. It will be exactly as you left it
before you invoked the Commit Browser.
The table below demonstrates a few status notations and associated options.

Condition Listed status Default option Alternative options

File changed in the Changed In Commit to Repository • Undo Checkout
workspace Workspace • No Action
File added to Not In Add to Repository • Delete Locally
version control Repository • No Action
File deleted from Not In If removed from within • Undo Checkout
version control Workspace JBuilder: • No Action
Remove From
Repository

If removed from outside

JBuilder:
Get From Repository

Working on an existing project in VSS 7-13

Version labeling a project

Note The term “repository” is used as a generic term for the version control
structure that VSS calls the “database.” In JBuilder’s version control
terminology, “database” and “repository” are synonymous.

Summary comments
The Use Summary Comment checkbox at the bottom of the Individual
Comment pane allows you to attach the same summary comment to
multiple files. This summary comment will be maintained along with the
individual comment written for each file. Select the Summary Comment
tab to write a summary comment.
The Summary Comment page offers the option of placing the summary
comment before the individual comments applied to individual files. This
option is on by default. If you deselect this option and select the Use
Summary Comment option on the Commits page, then the summary
comment will be applied only to files that don’t have individual
comments.

Version labeling a project

Version labels mark the evolution of the entire project without reference to
the changes in individual files. To create a version label for the active
project,
• Select Team|Create Version Label.
The Create Visual SourceSafe Version Label dialog box appears.
• Name the version label according to your usual practices and enter a
comment describing the label’s purpose.
• Click OK to close the dialog.
JBuilder applies the label to every file in the project that resides on the
database.

See also
• “Version labeling” on page 9-7.

7-14 Team Development Using JBuilder

 Chapter

Working on a new project in VSS

Chapter8
8
JBuilder must be notified that you want to put the active project under
version control. Then it populates the Team menu with applicable VSS
commands. To notify JBuilder,
1 Select Team|Select Project VCS. The Select Project VCS dialog box
appears:

2 Choose Visual SourceSafe from the dialog.

3 Click OK or press Enter to close the dialog box.

Placing a new project into Visual SourceSafe

This command invokes the Place Project Into VSS wizard. It takes an open
JBuilder project and creates a corresponding VSS project in an existing
VSS database. In the wizard, you specify which files and subdirectories to
include in the VSS project and which files to keep checked out after the
project is placed into VSS.
When you install JBuilder, it searches for a VSS installation. If it finds one,
it records the location of the runtime directory and chooses a default

Working on a new project in VSS 8-1

Placing a new project into Visual SourceSafe

database. If JBuilder doesn’t find these paths, this wizard prompts you for
them.
The wizard normally has five steps:
1 Select Team|Place Project Into VSS. The Select Visual SourceSafe
Database Directory page appears. After the first use, the first database
you used is offered as the default. Choose a different one from the drop
down menu or browse to a new location.
If you don’t know your VSS database directory path and it doesn’t
appear to match the hints provided, please see your VSS administrator.
2 Click Next to go to the Enter Username And Password page.
3 Enter the identification data you use to access Visual SourceSafe.
If your user name or password changes in Visual SourceSafe, you can
change it to match by selecting Team|Configure Visual SourceSafe.
4 Click Next to go to the Select Directories And Files To Include page:

Check the directories that you want to include entirely. If you want to
choose individual files to include, expand the directory in the tree view
and check the files inside it that you want to keep.
By default, the bak and classes directories are excluded and the src files
are included. The .jpx project file is required to be included because it
manages team-wide version control settings and preferences as well as
other project settings.

8-2 Team Development Using JBuilder

 Placing a new project into Visual SourceSafe

5 Click Next to go to the Select Files To Keep Checked Out page:

Expand the directories to see the files inside. Check the files you want
to keep checked out to your work area so you can work on them after
the project is placed into VSS.
6 Click Next to proceed to the Select Location In VSS Database page.
7 In the Location field, select an existing root VSS directory to keep the
new project in. All of the root directories available in the database are
listed in the drop down menu.
8 In the Project Name field, type a unique project name for this project.
This will be the project directory inside the database’s root directory.
9 Click Finish.
The Placing Project Into VSS feedback dialog appears. It reports on the
progress of the command and lets you know when the project is in VSS.
10 Click Close to close the dialog and return to the IDE.
The files you checked out appear in the content pane with write access
assigned to you until you check them back in.

See also
• “Pulling an existing project” on page 7-1 to learn more about runtime
directory discovery.

Working on a new project in VSS 8-3

8-4 Team Development Using JBuilder
 Chapter

Programmer’s guide to the

Chapter9
9
VSS integration
The JBuilder integration of VSS is based on VSS’s command-line interface.
This document provides background information on the VSS integration
including some commands, technical information, and suggestions to
improve performance.
This provides compatibility with different versions of VSS.

Configuring the connection

Selecting VSS
Using Team|Select Project VCS and selecting Visual SourceSafe notifies
JBuilder which set of version control menu commands to make available.
This command notifies VSS and populates the Team Development menus
with appropriate commands.

See also
• “Runtime location and performance” on page 9-2 to understand how to
improve the performance of this command.

Configuring the database connection

When you first install JBuilder, it looks for a Visual SourceSafe
installation. If it finds one, it sets the path to the VSS installation and the
default database. If you install VSS after JBuilder (or if JBuilder can’t find

Programmer’s guide to the VSS integration 9-1

Pulling an existing project

the VSS installation for some reason) then, the first time you use the Pull
Project or Post Project wizard, there’s an extra step that prompts you for
those paths. Once the paths are set, JBuilder stores them for all future
projects.
If these paths need to be set,
• Step 1 of the wizards, Select Visual SourceSafe Runtime Directory,
prompts you for the location of the client installation, ss.exe.
• Step 2 of the wizards, Select Visual SourceSafe Database Directory,
prompts you for the parent directory of the database.
Once the paths are set, the Select Visual SourceSafe Database Directory
page becomes Step 1. It offers the path to the default database directory,
and allows you to choose or type in another one.

Runtime location and performance

The Select Visual SourceSafe Runtime Directory step notifies you that a
local installation of the VSS client improves performance significantly.
This is due to limitations in technology, particularly the inevitable
time-lag required to send and receive a large number of VSS commands
simultaneously through a LAN connection. This time-lag is most
noticeable when you first access VSS through JBuilder at the start of a
work session. Sending commands to and receiving responses from the
local machine is far faster.
You can install VSS locally through the LAN. Visual SourceSafe states that
this is the preferred way to do so, as it configures your VSS connection
properly and saves you time. Consult your VSS administrator to learn
how to install the client locally from the LAN.

Pulling an existing project

Pulling an existing project writes the latest database version of the project
into your work area. Once the project has been pulled, use the menus to
check out the files you want to work on.

Using the Select Visual SourceSafe Database Directory step

This step tells JBuilder which database directory to start in. The database
directory is the parent directory that contains the databases stored in
Visual SourceSafe. The “database directory” term is congruent to the
generic “repository” term used in the Commit Browser and Status
Browser.

9-2 Team Development Using JBuilder

 Pulling an existing project

After the initial use,

• The Select Visual SourceSafe Database Directory step is Step 1.
• The database directory you selected the first time becomes the default
in the Directory field.
Any time you use this wizard, the drop-down list and the ellipsis (...)
button are available, allowing you to choose or navigate to a different
database directory.

Using the Enter Username And Password step

This step provides JBuilder with your identification information, which it
passes to VSS in order to enable your access through the JBuilder
interface.

Using the Select Visual SourceSafe Project step

The first time you use this wizard, the Project field will be empty. Click
the down arrow to choose from the list of projects in that database.
JBuilder may take a moment to query the database and return the full list
of the projects available.
The first project chosen becomes the default subsequently displayed in
this field. All the other projects in that database are always available from
the drop-down list.

Using the Select Empty Target Directory step

You need a work area to pull the project into. This step defines that work
area as a directory which you name. The project is pulled in as a
subdirectory of the target directory. In navigating to the project in the
future, keep this extra layer in mind.
The final page of the wizard displays stdout output from the commands
passed to VSS.

See also
• “Configuring the database connection” on page 9-1 to learn more about
the first steps of this wizard.

Programmer’s guide to the VSS integration 9-3

Checking out files

Checking out files

Checking out a file writes the latest version of the file to your work area.
VSS can be set to function either as an optimistic system, allowing
multiple checkouts and merging differences, or as a pessimistic system,
allowing only one user at a time to write to a file. It depends on company
practices and certain settings the VSS administrator makes.
JBuilder respects the read/write status that the administrator sets for the
checkout command. Therefore, if checking out a file normally means that
others can’t write to it, then checking out a file using JBuilder still means
others can’t write to it. Likewise, if several developers can write to the
same file simultaneously, then they can still do so when they use JBuilder
to check the file out.

Undoing a checkout
Undoing a checkout voids all changes you made to that file since you
checked it out. Database settings determine whether the latest version is
retrieved from the database or the local version is simply reverted.
Undo Checkout performs a Get operation when it’s finished, unless the
Delete_Local initialization variable in the ss.ini file is set to Yes.
If someone checks in a file that has not changed and inadvertently creates
a new version, VSS performs an Undo Check Out automatically. This way
the file is unlocked and therefore accessible again, but no new version is
logged.

Checking in files
The checkin command posts your changes to the database version of the
files, generating a new version of each file. If the files were locked while
they were checked out to you, the lock is removed. This depends on an
administrative setting in VSS. If you have questions about it, please ask
your VSS administrator.
Important The current top-level .jpx project file for the project is checked in and out
by a separate process. Please see the next heading.

Checking the project file in or out

The project file is checked in and checked out separately from the rest of
the project. It’s handled slightly differently from other files under VSS
control.

9-4 Team Development Using JBuilder

 Adding and removing files

This command checks it in without a lock, regardless of the administrative

settings regarding regular checkouts. Therefore, the project file will
always be able to be checked out and changed by multiple users. Keeping
it synchronized is important.
JBuilder’s version control integrations require a project file of the .jpx
type, for programmatic reasons that make it easier to work with in a
shared environment. The .jpx project file is an XML file type. However,
it’s handled by VSS as a binary file, in order to maintain the validity of the
project file values. When you check in or check out the project file, the old
settings are overwritten. There’s no attempt to merge them with the new
ones, since that could result in meaningless values.
As used in the VSS integration, the project file controls path settings:
source, test, output, library, and backup paths. Local project settings, such
as doc author and runtime configurations, are not affected by the
synchronization. JBuilder handles this distinction behind the scenes.
Note Only the active project file in the current project directory is treated
specially by the version control integration. Child project files are checked
in and out as normal binary files.

Adding and removing files

Adding files
Adds files to the VSS database and logs the comment you type for the
addition. JBuilder uses an unadorned ss -add command for each file, so if
you want to apply options, use the command line.

Removing files
Removes files from the VSS database. Logs the comment you type.
JBuilder uses an unadorned ss -remove command for each file, so if you
want to apply options, use the command line.
Keep two things in mind:
• Files removed this way can be recovered using VSS’s Recover
command. This command is not supported by JBuilder out of the box.
• Files are removed only from the database, not from the JBuilder project.
In order to remove files from the directory and no longer see their
nodes in the project pane, use the Remove From Project command in
the project pane.

Programmer’s guide to the VSS integration 9-5

Checking in the entire project

Checking in the entire project

JBuilder provides browsers that can display pertinent version control
information and execute commands on many files at once. Both the Status
Browser and the Commit Browser query VSS for the status and repository
version of each changed file, and combine that information with
information that JBuilder already has from your work session.
All the VSS commands that are used by these browsers have already been
discussed. They do exactly what you’d expect, based on the information
presented so far: Add passes an unadorned -add command, and so on. The
purpose of the browsers is to bring together all of the supported VSS
commands and the information you need to choose the right one, in order
to maximize productive time and minimize time spent dealing with
version control responsibilities.

Using the Status Browser

The Status Browser is primarily a viewing tool: it displays the VSS status
of each changed file, the source for each available version, and differences
between, for instance, work area and database versions. The only VSS
command used is the status query for each changed, added, or removed
file.
Unchanged files and directories don’t show in the Status Browser.
Directories and files you don’t want to see are hidden as well. Set these
using the File Include Lists page.

Using the Commit Browser

The Commit Browser provides all of the same functions as the Status
Browser. It also allows you to set the command you want to apply to each
individual file, enter comments for individual files and for the whole
group, then execute all of the commands with one click. JBuilder passes
the commands, the comments, and the files they apply to behind the
scenes. In the case of a very large checkin, having a local VSS client
improves performance.
Note Comments for each file may be viewed from the History Info page in the
content pane of the JBuilder IDE. Other history pages provide views of
previous revisions and allow you to edit the current buffer version.

9-6 Team Development Using JBuilder

 Version labeling

Version labeling
Version labels, or tags, allow you to take a snapshot of the entire project at
any point in time. Since different files change at different rates, a project of
100 files can contain 100 different current revision numbers. Version labels
allow you to mark the whole project without regard for the revision status
of any individual files.
Version labels are typically used to mark milestones such as releases and
other important stages in a project’s lifecycle.
JBuilder applies the tag exactly as you type it to all of the files in the active
project. If necessary, tags can be altered using Visual SourceSafe.

Checking in a new project

If JBuilder doesn’t know where to find the runtime, the first step of this
wizard prompts the user for that location. Once this path is set, that step of
the wizard no longer appears in subsequent uses.
The usual first two steps of this wizard are Select Visual SourceSafe
Database Directory and Enter Username And Password. These are also
the first two steps of the Pull Project From Visual SourceSafe wizard, and
are discussed in that section. Both wizards use these steps identically.

Choosing what to include in the checkin

The Select Directories And Files To Include/Exclude step controls what’s
included in the checked-in project. Expand nodes that can be expanded to
view their contents. Backup and output directories are excluded by
default, but that can be changed. The project file is required by JBuilder to
maintain shared settings, so it’s checked for inclusion and grayed out so it
can’t be changed.

Choosing which files to check out

The Select Files To Keep Checked Out step tells JBuilder which files to
check back out to you after the project is checked in. This just means
JBuilder applies a checkout command to the selected files immediately
after the checkin command has been applied to the project.

Programmer’s guide to the VSS integration 9-7

Checking in a new project

Setting the project root in the database

The Select Location In VSS Database step sets the path to the root
directory in the database and names the project in VSS. You must choose
an existing root directory. This wizard doesn’t create root directories for
you.
The final page of the wizard displays stdout output from the commands
passed to VSS.

See also
• “Configuring the database connection” on page 9-1 to learn about the
first steps of this wizard when it’s first used.
• “Using the Select Visual SourceSafe Database Directory step” on
page 9-2 to learn about the Select Visual SourceSafe Database Directory
step, which becomes the first step for all subsequent uses after the
runtime path is set.
• “Using the Enter Username And Password step” on page 9-3 to learn
about the first steps of this wizard when it’s first used.

9-8 Team Development Using JBuilder

 Chapter

Rational ClearCase in JBuilder

Chapter10
10
This is a feature of JBuilder’s integration of Rational ClearCase allows you to perform the
JBuilder Enterprise. most common version control tasks from within the development
environment. JBuilder simplifies some tasks, such as adding nested
directories: JBuilder recursively adds the subdirectories and files you
select, so you don’t have to add each one individually.
ClearCase commands are generally available from two places in the IDE:
the Team menu from the main menu bar, and the context (right-click)
menu in the project pane. JBuilder provides support for Base ClearCase
and dynamic views.
ClearCase in JBuilder is supported on Windows, Solaris, and Linux. This
integration was designed and tested on ClearCase version 4.1. All
instructions assume that you have a compatible ClearCase client installed
and configured on your machine and that you have appropriate access to
a compatible ClearCase server. If you have questions about your
ClearCase installation, please contact your ClearCase administrator.

Note for Linux users

The ClearCase integration is developed and tested on RedHat Linux 6.2.
To use ClearCase on Linux,
• Install the kernel patch from Rational and recompile the kernel in order
to install ClearCase on Linux.
• Put the cleartool command in the PATH in order to enable ClearCase
support in JBuilder.
Support for Linux clients is available as of ClearCase v. 4.1; prior versions
only support servers.

Rational ClearCase in JBuilder 10-1

Selecting ClearCase as your version control system

Selecting ClearCase as your version control system

A JBuilder project must be under ClearCase control before ClearCase
commands become available. There are two ways to ensure this: pull an
existing project from the repository and configure the connection
automatically, or select ClearCase by hand from an open project.
To select ClearCase by hand from an open project,
1 Select Team|Select Project VCS. The Select Project VCS dialog box
appears:

2 Choose ClearCase from the dialog.

3 Click OK or press Enter to close the dialog box.
This populates the Team menu with appropriate commands and makes
the ClearCase menu available from the context (right-click) menu in the
project pane.

Viewing the connection

Once the connection has been used, you can view it by selecting Team|
Configure ClearCase. It shows the configuration of ClearCase as returned
by the cleartool -version command.

10-2 Team Development Using JBuilder

 Chapter

Working on an existing project

Chapter11
11
in ClearCase
JBuilder supports creating a VOB, mounting a VOB, checking files in and
out, undoing a checkout, and labeling projects. JBuilder also provides a
merge mechanism to support checkins of files that have been modified on
the server since your last checkout.

Pulling an existing project (mounting a VOB)

There are two possible ways to mount a VOB from within JBuilder: from
the object gallery or from the Team menu. (This is the only ClearCase
command available from the object gallery.)
From the object gallery:
1 Select File|New. The object gallery appears.
2 Choose the Project tab.
3 Choose Pull Project From ClearCase.
4 Double-click the icon, click OK, or press Enter to start the Pull Project
From ClearCase wizard.

From the Team menu:

1 Select Team|Pull Project From ClearCase.
Both of these ways access the New Project From ClearCase VOB/
Repository wizard. This wizard provides drop-down lists for the available
VOBs and views.

Working on an existing project in ClearCase 11-1

Checking out a file

Using the Pull Project From ClearCase wizard

Once the wizard is invoked,
1 From the drop-down list in the VOB field, choose the VOB you want to
mount.
2 From the View field, type in or choose the view you want to start.
3 If necessary, change the Drive For Views field so it points to the drive
your target view is in.
4 Auto-save Files Before Checkin automatically saves modified files
before executing a checkin command. By default, this option is on, but
uncheck it if you’d rather be prompted to save modified files when you
check them in.
5 Click OK or press Enter.
JBuilder gets the associated .jpx project file and puts the files it refers to
into your view. If there is no associated .jpx file, JBuilder creates one and
puts the files from that VOB into the new JBuilder project. The new project
file becomes part of the project.
JBuilder remembers each view that you use and, in subsequent uses, adds
it to the drop-down list of views available in this wizard.
Tip JBuilder automatically restarts all the views used previously to manage a
JBuilder project. To keep JBuilder’s list of views current, remove views
from within JBuilder’s IDE.

Checking out a file

Checking out a file makes it writable to the person who has it checked out.
More than one user at a time can have the same files checked out.
In JBuilder, the Check Out command is available from the Team menu
and from the context menu in the project pane.
From the Team menu,
1 Select Team|Check Out “<Filename>”

To check out files by using the context menu,

1 Select the file or files in the project pane.
Use the Ctrl key or the Shift key to select more than one file.
2 Right-click on any selected file.

11-2 Team Development Using JBuilder

 Posting changes to a single file or set of files

3 Select ClearCase from the context menu.

The submenu that appears applies to all of the selected files.
4 Select the Check Out Files command from the submenu.
The files are checked out to you.
JBuilder automatically checks out the parent directory of the files that are
checked out.

Undoing a checkout
Undo Checkout revokes your write access and discards the changes you
made to a file since you checked it out. In JBuilder, this command is
available from the Team menu and from the context menu in the project
pane.
From the Team menu,
1 Select Team|Undo Checkout “<Filename>”

To undo checkouts on files by using the context menu,

1 Select the file or files in the project pane.
Use the Ctrl key or the Shift key to select more than one file.
2 Right-click on any selected file.
3 Select ClearCase from the context menu.
The submenu that appears applies to all of the selected files.
4 Select the Undo Checkout command from the submenu.
Your write access to those files is revoked and the changes you made are
discarded.

Posting changes to a single file or set of files

The Check In command is available from the Team menu and from the
context menu in the project pane.
From the Team menu,
1 Select Team|Check In “<Filename>”

To add files by using the context menu,

1 Select the file or files in the project pane.
Use the Ctrl key or the Shift key to select more than one file.

Working on an existing project in ClearCase 11-3

Posting changes to a single file or set of files

2 Right-click on any selected file.

3 Select ClearCase from the context menu.
The submenu that appears applies to all of the selected files.
4 Select the Check In Files command from the submenu.
The Check In Files dialog box appears. Look at the list of files and make
sure it matches what you intended.
5 Type a comment in the Description Of Changes field according to your
usual practices.
6 Check or uncheck the Keep Files Checked Out option. This option
checks the files back out to you immediately after the checkin, so you
can continue to work on them. This option is checked by default.
7 Click OK to check in the files.
8 Click OK to close the dialog.

Merging differences between versions

When the Check In command is used, JBuilder looks for updates before
checking the modified files in. If files have been changed by others since
you last checked them out, those files are displayed in the Merging Files
dialog box. The Merging Files dialog box asks you to choose between
merging the differences and then checking in the files, or canceling the
checkin on the files that have changed in both places.
If the Merge Files dialog box appears when you check files in, look at the
files affected by the merge. If you want to merge them, click OK to merge
or click Cancel to keep your local version of the files without checking
them in yet.
If you click OK, JBuilder will merge the files. This is normally
straightforward, and each file becomes one unified version incorporating
both sets of changes.
Occasionally, there may be a merge conflict. This happens when there’s a
difference between workspace and server versions in the same physical
part of a file. JBuilder displays files with merge conflicts in another dialog
box, and does not check them in. Merge conflicts must be resolved within
ClearCase.
Files that don’t need merging will be checked in normally, regardless of
how many other files in the list need merging.

11-4 Team Development Using JBuilder

 Adding a new file

Adding a new file

New files and directories often get added to the project. If these file system
components are created inside a ClearCase view, they are seen as view
private elements. They need to be added to the VOB so that they can be
shared. The Add command in JBuilder is available from the Team menu
and from the context menu in the project pane.
From the Team menu,
1 Select Team|Add “<Filename>”

To check in files by using the context menu,

1 Select the file or files in the project pane.
Use the Ctrl key or the Shift key to select more than one file.
2 Right-click on any selected file.
3 Select ClearCase from the context menu.
The submenu that appears applies to all of the selected files.
4 Select the Add Files command from the submenu.
The files are added to the VOB and become available to other users. They
remain writable to you.
Note A file element can only be added if its directory tree is under ClearCase;
therefore, when you add a file inside of a directory that’s not under
ClearCase, JBuilder traverses up the tree until it finds a directory that is
under ClearCase. Then it adds the new directory structure under that
parent directory, and adds the file you selected in the appropriate place in
the tree.

Version labeling (tagging)

Tags, or version labels, allow you to take a snapshot of the entire project at
any point in time. Since different files change at different rates, a project of
100 files can contain 100 different current revision numbers. Tags let you
mark the evolution of the entire project without reference to changes in
individual files. To apply one,
1 Select Team|Version Label.
2 Enter the name of the label you want to apply.

Working on an existing project in ClearCase 11-5

Version labeling (tagging)

3 Enter a comment describing the label, according to your usual

practices.
4 Click OK to close the dialog.
The label is applied to all files in the project.
Note JBuilder rolls the two steps of applying for the tag and creating it into one
visible step.

11-6 Team Development Using JBuilder

 Chapter

Working on a new project

Chapter12
12
in ClearCase
In the Rational ClearCase integration, the key task available for working
on a new project is creating a new VOB.

Placing a new project into ClearCase

These instructions assume you have the ClearCase access to create a VOB.
Once you have created a new project and chosen ClearCase as the version
control system to use for it, create a new VOB for the project by selecting
Team|Place Project Into ClearCase. The Place Project wizard shows.
To use the wizard,
• Type in the new VOB’s name in the Tab field.
This is how ClearCase refers to the project on your client.
• Type in or select the path to the physical location of the new VOB on
your server in the Storage Path field.
• Type in or select the name of an existing view to use to access the new
VOB in the View field.
• Type your password for ClearCase access into the ClearCase Registry
Password field.
If you have suitable access, JBuilder proceeds. If not, please contact
your ClearCase administrator.
• Type a description of what you’re doing in the Comment field,
according to your usual practices.

Working on a new project in ClearCase 12-1

Working with views

• Click Next to proceed to Step 2, which displays output on the process of

creating the VOB and alerts you when the process is complete.
• Click Finish to close the wizard.
Note JBuilder preserves the original work space; therefore, after it creates the
new VOB, it copies files into the VOB rather than moving them from the
original workspace. All source and non-generated resource files in the
project are copied into the VOB.

Working with views

JBuilder provides a ClearCase View Editor which displays views, their
paths, and their content. To access it, select Team|Edit/Add Views.
Select a view in the list to see its content displayed in the View Content
field below. The View Content field is editable, so you can modify any
view you use at any time.
To delete a ClearCase view,
1 Select the view in the Views table.
2 Click the Delete button.
The view disappears from the table.
3 Click OK to close the dialog box.

Adding new views

JBuilder supports creating new ClearCase views:
1 Select Team|Edit/Add Views to access the ClearCase View Editor.
2 Click the Add button.
The Create New View dialog box appears.
3 Name the view.
4 Enter the view’s path.
5 Click OK to close the dialog.
The new view and its path appear in the table.
6 Click OK to close the ClearCase View Editor.

12-2 Team Development Using JBuilder

 Working with views

Editing existing views

JBuilder allows you to change the path and name of a view that you have
just created:
1 Select Team|Edit/Add Views to access the ClearCase View Editor.
2 Select a newly-created view from the View table.
This enables the Edit button.
3 Click the Edit button.
4 Alter the view’s name or path in the Edit View dialog box.
5 Click OK to close the dialog.
The altered view is visible in the Path column of the view table.
Note Once you click OK in the ClearCase View Editor, the name and path of the
new view are permanent. They can be deleted but can no longer be edited.

Working on a new project in ClearCase 12-3

12-4 Team Development Using JBuilder
 Chapter

Version control reference

Chapter13
13
This is a feature of These resources provide more information on version management
JBuilder SE and generally and more assistance with the different version control tools
Enterprise supported by JBuilder.
Please see “Contacting Borland developer support” on page 1-5 for
information on helpful JBuilder and Borland links and newsgroups.
The version control system has a published API. You can use it to
customize an existing integration or to design your own. To do so,
1 Select Help|Help Topics.
2 In the Contents page of the help viewer, open JBuilder OpenTools
Documentation.
3 Start with the first chapter, “Developing OpenTools”. The documents
under this heading explain the APIs conceptually. This information
makes it much easier to approach the APIs and get the most out of
them.
4 Open the next chapter, “JBuilder OpenTools API Documentation”.
Read the introductory material for information on the structure and use
of the API documentation.
5 Open the com.borland.primetime.teamdev packages.
These tell you how to integrate your own version control tool into the
JBuilder IDE or customize the existing integrations.
There are other APIs available from Help|JBuilder OpenTools Links, but
the version control API is not one of them.

Version control reference 13-1

General revision management resources

General revision management resources

Comparisons of tools:
CM Yellow Pages:
http://www.cmtoday.com/yp/configuration_management.html

Resources for supported tools

CVS
List of newsgroups: http://www.cvshome.org/communication.html
CVS Home: http://www.cvshome.org/
CVS documentation: http://www.cvshome.org/docs/manual/
index.html
User information: http://www.devguy.com/fp/cfgmgmt/cvs/
Special considerations:
• Get CVS for various platforms from the source:
http://www.cvshome.org/dev/codes.html
• Windows user FAQ:
http://www.computas.com/pub/wincvs-howto/
• CVS for NT: http://www.cvsnt.org/ (home page)
• CVS for the Mac (see the OpenTools documentation to extend
JBuilder’s capabilities): http://www.maccvs.org/ (home page)

Rational ClearCase
This is a feature of Home page: http://www.rational.com/products/clearcase/index.jsp
JBuilder Enterprise

Visual SourceSafe
This is a feature of Home page: http://msdn.microsoft.com/ssafe/
JBuilder Enterprise
Special considerations:
• On UNIX (see the OpenTools documentation to extend JBuilder’s
capabilities):
http://www.mainsoft.com/products/visualsourcesafe.html

13-2 Team Development Using JBuilder

 Index
B N
Borland newsgroups 1-6
contacting 1-5 Borland 1-6
Borland Online 1-5
O
C online resources 1-5
ClearCase integration 10-1
See also version control, ClearCase R
Commit Browser
in CVS 3-7 revision management 1-1
in VSS 7-11 See also version control
contacting Borland 1-5
newsgroups 1-6 S
World Wide Web 1-5
security
CVS Helper 5-7
CVS Helper 5-9
See also version control, CVS
selecting version control systems
CVS integration 2-1
CVS 4-1
See also version control, CVS
setting environment variables 5-9
Status Browser
D in CVS 3-5
developer support 1-5 in VSS 7-9
documentation conventions 1-2
Macintosh-specific 1-4 T
platform conventions 1-4
Team Development 1-1
See also version control
E technical support 1-5
environment variables 5-9
U
F Usenet newsgroups 1-6
file types
associating 5-9 V
fonts
version control
JBuilder documentation conventions 1-2
how it works 1-2
resources and bookmarks 13-1
G version control, ClearCase 10-1
glossary adding new files 11-5
CVS terms 2-2 applying tags 11-5
checking in files 11-3
M checking out 11-2
creating a new VOB 12-1
Macintosh menus 10-2
support in JBuilder 1-4 merging workspace and server versions 11-4
merge conflicts mounting a VOB/pulling a project 11-1
reconciling in CVS 3-11 New Project From ClearCase VOB/Repository
modules, creating in CVS 4-1 wizard 11-2
undo checkout 11-3
using on Linux 10-1

Index I-1
 viewing the connection 10-2 reconciling merge conflicts 3-11
views 12-2 removing files 3-14
views, adding 12-2 selecting CVS 4-1
views, deleting 12-2 Status Browser dialog 3-5
views, editing 12-3 updating files 3-10
version control, CVS 3-1 updating the project 3-12
adding files 3-13 using watches and edits 3-16
checking file status 3-15 version labelling 3-15
checking out modules 3-2 watches and edits 3-15
Commit Browser Action options 3-8 version control, VSS 6-1
committing files 3-4 adding files 7-7
committing the project 3-7 checking in files 7-6
configuring connection 2-1 checking in the entire project 7-11
creating local repositories 4-4 checking out a project 7-1
CVS Helper 5-7 checking out files 7-3
CVS Helper security 5-9 Commit Browser, Action options 7-12
CVS Helper technical information 5-8 configuring project connection 6-1
CVSROOT syntax 5-10 creating a version label 7-14
environment variables 5-9 File Include lists 7-10
File Include lists 3-6 placing project into database 8-1
finding a tagged conflict 3-11 posting .jpx files 7-6
glossary 2-2 programmer's guide 9-1
handling binary files 5-9 pulling .jpx files 7-5
managing file status 3-15 removing files 7-8
modules, creating 4-1 source views 7-12
overview 2-1 Status Browser 7-9
programmer's guide to integration 5-1 undoing a file checkout 7-4
programmer's guide, project checkin 5-5 views in ClearCase 12-2
programmer's guide, pull project 5-3 See also version control, ClearCase
programmer's guide, pulling project file 5-4 Visual SourceSafe integration 6-1
pulling and posting the project file 3-13 See also version control, VSS
querying repository 5-7 VSS integration 6-1
reconciling conflicts automatically 3-12 See also version control, VSS
reconciling conflicts manually 3-12

I-2 Team Development Using JBuilder