<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<section id="JCRWithGateIn.HowToExtendMyGateInInstance">
  <title>How to extend my GateIn instance?</title>

  <para>Since GateIn beta 2, there are a set of features added to customize a
  GateIn instance without modifying the GateIn binary. This usecase will be
  called <emphasis>portal extension</emphasis> in this documentation. Those
  features are also required to be able to launch several portal instances at
  the same time, in "eXo terminology" that means to have several
  "portal.war".</para>

  <section id="JCRWithGateIn.HowToExtendMyGateInInstance.Motivations">
    <title>Motivations</title>

    <para>Up to now, to create an application over an GateIn such as DMS, WCM,
    CS and KS, we need to modify files into the "portal.war". This has many
    painful consequences, such as:</para>

    <itemizedlist>
      <listitem>
        <para>It is quite hard to manage from the support point of view since
        we never know if or how the customer changed his eXo product.</para>
      </listitem>

      <listitem>
        <para>It is hard to be able to package several eXo products (WCM,
        CS...) as we need to merge everything manually which is quite error
        prone.</para>
      </listitem>
    </itemizedlist>

    <para>Finally, at the very beginning, eXo was developed to be able to
    support several portal instances (which also means several portal
    containers) but with the time several bad practices made it impossible. So
    it was important to review the whole code base in order to help/enforce
    all the GateIn developers to follow the "good practices".</para>
  </section>

  <section id="JCRWithGateIn.HowToExtendMyGateInInstance.Prerequisites">
    <title>Prerequisites</title>

    <para>To be able to migrate an application to GateIn, the first thing we
    need to do is to ensure that our application supports properly several
    portal container instances. The following section aims to help you to be
    compatible with GateIn.</para>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.Prerequisites.RemovingAllHardCodedPortalContainerName">
      <title>Removing all the hard coded portal container name (i.e.
      "portal")</title>

      <para>Now if we need to get the portal container name (even in a
      standalone mode: in case of standalone mode the default value will be
      returned), we can:</para>

      <itemizedlist>
        <listitem>
          <para>If the component is instantiated by Pico container, you can
          add in the constructor of your component, the component
          <emphasis>ExoContainerContext</emphasis>, then call the method
          <emphasis>getPortalContainerName()</emphasis></para>
        </listitem>

        <listitem>
          <para>If the component is not instantiated by Pico container, you
          can call at runtime the static method
          <emphasis>PortalContainer.getCurrentPortalContainerName()</emphasis></para>
        </listitem>

        <listitem>
          <para>In js files, you can use the variable
          <emphasis>currentContext</emphasis> if your script must be loaded
          before the variable <emphasis>eXo.env.server.context</emphasis>,
          otherwise use <emphasis>eXo.env.server.context</emphasis>
          instead.</para>
        </listitem>

        <listitem>
          <para>In jsp files, you can use
          <emphasis>request.getContextPath()</emphasis>.</para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.Prerequisites.RemovingAllHardCodedRestContextName">
      <title>Removing all the hard coded rest context name (i.e.
      "rest")</title>

      <para>Now if we need to get the rest context name (even in a standalone
      mode: in case of standalone mode the default value will be returned), we
      can:</para>

      <itemizedlist>
        <listitem>
          <para>If the component is instantiated by Pico container, you can
          add in the constructor of your component, the component
          <emphasis>ExoContainerContext</emphasis>, then call the method
          <emphasis>getRestContextName()</emphasis></para>
        </listitem>

        <listitem>
          <para>If the component is not instantiated by Pico container, you
          can call at runtime the static method
          <emphasis>PortalContainer.getCurrentRestContextName()</emphasis></para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.Prerequisites.RemovingAllHardCodedRealmName">
      <title>Removing all the hard coded realm name (i.e.
      "exo-domain")</title>

      <para>Now if we need to get the realm name (even in a standalone mode:
      in case of standalone mode the default value will be returned), we
      can:</para>

      <itemizedlist>
        <listitem>
          <para>If the component is instantiated by Pico container, you can
          add in the constructor of your component, the component
          <emphasis>ExoContainerContext</emphasis>, then call the method
          <emphasis>getRealmName()</emphasis></para>
        </listitem>

        <listitem>
          <para>If the component is not instantiated by Pico container, you
          can call at runtime the static method
          <emphasis>PortalContainer.getCurrentRealmName()</emphasis></para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.Prerequisites.MakingHttpFiltersCompatible">
      <title>Making your Http Filters compatible</title>

      <para>Now all your Http Filters that need to get the current
      <emphasis>ExoContainer</emphasis> must extends
      <emphasis>org.exoplatform.container.web.AbstractFilter</emphasis>. You
      just need to call the method <emphasis>getContainer()</emphasis> to get
      the current <emphasis>ExoContainer</emphasis>.</para>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.Prerequisites.MakingHttpServletsCompatible">
      <title>Making your HttpServlets compatible</title>

      <para>Now all your HttpServlets that need to get the current
      <emphasis>ExoContainer</emphasis> must extends
      <emphasis>org.exoplatform.container.web.AbstractHttpServlet</emphasis>.
      This abstract class will ensure that the environment has been properly
      set, so you will be able to call the usual methods such as
      <emphasis>ExoContainerContext.getCurrentContainer()</emphasis> (if it
      must also be compatible with the standalone mode) or
      <emphasis>PortalContainer.getInstance()</emphasis> (if it will only work
      on a portal environment mode).</para>

      <para>If you had to implement the method
      <emphasis>service(HttpServletRequest req, HttpServletResponse
      res)</emphasis>, now you will need to implement
      <emphasis>onService(ExoContainer container, HttpServletRequest req,
      HttpServletResponse res)</emphasis>, this method will directly give you
      the current <emphasis>ExoContainer</emphasis> in its signature.</para>

      <important>
        <title>Useful Information</title>

        <para>In the class
        <emphasis>org.exoplatform.container.web.AbstractHttpServlet</emphasis>
        you have a method called
        <emphasis>requirePortalEnvironment()</emphasis> that is used to
        indicate that we would like the abstract class to setup or not the
        full portal environment ( <emphasis>PortalContainer</emphasis>,
        <emphasis>ClassLoader</emphasis> and
        <emphasis>ServletContext</emphasis>) before executing the servlet.
        This value should return true when the servlet is executed within the
        web application of a portal container. By default, it checks if the
        name of the current <emphasis>ServletContext</emphasis> is a portal
        container name, it is sufficient in most of cases but you can still
        overload this method if you already know that the servlet will always
        been executed within the web application of portal container (i.e. the
        method always return true) or will never be executed within the web
        application of a portal container (i.e. the method always return
        false) .</para>
      </important>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.Prerequisites.MakingHttpSessionListenersCompatible">
      <title>Making your HttpSessionListeners compatible</title>

      <para>Now all your HttpSessionListeners that need to get the current
      <emphasis>ExoContainer</emphasis> must extends
      <emphasis>org.exoplatform.container.web.AbstractHttpSessionListener</emphasis>.
      This abstract class will give you the current
      <emphasis>ExoContainer</emphasis> directly in the signature of the
      methods to implement which are _ onSessionCreated(ExoContainer
      container, HttpSessionEvent event)\_ and
      <emphasis>onSessionDestroyed(ExoContainer container, HttpSessionEvent
      event)</emphasis></para>

      <para>You will also need to implement the method called
      <emphasis>requirePortalEnvironment()</emphasis> that is used to indicate
      that we would like the abstract class to setup or not the full portal
      environment ( <emphasis>PortalContainer</emphasis> and
      <emphasis>ClassLoader</emphasis>) before processing the event. This
      value should return true when the event is processed within the web
      application of a portal container.</para>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.Prerequisites.UseInitTasks">
      <title>Use init tasks if you need a PortalContainer to initialize an
      Http Filter or an HttpServlet</title>

      <para>If your Http <emphasis>Filter</emphasis> or your
      <emphasis>HttpServlet</emphasis> requires a PortalContainer to
      initialize, you need to convert your code in order to launch the code
      responsible for the initialization in the method
      <emphasis>onAlreadyExists</emphasis> of an
      <emphasis>org.exoplatform.container.RootContainer.PortalContainerInitTask</emphasis>.</para>

      <para>We need to rely on init tasks, in order to be sure that the portal
      container is at the right state when the task is executed, in other
      words the task could be delayed if you try to execute it too early. Each
      task is linked to a web application, so when we add a new task, we first
      retrieve all the portal containers that depend on this web application
      according to the <emphasis>PortalContainerDefinitions</emphasis>, and
      for each container we add the task in a sorted queue which order is in
      fact the order of the web applications dependencies defined in the
      <emphasis>PortalContainerDefinition</emphasis>. If no
      <emphasis>PortalContainerDefinition</emphasis> can be found we execute
      synchronously the task which is in fact the old behavior (i.e. without
      the starter).</para>

      <para>The supported init tasks are:</para>

      <itemizedlist>
        <listitem>
          <para>The
          <emphasis>org.exoplatform.container.RootContainer.PortalContainerPreInitTask</emphasis>
          which are executed before the portal container has been
          initialized</para>
        </listitem>

        <listitem>
          <para>The
          <emphasis>org.exoplatform.container.RootContainer.PortalContainerPostInitTask</emphasis>
          which are executed after the portal container has been
          initialized</para>
        </listitem>

        <listitem>
          <para>The
          <emphasis>org.exoplatform.container.RootContainer.PortalContainerPostCreateTask</emphasis>
          which are executed after the portal container has been fully created
          (i.e. after all the post init tasks).</para>
        </listitem>
      </itemizedlist>

      <para>An init task is defined as below:</para>

      <note>
        <title>PortalContainerPreInitTask</title>

        <programlisting language="java">   /**
    * This interface is used to define a task that needs to be launched at a given state during the
    * initialization of a portal container
    */
   public static interface PortalContainerInitTask
   {

      /**
       * This method allows the implementation to define what the state "already exists"
       * means for a portal container
       *
       * @param portalContainer the value of the current portal container
       * @return &lt;code&gt;true&lt;/code&gt; if the portal container exists according to the task
       * requirements, &lt;code&gt;false&lt;/code&gt; otherwise
       */
      public boolean alreadyExists(PortalContainer portalContainer);

      /**
       * This method is called if the related portal container has already been registered
       *
       * @param context the servlet context of the web application
       * @param portalContainer the value of the current portal container
       */
      public void onAlreadyExists(ServletContext context, PortalContainer portalContainer);

      /**
       * Executes the task
       *
       * @param context the servlet context of the web application
       * @param container The portal container on which we would like to execute the task
       */
      public void execute(ServletContext context, PortalContainer portalContainer);

      /**
       * @return the type of the task
       */
      public String getType();
   }</programlisting>
      </note>

      <para>To add a task, you can either call:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis>PortalContainer.addInitTask(ServletContext context,
          PortalContainerInitTask task)</emphasis> in order to execute the
          task on all the portal containers that depend on the given
          <emphasis>ServletContext</emphasis> according to the
          <emphasis>PortalContainerDefinitions</emphasis>.</para>
        </listitem>

        <listitem>
          <para><emphasis>PortalContainer.addInitTask(ServletContext context,
          PortalContainerInitTask task, String portalContainerName)</emphasis>
          in order to execute the task on a given portal container.</para>
        </listitem>

        <listitem>
          <para><emphasis>RootContainer.addInitTask(ServletContext context,
          PortalContainerInitTask task)</emphasis> in order to execute the
          task on the portal container which name is the name of the given
          <emphasis>ServletContext</emphasis>.</para>
        </listitem>
      </itemizedlist>

      <para>We will take for example the class
      <emphasis>GadgetRegister</emphasis> that is used to register new google
      gadgets on a given portal container.</para>

      <para><emphasis role="underline">The old code was:</emphasis></para>

      <note>
        <title>Old GadgetRegister.java</title>

        <programlisting language="java">...
