<?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-Data_Import_Strategy">
   <title>Data Import Strategy</title>
    <highlights>
       <itemizedlist>
             <listitem>
               <para><emphasis role="bold"><link linkend="sect-Reference_Guide-Portal_Data_Override">Portal Data Override</link></emphasis></para>
             <para>Information about Data Import activation.</para>
           </listitem>
              <listitem>
               <para><emphasis role="bold"><link linkend="sect-Reference_Guide-Import_Mode">Import Mode</link></emphasis></para>
             <para>Information about modes for the import strategy.</para>
           </listitem>
           <listitem>
               <para><emphasis role="bold"><link linkend="sect-Reference_Guide-Import_Strategy">Data Import Strategy</link></emphasis></para>
             <para>Information about 3 types of object data: <emphasis>Portal Config</emphasis>, <emphasis> Page Data</emphasis> and <emphasis>Navigation Data</emphasis>.</para>
           </listitem>
       </itemizedlist>
</highlights>
       <para>In the Portal extension mechanism, developers can define an extension
        that Portal data can be customized by configurations in the extension. There
        are several cases which an extension developer wants to define how to customize the Portal data, 
        for example modifying, overwriting or just inserting a bit into the data defined by the portal. 
        Therefore, GateIn also defines several modes for each case and the only thing which a developer has to do is to clarify the
        usecase and reasonably configure extensions. 
      </para>
      <para>
        This section shows you how data are changes in each mode.
      </para>
 
   <section id="sect-Reference_Guide-Portal_Data_Override" role="NotInToc">
     <title>Portal Data Override</title>
     <para>
     In order to activate the Data Import on specific Portal metadata, you must set <emphasis>override</emphasis> parameter of <emphasis>NewPortalConfigListener</emphasis> component registering this Portal metadata to <emphasis role="bold">true</emphasis>. If this parameter is missing, its value is <emphasis role="bold">false</emphasis> and the Portal metadata is not reimported. See the following example to activate Data Import:  
     </para>
