Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Buckminster Project/docs/drafts/ResourceMap
Contents
Buckminster Resource Map
Each Buckminster installation will utilize one or more resource maps (an XML document) that will map the name of a requested component to one of several search paths. The resource map contains a list of pairs with a regular expression and a corresponding entry that is either the name of a search path or a pointer to another resource map. The name of the requested component is matched against the regular expressions and the first match found denotes the search path to use or a redirection to another resource map. When the latter happens, the mapping process is delegated to the other resource map.
A resource map also contains at least one site declaration.
Site
Since a resource map is meant to be shared among many Buckminster users, a site acts a grouping of properties that is specific to some arbitrary group. A developer specifies his or her 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.
Search Path
A search path is a named list of provider declarations that will be traversed in order. A component name will be mapped to exactly one search path. A failure to find a matching search path is considered an error since without it, there's no way to find the component.
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 component reader that is associated with a component type and a version converter.
Component type
A component type knows how to extract dependency information from a component. Buckminster introduces a native component type that contains a Buckminster Dependency Specification (dspec for short). It also have built-in types for update-sites, features, plug-ins, and fragments that will produce a dspec from the Eclipse provided manifest files.
New component types can be added using the extension-point org.eclipse.buckminster.core.componentTypes.
Component reader
Buckminster connects to a component using a component reader. A reader performs three significant tasks:
- It can list component branches and/or tags that corresponds to a component request
- It can read individual files from a component and thus support a component type in gathering the information needed to recursively create a dependency graph.
- It can materialize the component on the local disk.
A reader will typically adapt to some specific type of source code control system such as CVS, Subversion, Perforce, or ClearCase but it can also be an adaptor for Maven repositories, FTP archives, or software that is installed on disk. One example of the latter is the "eclipse-installed" reader that will connect to components (in this case - features, plug-ins, and fragments) that are present in your Eclipse installation.
Regardless of type, the reader must have the following information in order to connect.
- Repository URI (specified by the provider).
- Component name.
- A version designator with an associated version type.
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.
New types of component readers can be added using the extension-point org.eclipse.buckminster.core.readerTypes.
Version Converter
The conversion from plain version into a branch selector is performed by a version converter.
Buckminster delivers two converters by default. One that will create a branch selector that reflects the latest version on a branch named from the plain version, i.e. "3.1.0" will be translated into "3.1.0/LATEST" and one that will use the plain version as a tag on the default branch. i.e. "3.1.0" will be translated into "main/3.1.0". Regular expressions can be used when less straight forward mappings are desired such as "3.1.0" into "main/v3_1_0-xyz". It is required that the mapping can be reversed without loss of information.
New version converters can be added using the extension-point org.eclipse.buckminster.core.versionConverters.
The versions designated by a component request are always converted to version selectors before they are passed to a component reader. A component reader will only understand version selectors.
A reader defines a default branch. For CVS that will be "head", for SVN it will probably be "trunk", ClearCase will use "main", etc.
A component reader that connects to an non versioned artifact will only understand the notation <default branch>/LATEST. A reader that cannot combine branch with tag (such as Subversion) will use <default branch>/<tag> to denote a tag and <branch>/LATEST to denote a branch (those notations are the most common even when branches and tags indeed can be combined).
A version selector is qualified in one of four ways:
- Latest
Denotes the latest revision on the branch. Notation: <branch>/LATEST - Tag
Denotes a specific tag on the branch. Notation <branch>/<tag> - Change number
Denotes a specific change number on the branch. Notation <branch>#<number> - Timestamp
Denotes a specific point in time (UTC) on the branch. Notation <branch>@yyyy-MM-dd[THH:mm:ss]. The delimiters are all optional except for the 'T'.
A version selector that does not contain a '/', '#', or '@' is considered a plain version and hence, those characters cannot be used in a plain version selector.