public class GadgetRegister implements ServletContextListener
{
...
  public void contextInitialized(ServletContextEvent event)
  {
    try
    {
      ExoContainer pcontainer =  ExoContainerContext.getContainerByName("portal") ;
      SourceStorage sourceStorage = (SourceStorage)pcontainer.getComponentInstanceOfType(SourceStorage.class);
      ...
  }
  ...
}</programlisting>
      </note>

      <para>The new code relies on a
      <emphasis>org.exoplatform.container.RootContainer.PortalContainerPostInitTask</emphasis>,
      as you can see below</para>

      <note>
        <title>New GadgetRegister.java</title>

        <programlisting language="java">...
public class GadgetRegister implements ServletContextListener {
...
   public void contextInitialized(ServletContextEvent event)
   {
      // Create a new post init task
      final PortalContainerPostInitTask task = new PortalContainerPostInitTask()
      {

         public void execute(ServletContext context, PortalContainer portalContainer)
         {
            contextInitialized(context, portalContainer);
         }
      };
      // Add the init task to all the related portal containers
      PortalContainer.addInitTask(event.getServletContext(), task);
   }

   private void contextInitialized(ServletContext context, PortalContainer pcontainer)
   {
      try
      {
         SourceStorage sourceStorage = (SourceStorage)pcontainer.getComponentInstanceOfType(SourceStorage.class);
         ...
   }
  ...
}</programlisting>
      </note>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.Prerequisites.MakingLoginModulesCompatible">
      <title>Making your LoginModules compatible</title>

      <para>Now all your LoginModules that need to get the current
      <emphasis>ExoContainer</emphasis> must extends
      <emphasis>org.exoplatform.services.security.jaas.AbstractLoginModule</emphasis>.
      You just need to call the method <emphasis>getContainer()</emphasis> to
      get the current <emphasis>ExoContainer</emphasis>.</para>

      <important>
        <title>Useful Information</title>

        <para>The class
        <emphasis>org.exoplatform.services.security.jaas.AbstractLoginModule</emphasis>
        supports 2 login module options which are
        <emphasis>portalContainerName</emphasis> and
        <emphasis>realmName</emphasis>, to allow you to indicate the realm
        name and the portal container name, if you want to change the default
        value.</para>
      </important>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.Prerequisites.AvoidingStaticModifier">
      <title>Avoiding <emphasis>static</emphasis> modifier on component
      dependency</title>

      <para>A local variable that stores a component dependency must not be
      static. In other words, when you create a component A that depends on
      component B, we don't store B in a static variable of A otherwise we
      cannot have several different instances of A in the same JVM which is
      not compatible with a multi-portal instance.</para>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.Prerequisites.AvoidComponentInitialization">
      <title>Avoid component initialization based on component dependency in
      the constructor</title>

      <para>We will have more and more extensible components (i.e. that can be
      extended thanks to an external plugin) which means that those components
      can only be initialized in the <emphasis>start</emphasis> method, thus
      it is not a good practice to initialize a component in its constructor
      if this initialization uses other components because those components
      may not be initialized. For example, now the ResourceBundleService is
      extensible, so if you create a component that depends on the
      ResourceBundleService and you need the ResourceBundleService to
      initialize your component, your component will need to be "Startable"
      and you will have to initialize your component in a
      <emphasis>start</emphasis> method.</para>
    </section>
  </section>

  <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ">
    <title>FAQ</title>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.WhatChanged">
      <title>What has changed since the previous versions?</title>

      <para>The main difference with previous versions is the way to package
      your application, in the previous versions you had to change the content
      of the file <emphasis>portal.war</emphasis> in order to customize the
      portal. Now we more consider your application as an add-on that you can
      packaged in another ear/war file. You just need to follow some rules in
      order to notify the platform that it must take into account your add-on
      in order to customize the portal.</para>

      <para>Among other things, you will have to:</para>

      <itemizedlist>
        <listitem>
          <para>Indicate the platform how to initialize and manage your
          application by defining and registering the
          <emphasis>PortalContainerDefinition</emphasis> related to your
          portal instance.</para>
        </listitem>

        <listitem>
          <para>Deploy the <emphasis>starter</emphasis> ear/war file that is
          used to create and start all the portals (i.e. portal
          containers).</para>
        </listitem>
      </itemizedlist>

      <warning>
        <title>Warning</title>

        <para>Please take into account, that you need to ensure that the
        <emphasis>starter</emphasis> is launched after all the other ear/war
        files.</para>
      </warning>

      <important>
        <title>Nota Bene</title>

        <para>If you don't need to customize the portal, you don't have to
        deploy the starter. The old way to deploy an application is still
        compatible.</para>
      </important>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.WhatMainPurposeOfPortalExtension">
      <title>What is the main purpose of a <emphasis>portal
      extension</emphasis>?</title>

      <para>An <emphasis>extension</emphasis> is just a set of files that we
      use to customize or add new features to a given portal. An extension
      must be the least intrusive as possible, as we could potentially have
      several extensions for the same portal. In other words, we are supposed
      to only add what is missing in the portal and avoid changing or
      duplicated files that are in the portal.war.</para>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.WhatMainPurposeOfStarter">
      <title>What is the main purpose of the
      <emphasis>starter</emphasis>?</title>

      <para>The <emphasis>sarter</emphasis> is a web application that has been
      added to create and start all the portals (i.e. portal containers) at
      the same time when all the other web applications have already been
      started. In fact all other web applications can potentially defined
      several things at startup such as skins, javascripts, google gadgets and
      configuration files, thus the loading order is important as we can
      redefine skins or configuration files or a javascript from a web
      application 1 could depend on another javascript from a web application
      2 so if the web application 2 is loaded after the web application 1, we
      will get errors in the merged javascript file.</para>

      <para>If a <emphasis>PortalContainerDefinition</emphasis> has been
      defined, the loading order will be the order that has been used to
      define the list of dependency. And if you defined a
      <emphasis>PortalContainerDefinition</emphasis> you need to deploy the
      starter otherwise the loading order will be the default one (i.e. the
      loading order of the Application Server)</para>

      <para>So if you need to customize your portal by adding a new extension
      and/or a new portal, you need to defined the related
      <emphasis>PortalContainerDefinitions</emphasis> so you need to deploy
      also the starter. Otherwise, you don't need to define any
      <emphasis>PortalContainerDefinition</emphasis> and to deploy the
      <emphasis>starter</emphasis>.</para>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowPortalAndPortalContainerRelated">
      <title>How a portal and a portal container are related?</title>

      <para>Each portal instance has its own portal container which allows the
      portal to have its own set of components/services. It will ensure the
      isolation between the different portal instances.</para>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToDefineAndRegisterPortalContainerDefinition">
      <title>How to define and register a
      <emphasis>PortalContainerDefinition</emphasis>?</title>

      <para>A <emphasis>PortalContainerDefinition</emphasis> allows you to
      indicate the platform how it must initialize and manage your portal. In
      a <emphasis>PortalContainerDefinition</emphasis>, you can define a set
      of properties, such as:</para>

      <itemizedlist>
        <listitem>
          <para>The name of the portal container</para>
        </listitem>

        <listitem>
          <para>The name of the context name of the rest web
          application</para>
        </listitem>

        <listitem>
          <para>The name of the realm</para>
        </listitem>

        <listitem>
          <para>The list of all the dependencies of the portal container
          ordered by priority</para>
        </listitem>
      </itemizedlist>

      <para>You can define and register a
      <emphasis>PortalContainerDefinition</emphasis> thanks to an external
      plugin that has to be treated at the <emphasis>RootContainer</emphasis>
      level. In other words, your configuration file must be a file
      <emphasis>conf/configuration.xml</emphasis> packaged into a jar file or
      $AS_HOME/exo-conf/configuration.xml (for more details, please have a
      look to the article <link
      linkend="Kernel.ContainerConfiguration">Container
      Configuration</link>).</para>

      <para><emphasis role="underline">See below an example of configuration
      file that define and register a
      PortalContainerDefinition:</emphasis></para>

      <programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;configuration
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"
  xmlns="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"&gt;
  &lt;external-component-plugins&gt;
    &lt;!-- The full qualified name of the PortalContainerConfig --&gt;
    &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt;
    &lt;component-plugin&gt;
      &lt;!-- The name of the plugin --&gt;
      &lt;name&gt;Add PortalContainer Definitions&lt;/name&gt;
      &lt;!-- The name of the method to call on the PortalContainerConfig in order to register the PortalContainerDefinitions --&gt;
      &lt;set-method&gt;registerPlugin&lt;/set-method&gt;
      &lt;!-- The full qualified name of the PortalContainerDefinitionPlugin --&gt;
      &lt;type&gt;org.exoplatform.container.definition.PortalContainerDefinitionPlugin&lt;/type&gt;
      &lt;init-params&gt;
        &lt;object-param&gt;
          &lt;name&gt;portal&lt;/name&gt;
          &lt;object type="org.exoplatform.container.definition.PortalContainerDefinition"&gt;
            &lt;!-- The name of the portal container --&gt;
            &lt;field name="name"&gt;&lt;string&gt;portal&lt;/string&gt;&lt;/field&gt;
            &lt;!-- The name of the context name of the rest web application --&gt;
            &lt;field name="restContextName"&gt;&lt;string&gt;rest&lt;/string&gt;&lt;/field&gt;
            &lt;!-- The name of the realm --&gt;
            &lt;field name="realmName"&gt;&lt;string&gt;exo-domain&lt;/string&gt;&lt;/field&gt;
            &lt;!-- All the dependencies of the portal container ordered by loading priority --&gt;
            &lt;field name="dependencies"&gt;
              &lt;collection type="java.util.ArrayList"&gt;
                &lt;value&gt;
                  &lt;string&gt;eXoResources&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;portal&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;dashboard&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;exoadmin&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;eXoGadgets&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;eXoGadgetServer&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;rest&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;web&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;wsrp-producer&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;sample-ext&lt;/string&gt;
                &lt;/value&gt;
              &lt;/collection&gt;
            &lt;/field&gt;
          &lt;/object&gt;
        &lt;/object-param&gt;
      &lt;/init-params&gt;
    &lt;/component-plugin&gt;
  &lt;/external-component-plugins&gt;
&lt;/configuration&gt;</programlisting>

      <para>In the previous example, we define a portal container called
      "portal", which rest context name is "rest", which realm name is
      "exo-domain" and which dependencies are the web applications
      "eXoResources", "portal"... The platform will load first "eXoResources",
      then "portal" and so on.</para>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowPlatformInterpretsDependencyOrder">
      <title>How the platform interprets the dependency order defined into the
      PortalContainerDefinition?</title>

      <para>The dependency order defined into the
      <emphasis>PortalContainerDefinition</emphasis> is really crucial since
      it will be interpreted the same way by several components of the
      platform. All those components, will consider the 1st element in the
      list is less important than the second element and so on.</para>

      <para><emphasis role="underline">So it is currently used
      to:</emphasis></para>

      <itemizedlist>
        <listitem>
          <para>Know loading order of all the dependencies</para>
        </listitem>

        <listitem>
          <para>If we have several
          <emphasis>PortalContainerConfigOwner</emphasis> (see next section
          for more details about a PortalContainerConfigOwner)</para>

          <itemizedlist>
            <listitem>
              <para>The ServletContext of all the
              <emphasis>PortalContainerConfigOwner</emphasis> will be unified,
              if we use the unified ServletContext
              (PortalContainer.getPortalContext()) to get a resource, it will
              try to get the resource in the ServletContext of the most
              important <emphasis>PortalContainerConfigOwner</emphasis> (i.e.
              last in the dependency list) and if it cans find it, it will try
              with the second most important
              <emphasis>PortalContainerConfigOwner</emphasis> and so
              on.</para>
            </listitem>