<programlisting language="xml"><![CDATA[<component-plugin>
	<!-- The name of the plugin -->
	<name>new.portal.config.user.listener</name>
	<!-- The name of the method to call on the UserPortalConfigService in order to register the NewPortalConfigs -->
	<set-method>initListener</set-method>
	<!-- The full qualified name of the NewPortalConfigListener -->
	<type>org.exoplatform.portal.config.NewPortalConfigListener</type>
	<description>this listener init the portal configuration</description>
	<init-params>
		<value-param>
			<name>override</name>
			<description>The flag parameter to decide if portal metadata is overriden on restarting server</description>
			<value>true</value>
		</value-param>
		<!-- List of NewPortalConfig instances-->
		...
	</init-params>
</component-plugin>]]></programlisting>
   </section>
   <section id="sect-Reference_Guide-Import_Mode" role="NotInToc">
      <title>Import Mode</title>
      In this section, the following modes for the import strategy are introduced:
      <itemizedlist>
         <listitem>
            <para>
               <emphasis>CONSERVE</emphasis> 
            </para>
         </listitem>
         <listitem>
            <para>
               <emphasis>MERGE</emphasis>
            </para>
         </listitem>
         <listitem>
            <para>
               <emphasis>INSERT</emphasis>
            </para>
         </listitem>
         <listitem>
            <para>
               <emphasis>OVERWRITE</emphasis>
            </para>
         </listitem>
      </itemizedlist> 
      <para>
        Each mode indicates how the Portal data are imported. The import mode value is
        set whenever NewPortalConfigListener is initiated. If the mode is not set,
        the default value will be used in this case. The default value is configurable as
        a UserPortalConfigService initial param. For example, the bellow configuration
        means that default value is <emphasis>MERGE</emphasis>
      </para>
      <programlisting language="xml"><![CDATA[<component>
  <key>org.exoplatform.portal.config.UserPortalConfigService</key>
  <type>org.exoplatform.portal.config.UserPortalConfigService</type>
  <component-plugins>
  ............
  </component-plugins>
  <init-params>
    <value-param>
      <name>default.import.mode</name>
      <value>merge</value>
    </value-param>
  </init-params>
</component>]]></programlisting>
      <para>
      The way that the import strategy works with the import mode will be clearly demonstrated in next sections for each type of data.
      </para>
   </section>
   <section id="sect-Reference_Guide-Import_Strategy" role="NotInToc">
      <title>Data Import Strategy</title>
      The 'Portal Data' term which has been referred in the previous sections can be
      classified into three types of object data: Portal Config, Page Data and
      Navigation Data; each of which has some differences in the import strategy.

     <para id="sect-Reference_Guide-Navigation_Data">
          <citetitle>
            <emphasis role="bold">Navigation Data</emphasis>
          </citetitle>
        </para>
              The navigation data import strategy will be processed to the import mode level as the followings:
         <itemizedlist>
            <listitem>
               <emphasis>CONSERVE</emphasis>: If the navigation exists, leave it untouched. Otherwise, import data.
            </listitem>
            <listitem>
               <emphasis>INSERT</emphasis>: Insert the missing description data, but add only new nodes. Other modifications remains untouched.
            </listitem>
            <listitem>
               <emphasis>MERGE</emphasis>: Merge the description data, add missing nodes and update same name nodes.
            </listitem>
            <listitem>
               <emphasis>OVERWRITE</emphasis>: Always destroy the previous data and recreate it.
            </listitem>
         </itemizedlist>
         <para>
            In the GateIn navigation structure, each navigation can be referred
            to a tree which each node links to a page content. Each node contains some
            description data, such as label, icon, page reference, and more. Therefore, GateIn
            provides a way to insert or merge new data to the initiated navigation tree or a
            sub-tree.
         </para>
         <para>
            The merge strategy performs the recursive comparison of child nodes between the
            existing persistent nodes of a navigation and the transient nodes provided by
            a descriptor:
            <procedure id="proc-Reference_Guide-Merge_Strategy">
               <step>
				<para>
                  Start with the root nodes (which is the effective root node or another node if the parent URI is specified).
				</para>
               </step>
               <step>
				<para>
                  Compare the set of child nodes and insert the missing nodes in the persistent nodes.
				</para>
               </step>
               <step>
				<para>
                  Proceed recursively for each child having the same name.
				</para>
               </step>
            </procedure>
         </para>
            Let's see the example with two navigation nodes in each import mode. In this case, there are 2 navigation definitions:
         <programlisting language="xml"><![CDATA[<node-navigation>
  <page-nodes>
    <node>
      <name>foo</name>
      <icon>foo_icon_1</icon>
      <node>
        <name>juu</name>
        <icon>juu_icon</icon>
      </node>
    </node>
    <node>
      <name>daa</name>
      <icon>daa_icon</icon>
    </node>
  </page-nodes>
</node-navigation>]]></programlisting>
      Navigation node tree hierarchy
      <mediaobject>
         <imageobject role="html">
            <imagedata fileref="images/DataImportStrategy/navigation1.png" format="PNG" align="center"/>
         </imageobject>
          <imageobject role="fo">
            <imagedata fileref="images/DataImportStrategy/navigation1.png" format="PNG" align="center" scalefit="1" width="100mm"/>
         </imageobject>
      </mediaobject>
      <programlisting language="xml"><![CDATA[<node-navigation>
  <page-nodes>
    <node>
      <name>foo</name>
      <icon>foo_icon_2</icon>
    </node>
    <node>
      <name>bar</name>
      <icon>bar_icon</icon>
    </node>
  </page-nodes>
</node-navigation>]]></programlisting>
      Navigation node tree hierarchy
      <mediaobject>
         <imageobject role="html">
            <imagedata fileref="images/DataImportStrategy/navigation2.png" format="PNG" align="center"/>
         </imageobject>
          <imageobject role="fo">
            <imagedata fileref="images/DataImportStrategy/navigation2.png" format="PNG" align="center" scalefit="1" width="100mm"/>
         </imageobject>
      </mediaobject>
      <para>
         For example, the <emphasis>navigation1</emphasis> is loaded before <emphasis>navigation2</emphasis>. The Navigation
         Importer processes on two navigation definitions, depending on the Import Mode defined in portal configuration.
         <itemizedlist>
            <listitem>
               <para>
                  Case 1: Import mode is <emphasis>CONSERVE</emphasis>.
               </para>
               <para>
                  With the <emphasis>CONSERVE</emphasis> mode, data are only imported when they do not exist. So, if
                  the navigation has been created by the <emphasis>navigation1</emphasis> definition, the <emphasis>navigation2</emphasis> definition
                  does not affect anything on it. We have the result as following
               </para>
               <mediaobject>
                  <imageobject>
                     <imagedata fileref="images/DataImportStrategy/navigation1.png" format="PNG" align="center"/>
                  </imageobject>
               </mediaobject>
            </listitem>
            <listitem>
               <para>
                  Case 2: Import mode is <emphasis>INSERT</emphasis>.
               </para>
               <para>
                  If a node does not exist, the importer will add new nodes to the navigation tree. You will see the following result:
               </para>
               <mediaobject>
                  <imageobject role="html">
                     <imagedata fileref="images/DataImportStrategy/navigation_insert.png" format="PNG" align="center"/>
                  </imageobject>
                   <imageobject role="fo">
                     <imagedata fileref="images/DataImportStrategy/navigation_insert.png" format="PNG" align="center" scalefit="1" width="100mm"/>
                  </imageobject>
               </mediaobject>
               <para>
                  Hereafter, the node 'bar' is added to the navigation tree, because it does not exist in the initiated data.
                  Other nodes are kept in the import process.
               </para>
            </listitem>
            <listitem>
               <para>
                  Case 3: Import mode is <emphasis>MERGE</emphasis>.
               </para>
               <para>
                  The <emphasis>MERGE</emphasis> mode indicates that a new node is added to the navigation tree, and
                  updates the node data (such node label and node icon in the example) if it exists. 
               </para>
               <mediaobject>
                  <imageobject role="html">
                     <imagedata fileref="images/DataImportStrategy/navigation_merge.png" format="PNG" align="center"/>
                  </imageobject>
                   <imageobject role="fo">
                     <imagedata fileref="images/DataImportStrategy/navigation_merge.png" format="PNG" align="center" scalefit="1" width="100mm"/>
                  </imageobject>
               </mediaobject>
            </listitem>
            <listitem>
               <para>
                  Case 4: Import mode is <emphasis>OVERWRITE</emphasis>.
               </para>
               <para>
                  Everything will be destroyed and replaced with new data if the <emphasis>OVERWRITE</emphasis> mode is used.
               </para>
               <mediaobject>
                  <imageobject role="html">
                     <imagedata fileref="images/DataImportStrategy/navigation2.png" format="PNG" align="center"/>
                  </imageobject>
                   <imageobject role="fo">
                     <imagedata fileref="images/DataImportStrategy/navigation2.png" format="PNG" align="center" scalefit="1" width="100mm"/>
                  </imageobject>
               </mediaobject>
            </listitem>
         </itemizedlist>
      </para>


     <para id="sect-Reference_Guide-Portal_Config">
      <citetitle><emphasis role="bold">Portal Config</emphasis></citetitle>
    </para>

         <para>
            PortalConfig defines the portal name, permission, layout and some properties
            of a site. These information are configured in the <filename>portal.xml</filename>, <filename>group.xml</filename> or
            <filename>user.xml</filename>, depending on the site type. The PortalConfig importer performs a strategy
            that is based on the mode defined in NewPortalConfigListener, including <emphasis>CONSERVE</emphasis>,
            <emphasis>INSERT</emphasis>, <emphasis>MERGE</emphasis> or <emphasis>OVERWRITE</emphasis>. Let's see how the import mode affects in the process of
            portal data performance:
         </para>
         <itemizedlist>
            <listitem>
               <emphasis>CONSERVE</emphasis>: There is nothing to be imported. The existing data will be kept without any changes.
            </listitem>
            <listitem>
               <emphasis>INSERT</emphasis>: When the portal config does not exist, create the new portal defined by the portal config definition. Otherwise, do nothing.
            </listitem>
            <listitem>
               <emphasis>MERGE</emphasis> and <emphasis>OVERWRITE</emphasis> have the same behavior. The new portal config will be created if it does not exist or update portal properties defined by the portal config definition.
            </listitem>
         </itemizedlist>

        <para id="sect-Reference_Guide-Page_Data">
          <citetitle>
            <emphasis role="bold">Page Data</emphasis>
          </citetitle>
        </para>

        <para>
            The import mode affects the page data import as the same as Portal Config.
         </para>

      <note>
         <para>
            If the Import mode is <emphasis>CONSERVE</emphasis> or <emphasis>INSERT</emphasis>, the data import strategy always performs
            as the <emphasis>MERGE</emphasis> mode in the first data initialization of the Portal.
         </para>
      </note>
   </section>
<para>
<prompt>
  <emphasis role="bold">See also</emphasis>
</prompt>
</para>
		<itemizedlist>
           <listitem>
               <para><link linkend="sect-Reference_Guide-Default_Portal_Configuration">Default Portal Configuration</link></para>
           </listitem>
           <listitem>
               <para><link linkend="sect-Reference_Guide-Portal_Default_Permission_Configuration">Portal Default Permission Configuration</link></para>
           </listitem>
           <listitem>
               <para><link linkend="sect-Reference_Guide-Portal_Navigation_Configuration">Portal Navigation Configuration</link></para>
           </listitem>
		    <listitem>
               <para><link linkend="sect-Reference_Guide-Internationalization_Configuration">Internationalization Configuration</link></para>
           </listitem>
           <listitem>
               <para><link linkend="sect-Reference_Guide-XML_Resources_Bundles">XML Resources Bundles</link></para>
           </listitem>
		   <listitem>
               <para><link linkend="sect-Reference_Guide-Javascript_Configuration">JavaScript Configuration</link></para>
           </listitem>
       </itemizedlist>
</section>
