View source for Hello XML World Example (Buckminster)

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

{{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: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==
* Make sure you have Subclipse '''OR''' Subversive installed (not both). You can find their respective update sites here:
** <nowiki>http://subclipse.tigris.org/update_1.2.x</nowiki>
** <nowiki>http://www.polarion.org/projects/subversive/download/1.1/update-site</nowiki>
* 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:
** 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:
** http://www.eclipse.org/buckminster/samples/queries/demo.cquery	 

That will start the Buckminster materialization of the project.

==The CQUERY==	 
The CQuery looks like this:

<pre>
<?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>
</pre>

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 <tt>org.demo.hello.xml.world</tt>, that it is a plugin and that it follows the OSGi versioning scheme.

For more details see [[Buckminster Component Query|CQUERY]]

==The RMAP==
This is what the RMAP looks like:
<pre>
<?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>
</pre>

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 <tt>org.demo.</tt> 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 <tt>buckminster.component</tt> which contains the name of the component being matched.
** The provider will provide source (source=true).

==The CSPEC in Component <tt>org.demo.worlds</tt>==
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 [[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>
<?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>
</pre>

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 <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).
** <tt>java.binary.archives</tt> 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 <tt>org.demo.xml.provider</tt> 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 <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 <tt>org.demo.xml.provider</tt>.
<pre>
<?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>
</pre>
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 <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.
** 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>
** The products section declares that the result is called <tt>output</tt> and where the output is produced.

==Demo flow==
The following takes place when Buckminster resolves the query.

# 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 SVN provider of this RMAP is chosen (it's the only one)
## The component types <tt>eclipse.feature,osgi.bundle,buckminster</tt> will make the provider scan for certain files.
## 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 selected component type (osgi.bundle) will create a CSPEC from the manifest files.
## 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
## 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 no matching OSGi manifest is found. Instead a CSPEC that has been checked in with the component is used.
## 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
## 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 first component that becomes known to Eclipse is <tt>org.demo.worlds</tt>
## The CSPEX of the second component, <tt>org.demo.xml.provider</tt> contains a prebind action that:
### 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 <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 <tt>org.demo.xml.provider</tt> component bound to the workspace.
## Component <tt>org.demo.hello.xml.world</tt> is bound last.
## Eclipse receives a lot of events and thus, rebuilds the workspace.

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 Tutorials]]
[[Category:Buckminster Introduction]]
[[Category:Buckminster Examples]]