            <listitem>
              <para>The ClassLoader of all the
              <emphasis>PortalContainerConfigOwner</emphasis> will be unified,
              if we use the unified ClassLoader
              (PortalContainer.getPortalClassLoader()) to get a resource, it
              will try to get the resource in the ClassLoader of the most
              important <emphasis>PortalContainerConfigOwner</emphasis> (i.e.
              last in the dependency list) and if it cans find it, it will try
              with the second most important
              <emphasis>PortalContainerConfigOwner</emphasis> and so
              on.</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToChangeNameOfServletContextRealmRestContext">
      <title>How to change the ServletContext name, the realm name and/or the
      rest context name of my portal without using a
      PortalContainerDefinition?</title>

      <para>To do that you need first to change the default values used by a
      PortalContainer that has not been defined thanks to a
      <emphasis>PortalContainerDefinition</emphasis>. Those default values can
      be modified thanks to a set of init parameters of the component
      <emphasis>PortalContainerConfig</emphasis>.</para>

      <para>The component <emphasis>PortalContainerConfig</emphasis> must be
      registered at the <emphasis>RootContainer</emphasis> level. In other
      words, your configuration file must be a file
      <emphasis>conf/configuration.xml</emphasis> packaged into a jar file or
      $AS_HOME/exo-conf/configuration.xml (for more details please have a look
      to the article <link linkend="Kernel.ContainerConfiguration">Container
      Configuration</link>).</para>

      <para><emphasis role="underline">In the example below we will
      rename:</emphasis></para>

      <itemizedlist>
        <listitem>
          <para>The portal name "portal" to "myPortal".</para>
        </listitem>

        <listitem>
          <para>The rest servlet context name "rest" to "myRest".</para>
        </listitem>

        <listitem>
          <para>The realm name "exo-domain" to "my-exo-domain".</para>
        </listitem>
      </itemizedlist>

      <para><emphasis role="underline">See below an example</emphasis></para>

      <programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;configuration
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"
  xmlns="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"&gt;
  &lt;component&gt;
    &lt;!-- The full qualified name of the PortalContainerConfig --&gt;
    &lt;type&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/type&gt;
    &lt;init-params&gt;
      &lt;!-- The name of the default portal container --&gt;
      &lt;value-param&gt;
        &lt;name&gt;default.portal.container&lt;/name&gt;
        &lt;value&gt;myPortal&lt;/value&gt;
      &lt;/value-param&gt;
      &lt;!-- The name of the default rest ServletContext --&gt;
      &lt;value-param&gt;
        &lt;name&gt;default.rest.context&lt;/name&gt;
        &lt;value&gt;myRest&lt;/value&gt;
      &lt;/value-param&gt;
      &lt;!-- The name of the default realm --&gt;
      &lt;value-param&gt;
        &lt;name&gt;default.realm.name&lt;/name&gt;
        &lt;value&gt;my-exo-domain&lt;/value&gt;
      &lt;/value-param&gt;
    &lt;/init-params&gt;
  &lt;/component&gt;
&lt;/configuration&gt;</programlisting>

      <para>Once your configuration is ready, you need to:</para>

      <itemizedlist>
        <listitem>
          <para>Update the file <emphasis>WEB-INF/web.xml</emphasis> of the
          file "portal.war" by changing the "display-name" (the new value is
          "myPortal") and the "realm-name" in the "login-config" (the new
          value is "my-exo-domain").</para>
        </listitem>

        <listitem>
          <para>If you use JBoss AS: Update the file
          <emphasis>WEB-INF/jboss-web.xml</emphasis> of the file "portal.war"
          by changing the "security-domain" (the new value is
          "java:/jaas/my-exo-domain").</para>
        </listitem>

        <listitem>
          <para>Rename the "portal.war" to "myPortal.war" (or "02portal.war"
          to "02myPortal.war")</para>
        </listitem>

        <listitem>
          <para>Update the file <emphasis>WEB-INF/web.xml</emphasis> of the
          file "rest.war" by changing the "display-name" (the new value is
          "myRest") and the "realm-name" in the "login-config" (the new value
          is "my-exo-domain").</para>
        </listitem>

        <listitem>
          <para>If you use JBoss AS: Update the file
          <emphasis>WEB-INF/jboss-web.xml</emphasis> of the file "rest.war" by
          changing the "security-domain" (the new value is
          "java:/jaas/my-exo-domain").</para>
        </listitem>

        <listitem>
          <para>Rename the "rest.war" to "myRest.war"</para>
        </listitem>

        <listitem>
          <para>If "portal.war" and "rest.war" were embedded into an ear file:
          Update the file <emphasis>META-INF/application.xml</emphasis> of the
          file "exoplatform.ear" by remaming "02portal.war" to
          "02myPortal.war", "portal" to "myPortal", "rest.war" to "myRest.war"
          and "rest" to "myRest".</para>
        </listitem>
      </itemizedlist>

      <para>The end of the process depends on your application server</para>

      <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToChangeNameOfServletContextRealmRestContext.JBoss">
        <title>On JBoss (tested on JBoss 5.1.0.GA)</title>

        <para>You need to change the name of the application policy in your
        file <emphasis>conf/login-config.xml</emphasis> (the new name is
        "my-exo-domain").</para>
      </section>

      <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToChangeNameOfServletContextRealmRestContext.Tomcat">
        <title>On Tomcat (tested on Tomcat 6.0.20)</title>

        <para><emphasis role="underline">You need to:</emphasis></para>

        <itemizedlist>
          <listitem>
            <para>Update the file
            <emphasis>tomcat/conf/Catalina/localhost/portal.xml</emphasis> by
            changing the "path" (the new value is "/myPortal"), the "docBase"
            (the new value is "myPortal") and the "appName" in the "Realm"
            definition (the new value is "my-exo-domain").</para>
          </listitem>

          <listitem>
            <para>Rename the file
            <emphasis>tomcat/conf/Catalina/localhost/portal.xml</emphasis> to
            <emphasis>myPortal.xml</emphasis>.</para>
          </listitem>

          <listitem>
            <para>Update the file
            <emphasis>tomcat/conf/Catalina/localhost/rest.xml</emphasis> by
            changing the "path" (the new value is "/myRest"), the "docBase"
            (the new value is "myRest") and the "appName" in the "Realm"
            definition (the new value is "my-exo-domain").</para>
          </listitem>

          <listitem>
            <para>Rename the file
            <emphasis>tomcat/conf/Catalina/localhost/rest.xml</emphasis> to
            <emphasis>myRest.xml</emphasis>.</para>
          </listitem>

          <listitem>
            <para>Change the realm name in the file
            <emphasis>tomcat/conf/jaas.conf</emphasis> (the new name is
            "my-exo-domain").</para>
          </listitem>
        </itemizedlist>
      </section>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToAddNewConfigurationFile">
      <title>How to add new configuration file to a given portal from a war
      file?</title>

      <para>To indicate the platform that a given web application has
      configuration file to provide, you need to:</para>

      <itemizedlist>
        <listitem>
          <para>Add the ServletContextListener
          <emphasis>org.exoplatform.container.web.PortalContainerConfigOwner</emphasis>
          in its web.xml.</para>
        </listitem>

        <listitem>
          <para>Add the servlet context name of this web application as a new
          dependency in the <emphasis>PortalContainerDefinition</emphasis> of
          all the portal containers for which you want to share the
          configuration file embedded into the war file, located at
          <emphasis>WEB-INF/conf/configuration.xml</emphasis>.</para>
        </listitem>
      </itemizedlist>

      <para>The simple fact to add this Servlet Context Listener, will add the
      Servlet Context of this web application to the Unified Servlet Context
      of all the <emphasis>PortalContainers</emphasis> that depend on this web
      application according to their
      <emphasis>PortalContainerDefinition</emphasis>.</para>

      <important>
        <title>Useful Information #1</title>

        <para>The position of the servlet context name of this web application
        in the dependency list is important since the last configuration file
        loaded has always right towards other configuration files. Each
        configuration file loaded, could potentially redefine a configuration
        file that has already been loaded. Moreover, as we now use a unified
        Servlet Context to load the configuration files, if you want for
        instance to import the file
        <emphasis>war:/conf/database/database-configuration.xml</emphasis> and
        this file exists in 2 different web applications, the file from the
        last (according to the dependency order) web application will be
        loaded.</para>
      </important>

      <important>
        <title>Useful Information #2</title>

        <para>A portal is implicitly considered as a
        <emphasis>PortalContainerConfigOwner</emphasis> without having to
        define the ServletContextListener
        <emphasis>org.exoplatform.container.web.PortalContainerConfigOwner</emphasis>
        in its web.xml.</para>
      </important>

      <para>See an example of a web.xml below:</para>

      <programlisting language="xml">&lt;?xml version="1.0" encoding="ISO-8859-1" ?&gt;
&lt;!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
                 "http://java.sun.com/dtd/web-app_2_3.dtd"&gt;
&lt;web-app&gt;
  &lt;display-name&gt;sample-ext&lt;/display-name&gt;

  &lt;context-param&gt;
    &lt;param-name&gt;org.exoplatform.frameworks.jcr.command.web.fckeditor.digitalAssetsWorkspace&lt;/param-name&gt;
    &lt;param-value&gt;collaboration&lt;/param-value&gt;
    &lt;description&gt;Binary assets workspace name&lt;/description&gt;
  &lt;/context-param&gt;

  &lt;context-param&gt;
    &lt;param-name&gt;org.exoplatform.frameworks.jcr.command.web.fckeditor.digitalAssetsPath&lt;/param-name&gt;
    &lt;param-value&gt;/Digital Assets/&lt;/param-value&gt;
    &lt;description&gt;Binary assets path&lt;/description&gt;
  &lt;/context-param&gt;

  &lt;context-param&gt;
    &lt;param-name&gt;CurrentFolder&lt;/param-name&gt;
    &lt;param-value&gt;/Digital Assets/&lt;/param-value&gt;
    &lt;description&gt;Binary assets workspace name&lt;/description&gt;
  &lt;/context-param&gt;

  &lt;!-- ================================================================== --&gt;
  &lt;!--   RESOURCE FILTER TO CACHE MERGED JAVASCRIPT AND CSS               --&gt;
  &lt;!-- ================================================================== --&gt;
  &lt;filter&gt;
    &lt;filter-name&gt;ResourceRequestFilter&lt;/filter-name&gt;
    &lt;filter-class&gt;org.exoplatform.portal.application.ResourceRequestFilter&lt;/filter-class&gt;
  &lt;/filter&gt;

  &lt;filter-mapping&gt;
    &lt;filter-name&gt;ResourceRequestFilter&lt;/filter-name&gt;
    &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
  &lt;/filter-mapping&gt;


  &lt;!-- ================================================================== --&gt;
  &lt;!--           LISTENER                                                 --&gt;
  &lt;!-- ================================================================== --&gt;
  &lt;listener&gt;
    &lt;listener-class&gt;org.exoplatform.container.web.PortalContainerConfigOwner&lt;/listener-class&gt;
  &lt;/listener&gt;
  &lt;!-- ================================================================== --&gt;
  &lt;!--           SERVLET                                                  --&gt;
  &lt;!-- ================================================================== --&gt;
  &lt;servlet&gt;
    &lt;servlet-name&gt;GateInServlet&lt;/servlet-name&gt;
    &lt;servlet-class&gt;org.gatein.wci.api.GateInServlet&lt;/servlet-class&gt;
    &lt;load-on-startup&gt;0&lt;/load-on-startup&gt;
  &lt;/servlet&gt;
  &lt;!--  =================================================================  --&gt;
  &lt;servlet-mapping&gt;
    &lt;servlet-name&gt;GateInServlet&lt;/servlet-name&gt;
    &lt;url-pattern&gt;/gateinservlet&lt;/url-pattern&gt;
  &lt;/servlet-mapping&gt;
&lt;/web-app&gt;</programlisting>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToCreateDefinePortalExtension">
      <title>How to create/define a portal extension?</title>

