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 "Hello XML World Example (Buckminster)"

m (Increased indention depth of element <cs:path...>)
m (new update site link)
 
(23 intermediate revisions by 6 users not shown)
Line 3: Line 3:
 
This examples shows several Buckminster features in action. What these components actualy do when they are executed is not that interesting - there is an XML file with "worlds", there is a world producer and a class that says "hello" to worlds.
 
This examples shows several Buckminster features in action. What these components actualy do when they are executed is not that interesting - there is an XML file with "worlds", there is a world producer and a class that says "hello" to worlds.
  
{{BlueBox|If you want to see the difference between setting up this example project manually, and how it works when running Buckminster, see the usage scenario [[Sharing a Project (Buckminster)|Sharing a Project]].}}
+
{{BlueBox|If you want to see the difference between setting up this example project manually, and how it works when running Buckminster, see the usage scenario [[Sharing a Project (Buckminster)|Sharing a Project]].}}
 
+
Here is an overview of what is going on:
+
<p align="center">[[Image:helloDemo.gif]]</p>
+
 
+
* The A component is called <tt>org.demo.hello.xml.world</tt>
+
** It lives in a CVS repository
+
** It is an Eclipse plugin - it has some meta data
+
** A has a dependency on B
+
* The B component is called <tt>org.demo.xml.provider</tt>
+
** It lives in a CVS repository
+
** It is an Eclipse plugin - it has some meta data
+
** It requires two jars; the jar in component D, and a jar that is built by component C.
+
* Component C is called <tt>org.demo.worlds</tt>
+
** It lives in a CVS repository
+
** Although it is an Eclipse project, it is <b>not</b> an Eclipse plugin.
+
* Component D is a sax parser called <tt>se.tada.util.sax</tt>
+
** It lives in binary form in the maven repository at Ibiblio
+
  
 +
Here is an overview of what is going on:
 +
<p align="center">[[Image:Buckminster_HelloDemo.gif]]</p>
 +
 +
* Component <tt>org.demo.hello.xml.world</tt>
 +
** lives in a SVN repository
 +
** is an Eclipse plugin - it has some meta data
 +
** has a dependency on <tt>org.demo.xml.provider</tt>
 +
* Component <tt>org.demo.xml.provider</tt>
 +
** lives in a SVN repository
 +
** is an Eclipse plugin - it has some meta data
 +
** requires two jars; the <tt>se.tada/tada-sax.jar</tt>, and a jar that is built by component <tt>org.demo.worlds</tt>.
 +
* Component <tt>org.demo.worlds</tt>
 +
** lives in a SVN repository
 +
** although it is an Eclipse project, it is <b>not</b> an Eclipse plugin.
 +
* Component <tt>se.tada.util.sax</tt>
 +
** lives in binary form in the global maven repository
 +
 
==How to run the example==
 
==How to run the example==
* Make sure you have the latest version of Buckminster
+
* Make sure you have Subclipse '''OR''' Subversive installed (not both). You can find their respective update sites here:
* Make sure you have the Buckminster Maven plugin installed as this demo fetches things from a Maven repository
+
** <nowiki>http://subclipse.tigris.org/update_1.2.x</nowiki>
* If you are on windows Use the File > Open dialog in Eclipse, and enter this URL:
+
** <nowiki>http://www.polarion.org/projects/subversive/download/1.1/update-site</nowiki>
** http://www.eclipse.org/buckminster/samples/queries/demo.cquery
+
* Install Buckminster from the Update Manager using our update site at <nowiki>http://download.eclipse.org/tools/buckminster/updates-3.7</nowiki>. Include the following features:
* If you are on Linux or a Unix platform then:
+
** Core
** Download and save the demo.cquery file from the URL above. You can use your favourite web browser or the command below:
+
** Maven support
*** wget  http://www.eclipse.org/buckminster/samples/queries/demo.cquery
+
** PDE support
** Use the File->Open dialog in eclipse to open the demo.cquery file
+
** Subclipse support '''OR''' Subversive support (not both).
 +
* Use the ''File'' > ''Open a Component Query...'' dialog in Eclipse, and enter this URL:
 +
** http://www.eclipse.org/buckminster/samples/queries/demo.cquery
  
 
That will start the Buckminster materialization of the project.
 
That will start the Buckminster materialization of the project.
  
==The CQUERY==
+
==The CQUERY==
 
