From Eclipsepedia

< To: Buckminster Project

In order to increase navigability of the specification it is suggested that the reader enables "Auto-number headings" in his Wiki account Preferences > Misc

Contents 1 Introduction 1.1 Background 1.2 Prefixes and Namespaces used in this document 1.3 BNF pseudo-schemas 1.4 Document structure 2 Language components 3 RMAP (Resource Map) 3.1 RMAP pseudo-schema 3.2 Rmap component 3.2.1 SearchPath component 3.2.1.1 Provider component 3.2.1.1.1 Provider Matcher component 3.2.1.1.1.1 Provider Match component 3.2.1.1.1.2 Provider Group component 3.2.1.1.1.3 =Provider Group Name component= 3.2.1.1.1.4 =Provider Version Name component= 3.2.1.1.1.5 =Provider Group Timestamp component= 3.2.1.1.1.6 =Provider Group Revision component= 3.2.1.1.1.7 =Provider Group Os component= 3.2.1.1.1.8 =Provider Group Ws component= 3.2.1.1.1.9 =Provider Group Arch component= 3.2.1.1.1.10 =Provider Group Nl component= 3.2.1.1.2 Uri component 3.2.1.1.3 Provider Digest component 3.2.1.1.4 VersionConverter component 3.2.1.1.4.1 Transform component 3.2.2 Locator component 3.2.3 Redirect component 3.3 RMAP sample 4 CQUERY (Component Query) 4.1 CQUERY pseudo-schema 4.2 ComponentQuery component 4.2.1 RootRequest component 4.2.2 AdvisorNode component 5 CSPEC (Component Specification) 5.1 CSPEC pseudo-schema 5.2 Cspec component 5.2.1 Dependencies component 5.2.1.1 Dependency component 5.2.1.1.1 ObtainedFrom component 5.2.2 Generators component 5.2.2.1 Generator component 5.2.3 Artifacts component 5.2.3.1 Public/Private Artifacts 5.2.3.1.1 Artifacts InstallerHints component 5.2.3.1.2 Artifacts Path component 5.2.4 Groups component 5.2.4.1 Public/Private Groups 5.2.4.1.1 Groups InstallerHints component 5.2.4.1.2 Groups Attribute component 5.2.5 Actions component 5.2.5.1 Public/Private Actions 5.2.5.1.1 Actions InstallerHints component 5.2.5.1.2 ActorProperties component 5.2.5.1.3 Actions Properties component 5.2.5.1.4 Prerequisites component 5.2.5.1.4.1 Prerequisites InstallerHints component 5.2.5.1.4.2 Prerequisites Attribute component 5.2.5.1.5 Products component 5.2.5.1.6 Products Path component 5.2.5.1.6.1 Products Public/Private 5.2.5.1.6.2 =Products Public/Private InstallerHints component= 5.2.5.1.6.3 =Products Public/Private Path component= 6 CSPECX (CSPEC Extension) 6.1 CSPECX pseudo-schema 6.2 CspecExtension component 6.2.1 AlterDependencies component 6.2.1.1 Remove component 6.2.2 AlterArtifacts component 6.2.2.1 Public/Private AlterArtifacts 6.2.2.1.1 AlterArtifacts AlterInstallerHints component 6.2.2.1.1.1 Remove component 6.2.2.1.2 RemovePath component 6.2.2.2 Remove component 6.2.3 AlterGroups component 6.2.3.1 Public/Private AlterGroups 6.2.3.1.1 AlterGroups AlterInstallerHints component 6.2.3.1.1.1 Remove component 6.2.3.1.2 AlterGroups AlterAttribute component 6.2.3.1.3 Remove component 6.2.3.2 Remove component 6.2.4 AlterActions component 6.2.4.1 Public/Private AlterActions 6.2.4.1.1 AlterActions AlterInstallerHints component 6.2.4.1.1.1 Remove component 6.2.4.1.2 AlterActorProperties component 6.2.4.1.2.1 Remove component 6.2.4.1.3 AlterActions AlterProperties component 6.2.4.1.3.1 Remove component 6.2.4.1.4 AlterPrerequisites component 6.2.4.1.4.1 AlterPrerequisites AlterInstallerHints component 6.2.4.1.4.2 =Remove component= 6.2.4.1.4.3 AlterPrerequisites AlterAttribute component 6.2.4.1.4.4 Remove component 6.2.4.1.4.5 AlterProducts component 6.2.4.1.4.6 =AlterProducts Public/Private= 6.2.4.1.4.7 ==AlterProducts Public/Private AlterInstallerHints component== 6.2.4.1.4.8 ===Remove component=== 6.2.4.1.4.9 ==AlterProducts Public/Private RemovePath component== 6.2.4.1.4.10 =RemoveProduct component= 6.2.4.1.4.11 =RemovePath component= 6.2.4.2 Remove component 7 BOM (Bill of Materials) 8 MSPEC (Materialization Specification) 8.1 MSPEC pseudo-schema 8.2 Mspec component 8.2.1 MspecNode component 8.2.1.1 Unpack component 9 Shared Language Concepts 9.1 Property Framework 9.1.1 Property component 9.1.2 PropertyElement component 9.1.2.1 Constant component 9.1.2.2 Format component 9.1.2.2.1 Split component 9.1.2.3 PropertyRef component 9.1.2.4 Replace component 9.1.2.4.1 Match component 9.1.2.5 ToLower component 9.1.2.6 ToUpper component

Introduction

This document describes the conceptual model of the Buckminster 1.0 component meta-data language. The document is not a formal specification although it uses some of the terminology and structure required for W3C-style specifications.

This document is intended as a complete reference for those working with the various Buckminster artifacts at the XML representation level as well as contributors and consumers of Buckminster. A compressed description of the Buckminster 1.0 component meta-data language can be found in the primer. It focuses on the required or most used language artifacts and provides plenty of examples.

Background

Buckminster is a component resolution & materialization framework. Its purpose is to get software components for you and materialize them in a context of choice, typically a workspace or file system. This applies whether you are looking at what's available on your local machine, within your development organization or in the public open source cloud. Buckminster is an extensible meta-framework, comprising a component metadata language and a runtime.

The Buckminster component meta-data language allows the Buckminster framework to understand information expressed about components, their dependencies and their associated lifecycle actions. The language also allows users to express component queries and describe reusable component assemblies ready to be consumed via Buckminster.

