Loading with Load Rules in Rational Team Concert 4.0 and later

Jazz SCM Team
Last updated: September 13, 2012
Build basis: Rational Team Concert 4.0

The Rational Team Concert (RTC) clients provide flexibility in choosing which items in a repository workspace are to be loaded and where on disk they should be loaded to.  Load rules are a way of describing what is loaded from a repository workspace and where it should be loaded. It could take several steps to load a repository workspace exactly as you would like in the sandbox and to repeat those steps can be error prone for yourself and other team members. However, if the layout information is captured in load rules, they can be easily re-used by other team members when loading their repository workspace into their sandbox. They can also be used in builds.

This article will describe briefly how to generate and use load rules. The main focus is to describe the format of load rules so that you can understand what they will load and how to further customize them. You may want to also read the “Loading Content from a Jazz Source Control Repository in Rational Team Concert 4.0 and later” article to gain more of an understanding on options available for loading into a sandbox.

Table of Contents

Overview

Load rules contain all the information necessary for configuring a load operation. All that needs to be supplied is a context. The context consists of a repository workspace and the sandbox it is to be loaded into.

A load rule is a collection of smaller rules that describe the individual items or folder contents that are to be loaded. The rules also describe where in the sandbox items are to be loaded. There are two types of rules. Item rules and Parent rules.  Item rules identify a specific file/folder/symbolic link that is to be loaded.  Parent rules identify a folder whose children are to be loaded. Parent rules support filters to restrict which children are loaded. Both types of rules allow you to identify where in the sandbox the items are to be loaded.

The load rule is stored in xml format within a file.  Since it is just a regular file, it can checked in and delivered to a stream. This enables it to be shared easily with other team members.  Because the file is in xml format, it can be edited by hand for further customization.

The Eclipse, Visual Studio and Command Line Interface (CLI) clients all provide support for generating load rules and loading a sandbox based upon a load rule.

Terminology

There are a few terms that are used within this document and within the clients.

Workspace

Workspace is an overloaded term when working with the Eclipse client. There is the “Repository Workspace” which is your copy of a Stream. This is the place where your checked in changes go. It is your own private area to back up your changes until you are ready to make them available to others. It is persisted on the server and a copy of it usually loaded into a Sandbox. There is also the “Eclipse Workspace” which describes the area on disk that Eclipse uses to hold projects (code you may be working on).  To summarize, the Eclipse Workspace is a place on disk for files/folders/symbolic links; the Repository Workspace is a place on the RTC server for preserving versions of files/folders/symbolic links. When we use the term “workspace” we try to qualify it so it is clear which one we are speaking about, but we sometimes forget.

Sandbox

A sandbox is the root directory under which contents of a repository workspace will be loaded onto disk. A sandbox contains a set of “shares”. It may also have other contents outside of a share which are not under source control. If you are using the Eclipse Client, the sandbox will default to be the same directory as the Eclipse Workspace. Note this is just the default, you can pick another directory to be your Sandbox. Also with the Eclipse and CLI clients, you can work with more than 1 sandbox at a time if you want.

Share

A share is the top level item (file, folder, symbolic link) in a Repository workspace that has been loaded into a Sandbox. If a share is a folder, its contained children will be under Jazz Source Control. If you are using the Eclipse client, often the folder containing the “.project” file describing an Eclipse project is a share. But a share is independent of the Eclipse Project, it is simply the root item loaded into a Sandbox.

The term share can also be used as a verb (meaning it is a little overloaded). When you initially put a collection of files and folders under Jazz Source control, you use the Share action (which brings up the Share Wizard). The share action is done on the item you want to be a share in your sandbox. We will also use the expression to “share your changes with others” when talking about delivering changes to a stream.

Migrating 3.0.1 and earlier load rules

Prior to the RTC 4.0 release, there was primitive support for load rules. The load rule format was a line oriented name-value pair. It allowed you to specify the item or parent folder to load. It did not provide any support for filters, nor for any sandbox location information. It was also restricted to a single component within a workspace. The load rules were only usable from the command line and builds. If you are currently using that format, it is still supported, but you should consider it deprecated. In some future release, the support for that format will be dropped.

To migrate, you should populate a sandbox using the existing load rule(s). Then with RTC 4.0, generate the load rule(s) for the sandbox. The load rule generated will be in the new xml format.

Creating load rules

Load rules can be generated automatically in each of the Eclipse, Visual Studio and Command Line (CLI) clients. The rule(s) generated is based upon the contents of the sandbox and is independent of the client. That said though, the Eclipse client supports some additional Eclipse project creation options during a load. They are only applicable if the Eclipse client does the load.

The default file extension is “.loadrule” but you can rename it to any extension desired though. The sandbox is examined to determine the shares present and the rule is generated from that. If your sandbox has more than one repository workspace loaded in it, then multiple load rules will be generated. One load rule per repository workspace.

Step by step instructions are in the How to generate and use load rules in the different RTC clients section later. This article’s main focus is understanding what the load rule contains.

Identifying Components, Items and Parent folders

Within the specification of what to load, the rule needs to identify the component that the file/folder/link is being loaded from along with the item or parent folder itself. You have two ways of identifying the component and item/parent folder being loaded. You can identify it via its unique id (itemId) or through its name/path. There are advantages and disadvantages to both approaches.

