<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
        <!ENTITY % BOOK_ENTITIES SYSTEM "../../Reference_Guide.ent">
        %BOOK_ENTITIES;
        ]>
<section id="sect-Reference_Guide-Global_Portlet" role="NotInToc">
  <title>Global porlet.xml file</title>

	<para xml:id="sect-Reference_Guide-Global_Portlet-Global_usecase">
      <citetitle>
      <emphasis role="bold">Global portlet.xml usecase</emphasis>
      </citetitle>
    </para>   
      <para>The Portlet Specification introduces PortletFilter as a standard approach to extend the behaviors of portlet
          objects. For example, a filter can transform the content of portlet requests and portlet responses.
          According to the Portlet Specification, normally there are 3 steps in setting up a portlet filter:
      </para>
      <procedure>
          <step>
              <para>Implement a PortletFilter object</para>
          </step>
          <step>
              <para>Define the filter in portlet application deployment descriptor</para>
          </step>
          <step>
              <para>Define the filter mapping in portlet definitions</para>
          </step>
      </procedure>
      <para>Two first steps are quite simple and easy to be done, however, at the step 3, developers/administrators
          need to replicate the filter mapping in many portlet definitions, that makes work error and tedious in
          several use cases.
          The global portlet feature is designed to compensate such limitation.
      </para>

	<para xml:id="sect-Reference_Guide-Global_Portlet-Global_metadata">
      <citetitle>
      <emphasis role="bold">Global metadata</emphasis>
      </citetitle>
    </para>
    
    <para>The Global metadata is declared in the
            <filename>portlet.xml</filename> file conforming with Portlet 2.0 &apos;s XSD.
    </para>
    <programlisting language="xml">&lt;portlet-app version=&quot;1.0&quot; xmlns=&quot;http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd&quot;
             xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;
             xsi:schemaLocation=&quot;http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd&quot;&gt;

&lt;/portlet-app&gt;</programlisting>
	<itemizedlist>
		<listitem>
			<para xml:id="sect-Reference_Guide-Global_Portlet-Location">
				<emphasis role="bold">Location</emphasis>
			</para>
			<para>The path to the global <filename>portlet.xml</filename> is value of <emphasis >gatein.portlet.config</emphasis> in the <filename>configuration.properties</filename> file and varied by hosting
            application servers.
			</para>
				<itemizedlist>
					<listitem>
						<para><emphasis role="bold">For Tomcat</emphasis>: <filename>$PLATFORM_TOMCAT_HOME/gatein/conf/portlet.xml</filename></para>
					</listitem>
					<listitem>
						<para><emphasis role="bold">For JBoss</emphasis>: <filename>$PLATFORM_JBOSS_HOME/server/default/conf/gatein/portlet.xml</filename></para>
					</listitem>
				</itemizedlist>
		</listitem>
		<listitem>
			<para xml:id="sect-Reference_Guide-Global_Portlet-Global_metadata_elements">
				<emphasis role="bold">Global metadata elements</emphasis>
			</para>
			<para>The global <filename>portlet.xml</filename> file conforms to the schema of the portlet deployment descriptor defined in the Portlet
            Specification with some restrictions. In this file, the following elements are supported:
			</para>
			  <itemizedlist>
				<listitem>
				  <para xml:id="sect-Reference_Guide-Global_metadata_elements-Global_Portlet-Portlet_filter"><emphasis role="bold">Portlet filter</emphasis>: The Portlet filter mappings declared in the global<filename> portlet.xml</filename> file are applied across portlet applications. With
                the XML configuration below, the filter ApplicationMonitoringFilter involves in request handling on any
                deployed portlet.
				 </para>
        <programlisting language="xml">&lt;filter&gt;
     &lt;filter-name&gt;org.exoplatform.portal.application.ApplicationMonitoringFilter&lt;/filter-name&gt;
    &lt;filter-class&gt;org.exoplatform.portal.application.ApplicationMonitoringFilter&lt;/filter-class&gt;
    &lt;lifecycle&gt;ACTION_PHASE&lt;/lifecycle&gt;
    &lt;lifecycle&gt;RENDER_PHASE&lt;/lifecycle&gt;
    &lt;lifecycle&gt;EVENT_PHASE&lt;/lifecycle&gt;
    &lt;lifecycle&gt;RESOURCE_PHASE&lt;/lifecycle&gt;
&lt;/filter&gt;</programlisting>
				</listitem>
				<listitem>
				  <para><emphasis role="bold">Application Monitoring Filter</emphasis>: This filter supports 4 lifecycle phases as the order below:
				  <emphasis >ACTION_PHASE/ EVENT_PHASE/ RENDER_PHASE/ RESOURCE_PHASE</emphasis>
				  and
				  records statistic information on deployed portlets.
				  The filter alternates actual monitoring mechanism in WebUI Framework.
				  </para>
				</listitem>
				<listitem>
				  <para xml:id="sect-Reference_Guide-Global_metadata_elements-Global_Portlet-Portlet_mode"><emphasis role="bold">Portlet Mode and Window State</emphasis>: The global <filename>portlet.xml</filename> file is considered as an alternative place to declare custom Portlet Modes and Window States.
				</para>
				</listitem>
			  </itemizedlist>
		</listitem>
	</itemizedlist>  
</section>