Prefixes and Namespaces used in this document

The following namespaces and prefixes are used throughout the document. The same combinations will be used in the associated schemas as well unless specified otherwise.

Prefix	Namespace	Source	Schema
xs	http://www.w3.org/2001/XMLSchema	Defined in the W3C XML Schema specification (Part 1 & 2)	-
com	http://www.eclipse.org/buckminster/Common-1.0	Defined in the Buckminster meta-data language	common-1.0.xsd
rm	http://www.eclipse.org/buckminster/RMap-1.0	Defined in the Buckminster meta-data language	rmap-1.0.xsd
cq	http://www.eclipse.org/buckminster/CQuery-1.0	Defined in the Buckminster meta-data language	cquery-1.0.xsd
cs	http://www.eclipse.org/buckminster/CSpec-1.0	Defined in the Buckminster meta-data language	cspec-1.0.xsd
md	http://www.eclipse.org/buckminster/MetaData-1.0	Defined in the Buckminster meta-data language	metadata-1.0.xsd
mpv	http://www.eclipse.org/buckminster/MavenProvider-1.0	Defined in the Buckminster meta-data language	maven-provider-1.0.xsd

BNF pseudo-schemas

Pseudo-schemas are used throughout the document to provide a compressed view of the elements and attributes for each language element. The pseudo-schemas use BNF-style conventions for attributes and elements:

• "?" denotes optionality (i.e. zero or one occurrences)
• "*" denotes zero or more occurrences
• "+" one or more occurrences
• "[" and "]" are used to form groups
• "|" represents a choice

Attributes are assigned a value which corresponds to their type which may be either based on the XML Schema data types or the Buckminster language. Prefixes indicate which applies. Elements with simple content are conventionally assigned a value which corresponds to the type of their content, as defined in the associated schema. In order to increase readability required attributes and elements are highlighted in bold.

<defined_element
      required_attribute_of_type_string="xs:string"
      optional_attribute_of_type_int="xs:int"? >
  <required_element />
  <optional_element />?
  <one_or_more_of_these_elements />+
  [ <choice_1 /> | <choice_2 /> ]*
</defined_element>

The Buckminster component meta-data language has six parts each conforming to a specific Buckminster artifact type. Each language part or artifact type has a namespace associated with it which is mapped to a distinct schema (see Prefixes and Namespaces used in this document). This document assumes that pseudo-schemas given for a particular part will use their associated namespace as a default namespace (i.e. http://www.eclipse.org/buckminster/RMap-1.0 for RMAP). Elements declared in other namespaces and shared across the six language parts will be indicated using the namespace prefixes as listed above.

Note that attributes will never be prefixed as all Buckminster schemas declare the attributeFormDefault to be unqualified. Consult the W3C XML Schema recommendation for details on this (XML Schema Part 1).

Document structure

The main section of the document describes the six Buckminster artifact types which correspond to the six parts of the language. Each of those parts is addressed in a main section. Each of the main sections provides an XML instance example for each Buckminster artifact.

The document explains the conceptual model of Buckminster and refers to components of the Buckminster language each of which is mapped to an XML element information item. Complete BNF pseudo-schemas are given at the start of each part to illustrate those.

The individual element descriptions provide pseudo-schemas to a depth of one only. Each of those subsections provides an explanation of the component (or element) semantics as well as a table view of the attributes with explanations of the semantics of those attribute in the context of the Buckminster framework. More detailed descriptions are provided where necessary.

Language components

The Buckminster meta-data language 1.0 has six main components or artifact types. These artifacts are typically represented in distinct files which use the identifiers (i.e. RMAP, CQUERY) of the artifact types as file extensions. The Buckminster runtime enforces this convention with all file extensions expected to be lower case.

The modular structure of the language guarantees exchange and re-use of artifacts in different application scenarios and allows the development of targeted tools such as Buckminster editors and wizards.

RMAP (Resource Map)

A resource map is used when resolving a request for a component through Buckminster Component Query. It supports federated, parameterized and search-path based resolution of materializable components. A CQUERY appoints a URL identifying an RMAP for the resolution process. The resolution is federated because resolution can be delegated to another RMAP. It is parameterized as properties can be used as parameters in the search paths (e.g. like $HOME, $CLOSEST_MIRROR).

RMAP pseudo-schema

The following pseudo-schema provides an overview of the XML vocabulary used to describe a resource map. It is fully expanded with the exception of those components that are part of the Buckminster property model shared across all Buckminster artifacts. An XML style comment indicates where element syntax with regard to child elements is not fully expanded.

NOTE that the pseudo-schema is navigable. Each element links to the document section explaining the structure and semantics of the element.

<rmap>
   <documentation/> ?
   [ 
     <property
           key="com:propertyKey"
           value="xs:string" 
           mutable="xs:boolean" ? />
    |
     <propertyElement>
        <!-- TO BE EXPANDED ... SEE BUCKMINSTER PROPERTY SECTION-->
     </propertyElement>
    |
     <searchPath
           name="xs:string" >
        <provider
                 readerType="xs:string" 
                 componentTypes="xs:string"
                 componentType="xs:string" <!-- DEPRECATED -->
                 managedCategories="xs:string" ? <!-- DEPRECATED -->
                 mutable="xs:boolean" ?
                 source="xs:boolean" ? >
           <documentation/> ?
           <matcher
                 base="xs:string>
              [ 
                <match
                      name="xs:string"
                      optional="xs:boolean"
                      pattern="xs:string"
                      prefix="xs:string"
                      suffix="xs:string" /> 
               |
                <group
                      name="xs:string"
                      optional="xs:boolean">
                   [
                     <name
                           name="xs:string"
                           optional="xs:boolean"
                           pattern="xs:string"
                           prefix="xs:string"
                           suffix="xs:string" /> 
                    |
                     <version
                           name="xs:string"
                           optional="xs:boolean"
                           pattern="xs:string"
                           prefix="xs:string"
                           suffix="xs:string" /> 
                    |
                     <timestamp
                           name="xs:string"
                           optional="xs:boolean"
                           pattern="xs:string"
                           prefix="xs:string"
                           suffix="xs:string" /> 
                    |
                     <revision
                           name="xs:string"
                           optional="xs:boolean"
                           pattern="xs:string"
                           prefix="xs:string"
                           suffix="xs:string" /> 
                    |
                     <os
                           name="xs:string"
                           optional="xs:boolean"
                           pattern="xs:string"
                           prefix="xs:string"
                           suffix="xs:string" /> 
                    |
                     <ws
                           name="xs:string"
                           optional="xs:boolean"
                           pattern="xs:string"
                           prefix="xs:string"
                           suffix="xs:string" /> 
                    |
                     <arch
                           name="xs:string"
                           optional="xs:boolean"
                           pattern="xs:string"
                           prefix="xs:string"
                           suffix="xs:string" /> 
                    |
                     <nl
                           name="xs:string"
                           optional="xs:boolean"
                           pattern="xs:string"
                           prefix="xs:string"
                           suffix="xs:string" />
                    |
                     <match
                           name="xs:string"
                           optional="xs:boolean"
                           pattern="xs:string"
                           prefix="xs:string"
                           suffix="xs:string" />  
                   ]*                       
                </group>
              ]+
           </matcher>
           <uri>
              <!-- TO BE EXPANDED ... SEE BUCKMINSTER PROPERTY SECTION-->
           </uri>
           <digest
                 algorithm="xs:string" />
           <versionConverter
                 type="xs:string" >
              <transform
                    toPattern="xs:string"
                    toReplacement="xs:string"
                    fromPattern="xs:string"
                    fromReplacement="xs:string" > *
           </versionConverter> ?
        </provider> +
     </searchPath>
    |
     <locator
           pattern="xs:string" 
           searchPathRef="xs:string" />
    |
     <redirect
           pattern="xs:string" 
           href="com:URL" />
   ]*
</rmap>

Navigate through the following sections if a non-expanded view of individual components is required.

Rmap component

The Rmap component is represented by an rmap XML element information item which serves as the root element of a resource map artifact (that is a ".rmap" file). It is a container for optional SearchPath, Locator, Redirect, Property and PropertyElement components which are represented with correspondingly named XML element information items. The non-expanded pseudo-schema shows the element information items directly contained by rmap.

 <rmap>
   <documentation/> ?
   [ <property/> | <propertyElement/> | <searchPath/> | <locator/> | <redirect/> ]*
 </rmap>

The documentation element may contain mixed content and should be used to provide contextual documentation of the RMAP and its contained elements. This applies whereever the documentation element is shown in the Buckminster specification.

SearchPath component

A SearchPath provides a reusable pointer to an area that Buckminster will use during the component resolution and materialization process. A complete SearchPath definition expresses where to find things, how to read and interpret its location and content and how to get access to those.

The RMAP can contain any number of named SearchPaths. The defined SearchPaths are unrelated data items. Thus, the order in which they appear carries no implicit information and has no influence on how Buckminster interpretes them.

A SearchPath MUST CONTAIN one or more Providers. Buckminster consults those in the order in which they appear until the component resolution process succeeds with one of them. Buckminster WILL flag up an error when a component can not be found based on the information provided by a searchPath. NOTE that their may be multiple matching Providers for a particular component. In this case Buckminster will internally assign a "Provider score" which ranks those providers depending on how well they fit a set of component constraints that are embodied in AdvisorNodes defined for the ComponentQuery that Buckminster resolves. Two properties specifically contribute to this score: mutable and source. The preferences regarding those properties may be stated in an AdvisorNode and will contribute to the score and the resulting Provider ranking. Only if all Provider in a set are equally ranked, the order of appearance decides which will be picked: the first matching one.

The SearchPath component is represented by a searchPath XML element information item. It is a container for required Provider components which are represented with correspondingly named XML element information items. The non-expanded pseudo-schema shows the element information items directly contained by searchPath.

<rmap>
   <searchPath
           name="xs:string" >
      <provider/> +
      <documentation/> ?
   </searchPath>
</rmap>

The searchPath element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):