      <para>A portal extension is in fact a web application declared as a
      <emphasis>PortalContainerConfigOwner</emphasis> (see previous section
      for more details about a
      <emphasis>PortalContainerConfigOwner</emphasis>) that has been added to
      the dependency list of the
      <emphasis>PortalContainerDefinition</emphasis> of a given portal.</para>

      <para><emphasis role="underline">See below an example of configuration
      file that add the portal extension "portal-ext" to the dependency list
      of the portal "portal":</emphasis></para>

      <programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;configuration
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"
  xmlns="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"&gt;
  &lt;external-component-plugins&gt;
    &lt;!-- The full qualified name of the PortalContainerConfig --&gt;
    &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt;
    &lt;component-plugin&gt;
      &lt;!-- The name of the plugin --&gt;
      &lt;name&gt;Add PortalContainer Definitions&lt;/name&gt;
      &lt;!-- The name of the method to call on the PortalContainerConfig in order to register the PortalContainerDefinitions --&gt;
      &lt;set-method&gt;registerPlugin&lt;/set-method&gt;
      &lt;!-- The full qualified name of the PortalContainerDefinitionPlugin --&gt;
      &lt;type&gt;org.exoplatform.container.definition.PortalContainerDefinitionPlugin&lt;/type&gt;
      &lt;init-params&gt;
        &lt;object-param&gt;
          &lt;name&gt;portal&lt;/name&gt;
          &lt;object type="org.exoplatform.container.definition.PortalContainerDefinition"&gt;
            &lt;!-- The name of the portal container --&gt;
            &lt;field name="name"&gt;&lt;string&gt;portal&lt;/string&gt;&lt;/field&gt;
            &lt;!-- The name of the context name of the rest web application --&gt;
            &lt;field name="restContextName"&gt;&lt;string&gt;rest&lt;/string&gt;&lt;/field&gt;
            &lt;!-- The name of the realm --&gt;
            &lt;field name="realmName"&gt;&lt;string&gt;exo-domain&lt;/string&gt;&lt;/field&gt;
            &lt;!-- All the dependencies of the portal container ordered by loading priority --&gt;
            &lt;field name="dependencies"&gt;
              &lt;collection type="java.util.ArrayList"&gt;
                &lt;value&gt;
                  &lt;string&gt;eXoResources&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;portal&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;dashboard&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;exoadmin&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;eXoGadgets&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;eXoGadgetServer&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;rest&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;web&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;wsrp-producer&lt;/string&gt;
                &lt;/value&gt;
                &lt;!-- The sample-ext has been added at the end of the dependency list in order to have the highest priority towards
                the other web applications and particularly towards "portal" --&gt;
                &lt;value&gt;
                  &lt;string&gt;sample-ext&lt;/string&gt;
                &lt;/value&gt;
              &lt;/collection&gt;
            &lt;/field&gt;
          &lt;/object&gt;
        &lt;/object-param&gt;
      &lt;/init-params&gt;
    &lt;/component-plugin&gt;
  &lt;/external-component-plugins&gt;
&lt;/configuration&gt;</programlisting>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToDeployPortalExtension">
      <title>How to deploy a portal extension?</title>

      <para>Refer to <emphasis>How to deploy the sample
      extension?</emphasis></para>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToCreateDefineNewPortal">
      <title>How to create/define a new portal?</title>

      <para>To duplicate the entire "portal.war" file to create a new portal,
      you just need to duplicate the following files from the original
      "portal.war":</para>

      <itemizedlist>
        <listitem>
          <para>login/jsp/login.jsp</para>
        </listitem>

        <listitem>
          <para>login/skin: You can customize the css files and
          pictures</para>
        </listitem>

        <listitem>
          <para>bookmark.jsp</para>
        </listitem>

        <listitem>
          <para>favicon.ico: You can replace it by your own logo</para>
        </listitem>

        <listitem>
          <para>index.jsp</para>
        </listitem>

        <listitem>
          <para>portal-unavailable.jsp</para>
        </listitem>

        <listitem>
          <para>portal-warning.jsp</para>
        </listitem>

        <listitem>
          <para>WEB-INF/web.xml: You just need to change the "display-name"
          and set a different value for the "realm-name" in the
          "login-config". Indeed, we must have one realm name per
          portal.</para>
        </listitem>

        <listitem>
          <para>WEB-INF/jboss-web.xml: If you use JBoss AS, you need to
          duplicate also this file and set the new "security-domain" with the
          new realm name.</para>
        </listitem>
      </itemizedlist>

      <para>You need also to duplicate the "rest.war" file to create a
      dedicated rest web application for your portal as we must have one rest
      web application per portal, in fact you just need to duplicate the
      following files from the original "rest.war":</para>

      <itemizedlist>
        <listitem>
          <para>WEB-INF/web.xml: You just need to change the "display-name"
          and set a different value for the "realm-name" in the
          "login-config". Indeed, we must have one realm name per
          portal.</para>
        </listitem>

        <listitem>
          <para>WEB-INF/jboss-web.xml: If you use JBoss AS, you need to
          duplicate also this file and set the new "security-domain" with the
          new realm name.</para>
        </listitem>
      </itemizedlist>

      <para>Finally, you need to register and define the corresponding
      <emphasis>PortalContainerDefinition</emphasis>. The
      <emphasis>PortalContainerDefinition</emphasis> of your portal will be
      composed of:</para>

      <itemizedlist>
        <listitem>
          <para>The name of new portal</para>
        </listitem>

        <listitem>
          <para>The name of the context name of the new rest web
          application</para>
        </listitem>

        <listitem>
          <para>The name of the new realm</para>
        </listitem>

        <listitem>
          <para>The list of all the dependencies of the original portal, with
          the new name of the rest web application instead of the old name
          (i.e. "rest") and with a new dependency which is in fact the name of
          your portal. As we leave the dependency of the original portal in
          the list of dependencies, it will load the configuration files of
          original "portal.war" file.</para>
        </listitem>
      </itemizedlist>

      <para><emphasis role="underline">See an example below:</emphasis></para>

      <programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;configuration
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"
  xmlns="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"&gt;
  &lt;external-component-plugins&gt;
    &lt;!-- The full qualified name of the PortalContainerConfig --&gt;
    &lt;target-component&gt;org.exoplatform.container.definition.PortalContainerConfig&lt;/target-component&gt;
    &lt;component-plugin&gt;
      &lt;!-- The name of the plugin --&gt;
      &lt;name&gt;Add PortalContainer Definitions&lt;/name&gt;
      &lt;!-- The name of the method to call on the PortalContainerConfig in order to register the PortalContainerDefinitions --&gt;
      &lt;set-method&gt;registerPlugin&lt;/set-method&gt;
      &lt;!-- The full qualified name of the PortalContainerDefinitionPlugin --&gt;
      &lt;type&gt;org.exoplatform.container.definition.PortalContainerDefinitionPlugin&lt;/type&gt;
      &lt;init-params&gt;
        &lt;object-param&gt;
          &lt;name&gt;sample-portal&lt;/name&gt;
          &lt;object type="org.exoplatform.container.definition.PortalContainerDefinition"&gt;
            &lt;!-- The name of the portal container --&gt;
            &lt;field name="name"&gt;&lt;string&gt;sample-portal&lt;/string&gt;&lt;/field&gt;
            &lt;!-- The name of the context name of the rest web application --&gt;
            &lt;field name="restContextName"&gt;&lt;string&gt;rest-sample-portal&lt;/string&gt;&lt;/field&gt;
            &lt;!-- The name of the realm --&gt;
            &lt;field name="realmName"&gt;&lt;string&gt;exo-domain-sample-portal&lt;/string&gt;&lt;/field&gt;
            &lt;!-- All the dependencies of the portal container ordered by loading priority --&gt;
            &lt;field name="dependencies"&gt;
              &lt;collection type="java.util.ArrayList"&gt;
                &lt;value&gt;
                  &lt;string&gt;eXoResources&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;portal&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;dashboard&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;exoadmin&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;eXoGadgets&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;eXoGadgetServer&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;rest-sample-portal&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;web&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;wsrp-producer&lt;/string&gt;
                &lt;/value&gt;
                &lt;value&gt;
                  &lt;string&gt;sample-portal&lt;/string&gt;
                &lt;/value&gt;
              &lt;/collection&gt;
            &lt;/field&gt;
          &lt;/object&gt;
        &lt;/object-param&gt;
      &lt;/init-params&gt;
    &lt;/component-plugin&gt;
  &lt;/external-component-plugins&gt;
&lt;/configuration&gt;</programlisting>

      <important>
        <title>Useful Information #1</title>

        <para>A portal is implicitly a
        <emphasis>PortalContainerConfigOwner</emphasis> which means that it
        shares the configuration file embedded into the war file, located at
        <emphasis>WEB-INF/conf/configuration.xml</emphasis></para>
      </important>

      <important>
        <title>Useful Information #2</title>

        <para>The position of the servlet context name of this web application
        in the dependency list is important since the last configuration file
        loaded has always right towards other configuration files. Each
        configuration file loaded, could potentially redefine a configuration
        file that has already been loaded. Moreover, as we now use a unified
        Servlet Context to load the configuration files, if you want for
        instance to import the file
        <emphasis>war:/conf/database/database-configuration.xml</emphasis> and
        this file exists in 2 different web applications, the file from the
        last (according to the dependency order) web application will be
        loaded.</para>
      </important>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToDeployNewPortal">
      <title>How to deploy a new portal?</title>

      <para>Refer to <emphasis>How to deploy the sample
      portal?</emphasis></para>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToImportProperlyConfigurationFileUsingPrefixWar">
      <title>How to import properly a configuration file using the prefix
      "war:"?</title>

      <para>Now, the <emphasis>ConfigurationManager</emphasis> uses by default
      the unified servlet context of the portal in order to get any resources
      in particular the configuration files. The unified servlet context is
      aware of the priorities that has been set in the
      <emphasis>PortalContainerDefinition</emphasis> of the portal. In other
      words, if you want for instance to import the file
      <emphasis>war:/conf/database/database-configuration.xml</emphasis> and
      this file exists in 2 different web applications, the file from the last
      (according to the dependency order) web application will be
      loaded.</para>

      <para>So, in order to avoid issues when we would like to package several
      products at the same time (i.e. WCM, DMS, CS, KS), we need to:</para>

      <itemizedlist>
        <listitem>
          <para>Avoid the best you can to redefine a configuration file from
          the "portal.war" by using the exact same path (like the previous
          example)</para>
        </listitem>

        <listitem>
          <para>Add your configuration files in a dedicated folder which name
          will be the name of the product, in oder to ensure that no other
          products will use the same path</para>
        </listitem>
      </itemizedlist>

      <para>The example below, is an the example of a file
      <emphasis>WEB-INF/conf/configuration.xml</emphasis> of the product
      "sample-ext".</para>

      <programlisting language="xml">&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
&lt;configuration
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"
  xmlns="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"&gt;
  &lt;import&gt;war:/conf/sample-ext/common/common-configuration.xml&lt;/import&gt;
  &lt;import&gt;war:/conf/sample-ext/jcr/jcr-configuration.xml&lt;/import&gt;
  &lt;import&gt;war:/conf/sample-ext/portal/portal-configuration.xml&lt;/import&gt;
  &lt;import&gt;war:/conf/sample-ext/web/web-inf-extension-configuration.xml&lt;/import&gt;
&lt;/configuration&gt;</programlisting>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToAvoidDuplicatingConfigurationFiles">
      <title>How to avoid duplicating configuration files just to rename a
      simple value?</title>

