getting-started/src/web-module/controller.xml

<?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="controller">
	<title>The controller</title>
	<para>
		The Spring&rsquo;s MVC style of web application development is used in which the central type
    	is the <literal>Controller</literal> class.
	</para>

	<section id="import.greenpages.web">
		<title>Import the web project</title>
	<para>
		The @greenpages@ application is divided into OSGi bundles that are represented as Eclipse
		projects. In this step import the <literal>greenpages.web</literal> project.
	</para>
	<para>
		Starting with no projects, import the web project by right-clicking in the <emphasis>Package Explorer</emphasis>
		view and selecting the <emphasis>Import…</emphasis> menu item.
		In the dialog that opens, choose <menuchoice><guimenuitem>General</guimenuitem>
		<guimenuitem>Existing Projects into Workspace</guimenuitem></menuchoice> and select <emphasis>Next</emphasis>.
		In the following dialog set the <emphasis>root directory</emphasis> to the value of 
		<literal>$GREENPAGES_HOME/start/greenpages.web</literal> and press <emphasis>Finish</emphasis>.
	</para>
	<para>
		(Initially this project may have compiler errors; 
		this is to be expected particularly if the @maven@ repository hasn&rsquo;t yet been created.)
<!--		<mediaobject>-->
<!--			<imageobject role="fo">-->
<!--				<imagedata fileref="images/web-module/import-greenpages-web.png" format="PNG" align="center" width="10cm"/>-->
<!--			</imageobject>-->
<!--			<imageobject role="html">-->
<!--				<imagedata fileref="images/web-module/import-greenpages-web.png" format="PNG" align="center"/>-->
<!--			</imageobject>-->
<!--		</mediaobject>-->
		When this project is imported go to the next step.
	</para>
	</section>

	<section id="controller.controller">
		<title>The controller class</title>
		<para>
			In the <literal>src/main/java</literal> source folder of the <literal>greenpages.web</literal> project 
			the package <classname>greenpages.web</classname>
			should contain the controller class named
			<classname>GreenPagesController</classname>.
			Create this by right-clicking on the <literal>greenpages.web</literal> package in the
			<literal>src/main/java</literal> source folder and selecting 
			<menuchoice><guimenuitem>New</guimenuitem><guimenuitem>Class</guimenuitem></menuchoice>.
			(If <emphasis>Class</emphasis> is not offered on the <emphasis>New</emphasis> menu 
			the <emphasis>Java</emphasis> perspective may not be being used, in which case look for 
			the <emphasis>Class</emphasis> option under <emphasis>Other…</emphasis> in the <emphasis>Java</emphasis> section.)
		</para>
		
		<para>
			Name the new class <classname>GreenPagesController</classname> and press <emphasis>Finish</emphasis>.
			<mediaobject>
				<imageobject role="fo">
					<imagedata fileref="images/web-module/new-greenpages-controller.png" format="PNG" align="center" width="12cm"/>
				</imageobject>
				<imageobject role="html">
					<imagedata fileref="images/web-module/new-greenpages-controller.png" format="PNG" align="center"/>
				</imageobject>
			</mediaobject>
		</para>
		
		<para>
			The code should be edited to look like this:
<programlisting language="java"><![CDATA[@Controller
public class GreenPagesController {
	…
    @RequestMapping("/home.htm")
    public void home() {
    }
    …]]>
</programlisting>
		</para>
		<para>
			The annotations <classname>Controller</classname> and <classname>RequestMapping</classname> 
			are from Spring Framework and are imported by adding the lines:
<programlisting language="java"><![CDATA[import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;]]>
</programlisting>
    </para>
	<para>
	    @sts.short@ will offer (as a <emphasis>Quick Fix</emphasis>) to insert imports for these Spring Framework annotations
    	the first time they are used. 
    	(Java 1.6 supports annotations, and the Spring Framework libraries are accessible by
    	linking to the correct @webserv@ runtime environment or generating the correct dependencies for the @maven@ plug-in.)
    </para>
	</section>

	<section id="controller.component.scanning">
		<title>Enabling component scanning</title>
		<para>
			Spring will detect the <classname>@Controller</classname> annotation and create a bean of controller type, 
			<emphasis>provided that</emphasis> it scans the classpath for these.
			Spring&rsquo;s component scanning is enabled by inserting a <literal>context</literal> tag 
			in one of the Spring bean definition files.
		</para>
		<para>
			Open the <filename>WEB-INF/greenpages-servlet.xml</filename> file in the
			<literal>src/main/webapp</literal> folder and ensure the following lines are present:
<programlisting language="xml"><![CDATA[	<!-- enable classpath scanning -->
	<context:component-scan base-package="greenpages.web" />]]>
</programlisting>
		</para>
		<para>
			Experiment by adding and removing this line, saving the file after each change. 
			(<emphasis>Easily done by commenting it—use the
			<emphasis>Toggle Comment</emphasis>
			shortcut in @sts.short@.</emphasis>) 
			Look in the <emphasis>Spring Explorer</emphasis> view for a bean named <literal>greenPagesController</literal>
			dynamically created by the <literal>component-scan</literal> tag.
		</para>
	</section>
</section>