Attribute	Type	Values	Semantics
name	xs:string	-	The name of the searchPath MUST BE unique within the set of all searchPaths defined in an RMAP. The Buckminster resolution process MUST FAIL if duplicate names are used for searchPath in the same RMAP.

Provider component

A Provider declares all information required to obtain a component of a specific type, from a specific location using a specific versioning scheme. The information declared by a Provider allows the Buckminster framework to dynamically instantiate and configure a component reader (enumerating and reading the content) for a particular component type (obtaining and translating dependency information) and a version converter that maps Buckminsters notion of a "version" (i.e. as expressed in a component query) to the corresponding "version selector" of the provider (such as branch name, change-number, timestamp, etc).

The Provider component is represented by a provider XML element information item. It is a container for a required Uri and an optional VersionConverter components which are represented with correspondingly named XML element information items. The non-expanded pseudo-schema shows the element information items directly contained by provider.

<rmap>
   <searchPath>
        <provider
                 readerType="xs:string" 
                 componentTypes="xs:string"
                 componentType="xs:string" <!-- DEPRECATED -->
                 managedCategories="xs:string" ? <!-- DEPRECATED -->
                 mutable="xs:boolean" ?
                 source="xs:boolean" ? >
           <documentation/> ?
           <matcher/> ?
           <uri/>
           <digest/> ?
           <versionConverter/> ?
        </provider> +
     </searchPath>
</rmap>

The provider element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):