      <para>In your configuration file, you can use a special variable called
      <emphasis>container.name.suffix</emphasis> in order to add a suffix to
      values that could change between portal containers. The value of this
      variable will be an empty sting if no
      <emphasis>PortalContainerDefinition</emphasis> has been defined
      otherwise the value will be
      <emphasis>\-$portal.container.name</emphasis>. <emphasis
      role="underline">See an example below:</emphasis></para>

      <programlisting language="xml">&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
&lt;configuration
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"
   xmlns="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"&gt;
  &lt;component&gt;
    &lt;key&gt;org.exoplatform.services.database.HibernateService&lt;/key&gt;
    &lt;jmx-name&gt;database:type=HibernateService&lt;/jmx-name&gt;
    &lt;type&gt;org.exoplatform.services.database.impl.HibernateServiceImpl&lt;/type&gt;
    &lt;init-params&gt;
      &lt;properties-param&gt;
        &lt;name&gt;hibernate.properties&lt;/name&gt;
        &lt;description&gt;Default Hibernate Service&lt;/description&gt;
        &lt;property name="hibernate.show_sql" value="false"/&gt;
        &lt;property name="hibernate.cglib.use_reflection_optimizer" value="true"/&gt;
        &lt;property name="hibernate.connection.url" value="jdbc:hsqldb:file:../temp/data/exodb${container.name.suffix}"/&gt;
        &lt;property name="hibernate.connection.driver_class" value="org.hsqldb.jdbcDriver"/&gt;
        &lt;property name="hibernate.connection.autocommit" value="true"/&gt;
        &lt;property name="hibernate.connection.username" value="sa"/&gt;
        &lt;property name="hibernate.connection.password" value=""/&gt;
        &lt;property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/&gt;
        &lt;property name="hibernate.c3p0.min_size" value="5"/&gt;
        &lt;property name="hibernate.c3p0.max_size" value="20"/&gt;
        &lt;property name="hibernate.c3p0.timeout" value="1800"/&gt;
        &lt;property name="hibernate.c3p0.max_statements" value="50"/&gt;
      &lt;/properties-param&gt;
    &lt;/init-params&gt;
  &lt;/component&gt;
&lt;/configuration&gt;</programlisting>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToAddOrChangeRepositoryAndWorkspace">
      <title>How to add or change a Repository and/or a Workspace?</title>

      <para>Now you can add new JCR repositories or workspaces thanks to an
      external plugin, the configuration of your JCR Repositories will be
      merged knowing that the merge algorithm will:</para>

      <itemizedlist>
        <listitem>
          <para>Add missing Repository Definitions and/or Workspace
          Definitions.</para>
        </listitem>

        <listitem>
          <para>Change the properties of a Repository Definition if it has
          already been defined.</para>
        </listitem>

        <listitem>
          <para>Replace the Workspace Definition if it has already been
          defined.</para>
        </listitem>
      </itemizedlist>

      <para><emphasis role="underline">See an example of jcr-configuration.xml
      below:</emphasis></para>

      <programlisting language="xml">&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
&lt;configuration
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"
  xmlns="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"&gt;
  &lt;external-component-plugins&gt;
    &lt;!-- The full qualified name of the RepositoryServiceConfiguration --&gt;
    &lt;target-component&gt;org.exoplatform.services.jcr.config.RepositoryServiceConfiguration&lt;/target-component&gt;
    &lt;component-plugin&gt;
      &lt;!-- The name of the plugin --&gt;
      &lt;name&gt;Sample RepositoryServiceConfiguration Plugin&lt;/name&gt;
      &lt;!-- The name of the method to call on the RepositoryServiceConfiguration in order to add the RepositoryServiceConfigurations --&gt;
      &lt;set-method&gt;addConfig&lt;/set-method&gt;
      &lt;!-- The full qualified name of the RepositoryServiceConfigurationPlugin --&gt;
      &lt;type&gt;org.exoplatform.services.jcr.impl.config.RepositoryServiceConfigurationPlugin&lt;/type&gt;
      &lt;init-params&gt;
        &lt;value-param&gt;
          &lt;name&gt;conf-path&lt;/name&gt;
          &lt;description&gt;JCR configuration file&lt;/description&gt;
          &lt;value&gt;war:/conf/sample-ext/jcr/repository-configuration.xml&lt;/value&gt;
        &lt;/value-param&gt;
      &lt;/init-params&gt;
    &lt;/component-plugin&gt;
  &lt;/external-component-plugins&gt;
&lt;/configuration&gt;</programlisting>

      <para>See an example of repository-configuration.xml below:</para>

      <programlisting language="xml">&lt;repository-service default-repository="repository"&gt;
  &lt;repositories&gt;
    &lt;repository name="repository" system-workspace="system" default-workspace="portal-system"&gt;
      &lt;security-domain&gt;exo-domain&lt;/security-domain&gt;
      &lt;access-control&gt;optional&lt;/access-control&gt;
      &lt;authentication-policy&gt;org.exoplatform.services.jcr.impl.core.access.JAASAuthenticator&lt;/authentication-policy&gt;
      &lt;workspaces&gt;
        &lt;workspace name="sample-ws"&gt;
          &lt;container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer"&gt;
            &lt;properties&gt;
              &lt;property name="source-name" value="jdbcexo${container.name.suffix}" /&gt;
              &lt;property name="dialect" value="hsqldb" /&gt;
              &lt;property name="multi-db" value="false" /&gt;
              &lt;property name="max-buffer-size" value="204800" /&gt;
              &lt;property name="swap-directory" value="../temp/swap/sample-ws${container.name.suffix}" /&gt;
            &lt;/properties&gt;
            &lt;value-storages&gt;
              &lt;value-storage id="sample-ws" class="org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"&gt;
                &lt;properties&gt;
                  &lt;property name="path" value="../temp/values/sample-ws${container.name.suffix}" /&gt;
                &lt;/properties&gt;
                &lt;filters&gt;
                  &lt;filter property-type="Binary" /&gt;
                &lt;/filters&gt;
              &lt;/value-storage&gt;
            &lt;/value-storages&gt;
          &lt;/container&gt;
          &lt;initializer class="org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer"&gt;
            &lt;properties&gt;
              &lt;property name="root-nodetype" value="nt:unstructured" /&gt;
              &lt;property name="root-permissions"
                value="any read;*:/platform/administrators read;*:/platform/administrators add_node;*:/platform/administrators set_property;*:/platform/administrators remove" /&gt;
            &lt;/properties&gt;
          &lt;/initializer&gt;
          &lt;cache enabled="true"&gt;
            &lt;properties&gt;
              &lt;property name="max-size" value="20000" /&gt;
              &lt;property name="live-time" value="30000" /&gt;
            &lt;/properties&gt;
          &lt;/cache&gt;
          &lt;query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex"&gt;
            &lt;properties&gt;
              &lt;property name="index-dir" value="../temp/jcrlucenedb/sample-ws${container.name.suffix}" /&gt;
            &lt;/properties&gt;
          &lt;/query-handler&gt;
          &lt;lock-manager class="org.exoplatform.services.jcr.impl.core.lock.infinispan.ISPNCacheableLockManagerImpl"&gt;
              &lt;properties&gt;
                  &lt;property name="time-out" value="15m" /&gt;
                  &lt;property name="infinispan-configuration" value="conf/standalone/cluster/test-infinispan-lock.xml" /&gt;
                  &lt;property name="jgroups-configuration" value="udp-mux.xml" /&gt;
                  &lt;property name="infinispan-cluster-name" value="JCR-cluster" /&gt;
                  &lt;property name="infinispan-cl-cache.jdbc.table.name" value="lk" /&gt;
                  &lt;property name="infinispan-cl-cache.jdbc.table.create" value="true" /&gt;
                  &lt;property name="infinispan-cl-cache.jdbc.table.drop" value="false" /&gt;
                  &lt;property name="infinispan-cl-cache.jdbc.id.column" value="id" /&gt;
                  &lt;property name="infinispan-cl-cache.jdbc.data.column" value="data" /&gt;
                  &lt;property name="infinispan-cl-cache.jdbc.timestamp.column" value="timestamp" /&gt;
                  &lt;property name="infinispan-cl-cache.jdbc.datasource" value="jdbcjcr" /&gt;
                  &lt;property name="infinispan-cl-cache.jdbc.dialect" value="${dialect}" /&gt;
                  &lt;property name="infinispan-cl-cache.jdbc.connectionFactory" value="org.exoplatform.services.jcr.infinispan.ManagedConnectionFactory" /&gt;
              &lt;/properties&gt;
          &lt;/lock-manager&gt;
        &lt;/workspace&gt;
      &lt;/workspaces&gt;
    &lt;/repository&gt;
  &lt;/repositories&gt;
&lt;/repository-service&gt;</programlisting>

      <warning>
        <title>Warning</title>

        <para>If you have to change the default repository or the default
        workspace, please be careful since it could cause side effects as you
        could be incompatible with some portal configuration files that refer
        explicitly to <emphasis>portal-system</emphasis> and/or to
        <emphasis>repository</emphasis>. To solve this problem you can either
        redefine the configuration file in a portal extension to change the
        workspace name and/or the repository name or you could also add your
        own repository instead of your own workspace.</para>
      </warning>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToAddNewResourceBundles">
      <title>How to add new ResourceBundles to my portal?</title>

      <para>Now you can add new Resource Bundles, thanks to an external
      plugin.</para>

      <para><emphasis role="underline">See an example below:</emphasis></para>

      <programlisting language="xml">&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
&lt;configuration
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"
  xmlns="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"&gt;
  &lt;external-component-plugins&gt;
    &lt;!-- The full qualified name of the ResourceBundleService --&gt;
    &lt;target-component&gt;org.exoplatform.services.resources.ResourceBundleService&lt;/target-component&gt;
    &lt;component-plugin&gt;
      &lt;!-- The name of the plugin --&gt;
      &lt;name&gt;Sample ResourceBundle Plugin&lt;/name&gt;
      &lt;!-- The name of the method to call on the ResourceBundleService in order to register the ResourceBundles --&gt;
      &lt;set-method&gt;addResourceBundle&lt;/set-method&gt;
      &lt;!-- The full qualified name of the BaseResourceBundlePlugin --&gt;
      &lt;type&gt;org.exoplatform.services.resources.impl.BaseResourceBundlePlugin&lt;/type&gt;
      &lt;init-params&gt;
        &lt;!--values-param&gt;
          &lt;name&gt;classpath.resources&lt;/name&gt;
          &lt;description&gt;The resources that start with the following package name should be load from file system&lt;/description&gt;
          &lt;value&gt;locale.portlet&lt;/value&gt;
        &lt;/values-param--&gt;
        &lt;values-param&gt;
          &lt;name&gt;init.resources&lt;/name&gt;
          &lt;description&gt;Store the following resources into the db for the first launch &lt;/description&gt;
          &lt;value&gt;locale.portal.sample&lt;/value&gt;
        &lt;/values-param&gt;
        &lt;values-param&gt;
          &lt;name&gt;portal.resource.names&lt;/name&gt;
          &lt;description&gt;The properties files of the portal , those file will be merged
            into one ResoruceBundle properties &lt;/description&gt;
          &lt;value&gt;locale.portal.sample&lt;/value&gt;
        &lt;/values-param&gt;
      &lt;/init-params&gt;
    &lt;/component-plugin&gt;
  &lt;/external-component-plugins&gt;
&lt;/configuration&gt;</programlisting>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToOverwriteExistingResourceBundles">
      <title>How to overwrite existing ResourceBundles in my portal?</title>

      <para>Now each portal container has its own
      <emphasis>ClassLoader</emphasis> which is automatically set for you at
      runtime (FYI: it could be retrieved thanks to
      <emphasis>portalContainer.getPortalClassLoader()</emphasis>). This
      <emphasis>ClassLoader</emphasis> is an unified
      <emphasis>ClassLoader</emphasis> that is also aware of the dependency
      order defined into the <emphasis>PortalContainerDefinition</emphasis>,
      so to add new keys or update key values, you just need to:</para>

