Component Query (Buckminster)

< To: Buckminster Project

This page has been archived. Go to Buckminster UI Guide instead.

A Component Query is the topmost input to the Buckminster resolution process. It specifies "the thing you want to resolve" and provides guidelines for the resolution stages of the process.

Where to start

A Component Query is managed by the Component Query Editor. The editor can be started in one of the following ways:

• Navigate to File -> New -> Other -> Buckminster -> Component Query File. This creates a new blank Component Query
• Navigate to File -> Open. Then select a file with .cquery extension
• Navigate to Buckminster -> Open Component Query. Enter a URL to a remote Component Query
• Double click on file with .cquery extension in your workspace

Component Query Editor

There is an Eclipse Editor provided in the Buckminster Eclipse plugin that helps you construct a Component Query.

Figure: Screenshot of the Eclipse Component Query Editor - Main Tab

The Component Query contains:

• A component request that denotes the top-component of the query.
• The URL of the Resource Map that should be used.
• Zero to many AdvisorNodes (explained below).
• Properties
• Documentation

Component Query Files

A component query can be entered and used directly, or saved in a file for later use. The file format is in XML and the ending of the file is .cquery. You can open and edit saved cquery files if you want.

Tip: Use different query files for different scenarios. You can have as many .cquery files as you want. You may be working on different projects and in different phases. Rather than changing one query to suit the situation, you can have one per scenario that you want to set up. When working in a team environment it is very useful to share query files as it increases repeatability, and reduces opportunity for human errors.

Request

A Component Request is a pointer that specifies a component by name, category, and suitable version(s) of that component.

The request is easily edited (the two first lines in the editor), where the wanted component name is entered, the category, version designator and version type.

There is a convenient drop down to help in specifying the Version Designator - you do not have to remember which of brackets and parenthesis you should use for exclusive and inclusive range - it is spelled out here.

If you leave the version designator empty you are asking for "the best" version. This will resolve the version that, when compared using the Version Type (Buckminster) is considered to be highest in magnitude.

Unfortunately, there is no convenient drop down where you can select between possible versions. Finding them is one of the tasks that the first phase of the resolver will perform when building the dependency graph. There is also a drop down to allow you to select a Version Type.

URL to Resource Map

This is the URL to the resourcemap to use for the resolution.

For example the http, and file protocols are supported. Also the cvs protocol can be used. It has the following format:
cvs://[<user>[:<password>]@]<host>/<path>?respository=/<repository>[&method=<method>][#<tag>]
e.g.
cvs://anonymous@dev.eclipse.org/org.eclipse.buckminster/org.eclipse.buckminster/demo/rmaps/demo.rmap?repository=/cvsroot/technology&method=pserver

Please see Resource Map for more information.

Advisor Nodes

The Advisor Nodes section allows you to specify "advice" (or rules if you like) that will be applied throughout the resolution process. A rule is triggered when Buckminster processes a component with a name and category that matches the pattern and category for the rule.

Pattern matching takes place in the order they are listed, and you can rearrange the order with the up/down buttons on the right. The search for a rule to apply stops if there is a match, meaning that you can not trigger more than one rule for a component and you must be careful to place more general (broad) matching rules towards the bottom of the list.

Figure: Screen shot of the Eclipse Component Query Editor - Advisor Nodes Tab

Name Pattern

The 'Name Pattern' field displays the name pattern of the advisor node selected in the list. It is in the form of a regular expression.

Matched Category

The 'Matched Category' field displays the optional category discriminator for the advisor node. The node will discriminate all components but the ones that belongs to the given category unless the field is left empty.

Skip Component

The check box 'skip component' enables you to ignore the matched component completely. This is useful if you know that a component has listed dependencies to components that you really do not need. A skipped component will not be resolved, and its dependencies will not be included in the resolution.

Project Name Mapping

The two fields 'Source Pattern' and 'Replacement' forms a regular expression substitution. The source pattern defines the subgroups that can be referenced using $<n> in the replacement. See regular expression for more info.

Special Requirements

The 'Special Requirements' section contains settings for mutable level and source.

The mutable level setting allows you to specify if you need access to a component in a way that allows you to make changes to its content and write them back, if you want read only access, or if you are indifferent to what you get.

The source level setting allows to specify that the component must contain source code (required), if you are indifferent, or if you only want a component that does not contain source.

Version Designator/Type Override

This section allows you to specify an override for what version to use, and how to interpret the expressed version string. You may want to replace a standard component with one that you are working on - so here is your chance to replace that buggy "1.0.0" that would otherwise be materialized with "1.0.0-experimental" (and as you can see, this type of override needs both a different designator, and a different version type (the standard Version Type would not recognize the '-experimental' part. You can also use this override to narrow the search. The default may be something like "1.0 or larger", but you may know that version "2.7" and beyond does not work.

Properties

In addition to appointing a properties file, a Component Query can also have embedded properties.

File:BuckminsterCQueryEditorProperties.png
Figure: Screenshot of the Eclipse Component Query Editor - Properties Tab

Documentation

The Component Query might be described in detail using the documentation tab.

Figure: Screenshot of the Eclipse Component Query Editor - Documentation Tab

Materialization Controls

At the bottom there are controls that allows you to specify how resolution should take place.

'Resolve Immediately' means that all component dependencies will be traversed and resolved before the wizard displays the result. If you want to be involved in the process uncheck this box, and the wizard will pop-up with an empty tree, letting you resolve each branch manually, either step-by-step or recursively.

A checked 'Continue on Error' means that the resolution will continue even if there are errors. Otherwise it will stop on an error. Everything materialized up to that point will remain, but perhaps be in a undefined state if an error occurred in the middle of the resolution.

A "Resolve to Wizard" starts a resolution process and guides you through the process using a wizard. Nothing is actually materialized, but you can examine what your query will result in. This is especially useful when you are adding Advisor Nodes and you want to make sure they have the intended effect before you start materializing a possibly large number of large components. If you want to materialize once you have seen the result, the wizard has a "Finish" button in the last stage that will materialize everything. Use cancel, if you do not want to materialize.

Figure: Screen shot of the Component Query Wizard as it has a resolved a Component Query for the Buckminster project itself

Resolve and Materialize, starts the resolution process and materializes the component and all dependencies (recursively).

Save Externally As, allows you to export the Component Query to a file outside of your Eclipse workspace. Eclipse does not have this functionality, standard functionality allows files outside the projects to be opened and saved, but not created. Sometimes it is useful to be able to save a copy this way.

Scope of the Query

The Component Query is used throughout the resolution process so the overrides will reach the leafs if their component names are matched by an Advisor Node.