If you identify a component by name, then the xml is easy to read and accurately reflects what you logically think is being loaded. So if you specified the component name “C1”, when you look at the rule and the context workspace’s definition, you can easily know which component the items are being loaded from. If you decide to add a load specification through manual editing of the load rule, then it is easy to describe which component you want the item to be loaded from. The disadvantage is that if you rename components (i.e. “C1” to “Product Test”), you will need to update all the load rules referencing it by name.

If you identify a component by its itemId, then the component with that id within the context workspace is the one that items will be loaded. The advantage is that if you rename your component, no changes have to be made to the load rule. The disadvantage is that the load rule is not very readable. It is hard to look at the load rule and know what is being loaded. The load rule generated will have comments to help with the readability, but they are comments not the specification.

Similarly the item/parent folder to be loaded can be identified by its unique id or its full repository path. The same advantages/disadvantages apply. With items and parent folders (because it is the full repository path), you need to also take into account that moves as well as renames of parent folders can also invalidate the path. Using the unique id as opposed to the repository path when the relative sandbox path does not include the repository path may be more efficient. In particular, it will be more efficient when using the rule to configure the load where a large number of items are defined by the rule.

When generating a load rule, you have the option to generate the rule using either unique ids or the repository path and component name. Depending on which option you choose, the alternate option is included in the generated load rule as a comment. This is to help with the readability if you choose unique ids. Or if you chose to generate using repository paths/component name, you have the option to edit it to reference the unique id if you want.

Using load rules

A load rule will describe which items are to be loaded from different components. It does not contain though any information about which repository workspace. You identify the repository workspace as the context to the load along with the load rule. The load rule can be within the repository workspace being loaded, or it can be a file somewhere on disk. Some of the load options also allow the load to be further restricted to a specific component.  This is possible even if the load rule itself includes rules for loading items in other components.

Each of the clients have a variety of actions to perform a load. Since this article is focused primarily on the load rule itself we will not go into the actions here.  An overview on how to load using a load rule for your RTC client is covered at the end with the examples.

Rule Elements

The load rule is in xml format. Below is a description of the key elements and their attributes. The examples following will illustrate how the rules will configure the load. The load rule contains item rules (describes an individual item in a component to load) and parent rules (describes contained folders, files, links to load).

The information below is organized by defining the different xml elements that form load rules. For each xml element we identify the attributes and elements that it can contain. Remember, the examples following will show you how to put all the pieces together.

sourceControlLoadRule

The root element within a SCM load rule is: sourceControlLoadRule

This element contains the constraints that affect the overall load operation. In addition it contains elements that describe what is to be loaded.

Attributes

version

The version number of the load rule. Useful if the syntax is later extended. Required current value is “1”.

eclipseProjectOptions

The Eclipse specific options for a load. The acceptable values of this attribute correspond to similar options available in the Load Wizard. This attribute is optional however, and if not supplied, the contents are just loaded normally. Valid values are:

• import Imports top level Eclipse projects found.
• create Creates Eclipse projects for the top level folders loaded.

If you are using the load rule through the Command Line interface or the Visual Studio client, you will not want to specify the eclipseProjectOptions attribute. Also note, that when a load rule is used in a build, the eclipseProjectsOptions is ignored as it does not make sense to create/import Eclipse projects during a build.

Contained Elements

excludeFilter

An excludeFilter is a single filter that applies in general to all of the item (and their contents) being loaded by the rule. The filter is optional and in most cases is not present.

itemLoadRule

An itemLoadRule identifies a single file, folder or symbolic link within a component. The rule also specifies where within the sandbox it should be loaded. The sourceControlLoadRule element may contain 0 or more itemLoadRule entries.

parentLoadRule

A parentLoadRule identifies a folder whose contained items are to be loaded. The folder itself is not loaded. The rule also specifies where within the sandbox the contained items should be loaded. The parentLoadRule element also supports filtering to control which of the immediately contained items should be loaded. The sourceControlLoadRule element may contain 0 or more parentLoadRule entries.

itemLoadRule

The itemLoadRule element describes a single item to be loaded. The item can be a file, folder or symbolic link anywhere within the repository workspace. The item can also be the component (thought of as loading the component root folder). The item being loaded can be placed anywhere within the sandbox (except within other contents loaded from the repository – overlapping shares are not supported).

Typically the itemLoadRule element would be used when a specific set of items are only to be loaded. It is also used when the desire is to load perhaps just a handful of files within a particular folder (sometimes called sparse loading).

If you are loading a number of items below a particular folder (including the component root folder “/”) you may want to consider using the parentLoadRule element instead. That way when new items are added to that folder they will be automatically loaded without needing to update the load rule to identify a new item to be loaded.

Attributes

alternateName

An alternate name that the item is to be loaded with rather than its name in the repository. This works in conjunction with the sandboxRelativePath element (if included). The alternateName attribute is optional except in the case were the component root itself is being loaded (repository path “/”). Then it must be supplied, it can be the name of the component or what ever other name you prefer.

Contained Elements

component

The component element identifies the component the item to be loaded comes from. This is required and there can be just 1 instance of the component element per itemLoadRule.

item

The item element identifies the item to be loaded. This is required and there can be just 1 instance of the item element per itemLoadRule.

sandboxRelativePath

The sandboxRelativePath element provides additional information relating to where in the sandbox the item is to be loaded. It is optional. If not supplied, the item is loaded directly under the sandbox. If sandboxRelativePath is supplied the item will be loaded at the path described under the sandbox. There can be at most 1 instance of the sandboxRelativePath element per itemLoadRule.