The CQuery looks like this:
 
The CQuery looks like this:
 +
 
<pre>
 
<pre>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>
<cq:componentQuery xmlns:cq="http://www.eclipse.org/buckminster/CQuery-1.0"
+
<cq:componentQuery
resourceMap="http://www.eclipse.org/buckminster/samples/rmaps/demo.rmap">
+
  xmlns:cq="http://www.eclipse.org/buckminster/CQuery-1.0"
     <cq:rootRequest name="org.demo.hello.xml.world" category="plugin" versionType="OSGi"/>
+
  resourceMap="http://www.eclipse.org/buckminster/samples/rmaps/demo.rmap">
 +
     <cq:rootRequest
 +
      name="org.demo.hello.xml.world"
 +
      componentType="osgi.bundle" versionType="OSGi"/>
 
</cq:componentQuery>
 
</cq:componentQuery>
 
</pre>
 
</pre>
Line 55: Line 61:
 
<pre>
 
<pre>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>
<rm:rmap
+
<rmap
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+
xmlns="http://www.eclipse.org/buckminster/RMap-1.0"
    xmlns:rm="http://www.eclipse.org/buckminster/RMap-1.0"
+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:mp="http://www.eclipse.org/buckminster/MavenProvider-1.0"
+
xmlns:mp="http://www.eclipse.org/buckminster/MavenProvider-1.0"
    xmlns:bc="http://www.eclipse.org/buckminster/Common-1.0">
+
xmlns:bc="http://www.eclipse.org/buckminster/Common-1.0">
  
    <rm:searchPath name="default">
+
  <searchPath name="default">
        <rm:provider readerType="cvs" componentType="eclipse-project" mutable="true" source="true">
+
    <provider
            <rm:uri format=":pserver:anonymous@dev.eclipse.org:/cvsroot/technology,org.eclipse.buckminster/org.eclipse.buckminster/demo/{0}">
+
    readerType="svn"
                <bc:propertyRef key="buckminster.component" />
+
    componentTypes="eclipse.feature,osgi.bundle,buckminster"
            </rm:uri>
+
    source="true">
        </rm:provider>
+
      <uri
    </rm:searchPath>
+
      format="svn://dev.eclipse.org/svnroot/tools/org.eclipse.buckminster/trunk/org.eclipse.buckminster/demo/{0}">
 +
        <bc:propertyRef key="buckminster.component" />
 +
      </uri>
 +
    </provider>
 +
  </searchPath>
  
    <rm:searchPath name="maven">
+
  <locator searchPathRef="default" pattern="^org\.demo\..*" />
        <rm:provider xsi:type="mp:MavenProvider" readerType="maven" componentType="maven" mutable="false" source="false">
+
  <redirect href="http://www.eclipse.org/buckminster/samples/rmaps/dogfood2.rmap" pattern=".*"/>
            <rm:uri format="http://www.ibiblio.org/maven"/>
+
</rmap>
            <mp:mappings>
+
                <mp:entry name="se.tada.util.sax" groupId="se.tada" artifactId="tada-sax"/>
+
            </mp:mappings>
+
        </rm:provider>
+
    </rm:searchPath>
+
 
+
    <rm:locator searchPathRef="maven" pattern="^se\.tada\..*" />
+
    <rm:locator searchPathRef="default" pattern="^org\.demo\..*" />
+
 
+
</rm:rmap>
+
 
</pre>
 
</pre>
  
 
This is what the RMAP XML means:
 
This is what the RMAP XML means:
 
* The 6 first lines declare the name spaces and syntax of the rmap and the repository providers needed.
 
