Red Hat JBoss Portal 6.2

Development Guide

For use with Red Hat JBoss Portal 6.2

Jared Morgan

Red Hat, Ltd. Customer Content Services

Aakanksha Singh

Red Hat, Ltd. Customer Content Services

Legal Notice

Copyright © 2015 Red Hat, Inc..
This 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.
The 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.


The Development Guide is intended for those developing portlet applications and gadgets for the product, and outlines options and strategies for successful deployment.
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. Getting Help and Giving Feedback
2.1. Do You Need Help?
2.2. We Need Feedback
I. Architectural and Design Choices
1. Architectural Choices
1.1. Identity server
1.2. Storage
1.3. Cluster
1.4. SSO
1.4.1. Summary
2. Design Choices
2.1. Dashboards
2.2. JCR Index Replication in a Cluster Setup
2.2.1. JCR Index Replication in a Cluster Setup
2.2.2. Standalone Index
2.2.3. Local Index
2.2.4. Shared Index
II. Portal API
3. PortalRequest and Portal
4. Site
4.1. Retrieving Sites
4.2. Creating a Site
4.2.1. Setting Attributes for a Site
4.2.2. Setting permissions for a site
4.3. Deleting a Site
5. Navigation
5.1. Retrieving Navigation Nodes
5.1.1. NodeVisitor
5.1.2. Filtering Navigation Nodes
5.2. Creating a Navigation Node
5.2.1. Navigation Node Visibility
5.2.2. Localization
5.3. Deleting a Navigation Node
5.4. Moving a Navigation Node
6. Page
6.1. Retrieving Pages
6.2. Creating a Page
6.2.1. Setting Permissions for a Page
6.3. Page Composition
6.4. Deleting a Page
6.5. Application
7. OAuth Provider API
7.1. Retrieve an Instance of OAuthProvider
7.2. OAuthProvider Operations
7.3. Access to Provider-specific Operations
8.1. Overview
8.1.1. Base URL
8.1.2. Authentication
8.1.3. Content Type
8.1.4. Localization
8.2. Resources
8.2.1. Sites
8.2.2. Pages
8.2.3. Navigation
8.2.4. Working with Templates
9. Organization API
9.1. Organization API
10. Accessing User Profile
III. Portal Development
11. Portal Life-cycle
11.1. Application Server Start and Stop
11.1.1. Advanced WCI Registration
11.2. The Command Servlet
12. Portal Containers
13. Skinning the Portal
13.1. Skin Components
13.2. Skin Selection
13.2.1. Skin Selection Through the User Interface
13.2.2. Setting the Default Skin within the Configuration Files
13.3. Skins in Page Markups
13.4. The Skin Service
13.4.1. Skin configuration
13.4.2. Resource Request Filter
13.5. The Default Skin
13.6. Creating New Skins
13.6.1. Creating New Skins
13.6.2. Creating a New Portal Skin
13.6.3. Creating a New Window Style
13.6.4. How to Create New Portlet Skins
13.6.5. Create New Portlet Specification CSS Classes
13.7. Tips and Tricks
13.7.1. CSS Hosted on CDN
13.7.2. Easier CSS Debugging
13.7.3. Some CSS Techniques
14. Portal Extension
14.1. How the Shadowing Mechanism Works
14.2. Custom Groovy Template for a Portlet
14.3. Custom Skin for a Portlet
14.3.1. gatein-resources.xml
14.3.2. CSS and Images
14.4. Custom Navigation and Pages
14.4.1. portal-configuration.xml
14.5. Navigation Node Types
14.6. Internationalization of Navigation Nodes
14.7. Custom Internationalization Resource Bundles
14.8. Custom Sign-in Page
15. Visual Identity
16. Data Import Strategy
16.1. Import Strategy Overview
16.1.1. Portal Configuration
16.1.2. Page Data
16.1.3. Navigation Data
17. Right To Left (RTL) Framework
17.1. Groovy templates
17.2. Stylesheet
17.3. Images
17.4. Client Side JavaScript
18. XML Resources Bundles
18.1. XML format
18.2. Portal Support
19. Navigation Controller
19.1. Controller Configuration (controller.xml)
19.1.1. Rendering
IV. Gadget Development
20. Gadgets in Portal
20.1. Sources to Develop Gadgets
21. Portlet Development Resources
21.1. JSR-168 and JSR-286 overview
21.1.1. Portal Pages
21.1.2. Rendering Modes
21.1.3. Window States
21.2. Tutorials
21.2.1. Deploying your first portlet
21.2.2. JavaServer Pages Portlet Example
22. Portlet Development
22.1. Starting a Portlet Project
22.1.1. The Bill of Materials (BOM) Concept
22.1.2. Using the BOM
22.2. Building and Deploying Portlets
22.3. Standard Portlet Development (JSR-286)
22.3.1. Java Configuration
22.3.2. portlet.xml
22.3.3. web.xml
22.3.4. Building and Deploying Portlets
23. Basic JSF Portlet Development
23.1. Example Code
23.1.1. pom.xml
23.1.2. JSF Template Files
23.1.3. Java Beans
23.1.4. portlet.xml
23.1.5. web.xml
23.1.6. Custom CSS
23.1.7. Internationalization
23.2. Further Steps
23.3. See also
24. JSF Portlet Development with RichFaces
24.1. Example Code
24.1.1. pom.xml
24.1.2. JSF Template Files
24.1.3. Java Beans
24.1.4. portlet.xml
24.1.5. web.xml
24.1.6. Custom CSS
24.1.7. Internationalization
24.2. Further Steps
24.3. See also
25. Portlets with JSF and CDI
26. CDI Portlet Development
26.1. GenericPortlet and Portlet Filter Injection
26.2. Portlet CDI Scopes
26.2.1. @PortletLifecycleScoped
26.2.2. @PortletRedisplayScoped
27. Portlet Filter
27.1. Global Metadata Elements
27.1.1. Global Metadata Elements
27.1.2. Configuring a Portlet Filter
28. Portlet Bridge
28.1. JBoss Portlet Bridge
28.2. Portlet application
28.3. Extensions
28.4. Examples
28.5. Render Policy Parameters
28.6. Facelets Configuration
28.7. JSP-only Configuration
28.8. RichFaces Local and Remote Portlet Support
28.9. Sending and Receiving Events
28.10. Sending Events
28.11. Receiving Events
28.12. Public Render Parameters
28.13. Saving Bridge Request Scope after Render complete
28.14. PRP portlet configuration
28.15. Application configuration
28.16. Portlet Session
28.17. Resource serving
28.18. Serving JSF Resources in a Portlet
28.19. Expression Language Reference
28.20. Expression Language Configuration
28.21. Developing Portlets with the Bridge
28.21.1. Implementing Portlet Bridge
28.21.2. Declaring Artifact Dependencies
28.21.3. Declaring Depchain Dependencies
28.21.4. Deploying Portlet Bridge Portlets
28.21.5. Disable Automatic Portlet Bridge Injection
28.21.6. Supported Portlet Tags
28.21.7. Excluding Attributes from the Bridge Request Scope
28.21.8. Prevent Resources Being Added to Portal Page Head
28.21.9. JSF Facelet View
28.21.10. Error Handling
28.21.11. Switching Portlet Modes
28.21.12. Navigating to a mode's last viewId
28.21.13. Using Wildcards to Identify the Rule Target
28.21.14. Clearing the View History when Changing Portlet Modes
28.21.15. Communication Between Portlets
28.21.16. Storing Components in PortletSession.APPLICATION_SCOPE
28.21.17. Using the PortletSession
28.21.18. Linking to a Facelets page within the Same Portlet
28.21.19. Redirecting to an External Page or Resource
28.21.20. Using Provided EL Variables
29. Navigation Portlet Using the Public API
29.1. Example Code
29.1.1. Required Java Classes
29.1.2. Required JSP
29.1.3. Required JavaScript
29.1.4. Further Steps
29.2. See also
30. Using Data from Social Networks in Portlets
30.1. Social Portlets Example Code
30.1.1. Prerequisites
30.2. Retrieving the Access Token
30.3. Facebook
30.4. Google+
30.5. Twitter
30.6. Configuration and Deployment Descriptors
30.7. Further Steps
31. Spring Framework Portlet Development
V. JavaScript Development
32. JavaScript Modularity
32.1. JavaScript Modules
32.2. Introduction to Modules
32.3. Script Support
33. JavaScript in JBoss Portal
33.1. Declaring a Module
33.2. Translation to the AMD System
33.3. Producing Dependencies
34. Native AMD Modules
34.1. Difference in Native AMD and Portal Modules
34.2. Native AMD Modules hosted on CDN
34.3. Mapping path entries for AMD Modules
34.4. Fallback Paths
34.5. Example to Ensure Portal wide Consistency in mapping paths
35. Module Scopes
35.1. Shared Scope
35.2. Portal Scope
35.3. Portlet Scope
36. Portlet Dynamic Module
37. Aliases
38. Custom Adapters
39. Module Resources
40. Load Groups
41. Localization
42. Non-AMD Scripts
VI. JavaScript Code Examples
43. Module Code Examples
43.1. Declare a Module
43.2. Declare an AMD Module
43.3. Use jQuery Module
43.4. Use a Custom jQuery Version
43.5. jQuery Plug-ins
43.6. Override Native AMD Module Dependency
43.7. CommonJS modules
43.8. Mustache.js module
43.9. Resource loading with Text.js
44. Script Code Examples
44.1. Accessing a module from a script
44.2. Exposing jQuery Version Globally
44.3. Defining a custom global jQuery
44.4. Using a Global jQuery plugin
VII. Advanced Development Concepts
A. The eXo Kernel
A.1. The eXo Kernel
A.2. Kernel Configuration Namespace
A.3. Configuration Retrieval
A.4. PortalContainer Advanced Concepts
A.4.1. Add new configuration files from a WAR file
A.4.2. Creating PortalContainers from a WAR File
A.4.3. Defining a PortalContainer with its dependencies and its settings
A.4.4. PortalContainer Settings
A.4.5. Dynamically Changing a PortalContainerDefinition
A.4.6. Dynamically Disable a Portal Container
A.5. Runtime Configuration Profiles
A.6. Component request life cycle
A.6.1. Component request life cycle contract
A.6.2. Request life cycle
A.7. Configuring Services
A.7.1. Configuration syntax
A.8. Specific Services
A.8.1. ListenerService
A.8.2. Job Scheduler
A.8.3. The data source provider
A.9. Configuring a portal container
A.10. System property configuration
A.10.1. Properties <init-param>
A.10.2. Properties URL <init-param>
A.10.3. System Property configuration of the properties URL
A.10.4. Variable Syntaxes
A.11. The Extension Mechanism and Portal Extensions
A.11.1. Running Multiple Portals
A.12. Manageability
A.12.1. Introduction
A.12.2. Managed framework API
A.12.3. JMX Management View
A.12.4. Example
B. eXo JCR
B.1. Introduction and Support Scope
B.2. Concepts
B.2.1. Repository and Workspace
B.2.2. Items
B.2.3. The Data Model
B.2.4. Data Abstraction
B.3. eXo JCR Repository Service Components
B.3.1. Workspace Data Model
B.4. Template for JCR configuration file
B.4.1. Portal Configuration for JCR
B.5. Multi-language Support
B.5.1. Oracle
B.5.2. DB2
B.5.3. MySQL
B.5.4. PostgreSQL
B.6. Configuring Search
B.6.1. Global Search Index
B.6.2. Indexing Configuration
B.6.3. Advanced features
B.7. Configuring the JDBC Data Container
B.7.1. Introduction
B.7.2. Supported Databases
B.7.3. Configuring the database using SQL-script
B.7.4. Multilanguage support database configuration
B.7.5. Isolated-database Configuration
B.7.6. Multi-database Configuration
B.7.7. Single-database Configuration
B.7.8. Simple and Complex queries
B.7.9. Force Query Hints
B.7.10. Notes for Microsoft Windows Users
B.8. External Value Storages
B.8.1. Tree File Value Storage
B.8.2. Disabling Value Storage
B.9. Workspace Data Container
B.10. Configuring the Cluster
B.10.1. Launching Cluster
B.10.2. Requirements
B.11. Configuring JBoss Cache
B.11.1. Indexer lock manager and data container configuration
B.11.2. JGroups configuration
B.11.3. Sharing JBoss Cache instances
B.11.4. Shipped JBoss Cache configuration templates
B.12. LockManager
B.12.1. CacheableLockManagerImpl
B.12.2. JBoss Cache Configuration
B.12.3. Configuration of JBoss Cache for LockManager
B.12.4. LockManager Configuration Template
B.12.5. Creating udp-mux.xml
B.12.6. FQN type and node type in different Databases
B.12.7. Lock Migration
B.13. JCR Indexing
B.13.1. Standalone Index
B.13.2. Local Index
B.13.3. Shared Index
B.13.4. RSync-based Index
B.13.5. Query-handler configuration
B.13.6. Asynchronous Re-indexing
B.13.7. Lucene tuning
B.13.8. Searching Repository Content
B.13.9. Highlighting
B.13.10. SpellChecker
B.13.11. Similarity
B.14. Full Text Search And Affecting Settings
B.14.1. Lucene Analyzers
B.14.2. Property Indexing
B.14.3. Different Analyzers
B.15. WebDAV
B.15.1. WebDAV Configuration
B.15.2. WebDAV and JCR Actions
B.15.3. WebDAV Limitation on Windows
B.15.4. WebDAV Limitation for Microsoft Office 2010
B.16. FTP
B.17. Use External Backup Tool
B.17.1. Repository Suspending
B.17.2. Backup Considerations
B.17.3. Repository Resuming
B.18. eXo JCR statistics
B.18.1. Statistics on the Database Access Layer
B.18.2. Statistics on the JCR API Accesses
B.18.3. Statistics Manager
B.19. Checking Repository Integrity and Consistency
B.19.1. JMX-based consistency tool
B.20. JCR Performance Tuning Guide
B.20.1. Cluster configuration
B.20.2. JCR Clustered Performance
B.20.3. JBoss Enterprise Application Platform 6 Tuning
B.20.4. JCR Cache Tuning
B.20.5. Clustering Tuning
B.20.6. Declaring the Datasources in the Application Server
C. Quickstarts
C.1. Quickstarts
C.2. Quickstarts Downloads Page
C.3. JBoss Developer Studio or Eclipse with JBoss Tools
D. Revision History