      <itemizedlist>
        <listitem>
          <para>Add the corresponding resource bundle with the same name, with
          <emphasis role="underline">the same extension</emphasis> (xml or
          properties) at the same location into the
          <emphasis>classpath</emphasis> of your Web application (i.e.
          directly into the <emphasis>WEB-INF/classes</emphasis> directory or
          into a jar file in the <emphasis>WEB-INF/lib</emphasis>
          directory)</para>
        </listitem>

        <listitem>
          <para>Ensure that your web application is defined after the web
          application of the portal in the dependency list of the related
          <emphasis>PortalContainerDefinition</emphasis>.</para>
        </listitem>
      </itemizedlist>

      <para>In the example below, we want to change the values of the keys
      <emphasis>UIHomePagePortlet.Label.Username</emphasis> and
      <emphasis>UIHomePagePortlet.Label.Password</emphasis>, and add the new
      key <emphasis>UIHomePagePortlet.Label.SampleKey</emphasis> into the
      Resource Bundle <emphasis>locale.portal.webui</emphasis>.</para>

      <note>
        <title>WEB-INF/classes/local/portal/webui_en.properties</title>

        <programlisting>#############################################################################
#org.exoplatform.portal.webui.component.UIHomePagePortlet															#
#############################################################################

UIHomePagePortlet.Label.Username=Usr:
UIHomePagePortlet.Label.Password=Pwd:
UIHomePagePortlet.Label.SampleKey=This is a new key that has been added to the Resource Bundle "locale.portal.webui" of "sample-ext"</programlisting>
      </note>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToReplaceGroovyTemplate">
      <title>How to replace a groovy template of my portal?</title>

      <para>Now each portal container has its own
      <emphasis>ServletContext</emphasis> which is automatically set for you
      at runtime (FYI: it could be retrieved thanks to
      <emphasis>portalContainer.getPortalContext()</emphasis>). This
      <emphasis>ServletContext</emphasis> is an unified
      <emphasis>ServletContext</emphasis> that is also aware of the dependency
      order defined into the <emphasis>PortalContainerDefinition</emphasis> so
      to replace a groovy template of the portal, you just need to:</para>

      <itemizedlist>
        <listitem>
          <para>Add the corresponding groovy template with the same name at
          the same location into your Web application</para>
        </listitem>

        <listitem>
          <para>Ensure that your web application is defined after the web
          application of the portal in the dependency list of the related
          <emphasis>PortalContainerDefinition</emphasis>.</para>
        </listitem>
      </itemizedlist>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToAddNewPortalConfigurationsNavigationsPagesAndPortletPreferences">
      <title>How to add new Portal Configurations, Navigations, Pages or
      Portlet Preferences to my portal?</title>

      <para>Now you can add new Portal Configurations, Navigations, Pages or
      Portlet Preferences thanks to an external plugin.</para>

      <para><emphasis role="underline">See an example below:</emphasis></para>

      <programlisting language="xml">&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
&lt;configuration
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"
  xmlns="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"&gt;
  &lt;external-component-plugins&gt;
    &lt;!-- The full qualified name of the UserPortalConfigService --&gt;
    &lt;target-component&gt;org.exoplatform.portal.config.UserPortalConfigService&lt;/target-component&gt;
    &lt;component-plugin&gt;
      &lt;!-- The name of the plugin --&gt;
      &lt;name&gt;new.portal.config.user.listener&lt;/name&gt;
      &lt;!-- The name of the method to call on the UserPortalConfigService in order to register the NewPortalConfigs --&gt;
      &lt;set-method&gt;initListener&lt;/set-method&gt;
      &lt;!-- The full qualified name of the NewPortalConfigListener --&gt;
      &lt;type&gt;org.exoplatform.portal.config.NewPortalConfigListener&lt;/type&gt;
      &lt;description&gt;this listener init the portal configuration&lt;/description&gt;
      &lt;init-params&gt;
        &lt;object-param&gt;
          &lt;name&gt;portal.configuration&lt;/name&gt;
          &lt;description&gt;description&lt;/description&gt;
          &lt;object type="org.exoplatform.portal.config.NewPortalConfig"&gt;
            &lt;field name="predefinedOwner"&gt;
              &lt;collection type="java.util.HashSet"&gt;
                &lt;value&gt;
                  &lt;string&gt;classic&lt;/string&gt;
                &lt;/value&gt;
              &lt;/collection&gt;
            &lt;/field&gt;
            &lt;field name="ownerType"&gt;
              &lt;string&gt;portal&lt;/string&gt;
            &lt;/field&gt;
            &lt;field name="templateLocation"&gt;
              &lt;string&gt;war:/conf/sample-ext/portal&lt;/string&gt;
            &lt;/field&gt;
          &lt;/object&gt;
        &lt;/object-param&gt;
        &lt;object-param&gt;
          &lt;name&gt;group.configuration&lt;/name&gt;
          &lt;description&gt;description&lt;/description&gt;
          &lt;object type="org.exoplatform.portal.config.NewPortalConfig"&gt;
            &lt;field name="predefinedOwner"&gt;
              &lt;collection type="java.util.HashSet"&gt;
                &lt;value&gt;
                  &lt;string&gt;platform/users&lt;/string&gt;
                &lt;/value&gt;
              &lt;/collection&gt;
            &lt;/field&gt;
            &lt;field name="ownerType"&gt;
              &lt;string&gt;group&lt;/string&gt;
            &lt;/field&gt;
            &lt;field name="templateLocation"&gt;
              &lt;string&gt;war:/conf/sample-ext/portal&lt;/string&gt;
            &lt;/field&gt;
          &lt;/object&gt;
        &lt;/object-param&gt;
        &lt;object-param&gt;
          &lt;name&gt;user.configuration&lt;/name&gt;
          &lt;description&gt;description&lt;/description&gt;
          &lt;object type="org.exoplatform.portal.config.NewPortalConfig"&gt;
            &lt;field name="predefinedOwner"&gt;
              &lt;collection type="java.util.HashSet"&gt;
                &lt;value&gt;
                  &lt;string&gt;root&lt;/string&gt;
                &lt;/value&gt;
              &lt;/collection&gt;
            &lt;/field&gt;
            &lt;field name="ownerType"&gt;
              &lt;string&gt;user&lt;/string&gt;
            &lt;/field&gt;
            &lt;field name="templateLocation"&gt;
              &lt;string&gt;war:/conf/sample-ext/portal&lt;/string&gt;
            &lt;/field&gt;
          &lt;/object&gt;
        &lt;/object-param&gt;
      &lt;/init-params&gt;
    &lt;/component-plugin&gt;
  &lt;/external-component-plugins&gt;
&lt;/configuration&gt;</programlisting>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToAddHttpFilters">
      <title>How to add new Http Filters to my portal without modifying the
      portal binary?</title>

      <para>We added a <emphasis>GenericFilter</emphasis> that allows you to
      define new Http Filters thanks to an external plugin. Your filter will
      need to implement the interface
      <emphasis>org.exoplatform.web.filter.Filter</emphasis>.</para>

      <para><emphasis role="underline">See an example of configuration
      below:</emphasis></para>

      <programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;configuration
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"
  xmlns="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"&gt;
  &lt;external-component-plugins&gt;
    &lt;!-- The full qualified name of the ExtensibleFilter --&gt;
    &lt;target-component&gt;org.exoplatform.web.filter.ExtensibleFilter&lt;/target-component&gt;
    &lt;component-plugin&gt;
      &lt;!-- The name of the plugin --&gt;
      &lt;name&gt;Sample Filter Definition Plugin&lt;/name&gt;
      &lt;!-- The name of the method to call on the ExtensibleFilter in order to register the FilterDefinitions --&gt;
      &lt;set-method&gt;addFilterDefinitions&lt;/set-method&gt;
      &lt;!-- The full qualified name of the FilterDefinitionPlugin --&gt;
      &lt;type&gt;org.exoplatform.web.filter.FilterDefinitionPlugin&lt;/type&gt;
      &lt;init-params&gt;
        &lt;object-param&gt;
          &lt;name&gt;Sample Filter Definition&lt;/name&gt;
          &lt;object type="org.exoplatform.web.filter.FilterDefinition"&gt;
            &lt;!-- The filter instance --&gt;
            &lt;field name="filter"&gt;&lt;object type="org.exoplatform.sample.ext.web.SampleFilter"/&gt;&lt;/field&gt;
            &lt;!-- The mapping to use --&gt;
            &lt;!-- WARNING: the mapping is expressed with regular expressions --&gt;
            &lt;field name="patterns"&gt;
              &lt;collection type="java.util.ArrayList" item-type="java.lang.String"&gt;
                &lt;value&gt;
                  &lt;string&gt;/.*&lt;/string&gt;
                &lt;/value&gt;
              &lt;/collection&gt;
            &lt;/field&gt;
          &lt;/object&gt;
        &lt;/object-param&gt;
      &lt;/init-params&gt;
    &lt;/component-plugin&gt;
  &lt;/external-component-plugins&gt;
&lt;/configuration&gt;</programlisting>

      <para>See an example of Filter below:</para>

      <note>
        <title>SampleFilter.java</title>

        <programlisting language="java">...
import org.exoplatform.web.filter.Filter;

import java.io.IOException;

import javax.servlet.FilterChain;
import javax.servlet.ServletException;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;

public class SampleFilter implements Filter
{

   public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException,
      ServletException
   {
      System.out.println("SampleFilter start");
      try
      {
         chain.doFilter(request, response);
      }
      finally
      {
         System.out.println("SampleFilter end");
      }
   }
}</programlisting>
      </note>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToAddNewHttpSessionListenersAndServletContextListeners">
      <title>How to add new <emphasis>HttpSessionListeners</emphasis> and/or
      <emphasis>ServletContextListeners</emphasis> to my portal without
      modifying the portal binary?</title>

      <para>We added a <emphasis>GenericHttpListener</emphasis> that allows
      you to define new <emphasis>HttpSessionListeners</emphasis> and/or
      <emphasis>ServletContextListeners</emphasis> thanks to an external
      plugin. Actually, the <emphasis>GenericHttpListener</emphasis> will
      broadcast events thanks to the <emphasis>ListenerService</emphasis> that
      you can easily capture. The events that it broadcasts are:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis>org.exoplatform.web.GenericHttpListener.sessionCreated</emphasis>:
          When a new session is created in the portal.</para>
        </listitem>

        <listitem>
          <para><emphasis>org.exoplatform.web.GenericHttpListener.sessionDestroyed</emphasis>:
          When a session is destroyed in the portal.</para>
        </listitem>

        <listitem>
          <para><emphasis>org.exoplatform.web.GenericHttpListener.contextInitialized</emphasis>:
          When the servlet context of the portal is initialized.</para>
        </listitem>

        <listitem>
          <para><emphasis>org.exoplatform.web.GenericHttpListener.contextDestroyed</emphasis>:
          When the servlet context of the portal is destroyed.</para>
        </listitem>
      </itemizedlist>

      <para>If you want to listen to
      <emphasis>org.exoplatform.web.GenericHttpListener.sessionCreated</emphasis>,
      you will need to create a Listener that extends
      _Listener&lt;PortalContainer, HttpSessionEvent&gt;_If you want to listen
      to \_org.exoplatform.web.GenericHttpListener.sessionDestroyed_, you will
      need to create a Listener that extends _Listener&lt;PortalContainer,
      HttpSessionEvent&gt;_If you want to listen to
      \_org.exoplatform.web.GenericHttpListener.contextInitialized_, you will
      need to create a Listener that extends _Listener&lt;PortalContainer,
      ServletContextEvent&gt;_If you want to listen to
      \_org.exoplatform.web.GenericHttpListener.contextDestroyed_, you will
      need to create a Listener that extends
      <emphasis>Listener&lt;PortalContainer,
      ServletContextEvent&gt;</emphasis></para>