component

The component element identifies the component in which the items to be loaded will be found. It is specified as part of the itemLoadRule and parentLoadRule elements.

Attributes

name

The name of the component within the workspace to be loaded. Either name or itemId should be supplied. Not both.

itemId

The unique identifier of the component (UUID). Either name or itemId should be supplied. Not both.

Contained Elements

none

item

The item element identifies a file, folder or link within the workspace’s component that is to be loaded. It is specified as part of the itemLoadRule element.

Attributes

repositoryPath

The path in the repository to the item to be loaded. If you want to specify the component root as the folder, its repository path is “/”. Either repositoryPath or itemId & itemType should be supplied. Not both.

itemId

The unique identifier of the item. Either repositoryPath or itemId & itemType should be supplied. Not both.

itemType

The type of the item to be loaded. The type should be one of the following values: file, folder or link. The itemId attribute must also be supplied to identify the item to be loaded. Either repositoryPath or itemId & itemType should be supplied. Not both.

Contained Elements

none

sandboxRelativePath

By default when files, folders and symbolic links are loaded, they are loaded immediately below the sandbox root folder. There are times when you would like to have the items loaded in unshared folders (folders that are not tracked) within the sandbox. For example you may want to load a single icon file from your repository workspace, but when on disk you would like its path to be the same path as in the repository.

The sandboxRelativePath element allows you to specify a relative path within the sandbox at which to load the items identified by the itemLoadRule or parentLoadRule. You can fully hard code the path you want within sandboxRelativePath or you can choose to have it generated based on some simple heuristics such as include the component name, include the repository path.

Attributes

pathPrefix

A string representing a hard-coded path relative to the start of the sandbox. Optional.

includeComponentName

A Boolean indicating if the component name should make up part of the relative path from the start of the sandbox. If “true”, the component name will be appended to the relative path after the pathPrefix (if supplied). Optional.

includeRepositoryPath

A Boolean indicating if the relative path should include the path in the repository leading up to but not including the elements being loaded. If “true”, the repository path will be appended to the relative path after the pathPrefix and Component name (if supplied/included). In the case of the parentLoadRule element, the repository path is path of the parent folder. In the case of the itemLoadRule element, it is the path of the parent folder containing the item to be loaded. With the itemLoadRule you can also indicate if the item itself should be loaded with an alternative name.

Contained Elements

none

parentLoadRule

There are times where a large number of items to be loaded are all within the same containing (parent) folder. You can specify them all individually, but it becomes tedious and error prone. It also means that every time a new project is added under that root folder, the load rule needs to be updated to include it. Instead, you can define a parentLoadRule which identifies a parent folder whose immediate contents (files, folders, links) are the items to be loaded.

parentLoadRule also allows for the specification of filters that can be used to limit the immediate children that are to be loaded. There is support to both include and exclude children. If both filters are supplied, both filters are applied to the resulting set. For example if the parent folder contained 10 items. The first filter would be applied potentially narrowing the selection to 7 items. The second filter would then be applied to the remaining 7 items further narrowing the selection to for example 5 items which would then be subsequently loaded.

Attributes

none

Contained Elements

component

The component element identifies the component the parent folder is within. This is required and there can be just 1 instance of the component element per parentLoadRule.

parentFolder

The parentFolder element identifies the folder whose children are to be loaded. This is required and there can be just 1 instance of the parentFolder element per parentLoadRule.

include

The include element is a filter that describes which of the items contained in the parent folder should be loaded. It may be further filtered by the exclude element if supplied. It is optional and at most there can be just 1 instance of the include element per parentLoadRule. The include element itself allows for multiple names/patterns to be specified.

exclude

The exclude element is a filter that describes which of the items contained in the parent folder should not be loaded. The remaining items are the ones that should be loaded. The set of items may be further filtered by the include element if supplied. It is optional and at most there can be just 1 instance of the exclude element per parentLoadRule. The exclude element itself allows for multiple names/patterns to be specified.

sandboxRelativePath

Provides additional information relating to where in the sandbox the items are to be loaded. It is optional. If not supplied, the items are loaded directly under the sandbox. If sandboxRelativePath is supplied the items will be loaded at the path described under the sandbox. There can be at most 1 instance of the sandboxRelativePath element per parentLoadRule.

parentFolder

The parentFolder element identifies a folder within the workspace’s component whose immediate children are to be loaded (subject to any include and exclude filters). It is specified as part of the parentLoadRule element.

Attributes

repositoryPath

The path in the repository to the folder whose contained elements are to be loaded. If you want to specify the component root as the folder, its repository path is “/”. Either repositoryPath or itemType & itemId should be supplied. Not both.

itemId

The unique identifier of the item. Either repositoryPath or itemId & itemType should be supplied. Not both.

itemType

The type of the item to be loaded. The type should be a folder. The itemId attribute must also be supplied to identify the item to be loaded. Either repositoryPath or itemType & itemId should be supplied. Not both.

Contained Elements

none

include

The include element is a collection of filter elements to be applied to the names of the items contained within the parent folder to decide whether they are items to be loaded or not. Note the exclude filters are also applied (if specified) so if the include filters identifies an item the exclude filters can still cause it to be excluded from the load. The filter allows for an exact name match or a pattern match on the name.

Attributes

none

Contained Elements

filter