* The 6 first lines declare the name spaces and syntax of the rmap and the repository providers needed.
* Below that you see two major elements declaring search paths, the first is called default, and the second is called maven.
+
* Below that you see a search path element called default.
* Continue down and you see two locator declarations...
+
* Continue down and you see a locator and a redirect declaration. The pattern of those declarations are matched in the order that they are declared. The first match wins and the match stops.
** the first states that if a component name starts with <tt>se.tada.</tt> then the maven search path should be used.
+
** the locator states that if a component name starts with <tt>org.demo.</tt> then the search path named "default" in this rmap should be used.
** and the second locator states that if the name starts with <tt>org.demo.</tt> then the default path should be used.
+
** the redirect states that all other names should be delegated to another rmap (and its locators and redirects).
* Back to the paths:
+
* Back to the default searchPath:
** The default path:
+
** A provider for a Subversion type repository is declared with a URL that, after parameter substitution, will point to the component root.
*** The default path declares that the repository is in CVS and that what we find is an eclipse project
+
** This name is obtained from the preset property <tt>buckminster.component</tt> which contains the name of the component being matched.
*** We do not need to commit changes back (mutable=false), and we do not want source (source=false).
+
** The provider will provide source (source=true).
*** The URI to the CVS repository is stated next
+
*** This URI ends with the name of the component. This name is obtained from the preset property <tt>buckminster.component</tt> which contains the name of the component being matched.
+
** The maven path:
+
*** The maven path declares that it uses a maven provider and a reader type of maven and that the component type is also a maven component. Further the mutable=false says that we are not interested in committing any changes back to the repository, and source=false says that we are not interested in source.
+
*** A URI to the maven repository at Ibiblio is declared
+
*** A mapping that translates the component name into what the actual file on Ibiblio is called is then declared (i.e. mapping <tt>se.tada.util.sax</tt> to <tt>tada-sax</tt>).
+
  
==The CSPEC in Component C==
+
==The CSPEC in Component <tt>org.demo.worlds</tt>==
Since component C - <tt>org.demo.worlds</tt> is not a plugin and thus lack meta data that describes its dependencies, and  
+
Since this is not a plugin and thus lack meta data that describes its dependencies, and  
 
how to produce it, we need to add this information.  
 
how to produce it, we need to add this information.  
We decide to use Buckminster's [[Buckminster Component Specification|CSPEC]] XML language. This is what we place in a file called <tt>buckminster.cspec</tt> inside component C:
+
We decide to use Buckminster's [[Buckminster Component Specification|CSPEC]] XML language. This is what we place in a file called <tt>buckminster.cspec</tt> inside component <tt>org.demo.worlds</tt>:
 
<pre>
 
<pre>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<cs:cspec xmlns:cs="http://www.eclipse.org/buckminster/CSpec-1.0" name="org.demo.worlds">
 
<cs:cspec xmlns:cs="http://www.eclipse.org/buckminster/CSpec-1.0" name="org.demo.worlds">
    <cs:artifacts>
+
  <cs:artifacts>
    <cs:public name="source" path="src/"/>
+
    <cs:public name="source" path="src/"/>
    </cs:artifacts>
+
  </cs:artifacts>
    <cs:actions>
+
  <cs:actions>
        <cs:public name="java.binary.archives" actor="ant">
+
    <cs:public name="java.binary.archives" actor="ant">
            <cs:actorProperties>
+
      <cs:actorProperties>
                <cs:property key="buildFile" value="make/build.xml"/>
+
        <cs:property key="buildFile" value="make/build.xml"/>
            </cs:actorProperties>
+
      </cs:actorProperties>
            <cs:prerequisites alias="input">
+
      <cs:prerequisites alias="input">
                <cs:local attribute="eclipse.build"/>
+
        <cs:attribute name="eclipse.build"/>
            </cs:prerequisites>
+
      </cs:prerequisites>
            <cs:products alias="output" base="bin/jars/">
+
      <cs:products alias="output" base="${buckminster.home}/bin/jars/">
                <cs:path path="worlds.jar"/>
+
        <cs:path path="worlds.jar"/>
            </cs:products>
+
      </cs:products>
        </cs:public>
+
    </cs:public>
        <cs:private name="eclipse.build">
+
    <cs:private name="eclipse.build" actor="eclipse.build">
            <cs:prerequisites>
+
      <cs:prerequisites>
                <cs:local attribute="source"/>
+
        <cs:attribute name="source"/>
            </cs:prerequisites>
+
      </cs:prerequisites>
            <cs:products base="bin/classes/">
+
      <cs:products base="${buckminster.home}/bin/classes/">
                <cs:path path="."/>
+
        <cs:path path="."/>
            </cs:products>
+
      </cs:products>
        </cs:private>
+
    </cs:private>
    </cs:actions>
+
  </cs:actions>
    <cs:groups>
+
  <cs:groups>
    <cs:public name="java.binaries">
+
    <cs:public name="java.binaries">
    <cs:local attribute="eclipse.build"/>
+
      <cs:attribute name="eclipse.build"/>
    </cs:public>
