Mastership


The following sections describe how mastership applies to objects in databases.

Replica Mastership

When you create a new replica, its replica object (the database object that records the replica’s existence) is mastered by the creating replica. Therefore, you can modify or delete the replica object only at the creating replica, unless you transfer mastership to another replica.

To facilitate replica maintenance, we recommend that each replica be self-mastering, which means that it masters its own replica object. For more information, see Transferring Mastership of a Replica Object.

Note: To perform certain procedures on a replica object, you must make the replica self-mastering. This requirement is noted in the documentation for those procedures.

Branch Mastership

Branch mastership is the scheme that supports independent development work at different VOB replicas. Every branch type defined in a VOB (including the main branch type) has a master replica.

Mastership restrictions allow you to create a branch only if its creation will not conflict with an attempt to create a branch of that type at the replica that masters the type:

Note: Remember that a branch is an instance of a branch type. For example, main is a branch type, and acc.c@@/main and resource.h@@\main are branches.

The branch mastership strategy works with the strategy of using branches to isolate changes for particular development tasks. (For example, fixing a defect may require changes to five elements, in which each change is made on a branch of type v1.0_bugfix.) With Rational ClearCase MultiSite, work on various tasks can be done at different replicas, each using its own branch type. The work on different branches can be propagated among replicas, and then merged, as often as required by an organization’s development strategy. Because the branches of an element are independent, changes made at different replicas do not conflict.

Figure 2 shows a sample version tree. Each replica masters a branch type and developers using that replica can create versions only on the branch of that type. For example, the boston_hub replica masters the main branch type, the sanfran_hub replica masters the v1.0_integration branch type, and the bangalore replica masters the v1.0_bugfix branch type.

Figure 2 Branch Mastership

Branch mastership is implemented at both the branch type level and the branch level:

Creation of the main Branch of an Element

There is an exception to the rule that a branch can be created only at the master replica of the branch type. When you add a file to source control or create a new directory element, the main branch is created even if your current replica does not master the main branch type. By default, the main branch of a new element is mastered by the replica that masters the main branch type, and you cannot create new versions on the branch. During element creation, you can specify an option to have your current replica master all newly created branches. For more information, see Assigning Branch Mastership During Element Creation.

Synchronizing Development on Different Branches

Development of an element with multiple branches can take place in different replicas concurrently, with occasional synchronizations. (The more frequently you update, the easier it is to track and reconcile the changes on different branches of elements. To reconcile changes, you use the ClearCase version-comparison and merge facilities.)

For example, before the Boston site starts using MultiSite, the element cmdsyn.c has two branches, cmdsyn.c@@/main and cmdsyn.c@@/main/v1.0_integration:

When the Boston site starts using MultiSite, the administrator creates a new replica for the San Francisco site. Because integration for Version 1.0 will be done at the San Francisco site, the sanfran_hub replica must master the v1.0_integration branch type. The administrator transfers mastership of the v1.0_integration branch type to the sanfran_hub replica.

Developers in San Francisco can now create versions on existing branches of type v1.0_integration and can create new instances of that branch type. Work continues on the main branch in Boston:

The administrators at the Boston and San Francisco sites decide to merge some of the work on the v1.0_integration branch with the work done on the main branch. The San Francisco administrator sends an update packet to the boston_hub replica, and the Boston administrator imports it:

The Boston administrator then merges from the v1.0_integration branch to the main branch by checking out the latest version on the main branch, merging from the latest version on the v1.0_integration branch, and checking in the result of the merge:

Default and Explicit Branch Mastership

Branches can have default mastership or explicit mastership. When a branch is created, it is mastered by the replica that masters the branch type (default mastership). When you transfer mastership of a branch to another replica, that replica masters the branch explicitly. The output of describe shows which replica masters a branch and whether mastership is explicit or default.

For example, the branch type v2.0_port was created at, and is mastered by, the sanfran_hub replica. The test2.txt@@/main/v2.0_port branch has default mastership, as shown by the (defaulted) annotation:

multitool describe test2.txt@@/main/v2.0_port 
branch “test2.txt@@/main/v2.0_port”
  created 18-Aug-00.10:50:34 by John Cole (jcole.user@goldengate)
  branch type: v2.0_port
  master replica: sanfran_hub@/vobs/dev (defaulted)
...

The administrator at the sanfran_hub replica transfers mastership of this branch to the boston_hub replica:

multitool chmaster –nc boston_hub test2.txt@@/main/v2.0_port 
Changed mastership of branch "/vobs/dev/test2.txt@@/main/v2.0_port" to 
"boston_hub"

The output of describe shows that this branch is now mastered explicitly by the boston_hub replica; the (defaulted) annotation is not present:

multitool describe test2.txt@@/main/v2.0_port 
branch “test2.txt@@/main/v2.0_port”
  created 18-Aug-00.10:50:34 by John Cole (jcole.user@goldengate)
  branch type: v2.0_port
  master replica: boston_hub@/vobs/dev
...

When you transfer mastership of a branch type, mastership is transferred for all branches of that type with default mastership. Mastership of branches with explicit mastership is not transferred.

For more information, see the chmaster reference page and Transferring Mastership of a Branch.

Type Object Mastership

By default, you can create an instance of a type only in the replica that masters the type object. For example, if the sanfran_hub replica masters the TESTED_BY attribute type, you can create a TESTED_BY attribute only in the sanfran_hub replica.

