Skip to main content
Jump to: navigation, search

Difference between revisions of "Component Query (Buckminster)"

Line 18: Line 18:
  
 
{{BlueBox|'''Tip: Use different query files for different scenarios.'''
 
{{BlueBox|'''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.}}
+
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==
 
==Request==
Line 29: Line 29:
  
 
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 [[Version Type (Buckminster)|Version Type]].
+
There is also a drop down to allow you to select a [[Version Type (Buckminster)|Version Type]].
  
 
==URL to Resource Map==
 
==URL to Resource Map==
  
This is the URL to the resourcemap to use for the resolvement.  
+
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:<br>
 
For example the http, and file protocols are supported. Also the cvs protocol can be used. It has the following format:<br>
Line 48: Line 48:
  
 
<br>
 
<br>
{{Figure|image=BuckminsterCQueryEditorANodes.png|title=Screenshot of the Eclipse Component Query Editor - Advisor Nodes Tab}}
+
{{Figure|image=BuckminsterCQueryEditorANodes.png|title=Screen shot of the Eclipse Component Query Editor - Advisor Nodes Tab}}
  
 
===Name Pattern===
 
===Name Pattern===
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 resolved, and its dependencies will not be included in the resolution.
+
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===
 
===Project Name Mapping===
Line 67: Line 67:
 
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 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.
+
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===
 
===Version Designator/Type Override===
Line 74: Line 74:
  
 
==Properties==
 
==Properties==
Component Query might have its own properties.
+
In addition to appointing a properties file, a Component Query can also have embedded properties.
 
<br>
 
<br>
 
{{Figure|image=BuckminsterCQueryEditorProperties.png|title=Screenshot of the Eclipse Component Query Editor - Properties Tab}}
 
{{Figure|image=BuckminsterCQueryEditorProperties.png|title=Screenshot of the Eclipse Component Query Editor - Properties Tab}}
  
 
==Documentation==
 
==Documentation==
Component Query might be documented.
+
The Component Query might be described in detail using the documentation tab.
 
<br>
 
<br>
 
{{Figure|image=BuckminsterCQueryEditorDocumentation.png|title=Screenshot of the Eclipse Component Query Editor - Documentation Tab}}
 
{{Figure|image=BuckminsterCQueryEditorDocumentation.png|title=Screenshot of the Eclipse Component Query Editor - Documentation Tab}}
Line 90: Line 90:
 
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 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 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|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=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).
 
Resolve and Materialize, starts the resolution process and materializes the component and all dependencies (recursively).
Line 100: Line 100:
 
==Scope of the Query==
 
==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.
 
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.
 
 
{| {{BMTableStyle}}
 
|+ {{BMTableCaptionStyle}} | Use Known/Unknown combinations
 
|- {{BMTHStyle}}
 
!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?
 
 
[[Category:Buckminster]]
 
[[Category:Buckminster]]
 
[[Category:Buckminster Key Concepts]]
 
[[Category:Buckminster Key Concepts]]
 
[[Category:Buckminster Documentation]]
 
[[Category:Buckminster Documentation]]
 
<noinclude>
 
<noinclude>

Revision as of 02:56, 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 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.


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

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

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

Copyright © Eclipse Foundation, Inc. All Rights Reserved.