ibm - rational xde guide to team development for windows

Rational Software Corporation®

Rational XDEGuide to Team Development

VERSION: 2003.06.00

PART NUMBER: G126-5387-00

WINDOWS

[email protected]://www.rational.com

Legal NoticesCopyright ©2003, Rational Software Corporation. All rights reserved.Part Number: 800-026181-000Version 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 RightsLicensee 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 DisclaimerThis 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 AcknowledgementsPortions 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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xixAudience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix

Other Resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix

XDE Integrations With Other Rational Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx

Contacting Rational Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi

1 Using This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23Understanding Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Roadmap: Chapters and Applicable Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

2 Planning a Configuration Management Environment . . . . . . . . . . . . .27Understanding Your Configuration Management Needs. . . . . . . . . . . . . . . . . . . . . . 27

Increasing Software System Complexity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Increasing Project Environment Complexity . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Identifying Configuration Management Needs . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Basic Version Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Parallel Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Automated Workspace Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Automated Build and Release Management . . . . . . . . . . . . . . . . . . . . . . . . 31Component-Based Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Activity-Based Configuration Management . . . . . . . . . . . . . . . . . . . . . . . . . 32

How Parallel Development Can Help Your Team . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Maintaining an Existing Release While Developing the Next Release . . . . . . . . 32Developing Multiple Releases and Multiple Patch Streams . . . . . . . . . . . . . . . . 33Controlling the Rate of Change Within a Project . . . . . . . . . . . . . . . . . . . . . . . . 33Allowing Teams to Experiment with Extending the Architecture. . . . . . . . . . . . . 34Other Examples of Isolating Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Controlling Releases Within a Development Group . . . . . . . . . . . . . . . . . . . . . . 35

Planning for Geographically Distributed Development . . . . . . . . . . . . . . . . . . . . . . . 35Planning the Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Planning Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Planning the Technology Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Implementation Technologies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Infrastructure Technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

v

3 Working Without Configuration Management. . . . . . . . . . . . . . . . . . . 39The 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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Understanding Model Partitioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Deciding Whether to Partition Models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Benefits of Model Partitioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Faster Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Less Merging: Faster Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Drawbacks of Model Partitioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Out-of-Context Merging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Discrepancies With Logical Elements and Physical Representations . . . . . 45

Moving Files With XDE and ClearCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Balancing the Benefits and Drawbacks of Model Partitioning . . . . . . . . . . . . . . 46

Model Partitioning Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46When to Decompose a Model Into Subunits . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Determining Candidates for Separate Storage Units . . . . . . . . . . . . . . . . . . . . . 47

Minimizing the Dependencies Between Units . . . . . . . . . . . . . . . . . . . . . . . 47Creating Separate Units for Complex Diagrams . . . . . . . . . . . . . . . . . . . . . 47

Partitioning Stable Abstraction Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Developing an Ownership Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Model Ownership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Package Ownership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Subunit Ownership. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Avoiding Merges When Separating or Combining Model Elements . . . . . . . . . . 50

5 Comparing and Merging Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Working With ClearCase. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Merging Models With ClearCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Merging Silently . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Merging Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Triggering Multiple Model Merge Sessions . . . . . . . . . . . . . . . . . . . . . . . . . 52

Working With Other Configuration Management Systems . . . . . . . . . . . . . . . . . . . . 53

Working With Subunits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Moving Model Elements From the Model Explorer . . . . . . . . . . . . . . . . . . . . . . . 54Moving Model Elements From Outside the Model Explorer . . . . . . . . . . . . . . . . 54

vi Rational XDE Guide to Team Development

Working With Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Referencing Model Elements In Other Subunits . . . . . . . . . . . . . . . . . . . . . . . . 55Combining Separated Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Setting Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Understanding Automatic XDE Compare/Merge Sessions . . . . . . . . . . . . . . . . . . . 55Starting an XDE Compare/Merge Session Automatically . . . . . . . . . . . . . . . . . 56

Starting a Session In a New XDE Instance . . . . . . . . . . . . . . . . . . . . . . . . . 56Starting a Session In an Existing XDE Instance . . . . . . . . . . . . . . . . . . . . . 57

Understanding the Results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Ending the Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Understanding Manual XDE Compare/Merge Sessions. . . . . . . . . . . . . . . . . . . . . . 58Starting an XDE Compare/Merge Session Manually . . . . . . . . . . . . . . . . . . . . . 59Selecting Contributors and Base Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Models With a Common Ancestor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Models Without a Common Ancestor (Fusing) . . . . . . . . . . . . . . . . . . . . . . 61Alternate Workflow: Merging More Than Two Contributors And a

