<?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" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../../Reference_Guide.ent">
%BOOK_ENTITIES;
]>
<section id="sect-Reference_Guide-Navigation_Controller">
      <title>Navigation Controller </title>
      <section id="sect-Reference_Guide-Navigation_Controller-Description">
        <title>Description</title>
        <para>The navigation controller is a major enhancement of GateIn that has several goals:</para>
        <itemizedlist>
          <listitem>
            <para>Provide non-ambiguous URLs for resources managed by the portal, such as navigation. Previously, different resources were possible for a single URL, even worse, the set of resources available for an URL depends on private navigations (groups and dashboard).</para>
          </listitem>
          <listitem>
            <para>Decouple the HTTP request from the portal request. Previously, both were tightly coupled, for instance, the URL for a site had to begin with <emphasis>/public/{sitename}</emphasis> or <emphasis>/private/{sitename}</emphasis> .The navigation controller provides a flexible and configurable mapping.</para>
          </listitem>
          <listitem>
            <para>Provide a more friendly URL and let portal administrator configure how the HTTP request should look like.</para>
          </listitem>
        </itemizedlist>
      </section>
      <section id="sect-Reference_Guide-Navigation_Controller-Controller_Action">
        <title>Controller in Action</title>
        <section>
          <title>Controller</title>
          <para>The <code>WebAppController</code> is the component of GateIn that processes HTTP invocations and transforms them into a portal request. It has been improved with the addition of a request mapping engine (<emphasis role="bold">controller</emphasis>) whose role is to make the HTTP request decouple and create a portal request. The mapping engine makes two essential tasks:</para>
          <itemizedlist>
            <listitem>
              <para>Create a <emphasis role="bold">Map&lt;QualifiedName, String&gt;</emphasis> from an incoming HTTP request.</para>
            </listitem>
            <listitem>
              <para>Render a <emphasis role="bold">Map&lt;QualifiedName, String&gt; </emphasis> as an HTTP URL.</para>
            </listitem>
          </itemizedlist>
          <para>The goal of the controller (mapping engine) is to <emphasis role="bold">decouple</emphasis> the request processed by GateIn from the incoming HTTP request. Indeed, a request contain data that determine how the request will be processed and such data can be encoded in various places in the request, such as the request path, or a query parameter. The controller allows GateIn to route a request according to a set of parameters (a map) instead of the servlet request.</para>
          <para>The controller configuration is declarative in an .xml file, allowing easy reconfiguration of the routing table and it is processed into an internal data structure that is used to perform resolution (routing or rendering).</para>
        </section>
        <section id="sect-Reference_Guide-Navigation_Controller-Building_controller">
          <title>Building controller</title>
          <para>The controller configuration that contains the routing rules is loaded from the <emphasis role="bold">controller.xml</emphasis> file that is retrieved in the GateIn configuration directory. Its location is determined by the <emphasis role="bold">gatein.controller.config</emphasis> property.</para>
          <para>
            <emphasis role="bold">WebAppController</emphasis> loads and initializes the mapping engine.</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[
<!-- conf/portal/controller-configuration.xml of portal.war -->
<component>
  <type>org.exoplatform.web.WebAppController</type>
    <init-params>
      <value-param>
        <name>controller.config</name>
        <value>${gatein.portal.controller.config}</value>
      </value-param>
    </init-params>
</component>
]]></programlisting>
          </programlistingco>
          <para>GateIn's extension project can define their own routing table, thanks to the extension mechanism.</para>
          <para>The <emphasis role="bold">controller.xml</emphasis> file can be changed and reloaded at runtime. This helps the test of different configurations easily (configuration loading operations) and provides more insight into the routing engine (the findRoutes operation). See <emphasis role="bold">Rebuiding controller</emphasis> below for more details.</para>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold">ReBuilding controller</emphasis>
              </para>
            </listitem>
          </itemizedlist>
          <para>The WebAppController is annotated with <code>@Managed</code> annotations and is bound under the <code>view=portal,service=controller</code> JMX name and under the "portalcontroller" REST name.</para>
          <para>It provides the following attributes and operations:</para>
          <itemizedlist>
            <listitem>
              <para>Attribute configurationPath: the "read-only" configuration path of the <emphasis role="bold">controller.xml</emphasis> file.</para>
            </listitem>
            <listitem>
              <para>Operation loadConfiguration: load a new configuration file from a specified XML path.</para>
            </listitem>
            <listitem>
              <para>Operation reloadConfiguration: reload the configuration file.</para>
            </listitem>
            <listitem>
              <para>Operation findRoutes: route the request argument through the controller and returns a list of all parameter map resolutions. The argument is a request URI, such as <emphasis>/groups/:platform:administrators/administration/registry</emphasis>. It returns a string representation (<code>List&lt;Map&gt;</code>) of the matched routes.</para>
            </listitem>
          </itemizedlist>
        </section>
        <section id="sect-Reference_Guide-Navigation_Controller-Controller_Config">
          <title>Controller Configuration (controller.xml)</title>
          <para>Most of the controller configuration cares about defining rules (Routing table - contains routes object) that will drive the resolution. Routes are processed during the controller initialization to give a tree of node.</para>
          <itemizedlist>
            <listitem>
              <para> Each node is related to its parent with a matching rule that can either be an <emphasis role="bold">exact string matching</emphasis> or a <emphasis role="bold">regular expression matching</emphasis>.
              </para>
            </listitem>
            <listitem>
              <para> Each node is associated with a set of parameters.</para>
            </listitem>
          </itemizedlist>
          <para>A parameter is defined by a qualified name and there are three kinds of parameters explained in the sections below.</para>
          <section id="sect-Reference_Guide-Navigation_Controller-Controller_Config-Route_Parameter">
            <title>
              <emphasis role="bold">Route parameters</emphasis>
            </title>
            <para>Route parameters defines a fixed value associate with a qualified name.</para>
            <itemizedlist>
              <listitem>
                <para>Routing: route parameters allow the controller to distinguish branches easily and route the request accordingly.</para>
              </listitem>
              <listitem>
                <para>Rendering: the system will select a route to render an URL if all route parameters are always matched.</para>
              </listitem>
            </itemizedlist>
            <para>
              <emphasis role="bold">Example:</emphasis>
            </para>
            <programlistingco>
              <areaspec units="linecolumn"/>
              <programlisting language="xml"><![CDATA[
<route path="/foo">
  <route-param qname="gtn:handler">
    <value>portal</value>
  </route-param>
</route>
]]></programlisting>
            </programlistingco>
            <para>This configuration matches the request path "<emphasis role="bold">/foo</emphasis>" to the map (gtn:handler=portal). Conversely, it renders the (gtn:handler=portal) map as the "<emphasis role="bold">/foo</emphasis>" URL. This example shows two concepts:</para>
            <itemizedlist>
              <listitem>
                <para>exact path matching ("/foo")</para>
              </listitem>
              <listitem>
                <para>route parameters ("gtn:handler")</para>
              </listitem>
            </itemizedlist>
          </section>
          <section id="sect-Reference_Guide-Navigation_Controller-Controller_Config-Path_Parameters">
            <title>
              <emphasis role="bold">Path parameters - <emphasis role="italic">Regular expression support</emphasis>
              </emphasis>
            </title>
            <para>Path parameters allow to associate a portion of the request path with a parameter. Such parameter will match any non empty portions of text except the <emphasis role="bold">/</emphasis> character (that is the [^/]+ regular expression) otherwise they can be associated with a regular expression for matching specific patterns. Path parameters are mandatory for matching since they are a part of the request path, however it is allowed to write regular expression matching an empty value.</para>
            <itemizedlist>
              <listitem>
                <para>Routing: route is accepted if the regular expression is matched.</para>
              </listitem>
              <listitem>
                <para>Rendering: the system will select a route to render an URL if all route parameters are always matched.</para>
              </listitem>
            </itemizedlist>
            <para>
              <emphasis role="bold">Encoding</emphasis>
            </para>
            <para>Path parameters may contain the '/' character which is a reserved char for the URI path. This case is specially handled by the navigation controller by using a special character to replace the '/' literals. By default, the character is the colon <emphasis role="bold">":"</emphasis> and can be changed to other possible values (see controller XML schema for possible values) to give a greater amount of flexibility.</para>
            <para>This encoding is applied only when the encoding is performed for parameters having a mode set to the <code>default-form</code> value, for instance, it does not happen for navigation node URI (for which <emphasis role="bold">/</emphasis> are encoded literally). The separator escape char can still be used but under it is percent escaped form, so by default, a path parameter value containing the colon <emphasis role="bold">":"</emphasis> would be encoded as <code>%3A</code> and conversely the <code>%3A</code> value will be decoded as the colon <emphasis role="bold">":"</emphasis>.</para>
            <para>
              <emphasis role="bold">Example: No pattern is define, the default one [^/]+ will be used:</emphasis>
            </para>
            <programlistingco>
              <areaspec units="linecolumn"/>
              <programlisting language="xml"><![CDATA[
<route path="/{gtn:path}">
</route>
]]></programlisting>
            </programlistingco>
            <para>As a result of the example above, routing and rendering is as below:</para>
            <programlistingco>
              <areaspec units="linecolumn"/>
              <programlisting><![CDATA[
Routing and Rendering
Path "/foo"      <--> the map (gtn:path=foo)

Path "/foo:bar"  <--> the map (gtn:path=foo/bar)
]]></programlisting>
            </programlistingco>
            <para>If the request path contains another "/" char, it will not work. The default encoding mode is <emphasis role="bold">default-form</emphasis>. In the example above, "/foo/bar" is not matched, so the system returns an empty parameter map.</para>
            <para>However, this problem could be solved with the following configuration:</para>
            <programlistingco>
              <areaspec units="linecolumn"/>
              <programlisting language="xml"><![CDATA[
<route path="/{gtn:path}">
  <path-param encoding="preserve-path" qname="gtn:path">
    <pattern>.*</pattern>
  </path-param>
</route>
]]></programlisting>
            </programlistingco>
            <itemizedlist>
              <listitem>
                <para>The ".*" declaration allows matching any char sequence.</para>
              </listitem>
              <listitem>
                <para>The "<emphasis>preserve-path</emphasis>" encoding tells the engine that the "/" chars should be handled by the path parameter itself as they have a special meaning for the router. Without this special encoding, "/" would be rendered as the ":" character and conversely the ":" character would be matched as the "/" character.</para>
              </listitem>
            </itemizedlist>
          </section>
          <section id="sect-Reference_Guide-Navigation_Controller-Controller_Config-Request_Parameters">
            <title>Request parameters</title>
            <para>Request parameters are matched from the request parameters (GET or POST). The match can be optional as their representation in the request allows it.</para>
            <itemizedlist>
              <listitem>
                <para><emphasis role="bold">Routing</emphasis>:</para>
                <itemizedlist>
                  <listitem>
                    <para>Route is accepted when a required parameter is present and matched in the request.</para>
                  </listitem>
                  <listitem>
                    <para>Route is accepted when an optional parameter is absent or matched in the request.</para>
                  </listitem>
                </itemizedlist>
              </listitem>
              <listitem>
                <para><emphasis role="bold">Rendering</emphasis>:</para>
                <itemizedlist>
                  <listitem>
                    <para>For required parameters, the system will select a route to render an URL when the parameter is present and matched in the map.</para>
                  </listitem>
                  <listitem>
                    <para>For optional parameters, the system will select a route to render an URL when the parameter is absent or matched in the map.</para>
                  </listitem>
                </itemizedlist>
              </listitem>
            </itemizedlist>
            <para>
              <emphasis role="bold">Example:</emphasis>
            </para>
            <programlistingco>
              <areaspec units="linecolumn"/>
              <programlisting language="xml"><![CDATA[
<route path="/">
  <request-param name="path" qname="gtn:path"/>
</route>
]]></programlisting>
            </programlistingco>
            <para>Request parameters are declared by a <code>request-param</code> element and will match any value by default. A request like "/?path=foo" is mapped to the (gtn:path=foo) map. The <code>name</code> attribute of the <code>request-param</code> tag defines the request parameter value. This element accepts more configuration:</para>
            <itemizedlist>
              <listitem>
                <para>A <code>value</code> or a <code>pattern</code> element that is a child element used to match a constant or a pattern.</para>
              </listitem>
              <listitem>
                <para>A <code>control-mode</code> attribute with the <code>optional</code> or <code>required</code> value indicates if matching is mandatory or not.</para>
              </listitem>
              <listitem>
                <para>A <code>value-mapping</code> attribute with the possible values, such as <code>canonical</code>, <code>never-empty</code>, <code>never-null</code> can be used to filter values after matching is done. For instance, a parameter configured with <code>value-mapping="never-empty"</code> and matched with the empty string value will not put the empty string in the map.</para>
              </listitem>
            </itemizedlist>
          </section>
          <section id="sect-Reference_Guide-Navigation_Controller-Controller_Config-Route_Precedence">
            <title>Route precedence</title>
            <para>The order of route declaration is important as it affects on how rules are matched. Sometimes, the same request could be matched by several routes and the routing table is ambiguous.</para>
            <programlistingco>
              <areaspec units="linecolumn"/>
              <programlisting language="xml"><![CDATA[
<route path="/foo">
  <route-param qname="gtn:handler">
    <value>portal</value>
  </route-param>
</route>
<route path="/{gtn:path}">
  <path-param encoding="preserve-path" qname="gtn:path">
    <pattern>.*</pattern>
  </path-param>
</route>
]]></programlisting>
            </programlistingco>
            <para>In that case, the request path "/foo" will always be matched by the first rule before the second rule. This can be misleading since the map (gtn:path=foo) would be rendered as "/foo" as well and would not be matched by the first rule. Such ambiguit can happen, it can be desirable or not.</para>
          </section>
          <section id="sect-Reference_Guide-Navigation_Controller-Controller_Config-Route_nesting">
            <title>Route nesting</title>
            <para>Route nesting is possible and often desirable as it helps to:</para>
            <itemizedlist>
              <listitem>
                <para>Factor common parameters in a common rule.</para>
              </listitem>
              <listitem>
                <para>Perform more efficient matching as the match of the common rule is done once for all the sub routes.</para>
              </listitem>
            </itemizedlist>
            <programlistingco>
              <areaspec units="linecolumn"/>
              <programlisting language="xml"><![CDATA[
<route path="/foo">
  <route-param qname="gtn:handler">
    <value>portal</value>
  </route-param>
  <route path="/bar">
    <route-param qname="gtn:path">
      <value>bar</value>
    </route-param>
  </route>
  <route path="/juu">
    <route-param qname="gtn:path">
      <value>juu</value>
    </route-param>
  </route>
</route>
]]></programlisting>
            </programlistingco>
            <itemizedlist>
              <listitem>
                <para>The request path "/foo/bar" is mapped to the (gtn:handler=portal,gtn:path=bar) map.</para>
              </listitem>
              <listitem>
                <para>The request path "/foo/juu" is mapped to the (gtn:handler=portal,gtn:path=juu) map.</para>
              </listitem>
              <listitem>
                <para>The request path "/foo" is not mapped as non leaf routes do not perform matches.</para>
              </listitem>
            </itemizedlist>
          </section>
        </section>
      </section>
      <section id="sect-Reference_Guide-Navigation_Controller-Integrate_Gatein_WebUI_Framework">
        <title>Integrate to GateIn WebUI framework</title>
        <section id="sect-Reference_Guide-Navigation_Controller-Integrate_Gatein_WebUI_Framework-Routing">
          <title>Routing</title>
          <para>GateIn defines a set of parameters in its routing table, for each client request, the mapping engine processes the request path and return the defined parameters with their values as a Map&lt;QualifiedName, String&gt;</para>
          <para>
            <emphasis role="bold">gtn:handler</emphasis>
          </para>
          <para>The gtn:handler names is one of the most important qualified name as it determines which handler will take care of the request processing just after the controller has determined the parameter map. The handler value is used to make a lookup in the handler map of the controller. An handler is a class that extends the <code>WebRequestHandler</code> class and implements the <code>execute(ControllerContext)</code> method. Several handlers are available by default:</para>
          <itemizedlist>
            <listitem>
              <para>portal: process aggregated portal requests.</para>
            </listitem>
            <listitem>
              <para>upload/download: process file upload and download.</para>
            </listitem>
            <listitem>
              <para>standalone: process standalone portal requests.</para>
            </listitem>
            <listitem>
              <para>legacy: handle legacy URL redirection (see <xref linkend="sect-Reference_Guide-Navigation_Controller-Legacy_handler"/>).</para>
            </listitem>
            <listitem>
              <para>default: HTTP redirection to the default portal of the container.</para>
            </listitem>
            <listitem>
              <para>staticResource: serve static resources like image, CSS or JavaScript and more in <emphasis role="bold">portal.war</emphasis> (see <xref linkend="sect-Reference_Guide-Navigation_Controller-Static_resource_handler"/>).</para>
            </listitem>
          </itemizedlist>
          <para>
            <emphasis role="bold">gtn:sitetype / gtn:sitename / gtn:path</emphasis>
          </para>
          <para>Those qualified names drives a request for the portal handler. They are used to determine which site to show and which path to resolve against a navigation. For instance, the (gtn:sitetype=portal,gtn:sitename=classic,gtn:path=home) instruct the portal handler to show the home page of the classic portal site.</para>
          <para>
            <emphasis role="bold">gtn:lang</emphasis>
          </para>
          <para>This parameter shows which language used in the URL for the portal handler. This is a new feature offered, now language can be specified on URL. It means that users can bookmark that URL (with the information about language) or he can changed the language simply by modifying the URL address.</para>
          <para>
            <emphasis role="bold">gtn:componentid / gtn:action / gtn:objectid</emphasis>
          </para>
          <para>The webui parameters used by the portal handler for managing webui component URLs for portal applications (but not for portlet applications).</para>
        </section>
        <section id="sect-Reference_Guide-Navigation_Controller-Integrate_Gatein_WebUI_Framework-Rendering">
          <title>Rendering</title>
          <para>The <emphasis role="bold">controller</emphasis> is designed to render a Map&lt;QualifiedName, String&gt; as an HTTP URL according to its routing table, but to integrate it for easy usage in WebUI Framework of GateIn, you need some more components:</para>
          <section>
            <title>
              <emphasis role="bold">PortalURL</emphasis>
            </title>
            <para>
              <code>PortalURL</code> plays a similar role at the portal level. Its main role is to abstract the creation of an URL for a resource managed by the portal.</para>
            <programlistingco>
              <areaspec units="linecolumn"/>
              <programlisting language="java"><![CDATA[
public abstract class PortalURL<R, U extends PortalURL<U>>
{
   ...
}
]]></programlisting>
            </programlistingco>
            <para>The <code>PortalURL</code> declaration may seem a bit strange at first sight with two generic types: <code>U</code> and <code>R</code>.</para>
            <itemizedlist>
              <listitem>
                <para>The <code>R</code> generic type represents the type of the resource managed by the portal.</para>
              </listitem>
              <listitem>
                <para>The <code>U</code> generic type is also described as <emphasis role="bold">self bound generic type</emphasis>. This design pattern allows a class to return subtypes of itself in the class declaring the generic type. Java Enums are based on this principle (<code>class Enum&lt;E extends Enum&lt;E&gt;&gt;</code>).</para>
              </listitem>
            </itemizedlist>
            <para>A portal URL has various methods but certainly the most important method is the <code>toString()</code> method that generates an URL targeting to the resource. The remaining methods are <code>getter</code> and <code>setter</code> used to mutate the URL configuration, those options will affect the URL representation when it is generated.</para>
            <itemizedlist>
              <listitem>
                <para>resource: the mandatory resource associated with the URL.</para>
              </listitem>
              <listitem>
                <para>locale: the optional locale used in the URL allowing the creation of bookmarkable URL containing a language.</para>
              </listitem>
              <listitem>
                <para>confirm: the optional confirmation message displayed by the portal in the context of the portal UI.</para>
              </listitem>
              <listitem>
                <para>ajax: the ajax option allowing an ajax invocation of the URL.</para>
              </listitem>
            </itemizedlist>
            <para>
              <emphasis role="bold">Obtaining a PortalURL</emphasis>
            </para>
            <para>
              <code>PortalURL</code> objects are obtained from <code>RequestContext</code> instance, such as the <code>PortalRequestContext</code>, or the <code>PortletRequestContext</code>. Usually, those are obtained thanks to the <code>getCurrentInstance</code> method of the <code>RequestContext</code> class:</para>
            <programlistingco>
              <areaspec units="linecolumn"/>
              <programlisting language="java"><![CDATA[
RequestContext ctx = RequestContext.getCurrentInstance();
]]></programlisting>
            </programlistingco>
            <para>
              <code>PortalURL</code> are created via to the <code>createURL</code> method that takes an input as a resource type. The resource type is usually a constant and type-safe object that allows to retrieve the <code>PortalURL</code> subclasses:</para>
            <programlistingco>
              <areaspec units="linecolumn"/>
              <programlisting language="java"><![CDATA[
RequestContext ctx = RequestContext.getCurrentInstance();
PortalURL<R, U> url = ctx.createURL(type);
]]></programlisting>
            </programlistingco>
            <para>In reality, you will use a concrete type constant and have instead more concrete code like:</para>
            <programlistingco>
              <areaspec units="linecolumn"/>
              <programlisting language="java"><![CDATA[
RequestContext ctx = RequestContext.getCurrentInstance();
NodeURL url = ctx.createURL(NodeURL.TYPE);
]]></programlisting>
            </programlistingco>
            <note>
              <para>The <code>NodeURL.TYPE</code> is actually declared as <code>new ResourceType&lt;NavigationResource, NodeURL&gt;()</code> that can be described as a <code>type-literal</code> object emulated by a Java anonymous inner class. Such literal was introduced by Neil Gafter as Super Type Token and popularized by Google Guice as Type Literal. It is an interesting way to create a literal representing a kind of Java type.</para>
            </note>
          </section>
          <section id="sect-Reference_Guide-Navigation_Controller-Integrate_Gatein_WebUI_Framework-NodeURL">
            <title>
              NodeURL
            </title>
            <para>The <code>NodeURL</code> class is one of the subclass of <code>PortalURL</code> that is specialized in navigation node resources:</para>
            <programlistingco>
              <areaspec units="linecolumn"/>
              <programlisting language="java"><![CDATA[
public class NodeURL extends PortalURL<NavigationResource, NodeURL>
{
   ...
}
]]></programlisting>
            </programlistingco>
            <para>The <code>NodeURL</code> class does not carry any generic types of its super class, which means that a <code>NodeURL</code> is type-safe and you do not have to worry about generic types.</para>
            <para>Using a <code>NodeURL</code> is pretty straightforward:</para>
            <programlistingco>
              <areaspec units="linecolumn"/>
              <programlisting language="java"><![CDATA[
NodeURL url = RequestContext.getCurrentInstance().createURL(NodeURL.TYPE);
url.setResource(new NavigationResource("portal", "classic, "home"));
String s = url.toString();
]]></programlisting>
            </programlistingco>
            <para>The <code>NodeURL</code> subclass contains the specialized <code>setter</code> methods to make its usage even easier:</para>
            <programlistingco>
              <areaspec units="linecolumn"/>
              <programlisting language="java"><![CDATA[
UserNode node = ...;
NodeURL url = RequestContext.getCurrentInstance().createURL(NodeURL.TYPE);
url.setNode(node);
String s = url.toString();
]]></programlisting>
            </programlistingco>
          </section>
          <section id="sect-Reference_Guide-Navigation_Controller-Integrate_Gatein_WebUI_Framework-ComponentURL">
            <title>
              ComponentURL
            </title>
            <para>The <code>ComponentURL</code> subclass is another specialization of <code>PortalURL</code> that allows the creation of WebUI components URLs. <code>ComponentURL</code> is commonly used to trigger WebUI events from client side:</para>
            <programlistingco>
              <areaspec units="linecolumn"/>
              <programlisting><![CDATA[
<% def componentURL = uicomponent.event(...); /*or uicomponent.url(...) */ %>
  <a href=$componentURL>Click me</a>
]]></programlisting>
            </programlistingco>
            <para>Normally, you should not have to deal with it as the WebUI framework has already an abstraction for managing URL known as <code>URLBuilder</code>. The <code>URLBuilder</code> implementation delegates URL creation to <code>ComponentURL</code> objects.</para>
          </section>
          <section>
            <title>Portlet URLs</title>
            <para>Portlet URLs API implementation delegates to the portal <code>ComponentURL</code> (via the portlet container SPI). It is possible to control the language in the URL from a <code>PortletURL</code> object by setting the <code>gtn:lang</code> property:</para>
            <itemizedlist>
              <listitem>
                <para>When the property value is set to a value returned by the <code>Locale#toString()</code> method for locale objects having a non null language value and a null variant value, the URL generated by the <code>PortletURL#toString()</code> method will contain the locale in the URL.</para>
              </listitem>
              <listitem>
                <para>When the property value is set to an empty string, the generated URL will not contain a language. If the incoming URL was carrying a language, this language will be erased.</para>
              </listitem>
              <listitem>
                <para>When the property value is not set, it will not affect the generated URL.</para>
              </listitem>
            </itemizedlist>
            <programlistingco>
              <areaspec units="linecolumn"/>
              <programlisting language="java"><![CDATA[
PortletURL url = resp.createRenderURL();
url.setProperty("gtn:lang", "fr");
writer.print("<a href='" + url + "'>French</a>");
]]></programlisting>
            </programlistingco>
          </section>
          <section id="sect-Reference_Guide-Navigation_Controller-Integrate_Gatein_WebUI_Framework-URLBuilder">
            <title>Webui <code>URLBuilder</code>
            </title>
            <para>This internal API used to create URL works as usual and delegates to the <code>PortletURL</code> API when the framework is executed in a portlet, and delegates to a <code>ComponentURL</code> API when the framework is executed in the portal context. The API has been modified to take in account the language in URL with two properties on the builder:</para>
            <itemizedlist>
              <listitem>
                <para>locale: a locale for setting on the URL.</para>
              </listitem>
              <listitem>
                <para>removeLocale: a boolean for removing the locale present on the URL.</para>
              </listitem>
            </itemizedlist>
          </section>
          <section id="sect-Reference_Guide-Navigation_Controller-Integrate_Gatein_WebUI_Framework-Groovy_Templates">
            <title>Groovy Templates</title>
            <para>In a Groovy template, the mechanism to create an URL is the same as the way of APIs above, however a splash of integration has been done to make creation of NodeURL simpler. A closure is bound under the <code>nodeurl</code> name and is available for invocation anytime. It will simply create a NodeURL object and return it:</para>
            <programlistingco>
              <areaspec units="linecolumn"/>
              <programlisting language="java"><![CDATA[
UserNode node = ...;
NodeURL url = nodeurl();
url.setNode(node);
String s = url.toString();
]]></programlisting>
            </programlistingco>
            <para>The <code>nodeurl</code> closure is bound to Groovy template in <code>WebuiBindingContext</code>.
            </para>
            <programlistingco>
              <areaspec units="linecolumn"/>
              <programlisting language="java"><![CDATA[
// Closure nodeurl()
put("nodeurl", new Closure(this)
{
  @Override
  public Object call(Object[] args)
  {
    return context.createURL(NodeURL.TYPE);
  }
});
]]></programlisting>
            </programlistingco>
          </section>
        </section>
      </section>
      <section id="sect-Reference_Guide-Navigation_Controller-Changes_Migration">
        <title>Changes and migration from GateIn 3.1.x</title>
        <para>The navication controller implies a migration of the client code that is coupled to several internal APIs of GateIn. The major impact is related to anything dealing with URL:</para>
        <itemizedlist>
          <listitem>
            <para>Creation of an URL representing a resource managed by the portal: navigation node or UI component.</para>
          </listitem>
          <listitem>
            <para>Using HTTP request related information.</para>
          </listitem>
        </itemizedlist>
        
        <section id="sect-Reference_Guide-Navigation_Controller-Changes_Migration-Navigation_Node_URL">
          <title>Migration of navigation node URL</title>
          <para>
            <emphasis role="bold">Using free form node</emphasis>
          </para>
          <para>The previous code for creating navigation node was like:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="java"><![CDATA[
String uri = Util.getPortalRequestContext().getPortalURI() + "home";
]]></programlisting>
          </programlistingco>
          <para>The new code will look like:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="java"><![CDATA[
PortalURL nodeURL = nodeurl();
NavigationResource resource = new NavigationResource(SiteType.PORTAL, pcontext.getPortalOwner(), "home");
String uri = nodeURL.setResource(resource).toString();
]]></programlisting>
          </programlistingco>
          <para>
            <emphasis role="bold">Using UserNode object</emphasis>
          </para>
		  <para>The previous code for creating navigation node was like:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="java"><![CDATA[
UserNode node = ...;
String uri = Util.getPortalRequestContext().getPortalURI() + node.getURI()";
]]></programlisting>
          </programlistingco>
          <para>The new code will look like</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="java"><![CDATA[
UserNode node = ...;
PortalURL nodeURL = nodeurl();
String uri = nodeURL.setNode(node).toString();
]]></programlisting>
          </programlistingco>
        </section>
        <section id="sect-Reference_Guide-Navigation_Controller-Changes_Migration-Security_Changes">
          <title>Security changes</title>
          <para>Security configuration needs to be changed to keep the flexibility added by the navigation controller. In particular, the authentication does not depend anymore on path specified in <code>web.xml</code> but relies on the security mandated by the underlying resource instead. Here are the noticeable changes for security:</para>
          <itemizedlist>
            <listitem>
              <para>Authentication is now triggered on the "<code>/login</code>" URL when it does not have a username or a password specified. Therefore, the URL <code>/login?initialURI=/classic/home</code> is (more or less) equivalent to <code>/private/classic/home</code>.
              </para>
            </listitem>
            <listitem>
              <para>When a resource cannot be viewed due to security constraint.</para>
              <itemizedlist>
                <listitem>
                  <para>If the user is not logged, the authentication will be triggered.</para>
                </listitem>
                <listitem>
                  <para>Otherwise, a special page (the usual one) will be displayed instead.</para>
                </listitem>
              </itemizedlist>
            </listitem>
          </itemizedlist>
        </section>
        <section id="sect-Reference_Guide-Navigation_Controller-Changes_Migration-Default_handler">
          <title>Default handler</title>
          <para>Redirection to the default portal used to be done by the <code>index.jsp</code> JSP page. This is not the case anymore, the <emphasis>index.jsp</emphasis> file has been removed and the welcome file in <code>web.xml</code> was removed, too. Instead a specific handler in the routing table has been configured, the sole role of this handler is to redirect the request to the default portal when no other request has been matched previously:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[
<controller>
  ...
  <route path="/">
    <route-param qname="gtn:handler">
      <value>default</value>
    </route-param>
  </route>
</controller>
]]></programlisting>
          </programlistingco>
        </section>
        <section id="sect-Reference_Guide-Navigation_Controller-Legacy_handler">
          <title>Legacy handler</title>
          <para>Legacy URLs such as <code>/public/...</code> and <code>/private/...</code> are now emulated to determine the best resource with the same resolution algorithm, but instead of displaying the page, it will make an HTTP 302 redirection to the correct URL. This handler is present in the controller configuration. There is a noticeable difference between the two routes.</para>
          <itemizedlist>
            <listitem>
              <para>The public redirection attempts to find a node with the legacy resolution algorithm without authentication, which means that secured nodes will not be resolved and the redirection of a secured node will likely redirect to another page. For instance, resolving the URL <emphasis>/public/classic/administration/registry</emphasis> path will likely resolve to another node if the user is not authenticated and is not in the platform administrator group.</para>
            </listitem>
            <listitem>
              <para>The private redirection performs first an authentication before doing the redirection. In that case, the <emphasis>/private/classic/administration/registry</emphasis> path will be redirected to the <emphasis>/portal/groups/:platform:administrators/administration/registry</emphasis> page if the user has the sufficient security rights.</para>
            </listitem>
          </itemizedlist>
        </section>
        <section id="sect-Reference_Guide-Navigation_Controller-Static_resource_handler">
          <title>Static resource handler</title>
          <para>The "/" mapping for the "default" servlet is now replaced by mapping for the <code>org.exoplatform.portal.application.PortalController</code> servlet. It means that you need a handler (<emphasis>org.exoplatform.portal.application.StaticResourceRequestHandler</emphasis>) to serve static resources like image, CSS or JavaScript files in <code>portal.war</code>. And it should be configured, and extended easily thanks to the <code>controller.xml</code> file. This file can be overridden and can be changed and reloaded at runtime (WebAppController is MBean with some operations, such as <code>reloadConfiguration()</code>).</para>
          <para>Declare StaticResourceHandler in <code>controller.xml</code></para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[
<route path="/{gtn:path}">
  <route-param qname="gtn:handler">
    <value>staticResource</value>
  </route-param>
  <path-param encoding="preserve-path" qname="gtn:path">
    <pattern>.*\.(jpg|png|gif|ico|css)</pattern>
  </path-param>
</route>
]]></programlisting>
          </programlistingco>
          <para>And you do not need these kinds of the following mapping in the <emphasis>web.xml</emphasis> in <code>portal.war</code> anymore.</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[
<servlet-mapping>
  <servlet-name>default</servlet-name>
  <url-pattern>*.jpg</url-pattern>
</servlet-mapping>
...
]]></programlisting>
          </programlistingco>
        </section>
        <section>
          <title>portal.war's web.xml changes</title>
          <para><emphasis role="bold">DoLoginServlet declaration</emphasis>:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[
<servlet>
  <servlet-name>DoLoginServlet</servlet-name>
  <servlet-class>org.exoplatform.web.login.DoLoginServlet</servlet-class>
</servlet>
<servlet-mapping>
  <servlet-name>DoLoginServlet</servlet-name>
  <url-pattern>/dologin</url-pattern>
</servlet-mapping>
]]></programlisting>
          </programlistingco>
          <para>Delare <emphasis role="bold">portal servlet</emphasis> as the default servlet:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[
<servlet-mapping>
   <servlet-name>portal</servlet-name>
   <url-pattern>/</url-pattern>
</servlet-mapping>
]]></programlisting>
          </programlistingco>
          <para>Some mapping declarations for portal servlet are unused,so you should remove them: <emphasis role="bold">
              <emphasis role="italic">/private/* /public/* /admin/* /upload/* /download/*</emphasis>
            </emphasis>
          </para>
          <para><emphasis role="bold">Add some security constraints</emphasis>:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[
<security-constraint>
  <web-resource-collection>
    <web-resource-name>user authentication</web-resource-name>
      <url-pattern>/dologin</url-pattern>
      <url-pattern>/standalone/*</url-pattern>
      <url-pattern>/groups/*</url-pattern>
      <url-pattern>/users/*</url-pattern>
...
  </web-resource-collection>
</security-constraint>
]]></programlisting>
          </programlistingco>
          <para>You can remove the <emphasis>index.jsp</emphasis> file, and its declaration in the <emphasis>web.xml</emphasis> file thank to the default request handler:</para>
          <programlistingco>
            <areaspec units="linecolumn"/>
            <programlisting language="xml"><![CDATA[
<welcome-file-list>
  <welcome-file>/index.jsp</welcome-file>
</welcome-file-list>
]]></programlisting>
          </programlistingco>
        </section>
        <section id="sect-Reference_Guide-Navigation_Controller-Changes_Migration-Dashboard_changes">
          <title>Dashboard changes</title>
          <para>There are several important changes to take in account:</para>
          <itemizedlist>
            <listitem>
              <para>Dashboard are now bound to a single URL (/users/root by default) and dashboard pages are leaf of this path.</para>
            </listitem>
            <listitem>
              <para>Dashboard lifecycle can be decoupled (create or destroy) from the identity creation in a configurable manner in <code>UserPortalConfigService</code> and exposed in <code>configuration.properties</code> under <code>gatein.portal.idm.createuserportal</code> and <code>gatein.portal.idm.destroyuserportal</code>.</para>
            </listitem>
            <listitem>
              <para>By default, dashboard are not created when a user is registered.</para>
            </listitem>
            <listitem>
              <para>A dashboard is created when the user accesses his dashboard URL.</para>
            </listitem>
          </itemizedlist>
        </section>
        <section id="sect-Reference_Guide-Navigation_Controller-Changes_Migration-Remove_unused_files">
          <title>Remove unused files</title>
          <para><emphasis role="bold">portal-unavailable.jsp</emphasis>: this file is presented before if a user goes to a non-available portal. But now the server sends a 404 status code instead.</para>
          <para><emphasis role="bold">portal-warning.jsp</emphasis>: this file is not used in any places.</para>
        </section>
      </section>
</section>
