IBM - Rational XDE Guide To Team Development For Windows

Rational Software Corporation ®
Rational XDE
Guide to Team Development
VERSION: 2003.06.00
PART NUMBER : G126-5387-00
WINDOWS
support@rational.com
http://www.rational.com
Legal Notices
Copyright ©2003, Rational Software Corporation. All rights reserved.
Part Number: 800-026181-000
Version Number: 2003.06.00
This manual (the "Work") is protected under the copyright laws of the United States and/or
other jurisdictions, as well as various international treaties. Any reproduction or distribution of
the Work is expressly prohibited without the prior written consent of Rational Software
Corporation.
The Work is furnished under a license and may be used or copied only in accordance with the
terms of that license. Unless specifically allowed under the license, the Work or copies of it may
not be provided or otherwise made available to any other person. No title to or ownership of
the manual is transferred. Read the license agreement for complete terms.
Rational Software Corporation, Rational, Rational Suite, Rational Suite ContentStudio, Rational
Apex, Rational Process Workbench, Rational Rose, Rational Summit, Rational Unified process,
Rational Visual Test, AnalystStudio, ClearCase, ClearCase Attache, ClearCase MultiSite,
ClearDDTS, ClearGuide, ClearQuest, PerformanceStudio, PureCoverage, Purify, Quantify,
Requisite, RequisitePro, RUP, SiteCheck, SiteLoad, SoDa, TestFactory, TestFoundation, TestMate
and TestStudio are registered trademarks of Rational Software Corporation in the United States
and are trademarks or registered trademarks in other countries. The Rational logo, Connexis,
ObjecTime, Rational Developer Network, RDN, ScriptAssure, and XDE, among others, are
trademarks of Rational Software Corporation in the United States and/or in other countries.
All other names are used for identification purposes only and are trademarks or registered
trademarks of their respective companies.
Portions covered by U.S. Patent Nos. 5,193,180 and 5,335,344 and 5,535,329 and 5,574,898 and
5,649,200 and 5,675,802 and 5,754,760 and 5,835,701 and 6,049,666 and 6,126,329 and 6,167,534
and 6,206,584. Additional U.S. Patents and International Patents pending.
U.S. Government Restricted Rights

Licensee agrees that this software and/or documentation is delivered as "commercial computer
software," a "commercial item," or as "restricted computer software," as those terms are defined
in DFARS 252.227, DFARS 252.211, FAR 2.101, OR FAR 52.227, (or any successor provisions
thereto), whichever is applicable. The use, duplication, and disclosure of the software and/or
documentation shall be subject to the terms and conditions set forth in the applicable Rational
Software Corporation license agreement as provided in DFARS 227.7202, subsection (c) of FAR
52.227-19, or FAR 52.227-14, (or any successor provisions thereto), whichever is applicable.
Warranty Disclaimer
This document and its associated software may be used as stated in the underlying license
agreement. Except as explicitly stated otherwise in such license agreement, and except to the
extent prohibited or limited by law from jurisdiction to jurisdiction, Rational Software
Corporation expressly disclaims all other warranties, express or implied, with respect to the
media and software product and its documentation, including without limitation, the
warranties of merchantability , non-infringement, title or fitness for a particular purpose or
arising from a course of dealing, usage or trade practice, and any warranty against interference
with Licensee's quiet enjoyment of the product.
Third Party Notices, Code, Licenses, and Acknowledgements
Portions Copyright ©1992-1999, Summit Software Company. All rights reserved.
Microsoft, the Microsoft logo, Active Accessibility, Active Client, Active Desktop, Active
Directory, ActiveMovie, Active Platform, ActiveStore, ActiveSync, ActiveX, Ask Maxwell,
Authenticode, AutoSum, BackOffice, the BackOffice logo, bCentral, BizTalk, Bookshelf,
ClearType, CodeView, DataTips, Developer Studio, Direct3D, DirectAnimation, DirectDraw,
DirectInput, DirectX, DirectXJ, DoubleSpace, DriveSpace, FrontPage, Funstone, Genuine
Microsoft Products logo, IntelliEye, the IntelliEye logo, IntelliMirror, IntelliSense, J/Direct,
JScript, LineShare, Liquid Motion, Mapbase, MapManager, MapPoint, MapVision, Microsoft
Agent logo, the Microsoft eMbedded Visual Tools logo, the Microsoft Internet Explorer logo, the
Microsoft Office Compatible logo, Microsoft Press, the Microsoft Press logo, Microsoft
QuickBasic, MS-DOS, MSDN, NetMeeting, NetShow, the Office logo, Outlook, PhotoDraw,
PivotChart, PivotTable, PowerPoint, QuickAssembler, QuickShelf, RelayOne, Rushmore,
SharePoint, SourceSafe, TipWizard, V-Chat, VideoFlash, Visual Basic, the Visual Basic logo,
Visual C++, Visual C#, Visual FoxPro, Visual InterDev, Visual J++, Visual SourceSafe, Visual
Studio, the Visual Studio logo, Vizact, WebBot, WebPIP, Win32, Win32s, Win64, Windows, the
Windows CE logo, the Windows logo, Windows NT, the Windows Start logo, and XENIX, are
either trademarks or registered trademarks of Microsoft Corporation in the United States
and/or in other countries.
Sun, Sun Microsystems, the Sun Logo, Ultra, AnswerBook 2, medialib, OpenBoot, Solaris, Java,
Java 3D, ShowMe TV, SunForum, SunVTS, SunFDDI, StarOffice, and SunPCi, among others, are
trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.
Purify is licensed under Sun Microsystems, Inc., U.S. Patent No. 5,404,499.
Licensee shall not incorporate any GLOBEtrotter software (FLEXlm libraries and utilities) into
any product or application the primary purpose of which is software license management.
BasicScript is a registered trademark of Summit Software, Inc.
Design Patterns: Elements of Reusable Object-Oriented Software, by Erich Gamma, Richard
Helm, Ralph Johnson and John Vlissides. Copyright © 1995 by Addison-Wesley Publishing
Company, Inc. All rights reserved.
Additional legal notices are described in the legal_information.html file that is included in your
Rational software installation.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
Other Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
XDE Integrations With Other Rational Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx
Contacting Rational Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi
1 Using This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23

Understanding Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Roadmap: Chapters and Applicable Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2 Planning a Configuration Management Environment . . . . . . . . . . . . .27

Understanding Your Configuration Management Needs . . . . . . . . . . . . . . . . . . . . . . 27
Increasing Software System Complexity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Increasing Project Environment Complexity . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Identifying Configuration Management Needs . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Basic Version Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Parallel Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Automated Workspace Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Automated Build and Release Management . . . . . . . . . . . . . . . . . . . . . . . . 31
Component-Based Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Activity-Based Configuration Management . . . . . . . . . . . . . . . . . . . . . . . . . 32
How Parallel Development Can Help Your Team . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Maintaining an Existing Release While Developing the Next Release . . . . . . . . 32
Developing Multiple Releases and Multiple Patch Streams . . . . . . . . . . . . . . . . 33
Controlling the Rate of Change Within a Project . . . . . . . . . . . . . . . . . . . . . . . . 33
Allowing Teams to Experiment with Extending the Architecture . . . . . . . . . . . . . 34
Other Examples of Isolating Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Controlling Releases Within a Development Group . . . . . . . . . . . . . . . . . . . . . . 35
Planning for Geographically Distributed Development . . . . . . . . . . . . . . . . . . . . . . . 35
Planning the Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Planning Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Planning the Technology Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Implementation Technologies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Infrastructure Technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
v
3 Working Without Configuration Management. . . . . . . . . . . . . . . . . . . 39
The Analyst Role. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Sharing Files by E-Mail or in Common Directories . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Sharing Models Without a Configuration Management System . . . . . . . . . . . . . . . . 40
Recognizing That You Need to Use Configuration Management . . . . . . . . . . . . . . . 41
4 Planning Model Partitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Understanding Model Partitioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Deciding Whether to Partition Models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Benefits of Model Partitioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Faster Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Less Merging: Faster Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Drawbacks of Model Partitioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Out-of-Context Merging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Discrepancies With Logical Elements and Physical Representations . . . . . 45
Moving Files With XDE and ClearCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Balancing the Benefits and Drawbacks of Model Partitioning . . . . . . . . . . . . . . 46
Model Partitioning Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
When to Decompose a Model Into Subunits . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Determining Candidates for Separate Storage Units . . . . . . . . . . . . . . . . . . . . . 47
Minimizing the Dependencies Between Units . . . . . . . . . . . . . . . . . . . . . . . 47
Creating Separate Units for Complex Diagrams . . . . . . . . . . . . . . . . . . . . . 47
Partitioning Stable Abstraction Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Developing an Ownership Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Model Ownership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Package Ownership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Subunit Ownership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Avoiding Merges When Separating or Combining Model Elements . . . . . . . . . . 50
5 Comparing and Merging Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Working With ClearCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Merging Models With ClearCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Merging Silently . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Merging Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Triggering Multiple Model Merge Sessions . . . . . . . . . . . . . . . . . . . . . . . . . 52
Working With Other Configuration Management Systems . . . . . . . . . . . . . . . . . . . . 53
Working With Subunits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Moving Model Elements From the Model Explorer . . . . . . . . . . . . . . . . . . . . . . . 54
Moving Model Elements From Outside the Model Explorer . . . . . . . . . . . . . . . . 54
vi Rational XDE Guide to Team Development

Working With Packages . . . . . . . . . . . . . . . . . . . . . ....... ...... ....... .. 54
Referencing Model Elements In Other Subunits . . ....... ...... ....... .. 55
Combining Separated Units . . . . . . . . . . . . . . . . . . ....... ...... ....... .. 55
Setting Preferences . . . . . . . . . . . . . . . . . . . . . . . . ....... ...... ....... .. 55
Understanding Automatic XDE Compare/Merge Sessions . . . . . . . . . . . . . . . . . . . 55
Starting an XDE Compare/Merge Session Automatically . . . . . . . . . . . . . . . . . 56
Starting a Session In a New XDE Instance . . . . . . . . . . . . . . . . . . . . . . . . . 56
Starting a Session In an Existing XDE Instance . . . . . . . . . . . . . . . . . . . . . 57
Understanding the Results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Ending the Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Understanding Manual XDE Compare/Merge Sessions. . . . . . . . . . . . . . . . . . . . . . 58
Starting an XDE Compare/Merge Session Manually . . . . . . . . . . . . . . . . . . . . . 59
Selecting Contributors and Base Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Models With a Common Ancestor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Models Without a Common Ancestor (Fusing) . . . . . . . . . . . . . . . . . . . . . . 61
Alternate Workflow: Merging More Than Two Contributors And a
Base Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Selecting Subunits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Understanding the Results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Ending the Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Understanding the Results of an XDE Compare Session . . . . . . . . . . . . . . . . . . . . 63
Understanding Model Element Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Matching Elements By GUID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Matching Elements By Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Exceptions To Matching By Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Matching Elements When Fusing Models . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Identifying Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Detecting Moved or Changed Model Elements . . . . . . . . . . . . . . . . . . . . . . . . . 65
Identifying Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Working With the Results of an XDE Merge Session . . . . . . . . . . . . . . . . . . . . . . . . 68
Understanding the Unresolved Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Counting Unresolved Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Counting Unresolved Difference Not Part Of a Conflict . . . . . . . . . . . . . . . . 69
XDE Merge Session Workflow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Resolving Differences Automatically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Understanding Auto-Resolve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Merging With a Common Base Model: Auto-Resolve States . . . . . . . . . . . 70
Merging Without a Common Ancestor Base Model (fusing): Auto-Resolve
States. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Contents vii
Navigating Through Differences and Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Auto-Advance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Merge Phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Manually Resolving Differences and Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Resolving Differences and Conflicts Individually . . . . . . . . . . . . . . . . . . . . . 76
Resolving Several Differences and Conflicts At Once . . . . . . . . . . . . . . . . . 77
Example Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Model Merging Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Updating Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Resolving Conflicts Consistently . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Merge Granularity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Optimizing XDE Compare/Merge Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Optimizing Performance: Key Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Factors That Affect XDE Compare/Merge Performance . . . . . . . . . . . . . . . . . . . 82
Checkin Frequency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Modifying Versus Adding To a Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Other Factors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Evaluating Risk Factors Early In the Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Example Scenarios. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Working With a Single Branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Working With a Main Branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Working With UCM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Working Without Configuration Management . . . . . . . . . . . . . . . . . . . . . . . 85
Working In Parallel Development: Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Merging Into the Common Model Separately. . . . . . . . . . . . . . . . . . . . . . . . 86
Example: Working In Parallel Development . . . . . . . . . . . . . . . . . . . . . . . . . 86
6 Understanding the Rational XDE Compare/Merge User Interface . . 89

The Comparative Model Explorers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Element Order In the Comparative Model Explorer . . . . . . . . . . . . . . . . . . . . . . 91
Unnamed Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Generalized Icons For Specialized Element Types. . . . . . . . . . . . . . . . . . . . . . . 92
Difference Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Conflict Icons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Resolution Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
The Comparative Property Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
The Comparative Property Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
The Differences Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Differences Arranged by Conflict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
viii Rational XDE Guide to Team Development

Conflicts Arranged by Difference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Model Elements Specific to the Comparative Model Explorers . ...... ....... . . 97
Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... ....... . . 97
Tagged Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ...... ....... . . 98
Additional Semantic Model Elements. . . . . . . . . . . . . . . . . . ...... ....... . 100
View Elements Within Diagrams . . . . . . . . . . . . . . . . . . . . . ...... ....... . 100
7 Working With Cross-Model References . . . . . . . . . . . . . . . . . . . . . . . 103

Local and Cross-Model References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Source-Relative References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Working With Source-Relative References . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Working With Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Component-Relative References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ....... . 106
Creating Development Components . . . . . . . . . . . . . . . . . . . . . . . . ....... . 107
Working With Component-Relative References . . . . . . . . . . . . . . . . ....... . 107
Working With Platform Models . . . . . . . . . . . . . . . . . . . . . . . . . ....... . 107
Working With Shared Models Outside of Source Control . . . . . ....... . 108
8 Understanding the Basics of UCM . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

What Is UCM? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
The Building Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Why Use UCM? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Typical Way to Use UCM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
UCM Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
UCM Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Baseline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
ClearCase Basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
VOBs and Their Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Views and Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Using ClearCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Behind the Scenes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
For More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
9 Designing a ClearCase UCM Environment. . . . . . . . . . . . . . . . . . . . . 117

Designing UCM Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
The Elements of Your Design. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Contents ix
System Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Team Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Release Strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Example: Multiple Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Situation 1: Simple . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Situation 2: More Complex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Example: Multiple GUIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Refining the Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Administrative Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Storing Multiple Components in a Single VOB. . . . . . . . . . . . . . . . . . . . . . 120
Managing Complexity: Read-only or Unavailable Components . . . . . . . . . 121
Designing Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Other Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Adding a Component to an Existing Environment . . . . . . . . . . . . . . . . . . . . . . 122
Relating Component Design to Release Planning . . . . . . . . . . . . . . . . . . . . . . . . . 122
Composite Baselines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Promotion Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
10 Scenario: Rational XDE and Base ClearCase With IBM WSAD . . . . 125
Before You Begin: Installing and Configuring Software. . . . . . . . . . . . . . . . . . . . . . 125
Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Setting Up the ClearCase LT 2003 Environment . . . . . . . . . . . . . . . . . . . . 125
Using ClearCase 2003 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Setting Up the User Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Configuring ClearCase Groups and Environment Variables . . . . . . . . . . . 126
Setting Up the ClearCase Environment . . . . . . . . . ...... ....... ...... ..... 127
Planning VOBs . . . . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... ..... 128
Creating VOBs . . . . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... ..... 128
Creating a View . . . . . . . . . . . . . . . . . . . . . . . . ...... ....... ...... ..... 128
Starting XDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Creating a Java Modeling Project and XDE Models . . . . . . . . . . . . . . . . . . . . . . . . 129
Creating a Java Modeling Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Validating Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Creating XDE Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Dividing a Model to Allow Concurrent Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Composite Object Versioning Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Navigator Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Dividing a Model Into Subunits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Adding Java Classes to the Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
x Rational XDE Guide to Team Development

Generating Code for the Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Saving, Validating, and Checking In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Creating a Project Set File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Adding the Project Set File to Source Control . . . . . . . . . . . . . . . . . . . . . . 135
Developing as Part of a Team. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Setting Up the Developers’ Work Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Starting to Work in XDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Adding to the XDE Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Creating Cross-Model References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Importing the Project Set File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Tips for Working with ClearCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Starting Parallel Development: Comparing and Merging Models. . . . . . . . . . . 140
Introducing Conflicts into the Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Resolving the Conflict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Refactoring: Adding, Moving, and Deleting Files . . . . . . . . . . . . . . . . . . . . . . . 142
Resolving Broken Cross-Model References . . . . . . . . . . . . . . . . . . . . . . . . . . 143
11 Scenario: Rational XDE and UCM With IBM WSAD. . . . . . . . . . . . . . 145

Before You Begin: Installing and Configuring Software . . . . . . . . . . . . . . . . . . . . . 145
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Using ClearCase 2003 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Setting Up the User Community. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Setting Up the ClearCase Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Creating the Initial Project VOB and UCM Project . . . . . . . . . . . . . . . . . . . . . . 148
Planning UCM Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Creating VOBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Creating ClearCase Work Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Registering UCM Components as Modifiable . . . . . . . . . . . . . . . . . . . . . . . . . 152
Adding Foundation Baselines to Your UCM Project. . . . . . . . . . . . . . . . . . 152
Changing UCM Project Policies for the UCM Components . . . . . . . . . . . . 153
Synchronizing the Integration Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Recommending a Baseline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Rebasing Your Development Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Starting XDE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Creating a Java Modeling Project and XDE Models . . . . . . . . . . . . . . . . . . . . . . . . 155
Creating a Java Modeling Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Validating Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Contents xi
Navigator Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Adding Java Classes to the Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Generating Code for the Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Saving, Validating, and Checking In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Creating a Project Set File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Adding the Project Set File to Source Control . . . . . . . . . . . . . . . . . . . . . . 162
Delivering to the Integration Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Viewing the ClearCase Branch Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Loading the Project Set in a New View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Testing the Delivery in the Integration View . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Completing the Delivery to the Integration Stream . . . . . . . . . . . . . . . . . . . . . . 165
Creating and Recommending a Baseline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Creating a Baseline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Recommending a Baseline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Developing as Part of a Team . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Joining the UCM Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Adding to the XDE Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Creating Cross-Model References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Delivering to the Integration Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Creating and Recommending a Baseline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Rebasing as dev2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Importing the Project Set File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Tips for Working with ClearCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Starting Parallel Development: Comparing and Merging Models . . . . . . . . . . . 171
Introducing Conflicts into the Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Resolving Broken Cross-Model References . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
12 Scenario: Rational XDE and Base ClearCase With

Microsoft VS.NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
xii Rational XDE Guide to Team Development

Using ClearCase 2003 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Setting Up the User Community. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Setting Up the ClearCase Environment ................... ...... ....... . 179
Planning VOBs. . . . . . . . . . . . . . . . ................... ...... ....... . 180
Working with VS.NET Projects ................... ...... ....... . 180
Creating VOBs . . . . . . . . . . . . . . . . ................... ...... ....... . 180
Creating a View . . . . . . . . . . . . . . . ................... ...... ....... . 181
Creating a VS.NET Solution With XDE Models . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Creating a VS.NET Solution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Creating a Blank Solution within a VOB . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Creating a Visual C# Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Creating a VB.NET Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Creating an IIS Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Creating an ASP.NET Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Adding Code Models to the Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Validating Models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Creating XDE Models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Adding a Getting Started Model to the Solution . . . . . . . . . . . . . . . . . . . . 185
Adding a Blank Model to Each Project . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Composite Object Versioning Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Solution Explorer Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Dividing a Model Into Subunits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Adding the Solution to Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Testing in the Development View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Creating Sample Content. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Checking In all Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Creating IIS Virtual Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Updating Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Contents xiii
Resolving Broken Cross-Model References . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
13 Scenario: Rational XDE and UCM With Microsoft VS.NET . . . . . . . 197

Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Using ClearCase 2003 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Setting Up the User Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Setting Up the ClearCase Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Creating the Initial Project VOB and UCM Project . . . . . . . . . . . . . . . . . . . . . . 200
Planning UCM Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Working with VS.NET Projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Creating VOBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Creating ClearCase Work Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Registering UCM Components as Modifiable. . . . . . . . . . . . . . . . . . . . . . . . . . 205
Adding Foundation Baselines to Your UCM Project . . . . . . . . . . . . . . . . . . 205
Changing UCM Project Policies for the UCM Components . . . . . . . . . . . . 206
Synchronizing the Integration Stream. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Recommending a Baseline. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Rebasing Your Development Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Creating a VS.NET Solution With XDE Models . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Creating a VS.NET Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Creating a Blank Solution within a VOB . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Creating a Visual C# Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Creating a VB.NET Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Creating an IIS Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Creating an ASP.NET Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Adding Code Models to the Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Validating Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Adding a Getting Started Model to the Solution . . . . . . . . . . . . . . . . . . . . . 211
Adding a Blank Model to Each Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Solution Explorer Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Setting Up the Solution in the ClearCase Environment . . . . . . . . . . . . . . . . . . . . . 214
Adding the Solution to Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
xiv Rational XDE Guide to Team Development

Creating Sample Content. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Checking In all Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Delivering to the Integration Stream. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Viewing the ClearCase Branch Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Creating an IIS Alias for the Integration View. . . . . . . . . . . . . . . . . . . . . . . . . . 217
Testing in the Integration View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Opening the Solution in the Integration View. . . . . . . . . . . . . . . . . . . . . . . 218
Creating an ASP.NET Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Testing the Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Completing the Delivery to the Integration Stream . . . . . . . . . . . . . . . . . . . . . 221
Creating and Recommending a Baseline. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Creating a Baseline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Recommending a Baseline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Joining the UCM Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Creating IIS Virtual Directories and ASP.NET Applications . . . . . . . . . . . . 224
Delivering to the Integration Stream. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Creating and Recommending a Baseline. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Rebasing as dev2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Opening the Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Resolving Broken Cross-Model References . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Contents xv
xvi Rational XDE Guide to Team Development
Tables
Table 1 Applicable Roles in This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Table 2 Roadmap: Chapters and Applicable Roles . . . . . . . . . . . . . . . . . . . . 24
Table 3 Software Development Problems and CM Recommendations . . . . . 28
Table 4 Team Characteristics and CM Needs . . . . . . . . . . . . . . . . . . . . . . . . 29
Table 5 Types of Differences Between a Contributor and a Base Model . . . . 65
Table 6 Types of Conflicts Between Contributors and a Base Model . . . . . . . 66
Table 7 Merging with a Common Ancestor: Auto-Resolve States . . . . . . . . . 71
Table 8 Merging without a Common Ancestor Base Model (fusing):
Auto-Resolve States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Table 9 Sample Merge Result With Auto-Resolved Differences . . . . . . . . . . 78
Table 10 Resolving Each Conflict Individually in Favor of Contributor 2 . . . . . 79
Table 11 Applying the Resolve All Using Contributor 2 Command . . . . . . . . . 79
Table 12 Columns in the Comparative Model Explorer . . . . . . . . . . . . . . . . . . 90
Table 13 Difference Icons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Table 14 Sample Conflict Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Table 15 Sample Resolution Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Table 16 Columns in the Comparative Property Browser. . . . . . . . . . . . . . . . . 95
Table 17 Profile-Related Model Elements in the Comparative Model Explorer 98
Table 18 Tagged Value-Related Model Elements in the Comparative Model
Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Table 19 Semantic Model Elements in the Comparative Model Explorer. . . . 100
Table 20 Selected View-Related Model Elements in the Comparative Model
Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Table 21 Creating Source-Relative References Between Projects . . . . . . . . 105
Table 22 Starting the Design Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
xvii
xviii Rational XDE Guide to Team Development
Preface
This manual provides information on planning, setting up, and working in a Rational
XDE team development environment. This manual also includes sample workflows
that describe how to integrate XDE with Rational ClearCase.
Audience
This manual is intended for administrators, project managers, and all members of the
software development team, including configuration managers, software architects,
and developers.
Other Resources
■
All manuals are available online, either in HTML or PDF format. The online
manuals are on the Rational Solutions for Windows Online Documentation CD.
■
To send feedback about documentation for Rational products, please send e-mail
to techpubs@rational.com.
■
For more information about Rational Software technical publications, see:
http://www.rational.com/documentation.
■
For more information on training opportunities, see the Rational University Web
site: http://www.rational.com/university.
■
For articles, discussion forums, and Web-based training courses on developing
software with Rational Suite products, join the Rational Developer Network by
selecting Start > Programs > Rational Suite > Logon to the Rational Developer
Network.
xix
XDE Integrations With Other Rational Products
Integration Description Where it is Documented
XDE– You can compare and track different ■

Rational XDE Help topic: Rational
ClearCase model elements, identify the differences ClearCase and Rational XDE
between them, and merge models. Integration
■ Rational XDE Help topic: Working with
Models Under Source Control
■
Rational XDE Help topic: Working with
Rational ClearCase
XDE– You can perform run-time analysis on ■

PurifyPlus applications generated from XDE. PurifyPlus and Rational XDE
Run-time analysis is the execution of Integration
instrumented code and the analysis of ■
Rational XDE Help topic: Tracing
the collected data to find programming Application Execution to Trace
errors and ways to improve software Sequence Diagrams
performance.
XDE– You can associate RequisitePro ■

RequisitePro requirements and documents with XDE RequisitePro and Rational XDE
use cases and models. Integration
■
Rational XDE Help topic: Configuring
Rational XDE Models for Requirements
Integration
XDE– You can launch Extended Help from the ■

Rational Unified Help menu. Extended Help displays Unified Process
Process RUP tool mentors for XDE.
xx Rational XDE Guide to Team Development

Contacting Rational Technical Support
If you have questions about installing, using, or maintaining this product, contact
Rational Technical Support as follows:
Your Location Telephone Facsimile E-mail
North America (800) 433-5444 (781) 676-2460 support@rational.com

(toll free) Lexington, MA
(408) 863-4000
Cupertino, CA
Europe, Middle +31 (0) 20-4546-200 +31 (0) 20-4546-201 support@europe.rational.com

East, Africa Netherlands Netherlands
Asia Pacific +61-2-9419-0111 +61-2-9419-0123 support@apac.rational.com

Australia Australia
Note: When you contact Rational Technical Support, please be prepared to supply the
following information:
■
Your name, company name, telephone number, and e-mail address
■
Your operating system, version number, and any service packs or patches you
have applied
■
Product name and release number
■
Your case ID number (if you are following up on a previously reported problem)
Chapter - Preface xxi

xxii Rational XDE Guide to Team Development
Using This Manual
1
The Rational XDE Guide to Team Development provides information on planning,
setting up, and working in an XDE team development environment.
Understanding Roles
This manual refers to roles that perform team development tasks. The following table
describes these roles.
Table 1 Applicable Roles in This Manual
Role Description
Analyst Defines the system to develop; manages requirements as they change

throughout the project.
Architect Designs initial model steps, model packages, and system model parts.
Configuration Performs all VOB or UCM component administrative steps. In a UCM

Manager environment: promotes version and baseline labels, plans the environment
(including components), and sets up the initial projects.
Network Establishes the user communities. Assists with meeting prerequisites.

Administrator
Tool Completes the tool installation prerequisites.

Administrator
Project Manager Creates UCM reports; tracks metrics.
Developer Adds classes; establishes and maintains file directories; manages personal
ClearCase environment.
Tester (and Outside of the scope of this manual.

other roles)
23
The correspondence of these roles to the people on your project varies depending on
the size of your project:
■
On a small project, one person might play many roles. For example, the person
you think of as the team leader might take on all leader, administrator, and
manager roles, while another two people might act both as architect and
developer.
■
On a medium project, you might work with an IT department that handles
installation and configuration of all tools, while other team members fill the other
roles.
■
On a large project, each role might be filled by multiple people. In this case, you
may want to designate one person on each role-team who serves as an interface to
the other teams.
Roadmap: Chapters and Applicable Roles

Each chapter in this manual is of most interest to only a few roles. The following table
provides a summary of how the contents of this manual map to different roles.
Table 2 Roadmap: Chapters and Applicable Roles
Chapter Applicable Roles
2 Planning a Configuration Management Environment Architect

Configuration Manager
Network Administrator
Project Manager
3 Working Without Configuration Management Analyst

Project Manager
4 Planning Model Partitions Architect

Developer
5 Comparing and Merging Models Developer
6 Understanding the Rational XDE Compare/Merge User Interface
7 Working With Cross-Model References
8 Understanding the Basics of UCM All Roles
24 Rational XDE Guide to Team Development

Table 2 Roadmap: Chapters and Applicable Roles
Chapter Applicable Roles
9 Designing a ClearCase UCM Environment Architect

Configuration Manager
Network Administrator
10 Scenario: Rational XDE and Base ClearCase With IBM WSAD (1) Architect
11 Scenario: Rational XDE and UCM With IBM WSAD(1) Configuration Manager
Developer
12 Scenario: Rational XDE and Base ClearCase With Microsoft
VS.NET(1)
13 Scenario: Rational XDE and UCM With Microsoft VS.NET(1)
(1) These chapters describe sample team development scenarios that may be of interest to all roles.
Chapter 1 - Using This Manual 25

Planning a Configuration
Management
Environment
2
Configuration management (CM) is a software engineering discipline comprising the
tools and techniques (processes or methodology) that a company uses to manage
change to its software assets. The goal of successful CM is to allow change in a
structured, controlled, and repeatable fashion.
Successful CM is achieved through the application of both tools and processes to a
software development project:
■ CM tools are software tools that automate and facilitate the application of the CM
activities.
■ A CM process is the way CM is performed on your project; specifically, how a CM
tool is applied to accomplish a task. The key to a good process is in tailoring it to be
as simple as possible, following standard industry practices.
This chapter describes various CM issues, needs, and features that impact a wide
variety of teams. The contents of this chapter should help your team answer some of
the following questions:
■ What are our current and future CM needs?
■ Do the CM tools and processes we use meet our current needs and will they be
able to meet our future needs? If not, what steps should we take to ensure that
these needs are met?
■ What is the impact to our business if we cannot meet these needs?
Understanding Your Configuration Management Needs

Software projects typically encounter common problems. Although CM systems
cannot solve all of these problems, they can significantly contribute to the solution.
27
Table 3 describes common software development problems and ways that CM can
contribute to the solution.
Table 3 Software Development Problems and CM Recommendations
Problem CM Recommendation
Increasing software system Regularly evaluate and tune your CM processes and use CM
complexity tools that are easily customized and highly scalable. For more
information, see Increasing Software System Complexity on
page 28.
Increasing project Use scalable CM tools and processes. For more information,
environment complexity see Increasing Project Environment Complexity on page 28.
Identifying and meeting team Use CM tools and processes that meet the needs of your team.
needs For more information, see Identifying Configuration
Management Needs on page 29.
It is better to address all key elements of a process in a lightweight manner before

focusing heavily on one particular problem area. After the framework for a quality
process is in place, a project team can then focus on the following major problem
areas:
■
Identify and prioritize risks to the project.
■
Determine early mitigation strategies for those identified risks.
Increasing Software System Complexity

As a software product evolves, it typically increases in complexity, usually with the
addition of more features and functions after the initial design. From a CM
standpoint, the increase in complexity takes several forms:
■
Increase in the size of the software that is being managed.
■
Increase in the complexity of the problems that are to be solved.
■ Increase in the complexity of a maturing architecture.
■ Inclusion of third-party software components.
■ Increase in the number of platforms to support.
Increasing Project Environment Complexity

A project’s development environment grows in complexity as the following changes
occur:
■
An increase in the number and frequency of product releases.

■
An increase in the number of team members.
■
The location of development teams at different sites.
■
A need to support parallel development.
Identifying Configuration Management Needs

This section attempts to describe the CM needs of several broad project categories.
Some projects will not fit exactly into any one of these categories, and some might not
fit into any at all. These categories are meant to provide a context in which to organize
and discuss project needs and CM solutions.
CM needs depend on several factors, including a team’s level of formality and its
geographic distribution. Table 4 provides general guidelines for a team’s CM needs,
based on team size and number of projects.
Table 4 Team Characteristics and CM Needs
Your Team Team Characteristics CM Needs
Small 2 to 5 members working on Basic version control

one project without links to
any other projects
Modest 6 to 15 members, working [All of the above] plus the following:

on one or more products in ■ Parallel development
a family
■ Automated workspace management
■
Automated build and release management
Modest teams can also benefit from component-
and activity-based development.
Major 1 to 10 cooperating teams of [All of the above] plus some or all of the following:
2 to 30 members each, with ■ Component-based development
fewer than 150 total
members, working toward
■ Activity-based configuration management
a common release of one or ■ Geographically distributed development. For
more products in a product more information, see Planning for
family Geographically Distributed Development on
page 35.
Multiple A large number of teams of All of the above

Teams various sizes cooperating
on a release of one or more
products, where the total
number of team members is
150 or more
Chapter 2 - Planning a Configuration Management Environment 29

The remainder of this chapter describes these features of CM in more detail.
Basic Version Control