Base Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Selecting Subunits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Understanding the Results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Ending the Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Understanding the Results of an XDE Compare Session . . . . . . . . . . . . . . . . . . . . 63Understanding Model Element Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Matching Elements By GUID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Matching Elements By Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Exceptions To Matching By Name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Matching Elements When Fusing Models . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Identifying Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Detecting Moved or Changed Model Elements . . . . . . . . . . . . . . . . . . . . . . . . . 65Identifying Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Working With the Results of an XDE Merge Session . . . . . . . . . . . . . . . . . . . . . . . . 68Understanding the Unresolved Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Counting Unresolved Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Counting Unresolved Difference Not Part Of a Conflict . . . . . . . . . . . . . . . . 69XDE Merge Session Workflow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Resolving Differences Automatically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Understanding Auto-Resolve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Merging With a Common Base Model: Auto-Resolve States . . . . . . . . . . . 70Merging Without a Common Ancestor Base Model (fusing): Auto-Resolve

States. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Contents vii

Navigating Through Differences and Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . 74Auto-Advance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Merge Phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Manually Resolving Differences and Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . 75Resolving Differences and Conflicts Individually . . . . . . . . . . . . . . . . . . . . . 76Resolving Several Differences and Conflicts At Once . . . . . . . . . . . . . . . . . 77Example Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Model Merging Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Updating Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Resolving Conflicts Consistently . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Merge Granularity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Optimizing XDE Compare/Merge Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Optimizing Performance: Key Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Factors That Affect XDE Compare/Merge Performance. . . . . . . . . . . . . . . . . . . 82

Checkin Frequency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Modifying Versus Adding To a Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Other Factors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Evaluating Risk Factors Early In the Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Example Scenarios. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Working With a Single Branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Working With a Main Branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Working With UCM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Working Without Configuration Management . . . . . . . . . . . . . . . . . . . . . . . 85

Working In Parallel Development: Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Merging Into the Common Model Separately. . . . . . . . . . . . . . . . . . . . . . . . 86Example: Working In Parallel Development . . . . . . . . . . . . . . . . . . . . . . . . . 86

6 Understanding the Rational XDE Compare/Merge User Interface . . 89The Comparative Model Explorers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Element Order In the Comparative Model Explorer . . . . . . . . . . . . . . . . . . . . . . 91Unnamed Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Generalized 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Differences Arranged by Conflict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

viii Rational XDE Guide to Team Development

Conflicts Arranged by Difference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Model Elements Specific to the Comparative Model Explorers . . . . . . . . . . . . . . . . 97Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Tagged Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98Additional Semantic Model Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100View Elements Within Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

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

Source-Relative References. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Working With Source-Relative References . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Working With Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Component-Relative References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Creating Development Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Working With Component-Relative References. . . . . . . . . . . . . . . . . . . . . . . . 107

Working With Platform Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Working With Shared Models Outside of Source Control . . . . . . . . . . . . . 108

8 Understanding the Basics of UCM . . . . . . . . . . . . . . . . . . . . . . . . . . . 109What Is UCM? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

The Building Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Why Use UCM? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Typical Way to Use UCM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

UCM Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112UCM Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Baseline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

ClearCase Basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113VOBs and Their Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Views and Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Using ClearCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Behind the Scenes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

For More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

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

The Elements of Your Design. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Contents ix

System Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Team Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Release Strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Example: Multiple Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Situation 1: Simple . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Situation 2: More Complex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Example: Multiple GUIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Refining the Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Administrative Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Storing Multiple Components in a Single VOB. . . . . . . . . . . . . . . . . . . . . . 120Managing Complexity: Read-only or Unavailable Components . . . . . . . . . 121Designing Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Other Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Adding a Component to an Existing Environment . . . . . . . . . . . . . . . . . . . . . . 122

Relating Component Design to Release Planning . . . . . . . . . . . . . . . . . . . . . . . . . 122Composite Baselines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Promotion Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

10 Scenario: Rational XDE and Base ClearCase With IBM WSAD. . . . 125Before You Begin: Installing and Configuring Software. . . . . . . . . . . . . . . . . . . . . . 125

Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Setting Up the ClearCase LT 2003 Environment . . . . . . . . . . . . . . . . . . . . 125

Using ClearCase 2003 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Setting Up the User Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Configuring ClearCase Groups and Environment Variables . . . . . . . . . . . 126

Setting Up the ClearCase Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Planning VOBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128Creating VOBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128Creating a View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Starting XDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Creating a Java Modeling Project and XDE Models . . . . . . . . . . . . . . . . . . . . . . . . 129Creating a Java Modeling Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Validating Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Creating XDE Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Dividing a Model to Allow Concurrent Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Composite Object Versioning Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Navigator Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Dividing a Model Into Subunits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Adding Java Classes to the Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

x Rational XDE Guide to Team Development

Generating Code for the Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Saving, Validating, and Checking In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Creating a Project Set File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Adding the Project Set File to Source Control . . . . . . . . . . . . . . . . . . . . . . 135

