Chapter 1. Upgrading 2.0 - 2.2
Prev |  | Next

## Chapter 1. Upgrading 2.0 - 2.2

### Roy Russo

`<roy at jboss dot org>`

### Boleslaw Dawidowicz

`<boleslaw.dawidowicz@jboss.com>`

This chapter addresses migration issues from version 2.0 to 2.2 of JBoss Portal.

## 1.1. Deployment Descriptors

From version 2.0 to 2.2, the JBoss Portal deployment descriptors have changed when defining pages, portlets, and portal instances.

### 1.1.1. Example - Assigning a Portlet on a Page

To describe the changes made to the deployment descriptors, we have made available an example that you can download here: HelloWorld Portlet . After this helloworldportlet.ear is deployed, you should be able to access the new portal page by pointing your browser to http://localhost:8080/portal/portal/default/HelloWorld .

All portal, page, and portlet instance deployment is now handled by one file: *-object.xml. You no longer need the *-portal.xml, *-pages.xml, and *-instances.xml found in JBoss Portal 2.0. For our example we make available helloworld-object.xml located under helloworldportlet.war/WEB-INF/ , and it looks like this:

                    <?xml version="1.0" encoding="UTF-8"?>
                    <deployments>
                    <deployment>
                    <if-exists>overwrite</if-exists>
                    <parent-ref>default</parent-ref>
                    <properties/>
                    <page>
                    <page-name>Hello World</page-name>
                    <properties/>
                    <window>
                    <window-name>HelloWorldPortletWindow</window-name>
                    <instance-ref>HelloWorldPortletInstance</instance-ref>
                    <region>center</region>
                    <height>0</height>
                    </window>
                    </page>
                    </deployment>
                    <deployment>
                    <if-exists>overwrite</if-exists>
                    <instance>
                    <instance-name>HelloWorldPortletInstance</instance-name>
                    <component-ref>helloworld.HelloWorldPortlet</component-ref>
                    </instance>
                    </deployment>
                    </deployments>

A deployment file can be composed of a set of <deployments>. In our example file, above, we are defining a page, placing the HelloWorldPortlet as a window on that page, and creating an instance of that portlet. You can then use the Management Portlet (bundled with JBoss Portal) to modify the instances of this portlet, reposition it, and so on...

- <if-exists> Possible values are overwrite or keep . Overwrite will destroy the existing object and create a new one based on the content of the deployment. Keep will maintain the existing object deployment or create a new one if it does not yet exist.
- <parent-ref> Indicates where the object should be hooked in to the portal tree. See the chapter on Dynamicity for the tree-concept within JBoss Portal.
- <properties> Properties definition specific to this page, commonly used to define the specific theme and layout to use. If not defined, the default portal layouts/theme combination will be used.
- <page> The start of a page definition.
- <page-name> The name of the page.
- <window> The start of a window definition.
- <window-name> The name of the window.
- <instance-ref> The instance reference used by this window. Should correspond with the <instance-name> variable.
- <height> The vertical position of this window within the region defined in the layout.
- <instance> The start of an instance definition. page.
- <instance-name> Maps to the above <instance-ref> variable.
- <component-ref> Takes the name of the application followed by the name of the portlet, as defined in the portlet.xml

### Note

For further explanation of the deployment descriptor, please view the XMLDescriptor section in the Reference Guide

## 1.2. Content Management System

From version 2.0 to 2.2, the JBoss Portal Content Management System changed from using Apache Slide API to the Java Content Repository (JCR), JSR-170 using the Apache Jackrabbit implementation.

### 1.2.1. Migrating Content

Since the underlying layer of the CMS has changed, it will be necessary for users migrating from 2.0 to move their content, so the following steps describe how to perform this operation.

JBoss Portal v2.0 had native WebDAV support, allowing a user to connect to the content repository via the Operating System, given the proper credentials. You will use this method to extract the content, zip it in an archive, and upload it to the new CMS.

- First, start up your previous installation of JBoss Portal 2.0, and connect to it using MS WebFolders. Using the Add Network Place option under My Network Places , add a new network place, giving it the path to your webdav respository. By default it is http://localhost:8080/webdav . Upon providing the proper credentials, you should see your repository structure.

- Navigate to http://localhost:8080/webdav/files and your entire content directory structure with files should be available here. You should be able now to zip these directories and upload them as an archive to the JBoss Portal 2.2 CMS via the CMSAdminPortlet.

### Warning

There are two known issues you need to know about when importing content from the old repository using this method:

- Version information will be lost.
- You must verify that pre-existing links to local resources are correct.

## 1.3. Forums Migration

### 1.3.1. Forums DB schema issues

Database schema differs slightly between portal 2.0.0 and 2.0.1 versions. Some new talbes were added for new functionality. There were few columns removed or type changed also.

From 2.0.1 RC2 version portal performs schema update try during startup/deployment. Hibernate SchemaUpdate hbm2ddl tool is able to add new tables or new columns. What it doesn't do is removing unnessesary columns or column sql-type changes.

Besides of that, it is always good to back up your data as this behaviour might depends on different RDBMS versions.

### 1.3.2. Portal 2.0.0 to 2.0.1 Forums migration

In portal 2.0.1 there are some changes in db schema related to Forums Portlet

For eg. columns such as:

- jbp_forums_forums --> jbp_last_post_id
- jbp_forums_topics --> jbp_first_post_id
- jbp_forums_topics --> jbp_last_post_id

are now not used. These are retrieved using Hibernate collections storing capabilities.

Column:

- jbp_forums_posts --> jbp_text

had wrong SQL type. It was 'varchar(255)' in 2.0.0 and it is 'text' in 2.0.1.

### 1.3.3. Nessesary steps to migrate Forums

After upgrading portal to 2.0.1, schema should be updated automaticly and all new nessesary tables/columns created. If this process fail the schema will be dropped/created. Remember to backup your data before doing migration!

After successfull update beware of the fact that you will have:

- a number of unused columns in schema
- texts of messages stored in varchar(255) column - Posts in forums couldn't be longer than 255 chars. In fact longer messages will cause portlet exception...

To deal with second issue we must change jbp_forums_posts-->jbp_text column type. It's very simple to do in MySQL RDBMS:

                   ALTER TABLE jbp_forums_posts CHANGE jbp_text jbp_text text

In Postgres it will be:

                   ALTER TABLE portal.jbp_forums_posts ALTER jbp_text TYPE text;

This will change column type.

Check in your RDBMS docs if such `ALTER TABLE` SQL statement works. If not you should probably recreate jbp_forums_posts table with proper SELECT/INSERT statement.

Prev | Up | Next
Acknowledgements | Home | Chapter 2. JSR168 portlets