Basic version control lets you:
■ Maintain a library or repository of files.
■ Create and store multiple versions of files.
■ Lock files (to enforce serialized change to any given file).
■ Identify collections of file versions.
■ Extract/retrieve versions of files from the repositories.
Basic version control is sufficient in software development environments where users
create, own, and maintain separate software system components and rarely need to
change each other’s files. When users need to change each other’s files, they request
permission from the owners of those files.
Parallel Development
Parallel development allows users to work on multiple software releases at the same
time. Multiple users can also work on the same files at the same time. Parallel
development frees users from the constraints of serial development, where one user
completes one task before the next user can begin another. Because users do not own
separate software system components, they do not need to request permission to
change each other’s files.
Parallel development is essential for large teams and teams that share high-traffic
files. Other development environments that can benefit from parallel development
include those in which:
■ Users check out files for long periods of time.
■ Users make changes to interfaces and also update the code that uses those
interfaces.
■ Teams require continuous or frequent builds; to improve reliability, users can test
and build software before they submit the software for a build.
■ Major software interfaces change, which affects the files of multiple users. Users
must carefully coordinate changes to shared files; if they do not, the software
cannot be built.
If you incorporate parallel development into your environment, ensure that the CM
tool you use has good file merging capabilities. When multiple users work on the
same files at the same time, they will eventually make conflicting changes that must
be resolved by a good file merging tool. For more information, see How Parallel
Development Can Help Your Team on page 32.

Automated Workspace Management
Automated workspace management lets project teams automatically create, populate,
and update workspaces. Automated workspace management lets you:
■
Recreate the product directory structure.
■
Populate the directory structure with the right file versions.
■
Update a workspace to include newer versions.
Automated Build and Release Management

Automated build and release management ensures that significant system builds can
be reproduced and maintained. This capability is very important for teams that
require regular builds and maintain many files. Key steps in the build process are as
follows:
1 Identify the versions of the source to be built.
2 Create or populate a clean workspace that selects those versions (and is locked).
3 Perform and audit the build.
4 Stage the files produced by the build and the build audit.
5 Identify the staged files.
6 Produce the necessary media.
If your team wants to automate build and release management, select a CM tool that
supports and automates these steps.
Component-Based Development
Component-based development is the development of a software system by
decomposing it into smaller pieces called components, either during design or while
rearchitecting an existing system.
Components have well-defined interfaces and can have build-time or run-time
dependencies on other components. For CM purposes, you need to be able to do the
following:
■ Identify component versions.
■ Assemble a consistent set of component versions so that you can always create a
version of the system as a whole.

Activity-Based Configuration Management
Activity-based CM is the management of changes to the software system that is based
on higher-level activities, such as tasks, defects, and enhancements, rather than
individual file versions. A tool that supports activity-based CM must let you:
■
Track the file versions that implement the work required for a specific activity.
■
Present activities as a key object in the CM tool.
The idea is to simplify complexity and ensure that systems can manage and verify all
activities (especially defects) that go into specific builds.
How Parallel Development Can Help Your Team

This section gives examples of ways in which teams can use parallel development to
solve potential development problems. If your team is experiencing these problems,
or problems like them, consider setting up your developers to work in parallel with
each other.
Maintaining an Existing Release While Developing the Next Release

Team A completed the release of its V1.0 product last month. During design and
development, the team placed under source control all its artifacts, including
requirements, specifications, models, development environment, source code, build
scripts, documentation, tests, and test harnesses. When they released V1.0, they
labeled, or created a baseline of, the complete set of artifacts related to the product.
They have started work on the next minor enhancement release, V1.1, using the V1.0
code as a starting point. Meanwhile, customers have discovered problems with the
V1.0 release, some critical enough to cause the team to start work on the V1.0a service
pack release. The same people developing V1.1 are also fixing defects on the V1.0a
project.
To work on these two projects simultaneously, the team creates ClearCase branches
from the V1.0 starting place. When developers work on V1.0a, they do not see V1.1
changes. Similarly, when developers work on V1.1, they do not see changes from
V1.0a. The branch structure isolates the two projects.
After V1.0a ships, the team does an inventory to discover what files changed and
what defects were fixed. They schedule an integration to merge all the V1.0a fixes into
the V1.1 branch so that the next release does not introduce regressions.
The Team A developers are maintaining multiple workspaces on different branched
configurations. This scenario is very common and very effective. It illustrates the
fundamental utility of parallel development.

Developing Multiple Releases and Multiple Patch Streams
Now extend the single patch release scenario to consider a product that has multiple
releases in active use. Products generally are required to support several releases to
allow users to migrate gradually to newer software releases. In this example, Team B
is supporting four parallel streams – three patch streams for the releases in the field
and the stream associated with work on the next release. A configuration
management (CM) system that can effectively support parallel development is one
that:
■
Lets a developer configure and load workspaces easily and efficiently.
■
Lets developers and managers identify differences between streams.
■
Automates the process of merging streams together.
Controlling the Rate of Change Within a Project

In this example, Team C is developing a three-tier application, with large teams
dedicated to each tier. Because of the project’s size, the teams have instituted formal
controls over interfaces and protocols to manage the communications between tiers.
The team needs a method to introduce protocol changes to control the rate of change.
The team wants to allow the upper-tier developers to work on a stable base for long
enough to develop their own features. Therefore, the team adopts interface and other
changes from other tiers only at specific times.
Team C decides to institute release management at a sub-product level. The overall
product uses labels such as prod_v1.0_build_xx, but each team can use labeling
conventions such as:
Data_layer_v1.0_build_xx
Services_layer_v1.0_build_xx
Gui_layer_v1.0_build_xx
The team can then control changes by combining builds from different sub-projects, as
illustrated in this scenario:
1 The Services team starts with the Data team’s Build 34. The team integrates and
tests the services layer and releases its own build 12.
2 The Gui team starts with the Data team’s build 34 and the Service team’s build 12.
The team integrates and tests its latest work and creates its own build 29.
3 An integrator combines the three builds and assigns the prod_v1.0_build_1.
4 The test group uses the product’s first build to evaluate development progress.

5 Meanwhile, the data services team works toward the next release, incorporating
new protocols and features on its primary branch. The team can also respond to
critical bugs by branching from earlier versions. This technique helps the team
avoid introducing new features earlier than intended.
Allowing Teams to Experiment with Extending the Architecture

Suppose that on Team D, the database team believes that if it caches queries in a
particularly complex way, it can realize a significant increase in the transaction rates
that it supplies. An architect has prepared an initial proposal for this work, and the
organization has decided to let a few developers investigate the idea further.
The team decides to start with an existing product baseline, which contains three
subsystem baselines. The team uses this initial baseline to obtain a reference
measurement of the system performance. After the team develops the new feature, it
measures the performance of the system with improvements. The team then
compares that measurement to the reference measurement and uses the result to
decide whether the feature is worth incorporating.
Team D creates a small team of six developers to focus on the improvement. The new
team creates a branch off the database baseline it has chosen. When the team finishes
its work, it has these options:
■
If the work does not produce the expected results, the versions on the branch are
abandoned, and work continues on the main line of development.
■
If the work does produce the expected results, the team merges the branch to the
main line of development that the rest of the database team is working on.
Other Examples of Isolating Work

Other situations in which you might want to isolate development work by working
on a branch include the following:
■
Team members reconfigure code to isolate the user-visible text (in dialog boxes
and error messages) so that the text can be translated. Typically, during this
change, you place the user-visible text into its own files.
■
In a banking application, local banking laws might dictate that you need different
algorithms or business rules to represent and manipulate currency. In this case,
you can keep each variant on a separate branch, while maintaining the same build
process for the entire system.
■
A team working with third-party component libraries wants to integrate a newer
version of a component library in isolation, and when they are assured that it is
working correctly, merge it in. By isolating its work, the team avoids introducing
change (and possibly errors) into the larger development community.

■
A team is moving to a new operating system version, compiler version, or
database, and they want to initially isolate all the code changes needed to support
the new software. They work on a separate branch so they can introduce the
change atomically to the large developer base.
Controlling Releases Within a Development Group

In some cases, you may want to use branches to strictly control releases to different
parts of the development group. For example, Team E creates three branches for the
development, test, and production versions of its product:
1 When the development group is ready to release a version to the test group, it
creates a baseline of its branch, and merges from that baselined version of its
branch to the test branch.
2 The test group creates a baseline, tests it, and releases it (by merging) to the
production branch.
3 If the test group finds defects, the development group can fix the defects on
subbranches of the test branch, and then create another baseline of the test branch.
The development group can then merge the fixes on the branch back into the
development group branch.
Planning for Geographically Distributed Development

Geographically distributed development is the development of a software system by
team members or entire teams that work in different locations.
Some of the challenges that affect geographically distributed development include:
■
Organization
■
Communication
■ Technology tools
Planning the Organization

Organization deals with how team members are grouped into projects, who is
responsible for leading the team, how multiple teams are interrelated, who is
responsible for making projectwide decisions, and who is responsible for the success
or failure of the project.

Many distributed development projects fail because they do not establish a unified
organizational structure between teams working at two or more sites. The key
decisions about roles that must be communicated to all team members are:
❑ Identify who is responsible for the overall success of the project.
❑ Identify who is responsible for the managerial issues the project encounters.
❑ Identify who is responsible for the overall system architecture.
❑ Identify all project team members.
Planning Communication
To communicate effectively in a geographically distributed environment, teams must
have a common vision of how the system will work, expressed in an agreed-upon
system architecture. Teams must carefully plan how they divide and assign features
for development.
To develop a good communication environment, you must:
❑ Establish a system architecture.
❑ Divide your architecture into components that can be developed separately.
❑ Assign each developmental component to one co-located team.
You need strong communication channels during architectural definition and system
integration; however, during the development of each individual component, the only
time the team must communicate is when the component interfaces require
clarification or modification.
Planning the Technology Tools

Distributed development involves two types of technology tools:
■
Implementation technologies
■
Infrastructure technologies

Implementation Technologies
Implementation technologies create the system being developed. These technologies
include the operating system, GUI components, and database.
When defining the system architecture, early in the process, specify the technologies
that implement the system and demand commonality, unless there are sound business
reasons for deviating.
Infrastructure Technologies
Infrastructure technologies establish an effective distributed software development
environment. These technologies include the CM tool and process, compiler, and
integrated development environment (IDE). When planning which infrastructure
technologies to use on a project, consider the following:
❑ Try to achieve a common set of infrastructure technologies early in the

process and demand commonality, unless there are sound business reasons
for deviating. Consider the following technologies:
■
CM tools and processes
■
Defect tracking/reporting tools and processes
■
Build technology
■
Project management tools
❑ Ensure that the tools you use support distributed development.
In terms of CM, consider the following:
❑ There should be a reliable, secure means of replication and synchronization

of the data between sites that can be completely automated. Good network
performance is critical. If the network is too slow, it will not be used.
❑ The tools should make the team’s geographical distribution as transparent

as possible. The more teams feel as if they are working at the same site, the
better the communication and coordination will be.
❑ There must be a clear distinction between which site currently owns which
parts of the shared data.
❑ Ensure that the CM tools and processes you use are flexible and can
accommodate any possible rapid team growth.

Working Without
Configuration
Management
3
Most teams that use Rational XDE also use a Configuration Management (CM)
system to help them manage files, file versions, share files, and build processes.
However, some teams, such as a small team of analysts, may choose to work without
a CM system. This chapter describes:
■ The Analyst Role
■ Sharing files by e-mail or in common directories
■ Sharing models without a CM system
■ Signs that your project would benefit if you use a CM system
The Analyst Role

The analysts on your team are responsible for:
■
Understanding the problem to be solved
■
Understanding stakeholder needs and communicating those needs to the
development team
■
Articulating and managing requirements as they change throughout the project
■
Helping to define the system to develop
Analysts work with use-case diagrams to create visual models of the system
requirements. Analysts also often work with activity and sequence diagrams.
If your development team already works in a CM environment, it’s probably easiest
to start your work by storing XDE models in a CM system.
CM systems help manage the coordination of shared artifacts. If you choose to work
without a CM system, you must perform this coordination manually. Therefore, it is
easier to work with a CM system if you need to share models. If you must share
models without a CM system, follow the guidelines described in Sharing Models
Without a Configuration Management System on page 40.
39
Sharing Files by E-Mail or in Common Directories
If you share files by e-mail, you have probably developed a simple, informal process
in which you have agreed on topics such as:
■ Who owns which file. (It’s important to be clear about this so that, at most, only
one person works on any given file.)
■ How often or at what point you will e-mail the file. (When using these informal
systems, it reduces confusion to exchange files as infrequently as possible.)
■ How you will create occasional snapshots of the shared files that everyone can use
as a basis for further work.
If e-mailing shared sets of files becomes too complex, you can use a shared folder to
distribute these files. As the owner of the folder, your responsibilities include:
■
Determining and communicating how often updated files need to be placed in the
shared folder
■
Verifying that sets of files work together
■
Maintaining security and access privileges
■
Developing a model versioning strategy, if required
Sharing Models Without a Configuration Management System

If you share an XDE model without using a CM system, you must initiate an XDE
compare and merge session every time you combine two or more variations of your
model; otherwise, changes may be lost.
To reduce the need to merge models, we recommend that you separate models into
packages (.pkx files) and make each package a subunit. Assign each subunit to only
one user. If users work on separate package subunits, they will merge files less often
than if they work in packages that are not in subunits. For more information, see
Planning Model Partitions on page 43.
Some changes that are made within a package (contained in a subunit) can result in
changes to other subunits outside of that package’s subunit. For more information,
see Working With Packages on page 54.

Recognizing That You Need to Use Configuration Management
If you are on a small team whose members infrequently shares files, then sharing files
by e-mail can work effectively. However, several factors can eventually make this
method difficult to maintain, including:
■ As the number of files increases, keeping track of file versions becomes difficult.
For example, if a team member asks you to refer to the latest file version, you must
be able to confirm that you are accessing the correct version. You may find yourself
searching model files for certain attributes or characteristics that identify the
correct version, which can be a tedious process.
■ You cannot retrieve previous file versions, so you must manually create snapshots
at appropriate times. With no central repository that contains current or previous
releases, you must collect previous file versions from team members.
■
It is difficult to identify the most recent files, which places extra burden on team
members who work with files owned by multiple people.
■
It is difficult to revert to earlier versions when deciding to undo recent changes.
■
It is confusing when different team members want to work on the same file.
If you share files without using a CM system, regularly evaluate your process to
determine whether a CM system can improve your workflow.
Chapter 3 - Working Without Configuration Management 41

Planning Model Partitions
4
In modern software engineering practice, developers partition source code functions
and definitions into files in ways that minimize the number of concurrent changes
required. When you create a model element in a Rational XDE model, such as a new
class or package, you can partition it into a subunit (or storage unit), which creates a
new file to hold the model element and any of its children. This chapter provides
guidance on how to effectively partition XDE model elements for a model-driven
development approach.
Understanding Model Partitioning

There are many ways to partition XDE models. You may want to create partitions for
performance reasons or to allow teams to work on different model elements
simultaneously. In general, when you carefully plan the partitioning of XDE models,
you facilitate the ability of your team to collaborate during the design of a complex
system.
By default, XDE stores an entire model in a single file, or storage unit. Alternatively,
you can use XDE to do the following:
■
Place a separable model element into its own subunit. You can separate model
elements such as packages, subsystems, diagrams, and classes.
■
Automatically create packages and subsystems as subunits.
■
Prevent the manual creation of subunits.
At a higher level of abstraction, you can create more than one model for a single
application. XDE lets you open more than one model at a time and create references
between them, which makes it easier to work with multiple models.
43
Deciding Whether to Partition Models
This section discusses the benefits and the drawbacks of partitioning an XDE model
into subunits.
Benefits of Model Partitioning

The size of a model and the amount of parallel work required by a particular team
determine whether and how to partition the model into subunits. The benefits that
can result from partitioning include faster reloading and less merging (which results
in faster integration).
Faster Loading
When XDE loads a model, it loads only the minimal set of subunits required;
therefore, when you partition a large model into many subunits, the model loads
more quickly than the same model stored in a single file.
Less Merging: Faster Integration

A team working on a particular model usually partitions the model so that different
team members can avoid working on the same storage unit simultaneously. When
only one person changes a storage unit at one time, no conflicts arise when you
deliver the storage unit. This eliminates the need to merge at integration time, which
speeds up the integration process.
Drawbacks of Model Partitioning

Although partitioning a model into subunits decreases the chances of having to
perform a merge during integration, there are still occasions when a merge operation
is required. When these merges occur, the partitioning of the model into separate
units can make the resulting merge operations more challenging than they would
have been if the model occupied a single storage unit.
Out-of-Context Merging
When Rational ClearCase initiates merges, it performs them one file at a time, which
causes XDE to merge a single model storage unit at a time. For example, when you
deliver an activity, a new XDE compare/merge session begins for each individual
conflicting storage unit included in the activity’s change set. Because these merge
sessions are done without the context of the other storage units, the validation
capabilities of the tool are limited during the merge to the one storage unit. You
cannot validate files that are out-of-context.

Discrepancies With Logical Elements and Physical
Representations
When a model element in a separate storage unit file is renamed or moved in the XDE
Model Explorer, XDE neither renames nor moves the element’s storage unit file. This
can cause unexpected consequences for some operations.
Consider the following example:
1 A model has several packages. The packages and classes are in separate storage
units.
2 In the Model Explorer, if you move a class from one logical package to another
logical package, the storage unit file for that class remains in the directory of its
original package.
3 If you perform an operation, such as a ClearCase labeling operation, on the class’s
new package directory, the operation does not operate on the model element’s
storage unit file because it remains in its original package directory.
4 If you partition a model named myModel into two top-level packages, P1 and P2,
and P1 contains a separate class C1 (in its own storage unit), the physical layout of
the model on the file system is as follows:
❑
C:\Dev\myModel.mdx
❑
C:\Dev\myModel\P1.pkx
❑
C:\Dev\myModel\P1\C1.clx
❑
C:\Dev\myModel\P2.pkx
The discrepancies discussed above mean that:

■
Moving C1 from P1 to P2 in the Model Explorer leaves the storage unit files in their
original locations.
■
Renaming C1 to C2 does not rename C1.clx.
■ Deleting C1 from the model does not delete C1.clx.
Therefore, you should partition an abstraction level of a model when that level
stabilizes. For more information, see Partitioning Stable Abstraction Levels on page 48.
Moving Files With XDE and ClearCase

XDE handles file movement to provide consistent management of storage units,
regardless of the configuration management (CM) system.
ClearCase handles the movement of files in the repository because it can associate
versions with directories as well as files. When a file moves from one directory to
another, ClearCase can track that an older version of a directory contained the file and
Chapter 4 - Planning Model Partitions 45

that the new version of the directory does not. ClearCase can also track when a
particular element in the file system, even another directory, has moved to a new
directory, so the version history of the element remains intact.
By contrast, most other CM systems do not handle file movement gracefully. To move
a file to a new directory, you delete the file from its original location in the repository
and then create a new file in the new location in the repository. This causes the change
history of the new file to disassociate from that of the old file, so someone who wants
to see the entire change history must know to look at both files. Therefore, moving
files in the repository is generally not encouraged. For more information, see
Refactoring: Adding, Moving, and Deleting Files on page 142.
Balancing the Benefits and Drawbacks of Model Partitioning

The benefits of model partitioning include the following:
■
Units load faster, an important consideration for large models.
■
With an appropriate amount of partitioning, developers rarely have to work on the
same unit at the same time, reducing the frequency of merge operations.
The drawbacks of model partitioning include the following:
■
As you decompose the model into more storage units, the merge operations that
occur can present challenges that do not occur when the model is in a single
storage unit. For example, the internal validation that XDE performs on a unit
during the merge operation can only consider the information present in the unit
being merged, now just a small part of the entire model.
■
Discrepancies can occur between the location of model elements in the model and
the location of their storage units in the file system and your CM system.
Model Partitioning Guidelines

When developing a model partitioning strategy, consider the following guidelines:
■
Think about when to decompose a model into subunits.
■
Determine candidates for separate storage units.
■
Partition stable abstraction levels.
■
Develop an ownership policy.
■
Avoid merges when separating or combining model elements.

When to Decompose a Model Into Subunits
The proper balance between having too few storage units and too many storage units
depends on your circumstances. However, few large teams work with a large model
in a single storage unit, because the benefits of breaking a large model into units
generally outweigh the drawbacks. When a unit grows to the point where more than
one person is working on it at the same time, you should decompose it into more
storage units.
One of the keys to deciding when to create subunits is understanding how
independently the developers on your team work. If your subunits are almost
completely independent of one another, you rarely need to perform merges. On the
rare occasions that you do need to perform merges, the few dependencies between
subunits mean that merging the units separately is fairly straightforward. However, if
your units have interdependencies, changes can result in many conflicts.
Determining Candidates for Separate Storage Units

When determining candidates for separate storage units, consider the following:
■ Minimize the coupling between units.
■ Create separate units for complex diagrams.
Minimizing the Dependencies Between Units

When you design code, you have probably adopted the generally accepted practices
for separating large systems into subsystems. For example, you try to create
self-contained units, with minimal or no dependencies on other units. These
principles apply as well to partitioning XDE models.
When you minimize the dependencies between units, you reduce the likelihood that a
change in one unit affects others. If, on the other hand, you allow dependencies
between subunits, the result can be widespread conflicts that you must resolve in
merge sessions. These conflicts are usually out-of-context merges, which can be more
challenging to resolve. For more information, see Out-of-Context Merging on page 44.
Creating Separate Units for Complex Diagrams

Model diagrams can affect interdependencies. An XDE diagram can have references
to many model elements within its model. It can also have references to model
elements in other models. These references can make a diagram sensitive to changes
in other subunits of the same model and even in different models.

Diagrams cannot update to reflect changes when they are closed; they can only
update when they are open. If you leave a diagram closed while you work on other
units, the diagram does not change and it does not immediately require merging.
Later, when you open the diagram, it changes and may require merging. For more
information, see Updating Diagrams on page 80.
In many cases, it is easier to put a complex diagram in a separate unit and leave it
closed. You can then either choose to make occasional larger merges or frequent
smaller merges. You must determine which method is more effective for your team.
Partitioning Stable Abstraction Levels

You should partition an abstraction level of a model into subunits when that level
stabilizes. With the abstraction level stabilized, it is less likely that the partitioning
will change, which can result in inconsistencies between the logical and physical
representation of the model.
For example, during the initial phase of a model lifecycle, only a limited number of
designers (often just the architect of the project) work on the model. The first few
versions of the model depict the top-level subsystems of the system. Until the
top-level packages are defined and it is obvious that they will survive future
iterations, separating the model into subunits is not recommended.
When the top-level subsystems are mature, consider separating them, to enable
parallel development and improve the speed with which the model opens. This is a
recursive operation: When each individual subsystem’s contents stabilize, you can
safely partition the subsystem.
Developing an Ownership Policy

In general, merges occur when multiple people make changes to the same file. One
way to reduce merges is to establish an ownership policy, so that each file has only
one owner who is permitted to change it.
Model Ownership
At the simplest level, you can assign a single owner for each model. Only one person
makes changes to that model, so no merges are necessary. The XDE multiple model
capability lets you work with a large system that contains many smaller models.
Typically, there is one master model with a diagram referencing others. The master
model serves as the root for someone who wants to explore a system.
To practice model ownership, establish the size and scope of each model so that a
single person can work on it.

There are times when additional constraints apply. For example, with an integrated
development environment (IDE) project that has only one code model, the size or
scope of the code model is determined by the size of the project. If the project is sized
so that a single person can own it, then this model ownership policy works well.
Typically, though, more than one person works on a project, which means that model
ownership is not practical for the IDE project’s code model.
Package Ownership
If model ownership is not practical, you can practice package ownership. With this
policy, each individual is responsible for the contents of a package. Adding a new
package directly under the model results in a change to the root of the model (because
it has a new child) but most other changes within the separate packages do not affect
the root model file (the .mdx file). Individuals can work on their own packages
without needing to perform many merges. Occasionally, you will be required to
perform merges that involve the root unit of the model, but these merges should be
infrequent and, in many cases, are silent merges that do not require user intervention.
Subunit Ownership
If package ownership is not practical, you can create subunits to avoid more than one
person working in the same area at the same time. This lets you implement a storage
unit ownership policy.
■ Several people may need to work at the same time on individual classes in a
particular package. If you’re working with a language such as Java, the language
structure might dictate that the classes all reside in the same package.
❑ You can separate the classes into their own subunits, so that the developers can
work on each class in parallel without triggering complex merges.
❑ If, instead, the classes are combined with their package, then each person
changes the same file, which requires merges. Even though many of these
merges are silent merges not requiring user intervention, silent merges take
time. On the other hand, using separate units results in trivial merges, where
the latest version is added to the repository with no merge needed.
When ownership is assigned to the different parts of a model, only owners of a
particular storage unit can modify it. Because ClearCase and XDE currently do not
provide easy ways to enforce such a policy, you must set up a process to
accommodate this practice. Some teams prefer to relax these rules by letting other
team members modify a storage unit, with the approval of the owner.

Avoiding Merges When Separating or Combining Model Elements
When you separate a model element or you combine it with other elements, ensure
that no other users are modifying that model element while you are working. If other
users are working on the same model element, you lose their modifications.
1 Fred and Scott work on a model that contains a separate package P1 (P1.pkx). This
package contains a combined class C1 – a class that is not yet (but is about to be) in
its own, separate storage unit.
2 Fred separates C1 into a file named C1.clx. Fred checks out P1.pkx, adds C1.clx to
source control, and delivers these changes.
Result: The original model accepts Fred’s changes with no conflicts.
3 In parallel, Scott changes the documentation of C1. Scott checks out P1.pkx, and
delivers these changes.
4 When Scott delivers P1.pkx, the XDE compare/merge functionality merges the
package.
Result: No conflict occurs because XDE already accepted Fred’s changes to C1. The
documentation changes Scott made to C1 in P1 are not saved because C1 is no
longer stored in P1.pkx; C1 is in a separate subunit (C1.clx).
To avoid this situation in a Unified Change Management (UCM) environment, Scott
should rebase to a baseline that includes Fred’s changes and then make the
documentation changes to C1. If Scott made changes to C1’s documentation first and
then performed a rebase operation, the merge of the integration stream into Scott’s
development stream would result in the same outcome as described above.
As a general rule, any operation that results in a change to the model structure should
be made in a controlled environment.

Comparing and Merging
Models 5
If you work with Rational XDE in a team environment, you will probably have to
merge models eventually. For example, you and a colleague work on the same model
at the same time. Your colleague makes changes and checks them in. When you check
in your changes, you may overwrite your colleague’s changes. Because this is rarely
the result you want, you should merge the two changed units.
This chapter describes XDE compare/merge functionality, which you use to compare
or merge XDE models.
Note: When you work with XDE, use the compare/merge functionality to merge
models. Using any other tool to merge models will likely result in a damaged model.
Working With ClearCase

When you work with Rational ClearCase and XDE, the XDE compare/merge
functionality should automatically perform any model merges; if not, ClearCase is not
properly configured. ClearCase 2003 and ClearCase LT 2003 include a new VOB
feature level (Feature Level 4) that incorporates built-in support for XDE
compare/merge functionality as the Type Manager for XDE model units.
You must configure ClearCase 2002 to support XDE as the Type Manager. With
ClearCase 2002, XDE checks this configuration setting during startup. For more
information, see the Rational XDE Help.
Note: When directories that contain XDE model files need to be merged, you will see
a ClearCase directory merge session. This is normal behavior and does not indicate a
problem with your ClearCase XDE Type Manager configuration.
Merging Models With ClearCase

When you work with XDE and ClearCase, especially in a team environment, you may
have to merge models or parts of models. Consider the following example:
1 You and a colleague work on a model that is in ClearCase.
2 You both make changes to the model.
3 Your colleague checks in changes.
4 You check in changes.
51
5 ClearCase detects that the latest version in the repository is not the version you
checked out and modified.
6 ClearCase detects that your version cannot replace the version in the repository
without deleting your colleague’s changes.
7 ClearCase attempts to merge your changes into the latest version in the repository.
Merging Silently
In the example above, ClearCase prompts you to merge. If you do not select the
graphical merge option, ClearCase attempts to merge the model silently (that is,
without presenting a user interface to you). If you and your colleague made changes
to independent areas of the model, the silent merge succeeds and no XDE merge
session is required. For example, if you rename one class and your colleague adds an
operation to some other class, then these two changes are independent of one another
and there are no conflicts.
The example above refers to a Base ClearCase environment. In a Unified Change
Management (UCM) environment, you have the option to merge graphically when
you initiate a deliver operation (on the Deliver from Stream Preview dialog box).
Merging Conflicts
If a change that you make conflicts with a change your colleague makes, then the
silent merge cannot complete. For example, if both of you rename the same class, then
the silent merge fails and a graphical XDE merge session starts so that you can resolve
the conflict.
Of course, if you select the graphical merge option during a merge, a graphical XDE
merge session starts even if XDE only encounters differences (no conflicts) during the
merge.
Triggering Multiple Model Merge Sessions

Many ClearCase operations can affect many files at one time. An operation can affect
many models or many units from one or more models, so a single ClearCase
operation can trigger multiple model merge sessions. Each model unit merges
separately in its own merge session. For more information, see Starting a Session In a
New XDE Instance on page 56.
If the merge completes successfully during the silent merge, then there is no graphical
merge session for that unit. Other units may require graphical merge sessions to allow
you to resolve conflicts. These model unit merge sessions may occur with non-model
merge sessions, such as source code merges. ClearCase determines the order in which
the files are merged.

If the ClearCase operation you perform may result in multiple XDE compare/merge
sessions, then you can save time by ensuring that your session starts in an existing
XDE instance that is already open. For more information, see Starting a Session In an
Existing XDE Instance on page 57.
Working With Other Configuration Management Systems

If you use XDE with a configuration management (CM) system other than ClearCase,
you must:
■ Configure the system to handle XDE model unit files as binary files, so that merges
to model files are not attempted textually. For a list of extensions to various types
of model unit files, see the Rational XDE Help.
Note: If possible, set up your CM system to warn you of merges without
performing them.
■
Manually merge models using XDE compare/merge functionality.
If you use XDE without a CM system, you must also manually merge models using
XDE compare/merge functionality.
Working With Subunits

A model can consist of many subunits. Subunits are often referred to as storage units.
If subunits are in a CM system, they may be referred to as controlled units.
Subunits can consist of many different model elements, including classes, diagrams,
and packages. Initially, your model consists of a single file with an mdx extension.
When you create a model element in a model, such as a new class or package, you can
turn it into a subunit, which creates a new file to hold the model element and any of
its children. For more information, see Dividing a Model to Allow Concurrent Use in the
scenario chapters.
1 You have a model, MyModel, that contains a package, Package1.
2 If you make Package1 into a separate unit, a folder called MyModel, located in the
same folder containing MyModel.mdx, is created to contain the new package file,
Package1.pkx.
3 If you create Class1 in Package1 and make Class1 a separate unit, XDE creates a
folder called Package1 in the same folder containing Package1.pkx. Inside Package1,
you have the separate unit for Class1, Class1.clx.
Chapter 5 - Comparing and Merging Models 53

The model’s file system structure mirrors its hierarchy when first created:
❑
C:\Dev\MyModel.mdx
❑ C:\Dev\MyModel
❑ C:\Dev\MyModel\Package1.pkx
❑
C:\Dev\MyModel\Package1
❑ C:\Dev\MyModel\Package1\Class1.clx
Moving Model Elements From the Model Explorer

In the example above, within the model, you can move the package or class to some
other package in the model, but in the file system, the package or class files remain in
their original locations. For example, if you create Package2 and drag Class1 into
Package2, Class1.clx remains in the Package1 directory; it is not automatically moved to
the Package2 directory.
You should only move model elements from the XDE Model Explorer, so that XDE
retains knowledge of the location of the actual file corresponding to the moved
element.
Moving Model Elements From Outside the Model Explorer

If you work outside the Model Explorer to move a file representing a unit, XDE does
not know where the moved unit was located. Model elements whose storage units
cannot be located are marked with a small red x over the document icon that overlays
the model element. You can locate the moved unit by right-clicking on the model
element and clicking Browse for Unit.
Working With Packages

Some changes that are made within a package (contained in a subunit) can result in
changes to other subunits outside of that package’s subunit. For example:
■
Adding, deleting, or renaming a package affects the package’s parent, which may
be in a separate subunit.
■ Moving a package affects the source parent and the destination parent, both of
which may be in separate subunits.
■ Applying a new stereotype (or modifying an existing one) to an element in a
package affects the root model subunit.
Whenever changes affect subunits outside of a user’s assigned package or packages,
an XDE merge session may be required to resolve differences and conflicts.