Attribute	Type	Values	Semantics
readerType	xs:string	-	The readerType specifies the component reader that Buckminster should associate with this provider. The value of this attribute must specify the fully qualified name of a reader. The Buckminster framework provides reference implementations for the following reader types (details of the existing reader implementations can be found in Buckminster Component Readers). The attribute value that MUST BE used to reference those readers is highlighted in bold: cvs - a reader capable of navigating and reading CVS repositories. svn - a reader capable of navigating and reading Subversion repositories. The SVN repository reader assumes that any repository contains the three recommended directories trunk, tags and branches. maven - a reader capable of navigating and reading Maven repositories. It is based on the url.catalog reader. Maven 2 features are not fully supported yet. p4 - a reader capable of navigating and reading Perforce repositories. site.feature - an update site reader or all locations that provided feature.xml, plugin.xml and/or site.xml files. eclipse.platform - a reader to obtain information from the target platform (most commonly your installed features and plugins). This reader will not materialize anything into your workspace. It will "resolve" using what's already present in your runtime or appointed platform. eclipse.import - a reader replicating the Eclipse feature and plugin import (from your platform or an arbitrary site). NOTE that the type of import (binary, linked, or source) is controlled using URL parameters in the repository Locator. url - a reader capable of reading one single file appointed by an URL (typically a jar, dll, or other pre-compiled artifact). The file is treated as a component in its own right. url.catalog - reads files from a specific catalog (folder) appointed by a URL. url.zipped - reads individual files from a zip archive appointed by a URL. local - capable of reading existing components (i.e. previously materialised) just using the component meta-data. Consult the information for the format attribute of Uri to see examples of the format required to encode location and access details for each reader type. The specified readerType may be a custom reader which must be declared using the Buckminster org.eclipse.buckminster.core.readerTypes extension point. The Extending Buckminster with a custom component reader document explains how this can be done.
componentTypes	xs:string	-	NOTE this replaces both managedCategories and componentType. The notion of category has been replaced by an extended notion of componentTypes. The attribute now takes a comma-separated list of componentTypes which also capture the semantics previously covered by categories. The componentTypes are required to configure the required reader. A component type indicates to the reader which component structure and meta-data to expect for the declared Provider. This information is essential in order for Buckminster to extract component dependency information which Buckminster automatically translates into its own dependency format (CSPEC) which will then be used in the component resolution and materialization process. A component type must be referenced in this attribute by its fully qualified name. Buckminster provides reference implementations for the following component types with the associated attribute values as indicated: osgi.bundle - standard component type for software assets maintained with Eclipse expecting assets such as .project or plugin.xml files. Essentially, an Eclipse plugin. eclipse.feature - an Eclipse feature component. eclipse.site - a component that is an Eclipse update site. eclipse.project - (DEPRECATED !!! This is now an alias for componentTypes "osgi.bundle,eclipse.feature,buckminster"). Standard component type for software assets maintained with Eclipse expecting assets such as .project or plugin.xml files. eclipse.installed - (DEPRECATED !!! This is now an alias for componentTypes "osgi.bundle,eclipse.feature"). Refers to components that are deployed in your Eclipse runtime. jar - refers to components that are JAR files and can be treated as components in their own right. Buckminster will generate a CSPEC that has no dependencies. This type is intended to be used when you want to depend on a JAR known to be found using a common URL. maven - basically an extended JAR type but assuming Maven repository dependency information contained in a POM. buckminster - refers to software assets that have no derivable component specification information, or where a specific Component Type has not been created. Assumes that the owner of the asset has added a manually created (and maintained) CSPEC inside the software asset. The reader will expect an included buckminster.cspec site.feature - refers to components found on an update site with the typical meta-data files. MUST BE used in combination with a site.feature component reader. bom - refers to a component which is a BOM artifact as produced by the Buckminster resolution process. The Buckminster framework is capable of plugging the BOM information into the resolution process and result. unknown - indicates components for which no dependency information can be inferred or has been made available. The specified componentTypes may include a custom type which must be declared using the Buckminster org.eclipse.buckminster.core.componentTypes extension point. The Extending Buckminster with a custom component type document explains how this can be done.
componentType	xs:string	-	DEPRECATED !!! USE componentTypes INSTEAD !!! NOTE that this attribute will be removed from future versions of the specification. Consult the documentation on the extended notion of componentTypes in the appropriate sections. The componentType is required to configure the required reader. The component type indicates to the reader which component structure and meta-data to expect for the declared Provider. This information is essential in order for Buckminster to extract component dependency information which Buckminster automatically translates into its own dependency format (CSPEC) which will then be used in the component resolution and materialization process. A component type must be referenced in this attribute by its fully qualified name. Buckminster provides reference implementations for the following component types with the associated attribute values as indicated: eclipse.project - standard component type for software assets maintained with Eclipse expecting assets such as .project or plugin.xml files. (DEPRECATED !!! This is now an alias for componentTypes "osgi.bundle,eclipse.feature,buckminster"). eclipse.installed - refers to components that are deployed in your Eclipse runtime. (DEPRECATED !!! This is now an alias for componentTypes "osgi.bundle,eclipse.feature"). jar - refers to components that are JAR files and can be treated as components in their own right. Buckminster will generate a CSPEC that has no dependencies. This type is intended to be used when you want to depend on a JAR known to be found using a common URL. maven - basically an extended JAR type but assuming Maven repository dependency information contained in a POM. buckminster - refers to software assets that have no derivable component specification information, or where a specific Component Type has not been created. Assumes that the owner of the asset has added a manually created (and maintained) CSPEC inside the software asset. site.feature - refers to components found on an update site with the typical meta-data files. MUST BE used in combination with a site.feature component reader. bom - refers to a component which is a BOM artifact as produced by the Buckminster resolution process. The Buckminster framework is capable of plugging the BOM information into the resolution process and result. unknown - indicates components for which no dependency information can be inferred or has been made available. The specified componentType may be a custom type which must be declared using the Buckminster org.eclipse.buckminster.core.componentTypes extension point. The Extending Buckminster with a custom component type document explains how this can be done.
managedCategories	xs:string	feature plugin	DEPRECATED !!! NOTE that this attribute will be removed from future versions of the specification. Consult the documentation on the extended notion of componentTypes in the appropriate sections. The value of managedCategories MUST BE a comma-separated list of component categories. Buckminster currently supports the two categories listed. They allow to distinguish between components which are of the same name but fall in either the category feature or plugin. The managedCategories attribute essentially defines a filter on the Provider. Through the specification of managedCategories the Provider can state that it can only handle requests for components of the specified category. This directly relates to the information specified by the category attribute in a RootRequest of a ComponentQuery. If such a request specifies no category or a category matched by managedCategories the Provider will handle the request, that is the Buckminster runtime will consult it during the resolution and materialization process. If no managed categories are specified, the Provider is considered a handler for all categories.
mutable	xs:boolean	true false	The mutable attribute specifies whether a Provider will provide mutable artifacts (this is typically the case for component readers of type cvs or svn) or whether its content cannot be edited and submitted back (examples would be maven, eclipse.platform, etc). The value of this attribute must be considered with source attribute and the mutableLevel and sourceLevel attribute values specified on an AdvisorNode given with a RootRequest in a ComponentQuery. Together they contribute to an internally computed Provider score which allows to rank all matching Providers. In cases of equally ranked Providers the first one appearing in the list of matching Providers will be chosen. EXAMPLES: A component query may for example specify that it wants to REJECT providers with mutable content (see mutableLevel attribute for more details). In this case, assuming a Provider indicates mutable="true", the Buckminster runtime will skip this Provider during the resolution and materialization process. In a more complex example it may be that an AdvisorNode specifies a mutableLevel="DESIRE" and a sourceLevel="DESIRE". Assuming two matching Providers with a mutable/source combination of true/true and true/false. In this case the first Provider would be chosen as it would have a higher ranked "Provider score".
source	xs:boolean	true false	Conceptually, the source attribute is similar to the mutable attribute. It allows to specify whether the Provider has content in source (i.e. cvs) or binary (i.e. maven) form. The value of this attribute must be considered with mutable attribute and the mutableLevel and sourceLevel attribute values specified on an AdvisorNode given with a RootRequest in a ComponentQuery. Together they contribute to an internally computed Provider score which allows to rank all matching Providers. In cases of equally ranked Providers the first one appearing in the list of matching Providers will be chosen. EXAMPLES: see examples for the mutable attribute ...

