getting-started/src/middle-tier/create-db-project.xml - virgo/org.eclipse.virgo.documentation - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
 		"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
 <section id="middle-tier.create-db-project">
 	<title>Creating the DataSource project</title>

 	<para>
 		This section describes how to use
 		the bundle project creation wizard to create a new <literal>Bundle Project</literal>. The project&rsquo;s Spring bean
 		definition files will also be created using the Spring bean configuration file creation wizard.
 	</para>
 	<section id="middle-tier.create-db-project.new-bundle-project">
 		<title>Creating a new Bundle Project</title>
 		<para>
 			Create a new project by right-clicking in the <emphasis>Package Explorer</emphasis> view and selecting
 			<menuchoice><guimenu>New</guimenu><guimenuitem>Project…</guimenuitem></menuchoice>. In the resulting
 			dialog select <menuchoice><guimenu>EclipseRT</guimenu><guimenuitem>Bundle
 			Project</guimenuitem></menuchoice> and press <emphasis>Next</emphasis>:
 		<mediaobject>
 			<imageobject role="fo">
 				<imagedata fileref="images/middle-tier/new-bundle-project.png" format="PNG" align="center" width="8cm"/>
 			</imageobject>
 			<imageobject role="html">
 				<imagedata fileref="images/middle-tier/new-bundle-project.png" format="PNG" align="center"/>
 			</imageobject>
 		</mediaobject>
 		</para>

 		<para>
 			In the <emphasis>New Bundle Project</emphasis> dialog, name the project <literal>greenpages.db</literal>.
             Choose the create the project from an existing source location and specify a location that will place the new
 			<literal>greenpages.db</literal> alongside the project skeletons that were imported into the workspace
 			earlier. If the <literal>start</literal> directory of the @greenpages@ sample is being used this will
             be <literal>$GREENPAGES_HOME/start/greenpages.db</literal> (and, <emphasis>mutatis mutandis</emphasis> on Windows).
             Click <emphasis>Next</emphasis>.
 		<mediaobject>
 			<imageobject role="fo">
 				<imagedata fileref="images/middle-tier/create-bundle-project.png" format="PNG" align="center" width="12cm"/>
 			</imageobject>
 			<imageobject role="html">
 				<imagedata fileref="images/middle-tier/create-bundle-project.png" format="PNG" align="center"/>
 			</imageobject>
 		</mediaobject>
 		</para>

 		<para>
 			In this page of the wizard, many of the <emphasis>Bundle Properties</emphasis> are already populated. The
 			<literal>Bundle-SymbolicName</literal> is the name of the project. The <literal>Bundle-Name</literal> is
 			derived from the <literal>Bundle-SymbolicName</literal>. The <literal>Bundle-Version</literal> is
 			set, and there is no <literal>Bundle-Description</literal>.
 		</para>
 		<para>
 			Change the <literal>Bundle-Name</literal> to <quote><literal>@greenpages@ DataSource</literal></quote> to more accurately
 			describe the bundle&rsquo;s purpose. An option to &lsquo;Enable Bundle Classpath Container&rsquo; is already selected. It should
 			be <emphasis>de</emphasis>-selected, as a @maven@ Classpath container will be configured later.
 			Ensure that the <emphasis>Target Runtime</emphasis>
 			is set to <emphasis>Virgo Web Server (Runtime) v2.1</emphasis>.
 			Click <emphasis>Finish</emphasis>.
 		<mediaobject>
 			<imageobject role="fo">
 				<imagedata fileref="images/middle-tier/config-bundle-project.png" format="PNG" align="center" width="9cm"/>
 			</imageobject>
 			<imageobject role="html">
 				<imagedata fileref="images/middle-tier/config-bundle-project.png" format="PNG" align="center"/>
 			</imageobject>
 		</mediaobject>
             The <literal>greenpages.db</literal> project appears in the <emphasis>Package Explorer</emphasis> view.
 		</para>
 	</section>

 	<section id="middle-tier.create-db-project.configuring-classpath">
 		<title>Configuring the project&rsquo;s classpath container</title>
 		<para>
 			Before a Maven Classpath Container can be added to the project, a <literal>pom.xml</literal> file must
 			be created.
 			Create a new file in the root of the <literal>greenpages.db</literal> project named
 			<literal>pom.xml</literal> and add the following contents to it:
 <programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
 <project
 	xmlns="http://maven.apache.org/POM/4.0.0"
 	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

 	<parent>
 		<groupId>com.springsource.dmserver</groupId>
 		<artifactId>greenpages.parent</artifactId>
 		<version>@app.version@</version>
 		<relativePath>../parent</relativePath>
 	</parent>

 	<modelVersion>4.0.0</modelVersion>
 	<groupId>com.springsource.dmserver</groupId>
 	<artifactId>greenpages.db</artifactId>
 	<name>greenpages.db</name>
 	<packaging>jar</packaging>

 	<dependencies>
 	</dependencies>

 </project>]]>
 </programlisting>
 			Save the file.
 		</para>

 		<para>
 			A @maven@ Classpath Container can now be added to the project. Right-click the
 			<literal>greenpages.db</literal> project in the Package Explorer and select
 			<menuchoice><guimenu>Maven 2</guimenu><guimenuitem>Enable dependency management</guimenuitem></menuchoice>.
 			Eclipse will perform some workspace building, and the <literal>greenpages.db</literal> project will now be marked as a Maven project.
 			(If the error <literal>Cannot find artifact for parent POM</literal> occurs check that the version is correct.
 			It may differ from the one given here.)
 		</para>
 	</section>

 	<section id="middle-tier.create-db-project.config-src-folders">
 		<title>Configuring the source folders</title>
 		<para>
 			The last part of the setup of the project is to configure its source folders.
 			Return to the <emphasis>Properties</emphasis> dialog of
 			the <literal>greenpages.db</literal> project (from the <emphasis>Package Explorer</emphasis> view).
 			Select <emphasis>Java Build Path</emphasis> on the left-hand side and the <emphasis>Source</emphasis> tab
 			on the right-hand side.
 			Remove any pre-configured source folders by selecting them and
 			clicking <emphasis>Remove</emphasis>.
 		</para>

 		<para>
 			Now click <emphasis>Add folder</emphasis> and then
 			<emphasis>Create new folder…</emphasis>.
 			Specify <literal>src/main/resources</literal> as the folder
 			name and click <emphasis>Finish</emphasis>, then <emphasis>OK</emphasis> and <emphasis>OK</emphasis> again.
 		</para>

 		<para>
 			The final change to be made is to drag the <literal>META-INF</literal> folder from <literal>src</literal>
 			to <literal>src/main/resources</literal>.
 			Once these changes have been made the project will appear
 			similar to the following in the <emphasis>Package Explorer</emphasis> view:
 		<mediaobject>
 			<imageobject role="fo">
 				<imagedata fileref="images/middle-tier/db-project.png" format="PNG" align="center" width="7cm"/>
 			</imageobject>
 			<imageobject role="html">
 				<imagedata fileref="images/middle-tier/db-project.png" format="PNG" align="center"/>
 			</imageobject>
 		</mediaobject>
 		</para>
 		<para>
 			(It is useful to check that the @maven@ project just configured has the correct Java System library associated with it and that
 			the <literal>MANIFEST.MF</literal> file that we have just moved is correctly generated when necessary.
 			To ensure this, disable the dependency management (enabled in the previous section) and then re-enable it, saving the changes in between.
 			This step may also change the Java system libraries associated with the build (right-click on the <literal>greenpages.db</literal> project, under Properties, Java build path and Libraries).
 			If the Java system libraries look incorrect, simply remove them in the Libraries window and reset them.)
 		</para>
 	</section>

 	<section id="middle-tier.create-db-project.config-datasource">
 		<title>Configuring the DataSource</title>
 		<para>
 			The DataSource bundle&rsquo;s main rôle is to configure and create a <literal>DataSource</literal> object and to
 			publish this to the OSGi service registry. This will be done by creating
 			a handful of Spring beans.
 		</para>

 		<para>
 			By default, Spring DM looks for application context files in a bundle&rsquo;s <literal>META-INF/spring</literal>
 			directory. Create a new folder named <literal>spring</literal> in the <literal>greenpages.db</literal>
 			project&rsquo;s <literal>META-INF</literal> folder. Having created the new folder, right-click it in the
 			Package Explorer and select
 			<menuchoice><guimenu>New </guimenu><guimenuitem>Spring Bean Configuration File</guimenuitem></menuchoice>.
 			This will open the wizard for creating Spring bean configuration files.
 		</para>

 		<para>
 			In the wizard enter a <literal>File name</literal> of <literal>module-context.xml</literal> and click
 			<emphasis>Next</emphasis>:
 			<mediaobject>
 				<imageobject role="fo">
 					<imagedata fileref="images/middle-tier/db-module-create-module-context.png" format="PNG" align="center" width="9cm"/>
 				</imageobject>
 				<imageobject role="html">
 					<imagedata fileref="images/middle-tier/db-module-create-module-context.png" format="PNG" align="center"/>
 				</imageobject>
 			</mediaobject>
 		</para>

 		<para>
 			Add the <emphasis>p - http://www.springframework.org/schema/p</emphasis> namespace declaration to the pre-selected
 			<emphasis>beans</emphasis> declaration and then click <emphasis>Finish</emphasis>.
 			<mediaobject>
 				<imageobject role="fo">
 					<imagedata fileref="images/middle-tier/db-module-namespace-declaration-configuration.png" format="PNG" align="center" width="9cm"/>
 				</imageobject>
 				<imageobject role="html">
 					<imagedata fileref="images/middle-tier/db-module-namespace-declaration-configuration.png" format="PNG" align="center"/>
 				</imageobject>
 			</mediaobject>
 		</para>

 		<para>
 			Update the newly-created file (which is opened by Eclipse) to declare a bean that defines the <literal>DataSource</literal>
             object that will be used to access the @greenpages@ database.
             Do this by adding the following bean declaration:
 <programlisting language="xml"><![CDATA[	<bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource"
 	p:driverClassName="org.h2.Driver" p:url="jdbc:h2:~/greenpages-db/greenpages"
 	p:username="greenpages" p:password="pass"
 	init-method="createDataSource" destroy-method="close" />]]>
 </programlisting>
 			The new bean has introduced a dependency on Commons DBCP, which will cause an error to be reported by Eclipse.
 		</para>

 		<para>
 			This dependency must be recorded in the project&rsquo;s pom file. Open the pom file for <literal>greenpages.db</literal> and add
 			the following dependency between the <literal>&lt;dependencies&gt;</literal> tags:
 <programlisting language="xml"><![CDATA[        <dependency>
             <groupId>org.apache.commons</groupId>
             <artifactId>com.springsource.org.apache.commons.dbcp</artifactId>
         </dependency>]]>
 </programlisting>
 			Save the updated pom and then switch back to the editor for <literal>module-context.xml</literal>.
 			Save the updated file and
 			observe that the previously reported problem is now resolved as Commons DBCP is available on the classpath.
 		</para>
 		<para>
 			Now that the <literal>DataSource</literal> bean is available, it can be published into the OSGi service registry.
         </para>
         <para>
 			Right-click the <literal>spring</literal> folder and select
 			<menuchoice><guimenu>New </guimenu><guimenuitem>Spring Bean Configuration File</guimenuitem></menuchoice> again.
 			This time specify
 			a name of <literal>osgi-context.xml</literal>, click <emphasis>Next</emphasis>, and add the <literal>osgi</literal>
 			namespace declaration
 			(ensure that the resultant schema location string contains the URL
 			<literal>http://www.springframework.org/schema/osgi/spring-osgi-1.2.xsd</literal>
 			as
 			<literal>http://www.springframework.org/schema/osgi/spring-osgi-2.0-m1.xsd</literal>
 			will result in an obscure deployment failure due to an invalid 'cacheTarget' property).
 			Click <emphasis>Finish</emphasis> and then add the following to the new file to publish the
 			<literal>DataSource</literal> as a service:
 <programlisting language="xml"><![CDATA[    <!--
         export the dataSource bean to the OSGi service registry under the
         DataSource interface
     -->
     <osgi:service ref="dataSource" interface="javax.sql.DataSource" />]]>
 </programlisting>
 		</para>
 	</section>

 	<section id="id=middle-tier.create-db-project.config-bundlor-template">
 		<title>Configuring Bundlor&rsquo;s manifest template</title>
 		<para>
 			Bundlor uses a manifest <emphasis>template</emphasis> to control the contents of the generated manifest.
 			Create a new file named
 			<literal>template.mf</literal> in the root of the <literal>greenpages.db</literal> project.
 			Open the existing
 			<literal>MANIFEST.MF</literal> and switch to the <literal>MANIFEST.MF</literal> tab to view its source. Copy
 			the contents. Switch to the editor for <literal>template.mf</literal>, switch to the
 			<literal>template.mf</literal> tab and paste the contents from <literal>MANIFEST.MF</literal>. These entries
 			will tell Bundlor what the resulting manifest&rsquo;s bundle symbolic name, bundle version, etc. should be. Save the
 			updated template.
 		</para>

 		<para>
 			Still in the <literal>template.mf</literal> editor switch to the <emphasis>Overview</emphasis> tab
 			and click <emphasis>Update MANIFEST.MF</emphasis> which is under the <quote>Bundle Actions</quote> section.
 		</para>

 		<para>
             At this point Bundlor will scan the project to determine its
 			dependencies. It will scan both <literal>module-context.xml</literal> and <literal>osgi-context.xml</literal>
 			looking for references to classes. For each class to which it finds a reference, an import for the class&rsquo;s
 			package will be added to the resulting manifest.
 		</para>

 		<para>
 			In this case, Bundlor will generate imports for
 			both <code>javax.sql</code> and <code>org.apache.commons.dbcp</code>.
 			These imports may not be resolved.
 			The <literal>greenpages.db</literal> project needs to be associated with a @webserv@ instance which has the
 			Commons DBCP bundle in its repository to resolve them.
 			In any event the next step adds the <literal>greenpages.db</literal>
 			project to the @greenpages@ PAR and will result in it inheriting the PAR project&rsquo;s targetted runtime
 			configuration.
 		</para>

 		<para>
 			Double-click the <literal>MANIFEST.MF</literal> file in the <literal>greenpages</literal> project in the
 			<emphasis>Package Explorer</emphasis> view.
             Switch to the <literal>Dependencies</literal> tab and click <emphasis>Add…</emphasis>.
 			Select <literal>greenpages.db</literal> and click <emphasis>OK</emphasis>.
 			Save the updated file.
 			A problem concerning the <code>org.apache.commons.dbcp</code> dependency should now be resolved
 			(along with any other resolution errors) and (if the server is running) the
 			@greenpages@ application will be redeployed due to the addition of the <literal>greenpages.db</literal>
 			module.
 			Start the server if it is not already running and observe that this deployment fails.
 		</para>

 		<para>
 			The deployment will fail because the <code>org.h2.Driver</code> class that is referenced in the
 			<literal>DataSource</literal> bean&rsquo;s definition in <literal>module-context.xml</literal> is not available to
 			the bundle.
 			(Check for the exception <code>org.springframework.beans.factory.BeanCreationException</code> with
 			text something like:
 <programlisting><![CDATA[Error creating bean with name 'dataSource'
 	defined in URL [bundleentry://68.fwk504117357/META-INF/spring/ module-context.xml]:
 	Invocation of init method failed;
 	nested exception is org.apache.commons.dbcp.SQLNestedException: Cannot load JDBC driver class 'org.h2.Driver']]>
 </programlisting>
 			though the numbers might be different.)
 		</para>

 		<para>
 			There are a few cases where Bundlor will not identify a dependency on a class and, at the moment,
 			this is one of them, although this is an area of Bundlor that is being improved all the time.
 			Thankfully, it is easy to add the required import by making a simple update to the template.
 		</para>

 		<para>
 			Open the editor for the
 			<literal>template.mf</literal> file in the <literal>greenpages.db</literal> project and add the following
 			<literal>Import-Package</literal> header and save the updated manifest:
 <programlisting>Import-Package: org.h2;version="[1.0.71,1.0.71]"
 </programlisting>
 		</para>

 		<para>
 			Saving the manifest will trigger a redeployment (or click on <emphasis>Update MANIFEST.MF</emphasis> as before)
 			which will fail if the H2 database is not available.
 			(Refer to the section <xref linkend="installing.greenpages.building.db"/>
 			in <xref linkend="installing.greenpages"/> to run and configure the database.)
 		</para>

 		<para>
 			If the database is running the @greenpages@ application should correctly deploy.
 			Although the application web front-end will run, the database contents is
 			not visible, of course, because we are still running with the <emphasis>stub</emphasis> version of the <code>search</code> method on the controller.
 			The implementation of the <code>Directory</code> service needs to be changed to exploit the database.</para>

 		<para>
 			(One possible cause of failure here is the username and password on the <literal>dataSource</literal>
 			bean defined in <literal>module-context.xml</literal>. Check that these are exactly correct.)
 		</para>
 	</section>
 </section>
	<?xml version="1.0" encoding="UTF-8"?>
	<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
	"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
	<section id="middle-tier.create-db-project">
	<title>Creating the DataSource project</title>

	<para>
	This section describes how to use
	the bundle project creation wizard to create a new <literal>Bundle Project</literal>. The project’s Spring bean
	definition files will also be created using the Spring bean configuration file creation wizard.
	</para>
	<section id="middle-tier.create-db-project.new-bundle-project">
	<title>Creating a new Bundle Project</title>
	<para>
	Create a new project by right-clicking in the <emphasis>Package Explorer</emphasis> view and selecting
	<menuchoice><guimenu>New</guimenu><guimenuitem>Project…</guimenuitem></menuchoice>. In the resulting
	dialog select <menuchoice><guimenu>EclipseRT</guimenu><guimenuitem>Bundle
	Project</guimenuitem></menuchoice> and press <emphasis>Next</emphasis>:
	<mediaobject>
	<imageobject role="fo">
	<imagedata fileref="images/middle-tier/new-bundle-project.png" format="PNG" align="center" width="8cm"/>
	</imageobject>
	<imageobject role="html">
	<imagedata fileref="images/middle-tier/new-bundle-project.png" format="PNG" align="center"/>
	</imageobject>
	</mediaobject>
	</para>

	<para>
	In the <emphasis>New Bundle Project</emphasis> dialog, name the project <literal>greenpages.db</literal>.
	Choose the create the project from an existing source location and specify a location that will place the new
	<literal>greenpages.db</literal> alongside the project skeletons that were imported into the workspace
	earlier. If the <literal>start</literal> directory of the @greenpages@ sample is being used this will
	be <literal>$GREENPAGES_HOME/start/greenpages.db</literal> (and, <emphasis>mutatis mutandis</emphasis> on Windows).
	Click <emphasis>Next</emphasis>.
	<mediaobject>
	<imageobject role="fo">
	<imagedata fileref="images/middle-tier/create-bundle-project.png" format="PNG" align="center" width="12cm"/>
	</imageobject>
	<imageobject role="html">
	<imagedata fileref="images/middle-tier/create-bundle-project.png" format="PNG" align="center"/>
	</imageobject>
	</mediaobject>
	</para>

	<para>
	In this page of the wizard, many of the <emphasis>Bundle Properties</emphasis> are already populated. The
	<literal>Bundle-SymbolicName</literal> is the name of the project. The <literal>Bundle-Name</literal> is
	derived from the <literal>Bundle-SymbolicName</literal>. The <literal>Bundle-Version</literal> is
	set, and there is no <literal>Bundle-Description</literal>.
	</para>
	<para>
	Change the <literal>Bundle-Name</literal> to <quote><literal>@greenpages@ DataSource</literal></quote> to more accurately
	describe the bundle’s purpose. An option to ‘Enable Bundle Classpath Container’ is already selected. It should
	be <emphasis>de</emphasis>-selected, as a @maven@ Classpath container will be configured later.
	Ensure that the <emphasis>Target Runtime</emphasis>
	is set to <emphasis>Virgo Web Server (Runtime) v2.1</emphasis>.
	Click <emphasis>Finish</emphasis>.
	<mediaobject>
	<imageobject role="fo">
	<imagedata fileref="images/middle-tier/config-bundle-project.png" format="PNG" align="center" width="9cm"/>
	</imageobject>
	<imageobject role="html">
	<imagedata fileref="images/middle-tier/config-bundle-project.png" format="PNG" align="center"/>
	</imageobject>
	</mediaobject>
	The <literal>greenpages.db</literal> project appears in the <emphasis>Package Explorer</emphasis> view.
	</para>
	</section>

	<section id="middle-tier.create-db-project.configuring-classpath">
	<title>Configuring the project’s classpath container</title>
	<para>
	Before a Maven Classpath Container can be added to the project, a <literal>pom.xml</literal> file must
	be created.
	Create a new file in the root of the <literal>greenpages.db</literal> project named
	<literal>pom.xml</literal> and add the following contents to it:
	<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
	<project
	xmlns="http://maven.apache.org/POM/4.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

	<parent>
	<groupId>com.springsource.dmserver</groupId>
	<artifactId>greenpages.parent</artifactId>
	<version>@app.version@</version>
	<relativePath>../parent</relativePath>
	</parent>

	<modelVersion>4.0.0</modelVersion>
	<groupId>com.springsource.dmserver</groupId>
	<artifactId>greenpages.db</artifactId>
	<name>greenpages.db</name>
	<packaging>jar</packaging>

	<dependencies>
	</dependencies>

	</project>]]>
	</programlisting>
	Save the file.
	</para>

	<para>
	A @maven@ Classpath Container can now be added to the project. Right-click the
	<literal>greenpages.db</literal> project in the Package Explorer and select
	<menuchoice><guimenu>Maven 2</guimenu><guimenuitem>Enable dependency management</guimenuitem></menuchoice>.
	Eclipse will perform some workspace building, and the <literal>greenpages.db</literal> project will now be marked as a Maven project.
	(If the error <literal>Cannot find artifact for parent POM</literal> occurs check that the version is correct.
	It may differ from the one given here.)
	</para>
	</section>

	<section id="middle-tier.create-db-project.config-src-folders">
	<title>Configuring the source folders</title>
	<para>
	The last part of the setup of the project is to configure its source folders.
	Return to the <emphasis>Properties</emphasis> dialog of
	the <literal>greenpages.db</literal> project (from the <emphasis>Package Explorer</emphasis> view).
	Select <emphasis>Java Build Path</emphasis> on the left-hand side and the <emphasis>Source</emphasis> tab
	on the right-hand side.
	Remove any pre-configured source folders by selecting them and
	clicking <emphasis>Remove</emphasis>.
	</para>

	<para>
	Now click <emphasis>Add folder</emphasis> and then
	<emphasis>Create new folder…</emphasis>.
	Specify <literal>src/main/resources</literal> as the folder
	name and click <emphasis>Finish</emphasis>, then <emphasis>OK</emphasis> and <emphasis>OK</emphasis> again.
	</para>

	<para>
	The final change to be made is to drag the <literal>META-INF</literal> folder from <literal>src</literal>
	to <literal>src/main/resources</literal>.
	Once these changes have been made the project will appear
	similar to the following in the <emphasis>Package Explorer</emphasis> view:
	<mediaobject>
	<imageobject role="fo">
	<imagedata fileref="images/middle-tier/db-project.png" format="PNG" align="center" width="7cm"/>
	</imageobject>
	<imageobject role="html">
	<imagedata fileref="images/middle-tier/db-project.png" format="PNG" align="center"/>
	</imageobject>
	</mediaobject>
	</para>
	<para>
	(It is useful to check that the @maven@ project just configured has the correct Java System library associated with it and that
	the <literal>MANIFEST.MF</literal> file that we have just moved is correctly generated when necessary.
	To ensure this, disable the dependency management (enabled in the previous section) and then re-enable it, saving the changes in between.
	This step may also change the Java system libraries associated with the build (right-click on the <literal>greenpages.db</literal> project, under Properties, Java build path and Libraries).
	If the Java system libraries look incorrect, simply remove them in the Libraries window and reset them.)
	</para>
	</section>

	<section id="middle-tier.create-db-project.config-datasource">
	<title>Configuring the DataSource</title>
	<para>
	The DataSource bundle’s main rôle is to configure and create a <literal>DataSource</literal> object and to
	publish this to the OSGi service registry. This will be done by creating
	a handful of Spring beans.
	</para>

	<para>
	By default, Spring DM looks for application context files in a bundle’s <literal>META-INF/spring</literal>
	directory. Create a new folder named <literal>spring</literal> in the <literal>greenpages.db</literal>
	project’s <literal>META-INF</literal> folder. Having created the new folder, right-click it in the
	Package Explorer and select
	<menuchoice><guimenu>New </guimenu><guimenuitem>Spring Bean Configuration File</guimenuitem></menuchoice>.
	This will open the wizard for creating Spring bean configuration files.
	</para>

	<para>
	In the wizard enter a <literal>File name</literal> of <literal>module-context.xml</literal> and click
	<emphasis>Next</emphasis>:
	<mediaobject>
	<imageobject role="fo">
	<imagedata fileref="images/middle-tier/db-module-create-module-context.png" format="PNG" align="center" width="9cm"/>
	</imageobject>
	<imageobject role="html">
	<imagedata fileref="images/middle-tier/db-module-create-module-context.png" format="PNG" align="center"/>
	</imageobject>
	</mediaobject>
	</para>

	<para>
	Add the <emphasis>p - http://www.springframework.org/schema/p</emphasis> namespace declaration to the pre-selected
	<emphasis>beans</emphasis> declaration and then click <emphasis>Finish</emphasis>.
	<mediaobject>
	<imageobject role="fo">
	<imagedata fileref="images/middle-tier/db-module-namespace-declaration-configuration.png" format="PNG" align="center" width="9cm"/>
	</imageobject>
	<imageobject role="html">
	<imagedata fileref="images/middle-tier/db-module-namespace-declaration-configuration.png" format="PNG" align="center"/>
	</imageobject>
	</mediaobject>
	</para>

	<para>
	Update the newly-created file (which is opened by Eclipse) to declare a bean that defines the <literal>DataSource</literal>
	object that will be used to access the @greenpages@ database.
	Do this by adding the following bean declaration:
	<programlisting language="xml"><![CDATA[ <bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource"
	p:driverClassName="org.h2.Driver" p:url="jdbc:h2:~/greenpages-db/greenpages"
	p:username="greenpages" p:password="pass"
	init-method="createDataSource" destroy-method="close" />]]>
	</programlisting>
	The new bean has introduced a dependency on Commons DBCP, which will cause an error to be reported by Eclipse.
	</para>

	<para>
	This dependency must be recorded in the project’s pom file. Open the pom file for <literal>greenpages.db</literal> and add
	the following dependency between the <literal><dependencies></literal> tags:
	<programlisting language="xml"><![CDATA[ <dependency>
	<groupId>org.apache.commons</groupId>
	<artifactId>com.springsource.org.apache.commons.dbcp</artifactId>
	</dependency>]]>
	</programlisting>
	Save the updated pom and then switch back to the editor for <literal>module-context.xml</literal>.
	Save the updated file and
	observe that the previously reported problem is now resolved as Commons DBCP is available on the classpath.
	</para>
	<para>
	Now that the <literal>DataSource</literal> bean is available, it can be published into the OSGi service registry.
	</para>
	<para>
	Right-click the <literal>spring</literal> folder and select
	<menuchoice><guimenu>New </guimenu><guimenuitem>Spring Bean Configuration File</guimenuitem></menuchoice> again.
	This time specify
	a name of <literal>osgi-context.xml</literal>, click <emphasis>Next</emphasis>, and add the <literal>osgi</literal>
	namespace declaration
	(ensure that the resultant schema location string contains the URL
	<literal>http://www.springframework.org/schema/osgi/spring-osgi-1.2.xsd</literal>
	as
	<literal>http://www.springframework.org/schema/osgi/spring-osgi-2.0-m1.xsd</literal>
	will result in an obscure deployment failure due to an invalid 'cacheTarget' property).
	Click <emphasis>Finish</emphasis> and then add the following to the new file to publish the
	<literal>DataSource</literal> as a service:
	<programlisting language="xml"><![CDATA[ <!--
	export the dataSource bean to the OSGi service registry under the
	DataSource interface
	-->
	<osgi:service ref="dataSource" interface="javax.sql.DataSource" />]]>
	</programlisting>
	</para>
	</section>

	<section id="id=middle-tier.create-db-project.config-bundlor-template">
	<title>Configuring Bundlor’s manifest template</title>
	<para>
	Bundlor uses a manifest <emphasis>template</emphasis> to control the contents of the generated manifest.
	Create a new file named
	<literal>template.mf</literal> in the root of the <literal>greenpages.db</literal> project.
	Open the existing
	<literal>MANIFEST.MF</literal> and switch to the <literal>MANIFEST.MF</literal> tab to view its source. Copy
	the contents. Switch to the editor for <literal>template.mf</literal>, switch to the
	<literal>template.mf</literal> tab and paste the contents from <literal>MANIFEST.MF</literal>. These entries
	will tell Bundlor what the resulting manifest’s bundle symbolic name, bundle version, etc. should be. Save the
	updated template.
	</para>

	<para>
	Still in the <literal>template.mf</literal> editor switch to the <emphasis>Overview</emphasis> tab
	and click <emphasis>Update MANIFEST.MF</emphasis> which is under the <quote>Bundle Actions</quote> section.
	</para>

	<para>
	At this point Bundlor will scan the project to determine its
	dependencies. It will scan both <literal>module-context.xml</literal> and <literal>osgi-context.xml</literal>
	looking for references to classes. For each class to which it finds a reference, an import for the class’s
	package will be added to the resulting manifest.
	</para>

	<para>
	In this case, Bundlor will generate imports for
	both <code>javax.sql</code> and <code>org.apache.commons.dbcp</code>.
	These imports may not be resolved.
	The <literal>greenpages.db</literal> project needs to be associated with a @webserv@ instance which has the
	Commons DBCP bundle in its repository to resolve them.
	In any event the next step adds the <literal>greenpages.db</literal>
	project to the @greenpages@ PAR and will result in it inheriting the PAR project’s targetted runtime
	configuration.
	</para>

	<para>
	Double-click the <literal>MANIFEST.MF</literal> file in the <literal>greenpages</literal> project in the
	<emphasis>Package Explorer</emphasis> view.
	Switch to the <literal>Dependencies</literal> tab and click <emphasis>Add…</emphasis>.
	Select <literal>greenpages.db</literal> and click <emphasis>OK</emphasis>.
	Save the updated file.
	A problem concerning the <code>org.apache.commons.dbcp</code> dependency should now be resolved
	(along with any other resolution errors) and (if the server is running) the
	@greenpages@ application will be redeployed due to the addition of the <literal>greenpages.db</literal>
	module.
	Start the server if it is not already running and observe that this deployment fails.
	</para>

	<para>
	The deployment will fail because the <code>org.h2.Driver</code> class that is referenced in the
	<literal>DataSource</literal> bean’s definition in <literal>module-context.xml</literal> is not available to
	the bundle.
	(Check for the exception <code>org.springframework.beans.factory.BeanCreationException</code> with
	text something like:
	<programlisting><![CDATA[Error creating bean with name 'dataSource'
	defined in URL [bundleentry://68.fwk504117357/META-INF/spring/ module-context.xml]:
	Invocation of init method failed;
	nested exception is org.apache.commons.dbcp.SQLNestedException: Cannot load JDBC driver class 'org.h2.Driver']]>
	</programlisting>
	though the numbers might be different.)
	</para>

	<para>
	There are a few cases where Bundlor will not identify a dependency on a class and, at the moment,
	this is one of them, although this is an area of Bundlor that is being improved all the time.
	Thankfully, it is easy to add the required import by making a simple update to the template.
	</para>

	<para>
	Open the editor for the
	<literal>template.mf</literal> file in the <literal>greenpages.db</literal> project and add the following
	<literal>Import-Package</literal> header and save the updated manifest:
	<programlisting>Import-Package: org.h2;version="[1.0.71,1.0.71]"
	</programlisting>
	</para>

	<para>
	Saving the manifest will trigger a redeployment (or click on <emphasis>Update MANIFEST.MF</emphasis> as before)
	which will fail if the H2 database is not available.
	(Refer to the section <xref linkend="installing.greenpages.building.db"/>
	in <xref linkend="installing.greenpages"/> to run and configure the database.)
	</para>

	<para>
	If the database is running the @greenpages@ application should correctly deploy.
	Although the application web front-end will run, the database contents is
	not visible, of course, because we are still running with the <emphasis>stub</emphasis> version of the <code>search</code> method on the controller.
	The implementation of the <code>Directory</code> service needs to be changed to exploit the database.</para>

	<para>
	(One possible cause of failure here is the username and password on the <literal>dataSource</literal>
	bean defined in <literal>module-context.xml</literal>. Check that these are exactly correct.)
	</para>
	</section>
	</section>