Referencing Model Elements In Other Subunits
Subunits often have references to model elements in other subunits. When you start
an XDE compare or merge session for a single subunit that contains a reference to a
model element in another subunit, XDE informs you that the element is not
participating in the session. The current XDE compare or merge session does not
include the subunit containing the referenced model element. This behavior is normal
for the following situations:
■
Compare or merge sessions that involve a single subunit.
■
Manually-initiated compare or merge sessions that involve a subset of a model.
Combining Separated Units

You can combine separated units (using the Combine Unit menu item). For example,
you can bring Class1 back into its parent, which was Package1 in the example above.
XDE does not delete the Class1.clx storage unit, even though it is no longer a part of
the model.
Setting Preferences
You can set a preference to automatically make all subsystems and packages subunits
when they are created. You can also set a preference to warn against the creation or
deletion of subunits.
Understanding Automatic XDE Compare/Merge Sessions

XDE compare/merge sessions can start automatically on XDE clients that have
ClearCase installed and properly configured. Automatic XDE compare/merge
sessions provide a workflow that is less vulnerable to user errors.
An XDE compare session typically starts when you attempt to examine the history of
a model's changes (for example, you select the Team > Compare With Previous Version
context-menu item).
An XDE merge session typically starts when you merge the changes from two (or
more) users, such as during a UCM rebase, UCM deliver, or a non-UCM check-in.
The workflow for an automatic XDE compare session is as follows:

1 You perform a ClearCase operation that affects XDE model files (for example, you
select the Team > Compare With Previous Version context-menu item).
2 ClearCase starts an XDE compare session.

3 XDE compare/merge functionality compares the model file contributors and
presents the results.
4 You browse the differences and detected conflicts.
5 You close the XDE compare session.
6 The ClearCase operation exits.
The workflow for an automatic XDE merge session is as follows:

1 You perform a ClearCase operation (for example, a UCM rebase) that affects XDE
model files.
2 ClearCase starts a separate XDE merge session for each changed model file.
3 XDE compare/merge functionality compares the models, automatically resolves
all possible differences, and presents the results.
Note: If you do not select the option to merge graphically, then the XDE merge
results only appear graphically if conflicts are encountered. For more information,
see Merging Silently on page 52.
4 You can browse the results, resolve any unresolved conflicts or differences, or
revise any previously resolved differences.
5 Once you have resolved all conflicts and differences, you commit the changes from
the XDE merge session.
6 The ClearCase operation continues or exits.
Starting an XDE Compare/Merge Session Automatically

An automatic XDE compare/merge session is one that ClearCase initiates as a result
of some ClearCase operation, such as a UCM deliver operation. A single session starts
up for each subunit of the model. ClearCase determines what must be merged on a
file-by-file basis. Therefore, a model that consists of 10 subunits, where each subunit
contains a conflict, may result in 10 separate XDE compare/merge sessions, each one
covering a single subunit. For more information, see Triggering Multiple Model Merge
Sessions on page 52.
Subunits without conflicts are merged silently. For more information, see Merging
Silently on page 52.
Starting a Session In a New XDE Instance

When ClearCase starts an XDE compare/merge session, the behavior you observe
depends on how the ClearCase operation triggering the session was initiated.

Certain ClearCase operations can trigger an XDE compare/merge session to start up
in a new XDE instance. This new XDE instance starts and hosts the XDE
compare/merge session. When that session completes, that XDE instance closes.
Starting a Session In an Existing XDE Instance

Certain ClearCase operations, such as a UCM deliver operation initiated from
ClearCase Explorer, can trigger an XDE compare/merge session to start up in any
existing XDE instance. Because the XDE instance was open before the session began, it
does not close when the session completes. If there is no current XDE instance open
when the ClearCase operation triggering a merge is initiated, then an XDE instance
opens for the session. Once the session completes, the XDE instance remains open so
that it can be reused.
If the ClearCase operation you perform may result in multiple XDE compare/merge
sessions, then you can save time by ensuring that your session starts in an existing
XDE instance that is already open. Each session reuses that open XDE instance and
you avoid opening and closing multiple sessions.
Understanding the Results

During an XDE compare session, XDE compares the contributors by detecting
matches, differences, and conflicts between all model elements. For more information,
see Understanding the Results of an XDE Compare Session on page 63.
During an XDE merge session, XDE compares the contributors as described above
and also automatically resolves all possible conflicts and differences. For more
information, see Working With the Results of an XDE Merge Session on page 68.
After XDE completes comparing or merging all contributors, you can examine the
results. For more information, see Understanding the Rational XDE Compare/Merge User
Interface on page 89.
If you are working in an XDE merge session, you can:
■ Manually resolve differences and conflicts.
■ Review and modify the automatic resolutions that XDE applied.
Once there are no more conflicts or differences to resolve, you can successfully end
your merge session.
Note: Always use the File > Compare/Merge menu items to complete a merge session.
Avoid using the Close box. If you click the Close box to end a session and you have
unresolved conflicts, then you cannot cancel the session close – you can only commit
the incomplete merge session, or cancel and then restart the session.

Ending the Session
How you end the session depends on the type of session you are working in.
If you are working in an XDE compare session, you can end the session by clicking
File > Compare/Merge > Close Session.
If you are working in an XDE merge session, then you can end the session by
performing either of the following steps:
■
Commit the current merge result to ClearCase (File > Compare/Merge > Save and
Commit ClearCase Session).
■
Cancel the merge session (File > Compare/Merge > Cancel Session). The ClearCase
command that initiated the session interprets this action as a failure.
Understanding Manual XDE Compare/Merge Sessions

You must manually start XDE compare/merge sessions in environments where
ClearCase is not installed. An XDE compare session is typically performed when you
examine the history of a model's changes. An XDE merge session is typically required
when you merge the changes from two (or more) users.
The workflow for a manual XDE compare or merge session is as follows:

1 You start the XDE compare or merge session.
2 You select the contributors that you want to compare or merge. From these
contributors, you select a common base contributor.
3 If the models are broken into subunits, you can specify a subset of subunits to
compare or merge.
4 XDE compare/merge functionality compares the models, automatically resolves
all possible differences, and presents the results.
5 If you are in an XDE compare session, you browse the differences and detected
conflicts.
If you are in an XDE merge session, you perform any of the following:
❑
Browse the results.
❑
Resolve any unresolved conflicts or differences.
❑
Revise any previously resolved differences.
6 If you are in an XDE compare session, you close the session or start an XDE merge
session from your compare session.

If you are in an XDE merge session, you close the session. To successfully close an
XDE merge session, you must resolve all conflicts and differences, and save the
merged model.
Starting an XDE Compare/Merge Session Manually

To start an XDE compare or merge session manually, click File > Compare/Merge > New
Session.
Once you have selected your contributors and base model, you begin an XDE
compare or merge session by clicking either the Compare or Merge button on the
Select Contributors dialog box.
Selecting Contributors and Base Models

At the start of a manual XDE compare or merge session, you select the contributors to
participate in the session. By default, a dialog box lists all the models currently open
in the XDE Model Explorer, and the first one is chosen as the base contributor. You can
remove models from this list, but you cannot remove the model currently selected as
the base contributor. If you do not want that model to participate in the compare or
merge session, then you must first select another model from the list to be the base
contributor. You can then remove the model that should not participate in the session.
You can also browse in the dialog box to find models in the file system to add to the
list of compare or merge participants. As the dialog box populates with models, you
can select the participants in your compare or merge session.
The base model is the reference point from which XDE tracks differences during a
compare or merge session. The base model is usually the common ancestor (or root) of
the models you are comparing or merging. The common ancestor is the model from
which the other contributors have evolved.
Regardless of the presence of a common ancestor, each XDE compare or merge session
requires that one contributor be designated as the base model for that session. This
affects how detected differences are interpreted.
Example
To understand the importance of selecting a base model, consider the following
scenario:
You compare two models, where one contributor has class A and the other does not.
Did one contributor add Class A or did the other delete Class A? If there is a common
ancestor, you can view it to determine whether Class A was present originally.
If the base model does not have Class A, then the first contributor added Class A.
If the base model has Class A, then the second contributor deleted Class A.

The use of a base model allows XDE to distinguish between additions from deletions.
Note: The base model always occupies the slot for Contributor 1 in the Comparative
Model Explorers.
Once you have selected your contributors and base model, you begin an XDE
compare or merge session by clicking either the Compare or Merge button on the
Select Contributors dialog box.
Models With a Common Ancestor

We recommend that you select a common ancestor as a base model during manual
XDE compare/merge sessions. This is often possible when you work with CM
systems that support parallel development by reporting when a merge is required.
1 Two users, Albert and Charlie, check out version 10 of model M.
2 Albert makes changes and checks in the model. The CM system reports that no
merge is required and designates the new model as version 11.
3 Betty checks out version 11 of the model.
4 Betty makes changes and checks in the model. The CM system reports that no
merge is required and designates the new model as version 12.
5 Charlie finishes making changes and attempts to check in the model, but the CM
system reports that a merge is required. Charlie cancels the checkin.
6 Charlie needs to perform a manual merge session to merge the changes with the
latest version in CM (12). The common ancestor is the version that Charlie
originally checked out (10). Charlie extracts versions 10 and 12 from the CM
system.
7 Charlie selects the model (on disk), and versions 10 and 12 from CM as
contributors for the merge session. Charlie designates version 10 as the base
contributor.
8 Charlie reviews and merges the changes with Albert’s and Betty’s, then saves the
merged model and closes the merge session.
9 Charlie checks in the merged model. The CM system again reports that a merge is
required, but now Charlie confirms that the merge is complete. The CM system
designates Charlie’s merged model as version 13.
As described in Step 6, the common ancestor for a compare or merge session is often
the model you used to begin your recent work (that is, the version you checked out
from the CM system).

If all other users properly merge their work when required, the common ancestor is
your original check-out, even if another user checked out an earlier version prior to
your check-out. For example, if Betty checked out version 8 of the model (instead of
version 11), then merged changes from other contributors as part of Step 4, the
common ancestor for Charlie’s merge session in Step 6 is still version 10.
Note: With XDE, the advantage of using a common ancestor as the base model is that
XDE automatically resolves more differences and conflicts without user intervention
than if you compare and merge two models with no common ancestor.
Models Without a Common Ancestor (Fusing)

If two users begin modeling on their own and at some point merge their models in
XDE, there is no common ancestor for the models. XDE compare/merge functionality
fuses the two models by combining each contributor’s elements.
Model fusing is not a recommended workflow for daily development work, but
rather a supported workflow for the early inception of a project after several users
have developed ideas or architectures independently.
The result of fusing two contributor’s models should be adopted by both contributors
and used as a common ancestor for subsequent work.
Selecting a Base Model When Fusing

In an XDE compare or merge session, you must always select a base model. The
recommended base model for contributors without a common ancestor is a
newly-created empty model.
Alternate Workflow: Merging More Than Two Contributors And a

Base Model
You can merge more than two contributors and a base model at one time (as many as
seven contributors are possible). However, this workflow is not recommended
because all of the contributors must have the same base contributor and more
conflicts and fewer automatic resolutions occur.
Note: The base model always occupies the slot for Contributor 1.
Selecting Subunits
After you choose the participants in your compare or merge session, you proceed to
the next step. If any models have subunits, you can choose the subunits to participate
in the session. You can compare or merge a single subunit or some subset of the
model.

Avoid model inconsistencies when you merge subsets of models. For example,
suppose you initiate a merge session where one user renamed a class in a separate
subunit and the other user renamed the same class to a different name. You should
merge the separate subunit containing the class to resolve this conflict. However,
other subunits in the model (for example, a diagram) may depend on the name of that
class in some way. XDE will not notify you that these dependencies exist between
separate subunits. If you do not merge these other subunits to resolve that conflict, the
model that results from the partial merge (a merge of some subset of the model) will
contain inconsistencies.
Understanding the Results

During an XDE compare session, XDE compares the contributors by detecting
matches, differences, and conflicts between all model elements. For more information,
see Understanding the Results of an XDE Compare Session on page 63.
During an XDE merge session, XDE compares the contributors as described above
and also automatically resolves all possible conflicts and differences. For more
information, see Working With the Results of an XDE Merge Session on page 68.
After XDE completes comparing or merging all contributors, you can examine the
results. For more information, see Understanding the Rational XDE Compare/Merge User
Interface on page 89.
If you are working in an XDE merge session, you can:
■
Manually resolve differences and conflicts.
■
Review and modify the automatic resolutions that XDE applied.
Once there are no more conflicts or differences to resolve, you can successfully end
your merge session.
Ending the Session

After you have examined the results, you have the following options:
■
If you are in an XDE compare session, you can end the session (File >
Compare/Merge > Close Session), or you can start an XDE merge session (Merge >
Merge Compared Models).
■
If you are in an XDE merge session, you can manually resolve differences and
conflicts or review and modify the automatic resolutions that XDE applied. Once
there are no more conflicts or differences, you can successfully complete the
session.

If you started the merge session manually, then you must end it manually by saving
(File > Compare/Merge > Save Merged Model) and then closing the session (File >
Compare/Merge > Close Session). If you close the session before you save the merge
result model, XDE prompts you to save the model.
Understanding the Results of an XDE Compare Session

During an XDE compare session, XDE performs three main tasks:
1 XDE identifies matching elements between a contributor and its base model. A
match indicates that elements may be identical.
2 XDE identifies differences between matched elements and generates differences
for unmatched elements.
3 XDE identifies conflicts between sets of differences from two or more contributors
(no conflicts are possible with only one contributor and its base model).
Understanding Model Element Matching

The purpose of matching model elements is to:
■
Determine which elements in different contributors should be compared against
each other.
■
Identify elements that do not exist in all contributors (elements that are either
being added or deleted).
Matching elements is a prerequisite to identifying differences between elements.
There are several matching algorithms, but the most common is to match elements by
GUID.
Matching Elements By GUID

When models are created, each element in the model is assigned a Globally Unique
Identifier (GUID), a unique machine-generated 16-byte quantity. An example of a
GUID is {CD7F4B49-CB80-4300-9607-1CBE753CB506}. This is one possible
representation of a GUID. GUIDs may appear in different formats depending on the
context.
When XDE merges models from a common ancestor, model elements are matched
primarily by their GUID. Matching by GUID allows XDE to analyze a model element
and detect relevant differences even after model elements have been moved or
renamed within a contributor.

Matching Elements By Name
When model elements are not matched by GUID, XDE attempts to match model
elements that have matching parent elements by their name. For example, if two
contributors each add a Class named BankMachine to the existing package Main, the
Class is considered matched (and the merged model will contain only one Class
named BankMachine). XDE will match the BankMachine Class even if one of the
contributors moves or renames the existing parent package Main.
Exceptions To Matching By Name

Some model elements have special matching requirements that override matching by
name.
Note: XDE matches most model elements by GUID, which does not have special
exceptions.
Diagrams are a common exception to matching by name. Diagrams are not matched
by name because separately created diagrams are likely to contain mutually distinct
details that do not need to appear on the same diagram (at least not automatically).
For example, if two contributors each add a diagram with the same name, the
diagrams will be considered to be unmatched (and both will be separately added to
the merge model).
UML Operations are another common exception to matching by name. They may
have overloaded names, so they are matched by the signature of their parameters.
Operations from separate contributors can match by name only in the following
situations:
■
Their names are the same.
■
Their parents match.
■
Their child parameters have the same names, kinds, and types.
■
Their child parameters appear in the same order.
For example, if two contributors each add an operation with the same name but with
distinct signatures, the operations will not match. Both contributors will be added to a
merged model.
Matching Elements When Fusing Models

When XDE merges models without a common ancestor (fusing), all model elements
are created at different times, so no GUIDs will match. Therefore, when XDE fuses
models, all model elements are matched by name only.

Identifying Differences
When comparing models, XDE can identify several types of differences between a
contributor and its base model, as described in the following table. For more
information, see Difference Icons on page 93.
Table 5 Types of Differences Between a Contributor and a Base Model
Icon Description
XDE detects Add differences when an element within a contributor model is not
matched within the base model.
XDE detects a Change difference on a property or a name of a matched element.

Some element properties are actually reference collections or point collections, so
they can have Add, Delete or Reorder differences on those properties.
XDE detects Delete differences when an element within a base model is not
matched within a contributor model.
XDE detects a Move difference when an element is not in the same location within
a contributor model as it is within the base model.
Two icons represent a Move difference: the top icon in the left column (similar to a
Delete icon) indicates that an element was moved from a location; the other icon
(similar to an Add icon) indicates that an element was moved to a location.
A Reorder difference is a Move difference to another relative location under the
same parent element. The same icons are used for Reorder and Move differences.
Note: When there is more than one contributor, the contributor models are never
directly compared. Contributor models are only compared with the base model. XDE
analyzes and compares separate lists of differences and identifies conflicts.
Detecting Moved or Changed Model Elements

The XDE compare/merge functionality can detect when model elements have moved
or changed their order. For example, a diagram is moved from one package to
another. If both packages are participating in a merge, either because they are both in
the same unit, or because the units containing them are both participating in the
merge, then XDE detects that the diagram moved and presents that as a difference
relative to the base contributor. To handle such cases, XDE must do more than a
simple side-by-side comparison of model elements and properties.
How does XDE know that the diagram in the new location is the same diagram that
was in the old location? XDE uses Globally Unique Identifiers (GUIDs) to identify
each model element. In the example above, the diagram has its own GUID. XDE
detects that a diagram with that GUID is in one location in the base contributor and a

diagram with the same GUID is in a different location in the other contributor. XDE
detects the move of the diagram even if the diagram was renamed when it was
moved.
For more information, see Understanding Model Element Matching on page 63.
Identifying Conflicts
A conflict is flagged whenever more than one contributor has a difference in a model
element or property relative to the base contributor.
The notation for a conflict is difference-difference; for example, a Change-Change conflict
means that a contributor and the base contributor have each changed the same model
element or property. For more information, see Identifying Differences on page 65.
The following table describes the types of conflicts that XDE identifies. For more
information, see Conflict Icons on page 94.
Table 6 Types of Conflicts Between Contributors and a Base Model
Icon Description
This icon indicates an Add-Add conflict.

An element in a location that can only contain one element is known as a singleton.
Adding more than one singleton element to the same location can result in an
Add-Add conflict. Most elements belong in a collection owned by their parent, but
some element types belong to their parent as a singleton. If more than one
contributor adds a singleton element to the same parent, the added elements will
conflict.
Changing styles on the same diagram element or view element can also result in an
Add-Add conflict. Diagram elements and view elements can only have one reference
to each of their style types. If two contributors add a reference to a new style type,
even if they modified different parts of the same style type (for example, line color
versus font color), the added references will conflict.
Modifying add-in related information on the same element can also result in an
Add-Add conflict. In addition, tagged values that contain the same information can
result in Add-Add conflicts. Add-ins often attach extra information to modeling
elements using tagged values. If two contributors provide the same type of add-in
related information to the same element, the added tagged values will conflict.
An Add-Delete conflict is created when one contributor deletes an element and

another contributor adds items to that element or one of its descendents.
A Change-Change conflict is created when two contributors modify the same property
of an element. However, if the new value for the property is the same, the default
resolution is to accept the change.

Table 6 Types of Conflicts Between Contributors and a Base Model
Icon Description
A Change-Delete conflict is created when one contributor deletes an element and

another contributor changes the contents of that element or one of its descendents.
A Delete-Reorder conflict is created when one contributor deletes an element and

another contributor reorders the contents of that element or one of its descendents.
A Delete-Delete conflict is created when two contributors delete the same element.
The default resolution is to delete the element, but you can review this decision.
If one contributor deletes an element and the other element deletes a descendant of
that element, a conflict is created. The default resolution of the conflict is to delete the
parent element, but you can review this decision.
A Delete-Move conflict is created when one contributor deletes an element and

another contributor moves items to that element or one of its descendents.
A Move-Move conflict is created when two contributors move the same element.
However, if the destination is the same in both cases, the default resolution is to
accept the move.
A Reorder-Reorder conflict is created when a collection of elements is reordered by

one contributor, and reordered by another contributor (to a different order). Only
one order can be accepted. Typically a user has little direct control of the stored order
of elements in a collection, but sometimes a user can indirectly reorder elements in a
collection. In such cases, the resolution may be arbitrarily chosen.
The same icon is used for Reorder-Reorder and Move-Move conflicts.
An Atomic conflict is a special kind of Change-Change conflict that handles tagged

values added by add-ins. Add-ins often attach extra information to modeling
elements using tagged values, and sometimes several tagged values are logically tied
together.
In many cases, it is incorrect to permit a change of one tagged value from one
contributor and a logically tied tagged value from a different contributor. You must
resolve from the same contributor all of the tagged values that are logically tied to
the same modeling element. Change-Change conflicts are created to enforce this
behavior.
The same icon is used for Atomic and Change-Change conflicts.
Note: If two contributors conflict for more than one reason, the conflicts are
combined. For example, if one contributor deletes a package and another contributor
adds and moves items into that package, the resulting Add-Delete conflict and
Delete-Move conflict are combined, and are typically resolved simultaneously by the
same decision.

Working With the Results of an XDE Merge Session
At the beginning of an XDE merge session, XDE compares all models that are
contributing in the session. XDE then generates a merged model (a copy of the base
model) and attempts to apply automatic resolutions to all differences and conflicts
that it detects. You can then manually resolve any conflicts or differences that XDE
could not automatically resolve. You can also review and correct any resolutions.
This section discusses how you resolve conflicts and differences (automatically or
manually) and provides general merge guidelines.
Understanding the Unresolved Count

At the beginning of an XDE compare/merge session, an unresolved count is calculated
and can be viewed on the status bar. This value is updated as you manually resolve
conflicts and differences.
The unresolved count is calculated as follows:

Unresolved count = Unresolved conflicts + Unresolved differences not part of a conflict
Note: Unresolved differences that are part of a conflict are not included in the
unresolved count. For more information, see Counting Unresolved Conflicts.
Example unresolved count:
Unresolved Unresolved differences Unresolved differences that

Unresolved count
conflicts that are part of a conflict are not part of a conflict
10 30 15 10 + 15 = 25
Note: Conflicts are the result of two (or more) differences, which are, or may be,
incompatible or mutually exclusive. For more information, see Identifying Conflicts on
page 66.
Counting Unresolved Conflicts

A conflict is resolved when all of the differences within it are resolved. Because
resolving a conflict typically only requires one user action, the unresolved count does
not count each of the unresolved differences that are part of a conflict.

Counting Unresolved Difference Not Part Of a Conflict
The unresolved count also counts differences that are not part of a conflict.
Unresolved differences that are not part of a conflict typically depend upon the
resolution of an unresolved conflict. For example, an addition of a child element
requires its parent to exist. If the parent is added by the same contributor (or deleted
by another contributor) and the parent is part of an unresolved conflict, then the child
is not part of that conflict, but depends upon that conflict. The addition of the child
element is a separate unresolved difference and contributes to the unresolved count.
XDE Merge Session Workflow

The unresolved count affects the workflow of an XDE merge session in the following
ways:
■
If an automatic XDE merge session initially calculates an unresolved count of zero,
the contributors will be automatically merged silently and no graphical
(interactive) XDE merge session is presented. If an automatic merge session
initially calculates an unresolved count greater than zero, a graphical (interactive)
XDE merge session is presented.
■
Closing an automatic XDE merge session successfully (using File > Save and
Commit ClearCase Session) is only possible once the unresolved count is reduced
to zero.
■
Closing a manual XDE merge session (using File > Close Session) is only possible
once the unresolved count is reduced to zero.
The goal of the XDE merge session is to reduce the unresolved count to zero. This
happens both automatically (before the XDE merge session becomes interactive) and
manually (as a result of your actions). For more information, see Resolving Differences
Automatically on page 69 and Manually Resolving Differences and Conflicts on page 75.
Resolving Differences Automatically

Whenever only one contributor makes a change, XDE automatically propagates the
change to the merge result. This automatic resolution of simple differences is called an
auto-resolution. For more information, see Understanding Auto-Resolve on page 70.
Consider the following examples:
■
The base contributor has a class C1. If one user changes the name of that class
while the other leaves the name the same as the base contributor, then only one
user has changed the name and that change is applied automatically to the merge
result model.
■
If more than one user has introduced a difference in the same model element, or in
the same property of the same model element, then XDE must examine further.

❑
If both users make the same change, such as both deleting a class, then that
change automatically propagates to the merge result model.
❑
If the differences in the two contributors are different and incompatible, such as
one renames the class while the other deletes it, then the user must resolve the
conflict.
Understanding Auto-Resolve
The XDE compare/merge Auto-Resolve functionality helps to reduce the unresolved
count before the XDE merge session becomes interactive. The Auto-Resolve
functionality runs before the initial unresolved count is calculated and displayed. For
more information, see Understanding the Unresolved Count on page 68.
When XDE first begins a merge session, it applies the Auto-Resolve procedure to the
entire set of contributors with differences and conflicts that it can automatically
resolve, including:
■
Nonconflicting differences
■
Delete-Delete conflicts
■
Move-Move (same location) conflicts
■
Change-Change (same change) conflicts
For more information, see Identifying Conflicts on page 66.
If a contributor model that is not the base model includes a change (adds, modifies,
moves, or deletes an object), that change is applied to the merged (output) model.
XDE can select properties from different contributor models and merge them.
However, if two or more users change the same property, XDE cannot decide which
contributor to choose, and it generates a conflict which the user must then resolve.
Note: You can only manually perform the auto-resolve action (Merge > Auto-Resolve)
on an element that has been reverted to its unresolved state (Merge > Unresolve). If
you want to review the differences again, and possibly choose another resolution, you
can unresolve the element again. The differences become unresolved.
Merging With a Common Base Model: Auto-Resolve States

When merging models with a common ancestor base model, Auto-Resolve follows
the rules illustrated in Table 7 for a typical case of three contributors. Contributor 1 is
the common base model.

In Table 7, the cells of the Contributor columns describe the state of a model element
or model element property. For more information, see the text that follows Table 7.
Table 7 Merging with a Common Ancestor: Auto-Resolve States
Contributor 1
Auto-Resolve State Contributor 2 Contributor 3 Result
(Base Model)
No change A A A A
Added -- A -- A
Changed A A B B
Moved A A B B
Deleted A A -- --
Change-Change A B C !
Conflict
Change-Delete A B -- !
Conflict
Add-Add Conflict -- B C !
“-” means the contributor is not available.

“!” means there is a conflict.
Auto-Resolve State: No change

If a model element has no differences in any of the contributors, then all contributors
have the same value for that model element, shown as A in Table 7. As shown in the
first row, the merge result model has that same value, A, for that model element.
Auto-Resolve State: Added

If one contributor adds a model element, then only that contributor has that model
element, shown as A in the second row of Table 7. The other contributors have no
value for that model element, but the merge result model has this model element. This
occurs because only one contributor has a difference relative to the base contributor
and such trivial differences are automatically applied through the automatic
resolution (auto-resolve) mechanism.

Auto-Resolve State: Changed or Moved
For the Changed or Moved case in Table 7, only one contributor has a change to the
model element value, B, whereas the other contributors have the original value, A.
Again, because only one contributor shows a difference, it is automatically applied to
the merge result model, which sees value B.
Auto-Resolve State: Deleted

For the Deleted case in Table 7, the base and one contributor have the value A for
some model element or property but the other contributor deleted it. Again, because
only one contributor shows a difference relative to the base contributor, it is
automatically applied to the merge result model, which has that element deleted.
Auto-Resolve State: Conflict

The last three rows in Table 7 show conflicts that require user intervention to resolve.
In the first case, a Change-Change conflict, one contributor changed the value or
property of a model element to one value, B, whereas the other contributor changed
the same model element or property to a different value, C. XDE does not know
which value is correct, so it identifies this situation as one that requires user
intervention to resolve.
In the second conflict case, a Change-Delete conflict, one contributor changed the
value of a property to B, whereas the other contributor deleted it. Again, XDE cannot
tell which result is correct, so it identifies this conflict as one that requires user
intervention to resolve.
In the last conflict case, an Add-Add conflict, both contributors added a property to
the model element or added a model element where there can be only one. In this
case, XDE cannot tell which value is correct, so it identifies this as a conflict that
requires user intervention to resolve. It is possible to have Add-Add cases that are not
conflicts. For example, if each contributor adds a class to a model, both classes are
automatically added to the result model.
Merging Without a Common Ancestor Base Model (fusing):

Auto-Resolve States
When XDE merges models that do not have a common ancestor base model (known
as fusing), the Auto-Resolve process behaves slightly differently, as illustrated in
Table 8 (a typical case of three contributors). For more information, see Models Without
a Common Ancestor (Fusing) on page 61.

In Table 8, the cells of the Contributor columns describe the state of a model element
or model element property. For more information, see the text that follows Table 8.
Table 8 Merging without a Common Ancestor Base Model (fusing):

Auto-Resolve States
Contributor 1
Auto-Resolve State Contributor 2 Contributor 3 Result
(Base Model)
No change A A A A
Added -- A -- A
Changed A A B ! (1)(2)
Moved A A B ! (1)(2)
Deleted A -- -- A (Ignored) (1)(2)
Change-Change A B C ! (1)
Conflict
Change-Delete A B -- ! (1)
Conflict
Add-Add Conflict -- B C !
(1) These cases are rare if the base model is an empty model.
(2) These results differ from the results in Table 7 on page 71. These results occur to reduce the risk of
accidental data loss.
“-” means the contributor is not available.
“!” means there is no automatic resolution.
Note: Only the role of the base model is fixed in the Auto-Resolve procedure. The
order of the other contributors is not important. For example, you can switch the
positions of Contributor 2 and Contributor 3 without affecting the results of the
procedure.
In Table 8, there is no common ancestor. However, you must designate a base
contributor, but you should not expect to see the same GUIDs in the various
contributors. Where there is a common ancestor, on the other hand, it is common for
the same model element to appear in all contributors with the same GUID in all cases.
Without a common ancestor, there are cases where Table 8 differs from the common
ancestor table (Table 7). For example, the Changed or Moved case now results in a
conflict. Ultimately, without a common ancestor to establish history, you are less
certain that the merge result is the result you want.

Navigating Through Differences and Conflicts
This section describes how you can navigate through differences and conflicts by
using the Auto-Advance functionality and switching between merge phases (semantic
and diagram). You can also use menu items, toolbars, or keyboard accelerators to
navigate through conflicts and differences.
Auto-Advance
You can move through the merged model and make changes manually, or you can use
the Auto-Advance functionality to allow XDE to automatically move to the next
unresolved difference or conflict after you resolve a difference or conflict. By default,
the Auto-Advance functionality is set to Next Unresolved Difference when you load the
model files.
You can specify whether to advance to the Next Unresolved Difference, which includes a
difference involved in a conflict, or the Next Difference. After you accept a change in
the model, XDE automatically moves the current selection in either the Comparative
Model Explorer or the Comparative Property Browser to the next unresolved
difference (or difference).
Figure 1 illustrates the three Auto-Advance toolbar buttons. From left to right, the
buttons are: Do Not Auto-Advance, Next Unresolved Difference, and Next Difference.
You can disable the Auto-Advance functionality by selecting the Do Not Auto-Advance
toolbar button.
Figure 1 Auto-Advance Toolbar Buttons
Merge Phases
Each merge session consists of two separate phases:
■
The semantic phase, in which you resolve any conflicts that involve the model
elements of your model other than those on diagrams.
■
The diagram phase, which begins automatically after you complete the semantic
phase, so that you can resolve any conflicts on diagrams.
The Semantic Phase

When you resolve conflicts in the semantic phase (from the Semantic Comparative
Model Explorer) in favor of the deletion of an element, that conflict resolution
automatically propagates to all diagrams available to the merge session.

1 You have a conflict between the renaming or deletion of class C1. A diagram, D1,
contains a view of class C1.
2 The semantic phase presents the conflict. If you resolve the conflict in favor of the
deletion of C1, the resolution automatically propagates to diagram D1, and the
conflict on that diagram resolves in favor of the deletion of the view of C1. This
reduces the number of conflicts you have to resolve and helps ensure that conflicts
are resolved consistently. In this case, the deletion of C1 automatically results in
the deletion of the view of C1 from diagram D1.
The conflict resolution propagation described in the example above only applies to
the deletion of model elements. If you resolve the conflict in favor of the renaming of
the class, the resolution does not automatically propagate to the diagram.
The Diagram Phase

Although merge sessions start in the semantic phase, you can switch to the diagram
phase at any time by selecting the Diagram Comparative Model Explorer (DCME) tab.
However, you can save time by resolving all conflicts in the semantic phase first,
because doing so reduces the number of conflicts that remain to be resolved in the
diagram phase.
At the start of a merge session, XDE describes the two phases of the merge session and
how to complete them. When you resolve the last conflict in the semantic phase, if the
Auto-Advance option is on and there are conflicts to resolve in the diagram, then XDE
automatically takes you to the diagram phase (the DCME).
While you resolve conflicts, the status bar at the bottom of the XDE window shows
the total number of conflicts that must be resolved in the merge session. XDE takes
you to the diagram phase before the count gets to zero, so that you can resolve the
remaining conflicts in the diagram phase.
Manually Resolving Differences and Conflicts

