<document>
<header>
<product>resin</product>
<title>Hello World Portlet Tutorial</title>
<type>tutorial</type>
<tutorial-startpage>hello</tutorial-startpage>
<description>
The Hello, World tutorial shows the most basic portlet and
its configuration in a simple browser page.
</description>
</header>

<body>
<summary/>

<p>Portlets form a design pattern where a <em>Portal</em>
servlet combines one
or more component <em>Portlets</em> into a web page.  Because the portlets
are written as components, they can be cleanly written and tested.  
Applications which currently use many servlet includes might be more cleanly
written as portlet applications.</p>

<p>The Portal part of the pattern is a servlet which manages the
portlets.  In this example, the servlet is a simple "invoker" which
calls a single portlet to render the page.  Many applications will
write their own Portal servlets, using Resin's generic portal
library to handle the Portlet API.</p>


<p>The "Hello, world" portlet requires the following configuration:</p>

<ul>
<li>The HelloWorldPortlet.java code
<li>web.xml configuration of the Portlet servlet
</ul>

<section title="Files in this tutorial">
<deftable>
<tr><td><viewfile-link file="WEB-INF/classes/example/HelloWorldPortlet.java"/>
    <td>Simple portlet
<tr><td><viewfile-link file="WEB-INF/web.xml"/>
    <td>web-app configuration
</deftable>
</section>

<section title="Portlet">
<p>
A Portlet is a class that implements <a href="javadoc|javax.portlet.Portlet|"/>.
It is similar to a servlet.
</p>
<p>
The HelloWorldPortlet in this tutorial sends a <code>Hello, World</code>
message to the browser.
</p>
<p>
The response to the browser is generated by the <code>render()</code> method.
</p>

<example title="example.HelloWorldPortlet" file="WEB-INF/classes/example/HelloWorldPortlet.java">
package example;

import java.io.PrintWriter;
import java.io.IOException;

import javax.portlet.GenericPortlet;
import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;
import javax.portlet.PortletException;

public class HelloWorldPortlet extends GenericPortlet {
  /**
   * The portlet's main view prints "Hello, World"
   */
  public void doView(RenderRequest request, RenderResponse response)
    throws PortletException, IOException
  {
    PrintWriter out = response.getWriter();

    out.println("Hello, World");
  }
}
</example>

</section>

<section title="PortletServlet">

<p>
<a href="javadoc|com.caucho.portal.generic.PortletServlet|"/>
is a servlet that dispatches to a portlet.  
In this way, portlets can be used as drop-in replacements for servlets.
</p>


<example title="WEB-INF/web.xml" file="WEB-INF/web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="http://caucho.com/ns/resin/core"&gt;

  &lt;servlet servlet-name="hello" 
           servlet-class="com.caucho.portal.generic.PortletServlet"&gt;
    &lt;init&gt;
      &lt;portlet resin:type="example.HelloWorldPortlet"/&gt;
    &lt;/init&gt;
  &lt;/servlet&gt;

  &lt;servlet-mapping url-pattern="/hello" servlet-name="hello"/&gt;
&lt;/web-app&gt;

</example>

<p>
Portlets work without modification in all portal products.  The PortletServlet
is a simple way to get a portlet going, and provides a convenient way to replace
servlets with portlets.
</p>

<p>
This approach is valuable for developers that wish to take advantage of the
well defined pattern that portlets provide, without necessarily needing the
more complete set of features such as sophisticated rendering and management of
multiple portlets per page that a more complete portal provides.  
</p>

</section>

<section title="Compatibility">
<p>
The tutorial takes advantage of Resin's dependency injection features.  The
PortletServlet also supports the use of init-param's if dependency injection is not available.
</p>

<example title="init-param WEB-INF/web.xml">
&lt;web-app&gt;
  &lt;servlet&gt;
    &lt;servlet-name&gt;hello&lt;/servlet-name&gt;
    &lt;servlet-class&gt;com.caucho.portal.generic.PortletServlet&lt;/servlet-class&gt;
    &lt;init-param&gt;
      &lt;param-name&gt;portlet-class&lt;/param-name&gt;
      &lt;param-value&gt;example.HelloWorldPortlet&lt;/param-value&gt;
    &lt;/init-param&gt;
  &lt;/servlet&gt;

  &lt;servlet-mapping&gt;
    &lt;url-pattern&gt;/hello&lt;/url-pattern&gt;
    &lt;servlet-name&gt;hello&lt;/servlet-name&gt;
  &lt;/servlet-mapping&gt;
&lt;/web-app&gt;
</example>

</section>

</body>
</document>


