JBoss Portal 2.6.4

To start JBoss EAP or JBoss AS and deploy JBoss Portal:

WARN  [JDBCExceptionReporter] SQL Error: -22, SQLState: S0002
ERROR [JDBCExceptionReporter] Table not found in statement ...
WARN  [JDBCExceptionReporter] SQL Error: 1146, SQLState: 42S02
ERROR [JDBCExceptionReporter] Table 'jbossportal.jbp_cms_repositoryentry' doesn't exist
WARN  [JDBCExceptionReporter] SQL Error: 1146, SQLState: 42S02
ERROR [JDBCExceptionReporter] Table 'jbossportal.jbp_cms_version_refs' doesn't exist

The JBoss Portal source files can be obtained from the JBoss Portal Downloads page. The source files download uses a JBoss Portal Source Code naming convention. As well, the sources can be obtained from SVN:

Several modules have been extracted from the JBoss Portal SVN repository. These modules have a different lifecycle and a different version scheme. The following is a list of modules used in JBoss Portal 2.6.4, and the locations of their source code:

After checking out the source from SVN, or after extracting the JBoss Portal Source Code zip file, a directory structure similar to the following will be created:

If the source files were obtained from SVN, change into the trunk/src/ directory to see the directories from the above image. As well, there will be an empty thirdparty directory. This directory will contain files after building the JBoss Portal source code (Section 2.3.3, “Building and Deploying from the Sources”). For more information about the JBoss Portal SVN repository, and accessing different versions of the JBoss Portal codebase, please visit the JBoss Portal SVN Repo page on the JBoss Wiki.

During the first build, third-party libraries will be obtained from an online repository, so you must be connected to the Internet, and if you are behind a proxy server, you need to define your proxy server address and proxy server port number. If you are running Linux, add the following line to the $JBOSS_HOME/bin/run.sh file:

JAVA_OPTS=-Dhttp.proxyHost=<proxy-hostname> -Dhttp.proxyPort=<proxy-port>

Replace proxy-hostname with the proxy server's hostname, and proxy-port with the correct proxy server port number. If you are running Microsoft Windows, add the following line to the $JBOSS_HOME/bin/run.bat file:

set JAVA_OPTS=-Dhttp.proxyHost=<proxy-hostname> -Dhttp.proxyPort=<proxy-port>

Replace proxy-hostname with the proxy server's hostname, and proxy-port with the correct proxy server port number.

To build and deploy JBoss Portal from the sources, change into the JBOSS_PORTAL_SOURCE_DIRECTORY/build/ directory, where JBOSS_PORTAL_SOURCE_DIRECTORY is the directory where the JBoss Portal source code was downloaded to. Then, Microsoft Windows users need to run the build.bat deploy command, and Linux users need to run the ./build.sh deploy command.

At the end of the build process, the jboss-portal.sar file is copied into the $JBOSS_HOME/server/default/deploy/ directory:

To build the clustered version on Linux Operating Systems:

To build the clustered version on Microsoft Windows, repeat the previous steps, replacing ./build.sh with build.bat.

A database is required for JBoss Portal to run. JBoss EAP and JBoss AS include an embedded Hypersonic SQL database that JBoss Portal can use; however, this is only recommended for developer use. The following databases are recommended for production use, and have had test suites run against them: MySQL 4, MySQL 5, Microsoft SQL Server, PostgreSQL 8, Oracle 9, and Oracle 10. JBoss Portal can use any database that is supported by Hibernate.

To configure a database to use with JBoss Portal:

The JBoss Portal binary download that was extracted in Section 2.2.1.1, “Getting the Binary”, contains pre-configured Datasource descriptors for the more popular databases. Datasource descriptors are provided for the MySQL 4, MySQL 5, PostgreSQL, Microsoft SQL Server, and Oracle databases, and can be found in the setup subdirectory where the JBoss Portal binary was extracted to:

Copy the Datasource descriptor that matches your database into the $JBOSS_HOME/server/configuration/deploy/ directory, where configuration is either all, default, minimal, or production. For example, if you are using the production configuration, copy the Datasource descriptor into the $JBOSS_HOME/server/production/deploy/ directory. The production configuration only exists on JBoss EAP installations, and not JBoss AS.

After the Datasource descriptor has been copied into the deploy directory, make sure the username, password, connection-url, and driver-class are correct for your chosen database. Datasource descriptor files can be deployed to test before being used in production. The following is an example Datasource descriptor for the PostgreSQL database:

