JBoss Portal 2.2

JBoss Portal is 100% pure Java and therefore interoperable with most operating systems capable of running a Java Virtual Machine (JVM); including Windows, UNIX, and Linux.

JBoss Portal only works with JBoss Application Server.

JBoss Portal is Database-Agnostic.

The following list, outlines known-to-be-working database vendor and version combinations:

The source building mechanism works on Windows, Linux, MacOS X and any 'Unix like' operating system.

It is common to have a server running on the port 80 instead of the default port 8080.

To change it, you need to edit the file $JBOSS_HOME/server/default/deploy/jbossweb-tomcat50.sar/server.xml and change the port value of the HTTP Connector. You can also change the value of the SSL port, by default it is set to 8443. Remember to uncomment the following when you have configured it:

            
      <!-- SSL/TLS Connector configuration using the admin devl guide keystore
      <Connector port="8443" address="${jboss.bind.address}"
           maxThreads="100" strategy="ms" maxHttpHeaderSize="8192"
           emptySessionPath="true"
           scheme="https" secure="true" clientAuth="false"
           keystoreFile="${jboss.server.home.dir}/conf/chap8.keystore"
           keystorePass="rmi+ssl" sslProtocol = "TLS" />
      -->
            
         

Now you can restart JBoss and use the new port that you defined. On systems like Linux, you need privileges to be able to run a server on a port lower than 1000, starting JBoss on the port 80 as a regular user will not work, for testing you can log as root but is not recommended if the server is public as it could be a security breach in your system.

By default, the "main" page of JBoss portal will be accessible at http://localhost:8080/portal/index.html . You may want to change that either to a different name or to http://localhost:8080/index.html .

Now you can rebuild JBoss portal and redeploy it for the context path changes to take effect.

If you encounter that the Hibernate dialect is not working properly and would like to override the default behaviour, follow the instructions contained in this section:

               <?xml version='1.0' encoding='utf-8'?>
               <!DOCTYPE hibernate-configuration PUBLIC
               "-//Hibernate/Hibernate Configuration DTD//EN"
               "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">
               <hibernate-configuration>
               <session-factory>
               <property name="connection.datasource">java:PortalDS</property>
               <property name="show_sql">false</property>
               <property name="cache.provider_class">org.hibernate.cache.EhCacheProvider</property>
               <property name="cache.use_query_cache">true</property>
               
               <!-- Force the dialect instead of using autodetection -->
               <!--
               <property name="dialect">org.hibernate.dialect.PostgreSQLDialect</property>
               -->
               
               <!-- Mapping files -->
               <mapping resource="conf/hibernate/user/domain.hbm.xml"/>
               </session-factory>
               </hibernate-configuration>               
               

By default, the JBoss Portal CMS stores all node properties, references, and binary content in the database, using the portal datasource. The location of some of these items is configurable.

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

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

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.

The concept of dynamicity is that all portal objects are able to dynamically be modified at runtime, eliminating the need to struggle with large xml files, or restarting the application server for changes to take effect. In the scope of dynamicity, Portal objects are defined and can be altered as follows:

Dynamicity and our new consolidated deployment descriptor work hand-in-hand. Portal objects are all considered branches to the root portal context, and within our new deployment descriptor all branches (and leaves) can be specified.

Dynamicity allows an administrator to manage the entire portal deployment from within a portlet. Some of the many tasks available to administrators are:

Administrators may manage the portal, pages, subpages, and windows at any time, by clicking on the "Portal" tab at the top of the Management Portlet. The components currently deployed in the portal container are displayed in a tree-structure for ease-of-navigation and modification.

The CMSAdmin Portlet allows control over the content management system.

Viewing the CMSAdmin Portlet is accomplished by logging in as an admin (admin/admin) and navigating to the CMSManager page.

You should then be presented with a portlet that is similar to this:

This section describes common actions a user can perform from within the AdminCMS Portlet.

7.2.2. Viewing File Properties

Clicking on the icon or the "DisplayName" of a file brings up the File Properties page.

The File Properties window displays all the possible actions available to perform on a file.

Version and Locale Information are also contained on this screen. Note that any version labeled with the is the current "live" version shown to users.

7.2.3. Copying Files/Directories

Clicking on the icon displays the copy file/directory dialog window.

The copy resource window allows a user to copy files to any folder on the system, as well as copy whole directory trees to any directory on the system. A user can select which destination directory to copy the resource to, by using the directory browser. Clicking the icon expands the directory tree. Clicking on the name of the directory within the tree, sets it as the destination directory for the copied resource.

7.2.4. Moving Files/Directories

Clicking on the icon displays the move file/directory dialog window.

The move resource window allows a user to move files to any folder on the system, as well as move whole directory trees to any directory on the system. A user can select which destination directory to move the resource to, by using the directory browser. Clicking the icon expands the directory tree. Clicking on the name of the directory within the tree, sets it as the destination directory for the moved resource.

7.2.5. Deleting Files/Directories