Provider Matcher component

A Matcher allows to define directives required to interprete common download pages as a provider indirection mechanism.

A large number of components (zip and tar.gz archives in particular) can be found on download pages which are reachable via a URL and contain a number of references to download URLs appointing the actual download files. Matcher together with Match and Group allows to define patterns to extract download URLs according to preset filters and/or to manipulate URLs to enable a direct download (i.e. to circumvent the need to select mirrors). Patterns will be defined using Match and Group components.

The Matcher component is represented by a matcher XML element information item. It is a container for one or more Match and Group components which are represented with correspondingly named XML element information items. The non-expanded pseudo-schema shows the element information items directly contained by matcher.

<rmap>
   <searchPath>
        <provider>
           <matcher
                  base="xs:string" >
              [ <match/> | <group/> ]+
           </matcher>
        </provider>
     </searchPath>
</rmap>

The matcher element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):

Attribute	Type	Values	Semantics
base	xs:string	-	A URL appointing the "download page" which will act as a provider. Patterns defined to extract download URL appointing archive files will be applied to the content obtained from base.

Provider Match component

A Match is the most basic directive used within Matcher. It allows to define a pattern which must be matched by URLs contained in the content provided at the base URL appointed by the enclosing Matcher. The result of the pattern match can be assigned to a variable which is referenceable by other elements (i.e. Uri within the Provider context.

The Match component is represented by a match XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by match.

<rmap>
   <searchPath>
        <provider>
           <matcher>
              <match
                    name="xs:string"
                    optional="xs:boolean"
                    pattern="xs:string"
                    prefix="xs:string"
                    suffix="xs:string" />
           </matcher>
        </provider>
     </searchPath>
</rmap>

The match element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):

Attribute	Type	Values	Semantics
name	xs:string	-	The name of a variable by which the result of the match can be referenced within the Provider context. A reference to a match named SOMENAME would have to follow the format ${SOMENAME}. If the name is omitted a match result can be referred to by the index of capturing groups which would have to be used instead.
optional	xs:boolean	true false	Denotes if this part is optional or must be matched.
pattern	xs:string	-	The pattern which will be applied to URLs in turn. It must be a valid regular expression.
prefix	xs:string	-	A convenience mechanism which allows to define a start pattern of the regular expression in pattern. The prefix will be prepended to the pattern as if quoted. The prefix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters.
suffix	xs:string	-	A convenience mechanism which allows to define an end pattern of the regular expression in pattern. The suffix will be appended to the pattern as if quoted. The suffix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters.

Provider Group component

A Group allows to declare a complex matching and filter directive used within Matcher. It allows to define a pattern and filters which are associate with specific component properties expressed in a file name (such as the target operating system, version, locale, etc). A Group defines pattern fragments which are combined into a complete pattern that in turn must be matched by URLs contained in the content provided at the base URL appointed by the enclosing Matcher. The result of the complete pattern match or invidually defined pattern fragments can be assigned to a variables which are referenceable by other elements (i.e. Uri within the Provider context.

The Group component is represented by a group XML element information item. It is a container for zero to many Name, Version, Timestamp, Revision, Os, Ws, Arch, Nl and Match components. The non-expanded pseudo-schema shows the element and attribute information items contained by group.

<rmap>
   <searchPath>
        <provider>
           <matcher>
              <group
                    name="xs:string"
                    optional="xs:boolean" />
                 [ <name/> | <version/> | <timestamp /> | <revision/> | <os/> 
                  | <ws/> | <arch/> | <nl/> | <match/> ]*
              </group>
           </matcher>
        </provider>
     </searchPath>
</rmap>

The group element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):

Attribute	Type	Values	Semantics
name	xs:string	-	The name of a variable by which the result of the match can be referenced within the Provider context. A reference to a match named SOMENAME would have to follow the format ${SOMENAME}. If the name is omitted a match result can be referred to by the index of capturing groups which would have to be used instead.
optional	xs:boolean	true false	Denotes if this part is optional or must be matched.

=Provider Group Name component=

Name allows to define a pattern (fragment) matching the component name as part of the download archive URL name. If resolution constraints for this are defined the pattern essentially acts as a provider filter based on component names.

The Name component is represented by a name XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by name.

<rmap>
   <searchPath>
        <provider>
           <matcher>
              <group>
                 <name
                       name="xs:string"
                       optional="xs:boolean"
                       pattern="xs:string"
                       prefix="xs:string"
                       suffix="xs:string" />
              </group>
           </matcher>
        </provider>
     </searchPath>
</rmap>

The name element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):

Attribute	Type	Values	Semantics
name	xs:string	-	The name of a variable by which the result of the match can be referenced within the Provider context. A reference to a match named SOMENAME would have to follow the format ${SOMENAME}. If the name is omitted a match result can be referred to by the index of capturing groups which would have to be used instead.
optional	xs:boolean	true false	Denotes if this part is optional or must be matched.
pattern	xs:string	-	The pattern which will be applied to URLs in turn. It must be a valid regular expression. Sample pattern: "[a-zA-Z0-9_-]+"
prefix	xs:string	-	A convenience mechanism which allows to define a start pattern of the regular expression in pattern. The prefix will be prepended to the pattern as if quoted. The prefix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters.
suffix	xs:string	-	A convenience mechanism which allows to define an end pattern of the regular expression in pattern. The suffix will be appended to the pattern as if quoted. The suffix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters.