      <para><emphasis role="underline">See an example of configuration
      below:</emphasis></para>

      <programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;configuration
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"
  xmlns="http://www.exoplatform.org/xml/ns/kernel_1_3.xsd"&gt;
  &lt;external-component-plugins&gt;
    &lt;!-- The full qualified name of the ListenerService --&gt;
    &lt;target-component&gt;org.exoplatform.services.listener.ListenerService&lt;/target-component&gt;
    &lt;component-plugin&gt;
      &lt;!-- The name of the listener that is also the name of the target event --&gt;
      &lt;name&gt;org.exoplatform.web.GenericHttpListener.sessionCreated&lt;/name&gt;
      &lt;!-- The name of the method to call on the ListenerService in order to register the Listener --&gt;
      &lt;set-method&gt;addListener&lt;/set-method&gt;
      &lt;!-- The full qualified name of the Listener --&gt;
      &lt;type&gt;org.exoplatform.sample.ext.web.SampleHttpSessionCreatedListener&lt;/type&gt;
    &lt;/component-plugin&gt;
    &lt;component-plugin&gt;
      &lt;!-- The name of the listener that is also the name of the target event --&gt;
      &lt;name&gt;org.exoplatform.web.GenericHttpListener.sessionDestroyed&lt;/name&gt;
      &lt;!-- The name of the method to call on the ListenerService in order to register the Listener --&gt;
      &lt;set-method&gt;addListener&lt;/set-method&gt;
      &lt;!-- The full qualified name of the Listener --&gt;
      &lt;type&gt;org.exoplatform.sample.ext.web.SampleHttpSessionDestroyedListener&lt;/type&gt;
    &lt;/component-plugin&gt;
    &lt;component-plugin&gt;
      &lt;!-- The name of the listener that is also the name of the target event --&gt;
      &lt;name&gt;org.exoplatform.web.GenericHttpListener.contextInitialized&lt;/name&gt;
      &lt;!-- The name of the method to call on the ListenerService in order to register the Listener --&gt;
      &lt;set-method&gt;addListener&lt;/set-method&gt;
      &lt;!-- The full qualified name of the Listener --&gt;
      &lt;type&gt;org.exoplatform.sample.ext.web.SampleContextInitializedListener&lt;/type&gt;
    &lt;/component-plugin&gt;
    &lt;component-plugin&gt;
      &lt;!-- The name of the listener that is also the name of the target event --&gt;
      &lt;name&gt;org.exoplatform.web.GenericHttpListener.contextDestroyed&lt;/name&gt;
      &lt;!-- The name of the method to call on the ListenerService in order to register the Listener --&gt;
      &lt;set-method&gt;addListener&lt;/set-method&gt;
      &lt;!-- The full qualified name of the Listener --&gt;
      &lt;type&gt;org.exoplatform.sample.ext.web.SampleContextDestroyedListener&lt;/type&gt;
    &lt;/component-plugin&gt;
  &lt;/external-component-plugins&gt;
&lt;/configuration&gt;</programlisting>

      <para>See an example of Session Listener below:</para>

      <note>
        <title>SampleHttpSessionCreatedListener.java</title>

        <programlisting language="java">..
import org.exoplatform.container.PortalContainer;
import org.exoplatform.services.listener.Event;
import org.exoplatform.services.listener.Listener;

import javax.servlet.http.HttpSessionEvent;

public class SampleHttpSessionCreatedListener extends Listener&lt;PortalContainer, HttpSessionEvent&gt;
{

   @Override
   public void onEvent(Event&lt;PortalContainer, HttpSessionEvent&gt; event) throws Exception
   {
      System.out.println("Creating a new session");
   }
}</programlisting>
      </note>

      <para>See an example of Context Listener below:</para>

      <note>
        <title>SampleContextInitializedListener.java</title>

        <programlisting language="java">..
import org.exoplatform.container.PortalContainer;
import org.exoplatform.services.listener.Event;
import org.exoplatform.services.listener.Listener;

import javax.servlet.ServletContextEvent;

public class SampleContextInitializedListener extends Listener&lt;PortalContainer, ServletContextEvent&gt;
{

   @Override
   public void onEvent(Event&lt;PortalContainer, ServletContextEvent&gt; event) throws Exception
   {
      System.out.println("Initializing the context");
   }
}</programlisting>
      </note>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToAddNewHttpServlet">
      <title>How to add new <emphasis>HttpServlet</emphasis> to my portal
      without modifying the portal binary?</title>

      <para>Actually, it is not possible but you can create a rest component
      instead. For more details about rest, please refer to the following
      article <link linkend="WS">WS</link>.</para>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToOverrideOrAddContextParameter">
      <title>How to override or add a Context Parameter to my portal without
      modifying the portal binary?</title>

      <para>Actually, you have nothing to do, you just need to ensure that you
      get the context parameter value from the unified servlet context of the
      portal, that should be set for you but you can still get it from
      <emphasis>portalContainer.getPortalContext()</emphasis>.</para>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.WhereFindExampleOfExtendingPortal">
      <title>Where can I found an example of how to extend my portal?</title>

      <para>We added an example of portal extension (i.e. ability to customize
      a portal without changing anything in the portal.ear) that you can find
      in the git repository of gatein at
      https://github.com/gatein/gatein-portal/tree/master/examples.</para>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToDeploySampleExtension">
      <title>How to deploy the sample extension?</title>

      <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToDeploySampleExtension.JBoss">
        <title>On JBoss (tested on JBoss 5.1.0.GA)</title>

        <para>We assume that you have a clean JBoss version of GateIn, in
        other words, we assume that you have already the file
        <emphasis>exoplatform.ear</emphasis> in the
        <emphasis>deploy</emphasis> directory of JBoss and you have the
        related application policy in your
        <emphasis>conf/login-config.xml</emphasis>.</para>

        <para><emphasis role="underline">You need to:</emphasis></para>

        <itemizedlist>
          <listitem>
            <para>Add the file <emphasis>sample-ext.ear</emphasis> from
            sample/extension/ear/target/ to the deploy directory of JBoss,
            this file contains:</para>

            <itemizedlist>
              <listitem>
                <para>The file <emphasis>sample-ext.war</emphasis> which is
                the web application that contains (potentially) configuration
                files, groovy templates, resource bundles, skins and
                javascript files, that will extend the portal.</para>
              </listitem>

              <listitem>
                <para>The file
                <emphasis>exo.portal.sample.extension.config-X.Y.Z.jar</emphasis>
                which is the file in which we defined the
                <emphasis>PortalContainerDefinition</emphasis> of the original
                portal in which we added <emphasis>sample-ext</emphasis> at
                the end of dependency list.</para>
              </listitem>

              <listitem>
                <para>The file
                <emphasis>exo.portal.sample.extension.jar-X.Y.Z.jar</emphasis>
                which is the file in which we have internal classes that are
                actualy a set of sample classes <emphasis>(SampleFilter,
                SampleContextInitializedListener,
                SampleContextDestroyedListener,
                SampleHttpSessionCreatedListener and
                SampleHttpSessionDestroyedListener)</emphasis></para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para>Add the file <emphasis>starter.ear</emphasis> from
            starter/ear/target/ to the deploy directory of JBoss, this file
            contains:</para>

            <itemizedlist>
              <listitem>
                <para>The file <emphasis>starter.war</emphasis> which is the
                web application that will create and start all the portal
                containers, that is why it must be launched after all the
                other web applications.</para>
              </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>

        <warning>
          <title>Warning #1</title>

          <para>This can only work if a Unified ClassLoader has been
          configured on your JBoss (default behavior) and the load order is
          first the <emphasis>exoplatform.ear</emphasis> then the
          <emphasis>sample-ext.ear</emphasis> and finally the
          <emphasis>starter.ear</emphasis>.</para>
        </warning>

        <warning>
          <title>Warning #2</title>

          <para>The file <emphasis>starter.ear</emphasis> must always been
          started last.</para>
        </warning>
      </section>

      <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToDeploySampleExtension.Tomcat">
        <title>On Tomcat (tested on Tomcat 6.0.20)</title>

        <para>We assume that you have a clean Tomcat version of GateIn, in
        other words, we assume that you have already all the jar files of
        GateIn and their dependencies into <emphasis>tomcat/lib</emphasis>,
        you have all the war files of GateIn into
        <emphasis>tomcat/webapps</emphasis> and you have the realm name
        "exo-domain" defined into the file
        <emphasis>tomcat/conf/jaas.conf</emphasis>.</para>

        <itemizedlist>
          <listitem>
            <para>Add the file <emphasis>sample-ext.war</emphasis> from
            sample/extension/war/target/ to the
            <emphasis>tomcat/webapps</emphasis> directory. <emphasis>(See the
            purpose of this file in the JBoss section)</emphasis>.</para>
          </listitem>

          <listitem>
            <para>Add the folder <emphasis>starter</emphasis> from
            starter/war/target/ to the <emphasis>tomcat/webapps</emphasis>
            directory. <emphasis>(See the purpose of this file in the JBoss
            section)</emphasis>.</para>
          </listitem>

          <listitem>
            <para>Rename the directory (unzipped folder)
            <emphasis>starter</emphasis> to <emphasis>starter.war</emphasis>
            (for more details see the warning below)</para>
          </listitem>

          <listitem>
            <para>Add the jar file
            <emphasis>exo.portal.sample.extension.config-X.Y.Z.jar</emphasis>
            from sample/extension/config/target/ to the
            <emphasis>tomcat/lib</emphasis> directory. <emphasis>(See the
            purpose of this file in the JBoss section)</emphasis>.</para>
          </listitem>

          <listitem>
            <para>Add the jar file
            <emphasis>exo.portal.sample.extension.jar-X.Y.Z.jar</emphasis>
            from sample/extension/jar/target/ to the
            <emphasis>tomcat/lib</emphasis> directory. <emphasis>(See the
            purpose of this file in the JBoss section)</emphasis>.</para>
          </listitem>
        </itemizedlist>

        <warning>
          <title>Warning</title>

          <para>This can only work if the <emphasis>starter.war</emphasis> is
          the last war file to be loaded, so don't hesitate to rename it if
          your war files are loaded following to the alphabetic order.</para>
        </warning>
      </section>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.WhereFindExampleOfCreatingNewPortal">
      <title>Where can I find an example of how to create a new
      portal?</title>

      <para>We added an example of new portal (i.e. ability to create a new
      portal from another portal without changing anything in the portal.ear)
      that you can find in the git repository of gatein at
      https://github.com/gatein/gatein-portal/tree/master/examples.</para>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToDeploySamplePortal">
      <title>How to deploy the sample portal?</title>

      <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToDeploySamplePortal.JBoss">
        <title>On JBoss (tested on JBoss 5.1.0.GA)</title>

        <para>We assume that you have a clean JBoss version of GateIn, in
        other words, we assume that you have already the file
        <emphasis>exoplatform.ear</emphasis> in the
        <emphasis>deploy</emphasis> directory of JBoss and you have the
        related application policy in your
        <emphasis>conf/login-config.xml</emphasis>.</para>

        <para><emphasis role="underline">You need to:</emphasis></para>

        <itemizedlist>
          <listitem>
            <para>Add the file <emphasis>sample-portal.ear</emphasis> from
            <emphasis>sample/portal/ear/target/</emphasis> to the deploy
            directory of JBoss, this file contains:</para>

            <itemizedlist>
              <listitem>
                <para>The file <emphasis>sample-portal.war</emphasis> which is
                the entry point of the new portal</para>
              </listitem>