+
    </cs:public>
    </cs:groups>
+
  </cs:groups>
 
</cs:cspec>
 
</cs:cspec>
 
</pre>
 
</pre>
Line 143: Line 137:
 
* First two lines declare that this is XML, and that it follows the CSPEC format, and it describes a component called org.demo.worlds
 
* First two lines declare that this is XML, and that it follows the CSPEC format, and it describes a component called org.demo.worlds
 
* Next section lists the component attributes that are artifacts (i.e. a static declaration of paths).
 
* Next section lists the component attributes that are artifacts (i.e. a static declaration of paths).
** There is only one declaration, a public attribute called <tt>src</tt> that is mapped to a directory called <tt>src</tt>. Notice that the name ends with a slash to denote that we refer to the directory.
+
** There is only one declaration, a public attribute called <tt>source</tt> that is mapped to a directory called <tt>src</tt>. Notice that the name ends with a slash to denote that we refer to the directory.
 
* Next section lists the component attributes that are implemented as actions (i.e. computed attribute values).
 
* Next section lists the component attributes that are implemented as actions (i.e. computed attribute values).
 
** <tt>java.binary.archives</tt> is the first
 
** <tt>java.binary.archives</tt> is the first
Line 149: Line 143:
 
*** Then there is one pre-requisite - the local attribute eclipse.build is needed before this action can execute.
 
*** Then there is one pre-requisite - the local attribute eclipse.build is needed before this action can execute.
  
 
+
==The CSPEX in the <tt>org.demo.xml.provider</tt> Component==
==The CSPEX in the B Component==
+
The component meta data is created from the information in the Eclipse plug-in. But there are things we want to add that can not
The B components component meta data is created from the information in the Eclipse plug-in. But there are things we want to add that can not
+
 
be declared in the regular plug-in meta data. Buckminster makes it possible to extend the generated CSPEC by adding a file <tt>buckminster.cspex</tt>. This file follows the CSPEC format. In this example this is straight forward as we are only adding things.
 
be declared in the regular plug-in meta data. Buckminster makes it possible to extend the generated CSPEC by adding a file <tt>buckminster.cspex</tt>. This file follows the CSPEC format. In this example this is straight forward as we are only adding things.
Here is the content of the CSPEX file for component B (<tt>org.demo.xml.provider</tt>).
+
Here is the content of the CSPEX file for component <tt>org.demo.xml.provider</tt>.
 
<pre>
 
<pre>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>
<cse:cspecExtension
+
<cs:cspecExtension
    xmlns:cse="http://www.eclipse.org/buckminster/CSpecExt-1.0"
+
  xmlns:com="http://www.eclipse.org/buckminster/Common-1.0"
    xmlns:com="http://www.eclipse.org/buckminster/Common-1.0"
+
  xmlns:cs="http://www.eclipse.org/buckminster/CSpec-1.0">
    xmlns:cs="http://www.eclipse.org/buckminster/CSpec-1.0">
+
  <cs:dependencies>
 +
    <cs:dependency name="org.demo.worlds"/>
 +
    <cs:dependency name="se.tada/tada-sax"  versionDesignator="1.0.0" versionType="OSGi"/>
 +
  </cs:dependencies>
 +
 
 +
  <cs:actions>
 +
 
 +
    <cs:public name="buckminster.prebind" actor="ant">
 +
 
 +
      <cs:actorProperties>
 +
        <cs:property key="buildFile" value="make/prebind.xml" />
 +
      </cs:actorProperties>
 +
 
 +
      <cs:prerequisites>
 +
        <cs:attribute component="se.tada/tada-sax" alias="tada-sax.jar" name="java.binary.archives"/>
 +
        <cs:attribute component="org.demo.worlds" alias="worlds.jar" name="java.binary.archives"/>
 +
      </cs:prerequisites>
  
    <cs:dependencies>
+
      <cs:products alias="output" base="${buckminster.home}">
        <cs:dependency name="org.demo.worlds"/>
+
         <cs:path path="jars/" />
         <cs:dependency name="se.tada.util.sax"  versionDesignator="1.0.0" versionType="OSGi"/>
+
      </cs:products>
    </cs:dependencies>
+
  
     <cs:actions>
+
     </cs:public>
        <cs:private name="buckminster.prebind" actor="ant">
+
   
            <cs:actorProperties>