Developing as Part of a Team. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Setting Up the Developers’ Work Areas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Starting to Work in XDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Adding to the XDE Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Creating Cross-Model References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Importing the Project Set File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Tips for Working with ClearCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Starting Parallel Development: Comparing and Merging Models. . . . . . . . . . . 140

Introducing Conflicts into the Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141Resolving the Conflict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Refactoring: Adding, Moving, and Deleting Files . . . . . . . . . . . . . . . . . . . . . . . 142Resolving Broken Cross-Model References . . . . . . . . . . . . . . . . . . . . . . . . . . 143

11 Scenario: Rational XDE and UCM With IBM WSAD. . . . . . . . . . . . . . 145Before You Begin: Installing and Configuring Software . . . . . . . . . . . . . . . . . . . . . 145

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Setting Up the ClearCase LT 2003 Environment . . . . . . . . . . . . . . . . . . . . 145

Using ClearCase 2003 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146Setting Up the User Community. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146


Setting Up the ClearCase Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147Creating the Initial Project VOB and UCM Project . . . . . . . . . . . . . . . . . . . . . . 148Planning UCM Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150Creating VOBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150Creating ClearCase Work Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151Registering UCM Components as Modifiable . . . . . . . . . . . . . . . . . . . . . . . . . 152

Adding Foundation Baselines to Your UCM Project. . . . . . . . . . . . . . . . . . 152Changing UCM Project Policies for the UCM Components . . . . . . . . . . . . 153

Synchronizing the Integration Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Recommending a Baseline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154Rebasing Your Development Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Starting XDE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

Creating a Java Modeling Project and XDE Models . . . . . . . . . . . . . . . . . . . . . . . . 155Creating a Java Modeling Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155Validating Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Contents xi

Creating XDE Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Dividing a Model to Allow Concurrent Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Composite Object Versioning Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158Navigator Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158Dividing a Model Into Subunits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Adding Java Classes to the Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Generating Code for the Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Saving, Validating, and Checking In. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Creating a Project Set File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Adding the Project Set File to Source Control . . . . . . . . . . . . . . . . . . . . . . 162

Delivering to the Integration Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162Viewing the ClearCase Branch Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163Loading the Project Set in a New View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164Testing the Delivery in the Integration View . . . . . . . . . . . . . . . . . . . . . . . . . . . 164Completing the Delivery to the Integration Stream . . . . . . . . . . . . . . . . . . . . . . 165Creating and Recommending a Baseline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Creating a Baseline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165Recommending a Baseline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Developing as Part of a Team . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Setting Up the Developers’ Work Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

Joining the UCM Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166Starting to Work in XDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Adding to the XDE Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168Creating Cross-Model References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

Delivering to the Integration Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Creating and Recommending a Baseline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Rebasing as dev2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Importing the Project Set File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Tips for Working with ClearCase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171Starting Parallel Development: Comparing and Merging Models . . . . . . . . . . . 171

Introducing Conflicts into the Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Resolving the Conflict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Refactoring: Adding, Moving, and Deleting Files . . . . . . . . . . . . . . . . . . . . . . . 174Resolving Broken Cross-Model References. . . . . . . . . . . . . . . . . . . . . . . . . . . 174

12 Scenario: Rational XDE and Base ClearCase With Microsoft VS.NET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Before You Begin: Installing and Configuring Software. . . . . . . . . . . . . . . . . . . . . . 177Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Setting Up the ClearCase LT 2003 Environment . . . . . . . . . . . . . . . . . . . . 177

xii Rational XDE Guide to Team Development

Using ClearCase 2003 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Setting Up the User Community. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178


Setting Up the ClearCase Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Planning VOBs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

Working with VS.NET Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180Creating VOBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180Creating a View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Creating a VS.NET Solution With XDE Models . . . . . . . . . . . . . . . . . . . . . . . . . . . 182Creating a VS.NET Solution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

Creating a Blank Solution within a VOB . . . . . . . . . . . . . . . . . . . . . . . . . . 182Creating a Visual C# Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182Creating a VB.NET Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Creating an IIS Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Creating an ASP.NET Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Adding Code Models to the Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Validating Models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

Creating XDE Models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Adding a Getting Started Model to the Solution . . . . . . . . . . . . . . . . . . . . 185Adding a Blank Model to Each Project . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Dividing a Model to Allow Concurrent Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Composite Object Versioning Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . 186Solution Explorer Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186Dividing a Model Into Subunits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Adding the Solution to Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187Testing in the Development View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187Creating Sample Content. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187Testing in the Development View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188Checking In all Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Developing as Part of a Team. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188Setting Up the Developers’ Work Areas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Creating IIS Virtual Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Starting to Work in XDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Adding to the XDE Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190Creating Cross-Model References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Updating Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192Starting Parallel Development: Comparing and Merging Models. . . . . . . . . . . 193


Refactoring: Adding, Moving, and Deleting Files . . . . . . . . . . . . . . . . . . . . . . . 195

Contents xiii