=Provider Version Name component=

Version allows to define a pattern (fragment) matching the component version as part of the download archive URL name. If resolution constraints for this are defined the pattern essentially acts as a provider filter based on component versions.

The Version component is represented by a version XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by version.

<rmap>
   <searchPath>
        <provider>
           <matcher>
              <group>
                 <version
                       name="xs:string"
                       optional="xs:boolean"
                       pattern="xs:string"
                       prefix="xs:string"
                       suffix="xs:string" />
              </group>
           </matcher>
        </provider>
     </searchPath>
</rmap>

The version element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):

Attribute	Type	Values	Semantics
name	xs:string	-	The name of a variable by which the result of the match can be referenced within the Provider context. A reference to a match named SOMENAME would have to follow the format ${SOMENAME}. If the name is omitted a match result can be referred to by the index of capturing groups which would have to be used instead.
optional	xs:boolean	true false	Denotes if this part is optional or must be matched.
pattern	xs:string	-	The pattern which will be applied to URLs in turn. It must be a valid regular expression. Sample pattern: "([0-9]+\.)*[0-9]+"
prefix	xs:string	-	A convenience mechanism which allows to define a start pattern of the regular expression in pattern. The prefix will be prepended to the pattern as if quoted. The prefix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters.
suffix	xs:string	-	A convenience mechanism which allows to define an end pattern of the regular expression in pattern. The suffix will be appended to the pattern as if quoted. The suffix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters.

=Provider Group Timestamp component=

A Timestamp allows to define a pattern (fragment) matching the a timestamp as part of the download archive URL name. If resolution constraints for this are defined the pattern essentially acts as a provider filter based on timestamps.

The Timestamp component is represented by a timestamp XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by timestamp.

<rmap>
   <searchPath>
        <provider>
           <matcher>
              <group>
                 <timestamp
                       name="xs:string"
                       optional="xs:boolean"
                       pattern="xs:string"
                       prefix="xs:string"
                       suffix="xs:string" />
              </group>
           </matcher>
        </provider>
     </searchPath>
</rmap>

The timestamp element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):

Attribute	Type	Values	Semantics
name	xs:string	-	The name of a variable by which the result of the match can be referenced within the Provider context. A reference to a match named SOMENAME would have to follow the format ${SOMENAME}. If the name is omitted a match result can be referred to by the index of capturing groups which would have to be used instead.
optional	xs:boolean	true false	Denotes if this part is optional or must be matched.
pattern	xs:string	-	The pattern which will be applied to URLs in turn. It must be a valid regular expression.
prefix	xs:string	-	A convenience mechanism which allows to define a start pattern of the regular expression in pattern. The prefix will be prepended to the pattern as if quoted. The prefix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters.
suffix	xs:string	-	A convenience mechanism which allows to define an end pattern of the regular expression in pattern. The suffix will be appended to the pattern as if quoted. The suffix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters.

=Provider Group Revision component=

A Revision allows to define a pattern (fragment) matching the a revision number as part of the download archive URL name. If resolution constraints for this are defined the pattern essentially acts as a provider filter based on revision numbers.

The Revision component is represented by a revision XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by revision.

<rmap>
   <searchPath>
        <provider>
           <matcher>
              <group>
                 <revision
                       name="xs:string"
                       optional="xs:boolean"
                       pattern="xs:string"
                       prefix="xs:string"
                       suffix="xs:string" />
              </group>
           </matcher>
        </provider>
     </searchPath>
</rmap>

The revision element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):

Attribute	Type	Values	Semantics
name	xs:string	-	The name of a variable by which the result of the match can be referenced within the Provider context. A reference to a match named SOMENAME would have to follow the format ${SOMENAME}. If the name is omitted a match result can be referred to by the index of capturing groups which would have to be used instead.
optional	xs:boolean	true false	Denotes if this part is optional or must be matched.
pattern	xs:string	-	The pattern which will be applied to URLs in turn. It must be a valid regular expression.
prefix	xs:string	-	A convenience mechanism which allows to define a start pattern of the regular expression in pattern. The prefix will be prepended to the pattern as if quoted. The prefix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters.
suffix	xs:string	-	A convenience mechanism which allows to define an end pattern of the regular expression in pattern. The suffix will be appended to the pattern as if quoted. The suffix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters.

=Provider Group Os component=

A Os allows to define a pattern (fragment) matching the operating system information as part of the download archive URL name. If resolution constraints for this are defined the pattern essentially acts as a provider filter based on operating system information.

The Os component is represented by a os XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by os.

<rmap>
   <searchPath>
        <provider>
           <matcher>
              <group>
                 <os
                       name="xs:string"
                       optional="xs:boolean"
                       pattern="xs:string"
                       prefix="xs:string"
                       suffix="xs:string" />
              </group>
           </matcher>
        </provider>
     </searchPath>
</rmap>

The os element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):

Attribute	Type	Values	Semantics
name	xs:string	-	The name of a variable by which the result of the match can be referenced within the Provider context. A reference to a match named SOMENAME would have to follow the format ${SOMENAME}. If the name is omitted a match result can be referred to by the index of capturing groups which would have to be used instead.
optional	xs:boolean	true false	Denotes if this part is optional or must be matched.
pattern	xs:string	-	The pattern which will be applied to URLs in turn. It must be a valid regular expression. Sample pattern: "aix|linux|macosx|solaris|win32"
prefix	xs:string	-	A convenience mechanism which allows to define a start pattern of the regular expression in pattern. The prefix will be prepended to the pattern as if quoted. The prefix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters.
suffix	xs:string	-	A convenience mechanism which allows to define an end pattern of the regular expression in pattern. The suffix will be appended to the pattern as if quoted. The suffix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters.

=Provider Group Ws component=

A Ws allows to define a pattern (fragment) matching the windowing system information as part of the download archive URL name. If resolution constraints for this are defined the pattern essentially acts as a provider filter based on windowing system information.

The Ws component is represented by a ws XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by ws.

<rmap>
   <searchPath>
        <provider>
           <matcher>
              <group>
                 <ws
                       name="xs:string"
                       optional="xs:boolean"
                       pattern="xs:string"
                       prefix="xs:string"
                       suffix="xs:string" />
              </group>
           </matcher>
        </provider>
     </searchPath>