Often, however, developers at different sites must create instances of the same type. For example, quality engineers at the bangalore replica may also need to use the TESTED_BY attribute. Therefore, you can create two kinds of attribute type, hyperlink type, and label type objects: unshared and shared.

Unshared Type Objects

Instances of an unshared type object can be created only in its master replica. (The instances are propagated to and seen in all replicas.) Thus, there are no issues with conflicting changes made in different replicas. By default, attribute types, hyperlink types, and label types are created as unshared. An unshared type object can be converted to shared.

Shared Type Objects

Instances of a shared type object can be created in multiple replicas. To prevent cross-replica conflicts, the following restrictions apply:

Note: If a hyperlink type is shared, you can create a hyperlink of that type between any two objects, at any replica. If the type is global, the restrictions on creation of the local copy apply.

Restrictions that prevent instance creation in an unreplicated VOB also prevent instance creation in a replica; for example, if there is a lock on the type object, instance creation fails. However, because locks are not replicated (except for locks created with –obsolete), a lock on a shared type object in one replica does not prevent instance creation in another replica.

A shared type cannot be converted to unshared. Instance restrictions (for example, once-per-branch use of a label type) for a shared type object cannot be changed.

Additional Restrictions for Shared Global Types

Additional mastership restrictions exist when you use an administrative VOB hierarchy and its global types. If a global type is shared, you can create instances of the type in a replica only if one of the following conditions exists:

These restrictions apply even if your current replica masters the object to which you are attaching the instance. These restrictions prevent conflicting, simultaneous creation of a given type with a given name at multiple sites. For more information about global types, see the Administrator’s Guide for Rational ClearCase.

For more information about changing type mastership, see Managing Mastership.

Creating an Instance of a Type

In summary, you can create an instance of a type in the following cases:

Example

The administrator at the boston_hub replica creates an attribute type with the following command:

cleartool mkattype –shared –vpbranch –nc TESTED 

This attribute type is defined to be shared across replicas, with the restriction that at most one instance can be created on each branch of an element. You can create an attribute of that type on a version if both of the following things are true:

Mastership Restrictions for VOB Objects

Table 2 describes the restrictions for VOB objects.

Table 2 Mastership Restrictions for VOB Objects
Object
Action
Object your current replica must master
Activity
Change (chactivity)
Remove (rmactivity)
Set (setactivity)
Activity
Attribute
Create (mkattr)
Type (if the attribute’s type is unshared)
Object to which attribute is being applied (if the attribute’s type is shared)
Remove (rmattr)
Type (if the attribute’s type is unshared)
Object from which attribute is being removed (if the attribute’s type is shared)
Baseline
Create (mkbl)
Stream where you make the baseline. For an imported baseline created from a pre-UCM label, your current replica must master the component and label type.
Label (mklabel)
Stream’s branch type (in each VOB where you have made changes)
Change (chbl)
Remove (rmbl)
Baseline
Branch
Change type (chtype)
New branch type and the branch you are changing
Create (mkbranch)
Branch type
Remove (rmbranch)
Branch
Checked-out version
Reserve (reserve)
Branch on which the version is checked out
Component
Remove (rmcomp)
Component
Element
Check in (checkin)
Branch on which you are checking in the version
Check out (checkout)
Branch on which you are checking out the version (unless you use –unreserved –nmaster)
Change type (chtype)
Relocate (relocate)
Remove (rmelem)
Element
Event record
Change (chevent)
For a version, the branch containing the version. For any other object, the object.
Folder
Change (chfolder)
Remove (rmfolder)
Folder
Hyperlink
Create (mkhlink)
Hyperlink type (for unshared types)
Remove (rmhlink)
Hyperlink
Label
Create (mklabel)
Remove (rmlabel)
If the label’s type is unshared, your current replica must master the label type. If the label’s type is shared, the following restrictions apply:
  • If the label type is one per branch, your current replica must master the branch containing the version.
  • If the label type is one per element, your current replica must master the version’s element.
Merge arrow
Remove (rmmerge)
Merge hyperlink
Object
Change event (chevent)
Change mastership (chmaster)
Change name (rename)
Lock obsolete (lock –obsolete)
Unlock (unlock)
Object
Change protection (protect)
Object (if current replica preserves identities or permissions)
Project
Change (chproject)
Remove (rmproject)
Project
Project VOB
Change list of promotion levels (setplevel)
PromotionLevel attribute type
Replica
Change host (chreplica)
Change preservation properties (chreplica)
Enable requests for mastership (reqmaster)
Remove (rmreplica)
Replica
Stream
Change (chstream)
Rebase (rebase)
Remove (rmstream)
Stream
Symbolic link
Remove (rmelem)
Symbolic link
Type
Copy (cptype)
The replica containing the original type must master that type.
Remove (rmtype)
Replace (mkobjecttype –replace)
Type
Version
Check in (checkin)
Check out (checkout)
Remove (rmver)
Branch
With checkout –unreserved –nmaster, there are no mastership restrictions.
VOB
Change feature level (chflevel)
The replica to be changed must be self-mastering.
Set up snapshots (vob_snapshot_setup)
The replica must be self-mastering.
VOB family
Change feature level (chflevel)
VOB object