<?xml version="1.0" encoding="UTF-8"?>
<datasources>
  <local-tx-datasource>
    <jndi-name>PortalDS</jndi-name>
    <connection-url>jdbc:postgresql:jbossportal</connection-url>
    <driver-class>org.postgresql.Driver</driver-class>
    <user-name>portal</user-name>
    <password>portalpassword</password>
  </local-tx-datasource>
</datasources>
					  

For further details about Datasource descriptors, please refer to the JBoss JDBC Datasource wiki page.

All hibernate.cfg.xml files in all JBoss Portal modules you intend to use need to be modified. The hibernate.cfg.xml files are found in the jboss-portal.sar/module/conf/hibernate/directory/ directory, where module is the module name, and directory is a directory that, depending on the module, may or may not exist.

To modify these files to force the DB dialect, un-comment the following line from each hibernate.cfg.xml file in each JBoss Portal module you intend to use, so that it looks like the following:

<!-- Force the dialect instead of using autodetection -->
<property name="dialect">org.hibernate.dialect.PostgreSQLDialect</property>

Note: this example is for a PostgreSQL database. If you use another database, you will need to modify org.hibernate.dialect.PostgreSQLDialect to reflect the correct database. For a list of supported dialects, refer to the dialects list on the Hibernate website.

To modify the DB dialect setting for the JBoss Portal CMS component:

Note: this example is for a PostgreSQL database. If you use another database, you will need to modify org.hibernate.dialect.PostgreSQLDialect to reflect the correct database. For a list of supported dialects, refer to the dialects list on the Hibernate website.

Themes in JBoss Portal 2.6 have changed since the Portal pages now contain additional areas, such as the Login, Admin, and Dashboard links, on the top right-hand corner:

If you use a default theme that exists in JBoss Portal 2.6, 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, please refer to those bundled with JBoss Portal as an example.

All procedures described in the following sections can performed using the AdminPortlet. Treat the directions as guidelines if you need to automate the migration of a large JBoss Portal deployment.

Database schema has not changed between the JBoss Portal 2.4 and 2.6 releases, but certain content that is kept in the databases has changed. Data can be updated manually by using the correct tools for your RDBMS. For example, if you are using a MySQL database, you can use the MySQL Query Browser.

The following instructions refer to a standard JBoss Portal 2.4 deployment. If you named core portlets, portlet instances, or portlet windows differently, you will need to make the appropriate modifications. The following is an example of using the MySQL Query Browser:

Names of certain core bundled portlets have changed. Destroy the following instances and use the AdminPortlet to recreate them, or, edit the JBP_INSTANCES table as follows:

The NavigationPortlet from JBoss Portal 2.4 has been removed, and its functionality is now replaced by PageCustomizerInterceptor. All references to the NavigationPortlet should be removed from all portal pages. Remove NavigationPortletInstance using the AdminPortlet, or edit the database as follows:

In JBoss Portal 2.6 versions, the way the CMS content is displayed changed significantly. For further information, please refer to Chapter 9, Content Integration and Chapter 21, CMS Portlet. Currently there is no need to have more than one instance of the CMSPortlet. The portlet window displays CMS content, not by referring to that portlet instance, but by having the proper content-type defined. The following configuration is in the jboss-portal.sar/conf/data/default-object.xml file:

<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>

The following example uses the MySQL Query Browser. Open the JBP_OBJECT_NODE table in your database schema. Look at the PATH column to identify any occurrences of CMS in your JBoss Portal deployment. Identify any row referring to CMSPortletWindow, and remember the number in PK column. The PK number is needed in the following steps:

Go to the JBP_WINDOW table and find a row with the same PK value from the JBP_OBJECT_NODE table. In such a row, replace CMSPortletInstance with a path to your CMS resource. For example, by default, JBoss Portal displays /default/index.html.

Go to the JBP_PORTAL_OBJECT_PROPS table and add a row containing:

A portal can be seen as pages with different areas, and inside areas, different windows, and each window having one portlet:

A portlet can have different view modes. Three modes are defined by the JSR-168 specification, but a portal can extend those modes. The three modes are:

Window states are an indicator of how much page real-estate a portlet should consume on any given page. The three states defined by the JSR-168 specification are:

This overview of the JSR-168 Portlet Specification is a work in progress. Check back for more in-depth analsis of the specification. The sections following here after contain real-world cases for how to leverage the specification.