Clicking on the icon displays the delete file/directory confirmation window.

The delete resource confirmation window allows a user to delete a file, or a directory on the system. Note that deleting a directory, will delete the entire tree, so all directories under the deleted one, will also be deleted.

Warning

Currently, there is no way to retrieve deleted files/directories! Deleting a file or directory is permanent!

7.2.6. Creating Directories

Clicking on the icon displays the create directory dialog window.

The create directory resource window allows a user to create a directory under chosen path. On this window, a user can specify a name for the new empty directory and assign it a description.

7.2.7. Creating Text/HTML Files

Clicking on the icon displays the create file dialog window with the embedded WYSIWYG editor and directory browser.

The create file window allows a user to create a text or HTML file using the embedded WYSIWYG HTML editor. The editor is a fully-functional HTML editor with a myriad of HTML functions. It also includes a preview button and a source view

button.

An in-depth walk-through of the editor is beyond the scope of this document. However, the editor does contain help pages within it, that can be accessed by clicking the icon.

Note

It is important to note here that when creating links to images or other resources within the system, as user must use the relative file path to that resource. ie: images/hello.gif. Keep in mind at all times that the document base is http://localhost/portal/ by default!

Additionally, a user can set a title for the file that will be used in the portlet title bar, and a language for the file, used in serving localized content.

7.2.8. Uploading Files

Clicking on the icon displays the upload file dialog window.

The upload file window allows a user to upload files to any directory on the system. The upload process will work on files up to 1GB and of all types. A user can select which destination directory to upload the resource to, by using the directory browser. Clicking the icon expands the directory tree. Clicking on the name of the directory within the tree, sets it as the destination directory for the uploaded resource. Additionally, a user can set a title for the file that will be used in the portlet title bar, and a language for the file, used in serving localized content.

7.2.9. Uploading Archives

Clicking on the icon displays the upload archive dialog window.

The upload archive window allows a user to upload archives to any directory on the system. The system will then explode the archive, create versions, and place all the files in the repository. A user can select which destination directory to upload the resource to, by using the directory browser. Clicking the icon expands the directory tree. Clicking on the name of the directory within the tree, sets it as the destination directory for the uploaded resource. Additionally, a user can set a language for the archive files, used in serving localized content.

7.2.10. Editing Text/HTML Files

Clicking on the icon displays the edit file dialog window with the embedded WYSIWYG editor and directory browser.

The edit file window allows a user to edit a text or HTML file using the embedded WYSIWYG HTML editor. The editor is a fully-functional HTML editor with a myriad of HTML functions. It also includes a preview button and a source view button.

A user may specify at this point if he would like to make the new edit "live", or available in production. Additionally, a user can set a title for the file that will be used in the portlet title bar.

The forums portlet is a port of the phpBB forums as a Java portlet. It is packaged independently of the core, so you can easily use it or not depending on your own needs.

Above is the main window displayed by default to any user. It lists all the forums classified by categories. It is possible to see how many topics and posts where written for each forum and the date and user of the last post. All those categories and forums can be configured if the user has the correct privileges. The next image show the main administration interface available to users with the correct credentials.

User features:

Admin features:

If you are deploying from binary , just move portal-forums.ear in to your deploy directory.

If you are deploying from source :

To install forums, you need to go to the directory forums and type sh build.sh deploy it will create a file portal-forums.ear and copy it to $JBOSS_HOME/server/default/deploy . If JBoss is already running you have nothing to do but to go to a page where the forums should be displayed (see your configuration).

To have the mail notification working, make sure that you correctly configure the mail service with an existing SMTP account in the file: $PORTAL_HOME/core/src/resources/portal-server-war/WEB-INF/jboss-service.xml

In $FORUMS_HOME/src/resources/portal-forums-war/WEB-INF/portlet.xml you can configure the following options:

You can restrict access to the forums for certain roles, to do so edit the file $FORUMS_HOME/src/resources/portal-forums-war/WEB-INF/jboss-portlet.xml . You should see the existing part:

            <scheme>
            <domain></domain>
            <item>
            <path>/</path>
            <permission>
            <permission-name>Add</permission-name>
            <role-name>Users</role-name>
            </permission>
            <permission>
            <permission-name>Admin</permission-name>
            <role-name>Admins</role-name>
            </permission>
            <!-- For non logged users -->
            <permission>
            <permission-name>Read</permission-name>
            <role-name></role-name>
            </permission>
            </item>
            </scheme>
         

This means that a user with role Users has the permission to add posts in forums, a user with role Admins has the permissions to Admin anything, while an anonymous user (not logged on), can only read.

If you want users to only view a category named "myCategory" to a certain role "myRole", here is an item that you can add:

            <item>
            <path>/myCategory</path>
            <permission>
            <permission-name>ReadCategory</permission-name>
            <role-name>myRole</role-name>
            </permission>
            </item>
         

