Skip to main content

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.

Jump to: navigation, search

Difference between revisions of "Component Query (Buckminster)"

Line 1: Line 1:
 
{{Backlink|Buckminster Project}}
 
{{Backlink|Buckminster Project}}
A [[Buckminster Component Query|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.
+
A [[Component Query (Buckminster)|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.
  
 
<noinclude>
 
<noinclude>
Line 21: Line 21:
  
 
==Request==
 
==Request==
{{:Buckminster Component Request}}
+
{{:Component Request (Buckminster)}}
 
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.
 
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 [[Buckminster Version Designator|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.
+
There is a convenient drop down to help in specifying the [[Version Designator (Buckminster)|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.
+
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.
 
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 [[Buckminster Version Type|Version Type]].
+
There is also a drop down to allwo you to select a [[Version Type (Buckminster)|Version Type]].
  
 
==URL to Resource Map==
 
==URL to Resource Map==
Line 40: Line 40:
 
<code>cvs://anonymous@dev.eclipse.org/org.eclipse.buckminster/org.eclipse.buckminster/demo/rmaps/demo.rmap?repository=/cvsroot/technology&method=pserver</code>
 
<code>cvs://anonymous@dev.eclipse.org/org.eclipse.buckminster/org.eclipse.buckminster/demo/rmaps/demo.rmap?repository=/cvsroot/technology&method=pserver</code>
  
Please see [[Buckminster Resource Map|Resource Map]] for more information.
+
Please see [[Resource Map (Buckminster)|Resource Map]] for more information.
  
 
==Advisor Nodes==
 
==Advisor Nodes==
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.
+
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.
 
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.
Line 57: Line 57:
  
 
===Skip Component===
 
===Skip Component===
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.
+
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 resolved, and its dependencies will not be included in the resolution.
  
 
===Project Name Mapping===
 
===Project Name Mapping===
Line 68: Line 68:
  
 
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.
 
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.
 
===Use Known/Unknown===
 
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.
 
{{BlueBox|'''Tip: Use more distincitve patterns if rule needed for some components'''<br>
 
Remember that 'Use Known/Unknown' just as Special Requirements apply only to components that are matched against the regular expression in the Advisor Node. If you need different settings for components that are matched by the same rule, you need to create a new Advisor Node and make the patterns more distincive.
 
}}
 
  
 
===Version Designator/Type Override===
 
===Version Designator/Type Override===
Line 96: Line 84:
  
 
==Materialization Controls==
 
==Materialization Controls==
At the bottom there are controls that allows you to specify how resolvement should take place.
+
At the bottom there are controls that allows you to specify how resolution 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.
+
'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 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 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 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.
 
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.
Line 106: Line 94:
 
{{Figure|image=BuckminsterCQueryWizard.png|title=Screenshot of the Component Query Wizard as it has a resolved a Component Query for the Buckminster project itself}}
 
{{Figure|image=BuckminsterCQueryWizard.png|title=Screenshot of the Component Query Wizard as it has a resolved a Component Query for the Buckminster project itself}}
  
Resolve and Materialize, starts the resolvement process and materializes the component and all dependencies (recursively).
+
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.
 
''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==
 
==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.
+
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.
  
 
=ISSUES=
 
=ISSUES=

Revision as of 03:51, 1 June 2007

< To: Buckminster Project
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.


Component Query Editor

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

BuckminsterCQueryEditorMain.png
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 differnet 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 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:
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.


BuckminsterCQueryEditorANodes.png
Figure: Screenshot 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 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 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 sourcecode (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

Component Query might have its own properties.

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

Documentation

Component Query might be documented.

BuckminsterCQueryEditorDocumentation.png
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 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.

BuckminsterCQueryWizard.png
Figure: Screenshot 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.

ISSUES

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.

Use Known/Unknown combinations
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?

Back to the top