              <listitem>
                <para>The file <emphasis>rest-sample-portal.war</emphasis>
                which is the entry point for <emphasis>rest</emphasis> outside
                the portal (in the portal you can access to
                <emphasis>rest</emphasis> thanks to path prefix
                <emphasis>/sample-portal/rest</emphasis>)</para>
              </listitem>

              <listitem>
                <para>The file
                <emphasis>exo.portal.sample.portal.config-X.Y.Z.jar</emphasis>
                which is the file in which we defined the
                <emphasis>PortalContainerDefinition</emphasis> of this
                portal</para>
              </listitem>

              <listitem>
                <para>The file
                <emphasis>exo.portal.sample.portal.jar-X.Y.Z.jar</emphasis>
                which is the file in which we have internal classes that are
                actualy a set of sample classes <emphasis>(SampleFilter,
                SampleContextInitializedListener,
                SampleContextDestroyedListener,
                SampleHttpSessionCreatedListener and
                SampleHttpSessionDestroyedListener)</emphasis></para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para>Add the file <emphasis>starter.ear</emphasis> from
            starter/ear/target/ to the deploy directory of JBoss, this file
            contains:</para>

            <itemizedlist>
              <listitem>
                <para>The file <emphasis>starter.war</emphasis> which is the
                web application that will create and start all the portal
                containers, that is why it must be launched after all the
                other web applications.</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para>Define the related application policy in your file
            <emphasis>conf/login-config.xml</emphasis>, as below:</para>
          </listitem>
        </itemizedlist>

        <programlisting language="xml">  &lt;application-policy name="exo-domain-sample-portal"&gt;
    &lt;authentication&gt;
      &lt;login-module code="org.exoplatform.web.security.PortalLoginModule" flag="required"&gt;
        &lt;module-option name="portalContainerName"&gt;sample-portal&lt;/module-option&gt;
        &lt;module-option name="realmName"&gt;exo-domain-sample-portal&lt;/module-option&gt;
      &lt;/login-module&gt;
      &lt;login-module code="org.exoplatform.services.security.jaas.SharedStateLoginModule" flag="required"&gt;
        &lt;module-option name="portalContainerName"&gt;sample-portal&lt;/module-option&gt;
        &lt;module-option name="realmName"&gt;exo-domain-sample-portal&lt;/module-option&gt;
      &lt;/login-module&gt;
      &lt;login-module code="org.exoplatform.services.security.j2ee.JbossLoginModule" flag="required"&gt;
        &lt;module-option name="portalContainerName"&gt;sample-portal&lt;/module-option&gt;
        &lt;module-option name="realmName"&gt;exo-domain-sample-portal&lt;/module-option&gt;
      &lt;/login-module&gt;
    &lt;/authentication&gt;
  &lt;/application-policy&gt;</programlisting>

        <warning>
          <title>Warning #1</title>

          <para>This can only work if a Unified ClassLoader has been
          configured on your JBoss (default behavior) and the load order is
          first the <emphasis>exoplatform.ear</emphasis> then the
          <emphasis>sample-portal.ear</emphasis> and finally the
          <emphasis>starter.ear</emphasis>.</para>
        </warning>

        <warning>
          <title>Warning #2</title>

          <para>The file <emphasis>starter.ear</emphasis> must always been
          started last.</para>
        </warning>
      </section>

      <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.HowToDeploySamplePortal.Tomcat">
        <title>On Tomcat (tested on Tomcat 6.0.20)</title>

        <para>We assume that you have a clean Tomcat version of GateIn, in
        other words, we assume that you have already all the jar files of
        GateIn and their dependencies into <emphasis>tomcat/lib</emphasis>,
        you have all the war files of GateIn into
        <emphasis>tomcat/webapps</emphasis> and you have the realm name
        "exo-domain" defined into the file
        <emphasis>tomcat/conf/jaas.conf</emphasis>.</para>

        <itemizedlist>
          <listitem>
            <para>Add the file <emphasis>sample-portal.war</emphasis> from
            sample/portal/war/target/ to the
            <emphasis>tomcat/webapps</emphasis> directory. <emphasis>(See the
            purpose of this file in the JBoss section)</emphasis>.</para>
          </listitem>

          <listitem>
            <para>Add the file <emphasis>rest-sample-portal.war</emphasis>
            from sample/portal/rest-war/target/ to the
            <emphasis>tomcat/webapps</emphasis> directory. <emphasis>(See the
            purpose of this file in the JBoss section)</emphasis>.</para>
          </listitem>

          <listitem>
            <para>Add the folder <emphasis>starter</emphasis> from
            starter/war/target/ to the <emphasis>tomcat/webapps</emphasis>
            directory. <emphasis>(See the purpose of this file in the JBoss
            section)</emphasis>.</para>
          </listitem>

          <listitem>
            <para>Rename the directory (unzipped folder)
            <emphasis>starter</emphasis> to <emphasis>starter.war</emphasis>
            <emphasis>(for more details see the warning
            below)</emphasis>.</para>
          </listitem>

          <listitem>
            <para>Add the jar file
            <emphasis>exo.portal.sample.portal.config-X.Y.Z.jar</emphasis>
            from sample/portal/config/target/ to the
            <emphasis>tomcat/lib</emphasis> directory. <emphasis>(See the
            purpose of this file in the JBoss section)</emphasis>.</para>
          </listitem>

          <listitem>
            <para>Add the jar file
            <emphasis>exo.portal.sample.portal.jar-X.Y.Z.jar</emphasis> from
            sample/portal/jar/target/ to the <emphasis>tomcat/lib</emphasis>
            directory. <emphasis>(See the purpose of this file in the JBoss
            section)</emphasis>.</para>
          </listitem>

          <listitem>
            <para>Define the related realm in your file
            <emphasis>tomcat/conf/jaas.conf</emphasis>, as below:</para>
          </listitem>
        </itemizedlist>

        <note>
          <title>tomcat/conf/jaas.conf</title>

          <programlisting>...
exo-domain-sample-portal {
  org.exoplatform.web.security.PortalLoginModule required
    portalContainerName="sample-portal"
    realmName="exo-domain-sample-portal";
  org.exoplatform.services.security.jaas.SharedStateLoginModule required
    portalContainerName="sample-portal"
    realmName="exo-domain-sample-portal";
  org.exoplatform.services.security.j2ee.TomcatLoginModule required
    portalContainerName="sample-portal"
    realmName="exo-domain-sample-portal";
};</programlisting>
        </note>

        <itemizedlist>
          <listitem>
            <para>Define the context of <emphasis>sample-portal</emphasis> by
            creating a file called <emphasis>sample-portal.xml</emphasis> into
            <emphasis>tomcat/conf/Catalina/localhost/</emphasis> with the
            following content:</para>
          </listitem>
        </itemizedlist>

        <note>
          <title>tomcat/conf/Catalina/localhost/sample-portal.xml</title>

          <programlisting language="xml">&lt;Context path='/sample-portal' docBase='sample-portal' debug='0' reloadable='true' crossContext='true' privileged='true'&gt;
  &lt;Logger className='org.apache.catalina.logger.SystemOutLogger'
          prefix='localhost_portal_log.' suffix='.txt' timestamp='true'/&gt;
  &lt;Manager className='org.apache.catalina.session.PersistentManager' saveOnRestart='false'/&gt;
  &lt;Realm className='org.apache.catalina.realm.JAASRealm'
         appName='exo-domain-sample-portal'
         userClassNames='org.exoplatform.services.security.jaas.UserPrincipal'
         roleClassNames='org.exoplatform.services.security.jaas.RolePrincipal'
         debug='0' cache='false'/&gt;
  &lt;Valve className='org.apache.catalina.authenticator.FormAuthenticator' characterEncoding='UTF-8'/&gt;&lt;/Context&gt;</programlisting>
        </note>

        <itemizedlist>
          <listitem>
            <para>Define the context of
            <emphasis>rest-sample-portal</emphasis> by creating a file called
            <emphasis>rest-sample-portal.xml</emphasis> into
            <emphasis>tomcat/conf/Catalina/localhost/</emphasis> with the
            following content:</para>
          </listitem>
        </itemizedlist>

        <note>
          <title>tomcat/conf/Catalina/localhost/rest-sample-portal.xml</title>

          <programlisting language="xml">&lt;Context path="/rest-sample-portal" docBase="rest-sample-portal" reloadable="true" crossContext="false"&gt;

  &lt;Logger className='org.apache.catalina.logger.SystemOutLogger'
            prefix='localhost_portal_log.' suffix='.txt' timestamp='true'/&gt;
    &lt;Manager className='org.apache.catalina.session.PersistentManager' saveOnRestart='false'/&gt;
    &lt;Realm className='org.apache.catalina.realm.JAASRealm'
           appName='exo-domain-sample-portal'
           userClassNames="org.exoplatform.services.security.jaas.UserPrincipal"
           roleClassNames="org.exoplatform.services.security.jaas.RolePrincipal"
           debug='0' cache='false'/&gt;
&lt;/Context&gt;</programlisting>
        </note>

        <warning>
          <title>Warning</title>

          <para>This can only work if the <emphasis>starter.war</emphasis> is
          the last war file to be loaded, so don't hesitate to rename it if
          your war files are loaded following to the alphabetic order.</para>
        </warning>
      </section>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.FAQ.java.lang.IllegalStateException">
      <title>I get "java.lang.IllegalStateException: No pre init tasks can be
      added to the portal container 'portal', because it has already been
      initialized." what can I do to fix it?</title>

      <para>To fix this issue you need to check if:</para>

      <orderedlist>
        <listitem>
          <para>The file <emphasis>starter-gatein.ear</emphasis> (which will
          be <emphasis>starter.war</emphasis> for Tomcat) has been
          deployed</para>
        </listitem>

        <listitem>
          <para>The file <emphasis>starter-gatein.ear</emphasis> (which will
          be <emphasis>starter.war</emphasis> for Tomcat) is the last ear file
          to be launched</para>
        </listitem>
      </orderedlist>

      <note>
        <title>Note</title>

        <para>With Tomcat to prevent any alphabetic issue, the good way to
        solve this problem is to:</para>

        <itemizedlist>
          <listitem>
            <para>Unzip the archive <emphasis>starter.war</emphasis> into a
            directory called <emphasis>starter</emphasis></para>
          </listitem>

          <listitem>
            <para>Remove the archive <emphasis>starter.war</emphasis></para>
          </listitem>

          <listitem>
            <para>Rename the folder <emphasis>starter</emphasis> to
            <emphasis>starter.war</emphasis></para>
          </listitem>
        </itemizedlist>

        <para>This tip works because folders corresponding to unzipped wars
        are launched after war files.</para>
      </note>
    </section>
  </section>

  <section id="JCRWithGateIn.HowToExtendMyGateInInstance.Recommendations">
    <title>Recommendations</title>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.Recommendations.NotShipConfigurationFilesWithJarFiles">
      <title>Don't ship your configuration files with your jar files?</title>

      <para>Remove all the configuration files from the jar files (
      <emphasis>conf/configuration.xml</emphasis> and
      <emphasis>conf/portal/configuration.xml</emphasis>) and move them to the
      war file of your extension, otherwise your configuration files will be
      loaded for all the portal containers which could cause incompatibility
      issues with other portals.</para>

      <para>Each extension should manage independently, its css files, js
      files, google gadgets and configuration files. If you add configuration
      files into the jar files of your extension, you brake this law.</para>
    </section>

    <section id="JCRWithGateIn.HowToExtendMyGateInInstance.Recommendations.UsingDedicatedWorkspaceRepositoryForExtension">
      <title>Using a dedicated workspace/repository for your
      extension?</title>

      <para>In order to avoid conflicts with other extensions and to manage
      each extension independently, it is highly recommended to use a
      dedicated workspace or repository per extension.</para>
    </section>
  </section>
</section>