During the merge session, XDE automatically resolves each difference and generates a
merged model for resolved differences. You can then perform the following:
■
Manually resolve differences and conflicts.
■
Review and modify the automatic resolutions that XDE applied.
Note: You can only resolve differences and conflicts during a merge session.
However, you can easily switch from a compare session to a merge session.
The goal of an XDE merge session is to reduce the unresolved count to zero. For more
information, see Understanding the Unresolved Count on page 68. XDE compare/merge
functionality provides several tools that help you achieve that goal quickly and
correctly, as discussed in the following sections.

Resolving Differences and Conflicts Individually
When you navigate to a difference (including a difference that is part of a conflict),
you can perform any of the following actions on that difference (or conflict):
■
Resolve Using
■
Auto-Resolve
■
Unresolve
You can access these actions from the Merge menu in XDE.
Resolve Using
The Resolve Using action changes the resolution of a difference (or conflict) to match
the specified contributor. If a contributor did not participate in a difference or conflict,
that contributor is not available as a choice for the Resolve Using action. The Resolve
Using Contributor 1 action is always an option for any difference because you can
always revert a difference to its state in the base model.
The Resolve Using action is typically the most common action performed during an
XDE merge session. The Resolve Using action is also available from the toolbar (one
button for each contributor).
Auto-Resolve
You can also perform the Auto-Resolve action for a selected difference. When XDE first
begins a merge session, it applies the Auto-Resolve action to the entire set of
contributors with differences and conflicts that it can automatically resolve. For more
information, see Understanding Auto-Resolve on page 70.
Reapplying the Auto-Resolve action is useful if a difference was originally unresolved
because of its dependency on an unresolved conflict, and that conflict has now been
resolved. The Auto-Resolve action is also useful if you have been experimenting with a
difference’s resolution, and you want to restore it to the auto-resolved value.
Note: You can only perform the Auto-Resolve action on differences that are
unresolved. If a difference is resolved, you must first unresolve that difference, as
described in the following section.
Unresolve
You can use the Unresolve action to undo a difference’s resolution, and add it to your
unresolved count. The Unresolve action is necessary if you want to reapply the Auto
Resolve action on a difference.
Note: You do not need to unresolve a resolved difference before manually resolving it
in favor of a different contributor; you can always manually change a resolution.

Resolving Several Differences and Conflicts At Once
You can resolve several differences and conflicts at once by using the following merge
actions:
■
Resolve Using (in Subtree mode)
■
Resolve All Using
These actions may overwrite previously applied resolutions. With both of these
actions, you specify one contributor to resolve a set of differences. If a difference did
not originate from that contributor, you can revert or ignore that difference’s
resolution. For more information, see Reverting Changes From Other Contributors on
page 77.
Subtree Mode
Subtree mode allows you to simultaneously change the resolution of all differences on
elements that are contained under a selected element. For example, when you select a
package in Subtree mode, the Resolve Using action propagates to all differences on all
elements nested within that package, resolving the entire package to use the specified
contributor. In Subtree mode, the selected element does not need to have a difference
to enable all possible Resolve Using contributors.
You can perform the following merge actions in Subtree mode:
■ Resolve Using
■ Unresolve
■ Auto-Resolve
You can switch Subtree mode on and off. Switch Subtree mode off to resolve an
individual element without affecting its sub-elements.
Subtree mode can be viewed and switched on and off from the toolbar.
Resolve All Using

You can use the Resolve All Using action to select a contributor to use for resolving all
differences and conflicts in the model. The Resolve All Using action is equivalent to
enabling Subtree mode, then selecting the Resolve Using action on the root node of the
model.
Reverting Changes From Other Contributors

When you specify a set of differences to be resolved by a particular contributor (by
using the Resolve All Using action or Resolve Using action in Subtree mode), some
differences can be unaffected by the specified contributor. In these cases, the
Resolve-Using Options dialog box allows you to revert those differences, or leave

them unaffected by the current action. The appearance of the dialog box and the
options enabled within it depend upon the presence of conflicting or non-conflicting
changes from other contributors that may be affected by the present action.
Reverting changes (whether conflicting or non-conflicting) implies that you want the
specified subtree (or the entire model) to match the corresponding part of the
contributor you specified. Not reverting implies that you do not want to affect the
resolution (or unresolved state, if applicable) for differences that do not involve the
specified contributor; you want all of the specified contributor’s changes and
potentially some changes from other contributors. The exact results after not reverting
differences from other contributors are not easily defined because the results depend
on the previous resolution state of those differences.
Example Scenarios
1 You have a base model, Contributor 1, with classes C1, C2, and C3.
2 Contributor 2 renames C1 to Class1 and C2 to Class2.
3 Contributor 3 renames C2 to MyClass2 and C3 to MyClass3.
The following table describes the changes each contributor makes and the merge
result (with auto-resolved differences):
Table 9 Sample Merge Result With Auto-Resolved Differences
Contributor 1 Contributor 2 Contributor 3

Merge Result
(Base Model) (Changes) (Changes)
C1 Class1 C1 Class1
C2 Class2 MyClass2 !
C3 C3 MyClass3 MyClass3
“!” means there is no automatic resolution.
At the start of the merge session (with auto-resolved differences) the class names are
Class1, C2, and MyClass3.
■ Class1 is applied automatically because only one user, Contributor 2, changed it
relative to the base.
■ ! is in the merge result because both Contributors 2 and Contributor 3 changed the
name of that class and the two differences (Class2 and MyClass2) are not the same
values. Therefore, there is no automatic resolution.

■
MyClass3 is automatically applied because only one contributor, Contributor 3,
changed it relative to the base.
You have a conflict with C2 that a user must resolve. By default, the merge result
model shows the base contributor’s values for all model elements and properties
engaged in conflicts. Therefore, if you save the merge result model without resolving
any conflicts, the result has all simple differences applied and all conflicts holding the
values in the base contributor.
If you manually resolve all conflicts in favor of Contributor 2, you resolve the one
existing conflict (the renaming of C2). The merge result accepts the renaming of C2 to
Class2, as shown in the following table:
Table 10 Resolving Each Conflict Individually in Favor of Contributor 2

Merge Result
C1 Class1 C1 Class1
C2 Class2 MyClass2 Class2
C3 C3 MyClass3 MyClass3
If you apply the Resolve All Using Contributor 2 command and revert non-conflicting
changes, the merge result accepts all of Contributor 2’s changes, as described in
Table 11.
Note: To revert non-conflicting changes, on the Resolve-Using Options dialog box,
select the Revert non-conflicting changes check box. For more information, see
Reverting Changes From Other Contributors on page 77.
Table 11 Applying the Resolve All Using Contributor 2 Command

Merge Result
C1 Class1 C1 Class1
C2 Class2 MyClass2 Class2
C3 C3 MyClass3 C3

The option to revert changes from other contributors ensures that even nonconflicting
differences are resolved in favor of the chosen contributor, whereas if you resolve each
conflict in favor of a chosen contributor, you have non-conflicting differences in their
auto-resolved state. In this case, C3 retains its name and discards Contributor 3’s name,
MyClass3.
Model Merging Guidelines

Merging code is not a trivial task; it requires a good understanding of both the system
containing the code that requires merging and the language in which the code is
written. Similarly, using the XDE compare/merge functionality to merge models
requires a good understanding of the artifacts being merged, of the model, and of the
Unified Modeling Language (UML).
Updating Diagrams
Some semantic changes that occur during an XDE compare/merge session can cause
pending side-effects on diagrams, particularly when auto-resize is enabled. For
example, a user may increase the required size of a class by giving an attribute a
longer name, or adding or deleting an operation. If that class appears on your
diagram and it is not updated, XDE compare/merge functionality may not detect that
a change is required. XDE performs the auto-resize calculation on your diagram the
next time you open it.
While many types of pending diagram changes are minor, to accept these changes in a
CM environment, you have to check out your diagram the next time you open it after
a successful merge and save the changes. You can prevent these pending side-effects
by opening your diagrams during or after an XDE compare/merge session but before
committing the merged model. After all subunits are merged, perform the following
steps:
1 Open your model.
2 Open and review all of your diagrams.
3 Save any changed diagrams.
4 Check in all of your checked-out files.
The diagrams you check in will contain the updated auto-resize calculations.
Resolving Conflicts Consistently

When you perform CM operations, such as ClearCase rebase and deliver, you may
need to perform many separate merge sessions to resolve the conflicts, and you must
resolve conflicts in a consistent manner across all of these merge sessions.

Inter-unit Consistency Errors
Inter-unit consistency errors may occur when two related conflicts found in different
storage units are resolved inconsistently.
1 Two users, Gary and Caroline, work on a model that is partitioned into two
top-level packages, P1 and P2 (each separated); P1 contains class C1 and P2
contains a diagram showing C1.
2 Gary deletes C1.
3 Caroline renames C1.
4 Gary delivers changes without requiring any merge.
5 Caroline delivers and gets two separate merge sessions, one for each package.
When merging P1, Caroline must resolve a delete-change conflict for C1. When
merging P2, Caroline must also resolve a delete-change conflict for the view of C1 on
the diagram. To keep the model consistent, Caroline should make coherent decisions.
Deleting C1 from P1 and keeping the view of C1 in P2 results in an unresolved
reference.
Model-Code Consistency Errors

Model-code consistency errors may occur when two related conflicts are resolved,
such as one in a storage unit and the other in the source file.
1 Two users, Robin and Paul, work on a model that contains a class C1 with an
operation fun, and the model is kept synchronized with a source file c1.java, which
contains the implementation of fun in C1.
2 Robin deletes fun in C1 and synchronizes c1.java.
3 Paul renames fun in C1 to bar in class C1 and synchronizes c1.java.
4 Robin delivers changes without requiring any merge.
5 Paul delivers and gets two separate merge sessions, one for the storage unit that
contains C1 and the other for the source file c1.java.
When merging the model storage unit, Paul must resolve a delete-change conflict for
fun in C1. When merging the source file c1.java, Paul must also resolve a delete-change
conflict for the implementation of fun in C1. To keep the model consistent, Paul should
make coherent decisions. Deleting fun in C1 from the model and renaming the
implementation of fun in C1 in the source file results in an inconsistency between the
model and the code.

Merge Granularity
The XDE compare/merge functionality does not merge the content of a model
element property. For this reason, you may want to avoid modifying properties, such
as the model element documentation, in parallel; otherwise, the integrator must select
one of the modified versions and then manually modify the property to incorporate
the changes from the other modified version, without assistance from XDE.
Optimizing XDE Compare/Merge Performance

XDE compare/merge performance depends significantly on the number of
differences that XDE processes during a compare or merge session. This affects the
amount of time that XDE spends processing the models (contributors) in a compare or
merge session during startup. During this time, a dialog box displays the progress of
the compare/merge session.
Although many factors affect the actual performance, as a general guide, XDE can
process hundreds of differences in minutes, but contributors with tens of thousands of
differences can take hours to process.
Optimizing Performance: Key Guidelines

The following general guidelines can improve XDE compare/merge performance:
1 Regularly merge your work with the work of your team.
2 After you merge your work with the work of your team, continue your work using
the latest available files.
For more information, see Example Scenarios on page 84 and Working In Parallel
Development: Workflow on page 86.
Factors That Affect XDE Compare/Merge Performance

Factors that affect XDE compare/merge performance include:
■
How often you check in.
■
How you modify a model.
■
What type of network environment you work in.

Checkin Frequency
The number of differences that XDE identifies in a compare or merge session depends
on how often you check in your work. Consider the following:
■
If you work with a CM system and regularly check in your work (which combines
it with others), then when you check out the result, XDE processes a relatively
small number of differences in each merge session.
■
If you work on your own for weeks and then merge all of your work into a model,
the resulting merge session can have a large number of differences to process.
Modifying Versus Adding To a Model

Another performance consideration is whether you modify the existing content of a
model or create new content. Consider the following:
■
If you modify the existing content of a model, XDE generally identifies a small
number of differences.
■
If you add new content to a model (such as a new class or package), everything in
that new content is identified as a difference by XDE because it is new work (none
of it exists in the base contributor). This scenario can result in large numbers of
differences.
While these considerations are not new (they exist with source code files as well),
model files are generally larger than source code files, so the effect of these
considerations on merge performance is more apparent.
Other Factors
Other general factors that can affect XDE compare/merge performance include the
following:
■
Workstation and network performance.
■ How complex the structure and organization of your models are.
■ The number of differences that result from the types of changes you make.
Evaluating Risk Factors Early In the Project

As with any risk factor in a project, identify and evaluate the risk early. To evaluate
XDE compare/merge performance, try a few sample merges early in the project. If
you do not evaluate XDE compare/merge performance early, you can subject your
project to unnecessary risk.

Example Scenarios
The following section describes a few sample XDE compare/merge scenarios and
provides guidelines on how to improve XDE compare/merge performance.
Working With a Single Branch

In this scenario, a team works in a single, common branch. When a user checks in a
file, it is available to others. The user then checks out the latest version of the file and
continues making changes. When these subsequent changes are checked in again, the
differences consist only of the changes made since the version the user checked out.
This generally results in a small number of differences in any resulting merge session.
In contrast, if a user continues working with the same file they checked in (local,
private copy), then the local copy does not contain any of the changes that other users
may have checked into the common branch recently. Therefore, the number of
differences between the user's local copy and the latest version in the CM system will
continue to increase over time and each subsequent merge session will take longer.
To avoid the above scenario, users should check out the latest version of a file that
requires changes rather than continuing to work with an older local copy.
Working With a Main Branch

In this scenario, a team works with several branches and a single main branch. Each
user works independently of others (on a separate branch). When a user makes
changes available to others, the changed files are merged into the main branch. In this
case, the daily checkin and checkout operations performed by the user should not
result in any merge sessions because the user works independently of other branches;
no other user makes any changes to this branch. However, when the user finally
merges changes into the main branch, the resulting merge session can have a large
number of differences.
To reduce the amount of time required to perform any resulting merges, users should
consider merging their work into the main branch about once every week.
Continuing Work After Merging to the Main Branch

If a user needs to make further changes after merging into the main branch, the latest
version in the main branch should be used as the starting point because the user's
local copies will not incorporate any other user’s changes in the main branch. If a user
continues to use a local copy, the next time a merge session is performed, the user
needs to repeat the earlier merge. Over time, as other users check in changes onto the
main branch, the number of changes missing from the user's local copy increases.
Also, the number of differences each merge session must process and the length of
time those sessions take will increase.

To reduce merge times, after users merge into a main branch, they should continue
their work using only the latest copies of model files from the main branch.
Working With UCM

UCM is a formal mechanism for working with separate branches and tracking
associated activities. In a common scenario, a team works with a single integration
stream and each user works on a separate development stream. Users should deliver
their work to the integration stream at least once every week and then rebase. This
practice ensures that any required merge sessions will have relatively few differences
to process.
If users do not rebase after delivering their work, then the number of differences
between their development stream and the integration stream continues to increase
over time. Each merge session will take longer to complete.
To avoid the above scenario, users should rebase after each deliver operation.
Working Without Configuration Management

If you work without a CM system, carefully consider how users can merge their work.
These merges should be performed frequently (for example, once a week). Each user
should use the resulting merged model for any further changes. Performing merges at
least once a week ensures that the number of differences during each merge session
remain small. Using the resulting merged model for any further work ensures that the
number of differences do not steadily grow over time.
When a team makes large changes quickly, such as at the start of a project, merges
should be performed more frequently to keep the number of differences in an XDE
merge session relatively small.
Teams should not work independently for a long period of time and then merge the
results just before a milestone. For example, a team partitions work into a set of
packages and each user works on a package for several weeks. Just before a major
milestone, the team merges all of their work. The number of differences being merged
in this situation can be very high and the resulting merges can take several hours to
complete.
To avoid the above scenario, teams should practice the following:
1 Merge all work together at least once a week.
2 After merging, start new work using the latest files (from the merge result) rather
than continuing to work on individual models from before the merge.

Working In Parallel Development: Workflow
The basic workflow for working in parallel is applicable both within and outside of a
CM system.
1 Create the main model and add high-level packages. To avoid conflicts during a
merge, separate the packages into subunits. Team members will merge their
changes into this main model.
2 All team members work by enforcing strong ownership on their packages.
3 Every few days, each team member merges their version of model n with the
common model n to create a new version n+1 of the common model. After
completing the merge, that team member should use the n+1 version of the
common model for further changes.
Merging Into the Common Model Separately

Two users should not merge their models directly. Instead, they should each merge
into the common model separately. These separate merge sessions should include the
following:
■
The user's model is one contributor.
■
The latest version of the common model is the other contributor.
■
The common ancestor of these models is the base contributor.
Note: Typically, the common ancestor is the version of the common model that the
user used when starting the current set of changes. The result of the merge session
becomes a new version of the common model.
Example: Working In Parallel Development

Two users (Bob and Mary) work in parallel on a model, OurModel. The team lead adds
two packages (package1 and package2) to the model and allows the users to access the
model.
Note: Because there are different versions of OurModel, this example uses a number
(in parentheses as a suffix) to designate each version of OurModel. If you work outside
of a CM system, you may prefer to append this number to the model name, so that
you can keep track of your versions.
1 Our two users start working on local copies of OurModel(1).
2 After working for a few days, Bob merges a model with OurModel(1) by
performing a two-way merge with OurModel(1), which is the base model.
3 Bob saves the result of the merge as OurModel(2), the second version of OurModel.

4 Mary wants to merge a model with the latest version of OurModel, which is now
OurModel(2). Mary uses a three-way merge where:
❑
Mary’s model is one contributor (the latest version of OurModel).
❑
OurModel(2), is the other contributor.
❑
The base model is the common ancestor of these two models (OurModel(1)).
Note: OurModel(1) is the common ancestor because it is the version that Mary
checked out to make changes, and it is also the common ancestor of the most
recent version of OurModel (OurModel(2)).
5 Mary encounters some conflicts and resolves them.
6 When Mary completes the merge session, the result of the merge is OurModel(3).
This is the new common version of OurModel.
7 Ideally, at this point Bob’s model is updated by incorporating all changes from
OurModel(3).
8 The next user to merge a version with the common model produces OurModel(4)
as the new common model.

Understanding the
Rational XDE
Compare/Merge User
6
Interface
This chapter describes various views, icons, and elements that are part of the Rational
XDE compare/merge user interface. Figure 2 illustrates a sample XDE
compare/merge user interface.
Figure 2 Sample XDE Compare/Merge User Interface
89
The Comparative Model Explorers
When an XDE compare/merge session starts, you see several key windows. The
window on top has two tabs, the Semantic Comparative Model Explorer (SCME) and
the Diagram Comparative Model Explorer (DCME). Initially, the SCME is in front, so
that you can resolve the semantic conflicts first. For more information, see Merge
Phases on page 74.
When you resolve a model element semantic conflict in favor of a deletion, that
conflict resolution decision automatically resolves related conflicts on diagrams, so
that views of the deleted element are automatically deleted. Therefore, it’s more
efficient to resolve conflicts in the SCME first. However, you can switch to the DCME
at any time by clicking the tab.
The Comparative Model Explorers (CME) let you:
■
Move from one selected difference or conflict to another.
■
Skip intervening elements that are not changing.
■
Use the Auto-Advance command to automatically move a selected element to the
next operation (specified in the Auto-Advance settings) after you accept a change
in the model.
The Comparative Model Explorer windows both show several major columns. If this
is a merge session, the first column holds the current merge result model. This column
is not present for compare sessions. The next major column holds the base contributor.
The other major columns hold the remaining contributors.
Each row in the Comparative Model Explorer corresponds to a single model element
across all contributors and the merge result. If a contributor does not have that model
element, then that row is blank in that contributor’s column.
Table 12 describes columns in the Comparative Model Explorer.
Table 12 Columns in the Comparative Model Explorer
Column Description
C Displays icons showing the nature of the conflict, such as a

change/change conflict.
R Shows the resolution state of a conflict or difference.
Merged Shows the model elements of the merge model result.

Table 12 Columns in the Comparative Model Explorer
Column Description
D Displays icons for each difference between the contributor to the

immediate right of this column and the base contributor. Because the
contributor to the immediate right of this column is the base
contributor, this column only shows the green check mark or the
revert icon.
[1] Base Displays the model elements of the base contributor.
immediate right of this column and the base contributor.a
[n] The next contributor.a
a. An XDE compare/merge session can include as many as seven contributors.
Note: Although the DCME describes information related to diagrams, it does not
show actual diagrams. Instead, it shows a tree list of each element associated with the
diagram.
Element Order In the Comparative Model Explorer

Elements that appear in the Comparative Model Explorer do not always appear in the
same order in the Model Explorer.
Unnamed Elements
Some object names that appear in the Model Explorer are derived from
supplementary information that is not stored as a name. This supplementary
information is not always derived from the Comparative Model Explorer. For
example, an Association may appear as (:Class1)(:Class2) in the Model Explorer but as
an unnamed Association in the Semantic CME. The information from which the name is
derived typically appears in the Comparative Property Browser for the element or one
of the element's children.
Examples of items that may appear in the Comparative Model Explorer without their
derived names are as follows:
■
an unnamed AssociatedClass
■
an unnamed Association
■
an unnamed Dependency
■
an unnamed Extend
■
an unnamed Generalization
Chapter 6 - Understanding the Rational XDE Compare/Merge User Interface 91

■
an unnamed GlobalAction
■
an unnamed Message
■
an unnamed ProxyState
■
an unnamed Realization
■
an unnamed Stimulus
■
an unnamed UninterpretedAction
Other elements that only appear with an icon and without a name in the Model
Explorer are explicitly referred to in XDE Compare/Merge sessions as an unnamed
Something. Examples of these elements without derived names include the following:
■
an unnamed ReturnType
■
an unnamed Transition
Generalized Icons For Specialized Element Types

The icons of some element types can appear in a generalized form in the Comparative
Model Explorer, despite appearing with a different, more specialized icon in the
Model Explorer. For example:
■
In the Comparative Model Explorer, the same Diagram icon represents all types of
diagrams. The specific type of diagram (for example: Activity, Class, Component,
Deployment, Sequence, Statechart, Use-case) is encoded as a property of the
Diagram object.
■
Junction, Deep-History, Shallow-History and Choice Points on State objects (in
Statechart diagrams) may appear with ChoicePoint icons. The type is encoded as a
property of the Choice Point object.
■
Entry, Exit and Do Actions on Activity objects (on Activity and StateChart
diagrams) may appear iconically as UninterpretedAction objects.
■
In the Comparative Model Explorer, the same Association icon represents
Aggregation, Composite and Directed Associations. The type of Association is
determined by examining the Aggregate and IsNavigable properties on its
Association Ends.

Difference Icons
Table 13 identifies the icons that appear in the Difference (D) status column in the
Comparative Model Explorer and in the Comparative Property Browser (CPB). XDE
displays one of these icons beside each element that has a difference. For more
information, see Identifying Differences on page 65.
Table 13 Difference Icons
Icon Description
Added element
Element property changed
Element affected by a parent element difference
Last element affected by a parent element difference
Deleted element
Element moved (in the location from which the element was moved)
Note: A reorder is a subcase of a move in which the source and
destination parent of the moved object are the same. The same icon is
used for moves and reorders.
Element moved (in the location to which the element was moved)
Unchanged element (only when the element is affected by changes in

other contributors)
Placeholder to keep all contributor trees in sync
Too many differences to display in a single icon

Conflict Icons
XDE displays a conflict icon beside each element that has a conflict. Conflict icons are
simple pairs of two difference icons. A checkmark in the Conflict (C) status column
indicates a resolved conflict.
Note: A checkmark in the Difference (D) status column indicates an unchanged
element.
Table 14 identifies a few sample conflict icons that appear in the Conflict (C) status
column in the Comparative Model Explorer and in the Comparative Property
Browser. For more information, see Identifying Conflicts on page 66.
For a complete list of conflict icons, see the Rational XDE Help.
Table 14 Sample Conflict Icons
Icon Description
Add-add conflict
Resolved add-add conflict
Conflicts involving too many differences to display in a single icon
Resolved conflicts involving too many differences to display in a

single icon
Resolution Icons
When you resolve a difference or conflict in your model, XDE displays a resolution
icon. A resolution icon represents the contributor selected to resolve the difference or
conflict. XDE accepts up to seven contributor models for merging (including a base or
root model).
Table 15 identifies a few sample resolution icons that appear beside each resolved
element in the Resolution (R) status column in the Comparative Model Explorer and
in the Comparative Property Browser.

For a complete list of resolution icons, see the Rational XDE Help.
Table 15 Sample Resolution Icons
Icon Description
Shows a difference that has been resolved by adding the

element as specified by Contributor n.
Shows a difference that has been resolved by deleting the

element as specified by Contributor n.
Shows a difference that has been resolved by ignoring

(reverting) the difference. This icon identifies a resolution that
uses Contributor 1.
Shows a difference that is unresolved.
The Comparative Property Browser

The Comparative Property Browser lets you:
■
Move from one selected difference or conflict to another.
■
Skip intervening elements that are not changing.
■
Use the Auto-Advance command to automatically move a selected element to the
next operation (specified in the Auto-Advance settings) after you accept a change
in the model.
Table 16 describes the columns in the Comparative Property Browser. When you
select a model element row in the SCME or DCME, the properties corresponding to
the selected model element row are shown in the Comparative Property Browser.
There is one row in the Comparative Property Browser for each property associated
with the model element selected in the Comparative Model Explorer.
Table 16 Columns in the Comparative Property Browser
Column Description
C Displays icons showing the nature of the conflict, such as a

change/change conflict.
R Shows the resolution state of a conflict or difference.

Table 16 Columns in the Comparative Property Browser
Column Description
Property Identifies, for each row, the name of the property being displayed in
that row.
immediate right of this column and the base contributor. Because
the contributor to the immediate right of this column is the base
contributor, this column only shows the green check mark or the
revert icon.
[1] Base Displays the model elements of the base contributor.
immediate right of this column and the base contributor.a
[n] The second contributor.a
a. An XDE compare/merge session can include as many as seven contributors.
Below the Comparative Property Browser is an area that contains two tabbed
windows: the Comparative Property Explorer (CPE) and the Differences Explorer
(DE).
The Comparative Property Explorer

The Comparative Property Explorer holds information specific to the property
currently selected in the Comparative Property Browser. For example, if you select the
Description property in the Comparative Property Browser, then the value of that
property shows up in the Comparative Property Explorer. This is particularly
valuable for those properties, like description properties, that typically hold
information that XDE cannot easily display in a single cell (row and column) in the
Comparative Property Browser.
The Differences Explorer

The Differences Explorer describes the currently-selected conflict. This is usually a
concise English-text description of the conflict. If you are new to the XDE compare
and merge feature, you should view the Differences Explorer for an explanation of the
conflict you currently have selected.

The Differences Explorer can show the following:
■
Differences arranged by conflict.
■
Conflicts arranged by difference.
Differences Arranged by Conflict

It is generally more useful to show differences arranged by conflict because this
method lists the differences that are causing a conflict. Recall that a conflict is flagged
whenever more than one contributor has a difference in a model element or property
relative to the base contributor.
Conflicts Arranged by Difference

In contrast, arranging the Differences Explorer by difference lists each difference
participating in the selected conflict and the nature of the conflict to which it is
contributing.
Model Elements Specific to the Comparative Model Explorers

This section describes the XDE model elements that you typically see in the
Comparative Model Explorers only during a compare/merge session. You are
unlikely to see these elements in the Model Explorer because they represent elements
in a diagram and are filtered out of the display in the Model Explorer.
Profiles
XDE uses Profiles to store additional feature-specific information that a user rarely
changes. A Profile is a collection of tagged value sets that belong to a model and can
be applied to elements within that model. Examples include Profiles for Java language
support and for Patterns. Profiles appear as direct children of the root model element.
Tagged value sets in Profiles are a collection of feature-specific default data that can be
applied to various types of model elements in the model. Tagged value sets can
contain tagged values and/or tag definitions. For more information, see Tagged Values
on page 98.
Profiles are typically hidden from the Model Explorer but can be viewed through the
Comparative Model Explorer because there can be differences with Profiles among
contributors in an XDE compare/merge session.
Note: Profiles change rarely and only by indirect user actions.

Table 17 lists the profile-related model elements that can appear in the Comparative
Model Explorer but not in the Model Explorer.
Table 17 Profile-Related Model Elements in the Comparative Model Explorer
Element Type Icon Description
Profile A collection of tagged value sets, each of which has

tag definitions and tagged values that collectively
make up a profile related to some domain.
Tagged value set A set of tag definitions and tagged values.
Stereotype A type of tagged value set, whose application is

often directly controllable and visible by the user.
Style A type of tagged value set used for formatting

diagrams and their contents. The default formats are
stored in the Profile section; non-default formats are
stored in the diagram.
For more information, see Tagged Values on page 98.
Tagged Values
XDE annotates model elements with UML tagged values that associate information
with those elements. A tagged value has a tag definition that defines its default value.
There are different types of tagged values for different types of data.
Tagged values are stored within tagged value sets in model Profiles and within styles
on diagrams. Tagged values can be owned by any model element. You can override
the feature-specific default values stored in a tagged value set that a model element
references.
Note: Tagged values change rarely and only by indirect user actions.

Table 18 lists the tagged value-related model elements that can appear in the
Comparative Model Explorer but not in the Model Explorer.
Table 18 Tagged Value-Related Model Elements in the Comparative Model

Explorer
Blob tagged value A tagged value of type binary.
Boolean tagged value A tagged value of type boolean.
Enumeration tagged A tagged value of type enumeration. The definition

value for an enumeration tagged value contains a collection of
tagged value literals.
Integer tagged value A tagged value of type integer.
Mask tagged value A tagged value of numeric type, defined by a

composition of tagged value literals.
Real tagged value A tagged value of type real.
References tagged value A tagged value whose type is a collection of references to

model elements.
Reference tagged value A tagged value whose type is a reference to a model

element.
String tagged value A tagged value of type string.
Tag definition A definition for a tagged value.
Tagged value literal One of the elements in the list of enumerations in an

enumeration tagged value.

Additional Semantic Model Elements
Table 19 lists additional semantic model elements that can appear in the Comparative
Table 19 Semantic Model Elements in the Comparative Model Explorer
Association end One end of an association, holding properties specific to

that end (such as navigability).
Association role An association within the context of a specific

collaboration.
Lifeline Created to capture semantic information that appears on

Sequence Interaction and Sequence Role diagrams.
Lifeline objects are typically unnamed and are visible in
the Semantic CME.
MessageEnd Created to capture semantic information that appears on

Sequence Interaction and Sequence Role diagrams.
MessageEnd objects are typically unnamed and are
visible in the Semantic CME.
Message objects (on Sequence Role diagrams) and
Stimulus objects (on Sequence Interaction diagrams) each
typically have two MessageEnd objects in addition to an
Action object (such as a CallAction). Each MessageEnd
object references a Lifeline object.
Constraint User-provided text to attach to a particular semantic

element. This is typically performed on a diagram.
Constraint objects are usually unnamed and are visible
on the Semantic CME; they are generally created on
diagrams.
Constrain A connector attaches a Constraint object to some other

(semantic) element in your model.
View Elements Within Diagrams

As defined by the Unified Modeling Language (UML) standard, a model element
representation within a diagram (called a view element) is a representation of another
element (called a model, or semantic, element). In this context, an XDE view element
is not the same as a ClearCase view element. The view elements are owned by the
diagram in which they are shown. View elements have a property named
ModelReference and this property indicates the model elements they represent.

A shape in a diagram is composed of a top-level view element, which is composed of
subviews it owns. For example, a shape representing a class in a diagram is a
PositionalGeneralView that is composed of a SubShapeView. The SubShapeView can
contain a NameCompartmentView (holding the name of the viewed model element), a
ListCompartmentView for attributes, and a second ListCompartmentView for operations.
Table 20 lists the view-related model elements that can appear in the Comparative

Explorer
View element overlay Represents another model element on a diagram. The

icon is displayed as an overlay above the UML icon of the
represented model element.
PositionalGeneralView Representation of objects within a diagram is done by a

SubShapeView, composition of various view elements, beginning with a
single PositionalGeneralView object.
NameCompartmentView
The PositionalGeneralView object contains a reference to
ListCompartmentView the semantic element being displayed on the diagram.
The child objects of a PositionalGeneralView add extra
view-related information for the element being
displayed.
The icon for all of these elements depends on the
underlying model element represented on the diagram.
For example, the first icon listed (in the Icon column) is a
view element overlay on a class icon, which indicates that
it is part of the diagram representation of a Class element.
The icons listed are some of many that can appear for
these element types.
ConnectorView Representation of line-like relationships such as

OnLineView Associations, Generalizations and Dependencies appear
as ConnectorView with the referenced model element.
Life-lines, Messages and Transitions also appear as
ConnectorViews. The icon appears as a view element
overlay on an Association.
The icons listed are some of many that can appear for
these element types.

Explorer
Note Text within a note element on a diagram.
Text Free standing text on a diagram.
NoteAttachment A connector that attaches a Note to some other diagram

element.