+
  </cs:actions>
                <cs:property key="buildFile" value="make/prebind.xml" />
+
    </cs:actorProperties>
+
    <cs:prerequisites>
+
                <cs:external component="se.tada.util.sax" alias="tada-sax.jar" attribute="java.binary.archives"/>
+
                <cs:external component="org.demo.worlds" alias="worlds.jar" attribute="java.binary.archives"/>
+
            </cs:prerequisites>
+
            <cs:products alias="output">
+
                <cs:path path="jars/" />
+
            </cs:products>
+
        </cs:private>
+
    </cs:actions>
+
  
</cse:cspecExtension>
+
</cs:cspecExtension>
 
</pre>
 
</pre>
 
This extension works as follows:
 
This extension works as follows:
* Lines 1-5 is the XML stuff and declaration of namespaces. Note the use of a cspecExtension element as the top most element.  
+
* Lines 1-4 is the XML stuff and declaration of namespaces. Note the use of a cspecExtension element as the top most element.  
* Next, two component dependencies are listed, on the component <tt>org.demo.worlds</tt>, and on the tada sax-parser <tt>se.tada.util.sax</tt>.
+
* Next, two component dependencies are listed, on the component <tt>org.demo.worlds</tt> (a plugin ("osgi.bundle")), and on the tada sax-parser <tt>se.tada/tada-sax</tt>.
 
* The following actions section declares a private "prebind" action - this action kicks in before the component content is bound to the Eclipse workspace. As you can see, the action is an ant action, and it uses a make/prebind.xml file with the instructions for the build.
 
* The following actions section declares a private "prebind" action - this action kicks in before the component content is bound to the Eclipse workspace. As you can see, the action is an ant action, and it uses a make/prebind.xml file with the instructions for the build.
 
** There are two pre-requisites - on the sax parser, and on a jar file called <tt>worlds-jar</tt> that is obtained from the attribute <tt>java.binary.archives</tt> in the component <tt>org.demo.worlds</tt>
 
** There are two pre-requisites - on the sax parser, and on a jar file called <tt>worlds-jar</tt> that is obtained from the attribute <tt>java.binary.archives</tt> in the component <tt>org.demo.worlds</tt>
Line 195: Line 192:
 
# Resolving the CSPEC for all components
 
# Resolving the CSPEC for all components
 
## The name of the top component in the CQUERY is resolved to the default searchPath in the RMAP.
 
## The name of the top component in the CQUERY is resolved to the default searchPath in the RMAP.
## The CVS provider of this RMAP is chosen (it's the only one)
+
## The SVN provider of this RMAP is chosen (it's the only one)
## The eclipse.project componentType will obtain the ProjectDescriptor (the .project) from the eclipse project.
+
## The component types <tt>eclipse.feature,osgi.bundle,buckminster</tt> will make the provider scan for certain files.
## From the natures of that descriptor, it will conclude that the component is a plugin.
+
## Components that contain a <tt>meta-inf/manifest.mf</tt> with a specific property will considered OSGi bundles (eclipse plug-ins in this case)
## The component type will use a PluginBuilder to create a CSPEC from the plugin manifest files.
+
## The selected component type (osgi.bundle) will create a CSPEC from the manifest files.
## This CSPEC will contain a dependency to the org.demo.xml.provider component.
+
## This CSPEC will contain a dependency to the <tt>org.demo.xml.provider</tt> component.
 
## Buckminster now resolves that component in the exact same #1 to #6
 
## Buckminster now resolves that component in the exact same #1 to #6
## The CSPEC from org.demo.xml.provider is augmented with a CSPEC extension (CSPEX) that adds the jar dependencies (since those cannot be fully expressed in the plugin manifest)
+
## The CSPEC from <tt>org.demo.xml.provider</tt> is augmented with a CSPEC extension (CSPEX) that adds the jar dependencies (since those cannot be fully expressed in the plugin manifest)
## The first jar dependency is resolved using the same provider as before but the ProjectDescriptor has no plugin nature this time so the CSPEC that has been checked in with the component instead.
+
## The first jar dependency is resolved using the same provider as before but the no matching OSGi manifest is found. Instead a CSPEC that has been checked in with the component is used.
## The second jar is resolved using the maven search path and the maven repository.
+
## When resolving the <tt>se.tada/tada-sax</tt> component, a redirect in the RMAP delegates to another RMAP.
 +