Resolving Broken Cross-Model References. . . . . . . . . . . . . . . . . . . . . . . . . . . 196

13 Scenario: Rational XDE and UCM With Microsoft VS.NET . . . . . . . 197Before You Begin: Installing and Configuring Software. . . . . . . . . . . . . . . . . . . . . . 197

Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197Setting Up the ClearCase LT 2003 Environment . . . . . . . . . . . . . . . . . . . . 197

Using ClearCase 2003 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198Setting Up the User Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198


Setting Up the ClearCase Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199Creating the Initial Project VOB and UCM Project . . . . . . . . . . . . . . . . . . . . . . 200Planning UCM Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

Working with VS.NET Projects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203Creating VOBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203Creating ClearCase Work Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204Registering UCM Components as Modifiable. . . . . . . . . . . . . . . . . . . . . . . . . . 205

Adding Foundation Baselines to Your UCM Project . . . . . . . . . . . . . . . . . . 205Changing UCM Project Policies for the UCM Components . . . . . . . . . . . . 206

Synchronizing the Integration Stream. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206Recommending a Baseline. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207Rebasing Your Development Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Creating a VS.NET Solution With XDE Models . . . . . . . . . . . . . . . . . . . . . . . . . . . 208Creating a VS.NET Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Creating a Blank Solution within a VOB. . . . . . . . . . . . . . . . . . . . . . . . . . . 209Creating a Visual C# Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209Creating a VB.NET Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209Creating an IIS Alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210Creating an ASP.NET Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210Adding Code Models to the Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Validating Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Creating XDE Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Adding a Getting Started Model to the Solution. . . . . . . . . . . . . . . . . . . . . 211Adding a Blank Model to Each Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Dividing a Model to Allow Concurrent Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212Composite Object Versioning Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212Solution Explorer Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213Dividing a Model Into Subunits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Setting Up the Solution in the ClearCase Environment . . . . . . . . . . . . . . . . . . . . . 214Adding the Solution to Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214Testing in the Development View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

xiv Rational XDE Guide to Team Development

Creating Sample Content. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214Testing in the Development View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215Checking In all Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215Delivering to the Integration Stream. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216Viewing the ClearCase Branch Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217Creating an IIS Alias for the Integration View. . . . . . . . . . . . . . . . . . . . . . . . . . 217Testing in the Integration View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

Opening the Solution in the Integration View. . . . . . . . . . . . . . . . . . . . . . . 218Creating an ASP.NET Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219Testing the Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Completing the Delivery to the Integration Stream . . . . . . . . . . . . . . . . . . . . . 221Creating and Recommending a Baseline. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

Creating a Baseline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222Recommending a Baseline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

Developing as Part of a Team. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223Setting Up the Developers’ Work Areas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

Joining the UCM Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223Creating IIS Virtual Directories and ASP.NET Applications . . . . . . . . . . . . 224

Starting to Work in XDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224Adding to the XDE Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225Creating Cross-Model References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

Delivering to the Integration Stream. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226Creating and Recommending a Baseline. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226Rebasing as dev2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227Opening the Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227Starting Parallel Development: Comparing and Merging Models. . . . . . . . . . . 228


Refactoring: Adding, Moving, and Deleting Files . . . . . . . . . . . . . . . . . . . . . . . 230Resolving Broken Cross-Model References . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

Contents xv

xvi Rational XDE Guide to Team Development

xvii

Table 1 Applicable Roles in This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Table 2 Roadmap: Chapters and Applicable Roles . . . . . . . . . . . . . . . . . . . . 24Table 3 Software Development Problems and CM Recommendations . . . . . 28Table 4 Team Characteristics and CM Needs . . . . . . . . . . . . . . . . . . . . . . . . 29Table 5 Types of Differences Between a Contributor and a Base Model . . . . 65Table 6 Types of Conflicts Between Contributors and a Base Model . . . . . . . 66Table 7 Merging with a Common Ancestor: Auto-Resolve States . . . . . . . . . 71Table 8 Merging without a Common Ancestor Base Model (fusing):

Auto-Resolve States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Table 9 Sample Merge Result With Auto-Resolved Differences . . . . . . . . . . 78Table 10 Resolving Each Conflict Individually in Favor of Contributor 2 . . . . . 79Table 11 Applying the Resolve All Using Contributor 2 Command . . . . . . . . . 79Table 12 Columns in the Comparative Model Explorer . . . . . . . . . . . . . . . . . . 90Table 13 Difference Icons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Table 14 Sample Conflict Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Table 15 Sample Resolution Icons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Table 16 Columns in the Comparative Property Browser. . . . . . . . . . . . . . . . . 95Table 17 Profile-Related Model Elements in the Comparative Model Explorer 98Table 18 Tagged Value-Related Model Elements in the Comparative Model

Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Table 19 Semantic Model Elements in the Comparative Model Explorer. . . . 100Table 20 Selected View-Related Model Elements in the Comparative Model

Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Table 21 Creating Source-Relative References Between Projects . . . . . . . . 105Table 22 Starting the Design Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Tables

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 [email protected].