One or more filter elements that describe the items to be included in the load.

exclude

The exclude element is a collection of filter elements to be applied to the names of the items contained within the parent folder to decide whether they should be in the list of items to be loaded or not. Note the include filters are also applied (if specified) so if the include filters does not identify an item to be considered for loading, then it will also be excluded even though not specifically listed in the exclude filters. The filter allows for an exact name match or a pattern match on the name.

Attributes

none

Contained Elements

filter

One or more filter elements that describe the items to be excluded from the load.

filter

The filter element is a filter to be applied to the names of the items contained within the parent folder to decide whether they should be included/excluded from the list of items to be loaded. The filter may be either an exact name match or a pattern match.

Attributes

name

The name to be matched exactly. Only one of name or pattern should be specified.

pattern

A simple pattern to be used for matching. The pattern may contain ‘*’ for 0 and many characters and ‘?’ for exactly one character. Literal ‘*’ and ‘?’ characters must be escaped in the pattern. For example “*” means literal “*”, “?” means literal “?”. Escaping any other character (including the escape character itself), just results in that character in the pattern. For example “a” means “a” and “” means “”

Contained Elements

none

excludeFilter

The load rule can be configured to have files/folders/links excluded from the load based upon their name. The filter is applied to the root items being loaded as well as the items below it. If a sub folder matches the filter then it and none of its contents will be loaded.

The excludeFilter can contain 1 or more name filters. The excludeFilter is optional, but if supplied, there can be just one within the sourceControlLoadRule. If you need to have different filters for different projects being loaded you will need to have multiple load rules.

Attributes

none

Contained Elements

filter

One or more filter elements can be supplied to describe the filtering to be applied. The filter element is further restricted to only support the name attribute.

Examples

We have covered the syntax of the load rule, but the interesting part is to see how the different types of elements work together to allow for flexible loading.  When a load rule is generated, it will attempt to pick the most logical sub-rules. But you know more about what your load strategy is and may want to further adjust the rules generated. The examples that follow are intended to help you understand and further customize the rules you generated.

To help with the examples, consider the rules being used to load a repository workspace containing 3 components (SCM Component, FileSystem Component and Test Component). Each of these components contain a structure of folders, files and links as shown below.  Some of the components contain “.project” files (Eclipse Project), this is just to help illustrate the use of the eclipseProjectOptions. Load rules are not restricted to Eclipse Projects.

SCM Component

/scmServer/  /scmServer/src/  /scmServer/src/...    /scmCommon/  /scmCommon/src/  /scmCommon/src/...    /scmClient/  /scmClient/src/  /scmClient/src/...    /experimental/  /experimental/scmIntegration/  /experimental/scmExport/  /experimental/scmImport/...  

FileSystem Component

/filesystem/  /filesystem/Daemon/  /filesystem/Daemon/.project  /filesystem/Daemon/src/  /filesystem/Daemon/src/...    /filesystem/Core/  /filesystem/Core/.project  /filesystem/Core/src/  /filesystem/Core/src/plugin.java  /filesystem/Core/icons/  /filesystem/Core/icons/etool16/  /filesystem/Core/icons/etool16/file.gif  /filesystem/Core/icons/etool16/folder.gif  /filesystem/Core/icons/etool16/link.gif  

Test Component

/TestProject/  /TestProject/.project  /TestProject/src/  /TestProject/src/test.dat  /TestProject/src/sample.dat  /TestProject/artifacts/  /TestProject/artifacts/testRun.result  /TestProject/artifacts/output/
/TestProject/artifacts/output/...
 

Example: Loading the component root & eclipseProjectOptions

A Jazz/RTC component has a root folder that can contain files, folders and symbolic links. The root folder is very similar in concept to the “/” or “c:/” directories on some file systems. The folder has no name or parent. Typically, the component contains a set of folders under the root folder and it is these folders that are loaded as shares in the sandbox. However, it is possible to load the component root as a share as well. When a root folder is loaded, a name for it will need to be given. Typically people will assign it the name of the component, but it can be anything.

In this example the component root for FileSystem Component is loaded. The name it was chosen to be loaded as is “FSRoot”. The eclipseProjectOption specified is to “import” eclipse projects encountered. When used to load the workspace, the sandbox will contain the layout below. The Eclipse workspace will contain projects for “Daemon” and “Core”. Since the component root is loaded, when new folders are shared into the component, the user will get them automatically when the changes to add the new folders are accepted.

<?xml version="1.0" encoding="UTF-8"?>  <scm:sourceControlLoadRule xmlns:scm="http://com.ibm.team.scm"  eclipseProjectOptions="import" version="1">      <itemLoadRule alternateName="FSRoot">          <component name="FileSystem Component"/>          <item repositoryPath="/"/>      </itemLoadRule>  </scm:sourceControlLoadRule>    

After loading with the example load rule the sandbox would contain:

/FSRoot/  /FSRoot/filesystem/  /FSRoot/filesystem/Daemon/  /FSRoot/filesystem/Daemon/.project  /FSRoot/filesystem/Daemon/src  /FSRoot/filesystem/Daemon/src/...      /FSRoot/filesystem/Core/  /FSRoot/filesystem/Core/.project  /FSRoot/filesystem/Core/src/  /FSRoot/filesystem/Core/src/plugin.java  /FSRoot/filesystem/Core/icons/  /FSRoot/filesystem/Core/icons/etool16/  /FSRoot/filesystem/Core/icons/etool16/file.gif  /FSRoot/filesystem/Core/icons/etool16/folder.gif  /FSRoot/filesystem/Core/icons/etool16/link.gif  

