View source for Resource Map (Buckminster)

<noinclude>{{Backlink|Buckminster Project}}
=Buckminster Resource Map=
</noinclude>
A resource map (RMAP) is used when resolving a request for a component [[Buckminster Component Query]] and supports federated, parameterized and search-path based resolution of materializable components.
<noinclude>
The RMAP is stored in a XML file using the {{Code|rmap}} [[Buckminster XML-Schemas|Buckminster XML-Schema]], and a URL is used to point to the wanted XML file containing the map. It is possible to define a default RMAP-URL which will be used if not specified in a query.

We say that 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 {{Code|$HOME}}, {{Code|$CLOSEST_MIRROR}}). 

=Organization of the RMAP=
The RMAP consists of:
{| {{BMTableStyle}}
|+ {{BMTableCaptionStyle}}|RMAP Elements
|- {{BMTHStyle}}
! min !! max !!element !! comment
|-
|0||&#42;||property||setting of a default constant property
|-
|0||&#42;||searchPath||named search path
|-
|0||&#42;||locator or redirect|| choice of search path locator, or redirect to another RMAP.
|-
|1||&#42;||site (deprecated)|| named grouping of parameters see [#deprecated]
|-
|0||&#42;||propertyElement (to be replaced)||allows string transformations of properties to aid in mapping
|}

==Properties==
Properties can be used in the RMAP to parameterize the search paths. Examples of properies are things like {{Code|$HOME}}, {{Code|$CLOSEST_MIRROR}}, etc. Default values for these properties must be set in the RMAP, or a user of the RMAP that does not have these properties set elsewhere will most likely not be able to use that RMAP.

The requirement that all used properties must have a default definition is currently not enforced by Buckminster, but may be in the future.

The properties set in the RMAP are default (last resort), but they can also be set elsewhere with higher priority. This table shows the order of precedence. Lowest precedence is at the bottom (i.e. used last if not set with higher precedence).

{| {{BMTableStyle}}
|+ {{BMTableCaptionStyle}}|RMAP precedence
|- {{BMTHStyle}}
!precedence!!property defined where!!comment
|-
|3||Commandline||Properties set with <tt>-Dxxx=yyy</tt> when invoking Eclipse IDE, or the headless Buckminster version.
|-
|2||SITE||Site properties are stored in a regular properties file and a preferences setting control which file to use.
|-
|2||CQUERY||When defining what to materialize in a CQUERY, it is also possible to set properties to override the default
|-
|1||RMAP||the default properties set in the RMAP itself
|} 

The SITE properties file is intended to be shared by a site/organization and be made available via an URL. Naturally, this mechanism is also very useful for individual developers maintaining their own RMAPs to define common parameter settings. Note that the precedence of these properties are higher than for both CQUERY and RMAP thus making sure that settings that should be used by the organization are not overridden by accident. 

The Commandline property settings override all others and should be seen as 'last resort' when the other property settings will produce the wrong result (or not work at all). You are perhaps materializing on some test server that is isolated from the rest of the network, and you need to override to point to something stored locally on this server, or you may need to test a specific experimental version that is not part of normal use of the RMAPs. The RMAP(s) and CQUERY files are perhaps checked into a source control system, and you can not (and indeed do not want to) check them out and change them. The command line property override is then the mechanism to use.

It is also possible to override the default properties in the CQUERY if you want a particular materialization to produce a particular result using components from other sources that normal. 