## The other RMAP will match the jar to a maven search path and the global maven repository.
 
# Materializing and binding the components
 
# Materializing and binding the components
 
## All components are copied (by Buckminster) to the local disk using the chosen providers.
 
## All components are copied (by Buckminster) to the local disk using the chosen providers.
 
## The bind phase starts and components are bound in dependency order.
 
## The bind phase starts and components are bound in dependency order.
## The first component that becomes known to Eclipse is org.demo.worlds (i.e. C)
+
## The first component that becomes known to Eclipse is <tt>org.demo.worlds</tt>
## The CSPEX of the second component, org.demo.xml.provider (i.e. B) contains a prebind action that:
+
## The CSPEX of the second component, <tt>org.demo.xml.provider</tt> contains a prebind action that:
### Builds component C to a jar and copies that jar into the <tt>jars</tt> directory of component B.
+
### Builds component <tt>org.demo.worlds</tt> to a jar and copies that jar into the <tt>jars</tt> directory of component <tt>org.demo.xml.provider</tt>.
### Copies the component D from a cache location into the <tt>jars</tt> directory of component B.
+
### Copies the component <tt>se.tada/tada-sax</tt> from a cache location into the <tt>jars</tt> directory of component <tt>org.demo.xml.provider</tt>.
## Once the prebind actions have completed, the B component bound to the workspace.
+
## Once the prebind actions have completed, the <tt>org.demo.xml.provider</tt> component bound to the workspace.
## Component A is bound last.
+
## Component <tt>org.demo.hello.xml.world</tt> is bound last.
 
## Eclipse receives a lot of events and thus, rebuilds the workspace.
 
## Eclipse receives a lot of events and thus, rebuilds the workspace.
  
Note that the tada-sax (i.e. D) was never bound to the workspace since it is not an Eclipse project.
+
Note that the <tt>se.tada/tada-sax</tt> was never bound to the workspace since it is not an Eclipse project.
  
 
[[Category:Buckminster]]
 
[[Category:Buckminster]]
 +
[[Category:Buckminster Tutorials]]
 +
[[Category:Buckminster Introduction]]
 
[[Category:Buckminster Examples]]
 
[[Category:Buckminster Examples]]

Latest revision as of 19:31, 7 December 2011

< To: Buckminster Project

Overview of the Example

This examples shows several Buckminster features in action. What these components actualy do when they are executed is not that interesting - there is an XML file with "worlds", there is a world producer and a class that says "hello" to worlds.

If you want to see the difference between setting up this example project manually, and how it works when running Buckminster, see the usage scenario Sharing a Project.

Here is an overview of what is going on:

Buckminster HelloDemo.gif

  • Component org.demo.hello.xml.world
    • lives in a SVN repository
    • is an Eclipse plugin - it has some meta data
    • has a dependency on org.demo.xml.provider
  • Component org.demo.xml.provider
    • lives in a SVN repository
    • is an Eclipse plugin - it has some meta data
    • requires two jars; the se.tada/tada-sax.jar, and a jar that is built by component org.demo.worlds.
  • Component org.demo.worlds
    • lives in a SVN repository
    • although it is an Eclipse project, it is not an Eclipse plugin.
  • Component se.tada.util.sax
    • lives in binary form in the global maven repository

How to run the example

  • Make sure you have Subclipse OR Subversive installed (not both). You can find their respective update sites here:
    • http://subclipse.tigris.org/update_1.2.x
    • http://www.polarion.org/projects/subversive/download/1.1/update-site
  • Install Buckminster from the Update Manager using our update site at http://download.eclipse.org/tools/buckminster/updates-3.7. Include the following features:
    • Core
    • Maven support
    • PDE support
    • Subclipse support OR Subversive support (not both).
  • Use the File > Open a Component Query... dialog in Eclipse, and enter this URL:

That will start the Buckminster materialization of the project.

The CQUERY

The CQuery looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<cq:componentQuery
  xmlns:cq="http://www.eclipse.org/buckminster/CQuery-1.0"
  resourceMap="http://www.eclipse.org/buckminster/samples/rmaps/demo.rmap">
    <cq:rootRequest
      name="org.demo.hello.xml.world"
      componentType="osgi.bundle" versionType="OSGi"/>
</cq:componentQuery>