Example: Loading with filters

In this example the SCM Component contains a mix of actively used folders as well as some experimental ones. We want to load the actively used folders but not the experimental ones. We could specify to load each individual item (scmServer, scmCommon, scmClient). However if a new folder “scmModel” was delivered and it should now be loaded as well, we would need to update the load rule. Instead if we use a parentLoadRule, we can specify all the items under it should be loaded except those with the name “experimental”. Then when new “scmModel” project is added, the load rule doesn’t need to be updated. Notice no Eclipse options are specified. This makes the rule suitable for use with the Visual Studio client, the Command Line Interface or when other tools than Eclipse are used to modify the code.

<?xml version="1.0" encoding="UTF-8"?>  <scm:sourceControlLoadRule xmlns:scm="http://com.ibm.team.scm" version="1">      <parentLoadRule>          <component name="SCM Component"/>          <parentFolder repositoryPath="/"/>          <exclude>              <filter name="experimental"/>          </exclude>      </parentLoadRule>  </scm:sourceControlLoadRule>  

After loading with the example load rule the sandbox would contain:

/scmServer/  /scmServer/src/  /scmServer/src/...    /scmCommon/  /scmCommon/src/  /scmCommon/src/...    /scmClient/  /scmClient/src/  /scmClient/src/...

If we know that there might be the addition of other folders with “experimental” in the name, we might want to use a pattern instead.

<?xml version="1.0" encoding="UTF-8"?>  <scm:sourceControlLoadRule xmlns:scm="http://com.ibm.team.scm" version="1">      <parentLoadRule>          <component name="SCM Component"/>          <parentFolder repositoryPath="/"/>          <exclude>              <filter pattern="*experimental*"/>          </exclude>      </parentLoadRule>  </scm:sourceControlLoadRule>  

As an example (a bit contrived) of using a combination of both include and exclude folders, suppose we wanted to load all folders starting with “scm” but not the “scmServer” one. We would combine an include element with an exclude element. The include says everything starting with “scm” (scmServer, scmCommon, scmClient all qualify). The exclude says not scmServer (result is scmCommon, scmClient). It doesn’t matter which order the filters are specified since they operate on the resulting set.  If exclude was applied first (scmCommon, scmClient, experimental all qualify), the include further filters to include only those items starting with “scm” (result is scmCommon, scmClient).

<?xml version="1.0" encoding="UTF-8"?>  <scm:sourceControlLoadRule xmlns:scm="http://com.ibm.team.scm" version="1">      <parentLoadRule>          <component name="SCM Component"/>          <parentFolder repositoryPath="/"/>          <include>              <filter pattern="scm*"/>          </include>          <exclude>              <filter name="scmServer"/>          </exclude>      </parentLoadRule>  </scm:sourceControlLoadRule>  

After loading with this sample load rule, the sandbox would contain

/scmCommon/  /scmCommon/src/  /scmCommon/src/...    /scmClient/  /scmClient/src/  /scmClient/src/...

Example: Loading from multiple components

In this example, the intention is to show that item rules can be combined with parent rules and the rules can all be for different components. This load rule consists of three sub rules; two parentLoadRule and an itemLoadRule. The first rule is the rule from the Loading with filters example. The second rule describes a folder from the FileSystem Component whose contained items are to be loaded. The folder is identified by its repository path.  The “filesystem” folder itself will not be loaded, just all its children. The third rule identifies a single item to be loaded from the Test Component. The item is identified by its repository path. While the example only shows 1 rule per component being loaded, this is not a restriction (its just how the example ended up). You can have several rules describing different parts of the component to load. If the workspace being loaded had other components than the 3 in our example, they would not be loaded because there are no rules for them.

<?xml version="1.0" encoding="UTF-8"?>  <scm:sourceControlLoadRule xmlns:scm="http://com.ibm.team.scm" eclipseProjectOptions="import" version="1">      <parentLoadRule>          <component name="SCM Component"/>          <parentFolder repositoryPath="/"/>          <exclude>              <filter name="experimental"/>          </exclude>      </parentLoadRule>      <parentLoadRule>          <component name="FileSystem Component"/>          <parentFolder repositoryPath="/filesystem"/>      </parentLoadRule>      <itemLoadRule>          <component name="Test Component"/>          <item repositoryPath="/TestProject"/>      </itemLoadRule>  </scm:sourceControlLoadRule>  

After loading with the example load rule the sandbox would contain:

/scmServer/  /scmServer/src/  /scmServer/src/...    /scmCommon/  /scmCommon/src/  /scmCommon/src/...    /scmClient/  /scmClient/src/  /scmClient/src/...    /Daemon/  /Daemon/.project  /Daemon/src/  /Daemon/src/...    /Core/  /Core/.project  /Core/src/  /Core/src/plugin.java  /Core/icons/  /Core/icons/etool16/  /Core/icons/etool16/file.gif  /Core/icons/etool16/folder.gif  /Core/icons/etool16/link.gif    /TestProject/  /TestProject/.project  /TestProject/src/  /TestProject/src/test.dat  /TestProject/src/sample.dat  /TestProject/artifacts/  /TestProject/artifacts/testRun.result  /TestProject/artifacts/output/  /TestProject/artifacts/output/...    