New in version 2.2, a role based access control model was introduced into the portal. As before, all portal resources are not secured by default. However, they can be protected via security constraints that tie a role and allowed actions to the resource. Portal resources are portlets, instances of those portlets, portlet windows, portal pages, and portals. As long as there is no security constraint defined for a resource, full access is granted to every user. Once a constraint is defined, only the allowed actions from that constraint are allowed for the roles defined in the constraint. All other access is denied. Access is checked from the top down, so that if a user has no access privileges to a portal, none of the pages are accessible either, and so on.

There are two ways to define security constraints for portal resources. Constraints can be defined in the relevant deployment desciptor, or via a management UI that is provided to admins, once the portal is up and running. To define a constraint that is active immediately after the portal is deployed, once can add a security constraint tag in the relevant descriptor.

Here is an example of a constraint to secure access to a page and only allow members of the 'Admin' role to 'view' the page (taken from a *-object.xml descriptor):

                
           <deployment>
              <if-exists>keep</if-exists>
              <parent-ref>default</parent-ref>
              <page>
                 <page-name>management</page-name>
                 <window>
                    <window-name>NavigationPortletWindow</window-name>
                    <!-- more window defs here -->
                 </window>
                 <security-constraint>
                    <policy-permission>
                       <role-name>Admin</role-name>
                       <action-name>view</action-name>
                    </policy-permission>
                 </security-constraint>
              </page>
           </deployment>
        

To complete the example, here is a snipped from a jboss-portlet.xml descriptor constraining access to the PolicyConfiguratorPortlet to the Admin role, allowing only to view the portlet.

                
            <portlet>
               <portlet-name>PolicyConfiguratorPortlet</portlet-name>
               <security-constraint>
                  <policy-permission>
                     <role-name>Admin</role-name>
                     <action-name>view</action-name>
                  </policy-permission>
               </security-constraint>
            </portlet>
        

To achieve the same results after the portal was deployed, one can login with an Admin role, and navigate to the management tab. There navigate to the desired portal resource in the tree, and click the security menu image. Pick from the offered Roles and actions and save your choice. The changes will immediately be active. Note that you can provide more then one security constraint per portal resource. This allows you to provide different roles with different access privileges for the same resource.

In order to not have to limit access to each instance or window of a particular portlet, the portal offers the possibility to secure the portlet itself. All children (instances and/or windows) will then automatically be secured as well. To secure a portlet add a security constraint to the jboss-portlet.xml entry for the portlet in question, and provide the desired role and action information. Of course, this function can be delayed until the portlet is deployed. The portlet can also be secured via the management UI.

To allow to secure all portlet windows that point to the same portlet instance with one constraint, the portal allows to define a constraint for a portlet instance. The constraint can be provided via the instance definition in the *-object.xml descriptor, or after the portlet is deployed via the management UI. The result is the same: all portlet windows of this instance will be protected.

To secure an individual portlet window, the *-object.xml descriptor allows to provide a security constraint for any individual window.

Analogous to the previous portal resources, pages can be secured via a security constraint as well.

If an entire portal needs to be secured, one security constraint placed for the portal will take care of that. All pages, and portlet windows will be secured automatically as well.

JBoss Portal leverages various clustered services that are found in JBoss Application Server. This section briefly details how each is leveraged:

If you have obtained the JBoss Portal source files, you can build JBoss Portal to work on a cluster in a simple process:

If you have the binary version of JBoss Portal, you will need to edit several files manually that would normally be editted for you by the build. The list below details the files and code blocks that need to be modified in each:

After modifying the above files, you can deploy the jboss-portal.sar and the appropriate datasource descriptor to JBOSS_HOME/server/all/deploy/*

Installation / Configuration

CMS

Miscellaneous

I am seeing "ERROR [JDBCExceptionReporter] Table not found in statement" in the logfile on first boot. What is this?

Ignore this error. It is used by the portal to create the initial database tables. On second boot, you should not see them at all.

I want to do a clean install/upgrade over my existing one. What are the steps?

Is my database vendor/version combination supported?

See Section 1.4, “Database”

How do I force the Hibernate Dialect used for my database?

See Section 3.3, “Forcing the DB dialect”

How do I change the CMS repository configuration?

There are 3 supported modes: 100% DB (default), 100% Filsystem, and Mixed (Blobs on the Filesystem and metadata in the DB). You can see configuration options here: Section 3.4, “Configuring the Content Store Location”

On reboot, the CMS is complaining about a locked repository.

This occurs when JBoss AS is improperly shutdown or the CMS Service errors on startup. To remove the lock, shutdown JBoss, and then remove the file under JBOSS_HOME/server/default/data/portal/cms/conf/.lock.

I created a file in the CMSAdmin. How do I view it?

Using the default configuration, the path to the file in the browser would be: http://localhost:8080/portal/content/path/to/file.ext. Note that all requests for cms content must be prepended with /content and then followed by the path/to/the/file.gif as it is in your directory structure.

Is there a sample portlet I can look at to learn about portlet development and JBoss Portal deployments?

Sample HelloWorld Portlets can be found at PortletSwap.com .