Red Hat JBoss Portal 5.1 Reference Guide

Transcription

1 Red Hat JBoss Portal 5.1 Reference Guide For use with Red Hat JBoss Portal Edition Red Hat Documentation Group

2 Red Hat JBoss Portal 5.1 Reference Guide For use with Red Hat JBoss Portal Edition Red Hat Documentation Group

3 Legal Notice Copyright 2013 Red Hat, Inc. T his document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed. Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law. Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries. Linux is the registered trademark of Linus Torvalds in the United States and other countries. Java is a registered trademark of Oracle and/or its affiliates. XFS is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries. MySQL is a registered trademark of MySQL AB in the United States, the European Union and other countries. Node.js is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project. T he OpenStack Word Mark and OpenStack Logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community. All other trademarks are the property of their respective owners. Abstract T his Reference Guide is a high-level usage document. It deals with more advanced topics than the Installation and User Guides, adding new content or taking concepts discussed in the earlier documents further. It aims to provide supporting documentation for advanced users of the Red Hat JBoss Portal product. Its primary focus is on advanced use of the product and it assumes an intermediate or advanced knowledge of the technology and terms.

4 Table of Contents Table of Contents. Preface Document Conventions T ypographic Conventions Pull-quote Conventions Notes and Warnings 9 2. Getting Help and Giving Feedback Do You Need Help? Give us Feedback 10. Chapter Introduction Related Links 12. Part..... I.. Portal Development Chapter Skinning the.... Portal Overview Skin Components Skin Selection Skin Selection T hrough the User Interface Setting the Default Skin within the Configuration Files Skins in Page Markups The Skin Service Skin configuration Resource Request Filter The Default Skin Creating New Skins Creating a New Portal Skin Portal Skin Configuration Portal Skin Preview Icon Creating a New Window Style Window Style Configuration Window Style CSS How to Set the Default Window Style How to Create New Portlet Skins Change Portlet Icons Create New Portlet Specification CSS Classes Tips and Tricks Easier CSS Debugging Some CSS T echniques Border Pattern Left Margin Left Pattern 27. Chapter Portal Life-cycle Overview Application Server start and stop T he Command Servlet 29. Chapter Default Portal Configuration Overview Configuration 32. Chapter Portal Default Permission Configuration Overview 33 1

5 Red Hat JBoss Portal 5.1 Reference Guide 5.2. Overwrite Portal Default Permissions 34. Chapter Portal Navigation Configuration Overview Portal Navigation Group Navigation User Navigation 46. Chapter Internationalization Configuration Overview Locales Configuration ResourceBundleService Navigation Resource Bundles Portlets Standard Portlet Resource Keys 50. Chapter Localization Configuration Pluggable Locale Policy LocalePolicy API Default LocalePolicy Custom LocalePolicy LocalePolicy Configuration Keeping non-bridged resources in sync with current Locale 54. Chapter Right To... Left.....(RTL) Framework Groovy templates Stylesheet Images Client Side JavaScript 59. Chapter XML..... Resources Bundles Overview XML format Portal Support 61. Chapter JavaScript Inter..... Application Communication Overview Library Syntax Example of Javascript events usage 64. Part..... II... Portlet development Chapter Portlet Primer JSR-168 and JSR-286 overview Portal Pages Rendering Modes Window States T utorials Deploying your first Portlet Compiling Package Structure Portlet Class Application Descriptors JavaServer Pages Portlet Example Package Structure Portlet Class 72 2

6 Table of Contents JSP files and the Portlet Tag Library JSF example using the JBoss Portlet Bridge Chapter Building JSF..... Portlets JBoss Portlet Bridge Overview Getting started with JBoss Portlet Bridge What's New in 2.0? Eventing Portlet Served Resources Public Render Parameters Bridge Frameworks and Extensions Seam Bridgelets RichFaces Bridgelets Before You Start Bridge Configuration Core Setup and Configuration portlet.xml faces-config.xml Facelets Configuration web.xml JSP Only Configuration web.xml RichFaces Setup and Configuration Options web.xml Configuration needed for Richfaces to work with WSRP and PortletBridge Seam Setup and Configuration Options Configuration Portlet 2.0 Coordination Sending and Receiving Events Configuration Public Render Parameters Configuration Serving Your JSF Resources in a Portlet Configuration Developing Portlets with the Bridge Excluding Attributes from the Bridge Request Scope Supporting PortletMode Changes Navigating to a mode's last viewid Note to Portlet Developers Clearing T he View History When Changing Portlet Modes General Error Handling Custom Ajax Error Handling Communication Between Your Portlets Storing Components in PortletSession.APPLICAT ION_SCOPE Using the PortletSession Linking to Portlet/JSF Pages Using h:outputlink Redirecting to an External Page or Resource Using Provided EL Variables 93. Chapter Authentication and..... Identity Password Encryption Predefined User Configuration Overview Plugin for adding users, groups and membership types Membership types Groups 98 3

7 Red Hat JBoss Portal 5.1 Reference Guide Users Plugin for managing user creation Authentication T oken Configuration The Token Service Implementing the T oken Service API Configuring T oken Services PicketLink IDM integration Configuration files Organization API Accessing User Profile SSO - Single Sign On Overview Enabling SSO using JBoss SSO Valve CAS - Central Authentication Service JOSSO - Java Open Single Sign-On Project OpenSSO - The Open Web SSO project SPNEGO - Simple and Protected GSSAPI Negotiation Mechanism LDAP Integration LDAP in Read-only Mode LDAP as Default Store Examples Chapter Web..... Services for... Remote Portlets (WSRP) Introduction Level of Support Deploying WSRP Non-default Ports or Hostnames Using WSRP with SSL Making a Portlet Remotable Consuming WSRP portlets from a remote Consumer Consuming Remote WSRP Portlets Overview Configuring a Remote Producer T he Configuration Portlet Using the Configuration portlet Using XML Adding remote portlets to categories Configuring Access to Remote Producers via XML Required Configuration Information Optional Configuration Examples Consumers Maintenance Modifying a Currently Held Registration Registration Modification for Service Upgrade Registration Modification on Producer Error Consumer Operations Importing and Exporting Portlets Erasing Local Registration Data Configuring the WSRP Producer Overview Default Configuration Registration Configuration Customization of Registration Handling Behavior WSRP Validation Mode Removing WSRP 172 4

8 Table of Contents. Part..... III... Advanced Development Chapter Foundations The exo Kernel Configuring services Configuration syntax Components External Plug-ins Includes, and special URLs Special variables InitParams configuration element Configuring a portal container T he Extension Mechanism and Portal Extensions Running Multiple Portals 189. Chapter exo..... JCR Introduction Concepts JCR configuration Example of the portal-system workspace Using AS Managed Datasources Datasource Configuration Declaring the datasource Datasource Paramenters Datasource Examples Configuring a DataSource for Remote Usage Configuring a Datasource to Use Login Modules External Value Storages Introduction T ree File Value Storage Content Addressable Value storage (CAS) support Search Configuration Global Search Index IndexingConfiguration Multi-language support in exo JCR RDB back end Oracle DB MySQL PostgreSQL JBoss Cache configuration Indexer, Lock Manager and Data Container JGroups configuration LockManager CacheableLockManagerImpl Simple JBoss Cache Configuration T emplate JBoss Cache Configuration QueryHandler configuration Configuration JBossT ransactionsservice Introduction Configuration 236. Revision History

9 6 Red Hat JBoss Portal 5.1 Reference Guide

10 Preface Preface 1. Document Conventions T his manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information. In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. T he Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later include the Liberation Fonts set by default Typographic Conventions Four typographic conventions are used to call attention to specific words and phrases. T hese conventions, and the circumstances they apply to, are as follows. Mono-spaced Bold Used to highlight system input, including shell commands, file names and paths. Also used to highlight keys and key combinations. For example: T o see the contents of the file m y_next_bestselling_novel in your current working directory, enter the cat m y_next_bestselling_novel command at the shell prompt and press Enter to execute the command. The above includes a file name, a shell command and a key, all presented in mono-spaced bold and all distinguishable thanks to context. Key combinations can be distinguished from an individual key by the plus sign that connects each part of a key combination. For example: Press Enter to execute the command. Press Ctrl+Alt+F2 to switch to a virtual terminal. T he first example highlights a particular key to press. T he second example highlights a key combination: a set of three keys pressed simultaneously. If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in m ono-spaced bold. For example: File-related classes include filesystem for file systems, file for files, and dir for directories. Each class has its own associated set of permissions. Proportional Bold T his denotes words or phrases encountered on a system, including application names; dialog box text; labeled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example: Choose System Preferences Mouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, select the Left-handed m ouse check box and click Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand). T o insert a special character into a gedit file, choose Applications Accessories 7

11 Red Hat JBoss Portal 5.1 Reference Guide Character Map from the main menu bar. Next, choose Search Find from the Character Map menu bar, type the name of the character in the Search field and click Next. T he character you sought will be highlighted in the Character T able. Double-click this highlighted character to place it in the T ext to copy field and then click the Copy button. Now switch back to your document and choose Edit Paste from the gedit menu bar. T he above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context. Mono-spaced Bold Italic or Proportional Bold Italic Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example: T o connect to a remote machine using ssh, type ssh username@ domain.name at a shell prompt. If the remote machine is example.com and your username on that machine is john, type ssh john@ exam ple.com. T he m ount -o rem ount file-system command remounts the named file system. For example, to remount the /home file system, the command is mount -o remount /home. T o see the version of a currently installed package, use the rpm -q package command. It will return a result as follows: package-version-release. Note the words in bold italics above username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system. Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example: Publican is a DocBook publishing system Pull-quote Conventions T erminal output and source code listings are set off visually from the surrounding text. Output sent to a terminal is set in mono-spaced roman and presented thus: books Desktop documentation drafts mss photos stuff svn books_tests Desktop1 downloads images notes scripts svgs Source-code listings are also set in m ono-spaced rom an but add syntax highlighting as follows: 8

12 Preface package org.jboss.book.jca.ex1; import javax.naming.initialcontext; public class ExClient { public static void main(string args[]) throws Exception { InitialContext inictx = new InitialContext(); Object ref = inictx.lookup("echobean"); EchoHome home = (EchoHome) ref; Echo echo = home.create(); System.out.println("Created Echo"); } } System.out.println("Echo.echo('Hello') = " + echo.echo("hello")); 1.3. Notes and Warnings Finally, we use three visual styles to draw attention to information that might otherwise be overlooked. Note Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier. Important Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled 'Important' will not cause data loss but may cause irritation and frustration. Warning Warnings should not be ignored. Ignoring warnings will most likely cause data loss. 2. Getting Help and Giving Feedback 2.1. Do You Need Help? If you experience difficulty with a procedure described in this documentation, visit the Red Hat Customer Portal at T hrough the customer portal, you can: search or browse through a knowledgebase of technical support articles about Red Hat products. submit a support case to Red Hat Global Support Services (GSS). access other product documentation. 9

13 Red Hat JBoss Portal 5.1 Reference Guide Red Hat also hosts a large number of electronic mailing lists for discussion of Red Hat software and technology. You can find a list of publicly available mailing lists at Click on the name of any mailing list to subscribe to that list or to access the list archives Give us Feedback If you find a typographical error, or know how this guide can be improved, we would love to hear from you. Submit a report in Bugzilla against the product JBoss Enterprise Portal Platform 5 and the component docs-reference_guide. T he following link will take you to a pre-filled bug report for this product: Fill out the following template in Bugzilla's Description field. Be as specific as possible when describing the issue; this will help ensure that we can fix it quickly. Document URL: Section Number and Name: Describe the issue: Suggestions for improvement: Additional information: Be sure to give us your name so that you can receive full credit for reporting the issue. 10

14 Chapter 1. Introduction Chapter 1. Introduction JBoss Enterprise Portal Platform is based on the GateIn project which is the merge of two mature Java projects; JBoss Portal and exo Portal. T his new community project takes the best of both offerings and incorporates them into a single portal framework. T he aim is to provide an intuitive user-friendly portal, and a framework to address the needs of today's Web 2.0 applications. T his book provides a deep-dive information about installation and configuration of the services provided by JBoss Enterprise Portal Platform. 11

15 Red Hat JBoss Portal 5.1 Reference Guide Notational Devices Along with the Document Conventions outlined in the Preface, this document will also use the following notational devices: Devices <JBOSS_HOME> T his device will refer to the JBoss Application Server (jboss-as) directory deployed in JBoss Enterprise Portal Platform by default. T herefore, if your JBoss Enterprise Portal Platform instance is deployed into a directory called jboss-epp-5.1.1/, your <JBOSS_HOME> directory would be jboss-epp /jboss-as/. <PROFILE> This device will usually follow an instance of <JBOSS_HOME> in a file path and refers to the directory that contains the server profile your JBoss Enterprise Portal Platform instance is configured to use. JBoss Enterprise Portal Platform comes with six profiles by default; all, default, minimal, production, standard and web. These profiles are found in the <JBOSS_HOME>/server/ directory. Therefore, if you are using the default profile, your <PROFILE> directory would be <JBOSS_HOME>/server/default/ 1.1. Related Links T echnical documentation Other technical documentation, including an Installation Guide, and a User Guide can be found at Non-technical documentation Links to non-technical documents are included on the front page of the portal: 12 Videos A link to videos related to the JBoss Enterprise Portal Platform is also included on the front page:

16 Chapter 1. Introduction page: 13

17 Red Hat JBoss Portal 5.1 Reference Guide Part I. Portal Development 14

18 Chapter 2. Skinning the Portal Chapter 2. Skinning the Portal 2.1. Overview JBoss Enterprise Portal Platform provides robust skinning support for the entire portal User Interface (UI). This includes support for skinning all of the common portal elements as well as being able to provide custom skins and window decoration for individual portlets. T his has been designed with common graphic resource reuse and ease of development in mind Skin Components The skin of a page is composed of three separate parts: Portal Skin The portal skin contains the CSS styles for the portal and its various UI components. This should include all the UI components except for the window decorators and portlet specific styles. Window Styles T he CSS styles associated with the portlet window decorators. T he window decorators contain the control buttons and borders surrounding each portlet. Individual portlets can have their own window decorator selected or be rendered without one. Portlet Skins The portlet skins dictate how portlets are rendered on the page. There are two main ways they can be effected: Portlet Specification CSS Classes The portlet specification defines a set of CSS classes that should be available to portlets. JBoss Enterprise Portal Platform provides these classes as part of the portal skin. This allows each portal skin to define its own look and feel for these default values. Portlet Skins JBoss Enterprise Portal Platform provides a means for portlet CSS files to be loaded based on the current portal skin. This allows a portlet to provide different CSS styles to better match the current portal look and feel. Portlet skins provide a much more customizable CSS experience than just using the portlet specification CSS classes. 15

19 Red Hat JBoss Portal 5.1 Reference Guide CSS Classes T he window decorators and the default portlet specification CSS classes should be considered separate types of skinning components, but they need to be included as part of the overall portal skin. The portal skin must include these components' CSS classes or they will not be displayed correctly. A portlet skin does not need to be included as part of the portal skin and can be included within the portlets web application Skin Selection Skin Selection Through the User Interface A skin can be selected to be displayed to the user by multiple means. The easiest way to change the skin is to select it through the user interface. An administrator can change the default skin for the portal, or a logged in user can select which skin they would prefer to be displayed. Please see the User Guide for information on how to change the skin using the user interface Setting the Default Skin within the Configuration Files The default skin can also be configured using the portal configuration files. This allows the portal to have the new default skin ready for use when JBoss Enterprise Portal Platform is first started. The default skin of the portal is called Default. To change this value add a skin tag in the 02portal.war/WEB-INF/conf/portal/portal/classic/portal.xm l configuration file. To change the skin to MySkin you would make the following changes: <portal-config>... <portal-name>classic</portal-name> <locale>en</locale> <access-permissions>everyone</access-permissions> <edit-permission>*:/platform/administrators</edit-permission> <skin>myskin</skin> 2.4. Skins in Page Markups A JBoss Enterprise Portal Platform skin contains CSS styles for the portal's components but also shares components that may be reused in portlets. When JBoss Enterprise Portal Platform generates a portal page markup, it inserts stylesheet links in the page's head tag. There are two main types of CSS links that will appear in the head tag: a link to the portal skin CSS file and a link to the portlet skin CSS files. Portal Skin The portal skin will appear as a single link to a CSS file. This link will contain contents from all the portal skin classes merged into one file. This allows the portal skin to be transferred as a single file instead of multiple smaller files. 16

20 Chapter 2. Skinning the Portal Portlet Skin Each portlet on a page may contribute its own style. The link to the portlet skin will only appear on the page if that portlet is loaded on the current page. A page may contain many portlet skin CSS links or none. In the code fragment below you can see the two types of links: <head>... <!-- The portal skin --> <link id="coreskin" rel="stylesheet" type="text/css" href="/exoresources/skin/stylesheet.css" /> <!-- The portlet skins --> <link id="web_footerportlet" rel="stylesheet" type="text/css" href= "/web/skin/portal/webui/component/uifooterportlet/defaultstylesheet.css" /> <link id="web_navigationportlet" rel="stylesheet" type="text/css" href= "/web/skin/portal/webui/component/uinavigationportlet/defaultstylesheet.css" /> <link id="web_homepageportlet" rel="stylesheet" type="text/css" href= "/portal/templates/skin/webui/component/uihomepageportlet/defaultstylesheet.css" /> <link id="web_bannerportlet" rel="stylesheet" type="text/css" href= "/web/skin/portal/webui/component/uibannerportlet/defaultstylesheet.css" />... </head> CSS Classes Window styles and the portlet specification CSS classes are included within the portal skin The Skin Service T he skin service manages the various types of skins. It is responsible for discovering and deploying skins into the portal Skin configuration JBoss Enterprise Portal Platform automatically discovers web archives that contain a file descriptor for skins (WEB-INF/gatein-resources.xm l). T his file is responsible for specifying the portal, portlet and window decorators to be deployed into the skin service. T he full schema can be found at: Below is an example of where to define a skin (MySkin) with its CSS location, and specify some window decorator skins: 17

21 Red Hat JBoss Portal 5.1 Reference Guide <gatein-resources> <portal-skin> <skin-name>myskin</skin-name> <CSS-path>/skin/myskin.CSS</CSS-path> <overwrite>false</overwrite> </portal-skin> </gatein-resources> <!-- window style --> <window-style> <style-name>mythemecategory</style-name> <style-theme> <theme-name>mythemeblue</theme-name> </style-theme> <style-theme> <theme-name>mythemered</theme-name> </style-theme> Resource Request Filter Because of JBoss Enterprise Portal Platform's Right-T o-left support, all CSS files need to be retrieved through a Servlet filter and the web application needs to be configured to activate this filter. This is already done for 01eXoResources.war web application which contains the default skin. Any new web applications containing skinning CSS files will need to have the following added to their web.xml : <filter> <filter-name>resourcerequestfilter</filter-name> <filterclass>org.exoplatform.portal.application.resourcerequestfilter</filter-class> </filter> <filter-mapping> <filter-name>resourcerequestfilter</filter-name> <url-pattern>*.css</url-pattern> </filter-mapping> The display-name Element The display-name element will also need to be specified in the web.xml for the skinning service to work properly with the web application The Default Skin T he default skin for JBoss Enterprise Portal Platform is located as part of the 01eXoResources.war. The main files associated with the skin are: 18 gatein-resources.xml For the default portal skin, this file contains definitions for the portal skin, the window decorations that this skin provides and well as defining some javascript resources which are not related to the skin. T he default portal skin doesn't directly define portlet skins, these should be provided by the portlets themselves.

22 Chapter 2. Skinning the Portal web.xml For the default portal skin, the web.xml of the exoresources.war will contains a lot of information which is mostly irrelevant to the portal skinning. The area of interest in this file is the resourcerequestfilter and the fact that the display-name is set. Stylesheet.CSS This file is the main portal skin stylesheet. It is the main entry point to the CSS class definitions for the skin. The main content points of this file url(portlet/stylesheet.css); The skin for the main portal page. Skins for various portal components. Window decoration skins. T he portlet specification CSS classes. This method imports other CSS stylesheet files (some of which may also import further CSS stylesheets) instead of defining all the CSS classes in this one file. Splitting the CSS classes between multiple files allows new skins to reuse parts of the default skin. To reuse a CSS stylesheet from the default portal skin you would need to reference the default skin from exoresources. For example; to include the window decorators from the default skin within a new portal skin you would need to use this import url(/exoresources/skin/portlet/stylesheet.css); Stylesheet Merging When the portal skin is added to the page, it merges all the CSS stylesheets into a single file Creating New Skins Creating a New Portal Skin New portal skins will need to be added to the portal through the skin service. Therefore, the web application which contains the skins will need to be properly configured for the skin service to discover them. T his means properly configuring the ResourceRequestFilter and gatein-resources.xm l. 19

23 Red Hat JBoss Portal 5.1 Reference Guide Portal Skin Configuration The gatein-resources.xml will need to specify the new portal skin. This will include the name of the new skin, where to locate its CSS stylesheet file and whether to overwrite an existing portal theme with the same name. <gatein-resources> <portal-skin> <skin-name>myskin</skin-name> <CSS-path>/skin/myskin.CSS</CSS-path> <overwrite>false</overwrite> </portal-skin> </gatein-resources> T he default portal skin and window styles are defined in 01eXoResources.war/WEB-INF/gateinresources.xm l. CSS The CSS for the portal skin needs to contain the CSS for all the window decorations and the portlet specification CSS classes Portal Skin Preview Icon It is possible to see a preview of what the portal will look like when selecting a new skin. This functionality relies on the current skin being updated with skin icons for all other available skins. Otherwise it will not be able to show the previews. It is recommended that preview icons of any other skins are included when creating a new portal skin and that the other skins are updated with your new portal skin preview. The portal skin preview icon is specified through the CSS of the portal skin. In order for the current portal skin to be able to display the preview it must specify a specific CSS class and set the icon as the background. For a portal named MySkin in must define the following CSS class: 20

24 Chapter 2. Skinning the Portal.UIChangeSkinForm.UIItemSelector.TemplateContainer.MySkinImage In order for the default skin to display the skin icon for a new portal skin, the preview screenshot needs to be placed in: 01eXoResources.war:/skin/DefaultSkin/portal/webui/com ponent/custom ization/ui ChangeSkinForm/background. The CSS stylesheet for the default portal needs to have the following updated with the preview icon CSS class. For a skin named MySkin then the following needs to be updated: 01eXoResources.war:/skin/DefaultSkin/portal/webui/com ponent/custom ization/ui ChangeSkinForm/Stylesheet.CSS..UIChangeSkinForm.UIItemSelector.TemplateContainer.MySkinImage margin: auto; width: 329px; height:204px; background: url('background/myskin.jpg') no-repeat top; cursor: pointer ; } Creating a New Window Style Window styles are the CSS applied to window decorations. An administrator can decide which style of decoration should go around the window when they add a new application or gadget to a page Window Style Configuration Window Styles are defined within a gatein-resources.xm l file which is used by the skin service to deploy the window style into the portal. Window styles can belong in a window style category. This category and the window styles will need to be specified in resources file. The following gatein-resources.xml fragment will add MyThemeBlue and MyThemeRed to the MyT hem e category. 21

25 Red Hat JBoss Portal 5.1 Reference Guide <window-style> <style-name>mytheme</style-name> <style-theme> <theme-name>mythemeblue</theme-name> </style-theme> <style-theme> <theme-name>mythemered</theme-name> </style-theme> </window-style> T he windows style configuration for the default skin is configured in: 01eXoResources.war/WEB- INF/gatein-resources.xm l. Window Styles and Portal Skins When a window style is defined in gatein-resources.xm l file, it will be available to all portlets regardless of whether the current portal skin supports the window decorator or not. It is recommended that when a new window decorator is added that it be added to all portal skins or that all portal skins share a common stylesheet for window decorators Window Style CSS In order for the skin service to display the window decorators, it must have CSS classes specifically named in relation to the window style name. The service will try and display CSS based on this naming convention. The CSS class must be included as part of the current portal skin for the window decorators to be displayed. The location of the window decorator CSS classes for the default portal theme is located at: 01eXoResources.war/skin/PortletT hem es/stylesheet.css. Create the CSS file: 22

26 Chapter 2. Skinning the Portal /*---- MyTheme ----*/.MyTheme.WindowBarCenter.WindowPortletInfo { margin-right: 80px; /* orientation=lt */ margin-left: 80px; /* orientation=rt */ }.MyTheme.WindowBarCenter.ControlIcon { float: right;/* orientation=lt */ float: left;/* orientation=rt */ width: 24px; height: 17px; cursor: pointer; background-image: url('background/mytheme.png'); }.MyTheme.ArrowDownIcon { background-position: center 20px; }.MyTheme.OverArrowDownIcon { background-position: center 116px; }.MyTheme.MinimizedIcon { background-position: center 44px; }.MyTheme.OverMinimizedIcon { background-position: center 140px; }.MyTheme.MaximizedIcon { background-position: center 68px; }.MyTheme.OverMaximizedIcon { background-position: center 164px; }.MyTheme.RestoreIcon { background-position: center 92px; }.MyTheme.OverRestoreIcon { background-position: center 188px; }.MyTheme.NormalIcon { background-position: center 92px; }.MyTheme.OverNormalIcon { background-position: center 188px; }.UIPageDesktop.MyTheme.ResizeArea { float: right;/* orientation=lt */ float: left;/* orientation=rt */ width: 18px; height: 18px; cursor: nw-resize; background: url('background/resizearea18x18.gif') no-repeat left top; /* orientation=lt */ background: url('background/resizearea18x18-rt.gif') no-repeat right top; /* orientation=rt */ }.MyTheme.Information { height: 18px; line-height: 18px; vertical-align: middle; font-size: 10px; padding-left: 5px;/* orientation=lt */ padding-right: 5px;/* orientation=rt */ margin-right: 18px;/* orientation=lt */ margin-left: 18px;/* orientation=rt */ 23

27 Red Hat JBoss Portal 5.1 Reference Guide }.MyTheme.WindowBarCenter.WindowPortletIcon { background-position: left top; /* orientation=lt */ background-position: right top; /* orientation=rt */ padding-left: 20px; /* orientation=lt */ padding-right: 20px; /* orientation=rt */ height: 16px; line-height: 16px; }.MyTheme.WindowBarCenter.PortletName { font-weight: bold; color: #333333; overflow: hidden; white-space: nowrap; width: 100%; }.MyTheme.WindowBarLeft { padding-left: 12px; background-image: url('background/mytheme.png'); background-repeat: no-repeat; background-position: left -148px; }.MyTheme.WindowBarRight { padding-right: 11px; background-image: url('background/mytheme.png'); background-repeat: no-repeat; background-position: right -119px; }.MyTheme.WindowBarCenter { background-image: url('background/mytheme.png'); background-repeat: repeat-x; background-position: left -90px; }.MyTheme.WindowBarCenter.FixHeight { height: 21px; padding-top: 8px; }.MyTheme.MiddleDecoratorLeft { padding-left: 12px; background: url('background/mytheme.png') repeat-y left; }.MyTheme.MiddleDecoratorRight { padding-right: 11px; background: url('background/mytheme.png') repeat-y right; }.MyTheme.MiddleDecoratorCenter { background: #ffffff; }.MyTheme.BottomDecoratorLeft { MyTheme: 12px; background-image: url('background/mytheme.png'); background-repeat: no-repeat; background-position: left -60px; }.MyTheme.BottomDecoratorRight { padding-right: 11px; background-image: url('background/mytheme.png'); background-repeat: no-repeat; background-position: right -30px; } 24

28 Chapter 2. Skinning the Portal.MyTheme.BottomDecoratorCenter { background-image: url('background/mytheme.png'); background-repeat: repeat-x; background-position: left top; }.MyTheme.BottomDecoratorCenter.FixHeight { height: 30px; } How to Set the Default Window Style To set the default window style to be used for a portal you will need to specify the CSS classes for a theme called DefaultT hem e. DefaultTheme You do not need to specify the DefaultTheme in gatein-resources.xml How to Create New Portlet Skins Portlets often require additional styles that may not be defined by the portal skin. JBoss Enterprise Portal Platform allows portlets to define additional stylesheets for each portlet and will append the corresponding link tags to the head. T he link ID will be of the form {portletappname}{portletname}. For example: ContentPortlet in content.war, will give id="contentcontentportlet". To define a new CSS file to include whenever a portlet is available on a portal page, the following fragment needs to be added in gatein-resources.xm l. <portlet-skin> <application-name>portletappname</application-name> <portlet-name>portletname</portlet-name> <skin-name>default</skin-name> <CSS-path>/skin/DefaultStylesheet.CSS</CSS-path> </portlet-skin> <portlet-skin> <application-name>portletappname</application-name> <portlet-name>portletname</portlet-name> <skin-name>otherskin</skin-name> <CSS-path>/skin/OtherSkinStylesheet.CSS</CSS-path> </portlet-skin> This will load the DefaultStylesheet.css when the Default skin is used and the OtherSkinStylesheet.css when the OtherSkin is used. Updating Portlet Skins If the current portal skin is not defined as one of the supported skins, then the portlet CSS class will not be loaded. It is recommended that portlet skins are updated whenever a new portal skin is created. 25

29 Red Hat JBoss Portal 5.1 Reference Guide Change Portlet Icons Each portlet can be registered by a unique icon in the portlet registry or page editor. This icon can be changed by adding an image to the directory of the portlet web application: skin/defaultskin/portleticons/portlet_name.png. To be used correctly the icon must be named after the portlet. For example; the icon for an account portlet named AccountPortlet would be located at: skin/defaultskin/portleticons/accountportlet.png Portlet Icons Directory You must use skin/defaultskin/portleticons/ for the directory to store the portlet icon regardless of what skin is going to be used Create New Portlet Specification CSS Classes T he portlet specification defines a set of default CSS classes that should be available for portlets. These classes are included as part of the portal skin. Please see the portlet specification for a list of the default classes that should be available. For the default portal skin, the portlet specification CSS classes are defined in: 01eXoResources.war/skin/Portlet/Stylesheet.CSS Tips and Tricks Easier CSS Debugging By default, CSS files are cached and their imports are merged into a single CSS file at the server side. This reduces the number of HTTP requests from the browser to the server. The optimization code is quite simple as all the CSS files are parsed at the server start and all and url(...) references are rewritten to support a single flat file. The result is stored in a cache directly used from the ResourceRequestFilter. Although the optimization is useful for a production environment, it may be easier to deactivate this optimization while debugging stylesheets. Set the java system property exo.product.developing to true to disable the optimization. For example, the property can be passed as a JVM parameter with -D option when running JBoss Enterprise Portal Platform. sh jboss-as/bin/run.sh -Dexo.product.developing=true Warning This option may cause display bugs in some browsers. 26

30 Chapter 2. Skinning the Portal Some CSS Techniques It is recommended that users have some experience with CSS before studying JBoss Enterprise Portal Platform CSS. JBoss Enterprise Portal Platform relies heavily on CSS to create the layout and effects for the UI. Some common techniques for customizing JBoss Enterprise Portal Platform CSS are explained below Border Pattern The decorator is a pattern to create a contour or a curve around an area. In order to achieve this effect you need to create nine cells. The BODY is the central area that you want to decorate. The other eight cells are distributed around the BODY cell. You can use the width, height and background image properties to achieve any decoration effect that you want. <div class="parent"> <div class="topleft"> <div class="topright"> <div class="topcenter"><span></span></div> </div> </div> <div class="centerleft"> <div class="centerright"> <div class="centercenter">body</div> </div> </div> <div class="bottomleft"> <div class="bottomright"> <div class="bottomcenter"><span></span></div> </div> <div> </div> Left Margin Left Pattern Left margin left pattern is a technique to create two blocks side by side. The left block will have a fixed size and the right block will take the rest of the available space. When the user resizes the browser the added or removed space will be taken from the right block. 27

31 Red Hat JBoss Portal 5.1 Reference Guide <div class="parent"> <div style="float: left; width: 100px"> </div> <div style="margin-left: 105px;"> <div> <div style="clear: left"><span></span></div> </div> 28

32 Chapter 3. Portal Life-cycle Chapter 3. Portal Life-cycle 3.1. Overview T his chapter describes the portal life-cycle from the application server start to its stop including how requests are handled Application Server start and stop A portal instance is simply a web application deployed as a WAR in an application server. Portlets are also part of an enhanced WAR called a portlet application. JBoss Enterprise Portal Platform does not require any particular setup for your portlet in most common scenarios and the web.xm l file can remain without any JBoss Enterprise Portal Platform specific configuration. During deployment, JBoss Enterprise Portal Platform will automatically and transparently inject a servlet into the portlet application to be able to interact with it. This feature is dependent on the underlying servlet container but will work out of the box on the proposed bundles The Command Servlet T he CommandServlet is called by the portlet container for requests to particular portlets, it also includes some init code when the portal is launched. T his servlet (org.gatein.wci.com m and.com m andservlet) is automatically added during the deployment of each portlet application and mapped to /gateinservlet. This is equivalent to adding the following into web.xml. Servlet Configuration As the servlet is already configured this example is for information only. <servlet> <servlet-name>gateinservlet</servlet-name> <servlet-class>org.gatein.wci.command.commandservlet</servlet-class> <load-on-startup>0</load-on-startup> </servlet> <servlet-mapping> <servlet-name>gateinservlet</servlet-name> <url-pattern>/gateinservlet</url-pattern> </servlet-mapping> It is possible to filter on the CommandServlet by filtering the URL pattern used by the servlet mapping. The example below would create a servlet filter that calculates the time of execution of a portlet request. The filter class: 29

33 Red Hat JBoss Portal 5.1 Reference Guide package org.example; import java.io.ioexception; import javax.servlet.filterchain; import javax.servlet.filterconfig; import javax.servlet.servletexception; import javax.servlet.servletrequest; import javax.servlet.servletresponse; public class MyFilter implements javax.servlet.filter { public void dofilter(servletrequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { long beforetime = System.currentTimeMillis(); chain.dofilter(request, response); long aftertime = System.currentTimeMillis(); System.out.println("Time to execute the portlet request (in ms): " + (aftertime - beforetime)); } } public void init(filterconfig config) throws ServletException { } public void destroy() { } The Java EE web application configuration file (web.xml) of the portlet is the file on which we want to know the time to serve a portlet request. As mentioned above nothing specific to JBoss Enterprise Portal Platform needs to be included, only the URL pattern to set has to be known. <?xml version="1.0"?> <web-app xmlns:xsi=" xsi:schemalocation=" version="2.5"> <filter> <filter-name>myfilter</filter-name> <filter-class>org.example.myfilter</filter-class> </filter> <filter-mapping> <filter-name>myfilter</filter-name> <url-pattern>/gateinservlet</url-pattern> <dispatcher>include</dispatcher> </filter-mapping> </web-app> 30

34 Chapter 3. Portal Life-cycle INCLUDE dispatcher It is important to set INCLUDE as dispatcher as the portal will always hit the CommandServlet through a request dispatcher. Without this, the filter will not be triggered, unless direct access to a resource (such as an image) is set. 31

35 Red Hat JBoss Portal 5.1 Reference Guide Chapter 4. Default Portal Configuration 4.1. Overview JBoss Enterprise Portal Platform's default home page URL is e}:{port}/portal/. T here may be multiple independent portals deployed in parallel at any given time, each of which has its root context ( e}:{port}/sam pleportal/, for example). Each portal container is internally composed of one or more 'portals'. This is because there needs to be at least one such portal available. T he default portal is called 'Classic'. When accessing JBoss Enterprise Portal Platform's default URL, you are automatically directed to the 'Classic' portal. T he default portal performs another important task. When starting up JBoss Enterprise Portal Platform for the first time, its JCR database (where portal runtime-configurable settings are stored) will be empty. T he default portal detects this and triggers automatic data initialization Configuration T he following example configuration can be found at: "02portal.war:/WEB- INF/conf/portal/portal-configuration.xm l". <component> <key>org.exoplatform.portal.config.userportalconfigservice</key> <type>org.exoplatform.portal.config.userportalconfigservice</type> <component-plugins> <component-plugin> <name>new.portal.config.user.listener</name> <set-method>initlistener</set-method> <type>org.exoplatform.portal.config.newportalconfiglistener</type> <description>this listener init the portal configuration</description> <init-params> <value-param> <name>default.portal</name> <description>the default portal for checking db is empty or not</description> <value>classic</value> </value-param>... </init-params> </component-plugin> </component-plugins> </component> In this example the Classic portal has been set as the default. Notice that the NewPortalConfigListener component-plugin is used to add configuration to UserPortalConfigService, which is designed in this way to allow other components to add configuration to it. Components, component-plugins, and init-params are explained in a later chapter of this document (Chapter 16, Foundations). 32

36 Chapter 5. Portal Default Permission Configuration Chapter 5. Portal Default Permission Configuration 5.1. Overview The default permission configuration for the portal is defined through the org.exoplatform.portal.config.useracl component configuration in the JBOSS_HOME/server/<PROFILE>/deploy/gatein.ear/02portal.war:/WEB- INF/conf/portal/portal-configuration.xm l file. It defines eight permissions types: super.user The super user has all the rights on the platform, this user is referred to as root. portal.administrator.groups Any member of those groups are considered administrators. Default value is /platform/adm inistrators. portal.administrator.mstype Any user with that membership type would be considered administrator or the associated group. Default value is m anager. portal.creator.groups This list defines all groups that will be able to manage the different portals. Members of this group also have the permission to create new portals. The format is m em bership:/group/subgroup. navigation.creator.membership.type Defines the membership type of group managers. T he group managers have the permission to create and edit group pages and they can modify the group navigation. guests.group Any anonymous user automatically becomes a member of this group when they enter the public pages. mandatory.groups Groups that can't be deleted. mandatory.mstypes Membership types that can't be deleted. 33

37 Red Hat JBoss Portal 5.1 Reference Guide <component> <key>org.exoplatform.portal.config.useracl</key> <type>org.exoplatform.portal.config.useracl</type> <init-params> <value-param> <name>super.user</name> <description>administrator</description> <value>root</value> </value-param> <value-param> <name>portal.creator.groups</name> <description>groups with membership type have permission to manage portal</description> <value>*:/platform/administrators,*:/organization/management/executiveboard</value> </value-param> <value-param> <name>navigation.creator.membership.type</name> <description>specific membership type have full permission with group navigation</description> <value>manager</value> </value-param> <value-param> <name>guests.group</name> <description>guests group</description> <value>/platform/guests</value> </value-param> <values-param> <name>mandatory.groups</name> <description>groups that can not be deleted.</description> <value>/platform/administrators</value> <value>/platform/users</value> <value>/platform/guests</value> </values-param> <values-param> <name>mandatory.mstypes</name> <description>membership type that can not be deleted.</description> <value>member</value> </values-param> </init-params> </component> 5.2. Overwrite Portal Default Permissions When creating custom portals and portal extensions it is possible to override the default configuration by using org.exoplatform.portal.config.portalaclplugin, configuring it as an external-plugin of org.exoplatform.portal.config.useracl service: 34

38 Chapter 5. Portal Default Permission Configuration <external-component-plugins> <target-component>org.exoplatform.portal.config.useracl</target-component> <component-plugin> <name>addportalaclplugin</name> <set-method>addportalaclplugin</set-method> <type>org.exoplatform.portal.config.portalaclplugin</type> <description>setting some permission for portal</description> <init-params> <values-param> <name>super.user</name> <value>root</value> </values-param> <values-param> <name>portal.creation.roles</name> <value>*:/platform/administrators</value> <value>*:/organization/management/executive-board</value> </values-param> </init-params> </component-plugin> </external-component-plugins> 35

39 Red Hat JBoss Portal 5.1 Reference Guide Chapter 6. Portal Navigation Configuration 6.1. Overview T here are three types of navigation available to portal users: Section 6.2, Portal Navigation Section 6.3, Group Navigation Section 6.4, User Navigation T hese navigations are configured using the standard XML syntax in the file; 02portal.war:/WEB- INF/conf/portal/portal-configuration.xm l. 36

40 Chapter 6. Portal Navigation Configuration <component> <key>org.exoplatform.portal.config.userportalconfigservice</key> <type>org.exoplatform.portal.config.userportalconfigservice</type> <component-plugins> <component-plugin> <name>new.portal.config.user.listener</name> <set-method>initlistener</set-method> <type>org.exoplatform.portal.config.newportalconfiglistener</type> <description>this listener init the portal configuration</description> <init-params> <value-param> <name>default.portal</name> <description>the default portal for checking db is empty or not</description> <value>classic</value> </value-param> <value-param> <name>page.templates.location</name> <description>the path to the location that contains Page templates</description> <value>war:/conf/portal/template/pages</value> </value-param> <object-param> <name>site.templates.location</name> <description>description</description> <object type="org.exoplatform.portal.config.siteconfigtemplate"> <field name="location"> <string>war:/conf/portal</string> </field> <field name="portaltemplates"> <collection type="java.util.hashset"> <value> <string>classic</string> </value> </collection> </field> <field name="grouptemplates"> <collection type="java.util.hashset"> <value> <string>group</string> </value> </collection> </field> <field name="usertemplates"> <collection type="java.util.hashset"> <value> <string>user</string> </value> </collection> </field> </object> </object-param> <object-param> <name>portal.configuration</name> <description>description</description> <object type="org.exoplatform.portal.config.newportalconfig"> <field name="predefinedowner"> <collection type="java.util.hashset"> <value><string>classic</string></value> </collection> 37

41 Red Hat JBoss Portal 5.1 Reference Guide </field> <field name="ownertype"><string>portal</string></field> <field name="templatelocation"><string>war:/conf/portal/</string></field> </object> </object-param> <object-param> <name>group.configuration</name> <description>description</description> <object type="org.exoplatform.portal.config.newportalconfig"> <field name="predefinedowner"> <collection type="java.util.hashset"> <value><string>/platform/administrators</string></value> <value><string>/platform/users</string></value> <value><string>/platform/guests</string></value> <value><string>/organization/management/executiveboard</string></value> </collection> </field> <field name="ownertype"><string>group</string></field> <field name="templatelocation"><string>war:/conf/portal</string></field> </object> </object-param> <object-param> <name>user.configuration</name> <description>description</description> <object type="org.exoplatform.portal.config.newportalconfig"> <field name="predefinedowner"> <collection type="java.util.hashset"> <value><string>root</string></value> <value><string>john</string></value> <value><string>mary</string></value> <value><string>demo</string></value> <value><string>user</string></value> </collection> </field> <field name="ownertype"><string>user</string></field> <field name="templatelocation"><string>war:/conf/portal</string></field> </object> </object-param> </init-params> </component-plugin> </component-plugins> </component> T his XML configuration defines where in the portal's WAR to look for configuration settings, and which portals, groups, and user specific views to include in portal/group/user navigation. The first time the portal is launched those files will be used to create an initial navigation. That information will then be stored in the JCR content repository and can be modified and managed from the portal UI. Each portal, groups and users navigation is indicated by a configuration paragraph, for example: 38

42 Chapter 6. Portal Navigation Configuration <object-param> <name>portal.configuration</name> <description>description</description> <object type="org.exoplatform.portal.config.newportalconfig"> <field name="predefinedowner"> <collection type="java.util.hashset"> <value><string>classic</string></value> </collection> </field> <field name="ownertype"> <string>portal</string> </field> <field name="templatelocation"> <string>war:/conf/portal/</string> </field> <field name="importmode"> <string>conserve</string> </field> </object> </object-param> predefinedowner defines the navigation owner, portal will look for the configuration files in folder with this name, if there is no suitable folder, a default portal will be created with name is this value. ownertype define the type of portal navigation. It may be a portal, group or user templatelocation the classpath where contains all portal configuration files importmode The mode for navigation import. There are 4 types of import mode: conserve: Import data when it does not exist, otherwise do nothing. insert: Import data when it does not exist, otherwise performs a strategy that adds new data only. merge: Import data when it does not exist, update data when it exists. rewrite: Overwrite data whatsoever. Based on these parameters, the portal will look for the configuration files and create a relevant portal navigation, pages and data import strategy. The portal configuration files will be stored in folders with path look like {templatelocation}/{ownertype}/{predefinedowner}, all navigations are defined in the navigation.xml file, pages are defined in pages.xml and portal configuration is defined in {ownert ype}.xm l. For example, with the above configuration, portal will look for all configuration files from war:/conf/portal/portal/classic path Portal Navigation The portal navigation incorporates the pages that can be accessed even when a user is not logged in (assuming the applicable permissions allow public access). For example; several portal navigations could be used when a company has multiple trademarks, and websites are set up for each of them. T he Classic portal is configured by three XML files in the 02portal.war:/WEB- INF/conf/portal/portal/classic directory: 39

43 Red Hat JBoss Portal 5.1 Reference Guide portal.xml This file describes the layout and portlets that will be shown on all pages. Usually the layout contains the banner, footer, menu and breadcrumbs portlets. JBoss Enterprise Portal Platform is extremely configurable as every view element (even the banner and footer) is a portlet. 4 0

44 Chapter 6. Portal Navigation Configuration <?xml version="1.0" encoding="iso "?> <portal-config xmlns:xsi=" xsi:schemalocation=" xmlns=" <portal-name>classic</portal-name> <locale>en</locale> <access-permissions>everyone</access-permissions> <edit-permission>*:/platform/administrators</edit-permission> <skin>newskin</skin> <properties> <entry key="sessionalive">ondemand</entry> </properties> <portal-layout> <portlet-application> <portlet> <application-ref>web</application-ref> <portlet-ref>bannerportlet</portlet-ref> <preferences> <preference> <name>template</name> <value>par:/groovy/groovy/webui/component/uibannerportlet.gtmpl</value> <read-only>false</read-only> </preference> </preferences> </portlet> <access-permissions>everyone</access-permissions> <show-info-bar>false</show-info-bar> </portlet-application> <portlet-application> <portlet> <application-ref>web</application-ref> <portlet-ref>navigationportlet</portlet-ref> </portlet> <access-permissions>everyone</access-permissions> <show-info-bar>false</show-info-bar> </portlet-application> <portlet-application> <portlet> <application-ref>web</application-ref> <portlet-ref>breadcumbsportlet</portlet-ref> </portlet> <access-permissions>everyone</access-permissions> <show-info-bar>false</show-info-bar> </portlet-application> <page-body> </page-body> <portlet-application> <portlet> <application-ref>web</application-ref> <portlet-ref>footerportlet</portlet-ref> <preferences> <preference> <name>template</name> 4 1

45 Red Hat JBoss Portal 5.1 Reference Guide <value>par:/groovy/groovy/webui/component/uifooterportlet.gtmpl</value> <read-only>false</read-only> </preference> </preferences> </portlet> <access-permissions>everyone</access-permissions> <show-info-bar>false</show-info-bar> </portlet-application> </portal-layout> </portal-config> It is also possible to apply a nested container that can also contain portlets. Row, column or tab containers are then responsible for the layout of their child portlets. Each application references a portlet using the id portal#{portalnam e}:/{portletwarnam e}/{portletnam e}/{uniqueid}. Use the page-body tag to define where JBoss Enterprise Portal Platform should render the current page. T he defined classic portal is accessible to "Everyone" (at /portal/public/classic) but only members of the group /platform/adm inistrators can edit it. navigation.xml This file defines all the navigation nodes the portal will have. The syntax is simple and uses nested node tags. Each node references a page defined in pages.xm l file. If the administrator wants to create node labels for each language, they will have to use xml:lang attribute in the label tag with value of xml:lang is the relevant locale. Otherwise, if they want the node label is localized by resource bundle files, the #{...} syntax will be used, the enclosed property name serves as a key that is automatically passed to internationalization mechanism which replaces the literal property name with a localized value taken from the associated properties file matching the current locale. 4 2

46 Chapter 6. Portal Navigation Configuration <?xml version="1.0" encoding="iso "?> <node-navigation xmlns:xsi=" xsi:schemalocation=" xmlns=" <priority>1</priority> <page-nodes> <node> <uri>home</uri> <name>home</name> <label>#{portal.classic.home}</label> <page-reference>portal::classic::homepage</page-reference> </node> <node> <uri>sitemap</uri> <name>sitemap</name> <label>#{portal.classic.sitemap}</label> <visibility>displayed</visibility> <page-reference>portal::classic::sitemap</page-reference> </node> </page-nodes> </node-navigation> T his navigation tree can have multiple views inside portlets (such as the breadcrumbs portlet) that render the current view node, the site map or the menu portlets. Warning For top nodes, the uri and the name of your navigation nodes must have the same value. For other nodes the uri is a relative path. For example; contentmanagement/fileexplorer where 'contentm anagem ent ' is the name of the parent node and 'fileexplorer' is the name of the node (<name>fileexplorer</name> ). Subnodes Subnodes can also be created using the following XML structure <?xml version="1.0" encoding="utf-8"?> <node> <uri>page</uri> <name>page</name> <label>page</label> <visibility>displayed</visibility> <page-reference>portal::classic::page</page-reference> <node> <uri>page/subpage</uri> <name>subpage</name> <label>sub-page</label> <visibility>displayed</visibility> <page-reference>portal::classic::subpage</page-reference> </node> </node> 4 3

47 Red Hat JBoss Portal 5.1 Reference Guide pages.xml T his element defines the parent/child relationship between a page and a subnode. T his configuration file structure is very similar to portal.xm l and it can also contain container tags (some usage examples of container tags can be found in 02portal.war/WEB- INF/conf/portal/portal/sharedlayout.xm l). Each application can decide whether to render the portlet border, the window state, the icons or portlet's mode. 4 4

48 Chapter 6. Portal Navigation Configuration <?xml version="1.0" encoding="iso "?> <page-set xmlns:xsi=" xsi:schemalocation=" xmlns=" <page> <name>homepage</name> <title>home Page</title> <access-permissions>everyone</access-permissions> <edit-permission>*:/platform/administrators</edit-permission> <portlet-application> <portlet> <application-ref>web</application-ref> <portlet-ref>homepageportlet</portlet-ref> <preferences> <preference> <name>template</name> <value>system:/templates/groovy/webui/component/uihomepageportlet.gtmpl</v alue> <read-only>false</read-only> </preference> </preferences> </portlet> <title>home Page portlet</title> <access-permissions>everyone</access-permissions> <show-info-bar>false</show-info-bar> <show-application-state>false</show-application-state> <show-application-mode>false</show-application-mode> </portlet-application> </page> <page> <name>sitemap</name> <title>site Map</title> <access-permissions>everyone</access-permissions> <edit-permission>*:/platform/administrators</edit-permission> <portlet-application> <portlet> <application-ref>web</application-ref> <portlet-ref>sitemapportlet</portlet-ref> </portlet> <title>sitemap</title> <access-permissions>everyone</access-permissions> <show-info-bar>false</show-info-bar> </portlet-application> </page> </page-set> 6.3. Group Navigation Group navigations are dynamically added to the user navigation at login. This allows users to see the pages assigned to any groups they belong to in the menu. The group navigation menu is configured by two XML files (navigation.xml and pages.xml). The 4 5

49 Red Hat JBoss Portal 5.1 Reference Guide syntax used in these files is the same as those covered in Section 6.2, Portal Navigation. T hey are located in 02portal.war/WEB-INF/conf/portal/group/group-name-path/ directory (For example; 02portal.war/WEB-INF/conf/portal/group/platform/adm inistrators/) User Navigation User navigation is the set of nodes and pages that are owned by a user. They are part of the user's dashboard. Two files configure the user navigation (navigation.xml and pages.xml). They are located in the directory "02portal.war/WEB-INF/conf/portal/users/{userNam e}". T he file exogadgets.war/web-inf/gadget.xm l defines the gadgets that will be available on a user dashboard. The example below shows a dashboard with all of the default gadgets included, as well as an extra currency converter gadget sourced from Google Gadgets. <?xml version="1.0" encoding="iso "?> <gadgets xmlns:xsi=" xsi:schemalocation=" xmlns=" <gadget name="todo"> <path>/gadgets/todo/todo.xml</path> </gadget> <gadget name="calendar"> <path>/gadgets/calendar/calendar.xml</path> </gadget> <gadget name="calculator"> <path>/gadgets/calculator/calculator.xml</path> </gadget> <gadget name="rssaggregator"> <path>/gadgets/rssaggregator/rssaggregator.xml</path> </gadget> <gadget name="currency"> <url> </gadget> </gadgets> 4 6

50 Chapter 7. Internationalization Configuration Chapter 7. Internationalization Configuration 7.1. Overview Assumed Knowledge JBoss Enterprise Portal Platform is fully configurable for internationalization, however users should have a general knowledge of Internationalization in Java products before attempting these configurations. Sun Java hosts a comprehensive guide to internationalizing java products at OC.html. All JBoss Enterprise Portal Platform applications contain property files for various languages. T hey are packaged with the portlets applications in a WEB-INF/classes/locale/ directory. These files are located in the classes folder of the WEB-INF directory, so as to be loaded by the ClassLoader. All resource files are in a subfolder named locale. For instance; the translations for the NavigationPortlet are located in web.war/web- INF/classes/locale/portlet/portal NavigationPortlet_de.properties NavigationPortlet_en.properties NavigationPortlet_es.properties NavigationPortlet_fr.properties NavigationPortlet_nl.properties NavigationPortlet_ru.properties NavigationPortlet_uk.properties NavigationPortlet_ar.xml Inside those file are typical key=value Java EE properties. For example; in the Spanish file: javax.portlet.title=portlet de navegaci\u00f3n T here are also properties files in the portal itself. T hey form the portal resource bundle. From a portlet you can then access translations from the portlet itself or shared at the portal level, both are aggregated when you need them. Translation in XML Format It is also possible to use a proprietary XML format to define translations. This is a more convenient way to translate a document for some languages such as Japanese, Arabic or Russian. Property files have to be ISO encoded, while the XML file can define its encoding. As a result it's easier for a human being to read a translation in XML instead of having to decode and encode the property file. For more information refer to: Chapter 10, XML Resources Bundles 4 7

51 Red Hat JBoss Portal 5.1 Reference Guide 7.2. Locales Configuration Various languages are available in the portal package. T he configuration below will define which languages are shown in the "Change Language" section and made available to users. T he 02portal.war:/WEB-INF/conf/com m on/com m on-configuration.xm l file of your installation contains the following section: <component> <key>org.exoplatform.services.resources.localeconfigservice</key> <type>org.exoplatform.services.resources.impl.localeconfigserviceimpl</type> <init-params> <value-param> <name>locale.config.file</name> <value>war:/conf/common/locales-config.xml</value> </value-param> </init-params> </component> T his configuration points to the locale configuration file. T he locale configuration file (02portal.war:/WEB-INF/conf/com m on/locales-config.xm l) contains the following code: <?xml version="1.0" encoding="utf-8"?> <locales-config> <locale-config> <locale>en</locale> <output-encoding>utf-8</output-encoding> <input-encoding>utf-8</input-encoding> <description>default configuration for english locale</description> </locale-config> <locale-config> <locale>fr</locale> <output-encoding>utf-8</output-encoding> <input-encoding>utf-8</input-encoding> <description>default configuration for the french locale</description> </locale-config> <locale-config> <locale>ar</locale> <output-encoding>utf-8</output-encoding> <input-encoding>utf-8</input-encoding> <description>default configuration for the arabic locale</description> <orientation>rt</orientation> </locale-config> </locales-config> locale: The locale has to be defined as per the codes defined here. In this example "ar" is Arabic. output-encoding: deals with character encoding. It is recommended that UT F-8 be used. input-encoding: In the Java implementation, the encoding parameters will be used for the request response stream. The input-encoding parameter will be used for request setcharacterencoding(..). description: A description of the language 4 8

52 Chapter 7. Internationalization Configuration orientation: Although the default orientation of text and images is Left-T o-right, JBoss Enterprise Portal Platform supports Right-T o-left orientation. Modifying text orientation is explained in Chapter 9, Right To Left (RTL) Framework ResourceBundleService T he resource bundle service is configured in: 02portal.war:/WEB-INF/conf/com m on/com m onconfiguration.xm l: <component> <key>org.exoplatform.services.resources.resourcebundleservice</key> <type>org.exoplatform.services.resources.impl.simpleresourcebundleservice</type> <init-params> <values-param> <name>classpath.resources</name> <description>the resources that start with the following package name should be load from file system</description> <value>locale.portlet</value> </values-param> <values-param> <name>init.resources</name> <description>initiate the following resources during the first launch</description> <value>locale.portal.expression</value> <value>locale.portal.services</value> <value>locale.portal.webui</value> <value>locale.portal.custom</value> <value>locale.navigation.portal.classic</value> <value>locale.navigation.group.platform.administrators</value> <value>locale.navigation.group.platform.users</value> <value>locale.navigation.group.platform.guests</value> <value>locale.navigation.group.organization.management.executiveboard</value> </values-param> <values-param> <name>portal.resource.names</name> <description>the properties files of the portal, those file will be merged into one ResoruceBundle properties </description> <value>locale.portal.expression</value> <value>locale.portal.services</value> <value>locale.portal.webui</value> <value>locale.portal.custom</value> </values-param> </init-params> </component> classpath.resources: T hese are discussed in a later section. portal.resource.names: Defines all resources that belong to the Portal Resource Bundle. T hese resources are merged to a single resource bundle which is accessible from anywhere in JBoss Enterprise Portal Platform. All these keys are located in the same bundle, which is separated from the navigation resource bundles. 4 9

53 Red Hat JBoss Portal 5.1 Reference Guide 7.4. Navigation Resource Bundles There is a resource bundle for each navigation. A navigation can exist for user, groups, and portal. T he previous example shows bundle definitions for the navigation of the classic portal and of four different groups. Each of these resource bundles occupies a different sphere, they are independent of each other and they are not included in the portal.resource.names parameter. T he properties for a group must be in the WEB-INF/classes/locale/navigation/group/ folder. For example; /WEB- INF/classes/locale/navigation/group/organization/m anagem ent/executiveboard_en.properties. The folder and file names must correspond to the group hierarchy. The group name "executiveboard" is followed by the iso 639 code. Each language defined in LocalesConfig must have a resource file defined. If the name of a group is changed the name of the folder and/or files of the correspondent navigation resource bundles must also be changed. Content of executive-board_en.properties: organization.title=organization organization.newstaff=new Staff organization.management=management This resource bundle is only accessible for the navigation of the organization.management.executive-board group Portlets Portlets are independent applications and deliver their own resource files. All shipped portlet resources are located in the locale/portlet subfolder. T he ResourceBundleService parameter classpath.resources defines this subfolder. Procedure 7.1. T o add a Spanish translation to the GadgetPortlet 1. Create the file GadgetPortlet_es.properties in: WEB- INF/classes/locale/portlet/gadget/GadgetPortlet. 2. In portlet.xm l, add Spanish as a supported-locale ('es' is the two letter code for Spanish). The resource-bundle is already declared and is the same for all languages : <supported-locale>en</supported-locale> <supported-locale>es</supported-locale> <resource-bundle>locale.portlet.gadget.gadgetportlet</resource-bundle> See the portlet specification for more details about portlet internationalization Standard Portlet Resource Keys T he portlet specification defines three standard keys: Title, Short Title and Keywords. Keywords is formatted as a comma-separated list of tags. 50

54 Chapter 7. Internationalization Configuration javax.portlet.title=breadcrumbs Portlet javax.portlet.short.title=breadcrumbs javax.portlet.keywords=breadcrumbs, Breadcrumb 51

55 Red Hat JBoss Portal 5.1 Reference Guide Chapter 8. Localization Configuration 8.1. Pluggable Locale Policy Every request processed by every portlet is invoked within a context of the current Locale. The current Locale can be retrieved by calling the getlocale() method of javax.portlet.portletrequest interface. T he exact algorithm for determining the current Locale is not specified by Portlet Specification. Portlet containers implement this the way they deem most appropriate. In JBoss Enterprise Portal Platform, each portal instance has a default language which can be used to present content for new users. Another option is to use each user s browser language preference, provided it matches one of the available localizations that JBoss Enterprise Portal Platform supports, and only fallback to the portal's default language if no match is found. Every user, while visiting a portal, has an option to change the language of the user interface by using a Language chooser. The choice can be remembered for the duration of the session, or it can be remembered for a longer period using a browser cookie, or, for registered and logged-in users, it can be saved into the user s profile. As there is more than one way to determine the Locale to be used for displaying a portal page, the mechanism for determining the current Locale of the request is pluggable in JBoss Enterprise Portal Platform, and the exact algorithm can be customized LocalePolicy API Customization is achieved by using LocalePolicy API, which is a simple API consisting of one interface, and one class: org.exoplatform.services.resources.localepolicy interface org.exoplatform.services.resources.localecontextinfo class T he LocalePolicy interface defines a single method that is invoked on the installed LocalePolicy service implementation: public interface LocalePolicy { public Locale determinelocale(localecontextinfo localecontext); } T he Locale returned by determinelocale() method is the Locale that will be returned to portlets when they call javax.portlet.portletrequest.getlocale() method. The returned Locale has to be one of the locales supported by portal, otherwise it will fall back to the portal default Locale. The supported locales are listed in JBOSS_HOME/server/<PROFILE>/deploy/gatein.ear/02portal.war/WEB- INF/conf/com m on/locales-config.xm l file as described in Section 7.2, Locales Configuration. T he determ inelocale() method takes a parameter of type LocaleContextInfo, which represents a compilation of preferred locales from different sources; user s profile, portal default, 52

56 Chapter 8. Localization Configuration browser language settings, current session, browser cookie. All these different sources of Locale configuration or preference are used as input to LocalePolicy implementation that decides which Locale should be used Default LocalePolicy By default, org.exoplatform.portal.application.localization.defaultlocalepolicyservice, an implementation of LocalePolicy, is installed to provide the default behavior. T his, however, can easily be extended and overridden. A completely new implementation can also be written from scratch. DefaultLocalePolicyService treats logged-in users slightly differently than anonymous users. Logged-in users have a profile that can contain language preference, while anonymous users do not. Here is an algorithm used for anonymous users. Procedure 8.1. An algorithm for anonymous users 1. Iterate over LocaleContextInfo properties in the following order: cookielocales sessionlocale browserlocales portallocale 2. Get each property's value. If it's a collection, get the first value. 3. If value is one of the supported locales return it as a result. 4. If the value is not in the supported locales set, try to remove country information and check if a language matching locale is in the list of supported locales. If so, return it as a result. 5. Otherwise, continue with the next property. If no supported locale is found the return locale eventually defaults to portallocale. T he algorithm for logged-in users is virtually the same except that the first Locale source checked is user's profile. Procedure 8.2. An algorithm for logged-in users 1. Iterate over LocaleContextInfo properties in the following order: userprofile cookielocales sessionlocale browserlocales portallocale 2. Perform the rest of the steps in Procedure 8.1, An algorithm for anonymous users Custom LocalePolicy T he easiest way to customize the LocalePolicy is to extend DefaultLocalePolicyService. A study of the source code is required. JavaDocs provide thorough information on this. Most customizations will involve simply overriding one or more of its protected methods. 53

57 Red Hat JBoss Portal 5.1 Reference Guide An example of a customization is an already provided NoBrowserLocalePolicyService. By overriding just one method, it skips any use of browser language preference. public class NoBrowserLocalePolicyService extends DefaultLocalePolicyService { /** * Override super method with no-op. * context locale context info available to implementations in order to determine appropriate Locale null protected Locale getlocaleconfigfrombrowser(localecontextinfo context) { return null; } } LocalePolicy Configuration T he LocalePolicy framework is enabled for portlets by configuring LocalizationLifecycle class in portal's webui configuration file: JBOSS_HOME/server/<PROFILE>/deploy/gatein.ear/02portal.war/WEB-INF/webuiconfiguration.xm l: <application-lifecycle-listeners>... <listener>org.exoplatform.portal.application.localization.localizationlifecycle</l istener> </application-lifecycle-listeners> The default LocalePolicy implementation is installed as an exo Kernel portal service via JBOSS_HOME/server/<PROFILE>/deploy/gatein.ear/lib/exo.portal.webui.portal- VERSION.jar/conf/portal/configuration.xm l. T he following excerpt is responsible for installing the service: <component> <key>org.exoplatform.services.resources.localepolicy</key> <type>org.exoplatform.portal.application.localization.defaultlocalepolicyservice</ type> </component> Besides implementing LocalePolicy, the service class also needs to implement org.picocontainer.startable interface in order to get installed. This configuration file should not be changed. The configuration in it can be overridden by placing it into portal's.war file: JBOSS_HOME/server/<PROFILE>/deploy/gatein.ear/02portal.war/WEB- INF/conf/configuration.xm l (usually as another file included into this one) Keeping non-bridged resources in sync with current Locale All the resources in portals that are not portlets themselves, but are accessed through portlets - reading 54

58 Chapter 8. Localization Configuration data through PortletRequest, and writing to PortletResponse - are referred to as 'bridged'. Any resources that are accessed directly, bypassing portal filters and servlets, are referred to as 'nonbridged'. Non-bridged servlets, and.jsps have no access to PortalRequest. They don't use PortletRequest.getLocale() to determine current Locale. Instead, they use ServletRequest.getLocale() which is subject to precise semantics defined by Servlet specification - it reflects browser's language preference. In other words, non-bridged resources do not have a notion of current Locale in the same sense that portlets do. The result is that when mixing portlets and non-bridged resources there may be a localization mismatch, an inconsistency in the language used by different resources composing your portal page. This problem is addressed by LocalizationFilter. This is a filter that changes the behavior of ServletRequest.getLocale() method so that it behaves the same way as PortletRequest.getLocale(). That way even localization of servlets, and.jsps accessed in a non-bridged manner can stay in sync with portlet localization. LocalizationFilter is installed through the portal's web.xml file: JBOSS_HOME/server/<PROFILE>/deploy/gatein.ear/02portal.war/WEB-INF/web.xm l. <filter> <filter-name>localizationfilter</filter-name> <filterclass>org.exoplatform.portal.application.localization.localizationfilter</filterclass> </filter>... <filter-mapping> <filter-name>localizationfilter</filter-name> <url-pattern>/* </url-pattern> <dispatcher>include</dispatcher> <dispatcher>forward</dispatcher> <dispatcher>request</dispatcher> <dispatcher>error</dispatcher> </filter-mapping> T here is a minor limitation with this mechanism in that it is unable to determine the current portal,and consequently, its default language. As a result the portallocale defaults to English, but can be configured to something else by using the filter's PortalLocale init param. For example: <filter> <filter-name>localizationfilter</filter-name> <filterclass>org.exoplatform.portal.application.localization.localizationfilter</filterclass> <init-param> <param-name>portallocale</param-name> <param-value>fr_fr</param-value> </init-param> </filter> 55

59 Red Hat JBoss Portal 5.1 Reference Guide By default, LocalizationFilter is applied very broadly to cover all the resources automatically. JBoss Enterprise Portal Platform uses some non-bridged.jsps that require LocalizationFilter, so narrowing the mapping to *.jsp is enough for JBoss Enterprise Portal Platform to function correctly. Additionally deployed portlets, and portal applications, however, may require broader mapping to cover their non-bridged resources. Narrowing the mapping might improve performance. T his is something to consider, when optimizing for speed. 56

60 Chapter 9. Right To Left (RTL) Framework Chapter 9. Right To Left (RTL) Framework The text orientation depends on the current locale setting. The orientation is a Java 5 enum that provides a set of functionalities: LT, // Western Europe RT, // Middle East (Arabic, Hebrew) TL, // Japanese, Chinese, Korean TR; // Mongolian public boolean islt() {... } public boolean isrt() {... } public boolean istl() {... } public boolean istr() {... } 9.1. Groovy templates Orientation is defined by implicit variables passed into the groovy binding context: Orientation T he current orientation as an Orientation. islt T he value of orientation.islt(). isrt T he value of orientation.isrt(). dir The string 'ltr' if the orientation is LT or the string 'rtl' if the orientation is RT Stylesheet T he skin service handles stylesheet rewriting to accommodate the orientation. It works by appending -lt or -rt to the stylesheet name. For instance: JBOSS_HOME/server/<PROFILE>/deploy/gatein.ear/web.war/skin/portal/webui/com pon ent/uifooterportlet/defaultstylesheet-rt.css will return the same stylesheet as JBOSS_HOME/server/<PROFILE>/deploy/gatein.ear/web.war/skin/portal/webui/com pon ent/uifooterportlet/defaultstylesheet.css but processed for the RT orientation. T he -lt suffix is optional. Stylesheet authors can annotate their stylesheet to create content that depends on the orientation. In the example below we need to use the orientation to modify the float attribute that will make the horizontal tabs either float on left or on right: 57

61 Red Hat JBoss Portal 5.1 Reference Guide Example 9.1. Example 1 float: left; /* orientation=lt */ float: right; /* orientation=rt */ font-weight: bold; text-align: center; white-space: nowrap; The LT produced output will be: float: left; /* orientation=lt */ font-weight: bold; text-align: center; white-space: nowrap; The RT produced output will be: float: right; /* orientation=rt */ font-weight: bold; text-align: center; white-space: nowrap; In this example we need to modify the padding according to the orientation: Example 9.2. Example 2 color: white; line-height: 24px; padding: 0px 5px 0px 0px; /* orientation=lt */ padding: 0px 0px 0px 5px; /* >orientation=rt */ The LT produced output will be: color: white; line-height: 24px; padding: 0px 5px 0px 0px; /* orientation=lt */ The RT produced output will be: color: white; line-height: 24px; padding: 0px 0px 0px 5px; /* orientation=rt */ 9.3. Images Sometimes it is necessary to create an RT version of an image that will be used from a template or from a stylesheet. However symmetric images can be automatically generated, avoiding the necessity to create a mirrored version of an image and further maintenance costs. 58

62 Chapter 9. Right To Left (RTL) Framework The web resource filter uses the same naming pattern as the skin service. When an image ends with the -rt suffix the portal will attempt to locate the original image and create a mirror of it. For instance: requesting the image JBOSS_HOME/server/<PROFILE>/deploy/gatein.ear/01eXoResources.war/skin/DefaultS kin/webui/com ponent/uit absystem/uit abs/background/norm alt abstyle-rt.gif returns a mirror of the image JBOSS_HOME/server/<PROFILE>/deploy/gatein.ear/01eXoResources.war/skin/DefaultS kin/webui/com ponent/uit absystem/uit abs/background/norm alt abstyle.gif. Note It is important to consider whether the image to be mirrored is symmetrical as this will impact it's final appearance. Here is an example combining stylesheet and images: line-height: 24px; background: url('background/navigationtab.gif') no-repeat right top; /* orientation=lt */ background: url('background/navigationtab-rt.gif') no-repeat left top; /* orientation=rt */ padding-right: 2px; /* orientation=lt */ padding-left: 2px; /* orientation=rt */ 9.4. Client Side JavaScript T he exo.core.i18n object provides the following parameters for orientation: getorientation() Returns either the string lt or rt getdir() Returns either the string ltr or rtl islt() Returns true for LT isrt() Returns true of RT 59

63 Red Hat JBoss Portal 5.1 Reference Guide Chapter 10. XML Resources Bundles Overview Resource bundles are usually stored in property files. However, as property files are plain files, issues with the encoding of the file may arise. The XML resource bundle format has been developed to provide an alternative to property files. The XML format declares the encoding of the file. This avoids use of the native2ascii program which can interfere with encoding. Property files generally use ISO character encoding which does not cover the full unicode charset. As a result, languages such as Arabic would not be natively supported. Tooling for XML files is better supported than the tooling for Java property files and thus the XML editor copes well with the file encoding XML format The XML format is very simple and has been developed based on the 'Don't Repeat Yourself' (DRY) principle. Usually resource bundle keys are hierarchically defined and we can leverage the hierarchic nature of the XML for that purpose. Here is an example of turning a property file into an XML resource bundle file: UIAccountForm.tab.label.AccountInputSet =... UIAccountForm.tab.label.UIUserProfileInputSet =... UIAccountForm.label.Profile =... UIAccountForm.label.HomeInfo=... UIAccountForm.label.BusinessInfo=... UIAccountForm.label.password=... UIAccountForm.label.Confirmpassword=... UIAccountForm.label. =... UIAccountForm.action.Reset=... <?xml version="1.0" encoding="utf-8"?> <bundle> <UIAccountForm> <tab> <label> <AccountInputSet>...</AccountInputSet> <UIUserProfileInputSet>...</UIUserProfileInputSet> </label> </tab> <label> <Profile>...</Profile> <HomeInfo>...</HomeInfo> <BusinessInfo>...</BusinessInfo> <password>...</password> <Confirmpassword>...</Confirmpassword> < >...</ > </label> <action> <Reset>...</Reset> </action> </UIAccountForm> </bundle> 60

64 Chapter 10. XML Resources Bundles Portal Support In order to be loaded by the portal at runtime (actually the resource bundle service), the name of the file must be the same as a property file and it must use the.xml suffix. For example; for the Account Portlet to be displayed in Arabic, the resource bundle would be AccountPortlet_ar.xml rather than AccountPortlet_ar.properties. 61

65 Red Hat JBoss Portal 5.1 Reference Guide Chapter 11. JavaScript Inter Application Communication Overview JavaScript Inter Application Communication is designed to allow applications within a page to exchange data. T his library is made for broadcasting messages on topic. It is based on three functions: Subscribe. Publish. Unsubscribe. A subscription to a topic will receive any subtopic messages. For example, an application subscribed to "/exo/application" will receive messages sent on the "/exo/application/m ap" topic. A message sent on "/exo", however, would not be received. Subscription T opics /exo T his topic contains all the events generated by the platform. /exo/portal/notification A message is sent on this topic will prompt a pop-up notification in the top right of the screen Library The Inter Application Communication library is found in 01eXoResources.war:/javascript/eXo/core/T opic.js 62

66 Chapter 11. JavaScript Inter Application Communication /** * publish is used to publish an event to the other subscribers to the given channels param {Object} senderid is a string that identify the sender param {String} topic is the topic that the message will be published {Object} message is the message that's going to be delivered to the subscribers to the topic */ Topic.prototype.publish = function(/*object*/ senderid, /*String*/ topicname, /*Object*/ message ) {... } /** * issubscribed is used to check if a function receive the events from a topic param {String} topic The topic. {Function} func is the name of the function of obj to call when a message is received on the topic */ Topic.prototype.isSubscribed = function(/*string*/ topic, /*Function*/ func) {... } /** * subscribe is used to subscribe a callback to a topic param {String} topic is the topic that will be listened {Function} func is the name of the function of obj to call when a message is received on the topic * * func is a function that take a Object in parameter. the event received have this format: * {senderid:senderid, message:message, topic: topic} * */ Topic.prototype.subscribe = function(/* String*/ topic, /* Function*/ func) {... } /** * unsubscribe is used to unsubscribe a callback to a topic param {String} topic is the topic param {Object} id is the id of the listener we want to unsubscribe */ Topic.prototype.unsubscribe = function(/* String*/ topic, /* Object*/ id) {... } Topic.prototype.initCometdBridge = function() {... } Syntax T he three messaging functions require particular objects and definitions in their syntax: Subscribe The subscribe function is used to subscribe a callback to a topic. It uses the following parameters: topic The topic that will be listened for. func The name of the object function to call when a message is received on the topic. It has to be a function that takes an Object parameter. The event received will have this 63

67 Red Hat JBoss Portal 5.1 Reference Guide format: { } senderid:senderid, message:message, topic: topic Publish T he publish function is used to publish an event to the other subscribed applications through the given channels. Its parameters are: senderid This is a string that identifies the sender. topicname The topic that the message will be published. message This is the message body to be delivered to the subscribers to the topic. Unsubscribe The unsubscribe function is used to unsubscribe a callback to a topic. The required parameters are: topic The topic that will is to be unsubscribed from. id This is the context object Example of Javascript events usage 64

68 Chapter 11. JavaScript Inter Application Communication taglib uri=" prefix="portlet" %> <portlet:defineobjects/> <div> <p> Received messages: <div id="received_<portlet:namespace/>"> </div> </p> <p> Send message: <input type="text" id="msg_<portlet:namespace/>"/> <a href="#" onclick="send_<portlet:namespace/>();">send</a> </p> </div> <script type="text/javascript"> Function.prototype.bind = function(object) { var method = this; return function() { method.apply(object, arguments); } } function send_<portlet:namespace/>() { var msg = document.getelementbyid("msg_<portlet:namespace/>").value; exo.core.topic.publish("<portlet:namespace/>", "/demo", msg); } function Listener_<portlet:namespace/>(){ } Listener_<portlet:namespace/>.prototype.receiveMsg = function(event) { document.getelementbyid("received_<portlet:namespace/>").innerhtml = document.getelementbyid("received_<portlet:namespace/>").innerhtml + "<br />* " + event.senderid + ": " + event.message; } function init_<portlet:namespace/>() { var listener_<portlet:namespace/> = new Listener_<portlet:namespace/>(); exo.core.topic.subscribe("/demo", listener_<portlet:namespace/>.receivemsg.bind(listener_<portlet:namespace/>)); } init_<portlet:namespace/>(); </script> 65

69 Red Hat JBoss Portal 5.1 Reference Guide Part II. Portlet development 66

70 Chapter 12. Portlet Primer Chapter 12. Portlet Primer JSR-168 and JSR-286 overview T he Java Community Process (JCP) uses Java Specification Requests (JSRs) to define proposed specifications and technologies designed for the Java platform. T he Portlet Specifications aim at defining portlets that can be used by any JSR-168 (Portlet 1.0) or JSR- 286 (Portlet 2.0) portlet container. Most Java EE (Enterprise Edition) portals include at least one compliant portlet container, and JBoss Enterprise Portal Platform is no exception. In fact, JBoss Enterprise Portal Platform includes a container that supports both versions. T his chapter gives a brief overview of the Portlet Specifications but portlet developers are strongly encouraged to read the JSR-286 Portlet Specification. JBoss Enterprise Portal Platform is fully JSR-286 compliant. Any JSR-168 or JSR-286 portlet operates as it is mandated by the respective specifications inside the portal Portal Pages A portal can be considered as a series of web pages with different areas within them. Those areas contain different windows and each window contains a portlet: T he diagram below visually represents this nesting: Rendering Modes A portlet can have different view modes. T hree modes are defined by the JSR-286 specification: View Generates markup reflecting the current state of the portlet. 67

71 Red Hat JBoss Portal 5.1 Reference Guide Generates markup reflecting the current state of the portlet. Edit Allows a user to customize the behavior of the portlet. Help Provides information to the user as to how to use the portlet Window States Window states are an indicator of how much page space a portlet consumes on any given page. The three states defined by the JSR-286 specification are: Normal A portlet shares this page with other portlets. Minimized A portlet may show very little information, or none at all. Maximized A portlet may be the only portlet displayed on this page Tutorials T he tutorials contained in this chapter are targeted toward portlet developers. It is also recommend that developers read and understand the JSR-286 Portlet Specification. Maven This example is using Maven to compile and build the web archive. Maven versions can be downloaded from maven.apache.org Deploying your first Portlet T his section describes how to deploy a portlet in JBoss Enterprise Portal Platform. An example portlet called Sim plesthelloworld is available in the /jboss-epp-<version>src/portal/exam ples/portlets/ directory of the JBoss Enterprise Portal Platform sources package or the jboss-epp-<version>-docs/epp-doc/exam ples/portlets directory of the documentation package Compiling T o compile and package the application: 1. Navigate to the application directory and execute: 68

72 Chapter 12. Portlet Primer mvn package 2. If the example is successfully packaged, the result will be available in: sim plesthelloworld/target/gatein-sim plest-helloworld ga- SNAPSHOT.war. 3. Copy the package file into JBOSS_HOME/server/default/deploy. 4. Start JBoss Application Server (if it is not already running). 5. Add the new portlet to the Application Registry. 6. Create a new portal page and add the portlet to it Package Structure Like other Java EE applications, JBoss Enterprise Portal Platform portlets are packaged in WAR files. A typical portlet WAR file can include servlets, resource bundles, images, HT ML, JavaServer Pages (JSP), and other static or dynamic files. T he following is an example of the directory structure of the Sim plesthelloworld portlet: -- SimplestHelloWorld war `-- WEB-INF -- classes `-- org `-- jboss `-- portal `-- portlet `-- samples `-- SimplestHelloWorldPortlet.class -- portlet.xml `-- web.xml T he compiled Java class implementing javax.portlet.portlet (through javax.portlet.genericportlet ) T his is the mandatory descriptor file for portlets. It is used during deployment. T his is the mandatory descriptor for web applications Portlet Class Below is the Java source for an example portlet named sim plesthelloworld/src/m ain/java/org/jboss/portal/portlet/sam ples: 69

73 Red Hat JBoss Portal 5.1 Reference Guide package org.jboss.portal.portlet.samples; import java.io.ioexception; import java.io.printwriter; import javax.portlet.genericportlet; import javax.portlet.renderrequest; import javax.portlet.renderresponse; public class SimplestHelloWorldPortlet extends GenericPortlet { public void doview(renderrequest request, RenderResponse response) throws IOException { } } PrintWriter writer = response.getwriter(); writer.write("hello World!"); writer.close(); All portlets must implement the javax.portlet.portlet interface. T he portlet API provides a convenient implementation of this interface. T he javax.portlet.portlet interface uses the javax.portlet.genericportlet class which implements the Portlet render method to dispatch to abstract mode-specific methods. This makes it easier to support the standard portlet modes. Portlet render also provides a default implementation for the processaction, init and destroy methods. It is recommended to extend GenericPortlet for most cases. If only the view mode is required, then only the doview method needs to be implemented. The GenericPortlet render implementation calls our implementation when the view mode is requested. Use the RenderResponse to obtain a writer to be used to produce content. Write the markup to display. Closing the writer. Markup Fragments Portlets are responsible for generating markup fragments, as they are included on a page and are surrounded by other portlets. This means that a portlet outputting HTML must not output any markup that cannot be found in a <body> element Application Descriptors JBoss Enterprise Portal Platform requires certain descriptors to be included in a portlet WAR file. T hese descriptors are defined by the Java EE (web.xm l) and Portlet Specification (portlet.xm l). Below is an example of the Sim plesthelloworldportlet/web-inf/portlet.xm l file. T his file 70

74 Chapter 12. Portlet Primer must adhere to its definition in the JSR-286 Portlet Specification. More than one portlet application may be defined in this file: <portlet-app xmlns=" xmlns:xsi=" xsi:schemalocation=" version="2.0"> <portlet> <portlet-name>simplesthelloworldportlet</portlet-name> <portlet-class> org.jboss.portal.portlet.samples.simplesthelloworldportlet </portlet-class> <supports> <mime-type>text/html</mime-type> </supports> <portlet-info> <title>simplest Hello World Portlet</title> </portlet-info> </portlet> </portlet-app> Define the portlet name. It does not have to be the class name. The Fully Qualified Name (FQN) of your portlet class must be declared here. The <supports> element declares all of the markup types that a portlet supports in the render method. This is accomplished via the <mime-type> element, which is required for every portlet. T he declared MIME types must match the capability of the portlet. It allows administrators to pair which modes and window states are supported for each markup type. This does not have to be declared as all portlets must support the view portlet mode. Use the <mime-type> element to define which markup type the portlet supports. In the example above this is text/html. This section tells the portal to only output HTML. When rendered, the portlet's title is displayed as the header in the portlet window, unless it is overridden programmatically. In the example above the title would be Simplest Hello World Portlet JavaServer Pages Portlet Example T his section discusses: 1. Adding more features to the previous example. 2. Using a JSP page to render the markup. 3. Using the portlet tag library to generate links to the portlet in different ways. 4. Using the other standard portlet modes. Compiling the example T he example used in this section is available in the /jboss-epp-<version>src/portal/exam ples/portlets/ directory of the JBoss Enterprise Portal Platform sources package or the /jboss-epp-<version>-docs/epp-doc/exam ples/portlets directory of the documentation package. 71

75 Red Hat JBoss Portal 5.1 Reference Guide Compile the example as so: 1. Execute: mvn package in the jsphellouser directory. 2. Copy jsphellouser/target/gatein-jsp-hellouser ga-snapshot.war to the deploy directory of JBoss Application Server. 3. Add the new portlet to the Application Registry. 4. Create a new portal page and add the portlet to it Package Structure T he package structure in this tutorial does not differ greatly from the previous example, with the exception of adding some JSP files which are detailed later. T he JSPHelloUser portlet contains the mandatory portlet application descriptors. T he following is an example of the directory structure of the JSPHelloUser portlet: gatein-jsp-hellouser->1.0.0-ga-snapshot.war -- META-INF -- MANIFEST.MF -- WEB-INF -- classes `-- org `-- jboss `-- portal `-- portlet `-- samples `-- JSPHelloUserPortlet.class -- portlet.xml `-- web.xml `-- jsp -- edit.jsp -- hello.jsp -- help.jsp `-- welcome.jsp Portlet Class 72

76 Chapter 12. Portlet Primer The code below is from the jsphellouser/src/m ain/java/org/jboss/portal/portlet/sam ples/jsphellouserport let.java Java source. It is split in different pieces. package org.jboss.portal.portlet.samples; import java.io.ioexception; import javax.portlet.actionrequest; import javax.portlet.actionresponse; import javax.portlet.genericportlet; import javax.portlet.portletexception; import javax.portlet.portletrequestdispatcher; import javax.portlet.renderrequest; import javax.portlet.renderresponse; import javax.portlet.unavailableexception; public class JSPHelloUserPortlet extends GenericPortlet { public void doview(renderrequest request, RenderResponse response) throws PortletException, IOException { String syourname = (String) request.getparameter("yourname"); if (syourname!= null) { request.setattribute("yourname", syourname); PortletRequestDispatcher prd = getportletcontext().getrequestdispatcher("/jsp/hello.jsp"); prd.include(request, response); } else { PortletRequestDispatcher prd = getportletcontext().getrequestdispatcher("/jsp/welcome.jsp"); prd.include(request, response); } }... Override the doview method (as in the first tutorial). This entry attempts to obtain the value of the render parameter named yourname. If defined it should redirect to the hello.jsp JSP page, otherwise to the welcom e.jsp JSP page. Get a request dispatcher on a file located within the web archive. Perform the inclusion of the markup obtained from the JSP. As well as the VIEW portlet mode, the specification defines two other modes; EDIT and HELP. These modes need to be defined in the portlet.xml descriptor. This will enable the corresponding buttons on the portlet's window. T he generic portlet that is inherited dispatches the different views to the methods: doview, dohelp and doedit. 73

77 Red Hat JBoss Portal 5.1 Reference Guide... protected void dohelp(renderrequest rrequest, RenderResponse rresponse) throws PortletException, IOException, UnavailableException { rresponse.setcontenttype("text/html"); PortletRequestDispatcher prd = getportletcontext().getrequestdispatcher("/jsp/help.jsp"); prd.include(rrequest, rresponse); } protected void doedit(renderrequest rrequest, RenderResponse rresponse) throws PortletException, IOException, UnavailableException { rresponse.setcontenttype("text/html"); PortletRequestDispatcher prd = getportletcontext().getrequestdispatcher("/jsp/edit.jsp"); prd.include(rrequest, rresponse); }... Portlet calls happen in one or two phases. One when the portlet is rendered and two when the portlet is actioned then rendered. An action phase is a phase where a state changes. The render phase will have access to render parameters that will be passed each time the portlet is refreshed (with the exception of caching capabilities). The code to be executed during an action has to be implemented in the processaction method of the portlet.... public void processaction(actionrequest arequest, ActionResponse aresponse) throws PortletException, IOException, UnavailableException { String syourname = (String) arequest.getparameter("yourname"); aresponse.setrenderparameter("yourname", syourname); }... processaction is the method from GenericPortlet to override for the action phase. Here the parameter is retrieved through an action URL. The value of yourname is kept to make it available in the rendering phase. The previous line simply copies an action parameter to a render parameter for this example JSP files and the Portlet Tag Library The help.jsp and edit.jsp files are very simple. Note that CSS styles are used as defined in the portlet specification. T his ensures that the portlet will render well within the theme and across portal vendors. <div class="portlet-section-header">help mode</div> <div class="portlet-section-body">this is the help mode, a convenient place to give the user some help information.</div> 74

78 Chapter 12. Portlet Primer <div class="portlet-section-header">edit mode</div> <div class="portlet-section-body">this is the edit mode, a convenient place to let the user change his portlet preferences.</div> The landing page contains the links and form to call our portlet: <%@ taglib uri=" prefix="portlet" %> <div class="portlet-section-header">welcome!</div> <br/> <div class="portlet-font">welcome on the JSP Hello User portlet, my name is GateIn Portal. What's yours?</div> <br/> <div class="portlet-font">method 1: We simply pass the parameter to the render phase:<br/> <a href="<portlet:renderurl><portlet:param name="yourname" value="john Doe"/> <br/> </portlet:renderurl>">john Doe</a></div> <div class="portlet-font">method 2: We pass the parameter to the render phase, using valid XML: Please check the source code to see the difference with Method 1. <portlet:renderurl var="myrenderurl"> <portlet:param name="yourname" value='john Doe'/> </portlet:renderurl> <br/> <a href="<%= myrenderurl %>">John Doe</a></div> <br/> <div class="portlet-font">method 3: We use a form:<br/> <portlet:actionurl var="myactionurl"/> <form action="<%= myactionurl %>" method="post"> </form> </div> <span class="portlet-form-field-label">name:</span> <input class="portlet-form-input-field" type="text" name="yourname"/> <input class="portlet-form-button" type="submit"/> The portlet taglib. This needs to be declared. T he first method showed here is the simplest one. portlet:renderurl will create a URL that calls the render phase of the current portlet and append the result at the place of the markup (within a tag). A parameter is also added directly to the URL. In this method the var attribute is used. This avoids having one XML tag within another. Instead 75

79 Red Hat JBoss Portal 5.1 Reference Guide of printing the url the portlet:renderurl tag will store the result in the referenced variable ( myrenderurl). T he variable m yrenderurl is used like any other JSP variable. T he third method mixes form submission and action request. Again, a temporary variable is used to put the created URL into. The action URL is used in HTML form. In the third method the action phase is triggered first then the render phase is triggered, which outputs some content back to the web browser based on the available render parameters JSF example using the JBoss Portlet Bridge In order to write a portlet using JSF a 'bridge' is needed. This software allows developers to write a portlet application as if it was a JSF application. T he bridge then negotiates the interactions between the two layers. An example using the JBoss Portlet Bridge is available in the /jboss-epp-<version>src/portal/exam ples/portlets/ directory of the JBoss Enterprise Portal Platform sources package or the /jboss-epp-<version>-docs/epp-doc/exam ples/portlets directory of the documentation package. T he configuration is slightly different from a JSP application. T his example can be used as a base to configure instead of creating a new application. As in any JSF application, the file faces-config.xm l is required. It must contain the following information: <faces-config>... <application> <view-handler>org.jboss.portletbridge.application.portletviewhandler</viewhandler> <statemanager>org.jboss.portletbridge.application.portletstatemanager</state-manager> </application>... </faces-config> T he portlet bridge libraries must be available and are usually bundled with the WEB-INF/lib directory of the web archive. T he other differences when compared to a regular portlet application are in the portlet descriptor. All the relevant details about this can be found in the JSR-301 specification that the JBoss Portlet Bridge implements. 76

80 Chapter 12. Portlet Primer <?xml version="1.0" encoding="utf-8"?> <portlet-app xmlns=" xmlns:xsi=" xsi:schemalocation=" version="2.0"> <portlet> <portlet-name>jsfhellouserportlet</portlet-name> <portlet-class>javax.portlet.faces.genericfacesportlet</portlet-class> <supports> <mime-type>text/html</mime-type> <portlet-mode>view</portlet-mode> <portlet-mode>edit</portlet-mode> <portlet-mode>help</portlet-mode> </supports> <portlet-info> <title>jsf Hello User Portlet</title> </portlet-info> <init-param> <name>javax.portlet.faces.defaultviewid.view</name> <value>/jsf/welcome.jsp</value> </init-param> <init-param> <name>javax.portlet.faces.defaultviewid.edit</name> <value>/jsf/edit.jsp</value> </init-param> <init-param> <name>javax.portlet.faces.defaultviewid.help</name> <value>/jsf/help.jsp</value> </init-param> </portlet> </portlet-app> All JSF portlets define javax.portlet.faces.genericfacesportlet as portlet class. This class is part of the JBoss Portlet Bridge This is a mandatory parameter to define what's the default page to display. This parameter defines which page to display on the 'edit' mode. This parameter defines which page to display on the 'help' mode. JBoss Portlet Bridge For more information about the JBoss Portlet Bridge, see the dedicated chapter which is part of this document. 77

81 Red Hat JBoss Portal 5.1 Reference Guide Chapter 13. Building JSF Portlets JBoss Portlet Bridge Overview What is the JBoss Portlet Bridge? T he JBoss Portlet Bridge (or JBPB for short) is a non-final implementation of the JSR-329 specification. It supports the JSF 1.2 runtime within a JSR 286 portlet and with added enhancements to support other web frameworks (such as Seam and RichFaces). It allows any Java developer to quickly get started with their JSF web application running in a portal environment. T he developer no longer needs to worry about the underlying portlet development, portlet concepts, or the API. Find more information about the JBoss Portlet Bridge, the developers, the community at the project page. Understanding how JSF works with Portal The portlet bridge is not a portlet. It is the mediator between the two environments and allows JSF and Portal to be completely unaware of each other. The bridge is used to execute Faces requests on behalf of the portlet. During each request, the Faces environment is setup and handled by the bridge. Part of this implementation acts as a Faces controller much as the FacesServlet does in the direct client request environment. T he other part of this implementation is provided by implementing a variety of (standard) Faces extensions. Disclaimer T his draft specification for the JSR 329 specification is not final. Any final specification that may be published will likely contain differences, some of which may be substantial. Publication of this draft specification is not intended to provide the basis for implementations of the specification. T his draft specification is provided AS IS. THERE ARE NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF CONDITION OF TITLE OR NONINFRINGEMENT. You may copy and display this draft specification provided that you include this notice and any existing copyright notice. Except for the limited copyright license granted above, there are no other licenses granted to any intellectual property owned or controlled by any of the authors or developers of this material. No other rights are granted by implication, estoppel or otherwise Getting started with JBoss Portlet Bridge JBoss Portlet Bridge not only gives you the ability to run JSF web applications in a portlet, but also gives you the benefit of running supported JBoss frameworks like Seam and RichFaces What's New in 2.0? 78

82 Chapter 13. Building JSF Portlets Eventing The bridge considers a portlet event a model event. The event is targeted to the applications data model, not its view. As JSF events primarily concern its view, the bridge processes the portlet events manually, however provisions are made to ensure that any model changes resulting from processing the event are updated in the view. Since event payloads are arbitrarily complex, the manual processing of the data, though managed by the bridge, is left to the (portlet) application to support. See Section , Sending and Receiving Events for details and examples Portlet Served Resources The bridge deals with portlet served resources in one of two ways: If the request is for a non-jsf resource, the bridge handles the request by acquiring a request dispatcher and forwarding the request to the named resource. If the request is for a JSF resource, the bridge runs the full JSF life-cycle ensuring that data is processed and the resource (markup) is rendered. See Section , Serving Your JSF Resources in a Portlet for details and examples Public Render Parameters T he bridge automates the processing of public render parameters. A public render parameter can be mapped to an object's accessor (get/set method) designed to handle a String representation of the value via a Faces ValueExpression. When a new public render parameter value is received in a request, the bridge sets the value by calling the ValueExpression's setvalue(). At the end of a request, if the current value of any mapped public render parameter doesn't match the current incoming value, the bridge sets the new value in an outgoing public render parameter (if feasible in the given phase). See Section , Public Render Parameters for details and examples Bridge Frameworks and Extensions T he JBoss Portlet Bridge currently supports JBoss Enterprise Portal Platform, GateIn, JSF 1.2, JBoss Seam, and JBoss Richfaces. T here are configurations that apply to supporting each framework. See section Section 13.3, Bridge Configuration for instructions. T he JBoss Portlet Bridge project is also actively developing extensions called "Bridgelets". In this release it was decided to bring all available bridgelets into the impl code base since they are critical in most JSF portlet applications. A single line of configuration utilizes these features Seam Bridgelets For example, the PortalIdentity Seam component allows you to instantly have Single Sign-On (SSO) between Seam and GateIn or JBoss Enterprise Portal Platform. T his extension is configured in your Seam application's com ponents.xm l file as follows. 79

83 Red Hat JBoss Portal 5.1 Reference Guide <security:portal-identity authenticate-method="#{authenticator.authenticate}"/> RichFaces Bridgelets Richfaces does not account for multiple components on the same portal page by default. This following web.xm l renders all RichFaces component javascript portal-friendly. <context-param> <param-name>org.jboss.portletbridge.wrap_scripts</param-name> <param-value>true</param-value> </context-param> Before You Start T he embedded version in the JBoss Enterprise Portal Platform is made to be compatible with the JSF implementation, portal and application server that compose the product. You will find the binaries embedded in jboss-epp-<version>/portletbridge You can run a provided archetype and deploy the generated war or ear in a few easy steps Bridge Configuration T he 329 specification is aimed at making the developer's life as easy as possible with JSF+Portlet development. You will see below that there are minimal settings to getting any JSF web application up and running in the Portal environment Core Setup and Configuration portlet.xml T he basic JSR-329 portlet configuration. <portlet> <portlet-name>yourportletname</portlet-name> <portlet-class> javax.portlet.faces.genericfacesportlet </portlet-class> <init-param> <name>javax.portlet.faces.defaultviewid.view</name> <value>/welcome.xhtml</value> </init-param> <init-param> <name>javax.portlet.faces.defaultviewid.edit</name> <value>/jsf/edit.xhtml</value> </init-param> <init-param> <name>javax.portlet.faces.defaultviewid.help</name> <value>/jsf/help.xhtml</value> </init-param> When preserveactionparams is set to TRUE, the bridge must maintain any request parameters assigned during the portlet's action request. 80

84 Chapter 13. Building JSF Portlets T he request parameters are maintained in the "bridge request scope". When this attribute is not present or is FALSE the action's request parameters are only maintained for the duration of the portlet request scope. <init-param> <name>javax.portlet.faces.preserveactionparams</name> <value>true</value> </init-param> faces-config.xml T he PortletViewHandler ensures that each JSF portlet instance is properly namespaced. <faces-config> <application> <view-handler> org.jboss.portletbridge.application.portletviewhandler </view-handler> <statemanager>org.jboss.portletbridge.application.portletstatemanager</state-manager> </application> Facelets Configuration T he following web.xm l setting is only for Facelets based applications web.xml <web-app xmlns=" xmlns:xsi=" xsi:schemalocation=" version="2.4">... <!-- This is optional parameters for a facelets based application --> <context-param> <param-name>org.ajax4jsf.view_handlers</param-name> <paramvalue>org.jboss.portletbridge.application.faceletportletviewhandler</param-value> </context-param> <context-param> <param-name>javax.portlet.faces.render_policy</param-name> <param-value> ALWAYS_DELEGATE </param-value> </context-param>... </web-app> RenderPolicy Options ALWAYS_DELEGAT E Indicates the bridge should not render the view itself but rather always delegate the rendering. 81

85 Red Hat JBoss Portal 5.1 Reference Guide NEVER_DELEGAT E Indicates the bridge should always render the view itself and never delegate. DEFAULT Directs the bridge to first delegate the render only if an Exception is thrown then render the view based on its own logic. If the configuration parameter is not present or has an invalid value the bridge renders using default behavior as it would if DEFAULT was set JSP Only Configuration T he following web.xm l setting is only for JSP based applications. Download the demonstration application here web.xml <web-app xmlns=" xmlns:xsi=" xsi:schemalocation=" version="2.4"> <context-param> <param-name>javax.portlet.faces.render_policy </param-name> <param-value> NEVER_DELEGATE </param-value> </context-param>... </web-app> RichFaces Setup and Configuration Options web.xml T he following configuration is designated for portlets using the RichFaces library. T hese settings will vary based on your individual needs. See this section of the RichFaces documentation for more details. Sometimes it is better to use the "ALL" load strategy in portlets so you do not need to worry about loading the "framework.pack.js" and "ui.pack.js" files manually in your portlet header. <context-param> <param-name>org.richfaces.loadstylestrategy</param-name> <param-value>all</param-value> </context-param> <context-param> <param-name>org.richfaces.loadscriptstrategy</param-name> <param-value>all</param-value> </context-param> 82

86 Chapter 13. Building JSF Portlets Note If you use the "NONE" strategy, you must include the following scripts in your portlet or portal page header. If you are using JBoss Portal, you can add this to the jboss-portlet.xml file. T he org.ajax4 jsf.resource_uri_prefix configuration cross-references the path to your scripts below. T hese settings are required for RichFaces using the "NONE" strategy. <script src="/faces/rfres/org/ajax4jsf/framework.pack.js" type="text/javascript"></script> <script src="/faces/rfres/org/richfaces/ui.pack.js" type="text/javascript"></script> <link rel="stylesheet" type="text/css" href="/faces/rfres/org/richfaces/skin.xcss"/> Seam automatically configures your Ajax4JSF Filter, so if you are running a Seam portlet, you do not need the following Filter configuration (however, you do need the RESOURCE_URI_PREFIX no matter what). <context-param> <param-name>org.ajax4jsf.resource_uri_prefix</param-name> <param-value>rfres</param-value> </context-param> <filter> <display-name>ajax4jsf Filter</display-name> <filter-name>ajax4jsf</filter-name> <filter-class>org.ajax4jsf.filter</filter-class> </filter> <filter-mapping> <filter-name>ajax4jsf</filter-name> <servlet-name>facesservlet</servlet-name> <dispatcher>forward</dispatcher> <dispatcher>request</dispatcher> <dispatcher>include</dispatcher> </filter-mapping>... </web-app> Configuration needed for Richfaces to work with WSRP and PortletBridge Use the following settings in web.xm l when running WSRP portlets: 83

87 Red Hat JBoss Portal 5.1 Reference Guide <context-param> <param-name>org.jboss.portletbridge.wrap_scripts</param-name> <param-value>false</param-value> </context-param>... <context-param> <param-name>org.richfaces.loadstylestrategy</param-name> <param-value>all</param-value> </context-param> <context-param> <param-name>org.richfaces.loadscriptstrategy</param-name> <param-value>default</param-value> </context-param> The styles below must also be manually added to the facelets template header in the JBOSS_HOME/portletbridge/exam ples/richfacesportlet-<version>.war:richfacespor tlet.war/tem plates/m ain.xhtm l file. <link rel="stylesheet" type="text/css" href="/richfacesportlet/faces/rfresorg/richfaces/renderkit/html/css/basic_both.xcss "/> <link rel="stylesheet" type="text/css" href="/richfacesportlet/faces/rfresorg/richfaces/renderkit/html/css/extended_both. xcss"/> <link rel="stylesheet" type="text/css" href="/richfacesportlet/faces/rfres/org/richfaces/skin.xcss"/> The table below outlines the current status of RichFaces features when used in both local and remote portlets. 84

88 Chapter 13. Building JSF Portlets T able RichFaces Feature Status Richfaces Component Supported as Local Portlet Supported as Remote Portlet using WSRP a4 j:com m andbutton Yes Yes a4 j:com m andlink Yes Yes a4 j:jsfunction Yes Yes a4 j:push Yes Yes a4 j:poll Yes Yes a4 j:queue No No a4 j:status Yes Yes a4 j:keepalive Yes Yes a4 j:include Yes Yes a4 j:loadstyle No No a4 j:loadscript Yes Yes a4 j:ajaxvalidator Yes Yes a4 j:beanvalidator Yes Yes a4 j:graphvalidator Yes Yes a4 j:m ediaoutput No Yes a4 j:outputpanel Yes (except Firefox 3.5) Yes a4 j:log Yes Yes rich:datat able Yes (except Firefox 3.6 and IE8) No a4 j:datafilterslider Yes Yes rich:datagrid Yes No rich:datalist Yes Yes rich:datascroller No No rich:extendeddatat able Yes (except IE7) No rich:repeat Yes Yes rich:scrollabledatat abl e Yes (except Firefox 3.6) Yes drag-drop support Yes Yes rich:contextmenu No No rich:dropdownmenu Yes Yes rich:tree Yes (except Firefox 3.5) Yes rich:m odalpanel Yes Yes rich:paint2d Yes Yes rich:panel Yes Yes rich:panelbar Yes Yes rich:panelmenu Yes Yes rich:progressbar Yes Yes rich:separator Yes Yes rich:sim plet ogglepanel Yes Yes rich:spacer Yes Yes 85

89 Red Hat JBoss Portal 5.1 Reference Guide rich:tabpanel Yes Yes (except tab deletion) rich:togglepanel Yes Yes rich:toolbar Yes Yes rich:toolt ip Yes Yes rich:calendar Yes No rich:colorpicker Yes Yes rich:com bobox Yes Yes rich:editor No No rich:fileupload No No rich:inplaceselect Yes Yes rich:inplaceinput Yes Yes rich:inputnum berspinner Yes (except IE7) Yes rich:inputnum berslider Yes Yes rich:suggestionbox Yes Yes rich:listshuttle Yes Yes rich:orderinglist Yes Yes rich:picklist Yes Yes Seam Setup and Configuration Options Configuration T he ExceptionHandler is used to clean Seam contexts and transactions after errors. <context-param> <param-name>org.jboss.portletbridge.exceptionhandler</param-name> <param-value> org.jboss.portletbridge.seamexceptionhandlerimpl </param-value> </context-param> Portlet 2.0 Coordination Schema and XSD Definitions It is important to ensure, before using either of the following mechanisms, that the proper 2.0 schema and xsd are defined at the top of your portlet.xml. <portlet-app xmlns=" version="2.0" xmlns:xsi=" xsi:schemalocation=" Sending and Receiving Events 86

90 Chapter 13. Building JSF Portlets Configuration Just like with any portlet 2.0 event consumer and receiver, you must define them in the portlet.xm l. You must also define the following init params in your portlet.xm l. <init-param> <name>javax.portlet.faces.autodispatchevents</name> <value>true</value> </init-param> <init-param> <name>javax.portlet.faces.bridgeeventhandler</name> <value>org.foo.eventhandler</value> </init-param> While future versions of the 2.0 bridge will automate the dispatching and consuming of events, at the moment you must dispatch the event in the JSF or Seam backing bean. if (response instanceof StateAwareResponse) { StateAwareResponse stateresponse = (StateAwareResponse) response; stateresponse.setevent(foo.qname, new Bar()); } You must also create the event handler class by implementing the BridgeEventHandler interface to process the event payload. public class BookingEventHandler implements BridgeEventHandler { public EventNavigationResult handleevent(facescontext context, Event event) { //process event payload here } } Public Render Parameters Configuration Public Render Parameters (or PRPs) are one of the most powerful and simple Portlet 2.0 features. Several portlets (JSF or otherwise) can share the same render parameters. T his feature can be used to present a cohesive UI to the user across all portlets on the page. An example would be using an employee ID to display relative data. The bridge maps a render parameter to a backing bean using settings in your faces-config.xml and portlet.xm l. A clear and working example can be found in the Seam Booking Demo portlet. You must define the following init params in your portlet.xm l. 87

91 Red Hat JBoss Portal 5.1 Reference Guide <init-param> <name>javax.portlet.faces.bridgepublicrenderparameterhandler</name> <value>org.foo.prphandler</value> </init-param>... <supported-public-render-parameter>mycoolprp</supported-public-render-parameter> Create a managed bean and public-param eter-m appings in your faces-config.xm l. T his should be a basic bean that you can bind the passed parameter to a string with getter and setter. <managed-bean> <managed-bean-name>bookingprp</managed-bean-name> <managed-bean-class>your.class.name</managed-bean-class> <managed-bean-scope>session</managed-bean-scope> </managed-bean> <application> <application-extension> <bridge:public-parameter-mappings> <bridge:public-parameter-mapping> <parameter>"the name of your portlet":hotelname</parameter> <model-el>#{bookingprp.hotelname}</model-el> </bridge:public-parameter-mapping> </bridge:public-parameter-mappings> </application-extension> </application> You must set the parameter in the JSF or Seam backing bean, if you are providing one from your portlet. if (response instanceof StateAwareResponse) { StateAwareResponse stateresponse = (StateAwareResponse) response; stateresponse.setrenderparameter("hotelname",selectedhotel.getname()); } T hen you must also implement the BridgePublicRenderParam eterhandler interface to process any updates from the received parameter. public void processupdates(facescontext context) { ELContext elcontext = context.getelcontext(); BookingPRPBean bean = (BookingPRPBean) elcontext.getelresolver().getvalue(elcontext, null, "bookingprp"); if(null!= bean){ //Do something with bean.gethotelname()); } else { } } Serving Your JSF Resources in a Portlet Configuration We have setup a few examples to show you how to use EL and a simple bean that will allow you to use the portlet resource serving mechanism within a JSF portlet. 88

92 Chapter 13. Building JSF Portlets In ResourceBean.java, you can see a very simple implementation of a Map object that uses the bridge to get and encode a resource url served from the portlets web application. So, when you have the normal "/images", "/styles" and other resource folders in your web application, you can use the following EL expression to serve them in your JSF application. #{resource['/img/the-path-to-my-image.png']} Just copy the ResourceBean.java code above, and add an entry to your faces-config.xm l for the bean: <managed-bean> <managed-bean-name>resource</managed-bean-name> <managed-bean-class>org.richfaces.demo.common.resourcebean</managed-bean-class> <managed-bean-scope>application</managed-bean-scope> </managed-bean> Developing Portlets with the Bridge T his chapter demonstrates common development tasks described by the 329 specification Excluding Attributes from the Bridge Request Scope When your application uses request attributes on a per request basis and you do not want that particular attribute to be managed in the extended bridge request scope, you must use the following configuration in your faces-config.xm l. In the code sample below you can see that any attribute namespaced as foo.bar or any attribute beginning with foo.baz(wild-card) will be excluded from the bridge request scope and only be used per that application's request. <application> <application-extension> <bridge:excluded-attributes> <bridge:excluded-attribute>foo.bar</bridge:excluded-attribute> <bridge:excluded-attribute>foo.baz.* </bridge:excluded-attribute> </bridge:excluded-attributes> </application-extension> </application> Supporting PortletMode Changes A PortletMode represents a distinct render path within an application. T here are three standard modes: view, edit, and help. The bridge's ExternalContext.encodeActionURL recognizes the query string parameter javax.portlet.faces.portletmode and uses this parameter's value to set the portlet mode on the underlying portlet actionurl or response. Once processed it then removes this parameter from the query string. T his means the following navigation rule causes one to render the \edit.jspx viewid in the portlet edit mode: 89

93 Red Hat JBoss Portal 5.1 Reference Guide <navigation-rule> <from-view-id>/register.jspx</from-view-id> <navigation-case> <from-outcome>edit</from-outcome> <to-view-id>/edit.jspx?javax.portlet.faces.portletmode=edit</to-view-id> </navigation-case> </navigation-rule> Navigating to a mode's last viewid By default a mode change will start in the mode's default view without any (prior) existing state. One common portlet pattern when returning to a mode left after entering another mode (e.g.. view -> edit -> view) is to return to the last view (and state) of this origin mode. The bridge will explicitly encode the necessary information so that when returning to a prior mode it can target the appropriate view and restore the appropriate state. T he session attributes maintained by the bridge are intended to be used by developers to navigate back from a mode to the last location and state of a prior mode. As such, a developer needs to describe a dynamic navigation: "From view X return to the last view of mode Y". T his is most easily expressed via an EL expression. For example: <navigation-rule> <from-view-id>/edit.jspx* </from-view-id> <navigation-case> <from-outcome>view</from-outcome> <to-view-id>#{sessionscope['javax.portlet.faces.viewidhistory.view']}</to-viewid> </navigation-case> </navigation-rule> Note to Portlet Developers Depending on the bridge implementation, when using values from these session scoped attributes or any viewids which may contain query string parameters it may be necessary to use the wild-card syntax when identifying the rule target. In the above, for example, the <to-view-id> expression returns a viewid of the form /viewid?javax.portlet.faces.portletmode=view&... Without wild-carding, when a subsequent navigation occurs from this new view, the navigation rules wouldn't resolve because there wouldn't be an exact match. Likewise, the above edit.jspx <from-view-id> is wild-carded because there are navigation rules that target it that use a query string: <to-view-id> /edit.jspx?javax.portlet.faces.portletmode=edit </to-view-id> Developers are encouraged to use such wild-carding to ensure they execute properly in the broadest set of bridge implementations. 90

94 Chapter 13. Building JSF Portlets Clearing The View History When Changing Portlet Modes By default the bridge remembers the view history when you switch to a different portlet mode (like "Help" or "Edit"). You can use the following parameter in your portlet.xml to use the default viewid each time you switch modes. <init-param> <name>javax.portlet.faces.extension.resetmodeviewid</name> <value>true</value> </init-param> General Error Handling Note If you are developing a Seam portlet you can now use pages.xml for all error handling. T he following configuration may be used to handle exceptions. T his is also useful for handling session timeout and ViewExpiredExceptions. The Location Element T he location element must contain the /faces/ mapping to work properly. <error-page> <exception-type>javax.servlet.servletexception</exception-type> <location>/faces/error.xhtml</location> </error-page> <error-page> <exception-type>javax.faces.application.viewexpiredexception</exception-type> <location>/faces/error.xhtml</location> </error-page> Custom Ajax Error Handling By default, error handling is sent to a standard servlet page for Ajax requests. To handle the error inside the portlet, use the following javascript: <script type="text/javascript"> A4J.AJAX.onError = function(req,status,message){ window.alert("custom onerror handler "+message); } A4J.AJAX.onExpired = function(loc,expiredmsg){ if(window.confirm("custom onexpired handler "+expiredmsg+" for a location: "+loc)){ return loc; } else { return false; } } </script> 91

95 Red Hat JBoss Portal 5.1 Reference Guide Also, add the following to web.xml. <context-param> <param-name>org.ajax4jsf.handleviewexpiredonclient</param-name> <param-value>true</param-value> </context-param> Read more about these settings here Request Errors and Session Expiration Handling Communication Between Your Portlets T here are four different ways to send messages, events, and parameters between portlets which are contained in different ears/wars or contained in the same war. Having two portlets in the same war or having them separated does not affect the Portlet Container because each portlet has a different HttpSession. The recommended way to share a parameter or event payload between two or more portlets with the Portlet 2.0 specification are the Section , Public Render Parameters and Section , Sending and Receiving Events mechanisms. This allows you to decouple your application from surgically managing objects in the PortletSession.APPLICATION_SCOPE. However, if these do not meet your use case or you have a different strategy, you can use one of the following methods Storing Components in PortletSession.APPLICATION_SCOPE Sometimes it is beneficial to store your Seam components in the portlet APPLICATION_SCOPE. By default, these objects are stored in the PORTLET_SCOPE but with the annotation below, this class can be pulled out of the PortletSession and its values used in other portlets across different Seam PortletScope(PortletScope.ScopeType.APPLICATION_SCOPE) T hen you would pull the stateful object from the session: YourSessionClass yoursessionclass = (YourSessionClass)getRenderRequest().getAttribute("javax.portlet.p./default/seamproj ect/seamprojectportletwindow?textholder"); T his method is demonstrated in this video: Lesson 2: Portlet 1.0 Advanced Seam and RichFaces Using the PortletSession If you need to access the PortletSession to simply share a parameter or value across multiple portlets, you can use the following: 92

96 Chapter 13. Building JSF Portlets Object objsession = FacesContext.getCurrentInstance().getExternalContext().getSession(false); try { if (objsession instanceof PortletSession) { PortletSession portalsession = (PortletSession)objSession; portalsession.setattribute("your parameter name","parameter value",portletsession.application_scope);... Then, in your JSP or Facelets page, you can use: #{httpsessionscope['your parameter name']} Note to Portlet Developers #{httpsessionscope} was implemented after BET A. If you are using the 1.0 bridge or pre BET A, you must use the EL variable #{sessionapplicationscope}. For more information about which EL variables are provided by the bridge, read section of the JSR- 329 specification Linking to Portlet/JSF Pages Using h:outputlink For linking to any JSF/Facelets page within your portlet web application, you can use the following. <h:outputlink value="#{facescontext.externalcontext.requestcontextpath}/home.xhtml"> <f:param name="javax.portlet.faces.viewlink" value="true"/> navigate to the test page </h:outputlink> Redirecting to an External Page or Resource To link to a non JSF view, jboss.org for example, you can use the following parameter. <h:commandlink actionlistener="#{yourbean.yourlistenr}"> <f:param name="javax.portlet.faces.directlink" value="true"/> navigate to the test page </h:commandlink> Then in your backing bean, you must call a redirect(). FacesContext.getCurrentInstance().getExternalContext().redirect(" g"); Using Provided EL Variables All EL variables found in the JSR-329 (Portlet 2.0) specification are available in the JBoss Portlet Bridge. For example, you can use the following to edit the portlet preferences on the UI: 93

97 Red Hat JBoss Portal 5.1 Reference Guide <h:form> <h:inputtext id="pref" required="true" value="#{mutableportletpreferencesvalues['username'].value}" /> <h:commandbutton actionlistener="#{mybean.savepref}" value="save Preferences" /> </h:form> T hen in your backing bean, you must call the PortletPreferences.store() method. Object request = FacesContext.getCurrentInstance().getExternalContext().getRequest(); PortletRequest portletrequest = (PortletRequest)request; if (request instanceof PortletRequest) { try { PortletPreferences portletpreferences = portletrequest.getpreferences(); portletpreferences.store(); 94

98 Chapter 14. Authentication and Identity Chapter 14. Authentication and Identity Password Encryption Username and passwords stored in clear text T he Remember Me feature of JBoss Enterprise Portal Platform uses a token mechanism to be able to authenticate returning users without requiring an explicit login. However, to be able to authenticate these users, the token needs to store the username and password in clear text in the JCR. Administrators have two options available to ameliorate this risk: 1. The Remember Me feature can be disabled by removing the corresponding checkbox in: <JBOSS_HOME>/server/<PROFILE>/deploy/gatein.ear/02portal.war/login/jsp/lo gin.jsp and <JBOSS_HOME>/server/<PROFILE>/deploy/gatein.ear/02portal.war/groovy/porta l/webui/uiloginform.gtm pl. 2. Passwords can be encoded prior to being saved to the JCR. T his option requires administrators to provide a custom subclass of org.exoplatform.web.security.security.abstractcodec and set up a codec implementation with CookieTokenService: Procedure Encrypt Password in JCR a. Create a javaclass similar to: 95

99 Red Hat JBoss Portal 5.1 Reference Guide package org.example.codec; import org.exoplatform.container.xml.initparams; import org.exoplatform.web.security.security.abstractcodec; import org.exoplatform.web.security.security.cookietokenservice; import org.picocontainer.startable; public class ExampleCodec extends AbstractCodec implements Startable { private String simpleparam; private CookieTokenService cookietokenservice; public ExampleCodec(InitParams params, CookieTokenService cookietokenservice) { simpleparam = params.getvalueparam("encodingparam").getvalue(); this.cookietokenservice = cookietokenservice; } public void start() { cookietokenservice.setupcodec(this); } public void stop() { } /** * Very simple encoding algorithm used only for demonstration purposes. * You should use stronger algorithm in real production environment. */ public String encode(string plaininput) { return plaininput + simpleparam; } public String decode(string encodedinput) { return encodedinput.substring(0, encodedinput.length() - simpleparam.length()); } } b. Compile the class and package it into a jar file. For this example we will call the jar file codec-exam ple.jar. c. Create a conf/portal/configuration.xm l file within the codec-exam ple.jar similar to the example below. This allows the portal kernel to find and use the new codec implementation. 96

100 Chapter 14. Authentication and Identity <?xml version="1.0" encoding="iso "?> <configuration xmlns:xsi=" xsi:schemalocation=" xmlns=" <component> <key>org.example.codec.examplecodec</key> <type>org.example.codec.examplecodec</type> <init-params> <value-param> <name>encodingparam</name> <value>aaa</value> </value-param> </init-params> </component> </configuration> d. Deploy the codec-example.jar into your <JBOSS_HOME>/server/<PROFILE>/deploy/gatein.ear/lib/ directory. e. Start (or restart) your JBoss Enterprise Portal Platform. Any passwords written to the JCR will now be encoded and not plain text Predefined User Configuration Overview The initial Organization configuration should be specified by editing the content of JBOSS_HOME/server/<PROFILE>/deploy/gatein.ear/02portal.war:/WEB- INF/conf/organization/organization-configuration.xm l. T his file uses the portal XML configuration schema. It lists several configuration plug-ins Plugin for adding users, groups and membership types The plugin type org.exoplatform.services.organization.organizationdatabaseinitializer is used to specify a list of membership types, a list of groups and a list of users to be created. T he checkdatabasealgorithm initialization parameter determines how the database update is performed. If its value is set to entry it means that each user, group and membership listed in the configuration is checked each time JBoss Enterprise Portal Platform is started. If the entry does not yet exist in the database, it is created. If checkdatabasealgorithm parameter value is set to empty, the configuration data will be updated to the database only if the database is empty Membership types T he predefined membership types are specified in the membershipt ype field of the OrganizationConfig plugin parameter. 97

101 Red Hat JBoss Portal 5.1 Reference Guide Note See 02portal.war:/WEB-INF/conf/organization/organizationconfiguration.xm l for the full content. <field name="membershiptype"> <collection type="java.util.arraylist"> <value> <object type="org.exoplatform.services.organization.organizationconfig$membershiptype"> <field name="type"> <string>member</string> </field> <field name="description"> <string>member membership type</string> </field> </object> </value> <value> <object type="org.exoplatform.services.organization.organizationconfig$membershiptype"> <field name="type"> <string>owner</string> </field> <field name="description"> <string>owner membership type</string> </field> </object> </value> <value> <object type="org.exoplatform.services.organization.organizationconfig$membershiptype"> <field name="type"> <string>validator</string> </field> <field name="description"> <string>validator membership type</string> </field> </object> </value> </collection> </field> Groups T he predefined groups are specified in the group field of the OrganizationConfig plugin parameter. Note See 02portal.war:/WEB-INF/conf/organization/organizationconfiguration.xm l for the full content. 98

102 Chapter 14. Authentication and Identity <field name="group"> <collection type="java.util.arraylist"> <value> <object type="org.exoplatform.services.organization.organizationconfig$group"> <field name="name"><string>platform</string></field> <field name="parentid"><string></string></field> <field name="description"><string>the /platform group</string></field> <field name="label"><string>platform</string></field> </object> </value> <value> <object type="org.exoplatform.services.organization.organizationconfig$group"> <field name="name"><string>administrators</string></field> <field name="parentid"><string>/platform</string></field> <field name="description"><string>the /platform/administrators group</string></field> <field name="label"><string>administrators</string></field> </object> </value> <value> <object type="org.exoplatform.services.organization.organizationconfig$group"> <field name="name"><string>users</string></field> <field name="parentid"><string>/platform</string></field> <field name="description"><string>the /platform/users group</string></field> <field name="label"><string>users</string></field> </object> </value> <value> <object type="org.exoplatform.services.organization.organizationconfig$group"> <field name="name"><string>guests</string></field> <field name="parentid"><string>/platform</string></field> <field name="description"><string>the /platform/guests group</string></field> <field name="label"><string>guests</string></field> </object> </value>... </collection> </field> Users T he predefined users are specified in the user field of the OrganizationConfig plugin parameter. Note See 02portal.war:/WEB-INF/conf/organization/organizationconfiguration.xm l for the full content. 99

103 Red Hat JBoss Portal 5.1 Reference Guide <field name="user"> <collection type="java.util.arraylist"> <value> <object type="org.exoplatform.services.organization.organizationconfig$user"> <field name="username"><string>root</string></field> <field name="password"><string>exo</string></field> <field name="firstname"><string>root</string></field> <field name="lastname"><string>root</string></field> <field localhost</string></field> <field name="groups"><string>member:/admin,member:/user,owner:/portal/admin</string></fi eld> </object> </value> <value> <object type="org.exoplatform.services.organization.organizationconfig$user"> <field name="username"><string>exo</string></field> <field name="password"><string>exo</string></field> <field name="firstname"><string>site</string></field> <field name="lastname"><string>site</string></field> <field localhost</string></field> <field name="groups"><string>member:/user</string></field> </object> </value>... </collection> </field> Plugin for managing user creation T he plugin type org.exoplatform.services.organization.im pl.newusereventlistener specifies which groups all newly created users should become members of. It specifies the group memberships and the membership types to use (while a group is just a set of users, a membership type represents a user's role within a group). It also specifies a list of users that should not be processed (such as administrative users like 'root'). Terminology The terms 'membership' and 'membership type' refer to the same thing, and are used interchangeably. 100

104 Chapter 14. Authentication and Identity <component-plugin> <name>new.user.event.listener</name> <set-method>addlistenerplugin</set-method> <type>org.exoplatform.services.organization.impl.newusereventlistener</type> <description>this listener assign group and membership to a new created user</description> <init-params> <object-param> <name>configuration</name> <description>description</description> <object type="org.exoplatform.services.organization.impl.newuserconfig"> <field name="group"> <collection type="java.util.arraylist"> <value> <object type="org.exoplatform.services.organization.impl.newuserconfig$joingroup"> <field name="groupid"><string>/platform/users</string></field> <field name="membership"><string>member</string></field> </object> </value> </collection> </field> <field name="ignoreduser"> <collection type="java.util.hashset"> <value><string>root</string></value> <value><string>john</string></value> <value><string>mary</string></value> <value><string>demo</string></value> </collection> </field> </object> </object-param> </init-params> </component-plugin> Authentication Token Configuration The Token Service T he Token Service is used in authentication. T he token system prevents user account information being sent in clear text mode within inbound requests. T his increases authentication security. T he token service allows administrators to create, delete, retrieve and clean tokens as required. T he service also defines a validity period of any given token. The token becomes invalid once this period expires Implementing the Token Service API All token services used in JBoss Enterprise Portal Platform authentication must be implemented by subclassing an AbstractT okenservice abstract class. T he following AbstractT okenservice methods represent the contract between authentication runtime, and a token service implementation. 101

105 Red Hat JBoss Portal 5.1 Reference Guide public Token gettoken(string id) throws PathNotFoundException, RepositoryException; public Token deletetoken(string id) throws PathNotFoundException, RepositoryException; public String[] getalltokens(); public long getnumbertokens() throws Exception; public String createtoken(credentials credentials) throws IllegalArgumentException,NullPointerException; public Credentials validatetoken(string tokenkey, boolean remove) throws NullPointerException; Configuring Token Services T oken services configuration includes specifying the token validity period. T he token service is configured as a portal component using the JBOSS_HOME/server/PROFILE/deploy/gatein.ear/02portal.war/WEB- INF/conf/com m on/autologin-configuration.xm l file. In the XML example below, CookieTokenService is a subclass of AbstractT okenservice so it has a property which specifies the validity period of the token. T he token service will initialize this validity property by looking for an init-param named service.configuration. T his property must have three values. <component> <key>org.exoplatform.web.security.security.cookietokenservice</key> <type>org.exoplatform.web.security.security.cookietokenservice</type> <init-params> <values-param> <name>service.configuration</name> <value>jcr-token</value> <value>7</value> <value>day</value> <value>autologin</value> </values-param> </init-params> </component> Service name Amount of time Unit of time In this case, the service name is jcr-token and the token expiration time is one week. JBoss Enterprise Portal Platform supports four time units: 1. SECOND 2. MINUTE 3. HOUR 4. DAY PicketLink IDM integration JBoss Enterprise Portal Platform uses the PicketLink IDM component to store necessary identity 102

106 Chapter 14. Authentication and Identity information about users, groups and memberships. While legacy interfaces are still used (org.exoplatform.services.organization) for identity management, there is a wrapper implementation that delegates to PicketLink IDM framework. T his section does not provide information about PicketLink IDM and its configuration. Please, refer to the appropriate project documentation ( for further information. Note It is important to fully understand the concepts behind this framework design before changing the default configuration. T he identity models represented in the org.exoplatform.services.organization interfaces and the one used in PicketLink IDM have some major differences. For example; PicketLink IDM provides greater abstraction. It is possible for groups in the IDM framework to form memberships with many parents (which requires recursive ID translation), while the org.exoplatform.services.organization model allows only pure tree-like membership structures. Additionally, org.exoplatform.services.organization membership concept needs to be translated into the IDM Role concept. T herefore PicketLink IDM model is used in a limited way. All these translations are applied by the integration layer Configuration files T he main configuration file is 02portal.war/WEB-INF/conf/organization/idmconfiguration.xm l: 103

107 Red Hat JBoss Portal 5.1 Reference Guide <configuration xmlns:xsi=" xsi:schemalocation=" xmlns=" <component> <key>org.exoplatform.services.organization.idm.picketlinkidmcacheservice</key> <type>org.exoplatform.services.organization.idm.picketlinkidmcacheservice</type> </component> <component> <key>org.exoplatform.services.database.hibernateservice</key> <jmx-name>database:type=hibernateservice</jmx-name> <type>org.exoplatform.services.database.impl.hibernateserviceimpl</type> <init-params> <properties-param> <name>hibernate.properties</name> <description>default Hibernate Service</description> <property name="hibernate.cache.region.jbc2.query.localonly" value="true" /> <property name="hibernate.cache.region.factory_class" value="org.hibernate.cache.jbc2.multiplexedjbosscacheregionfactory" /> <property name="hibernate.transaction.manager_lookup_class" value="org.hibernate.transaction.jbosstransactionmanagerlookup" /> <property name="hibernate.show_sql" value="false"/> <property name="hibernate.current_session_context_class" value="thread"/> <property name="hibernate.cache.use_second_level_cache" value="true"/> <property name="hibernate.cache.use_query_cache" value="true"/> <property name="hibernate.connection.datasource" value="${gatein.idm.datasource.name}${container.name.suffix}"/> <property name="hibernate.connection.autocommit" value="true"/> <!-- Should be automatically detected. Force otherwise <property name="hibernate.dialect" value="org.hibernate.dialect.xxxdialect"/> --> </properties-param> </init-params> </component> <component> <key>org.exoplatform.services.organization.idm.picketlinkidmservice</key> <type>org.exoplatform.services.organization.idm.picketlinkidmserviceimpl</type> <init-params> <value-param> <name>config</name> <value>war:/conf/organization/picketlink-idm/picketlink-idmconfig.xml</value> <!--Sample LDAP config--> <!--<value>war:/conf/organization/picketlink-idm/examples/picketlink-idmldap-config.xml</value>--> <!--Read Only "ACME" LDAP Example--> <!--<value>war:/conf/organization/picketlink-idm/examples/picketlink-idm- 104

108 <!--<value>war:/conf/organization/picketlink-idm/examples/picketlink-idmldap-acme-config.xml</value>--> <!--OpenLDAP LDAP config--> <!--<value>war:/conf/organization/picketlink-idm/examples/picketlink-idmopenldap-config.xml</value>--> <!--OpenLDAP ReadOnly "ACME" LDAP Example--> <!--<value>war:/conf/organization/picketlink-idm/examples/picketlink-idmopenldap-acme-config.xml</value>--> <!--MSAD LDAP Example--> <!--<value>war:/conf/organization/picketlink-idm/examples/picketlink-idmmsad-config.xml</value>--> <!--MSAD Read Only "ACME" LDAP Example--> <!--<value>war:/conf/organization/picketlink-idm/examples/picketlink-idmmsad-readonly-config.xml</value>--> </value-param> <!-- In default PicketLink IDM configuration hibernate store will namespace identity objects using this realm name if you want to share DB between portal and also share the same identity data remove the "${container.name.suffix}" part--> <value-param> <name>portalrealm</name> <value>idm_realm${container.name.suffix}</value> </value-param> <value-param> <name>apicacheconfig</name> <value>war:/conf/organization/picketlink-idm/jboss-cache.xml</value> </value-param> <value-param profiles="cluster"> <name>apicacheconfig</name> <value>war:/conf/organization/picketlink-idm/jboss-cachecluster.xml</value> </value-param> <value-param> <name>storecacheconfig</name> <value>war:/conf/organization/picketlink-idm/jboss-cache.xml</value> </value-param> <value-param profiles="cluster"> <name>storecacheconfig</name> <value>war:/conf/organization/picketlink-idm/jboss-cachecluster.xml</value> </value-param> </init-params> </component> Chapter 14. Authentication and Identity T he org.exoplatform.services.organization.idm.picketlinkidmserviceimpl service has the following options: config (value-param) T he PicketLink IDM configuration file. 105

109 Red Hat JBoss Portal 5.1 Reference Guide hibernate.properties (properties-param) A list of hibernate properties used to create SessionFactory that will be injected to JBoss Identity IDM configuration registry. hibernate.annotations (values-param) A list of annotated classes that will be added to Hibernate configuration. hibernate.mappings (values-param) A list of xml files that will be added to hibernate configuration as mapping files. jndiname (value-param) If the config parameter is not provided, this parameter will be used to perform JNDI lookup for IdentitySessionFactory. portalrealm (value-param) The realm name that should be used to obtain proper IdentitySession. The default is PortalRealm. apicacheconfig, storecacheconfig (value-param) T hese options reference the JBoss cache configuration used for Picketlink. T he org.exoplatform.services.organization.idm.picketlinkidmorganizationserviceimpl key is a main entrypoint implementing org.exoplatform.services.organization.organizationservice and is dependent on org.exoplatform.services.organization.idm.picketlinkidmservice T he org.exoplatform.services.organization.idm.picketlinkidmorganizationserviceimpl service has the following options defined as fields of object-param of type org.exoplatform.services.organization.idm.config: defaultgroupt ype The name of the PicketLink IDM GroupType that will be used to store groups. The default is 'GT N_GROUP_T YPE'. rootgroupname The name of the PicketLink IDM Group that will be used as a root parent. The default is 'GT N_ROOT_GROUP' passwordasattribute T his parameter specifies if a password should be stored using PicketLink IDM Credential object or as a plain attribute. The default is false. 106

110 Chapter 14. Authentication and Identity useparentidasgroupt ype This parameter stores the parent ID path as a group type in PicketLink IDM for any IDs not mapped with a specific type in 'grouptypemappings'. If this option is set to false, and no mappings are provided under 'groupt ypemappings', then only one group with the given name can exist in the JBoss Enterprise Portal Platform group tree. pathseparator When 'userparentidasgroupt ype' is set to true, this value will be used to replace all "/" characters in IDs. The "/" character is not allowed to be used in group type name in PicketLink IDM. associationmembershipt ype If this option is used, then each Membership, created with MembershipT ype that is equal to the value specified here, will be stored in PicketLink IDM as simple Group-User association. groupt ypemappings T his parameter maps groups added with JBoss Enterprise Portal Platform API as children of a given group ID, and stores them with a given group type name in PicketLink IDM. If the parent ID ends with "/*", then all child groups will have the mapped group type. Otherwise, only direct (first level) children will use this type. This can be leveraged by LDAP if LDAP DN is configured in PicketLink IDM to only store a specific group type. This will then store the given branch in JBoss Enterprise Portal Platform group tree, while all other groups will remain in the database. forcemembershipofmappedt ypes Groups stored in PicketLink IDM with a type mapped in 'groupt ypemappings' will automatically be members under the mapped parent. Group relationships linked by PicketLink IDM group association will not be necessary. This parameter can be set to false if all groups are added via JBoss Enterprise Portal Platform APIs. This may be useful with LDAP configuration as, when set to true, it will make every entry added to LDAP appear in JBoss Enterprise Portal Platform. T his, however, is not true for entries added via JBoss Enterprise Portal Platform management UI. ignoremappedmembershipt ype If "associationmem bershipt ype" option is used, and this option is set to true, then Membership with MembershipT ype configured to be stored as PicketLink IDM association will not be stored as PicketLink IDM Role. usejt A This is a boolean option which determines whether JTA (Java Transaction API) will be used in Picketlink IDM. Additionally, JBossIDMOrganizationServiceIm pl uses those defaults to perform identity management operations JBoss Enterprise Portal Platform User interface properties fields are persistent in JBoss Identity IDM using the attributes names: firstname 107

111 Red Hat JBoss Portal 5.1 Reference Guide lastname createddate lastlogintime organizationid password (if password is configured to be stored as attribute) JBoss Enterprise Portal Platform Group interface properties fields are persistent in JBoss Identity IDM using the attributes names: label description JBoss Enterprise Portal Platform Mem bershipt ype interface properties fields are persistent in JBoss Identity IDM using those RoleT ype properties: description owner create_date modified_date T he PicketLink IDM configuration file is shown below. T o understand all the options it contains, please refer to the PicketLink IDM Reference Guide 108

112 <jboss-identity xmlns="urn:picketlink:idm:config:v1_0_0_ga" xmlns:xsi=" xsi:schemalocation="urn:picketlink:idm:config:v1_0_0_ga identityconfig.xsd"> <realms> <realm> <id>idm_realm</id> <repository-id-ref>defaultportalrepository</repository-id-ref> <identity-type-mappings> <user-mapping>user</user-mapping> </identity-type-mappings> <options> <option> <name>template</name> <value>true</value> </option> <option> <name>cache.providerregistryname</name> <value>apicacheprovider</value> </option> </options> </realm> </realms> <repositories> <repository> <id>defaultportalrepository</id> <class>org.picketlink.idm.impl.repository.wrapperidentitystorerepository</class> <external-config/> <default-identity-store-id>hibernatestore</default-identity-store-id> <default-attribute-store-id>hibernatestore</default-attribute-store-id> </repository> </repositories> <stores> <attribute-stores/> <identity-stores> <identity-store> <id>hibernatestore</id> <class>org.picketlink.idm.impl.store.hibernate.hibernateidentitystoreimpl</class> <external-config/> <supported-relationship-types> <relationship-type>jboss_identity_membership</relationship-type> <relationship-type>jboss_identity_role</relationship-type> </supported-relationship-types> <supported-identity-object-types> <identity-object-type> <name>user</name> <relationships/> <credentials> <credential-type>password</credential-type> </credentials> <attributes/> <options/> </identity-object-type> </supported-identity-object-types> <options> <option> <name>hibernatesessionfactoryregistryname</name> <value>hibernatesessionfactory</value> Chapter 14. Authentication and Identity 109

113 Red Hat JBoss Portal 5.1 Reference Guide </option> <option> <name>populaterelationshiptypes</name> <value>true</value> </option> <option> <name>populateidentityobjecttypes</name> <value>true</value> </option> <option> <name>allownotdefinedidentityobjecttypes</name> <value>true</value> </option> <option> <name>allownotdefinedattributes</name> <value>true</value> </option> <option> <name>isrealmaware</name> <value>true</value> </option> </options> </identity-store> </identity-stores> </stores> <options> <option> <name>defaulttemplate</name> <value>idm_realm</value> </option> </options> </jboss-identity> Organization API T he exo.platform.services.organization package has five main components: User T he User component contains basic information about a user; such as username, password, first name, last name, and address. User Profile T he User Profile component contains extra information about a user, such as user's personal information, and business information. You can also add additional information about a user if your application requires it. Group T he Group component contains a group graph. Membership T ype T he Mem bership T ype component contains a list of predefined membership types. Membership 110

114 Chapter 14. Authentication and Identity The Membership component connects a User, a Group and a Membership Type. A user can have one or more memberships within a group. For example: User A can have the 'member' and 'admin' memberships in group /user. A user belongs to a group if he has at least one membership in that group. T he OrganizationService component is an additional component that serves as an entry point into the Organization API. It provides handling functionality for the five components. By exposing the Organization API, the OrganizationService component provides developers with access to handler objects for managing each of the five components: UserHandler UserProfileHandler GroupHandler MembershipT ypehandler MembershipHandler T he five central API components are designed to be similar to persistent entities and handlers are specified similarly to data access objects (DAO). Organization API simply describes a contract, meaning it is not a concrete implementation. T he described components are interfaces, allowing for different concrete implementations. In practical terms the existing implementation can be replaced with a different one Accessing User Profile T he following code retrieves the details for a logged-in user: 111

115 Red Hat JBoss Portal 5.1 Reference Guide // Alternative context: WebuiRequestContext context = WebuiRequestContext.getCurrentInstance() ; PortalRequestContext context = PortalRequestContext.getCurrentInstance() ; // Get the id of the user logged String userid = context.getremoteuser(); // Request the information from OrganizationService: OrganizationService orgservice = getapplicationcomponent(organizationservice.class) ; if (userid!= null) { User user = orgservice.getuserhandler().finduserbyname(userid) ; if (user!= null) { String firstname = user.getfirstname(); String lastname = user.getlastname(); String = user.get (); } } Below are two alternatives for retrieving the Organization Service: 1. OrganizationService service = (OrganizationService) ExoContainerContext.getCurrentContainer().getComponentInstanceOfType(Organizati onservice.class); 2. OrganizationService service = (OrganizationService) PortalContainer.getInstance().getComponentInstanceOfType(OrganizationService.cl ass); SSO - Single Sign On Overview JBoss Enterprise Portal Platform provides an implementation of Single Sign On (SSO) as an integration and aggregation platform. When logging into the portal users can access many systems through portlets using a single identity. In many cases, however, the portal infrastructure must be integrated with other SSO enabled systems. T here are many different Identity Management solutions available. In most cases each SSO framework provides a unique way to plug into a Java EE application. T his section will cover the implementation of four different SSO plug-ins with JBoss Enterprise Portal Platform: Section , CAS - Central Authentication Service Section , JOSSO - Java Open Single Sign-On Project Section , OpenSSO - The Open Web SSO project Section , SPNEGO - Simple and Protected GSSAPI Negotiation Mechanism 112

116 Chapter 14. Authentication and Identity Prerequisites In this tutorial, the SSO server is being installed in a Tomcat environment. Tomcat can be obtained from All the packages required for SSO setup can be found in a zip file located in the jbossepp-version/gatein-sso directory of the JBoss Enterprise Portal Platform binary package. In the following scenarios this directory will be referred to as PORTAL_SSO. Warning Users are advised to not run any portal extensions that could override the data when manipulating the gatein.ear file directly Enabling SSO using JBoss SSO Valve The JBoss SSO valve is useful to authenticate a user on one JBoss Enterprise Portal Platform node in a cluster and have that authentication automatically carry across to other nodes in the cluster. T his authentication can also be used in any other web applications which may require authentication, provided that these applications use same roles as the main portal instance. Attempting to use an SSO authentication in an application that uses different roles may create authorization errors (4 03 errors, for example). More info about the JBoss SSO valve can be found at US/JBoss_Enterprise_Web_Platform/5/html/Administration_And_Configuration_Guide/clustering-httpsso.html. T o successfully implement SSO integration, do the following: Procedure SSO Integration 1. Open the /<JBOSS_HOME>/server/<PROFILE>/deploy/jbossweb.sar/server.xm l file and uncomment one of the two Valve entries: For a non-clustered implementation, uncomment: <Valve classname="org.apache.catalina.authenticator.singlesignon" /> For a clustered implementation, uncomment: <Valve classname="org.jboss.web.tomcat.service.sso.clusteredsinglesignon" /> 2. To integrate with the JBoss SSO valve, follow one of the procedures below to make the necessary configuration changes in the Java Authentication and Authorization Service (JAAS): Procedure Call the JAAS authentication directly a. Open the /<JBOSS_HOME>/server/<PROFILE>/deploy/gatein.ear/02portal.war/logi n/jsp/login.jsp file. b. Change the line that reads: 113

117 Red Hat JBoss Portal 5.1 Reference Guide <form name="loginform" action="<%= contextpath + "/login"%>" method="post" style="margin: 0px;"> to read: <form name="loginform" action="<%= contextpath + "/private/j_security_check"%>" method="post" style="margin: 0px;"> c. Change the line that reads: <td><input class="username" name="username" value="<%=username%>"/></td> to read: <td><input class="username" name="j_username" value="<%=username%>"/></td> d. Change the line that reads: <td><input class="password" type="password" name="password" value=""/></td> to read: <td><input class="password" type="password" name="j_password" value=""/></td> Procedure Switch to BASIC authentication Change the auth-method element in <JBOSS_HOME>/server/<PROFILE>/deploy/gatein.ear/02portal.war/WEB- INF/web.xm l from FORM to BASIC: <login-config> <auth-method>basic</auth-method> <realm-name>gatein-domain</realm-name> <form-login-config> <form-login-page>/initiatelogin</form-login-page> <form-error-page>/errorlogin</form-error-page> </form-login-config> Testing the SSO Valve Once the JBoss SSO Valve has been enabled, it can be tested with the following steps: Procedure Testing the SSO Vavle 1. Copy the <PROFILE> you enabled the valve in (all, for example) into two new profiles called node1 and node2. 2. Run an instance of JBoss Enterprise Portal Platform using the node1 profile on a local machine:./run.sh -c node1 -Djboss.service.binding.set=ports-default - Dexo.profiles=cluster -Djboss.messaging.ServerPeerID=0 & 114

118 Chapter 14. Authentication and Identity 3. Start another instance using the node2 profile:./run.sh -c node2 -Djboss.service.binding.set=ports-01 -Dexo.profiles=cluster -Djboss.messaging.ServerPeerID=1 & 4. Navigate to and authenticate with the pre-configured user account "root" (password "gtn"). 5. Navigate to You should be automatically authenticated as user root on this node as well. Enabling SSO in a physical cluster If you require SSO to work across a physical cluster of separate machines you will need to use the cookiedomain attribute of the SSO valve. 1. Open the <JBOSS_HOME>/server/<PROFILE>/deploy/jbossweb.sar/server.xm l file. 2. Uncomment the line: <!-- <Valve classname="org.jboss.web.tomcat.service.sso.clusteredsinglesignon" /> --> 3. And edit it to match the following: <Valve classname="org.jboss.web.tomcat.service.sso.clusteredsinglesignon" cookiedomain="yourdomain.com" /> (Where yourdom ain.com is the domain used in your cluster. For example; and 4. Repeat the process in the other nodes in the cluster. This will ensure the JSESSIONIDSSO cookie is used in the correct domain, allowing the SSO authentication to occur. Enabling SSO with Other Web Applications As mentioned earlier, in order to use SSO authentication between JBoss Enterprise Portal Platform instances and other web applications, the roles defined in the web application must match those used in the portal instance. As an example, to use the SSO Valve to authenticate a user in both a portal instance and the JMX Console, the following actions would be required: Procedure Open the <JBOSS_HOME>/server/<PROFILE>/deploy/jm x-console.war/web-inf/web.xm l file and edit it as follows: 1. Change the <role-name> entry in the <auth-constraint> element (line 110) from JBossAdm in to users: 115

119 Red Hat JBoss Portal 5.1 Reference Guide <auth-constraint> <!--<role-name>jbossadmin</role-name>--> <role-name>users</role-name> </auth-constraint> 2. Change the <role-name> entry in the <security-role> element (line 120) from JBossAdm in to users <security-role> <!--<role-name>jbossadmin</role-name>--> <role-name>users</role-name> </security-role> T esting SSO With Other Web Applications T o test that SSO authentication is enabled from portal instances to other web applications (in this case, the JMX Console), do the following: Procedure Test SSO Between Portal and JMX Console 1. Start a portal instance on one node:./run.sh -c node1 -Djboss.service.binding.set=ports-default - Dexo.profiles=cluster -Djboss.messaging.ServerPeerID=0 & 2. Navigate to and authenticate with the pre-configured user account "root" (password "gtn"). 3. Navigate to You should be automatically authenticated into the JMX Console. Using SSO to Authenticate From the Public Page The previous configuration changes in this section are useful if a user is using a private URL ( for example) to log in to the portal instance. Further changes are needed however, if SSO authentication is required to work with the Sign In button on the front page of the portal ( T o enable this functionality, the Sign In link must redirect to the login.jsp file edited earlier to call the JAAS authentication directly. Procedure Redirect to Use SSO Valve Authentication 1. Open the <JBOSS_HOME>/server/<PROFILE>/deploy/gatein.ear/web.war/groovy/groovy/webu i/com ponent/uibannerportlet.gtm l file and edit the line: <a class="login" onclick="$signinaction"><%=_ctx.appres("uiloginform.label.signin")%></a> To read: <a class="login" href="/portal/private/classic"><%=_ctx.appres("uiloginform.label.signin")%></ a> 116

120 Chapter 14. Authentication and Identity 2. Open the <JBOSS_HOME>/server/<PROFILE>/deploy/gatein.ear/web.war/groovy/portal/webu i/com ponent/uilogoportlet.gtm pl file and change the line: <a onclick="$signinaction"><%=_ctx.appres("uilogoportlet.action.signin")%></a> To read: <a href="/portal/private/classic"><%=_ctx.appres("uilogoportlet.action.signin")%> </a> CAS - Central Authentication Service T his Single Sign On plugin enables seamless integration between JBoss Enterprise Portal Platform and the Central Authentication Service (CAS) Single Sign On Framework. Details about CAS can be found here. Procedure CAS server 1. Set up the server to authenticate against the portal login module. 2. Downloaded CAS from 3. Extract the downloaded file into a suitable location. T his location will be referred to as CAS_DIR in the following example. The simplest way to configure the web archive is to make the necessary changes directly into the CAS codebase. Note T o perform the final build step and complete these instructions you will need the Apache Maven 2. Download it from here. The CAS Server Plugin makes secure callbacks to a RESTful service installed on the remote JBoss Enterprise Portal Platform server to authenticate a user. In order for the plugin to function correctly, it needs to be properly configured to connect to this service. T his configuration is controlled by the cas.war/web-inf/deployerconfigcontext.xm l file. Procedure Modifying CAS server 1. Open CAS_DIR/cas-server-webapp/src/m ain/webapp/web- INF/deployerConfigContext.xm l 2. Replace this code: 117

121 Red Hat JBoss Portal 5.1 Reference Guide <!-- Whereas CredentialsToPrincipalResolvers identify who it is some Credentials might authenticate, AuthenticationHandlers actually authenticate credentials. Here e declare the AuthenticationHandlers that authenticate the Principals that the CredentialsToPrincipalResolvers identified. CAS will try these handlers in turn until it finds one that both supports the Credentials presented and succeeds in authenticating. +--> <property name="authenticationhandlers"> <list> <!-- This is the authentication handler that authenticates services by means of callback via SSL, thereby validating a server side SSL certificate. +--> <bean class="org.jasig.cas.authentication.handler.support.httpbasedservicecredentials AuthenticationHandler" p:httpclient-ref="httpclient" /> <!-- This is the authentication handler declaration that every CAS deployer will need to change before deploying CAS into production. The default SimpleTestUsernamePasswordAuthenticationHandler authenticates UsernamePasswordCredentials where the username equals the password. You will need to replace this with an AuthenticationHandler that implements your local authentication strategy. You might accomplish this by coding a new such handler and declaring edu.someschool.its.cas.myspecialhandler here, or you might use one of the handlers provided in the adaptors modules. +--> <bean class="org.jasig.cas.authentication.handler.support.simpletestusernamepassworda uthenticationhandler" /> </list> </property> with: 118

122 Chapter 14. Authentication and Identity <!-- Whereas CredentialsToPrincipalResolvers identify who it is some Credentials might authenticate, AuthenticationHandlers actually authenticate credentials. Here we declare the AuthenticationHandlers that authenticate the Principals that the CredentialsToPrincipalResolvers identified. CAS will try these handlers in turn until it finds one that both supports the Credentials presented and succeeds in authenticating. +--> <property name="authenticationhandlers"> <list> <!-- This is the authentication handler that authenticates services by means of callback via SSL, thereby validating a server side SSL certificate. +--> <bean class="org.jasig.cas.authentication.handler.support.httpbasedservicecredentials AuthenticationHandler" p:httpclient-ref="httpclient" /> <!-- This is the authentication handler declaration that every CAS deployer will need to change before deploying CAS into production. The default SimpleTestUsernamePasswordAuthenticationHandler authenticates UsernamePasswordCredentials where the username equals the password. You will need to replace this with an AuthenticationHandler that implements your local authentication strategy. You might accomplish this by coding a new such handler and declaring edu.someschool.its.cas.myspecialhandler here, or you might use one of the handlers provided in the adaptors modules. +--> <!-- Integrates with the Gatein Authentication Service to perform authentication --> <!-- Note: Modify the Plugin Configuration based on the actual information of a GateIn instance. The instance can be anywhere on the internet...not necessarily on localhost where CAS is running +--> <bean class="org.gatein.sso.cas.plugin.authenticationplugin"> <property name="gateinhost"><value>localhost</value></property> <property name="gateinport"><value>8080</value></property> <property name="gateincontext"><value>portal</value></property> </bean> </list> </property> Make sure to set the host, port and context with the values corresponding to your portal (also available in PORTAL_SSO/cas/plugin/WEB-INF/deployerConfigContext.xm l). 3. Copy PORTAL_SSO/cas/plugin/WEB-INF/lib/sso-cas-plugin-<VERSION>.jar and PORTAL_SSO/cas/plugin/WEB-INF/lib/commons-httpclient-<VERSION>.jar into the CAS_DIR/cas-server-webapp/src/m ain/webapp/web-inf/lib created directory. 4. If you have not already done so, download an instance of Tomcat and extract it into a suitable location (which will be called T OMCAT_HOME for these instructions). 119

123 Red Hat JBoss Portal 5.1 Reference Guide 5. Edit TOMCAT_HOME/conf/server.xml and change the 8080 port to 8888 to avoid a conflict with the default JBoss Enterprise Portal Platform. Note If JBoss Enterprise Portal Platform is running on the same machine as T omcat other ports will need to be changed in addition to 8080 in order to avoid conflicts. They can be changed to any free port. For example; you can change the admin port from 8005 to 8805 and the AJP port from 8009 to Navigate locally to the CAS_DIR/cas-server-webapp directory and execute the following command: mvn install 7. Copy the CAS_DIR/cas-server-webapp/target/cas.war file into the T OMCAT_HOME/webapps directory. T omcat should start without issue and should be accessible at Note At this stage the login functionality will not be available. Procedure Setup the CAS client 1. Copy all the libraries from the PORTAL_SSO/cas/gatein.ear/lib directory into the JBOSS_HOME/server/default/deploy/gatein.ear/lib) directory. 2. Edit the jboss-as/server/profile/deploy/gatein.ear/met A-INF/gatein-jbossbeans.xm l and uncomment this section: 120

124 Chapter 14. Authentication and Identity <authentication> <login-module code="org.gatein.sso.agent.login.ssologinmodule" flag="required"> </login-module> <login-module code="org.exoplatform.services.security.j2ee.jbossloginmodule" flag="required"> <module-option name="portalcontainername">portal</module-option> <module-option name="realmname">gatein-domain</module-option> </login-module> </authentication> There's a line comment already in this source file to assist you. 3. The installation can be tested at this point (assuming the CAS server on Tomcat is running): a. Start (or restart) JBoss Enterprise Portal Platform and direct your web browser to b. Login with the username root and the password gtn (or any other account created through the portal). T o utilize the Central Authentication Service, JBoss Enterprise Portal Platform needs to redirect all user authentication to the CAS server. Information about where the CAS is hosted must be properly configured within the JBoss Enterprise Portal Platform instance. T he required configuration is done by modifying three files. Procedure Redirect to CAS 1. Modify the 'Sign In' link in the <JBOSS_HOME>/server/<PROFILE>/deploy/gatein.ear/web.war/groovy/groovy/webu i/com ponent/uibannerportlet.gtm l file as follows: <!-- <a class="login" onclick="$signinaction"><%=_ctx.appres("uiloginform.label.signin")%></a> --> <a class="login" href="/portal/sso"><%=_ctx.appres("uiloginform.label.signin")%></a> 2. Modify the 'Sign In' link in the <JBOSS_HOME>/server/<PROFILE>/deploy/gatein.ear/web.war/groovy/portal/webu i/com ponent/uilogoportlet.gtm pl file as follows: <!-- <a onclick="$signinaction"><%=_ctx.appres("uilogoportlet.action.signin")%></a> --> <a href="/portal/sso"><%=_ctx.appres("uilogoportlet.action.signin")%></a> 3. Replace the entire contents of gatein.ear/02portal.war/login/jsp/login.jsp with: 121

125 Red Hat JBoss Portal 5.1 Reference Guide <html> <head> <script type="text/javascript"> window.location = '/portal/sso'; </script> </head> <body> </body> </html> 4. Add the following Filters at the top of the filter chain in gatein.ear/02portal.war/web- INF/web.xm l: <filter> <filter-name>loginredirectfilter</filter-name> <filter-class>org.gatein.sso.agent.filter.loginredirectfilter</filter-class> <init-param> <!-- This should point to your SSO authentication server --> <param-name>login_url</param-name> <!-- If casrenewticket param value of InitiateLoginServlet is: not specified or false --> <param-value> service= <!-- If casrenewticket param value of InitiateLoginServlet is : true --> <!-- <param-value> service= --> </init-param> </filter> <filter> <filter-name>caslogoutfilter</filter-name> <filter-class>org.gatein.sso.agent.filter.caslogoutfilter</filter-class> <init-param> <!-- This should point to your JOSSO authentication server --> <param-name>logout_url</param-name> <param-value> </init-param> </filter> <!-- Mapping the filters at the very top of the filter chain --> <filter-mapping> <filter-name>loginredirectfilter</filter-name> <url-pattern>/* </url-pattern> </filter-mapping> <filter-mapping> <filter-name>caslogoutfilter</filter-name> <url-pattern>/* </url-pattern> </filter-mapping> 5. Replace the InitiateLoginServlet declaration in gatein.ear/02portal.war/web- INF/web.xm l with: 122

126 Chapter 14. Authentication and Identity <servlet> <servlet-name>initiateloginservlet</servlet-name> <servlet-class>org.gatein.sso.agent.genericssoagent</servlet-class> <init-param> <param-name>ssoserverurl</param-name> <param-value> </init-param> <init-param> <param-name>casrenewticket</param-name> <param-value>false</param-value> </init-param> </servlet> Once these changes have been made, all links to the user authentication pages will redirect to the CAS centralized authentication form and CAS can be used as an SSO implementation in your portal JOSSO - Java Open Single Sign-On Project T his Single Sign On plugin enables seamless integration between JBoss Enterprise Portal Platform and the Java Open Single Sign-On Project (JOSSO) Single Sign On Framework. Details about JOSSO can be found at T his section details setting up the JOSSO server to authenticate against the JBoss Enterprise Portal Platform login module. Procedure JOSSO server 1. Download JOSSO from Note Use the package that embeds Apache Tomcat. The integration was tested with JOSSO Extract the package into what will be called JOSSO_HOME in this example. Procedure Modifying JOSSO server 1. Copy the files from PORTAL_SSO/josso/plugin into the JOSSO_HOME directory created in the last step. T his action should replace or add the following files to the JOSSO_HOME/webapps/josso/WEB- INF/lib directory: JOSSO_HOME/lib/josso-gateway-config.xm l JOSSO_HOME/lib/josso-gateway-gatein-stores.xm l JOSSO_HOME/webapps/josso/WEB-INF/classes/gatein.properties 2. Edit TOMCAT_HOME/conf/server.xml file and change the 8080 port to 8888 to avoid a conflict with the default JBoss Enterprise Portal Platform port. 123

127 Red Hat JBoss Portal 5.1 Reference Guide Port Conflicts If JBoss Enterprise Portal Platform is running on the same machine as T omcat, other ports need to be changed in addition to 8080 in order to avoid port conflicts. They can be changed to any free port. For example, you can change admin port from 8005 to 8805, and AJP port from 8009 to T omcat should now start and allow access to but at this stage login will not be available. Procedure Setup the JOSSO client 1. Copy the library files from PORTAL_SSO/josso/gatein.ear/lib into gatein.ear/lib 2. Copy the PORTAL_SSO/josso/gatein.ear/02portal.war/WEB-INF/classes/jossoagent-config.xm l file into the gatein.ear/02portal.war/web-inf/classes directory. 3. Edit jboss-as/server/profile/deploy/gatein.ear/met A-INF/gatein-jbossbeans.xm l and uncomment this section: <authentication> <login-module code="org.gatein.sso.agent.login.ssologinmodule" flag="required"> </login-module> <login-module code="org.exoplatform.services.security.j2ee.jbossloginmodule" flag="required"> <module-option name="portalcontainername">portal</module-option> <module-option name="realmname">gatein-domain</module-option> </login-module> </authentication> 4. The installation can be tested at this point. a. Start (or restart) JBoss Enterprise Portal Platform, and (assuming the JOSSO server on T omcat is running) direct your browser to b. Login with the username root and the password gtn or any account created through the portal. The next part of the process is to redirect all user authentication to the JOSSO server. 124

128 Chapter 14. Authentication and Identity Information about where the JOSSO server is hosted must be properly configured within the JBoss Enterprise Portal Platform instance. T he required configuration is done by modifying four files: Procedure Setup the portal to redirect to JOSSO 1. In the <JBOSS_HOME>/server/<PROFILE>/deploy/gatein.ear/web.war/groovy/groovy/webu i/com ponent/uibannerportlet.gtm l file modify the 'Sign In' link as follows: <!--<a class="login" onclick="$signinaction"><%=_ctx.appres("uiloginform.label.signin")%></a>--> <a class="login" href="/portal/sso"><%=_ctx.appres("uiloginform.label.signin")%></a> 2. Modify the 'Sign In' link in the gatein.ear/web.war/groovy/portal/webui/com ponent/uilogoportlet.gtm pl file as follows: <!-- <a onclick="$signinaction"><%=_ctx.appres("uilogoportlet.action.signin")%></a> --> <a href="/portal/sso"><%=_ctx.appres("uilogoportlet.action.signin")%></a> 3. Replace the entire contents of gatein.ear/02portal.war/login/jsp/login.jsp with: <html> <head> <script type="text/javascript"> window.location = '/portal/sso'; </script> </head> <body> </body> </html> 4. Add the following Filters to the top of the filter chain in gatein.ear/02portal.war/web- INF/web.xm l: 125

129 Red Hat JBoss Portal 5.1 Reference Guide <filter> <filter-name>loginredirectfilter</filter-name> <filter-class>org.gatein.sso.agent.filter.loginredirectfilter</filterclass> <init-param> <!-- This should point to your SSO authentication server --> <param-name>login_url</param-name> <param-value> josso_back_to= </init-param> </filter> <filter> <filter-name>jossologoutfilter</filter-name> <filter-class>org.gatein.sso.agent.filter.jossologoutfilter</filterclass> <init-param> <!-- This should point to your JOSSO authentication server --> <param-name>logout_url</param-name> <param-value> </init-param> </filter> <!-- filters should be placed at the very top of the filter chain --> <filter-mapping> <filter-name>loginredirectfilter</filter-name> <url-pattern>/* </url-pattern> </filter-mapping> <filter-mapping> <filter-name>jossologoutfilter</filter-name> <url-pattern>/* </url-pattern> </filter-mapping> 5. Replace the InitiateLoginServlet declaration in gatein.ear/02portal.war/web- INF/web.xm l with: <servlet> <servlet-name>initiateloginservlet</servlet-name> <servlet-class>org.gatein.sso.agent.genericssoagent</servlet-class> <init-param> <param-name>ssoserverurl</param-name> <param-value> </init-param> </servlet> 6. Remove the PortalLoginController servlet declaration and mapping in gatein.ear/02portal.war/web-inf/web.xm l From now on, all links redirecting to the user authentication pages will redirect to the JOSSO centralized authentication form OpenSSO - The Open Web SSO project T his Single Sign On plugin enables seamless integration between JBoss Enterprise Portal Platform and the Open Web SSO project (OpenSSO) Single Sign On Framework. Details about OpenSSO can be found here. T his section details the setting up of OpenSSO server to authenticate against the JBoss Enterprise Portal Platform login module. 126

130 Chapter 14. Authentication and Identity Procedure Obtaining OpenSSO 1. Download OpenSSO from 2. Extract the package into a suitable location. T his location will be referred to as OPENSSO_HOME in this example. To configure the web server as required, it is simpler to directly modify the source files. T he first step is to add the JBoss Enterprise Portal Platform Authentication Plugin. T he plugin makes secure callbacks to a REST ful service installed on the remote JBoss Enterprise Portal Platform server to authenticate a user. In order for the plugin to function correctly, it needs to be properly configured to connect to this service. This configuration is done via the opensso.war/config/auth/default/authenticationplugin.xm l file. Procedure Modifying OpenSSO server 1. Obtain a copy of Tomcat and extract it into a suitable location. This location will be referred to as TOMCAT_HOME in this example. 2. Edit TOMCAT_HOME/conf/server.xml and change the 8080 port to 8888 to avoid a conflict with the default JBoss Enterprise Portal Platform port. Note If JBoss Enterprise Portal Platform is running on the same machine as T omcat, other ports need to be changed in addition to 8080 in order to avoid port conflicts. They can be changed to any free port. For example, you can change the admin port from 8005 to 8805 and the AJP port from 8009 to Ensure the T OMCAT_HOME/webapps/opensso/config/auth/default/AuthenticationPlugin.xm l file matches the following: 127

131 Red Hat JBoss Portal 5.1 Reference Guide <?xml version='1.0' encoding="utf-8"?> <!DOCTYPE ModuleProperties PUBLIC "=//iplanet//authentication Module Properties XML Interface 1.0 DTD//EN" "jar://com/sun/identity/authentication/auth_module_properties.dtd"> <ModuleProperties modulename="authenticationplugin" version="1.0" > <Callbacks length="2" order="1" timeout="60" header="gatein OpenSSO Login" > <NameCallback> <Prompt> Username </Prompt> </NameCallback> <PasswordCallback echopassword="false" > <Prompt> Password </Prompt> </PasswordCallback> </Callbacks> </ModuleProperties> 4. Copy the following files; PORTAL_SSO/opensso/plugin/WEB-INF/lib/sso-opensso-plugin-<VERSION>.jar PORTAL_SSO/opensso/plugin/WEB-INF/lib/com m ons-httpclient-<version>.jar PORTAL_SSO/opensso/plugin/WEB-INF/lib/com m ons-logging-<version>.jar...into the T omcat directory at T OMCAT_HOME/webapps/opensso/WEB-INF/lib. 5. Copy the PORTAL_SSO/opensso/plugin/WEB-INF/classes/gatein.properties file into the T OMCAT_HOME/webapps/opensso/WEB-INF/classes directory. 6. T omcat should start and be able to access 128

132 Chapter 14. Authentication and Identity Note Login will not be available at this point. Procedure Configure the "gatein" realm 1. Direct your browser to 2. Create a default configuration. 3. Login as admin. Important Go to the "Configuration" tab then to "Authentication". Follow the link to "Core" and add a new value with the class name "org.gatein.sso.opensso.plugin.authenticationplugin". If this is not done AuthenticationPlugin is not available among other OpenSSO authentication modules. 4. Go to the "Access control" tab and create new realm called "gatein". 5. a. Go to the new "gatein" realm and click on the "Authentication" tab. b. Click on "ldapservice" (at the bottom in the "Authentication chaining" section). c. Change the selection from "Datastore", which is the default module in the authentication chain, to "AuthenticationPlugin". T hese changes enable authentication of the "gatein" realm using the GateIn REST service instead of the OpenSSO LDAP server. 6. Go to "Advanced properties" and change UserProfile from "Required" to "Dynamic" to ensure all new users are automatically created in the OpenSSO datastore after successful authentication. 7. Increase the user privileges to allow REST access with the following procedure: a. Go to "Access control", then Top level realm, then click on the "Privileges" tab and go to "All authenticated users". b. Check the last two checkboxes: Read and write access only for policy properties Read and write access to all realm and policy properties 8. Repeat step 7 for the 'gatein' realm as well. Procedure Setup the OpenSSO client 1. Copy all libraries from the PORTAL_SSO/opensso/gatein.ear/lib directory into the JBOSS_HOME/server/default/deploy/gatein.ear/lib directory. Alternatively, in a T omcat environment, copy the libraries into the GAT EIN_HOME/lib directory. 2. Edit the jboss-as/server/profile/deploy/gatein.ear/met A-INF/gatein-jbossbeans.xm l and uncomment this section: 129

133 Red Hat JBoss Portal 5.1 Reference Guide <authentication> <login-module code="org.gatein.sso.agent.login.ssologinmodule" flag="required"> </login-module> <login-module code="org.exoplatform.services.security.j2ee.jbossloginmodule" flag="required"> <module-option name="portalcontainername">portal</module-option> <module-option name="realmname">gatein-domain</module-option> </login-module> </authentication> 3. T est the installation: a. Access JBoss Enterprise Portal Platform by going to (assuming that the OpenSSO server using T omcat is still running). b. Login with the username root and the password gtn or any account created through the portal. The next part of the process is to redirect all user authentication to the OpenSSO server. Information about where the OpenSSO server is hosted must be properly configured within the Enterprise Portal Platform instance. T he required configuration is done by modifying three files: Procedure Setup the portal to redirect to OpenSSO 1. Modify the 'Sign In' link in the <JBOSS_HOME>/server/<PROFILE>/deploy/gatein.ear/web.war/groovy/groovy/webu i/com ponent/uibannerportlet.gtm l file as follows: <!-- <a class="login" onclick="$signinaction"><%=_ctx.appres("uiloginform.label.signin")%></a> --> <a class="login" href="/portal/sso"><%=_ctx.appres("uiloginform.label.signin")%></a> 2. Modify the 'Sign In' link in the gatein.ear/web.war/groovy/portal/webui/com ponent/uilogoportlet.gtm pl file as follows: <!-- <a onclick="$signinaction"><%=_ctx.appres("uilogoportlet.action.signin")%></a> --> <a href="/portal/sso"><%=_ctx.appres("uilogoportlet.action.signin")%></a> 3. Replace the entire contents of gatein.ear/02portal.war/login/jsp/login.jsp with: 130

134 Chapter 14. Authentication and Identity <html> <head> <script type="text/javascript"> window.location = '/portal/sso'; </script> </head> <body> </body> </html> 4. Add the following Filters to the top of the filter chain in gatein.ear/02portal.war/web- INF/web.xm l: <filter> <filter-name>loginredirectfilter</filter-name> <filter-class>org.gatein.sso.agent.filter.loginredirectfilter</filterclass> <init-param> <!-- This should point to your SSO authentication server --> <param-name>login_url</param-name> <param-value> realm=gatein&amp;goto= -value> </init-param> </filter> <filter> <filter-name>openssologoutfilter</filter-name> <filter-class>org.gatein.sso.agent.filter.openssologoutfilter</filterclass> <init-param> <!-- This should point to your OpenSSO authentication server --> <param-name>logout_url</param-name> <param-value> </init-param> </filter> <!-- place the filters at the top of the filter chain --> <filter-mapping> <filter-name>loginredirectfilter</filter-name> <url-pattern>/* </url-pattern> </filter-mapping> <filter-mapping> <filter-name>openssologoutfilter</filter-name> <url-pattern>/* </url-pattern> </filter-mapping> 5. Replace the InitiateLoginServlet declaration in gatein.ear/02portal.war/web- INF/web.xm l with: 131

135 Red Hat JBoss Portal 5.1 Reference Guide <servlet> <servlet-name>initiateloginservlet</servlet-name> <servlet-class>org.gatein.sso.agent.genericssoagent</servlet-class> <init-param> <param-name>ssoserverurl</param-name> <param-value> </init-param> <init-param> <param-name>ssocookiename</param-name> <param-value>iplanetdirectorypro</param-value> </init-param> </servlet> From now on, all links redirecting to the user authentication pages will redirect to the OpenSSO centralized authentication form SPNEGO - Simple and Protected GSSAPI Negotiation Mechanism T he Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO) uses desktop credentials provided during a desktop login to transparently authenticate a portal user through a web browser. For illustrative purposes; a typical use case would be: 1. A user logs into their desktop computer with a login that is governed by an Active Directory domain. 2. The user then launches a web browser to access a web application (that uses JBoss Negotiation) hosted on JBoss Enterprise Portal Platform. 3. T he browser transfers the desktop credentials to the web application. 4. JBoss EAP/AS uses background GSS messages with the Active Directory (or any Kerberos Server) to validate the user. 5. T he user experiences a seamless single sign on (SSO) into the web application. JBoss Enterprise Portal Platform uses JBoss Negotiation to enable SPNEGO-based desktop SSO. T he following procedure outlines how to integrate SPNEGO with the JBoss Enterprise Portal Platform. Procedure SPNEGO Configuration 1. Activate the Host authentication. Add the following host login module to the jbossas/server/profile/conf/login-config.xm l: 132

136 Chapter 14. Authentication and Identity <!-- SPNEGO domain --> <application-policy name="host"> <authentication> <login-module code="com.sun.security.auth.module.krb5loginmodule" flag="required"> <module-option name="storekey">true</module-option> <module-option name="usekeytab">true</module-option> <module-option LOCAL.NETWORK</module-option> <module-option name="keytab">/home/user/krb5keytabs/jboss.keytab</module-option> <module-option name="donotprompt">true</module-option> <module-option name="debug">true</module-option> </login-module> </authentication> </application-policy> The 'keytab' value should point to the keytab file that was generated by the kadmin Kerberos tool. See the Setting up your Kerberos Development Environment guide for more details. 2. Extend the core authentication mechanisms to support SPNEGO. Under deployers/jbossweb.deployer/met A-INF/war-deployers-jboss-beans.xm l, add a 'SPNEGO' authenticators property 133

137 Red Hat JBoss Portal 5.1 Reference Guide <property name="authenticators"> <map keyclass="java.lang.string" valueclass="java.lang.string"> <entry> <key>basic</key> <value>org.apache.catalina.authenticator.basicauthenticator</value> </entry> <entry> <key>client-cert</key> <value>org.apache.catalina.authenticator.sslauthenticator</value> </entry> <entry> <key>digest</key> <value>org.apache.catalina.authenticator.digestauthenticator</value> </entry> <entry> <key>form</key> <value>org.apache.catalina.authenticator.formauthenticator</value> </entry> <entry> <key>none</key> <value>org.apache.catalina.authenticator.nonloginauthenticator</value> </entry> <!-- Add this entry --> <entry> <key>spnego</key> <value>org.jboss.security.negotiation.negotiationauthenticator</value> </entry> </map> </property> 3. Add the Gatein SSO module binaries by adding PORTAL_SSO/spnego/gatein.ear/lib/ssoagent.jar and PORTAL_SSO/spnego/gatein.ear/lib/spnego-VERSION-epp-GA.jar to deploy/gatein.ear/lib. 4. Modifying deploy/gatein.ear/met A-INF/gatein-jboss-beans.xm l to match the following: 134

138 Chapter 14. Authentication and Identity <deployment xmlns="urn:jboss:bean-deployer:2.0"> <application-policy xmlns="urn:jboss:security-beans:1.0" name="gateindomain"> <!-- Uncomment this for Kerberos based SSO integration --> <authentication> <login-module code="org.gatein.sso.spnego.spnegologinmodule" flag="requisite"> <module-option name="password-stacking">usefirstpass</module-option> <module-option name="serversecuritydomain">host</module-option> </login-module> <login-module code="org.gatein.sso.agent.login.spnegorolesmodule" flag="required"> <module-option name="password-stacking">usefirstpass</module-option> <module-option name="portalcontainername">portal</module-option> <module-option name="realmname">gatein-domain</module-option> </login-module> </authentication> </application-policy> </deployment> T his activates the SPNEGO LoginModule for use with JBoss Enterprise Portal Platform. 5. Modify gatein.ear/02portal.war/web-inf/web.xm l to match: <!-- <login-config> <auth-method>form</auth-method> <realm-name>gatein-domain</realm-name> <form-login-config> <form-login-page>/initiatelogin</form-login-page> <form-error-page>/errorlogin</form-error-page> </form-login-config> </login-config> --> <login-config> <auth-method>spnego</auth-method> <realm-name>spnego</realm-name> </login-config> T his integrates SPNEGO support into the Portal web archive by switching authentication mechanism from the default "FORM"-based to "SPNEGO"-based authentication. 6. Add the following filters to the top of the Filter chain in the web.xml file: 135

139 Red Hat JBoss Portal 5.1 Reference Guide <filter> <filter-name>loginredirectfilter</filter-name> <filter-class>org.gatein.sso.agent.filter.loginredirectfilter</filterclass> <init-param> <!-- This should point to your SSO authentication server --> <param-name>login_url</param-name> <param-value>/portal/private/classic</param-value> </filter> <filter> <filter-name>spnegofilter</filter-name> <filter-class>org.gatein.sso.agent.filter.spnegofilter</filter-class> </filter> <filter-mapping> <filter-name>loginredirectfilter</filter-name> <url-pattern>/* </url-pattern> </filter-mapping> <filter-mapping> <filter-name>spnegofilter</filter-name> <url-pattern>/* </url-pattern> </filter-mapping> T his integrates request pre-processing needed for SPNEGO. 7. Edit the 'Sign In' link in JBOSS_HOME/server/PROFILE/deploy/gatein.ear/web.war/groovy/groovy/webui/c om ponent/uibannerportlet.gtm pl to match the following: <!--<a onclick="$signinaction"><%=_ctx.appres("uiloginform.label.signin")%></a>--> <a href="/portal/sso"><%=_ctx.appres("uiloginform.label.signin")%></a> T his modifies the Portal's 'Sign In' link to perform SPNEGO authentication. 8. Start the JBoss Enterprise Portal Platform; sudo./run.sh -Djava.security.krb5.realm=LOCAL.NETWORK - Djava.security.krb5.kdc=server.local.network -c spnego -b server.local.network T he PROFILE parameter in the above command should be replaced with the server profile modified with the above configuration. 9. Login to Kerberos: kinit -A demo Clicking the 'Sign In' link on the JBoss Enterprise Portal Platform should automatically sign the 'demo' user into the portal LDAP Integration 136

140 Chapter 14. Authentication and Identity Notational Device For ease of readability the following section uses the notational device ID_HOME to represent the file path JBOSS_HOME/server/<PROFILE>/deploy/gatein.ear/02portal.war/WEB- INF/conf/organization/, as this directory is the root of all JBoss Enterprise Portal Platform's identity-related configuration. LDAP (Lightweight Directory Access Protocol) is a set of open protocols used to access centrally stored information over a network. It is based on the X.500 standard for directory sharing, but is less complex and resource-intensive. Using a client/server architecture, LDAP provides a reliable means to create a central information directory accessible from the network. When a client attempts to modify information within this directory, the server verifies the user has permission to make the change, and then adds or updates the entry as requested. T o ensure the communication is secure, the Secure Sockets Layer (SSL) or T ransport Layer Security (TLS) cryptographic protocols can be used to prevent an attacker from intercepting the transmission. LDAP provides the protocols required to manage the data stored in a Directory Server. A Directory Server contains information about resources available (user accounts and printers for example) and their location on the network. T he following table is a list of Directory Servers that are supported and certified in JBoss Enterprise Portal Platform. T able Supported and Certified directory servers Directory Server OpenDS 1.2 OpenDS 2.0 OpenLDAP 2.4 Red Hat Directory Server (RHDS) 7.1 Version Microsoft Active Directory (MSAD) Windows Server 2008 Examples JBoss Enterprise Portal Platform includes several example LDAP configuration.xml files and.ldif (LDAP Data Interchange Format) data files. T hese examples are in the ID_HOME/picketlink-idm/exam ples directory and can be deployed in a testing environment to assist in configuring LDAP. Procedure LDAP Set Up 1. Install your LDAP server by following the installation instructions provided for the product you are using. If you are installing the Red Hat Directory Server (RHDS), you should refer to the Installation Guide at If you are using a third party directory server (OpenDS, OpenLDAP or Miscrosoft Active Directory (MSAD)), refer the appropriate documentation for that product. 137

141 Red Hat JBoss Portal 5.1 Reference Guide T he following values provide an example of working configuration settings for the different Directory Servers: Table Director y Server Value root user Distingu ished Name (DN) Passwor d Port Admin Port Base DN Databas e Populati on SSO/T L S RHDS and OpenDS cn=direct ory Manager passwor d dc=exam ple,dc=co m "Only create the base entry" no SSO, no TLS MSAD CN=User s OpenLD AP cn=mana ger,dc=e xample,d c=com secret 1389 dc=exam ple,dc=co m T hese, and other appropriate settings, should be adjusted to suit your circumstances. 2. Optional: Import an ldif file and populate the Directory Server. 3. Start the Directory Server LDAP in Read-only Mode This section will show you how to add LDAP in read-only mode. This means that user data entries (both pre-existing, and newly added through the JBoss Enterprise Portal Platform User Interface) will be consumed though the Directory Server and LDAP services, but written to the underlying database. T he only exception is that passwords updated via the UI will also be propagated into the appropriate LDAP entry. Procedure Set up LDAP read-only Mode 1. Open the ID_HOME/idm-configuration.xm l file. JBoss Enterprise Portal Platform uses the PicketLink IDM framework as the underlying identity storage system, hence all the configurations use dedicated Picketlink settings. 2. Comment out the default Picketlink config value: <value>war:/conf/organization/picketlink-idm/picketlink-idmconfig.xml</value> 3. Uncomment the appropriate sample configuration values as described below, depending on which Directory Server you are implementing: Procedure 14.25, Red Hat Directory Server or OpenDS Procedure 14.26, Microsoft Active Directory Procedure 14.27, OpenLDAP Procedure Red Hat Directory Server or OpenDS 138

142 Chapter 14. Authentication and Identity a. Uncomment the line under "Read Only "ACME" LDAP Example": <!--Read Only "ACME" LDAP Example--> <value>war:/conf/organization/picketlink-idm/examples/picketlink-idmldap-acme-config.xml</value> b. Uncomment the grouptypemappings under "Uncomment for ACME LDAP example": <!-- Uncomment for ACME LDAP example --> <entry> <key><string>/acme/roles/* </string></key> <value><string>acme_roles_type</string></value> </entry> <entry> <key><string>/acme/organization_units/* </string></key> <value><string>acme_ou_type</string></value> </entry> Refer to Example 14.2, Read Only groupt ypemappings for more information about how these grouptypemappings operate. c. Continue to Step 4. Procedure Microsoft Active Directory a. Uncomment the line under "MSAD Read Only "ACME" LDAP Example": <!--MSAD Read Only "ACME" LDAP Example--> <value>war:/conf/organization/picketlink-idm/examples/picketlink-idmmsad-readonly-config.xml</value> b. Uncomment the grouptypemappings under "Uncomment for MSAD ReadOnly LDAP example": <!-- Uncomment for MSAD ReadOnly LDAP example --> <entry> <key><string>/acme/roles/* </string></key> <value><string>msad_roles_type</string></value> </entry> Refer to Example 14.2, Read Only groupt ypemappings for more information about how these grouptypemappings operate. c. Continue to Step 4. Procedure OpenLDAP a. If you have not done so already, install your LDAP server. Refer to Procedure 14.23, LDAP Set Up for some assistance. b. Uncomment the line under "OpenLDAP ReadOnly "ACME" LDAP Example": <!--OpenLDAP ReadOnly "ACME" LDAP Example--> <value>war:/conf/organization/picketlink-idm/examples/picketlink-idmopenldap-acme-config.xml</value> c. Uncomment the grouptypemappings under "Uncomment for ACME LDAP example": 139

143 Red Hat JBoss Portal 5.1 Reference Guide <!-- Uncomment for ACME LDAP example --> <entry> <key><string>/acme/roles/* </string></key> <value><string>acme_roles_type</string></value> </entry> <entry> <key><string>/acme/organization_units/* </string></key> <value><string>acme_ou_type</string></value> </entry> Refer to Example 14.2, Read Only groupt ypemappings for more information about how these grouptypemappings operate. d. Continue to Step To use a different LDAP server or directory data, edit the DS-specific.xml file you uncommented in Substep 3a above and change the values to suit your requirements. Refer to the list in Example 14.1, LDAP configuration for some examples or refer to the productspecific documentation for more information. 5. Start the server. 6. Navigate to the portal homepage ( and log in as an administrator. 7. Navigate to Group Organization Users and groups management. a. Create a new group called acme under the root node. b. For RHDS, OpenDS and OpenLDAP: Create two sub-groups called roles and organization_units. For MSAD: Create a subgroup called roles. Users defined in LDAP should be visible in "Users and groups management" and groups from LDAP should be present as children of /acme/roles and /acme/organization_units. More information about configuration can be found in Section 14.4, PicketLink IDM integration and in the PicketLink project Reference Guide LDAP as Default Store Follow the procedure below to set LDAP up as the default identity store for JBoss Enterprise Portal Platform. All default accounts and some of groups that comes with JBoss Enterprise Portal Platform will be created in the LDAP store. The LDAP server will be configured to store part of the JBoss Enterprise Portal Platform group tree. This means that groups under specified part of the tree will be stored in directory server while all others will be stored in database. Procedure Set up LDAP as Default Indentity Store 1. If you have not done so already, install your LDAP server. Refer to Procedure 14.23, LDAP Set Up for some assistance. 2. Open the ID_HOME/idm-configuration.xm l file. JBoss Enterprise Portal Platform uses the PicketLink IDM framework as the underlying identity storage system, hence all the configurations use dedicated Picketlink settings. 3. Comment out the default Picketlink config value: war:/conf/organization/picketlinkidm/picketlink-idm-config.xml 4. Uncomment the appropriate LDAP configuration entry depending on your LDAP server: 14 0

144 Chapter 14. Authentication and Identity Procedure For RHDS and OpenDS a. Expose the entry under "Sample LDAP config": <!--Sample LDAP config--> <value>war:/conf/organization/picketlink-idm/examples/picketlink-idmldap-config.xml</value> b. Continue to Step 5 Procedure For MSAD a. Expose the entry under "MSAD LDAP Example": <!--MSAD LDAP Example--> <value>war:/conf/organization/picketlink-idm/examples/picketlink-idmmsad-config.xml</value> Procedure To use SSL encryption with MSAD: a. Open the ID_HOME/picketlink-idm/exam ples/picketlink-idm-m sadconfig.xm l. b. Ensure the following entries are uncommented and that the path to the truststore file and password are correct: <option> <name>customsystemproperties</name> <value>javax.net.ssl.truststore=/path/to/truststore</value> <value>javax.net.ssl.truststorepassword=password</value> </option> You can import a custom certificate by replacing the certificate and truststore details in the following command: keytool -import -file certificate -keystore truststore b. Continue to Step 5 Procedure For OpenLDAP a. Expose the entry under "OpenLDAP LDAP config": <!--OpenLDAP LDAP config--> <value>war:/conf/organization/picketlink-idm/examples/picketlink-idmopenldap-config.xml</value> b. Continue to Step 5 5. Uncomment the grouptypemappings under "Uncomment for sample LDAP configuration": <entry> <key><string>/platform/* </string></key> <value><string>platform_type</string></value> </entry> <entry> <key><string>/organization/* </string></key> <value><string>organization_type</string></value> </entry> Refer to Example 14.3, Default grouptypemappings for more information about how these 14 1

145 Red Hat JBoss Portal 5.1 Reference Guide grouptypemappings operate. 6. To use a different LDAP server or directory data, edit the DS-specific.xml file you uncommented in Step 4 above and change the values to suit your requirements. Refer to the list in Example 14.1, LDAP configuration for some examples or refer to the productspecific documentation for more information. 7. Start the server. 8. Navigate to the portal homepage ( and log in as an administrator Examples 14 2

146 Chapter 14. Authentication and Identity Example LDAP configuration The following settings are stored in the Picketlink configuration file that is nominated in the idmconfiguration.xml file of your deployment (under the config parameter of the PicketLinkIDMService component): This file could be: T he default picketlink-idm-config.xm l. One of the three example configuration files discussed in Procedure 14.24, Set up LDAP readonly Mode : picketlink-idm-ldap-acm e-config.xm l picketlink-idm-m sad-readonly-config.xm l picketlink-idm-openldap-acm e-config.xm l A custom file created by modifying one of the above files. Configuration options ctxdns This is the DN that will be used as context for IdentityObject searches. More than one value can be specified. Some examples are: ou=people,o=acme,dc=example,dc=com ou=roles,o=acme,dc=example,dc=com ou=organizationunits,o=acme,dc=example,dc=com MSAD: CN=Users,DC=test,DC=domain (in two places). providerurl T he LDAP server connection URL. Formatted as "ldap://localhost:<port>". T he default setting is: ldap://localhost:1389. MSAD: Should use SSL connection (ldaps://xxx:636) for password update or creation to work. admindn The LDAP entry used to connect to the server. Some possible values are: RHDS or OpenDS: cn=directory Manager OpenLDAP: cn=manager,dc=my-domain,dc=com MSAD: T EST\Administrator adminpassword T he password associated with the admindn. customsystemproperties 14 3

147 Red Hat JBoss Portal 5.1 Reference Guide This option defines the values needed to use SSL encryption with LDAP. 14 4

148 Chapter 14. Authentication and Identity Example Read Only groupt ypemappings T he grouptypemappings exposed in the idm-configuration.xm l file correspond to identityobject-type values defined in the DS-specific configuration file (referenced in Sub-step 3a of the DS-specific procedure above). For RHDS, OpenDS and OpenLDAP the picketlink-idm-ldap-acme-config.xml and picketlink-idm-openldap-acm e-config.xm l files contain the following values: <repository> <id>portalrepository</id> <class>org.picketlink.idm.impl.repository.fallbackidentitystorerepository</class > <external-config/> <default-identity-store-id>hibernatestore</default-identity-store-id> <default-attribute-store-id>hibernatestore</default-attribute-store-id> <identity-store-mappings> <identity-store-mapping> <identity-store-id>portalldapstore</identity-store-id> <identity-object-types> <identity-object-type>user</identity-object-type> <identity-object-type>acme_roles_type</identity-object-type> <identity-object-type>acme_ou_type</identity-object-type> </identity-object-types> <options> <option> <name>readonly</name> <value>true</value> </option> </options> </identity-store-mapping> </identity-store-mappings> <options> <option> <name>allownotdefinedattributes</name> <value>true</value> </option> </options> </repository> T he PicketLink IDM configuration file dictates that users and those two group types be stored in LDAP. An additional option defines that nothing else (except password updates) should be written there. All groups under /acme/roles will be stored in PicketLink IDM with the acme_roles_type group type name and groups under /acme/organization_units will be stored in PicketLink IDM with acme_ou_type group type name. For MSAD, the identity-object-types values in picketlink-idm-m sad-readonlyconfig.xm l change to: 14 5

149 Red Hat JBoss Portal 5.1 Reference Guide <identity-store-id>portalldapstore</identity-store-id> <identity-object-types> <identity-object-type>user</identity-object-type> <identity-object-type>msad_roles_type</identity-object-type> </identity-object-types> The difference is that this configuration maps only one group type and points to the same container in LDAP for both users and mapped groups. 14 6

150 Chapter 14. Authentication and Identity Example Default groupt ypemappings T he grouptypemappings exposed in the idm-configuration.xm l file correspond to identityobject-type values defined in the DS-specific configuration file (referenced in Sub-step 3a of the DS-specific procedure above). All of the supported LDAP configurations use the following values when implemented as the default identity store: <repository> <id>portalrepository</id> <class>org.picketlink.idm.impl.repository.fallbackidentitystorerepository</class > <external-config/> <default-identity-store-id>hibernatestore</default-identity-store-id> <default-attribute-store-id>hibernatestore</default-attribute-store-id> <identity-store-mappings> <identity-store-mapping> <identity-store-id>portalldapstore</identity-store-id> <identity-object-types> <identity-object-type>user</identity-object-type> <identity-object-type>platform_type</identity-object-type> <identity-object-type>organization_type</identity-object-type> </identity-object-types> <options/> </identity-store-mapping> </identity-store-mappings> <options> <option> <name>allownotdefinedattributes</name> <value>true</value> </option> </options> </repository> <repository> <id>defaultportalrepository</id> <class>org.picketlink.idm.impl.repository.wrapperidentitystorerepository</class> <external-config/> <default-identity-store-id>hibernatestore</default-identity-store-id> <default-attribute-store-id>hibernatestore</default-attribute-store-id> </repository> T he grouptypemappings define that all groups under /platform should be stored in PicketLink IDM with the platform_type group type name and groups under /organization should be stored in PicketLink IDM with organization_type group type name. T he PicketLink IDM configuration file repository maps users and those two group types as stored in LDAP. 14 7

151 Red Hat JBoss Portal 5.1 Reference Guide Chapter 15. Web Services for Remote Portlets (WSRP) Introduction T he Web Services for Remote Portlets (WSRP) specification defines a web service interface for accessing and interacting with interactive presentation-oriented web services. It has been produced through the efforts of the Web Services for Remote Portlets (WSRP) OASIS T echnical Committee. It is based on the requirements gathered and the proposals made to the committee. Scenarios that motivate WSRP functionality include: Content hosts, such as portal servers, providing Portlets as presentation-oriented web services that can be used by aggregation engines. Aggregating frameworks, including portal servers, consuming presentation-oriented web services offered by content providers and integrating them into the framework. More information on WSRP can be found on the official website. We suggest reading the primer for a good, albeit technical, overview of WSRP Level of Support T he WSRP T echnical Committee defined WSRP Use Profiles to help with WSRP interoperability. T erms defined in that document will be used in this section. JBoss Enterprise Portal Platform provides a Simple level of support for the WSRP Producer, with the exception of out-of-band registration. In-band registration and persistent local state (which are defined at the Complex level) are supported. JBoss Enterprise Portal Platform provides a Medium level of support for the Consumer, excepting HT ML markup (as JBoss Enterprise Portal Platform itself does not handle other markup types). Explicit portlet cloning and the PortletManagem ent interface are supported. T he WSRP component has Level 1 Producer and Consumer caching. Cookie handling is supported properly on the Consumer. T he Producer requires cookie initialization (as this improves interoperability with some consumers). JBoss Enterprise Portal Platform does not support custom window states or modes, therefore neither does the WSRP component. It does, however, support CSS on both the Producer (although this is more a function of the portlets than an inherent Producer capability) and Consumer. JBoss Enterprise Portal Platform 5.1 includes implementations of WSRP 1.0 and 2.0. All optional features in WSRP 2 are implemented in JBoss Enterprise Portal Platform 5.1 except support for lifetimes and leasing support Deploying WSRP 14 8

152 Chapter 15. Web Services for Remote Portlets (WSRP) Notational Devices T he following list of support files uses the following notational devices: Notations: JBOSS_HOME JBOSS_HOME refers to the directory that your instance of JBoss Enterprise Portal Platform has been extracted/installed to. For example: /hom e/username/jbossepp-<version>/ WSRP_PATH The WSRP files referred to in this section are found in the JBOSS_HOME/jbossas/server/<PROFILE>/deploy/gatein.ear directory. For ease of reference this path will be represented by: WSRP_PATH. WSRP_VERSION WSRP_VERSION represents the version of the WSRP component in use. PORTAL_VERSION PORTAL_VERSION represents the version of JBoss Enterprise Portal Platform in use. WSRP support files WSRP_PATH/wsrp-admin-gui.war T his file contains the WSRP Configuration portlet with which you can configure consumers to access remote servers and how the WSRP producer is configured. WSRP_PATH/wsrp-producer.war T his file contains the WSRP producer web application. WSRP_PATH/lib/wsrp-common-WSRP_VERSION.jar T his file contains common classes needed by the different WSRP libraries. WSRP_PATH/lib/wsrp-consumer-WSRP_VERSION.jar T his file contains the WSRP consumer. WSRP_PATH/lib/wsrp-integration-api-WSRP_VERSION.jar T his file contains the API classes needed to integrate the WSRP component into portals. WSRP_PATH/lib/wsrp-producer-lib-$WSRP_VERSION.jar This file contains the classes needed by the WSRP producer. WSRP_PATH/lib/wsrp-wsrp1-ws-WSRP_VERSION.jar T his file contains the generated JAX-WS classes for WSRP version

153 Red Hat JBoss Portal 5.1 Reference Guide WSRP_PATH/lib/wsrp-wsrp2-ws-WSRP_VERSION.jar This file contains the JAX-WS classes for WSRP version 2. WSRP_PATH/lib/gatein.portal.component.wsrp-PORTAL_VERSION.jar T his file contains the code to integrate the WSRP service into JBoss Enterprise Portal Platform Non-default Ports or Hostnames JBoss WS (the web service stack that JBoss Enterprise Portal Platform uses) should update the port and host name used in WSDL. Refer to the JBoss WS user guide for more information. If the host name and port on which the server runs have been modified, the configuration for the Consumer used to consume JBoss Enterprise Portal Platform's "self" Producer will need to be updated. Refer to Section 15.6, Consuming Remote WSRP Portlets for directions on how to do this Using WSRP with SSL It is possible to use WSRP over SSL for secure exchange of data. Refer to these instructions for how to do this Making a Portlet Remotable Note Only JSR-286 (Portlet 2.0) portlets can be made remotable as the mechanism to expose a portlet to WSRP relies on a JSR-286-only functionality. JBoss Enterprise Portal Platform does not, by default, expose local portlets for consumption by remote WSRP consumers. In order to make a portlet remotely available, it must be made "remotable" by marking it as such in the associated portlet.xm l. A specific org.gatein.pc.rem otable container-runtim e-option is used to accomplish this. Setting its value to true makes the portlet available for remote consumption, while setting its value to false will not publish it remotely. As specifying the remotable status for a portlet is optional, nothing need be done if portlets do not need to be remotely available. In the following example, the "BasicPortlet" portlet is specified as being remotable. 150

154 Chapter 15. Web Services for Remote Portlets (WSRP) <?xml version="1.0" standalone="yes"?> <portlet-app xmlns=" xmlns:xsi=" xsi:schemalocation=" version="2.0"> <portlet-app> <portlet> <portlet-name>basicportlet</portlet-name>... <container-runtime-option> <name>org.gatein.pc.remotable</name> <value>true</value> </container-runtime-option> </portlet> </portlet-app> It is also possible to specify that all the portlets declared within a given portlet application be remotable by default. T his is done by specifying the container-runtim e-option at the portlet-app element level. Individual portlets can override that value to not be remotely exposed. For example: <?xml version="1.0" standalone="yes"?> <portlet-app xmlns=" xmlns:xsi=" xsi:schemalocation=" version="2.0"> <portlet-app> <portlet> <portlet-name>remotelyexposedportlet</portlet-name>... </portlet> <portlet> <portlet-name>notremotelyexposedportlet</portlet-name>... <container-runtime-option> <name>org.gatein.pc.remotable</name> <value>false</value> </container-runtime-option> </portlet> <container-runtime-option> <name>org.gatein.pc.remotable</name> <value>true</value> </container-runtime-option> </portlet-app> T his example defines two portlets. As the org.gatein.pc.rem otable container-runtim e- option is set to true at the portlet-app level, all portlets defined in this particular portlet application are exposed remotely by JBoss Enterprise Portal Platform's WSRP Producer. 151

155 Red Hat JBoss Portal 5.1 Reference Guide It is possible to override this default behavior. Specifying a value for the org.gatein.pc.remotable container-runtim e-option at the portlet level will take precedence over the default. In the example above, the RemotelyExposedPortlet inherits the remotable status defined at the portlet-app level since it does not specify a value for the org.gatein.pc.remotable container-runtim e-option. T he NotRem otelyexposedportlet, however, overrides the default behavior and is not remotely exposed. Note Portlets are not remotely exposed if no top-level org.gatein.pc.rem otable containerruntim e-option value is set to true Consuming WSRP portlets from a remote Consumer Configuration is extremely variable between different WSRP Consumers. Most, however, require a specification of the URL for the Producer's WSDL definition. If the JBoss Enterprise Portal Platform Consumer is not being used, refer to the documentation for the Consumer that is in use for specific instructions. For instructions on how to specify this URL in JBoss Enterprise Portal Platform, refer to Section 15.6, Consuming Remote WSRP Portlets. JBoss Enterprise Portal Platform's Producer is automatically set up when a portal instance is deployed with the WSRP service. The WSDL file can be accessed at: File paths: WSRP 1.0: WSRP 2.0: T he default hostname is localhost and the default port is Consuming Remote WSRP Portlets Overview To be able to consume WSRP portlets exposed by a remote producer, JBoss Enterprise Portal Platform's WSRP consumer must be configured to access that remote producer. Access to a remote producer can be configured using WSRP Producer descriptors. Alternatively, a portlet is provided to configure remote producers. 152

156 Chapter 15. Web Services for Remote Portlets (WSRP) Once a remote producer has been configured, the portlets that it exposes are then available in the Application Registry to be added to categories and then to pages Configuring a Remote Producer Access to a remote producer needs to be defined so that portlets can be consumed within JBoss Enterprise Portal Platform. T his section will show how to configure access to Oracle's public WSRP producer. Firstly using the configuration portlet. T hen how the same result can be accomplished with a producer descriptor, though it is far easier to do so via the configuration portlet. Chunked Encoding Some WSRP producers, such as Oracle, do not support chunked encoding. If your producer does not support chunked encoding, it will not be able to properly connect to the producer. T his will manifest itself with the following error: Caused by: org.jboss.ws.wsexception: Invalid HTTP server response [503] - Service Unavailable. A workaround for this issue involves editing the chunksize setting in the standard-jaxwsclient-config.xm l file. Refer to for more information T he Configuration Portlet JBoss Enterprise Portal Platform provides a graphical portlet to assist with configuring access to, and other facets of, remote WSRP Producers. It is available at: initialuri=%2fportal%2fprivate%2fclassic%2fwsrpconfiguration&username=root&password=gtn. T he portlet also is a group page for /platform/administrators Although the Configuration Portlet is installed by default in JBoss Enterprise Portal Platform 5.1., installation instructions are included below should the portlet ever need to be re-installed: Procedure Installing the configuration portlet: 1. Log into the portal as an administrator and go to the Application Registry (Click if using the default installation). 2. Add the WSRP Configuration portlet to the Administration category. If the Import Applications functionality is used, the WSRP Configuration portlet will be automatically added to the Administration category. 3. Once the portlet is added to a category, it can be added to a page and used. It is recommended that it be added to the same page as the Application Registry (as other operations relating to WSRP and adding portlets to categories are somewhat related). Add the WSRP Configuration portlet to the page using the standard procedure. 153

157 Red Hat JBoss Portal 5.1 Reference Guide T his screen presents all the configured consumers associated with their status and possible actions on them. A Consumer can be active or inactive. Activating a Consumer means that it is ready to act as a portlet provider. Note also that a Consumer can be marked as requiring refresh, which means that the information held about it might not be up to date. Refreshing it from the remote Producer will update this information. T his can happen for several reasons: the service description for that remote Producer has not been fetched yet, the cached version has expired or modifications have been made to the configuration that could potentially invalidate it, thus requiring re-validation of the information. To create a new Consumer: Procedure Creating a Consumer 1. T ype " oracle" into the "Create a consumer named:" field. 2. Click on "Create consumer" to create a new Consumer called oracle. 3. In the next form, set the cache expiration value to 300 seconds. 4. Leave the default timeout value for web services (WS) operations. 5. Enter the WSDL URL for the producer in the text field. 6. Press the "Refresh & Save" button: T his will retrieve the service description associated with the Producer which WSRP interface is described by the WSDL file found at the URL entered. In this case, querying the service description will show that the Producer requires registration but did not request any registration property: 154

158 Chapter 15. Web Services for Remote Portlets (WSRP) The Consumer for the oracle Producer should now be available as a portlet provider and be ready to be used. Assuming that the producer required a value for an em ail registration property, JBoss Enterprise Portal Platform's WSRP consumer will report that some information was missing: Values As at this release there is no automated way to learn about which possible values (if any) are expected by the remote Producer. Possible values may be indicated in the registration property description but this is not always the case. Refer to the specific Producer's documentation. Enter an address for the registration property ("exam ple@ exam ple.com") and press "Save & Refresh" once more: 155

159 Red Hat JBoss Portal 5.1 Reference Guide Using XML Although using the WSRP Configuration portlet to configure Consumers is recommended, the WSRP component provides an alternative way to configure consumers. T his is done by editing the XML file located at WSRP_PATH/lib/wsrpconsum er-wsrp_version.jar/conf/wsrp-consum ers-config.xm l. <?xml version='1.0' encoding='utf-8'?> <deployments xmlns=" xmlns:xsi=" xsi:schemalocation=" <deployment> <wsrp-producer id="self" expiration-cache="300" ws-timeout="30000"> <endpoint-wsdl-url> wsdl</endpoint-wsdl-url> <registration-data> <property> <name> </name> <lang>en</lang> <value>example@ example.com</value> </property> </registration-data> </wsrp-producer> </deployment> <deployment> <wsrp-producer id="oracle" expiration-cache="300"> <endpoint-wsdl-url> WSDL</endpoint-wsdl-url> <registration-data/> </wsrp-producer> </deployment> </deployments> T he file as shown above specifies access to two producers: self, which consumes JBoss Enterprise Portal Platform's own WSRP producer (albeit in a version that assumes that the producer requires a 156

160 Chapter 15. Web Services for Remote Portlets (WSRP) value for an em ail registration property), and oracle, which consumes Oracle's public producer, both in configurations as shown in the procedure above. Note An XML Schema defining which elements are available to configure Consumers via XML can be found in WSRP_PATH/lib/wsrp-integrationapi-WSRP_VERSION.jar/xsd/gatein_wsrp_consumer_1_0.xsd Adding remote portlets to categories Clicking on the Portlet link in the Application Registry will now show the remote portlets in the REMOTE tab in the left column: These portlets are available to be used as regular portlets: they can be used in categories and added to pages. Using the Import Applications functionality will also automatically import them into categories based on the keywords they define. More specifically, to add a WSRP portlet to a category, select wsrp in the Application Type drop-down menu: Configuring Access to Remote Producers via XML Again, configuring consumers via XML is done by editing WSRP_PATH/lib/wsrpconsum er-wsrp_version.jar/conf/wsrp-consum ers-config.xm l. 157

161 Red Hat JBoss Portal 5.1 Reference Guide The Consumer Configuration file It is important to understand how the XML Consumers configuration file is processed. It is read the first time the WSRP service starts and the associated information is then put under control of the JCR (Java Content Repository). Subsequent launches of the WSRP service will use the JCR-stored information for all producers that are already known to JBoss Enterprise Portal Platform. More specifically, the wsrpconsum ers-config.xm l file is scanned for producer identifiers. Any identifier that is already known will be bypassed and the JCR information associated with this remote producer will be used. The information defined at the XML level is only processed for producer definition for which no information is already present in the JCR. T herefore, to delete a Producer configuration, the associated information in the database must be deleted (this can be accomplished using the configuration portlet as shown in Section , T he Configuration Portlet ). T he associated information in wsrp-consum ers-config.xm l (if such information exists) must also be removed, otherwise the producer will be re-created the next time the WSRP is launched Required Configuration Information T he following information needs to be provided to configure access to a remote Producer: 1. An identifier must be provided for the producer being configured so that it can be referred to later. T his is done in the mandatory id attribute of the <wsrp-producer> element. 2. JBoss Enterprise Portal Platform also needs to know about the remote Producer's endpoints to be able to connect to the remote web services and perform WSRP invocations. Use the <endpointwsdl-url> element to specify the URL for the WSDL description of the remote WSRP service. Both the id attribute and <endpoint-wsdl-url> elements are required for a functional remote producer configuration Optional Configuration It is also possible to provide additional configuration, which, in some cases, might be important to establish a proper connection to the remote producer. Optional Configurations 158 Caching T o prevent unnecessary traffic between the local consumer and the remote producer, it is possible to cache some of the information sent by the producer (such as the list of offered portlets) for a given duration. T he rate at which the information is refreshed is defined by the expiration-cache attribute of the <wsrp-producer> element (in seconds). For example; providing a value of 120 for expiration-cache means that the producer information will not be refreshed for 2 minutes after it has been accessed. If no value is provided, JBoss Enterprise Portal Platform will always access the remote producer regardless of whether the remote information has changed or not. Since, in most instances, the information provided by the producer does not change often, use of this caching facility to minimize bandwidth usage is recommended.

162 Chapter 15. Web Services for Remote Portlets (WSRP) WS Timeout It is also possible to define a timeout after which WS operations are considered as failed. This is helpful to avoid blocking the WSRP service, as it waits on a service that does not answer. Use the ws-tim eout attribute of the <wsrp-producer> element to specify how many milliseconds the WSRP service will wait for a response from the remote producer before timing out. Pre-registration information Some producers require consumers to register with them before authorizing them to access their offered portlets. If known, some registration information can be provided in the producer configuration beforehand, so that the consumer can register with the remote producer when required. Note Only simple String properties are supported. It is not possible to configure complex registration data. However, this should be sufficient for most cases. T his pre-registration configuration is done via the <registration-data> element. If the remote producer does not require any registration properties, only an empty <registration-data> element need be provided, as JBoss Enterprise Portal Platform can generate the mandatory information. Values for the registration properties required by the remote producer can be provided via <property> elements. Refer to the example below for more details. Additionally, the default consumer name automatically provided by JBoss Enterprise Portal Platform can be overridden via the <consum er-nam e> element. When providing a consumer name, please remember that it should uniquely identify your consumer Examples This is the configuration of the selfv1 and selfv2 consumers as found in default-wsrp.xml with a cache expiring every five minutes and with a 30 second timeout for web service operations: 159

163 Red Hat JBoss Portal 5.1 Reference Guide <?xml version='1.0' encoding='utf-8'?> <deployments xmlns=" xmlns:xsi=" xsi:schemalocation=" <deployment> <wsrp-producer id="selfv1" expiration-cache="300" ws-timeout="30000"> <endpoint-wsdl-url> wsdl</endpoint-wsdl-url> <registration-data/> </wsrp-producer> </deployment> <deployment> <wsrp-producer id="selfv2" expiration-cache="300" ws-timeout="30000"> <endpoint-wsdl-url> wsdl</endpoint-wsdl-url> <registration-data/> </wsrp-producer> </deployment> </deployments> This is an example of a WSRP descriptor with registration data and cache expiring every minute: <?xml version='1.0' encoding='utf-8'?> <deployments xmlns=" xmlns:xsi=" xsi:schemalocation=" <deployments> <deployment> <wsrp-producer id="anotherproducer" expiration-cache="60"> <endpoint-wsdl-url> <registration-data> <property> <name>property name</name> <lang>en</lang> <value>property value</value> </property> </registration-data> </wsrp-producer> </deployment> </deployments> Consumers Maintenance Modifying a Currently Held Registration Registration Modification for Service Upgrade Producers often offer several levels of service depending on consumers' subscription levels (for example). T his is implemented at the WSRP level with the registration concept: producers can assert which level of service to provide to consumers based on the values of given registration properties. There may also be cases where the registration information has changed and must be updated. For 160

164 Chapter 15. Web Services for Remote Portlets (WSRP) There may also be cases where the registration information has changed and must be updated. For example, the producer required you to provide a valid and the previous address is not valid anymore and needs to be updated. T herefore at times it may be necessary to modify the registration that sets the service agreement between a consumer and a producer. For example; the producer requiring an that was configured in Section , T he Configuration Portlet. In that case the producer was requiring registration and required a value to be provided for the em ail property. To update the address that was provided, the remote producer must be informed that some registration data has been modified. T he following procedure assumes access to the producer has been configured as previously described. 1. Go to the configuration screen for the self producer and change the value of to [email protected] instead of [email protected]: 2. Click on "Update properties" to save the change. A "Modify registration" button should now appear to let you send this new data to the remote producer: 3. Click on Modify registration and, if the updated registration details have been accepted by the remote producer the following should appear: 161

165 Red Hat JBoss Portal 5.1 Reference Guide Registration Modification on Producer Error If a Producer administrator changes the requirements for registered consumers, invoking operations on the producer may fail with an OperationFailedFault. JBoss Enterprise Portal Platform will attempt to assist in these cases. T his section will discuss an example using the self producer. Assuming that the registration requires a valid value for an em ail registration property (as has been shown) the configuration screen for this producer should show: If the administrator of the producer now requires an additional value to be provided for a name registration property operations with this producer will fail. If a registration modification is required, go to the configuration screen for this remote producer and refresh the information held by the consumer by pressing "Refresh & Save": 162

166 Chapter 15. Web Services for Remote Portlets (WSRP) T he configuration screen now shows the currently held registration information and the expected information from the producer. Enter a value for the name property and then click on "Modify registration". If the producer accepts the new registration data, the following screen will appear: 163

167 Red Hat JBoss Portal 5.1 Reference Guide JBoss Enterprise Portal Platform 5.1 and WSRP 1 Exceptions In WSRP 1, it can be difficult to ascertain what caused an OperationFailedFault as it is a generic exception returned by producers during a failed method invocation. An OperationFailedFault failure can be caused by several different reasons, one of them being a request to modify the registration data. In these instances examining the log files may assist in gathering more information about the problem. WSRP 2 introduces an exception that is specific to a request to modify registrations which reduces the ambiguity that currently exists Consumer Operations Several operations are available from the consumer list view of the WSRP configuration portlet: T he available operations are: Configure Displays the consumer details and allows user to edit them. Refresh Forces the consumer to retrieve the service description from the remote producer to refresh the local information (such as offered portlets, registration information). Activate/Deactivate Activates or deactivates a consumer, governing whether it will be available to provide portlets and receive portlet invocations. Register/De-register Registers or de-registers a consumer based on whether registration is required and/or acquired. Delete Destroys the consumer, after de-registering it if it was registered. Additional Functionalities in WSRP 2.0 In addition to those listed above, the WSRP 2.0 implementation in JBoss Enterprise Portal Platform 5.1 also includes the following functions: Additional Functions: Export 164

168 Chapter 15. Web Services for Remote Portlets (WSRP) Exports some or all of the consumer's portlets to be able to later import them in a different context Import Imports some or all of previously exported portlets Importing and Exporting Portlets Import and export are new functionalities added in WSRP 2. Exporting a portlet allows a consumer to get an opaque representation of the portlet which can then be use by the corresponding import operation to reconstitute it. T his is mostly used in migration scenarios during batch operations. Since JBoss Enterprise Portal Platform does not currently support automated migration of portal data, the functionality provided as part of WSRP 2 is necessarily less complete than it could be with full portal support. T he import/export implementation in JBoss Enterprise Portal Platform allows users to export portlets from a given consumer and then import them back to replace existing portlets assigned to windows on pages by the previously exported portlets. Procedure Click on the "Export" action for a given consumer to display the list of portlets currently made available by this specific consumer. An example list is shown below: 2. Once portlets have been selected, they can be exported by clicking on the "Export" button. T his makes them available for later import: 3. T he portlets can be re-imported directly by pressing the "Use for im port" button or, on the Consumers list page, using the "Im port" action for a given consumer. The example below assumes that the second option has been used and that several sets of previously exported portlets are available to import from. After clicking the action link, a screen similar to the one below should appear: T his screen presents the list of available exports with available operations for each. Operations: 165

169 Red Hat JBoss Portal 5.1 Reference Guide View Displays the export details as previously seen when the export was first performed. Delete Deletes the selected export, asking you for confirmation first. Use for import Selects the export to import portlets from. 4. Once you have selected an export to import from, you will see a screen similar to the one below: T he screen displays the list of available exported portlets for the previously selected export. You can select which portlet you want to import by checking the checkbox next to its name. 5. Select the content of which window the imported portlet will replace. This process is done in three steps: T his example assumes that you have the following page called page1 which contains two windows called NetUnity WSRP 2 Interop - Cache Markup (rem ote) and /sam plesrem otecontroller-portlet.rem otecontrol (rem ote), as shown below: In this example, we want to replace the content of the /sam ples-rem otecontroller- 166

170 Chapter 15. Web Services for Remote Portlets (WSRP) portlet.remotecontrol (remote) with the content of the /ajaxportlet.jsfajaxportlet portlet that was previously exported. Procedure a. Check the box next to the /ajaxportlet.jsfajaxportlet portlet name to indicate that you want to import its data. b. Select page1 in the list of available pages. The screen will then refresh to display the list of available windows on that page, similar to the image below: Note At this point, you still need to select which window content you want to replace before being able to complete the import operation c. Select the /sam ples-rem otecontroller-portlet.rem otecontrol (rem ote) window, which enables the "Import" button. This indicates that all the necessary data to perform the import is available. d. Click the "Import" button. A screen similar to the one below will appear: 6. T he page1 page should now show that the content of /sam ples-rem otecontrollerportlet.remotecontrol (remote) window has been replaced by the content of the /ajaxportlet.jsfajaxportlet imported portlet and that the window has been renamed appropriately. 167

171 Red Hat JBoss Portal 5.1 Reference Guide Erasing Local Registration Data In rare cases, it may be necessary to erase the local data without being able to de-register first. This can occur when a consumer is registered with a producer that has been modified by its administrator to not require registration any longer. In this scenario, local registration information can be erased from the consumer to allow it to resume interacting with the remote producer. T o do this click on the "Erase local registration" button next to the registration context information on the consumer configuration screen: 168

172 Chapter 15. Web Services for Remote Portlets (WSRP) Warning This operation is dangerous as it can result in inability to interact with the remote producer if invoked when not required. The warning message below will be displayed before any data is erased Configuring the WSRP Producer Overview T he behavior of the Portal's WSRP Producer can be configured using the WSRP administration interface, (this is the recommended method), or by editing the WSRP_PATH/lib/gatein.portal.com ponent.wsrp-<version>-epp-ga.jar/conf/wsrpproducer-config.xm l file. Several aspects can be modified with respect to whether registration is required for consumers to access the Producer's services. An XML Schema for the configuration format is available at WSRP_PATH/lib/wsrp-integrationapi-WSRP_VERSION.jar/xsd/gatein_wsrp_producer_1_0.xsd. An alternative to editing the default wsrp-producer-config.xm l file is to make a custom copy containing the required configuration options. If a copy is used in place of the original, however, the WSRP_PATH/02portal.war/WEB- INF/conf/wsrp/wsrp-configuration.xm l must be updated to reference the custom file (this file defines the component WSRPServiceIntegration and contains a producer and consumer configuration location) Default Configuration T he default producer configuration requires that consumers register with it before providing access to its services. However it does not require any specific registration properties (excepting those mandated by the WSRP standard). It does, however, require consumers to be registered before sending them a full service description. This means that the WSRP producer will not provide the list of offered portlets and other capabilities to unregistered consumers. 169

173 Red Hat JBoss Portal 5.1 Reference Guide The producer also uses the default RegistrationPolicy paired with the default RegistrationPropertyValidator. T his allows users to customize how Portal's WSRP Producer decides whether a given registration property is valid or not (however property validators are discussed in greater detail in Section , Registration Configuration ). JBoss Enterprise Portal Platform provides a web interface to configure the producer's behavior. It can be accessed by clicking on the "Producer Configuration" tab of the "WSRP" page of the "admin" portal. T he default configuration should show: You can specify whether or not the producer will send the full service description to unregistered consumers, and, if it requires registration, which RegistrationPolicy to use (and, if needed, which RegistrationPropertyValidator), along with required registration property description for which consumers must provide acceptable values to successfully register. WSDL URLs to access JBoss Enterprise Portal Platform's WSRP producer are now displayed in either in WSRP 1 or WSRP 2 mode Registration Configuration In order to have consumers register with Portal's producer the Portal's behavior with respect to registration must be configured. Registration is optional, as are registration properties. T he producer can require registration without requiring consumers to pass any registration properties as is the case in the default configuration. T he following section discusses configuring a producer's registration behavior from a blank state: 1. T o allow unregistered consumers to see the list of offered portlets, leave the first checkbox ("Access to full service description requires consumers to be registered.") unchecked. 2. To specify, however, that consumers will need to be registered to be able to interact with the producer, check the second box ("Requires registration. Modifying this information will trigger invalidation of consumer registrations."). T he screen will refresh and display: 170

174 Chapter 15. Web Services for Remote Portlets (WSRP) 3. The fully-qualified name for the RegistrationPolicy and RegistrationPropertyValidator can be specified here. T he default values are acceptable. Refer to Section , Customization of Registration Handling Behavior for more information. 4. T o add a registration property called em ail click "Add property" and enter the appropriate information in the fields, providing a description for the registration property that can be used by consumers to determine its purpose: 5. Press "Save" to record the modifications. Note At this time, only String (xsd:string) properties are supported. Note If consumers are already registered with the producer, modifying the configuration of required registration information will trigger the invalidation of held registrations, requiring consumers to modify their registration before being able to access the producer again. T he consumer side of that process is documented in Section , Registration Modification on Producer Error Customization of Registration Handling Behavior Registration handling behavior can be customized by users to suit their Producer needs. T his is done with an implementation of the RegistrationPolicy interface. T his interface defines methods that are called by Portal's Registration service so that decisions can be made appropriately. A default registration policy that provides basic behavior is provided and should be enough for most user needs. While the default registration policy provides default behavior for most registration-related aspects, one aspect requires specific configuration: whether a given value for a registration property is acceptable by the WSRP Producer. 171

175 Red Hat JBoss Portal 5.1 Reference Guide T his is done by plugging a RegistrationPropertyValidator into the default registration policy. T his allows users to define their own validation mechanism. Refer to the Javadoc for org.gatein.registration.registrationpolicy and org.gatein.registration.policies.registrationpropertyvalidator for more details on what is expected of each method. A defined registration policy is required for the producer to be correctly configured. Do this by specifying the qualified class name of the registration policy. As it is anticipated that most users will use the default registration policy, it is possible to provide the class name of a custom property validator instead to customize the default registration policy behavior. Note that property validators are only used by the default policy. Note Since the policy or the validator are defined via their class name and dynamically loaded, it is important to ensure that the identified class is available to the application server. One way to accomplish that is to deploy the policy implementation as a JAR file in the AS instance deploy directory. Note also that, since both policies and validators are dynamically instantiated, they must provide a default, no-argument constructor WSRP Validation Mode T he lack of conformance kit and the wording of the WSRP specification leaves room for differing interpretations, resulting in interoperability issues. It is therefore possible to encounter issues when using consumers from different vendors. Experience of these issues has produced a way to relax the validation that the WSRP producer performs on the data provided by consumers to help with interoperability by accepting data that would normally be invalid. Note that the our validation algorithm is only relaxed on aspects of the specification that are deemed harmless such as invalid language codes. By default, the WSRP producer is configured in strict mode. If you experience issues with a given consumer, you may attempt to relax the validation mode. Un-checking the "Use strict WSRP compliance" checkbox on the Producer configuration screen to do this Removing WSRP If you are not going to use WSRP in your JBoss Enterprise Portal Platform instance, the WSRP configuration files may be left in place. T hey will not adversely affect your installation. However, if you wish to completely remove WSRP from your portal installation, follow this procedure: Procedure Navigate to the JBOSS_HOME/server/<PROFILE>/conf/gatein/ directory of your JBoss Enterprise Portal Platform instance. a. Open the configuration.xm l file and remove the following lines: 172

176 Chapter 15. Web Services for Remote Portlets (WSRP) <value> <string>wsrp-producer</string> </value> 2. Navigate up two directory levels and into the deploy/gatein.ear/ directory (For example: cd../../deploy/gatein.ear/). 3. Remove the following files: wsrp-adm in-gui.war wsrp-producer.war 4. Navigate into the lib/ subdirectory and remove the following files: gatein.portal.com ponent.wsrp-port AL_VERSION.jar wsrp-com m on-wsrp_version.jar wsrp-consum er-wsrp_version.jar wsrp-integration-api-wsrp_version.jar wsrp-producer-lib-wsrp_version.jar wsrp-wsrp1-ws-wsrp_version.jar wsrp-wsrp2-ws-wsrp_version.jar 5. Return to the gatein.ear/ directory and move into the MET A-INF/ subdirectory. a. Open the application.xm l file and remove the following modules: <module> <web> <web-uri>wsrp-admin-gui.war</web-uri> <context-root>wsrp-admin-gui</context-root> </web> </module> <module> <web> <web-uri>wsrp-producer.war</web-uri> <context-root>wsrp-producer</context-root> </web> </module> b. Save and exit the file. 6. Return to the gatein.ear/ directory and navigate into the 02portal.war/WEB-INF/conf/ subdirectory. a. Remove the wsrp/ directory. b. Open the configuration.xm l file and remove the following line: <import profiles="jboss">war:/conf/wsrp/wsrp-configuration.xml</import> c. Save and exit the file. 7. From your current location, navigate into the portal/ subdirectory. a. Open the portal-configuration.xm l file and remove the line: <value>org.exoplatform.portal.pom.spi.wsrp.wsrpstate</value> b. Save and exit the file. 173

177 Red Hat JBoss Portal 5.1 Reference Guide 8. Return to the conf/ directory and move into the jcr/ subdirectory. a. Open the jcr-configuration.xm l file and remove the line: <property name="wsrp" value=" b. Remove the following configuration file references: <value>war:/conf/wsrp/consumers-configuration-nodetypes.xml</value> <value>war:/conf/wsrp/producer-configuration-nodetypes.xml</value> <value>war:/conf/wsrp/producer-registrations-nodetypes.xml</value> <value>war:/conf/wsrp/producer-pc-nodetypes.xml</value> <value>war:/conf/wsrp/migration-nodetypes.xml</value> c. Save and exit the file. d. Open the repository-configuration.xm l and remove the WSRP workspace: 174

178 Chapter 15. Web Services for Remote Portlets (WSRP) <!-- WSRP --> <workspace name="wsrp-system"> <container> <properties> <property name="source-name" value="${gatein.jcr.datasource.name}${container.name.suffix}"/> <property name="dialect" value="${gatein.jcr.datasource.dialect}"/> <property name="multi-db" value="false"/> <property name="update-storage" value="true"/> <property name="max-buffer-size" value="204800"/> <property name="swap-directory" value="${gatein.jcr.data.dir}/swap/wsrp${container.name.suffix}"/> </properties> <value-storages> <value-storage id="gadgets" > <properties> <property name="path" value="${gatein.jcr.storage.data.dir}/wsrp${container.name.suffix}"/> </properties> <filters> <filter property-type="binary"/> </filters> </value-storage> </value-storages> </container> <initializer> <properties> <property name="root-nodetype" value="nt:unstructured"/> <property name="root-permissions" value="*:/platform/administrators read;*:/platform/administrators add_node;*:/platform/administrators set_property;*:/platform/administrators remove"/> </properties> </initializer> <cache enabled="true"> <properties> <property name="jbosscache-configuration" value="${gatein.jcr.cache.config}" /> <property name="jgroups-configuration" value="${gatein.jcr.jgroups.config}" /> <property name="jgroups-multiplexer-stack" value="true" /> <property name="jbosscache-cluster-name" value="jcr- ${container.name.suffix}-wsrp-system" /> </properties> </cache> <query-handler> <properties> <property name="index-dir" value="${gatein.jcr.index.data.dir}/wsrpsystem${container.name.suffix}"/> <property name="changesfilter-class" value="${gatein.jcr.index.changefilterclass}" /> <property name="jbosscache-configuration" value="${gatein.jcr.index.cache.config}" /> <property name="jgroups-configuration" value="${gatein.jcr.jgroups.config}" /> <property name="jgroups-multiplexer-stack" value="true" /> <property name="jbosscache-cluster-name" value="jcrindexer- 175

179 Red Hat JBoss Portal 5.1 Reference Guide ${container.name.suffix}-wsrp-system" /> <property name="max-volatile-time" value="60" /> </properties> </query-handler> <lock-manager> <properties> <property name="time-out" value="15m" /> <property name="jbosscache-configuration" value="${gatein.jcr.lock.cache.config}" /> <property name="jgroups-configuration" value="${gatein.jcr.jgroups.config}" /> <property name="jgroups-multiplexer-stack" value="true" /> <property name="jbosscache-cluster-name" value="jcrlock- ${container.name.suffix}-wsrp-system" /> <property name="jbosscache-cl-cache.jdbc.table.name" value="jcrlock_wsrp_system" /> <property name="jbosscache-cl-cache.jdbc.table.create" value="true" /> <property name="jbosscache-cl-cache.jdbc.table.drop" value="false" /> <property name="jbosscache-cl-cache.jdbc.table.primarykey" value="pk" /> <property name="jbosscache-cl-cache.jdbc.fqn.column" value="fqn" /> <property name="jbosscache-cl-cache.jdbc.node.column" value="node" /> <property name="jbosscache-cl-cache.jdbc.parent.column" value="parent" /> <property name="jbosscache-cl-cache.jdbc.datasource" value="${gatein.jcr.datasource.name}${container.name.suffix}" /> </properties> </lock-manager> </workspace> 9. Optional: Remove any references to WSRP from the following files: gatein.ear/01exoresources.war/met A-INF/MANIFEST.MF gatein.ear/met A-INF/MANIFEST.MF gatein.ear/02portal.war/met A-INF/MANIFEST.MF 176

180 Part III. Advanced Development Part III. Advanced Development 177

181 Red Hat JBoss Portal 5.1 Reference Guide Chapter 16. Foundations The exo Kernel JBoss Enterprise Portal Platform is built as a set of services on top of a dependency injection kernel. T he kernel provides configuration, life-cycle handling, component scopes, and some core services. Service components exist in two scopes. T he first scope is represented by the RootContainer. It contains services that exist independently of any portal, and can be accessed by all portals. The second scope, the PortalContainer, is portal-specific. Each portal exists in an instance of the PortalContainer. T his scope contains services that are common for a set of portals, and services which should not be shared by all portals. Whenever a specific service is looked up through the PortalContainer, and the service is not available, the lookup is delegated further up to the RootContainer. JBoss Enterprise Portal Platform can have default instances of a certain component in the RootContainer, and portal specific instances in some or all PortalContainers, that override the default instance. Whenever your portal application has to be integrated more closely with exo services, these services can be looked up through the PortalContainer. Important Only officially documented services should be accessed this way, and used according to documentation, as most of the services are an implementation detail of exo, and subject to change without notice. 178

182 Chapter 16. Foundations Configuring services T he exo Kernel uses dependency injection to create services based on configuration.xm l configuration files. The location of the configuration files determines if services are placed into the RootContainer scope, or into the PortalContainer scope. All configuration.xm l files located at conf/configuration.xm l in the classpath (any directory, or any jar in the classpath) will have their services configured in the RootContainer scope. All configuration.xm l files located at conf/portal/configuration.xm l in the classpath will have their services configured at the PortalContainer scope. Additionally, portal extensions can contain configuration in JBOSS_HOME/server/<PROFILE>/deploy/gatein.ear/02portal.war/WEB- INF/conf/configuration.xml, and will also have their services configured in the PortalContainer scope. Note Portal extensions are described later in this document Configuration syntax Components A service component is defined in configuration.xm l by using a <component> element. Only one piece of information is required when defining a service; the service implementation class. T his is specified using <type> Every component has a <key> that identifies it. If not explicitly set, a key defaults to the value of <type>. If a key can be loaded as a class, a class object is used as a key, otherwise a string is used. The usual approach is to specify an interface as a key. <?xml version="1.0" encoding="iso "?> <configuration xmlns:xsi=" xsi:schemalocation=" xmlns=" <component> <key>org.exoplatform.services.database.hibernateservice</key> <type>org.exoplatform.services.database.impl.hibernateserviceimpl</type>... </component> </configuration> External Plug-ins T he exo Kernel supports non-component objects that can be configured, instantiated, and injected into registered components using method calls. T his 'plugin' method allows portal extensions to add 179

183 Red Hat JBoss Portal 5.1 Reference Guide additional configurations to core services. An external plugin is defined by using the <external-com ponent-plugin> wrapper element which contains one or more <com ponent-plugin> definitions. T he <external-com ponent-plugin> element uses <target-com ponent> to specify a target service component that will receive injected objects. Every <com ponent-plugin> defines an implementation type, and a method on the target component to use for injection (<set-m ethod>). A plugin implementation class has to implement the org.exoplatform.container.component. ComponentPlugin interface. In the following example the PortalContainerDefinitionPlugin implements the Com ponentplugin: <?xml version="1.0" encoding="utf-8"?> <configuration xmlns:xsi=" xsi:schemalocation=" xmlns=" <external-component-plugins> <targetcomponent>org.exoplatform.container.definition.portalcontainerconfig</targetcomponent> <component-plugin> <!-- The name of the plugin --> <name>add PortalContainer Definitions</name> <!-- The name of the method to call on the PortalContainerConfig in order to register the PortalContainerDefinitions --> <set-method>registerplugin</set-method> <!-- The fully qualified name of the PortalContainerDefinitionPlugin --> <type>org.exoplatform.container.definition.portalcontainerdefinitionplugin</type>... </component-plugin> </external-component-plugins> </configuration> Includes, and special URLs It is possible to divide the configuration.xm l file into many smaller files, which are then included into the main configuration file. The included files must be valid xml files; they cannot be fragments of text. Below is an example configuration.xm l that 'outsources' its content into several files: 180

184 Chapter 16. Foundations <configuration xmlns:xsi=" xsi:schemalocation=" xmlns=" <import>war:/conf/sample-ext/jcr/jcr-configuration.xml</import> <import>war:/conf/sample-ext/portal/portal-configuration.xml</import> </configuration> T his line is being used to reference another configuration file. T he war: URL schema indicates that the following path is to be resolved relative to the current PortalContainer's servlet context resource path, starting with WEB-INF as a root. Note T he current PortalContainer is really a newly created PortalContainer, as war: URLs only make sense for PortalContainer scoped configuration. T hrough the extension mechanism the servlet context used for resource loading is a unified servlet context (this is explained in a later section). T o have an 'include' path resolved relative to current classpath (context classloader), use a 'jar:' URL schema Special variables Configuration files may contain a special variable reference ${container.name.suffix}. T his variable resolves to the name of the current portal container, prefixed by underscore (_). T his facilitates reuse of configuration files in situations where portal-specific unique names need to be assigned to some resources; JNDI names, Database/DataSource names and JCR repository names, for example. T his variable is only defined when there is a current PortalContainer available and is only available for PortalContainer scoped services. A good example of this is the HibernateService: 181

185 Red Hat JBoss Portal 5.1 Reference Guide <?xml version="1.0" encoding="iso "?>... <configuration xmlns:xsi=" xsi:schemalocation=" xmlns=" <component> <key>org.exoplatform.services.database.hibernateservice</key> <jmx-name>database:type=hibernateservice</jmx-name> <type>org.exoplatform.services.database.impl.hibernateserviceimpl</type> <init-params> <properties-param> <name>hibernate.properties</name> <description>default Hibernate Service</description> <property name="hibernate.cache.region.jbc2.query.localonly" value="true" /> <property name="hibernate.cache.region.factory_class" value="org.hibernate.cache.jbc2.multiplexedjbosscacheregionfactory" /> <property name="hibernate.transaction.manager_lookup_class" value="org.hibernate.transaction.jbosstransactionmanagerlookup" /> <property name="hibernate.show_sql" value="false"/> <property name="hibernate.current_session_context_class" value="thread"/> <property name="hibernate.cache.use_second_level_cache" value="true"/> <property name="hibernate.cache.use_query_cache" value="true"/> <property name="hibernate.connection.datasource" value="${gatein.idm.datasource.name}${container.name.suffix}"/> <property name="hibernate.connection.autocommit" value="true"/> <!-- Should be automatically detected. Force otherwise <property name="hibernate.dialect" value="org.hibernate.dialect.xxxdialect"/> --> </properties-param> </init-params> </component>... </configuration> InitParams configuration element InitParams is a configuration element that is essentially a map of key-value pairs, where key is always a String, and value can be any type that can be described using the kernel XML configuration. Service components that form the JBoss Enterprise Portal Platform infrastructure use InitParams elements to configure themselves. A component can have one instance of InitParams injected at most. If the service component's constructor takes InitParams as any of the parameters it will automatically be injected at component instantiation time. The XML configuration for a service component that expects an InitParams element must have an <init-params> element present, however this element can be left empty. Below is an example of how the kernel XML configuration syntax looks when creating InitParams instances: 182

186 Chapter 16. Foundations <component> <key>org.exoplatform.services.naming.initialcontextinitializer</key> <type>org.exoplatform.commons.initialcontextinitializer2</type> <init-params> <properties-param> <name>default-properties</name> <description>default initial context properties</description> </properties-param> </init-params> </component> An InitParams element description begins with an <init-params> element. It can have zero or more children elements, each of which is one of the following: or <value-param> <values-param> <properties-param> <object-param> Each of these child elements takes a <name> that serves as a map entry key, and an optional <description>. It also takes a type-specific value specification. T he value specification for the <properties-param> defines one or more <property> elements, each of which specifies two strings; a property name and a property value. This is evident in the two previous examples. Each <properties-params> defines one java.util.properties instance. T he value specification for <value-param> elements is a <value> element which defines a String instance. 183

187 Red Hat JBoss Portal 5.1 Reference Guide <component> <key>org.exoplatform.services.resources.resourcebundleservice</key> <type>org.exoplatform.services.resources.impl.simpleresourcebundleservice</type> <init-params> <values-param> <name>classpath.resources</name> <description>the resources that start with the following package name should be load from file system</description> <value>locale.portlet</value> </values-param> <values-param> <name>init.resources</name> <description>store the following resources into the db for the first launch </description> <value>locale.test.resources.test</value> </values-param> <values-param> <name>portal.resource.names</name> <description>the properties files of the portal, those file will be merged into one ResourceBundle properties </description> <value>local.portal.portal</value> <value>local.portal.custom</value> </values-param> </init-params> </component> T he value specification for <values-param> requires one or more <value> elements. Each <value> represents one String instance. All String values are then collected into a java.util.list instance. 184

188 Chapter 16. Foundations <component> <key>org.exoplatform.services.cache.cacheservice</key> <jmx-name>cache:type=cacheservice</jmx-name> <type>org.exoplatform.services.cache.impl.cacheserviceimpl</type> <init-params> <object-param> <name>cache.config.default</name> <description>the default cache configuration</description> <object type="org.exoplatform.services.cache.exocacheconfig"> <field name="name"> <string>default</string> </field> <field name="maxsize"> <int>300</int> </field> <field name="livetime"> <long>300</long> </field> <field name="distributed"> <boolean>false</boolean> </field> <field name="implementation"> <string>org.exoplatform.services.cache.concurrent.concurrentfifoexocache</string> </field> </object> </object-param> </init-params> </component> For <object-param> entries, the value specification consists of an <object> element which is used for plain Java style object specification (specifying an implementation class - <type>, and property values - <field>). The following section has an example of specifying a field of with a Collection type. The InitParams structure (the names and types of entries) is specific for each service, as it is the code inside a service components' class that defines which entry names to look up and what types it expects to find Configuring a portal container A portal container is defined by several attributes: Portal Container Name This attribute is always equal to the URL context to which the current portal is bound. REST Context Name This attribute is used for REST access to portal application; every portal has one unique REST context name. Realm Name This is the name of the security realm used for authentication when users log into the portal. 185

189 Red Hat JBoss Portal 5.1 Reference Guide Dependencies This is a list of other web applications whose resources are visible to the current portal (via the extension mechanism described later), and are searched for in the specified order. 186

190 Chapter 16. Foundations <?xml version="1.0" encoding="utf-8"?> <configuration xmlns:xsi=" xsi:schemalocation=" xmlns=" <external-component-plugins> <!-- The full qualified name of the PortalContainerConfig --> <targetcomponent>org.exoplatform.container.definition.portalcontainerconfig</targetcomponent> <component-plugin> <!-- The name of the plugin --> <name>add PortalContainer Definitions</name> <!-- The name of the method to call on the PortalContainerConfig in order to register the PortalContainerDefinitions --> <set-method>registerplugin</set-method> <!-- The full qualified name of the PortalContainerDefinitionPlugin --> <type>org.exoplatform.container.definition.portalcontainerdefinitionplugin</type> <init-params> <object-param> <name>portal</name> <object type="org.exoplatform.container.definition.portalcontainerdefinition"> <!-- The name of the portal container --> <field name="name"><string>portal</string></field> > <!-- The name of the context name of the rest web application -- <field name="restcontextname"><string>rest</string></field> <!-- The name of the realm --> <field name="realmname"><string>exo-domain</string></field> <!-- All the dependencies of the portal container ordered by loading priority --> <field name="dependencies"> <collection type="java.util.arraylist"> <value> <string>exoresources</string> </value> <value> <string>portal</string> </value> <value> <string>dashboard</string> </value> <value> <string>exoadmin</string> </value> <value> <string>exogadgets</string> </value> <value> 187

191 Red Hat JBoss Portal 5.1 Reference Guide <string>exogadgetserver</string> </value> <value> <string>rest</string> </value> <value> <string>web</string> </value> <value> <string>wsrp-producer</string> </value> <!-- The sample-ext has been added at the end of the dependency list in order to have the highest priority --> <value> <string>sample-ext</string> </value> </collection> </field> </object> </object-param> </init-params> </component-plugin> </external-component-plugins> </configuration> Dependencies are part of the extension mechanism which is discussed later in this document. Every PortalContainer is represented by a PortalContainer instance, which contains: exocontainercontext T his contains information about the portal. Unified Servlet Context T his deals with web-archive-relative resource loading. Unified Classloader For classpath based resource loading. Various methods for retrieving services T he Unified servlet context and unified classloader are part of the extension mechanism (which is detailed in the next section). T hey provide the standard API (ServletContext, ClassLoader) with specific resource loading behavior, such as visibility into associated web application archives, configured with the dependencies property of PortalContainerDefinition. Resources from other web applications are queried in the order specified by the dependencies. T he later entries in the list override the previous ones The Extension Mechanism and Portal Extensions 188

192 Chapter 16. Foundations T he Extension mechanism makes it possible to override portal resources in a way similar to hardware plug-and-play functionalities. Customizations can be implemented without unpacking and repacking the original portal.war archives by adding a.war archive to the resources and configuring its position in the portal's classpath. Custom.war archives can be created with new resources that override the resources in the original archive. T hese archives, packaged for use through the extension mechanism, are called portal extensions. Procedure Creating a portal extension 1. Declare the PortalConfigOwner servlet context listener in the web.xm l of your web application. T his example shows a portal extension called sample-ext. <?xml version="1.0" encoding="iso "?> <!DOCTYPE web-app PUBLIC -//Sun Microsystems, Inc.//DTD Web Application 2.3//EN <web-app> <display-name>sample-ext</display-name> <listener> <listenerclass>org.exoplatform.container.web.portalcontainerconfigowner</listenerclass> </listener>... </web-app> 2. Add the application's servlet context name to the PortalContainerDefinition's list of dependencies. This must be done for each portal container that you want to have access to the new application. T he application's position in these lists will dictate its priority when the portal loads resources. The later your application appears in the list, the higher its resource priority will be. 3. At this point your new web archive will be on both the portal's unified classpath and unified servlet context resource path. Example Refer to the code extract in Section 16.5, Configuring a portal container for an example of a PortalContainerDefinition that has sample-ext in its list of dependencies Running Multiple Portals It is possible to run several independent portal containers, each bound to a different URL context, within the same JVM instance. T his method of deployment allows for efficient administration and resource consumption by allowing coexisting portals to reuse configuration arrangements through the extension mechanism. 189

193 Red Hat JBoss Portal 5.1 Reference Guide Portals can inherit resources and configuration from existing web archives and add extra resources as needed, overriding those that need to be changed by including modified copies. In order for a portal application to function correctly when deployed within a multiple portal deployment, it may have to dynamically query the information about the current portal container. T he application should not make any assumptions about the name, and other information of the current portal, as there are now multiple different portals in play. At any point during request processing, or life-cycle event processing, an application can retrieve this information through org.exoplatform.container.exocontainercontext. Sometimes an application must ensure that the proper PortalContainer is associated with the current exocontainercontext call. If the portal application contains servlets or servlet filters that need to access portal specific resources during their request processing, the servlet or filter must be associated with the current container. A servlet in this instance should extend the org.exoplatform.container.web.abstracthttpservlet class so as to properly initialize the current PortalContainer. T his will also set the current thread's context Classloader to one that looks for resources in associated web applications in the order specified by the dependencies configuration (as seen in Section 16.6, T he Extension Mechanism and Portal Extensions ). Filter classes need to extend the org.exoplatform.container.web.abstractfilter. Both AbstractHttpServlet, and AbstractFilter have a getcontainer() method, which returns the current PortalContainer. If your servlet handles the requests by implementing a service() method, that method must be renamed to match the following signature: /** * Use this method instead of Servlet.service() */ protected void onservice(exocontainer container, HttpServletRequest req, HttpServletResponse res) throws ServletException, IOException; Note T his ensures that AbstractHttpServlet's service() interception is not overwritten. An application may also need access to portal information within the HttpSessionListener. Ensure the abstract class org.exoplatform.container.web.abstracthttpsessionlistener is extended. In this instance, modify the method signatures as follows: 190

194 Chapter 16. Foundations /** * Use this method instead of HttpSessionListener.sessionCreated() */ protected void onsessioncreated(exocontainer container, HttpSessionEvent event); /** * Use this method instead of HttpSessionListener.sessionDestroyed() */ protected void onsessiondestroyed(exocontainer container, HttpSessionEvent event); Another method must also be implemented in this case: /** * Method should return true if unified servlet context, * and unified classloader should be made available */ protected boolean requireportalenvironment(); If this method returns true the current thread's context Classloader is set up according to the dependencies configuration and availability of the associated web applications. If it returns false the standard application separation rules are used for resource loading (effectively turning off the extension mechanism). T his method exists on both AbstractHttpServlet and AbstractFilter. T his is a default implementation that automatically returns true when it detects there is a current PortalContainer present and false otherwise. ServletContextListener-based initialization access to PortalContainer JBoss Enterprise Portal Platform has no direct control over the deployment of application archives (.war and.ear files); it is the application server that performs the deployment. However, applications in the dependencies configuration must be deployed before the portal that depends on them is initialized in order for the extension mechanism to work properly. Conversely, some applications may require an already initialized PortalContainer to properly initialize themselves. T his gives rise to a recursive dependency problem. A mechanism of initialization tasks and task queues has been implemented in JBoss Enterprise Portal Platform to resolve this dependency issue. Web applications that depend on a current PortalContainer to initialize must avoid performing their initialization directly on a ServletContextListener executed during their deployment (before any PortalContainer was initialized). T o ensure this, a web application should package its initialization logic into an init task of an appropriate type and only use ServletContextListener to insert the init task instance into the proper init tasks queue. An example of this is the Gadgets application which registers Google gadgets with the current PortalContainer. T his example uses PortalContainerPostInitT ask which is executed after the portal container has been initialized. 191

195 Red Hat JBoss Portal 5.1 Reference Guide public class GadgetRegister implements ServletContextListener { public void contextinitialized(servletcontextevent event) { // Create a new post-init task final PortalContainerPostInitTask task = new PortalContainerPostInitTask() { public void execute(servletcontext context, PortalContainer portalcontainer) { try { SourceStorage sourcestorage = (SourceStorage) portalcontainer.getcomponentinstanceoftype(sourcestorage.class);... } catch (RuntimeException e) { throw e; } catch (Exception e) { throw new RuntimeException("Initialization failed: ", e); } } }; } } // Add post-init task for execution on all the portal containers // that depend on the given ServletContext according to // PortalContainerDefinitions (via Dependencies configuration) PortalContainer.addInitTask(event.getServletContext(), task); In some situations initialization may be required after the portal container is instantiated but before it has initialized. PortalContainerPreInitT ask can be used in that case. Use PortalContainerPostCreateT ask if initialization is required after all the post-init tasks have been executed. LoginModules If some custom LoginModules require the current exocontainer for initialization ensure they extend org.exoplatform.services.security.jaas.abstractloginmodule. AbstractLoginModule enforces some basic configuration. It recognizes two initialization options; portalcontainername and realmname. The values for these options can be accessed via protected fields of the same name. 192

196 Chapter 17. exo JCR Chapter 17. exo JCR Introduction exo JCR usage T he JBoss Enterprise Portal Platform is using a JCR API to store its information for internal usage. We do not support usage of the JCR to store application information. T he information below is intended to assist users to understand particular low level details on how the JBoss Enterprise Portal Platform works and how it can be fine-tuned. The term JCR refers to the Java Content Repository. The JCR is the data store of JBoss Enterprise Portal Platform. All content is stored and managed via the JCR. T he exo JCR included with JBoss Enterprise Portal Platform 5.1 is a (JSR-170) compliant implementation of the JCR 1.0 specification. T he JCR provides versioning, textual search, access control, content event monitoring, and is used to storing text and binary data for the portal internal usage. The back-end storage of the JCR is configurable and can be a file system or a database Concepts Repository A repository is a form of data storage device. A 'repository' differs from a 'database' in the nature of the information contained. While a database holds hard data in rigid tables, a repository may access the data on a database by using less rigid meta-data. In this sense a repository operates as an 'interpreter' between the database(s) and the user. Note The data model for the interface (the repository) is rarely the same as the data model used by the repository's underlying storage subsystems (such as a database), however the repository is able to make persistent data changes in the storage subsystem. Workspace The exo JCR uses 'workspaces' as the main data abstraction in its data model. The content is stored in a workspace as a hierarchy of items and each workspace has its own hierarchy of items. Repositories access one or more workspaces. Persistent JCR workspaces consist of a directed acyclic graph of items where the edges represent the parent-child relation. Items An item is either a node or a property. Properties contain the data (either simple values or binary data). The nodes of a workspace give it its structure while the properties hold the data itself. Nodes Nodes are identified using accepted namespacing conventions. Changed nodes may be versioned through an associated version graph to preserve data integrity. 193

197 Red Hat JBoss Portal 5.1 Reference Guide Nodes can have various properties or child nodes associated to them. Properties Properties hold data as values of predefined types, such as: String, Binary, Long, Boolean, Double, Date, Reference and Path JCR configuration The JCR configuration is defined in an XML file which is constructed as per the DTD below: <!ELEMENT repository-service (repositories)> <!ATTLIST repository-service default-repository NMTOKEN #REQUIRED> <!ELEMENT repositories (repository)> <!ELEMENT repository (security-domain,access-control,session-maxage,authentication-policy,workspaces)> <!ATTLIST repository default-workspace NMTOKEN #REQUIRED name NMTOKEN #REQUIRED system-workspace NMTOKEN #REQUIRED > <!ELEMENT security-domain (#PCDATA)> <!ELEMENT access-control (#PCDATA)> <!ELEMENT session-max-age (#PCDATA)> <!ELEMENT authentication-policy (#PCDATA)> <!ELEMENT workspaces (workspace+)> <!ELEMENT workspace (container,initializer,cache,query-handler)> <!ATTLIST workspace name NMTOKEN #REQUIRED> <!ELEMENT container (properties,value-storages)> <!ATTLIST container class NMTOKEN #REQUIRED> <!ELEMENT value-storages (value-storage+)> <!ELEMENT value-storage (properties,filters)> <!ATTLIST value-storage class NMTOKEN #REQUIRED> <!ELEMENT filters (filter+)> <!ELEMENT filter EMPTY> <!ATTLIST filter property-type NMTOKEN #REQUIRED> <!ELEMENT initializer (properties)> <!ATTLIST initializer class NMTOKEN #REQUIRED> <!ELEMENT cache (properties)> <!ATTLIST cache enabled NMTOKEN #REQUIRED class NMTOKEN #REQUIRED > <!ELEMENT query-handler (properties)> <!ATTLIST query-handler class NMTOKEN #REQUIRED> <!ELEMENT access-manager (properties)> <!ATTLIST access-manager class NMTOKEN #REQUIRED> <!ELEMENT lock-manager (time-out,persister)> <!ELEMENT time-out (#PCDATA)> <!ELEMENT persister (properties)> <!ELEMENT properties (property+)> <!ELEMENT property EMPTY> To modify the configuration of the JCR Service, you would need to modify the file found at 194

198 Chapter 17. exo JCR JBOSS_HOME/server/PROFILE/deploy/gatein.ear/02portal.war/WEB- INF/conf/jcr/repository-configuration.xm l. <repository-service default-repository="repository"> <repositories> <repository name="repository" system-workspace="system" defaultworkspace="portal-system"> <security-domain>gatein-domain</security-domain> <access-control>optional</access-control> <authenticationpolicy>org.exoplatform.services.jcr.impl.core.access.jaasauthenticator</authenticat ion-policy> <!-- System --> <workspaces> [... Workspaces definitions...] </workspaces> </repository> </repositories> </repository-service> In JBoss Enterprise Portal Platform you will see several configured workspaces required for the portal. 1. system 2. portal-system: T o store portal metadata such as page compositions. 3. portal-work: T o store elements that are temporary such as tokens 4. wsrp-system: T o store WSRP related data 5. wsrp-system: T o store Portlet Container related data (such as portlet preferences Configure the workspaces by locating the workspace you need to modify in JBOSS_HOME/server/PROFILE/deploy/gatein.ear/02portal.war/WEB- INF/conf/jcr/repository-configuration.xm l. T he repository configuration supports human-readable values. T hey are not case-sensitive. Complete the appropriate element fields using the following value formats: Number formats: K or KB for kilobytes. M or MB for megabytes. G or GB for gigabytes. T or TB for terabytes. Examples: 200K or 200KB; 4M or 4MB; 1.4G or 1.4GB; 10T or 10TB. T ime formats: ms for milliseconds. s for seconds. m for minutes. h for hours. d for days. w for weeks. 195

199 Red Hat JBoss Portal 5.1 Reference Guide The default time format is seconds if no other format is specified. Examples: 500ms or 500 milliseconds; 20, 20s or 20 seconds; 30m or 30 minutes; 12h or 12 hours; 5d or 5 days; 4w or 4 weeks Example of the portal-system workspace 196

200 Chapter 17. exo JCR <!-- Portal system data --> <workspace name="portal-system"> <container class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.cqjdbcworkspace DataContainer"> <properties> <property name="source-name" value="${gatein.jcr.datasource.name}${container.name.suffix}"/> <property name="dialect" value="${gatein.jcr.datasource.dialect}"/> <property name="multi-db" value="false"/> <property name="update-storage" value="true"/> <property name="max-buffer-size" value="204800"/> <property name="swap-directory" value="${gatein.jcr.data.dir}/swap/portal-system${container.name.suffix}"/> </properties> <value-storages> <value-storage id="portal-system" class="org.exoplatform.services.jcr.impl.storage.value.fs.treefilevaluestorage"> <properties> <property name="path" value="${gatein.jcr.storage.data.dir}/portal-system${container.name.suffix}"/> </properties> <filters> <filter property-type="binary"/> </filters> </value-storage> </value-storages> </container> <initializer class="org.exoplatform.services.jcr.impl.core.scratchworkspaceinitializer"> <properties> <property name="root-nodetype" value="nt:unstructured"/> <property name="root-permissions" value="*:/platform/administrators read;*:/platform/administrators add_node;*:/platform/administrators set_property;*:/platform/administrators remove"/> </properties> </initializer> <cache enabled="true" class="org.exoplatform.services.jcr.impl.dataflow.persistent.jbosscache.jbosscachew orkspacestoragecache"> <properties> <property name="jbosscache-configuration" value="${gatein.jcr.cache.config}" /> <property name="jgroups-configuration" value="${gatein.jcr.jgroups.config}" /> <property name="jgroups-multiplexer-stack" value="true" /> <property name="jbosscache-cluster-name" value="jcr- ${container.name.suffix}-portal-system" /> </properties> </cache> <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.searchindex"> <properties> <property name="index-dir" value="${gatein.jcr.index.data.dir}/portal-system${container.name.suffix}"/> <property name="changesfilter-class" 197

201 Red Hat JBoss Portal 5.1 Reference Guide value="${gatein.jcr.index.changefilterclass}" /> <property name="jbosscache-configuration" value="${gatein.jcr.index.cache.config}" /> <property name="jgroups-configuration" value="${gatein.jcr.jgroups.config}" /> <property name="jgroups-multiplexer-stack" value="true" /> <property name="jbosscache-cluster-name" value="jcrindexer- ${container.name.suffix}-portal-system" /> <property name="max-volatile-time" value="60" /> </properties> </query-handler> <lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.cacheablelockmanageri mpl"> <properties> <property name="time-out" value="15m" /> <property name="jbosscache-configuration" value="${gatein.jcr.lock.cache.config}" /> <property name="jgroups-configuration" value="${gatein.jcr.jgroups.config}" /> <property name="jgroups-multiplexer-stack" value="true" /> <property name="jbosscache-cluster-name" value="jcrlock- ${container.name.suffix}-portal-system" /> <property name="jbosscache-cl-cache.jdbc.table.name" value="jcrlock_portal_system" /> <property name="jbosscache-cl-cache.jdbc.table.create" value="true" /> <property name="jbosscache-cl-cache.jdbc.table.drop" value="false" /> <property name="jbosscache-cl-cache.jdbc.table.primarykey" value="pk" /> <property name="jbosscache-cl-cache.jdbc.fqn.column" value="fqn" /> <property name="jbosscache-cl-cache.jdbc.node.column" value="node" /> <property name="jbosscache-cl-cache.jdbc.parent.column" value="parent" /> <property name="jbosscache-cl-cache.jdbc.datasource" value="${gatein.jcr.datasource.name}${container.name.suffix}" /> </properties> </lock-manager> </workspace> The name of the workspace. Workspace data container (physical storage) configuration. Workspace initializer configuration. Workspace storage cache configuration. Query handler configuration. The amount of time before the unused global lock is removed Using AS Managed Datasources 198

202 Chapter 17. exo JCR Supported Datasources It is important to note that JBoss Enterprise Portal Platform's JCR only supports no-txdatasource datasources. JBoss Enterprise Portal Platform uses JBoss's simplified datasource centric descriptor. T his simplified configuration descriptor is deployed the same directory as other deployable components (e.g.; <JBOSS_HOME>/server/<PROFILE>/deploy/). In order for the AS to recognize the datasources, they must adhere to the DBNAME-ds.xml naming convention. Example datasources for all certified databases are located in the <JBOSS_HOME>/docs/exam ples/jca/ directory. Edit the datasource that corresponds to your database, then copy it to the deploy/ directory before restarting the application server. T he next section discusses the various parameters used to configure a datasource, however, at a minimum, you will need to set the connection-url, user-name, and password as required for your database Datasource Configuration You must change your database T he default persistence configuration works out of the box with Hypersonic (HSQLDB) so that the JBoss Enterprise Platforms are able to run "out of the box". However, Hypersonic is not supported in production and should not be used in a production environment. Known issues with the Hypersonic Database include: no transaction isolation thread and socket leaks (connection.close() does not tidy up resources) persistence quality (logs commonly become corrupted after a failure, preventing automatic recovery) database corruption stability under load (database processes cease when dealing with too much data) not viable in clustered environments Declaring the datasource As mentioned above, datasource files are deployed alongside other deployable items in your <JBOSS_HOME>/server/<PROFILE>/deploy/ directory. Although the examples in <JBOSS_HOME>/docs/exam ples/jca/ focus on individual datasources, your DBNAME-ds.xm l file can contain all the required datasources for your portal instance, as shown in the default JBoss Enterprise Portal Platform datasource file below: 199

203 Red Hat JBoss Portal 5.1 Reference Guide <?xml version="1.0" encoding="utf-8"?> <!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~ JBoss, a division of Red Hat ~ ~ Copyright 2009, Red Hat Middleware, LLC, and individual ~ ~ contributors as indicated by authors tag. See the ~ ~ copyright.txt in the distribution for a full listing of ~ ~ individual contributors. ~ ~ ~ ~ This is free software; you can redistribute it and/or modify it ~ ~ under the terms of the GNU Lesser General Public License as ~ ~ published by the Free Software Foundation; either version 2.1 of ~ ~ the License, or (at your option) any later version. ~ ~ ~ ~ This software is distributed in the hope that it will be useful, ~ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of ~ ~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU ~ ~ Lesser General Public License for more details. ~ ~ ~ ~ You should have received a copy of the GNU Lesser General Public ~ ~ License along with this software; if not, write to the Free ~ ~ Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA ~ ~ USA, or see the FSF site: ~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-- > <datasources> <no-tx-datasource> <jndi-name>gatein-idm</jndi-name> <connectionurl>jdbc:hsqldb:${jboss.server.data.dir}${/}gatein${/}hypersonic${/}gatein-idmlocaldb</connection-url> <driver-class>org.hsqldb.jdbcdriver</driver-class> <user-name>sa</user-name> <password></password> <min-pool-size>5</min-pool-size> <max-pool-size>20</max-pool-size> <idle-timeout-minutes>0</idle-timeout-minutes> <prepared-statement-cache-size>32</prepared-statement-cache-size> </no-tx-datasource> <no-tx-datasource> <jndi-name>gatein-jcr</jndi-name> <connectionurl>jdbc:hsqldb:${jboss.server.data.dir}${/}gatein${/}hypersonic${/}gatein-jcrlocaldb</connection-url> <driver-class>org.hsqldb.jdbcdriver</driver-class> <user-name>sa</user-name> <password></password> <min-pool-size>5</min-pool-size> <max-pool-size>20</max-pool-size> <idle-timeout-minutes>0</idle-timeout-minutes> <prepared-statement-cache-size>32</prepared-statement-cache-size> </no-tx-datasource> </datasources> Datasource Paramenters T he following list contains parameters used in configuring a datasource: 200

204 Chapter 17. exo JCR T he following list contains parameters used in configuring a datasource: Common Datasource Parameters <mbean> A standard JBoss MBean deployment. <depends> T he ObjectNam e of an MBean service this ConnectionFactory or DataSource deployment depends upon. T he connection manager service will not be started until the dependent services have been started. <jndi-name> The JNDI name under which the Datasource should be bound. Note that this name is relative to the java:/ context, unless use-java-context is set to false. DataSource wrappers are not usable outside of the server VM, so they are normally bound under the java:/, which isn't shared outside the local VM. <use-java-context> Boolean value indicating whether the jndi-name should be prefixed with java:. T his prefix causes the Datasource to only be accessible from within the JBoss virtual machine. Defaults to TRUE. <user-name> The user name used to create the connection to the datasource. The actual username may be overridden by the application code getconnection parameters or the connection creation context JAAS Subject. Security This is not used when security is configured. <password> T he password used to create the connection to the datasource. Security This is not used when security is configured. <transaction-isolation> T he java.sql.connection transaction isolation of the connection. If not specified, the database-provided default is used. Possible values for <transaction-isolation> TRANSACTION_READ_UNCOMMITTED 201

205 Red Hat JBoss Portal 5.1 Reference Guide TRANSACTION_READ_COMMITTED TRANSACTION_REPEATABLE_READ TRANSACTION_SERIALIZABLE TRANSACTION_NONE <new-connection-sql> An SQL statement that is executed against each new connection. This can be used to set up the connection schema, for instance. <check-valid-connection-sql> An SQL statement that is executed before the connection is checked out from the pool to make sure it is still valid. If the SQL statement fails, the connection is closed and a new one is created. <valid-connection-checker-class-name> A class that checks whether a connection is valid using a vendor-specific mechanism. <exception-sorter-class-name> A class that parses vendor-specific messages to determine whether SQL errors are fatal, and destroys the connection if so. If empty, no errors are treated as fatal. <track-statements> Whether to monitor for unclosed Statements and ResultSets and issue warnings when they have not been closed. The default value is NOWARN. <prepared-statement-cache-size> The number of prepared statements per connection to be kept open and reused in subsequent requests. They are stored in a Least Recently Used (LRU) cache. The default value is 0, meaning that no cache is kept. <share-prepared-statements> When the <prepared-statement-cache-size> is non-zero, determines whether two requests in the same transaction should return the same statement. Defaults to FALSE. 202

206 Chapter 17. exo JCR Example Using <share-prepared-statements> T he goal is to work around questionable driver behavior, where the driver applies autocommit semantics to local transactions. Connection c = datasource.getconnection(); // auto-commit == false PreparedStatement ps1 = c.preparestatement(...); ResultSet rs1 = ps1.executequery(); PreparedStatement ps2 = c.preparestatement(...); ResultSet rs2 = ps2.executequery(); This assumes that the prepared statements are the same. For some drivers, ps2.executequery() automatically closes rs1, so you actually need two real prepared statements behind the scenes. T his only applies to the auto-commit semantic, where rerunning the query starts a new transaction automatically. For drivers that follow the specification, you can set it to TRUE to share the same real prepared statement. <set-tx-query-timeout> Whether to enable query timeout based on the length of time remaining until the transaction times out. Defaults to FALSE. <query-timeout> The maximum time, in seconds, before a query times out. You can override this value by setting <set-tx-query-timeout> to T RUE. <type-mapping> A pointer to the type mapping in conf/standardjbosscmp.xml. This element is a child element of <metadata>. A legacy from JBoss4. <validate-on-match> Whether to validate the connection when the JCA layer matches a managed connection, such as when the connection is checked out of the pool. With the addition of <backgroundvalidation> this is not required. It is usually not necessary to specify T RUE for <validateon-match> in conjunction with specifying TRUE for <background-validation>. Defaults to TRUE. <prefill> Whether to attempt to prefill the connection pool to the minimum number of connections. Only supporting pools (OnePool) support this feature. A warning is logged if the pool does not support prefilling. Defaults to T RUE. <background-validation> Background connection validation reduces the overall load on the RDBMS system when validating a connection. When using this feature, EAP checks whether the current connection in the pool a separate thread (ConnectionValidator). <background-validation-minutes> depends on this value also being set to TRUE. Defaults to FALSE. 203

207 Red Hat JBoss Portal 5.1 Reference Guide <background-validation-millis> Background connection validation reduces the overall load on the RDBMS system when validating a connection. Setting this parameter means that JBoss will attempt to validate the current connections in the pool as a separate thread (ConnectionValidator). T his parameter's value defines the interval, in milliseconds, for which the ConnectionValidator will run. This value should not be the same as your <idle-timeout-minutes> value. <idle-timeout-minutes> The maximum time, in minutes, before an idle connection is closed. A value of 0 disables timeout. Defaults to 15 minutes. <track-connection-by-tx> Whether the connection should be locked to the transaction, instead of returning it to the pool at the end of the transaction. In previous releases, this was true for local connection factories and false for XA connection factories. The default is now true for both local and XA connection factories, and the element has been deprecated. <interleaving> Enables interleaving for XA connection factories. <background-validation-minutes> How often, in minutes, the ConnectionValidator runs. Defaults to 10 minutes. Note You should set this to a smallervalue than <idle-timeout-minutes>, unless you have specified <min-pool-size> a minimum pool size set. <url-delimiter>, <url-property>, <url-selector-strategy-class-name> Parameters dealing with database failover. As of JBoss Enterprise Application Platform 5.1, these are configured as part of the main datasource configuration. In previous versions, <urldelimiter> appeared as <url-delimeter>. <stale-connection-checker-class-name> An implementation of org.jboss.resource.adapter.jdbc.stateconnectionchecker that decides whether SQLExceptions that notify of bad connections throw the org.jboss.resource.adapter.jdbc.stateconnectionexception exception. <max-pool-size> T he maximum number of connections allowed in the pool. Defaults to 20. <min-pool-size> 204

208 Chapter 17. exo JCR T he minimum number of connections maintained in the pool. Unless <prefill> is T RUE, the pool remains empty until the first use, at which point the pool is filled to the <min-pool-size>. When the pool size drops below the <min-pool-size> due to idle timeouts, the pool is refilled to the <min-pool-size>. Defaults to 0. <blocking-timeout-millis> The length of time, in milliseconds, to wait for a connection to become available when all the connections are checked out. Defaults to 30000, which is 30 seconds. <use-fast-fail> Whether to continue trying to acquire a connection from the pool even if the previous attempt has failed, or begin failover. T his is to address performance issues where validation SQL takes significant time and resources to execute. Defaults to FALSE. Parameters for javax.sql.xadatasource Usage <connection-url> T he JDBC driver connection URL string <driver-class> T he JDBC driver class implementing the java.sql.driver <connection-property> Used to configure the connections retrieved from the java.sql.driver. Example Example <connection-property> <connection-property name="char.encoding">utf-8</connection-property> Parameters for javax.sql.xadatasource Usage <xa-datasource-class> T he class implementing the XADataSource <xa-datasource-property> Properties used to configure the XADataSource. 205

209 Red Hat JBoss Portal 5.1 Reference Guide Example Example <xa-datasource-property> Declarations <xa-datasource-property name="ifxwaittime">10</xa-datasource-property> <xa-datasource-property name="ifxifxhost">myhost.mydomain.com</xadatasource-property> <xa-datasource-property name="portnumber">1557</xa-datasource-property> <xa-datasource-property name="databasename">mydb</xa-datasource-property> <xa-datasource-property name="servername">myserver</xa-datasourceproperty> <xa-resource-timeout> T he number of seconds passed to XAResource.setT ransactiont im eout() when not zero. <issamerm-override-value> When set to FALSE, fixes some problems with Oracle databases. <no-tx-separate-pools> Pool transactional and non-transactional connections separately Warning Using this option will cause your total pool size to be twice m ax-pool-size, because two actual pools will be created. Used to fix problems with Oracle. Security Parameters <application-managed-security> Uses the username and password passed on the getconnection or createconnection request by the application. <security-domain> Uses the identified login module configured in conf/login-m odule.xm l. <security-domain-and-application> Uses the identified login module configured in conf/login-m odule.xm l and other connection request information supplied by the application, for example JMS Queues and Topics. Parameters for XA Recovery in the JCA Layer <recover-user-name> 206

210 Chapter 17. exo JCR T he user with credentials to perform a recovery operation. <recover-password> Password of the user with credentials to perform a recovery operation. <recover-security-domain> Security domain for recovery. <no-recover> Excludes a datasource from recovery. The fields in Parameters for XA Recovery in the JCA Layer should have a fall back value of their nonrecover counterparts: <user-name>, < password> and <security-domain> Datasource Examples Configuring a DataSource for Remote Usage JBoss EAP supports accessing a DataSource from a remote client. See Example 17.4, Configuring a Datasource for Remote Usage for the change that gives the client the ability to look up the DataSource from JNDI, which is to specify use-java-context=false. Example Configuring a Datasource for Remote Usage <datasources> <local-tx-datasource> <jndi-name>genericds</jndi-name> <use-java-context>false</use-java-context> <connection-url>...</connection-url>... This causes the DataSource to be bound under the JNDI name GenericDS instead of the default of java:/genericds, which restricts the lookup to the same Virtual Machine as the EAP server. Note Use of the <use-java-context> setting is not recommended in a production environment. It requires accessing a connection pool remotely and this can cause unexpected problems, since connections are not serializable. Also, transaction propagation is not supported, since it can lead to connection leaks if unreliability is present, such as in a system crash or network failure. A remote session bean facade is the preferred way to access a datasource remotely Configuring a Datasource to Use Login Modules Procedure Configuring a Datasource to Use Login Modules 1. Add the <security-domain-parameter> to the XML file for the datasource. 207

211 Red Hat JBoss Portal 5.1 Reference Guide <datasources> <local-tx-datasource>... <security-domain>mydomain</security-domain>... </local-tx-datasource> </datasources> 2. Add an application policy to the login-config.xm l file. T he authentication section needs to include the configuration for your login-module. For example, to encrypt the database password, use the SecureIdentityLoginModule login module. <application-policy name="mydomain"> <authentication> <login-module code="org.jboss.resource.security.secureidentityloginmodule" flag="required"> <module-option name="username">scott</module-option> <module-option name="password">-170dd0fbd8c13748</moduleoption> <module-option name="managedconnectionfactoryname">jboss.jca:service=localtxcm,name=oracleds JAAS</module-option> </login-module> </authentication> </application-policy> 3. If you plan to fetch the data source connection from a web application, authentication must be enabled for the web application, so that the Subject is populated. 4. If users need the ability to connect anonymously, add an additional login module to the applicationpolicy, to populate the security credentials. 5. Add the UsersRolesLoginModule module to the beginning of the chain. The usersproperties and rolesproperties parameters can be directed to dummy files. <login-module code="org.jboss.security.auth.spi.usersrolesloginmodule" flag="required"> <module-option name="unauthenticatedidentity">nobody</module-option> <module-option name="usersproperties">props/users.properties</moduleoption> <module-option name="rolesproperties">props/roles.properties</moduleoption> </login-module> External Value Storages Introduction JCR values are stored in the Workspace Data container by default. exo JCR offers an additional option of storing JCR values separately from the Workspace Data container which can help keep Binary Large Objects (BLOBs) separate. Value storage configuration is a part of the repository configuration. Refer to Section , Example of the portal-system workspace for more details. T ree-based storage is recommended in most cases. 208

212 Chapter 17. exo JCR Tree File Value Storage T ree File Value Storage holds values in tree-like file system files. Path property points to the root directory to store the files. This is a recommended type of external storage because it can contain large amount of files limited only by disk/volume free space. However, using Tree File Value Storage can result in a higher time on value deletion, due to the removal of unused tree-nodes. <value-storage id="storage #1" class="org.exoplatform.services.jcr.impl.storage.value.fs.treefilevaluestorage"> <properties> <property name="path" value="data/values"/> </properties> <filters> <filter property-type="binary" min-value-size="1m"/> </filters> The id is the value storage unique identifier, used for linking with properties stored in a workspace container path is a location where value files will be stored. Each file value storage can have the filters for incoming values. A filter can match values by property-type, property-name, ancestor-path. It can also match the size of values stored (min-value-size) in bytes. In the previous example a filter with property-type and min-value-size has been used. T his results in storage for binary values with size greater of 1MB. It is recommended that properties with large values are stored in file value storage only. T he example below shows a value storage with different locations for large files (min-value-size a 20Mb-sized filter). A value storage uses ORed logic in the process of filter selection. This means the first filter in the list will be called first and if it is not matched the next will be called, and so on. In this example a value matches the 20MB filter min-value-size and will be stored in the path "data/20mvalues". All other filters will be stored in "data/values". 209

213 Red Hat JBoss Portal 5.1 Reference Guide <value-storages> <value-storage id="storage #1" class="org.exoplatform.services.jcr.impl.storage.value.fs.treefilevaluestorage"> <properties> <property name="path" value="data/20mvalues"/> </properties> <filters> <filter property-type="binary" min-value-size="20m"/> </filters> <value-storage> <value-storage id="storage #2" class="org.exoplatform.services.jcr.impl.storage.value.fs.treefilevaluestorage"> <properties> <property name="path" value="data/values"/> </properties> <filters> <filter property-type="binary" min-value-size="1m"/> </filters> <value-storage> <value-storages> Content Addressable Value storage (CAS) support exo JCR supports the Content-addressable storage feature for values storing. Content-addressable storage, also referred to as associative storage and abbreviated as CAS, is a mechanism for storing information that can be retrieved based on its content, not its storage location. It is typically used for high-speed storage and retrieval of fixed content, such as documents stored for compliance with government regulations. Content-addressable value storage stores unique content once. Different properties (values) with same content will be stored as one data file shared between those values. We can tell the value content will be shared across some values in storage and will be stored in one physical file. Storage size will be decreased for applications which govern potentially same data in the content. As an example; if 100 different properties contain the same data (mail attachments for example) the storage stores only one single file. T he file will be shared with all referencing properties. If a property value changes it is stored in an additional file. Alternatively the file is shared with other values, pointing to the same content. T he storage calculates value content address each time the property was changed. CAS write operations are more expensive compared to the non-cas storages. Content address calculation is based on java.security.messagedigest hash computation and has been tested with MD5 and SHA1 algorithms. Note CAS storage works most efficiently on data that does not change often. For data that changes frequently CAS is not as efficient as location-based addressing. CAS support can be enabled for Tree and Simple File Value Storage types. 210

214 Chapter 17. exo JCR T o enable CAS support just configure it in the JCR Repositories configuration with other Value Storages. <workspaces> <workspace name="ws"> <container class="org.exoplatform.services.jcr.impl.storage.jdbc.jdbcworkspacedatacontainer"> <properties> <property name="source-name" value="jdbcjcr"/> <property name="dialect" value="oracle"/> <property name="multi-db" value="false"/> <property name="update-storage" value="false"/> <property name="max-buffer-size" value="200k"/> <property name="swap-directory" value="target/temp/swap/ws"/> </properties> <value-storages> <! here > <value-storage id="ws" class="org.exoplatform.services.jcr.impl.storage.value.fs.casabletreefilevaluestora ge"> <properties> <property name="path" value="target/temp/values/ws"/> <property name="digest-algo" value="md5"/> <property name="vcas-type" value="org.exoplatform.services.jcr.impl.storage.value.cas.jdbcvaluecontentaddresss torageimpl"/> <property name="jdbc-source-name" value="jdbcjcr"/> <property name="jdbc-dialect" value="oracle"/> </properties> <filters> <filter property-type="binary"/> </filters> </value-storage> </value-storages> CAS Properties digest-algo Digest hash algorithm (MD5 and SHA1 were tested). vcas-type Value CAS internal data type, JDBC backed is currently implemented: org.exoplatform.services.jcr.im pl.storage.value.cas.jdbcvaluecontentad dressstorageim pl jdbc-source-name A JDBCValueContentAddressStorageIm pl specific parameter, a database will be used to save CAS metadata. jdbc-dialect A DBCValueContentAddressStorageIm pl specific parameter defining database dialect. 211

215 Red Hat JBoss Portal 5.1 Reference Guide Search Configuration The search function in JCR can be configured to perform in specific ways. This section will discuss configuring the search function to improve search performance and results. Below is an example of the configuration file that governs search behaviors. Refer to Section , Global Search Index for how searching operates in JCR and discussions about customized searches. The JCR index configuration file is located at JBOSS_HOME/server/<PROFILE>/deploy/gatein.ear/02portal.war/WEB- INF/conf/jcr/repository-configuration.xm l. A code example is included below with a list of the configuration parameters shown below that. <repository-service default-repository="db1"> <repositories> <repository name="db1" system-workspace="ws" default-workspace="ws">... <workspaces> <workspace name="ws">... <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.searchindex"> <properties> <property name="index-dir" value="${java.io.tmpdir}/temp/index/db1/ws" /> <property name="synonymprovider-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.propertiessynonymprovid er" /> <property name="synonymprovider-config-path" value="/synonyms.properties" /> <property name="indexing-config-path" value="/indexingconfiguration.xml" /> <property name="query-class" value="org.exoplatform.services.jcr.impl.core.query.queryimpl" /> </properties> </query-handler>... </workspace> </workspaces> </repository> </repositories> </repository-service> T he table below outlines the Configuration Parameters available, their default setting, which version of exo JCR they were implemented in and other useful information: 212

216 Chapter 17. exo JCR T able Configuration parameters Parameter Default Description Implemen ted in Version index-dir none T he location of the index directory. This parameter is mandatory. It is called "indexdir" in versions prior to exo JCR version 1.9. use-compoundfile true Advises lucene to use compound files for the index files. min-merge-docs 100 T he minimum number of nodes in an index until segments are merged. volatile-idle-time 3 Idle time in seconds until the volatile index part is moved to a persistent index even though m inmergedocs is not reached. max-merge-docs Integer.MAX_VALUE T he maximum number of nodes in segments that will be merged. The default value changed to Integer.MAX_VALUE in exo JCR version 1.9. merge-factor 10 Determines how often segment indices are merged. max-field-length T he number of words that are full-text indexed at most per property. cache-size 1000 Size of the document number cache. This cache maps UUID to lucene document numbers forceconsistencycheck false Runs a consistency check on every start up. If false, a consistency check is only performed when the search index detects a prior forced shutdown. auto-repair true Errors detected by a consistency check are automatically repaired. If false, errors are only written to the log. query-class QueryImpl Classname that implements the javax.jcr.query.query interface. This class must also extend from the class: org.exoplatform.services.jcr.impl.core. query.abstractqueryim pl. document-order true If true and the query does not contain an 'order by' clause, result nodes will be in document order. For better performance set to 'false' when queries return many nodes. result-fetch-size Integer.MAX_VALUE T he number of results when a query is

217 Red Hat JBoss Portal 5.1 Reference Guide executed. Default value: Integer.MAX_VALUE. excerptprovider-class DefaultXMLExcerpt T he name of the class that implements org.exoplatform.services.jcr.impl.core. query.lucene.excerptprovider. This should be used for the rep:excerpt() function in a query. support-highlighting false If set to true additional information is stored in the index to support highlighting using the rep:excerpt() function. none The name of a class that implements org.exoplatform.services.jcr.impl.core. query.lucene.synonym Provider. The default value is null synonymproviderclass synonymproviderconfig-path indexingconfiguration-path indexingconfiguration-class forceconsistencycheck none none IndexingConfigurationI mpl false T he path to the synonym provider configuration file. T his path is interpreted relative to the path parameter. If there is a path element inside the SearchIndex element, then this path is interpreted relative to the root path of the path. Whether this parameter is mandatory depends on the synonym provider implementation. The default value is null. T he path to the indexing configuration file. The name of the class that implements org.exoplatform.services.jcr.impl.core. query.lucene.indexingconfigu ration. If set to true a consistency check is performed depending on the parameter forceconsistencycheck. If set to false no consistency check is performed on start up, even if a redo log had been applied. spellchecker-class none The name of a class that implements org.exoplatform.services.jcr.impl.core. query.lucene.spellchecker. errorlog-size 50(KB) T he default size of error log file in KB. 1.9 upgrade-index false Allows JCR to convert an existing index into the new format. It is also possible to set this property via

218 Chapter 17. exo JCR system property. For example: -Dupgradeindex=true Indexes prior to exo JCR 1.12 will not run with exo JCR You must run an automatic migration. Start exo JCR with: -Dupgrade-index=true The old index format is then converted in the new index format. After the conversion the new format is used. On subsequent starts this option is no longer needed. The old index is replaced and a back conversion is not possible It is recommended that a backup of the index be made before conversion. (Only for migrations from JCR 1.9 and later.) analyzer org.apache.lucene.ana lysis. standard.standardana lyzer Class name of a lucene analyzer to use for full-text indexing of text Global Search Index By default exo JCR uses the Lucene standard Analyzer to index contents. This analyzer uses some standard filters in the method that analyzes the content: public TokenStream tokenstream(string fieldname, Reader reader) { StandardTokenizer tokenstream = new StandardTokenizer(reader, replaceinvalidacronym); tokenstream.setmaxtokenlength(maxtokenlength); TokenStream result = new StandardFilter(tokenStream); result = new LowerCaseFilter(result); result = new StopFilter(result, stopset); } return result; T he first filter (StandardFilter) removes possessive apostrophes ('s) from the end of words and removes periods (.) from acronyms. T he second filter (LowerCaseFilter) normalizes token text to lower case. The last filter (StopFilter) removes stop words from a token stream. The stop set is defined in the analyzer. 215

219 Red Hat JBoss Portal 5.1 Reference Guide The global search index is configured in the JBOSS_HOME/server/<VERSION>/deploy/gatein.ear/02portal.war/WEB- INF/conf/jcr/repository-configuration.xm l configuration file within the "query-handler" tag. <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.searchindex"> The same analyzer should always be used for indexing and for querying in lucene. Results may be unpredictable in other instances. exo JCR does this automatically. T he StandardAnalyzer (configured by default) can, however, be replaced with another. A customized QueryHandler can also be easily created. Customized Search Indexes and Analyzers Additional filters can be used in specific cases. T he ISOLatin1AccentFilter filter, for example, which replaces accented characters in the ISO Latin 1 character set (ISO ) by their unaccented equivalents. T he ISOLatin1AccentFilter is not present in the current lucene version used by exo. In order to use a different filter, a new analyzer must be created, as well as new search index to use the analyzer. T hese are packaged into a jar file, which is then deployed with the application. Procedure Create a new filter, analyzer and search index 1. Create a new filter with the method: public final Token next(final Token reusabletoken) throws java.io.ioexception This defines how characters are read and used by the filter. 2. Create the analyzer. T he analyzer must extend org.apache.lucene.analysis.standard.standardanalyzer and overload the method. Use the following to use new filters. public TokenStream tokenstream(string fieldname, Reader reader) 3. To create the new search index, extend org.exoplatform.services.jcr.im pl.core.query.lucene.searchindex and write the constructor to set the correct analyzer. Use the method below to return your analyzer: public Analyzer getanalyzer() { return MyAnalyzer; } Note In exo JCR version 1.12 (and later) the analyzer can be directly set in the configuration. For users with this version the creation of a new SearchIndex for new analyzers is redundant. 216

220 Chapter 17. exo JCR T o configure an application to use a new SearchIndex, replace the following code: <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.searchindex"> in JBOSS_HOME/server/<VERSION>/deploy/gatein.ear/02portal.war/WEB- INF/conf/jcr/repository-configuration.xm l with the new class: <query-handler class="mypackage.indexation.mysearchindex> T o configure an application to use a new analyzer, add the analyzer parameter to each query-handler configuration in JBOSS_HOME/server/<VERSION>/deploy/gatein.ear/02portal.war/WEB- INF/conf/jcr/repository-configuration.xm l: <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.searchindex"> <properties>... <property name="analyzer" value="org.exoplatform.services.jcr.impl.core.myanalyzer"/>... </properties> </query-handler> The new SearchIndex will start to index contents with the specified filters when the JCR is next started IndexingConfiguration From version 1.9, the default search index implementation in JCR allows user control over which properties of a node are indexed. Different analyzers can also be set for different nodes. T he configuration parameter is called indexingconfiguration and is not set by default. T his means all properties of a node are indexed. T o configure the indexing behavior add a parameter to the query-handler element in your configuration file. <param name="indexing-configuration-path" value="/indexing_configuration.xml"/> Node Scope Limit The node scope can be limited so that only certain properties of a node type are indexed. This can optimize the index size. With the configuration below only properties named Text are indexed for nt:unstructured node types. T his configuration also applies to all nodes whose type extends from nt:unstructured. 217

221 Red Hat JBoss Portal 5.1 Reference Guide <?xml version="1.0"?> <!DOCTYPE configuration SYSTEM " <configuration xmlns:nt=" <index-rule nodetype="nt:unstructured"> <property>text</property> </index-rule> </configuration> Namespace Prefixes T he namespace prefixes must be declared throughout the XML file in the configuration element that is being used. It is also possible to configure a boost value for the nodes that match the index rule. The default boost value is 1.0. Higher boost values (a reasonable range is ) will yield a higher score value and appear as more relevant. <?xml version="1.0"?> <!DOCTYPE configuration SYSTEM " <configuration xmlns:nt=" <index-rule nodetype="nt:unstructured" boost="2.0"> <property>text</property> </index-rule> </configuration> If you do not wish to boost the complete node, but only certain properties, you can also provide a boost value for the listed properties: <?xml version="1.0"?> <!DOCTYPE configuration SYSTEM " <configuration xmlns:nt=" <index-rule nodetype="nt:unstructured"> <property boost="3.0">title</property> <property boost="1.5">text</property> </index-rule> </configuration> Conditional Index Rules You may also add a condition to the index rule and have multiple rules with the same nodetype. The first index rule that matches will apply and all remaining ones are ignored: 218

222 Chapter 17. exo JCR <?xml version="1.0"?> <!DOCTYPE configuration SYSTEM " <configuration xmlns:nt=" <index-rule nodetype="nt:unstructured" boost="2.0" priority = 'high'"> <property>text</property> </index-rule> <index-rule nodetype="nt:unstructured"> <property>text</property> </index-rule> </configuration> In the above example the first rule only applies if the nt:unstructured node has a priority property with a value high. T he condition syntax only supports the equals operator and a string literal. Properties may also be referenced on the condition that are not on the current node: <?xml version="1.0"?> <!DOCTYPE configuration SYSTEM " <configuration xmlns:nt=" <index-rule nodetype="nt:unstructured" boost="2.0" condition="ancestor::*/@ priority = 'high'"> <property>text</property> </index-rule> <index-rule nodetype="nt:unstructured" boost="0.5" condition="parent::foo/@ priority = 'low'"> <property>text</property> </index-rule> <index-rule nodetype="nt:unstructured" boost="1.5" condition="bar/@ priority = 'medium'"> <property>text</property> </index-rule> <index-rule nodetype="nt:unstructured"> <property>text</property> </index-rule> </configuration> The indexing configuration allows the type of a node in the condition to be specified. Please note however that the type match must be exact. It does not consider sub types of the specified node type. <?xml version="1.0"?> <!DOCTYPE configuration SYSTEM " <configuration xmlns:nt=" <index-rule nodetype="nt:unstructured" boost="2.0" condition="element(*, nt:unstructured)/@ priority = 'high'"> <property>text</property> </index-rule> </configuration> 219

223 Red Hat JBoss Portal 5.1 Reference Guide All configured properties are full-text indexed by default (if they are of type STRING and included in the node scope index). A node scope search normally finds all nodes of an index. That is to say; jcr:contains(., 'foo') returns all nodes that have a string property containing the word 'foo'. Properties can be explicitly excluded from the node scope index with: <?xml version="1.0"?> <!DOCTYPE configuration SYSTEM " <configuration xmlns:nt=" <index-rule nodetype="nt:unstructured"> <property nodescopeindex="false">text</property> </index-rule> </configuration> Index Aggregates Sometimes it is useful to include the contents of descendant nodes into a single node to more easily search on content that is scattered across multiple nodes. JCR allows the definition of index aggregates based on relative path patterns and primary node types. T he following example creates an index aggregate on nt:file that includes the content of the jcr:content node: <?xml version="1.0"?> <!DOCTYPE configuration SYSTEM " <configuration xmlns:jcr=" xmlns:nt=" <aggregate primarytype="nt:file"> <include>jcr:content</include> </aggregate> </configuration> Included nodes can also be restricted to a certain type: <?xml version="1.0"?> <!DOCTYPE configuration SYSTEM " <configuration xmlns:jcr=" xmlns:nt=" <aggregate primarytype="nt:file"> <include primarytype="nt:resource">jcr:content</include> </aggregate> </configuration> The * wild-card can be used to match all child nodes: 220

224 Chapter 17. exo JCR <?xml version="1.0"?> <!DOCTYPE configuration SYSTEM " <configuration xmlns:jcr=" xmlns:nt=" <aggregate primarytype="nt:file"> uration <include primarytype="nt:resource">* </include> </aggregate> </configuration> Nodes to a certain depth below the current node can be included by adding multiple include elements. T he nt:file node may contain a complete XML document under jcr:content for example: <?xml version="1.0"?> <!DOCTYPE configuration SYSTEM " <configuration xmlns:jcr=" xmlns:nt=" <aggregate primarytype="nt:file"> <include>* </include> <include>*/* </include> <include>*/*/*</include> </aggregate> </configuration> Property-Level Analyzers How a property has to be analyzed can be defined in the following configuration section. If there is an analyzer configuration for a property, this analyzer is used for indexing and searching of this property. For example: <?xml version="1.0"?> <!DOCTYPE configuration SYSTEM " <configuration xmlns:nt=" <analyzers> <analyzer class="org.apache.lucene.analysis.keywordanalyzer"> <property>mytext</property> </analyzer> <analyzer class="org.apache.lucene.analysis.whitespaceanalyzer"> <property>mytext2</property> </analyzer> </analyzers> </configuration> T he configuration above sets lucene KeywordAnalyzer to index and search the property "mytext" across the entire workspace while the "mytext2" property is searched with the WhitespaceAnalyzer. T he WhitespaceAnalyzer tokenizes a property, the KeywordAnalyzer takes the property as a whole. Using different analyzers for different languages can be particularly useful. Characteristics of Node Scope Searches Unexpected behavior may be encountered when using analyzers to search within a property compared 221

225 Red Hat JBoss Portal 5.1 Reference Guide to searching within a node scope. This is because the node scope always uses the global analyzer. For example: the property "mytext" contains the text; "testing my analyzers" but no analyzers have been configured for this property (and the default analyzer in SearchIndex has not been changed). If the query is: xpath = "//*[jcr:contains(mytext,'analyzer')]" The xpath does not return a result in the node with the property above and default analyzers. Also, if a search is done on the node scope as follows: xpath = "//*[jcr:contains(.,'analyzer')]" No result will be returned. Only specific analyzers can be set on a node property, and the node scope indexing and analyzing is always done with the globally defined analyzer in the SearchIndex element. If the analyzer used to index the "mytext" property above is changed to: <analyzer class="org.apache.lucene.analysis.analyzer.germananalyzer"> <property>mytext</property> </analyzer> T he search below would return a result because of the word stemming (analyzers - analyzer). xpath = "//*[jcr:contains(mytext,'analyzer')]" The second search in the example: xpath = "//*[jcr:contains(.,'analyzer')]" Would still not give a result, since the node scope is indexed with the global analyzer, which in this case does not take into account any word stemming. Be aware that when using analyzers for specific properties, a result may be found in a property for certain search text, but the same search text in the node scope of the property may not find a result. Note Both index rules and index aggregates influence how content is indexed in JCR. If the configuration is changed, the existing content is not automatically re-indexed according to the new rules. Content must be manually re-indexed when the configuration is changed Multi-language support in exo JCR RDB back end Whenever a relational database is used to store multilingual text data in the exo Java Content Repository the configuration must be adapted to support UT F-8 encoding. Dialect is automatically detected for certified database. You can still enforce it in case of failure, see below. 222

226 Chapter 17. exo JCR T he following sections describe enabling UT F-8 support with various databases. Section , Oracle Section , DB2 Section , MySQL Section , PostgreSQL Note 1. T he configuration file to be modified for these changes is:jboss_home/server/<profile>/deploy/gatein.ear/02portal.war/web- INF/conf/jcr/repository-configuration.xm l 2. The datasource jdbcjcr used in the following examples can be configured via the InitialContextInitializer component Oracle In order to run a multi-language instance of JCR on an Oracle back end, Unicode encoding should be applied to the database. T o create a database with Unicode encoding using Oracle dialect for the Workspace Container, implement the following settings: <workspace name="collaboration"> <container class="org.exoplatform.services.jcr.impl.storage.jdbc.jdbcworkspacedatacontainer"> <properties> <property name="source-name" value="jdbcjcr" /> <property name="dialect" value="oracle" /> <property name="multi-db" value="false" /> <property name="max-buffer-size" value="200k" /> <property name="swap-directory" value="target/temp/swap/ws" /> </properties> DB2 DB2 Universal Database (DB2 UDB) supports UT F-8 and UT F-16/UCS-2. When a Unicode database is created, CHAR, VARCHAR and LONG VARCHAR data are stored in UT F-8 form. T his enables JCR multi-lingual support. Below is an example of creating a UTF-8 database using the db2 dialect for a workspace container with DB2 version 9 and higher: DB2 CREATE DATABASE dbname USING CODESET UTF-8 TERRITORY US 223

227 Red Hat JBoss Portal 5.1 Reference Guide <workspace name="collaboration"> <container class="org.exoplatform.services.jcr.impl.storage.jdbc.jdbcworkspacedatacontainer"> <properties> <property name="source-name" value="jdbcjcr" /> <property name="dialect" value="db2" /> <property name="multi-db" value="false" /> <property name="max-buffer-size" value="200k" /> <property name="swap-directory" value="target/temp/swap/ws" /> </properties>... Note For DB2 version 8.x support change the property "dialect" to db2v MySQL Using JCR with a MySQL-back end requires a special dialect MySQL-UTF8 to be used for internationalization support. T he database default charset should be latin1 so as to use limited index space effectively (1000 bytes for an MyISAM engine and 767 for InnoDB). If the database default charset is multibyte, a JCR database initialization error is encountered concerning index creation failure. JCR can work on any single byte default charset of database, with UTF8 supported by MySQL server. However it has only been tested using the latin1 charset. An example entry: <workspace name="collaboration"> <container class="org.exoplatform.services.jcr.impl.storage.jdbc.jdbcworkspacedatacontainer"> <properties> <property name="source-name" value="jdbcjcr" /> <property name="dialect" value="mysql-utf8" /> <property name="multi-db" value="false" /> <property name="max-buffer-size" value="200k" /> <property name="swap-directory" value="target/temp/swap/ws" /> </properties> PostgreSQL Multilingual support can be enabled with a PostgreSQL-back end in different ways: 1. Using the locale features of the operating system to provide locale-specific collation order, number formatting, translated messages, and other aspects. UTF-8 is widely used on Linux distributions by default, so it can be useful in such cases. 2. Providing a number of different character sets defined in the PostgreSQL server, including multiple-byte character sets, to support storing text any language, and providing character set translation between client and server. 224

228 Chapter 17. exo JCR Using UT F-8 database charset is recommended as it will allow any-to-any conversations and make this issue transparent for the JCR. Example of a database with UT F-8 encoding using PgSQL dialect for the Workspace Container: <workspace name="collaboration"> <container class="org.exoplatform.services.jcr.impl.storage.jdbc.jdbcworkspacedatacontainer"> <properties> <property name="source-name" value="jdbcjcr" /> <property name="dialect" value="pgsql" /> <property name="multi-db" value="false" /> <property name="max-buffer-size" value="200k" /> <property name="swap-directory" value="target/temp/swap/ws" /> </properties> JBoss Cache configuration JCR workspaces and their caches are configured in server/<profile>/deploy/gatein.ear/02portal.war/web-inf/conf/jcr/repositoryconfiguration.xm l. Parameterized properties will be replaced with actual parameters defined in jbossas/server/<profile>/conf/gatein/configuration.properties file. Refer the examples below for an active illustration of this parameter handling: Example repository-configuration.xm l <properties> <property name="source-name" value="${gatein.jcr.datasource.name}${container.name.suffix}"/> <property name="dialect" value="${gatein.jcr.datasource.dialect}"/> <property name="multi-db" value="false"/> <property name="update-storage" value="true"/> <property name="max-buffer-size" value="204800"/> <property name="swap-directory" value="${gatein.jcr.data.dir}/system${container.name.suffix}"/> </properties> 225

229 Red Hat JBoss Portal 5.1 Reference Guide Example configuration.properties # JCR gatein.jcr.config.type=local gatein.jcr.datasource.name=java:gatein-jcr gatein.jcr.datasource.dialect=auto gatein.jcr.data.dir=${gatein.data.dir}/jcr gatein.jcr.storage.data.dir=${gatein.jcr.data.dir}/values gatein.jcr.index.data.dir=${gatein.jcr.data.dir}/lucene gatein.jcr.index.changefilterclass=org.exoplatform.services.jcr.impl.core.query. DefaultChangesFilter </properties> The JBoss cache and jgroups configuration files are located inside the server/<profile>/deploy/gatein.ear/lib/exo.portal.com ponent.com m on-<version>. jar file. Within this jar the files are located at /conf/jcr/jbosscache/${gatein.jcr.config.type} (${gatein.jcr.config.type} is defined in configuration.properties and denotes either cluster or local directories) Indexer, Lock Manager and Data Container Each of these components uses instances of the JBoss Cache product for caching in a clustered environment so every element has its own transport and has to be configured correctly. As usual, workspaces have similar configurations but with different cluster-names (and possibly some other parameters). T he best way to configure them is to define specific configuration files for each component in each workspace. For example: <property name="jbosscache-configuration" value="conf/standalone/test-jbosscachelock-db1-ws1.xml" /> If there are many workspaces, however, configuring them in such a way can be hard to manage. T herefore the JCR offers a template-based configuration method for JBoss Cache instances. Administrators can use one template for the lock manager, another for the indexer and a third for the data container and then use them in all the workspaces by defining the map of substitution parameters in the main configuration file JGroups configuration JGroups is used by JBoss Cache for network communications and transport in a clustered environment. If the property "jgroups-configuration" is defined in the component configuration, it will be injected into the JBoss Cache instance on start up. <property name="jgroups-configuration" value="your/path/to/modified-udp.xml" /> As mentioned previously, each component (lock manager, data container and query handler) for each workspace requires its own clustered environment. 226

230 Chapter 17. exo JCR Each cluster should perform multi-casts on separate ports by default. T his configuration leads to unnecessary overhead on the cluster. JGroups offers a multiplexer feature providing the ability to use a single channel for a set of clusters. T his feature reduces network overheads and increases the performance and stability of an application. T o enable the multiplexer stack feature, the appropriate configuration file must be defined and the "jgroups-multiplexer-stack" should be set to "true". A configuration file named upd-m ux.xm l is pre-shipped with the product. For example: <property name="jgroups-configuration" value="jar:/conf/portal/udp-mux.xml" /> <property name="jgroups-multiplexer-stack" value="true" /> LockManager T he LockManager stores lock objects. It can lock or release objects as required. It is also responsible for removing stale locks. The LockManager in JBoss Enterprise Portal Platform is implemented with org.exoplatform.services.jcr.im pl.core.lock.jbosscache.cacheablelockmanager Impl. It is enabled by adding lock-m anager-configuration to workspace-configuration. For example: <workspace name="ws">... <lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.cacheablelockmanageri mpl"> <properties> <property name="time-out" value="15m" />... </properties> </lock-manager>... </workspace> CacheableLockManagerImpl CacheableLockManagerIm pl stores lock objects in JBoss-cache (which implements JDBCCacheLoader to store locks in a database). This means its locks are replicable and can affect an entire cluster rather than just a single node. The length of time LockManager allows a lock to remain in place can be configured with the "time-out" property. T he LockRemover thread periodically polls LockManager for locks that have passed the time-out limit and must be removed. The time-out for LockRemover is set as follows (the default value is 30m): 227

231 Red Hat JBoss Portal 5.1 Reference Guide <properties> <property name="time-out" value="10m" />... </properties> T here are a number of ways to configure CacheableLockManagerIm pl. Each involves configuring JBoss Cache and JDBCCacheLoader. Section , Simple JBoss Cache Configuration Section , T emplate JBoss Cache Configuration Refer to for more information about JBoss Cache and JDBCCacheLoader Simple JBoss Cache Configuration One method to configure the LockManager is to put a JBoss Cache configuration file path into CacheableLockManagerIm pl. Note This is not the most efficient method for configuring the LockManager as it requires a JBoss Cache configuration file for each LockManager configuration in each workspace of each repository. T he configuration set up can subsequently become quite difficult to manage. T his method is useful, however, if a single, specially configured LockManager is required. T he required configuration is shown in the example below: <lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.cacheablelockmanageri mpl"> <properties> <property name="time-out" value="15m" /> <property name="jbosscache-configuration" value="conf/standalone/cluster/testjbosscache-lock-config.xml" /> </properties> </lock-manager> T he test-jbosscache-lock-config.xml is shown below. T he test-jbosscache-lock-config.xm l file: 228

232 Chapter 17. exo JCR <?xml version="1.0" encoding="utf-8"?> <jbosscache xmlns:xsi=" xmlns="urn:jboss:jbosscache-core:config:3.2"> <locking uselockstriping="false" concurrencylevel="50000" lockparentforchildinsertremove="false" lockacquisitiontimeout="20000" /> <clustering mode="replication" clustername="jboss-cache-lock-cluster_name"> <stateretrieval timeout="20000" fetchinmemorystate="false" nonblocking="true" /> <jgroupsconfig> <TCP bind_addr=" " start_port="9800" loopback="true" recv_buf_size=" " send_buf_size="640000" discard_incompatible_packets="true" max_bundle_size="64000" max_bundle_timeout="30" use_incoming_packet_handler="true" enable_bundling="false" use_send_queues="false" sock_conn_timeout="300" skip_suspected_members="true" use_concurrent_stack="true" thread_pool.enabled="true" thread_pool.min_threads="1" thread_pool.max_threads="25" thread_pool.keep_alive_time="5000" thread_pool.queue_enabled="false" thread_pool.queue_max_size="100" thread_pool.rejection_policy="run" oob_thread_pool.enabled="true" oob_thread_pool.min_threads="1" oob_thread_pool.max_threads="8" oob_thread_pool.keep_alive_time="5000" oob_thread_pool.queue_enabled="false" oob_thread_pool.queue_max_size="100" oob_thread_pool.rejection_policy="run" /> <MPING timeout="2000" num_initial_members="2" mcast_port="34540" bind_addr=" " mcast_addr=" " /> <MERGE2 max_interval="30000" min_interval="10000" /> <FD_SOCK /> <FD max_tries="5" shun="true" timeout="10000" /> <VERIFY_SUSPECT timeout="1500" /> <pbcast.nakack discard_delivered_msgs="true" gc_lag="0" retransmit_timeout="300,600,1200,2400,4800" use_mcast_xmit="false" /> <UNICAST timeout="300,600,1200,2400,3600" /> <pbcast.stable desired_avg_gossip="50000" max_bytes="400000" stability_delay="1000" /> <pbcast.gms join_timeout="5000" print_local_addr="true" shun="false" view_ack_collection_timeout="5000" view_bundling="true" /> <FRAG2 frag_size="60000" /> <pbcast.streaming_state_transfer /> <pbcast.flush timeout="0" /> </jgroupsconfig <sync /> </clustering> <loaders passivation="false" shared="true"> <preload> <node fqn="/" /> </preload> <loader class="org.jboss.cache.loader.jdbccacheloader" async="false" fetchpersistentstate="false" ignoremodifications="false" purgeonstartup="false"> <properties> cache.jdbc.table.name=jcrlocks_ws cache.jdbc.table.create=true cache.jdbc.table.drop=false 229

233 Red Hat JBoss Portal 5.1 Reference Guide cache.jdbc.table.drop=false cache.jdbc.table.primarykey=jcrlocks_ws_pk cache.jdbc.fqn.column=fqn cache.jdbc.fqn.type=varchar(512) cache.jdbc.node.column=node cache.jdbc.node.type=<blob> cache.jdbc.parent.column=parent cache.jdbc.datasource=jdbcjcr </properties> </loader> </loaders> </jbosscache> T he cluster name at clustering mode="replication" clustername="jboss-cache-lock- Cluster_Name" must be unique; T he cache.jdbc.table.name must be unique per datasource. T he cache.jdbc.node.type and cache.jdbc.fqn.type parameters must be configured according to the database in use. Refer to the table below for information about data types. Table Data Types in Different Databases DataBase name Node data type FQN data type default BLOB VARCHAR(512) HSSQL OBJECT VARCHAR(512) MySQL LONGBLOB VARCHAR(512) ORACLE BLOB VARCHAR2(512) PostgreSQL bytea VARCHAR(512) MSSQL VARBINARY(MAX) VARCHAR(512) DB2 BLOB VARCHAR(512) Sybase IMAGE VARCHAR(512) Ingres long byte VARCHAR(512) T emplate JBoss Cache Configuration Another method to configure LockManager is to use a JBoss Cache configuration template for all LockManagers. Below is an example test-jbosscache-lock.xm l template file: 230

234 Chapter 17. exo JCR <?xml version="1.0" encoding="utf-8"?> <jbosscache xmlns:xsi=" xmlns="urn:jboss:jbosscache-core:config:3.1"> <locking uselockstriping="false" concurrencylevel="50000" lockparentforchildinsertremove="false" lockacquisitiontimeout="20000" /> <clustering mode="replication" clustername="${jbosscache-cluster-name}"> <stateretrieval timeout="20000" fetchinmemorystate="false" /> <jgroupsconfig multiplexerstack="jcr.stack" /> <sync /> </clustering> <loaders passivation="false" shared="true"> <!-- All the data of the JCR locks needs to be loaded at startup --> <preload> <node fqn="/" /> </preload> <!-- For another cache-loader class you should use another template with cache-loader specific parameters --> <loader class="org.jboss.cache.loader.jdbccacheloader" async=q"false" fetchpersistentstate="false" ignoremodifications="false" purgeonstartup="false"> <properties> cache.jdbc.table.name=${jbosscache-cl-cache.jdbc.table.name} cache.jdbc.table.create=${jbosscache-cl-cache.jdbc.table.create} cache.jdbc.table.drop=${jbosscache-cl-cache.jdbc.table.drop} cache.jdbc.table.primarykey=${jbosscache-clcache.jdbc.table.primarykey} cache.jdbc.fqn.column=${jbosscache-cl-cache.jdbc.fqn.column} cache.jdbc.fqn.type=${jbosscache-cl-cache.jdbc.fqn.type} cache.jdbc.node.column=${jbosscache-cl-cache.jdbc.node.column} cache.jdbc.node.type=${jbosscache-cl-cache.jdbc.node.type} cache.jdbc.parent.column=${jbosscache-cl-cache.jdbc.parent.column} cache.jdbc.datasource=${jbosscache-cl-cache.jdbc.datasource} </properties> </loader> </loaders> </jbosscache> All the configurable parameters in this file are populated with templates which will be replaced with LockManager's configuration parameters. The parameters that will populate the above file are shown below: 231

235 Red Hat JBoss Portal 5.1 Reference Guide <lock-manager class="org.exoplatform.services.jcr.impl.core.lock.jbosscache.cacheablelockmanageri mpl"> <properties> <property name="time-out" value="15m" /> <property name="jbosscache-configuration" value="test-jbosscache-lock.xml" /> <property name="jgroups-configuration" value="udp-mux.xml" /> <property name="jgroups-multiplexer-stack" value="true" /> <property name="jbosscache-cluster-name" value="jcr-cluster-locks-ws" /> <property name="jbosscache-cl-cache.jdbc.table.name" value="jcrlocks_ws" /> <property name="jbosscache-cl-cache.jdbc.table.create" value="true" /> <property name="jbosscache-cl-cache.jdbc.table.drop" value="false" /> <property name="jbosscache-cl-cache.jdbc.table.primarykey" value="jcrlocks_ws_pk" /> <property name="jbosscache-cl-cache.jdbc.fqn.column" value="fqn" /> <property name="jbosscache-cl-cache.jdbc.fqn.type" value="auto"/> <property name="jbosscache-cl-cache.jdbc.node.column" value="node" /> <property name="jbosscache-cl-cache.jdbc.node.type" value="auto"/> <property name="jbosscache-cl-cache.jdbc.parent.column" value="parent" /> <property name="jbosscache-cl-cache.jdbc.datasource" value="jdbcjcr" /> </properties> </lock-manager> T he jgroups-configuration has been moved to a separate configuration file (udpmux.xml, shown below). In this case the udp-mux.xml is a common configuration for all JGroup components (QueryHandler, cache, LockManager), but this is not a requirement of the configuration method. T he jbosscache-cl-cache.jdbc.fqn.column and jbosscache-cl-cache.jdbc.node.type parameters are not explicitly defined as cache.jdbc.fqn.type and cache.jdbc.node.type are defined in the JBoss Cache configuration. Refer to T able 17.2, Data T ypes in Different Databases for information about setting these parameters or set them as AUTO and the data type will by detected automatically. udp-m ux.xm l: 232

236 Chapter 17. exo JCR <protocol_stacks> <stack name="jcr.stack"> <config> <UDP mcast_addr=" " mcast_port="45588" tos="8" ucast_recv_buf_size=" " ucast_send_buf_size="640000" mcast_recv_buf_size=" " mcast_send_buf_size="640000" loopback="false" discard_incompatible_packets="true" max_bundle_size="64000" max_bundle_timeout="30" use_incoming_packet_handler="true" ip_ttl="2" enable_bundling="true" enable_diagnostics="true" thread_naming_pattern="cl" use_concurrent_stack="true" thread_pool.enabled="true" thread_pool.min_threads="2" thread_pool.max_threads="8" thread_pool.keep_alive_time="5000" thread_pool.queue_enabled="true" thread_pool.queue_max_size="1000" thread_pool.rejection_policy="discard" oob_thread_pool.enabled="true" oob_thread_pool.min_threads="1" oob_thread_pool.max_threads="8" oob_thread_pool.keep_alive_time="5000" oob_thread_pool.queue_enabled="false" oob_thread_pool.queue_max_size="100" oob_thread_pool.rejection_policy="run" /> <PING timeout="2000" num_initial_members="3" /> <MERGE2 max_interval="30000" min_interval="10000" /> <FD_SOCK /> <FD timeout="10000" max_tries="5" shun="true" /> <VERIFY_SUSPECT timeout="1500" /> <BARRIER /> <pbcast.nakack use_stats_for_retransmission="false" exponential_backoff="150" use_mcast_xmit="true" gc_lag="0" retransmit_timeout="50,300,600,1200" discard_delivered_msgs="true" /> <UNICAST timeout="300,600,1200" /> <pbcast.stable stability_delay="1000" desired_avg_gossip="50000" max_bytes=" " /> <VIEW_SYNC avg_send_interval="60000" /> <pbcast.gms print_local_addr="true" join_timeout="3000" shun="false" view_bundling="true" /> <FC max_credits="500000" min_threshold="0.20" /> <FRAG2 frag_size="60000" /> <!--pbcast.streaming_state_transfer /--> <pbcast.state_transfer /> <!-- pbcast.flush /--> </config> </stack> </protocol_stacks> QueryHandler configuration Indexing content in a cluster can be problematic as indexes cannot be replicated across nodes. Data present and indexed on one node will not be indexed if it is replicated to another. T his problem can be overcome with the use of a coordinator-node. A coordinator-node can maintain a Lucene index of the data on a cluster. T he coordinator-node is chosen automatically, so there is no need for any special configuration. Other nodes in the cluster deliver indexing request messages to JBoss Cache. T he coordinator 233

237 Red Hat JBoss Portal 5.1 Reference Guide retrieves those messages and updates the index accordingly. Searching data on a cluster can be likewise problematic, as search engines are unable to work with the index/coordinator model proposed above. T herefore each node in the cluster must be configured to access the Lucene index from a shared directory. However the coordinator reserves the ability to edit that index. Regardless of whether they are running in a clustered environment or not, Indexers do not writes changes to the file system Lucene index immediately. T he data is written to a volatile index first. If (or when) the volatile index size reaches or exceeds 1 Mb it is flushed to the shared file system index. Volatile indexes can also be flushed after a given time. The volatile index time out is configured with the "max-volatile-time" parameter. Refer to Section 17.5, Search Configuration for more information Configuration Common requirements T he following requirements must be met to run a search engine in clustered environment: 1. A shared directory for storing the Lucene index (an NFS mounted directory, for example); 2. A JBoss Cache changes filter configured as org.exoplatform.services.jcr.impl.core.query.jbosscache.jbosscacheindexchanges Filter: Note T his filter ignores changes on non-coordinator nodes and indexes changes on the coordinator node. 3. A correctly configured instance of JBoss Cache; Query-handler configuration In gatein.ear/02portal.war/web-inf/conf/jcr/repository-configuration.xm l query handlers are already configured for the packaged workspaces such as: 234

238 Chapter 17. exo JCR <query-handler class="org.exoplatform.services.jcr.impl.core.query.lucene.searchindex"> <properties> <property name="index-dir" value="${gatein.jcr.index.data.dir}/system${container.name.suffix}"/> <property name="changesfilter-class" value="${gatein.jcr.index.changefilterclass}" /> <property name="jbosscache-configuration" value="${gatein.jcr.index.cache.config}" /> <property name="jgroups-configuration" value="${gatein.jcr.jgroups.config}" /> <property name="jgroups-multiplexer-stack" value="true" /> <property name="jbosscache-cluster-name" value="jcrindexer- ${container.name.suffix}-system" /> <property name="max-volatile-time" value="60" /> </properties> </query-handler> The index-dir property is the path to the index directory. Where ${gatein.jcr.index.data.dir} is obtained from the file configuration.properties as explained in the installation guide and ${container.nam e.suffix} is a dynamic value based on the name of the current portal context. T he jbosscache-configuration property is the configuration template for all query-handlers in the repository T he jgroups-configuration property is the configuration template for all components (search, cache, locks). When the jgroups-multiplexer-stack property is set to true (and appropriate jgroupsconfiguration parameters are set) then Multiplexing stack is enabled in JBoss Cache. T he jbosscache-cluster-name property is the cluster name. T his name must be unique. T he max-volatile-time property controls the time-out period between volatile index flushes. JBoss Cache template configuration Below is an example JBoss Cache template configuration file for the query handler used by the shippedin workspaces. 235

239 Red Hat JBoss Portal 5.1 Reference Guide <?xml version="1.0" encoding="utf-8"?> <jbosscache xmlns:xsi=" xmlns="urn:jboss:jbosscache-core:config:3.1"> <locking uselockstriping="false" concurrencylevel="64" lockparentforchildinsertremove="false" lockacquisitiontimeout="20000" /> <!-- Configure the TransactionManager --> <transaction transactionmanagerlookupclass="org.jboss.cache.transaction.jbossstandalonejtamanagerl ookup" /> <clustering mode="replication" clustername="${jbosscache-cluster-name}"> <stateretrieval timeout="20000" fetchinmemorystate="false" /> <jgroupsconfig multiplexerstack="jcr.stack" /> <sync /> </clustering> <!-- Eviction configuration --> <eviction wakeupinterval="5000"> <default algorithmclass="org.jboss.cache.eviction.fifoalgorithm" eventqueuesize=" "> <property name="maxnodes" value="5000" /> <property name="mintimetolive" value="20000" /> </default> </eviction> </jbosscache> JBossTransactionsService Introduction exo JCR uses the JBoss T ransaction Service (JBossT S) JT A implementation via exo container dependency Configuration T imeout configuration can be done in: gatein.ear/02portal.war/web- INF/conf/com m on/com m on-configuration.xm l <component> <key>org.exoplatform.services.transaction.transactionservice</key> <type>org.exoplatform.services.transaction.jbosscache.jbosstransactionsservice</typ e> <init-params> <value-param> <name>timeout</name> <value>300</value> </value-param> </init-params> </component> timeout - XA transaction timeout in seconds 236

240 Revision History Revision History Revision Rüdiger Landmann Rebuild with publican Revision Fri Aug Jared Morgan Updated the Product Name to reflect the new name grouping for the product. No update was made to details in the guide. Revision T hu Aug Scott Mumford Prep for release. Revision T ue Aug Scott Mumford JBEPP-894: Updated 'Enable SSO' section. 237