Working With
Cross-Model References 7
Rational XDE lets you store any portion of a model as a separate unit (subunit). You
can work with models or subunits by sorting them according to roles, users, or even
system architecture components. This improves parallel development because fewer
conflicts generally occur when fewer users make changes to the same files.
When you work on a model or model subunit, you may need to reference model
elements in other model locations. This chapter describes the different types of XDE
model references and how you can work with them.
Local and Cross-Model References

To create a model reference, drag a model element to another model location (either
within the same model or in a different model). XDE supports the following types of
model references, as illustrated in Local and Cross-Model References on page 104:
■
Local references
Local references extend between XDE model elements within the same model
(including references between subunits). Local references resolve through a
relative pathname to the model file that contains the referenced model element.
■
Cross-model references
Cross-model references extend between XDE models. You can create a cross-model
reference by dragging a model element from one model to another. XDE does not
copy the referenced model element to the new diagram; XDE only references the
diagram.
103
Figure 3 Local and Cross-Model References
XDE supports two types of cross-model references: source-relative and

component-relative.
Source-Relative References
A source-relative reference is a cross-model reference that XDE automatically
generates when you drag a model element from one model to another. Source-relative
references are the default cross-model reference type in XDE.
Note: We recommend using source-relative references in most modeling
environments, especially environments that use source control. For more information,
see Working With Source-Relative References on page 105.
XDE resolves source-relative references through a relative path from the unit that
contains the reference. With relative path resolution, you can copy, e-mail, or move file
sets from one file location to another and retain the source-relative references.

Table 21 describes how to create source-relative references between two integrated
development environment (IDE) projects.
Table 21 Creating Source-Relative References Between Projects
To Create a Source-Relative
IDE Project Project Contents
Reference:
proj1 ■
Code model with a main diagram Drag class1 onto the code model
■ Model element called class1 main diagram in proj2
proj2 ■ Code model with a main diagram Drag class2 onto the code model
■
Model element called class2 main diagram in proj1
Working With Source-Relative References

Source-relative references are the default cross-model reference with XDE. We
recommend that you use source-relative references in most modeling environments,
especially environments that use source control.
Working With Source Control

If your team uses source control, place all XDE project models into a source control
repository and use source-relative references.
Resolving Source-Relative References Before a Checkin

If you move a model or subunit from one disk location to another, you break all
references the model or subunit had with other models. If you check your changes
into source control, users who view your changes cannot resolve the broken
references.
We recommend that you validate all model references associated with your open
solution or workspace and resolve any broken references before you check your
model into source control.
When you open an XDE model file that contains unresolved cross-model references,
an error message appears. You must resolve all references before you can fully use the
model elements that contain the unresolved references.
Chapter 7 - Working With Cross-Model References 105

Component-Relative References
A component-relative reference is a cross-model reference that crosses a development
component boundary. Development components are shared folders that you can
move without breaking any cross-model references. You create development
components by registering shared folders with the XDE location registry. For more
information, see Creating Development Components on page 107.
The XDE location registry is a table that contains development component names and
locations. XDE resolves component-relative references through the location registry,
so component-relative references are relative to location names, not to pathnames.
Note: We recommend that you use component-relative references only when you
work with platform models or with shared models that are stored outside of source
control. For more information, see Working With Component-Relative References on
page 107.
Component-relative references provide location independence for shared models.
When you use component-relative references, you do not need to update all
references when a shared model moves to another server; you only update each user’s
location registry and all references resolve to their new locations. Figure 4 illustrates a
component-relative reference.
Figure 4 Component-Relative Reference

Creating Development Components
Before you create component-relative references, you must first create a development
component:
1 Create a shared folder that your entire team can access. The shared folder is your
development component.
2 On all workstations that must access the shared folder, register the shared folder in
the local XDE location registry:
a Open a model in XDE and select the Model Explorer.
b Click Modeling > Location Registry.
The Location Registry dialog box opens.
c Click the Register new Location button.
d In the Name box, type the name of your shared folder.
e In the Path box, type the location of your shared folder in the UNC format. For
example, \\machineName\shareFolderName.
f Click OK.
3 Add models to the registered shared folder.
You create a cross-model reference by dragging a model element from one model to
another. When you create a cross-model reference that crosses the boundary of a
development component, XDE stores this reference as a component-relative reference.
The XDE location registry resolves a component-relative reference.
Working With Component-Relative References

Component-relative references are useful in certain development environments.
However, because component-relative references require you to plan, create, and
maintain development components, you should carefully choose when to use these
references. We recommend that you use component-relative references only when you
work with platform models or with shared models that are stored outside of source
control.
Working With Platform Models

XDE contains sets of platform models that model the underlying platform services
that are accessed by XDE applications. When you reverse-engineer an IDE project,
XDE creates a code model for that project. The code model accesses XDE platform
models through component-relative cross-model references because XDE registers all
platform models as development components.
Chapter 7 - Working With Cross-Model References 107

Because all cross-model references to platform models are component-relative
references, you can reinstall XDE in any location without breaking cross-model
references to platform models.
Working With Shared Models Outside of Source Control

Your team can share models outside of source control by copying model versions to a
shared folder that is registered as a development component. For more information,
see Creating Development Components on page 107.

Understanding the Basics
of UCM 8
This chapter outlines how to use Unified Change Management (UCM) effectively to
manage change in your software development environment and describes the terms
and concepts used in UCM and ClearCase.
What Is UCM?
UCM is Rational Software’s approach to managing change in software system
development from requirements to release. UCM spans the development lifecycle and
defines how to manage change to requirements, visual models, documentation,
components, test cases, and source code.
The Building Blocks

UCM focuses on these concepts:
■
An activity is a piece of work to accomplish in order to advance the state of your
project. An activity might arise from an issue raised in a meeting, a defect entered
into a defect database, or a request for enhancement sent in by a customer.
Activities are tied to product features and requirements.
■
An artifact is an item, usually a file, that you want to store under version control.
At a more conceptual level, artifacts can be requirements, tests, visual models,
code, project plans, and so on.
One of UCM’s key strengths is that it links the activities used to plan and track project
progress with the artifacts that are undergoing change. UCM is supported by both
process and tools:
■ The Configuration and Change Management workflow in the Rational Unified
Process describes the process of using UCM.
■ Rational ClearCase provides rudimentary support for activity management. For
advanced activity management, you can use Rational ClearQuest to manage your
project’s tasks, defects, and requests for enhancement. ClearQuest also provides
charting and reporting tools that can help you track project progress.
Note: In this manual we show you how to use ClearCase with UCM; you may
want to add ClearQuest to manage your project activities.
■ ClearCase manages all artifacts produced by a software project.
109
Why Use UCM?
Rational customers and employees have successfully used ClearCase for years.
During that time, common patterns have emerged regarding how users set up and
use the tools. Based on our experience and observations, we have created UCM, a
process that helps you get started with ClearCase quickly and easily.
UCM raises the level of abstraction of working with configuration management (CM)
and change management tools. For example, in a typical CM environment, you need
to track the individual files to change. By contrast, with UCM, you work on activities,
letting the tools keep track of the details for you (for example, which files have
changed).
Typical Way to Use UCM

It can be intimidating to consider adding more process to your work day. UCM is
designed to automate much of the bookkeeping for you so that you need to track
fewer details. Figure 5 and the following steps describe a typical way to use UCM.
Figure 5 Typical UCM Workflow

Make
baselines
Rebase
work area
Deliver Work on
activities activities
Integrate Promote
work Development cycle baselines
Project management cycle

1 [one time] A project manager installs Rational software. The project manager sets
up the ClearCase environment and creates a Rational project. (A Rational project
associates Rational tools and enables integrations among them.)
2 [one time] You identify yourself to the project by joining the project. As a result, a
private workspace (consisting of a development stream and a development view) is
created for you. You also gain access to a workspace available to your entire team.
This public workspace consists of an integration stream; you can create a companion
integration view for your own use.
3 Your project manager assigns activities to you.
4 You receive the activities assigned to you. This is your to-do list. From this list, you
decide which activity to work on.
5 You work with artifacts as usual. Using ClearCase, you work in your private
development workspace to:
❑
Check out artifacts. When you check out an artifact, ClearCase asks which
activity you want to work on. In the background, ClearCase keeps track of the
change set (the list of changed artifacts) associated with the activity.
❑
Edit and verify the changes to your artifacts.
❑
Check the artifacts back in. When you check in artifacts, they are still part of
your private workspace. Your changes do not become publicly available until
you deliver them, as described in Step 6.
6 When you have finished work on the activity, you deliver changes for the entire
activity. Because ClearCase keeps track of the change set, you do not have to
specify the list of artifacts to deliver. Delivering the changes makes the changes
publicly available through the integration stream.
7 After developers deliver a set of activities, the project manager (or integrator)
creates a baseline: a new common starting place for all developers that includes the
new activities. On your project, a new baseline may be created on a regular basis,
perhaps even daily.
8 If the changes in the baseline are approved (through testing or through another
review process), your project manager (or integrator) promotes it, making it the
recommended baseline.
9 You rebase your development stream so that when you work on your next activity,
you are starting from the most recent recommended baseline. Restart with Step 4
to select the next activity to work on.
The exercises in this manual describe these steps in more detail and describe other
scenarios you may follow when using UCM.
Chapter 8 - Understanding the Basics of UCM 111

UCM Concepts
The section, What Is UCM? on page 109, describes how you typically use UCM. This
section helps you understand terms and concepts used in UCM and ClearCase.
UCM Basics
UCM provides a complete, out-of-the-box, activity-based change management
process.
Project
UCM organizes development work into projects. The UCM project includes policies
that govern how developers access and update the artifacts (typically, the files and
directories) used in their development effort.
Component
Each project has one or more UCM components, which are groupings of related sets of
files. For example, you might have one UCM component for each of the following
parts of your project: the GUI, the data definitions, and the business logic.
Activity
A UCM activity is a piece of work to accomplish in order to advance the state of your
project. In UCM, an activity is an object that tracks the work required to complete a
development task.
Stream
A stream helps define your workspace. A project has one integration stream, which is
part of the public workspace, and multiple development streams, each of which is
part of a developer’s private workspace. To complete each workspace, you need a
view, described on page 115.
You typically work in a development stream and then deliver your work to the
integration stream. The development stream tracks the activities assigned to you and
lets you work in isolation from the rest of the project team.
Baseline
A baseline is a collection of some or all of the activities delivered to date. A baseline
provides a common starting point for all developers on your project: you can rebase
your development stream so that it contains the changes in the most recent
recommended baseline.

ClearCase Basics
ClearCase helps you manage your project’s artifacts – the files that change as a result
of moving your project closer to its next release.
VOBs and Their Contents

ClearCase stores information in a database, called a versioned object base (VOB). A
VOB contains elements; each element stores a project directory or file. For each
element, ClearCase keeps track of each version you create. For example, in a fairly
simple development environment, one element might have versions as shown in the
version tree in Figure 6. (Each circle represents a version.)
Figure 6 Simple Version Tree

Another element might have a version tree as shown in Figure 7, representing the
creation of more versions, development on separate branches (which start with
rectangular boxes), and merges from one branch to another (denoted by an arrow
from one version to another). The ability to develop on branches and then merge
work together enables a powerful feature of ClearCase: the potential for parallel
development.
Figure 7 More Complex Version Tree
In Figure 7, the branch structures demonstrate how ClearCase lets your team work in
parallel on the same element. Some groups use this branching feature to work on
more than one release of software at a time. UCM uses branches to provide private
work areas (development streams and views) and the public work area (the
integration stream and view).
The arrows from one branch to another represent the merge actions, which lets you
reconcile differences between versions of the same element on different branches.
These merges happen when you deliver work. ClearCase automates most merges,
making it easy to share information developed on separate branches.

Views and Streams
If you are working with branches, ClearCase knows which version of each element
you want to work with. You use a ClearCase view to select one version of each element
in your workspace. In UCM, your stream provides these configuration instructions to
the view. In Base ClearCase, you must configure your view manually.
When you join a project, UCM automatically configures your stream so that you see
the right version for your work environment. A stream also tracks activities and
baselines (the common starting place for members of your project).
Using ClearCase
Typically, you work with version-controlled files in a ClearCase view just as you work
with other files on a networked disk drive. You can open them, print them, and so on.
If you want to change a version-controlled file, however, you must check out the file
from the VOB. You can then edit the file and possibly unit test it. When you reach a
milestone (even if you have not completely finished working on the file), you check in
the file. The section, What Is UCM? on page 109, describes how this check-out, change,
check-in process fits into the general process of using UCM – working on activities
and delivering work to the integration stream.
Behind the Scenes

Every UCM project must have a PVOB (a project VOB). A PVOB stores UCM objects,
including one or more projects, and also streams, activities, and change sets. Typically,
a project manager or configuration manager sets up a project’s PVOB before
ClearCase is installed on client computers.
For More Information

This chapter provides a starting point for understanding UCM. For more information,
see the following resources:
■ To learn more about the Rational Unified Process, read The Rational Unified Process:
An Introduction by Philippe Kruchten. Addison-Wesley, 2000.
■ To learn more about UCM in general, read Software Configuration Management
Strategies and Rational ClearCase: A Practical Introduction by Brian White.
Addison-Wesley, 2000.
■ To learn more about how project managers can set up and manage a UCM
environment, read Rational ClearCase Managing Software Projects (Windows
Edition), part of the ClearCase documentation set.

Designing a ClearCase
UCM Environment 9
Before you set up your ClearCase UCM environment, it’s important to spend time
designing the environment. For example, you need to decide how many versioned
object bases (VOBs) and components you require and how your group will work with
baselines.
This chapter discusses the topics to consider. When you have finished reading this
chapter, you should have a basic understanding of how we designed the Unified
Change Management (UCM) environment for the sample in this book. You should
also have a foundation for making decisions about your own project.
The following table provides some guidelines for starting the design process:
Table 22 Starting the Design Process
Question Answer
How long does the design For a simple project, you can probably accomplish the design
process take? work quickly, perhaps over the course of one or two hours.
For a larger, more complex project, plan to allocate more time.
It is much easier to design and set up an environment right
the first time than to redo a poorly thought out design.
Who should participate in the The team of people who design your ClearCase UCM
design? environment should be fairly small. At least include a
development project leader and a software architect because
your design will be based, in part, on the architecture of your
software project.
What should result from the We recommend that as part of the design process, you create a
design process? plan outlining the decisions you make. This plan will be
important to the people who are implementing and
maintaining your environment, especially if those people do
not participate in the design process.
117
Designing UCM Components
UCM components let you manage the complexity of working with the many
directories and files associated with a software project. When you organize your
project into components, you can view the entire project as a smaller set of
components rather than as a larger set of files and directories. You can use the
components as building blocks for either configuring a product or for releasing it.
When you plan a UCM environment, you designate the components that your team
will work on. These components are separable, reusable parts of the larger project.
Often, you can implement, maintain, and build a UCM component separately from
other components. Roughly, a UCM component might correlate to a code subsystem.
At first glance, you may be tempted to create one UCM component for each
integrated development environment (IDE) project, for example, isolating the
implementation of an interface, or a subsystem, or a DLL. In some cases, this solution
may be right for your team. In this section, we discuss some of the considerations for
designing the component structure for your project.
The Elements of Your Design

The issues you must consider when you design components are described in this
section.
System Architecture
Design your components to reflect your system architecture. So, for example:
■
If you’re using the traditional three-tier architecture – GUI (or presentation layer),
business rules, and data layer – start by designating three components.
■
If your product communicates with different databases, is the communication
code small, compact, and similar?
❑
If so, you might need just one component for that part of the project.
❑
If not – that is, if the communication code requires many lines of code or each
database has different requirements – it will be easier to designate one
component per database that you communicate with.
■
Do you have many IDE projects? If so, you probably do not want the same number
of UCM components because it will be hard to manage that amount of complexity.
Instead, focus on the team structure and the release strategy, as described in the
remainder of this section.

Team Structure
Is your team small? Do you all work in the same location? If so, you need fewer
components. For a larger team, we recommend the following:
■
Assign specific component-based tasks to sub-teams.
■
Do not split work on one component over geographical boundaries.
Release Strategy
It is important to think about your release strategy during component design. For
example:
■
Say your system communicates with different vendor databases. Do you plan to
build, test, and release your entire product on your own schedule? Or will you
release different versions as the database vendors release new versions of their
databases? If you need to release based on an external schedule, we recommend
that you create several components, where each component represents one
database.
■
Do you develop in parallel? Do you need to support your subteams as they
independently develop and deliver parts of the software to each other? If so, your
team structure, system architecture, and component design should all work
together.
Example: Multiple Databases

In this example, your team develops a product that can communicate with multiple
databases. Your group writes drivers to communicate with those databases.
Situation 1: Simple
In one instance, two developers who sit next to each other implement five database
drivers. You release your work based on your company’s schedule, rather than on an
externally-imposed schedule.
In this situation, we recommend that you use one VOB and that you develop the
drivers either in one component or in five sub-VOB components. You might choose to
use five sub-VOB components to build in flexibility in case you need to create
baselines and release each database driver separately.
You have simple development needs; with two co-located developers,
communications are simple and direct. You are implementing, building, and releasing
all five drivers on the same schedule; you never need to treat them separately. One
VOB should be sufficient for this work.
Chapter 9 - Designing a ClearCase UCM Environment 119

Situation 2: More Complex
Now consider a more complex development environment. In this case, 10 developers
implement the drivers, each of which requires a great deal of code. Your team releases
a new driver each time a database vendor issues a new release.
In this situation, we recommend that you create one VOB, containing several
components, each one representing a driver.
This setup allows you to treat each database driver as a separate entity. You can build,
test, and release separately without affecting the other drivers under development.
Example: Multiple GUIs

In this example, your team develops an application that you deliver in multiple
formats. For example, you deliver a thin client, a thick client, a native Windows GUI,
and a Web interface. Consider:
■ Whether the same group of people implements all the GUIs or if each GUI is
implemented by a different team. Your components should reflect the team
structure.
■ Whether the majority of the work is in the communications layer (the common
layer between the application and the individual GUIs) or whether there is a lot of
unshared code related to each GUI. If most of the code is common, then place it in
one component. If most of the code is unshared, consider creating one component
per GUI.
Refining the Design
Administrative Considerations
When you create, work with, and maintain a VOB, you add a small amount of
administrative overhead. Each VOB you create requires administrative and computer
resources (for example, process slots, and backup and restore services). The
requirements for each VOB are not necessarily significant, but they are cumulative, so
that the requirements for many VOBs can be significant.
Storing Multiple Components in a Single VOB

For efficiency, we encourage you to organize your project’s components so that each
VOB contains multiple components. It is inefficient to use a single VOB to store one
small component.
Even if you are storing a single component in a single VOB, we recommend that you
create the VOB so that it can contain multiple components. This strategy gives you
flexibility if you decide later to add a component to that VOB.

Managing Complexity: Read-only or Unavailable Components
You may want to use read-only permissions for a component if another project team
maintains that component and your project uses it. For example, to build your
executable files, you may need a library component that is developed by another
team. In this case, you would make the library component read-only so that your
team could use it but not modify it.
You may consider making some components unavailable. For example, say that in the
current release, you plan to support five database drivers, each developed in its own
component. In the next release, you plan to drop support for one of the drivers. You
can make the obsolete driver’s component unavailable by not including its UCM
component to your UCM project, thereby reducing the number of components that
team members work with.
Designing Directory Structure

ClearCase directory structures do not map exactly to IDE project structures. From a
user’s perspective:
■
All files reside within a view.
■
VOBs are located at the next hierarchical level.
■
A component’s root directory is either at the VOB root (for single-component
VOBS) or one level beneath it (for multiple-component VOBs).
Keep the following guidelines in mind when you design directory structures:
■
You cannot nest components.
■
You cannot place additional files or directories in a component root directory.
■
Store all artifacts related to a component’s features in that component. For
example, for a specific product feature, we recommend that you store code,
requirements, tests, designs, documentation, and other artifacts in the feature’s
component.
■
Include your tool specialists in the design process because some tools impose
directory structure restrictions.
For an example of a project directory structure, see “Organizing Components” in
Rational ClearCase Managing Software Projects.
Other Topics
For more information about working with multiple projects, engaging in parallel
development, and workspace management (working with projects and streams), see
Rational ClearCase Managing Software Projects.

Adding a Component to an Existing Environment
After you start work on a project, you may want to add a component. To add a
component to an existing environment:
1 From the Rational ClearCase Project Explorer, locate the project integration stream.
2 On the integration stream’s properties sheet, go to the Configuration tab and click
Add.
3 Select the component and the baseline of the component to add to the project.
Selecting a baseline in effect specifies which version of the component to add to the
project.
4 To make the component modifiable, go to the Components tab of the project policy
property sheet and follow the instructions there.
Relating Component Design to Release Planning

Ideally, your component design assists with release planning. The project’s
components are independent entities that can be released separately. In fact, just as
each ClearCase element has a set of versions, each component has a set of versions,
called a baseline.
Each baseline contains the set of work that has been delivered to the integration
stream since the last baseline. After you test the baseline to ensure that all the
delivered code works correctly and works well together, you make the baseline the
recommended baseline. Developers can then perform a rebase operation, which merges
files and directories from the integration stream to the development stream.
Composite Baselines
Each component has its own baseline. However, if you are working with multiple
components, you can create a composite baseline. A composite baseline can select other
baselines, including composite baselines.
Promotion Levels
Baselines have attributes, called promotion levels, which you can use to indicate the
quality or stability of a baseline. The default ClearCase promotion levels are:
■
Rejected
■
Initial
■
Built
■
Tested
■
Released

When you promote a baseline, you are assigning a promotion level to it. You can
customize the promotion levels. Also, as the project progresses, you may want to reset
the minimal promotion level to which you will rebase. For example, in the beginning
of a project, you may want to rebase to any new baseline whose promotion level is
Initial. Toward the end of the same project, you may want to ignore all Initial baselines
and rebase only if the promotion level is at Tested or Released.

Scenario: Rational XDE
and Base ClearCase With
IBM WSAD
10
This chapter helps you set up and work in an environment that demonstrates how
Rational XDE supports team development. You start a new project from Java project
templates and practice model-driven, team-oriented development.
The scenario in this chapter specifically involves two roles: configuration manager
and developer. The configuration manager’s user ID is vob_admin. There are two
developers, whose user IDs are dev1 and dev2.
Note: The scenario in this chapter may also be of interest to other roles. For more
information, see Understanding Roles on page 23.
Before You Begin: Installing and Configuring Software

This section identifies the key software installation and configuration tasks that you
must perform before you begin setting up your environment.
Prerequisites
In this scenario, we assume that the following software is installed on client
workstations:
■
WSAD 5.0
■
Rational XDE Developer - Java Platform Edition 2003
■
ClearCase LT Client
Setting Up the ClearCase LT 2003 Environment

In this scenario, we assume that the ClearCase LT 2003 environment is set up as
follows:
■
Rational ClearCase LT Server is installed. This is the shared server where your
team stores the source code control repositories.
125
■
The ClearCase Getting Started Wizard has been run on the ClearCase LT Server to
establish VOB storage locations.
Note: When you run the Getting Started Wizard, do not perform the Import Source
Files optional task. This task imports source files into a VOB named sources. In this
exercise, you create your own VOBs to store all source files.
■
All ClearCase LT Clients are configured to point to the ClearCase LT Server.
Using ClearCase 2003

You can also use ClearCase 2003 for this exercise. Some initial steps are different, but
the ClearCase setup environment (VOBs, views, and so on) is the same.
Setting Up the User Community

ClearCase uses integrated user identity based on the identity of the logged-in user. In
this scenario, administrative operations in the source control system are performed in
a special account, vob_admin. You set this account to use a special group, development,
as its primary group. The users, dev1 and dev2, also set the group development as their
primary group.
If you cannot arrange to set this group as the primary group for users in the domain,
you can do one of the following instead:
■
Use the default group Domain Users as the ClearCase group.
■
Ensure that every user sets their local user environment variable
CLEARCASE_PRIMARY_GROUP to development.
Using the default domain group Domain Users requires less work and prevents the
need to use the environment variable, but it allows all users in the domain to read and
potentially modify the ClearCase data. Using a special group provides a first-level of
information hiding that restricts access to the ClearCase repositories (VOBs) to users
in this group.
Configuring ClearCase Groups and Environment Variables

In this exercise, you configure your ClearCase group as development and set the
environment variable on your workstation.
If you use local accounts, create the local users and the group, and add the users to the
group. Otherwise, arrange for your network administrator to perform these tasks in
the domain.
To configure your ClearCase group locally:
1 Log in as the vob_admin.
2 Add vob_admin to the development group on your workstation.

Set a user environment variable. On Windows XP:
1 On the Control Panel, open the System application. On the Advanced tab, click
Environment Variables.
2 Click New.
3 In the New User Variable dialog box, set Variable name to
CLEARCASE_PRIMARY_GROUP. Set Variable value to development. Click OK.
The Environment Variables dialog box should include the highlighted line as follows:
Setting Up the ClearCase Environment

In this section, you set up your ClearCase environment by creating VOBs and a view.
Chapter 10 - Scenario: Rational XDE and Base ClearCase With IBM WSAD 127
Planning VOBs
As the number of files and directories in your system increases, you need a way to
reduce the complexity of managing them. VOBs are the ClearCase mechanism for
simplifying the organization of your files and directories. The elements that you
group into a VOB typically implement a reusable piece of your system architecture.
By organizing related files and directories into components, you can view your
system as a small number of identifiable components, rather than as one large set of
directories and files.
Creating VOBs
ClearCase stores file elements, directory elements, derived objects, and metadata in a
repository called a VOB.
Create three VOBs, one for each major IDE project:
1 Start the VOB Creation Wizard: click Start > Programs > Rational Software >
Rational ClearCase > Administration > Create VOB.
The Name and Major Parameters page appears.

2 In the What would you like the new VOB to be named? box, type atlas_gui.
3 Click Next.
The Components page appears.
4 Click the Create a VOB as a single VOB-level component button.
5 Click Finish.
The Confirmation dialog box appears.
6 Click OK.
7 Repeat Step 1 to Step 6 twice to create the following VOBs:
❑ atlas_services
❑ atlas_data_layer
Creating a View
While logged in as vob_admin, create the administrator’s view so that you can create
and populate the initial framework projects and file artifacts:
1 Start the View Creation Wizard: click Start > Programs > Rational Software >
Rational ClearCase > Create View.
2 On the Choose a Project page, click No to the question about working on a project
in the ClearCase project tree.

3 Click Next.
4 On the Choose Location for a Snapshot View page, accept the default path or type
another path that is on your computer.
The last part of the path is the name of the view. To follow this scenario, make sure
it is vob_admin_view, so that the full path you include here is, for example:
C:\temp\views\vob_admin_view
You may be prompted to create this area.

5 On the Confirm page, click OK to create the view.
When the view has been created, you are prompted to load elements into your
view. (Snapshot views work by copying files onto your disk. In the next step, you
select the sets of files to copy.)
6 On the Choose Elements to Load dialog box, select each of the VOBs you created
and click Add.
7 Click OK.
Starting XDE
1 Start XDE: click Start > Programs > Rational Software > Rational XDE in ClearCase
View.
2 XDE prompts you to select the ClearCase view to use. Select vob_admin_view to
begin your work.
Your IDE starts.
Creating a Java Modeling Project and XDE Models

In this section you create a sample Java modeling project and XDE models.
Creating a Java Modeling Project

To create the first project:
1 In the IDE, click File > New > Project.
2 On the New Project page:
❑
In the left pane, select Modeling.
❑
In the right pane, select Java Modeling Project.
3 On the XDE Java Project page:
❑
Assign the project name data_layer_project_1.
❑
Clear the Use default location check box.
❑
Specify the location by navigating to your view. Ensure that the project name is
specified in the path; for example:
C:\temp\views\vob_admin_view\atlas_data_layer\data_layer_project_1
❑ Click Finish.
A dialog box appears, prompting you to add the XDE Java code model to source
control.
4 On the Add Element(s) to Source Control dialog box, clear the Keep checked out
check box. Click OK.
A second dialog box appears, prompting you to add to source control. You see the
second dialog box as a side-effect of the integration: one is for the XDE models and
the second is for all other files.
5 Clear the Keep checked out check box. Click OK.
6 Follow Step 1 through Step 5 to create two more projects:
❑
Name: midd_tier_project_1
Example location: C:\temp\views\vob_admin_view\atlas_services\midd_tier_project_1
❑
Name: gui_project_1
Example location: C:\temp\views\vob_admin_view\atlas_gui\gui_project_1
Validating Models
We recommend that you validate your models frequently.
To validate a code model:
1 In the IDE, click the Navigator tab.
Note: You can also go to the Navigator by clicking Window > Show View >
Navigator.
2 Under data_layer_project_1 [vob_admin_view], double-click Java Code Model.mdx.

3 In the Model Explorer, right-click (data_layer_project_1) Java Code Model and then
click Validate.
Creating XDE Models

In a typical development environment, you create code models for code-related
aspects of your system via round-trip engineering. There are also parts of the system
not directly related to the code, for which you should create a content model; for

example, the system’s use cases or system architecture. In this section, you create an
XDE content model using the Getting Started model template and add this model to
gui_project_1:
2 Right-click gui_project_1 [vob_admin_view] and then click New > Model.
3 In the New XDE Model dialog box:
❑
In the left pane, select Rational XDE.
❑
In the right pane, select Getting Started.
❑
In the File name field, type System Model.
❑
In the Destination folder field, type gui_project_1.
❑
Click Finish.
check box and click OK.
5 Repeat Step 1 to Step 4 to add the following content models, all using the Blank
Model template:
❑
Add gui model to gui_project_1.
❑
Add services model to midd_tier_project_1.
❑
Add data model to data_layer_project_1.
Dividing a Model to Allow Concurrent Use

On a typical project, multiple team members who contribute in different disciplines
want to make changes to their parts of the system model concurrently. In general, we
suggest dividing models into the smallest number of subunits that allow multiple
users to work on (check out and edit) models while minimally interfering with the
work of other team members. We call this practice strong model ownership.
Composite Object Versioning Support

Because modifications in one part of a model can result in modifications in other parts
of the model, it is important that all related modified units be synchronized and
managed as a single logical unit for configuration management purposes at key
delivery points into configuration management (CM).
Prior to Rational XDE version 2002.05.20, Release 2.1, Service Release, there was no
automated support for treating models as a composite object. The Service Release
introduced composite object versioning (COV) operations that facilitate the
management of a model and all subunits in it linked to user gestures that perform
various CM operations.
The general purpose of COV is that operations performed on a single or subset of
subunits expand to include the entire file closure of the model. For example, if you
have a model with two classes, class1 and class2, which are both stored as separate
subunit files (class1.clx and class2.clx), and both class files are checked out, and you
attempt to check in just class1, the checkin automatically expands to include both
class1 and class2.
Note: COV applies within a single model only. Operations do not expand across
cross-model references to include all the referenced models.
For more information, see the XDE Help.
General Behavior
The usual CM dialog boxes are presented at the expected times. Users will observe
that there can be more files listed than were asked for. Users can override the COV
expanding behavior and deselect the additional files. Users can also cancel the entire
operation. It is recommended that users follow the suggestions and perform all the
operations on the entire set of units presented to ensure that a consistent and
complete baseline of model subunits is committed to the VOB at the same time. Users
in other views will then be able to update their models and see a consistent and
complete set of model elements.
Navigator Limitations
We recommend that you initiate CM operations from the Model Explorer because the
implementation of COV is more comprehensive from that window. In the Navigator,
the COV is only enabled if the selected unit is the root model file.
Dividing a Model Into Subunits

In this section, you divide the system model into subunits to make concurrent editing
more efficient.
1 In the IDE, click the Model Explorer tab.
Note: You can also go to the Model Explorer by clicking Window > Show View >
Model Explorer.
2 Under (gui_project_1) System Model, right-click Deployment and then click Make a
Separate Unit.
3 When you are prompted to check out the System Model file, click OK.
4 Repeat Step 2 to place the following model elements in separate files:
❑
Design
❑
Implementation View
❑
Use Cases

You have now stored the model elements in separate physical files, enabling team
members from separate disciplines to work on these files independently.
The initial framework design for the project is now complete.
5 Save your work: Click File > Save All.
Saving Your Work Consistently

When you work with subunits, we recommend that you save your work by using the
File > Save All menu item. If you use the File > Save menu item (or Ctrl + S), your work
may not be saved consistently.
For example, you change one subunit which results in changes in two other subunits.
If you save only the first subunit and not the two others, the files saved on disk will be
inconsistent with one another. If, instead, you use the File > Save All menu item, all
three changed files will be saved to disk and the files on disk will be consistent with
one another.
Adding Java Classes to the Framework