■ 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

http://www.rational.com/documentation/

http://www.rational.com/university

XDE Integrations With Other Rational Products

Integration Description Where it is Documented

XDE–ClearCase

You can compare and track different model elements, identify the differences between them, and merge models.

■ Rational XDE Help topic: Rational ClearCase and Rational XDE Integration

■ Rational XDE Help topic: Working with Models Under Source Control

■ Rational XDE Help topic: Working with Rational ClearCase

XDE–PurifyPlus

You can perform run-time analysis on applications generated from XDE.

Run-time analysis is the execution of instrumented code and the analysis of the collected data to find programming errors and ways to improve software performance.

■ Rational XDE Help topic: Rational PurifyPlus and Rational XDE Integration

■ Rational XDE Help topic: Tracing Application Execution to Trace Sequence Diagrams

XDE–RequisitePro

You can associate RequisitePro requirements and documents with XDE use cases and models.

■ Rational XDE Help topic: Rational RequisitePro and Rational XDE Integration

■ Rational XDE Help topic: Configuring Rational XDE Models for Requirements Integration

XDE–Rational Unified Process

You can launch Extended Help from the Help menu. Extended Help displays RUP tool mentors for XDE.

■ Rational XDE Help topic: Rational Unified Process

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:

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)

Your Location Telephone Facsimile E-mail

North America (800) 433-5444(toll free)

(408) 863-4000Cupertino, CA

(781) 676-2460Lexington, MA

[email protected]

Europe, Middle East, Africa

+31 (0) 20-4546-200Netherlands

+31 (0) 20-4546-201Netherlands

[email protected]

Asia Pacific +61-2-9419-0111Australia

+61-2-9419-0123Australia

[email protected]

Chapter - Preface xxi

xxii Rational XDE Guide to Team Development

1Using This Manual

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 Manager

Performs all VOB or UCM component administrative steps. In a UCM environment: promotes version and baseline labels, plans the environment (including components), and sets up the initial projects.

Network Administrator

Establishes the user communities. Assists with meeting prerequisites.

Tool Administrator

Completes the tool installation prerequisites.

Project Manager Creates UCM reports; tracks metrics.

Developer Adds classes; establishes and maintains file directories; manages personal ClearCase environment.

Tester (and other roles)

Outside of the scope of this manual.

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



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

(1) These chapters describe sample team development scenarios that may be of interest to all roles.

9 Designing a ClearCase UCM Environment Architect



10 Scenario: Rational XDE and Base ClearCase With IBM WSAD (1) Architect


Developer11 Scenario: Rational XDE and UCM With IBM WSAD(1)

12 Scenario: Rational XDE and Base ClearCase With Microsoft VS.NET(1)

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

Table 2 Roadmap: Chapters and Applicable Roles

Chapter Applicable Roles

Chapter 1 - Using This Manual 25

2Planning a Configuration Management Environment

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.

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.

Table 3 Software Development Problems and CM Recommendations

Problem CM Recommendation

Increasing software system complexity

Regularly evaluate and tune your CM processes and use CM tools that are easily customized and highly scalable. For more information, see Increasing Software System Complexity on page 28.

Increasing project environment complexity

Use scalable CM tools and processes. For more information, see Increasing Project Environment Complexity on page 28.

Identifying and meeting team needs

Use CM tools and processes that meet the needs of your team. For more information, see Identifying Configuration Management Needs on page 29.


■ 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 one project without links to any other projects

Basic version control

Modest 6 to 15 members, working on one or more products in a family

[All of the above] plus the following:■ Parallel development■ 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 2 to 30 members each, with fewer than 150 total members, working toward a common release of one or more products in a product family

[All of the above] plus some or all of the following: ■ Component-based development■ Activity-based configuration management■ Geographically distributed development. For

more information, see Planning for Geographically Distributed Development on page 35.

Multiple Teams

A large number of teams of various sizes cooperating on a release of one or more products, where the total number of team members is 150 or more

All of the above

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:

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:

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

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

❑ Establish a system architecture.

❑ Divide your architecture into components that can be developed separately.

❑ Assign each developmental component to one co-located team.


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:

In terms of CM, 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.

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


3Working Without Configuration Management

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

4Planning Model Partitions

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.


5Comparing and Merging Models

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:



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.

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

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.


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.


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.

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.

Table 6 Types of Conflicts Between Contributors and a Base Model

Icon Description


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:

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.

Unresolved conflicts

Unresolved differences that are part of a conflict

Unresolved differences that are not part of a conflict

Unresolved count

10 30 15 10 + 15 = 25


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.

“-” 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.

