Author: pnedonosko Date: 2010-05-19 09:50:04 -0400 (Wed, 19 May 2010) New Revision: 2410 Added: jcr/tags/1.12.2-CR1/docs/userguide/en/src/main/docbook/en-US/modules/portal-container.xml Modified: jcr/tags/1.12.2-CR1/docs/userguide/en/src/main/docbook/en-US/master.xml Log: EXOJCR-706 merge with trunk docs Modified: jcr/tags/1.12.2-CR1/docs/userguide/en/src/main/docbook/en-US/master.xml =================================================================== --- jcr/tags/1.12.2-CR1/docs/userguide/en/src/main/docbook/en-US/master.xml 2010-05-19 13:40:27 UTC (rev 2409) +++ jcr/tags/1.12.2-CR1/docs/userguide/en/src/main/docbook/en-US/master.xml 2010-05-19 13:50:04 UTC (rev 2410) @@ -57,6 +57,9 @@ <xi:include href="modules/performance.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="modules/portal-container.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </book> Copied: jcr/tags/1.12.2-CR1/docs/userguide/en/src/main/docbook/en-US/modules/portal-container.xml (from rev 2409, jcr/trunk/docs/userguide/en/src/main/docbook/en-US/modules/portal-container.xml) =================================================================== --- jcr/tags/1.12.2-CR1/docs/userguide/en/src/main/docbook/en-US/modules/portal-container.xml (rev 0) +++ jcr/tags/1.12.2-CR1/docs/userguide/en/src/main/docbook/en-US/modules/portal-container.xml 2010-05-19 13:50:04 UTC (rev 2410) @@ -0,0 +1,2516 @@ +<?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"> +<part> + <title>How to extend my GateIn instance?</title> + + <chapter id="Introduction"> + <title>Introduction</title> + + <section id="Overview"> + <title>Overview</title> + + <para>Since GateIn beta 2, we added a set of features in order 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> + + <section id="Motivations"> + <title>Motivations</title> + + <para>Up to now, to create an application over an eXo portal 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> + </chapter> + + <chapter id="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="Removeallthehardcodedportalcontainernamei.e.portal"> + <title>Remove 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="Removeallthehardcodedrestcontextnamei.e.rest"> + <title>Remove 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="Removeallthehardcodedrealmnamei.e.exodomain"> + <title>Remove 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="MakeyourHttpFilterscompatible"> + <title>Make 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="MakeyourHttpServletscompatible"> + <title>Make 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 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="MakeyourHttpSessionListenerscompatible"> + <title>Make 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="UseinittasksifyouneedaPortalContainertoinitializeanHttpFilteroranHttpServlet"> + <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>A init task is defined as below</para> + + <note> + <title>PortalContainerPreInitTask</title> + + <programlisting> /** + * 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>... +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>... +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="MakeyourLoginModulescompatible"> + <title>Make 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="Avoidstaticmodifieroncomponentdependency"> + <title>Avoid <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="Avoidcomponentinitializationbasedoncomponentdependencyintheconstructor"> + <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> + </chapter> + + <chapter id="FAQ"> + <title>FAQ</title> + + <section id="Whathaschangedsincethepreviousversions"> + <title>What has changed since the previous versions?</title> + + <para>The main difference with previous versions is the way to package + your application, in 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="Whatisthemainpurposeofaportalextension"> + <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 to change or + duplicate files that are in the portal.war.</para> + </section> + + <section id="Whatisthemainpurposeofthestarter"> + <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="Howaportalandaportalcontainerarerelated"> + <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="HowtodefineandregisteraPortalContainerDefinition"> + <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 wiki article <ulink + url="http://wiki.exoplatform.com/xwiki/bin/view/Kernel/Container+Con... + + <para><emphasis role="underline">See below an example of configuration + file that define and register a + PortalContainerDefinition:</emphasis></para> + + <programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt; +&lt;configuration + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd http://www.exoplaform.org/xml/ns/kernel_1_0.xsd" + xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.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="HowtheplatforminterpretsthedependencyorderdefinedintothePortalContainerDefinition"> + <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="HowtochangetheServletContextnametherealmnameandortherestcontextnameofmyportalwithoutusingaPortalContainerDefinition"> + <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 wiki article <ulink + url="http://wiki.exoplatform.com/xwiki/bin/view/Kernel/Container+Con... + + <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>&lt;?xml version="1.0" encoding="UTF-8"?&gt; +&lt;configuration + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd http://www.exoplaform.org/xml/ns/kernel_1_0.xsd" + xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.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="OnJBosstestedonJBoss5.1.0.GA"> + <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="OnTomcattestedonTomcat6.0.20"> + <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="Howtoaddnewconfigurationfiletoagivenportalfromawarfile"> + <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>&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="Howtocreatedefineaportalextension"> + <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>&lt;?xml version="1.0" encoding="UTF-8"?&gt; +&lt;configuration + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd http://www.exoplaform.org/xml/ns/kernel_1_0.xsd" + xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.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="Howtodeployaportalextension"> + <title>How to deploy a portal extension?</title> + + <para>Refer to <emphasis>How to deploy the sample + extension?</emphasis></para> + </section> + + <section id="Howtocreatedefineanewportal"> + <title>How to create/define a new portal?</title> + + <para>You have no need anymore, to duplicate the entire "portal.war" + file to create a new portal, you just 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>&lt;?xml version="1.0" encoding="UTF-8"?&gt; +&lt;configuration + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd http://www.exoplaform.org/xml/ns/kernel_1_0.xsd" + xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.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="Howtodeployanewportal"> + <title>How to deploy a new portal?</title> + + <para>Refer to <emphasis>How to deploy the sample + portal?</emphasis></para> + </section> + + <section id="Howtoimportproperlyaconfigurationfileusingtheprefixwar"> + <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>&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.exoplaform.org/xml/ns/kernel_1_0.xsd http://www.exoplaform.org/xml/ns/kernel_1_0.xsd" + xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.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="Howtoavoidduplicatingconfigurationfilesjusttorenameasimplevalue"> + <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>&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.exoplaform.org/xml/ns/kernel_1_0.xsd http://www.exoplaform.org/xml/ns/kernel_1_0.xsd" + xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.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="HowtoaddorchangeaRepositoryandoraWorkspace"> + <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>&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.exoplaform.org/xml/ns/kernel_1_0.xsd http://www.exoplaform.org/xml/ns/kernel_1_0.xsd" + xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.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>&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.JDBCWorkspaceDataContainer"&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="update-storage" value="true" /&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&gt; + &lt;time-out&gt;15m&lt;/time-out&gt;&lt;!-- 15min --&gt; + &lt;persister class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister"&gt; + &lt;properties&gt; + &lt;property name="path" value="../temp/lock/sample-ws${container.name.suffix}" /&gt; + &lt;/properties&gt; + &lt;/persister&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="HowtoaddnewResourceBundlestomyportal"> + <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>&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.exoplaform.org/xml/ns/kernel_1_0.xsd http://www.exoplaform.org/xml/ns/kernel_1_0.xsd" + xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.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="HowtooverwriteexistingResourceBundlesinmyportal"> + <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="Howtoreplaceagroovytemplateofmyportal"> + <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="HowtoaddnewPortalConfigurationsNavigationsPagesorPortletPreferencestomyportal"> + <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>&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.exoplaform.org/xml/ns/kernel_1_0.xsd http://www.exoplaform.org/xml/ns/kernel_1_0.xsd" + xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.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="HowtoaddnewHttpFilterstomyportalwithoutmodifyingtheportalbinary"> + <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>&lt;?xml version="1.0" encoding="UTF-8"?&gt; +&lt;configuration + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd http://www.exoplaform.org/xml/ns/kernel_1_0.xsd" + xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.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>... +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="HowtoaddnewHttpSessionListenersandorServletContextListenerstomyportalwithoutmodifyingtheportalbinary"> + <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>&lt;?xml version="1.0" encoding="UTF-8"?&gt; +&lt;configuration + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd http://www.exoplaform.org/xml/ns/kernel_1_0.xsd" + xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.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>.. +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>.. +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="HowtoaddnewHttpServlettomyportalwithoutmodifyingtheportalbinary"> + <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 wiki + article <ulink + url="http://wiki.exoplatform.com/xwiki/bin/view/WS">http://w... + </section> + + <section id="HowtooverrideoraddaContextParametertomyportalwithoutmodifyingtheportalbinary"> + <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="WherecanIfoundanexampleofhowtoextendmyportal"> + <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 svn of gatein at gatein/sample/extension.</para> + </section> + + <section id="Howtodeploythesampleextension"> + <title>How to deploy the sample extension?</title> + + <section id="OnJBosstestedonJBoss5.1.0.GA2"> + <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="OnTomcattestedonTomcat6.0.202"> + <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="WherecanIfoundanexampleofhowtocreateanewportal"> + <title>Where can I found 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 svn of gatein at gatein/sample/portal.</para> + </section> + + <section id="Howtodeploythesampleportal"> + <title>How to deploy the sample portal?</title> + + <section id="OnJBosstestedonJBoss5.1.0.GA3"> + <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> &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="OnTomcattestedonTomcat6.0.203"> + <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>&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>&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="Igetjava.lang.IllegalStateExceptionNopreinittaskscanbeaddedtotheportalcontainerportalbecauseithasalreadybeeninitialized.whatcanIdotofixit"> + <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 id="WhathasbeendonetoallowGateInextensions"> + <title>What has been done to allow GateIn extensions?</title> + + <para>Refer to the dedicated wiki article <ulink + url="What has been done to allow GateIn extensions?">What has been done + to allow GateIn extensions?</ulink></para> + </section> + </chapter> + + <chapter id="Recommendations"> + <title>Recommendations</title> + + <section id="Dontshipyourconfigurationfileswithyourjarfiles"> + <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="Useadedicatedworkspacerepositoryforyourextension"> + <title>Use 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> + </chapter> +</part>