</rmap>

The ws element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):

Attribute	Type	Values	Semantics
name	xs:string	-	The name of a variable by which the result of the match can be referenced within the Provider context. A reference to a match named SOMENAME would have to follow the format ${SOMENAME}. If the name is omitted a match result can be referred to by the index of capturing groups which would have to be used instead.
optional	xs:boolean	true false	Denotes if this part is optional or must be matched.
pattern	xs:string	-	The pattern which will be applied to URLs in turn. It must be a valid regular expression. Sample pattern: "carbon|gtk|motif|wpf|win32"
prefix	xs:string	-	A convenience mechanism which allows to define a start pattern of the regular expression in pattern. The prefix will be prepended to the pattern as if quoted. The prefix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters.
suffix	xs:string	-	A convenience mechanism which allows to define an end pattern of the regular expression in pattern. The suffix will be appended to the pattern as if quoted. The suffix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters.

=Provider Group Arch component=

A Arch allows to define a pattern (fragment) matching the architecture information as part of the download archive URL name. If resolution constraints for this are defined the pattern essentially acts as a provider filter based on architecture system information.

The Arch component is represented by a arch XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by arch.

<rmap>
   <searchPath>
        <provider>
           <matcher>
              <group>
                 <arch
                       name="xs:string"
                       optional="xs:boolean"
                       pattern="xs:string"
                       prefix="xs:string"
                       suffix="xs:string" />
              </group>
           </matcher>
        </provider>
     </searchPath>
</rmap>

The arch element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):

Attribute	Type	Values	Semantics
name	xs:string	-	The name of a variable by which the result of the match can be referenced within the Provider context. A reference to a match named SOMENAME would have to follow the format ${SOMENAME}. If the name is omitted a match result can be referred to by the index of capturing groups which would have to be used instead.
optional	xs:boolean	true false	Denotes if this part is optional or must be matched.
pattern	xs:string	-	The pattern which will be applied to URLs in turn. It must be a valid regular expression. Sample pattern: "ppc|x86|x86_64"
prefix	xs:string	-	A convenience mechanism which allows to define a start pattern of the regular expression in pattern. The prefix will be prepended to the pattern as if quoted. The prefix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters.
suffix	xs:string	-	A convenience mechanism which allows to define an end pattern of the regular expression in pattern. The suffix will be appended to the pattern as if quoted. The suffix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters.

=Provider Group Nl component=

A Nl allows to define a pattern (fragment) matching the locale as part of the download archive URL name. If resolution constraints for this are defined the pattern essentially acts as a provider filter based on locale information.

The Nl component is represented by a nl XML element information item. The non-expanded pseudo-schema shows the attribute information items contained by nl.

<rmap>
   <searchPath>
        <provider>
           <matcher>
              <group>
                 <nl
                       name="xs:string"
                       optional="xs:boolean"
                       pattern="xs:string"
                       prefix="xs:string"
                       suffix="xs:string" />
              </group>
           </matcher>
        </provider>
     </searchPath>
</rmap>

The nl element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):

Attribute	Type	Values	Semantics
name	xs:string	-	The name of a variable by which the result of the match can be referenced within the Provider context. A reference to a match named SOMENAME would have to follow the format ${SOMENAME}. If the name is omitted a match result can be referred to by the index of capturing groups which would have to be used instead.
optional	xs:boolean	true false	Denotes if this part is optional or must be matched.
pattern	xs:string	-	The pattern which will be applied to URLs in turn. It must be a valid regular expression. Sample pattern: "en_GB|en_US"
prefix	xs:string	-	A convenience mechanism which allows to define a start pattern of the regular expression in pattern. The prefix will be prepended to the pattern as if quoted. The prefix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters.
suffix	xs:string	-	A convenience mechanism which allows to define an end pattern of the regular expression in pattern. The suffix will be appended to the pattern as if quoted. The suffix can thus be provided as a literal without the need to use special regular expression syntax or escape special characters.

Uri component

A Uri declares the address associated with the enclosing Provider. It must contain sufficient information such that the component reader is able to access and read information from the location. This typically includes location path, protocol and access details (user name and password).

The Uri component is represented by a uri XML element information item. It is a container for optional Constant, Format, PropertyRef, Replace, Split, ToLower and ToUpper components which are represented with correspondingly named XML element information items. The non-expanded pseudo-schema shows the element information items directly contained by uri.

<rmap>
   <searchPath>
        <provider>
           <uri
                 format="xs:string" >
              [ <com:constant/> | <com:format/> | <com:propertyRef/> |
                <com:replace/> | <com:split/> | <com:toLower/> | <com:toUpper/> ] *
           </uri>
        </provider>
     </searchPath>
</rmap>

The uri element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):

Attribute	Type	Values	Semantics
format	xs:string	-	The value of this attribute encodes the access details required by the component reader. The specific format of this value depends on the component reader specified by the Provider in the SearchPath. EXAMPLE: Assuming declaration of a cvs reader on a component type of eclipse-project a valid attribute value (valid in the sense that the Buckminster framework implementation can utilise it) would be ":pserver:anonymous@dev.eclipse.org:/cvsroot/technology,org.eclipse.dash/{0}". EXAMPLES FOR ALL COMPONENT READER TYPES: ...

Provider Digest component

A Digest ...

The Digest component is represented by a digest XML element information item. The non-expanded pseudo-schema shows the attribute information items directly contained by digest.

<rmap>
   <searchPath>
        <provider>
           <digest
                 algorithm="xs:string" >
           </digest>
        </provider>
     </searchPath>
</rmap>

The digest element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):

Attribute	Type	Values	Semantics
algorithm	xs:string	-	-

VersionConverter component

A VersionConverter specifies how a component reader for a specific component type declared by the enclosing Provider should map between a simple version designator such as "3.1.0" and a version selector specific to the provider such as "main/3.1.0" (which can be based on branchname, tag, changenumber, or timestamp).

The VersionConverter component is represented by a versionConverter XML element information item. It is a container for optional Transform components which are represented with correspondingly named XML element information items. The non-expanded pseudo-schema shows the element information items directly contained by transform.