Table 7 Merging with a Common Ancestor: Auto-Resolve States

Auto-Resolve StateContributor 1 (Base Model) Contributor 2 Contributor 3 Result

No change A A A A

Added -- A -- A

Changed A A B B

Moved A A B B

Deleted A A -- --

Change-Change Conflict

A B C !

Change-Delete Conflict

A B -- !

Add-Add Conflict -- B C !


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.

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

Table 8 Merging without a Common Ancestor Base Model (fusing): Auto-Resolve States

Auto-Resolve StateContributor 1 (Base Model) Contributor 2 Contributor 3 Result

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 Conflict

A B C ! (1)

Change-Delete Conflict

A B -- ! (1)

Add-Add Conflict -- B C !


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:



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):

“!” 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.

Table 9 Sample Merge Result With Auto-Resolved Differences

Contributor 1(Base Model)

Contributor 2(Changes)


Merge Result

C1 Class1 C1 Class1

C2 Class2 MyClass2 !

C3 C3 MyClass3 MyClass3


■ 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:

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 10 Resolving Each Conflict Individually in Favor of Contributor 2



Contributor 3(Changes) Merge Result

C1 Class1 C1 Class1

C2 Class2 MyClass2 Class2

C3 C3 MyClass3 MyClass3

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.


6Understanding the Rational XDE Compare/Merge User 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.


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

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.

D Displays icons for each difference between the contributor to the immediate right of this column and the base contributor.a

[n] The next contributor.a

Table 12 Columns in the Comparative Model Explorer

Column Description

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.

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.

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


For a complete list of resolution icons, see the Rational XDE Help.

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

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.


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.

Property Identifies, for each row, the name of the property being displayed in that row.

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.

D Displays icons for each difference between the contributor to the immediate right of this column and the base contributor.a

[n] The second contributor.a

Table 16 Columns in the Comparative Property Browser

Column Description


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.

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


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 value

A tagged value of type enumeration. The definition 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 Model Explorer but not in the Model Explorer.

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.

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.


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 Model Explorer but not in the Model Explorer.

Table 20 Selected View-Related Model Elements in the Comparative Model 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

SubShapeView,

NameCompartmentView

ListCompartmentView

Representation of objects within a diagram is done by a composition of various view elements, beginning with a single PositionalGeneralView object.

The PositionalGeneralView object contains a reference to 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

OnLineView

Representation of line-like relationships such as 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.


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.

Table 20 Selected View-Related Model Elements in the Comparative Model Explorer



7Working With Cross-Model References

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.

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.

Table 21 Creating Source-Relative References Between Projects

IDE Project Project ContentsTo Create a Source-Relative Reference:

proj1 ■ Code model with a main diagram■ Model element called class1

Drag class1 onto the code model main diagram in proj2

proj2 ■ Code model with a main diagram■ Model element called class2

Drag class2 onto the code model main diagram in proj1

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.


8Understanding the Basics of UCM

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

Development cyclePromotebaselines

Integratework

Makebaselines

Rebasework area

Work onactivities

Deliveractivities

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.


9Designing a ClearCase UCM Environment

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 process take?

For a simple project, you can probably accomplish the design 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 design?

The team of people who design your ClearCase UCM 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 design process?

We recommend that as part of the design process, you create a 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.


10Scenario: Rational XDE and Base ClearCase With IBM WSAD

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

4 On the Add Element(s) to Source Control dialog box, clear the Keep checked out 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:


2 In the Model Explorer, right-click (data_layer_project_1) Java Code Model and then 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 > Rational ClearCase > Create View.

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.

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

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.


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), under the gui_project_1 project directory. For example:

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.


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.


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 dev2_view (your development view), under the gui_project_1 project directory. For example:

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 Existing XDE Instance on page 57.

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:

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.

Step dev1 activities dev2 activities

1 Checks out fileMakes changesKeeps file checked outQuits XDE

2 Checks out same file (unreserved)Makes conflicting changeKeeps file checked outQuits XDE

3 Checks in file reserved

4 Checks in file

(Next section) tries to check in, but needs to merge first.


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 click Team > Check In.


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.


11Scenario: Rational XDE and UCM With IBM WSAD

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 ucm_admin. There are two developers, whose user IDs are dev1 and dev2.




Prerequisites


■ WSAD 5.0

■ Rational XDE Developer - Java Platform Edition 2003





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


145




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, ucm_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.









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

ClearCase stores file elements, directory elements, derived objects, and metadata in a 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

As the number of files and directories in your system increases, you need a way to reduce the complexity of managing them. Components are the UCM mechanism for simplifying the organization of your files and directories. The elements that you 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

ClearCase stores file elements, directory elements, derived objects, and metadata in a 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.




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 integration stream. The development stream tracks the activities assigned to you and 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:


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


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.