Example: Loading from multiple components – Generated load rule

In the examples provided, we have removed comments from the load rules shown so that they are easy to read in this article. We also chose to use component names and repository paths to assist in readability. This is the load rule from the previous example that would be generated with the default setting for using UUIDs to identify items. It will provide the same output as in the previous example. If the filesystem folder is later renamed, or the TestProject is moved under a new “GreenThreads” folder the load rule would not need to be modified. The comments though would be incorrect.

<?xml version="1.0" encoding="UTF-8"?>  <!--Generated: 2011-09-07 08.50.49-->  <scm:sourceControlLoadRule xmlns:scm="http://com.ibm.team.scm" eclipseProjectOptions="import" version="1">      <parentLoadRule>          <component itemId="_7QmhcNlPEeCZ0q3kWdVOKA"/>          <!-- <component name="SCM Component" /> -->          <parentFolder itemId="_7YDNQNlPEeCZ0q3kWdVOKA" itemType="folder"/>          <!-- <parentFolder repositoryPath="/" /> -->          <exclude>              <filter name="experimental"/>          </exclude>      </parentLoadRule>      <parentLoadRule>          <component itemId="_966yoNlPEeCZ0q3kWdVOKA"/>          <!-- <component name="FileSystem Component" /> -->          <parentFolder itemId="_-9OkMNlPEeCrebrZZNFIcQ" itemType="folder"/>          <!-- <parentFolder repositoryPath="/filesystem" /> -->      </parentLoadRule>      <itemLoadRule>          <component itemId="_-D3TTdlPEeCZ0q3kWdVOKA"/>          <!-- <component name="Test Component" /> -->          <item itemId="_-D3TUdlPEeCZ0q3kWdVOKA" itemType="folder"/>          <!-- <item repositoryPath="/TestProject" /> -->      </itemLoadRule>  </scm:sourceControlLoadRule>

The contents within the sandbox would be the same as in the previous example.

Example: Loading part of an Eclipse project using sandboxRelativePath

In this example we want to load into Eclipse “Core” project from the FileSystem Component. But we don’t want to load the whole project, just the “folder.gif” file. We would like the layout on disk to match exactly what the repository layout is. We need rules to load the Eclipse “metadata” files related to the project and its natures. Different projects have different files that control the behaviour of the project, in this example only the “.project” file is needed, but you can see us needing plugin.properties, .manifest, etc. files with other types of projects. We also need a rule for the single file to be loaded sparsely. The eclipseProjectOptions is to import so that the project will be created during the load. The sandboxRelativePath element directs where in the sandbox the item should be loaded. In this example, the relative path is to be that of the item in the repository. We could also have specified to include the component name, or supplied a custom path.

The result is a sparsely loaded project. Note though that the etools16 folder is not tracked as loaded, so this is only useful if we just want to update the “folder.gif” file. If we want to add/remove items in the etools16 folder we would choose load just that folder as opposed to the single file.

<?xml version="1.0" encoding="UTF-8"?>  <scm:sourceControlLoadRule xmlns:scm="http://com.ibm.team.scm" eclipseProjectOptions="import" version="1">      <itemLoadRule>          <component name="FileSystem Component"/>          <item repositoryPath="/filesystem/Core/.project"/>          <sandboxRelativePath includeRepositoryPath="true"/>      </itemLoadRule>      <itemLoadRule>          <component name="FileSystem Component"/>          <item repositoryPath="/filesystem/Core/icons/etool16/folder.gif"/>          <sandboxRelativePath includeRepositoryPath="true"/>      </itemLoadRule>  </scm:sourceControlLoadRule>  

After loading with the example load rule the sandbox would contain:

/filesystem/Core/  /filesystem/Core/.project  /filesystem/Core/icons/  /filesystem/Core/icons/etool16/  /filesystem/Core/icons/etool16/folder.gif

Example: Loading into a specific folder structure

Suppose we have a repository workspace containing components C1, C2, C3 and C4. These components have folders below them that are to be loaded into a specific directory structure.  The source may have been organized into the components like this as a way of managing access to them or reusing them. The repository workspace looks like:

Now we want to load the folders into a particular folder structure in order to build it. The desired structure is as below.

Robotics
├── bionic  (from component C1)
│
├── schematics (from component C2)
│
├── packages
│   ├── apps  
│   │   ├── Bluetooth  (from component C3)
│   │   ├── Browser  (from component C4)
│   │   ├── Calculator  (from component C4)
│   │   ├── EmergencyInterrupt (from component C3)

We could use the load wizards to load it manually first and then generate the load rule. The load rule generated would be similar to the one below (names were used and comments removed simply to help with readability in this article). This example uses the sandboxRelativePath element showing how the relative path can be used to define where folders are to be loaded within the sandbox. While all the rules involved within the load rule are all parent rules in this case, we could also use filters and item load rules if our layout was more complicated.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<scm:sourceControlLoadRule version="1" xmlns:scm="http://com.ibm.team.scm">
    <parentLoadRule>
        <component name="C3"/>
        <parentFolder repositoryPath="/external/packages/apps"/>
        <sandboxRelativePath pathPrefix="/Robotics/packages/apps"/>
    </parentLoadRule>
    <parentLoadRule>
        <component name="C1"/>
        <parentFolder repositoryPath="/external"/>
        <sandboxRelativePath pathPrefix="/Robotics"/>
    </parentLoadRule>
    <parentLoadRule>
        <component name="C4"/>
        <parentFolder repositoryPath="/external/packages/apps"/>
        <sandboxRelativePath pathPrefix="/Robotics/packages/apps"/>
    </parentLoadRule>
    <parentLoadRule>
        <component name="C2"/>
        <parentFolder repositoryPath="/external"/>
        <sandboxRelativePath pathPrefix="/Robotics"/>
    </parentLoadRule>