This is what the XML in the CQUERY means:

  • The first two lines are the usual XML incantations, the first two indicating that this is XML, and this is the syntax of the XML - i.e. CQuery-1.0 and the namespace is called "cq".
  • The third line declares where the resource map to use when resolving components is found (we will look at the resource map next).
  • Next line states that the wanted (root) component is called org.demo.hello.xml.world, that it is a plugin and that it follows the OSGi versioning scheme.

For more details see CQUERY

The RMAP

This is what the RMAP looks like:

<?xml version="1.0" encoding="UTF-8"?>
<rmap
 xmlns="http://www.eclipse.org/buckminster/RMap-1.0"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:mp="http://www.eclipse.org/buckminster/MavenProvider-1.0"
 xmlns:bc="http://www.eclipse.org/buckminster/Common-1.0">

  <searchPath name="default">
    <provider
     readerType="svn"
     componentTypes="eclipse.feature,osgi.bundle,buckminster"
     source="true">
      <uri
       format="svn://dev.eclipse.org/svnroot/tools/org.eclipse.buckminster/trunk/org.eclipse.buckminster/demo/{0}">
        <bc:propertyRef key="buckminster.component" />
      </uri>
    </provider>
  </searchPath>

  <locator searchPathRef="default" pattern="^org\.demo\..*" />
  <redirect href="http://www.eclipse.org/buckminster/samples/rmaps/dogfood2.rmap" pattern=".*"/>
</rmap>

This is what the RMAP XML means:

  • The 6 first lines declare the name spaces and syntax of the rmap and the repository providers needed.
  • Below that you see a search path element called default.
  • Continue down and you see a locator and a redirect declaration. The pattern of those declarations are matched in the order that they are declared. The first match wins and the match stops.
    • the locator states that if a component name starts with org.demo. then the search path named "default" in this rmap should be used.
    • the redirect states that all other names should be delegated to another rmap (and its locators and redirects).
  • Back to the default searchPath:
    • A provider for a Subversion type repository is declared with a URL that, after parameter substitution, will point to the component root.
    • This name is obtained from the preset property buckminster.component which contains the name of the component being matched.
    • The provider will provide source (source=true).

The CSPEC in Component org.demo.worlds

Since this is not a plugin and thus lack meta data that describes its dependencies, and how to produce it, we need to add this information. We decide to use Buckminster's CSPEC XML language. This is what we place in a file called buckminster.cspec inside component org.demo.worlds:

<?xml version="1.0" encoding="UTF-8"?>
<cs:cspec xmlns:cs="http://www.eclipse.org/buckminster/CSpec-1.0" name="org.demo.worlds">
  <cs:artifacts>
    <cs:public name="source" path="src/"/>
  </cs:artifacts>
  <cs:actions>
    <cs:public name="java.binary.archives" actor="ant">
      <cs:actorProperties>
        <cs:property key="buildFile" value="make/build.xml"/>
      </cs:actorProperties>
      <cs:prerequisites alias="input">
        <cs:attribute name="eclipse.build"/>
      </cs:prerequisites>
      <cs:products alias="output" base="${buckminster.home}/bin/jars/">
        <cs:path path="worlds.jar"/>
      </cs:products>
    </cs:public>
    <cs:private name="eclipse.build" actor="eclipse.build">
      <cs:prerequisites>
        <cs:attribute name="source"/>
      </cs:prerequisites>
      <cs:products base="${buckminster.home}/bin/classes/">
        <cs:path path="."/>
      </cs:products>
    </cs:private>
  </cs:actions>
  <cs:groups>
    <cs:public name="java.binaries">
      <cs:attribute name="eclipse.build"/>
    </cs:public>
  </cs:groups>
</cs:cspec>

This meta data does the following:

  • First two lines declare that this is XML, and that it follows the CSPEC format, and it describes a component called org.demo.worlds
  • Next section lists the component attributes that are artifacts (i.e. a static declaration of paths).
    • There is only one declaration, a public attribute called source that is mapped to a directory called src. Notice that the name ends with a slash to denote that we refer to the directory.
  • Next section lists the component attributes that are implemented as actions (i.e. computed attribute values).
    • java.binary.archives is the first
      • It is implemented using an ANT action, and parameters are set
      • Then there is one pre-requisite - the local attribute eclipse.build is needed before this action can execute.

The CSPEX in the org.demo.xml.provider Component

