Spring/spring-webflow
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Integrated phonebook-portlet documentation.

Browse Source
This commit is contained in:
Erwin Vervaet
2007-03-09 20:26:14 +00:00
parent 0656a4ee51
commit 62ba6ecda4
1 changed files with 230 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

231
spring-webflow/docs/reference/src/practical.xml
View File

@@ -59,7 +59,10 @@
</para>
</listitem>
<listitem>
<para>Phonebook-Portlet - the phonebook sample in a Portlet environment (notice how the flow definitions do not change).</para>
<para>
<link linkend="phonebook-Portlet-sample">Phonebook-Portlet</link> - the
phonebook sample in a Portlet environment (notice how the flow definitions do not change).
</para>
</listitem>
</orderedlist>
</para>
@@ -2014,4 +2017,230 @@ public void registerCustomEditors(PropertyEditorRegistry registry) {
</para>
</sect2>
</sect1>
<sect1 id="phonebook-Portlet-sample">
<title>Phonebook-Portlet Example</title>
<sect2>
<title>Overview</title>
<para>
The Phonebook-Portlet demonstrates how to run the
<ulink url="http://www.ervacon.com/products/swf/intro/index.html">Phonebook</ulink>
sample as a JSR-168 portlet. The functionality for Phonebook and Phonebook-Portlet
including web flow definitions, JSP pages, and Java classes is the same and
already well documented.
The focus in Phonebook-Portlet is specifically on how to configure
and run Phonebook in a Portal container.
</para>
<note>
<para>
JSR-168 defines portlets but not how portlets integrate into a
portal container. This process is left open to portal vendors who
have their own individual mechanisms.
The Phonebook-Portlet sample is configured to run with
<ulink url="http://portals.apache.org/pluto/">Apache Pluto</ulink> -
a reference implementation of the Java Portlet Specification.
However, its dependence on Pluto is limited to configuration in web.xml.
Hence it should be easy to adapt for use
in other Portal/Portlet implementations after learning the
deployment steps specific for that implementation.
</para>
</note>
</sect2>
<sect2>
<title>Portal/Portlet Related Software Used in the Sample</title>
<para>
This section provides a very brief introduction to the portal related
supporting software used in the sample - namely Apache Pluto
and the Portlet MVC framework. If this is not new for you
feel free to skip to the next section.
</para>
<sect3>
<title>Apache Pluto</title>
<para>
For those familiar with servlet applications the process
of deploying and running a portlet application can be
confusing and requires some explanation.
Typically an application with JSR-168 portlets runs in
one webapp while a portal/portlet container runs
in a separate webapp making cross-context calls to
portlets. How exactly this is configured
depends on each portal vendor.
</para>
<para>
Pluto is an open-source reference implementation of the
Java Portlet specification. The following general steps
are required to run portlets with it. First the
the portlet application's web.xml is "injected" with
configuration required for Pluto. Secondly Pluto's
Portal web application, usually set to run at
http://localhost:8080/pluto/portal
is used to add or remove portlets to one or more
portal container pages.
</para>
<para>
The web.xml for the Phonebook-Portlet sample has
already been "injected" with the configuration required
for Pluto 1.1.0. Although this enables it for use with Pluto
you must still use the
admin pages of Pluto's Portal web application to add
the Phonebook-Portlet to a test portal page. For more
information on how to do this please follow instructions from
Apache Pluto.
</para>
</sect3>
<sect3>
<title>Portlet MVC Framework</title>
<para>
The Portlet MVC framework represents Spring's support for JSR-168.
It has many parallels with the Spring MVC framework such
as the DispatcherPortlet, the Controller interface,
handler mappings, view resolvers, and exception handlers.
The main differences between Portlet MVC and Spring MVC
have to do with the lifecycles of a portlet and its
distinct phases as defined in the Porlet Specification:
the action and the render phases.
For more information see
<ulink url="http://static.springframework.org/spring/docs/2.0.x/reference/portlet.html">
Chapter 16 (Portlet MVC Framework)</ulink> from the Spring reference
documentation.
</para>
</sect3>
</sect2>
<sect2>
<title>Portlet.xml Configuration</title>
<para>
Portlet.xml is a standard deployment descriptor where
portlet resources are defined. The Phonebook-Portlet
is based the Portlet MVC DispatcherPorlet:
<programlisting>
&lt;portlet-class&gt;
org.springframework.web.portlet.DispatcherPortlet
&lt;/portlet-class&gt;
</programlisting>
The DispatcherPortlet is Spring's implementation of the Portlet interface
dispatching requests for a portlet to registered Portlet MVC handlers.
The phonebook portlet is configured with the following Spring
contexts containing Portlet MVC handler, controller and
view resolver beans:
<programlisting>
&lt;init-param&gt;
&lt;name&gt;contextConfigLocation&lt;/name&gt;
&lt;value&gt;
/WEB-INF/phonebook-portlet-config.xml /WEB-INF/phonebook-webflow-config.xml
&lt;/value&gt;
&lt;/init-param&gt;
</programlisting>
The above configuration defines phonebook as a portlet resource. In order
to use it in a portal/portlet container
additional web.xml configuration is required.
</para>
</sect2>
<sect2>
<title>Web.xml Configuration</title>
<para>
The Java Portlet Specification is defined as a layer over existing Servlet
infrastructure. Therefore some sort of a servlet is required to accept servlet
requests and expose portlet resources. Portal vendors
provide such servlets and specific configuration varies by vendor.
The Phonebook-Portlet has the following Apache Pluto servlet definition
and servlet mapping:
<programlisting>
&lt;!-- Generated Portlet Wrapper Servlet for Apache Pluto deployment --&gt;
&lt;servlet&gt;
&lt;servlet-name&gt;phonebook&lt;/servlet-name&gt;
&lt;servlet-class&gt;org.apache.pluto.core.PortletServlet&lt;/servlet-class&gt;
&lt;init-param&gt;
&lt;param-name&gt;portlet-name&lt;/param-name&gt;
&lt;param-value&gt;phonebook&lt;/param-value&gt;
&lt;/init-param&gt;
&lt;load-on-startup&gt;1&lt;/load-on-startup&gt;
&lt;/servlet&gt;
&lt;servlet-mapping&gt;
&lt;servlet-name&gt;phonebook&lt;/servlet-name&gt;
&lt;url-pattern&gt;/PlutoInvoker/phonebook&lt;/url-pattern&gt;
&lt;/servlet-mapping&gt;
</programlisting>
</para>
<note>
<para>
The above configuration was auto generated using ant tasks from
Apache Pluto 1.1.0. This configuration is included in web.xml
for convenience and also as an example.
For the most up-to-date information on required configuration please
check Pluto's documentation.
</para>
</note>
<para>
The web.xml configuration also contains the following servlet definition:
<programlisting>
&lt;servlet&gt;
&lt;servlet-name&gt;viewRendererServlet&lt;/servlet-name&gt;
&lt;servlet-class&gt;
org.springframework.web.servlet.ViewRendererServlet
&lt;/servlet-class&gt;
&lt;/servlet&gt;
&lt;servlet-mapping&gt;
&lt;servlet-name&gt;viewRendererServlet&lt;/servlet-name&gt;
&lt;url-pattern&gt;/WEB-INF/servlet/view&lt;/url-pattern&gt;
&lt;/servlet-mapping&gt;
</programlisting>
</para>
<para>
The main purpose of this servlet is to allow reuse of Spring MVC's flexible
view resolution and rendering capabilities in a Portlet application.
The DispatcherPortlet converts a PortletRequest/PortletResponse to an
HttpServletRequest/HttpServletResponse and then performs an include of
this servlet.
</para>
</sect2>
<sect2>
<title>Portlet MVC Configuration</title>
<para>
The phonebook-portlet-config.xml is very similar to the Spring MVC
equivalent phonebook-servlet.xml from the Phonebook sample. The main
difference is in the use of a PortletModeHandlerMapping:
<programlisting>
&lt;bean id="portletModeControllerMapping"
class="org.springframework.web.portlet.handler.PortletModeHandlerMapping"&gt;
&lt;property name="portletModeMap"&gt;
&lt;map&gt;
&lt;entry key="view" value-ref="flowController"/&gt;
&lt;/map&gt;
&lt;/property&gt;
&lt;/bean&gt;
</programlisting>
and a PortletFlowController:
<programlisting>
&lt;bean id="flowController" class="org.springframework.webflow.executor.mvc.PortletFlowController"&gt;
&lt;property name="flowExecutor" ref="flowExecutor"/&gt;
&lt;property name="defaultFlowId" value="search-flow"/&gt;
&lt;/bean&gt;
</programlisting>
A PortletModeHandlerMapping allows mapping specific to each
portlet mode. The VIEW mode in this case is mapped to the
flowController bean, which delegates the request to Web Flow's
executor for launching or resuming a flow from a flow definition.
For more information on Phonebook flow definitions please
refer to the
<ulink url="http://www.ervacon.com/products/swf/intro/index.html">Phonebook</ulink>
sample documentation.
</para>
<para>
One last thing to observe is the following configuration in
/WEB-INF/phonebook-webflow-config.xml:
<programlisting>
&lt;!-- Launches new flow executions and resumes existing executions. --&gt;
&lt;flow:executor id="flowExecutor" registry-ref="flowRegistry"&gt;
&lt;flow:execution-attributes&gt;
&lt;!-- execution redirects don't apply in a Portlet environment --&gt;
&lt;flow:alwaysRedirectOnPause value="false"/&gt;
&lt;/flow:execution-attributes&gt;
&lt;/flow:executor&gt;
</programlisting>
As the comment indicates the default behavior of redirect after submit
must be turned off in a portlet environment where there is no HTTP redirect.
For more information on the alwaysRedirectOnPause refer to the following
<ulink url="http://www.ervacon.com/products/swf/tips/tip4.html">article</ulink>.
</para>
</sect2>
</sect1>
</chapter>