</scm:sourceControlLoadRule>

How to generate and use load rules

The format of the load rule is standard across all clients. You can use any of the clients to generate the rule and later use the same client or a different one to load using a load rule. Below is an overview of how to generate generate the load rules based on the contents of a sandbox.

How to generate and use load rules with the Eclipse Client

Generating load rules

The first step is to load your workspace into your sandbox based on how it should be setup. You can see the sandboxes that are currently in use by your RTC client on the Team > Jazz Source Control > Sandboxes preference page. Its from the preference page that you can generate a load rule.


Select the sandbox you want to generate the load rule for and then click Generate Load Rules…

In the Generate Load Rule File dialog, you can specify the name of the file(s) where the load rule(s) should be stored and where to save them. Typically only 1 load rule will be generated, but if you have more than 1 repository workspace loaded into your sandbox, you will have more than 1 load rule. If you put it within your sandbox under a share, you can easily check it in later. It is also here where you can specify the Eclipse project creation policy which will become the “eclipseProjectOptions” setting within the load rule. The resource identifiers section is where you decide how to identify the components, items and folders within the load rule. You can choose either by names/paths or their unique ids, the representation not chosen will be a comment within the load rule.

How to generate and use load rules with the Visual Studio Client

Generating load rules

The first step is to load your workspace into a sandbox based on how it should be setup. Visual Studio Client shows a list of recently visited sandboxes under the “Sandboxes” folder in Team Artifacts. Right-click on the current sandbox in the list, and click on Generate Load Rules… in the context menu.

In the Generate Load Rule File dialog, you can specify the name of the file(s) where the load rule(s) should be stored and where to save them.

Loading with load rules

To load with a load rule, start the Load Wizard by selecting the repository workspace or a component within a repository workspace that you want to load. On the first page of the load wizard select the Load from a load rule file option.


After clicking Next, you will be presented with the page shown below. It allows you to specify where the load rule you want to use is. If the load rule is on disk, choose the Local Load Rule File option and enter the path to the file. If the load rule is within the repository workspace, choose the Remote Load Rule File option and click the Browse button to find it within the repository workspace being loaded.

How to generate and use load rules with the Command Line Interface (CLI)

Generating a load rule

If you have a sandbox loaded (it may have been loaded through any of the RTC clients), load rule(s) can be created to describe what is loaded in the sandbox. The load rule can then be re-used by other team members or even yourself to load the sandbox again.

> scm create loadrules -r local -f roboticsLoadrules c:mySandboxRules

This will generate the load rules for the current sandbox and put them in c:mySandboxRules.  The prefix of the load rule will be roboticsLoadrules. The files will have .loadrule qualifier.  Typically only 1 load rule will be generated unless you have multiple workspaces loaded in your sandbox.

If you want to restrict the generation of the load rule to a particular workspace contained in the sandbox, you can use the -w option. If you want to restrict the generation of the load rule to a particular component of the workspace contained in the sandbox, you can use the -C option.

> scm create loadrules -r local -f roboticsLoadrules -w roboticsWorkspace -C C1 c:mySandboxRules

By default when the load rule is are generated, the components, items and parent folders are identified by their unique ids. If you want them to be identified by their names and paths, then the –use-component-name and –use-repository-path options can be used.

> scm create loadrules -r local -f roboticsLoadrules --use-component-name --use-repository-path c:mySandboxRules

At the start of the load rule, there are some generated comments relating to when the load rule was generated and the sandbox that was the basis for the load rule. You can also add your own custom comments to the load rule (for example who generated the load rule, or its purpose, etc.) using the -c [–comment] option.

> scm create loadrules -r local -f roboticsLoadrules -c "Developer setup for Robotics 5.3" c:mySandboxRules

Loading from a load rule

The CLI also supports loading using a load rule as the specification of what to load. To load from a load rule, specify the location of the rule on the file system using the -L option and the repository workspace to load. The following command will load the “Robotics Workspace” based on what the load rule “roboticsLoadrules.loadrule” specifies.

> scm load -r local -L roboticsLoadrules.loadrule "Robotics Workspace"  

You can also restrict the rule to a component within the repository workspace by also supplying the component. The command below will load only the “C1” component of the “Robotics Workspace” based on what the load rule “roboticsLoadrules.loadrule” specifies.

> scm load -r local -L roboticsLoadrules.loadrule "Robotics Workspace" "C1"  

You can also reference a load rule that is in the repository workspace as opposed to in a file on disk using the -R [–remote-rules] option. The reference to the remote rule includes the component that the rule is within as well as the path within the repository workspace to the load rule.

> scm load -r local -R "C1/external/roboticsLoadrules.loadrule" "Robotics Workspace"  

Summary