Naturally to make all of this work well, some planning and thought is needed in how you parameterize the search paths. (If there are no properties used in the search paths (etc) then naturally it is not possible to set any properties that will change the lookup in the RMAP.

===Property and PropertyElement===
There are two property element types for property elements. The plain 'property' element of PropertyConstant type is used to set constant values (strings, numbers etc.) while the element 'propertyElement' is of PropertyElement type and is used to set properties that are calculated using a set of functions for string manipulations. 
It is suggested in [https://bugs.eclipse.org/bugs/show_bug.cgi?id=143507 Bugzilla bug entry] that this functionality is removed from RMAP and replaced with less generic but easier to understand functionality.


 <property key="CLOSEST_MIRROR" value="megapool.com/megarepo"/>

===Available Properties===
Buckminster sets the following properties per component being resolved.

{| {{BMTableStyle}}
|+ {{BMTableCaptionStyle}}|Available Properties
|- {{BMTHStyle}}
!Property Name !! Description !! See Also
|-
|buckminster.component || The name of the component being resolved. ||
|-
|buckminster.category|| Used when the same component name is used for different 'flavors' of the same thing. || [[Buckminster Component Category]]
|-
|buckminster.version.designator|| The 'version string' of the component being resolved.|| [[Buckminster Version Designator]]
|-
|buckminster.version.type|| The type of the version designator.|| [[Buckminster Version Type]]
|-
|}

==Search Path==
A search path is very similar to a regular search path of directories to search for a file on your local computer, but Buckminster needs to know more - naturally the address of the 'place to search', but also how to interpret what is found at the given address. The needed information is described in a [#provider] element. So, the search path is simply a list of providers to search

The RMAP can contain any number of named search paths. The search paths are "just data", the order in which they occur in the RMAP is not important. The selection of a search path (or selection of a redirect to another RMPAP) is performed by looking at the Locator and Redirect elements in the RMAP. So, the search paths you specify is simply a catalogue of possible search paths.

Once a search path has been selected the listed providers are consulted in the order they occur in the path until the component is found. It is considered an error if a component can not be found using the selected search path.

{| {{BMTableStyle}}
|+ {{BMTableCaptionStyle}}|Search Path examples
|-
|<pre>
<searchPath name="WHAT IS A TYPICAL NAME">
<provider ...>
<provider ...>
</searchPath>
</pre>
|-
|}

===Provider===
A provider is a declaration that groups information needed to obtain a component of a specific type from a specific location using a specific versioning scheme. The information in the provider is used to create and configure a [[Buckminster Component Reader|Component Reader]] capable of enumerating and reading the content, a [[Buckminster Component Type|Component Type]] that understands how to use the reader to obtain the dependency information, and a [[Buckminster Version Converter|Version Converter]] that understands how to convert between a version string and the corresponding ’’version selector’’ (something like branch name, change-number, timestamp, etc.) suitable for use with the repository pointed to by the provider. 

The Provider consists of the following:

{| {{BMTableStyle}}
|+ {{BMTableCaptionStyle}}|Provider Elements
|- {{BMTHStyle}}
! attribute !! type !! comment
|-
| readerType || string || 
|-
| mutable || boolean || 
|-
| source || boolean || 
|-
| managedCategories || string || comma separated list of managed categories.<br>
A managed category is really a type of naming space. Currently supported (other than none) are "feature", and "plugin".
|-
|}

{| {{BMTableStyle}}
|+ {{BMTableCaptionStyle}}|Provider Elements
|- {{BMTHStyle}}
!min!!max!! element !! comment
|-
|1||1||uri||the adress provided to the reader
|-
|0||1||versionConverter||an optional element describing how version designators are mapped to/from the repository/component specific
|-
|}

====Component type====
{{:Buckminster Component Type}}

In the provider, the name of the <tt>ComponentType</tt> class is used. For example <tt>BuckminsterComponentType</tt>.


====Component Reader====
{{:Buckminster Component Reader}}

In the Provider, the name of the Component Reader class is used, and you need to add the adress to the repository in form of a URI.

{{BlueBox|
This probably belongs elewhere:
The component name and version selector both stem from the original component request. They will typically be specified in a component dependency of a dspec.

Once a reader has been instantiated, Buckminster will create a version query based on the comparator, the rule, and a branch selector. The reader uses this query when it obtains candidate component versions. The query might result in several candidate versions so the next step is to compare those matches with each other to figure out the best match.
}}

====Version Converter====
{{:Buckminster Version Converter}}

You need to specify the type of converter (currently "branch" or "tag"), and supply regular expressions to perform the translation. You may also use change-number or timestamp information to more precisely pinpoint a version selector. See [Version Selector] for additional information about what a Version Converter produces.

==Locator and Redirect List==
The RMAP can have any number of Locator or Redirect entries. The order in which they occur is important as the search for a matching entry is done in that order. The first matching Locator or Redirect is used. 

Locators and Redirects consist of a regular expression pattern and a reference to how the search for the component should continue. The Locator specifies the name of the search path to use, and the Redirect specifies the URL of a RMAP where the search should continue.

A component name will be mapped to exactly one search path. The first found match is used. It is an error if there is no match.

{| {{BMTableStyle}}
|+ {{BMTableCaptionStyle}}|Redirecting one special component
|-
|<pre>
<rm:redirect href="http://myorg.com/rmaps/myExperimentalMap.rmap" pattern="^com\.myorg\.myComponent" />
<rm:locator searchPathRef="myStandardPath" pattern="^com\.myorg(\..+)?" />
</pre>
|-
|}

In this example the component "com.myorg.myComponent" will be resolved using the rmap found at "myorg.com/rmaps/myExperimentalMap.rmap". All other components starting with "com.myorg" will be resolved using the "myStandardPath".

=Examples=
Here is an example borrowed from the Eclipse Monkey, part of the Eclipse "dash" project.

{| {{BMTableStyle}}
|+ {{BMTableCaptionStyle}}| RMAP for Eclipse Monkey
|-
|<pre>
<?xml version="1.0" encoding="UTF-8"?>
<rm:rmap
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:rm="http://www.eclipse.org/buckminster/RMap-1.0"
	xmlns:pv="http://www.eclipse.org/buckminster/Provider-1.0"
	xmlns:mp="http://www.eclipse.org/buckminster/MavenProvider-1.0"
	xmlns:bc="http://www.eclipse.org/buckminster/Common-1.0">

	<rm:site name="default">
	</rm:site>

	<rm:searchPath name="dash">
		<rm:provider readerType="cvs" componentType="eclipse-project" mutable="true" source="true">
			<pv:uri format=":pserver:anonymous@dev.eclipse.org:/cvsroot/technology,org.eclipse.dash/{0}">
				<bc:property key="buckminster.component" />
			</pv:uri>
		</rm:provider>
	</rm:searchPath>

	<rm:locator searchPathRef="dash" pattern="^org\.eclipse\.eclipsemonkey([\.\-].+)?" />
	<rm:locator searchPathRef="dash" pattern="^org\.eclipse\.eclipsemonkey-feature" />
	<rm:locator searchPathRef="dash" pattern="^org\.eclipse\.dash(\..+)?" />
	<rm:locator searchPathRef="dash" pattern="^org\.mozilla\.rhino" />

</rm:rmap>
</pre>
|-
|}

This RMAP tells you that components that match the four patterns at the end are found by using the search path called "dash". The search path "dash" in turn, defines that the source is available in a CVS repository and the URI to the repository is created by formatting the URI (the <tt>\{0\</tt>} is replaced with the value of the "buckminster.component" property - i.e. the name of the component).

=Deprecated=
==Site==
The Site is now deprecated, but older RMAP files with a Site section will still function but with some restrictions. Use the Property top level element instead. (And later the replacement for the PropertyElement).

The idea for the Site section was to aid in the sharing of settings of multiple users at a particular location (actually an arbitrary grouping). With the Site, a user was supposed to point to a particular named site in the preferences for the installation. A developer specifies the wanted site by setting a Buckminster preference. A good example of a site-specific property is a URL that denotes the closest mirror of an archive. A geographically spread development organization can maintain one resolver map and still have all offices use optimal archive mirrors when fetching artifacts.

The Site element defines that nested Property and PropertyElements are accepted. Should the current implementation encounter a Site element, it simply ignores the Site element and interprets the nested property and PropertyElement as top level elements. Naturally, if you had several site elements, a property set in an earlier will be overridden if the same property is set in a Site encountered later. In practice this should not be a problem as probably no one has ever used this functionality. Most existing RMAPs only contain one Site.


[[Category:Archived Buckminster Documentation]]

<noinclude>