4 On the Add Element(s) to Source Control dialog box, clear the Keep checked out 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_1Example 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.


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





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





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.





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.




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.


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:


2 In the Model Explorer, right-click (data_layer_project_1) Java Code Model and then click Synchronize.




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, under the gui_project_1 project directory. For example:

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.



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.


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:

1 In the ClearCase Project Explorer, right-click IntegrationStream and then click 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.





5 In the Where would you like the root of this view? box, specify the development view location (for example: C:\temp\views\dev1_InitialProject) and click Next.

6 In the Where would you like the root of this view? box, specify the integration view 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.


3 XDE prompts you to select the ClearCase view to use. Select dev1_InitialProject and click OK.

Your IDE starts.



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


6 In the Model Explorer, rename the new diagram Atlas System 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.


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.


3 On the Team Project Set page, click Browse and navigate to the location of your 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 Existing XDE Instance on page 57.


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 and deliver files, they must do a merge to resolve the differences. The following table describes the work you will do in this section:



2 Checks out same file Makes conflicting changeKeeps file checked outQuits XDE


Suppose that two users make a conflicting change when they both change the same 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.


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.



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 click Team > Check In.

d Click OK to complete the check in.

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

3 Checks in file

Delivers files

4 Checks in file

Delivers files, but needs to merge first.





At this point, dev1 and dev2 have both made changes to the same file. The dev2 user 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.

4 In the Model Explorer, right-click (midd_tier_project_1) services model and then click Team > Check In.

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





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.






6 Click Apply.

7 If you are prompted to check out, click OK.






12Scenario: Rational XDE and Base ClearCase With Microsoft VS.NET

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 Microsoft Visual Studio .NET 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.




Prerequisites


■ Microsoft VS.NET 7.1 with Microsoft .NET Framework

■ Rational XDE Developer .NET Edition 2003


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




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.





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.









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

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.

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

ClearCase stores file elements, directory elements, derived objects, and metadata in a repository called a VOB.





3 Click Next.




5 Click Finish.


6 Click OK.



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 > 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:



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.


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: C:\temp\views\vob_admin_view

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.



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

In a typical development environment, you create code models for code-related 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:



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.





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 (CM) purposes at key delivery points into CM.





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 can then update their models and see a consistent and complete set of model elements.

Solution Explorer 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 Solution Explorer, the COV is only enabled if the selected unit is the root model file.



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 > Rational ClearCase > Create View.

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.

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

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.



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.



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



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:

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.




1 As dev2, in the IDE, click the Solution Explorer tab. Under midd_tier_project_1, open services model.mdx.


3 When prompted to check out files, click Check Out.




2 Checks out same file (unreserved)Makes conflicting changeKeeps file checked outQuits XDE

3 Checks in file reserved

4 Checks in file

(Next section) tries to check in, but needs to merge first.


5 Quit XDE: Click File > Exit. Leave services model.mdx checked out.



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



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. Open the solution: Click File > Open Solution and browse to the atlas_project.sln file in your development view (dev1_view).

3 In the Model Explorer, right-click (midd_tier_project_1) services model and then 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





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.





6 Click Apply.

7 If you are prompted to check out, click Check Out.






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

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 Microsoft Visual Studio .NET 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 ucm_admin. There are two developers, whose user IDs are dev1 and dev2.




Prerequisites


■ Microsoft VS.NET 7.1 with Microsoft .NET Framework

■ Rational XDE Developer .NET Edition 2003


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




197

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





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, ucm_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.









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

ClearCase stores file elements, directory elements, derived objects, and metadata in a 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

As the number of files and directories in your system increases, you need a way to reduce the complexity of managing them. Components are the UCM mechanism for simplifying the organization of your files and directories. The elements that you 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

ClearCase stores file elements, directory elements, derived objects, and metadata in a 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.




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 integration stream. The development stream tracks the activities assigned to you and 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.




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:


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:


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:




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.



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

In a typical development environment, you create code models for code-related 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:



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:



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.




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 (CM) purposes at key delivery points into CM.


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.



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 can then update their models and see a consistent and complete set of model elements.

Solution Explorer 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 Solution Explorer, the COV is only enabled if the selected unit is the root model file.



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.




6 In the Where would you like the root of this view? box, specify the development view location (for example: C:\temp\views\dev1_InitialProject) and click Next.

7 In the Where would you like the root of this view? box, specify the integration view 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.


4 When the ClearCase - Select Activity dialog box appears, create a new activity 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.



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.



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.



❑ 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

3 When the ClearCase - Select Activity dialog box appears, create a new activity called dev2 initial changes and select the newly-created activity.




http://localhost/dev2_InitialProject/atlas_gui/gui_project_1

5 Click OK.



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 and deliver files, they must do a merge to resolve the differences. The following table describes the work you will do in this section:

