Component Query (Buckminster)
< To: Buckminster Project
A Component Query is the topmost input to the Buckminster materialization process. It specifies "the thing you want materialized" and provides guidelines for the resolve and materialization stages of the process.
- 1 Component Query Editor
- 1.1 Component Query Files
- 1.2 Request
- 1.3 URL to Resource Map
- 1.4 Advisor Nodes
- 1.5 Properties
- 1.6 Documentation
- 1.7 Materialization Controls
- 1.8 Scope of the Query
- 2 ISSUES
Component Query Editor
There is an Eclipse Editor provided in the Buckminster Eclipse plugin that helps you construct a Component Query.
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).
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.
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 Buckminster Version Type 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 allwo you to select a Version Type.
URL to Resource Map
This is the URL to the resourcemap to use for the resolvement.
For example the http, and file protocols are supported. Also the cvs protocol can be used. It has the following format:
Please see Resource Map for more information.
The Advisor Nodes section allows you to specify "advice" (or rules if you like) that will be applied throughout the materialization 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.
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.
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.
The checkbox '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 materialized, 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.
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 sourcecode (required), if you are indifferent, or if you only want a component that does not contain source.
There is a group of checkboxes that have effect during the resolve phase, and a setting for materialization-mode when materializing something that already exists locally.
The Known checkboxes allows you to specify what types of component the resolvment process should consider; Plugins and Features, Materializations, and Projects. If unchecked, resolution for the unchecked type will be via the RMAP and existing components treated as if not already materialized (i.e. ignored). If box is checked, and component already exists, its dependencies as found in the existing copy will be resolved.
Note that Buckminster keeps track of all materializations, and that the materialization checkbox refers to all materialization known to Buckminster. These materializations does not have to be in an Eclipse project at the moment.
The Unknown denotes what to do when Buckminster finds that the location intended for materialization is not empty although it is not previously known. The setting is one of "FAIL". "OVERWRITE", or "REUSE". In a build scenario where repeatability is very strict you would probably select the "FAIL" mode to make sure you are notified with an error if things are not clean when you start materializing. "OVERWRITE" means that the area is cleared and a new fresh copy is matialized. Finally, "REUSE" means that materialization should not take place, and the material already in place is trusted to be the content you want. This is a typical case during development if you are also using tools outside of Eclipse, and work directly in a view provided by the CM system.
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.
Component Query might have its own properties.
Figure: Screenshot of the Eclipse Component Query Editor - Properties Tab
Component Query might be documented.
At the bottom there are controls that allows you to specify how resolvement should take place.
'Resolve Immediately' means that all component dependecies 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 resolvement 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 occured in the middle of the resolvement.
A "Resolve to Wizard" starts a resolvement process and guides you through the process using a wizard. Nothing is acutally 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.
Resolve and Materialize, starts the resolvement 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 througout the resolvement process so the overrides will reach the leafs if their component names are matched by an Advisor Node.
It is really difficult to correctly document the functionality behind the "Use Known/Unknown" - here is an attempt to document the various cases for the settings.
|case||Use Existing Checked||Known in Meta Data||Exists||Resolved via RMAP||Comment|
|1||N||N||N||Y||m-mode ignored, not an issue as it is not known, and does not exist|
|2||N||Y||N||Y||Known in meta data, but deleted - what happens?|
|3||N||Y||Y||Y||m-mode ignored, the materialization was known, and will be used (if the resolve/BOM lists this component).|
|4||N||N||Y||Y||m-mode in effect, not known in meta data, but existed anyway|
|5||Y||N||N||Y||same as case 1 as it was not known and did not exist|
|6||Y||Y||N||N||exists in meta data, but is deleted. Resolve should skip it, but it does not exists, what happens?|
|7||Y||Y||Y||N||Not resolved as it is known and exists, m-mode ignored.|
|8||Y||N||Y||Y||Resolved as it is not known, m-mode in effect since when materializing something is found where the materialization is supposed to be stored.|
Please help me out - is this table correct. What happens in cases 2 and 6? Is this an error? Or, does Buckminster treat this as if it had not known the component in the first place and silently resolve/handle the issue?