In this section, you complete the initial framework by adding a Java class to the data
layer project:
2 In the Navigator, under data_layer_project_1 [vob_admin_view], open Java Code
Model.mdx.
3 From the Toolbox in the left pane, navigate to Java > Java Class. Drag Java Class
to the Main diagram of Java Code Model.mdx.
The Create Java Class dialog box appears.
4 In the Name box, type FirstClass and click OK.
5 At the prompt to check out, click OK.
6 Repeat Step 2 to Step 5 to add a class called FirstClass to Java Code Model.mdx
under midd_tier_project_1.
Generating Code for the Classes

If you choose to work with the XDE AutoSync preference cleared, then you must
generate code for classes manually. If you choose to work with the XDE AutoSync
preference selected, XDE automatically generates code for classes.
To check the status of the XDE AutoSync preference:
1 Click Window > Preferences.
The Preferences dialog box appears.
2 Expand Rational XDE and then click Code-Model Synchronization.
If the AutoSync preference is cleared, generate code manually for the new classes
you created.
3 Click OK to close the Preferences dialog box.
To generate code manually for the classes:
click Synchronize.
4 Repeat Step 2 to Step 3 to generate code for the class in (midd_tier_project_1) Java
Code Model.
Saving, Validating, and Checking In

To complete this part of the exercise, leave your environment in a stable state:
1 On the Modeling - Application menu, click File > Save All.
2 Validate the open models to ensure that they are consistent. For more information,
see Validating Models on page 130.
3 Ensure that all files are checked in:
❑
In the IDE, click the Model Explorer tab.
❑
In the Model Explorer, select all the files.
❑
Right-click and then click Team > Check In.
❑ In the Check In Element(s) dialog box, click OK.
Checking in files has made them visible to other users sharing your branch. You are
using \main branch development, and the other users are too, so they can see changes
the next time they update their view.
Creating a Project Set File

In this section you create a project set file (.psf), which will allow users of other views
to open (in one operation) the three projects you created.

In Eclipse, the Eclipse Workspace stores information about how projects are associated
with the Eclipse instance. The Eclipse Workspace concept is generally equivalent to a
VS.NET Solution file, except the Eclipse Workspace is stored separately from the
projects.
The Eclipse Workspace can provide more flexibility but it can make working with
ClearCase more difficult because you have to maintain awareness of the separate
workspace and manage it manually.
To create a project set file:
1 In the Modeling - Application Developer window, click the Navigator tab.
2 Collapse all three projects.
3 Select all three projects.
4 Click File > Export.
5 On the Export page, select Team Project Set and click Next.
6 On the Team Project Set page, ensure that all three projects are selected.
7 Click Browse.
The Save As dialog box appears.
8 Navigate to the gui_project_1 project directory in your current view. For example:
C:\temp\views\vob_admin_view\atlas_gui\gui_project_1
9 In the File name box, type atlas_projects.

10 Click Save to return to the Team Project Set page.
The File name box should show that atlas_projects.psf is located in your view,
under the gui_project_1 project directory. For example:
C:\temp\views\vob_admin_view\atlas_gui\gui_project_1\atlas_projects.psf
Note: Always save your Project Set File in a project directory that is within the
view that is associated with your workspace.
11 Click Finish.
Adding the Project Set File to Source Control

To add the project set file to source control:
2 Right-click gui_project_1 [vob_admin_view] and then click Refresh.
4 Exit the IDE: click File > Exit.
5 Log out as vob_admin.
Developing as Part of a Team

At this point in the scenario, the administrator has finished setting up the
environment. In this section, we switch our attention to the development process.
There are two users on your team, dev1 and dev2.
Setting Up the Developers’ Work Areas

In this section, you set up the individual work areas for dev1 and dev2:
1 Log in as dev1.
2 Set a user environment variable CLEARCASE_PRIMARY_GROUP to your domain
development. For more information, see Setting Up the User Community on page 126.
3 Create a dev1_view snapshot view:

a Start the View Creation Wizard, click Start > Programs > Rational Software >
b On the Choose a Project page, click No to the question about working on a

project in the ClearCase project tree.
c On the Choose Location for a Snapshot View page, accept the default path or
type another path that is on your computer.
The last part of the path is the name of the view. To follow this scenario, make
sure it is dev1_view, so that the full path you include here is, for example:
C:\temp\views\dev1_view

d On the Confirm page, click OK to create the view.
view. (Snapshot views work by copying files onto your disk. In the next step,
you select the sets of files to copy).
e On the Choose Elements to Load dialog box, select the VOBs that are part of
this scenario and click Add:
➑
atlas_services
➑
atlas_gui
➑
atlas_data_layer

f The VOBs appear in the Selected Elements list; click OK.
4 Log off as dev1 and repeat Step 1 to Step 3 to set up the environment for dev2.
Starting to Work in XDE

In this section, the dev1 user starts a modeling task as follows:
1 Log in as dev1.
View.
3 XDE prompts you to select the ClearCase view to use. Select dev1_view and click
OK.
Your IDE starts.

4 In the IDE, click File > Import.
5 On the Import page, select Team Project Set and click Next.
6 On the Team Project Set page, click Browse and navigate to the location of your
atlas_projects.psf file. The file is located in dev1_view (your development view),
C:\temp\views\dev1_view\atlas_gui\gui_project_1\atlas_projects.psf
7 Select atlas_projects.psf and click Open.
8 Click Finish.
The three projects load into your IDE.
Adding to the XDE Model

Create a subsystem use case package on each of the main diagrams:
1 In the IDE, click in the Navigator.
2 Under midd_tier_project_1 [dev1_view], open services model.mdx.
3 From the Toolbox in the left pane, drag a UML Use Case Package to the Main
diagram of services model.mdx.
4 At the prompt to check out files, click OK .
5 Rename the package services use cases.
6 Repeat Step 1 to Step 5 for the other two model files as follows:
❑ Under gui_project_1 [dev1_view], open gui_model.mdx and create a UML Use
Case Package called gui use cases.
❑
Under data_layer_project_1 [dev1_view], open data_model.mdx and create a
UML Use Case Package called data use cases.
7 Click File > Save All.
Creating Cross-Model References

So far, each model element is stored in a separate model. In this section, you create
references from one model to another. These references are called cross-model
references. Normally, the system handles cross-model references and you do not have
to worry about them. Later in this scenario, you will resolve inconsistencies in a
cross-model reference.
To create a cross-model reference:
2 Under gui_project_1 [dev1_view], open System Model.mdx.
3 In the Model Explorer, select (gui_project_1) System Model. From the Modeling
menu, click Add Diagram > Free Form.
4 When the Check Out Element(s) dialog box appears, click OK.
5 In the Model Explorer, rename the new diagram Atlas System Use Cases.
6 From the Model Explorer, drag the nodes for the following three use-case
packages onto the new diagram:
❑
gui use cases
❑ services use cases
❑
data use cases
On the new diagram, each package should have an arrow indicator in the top left
corner which identifies that the packages are cross-model references.
8 Check in all files:
a In the Model Explorer, select all files.
b Right-click and then click Team > Check In.
c When the Check In Element(s) dialog box appears, click OK.
You have created cross-model references.

Importing the Project Set File
Earlier in this scenario, you set up the work environment for dev2 and created a view.
When you loaded the view, you loaded the files corresponding to the \main\LATEST
version at the time the view was created. This version consisted of the basic
framework before dev1 started to work. Before you start to change the models, you
need to update your view by importing the project set file and update your view to
see the latest changes. Work as follows:
1 Log in as dev2.
View.
3 XDE prompts you to select the ClearCase view to use. Select dev2_view to begin
your work.
Your IDE starts.
4 Import the project set file to load the set of models into your environment: Click
File > Import.
atlas_projects.psf file. The file is located in dev2_view (your development view),
C:\temp\views\dev2_view\atlas_gui\gui_project_1\atlas_projects.psf
8 Click Finish.
9 Update dev2_view: from the ClearCase toolbar, click Update View.
10 The ClearCase Snapshot View Update dialog box appears and shows what has
changed since the last update. Exit the dialog box: click File > Exit.
Tips for Working with ClearCase

We caution you not to work in ClearCase outside the IDE when the IDE is running.
Independent ClearCase activities that can cause problems include checkouts or view
updates; these actions can cause items (versions, elements, projects) to be loaded into
your view. Eclipse does not include a mechanism to notify the shell of changes in the
file or directory structure. If you do create this situation, resolve it as follows:
1 In the Navigator, right-click a project and then click Refresh From Local.
2 In the Navigator, right-click a project and then click Team > Refresh Status.
These actions synchronize the file system state on disk with the in-memory state of
the Navigator and the source control status.
Note: Certain ClearCase operations that trigger merges can be initiated from outside
the IDE for performance reasons. For more information, see Starting a Session In an
Starting Parallel Development: Comparing and Merging Models

In this section, you perform parallel development. The two users on your team make
different changes to the same model element. In the next section, when the second
user tries to check in, they must do a merge to resolve the differences. The following
table describes the work you will do in this section:
Step dev1 activities dev2 activities
1 Checks out file

Makes changes
Keeps file checked out
Quits XDE
2 Checks out same file (unreserved)

Makes conflicting change
Quits XDE
3 Checks in file reserved
4 Checks in file
(Next section) tries to check in, but needs
to merge first.
Suppose that two users make a conflicting change when they both change the same
element and check in their changes. This generates a merge conflict when the second
user starts to check in.
XDE’s compare/merge functionality allows you to compare and track different model
elements, identify the differences between them, and merge models.

Introducing Conflicts into the Model
In this section, dev2 introduces a change and leaves the files checked out until dev1
checks out and makes conflicting changes to the same files:
1 As dev2, in the IDE, click the Navigator tab. Under midd_tier_project_1, open
services model.mdx.
2 In the Main diagram, click on the services use cases package and rename to dev2
middle tier.
3 When prompted to check out files, click OK.

5 Quit XDE: Click File > Exit. When you are prompted to check in your work, click
Cancel; you want to keep the files checked out.
6 Now repeat Step 1 to Step 5, this time logging in as dev1. Note the following:
❑ Rename the services use cases package to dev1 middle tier.
❑ When you are ready to check out the file, ClearCase prompts you to check the
file out unreserved because only one checkout per branch can be reserved and
dev2 holds the reservation.
7 Log in as dev2 again and check in your work as follows:
a Start XDE and, when prompted, select your view.
b In the Navigator, open services model.mdx.
c In the Model Explorer, right-click (midd_tier_project_1) services model and then
click Team > Check In.
d Click OK to complete the check in.
8 Quit the IDE. Click File > Exit.
Resolving the Conflict

At this point, dev1 and dev2 have both made changes to the same file. The dev2 user
has checked in changes (dev2 had a reserved checkout). The dev1 user has not yet
checked in changes. When dev1 checks in changes, ClearCase displays a prompt to
merge so that dev1 can resolve the changes. Proceed as follows:
1 Log in as dev1.
2 Start your IDE. When prompted, choose your development view (dev1_view).
3 In the Navigator, open services model.mdx.
4 In the Model Explorer, right-click (midd_tier_project_1) services model and then
5 Click OK.
A message appears saying that there are later versions of the file on this branch,
and asking whether you want to merge now.
6 Select the Merge the file graphically check box and click Yes.
Merging Changes
XDE automatically resolves each difference. The Comparative Model Explorer and
the Comparative Property Browser show the Conflict (C), Resolution (R), and
Difference (D) status columns for the merged model and the selected contributors.
A Merged column shows the resolutions applied to the individual model elements.
7 In the Semantic Comparative Model Explorer, select the model element showing
the conflict.
8 On the Merge menu, click Resolve Using > Resolve Using Contributor 3 to resolve
the conflict associated with the selected model element in the merged model with
the specified contributor 3.
9 Click File > Compare/Merge > Save and Commit ClearCase Session.
10 Before XDE closes, it prompts you to check in files. Click Yes.
The merge is now complete and the results are under ClearCase control.
Refactoring: Adding, Moving, and Deleting Files

In this section, you learn how to change the files on your project, keeping the XDE and
ClearCase file spaces consistent.
Consider the following scenario: You learn that your application will support many
data sources, not just one. You decide to create models for each so that you do not
clutter the name space in the project directory. You create a models subdirectory to
store all the XDE models. This section shows you how to move the model file
data model.mdx from its location in the project directory to the models subdirectory.
To create and populate a new folder in the project:

1 While logged in as dev1, in the IDE Navigator, right-click data_layer_project_1 and
then click New > Folder.
2 Name the new folder Models and click Finish.
3 When prompted to add to source control, select the Keep checked out check box
and click OK.
4 In the Navigator, drag the data model.mdx file into the new Models folder.
5 Check in all files. The data model.mdx file and its directory are now checked into
ClearCase.

Resolving Broken Cross-Model References
The cross-model references in the model you moved are now broken. Resolve these
broken references as follows:
1 In the Model Explorer, close System Model if it is open.
2 In the IDE Navigator, under gui_project_1, open System Model.mdx.
A Missing models dialog box appears. This message is normal because you moved
the file. However, the cross-model references to the model element (data use cases
package for the data_layer_project_1 of the application) are not updated. You must
resolve these broken references.
3 Click Resolve.
The Unresolved External References dialog box appears.
Note: If you choose Ignore and open the system use cases diagram, an icon
(crossed-out stop sign) appears on the model element that has the broken
reference(s). If you see this icon, you need to resolve broken references.
4 In the left pane, select the data model.mdx file.
5 In the Full box, browse to the new location of the data model.mdx file (in the new
Models folder).
6 Click Apply.
7 If you are prompted to check out, click OK.
You have now resolved the broken references in the data model.mdx file.
8 Check in all files.
Note: You can avoid resolving broken references this way by validating your models
before every check in.
This concludes the initial setup of a team development infrastructure.
and UCM With IBM WSAD 11
Rational XDE supports team development. You start a new project from Java project
templates and practice model-driven, team-oriented development.
and developer. The configuration manager’s user ID is ucm_admin. There are two

Prerequisites
workstations:
■
WSAD 5.0
■
Rational XDE Developer - Java Platform Edition 2003
■
ClearCase LT Client

follows:
■
■
The ClearCase Getting Started Wizard has not been run on the ClearCase LT
Server.
■
145

a special account, ucm_admin. You set this account to use a special group, development,
primary group.
■ Use the default group Domain Users as the ClearCase group.
■ Ensure that every user sets their local user environment variable
in this group.

the domain.
1 Log in as the ucm_admin.
2 Add ucm_admin to the development group on your workstation.
2 Click New.


To set up the ClearCase environment in this exercise, the administrative user
(ucm_admin) follows these high-level steps. You typically perform this setup once.
1 Set up your initial project by performing the following:
a Create a project VOB.
b Create a UCM project.
2 Plan how your UCM components map to your IDE project components.
3 Create UCM component VOBs.
4 Create ClearCase work areas by:
Chapter 11 - Scenario: Rational XDE and UCM With IBM WSAD 147
a Creating a development stream.
b Creating an integration stream.
c Creating a development view.
d Creating an integration view.
e Loading the new VOBs into your work area.
5 Register your UCM components as modifiable by:
a Adding foundation baselines to your UCM project.
b Changing UCM project policies for the UCM components.
6 Synchronize the integration stream.
7 Recommend a new baseline.
8 Rebase your development stream.
Creating the Initial Project VOB and UCM Project

repository called a versioned object base (VOB). Each UCM project must have a
project VOB (PVOB). A PVOB is a special kind of VOB that stores UCM objects, such
as projects, activities, and change sets. A PVOB must exist before you can create a
UCM project.
As the administrative user, create a PVOB called projects and a UCM project called
InitialProject by completing the ClearCase Getting Started Wizard.
To create a PVOB and UCM project:
1 Log on as ucm_admin on the ClearCase LT server.
2 Click Start > Programs > Rational Software > Rational ClearCase > Administration >
Getting Started Wizard.
The Rational ClearCase LT Getting Started Wizard page appears.

3 Click Next.
4 On the next page, accept the default directory for storing the ClearCase LT
database and click Next.
5 On the next page, accept the default Source VOB Name and Name of Initial
Component and click Next.
6 On the next page:

a In the Starting UCM Project Name box, ensure that InitialProject is entered.
b Select the Parallel stream project button and click Next.

7 On the next page, click Next to configure the server with the listed settings.
8 On the next page, click Close.
Note: The Import Source Files option is not appropriate for Eclipse projects because
Eclipse contains the logic that determines what file types should be placed under
source control. You do not use this initial repository sources, which you delete later in
the exercise.
Verifying VOB Ownership

To verify that VOB ownership is ucm_admin\development:
1 From the Start menu, click Run.
The Run dialog box appears.
2 Type cleardescribe vob:\projects
3 Click OK.
You should see the following:
Planning UCM Components
reduce the complexity of managing them. Components are the UCM mechanism for
group into a component typically implement a reusable piece of your system
architecture. By organizing related files and directories into components, you can
view your system as a small number of identifiable components, rather than as one
large set of directories and files.
Within a component, you organize directory and file elements into a directory tree.
You can convert existing VOBs or directory trees within VOBs into components, or
you can create a component from scratch.
Note: The directory and file elements of a component reside physically in a VOB. The
component object resides in a PVOB.
Creating VOBs
repository called a VOB. In ClearCase, a UCM component can be stored as the only
component in a VOB or as one of several components in a VOB. In this exercise we set
up the VOBs so that they can each contain one component only.

3 Click Next.
5 Click Finish.
6 Click OK.
❑
atlas_services
❑
atlas_data_layer

Creating ClearCase Work Areas
With UCM, a work area is the user work environment that is implemented with two
objects: a stream and a view. A stream defines the working configuration for the view
(or views) associated with it. A UCM project has one integration stream, which is part
of the shared work area, and multiple development streams, each of which is part of a
developer’s private work area.
You typically work with a development stream, then deliver your work to the
lets you work in isolation from the rest of the UCM project team.
A view selects the appropriate versions of files and directories, as defined by a set of
configuration rules, from all available versions in the VOB. ClearCase provides two
types of views: snapshot and dynamic. With snapshot views, files are copied from the
VOB to the local disk. Dynamic views reference files directly in the VOB.
Note: ClearCase LT uses snapshot views only.
Create work areas to populate the initial project framework and file artifacts.
To create a work area:
1 While logged in as ucm_admin, in the ClearCase Project Explorer, right-click
InitialProject and then click Join Project.
The Choose a Project page appears.

2 Ensure that InitialProject is selected and click Next.
The Create a Development Stream page appears.
3 Accept the default stream names and click Next.
The Choose Location for a Snapshot View page appears.
4 In the Where would you like the root of this view? box, specify the development
view location (for example: C:\temp\views\ucm_admin_InitialProject) and click
Next.
5 In the Where would you like the root of this view? box, specify the integration view
location (for example: C:\temp\views\ucm_admin_InitialProject_int) and click Next.
The Choose Components pages appears.
6 Select the Start component browser after creating view check box.
7 Clear the InitialComponent check box. Later, you create new components and add
them to the UCM project.
8 Click Finish.
The Confirm dialog box appears.
9 Click OK.
10 When the Choose Elements to Load dialog box appears:
a Select the Show All VOBs check box.

b From the Available Elements pane, add atlas_services, atlas_gui, and
atlas_data_layer to the Selected Elements pane, and click OK .
11 Click OK.
Your work area is rooted under ucm_admin_InitialProject (for example:

C:\temp\views\ucm_admin_InitialProject). In ClearCase, each VOB appears as a
subdirectory under the view root. UCM components can exist either as an entire VOB,
or as first-level subdirectories underneath a VOB. In this exercise, each of the three
components is located in a separate VOB.
Registering UCM Components as Modifiable

With UCM, you must register all components that you want to be modifiable in your
UCM project. Currently, only the component called sources, which you will delete
from your UCM project, is registered as modifiable.
Register your three new VOBs as modifiable by:
■
Adding foundation baselines to your UCM project.
■
Changing UCM project policies for the UCM components.
Adding Foundation Baselines to Your UCM Project

Add baselines to your UCM project that serve as the starting point for your team’s
developers. A baseline identifies one version of every element visible in a component.
To add foundation baselines to your UCM project:
1 In the ClearCase Project Explorer, right-click IntegrationStream and then click
Properties.
The Properties dialog box appears.

2 Select the Configuration tab.
3 Click Add.
The Add Baseline dialog box appears.
4 Click the Change button and select All Streams.
5 From the Component list, select atlas_data_layer.
6 In the bottom pane, select the atlas_data_layer_INITIAL baseline.
7 Click OK.

8 Repeat steps 4 to 7 twice to add the atlas_gui and atlas_services foundation
baselines.
9 Click OK.
10 The Rebase Stream Preview dialog box appears. Click OK to start the integration
stream rebase.
11 Complete the rebase by accepting all defaults.
Changing UCM Project Policies for the UCM Components

The three UCM components in this exercise currently have read-only permissions. To
enable components to be modifiable, change the UCM project policies for each
component.
To change UCM project policies for the UCM components:
1 In the ClearCase Project Explorer, right-click InitialProject and then click Policies.
The Policies dialog box appears.
2 On the Components tab, select the atlas_data_layer, atlas_gui, and atlas_services
check boxes and clear the InitialComponent check box.
3 Click OK.
The ClearCase Project Explorer dialog box appears and explains that you need to
synchronize the integration stream so that it’s updated with the new list of
modifiable components.
Click OK.
Synchronizing the Integration Stream

Update your integration stream with the latest changes by performing a synchronize
operation.
Note: You only need to synchronize the integration stream when the components in a
UCM project change. You rarely perform this activity after a UCM project starts.
To synchronize with the integration stream:
Properties.
2 Select the Views tab.

3 Select the view (there should only be one view) and click the Properties button.
4 On the General tab, click the Synchronize with stream button.
The Start Update dialog box appears.
5 Click OK.
The ClearCase Snapshot View Update window appears.
6 Click File > Exit.
Recommending a Baseline
You organize delivered activities into baselines. A baseline identifies one version of
every element visible in a component. Usually baselines go through a cycle of testing
and defect fixing until they reach a satisfactory level of stability. When a baseline
reaches this level, you designate it as a recommended baseline.
When developers join the UCM project, they populate their work areas with the
versions of directory and file elements represented by the UCM project’s
recommended baseline. Alternatively, developers can join the UCM project at a
feature-specific development stream level, in which case they populate their work
areas with the development stream’s recommended baseline. This practice ensures
that all members of the UCM project team start with the same set of files.
Recommend a new baseline to make the changes to your UCM project available to
developers.
To recommend baselines:
1 In the Project Explorer, right-click IntegrationStream and then click Recommend
Baselines.
The Recommended Baselines dialog box appears.

2 Select InitialComponent and click the Remove button.
3 Click the Add button.
6 Click OK.
7 Repeat steps 3 to 6 twice to recommend the atlas_gui and atlas_services baselines.
8 Click OK.
Rebasing Your Development Stream

The ClearCase rebase operation provides a way for you to update work areas with
work that has been integrated, tested, and approved for general use. This work is
represented by baselines.

To work with the set of versions in the recommended baseline, you rebase your work
area. To minimize the amount of merging necessary while you deliver activities, you
rebase your work area with each new recommended baseline as it becomes available.
After you rebase, you typically build and then test the source files in your
development view to verify that your undelivered activities build successfully with
the versions in the baseline.
Update your work area with the latest UCM project changes by rebasing your
development stream to the recommended baseline on the integration stream.
To rebase the development stream:
1 In the ClearCase Project Explorer, right-click ucm_admin_InitialProject and then
click Rebase Stream.
The Rebase Stream Preview dialog box appears.
2 Click OK to start the development stream rebase.
3 Click Complete when the Rebasing in View dialog box appears.
4 Click Close.
Starting XDE
View.
2 XDE prompts you to select the ClearCase view to use. Select

ucm_admin_InitialProject to begin your work.
Your IDE starts.
Creating a Java Modeling Project and XDE Models

In this section you create a sample Java modeling project and XDE models.
Creating a Java Modeling Project

To create the first project:
1 In the IDE, click File > New > Project.
2 On the New Project page:
❑
In the left pane, select Modeling.
❑
In the right pane, select Java Modeling Project.
3 On the XDE Java Project page:
❑
Assign the project name data_layer_project_1.
❑
Clear the Use default location check box.
❑
Specify the location by navigating to your view. Ensure that the project name is
specified in the path; for example:
C:\temp\views\ucm_admin_InitialProject\atlas_data_layer\data_layer_project_1
❑ Click Finish.
A dialog box appears, prompting you to add the XDE Java code model to source
control.
check box. Click OK.
5 You may need to create a UCM activity to record the versions being created. If you
are prompted, create an activity with name initial add to source control.
A second dialog box appears, prompting you to add to source control. You see the
second dialog box as a side-effect of the integration: one is for the XDE models and
the second is for all other files.
6 Clear the Keep checked out check box. Click OK.
7 When you are prompted for an activity, reuse the existing activity. Click OK.
8 Follow Step 1 through Step 7 to create two more projects:
❑
Name: midd_tier_project_1
Example location:
C:\temp\views\ucm_admin_InitialProject\atlas_services\midd_tier_project_1
❑
Name: gui_project_1
Example location: C:\temp\views\ucm_admin_InitialProject\atlas_gui\gui_project_1
Validating Models
We recommend that you validate your models frequently.
Note: You can also go to the Navigator by clicking Window > Show View >
Navigator.
2 Under data_layer_project_1 [ucm_admin_InitialProject], double-click Java Code

Model.mdx.

click Validate.
Creating XDE Models

aspects of your system via round-trip engineering. There are also parts of the system
not directly related to the code, for which you should create a content model; for
example, the system’s use cases or system architecture. In this section, you create an
XDE content model using the Getting Started model template and add this model to
gui_project_1:
2 Right-click gui_project_1 [ucm_admin_InitialProject] and then click New > Model.
3 In the New XDE Model dialog box:
❑
In the left pane, select Rational XDE.
❑
In the right pane, select Getting Started.
❑
In the File name field, type System Model.
❑
In the Destination folder field, type gui_project_1.
❑
Click Finish.
5 When you are prompted for an activity, reuse an existing activity or create a new
one. Click OK.
6 Repeat Step 1 to Step 5 to add the following content models, all using the Blank
Model template:
❑
Add gui model to gui_project_1.
❑
Add services model to midd_tier_project_1.
❑
Add data model to data_layer_project_1.

managed as a single logical unit for configuration management purposes at key
delivery points into configuration management (CM).
class1 and class2.
General Behavior
in other views will then be able to update their models and see a consistent and
complete set of model elements.
Navigator Limitations
implementation of COV is more comprehensive from that window. In the Navigator,
the COV is only enabled if the selected unit is the root model file.

more efficient.

Note: You can also go to the Model Explorer by clicking Window > Show View >
Model Explorer.
2 Under (gui_project_1) System Model, right-click Deployment and then click Make a
Separate Unit.
3 When you are prompted to check out the System Model file, click OK.
4 When you are prompted for an activity, create a new activity called check out. Click
OK.
5 Repeat Step 2 to place the following model elements in separate files:

❑
Design
❑
Implementation View
❑
Use Cases
You have now stored the model elements in separate physical files, enabling team
members from separate disciplines to work on these files independently.
The initial framework design for the project is now complete.
one. Click OK.
Saving Your Work Consistently

When you work with subunits, we recommend that you save your work by using the
File > Save All menu item. If you use the File > Save menu item (or Ctrl + S), your work
may not be saved consistently.
For example, you change one subunit which results in changes in two other subunits.
If you save only the first subunit and not the two others, the files saved on disk will be
inconsistent with one another. If, instead, you use the File > Save All menu item, all
three changed files will be saved to disk and the files on disk will be consistent with
one another.
Adding Java Classes to the Framework
In this section, you complete the initial framework by adding a Java class to the data
layer project:
2 In the Navigator, under data_layer_project_1 [ucm_admin_InitialProject], open Java
Code Model.mdx.
3 From the Toolbox in the left pane, navigate to Java > Java Class. Drag Java Class
to the Main diagram of Java Code Model.mdx.
The Create Java Class dialog box appears.
4 In the Name box, type FirstClass and click OK.
5 At the prompt to check out, click OK.
one. Click OK.
7 Repeat Step 2 to Step 6 to add a class called FirstClass to Java Code Model.mdx
under midd_tier_project_1.
Generating Code for the Classes

If you choose to work with the XDE AutoSync preference cleared, then you must
generate code for classes manually. If you choose to work with the XDE AutoSync
preference selected, XDE automatically generates code for classes.
To check the status of the XDE AutoSync preference:
1 Click Window > Preferences.
The Preferences dialog box appears.
2 Expand Rational XDE and then click Code-Model Synchronization.
If the AutoSync preference is cleared, generate code manually for the new classes
you created.
3 Click OK to close the Preferences dialog box.
To generate code manually for the classes:
click Synchronize.

one. Click OK.
5 Repeat Step 2 to Step 4 to generate code for the class in (midd_tier_project_1) Java
Code Model.
Saving, Validating, and Checking In

To complete this part of the exercise, leave your environment in a stable state:
1 On the Modeling - Application menu, click File > Save All.
2 Validate the open models to ensure that they are consistent. For more information,
see Validating Models on page 156.
3 Ensure that all files are checked in:
❑
In the IDE, click the Model Explorer tab.
❑
In the Model Explorer, select all the files.
❑
Right-click and then click Team > Check In.
❑
In the Check In Element(s) dialog box, click OK.
Creating a Project Set File

In this section you create a project set file (.psf), which will allow users of other views
to open (in one operation) the three projects you created.
In Eclipse, the Eclipse Workspace stores information about how projects are associated
with the Eclipse instance. The Eclipse Workspace concept is generally equivalent to a
VS.NET Solution file, except the Eclipse Workspace is stored separately from the
projects.
The Eclipse Workspace can provide more flexibility but it can make working with
ClearCase more difficult because you have to maintain awareness of the separate
workspace and manage it manually. However, when you start XDE through the
recommended path, XDE automatically creates an Eclipse Workspace directory as a
sibling directory to the view root, so you do not need to manage it manually. In this
exercise, once you create a project set file, XDE creates a sibling directory for your
development view called ucm_admin_InitialProject_ws.
To create a project set file:
1 In the Modeling - Application Developer window, click the Navigator tab.
2 Collapse all three projects.
3 Select all three projects.
4 Click File > Export.
5 On the Export page, select Team Project Set and click Next.
6 On the Team Project Set page, ensure that all three projects are selected.
7 Click Browse.
The Save As dialog box appears.
8 Navigate to the gui_project_1 project directory in your current view. For example:
C:\temp\views\ucm_admin_InitialProject\atlas_gui\gui_project_1
9 In the File name box, type atlas_projects.

10 Click Save to return to the Team Project Set page.
The File name box should show that atlas_projects.psf is located in your view,
C:\temp\views\ucm_admin_InitialProject\atlas_gui\gui_project_1\atlas_projects.psf
Note: Always save your Project Set File in a project directory that is within the
view that is associated with your workspace.
11 Click Finish.
Adding the Project Set File to Source Control

To add the project set file to source control:
2 Right-click gui_project_1 [ucm_admin_InitialProject] and then click Refresh .
one. Click OK.
Delivering to the Integration Stream

The ClearCase deliver operation makes work done in one stream available to another
stream.
Work is delivered in the form of activities or baselines. Differences between versions
already part of the target stream of the deliver operation and versions being delivered
are resolved through merging.
Versions associated with an activity or baseline must be checked in to be delivered.
Only activities that have been modified since the last deliver operation from the
development stream are considered for delivery.

Deliver your files to the integration stream so that other users can work with the
application. Until you deliver to the integration stream, users who join the UCM
project will see empty work areas.
Note: In the Navigator, a blue border around the fileicon indicates that the file is
under source control. All project files should currently be under source control.
To deliver the projects to the integration stream:
1 From the ClearCase toolbar in the IDE, click Deliver Stream.
The Deliver from Stream dialog box appears.
2 Select ucm_admin_InitialProject and click OK .
The Deliver from Stream Preview dialog box appears.
3 To view which file versions are associated with a UCM activity:
a Select an activity and click Properties.
The Properties dialog box appears for that activity.
b Click the Change Set tab to view all files associated with that activity.
c Click OK to return to the Deliver from Stream Preview dialog box.
4 Ensure that all activities are selected and click OK to begin the delivery.
Once all files are successfully merged, the Deliver from Stream - Merges Complete
dialog box appears.
5 Clear the Open a ClearCase Explorer window to the root of the view check box and
click OK
Note: Do not complete the delivery now. Leave the Delivering to View dialog box
open for now. You will complete the delivery later after you have tested files in the
integration view.
You have merged and checked out all of the files onto the integration stream and left
these files checked out in the integration view.
Viewing the ClearCase Branch Structure

Each time you revise and check in an element, ClearCase creates a new version of the
element in the VOB.
ClearCase can organize the different versions of an element in a VOB into a version
tree. Like any tree, a version tree has branches. Each branch represents an
independent line of development. Changes on one branch do not affect other
branches until you merge.
In UCM projects, the stream keeps track of which branch or set of branches you use in
a project; you usually do not work directly with branches.
You can view the underlying ClearCase branch structure associated with the streams
by looking at the version tree:
To view the ClearCase branch structure:
1 In the IDE Navigator, select a file.
2 From the ClearCase toolbar in the IDE, click Show Version Tree.
The ClearCase Version Tree Browser appears and displays the version tree for the
selected project.
3 Exit the ClearCase Version Tree Browser: click File > Exit.
4 Exit the IDE: Click File > Exit.
Loading the Project Set in a New View

