JBoss® Portal 2.6.6

JBoss Portal is 100% Pure Java™, and therefore it is interoperable with most operating systems capable of running a Java Virtual Machine (JVM™), including Linux®, Windows®, UNIX® operating systems, and Mac OS X.

JBoss Portal 2.6.6 is tested with JBoss Application Server (AS) 4.2.3, and Boss Enterprise Application Platform (EAP) 4.3. It is highly recommended that customers who have access to the JBoss Customer Support Portal (CSP) use JBoss EAP 4.3 (It is mandatory to get access to professional support). Customers who do not have access to the JBoss CSP should use JBoss AS.

JBoss Portal is database-agnostic. The following list outlines known-to-be-working database vendor and version combinations:

The source building mechanism works on Linux, Windows, Mac OS X, and UNIX operating systems.

This is the easiest and fastest way to get JBoss Portal installed and running. The JBoss Portal and JBoss AS bundle contains JBoss AS, JBoss Portal, and the embedded Hypersonic SQL database. To install the JBoss Portal and JBoss AS bundle:

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 binary package typically consists of the jboss-portal.sar/ directory, documentation such as the JBoss Portal User Guide and the JBoss Portal Reference Guide, and a set of pre-configured Datasource descriptors that allow JBoss Portal to communicate with an external database. This installation method is recommended for users who already have JBoss EAP or JBoss AS installed, or those who need to install JBoss Portal in a clustered environment.

2.2.1. Setting up your Environment

2.2.1.1. Getting the Binary

The binary download is available from the JBoss Portal Downloads page. Look for the JBoss Portal Binary package. Once the binary ZIP file has been downloaded and extracted, the folder hierarchy will look similar to the following:

Files contained in this download are used in later sections. Download and extract the JBoss Portal binary ZIP file before proceeding.

2.2.1.2. JBoss EAP and JBoss AS Setup

Before deploying JBoss Portal, make sure you have JBoss EAP or JBoss AS installed. Customers who have access to the JBoss Customer Support Portal (CSP) are advised to download and install JBoss EAP 4.3. Customers who do not have access to the JBoss CSP are advised to use JBoss AS. For JBoss AS installation instructions, please refer to the JBoss AS Installation Guide.

Use the JBoss EAP and JBoss AS ZIP file

Only use the JBoss EAP and JBoss AS ZIP file versions. DO NOT ATTEMPT to deploy JBoss Portal on the installer version of JBoss EAP or JBoss AS.

2.2.1.3. Operating System Environment Settings

For JBoss EAP, JBoss AS, and build targets to work, you must configure a JBOSS_HOME environment variable. This environment variable must point to the root directory of the JBoss EAP or JBoss AS installation directory, which is the directory where the JBoss EAP or JBoss AS files were extracted to.

On Windows, this is accomplished by going to Start > Settings > Control Panel > System > Advanced > Environment Variables. Under the System Variables section, click New. Set the JBOSS_HOME environment variable to the location of your JBoss EAP or JBoss AS installation directory:

To configure the JBOSS_HOME environment variable on Linux:

1. Add the following line to the ~/.bashrc file. Note: this must be configured while logged in as the user who runs JBoss EAP or JBoss AS:

   export JBOSS_HOME=/path/to/jboss/installation/
   

2. Run the following command to enable the JBOSS_HOME environment variable:

   source ~/.bashrc
   

JBoss EAP JBOSS_HOME Environment Variable

If you are running JBoss EAP, configure the JBOSS_HOME environment variable to point to the /path/to/jboss-eap-version/jboss-as/ directory.

2.2.1.4. Database Setup

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 and 5, Microsoft® SQL Server®, PostgreSQL 8, and Oracle® Database 9 and 10. JBoss Portal can use any database that is supported by Hibernate.

To configure a database to use with JBoss Portal:

1. Create a new database: this guide assumes that the new database is called jbossportal.

2. Grant access rights for a user to the jbossportal database: JBoss Portal needs to create tables and modify table data. Grant access rights to a desired user to the jbossportal database. Configure the same username and password in the Datasource descriptor.

3. Deploy an RDBMS JDBC™ connector: an RDBMS JDBC connector is required for JBoss Portal to communicate with a database. Copy the connector into the $JBOSS_HOME/server/default/lib/ directory. For example, an RDBMS JDBC connector for MySQL can be download from http://www.mysql.com/products/connector/j/. For the correct RDMBS JDBC connector, please refer to the database documentation.

2.2.1.5. Datasource Descriptors

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 and 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. The production configuration only exists on JBoss EAP, and not JBoss AS. For example, if you are using the all configuration, copy the Datasource descriptor into the $JBOSS_HOME/server/all/deploy/ directory.

After the Datasource descriptor has been copied into the deploy directory, make sure the user-name, 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 a 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.

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

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

It is common for web services to run on port 80. By default, JBoss EAP and JBoss AS use port 8080. If you can not use port forwarding, it is recommended to change the port JBoss EAP or JBoss AS listens on. To change the default port, open the $JBOSS_HOME/server/default/deploy/jboss-web.deployer/server.xml file, and edit the Connector port value for the jboss.web service; however, this configuration only applies to Apache Tomcat:

<Service name="jboss.web">
<Connector port="8088" address="${jboss.bind.address}"

This example changes the default port to port 8088. The JBoss EAP or JBoss AS server must be restarted before the new port settings take affect.

The default SSL port is 8843. To enable HTTPS support, refer to the JBoss AS Guide. For further information, refer to the Apache Tomcat SSL configuration how-to.

Please refer to Section 14.3.1, “Considerations to use WSRP when running Portal on a non-default port or hostname” to update the WSRP service after having changed the port.