The component meta data is created from the information in the Eclipse plug-in. But there are things we want to add that can not be declared in the regular plug-in meta data. Buckminster makes it possible to extend the generated CSPEC by adding a file buckminster.cspex. This file follows the CSPEC format. In this example this is straight forward as we are only adding things. Here is the content of the CSPEX file for component org.demo.xml.provider.

<?xml version="1.0" encoding="UTF-8"?>
<cs:cspecExtension
  xmlns:com="http://www.eclipse.org/buckminster/Common-1.0"
  xmlns:cs="http://www.eclipse.org/buckminster/CSpec-1.0">
  <cs:dependencies>
    <cs:dependency name="org.demo.worlds"/>
    <cs:dependency name="se.tada/tada-sax"  versionDesignator="1.0.0" versionType="OSGi"/>
  </cs:dependencies>

  <cs:actions>

    <cs:public name="buckminster.prebind" actor="ant">

      <cs:actorProperties>
        <cs:property key="buildFile" value="make/prebind.xml" />
      </cs:actorProperties>

      <cs:prerequisites>
        <cs:attribute component="se.tada/tada-sax" alias="tada-sax.jar" name="java.binary.archives"/>
        <cs:attribute component="org.demo.worlds" alias="worlds.jar" name="java.binary.archives"/>
      </cs:prerequisites>

      <cs:products alias="output" base="${buckminster.home}">
        <cs:path path="jars/" />
      </cs:products>

    </cs:public>
    
  </cs:actions>

</cs:cspecExtension>

This extension works as follows:

  • Lines 1-4 is the XML stuff and declaration of namespaces. Note the use of a cspecExtension element as the top most element.
  • Next, two component dependencies are listed, on the component org.demo.worlds (a plugin ("osgi.bundle")), and on the tada sax-parser se.tada/tada-sax.
  • The following actions section declares a private "prebind" action - this action kicks in before the component content is bound to the Eclipse workspace. As you can see, the action is an ant action, and it uses a make/prebind.xml file with the instructions for the build.
    • There are two pre-requisites - on the sax parser, and on a jar file called worlds-jar that is obtained from the attribute java.binary.archives in the component org.demo.worlds
    • The products section declares that the result is called output and where the output is produced.

Demo flow

The following takes place when Buckminster resolves the query.

  1. Resolving the CSPEC for all components
    1. The name of the top component in the CQUERY is resolved to the default searchPath in the RMAP.
    2. The SVN provider of this RMAP is chosen (it's the only one)
    3. The component types eclipse.feature,osgi.bundle,buckminster will make the provider scan for certain files.
    4. Components that contain a meta-inf/manifest.mf with a specific property will considered OSGi bundles (eclipse plug-ins in this case)
    5. The selected component type (osgi.bundle) will create a CSPEC from the manifest files.
    6. This CSPEC will contain a dependency to the org.demo.xml.provider component.
    7. Buckminster now resolves that component in the exact same #1 to #6
    8. The CSPEC from org.demo.xml.provider is augmented with a CSPEC extension (CSPEX) that adds the jar dependencies (since those cannot be fully expressed in the plugin manifest)
    9. The first jar dependency is resolved using the same provider as before but the no matching OSGi manifest is found. Instead a CSPEC that has been checked in with the component is used.
    10. When resolving the se.tada/tada-sax component, a redirect in the RMAP delegates to another RMAP.
    11. The other RMAP will match the jar to a maven search path and the global maven repository.
  2. Materializing and binding the components
    1. All components are copied (by Buckminster) to the local disk using the chosen providers.
    2. The bind phase starts and components are bound in dependency order.
    3. The first component that becomes known to Eclipse is org.demo.worlds
    4. The CSPEX of the second component, org.demo.xml.provider contains a prebind action that:
      1. Builds component org.demo.worlds to a jar and copies that jar into the jars directory of component org.demo.xml.provider.
      2. Copies the component se.tada/tada-sax from a cache location into the jars directory of component org.demo.xml.provider.
    5. Once the prebind actions have completed, the org.demo.xml.provider component bound to the workspace.
    6. Component org.demo.hello.xml.world is bound last.
    7. Eclipse receives a lot of events and thus, rebuilds the workspace.

Note that the se.tada/tada-sax was never bound to the workspace since it is not an Eclipse project.

Back to the top