Suppose that two users make a conflicting change when they both change the same element and deliver before a rebase. This generates a merge conflict when the second user starts to deliver.




2 Checks out same file Makes conflicting changeKeeps file checked outQuits XDE

3 Checks in file

Delivers files

4 Checks in file

Delivers files, but needs to merge first.




1 As dev2, in the IDE, click the Solution Explorer tab. Under midd_tier_project_1, open services model.mdx.


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.



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



At this point, dev1 and dev2 have both made changes to the same file. The dev2 user 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).


3 In the Model Explorer, right-click (midd_tier_project_1) services model and then 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





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.





6 Click Apply.

7 If you are prompted to check out, click Check Out.


Index

Aactivities 109, 112artifacts 109auto-advance 74auto-resolve 70, 76

Bbase models 59

designating 60merging with a common ancestor 70merging without a common ancestor 72selecting when fusing 61

baselines 111, 112adding 152, 205composite 122creating 165, 222promotion levels 122recommending 154, 165, 207, 222

branches (ClearCase) 114

Cchange sets 111checking in (ClearCase) 115, 134, 161checking out (ClearCase) 115ClearCase 113

adding baselines 152, 205branches 114checking in 115, 134, 161checking out 115configuring 51creating work areas 151, 204delivering 162, 216elements 113groups 126, 146, 178, 198merging automatically 56merging models 51moving XDE files 45setting up 147, 199version trees 113

viewing a branch 163, 217views 115

Comparative Model Explorer 90Comparative Property Browser 95Comparative Property Explorer 96comparing (XDE models) 140, 172, 193, 228

starting a manual session 59understanding the results 63workflow 55, 58

component-based development 31components

development 107planning communication 36

components (UCM) 112adding 122designing 118read-only 121

composite object versioning 131, 158configuration management 27

activity-based 32configuring for XDE 53working without 39

configuringClearCase 126, 146, 178, 198environment variables 126, 146, 178, 198

conflict icons 66, 94cross-model references

component-relative 106creating 103, 138, 168resolving 143, 174, 196, 231source-relative 104

Ddelivering activities 111, 162, 216development

components 107streams 112

diagram phase (merging) 75difference icons 65, 93Differences Explorer 96

233

Eelements (ClearCase) 113environment variables

configuring 126, 146, 178, 198

Ffusing models 61

Ggeographically distributed development 35GUIDs 63

Iicons

conflict 66, 94difference 65, 93resolution 94

integration streams 111, 112

Jjava

adding classes 133, 160creating modeling projects 129, 155

joining a project 166, 223

Mmerging

automatic 56base models 59ClearCase 51ClearCase versions 114common ancestors 59detecting changes 65diagram phase 74fusing 61guidelines 50, 80identifying conflicts 66identifying differences 65out-of-context 44

ownership policies 48resolving conflicts 80resolving differences 69sample scenario 140, 172, 193, 228semantic phase 74silent 52using a new XDE instance 56

model elementsmoving 54referencing 55

model partitioning 43benefits 44drawbacks 44guidelines 46planning 48

modelscreating XDE 130, 157fusing 61merging 80partitioning 43sharing 40sharing outside source control 108validating 130, 156

Pparallel development 30, 32

controlling change 33controlling releases 35developing multiple releases 32

partitioningmodels 43planning 48

platform models 107profiles 97project (UCM) 112, 148, 200

joining 111, 166, 223project set file

adding to source control 135, 162creating 134, 161importing 139, 170loading into a view 164

project VOB 115creating 148, 200

projectscontrolling change 33creating java modeling 129, 155Rational 111


PVOB. See project VOB.

RRational Unified Process 109rebase (UCM) 111, 154, 208refactoring 142, 174, 195, 230release strategy 119resolution icons 94resolve using 76

Ssemantic phase (merging) 74streams (UCM) 111, 112, 115

synchronizing 153, 206subunits

combining 55planning 47preferences 55referencing 55working with 53

system architecture 118

Ttagged values 98

UUCM 109

changing project policies 153, 206creating a project 148, 200designing components 118joining a project 166, 223

overview of using 110planning components 150, 202project 112project VOB 115rebasing 154, 208recommending baselines 154, 207registering components 152, 205streams 115

Unified Change Management. See UCM.unresolve 76

Vvalidating models 130, 156version trees (ClearCase) 113views (ClearCase) 115

creating 128, 136, 181, 188dynamic 151, 204snapshot 151, 204

VOBs 113creating 128, 150, 180, 203planning 128, 180storing components 120

XXDE

adding packages 137, 168comparing models 140, 172, 193, 228configuring ClearCase 51creating models 130, 157generating code for classes 133, 160merging models 140, 172, 193, 228project set file 134, 161refactoring 142, 174, 195, 230starting 129, 155

Index 235

ibm - rational xde guide to team development for windows

Documents