By default, the main JBoss Portal page is accessible by navigating to http://localhost:8080/portal/index.html. This can be changed to a different path, for example, http://localhost:8080/index.html. The context path can be changed when using the deployed jboss-portal.sar/, or before building from source. To change the context path when using the JBoss Portal binary package:

To change the context path when building from source:

<?xml version="1.0"?>
<jboss-web>
   <context-root>/tomcat-root</context-root>
</jboss-web>

This sections describes how to override the Database (DB) dialect settings. Under most circumstances, the auto-detect feature works. If the Hibernate dialect is not working correctly, override the default behavior by following the instructions in this section.

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

If you have a standard setup and a mail server installed, the email service should work without any extra configuration. Most Linux distributions have a mail server installed by default. The email service, for example, can be used to verify a user's email address when a user subscribes, or for CMS workflow notifications.

The email service is configured using the $JBOSS_HOME/server/default/deploy/jboss-portal.sar/META-INF/jboss-service.xml file. The following is an example of the section which is used to configure the email service:

<mbean
code="org.jboss.portal.core.impl.mail.MailModuleImpl"
name="portal:service=Module,type=Mail"
xmbean-dd=""
xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean">
<xmbean/>
<depends>jboss:service=Mail</depends>
<depends>portal:service=Module,type=IdentityServiceController</depends>
<attribute name="QueueCapacity">-1</attribute>
<attribute name="Gateway">localhost</attribute>
<attribute name="SmtpUser"></attribute>
<attribute name="SmtpPassword"></attribute>
<attribute name="JavaMailDebugEnabled">false</attribute>
<attribute name="SMTPConnectionTimeout">100000</attribute>
<attribute name="SMTPTimeout">10000</attribute>
<attribute name="JNDIName">java:portal/MailModule</attribute>
</mbean>

A different SMTP server (other than localhost) can be configured, along with a SMTP username and an SMTP password. The following is an example configuration that uses the Gmail SMTP server:

<mbean
code="org.jboss.portal.core.impl.mail.MailModuleImpl"
name="portal:service=Module,type=Mail"
xmbean-dd=""
xmbean-code="org.jboss.portal.jems.as.system.JBossServiceModelMBean">
<xmbean/>
<depends>jboss:service=Mail</depends>
<depends>portal:service=Module,type=IdentityServiceController</depends>
<attribute name="QueueCapacity">-1</attribute>
<attribute name="Gateway">smtp.gmail.com</attribute>
<attribute name="SmtpUser">username@gmail.com</attribute>
<attribute name="SmtpPassword">myPassword</attribute>
<attribute name="JavaMailDebugEnabled">false</attribute>
<attribute name="SMTPConnectionTimeout">100000</attribute>
<attribute name="SMTPTimeout">10000</attribute>
<attribute name="JNDIName">java:portal/MailModule</attribute>
</mbean>

Using this example, replace username@gmail.com and myPassword with your correct Gmail username and password.

There are a couple of scenarios where you need your proxy to be correctly defined at the JVM™ level so that you can access documents from Internet. It could be to get the thirdparty libraries if you decided to build JBoss Portal from the sources, to access RSS feeds or weather information in the samples portlet we provide or for your own needs.

To configure the proxy settings, you need to know the proxy host and the port to use. Then, add them when starting Java.

Usually setting up JAVA_OPTS environment variable to -Dhttp.proxyHost=YOUR_PROXY_HOST -Dhttp.proxyPort=YOUR_PROXY_PORT is enough.

JBoss Portal uses the JBoss Microkernel for the service infrastructure. The JBoss Microkernel provides injection of services into other services, otherwise known as wiring. Due to the Microkernel being JMX™ based, it is only possible to inject dynamic proxies that talk to the MBeanServer. The overhead at runtime is minimal since the Microkernel implementation is highly optimized; however, when it is used with Java 5, a noticeable bottleneck occurs due to the fact that the implementation of the JMX API classes, javax.management.*, provided by the Java Platform, perform synchronization. This does not occur under JDK™ 1.4, since those classes are implemented by JBoss MX.

JBoss Portal services use a special kind of Model MBean called JBossServiceModelMBean, which allows the un-wrapping of injected dynamic proxies, and replaces them with Plain Old Java Object (POJO) services. This removes the bottleneck when using Java 5, and also provides a performance boost on JDK 1.4. By default this feature is enabled, but it is possible to disable. To do this on Linux operating systems, change into the $JBOSS_HOME/bin/ directory and run the following command:

sh run.sh -Dportal.kernel.no_proxies=false

On Windows, run the following command:

run.bat -Dportal.kernel.no_proxies=false

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.

Users, roles, and pages created in JBoss Portal 2.4 should be accessible in JBoss Portal 2.6 deployments.

The upgrade procedure can be straightforward:

4.1.1. Themes

In JBoss Portal 2.6, portal pages contain additional areas, such as the Login, Admin, and Dashboard links, on the top right-hand corner of portal pages:

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 the bundled JBoss Portal 2.6 themes as an example.

4.1.2. Updating the Database

The following tables contain all references to portlets:

• JBP_INSTANCE

• JBP_WINDOW

• JBP_OBJECT_NODE

All procedures described in the following sections can performed using the JBoss Portal 2.4 Admin 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, you can use the MySQL Query Browser.

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. This can be done using the JBoss Portal 2.4 Admin portlet:

• HeaderContentPortlet

• URLPortlet

• TestPortlet

• PortletA

• PortletB

• SecuredTestPortlet

• CharsetPortlet

• CounterPortlet

• CachedCounterPortlet

• ExceptionPortlet

• PortletSessionPortlet

• EncodingPortlet

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

Requested Resource Error

When running JBoss Portal 2.6 with a database created by JBoss Portal 2.4, a non-existing portlet will try to be displayed, resulting in a 404, The requested resource() is not available error.