All changes are delivered to the integration view and checked out in the integration
view. You will start XDE and choose to work in your integration view. Because you
are in a new view and a new Eclipse workspace, you must load the project set.
View.
2 XDE prompts you to select the ClearCase view to use. Select

ucm_admin_InitialProject_int (your integration view) and click OK .
Your IDE starts.

5 On the Team Project Set page, click Browse and navigate to the integration view
location of atlas_projects.psf. The file is in your integration view, under the
gui_project_1 project directory. For example:
C:\temp\views\ucm_admin_InitialProject_int\atlas_gui\gui_project_1
7 Click Finish.
Testing the Delivery in the Integration View

At this stage, you typically verify that the application works as expected by testing the
delivery and confirming that all merges are done correctly and all changes are
delivered. However, because no one else is currently working on the project, you do
not need to perform this verification now.

Completing the Delivery to the Integration Stream
You should still have an incomplete delivery to your integration stream.
To complete the delivery to the integration stream:
1 Select the Delivering to View dialog box (still open from the incomplete deliver)
and click Complete.
2 Click Close.
The files are all checked into ClearCase in the integration stream. In the IDE, files
should still appear checked out because ClearCase actions that are initiated for
outside the IDE in which XDE is running are not automatically propagated to the
IDE. You need to update the IDE to reflect these changes. For more information,
see Tips for Working with ClearCase on page 171.
3 Update the IDE to reflect the latest changes in ClearCase: in the Navigator, select
all files; right-click and click Team > Refresh Status.
In the IDE, all files appear checked in.
4 Exit the IDE. Click File > Exit.
Creating and Recommending a Baseline

With UCM, at certain points in the development cycle, as dictated by your
development process, your integrator (or project leader) creates a new baseline based
on the activities that you and your team members have delivered. After testing, your
integrator communicates to your team that a new recommended baseline is available.
In the integrations stream, create a baseline and then recommend the baseline so that
users can have access to the latest UCM components.
Creating a Baseline
In the integration stream, create a baseline for all three UCM components.
Note: You can also separately create a baseline for each UCM component.
To create a baseline for all three UCM components:

1 In the ClearCase Project Explorer, right-click IntegrationStream and then click Make
Baseline.
The Make Baseline dialog box appears.

2 Click OK to create a baseline for each of the three UCM components.
Recommend the baseline that users will access when they rebase their development
streams.
To recommend a baseline:
Recommend Baselines.

2 Click Seed List.
When you seed the list for the new baselines at the INITIAL promotion level, you
will see the new baselines that you just created.
3 Click OK.
Once you have recommended a new baseline, you typically inform your team to
join the UCM project and begin work.
4 Exit ClearCase Project Explorer: click File > Exit.
5 Log out as ucm_admin.

Before you start this section, ensure that you have performed all initial setup for each
new user, as described in Before You Begin: Installing and Configuring Software on
page 145.

This exercise refers to two users: dev1 and dev2. Set up each user’s work areas by
joining the UCM project.
Joining the UCM Project

To join the UCM project:
1 Log in as dev1.
2 Open the ClearCase Project Explorer, right-click InitialProject and then click Join
Project.

3 Select InitialProject and click Next.

view location (for example: C:\temp\views\dev1_InitialProject) and click Next.
location (for example: C:\temp\views\dev1_InitialProject_int) and click Next.
The Choose Components page appears.
7 Clear the Start component browser after creating view check box.
8 Ensure that all three atlas project component check boxes are selected for loading.
Clear the InitialComponent check box.
9 Click Finish. When the Confirm dialog box appears, click OK.
10 Repeat Step 1 to Step 9 for dev2.

In this section, the dev1 user starts a modeling task as follows:
1 Log in as dev1.
View.
3 XDE prompts you to select the ClearCase view to use. Select dev1_InitialProject
and click OK.
Your IDE starts.
atlas_projects.psf file. The file is located in dev1_InitialProject (your development
view), under the gui_project_1 project directory. For example:
C:\temp\views\dev1_InitialProject\atlas_gui\gui_project_1\atlas_projects.psf
8 Click Finish.
Create a subsystem use case package on each of the main diagrams:
1 In the IDE, click in the Navigator.
2 Under midd_tier_project_1 [dev1_InitialProject], open services model.mdx.
4 At the prompt to check out files, click OK .
5 When prompted, create an activity called check out. Click OK.
❑ Under gui_project_1 [dev1_InitialProject], open gui_model.mdx and create a
UML Use Case Package called gui use cases.
❑ Under data_layer_project_1 [dev1_InitialProject], open data_model.mdx and
create a UML Use Case Package called data use cases.

So far, each model element is stored in a separate model. In this section, you create
references from one model to another. These references are called cross-model
references. Normally, the system handles cross-model references and you do not have
to worry about them. Later in this scenario, you will resolve inconsistencies in a
cross-model reference.
To create a cross-model reference:
2 Under gui_project_1 [dev1_InitialProject], open System Model.mdx.
4 When the Check Out Element(s) dialog box appears, click OK.
one. Click OK.
6 In the Model Explorer, rename the new diagram Atlas System Use Cases.
❑ gui use cases

❑
data use cases
9 Check in all files:
a In the Model Explorer, select all files.
b Right-click and then click Team > Check In.
c When the Check In Element(s) dialog box appears, click OK.
You have created cross-model references.

While logged in as dev1, deliver your files to the integration stream.
To deliver to the integration stream:
1 From the IDE, complete the delivery of your files to the integration stream. For
more information, see Delivering to the Integration Stream on page 162.
Because your delivery only reflects new model changes (no code changes), you do
not need to test the projects in the integration view before completing your
delivery.

As ucm_admin, create and recommend a baseline so that the changes delivered by dev1
can be shared with the team.
To create and recommend a baseline:
1 Log in as ucm_admin.
2 Create a new baseline. For more information, see Creating a Baseline on page 165.
3 Recommend the new baseline. For more information, see Recommending a Baseline
on page 166.
Rebasing as dev2
As dev2, rebase your development stream to the recommended baseline on the
integration stream to update your work area with the changes that dev1 delivered
(new model elements and cross-model references).
To rebase to the recommended baseline:
1 Log in as dev2.
View.
3 XDE prompts you to select the ClearCase view to use. Select dev2_InitialProject to
begin your work.
Your IDE starts.
4 From the ClearCase toolbar in the IDE, click Rebase Stream.
The Rebase Stream dialog box appears.
5 Ensure that dev2_InitialProject is selected and click OK.
6 To view the baselines for this rebase, click Advanced .
The Change Rebase Configuration dialog box appears with a list of baselines you
will rebase to.
7 Click OK to return to the Rebase Stream Preview dialog box.
8 Click OK to begin the rebase.
The Merges Complete dialog box appears.
9 Click OK.
The Rebasing in View dialog box appears.
10 Click Complete.
11 Click Close.
Note: We recommend that you always rebase your view with models closed. If you
rebase your view when models are open, you are not prompted to reload and you can
erase all changes from the previous version.
Importing the Project Set File

As dev2, load the project set file into your workspace:
1 Click File > Import.
Warning: You must open the Project Set file that is associated with your Eclipse
Workspace.

atlas_projects.psf file. The file is located in dev2_InitialProject (your development
view), under the gui_project_1 project directory. For example:
C:\temp\views\dev2_InitialProject\atlas_gui\gui_project_1\atlas_projects.psf
5 Click Finish.
Tips for Working with ClearCase

We caution you not to work in ClearCase outside the IDE when the IDE is running.
Independent ClearCase activities that can cause problems include checkouts or view
updates; these actions can cause items (versions, elements, projects) to be loaded into
your view. Eclipse does not include a mechanism to notify the shell of changes in the
file or directory structure. If you do create this situation, resolve it as follows:
1 In the Navigator, right-click a project and then click Refresh From Local.
2 In the Navigator, right-click a project and then click Team > Refresh Status.
These actions synchronize the file system state on disk with the in-memory state of
the Navigator and the source control status.
Note: Certain ClearCase operations that trigger merges can be initiated from outside
the IDE for performance reasons. For more information, see Starting a Session In an

user tries to check in and deliver files, they must do a merge to resolve the differences.
The following table describes the work you will do in this section:
1 Checks out file

Makes changes
Quits XDE
2 Checks out same file

Quits XDE
3 Checks in file
Delivers files
4 Checks in file
Delivers files, but needs to merge first.
element and deliver before a rebase. This generates a merge conflict when the second
user starts to deliver.

1 As dev2, in the IDE, click the Navigator tab. Under midd_tier_project_1, open
services model.mdx.
middle tier.
3 When prompted to check out files, click OK.

4 When prompted for an activity, create a new activity.
6 Quit XDE: Click File > Exit. When you are prompted to check in your work, click
Cancel; you want to keep the files checked out.
❑
Rename the services use cases package to dev1 middle tier.
8 Log in as dev2 again and check in and deliver your work as follows:
a Start XDE and, when prompted, select your view.
b In the Navigator, open services model.mdx.
c In the Model Explorer, right-click (midd_tier_project_1) services model and then
d Click OK to complete the check in.
e From the IDE, complete the delivery of your files to the integration stream.


has checked in changes. The dev1 user has not yet checked in changes. When dev1
delivers changes, ClearCase displays a prompt to merge so that dev1 can resolve the
changes. Proceed as follows:
1 Log in as dev1.
2 Start your IDE. When prompted, choose your development view
(dev1_InitialProject).
3 In the Navigator, open services model.mdx.
5 Complete the check in.
6 From the IDE, deliver your files to the integration stream.
A message appears saying that the element cannot be merged automatically.
7 Select the Start the Diff Merge tool for this element option and click OK to launch an
XDE compare/merge session.
Merging Changes
the conflict.
11 Select the Deliver from Stream - Merges Complete dialog box and click OK.
The Delivering to View dialog box appears.

12 Click Complete to make the changes from the merge permanent.

1 While logged in as dev1, in the IDE Navigator, right-click data_layer_project_1 and
then click New > Folder.
2 Name the new folder Models and click Finish.
3 When prompted to add to source control, select the Keep checked out check box
and click OK.
4 Create an activity called move model.
5 In the Navigator, drag the data model.mdx file into the new Models folder.
6 Check in all files. The data model.mdx file and its directory are now checked into
ClearCase.
7 Deliver all files to the IntegrationStream.

2 In the IDE Navigator, under gui_project_1, open System Model.mdx.
3 Click Resolve.

Models folder).
6 Click Apply.
7 If you are prompted to check out, click OK.
and Base ClearCase With
Microsoft VS.NET
12
Rational XDE supports team development. You start a new project from Microsoft
Visual Studio .NET project templates and practice model-driven, team-oriented
development.
and developer. The configuration manager’s user ID is vob_admin. There are two

Prerequisites
workstations:
■
Microsoft VS.NET 7.1 with Microsoft .NET Framework
■
Rational XDE Developer .NET Edition 2003
■ ClearCase LT Client
■
Microsoft Internet Information Services (IIS) 5.1
This exercise follows a standardized Web project model with http://localhost IIS
references and file share access mode to Web projects.

follows:
■
177
■
The ClearCase Getting Started Wizard has been run on the ClearCase LT Server to
establish VOB storage locations.
Note: When you run the Getting Started Wizard, do not perform the Import Source
Files optional task. This task imports source files into a VOB named sources. In this
exercise, you create your own VOBs to store all source files.
■


a special account, vob_admin. You set this account to use a special group, development,
primary group.
■
■
in this group.

the domain.
1 Log in as the vob_admin.
2 Add vob_admin to the development group on your workstation.

2 Click New.

In this section, you set up your ClearCase environment by creating VOBs and a view.
Chapter 12 - Scenario: Rational XDE and Base ClearCase With Microsoft VS.NET 179
Planning VOBs
reduce the complexity of managing them. VOBs are the ClearCase mechanism for
group into a VOB typically implement a reusable piece of your system architecture.
By organizing related files and directories into components, you can view your
system as a small number of identifiable components, rather than as one large set of
directories and files.
Working with VS.NET Projects

A VS.NET project forms a system or subsystem of the solution. These projects usually
have high internal coupling, are developed by a common group, and are released
together.
VS.NET projects are also typically grouped together to form a version of software. For
example, you can have a set of VS.NET projects that collectively implement the data
services subsystem of an application. A team can publish data services as version 1,
version 2, and version 3. Clients of data services can take version 1, then integrate and
take on version 2 as a unit.
In this exercise, you create a VS.NET solution that contains three projects. Each project
represents a separate layer of a three-layer Web project architecture.
In this exercise, the VS.NET projects and the layers they represent are:
■
An ASP.NET project, which represents a GUI project.
■
A VB.NET project, which represents a middle-tier layer.
■
A C# project, which represents a data layer.
Note: A more complex solution typically has several projects at each layer of
architecture.
Creating VOBs
repository called a VOB.

3 Click Next.

5 Click Finish.
6 Click OK.
❑
atlas_services
Creating a View
While logged in as vob_admin, create the administrator’s view so that you can create
and populate the initial solution framework projects and file artifacts:
1 Start the View Creation Wizard: click Start > Programs > Rational Software >
2 On the Choose a Project page, click No to the question about working on a project
in the ClearCase project tree.
3 Click Next.
4 On the Choose Location for a Snapshot View page, accept the default path or type
another path that is on your computer.
The last part of the path is the name of the view. To follow this scenario, make sure
it is vob_admin_view, so that the full path you include here is, for example:

5 On the Confirm page, click OK to create the view.
view. (Snapshot views work by copying files onto your disk. In the next step, you
select the sets of files to copy.)
6 On the Choose Elements to Load dialog box, select each of the VOBs you created
and click Add.
7 Click OK.
Creating a VS.NET Solution With XDE Models
A VS.NET solution stores project and user-specific information. You typically create a
VS.NET solution and then add projects to the solution to maintain a logical hierarchy
with the projects in your Web application.
Creating a VS.NET Solution

Create your VS.NET solution, which will include XDE models.
Creating a Blank Solution within a VOB

To create a blank solution called atlas_project and add it to the atlas_gui VOB:
1 Log on as vob_admin and open VS.NET.
2 Click File > New > Blank Solution.
The New Project dialog box appears.
3 In the Name box, rename the solution to atlas_gui.
4 Click Browse and select the location of your development view. For example:
5 Click OK to create the new blank solution.

6 In the Solution Explorer, rename the new solution (atlas_gui) to atlas_project.
Creating a Visual C# Project

To create the Visual C# project:
1 In the Solution Explorer, right-click atlas_project and then click Add > New Project.
2 In the Project Types pane of the Add New Project dialog box, select Visual C#
Projects.
3 In the Templates pane, select Class Library.

4 In the Name box, rename the project to data_layer_project_1.
5 Click Browse and select the location of atlas_data_layer in your view. For example:
C:\temp\views\vob_admin_view\atlas_data_layer
6 Click OK to create the new project.

Creating a VB.NET Project
To create the VB.NET project:
2 In the Project Types pane of the Add New Project dialog box, select Visual Basic
Projects.

4 In the Name box, rename the project to midd_tier_project_1.
5 Click Browse and select the location of atlas_services in your view. For example:
C:\temp\views\vob_admin_view\atlas_services
Creating an IIS Alias

Before you create the ASP.NET project that will reside with the solution in the
atlas_gui VOB, you must set up URL access to the Web project.
Because ClearCase manages all of the projects in subdirectories (VOBs), you must
create an IIS alias called vob_admin_view that points to your development view and
specify the location of the Web projects through that alias.
To create an IIS alias for your development view on Windows XP:
1 On the Control Panel, go to Administrative Tools > Internet Information Services.
2 Under Web Sites, right-click Default Web Site and then click New > Virtual Directory.
3 The Virtual Directory Creation Wizard appears. Click Next.
4 In the Alias box, type vob_admin_view and click Next.
5 In the Directory box, browse to the location of your development view. For
example:
6 Click Next.
7 Accept all defaults and complete the Wizard.
Note: The alias and directory name must match; otherwise, you will eventually
encounter a problem in VS.NET.
If you view the properties of this virtual directory, you can see that it is mapped to
your development view location.
To view the properties of the virtual directory mapped to your development view:
■
In Internet Information Services, under Default Web Site, right-click vob_admin_view
and then click Properties.
The path in the Local Path box maps to the location of your development view.
Creating an ASP.NET Project

To create the ASP.NET project.
Projects.
3 In the Templates pane, select ASP.NET Web Application.

In the Location box, map the IIS to the ClearCase view location where you want
the project to live:
http://localhost/vob_admin_view/atlas_gui/gui_project_1

The URL now maps to the location in your ClearCase view where you want the
project to reside, along with the other projects.
You have set up the project directory structure and initial code.
Adding Code Models to the Projects

To add code models to the VS.NET projects:
■ In the Solution Explorer, right-click atlas_project and then click Synchronize.
Validating Models
You should validate models early and often. Validate the three new code models.
■
In the Model Explorer, right-click each model root and then click Validate.
Because the code models are new, there are no validation errors.
Creating XDE Models

Add XDE content models to the solution.

Adding a Getting Started Model to the Solution
aspects of your system using XDE round-trip engineering. There are also parts of the
system not directly related to the code model, for which you should create a content
model (for example, the system’s use cases or system architecture). In this section, you
create an XDE content model using the Getting Started model template and add this
model to the gui_project_1:
To add a Getting Started model to a project:
1 In the Solution Explorer, right-click gui_project_1 and then click Add > Add New
Item.
2 In the Categories pane of the Add New Item dialog box, select Rational XDE.
3 In the Templates pane, select Getting Started.
4 In the Name box, change the name to System Model and click Open.
The model appears in the Solution Explorer and the Model Explorer.
Adding a Blank Model to Each Project

Add a subsystem model to each VS.NET project by using the XDE Blank Model
template.
To add a blank model to a project:
Item.
3 In the Templates pane, select Blank Model.
4 In the Name box, rename the model to gui model and click Open.
5 Repeat steps 1 to 4 to add a blank model named services model to
midd_tier_project_1.
6 Repeat steps 1 to 4 to add a blank model named data model to data_layer_project_1.

managed as a single logical unit for configuration management (CM) purposes at key
delivery points into CM.
class1 and class2.
General Behavior
in other views can then update their models and see a consistent and complete set of
model elements.
Solution Explorer Limitations

implementation of COV is more comprehensive from that window. In the Solution
Explorer, the COV is only enabled if the selected unit is the root model file.

more efficient.
To define a model element as a subunit:

1 In the Model Explorer, under (gui_project_1) System Model, right-click Deployment
and then click Make a Separate Unit.
2 Repeat step 1 for Design, Implementation View, and Use Cases nodes.
3 Click File > Save All to save changes.
You can view the subunits in both the Solution Explorer (as .pkx files) and the
Model Explorer (as icons).
Adding the Solution to Source Control

Add the new solution to source control:
■
In the IDE, click File > Source Control > Add Solution to Source Control.
The solution is now in ClearCase checked into your view.
Testing in the Development View

The solution is now in ClearCase. Build, debug, run, and test the application before
making it available to users.
1 In the Solution Explorer, right-click atlas_project, and then click Build Solution.
2 If you have any build errors, resolve them and rebuild the solution. At this stage,
you should not have any build errors.
3 Set the ASP.NET project as the startup project: select gui_project_1, right-click and
click Set as StartUp Project.
4 Set the WebForm1.aspx file as the start page: select WebForm1.aspx, right-click and
click Set As Start Page.
5 In the Solution Explorer, right-click atlas_project, and then click Debug > Start.
Your blank sample Web page appears.
You have built, debugged, and tested your solution.
Creating Sample Content

You currently have a blank Web page. Create sample content for the Startup Web Page,
adding a label field and a few buttons.
To add sample content to the Startup Web Page:
1 In the Solution Explorer, right-click WebForm1.aspx and then click Check Out.
The Check Out dialog box appears.
2 Add content to the blank Web page. For example, add a few buttons and some
text.
Again, build, debug, and test your application.
1 In VS.NET, click File > Save All to save changes.
3 If you have any build errors, resolve them and rebuild the solution.
4 Right-click atlas_project, and then click Debug > Start.
You should see your new controls on the page.
Checking In all Files

Checking in files or directories adds new versions to the VOB. Check in all the files
that are currently checked out.
To check in all files:
1 In the Solution Explorer, right-click atlas_project and then click Show Pending
Checkins.
The Pending Checkins Window appears.

2 Click Check In.
4 Log out as vob_admin.

At this point in the scenario, the administrator has finished setting up the
environment. In this section, we switch our attention to the development process.
There are two users on your team, dev1 and dev2.

In this section, you set up the individual work areas for dev1 and dev2:
1 Log in as dev1.
2 Set a user environment variable CLEARCASE_PRIMARY_GROUP to your domain
development.

3 Create a dev1_view snapshot view:
a Start the View Creation Wizard, click Start > Programs > Rational Software >
b On the Choose a Project page, click No to the question about working on a

project in the ClearCase project tree.
c On the Choose Location for a Snapshot View page, accept the default path or
type another path that is on your computer.
The last part of the path is the name of the view. To follow this scenario, make
sure it is dev1_view, so that the full path you include here is, for example:
C:\temp\views\dev1_view

d On the Confirm page, click OK to create the view.
view. (Snapshot views work by copying files onto your disk. In the next step,
you select the sets of files to copy).
e On the Choose Elements to Load dialog box, select the VOBs that are part of
this scenario and click Add:
➑
atlas_services
➑
atlas_gui
➑
atlas_data_layer
f The VOBs appear in the Selected Elements list; click OK.

4 Log off as dev1 and repeat Step 1 to Step 3 to set up the environment for dev2.
Creating IIS Virtual Directories

For each user (dev1 and dev2), perform the following:
■ Create an IIS virtual directory to map the view root directory for each user’s view.
For more information, see Creating an IIS Alias on page 183.

As dev1 in VS.NET, open your solution under source control for the first time.
Note: In VS.NET, the first time you open a solution under source control in a
newly-created view, you must go through the Open from Source Control menu item.
To open the solution again, you must go through the Open Solution menu item.
To open a solution under source control for the first time in a new view:
1 As dev1 in VS.NET, click ClearCase > Front Desk.
2 In the Front Desk Window, click Views.
3 From the Display menu, select <Add Views...> and browse to the location of your
snapshot view. For example:
C:\temp\views\dev2_view\atlas_gui
4 Click OK.
5 Click dev1_view (your development view).
6 Click the Open button, then click Open from Source Control.
7 When the Browse for Folder dialog box appears, select the atlas_gui folder in your
development view. For example:
8 Click OK.
The Set Project Location - atlas project dialog box appears.
9 Edit the Enter Working Copy Location box to specify the correct IIS virtual directory
for your development view. For example:
http://localhost/dev1_view/atlas_gui/gui_project_1
10 Click OK.
User dev1 now has a solution framework open and ready to begin work.

Create a subsystem use case package on the main diagram of each subsystem model:
1 In the Solution Explorer, under midd_tier_project_1, double-click services
model.mdx.
The Check Out For Edit dialog box appears.
3 Click Check Out.
❑ Under gui_project_1, open gui model.mdx and create a UML Use Case Package
called gui use cases.

❑
Under data_layer_project_1, open data model.mdx and create a UML Use Case
Package called data use cases.

diagram.
You will create cross-model references by:
■
Creating a new diagram on the System Model called Atlas System Use Cases.
■
Dragging the use-case packages from the three subsystem models onto the new
Atlas System Use Cases diagram.
To create cross-model references:
1 In the VS.NET Solution Explorer, under gui_project_1, open System Model.mdx.
3 Name the new diagram Atlas System Use Cases.
Note: Diagrams provide a means of visualizing and manipulating the model
elements in a model. Different diagrams represent different views of the system
that you are developing.
❑
gui use cases
❑
services use cases
❑ data use cases
5 Save all your work. Click File > Save All.
6 Check in all files: in the Pending Checkins window, click Check In.
Updating Views
Earlier in this scenario, you set up the work environment for dev2 and created a view.
When you loaded the view, you loaded the files corresponding to the \main\LATEST
version at the time the view was created. This version consisted of the basic
framework before dev1 started to work. Before you start to change the models, you
need to update your view. Work as follows:
1 Log in as dev2 and start VS.NET.
2 Click ClearCase > Front Desk.
4 From the Display menu, select <Add Views...> and browse to the location of your
snapshot view. For example:
5 Click OK.
6 In the left pane, click dev2_view (your development view).
9 Click OK.
http://localhost/dev2_view/atlas_gui/gui_project_1
11 Click OK.
12 Update dev2_view: in the Front Desk Window, click Tools.
13 In the Tools pane, double-click Update Snapshot View.

14 Click OK.
15 The ClearCase Snapshot View Update dialog box appears and shows what has
changed since the last update. Exit the dialog box: click File > Exit.

user tries to check in, they must do a merge to resolve the differences. The following
table describes the work you will do in this section:
1 Checks out file

Makes changes
Quits XDE
2 Checks out same file (unreserved)

Quits XDE
3 Checks in file reserved
4 Checks in file
(Next section) tries to check in, but needs
to merge first.
element and check in their changes. This generates a merge conflict when the second
user starts to check in.

1 As dev2, in the IDE, click the Solution Explorer tab. Under midd_tier_project_1,
open services model.mdx.
middle tier.
3 When prompted to check out files, click Check Out.

5 Quit XDE: Click File > Exit. Leave services model.mdx checked out.
❑
Rename the services use cases package to dev1 middle tier.
❑
To open the solution as dev1, in the bottom pane of the Front Desk Window,
click atlas_project, then click the Open button.
❑
When you are ready to check out the file, ClearCase prompts you to check the
file out unreserved because only one checkout per branch can be reserved and
dev2 holds the reservation.
7 Log in as dev2 again and check in your work as follows:
a Start the IDE.
b Click ClearCase > Front Desk.
c In the bottom pane of the Front Desk Window, click atlas_project, then click the
Open button.
d In the Model Explorer, right-click (midd_tier_project_1) services model and then

click Check In.

has checked in changes (dev2 had a reserved checkout). The dev1 user has not yet
checked in changes. When dev1 checks in changes, ClearCase displays a prompt to
merge so that dev1 can resolve the changes. Proceed as follows:
1 Log in as dev1.
2 Start your IDE. Open the solution: Click File > Open Solution and browse to the
atlas_project.sln file in your development view (dev1_view ).

click Check In.
4 Click OK.
A message appears saying that there are later versions of the file on this branch,
and asking whether you want to merge now.
5 Select the Merge the file graphically check box and click Yes.

Merging Changes
the conflict.
9 Before XDE closes, it prompts you to check in files. Click Yes.


1 While logged in as dev1, in the IDE Solution Explorer, right-click
data_layer_project_1 and then click Add > New Folder.
2 When prompted to check out, click Check Out.

3 Rename the new folder Models.
4 In the Model Explorer, close data model if open: right-click data model and then
click Close.
5 In the Solution Explorer, drag the data model.mdx file into the new Models folder.
Ignore any message prompts.
7 Check in all files from the Pending Checkins Window. The data model.mdx file and
its directory are now checked into ClearCase.
2 In the IDE Solution Explorer, under gui_project_1, open System Model.mdx.
3 Click Resolve.
Models folder).
6 Click Apply.
7 If you are prompted to check out, click Check Out.

and UCM With Microsoft
VS.NET
13
Rational XDE supports team development. You start a new project from Microsoft
Visual Studio .NET project templates and practice model-driven, team-oriented
development.
and developer. The configuration manager’s user ID is ucm_admin. There are two

Prerequisites
workstations:
■
Microsoft VS.NET 7.1 with Microsoft .NET Framework
■
Rational XDE Developer .NET Edition 2003
■ ClearCase LT Client
■
Microsoft Internet Information Services (IIS) 5.1
This exercise follows a standardized Web project model with http://localhost IIS
references and file share access mode to Web projects.

follows:
■
197
■
The ClearCase Getting Started Wizard has not been run on the ClearCase LT
Server.
■


a special account, ucm_admin. You set this account to use a special group, development,
primary group.
■
■
in this group.

the domain.
1 Log in as the ucm_admin.
2 Add ucm_admin to the development group on your workstation.

2 Click New.

To set up the ClearCase environment in this exercise, the administrative user
(ucm_admin) follows these high-level steps. You typically perform this setup once.
Chapter 13 - Scenario: Rational XDE and UCM With Microsoft VS.NET 199
1 Set up your initial project by performing the following:
a Create a project VOB.
b Create a UCM project.
2 Plan how your UCM components map to your IDE project components.
3 Create UCM component VOBs.
4 Create ClearCase work areas by:
a Creating a development stream.
b Creating an integration stream.
c Creating a development view.
d Creating an integration view.
e Loading the new VOBs into your work area.
5 Register your UCM components as modifiable by:
a Adding foundation baselines to your UCM project.
b Changing UCM project policies for the UCM components.
6 Synchronize the integration stream.
7 Recommend a new baseline.
8 Rebase your development stream.
Creating the Initial Project VOB and UCM Project

repository called a versioned object base (VOB). Each UCM project must have a
project VOB (PVOB). A PVOB is a special kind of VOB that stores UCM objects, such
as projects, activities, and change sets. A PVOB must exist before you can create a
UCM project.
As the administrative user, create a PVOB called projects and a UCM project called
InitialProject by completing the ClearCase Getting Started Wizard.
To create a PVOB and UCM project:
1 Log on as ucm_admin on the ClearCase LT server.
2 Click Start > Programs > Rational Software > Rational ClearCase > Administration >
Getting Started Wizard.
The Rational ClearCase LT Getting Started Wizard page appears.

3 Click Next.

4 On the next page, accept the default directory for storing the ClearCase LT
database and click Next.
5 On the next page, accept the default Source VOB Name and Name of Initial
Component and click Next.
6 On the next page:

a In the Starting UCM Project Name box, ensure that InitialProject is entered.
b Select the Parallel stream project button and click Next.
7 On the next page, click Next to configure the server with the listed settings.
8 On the next page, click Close.
Note: The Import Source Files option is not appropriate for VS.NET projects because
VS.NET contains the logic that determines what file types should be placed under
source control. You do not use this initial repository sources, which you delete later in
the exercise.
Verifying VOB Ownership

To verify that VOB ownership is ucm_admin\development:
1 From the Start menu, click Run.
The Run dialog box appears.
2 Type cleardescribe vob:\projects
3 Click OK.
Planning UCM Components

reduce the complexity of managing them. Components are the UCM mechanism for
group into a component typically implement a reusable piece of your system
architecture. By organizing related files and directories into components, you can
view your system as a small number of identifiable components, rather than as one
large set of directories and files.
Within a component, you organize directory and file elements into a directory tree.
You can convert existing VOBs or directory trees within VOBs into components, or
you can create a component from scratch.
Note: The directory and file elements of a component reside physically in a VOB. The
component object resides in a PVOB.

Working with VS.NET Projects
A VS.NET project forms a system or subsystem of the solution. These projects usually
have high internal coupling, are developed by a common group, and are released
together.
VS.NET projects are also typically grouped together to form a version of software. For
example, you can have a set of VS.NET projects that collectively implement the data
services subsystem of an application. A team can publish data services as version 1,
version 2, and version 3. Clients of data services can take version 1, then integrate and
take on version 2 as a unit.
In this exercise, you create a VS.NET solution that contains three projects. Each project
represents a separate layer of a three-layer Web project architecture.
In this exercise, the VS.NET projects and the layers they represent are:
■ An ASP.NET project, which represents a GUI project.
■ A VB.NET project, which represents a middle-tier layer.
■ A C# project, which represents a data layer.
Note: A more complex solution typically has several projects at each layer of
architecture.
Creating VOBs
repository called a VOB. In ClearCase, a UCM component can be stored as the only
component in a VOB or as one of several components in a VOB. In this exercise we set
up the VOBs so that they can each contain one component only.

3 Click Next.
5 Click Finish.
6 Click OK.
❑
atlas_services
Creating ClearCase Work Areas

With UCM, a work area is the user work environment that is implemented with two
objects: a stream and a view. A stream defines the working configuration for the view
(or views) associated with it. A UCM project has one integration stream, which is part
of the shared work area, and multiple development streams, each of which is part of a
developer’s private work area.
You typically work with a development stream, then deliver your work to the
lets you work in isolation from the rest of the UCM project team.
A view selects the appropriate versions of files and directories, as defined by a set of
configuration rules, from all available versions in the VOB. ClearCase provides two
types of views: snapshot and dynamic. With snapshot views, files are copied from the
VOB to the local disk. Dynamic views reference files directly in the VOB.
Note: ClearCase LT uses snapshot views only.
Create work areas to populate the initial solution framework and file artifacts.
To create a work area:
1 While logged in as ucm_admin, in the ClearCase Project Explorer, right-click
InitialProject and then click Join Project.