<rmap>
   <searchPath>
        <provider>
           <versionConverter 
                 type="xs:string"
                 versionTypeype="xs:string" >
              <transform/> *
           </versionConverter>
        </provider>
     </searchPath>
</rmap>

The versionConverter element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):

Attribute	Type	Values	Semantics
type	xs:string	branch or tag	The value of this attribute specifies which type of version converter the component reader specified by the Provider should use. The conversion can be customized through declarations in the Transform enclosed by the VersionConverter. branch - creates a version selector referencing the latest version on a branch named from the plain version, i.e. "3.1.0" will be translated into "3.1.0/LATEST". tag - creates a version selector referencing the plain version as a tag on the default branch. i.e. "3.1.0" will be translated into "main/3.1.0". With the tag converter it is possible to use a change number or timestamp instead of the tag. The specified version converter type may be a custom type which must be declared using the Buckminster org.eclipse.buckminster.core.versionConverters extension point. The Extending Buckminster with a custom version converter document explains how this can be done.
versionType	xs:string	string, triplet, or OSGi (this list might be extended)	The value of this attribute specifies what type of version this version converter will create. The default type is string. This value must be provided if you are using other types of versions such as OSGi or triplet.

Transform component

A Transform specifies how the conversion between a plain version ("3.1.0") and a version selector (i.e. "main/3.1.0") by the enclosing VersionConverter must be done. A sequence of Transforms details this bi-directional mapping process.

Transform defines substitution patterns via its attributes which facilitate the conversion/transformation.

The Transform component is represented by a transform XML element information item. The non-expanded pseudo-schema shows the attribute information items for transform.

<rmap>
   <searchPath>
        <provider>
           <versionConverter >
              <transform
                    toPattern="xs:string" 
                    toReplacement="xs:string" 
                    fromPattern="xs:string" 
                    fromReplacement="xs:string" />
           </versionConverter>
        </provider>
     </searchPath>
</rmap>

The transform element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):

Attribute	Type	Values	Semantics
fromPattern	xs:string	-	fromPattern builds a pair with the attribute fromReplacement. This attribute pair describes the transformation from plain version strings to version strings as potentially required for use in a version selector (i.e. from "3.1.0" to "v3_1_0"). fromPattern MUST provide a regular expression. All fragments of a given plain version string that match the expression will be replaced with the replacement string provided as a value of fromReplacement. EXAMPLE (assuming two transforms): Given is a version string 3.1.0. Assuming a first Transform with fromPattern="\." and fromReplacement="_", the version name 3.1.0 would be mapped to 3_1_0. Furthermore, assuming a second Transform with fromPattern="^(.*)$" and fromReplacement="v$1" the transformed 3_1_0 would be mapped further to v3_1_0.
fromReplacement	xs:string	-	fromReplacement builds a pair with the attribute fromPattern. SEE DETAILED EXPLANATION FOR THE fromPattern ATTRIBUTE.
toPattern	xs:string	-	toPattern builds a pair with the attribute toReplacement. This attribute pair describes the re-transformation of transformed version strings to the original plain versions (i.e. from "v3_1_0" to "3.1.0"). The information in these two attributes must exactly reverse the transformation specified in the fromReplacement/fromPattern attributes. The Buckminster framework enforces this requirement. toPattern MUST provide a regular expression. All fragments of a given transformed version string that match the expression will be replaced with the replacement string provided as a value of toReplacement. EXAMPLE (assuming the two transforms as specified in the example for fromPattern): Given is a previously transformed version string v3_1_0. Assuming the second Transform with toPattern="^v(.*)$" and toReplacement="$1", the version name v3_1_0 would be mapped to 3_1_0. Furthermore, assuming the first Transform with toPattern="_" and toReplacement="." the transformed 3_1_0 would be mapped back to 3.1.0.
toReplacement	xs:string	-	toReplacement builds a pair with the attribute toPattern. SEE DETAILED EXPLANATION FOR THE toPattern ATTRIBUTE.

Locator component

A Locator acts as a pointer to a SearchPath (defined in the enclosing Rmap) for component requests matching a specified component name pattern. A Locator is used by the Buckminster framework in the component resolution process triggered by a component request. Those requests may originate directly from a CQUERY or from CSPECs which may be resolved recursively as part of the former.

The framework will consult the Locators (and Redirects) in order to find the search path holding the information to analyse and obtain the components required to resolve a component query. An Rmap may specify multiple Locators (and Redirects). Each of those will specify a pattern that the framework component resolver will match against the name of the queried component.

NOTE that the resolver will traverse the Locators (and Redirects) in the order in which they appear in the Rmap. Thus, the order of those should be from "more specific" to "least specific" with regard to the component name matching patterns they provide. The Buckminster component resolver MUST FAIL if no Locator (or Redirect) pattern matches the queried component.

NOTE that different locators in an Rmap may point to the same SearchPath.

The Locator component is represented by a locator XML element information item. The non-expanded pseudo-schema shows the attribute information items for locator.

<rmap>
   <locator
           pattern="xs:string" 
           searchPathRef="xs:string"/>
</rmap>

The locator element has the following attributes. Required attributes are highlighted in bold. Values are given to indicate either a value constraint not formalised by the schema or to enumerate the valid values (in this case a default value is highlighted in bold):

Attribute	Type	Values	Semantics
pattern	xs:string	-	The value of this attribute MUST BE a regular expression representing a component name pattern which the Buckminster framework will use during the resolution process to match the name of a queried component. If a component name matches the pattern specified by this attribute the Buckminster component resolver will attempt to obtain the required component information from the location(s) provided by the SearchPath with the name given in the Locator's searchPathRef attribute which refers to the name given in SearchPath's name attribute.
searchPathRef	xs:string	-	Specifies the name of the search path (as given in a SearchPath's name attribute in the enclosing Rmap) that the Buckminster resolver should follow up during the component resolution process IF the name of the queried component is matched by the pattern provided in the Locator's pattern attribute. NOTE that different locators in an Rmap may point to the same SearchPath.

Redirect component

A Redirect acts as a pointer to an Rmap URL for component requests matching a component name pattern specified by the Redirect.

Redirect effectively works like an import for Locators, Redirects and SearchPaths in the appointed external Rmap. Just as a Locator, a Redirect is used by the Buckminster framework in the component resolution process triggered by a component request. Those requests may originate directly from a CQUERY or from CSPECs which may be resolved recursively as part of the former.

The framework will