There is a lot of flexibility in how to load the contents of a repository workspace. You can load the component root, or any item within it. Items can be loaded at the root of the sandbox or within a directory structure which is not under source control within the sandbox. By capturing the details of how to load a repository workspace in a load rule, that setup can be done by other users with their repository workspaces easily. The format of the load rule has been described so that you can understand and further customize it. The load rule format is also standard allowing the Eclipse, Visual Studio and CLI clients to interchangeably generate load rules and load based on them.

Appendix : Load Rule schema

To help understand the current load rule support, the following schema describes the overall format. Additional validation and constraints will be applied as the rule is parsed. It is strongly recommended you follow/consult the earlier sections which provide more guidelines and examples.

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"              xmlns:scm="http://com.ibm.team.scm"              targetNamespace="http://com.ibm.team.scm"              elementFormDefault="unqualified"              attributeFormDefault="unqualified">      <xsd:annotation>      <xsd:documentation xml:lang="en">         Licensed Materials - Property of IBM         (c) Copyright IBM Corporation 2011, 2012. All Rights Reserved.           Note to U.S. Government Users Restricted Rights:  Use,         duplication or disclosure restricted by GSA ADP Schedule          Contract with IBM Corp.      </xsd:documentation>    </xsd:annotation>      <xsd:element name="sourceControlLoadRule" type="scm:SourceControlLoadRuleType"/>      <xsd:complexType name="SourceControlLoadRuleType">      <xsd:sequence>        <xsd:element name="excludeFilter" type="scm:NameFilterType" minOccurs="0" maxOccurs="1"/>        <xsd:choice minOccurs="1" maxOccurs="unbounded">          <xsd:element name="parentLoadRule" type="scm:ParentLoadRuleType" maxOccurs="unbounded"/>          <xsd:element name="itemLoadRule" type="scm:ItemLoadRuleType" maxOccurs="unbounded"/>        </xsd:choice>      </xsd:sequence>      <xsd:attribute name="version" type="xsd:int" use="required"/>      <xsd:attribute name="eclipseProjectOptions" type="scm:EclipseProjectOptionsType" />    </xsd:complexType>      <xsd:simpleType name="EclipseProjectOptionsType">      <xsd:restriction base="xsd:string">        <xsd:enumeration value="import"/>        <xsd:enumeration value="create"/>      </xsd:restriction>    </xsd:simpleType>      <xsd:complexType name="ParentLoadRuleType">      <xsd:sequence>        <xsd:element name="component" type="scm:ComponentType" minOccurs="1" maxOccurs="1"/>        <xsd:element name="parentFolder" type="scm:VersionableType" minOccurs="1" maxOccurs="1"/>        <xsd:element name="include" type="scm:FilterType" minOccurs="0" maxOccurs="1"/>        <xsd:element name="exclude" type="scm:FilterType" minOccurs="0" maxOccurs="1"/>        <xsd:element name="sandboxRelativePath" type="scm:SandboxRelativePathType" minOccurs="0" maxOccurs="1"/>      </xsd:sequence>    </xsd:complexType>      <xsd:complexType name="FilterType">      <xsd:sequence>        <xsd:element name="filter" type="scm:FilterNamePatternType" minOccurs="1" maxOccurs="unbounded"/>      </xsd:sequence>    </xsd:complexType>      <xsd:complexType name="FilterNamePatternType">      <xsd:attribute name="name" type="xsd:string"/>      <xsd:attribute name="pattern" type="xsd:string"/>    </xsd:complexType>      <xsd:complexType name="NameFilterType">      <xsd:sequence>        <xsd:element name="filter" type="scm:FilterNameType" minOccurs="1" maxOccurs="unbounded"/>      </xsd:sequence>    </xsd:complexType>      <xsd:complexType name="FilterNameType">      <xsd:attribute name="name" type="xsd:string" use="required"/>    </xsd:complexType>      <xsd:complexType name="ComponentType">      <xsd:attribute name="name" type="xsd:string"/>      <xsd:attribute name="itemId" type="xsd:string"/>    </xsd:complexType>      <xsd:complexType name="VersionableType">      <xsd:attribute name="repositoryPath" type="xsd:string"/>      <xsd:attribute name="itemId" type="xsd:string"/>      <xsd:attribute name="itemType" type="scm:VersionableItemType"/>    </xsd:complexType>        <xsd:simpleType name="VersionableItemType">      <xsd:restriction base="xsd:string">        <xsd:enumeration value="file"/>        <xsd:enumeration value="folder"/>        <xsd:enumeration value="link"/>      </xsd:restriction>    </xsd:simpleType>      <xsd:complexType name="ItemLoadRuleType">      <xsd:sequence>        <xsd:element name="component" type="scm:ComponentType" minOccurs="1" maxOccurs="1"/>        <xsd:element name="item" type="scm:VersionableType" minOccurs="1" maxOccurs="1"/>        <xsd:element name="sandboxRelativePath" type="scm:SandboxRelativePathType" minOccurs="0" maxOccurs="1"/>      </xsd:sequence>      <xsd:attribute name="alternateName" type="xsd:string"/>    </xsd:complexType>      <xsd:complexType name="SandboxRelativePathType">      <xsd:attribute name="pathPrefix" type="xsd:string"/>      <xsd:attribute name="includeComponentName" type="xsd:boolean"/>      <xsd:attribute name="includeRepositoryPath" type="xsd:boolean"/>    </xsd:complexType>    </xsd:schema>

About the authors

The Jazz SCM Team is comprised of the folks who, write and use the wizards and tools for loading repository workspaces.

---

Copyright © 2012 IBM Corporation