2 Ensure that InitialProject is selected and click Next.
view location (for example: C:\temp\views\ucm_admin_InitialProject) and click
Next.
location (for example: C:\temp\views\ucm_admin_InitialProject_int) and click Next.
The Choose Components pages appears.
6 Select the Start component browser after creating view check box.

7 Clear the InitialComponent check box. Later, you create new components and add
them to the UCM project.
8 Click Finish.
The Confirm dialog box appears.
9 Click OK.
10 When the Choose Elements to Load dialog box appears:
a Select the Show All VOBs check box.

b From the Available Elements pane, add atlas_services, atlas_gui, and
atlas_data_layer to the Selected Elements pane, and click OK.
11 Click OK.
Your work area is rooted under ucm_admin_InitialProject (for example:

C:\temp\views\ucm_admin_InitialProject). In ClearCase, each VOB appears as a
subdirectory under the view root. UCM components can exist either as an entire VOB,
or as first-level subdirectories underneath a VOB. In this exercise, each of the three
components is located in a separate VOB.
Registering UCM Components as Modifiable

With UCM, you must register all components that you want to be modifiable in your
UCM project. Currently, only the component called sources, which you will delete
from your UCM project, is registered as modifiable.
Register your three new VOBs as modifiable by:
■
Adding foundation baselines to your UCM project.
■
Changing UCM project policies for the UCM components.
Adding Foundation Baselines to Your UCM Project

Add baselines to your UCM project that serve as the starting point for your team’s
developers. A baseline identifies one version of every element visible in a component.
To add foundation baselines to your UCM project:
Properties.
The Properties dialog box appears.

2 Select the Configuration tab.
3 Click Add.
4 Click the Change button and select All Streams.
7 Click OK.
8 Repeat steps 4 to 7 twice to add the atlas_gui and atlas_services foundation
baselines.
9 Click OK.
10 The Rebase Stream Preview dialog box appears. Click OK to start the integration
stream rebase.
11 Complete the rebase by accepting all defaults.
Changing UCM Project Policies for the UCM Components

The three UCM components in this exercise currently have read-only permissions. To
enable components to be modifiable, change the UCM project policies for each
component.
To change UCM project policies for the UCM components:
1 In the ClearCase Project Explorer, right-click InitialProject and then click Policies.
The Policies dialog box appears.
2 On the Components tab, select the atlas_data_layer, atlas_gui, and atlas_services
check boxes and clear the InitialComponent check box.
3 Click OK.
The ClearCase Project Explorer dialog box appears and explains that you need to
synchronize the integration stream so that it’s updated with the new list of
modifiable components.
Click OK.
Synchronizing the Integration Stream

Update your integration stream with the latest changes by performing a synchronize
operation.
Note: You only need to synchronize the integration stream when the components in a
UCM project change. You rarely perform this activity after a UCM project starts.

To synchronize with the integration stream:
Properties.
2 Select the Views tab.

3 Select the view (there should only be one view) and click the Properties button.
4 On the General tab, click the Synchronize with stream button.
5 Click OK.
The ClearCase Snapshot View Update window appears.
6 Click File > Exit.
You organize delivered activities into baselines. A baseline identifies one version of
every element visible in a component. Usually baselines go through a cycle of testing
and defect fixing until they reach a satisfactory level of stability. When a baseline
reaches this level, you designate it as a recommended baseline.
When developers join the UCM project, they populate their work areas with the
versions of directory and file elements represented by the UCM project’s
recommended baseline. Alternatively, developers can join the UCM project at a
feature-specific development stream level, in which case they populate their work
areas with the development stream’s recommended baseline. This practice ensures
that all members of the UCM project team start with the same set of files.
Recommend a new baseline to make the changes to your UCM project available to
developers.
To recommend baselines:
1 In the Project Explorer, right-click IntegrationStream and then click Recommend
Baselines.

2 Select InitialComponent and click the Remove button.
3 Click the Add button.
6 Click OK.
7 Repeat steps 3 to 6 twice to recommend the atlas_gui and atlas_services baselines.
8 Click OK.
Rebasing Your Development Stream

The ClearCase rebase operation provides a way for you to update work areas with
work that has been integrated, tested, and approved for general use. This work is
represented by baselines.
To work with the set of versions in the recommended baseline, you rebase your work
area. To minimize the amount of merging necessary while you deliver activities, you
rebase your work area with each new recommended baseline as it becomes available.
After you rebase, you typically build and then test the source files in your
development view to verify that your undelivered activities build successfully with
the versions in the baseline.
Update your work area with the latest UCM project changes by rebasing your
development stream to the recommended baseline on the integration stream.
To rebase the development stream:
1 In the ClearCase Project Explorer, right-click ucm_admin_InitialProject and then
click Rebase Stream.
2 Click OK to start the development stream rebase.
3 Click Complete when the Rebasing in View dialog box appears.
4 Click Close.
Creating a VS.NET Solution With XDE Models

A VS.NET solution stores project and user-specific information. You typically create a
VS.NET solution and then add projects to the solution to maintain a logical hierarchy
with the projects in your Web application.
Creating a VS.NET Solution

Create your VS.NET solution, which will include XDE models.

Creating a Blank Solution within a VOB
To create a blank solution called atlas_project and add it to the atlas_gui VOB:
1 Log on as ucm_admin and open VS.NET.
2 Click File > New > Blank Solution.
The New Project dialog box appears.
3 In the Name box, rename the solution to atlas_gui.
4 Click Browse and select the location of your development view. For example:
C:\temp\views\ucm_admin_InitialProject
5 Click OK to create the new blank solution.

6 In the Solution Explorer, rename the new solution (atlas_gui) to atlas_project.
Creating a Visual C# Project

To create the Visual C# project:
2 In the Project Types pane of the Add New Project dialog box, select Visual C#
Projects.

4 In the Name box, rename the project to data_layer_project_1.
5 Click Browse and select the location of atlas_data_layer in your view. For example:
C:\temp\views\ucm_admin_InitialProject\atlas_data_layer
Creating a VB.NET Project

To create the VB.NET project:
Projects.

4 In the Name box, rename the project to midd_tier_project_1.
5 Click Browse and select the location of atlas_services in your view. For example:
C:\temp\views\ucm_admin_InitialProject\atlas_services
Creating an IIS Alias
Before you create the ASP.NET project that will reside with the solution in the
atlas_gui VOB, you must set up URL access to the Web project.
Because ClearCase manages all of the projects in subdirectories (VOBs), you must
create an IIS alias called ucm_admin_InitialProject that points to your development
view and specify the location of the Web projects through that alias.
To create an IIS alias for your development view on Windows XP:
4 In the Alias box, type ucm_admin_InitialProject and click Next.
5 In the Directory box, browse to the location of your development view. For
example:
C:\temp\views\ucm_admin_InitialProject
6 Click Next.
Note: The alias and directory name must match; otherwise, you will eventually
encounter a problem in VS.NET.
If you view the properties of this virtual directory, you can see that it is mapped to
your development view location.
To view the properties of the virtual directory mapped to your development view:
■
In Internet Information Services, under Default Web Site, right-click
ucm_admin_InitialProject and then click Properties.
The path in the Local Path box maps to the location of your development view.
Creating an ASP.NET Project

To create the ASP.NET project.
Projects.
3 In the Templates pane, select ASP.NET Web Application.

In the Location box, map the IIS to the ClearCase view location where you want
the project to live:

http://localhost/ucm_admin_InitialProject/atlas_gui/gui_project_1

The URL now maps to the location in your ClearCase view where you want the
project to reside, along with the other projects.
You have set up the project directory structure and initial code.
Adding Code Models to the Projects

To add code models to the VS.NET projects:
■ In the Solution Explorer, right-click atlas_project and then click Synchronize.
Validating Models
You should validate models early and often. Validate the three new code models.
■ In the Model Explorer, right-click each model root and then click Validate.
Because the code models are new, there are no validation errors.
Creating XDE Models

Add XDE content models to the solution.
Adding a Getting Started Model to the Solution

aspects of your system using XDE round-trip engineering. There are also parts of the
system not directly related to the code model, for which you should create a content
model (for example, the system’s use cases or system architecture). In this section, you
create an XDE content model using the Getting Started model template and add this
model to the gui_project_1:
To add a Getting Started model to a project:
Item.
3 In the Templates pane, select Getting Started.
4 In the Name box, change the name to System Model and click Open.
Adding a Blank Model to Each Project
Add a subsystem model to each VS.NET project by using the XDE Blank Model
template.
To add a blank model to a project:
Item.
3 In the Templates pane, select Blank Model.
4 In the Name box, rename the model to gui model and click Open.
5 Repeat steps 1 to 4 to add a blank model named services model to
midd_tier_project_1.
6 Repeat steps 1 to 4 to add a blank model named data model to data_layer_project_1.


managed as a single logical unit for configuration management (CM) purposes at key
delivery points into CM.

class1 and class2.
General Behavior
in other views can then update their models and see a consistent and complete set of
model elements.
Solution Explorer Limitations

implementation of COV is more comprehensive from that window. In the Solution
Explorer, the COV is only enabled if the selected unit is the root model file.

more efficient.
To define a model element as a subunit:
1 In the Model Explorer, under (gui_project_1) System Model, right-click Deployment
and then click Make a Separate Unit.
2 Repeat step 1 for Design, Implementation View, and Use Cases nodes.
3 Click File > Save All to save changes.
You can view the subunits in both the Solution Explorer (as .pkx files) and the
Model Explorer (as icons).
You have completed the initial framework design for the solution and are ready to
add the solution to source control, which will allow other users to start working with
the solution.
Setting Up the Solution in the ClearCase Environment
Set up the solution in the ClearCase environment.
Adding the Solution to Source Control

Add the VS.NET solution to source control.
To add the solution to source control:
1 With the solution open, click File > Source Control > Add Solution to Source Control.
2 Click Continue in any Source Control dialog boxes that appear.
The ClearCase - Select Activity dialog box appears.
3 Click New to create a new activity.
The ClearCase - New Activity dialog box appears.
4 In the New Activity box, type import initial atlas project framework.
5 Click OK.
6 Click OK in any ClearCase - Select Activity dialog boxes that appear.

The solution is now in ClearCase under the development stream. Build, debug, run,
and test the application before making it available to users.
2 If you have any build errors, resolve them and rebuild the solution. At this stage,
you should not have any build errors.
3 Set the ASP.NET project as the startup project: select gui_project_1, right-click and
click Set as StartUp Project.
4 Set the WebForm1.aspx file as the start page: select WebForm1.aspx, right-click and
click Set As Start Page.
5 In the Solution Explorer, right-click atlas_project, and then click Debug > Start.
Your blank sample Web page appears.
Creating Sample Content

You currently have a blank Web page. Create sample content for the Startup Web Page,
adding a label field and a few buttons.

Previously, you created and associated an import initial atlas project framework UCM
activity. Now, switch to a developer role and create a second activity called add initial
controls to startup Web page.
To add sample content to the Startup Web Page:
1 In the Solution Explorer, right-click WebForm1.aspx and then click Check Out.
The Check Out dialog box appears.
2 Click New.
3 In the New Activity box, type add initial controls to startup web page and click OK.
4 Click Apply to All.
5 Add content to the blank Web page. For example, add a few buttons and some
text.

Again, build, debug, and test your application.
1 In VS.NET, click File > Save All to save changes.
3 If you have any build errors, resolve them and rebuild the solution.
4 Right-click atlas_project, and then click Debug > Start.
You should see your new controls on the page.
Checking In all Files

Checking in files or directories adds new versions to the VOB. Check in all the files
that are currently checked out.
To check in all files:
1 In the Solution Explorer, right-click atlas_project and then click Show Pending
Checkins.
The Pending Checkins Window appears.

2 Click Check In.
The ClearCase deliver operation makes work done in one stream available to another
stream.
Work is delivered in the form of activities or baselines. Differences between versions
already part of the target stream of the deliver operation and versions being delivered
are resolved through merging.
Versions associated with an activity or baseline must be checked in to be delivered.
Only activities that have been modified since the last deliver operation from the
development stream are considered for delivery.
Deliver your files to the integration stream so that other users can work with the
application. Until you deliver to the integration stream, users who join the UCM
project will see empty work areas.
Note: In the Solution Explorer, a lock icon indicates that the file is under source
control. All project files should currently be under source control.
To deliver the solution to the integration stream:
2 In the Front Desk Window, click the Deliver button.
The Deliver from Stream Preview dialog box appears.
3 To view which file versions are associated with a UCM activity:
a Select an activity and click Properties.
The Properties dialog box appears for that activity.
b Click the Change Set tab to view all files associated with that activity.
c Click OK to return to the Deliver from Stream Preview dialog box.
4 Ensure that all activities are selected and click OK to begin the delivery.
Once all files are successfully merged, the Deliver from Stream - Merges Complete
dialog box appears.
5 Click OK.
A ClearCase dialog box appears.
6 Click OK.
Note: Do not complete the delivery now. Leave the Delivering to View dialog box
open for now. You will complete the delivery later after you have tested files in the
integration view.
You have merged and checked out all of the files onto the integration stream and left
these files checked out in the integration view.

Viewing the ClearCase Branch Structure
Each time you revise and check in an element, ClearCase creates a new version of the
element in the VOB.
ClearCase can organize the different versions of an element in a VOB into a version
tree. Like any tree, a version tree has branches. Each branch represents an
independent line of development. Changes on one branch do not affect other
branches until you merge.
In UCM projects, the stream keeps track of which branch or set of branches you use in
a project; you usually do not work directly with branches.
You can view the underlying ClearCase branch structure associated with the streams
by looking at the version tree:
To view the ClearCase branch structure:
1 In the Front Desk Window, click Tools.
2 In the right pane, double-click Version Tree Browser.
3 In the Open dialog box, browse to the location of atlas_projects (for example:
C:\temp\views\ucm_admin_InitialProject\atlas_gui\atlas_projects) and click Open.
The ClearCase Version Tree Browser appears and displays the version tree for the
selected project.
4 Exit the ClearCase Version Tree Browser: click File > Exit.
Creating an IIS Alias for the Integration View

Because the solution contains an ASP.NET project, you must also create an IIS alias
for the integration view.
To create an IIS alias for your integration view on Windows XP:
4 In the Alias box, type ucm_admin_InitialProject_int and click Next.
5 In the Directory box, browse to the location of your integration view. For example:
C:\temp\views\ucm_admin_InitialProject_int
6 Click Next.
Testing in the Integration View
In the integration stream, all files have been merged successfully and are currently
checked out. In your integration view, all files are also currently checked out.
Before you open your solution in your integration view, you should close your
solution that is currently open in your development view.
To close the solution in your development view:
■
In VS.NET, click File > Close Solution .
In the integration view, you will open your solution, then rebuild, debug, and test it to
ensure that all changes from the delivery have been integrated properly.
Opening the Solution in the Integration View

Your integration view is attached to the UCM project’s integration stream. You use
the integration view to build and test the latest work delivered to the integration
stream.
Note: ClearCase LT views are snapshot views. Snapshot views copy files and
directories from VOBs to a directory on your computer.
In VS.NET, open the solution in your integration view.
2 Under InitialProject, select ucm_admin_InitialProject_int (your integration view).
The Browse for Folder dialog box appears.
4 Browse to the solution location in your integration view. For example:
C:\temp\views\ucm_admin_InitialProject_int\atlas_gui
5 Click OK to open the solution.

6 Select the deliver activity created during the deliver process and click OK.
7 Edit the Enter Working Copy Location Here box to specify the correct IIS virtual
directory for your integration view. For example:

http://localhost/ucm_admin_InitialProject_int/atlas_gui/gui_project_1.
8 Click OK.
All files are checked out to the integration view.
Note: From now on, you can open the solution through the Open Solution menu
item. The Open from Source Control menu item only performs special processing
the first time you open the solution in a new view.
Creating an ASP.NET Application

Before you can successfully debug the ASP.NET application in the integration view,
you must create an ASP.NET application for the integration view folder that contains
the ASP.NET project by using the IIS administrative tool. Otherwise, you will get
errors from ASP.NET when you debug the application in the integration view.
VS.NET created this ASP.NET application automatically in your development view
when you created the ASP.NET project, but you must perform this task manually in
any other views you create.
To create an ASP.NET application for your ASP.NET project in the integration view
on Windows XP:
2 Under Web Sites , expand Default Web Site.
Note: In the above window, you can see that gui_project_1 in your development
view has an ASP.NET application icon, while gui_project_1 in your integration
view does not.
3 Go to ucm_admin_InitialProject_int/atlas_gui. Right-click gui_project_1 and then click
Properties.
The gui_project_1 dialog box appears.

4 Click the Create button and accept all other defaults in the dialog box.

5 Click OK.
In the IIS administrative tool, the ASP.NET application icon appears beside
gui_project_1 (under ucm_admin_InitialProject_int).
Testing the Delivery

At this stage, you typically verify that the application works as expected by testing the
delivery and confirming that all merges are done correctly and all changes are
delivered. However, because no one else is currently working on the project, you do
not need to perform this verification now.
Completing the Delivery to the Integration Stream

You should still have an incomplete delivery to your integration stream.
To complete the delivery to the integration stream:
1 Select the Delivering to View dialog box (still open from the incomplete deliver)
and click Complete.
2 Click Close.
3 Exit the IDE. Click File > Exit.

With UCM, at certain points in the development cycle, as dictated by your
development process, your integrator (or project leader) creates a new baseline based
on the activities that you and your team members have delivered. After testing, your
integrator communicates to your team that a new recommended baseline is available.
In the integrations stream, create a baseline and then recommend the baseline so that
users can have access to the latest UCM components.
Creating a Baseline
In the integration stream, create a baseline for all three UCM components.
Note: You can also separately create a baseline for each UCM component.
To create a baseline for all three UCM components:

1 Ensure that you can access the ClearCase - UCM toolbar: click Views > Toolbars >
ClearCase - UCM .
2 On the ClearCase - UCM toolbar, click Make Baseline.

The Make Baseline dialog box appears.
3 Click OK to create a baseline for each of the three UCM components.
Recommend the baseline that users will access when they rebase their development
streams.
To recommend a baseline:
1 On the ClearCase - UCM toolbar, click Recommend Baseline.
2 Click Seed List.
When you seed the list for the new baselines at the INITIAL promotion level, you
will see the new baselines that you just created.
3 Click OK.

Once you have recommended a new baseline, you typically inform your team to
join the UCM project and begin work.
4 IDE: click File > Exit.
5 Log out as ucm_admin.

Before you start this section, ensure that you have performed all initial setup for each
new user.

This exercise refers to two users: dev1 and dev2. Set up each user’s work areas by
joining the UCM project, creating IIS virtual directories, and opening the solution in
VS.NET.
Joining the UCM Project

Join the UCM project from within the IDE.
To join the UCM project:
1 Log in as dev1 and start VS.NET.
3 In the Front Desk Window, click the Join Project button.
4 Select InitialProject and click Next.
view location (for example: C:\temp\views\dev1_InitialProject) and click Next.
location (for example: C:\temp\views\dev1_InitialProject_int) and click Next.
The Choose Components page appears.
8 Clear the Start component browser after creating view check box.
9 Ensure that all three atlas project component check boxes are selected for loading.
Clear the InitialComponent check box.
10 Click Finish. When the Confirm dialog box appears, click OK.
11 Repeat Step 1 to Step 10 for dev2.
Creating IIS Virtual Directories and ASP.NET Applications

For each user (dev1 and dev2), perform the following:
■ Create two IIS virtual directories to map the view root directories for each user’s
development and integration views. For more information, see Creating an IIS Alias
on page 210.
■ Create ASP.NET applications for gui_project_1 (the ASP.NET project) for each
user’s development and integration views. For more information, see Creating an
ASP.NET Application on page 219.

As dev1 in VS.NET, open your solution under source control for the first time.
1 As dev1 in VS.NET, click ClearCase > Front Desk.
2 Click dev1_InitialProject (your development view).
C:\temp\views\dev1_InitialProject\atlas_gui
5 Click OK.
6 When the ClearCase - Select Activity dialog box appears, create a new activity
called dev1 initial changes and select the newly-created activity.
http://localhost/dev1_InitialProject/atlas_gui/gui_project_1
8 Click OK.

Create a subsystem use case package on the main diagram of each subsystem model:
1 In the Solution Explorer, under midd_tier_project_1, double-click services
model.mdx.
The Check Out For Edit dialog box appears.
3 Click Check Out.
called create initial use-case packages and select the newly-created activity.
5 Click OK.
❑ Under gui_project_1, open gui model.mdx and create a UML Use Case Package
called gui use cases.
❑ Under data_layer_project_1, open data model.mdx and create a UML Use Case
Package called data use cases.

diagram.
You will create cross-model references by:
■ Creating a new diagram on the System Model called Atlas System Use Cases.
■ Dragging the use-case packages from the three subsystem models onto the new
Atlas System Use Cases diagram.
To create cross-model references:
1 In the VS.NET Solution Explorer, under gui_project_1, open System Model.mdx.
3 When prompted, check out System Model.mdx.
one. Click OK.
5 Name the new diagram Atlas System Use Cases.
Note: Diagrams provide a means of visualizing and manipulating the model
elements in a model. Different diagrams represent different views of the system
that you are developing.
❑
gui use cases
❑ data use cases
7 Save all your work. Click File > Save All.
8 Check in all files: in the Pending Checkins window, click Check In.

While logged in as dev1, deliver your files to the integration stream.
To deliver to the integration stream:
1 From the IDE, complete the delivery of your files to the integration stream. For
more information, see Delivering to the Integration Stream on page 216.
Because your delivery only reflects new model changes (no code changes), you do
not need to test the solution in the integration view before completing your
delivery.

As ucm_admin, create and recommend a baseline so that the changes delivered by dev1
can be shared with the team.
To create and recommend a baseline:
1 Log in as ucm_admin.
2 Create a new baseline. For more information, see Creating a Baseline on page 222.
3 Recommend the new baseline. For more information, see Recommending a Baseline
on page 222.

Rebasing as dev2
As dev2, rebase your development stream to the recommended baseline on the
integration stream to update your work area with the changes that dev1 delivered
(new model elements and cross-model references).
To rebase to the recommended baseline:
1 Log in as dev2 and open VS.NET.
3 Select dev2_InitialProject (your development view).
4 Click the Rebase button.
5 To view the baselines for this rebase, click Advanced .
The Change Rebase Configuration dialog box appears with a list of baselines you
will rebase to.
6 Click OK to return to the Rebase Stream Preview dialog box.
7 Click OK to begin the rebase.
The Merges Complete dialog box appears.
8 Click OK.
The Rebasing in View dialog box appears.
9 Click Complete.
10 Click Close.
Opening the Solution

As dev2, open the solution for the first time:
1 In the Front Desk Window, click the Open button, then click Open from Source
Control.
C:\temp\views\dev2_InitialProject\atlas_gui
called dev2 initial changes and select the newly-created activity.
http://localhost/dev2_InitialProject/atlas_gui/gui_project_1
5 Click OK.

user tries to check in and deliver files, they must do a merge to resolve the differences.
The following table describes the work you will do in this section:
1 Checks out file

Makes changes
Quits XDE
2 Checks out same file

Quits XDE
3 Checks in file
Delivers files
4 Checks in file
Delivers files, but needs to merge first.
element and deliver before a rebase. This generates a merge conflict when the second
user starts to deliver.

1 As dev2, in the IDE, click the Solution Explorer tab. Under midd_tier_project_1,
open services model.mdx.
middle tier.
3 When prompted to check out files, click Check Out.

4 When prompted for an activity, create a new activity.
6 Quit XDE: Click File > Exit. Leave services model.mdx checked out.
❑ Rename the services use cases package to dev1 middle tier.
❑ To open the solution as dev1, in the bottom pane of the Front Desk Window,
click atlas_project, then click the Open button.
8 Log in as dev2 again and check in and deliver your work as follows:
a Start the IDE.
b Click ClearCase > Front Desk.
c In the bottom pane of the Front Desk Window, click atlas_project, then click the
Open button.
d In the Model Explorer, right-click (midd_tier_project_1) services model and then

click Check In.
e From the IDE, complete the delivery of your files to the integration stream.

has checked in changes. The dev1 user has not yet checked in changes. When dev1
delivers changes, ClearCase displays a prompt to merge so that dev1 can resolve the
changes. Proceed as follows:
1 Log in as dev1.
2 Start your IDE. Open the solution: Click File > Open Solution and browse to the
atlas_project.sln file in your development view (dev1_InitialProject).
click Check In.
4 Complete the check in.
5 From the IDE, deliver your files to the integration stream.
A message appears saying that the element cannot be merged automatically.
6 Select the Start the Diff Merge tool for this element option and click OK to launch an
XDE compare/merge session.
Merging Changes
the conflict.
10 Select the Deliver from Stream - Merges Complete dialog box and click OK.
The Delivering to View dialog box appears.

11 Click Complete to make the changes from the merge permanent.


1 While logged in as dev1, in the IDE Solution Explorer, right-click
data_layer_project_1 and then click Add > New Folder.
2 When prompted to check out, click Check Out.

3 Create an activity called move model.
4 Rename the new folder Models.
5 In the Model Explorer, close data model if open: right-click data model and then
click Close.
6 In the Solution Explorer, drag the data model.mdx file into the new Models folder.
Ignore any message prompts.
8 Check in all files from the Pending Checkins Window. The data model.mdx file and
its directory are now checked into ClearCase.
9 Deliver all files to the IntegrationStream.

2 In the IDE Solution Explorer, under gui_project_1, open System Model.mdx.
3 Click Resolve.
Models folder).
6 Click Apply.
7 If you are prompted to check out, click Check Out.

Index
A viewing a branch 163, 217
views 115
activities 109, 112 Comparative Model Explorer 90
artifacts 109 Comparative Property Browser 95
auto-advance 74 Comparative Property Explorer 96
auto-resolve 70, 76 comparing (XDE models) 140, 172, 193, 228
starting a manual session 59
understanding the results 63
B workflow 55, 58
component-based development 31
base models 59 components
designating 60 development 107
merging with a common ancestor 70 planning communication 36
merging without a common ancestor 72 components (UCM) 112
selecting when fusing 61 adding 122
baselines 111, 112 designing 118
adding 152, 205 read-only 121
composite 122 composite object versioning 131, 158
creating 165, 222 configuration management 27
promotion levels 122 activity-based 32
recommending 154, 165, 207, 222 configuring for XDE 53
branches (ClearCase) 114 working without 39
configuring
ClearCase 126, 146, 178, 198
C environment variables 126, 146, 178, 198
conflict icons 66, 94
change sets 111
cross-model references
checking in (ClearCase) 115, 134, 161
component-relative 106
checking out (ClearCase) 115
creating 103, 138, 168
ClearCase 113
resolving 143, 174, 196, 231
adding baselines 152, 205
source-relative 104
branches 114
checking in 115, 134, 161
checking out 115
configuring 51 D
creating work areas 151, 204 delivering activities 111, 162, 216
delivering 162, 216 development
elements 113 components 107
groups 126, 146, 178, 198 streams 112
merging automatically 56 diagram phase (merging) 75
merging models 51 difference icons 65, 93
moving XDE files 45 Differences Explorer 96
setting up 147, 199
version trees 113
233
E ownership policies 48
resolving conflicts 80
elements (ClearCase) 113 resolving differences 69
environment variables sample scenario 140, 172, 193, 228
configuring 126, 146, 178, 198 semantic phase 74
silent 52
using a new XDE instance 56
F model elements
moving 54
fusing models 61 referencing 55
model partitioning 43
benefits 44
G drawbacks 44
guidelines 46
geographically distributed development 35
planning 48
GUIDs 63
models
creating XDE 130, 157
fusing 61
I merging 80
icons partitioning 43
conflict 66, 94 sharing 40
difference 65, 93 sharing outside source control 108
resolution 94 validating 130, 156
integration streams 111, 112
P
J parallel development 30, 32
java controlling change 33
adding classes 133, 160 controlling releases 35
creating modeling projects 129, 155 developing multiple releases 32
joining a project 166, 223 partitioning
models 43
planning 48
platform models 107
M profiles 97
merging project (UCM) 112, 148, 200
automatic 56 joining 111, 166, 223
base models 59 project set file
ClearCase 51 adding to source control 135, 162
ClearCase versions 114 creating 134, 161
common ancestors 59 importing 139, 170
detecting changes 65 loading into a view 164
diagram phase 74 project VOB 115
fusing 61 creating 148, 200
guidelines 50, 80 projects
identifying conflicts 66 controlling change 33
identifying differences 65 creating java modeling 129, 155
out-of-context 44 Rational 111

PVOB. See project VOB. overview of using 110
planning components 150, 202
project 112
R project VOB 115
rebasing 154, 208
Rational Unified Process 109 recommending baselines 154, 207
rebase (UCM) 111, 154, 208 registering components 152, 205
refactoring 142, 174, 195, 230 streams 115
release strategy 119 Unified Change Management. See UCM.
resolution icons 94 unresolve 76
resolve using 76
V
S
validating models 130, 156
semantic phase (merging) 74 version trees (ClearCase) 113
streams (UCM) 111, 112, 115 views (ClearCase) 115
synchronizing 153, 206 creating 128, 136, 181, 188
subunits dynamic 151, 204
combining 55 snapshot 151, 204
planning 47 VOBs 113
preferences 55 creating 128, 150, 180, 203
referencing 55 planning 128, 180
working with 53 storing components 120
system architecture 118
X
T
XDE
tagged values 98 adding packages 137, 168
comparing models 140, 172, 193, 228
configuring ClearCase 51
U creating models 130, 157
generating code for classes 133, 160
UCM 109 merging models 140, 172, 193, 228
changing project policies 153, 206 project set file 134, 161
creating a project 148, 200 refactoring 142, 174, 195, 230
designing components 118 starting 129, 155
joining a project 166, 223
Index 235

IBM - Rational XDE Guide To Team Development For Windows

Diunggah oleh

Informasi Dokumen

Deskripsi Asli:

Judul Asli

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

IBM - Rational XDE Guide To Team Development For Windows

Diunggah oleh

Hak Cipta:

Format Tersedia

Rational Software Corporation ®

PART NUMBER : G126-5387-00

U.S. Government Restricted Rights

1 Using This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23

2 Planning a Configuration Management Environment . . . . . . . . . . . . .27

4 Planning Model Partitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

5 Comparing and Merging Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

vi Rational XDE Guide to Team Development

6 Understanding the Rational XDE Compare/Merge User Interface . . 89

viii Rational XDE Guide to Team Development

7 Working With Cross-Model References . . . . . . . . . . . . . . . . . . . . . . . 103

8 Understanding the Basics of UCM . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

9 Designing a ClearCase UCM Environment. . . . . . . . . . . . . . . . . . . . . 117

x Rational XDE Guide to Team Development

11 Scenario: Rational XDE and UCM With IBM WSAD. . . . . . . . . . . . . . 145

12 Scenario: Rational XDE and Base ClearCase With

xii Rational XDE Guide to Team Development

13 Scenario: Rational XDE and UCM With Microsoft VS.NET . . . . . . . 197

xiv Rational XDE Guide to Team Development

Table 1 Applicable Roles in This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Integration Description Where it is Documented

XDE– You can compare and track different ■

XDE– You can perform run-time analysis on ■

XDE– You can associate RequisitePro ■

XDE– You can launch Extended Help from the ■

xx Rational XDE Guide to Team Development

Your Location Telephone Facsimile E-mail

North America (800) 433-5444 (781) 676-2460 support@rational.com

Europe, Middle +31 (0) 20-4546-200 +31 (0) 20-4546-201 support@europe.rational.com

Asia Pacific +61-2-9419-0111 +61-2-9419-0123 support@apac.rational.com

Chapter - Preface xxi

Table 1 Applicable Roles in This Manual

Analyst Defines the system to develop; manages requirements as they change

Configuration Performs all VOB or UCM component administrative steps. In a UCM

Network Establishes the user communities. Assists with meeting prerequisites.

Tool Completes the tool installation prerequisites.

Project Manager Creates UCM reports; tracks metrics.

Tester (and Outside of the scope of this manual.

Roadmap: Chapters and Applicable Roles

Table 2 Roadmap: Chapters and Applicable Roles

Chapter Applicable Roles

2 Planning a Configuration Management Environment Architect

3 Working Without Configuration Management Analyst

4 Planning Model Partitions Architect

5 Comparing and Merging Models Developer

6 Understanding the Rational XDE Compare/Merge User Interface

7 Working With Cross-Model References

8 Understanding the Basics of UCM All Roles

24 Rational XDE Guide to Team Development

Chapter Applicable Roles

9 Designing a ClearCase UCM Environment Architect

13 Scenario: Rational XDE and UCM With Microsoft VS.NET(1)

Chapter 1 - Using This Manual 25

Understanding Your Configuration Management Needs

Table 3 Software Development Problems and CM Recommendations

It is better to address all key elements of a process in a lightweight manner before

Increasing Software System Complexity

Increasing Project Environment Complexity

28 Rational XDE Guide to Team Development

Identifying Configuration Management Needs

Table 4 Team Characteristics and CM Needs

Your Team Team Characteristics CM Needs