[portal-commits] JBoss Portal SVN: r10565 - docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules.

Author: mmcallis Date: 2008-04-13 21:36:59 -0400 (Sun, 13 Apr 2008) New Revision: 10565 Modified: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/migration.xml Log: - updating 4.1. Manual Upgrade as per http://wiki.jboss.org/wiki/Portal2_6_from_2_4_migration - old content now in comments.. Modified: docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/migration.xml =================================================================== --- docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/migration.xml 2008-04-13 23:29:52 UTC (rev 10564) +++ docs/branches/JBoss_Portal_Branch_2_6/referenceGuide/en/modules/migration.xml 2008-04-14 01:36:59 UTC (rev 10565) @@ -21,6 +21,503 @@ </warning> </para> <sect1 id="manual_migration"> + <title>Manual Upgrade</title> + <para> + The database schema has not changed since JBoss Portal 2.4; however, there are several differences when using a database created by JBoss Portal 2.4, that prevent simply deploying the latest version of JBoss Portal. For example, some portlets are no longer present in JBoss Portal 2.6, and certain existing portlets are now packaged differently. This chapter describes updating a MySQL database created by JBoss Portal 2.4 for use with JBoss Portal 2.6. + </para> + <para> + The upgrade procedure can be straightforward: + </para> + <para> + <orderedlist> + <listitem> + <para> + If you are using the JBoss Portal binary, remove the <filename>$JBOSS_HOME/server/default/deploy/jboss-portal.sar/</filename> directory. If JBoss Portal was built from source, remove the <filename>$JBOSS_HOME/server/default/deploy/jboss-portal.sar</filename> file. + </para> + </listitem> + <!--<listitem> + Remove <emphasis role="bold">$JBOSS_HOME/server/default/data</emphasis> directory. + </listitem>--> + <listitem> + <para> + Update the data in the JBoss Portal database, as described in <xref linkend="upgrade_portal_database"/>. + </para> + </listitem> + <listitem> + <para> + Deploy JBoss Portal 2.6. + </para> + </listitem> + </orderedlist> + </para> + <sect2> + <title>Themes</title> + <para> + In JBoss Portal 2.6, portal pages contain additional areas, such as the <guiicon>Login</guiicon>, <guiicon>Admin</guiicon>, and <guiicon>Dashboard</guiicon> links, on the top right-hand corner: + </para> + <para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/migration/theme.png"/> + </imageobject> + </mediaobject> + </para> + <para> + Since portal pages now contain additional areas, certain themes have changed. If a default theme that exists in JBoss Portal 2.6 is used, such as renaissance, no configuration should be necessary. Using old themes from JBoss Portal 2.4 may make JBoss Portal 2.6 unusable, for example, not being able to log in. To update custom themes, refer to themes bundled with JBoss Portal 2.6 as an example. + </para> + </sect2> + <sect2 id="upgrade_portal_database"> + <title>Updating the Database</title> + <para> + The following tables contain all references to portlets: + </para> + <para> + <itemizedlist> + <listitem> + <para> + <emphasis>JBP_INSTANCE</emphasis> + </para> + </listitem> + <listitem> + <para> + <emphasis>JBP_WINDOW</emphasis> + </para> + </listitem> + <listitem> + <para> + <emphasis>JBP_OBJECT_NODE</emphasis> + </para> + </listitem> + </itemizedlist> + </para> + <para> + When running JBoss Portal 2.6 with a database created by JBoss Portal 2.4, a non-existing portlet will try to display, resulting in a <computeroutput>404</computeroutput>, <computeroutput>The requested resource() is not available</computeroutput>, error. + </para> + <para> + All procedures described in the following sections can performed using the <computeroutput>Admin</computeroutput> Portlet. Treat these directions as guidelines when migrating a large JBoss Portal deployment. Database data can be updated manually using the correct tools for your RDBMS. For example, if you are using a MySQL database, use the <ulink url="http://www.mysql.com/products/tools/query-browser/">MySQL Query Browser</ulink>. + </para> + <para> + During the upgrade process, legacy references have to be cleaned up, to either remove them, or to allow JBoss Portal 2.6 to recreate them correctly. Remove all references (instances and windows) to the portlets listed below, as they are not present in JBoss Portal 2.6. These can be done using the JBoss Portal 2.6 <computeroutput>Admin</computeroutput> portlet: + </para> + <para> + <itemizedlist> + <listitem> + <para> + <emphasis>HeaderContentPortlet</emphasis> + </para> + </listitem> + <listitem> + <para> + <emphasis>URLPortlet</emphasis> + </para> + </listitem> + <listitem> + <para> + <emphasis>TestPortlet</emphasis> + </para> + </listitem> + <listitem> + <para> + <emphasis>PortletA</emphasis> + </para> + </listitem> + <listitem> + <para> + <emphasis>PortletB</emphasis> + </para> + </listitem> + <listitem> + <para> + <emphasis>SecuredTestPortlet</emphasis> + </para> + </listitem> + <listitem> + <para> + <emphasis>CharsetPortlet</emphasis> + </para> + </listitem> + <listitem> + <para> + <emphasis>CounterPortlet</emphasis> + </para> + </listitem> + <listitem> + <para> + <emphasis>CachedCounterPortlet</emphasis> + </para> + </listitem> + <listitem> + <para> + <emphasis>ExceptionPortlet</emphasis> + </para> + </listitem> + <listitem> + <para> + <emphasis>PortletSessionPortlet</emphasis> + </para> + </listitem> + <listitem> + <para> + <emphasis>EncodingPortlet</emphasis> + </para> + </listitem> + </itemizedlist> + </para> + <para> + The following instructions refer to a standard JBoss Portal 2.4 deployment. If you named core portlets, portlet instances, or portlet windows differently, you need to make the appropriate modifications. The following is an example of using the MySQL Query Browser: + </para> + <para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/migration/querybrowser1.png"/> + </imageobject> + </mediaobject> + </para> + </sect2> + <sect2> + <title>Portlet Names</title> + <para> + Names of certain core bundled-portlets have changed. Destroy the following instances and use the <computeroutput>Admin</computeroutput> Portlet to recreate them, or, edit the <emphasis role="bold">JBP_INSTANCES</emphasis> table as follows: + </para> + <para> + <itemizedlist> + <listitem> + <para> + Change <emphasis>local.samples.JSPPortlet'</emphasis> in the <emphasis>PORTLET_REF</emphasis> column to <emphasis>local./portal-jsp-samples.JSPPortlet</emphasis>. + </para> + </listitem> + <listitem> + <para> + Change <emphasis>local.portal.CMSPortlet</emphasis> in the <emphasis>PORTLET_REF</emphasis> column to <emphasis>local./portal-cms.CMSPortlet</emphasis>. + </para> + </listitem> + <listitem> + <para> + Change <emphasis>local.portal.CMSAdminPortlet</emphasis> in the <emphasis>PORTLET_REF</emphasis> column to <emphasis>local./portal-cms.CMSAdminPortlet</emphasis>. + </para> + </listitem> + <listitem> + <para> + Change <emphasis>local.portal.ManagementPortlet</emphasis> in the <emphasis>PORTLET_REF</emphasis> column to <emphasis>local./portal-admin.AdminPortlet</emphasis>. + </para> + </listitem> + </itemizedlist> + </para> + <para> + Some portlets are no longer present in JBoss Portal 2.6, and certain existing portlets are now packaged differently. Remove the following entires in the <emphasis role="bold">JBP_INSTANCE</emphasis> table, so that JBoss Portal 2.6 can recreate them: + </para> + <para> + <itemizedlist> + <listitem> + <para> + rows containing <emphasis>NewsPortletInstance2</emphasis> in the <emphasis>ID</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>local.portal.NavigationPortlet</emphasis> in the <emphasis>PORTLET_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>local.samples.HeaderContentPortlet</emphasis> in the <emphasis>PORTLET_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>local.samples.WeatherPortlet</emphasis> in the <emphasis>PORTLET_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>local.samples.NewsPortlet</emphasis> in the <emphasis>PORTLET_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>local.samples.URLPortlet</emphasis> in the <emphasis>PORTLET_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>local.samples.TestPortlet</emphasis> in the <emphasis>PORTLET_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>local.samples.PortletA</emphasis> in the <emphasis>PORTLET_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>local.samples.PortletB</emphasis> in the <emphasis>PORTLET_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>local.samples.SecuredTestPortlet</emphasis> in the <emphasis>PORTLET_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>local.samples.CharsetPortlet</emphasis> in the <emphasis>PORTLET_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>local.samples.CounterPortlet</emphasis> in the <emphasis>PORTLET_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>local.samples.CachedCounterPortlet</emphasis> in the <emphasis>PORTLET_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>local.samples.ExceptionPortlet</emphasis> in the <emphasis>PORTLET_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>local.samples.PortletSessionPortlet</emphasis> in the <emphasis>PORTLET_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>local.samples.EncodingPortlet</emphasis> in the <emphasis>PORTLET_REF</emphasis> column. + </para> + </listitem> + </itemizedlist> + </para> + <para> + Remove the following entires in the <emphasis role="bold">JBP_WINDOW</emphasis> table, so that JBoss Portal 2.6 can recreate them: + </para> + <para> + <itemizedlist> + <listitem> + <para> + rows containing <emphasis>NavigationPortletInstance</emphasis> in the <emphasis>INSTANCE_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>URLPortletInstance</emphasis> in the <emphasis>INSTANCE_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>PortletAInstance</emphasis> in the <emphasis>INSTANCE_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>PortletBInstance</emphasis> in the <emphasis>INSTANCE_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>EncodingPortletInstance</emphasis> in the <emphasis>INSTANCE_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>PortletSessionPortletInstance</emphasis> in the <emphasis>INSTANCE_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>CachedCounterPortletInstance</emphasis> in the <emphasis>INSTANCE_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>CounterPortletInstance</emphasis> in the <emphasis>INSTANCE_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>CharsetPortletInstance</emphasis> in the <emphasis>INSTANCE_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>SecuredTestPortletInstance</emphasis> in the <emphasis>INSTANCE_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>SecuredTestPortletInstance</emphasis> in the <emphasis>INSTANCE_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>ExceptionPortletinstance</emphasis> in the <emphasis>INSTANCE_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>HeaderContentPortletInstance</emphasis> in the <emphasis>INSTANCE_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>TestPortletInstance</emphasis> in the <emphasis>INSTANCE_REF</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>MissingPortletInstance</emphasis> in the <emphasis>INSTANCE_REF</emphasis> column. + </para> + </listitem> + </itemizedlist> + </para> + <para> + Remove the following entires in the <emphasis role="bold">JBP_OBJECT_NODE</emphasis> table, so that JBoss Portal 2.6 can recreate them: + </para> + <para> + <itemizedlist> + <listitem> + <para> + rows containing <emphasis>NavigationPortletWindow</emphasis> in the <emphasis>NAME</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>URLPortletWindow</emphasis> in the <emphasis>NAME</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>PortletAWindow</emphasis> in the <emphasis>NAME</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>PortletBWindow</emphasis> in the <emphasis>NAME</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>MissingInstanceWindow</emphasis> in the <emphasis>NAME</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>EncodingPortletWindow</emphasis> in the <emphasis>NAME</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>PortletSessionPortletWindow</emphasis> in the <emphasis>NAME</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>CachedCounterPortletWindow</emphasis> in the <emphasis>NAME</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>CounterPortletWindow</emphasis> in the <emphasis>NAME</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>CharsetPortletWindow</emphasis> in the <emphasis>NAME</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>SecuredTestPortletWindow</emphasis> in the <emphasis>NAME</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>ExceptionPortletWindow</emphasis> in the <emphasis>NAME</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>MissingPortletWindow</emphasis> in the <emphasis>NAME</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>HeaderContentPortletWindow</emphasis> in the <emphasis>NAME</emphasis> column. + </para> + </listitem> + <listitem> + <para> + rows containing <emphasis>TestPortletWindow</emphasis> in the <emphasis>NAME</emphasis> column. + </para> + </listitem> + </itemizedlist> + </para> + </sect2> + <sect2> + <title>CMS</title> + <para> + In JBoss Portal 2.6 versions, the way the CMS content is displayed changed significantly. For further information, please refer to <xref linkend="contentintegration"/> and <xref linkend="cmsPortlet"/>. Currently there is no need to have more than one instance of the <emphasis>CMSPortlet</emphasis>. The portlet window displays CMS content, not by referring to that portlet instance, but by having the proper <emphasis>content-type</emphasis> defined. The following configuration is in the <filename>jboss-portal.sar/conf/data/default-object.xml</filename> file: + </para> + <para> +<screen><![CDATA[ +<window> + <window-name>CMSWindow</window-name> + <content> + <content-type>cms</content-type> + <content-uri>/default/index.html</content-uri> + </content> + <region>center</region> + <height>0</height> +</window>]]> +</screen> + </para> + <para> + The following example uses the MySQL Query Browser. Open the <emphasis role="bold">JBP_OBJECT_NODE</emphasis> table in your database schema. Look at the <emphasis role="bold">PATH</emphasis> column to identify any occurrences of CMS in your JBoss Portal deployment. Identify any row referring to <emphasis>CMSPortletWindow</emphasis>, and remember the number in <emphasis role="bold">PK</emphasis> column. The <emphasis role="bold">PK</emphasis> number is needed in the following steps: + </para> + <para> + <mediaobject> + <imageobject> + <imagedata align="center" valign="middle" fileref="images/migration/querybrowser2.png"/> + </imageobject> + </mediaobject> + </para> + <para> + Go to the <emphasis role="bold">JBP_WINDOW</emphasis> table and find a row with the same + <emphasis role="bold">PK</emphasis> value from the <emphasis role="bold">JBP_OBJECT_NODE</emphasis> table. In such a row, replace <emphasis>CMSPortletInstance</emphasis> with a path to your CMS resource. For example, by default, JBoss Portal displays <filename>/default/index.html</filename>. + </para> + <para> Go to the <emphasis role="bold">JBP_PORTAL_OBJECT_PROPS</emphasis> table and add a row containing: + <itemizedlist> + <listitem> + <para> + The <emphasis role="bold">PK</emphasis> number remembered from the <emphasis>OBJECT_KEY</emphasis> column. + </para> + </listitem> + <listitem> + <para> + <emphasis>portal.windowContentType</emphasis> in the <emphasis>NAME</emphasis> column. + </para> + </listitem> + <listitem> + <para> + <emphasis>cms</emphasis> in the <emphasis>jbp_VALUE</emphasis> column. + </para> + </listitem> + </itemizedlist> + </para> + <para> + <note> + <title>Portlet Content Type and Path to the CMS Resource</title> + <para> + You can change the portlet window content type and configure the path to the CMS resource + using the <computeroutput>Admin</computeroutput> Portlet. + </para> + </note> + </para> + </sect2> +</sect1> + <!--<sect1 id="manual_migration"> <title>Manual Upgrade</title> <para> Although the database schema remains the same in JBoss Portal 2.6, there are several differences that prevent simply deploying the latest version of JBoss Portal, when using a database created for JBoss Portal 2.4. This chapter describes updating a JBoss Portal 2.4 MySQL database for use with JBoss Portal 2.6. @@ -34,11 +531,11 @@ <para> If you are using the JBoss Portal binary, remove the <filename>$JBOSS_HOME/server/default/deploy/jboss-portal.sar/</filename> directory. If JBoss Portal was built from source, remove the <filename>$JBOSS_HOME/server/default/deploy/jboss-portal.sar</filename> file. </para> - </listitem> + </listitem> --> <!--<listitem> Remove <emphasis role="bold">$JBOSS_HOME/server/default/data</emphasis> directory. </listitem>--> - <listitem> + <!-- <listitem> <para> Update the data in the JBoss Portal database, as described in <xref linkend="upgrade_portal_database"/>. </para> @@ -193,7 +690,7 @@ </note> </para> </sect2> -</sect1> +</sect1> --> <!-- <para>This chapter addresses migration issues from version 2.2 to 2.4 of JBoss Portal.</para> <sect1 id="migrating_database">