JSR 168 portlets in IBM WebSphere Portal

1. Session Number: D19 JSR 168 portlets in IBM WebSphere Portal Oliver Koeth (okoeth@de.ibm.com)

2. Agenda • JSR 168 overview • Model and goals of the specification • Support for two portlet APIs in WebSphere portal • JSR 168 content • Important new API features of JSR 168 • Best practices + outlook • IBM extensions for JSR portlets • Features of the portal framework • Additional APIs for portlet functionality • Additional APIs for better integration of portlets + portal • Contrasting IBM and JSR API features • Resources

3. Objectives • After this session you should… • know what can you achieve with JSR portlets in WebSphere Portal: • know which concepts and features are supported by the JSR 168 standard and what is not part of the standard • be able to make good use of portlet-specific programming concepts • know additional non-standard features WebSphere Portal provide for portlet programming and what they are good for • understand what the transition from IBM to JSR portlets means

4. JSR 168 Overview The Java Portlet Specification v1.0

5. JSR 168 Goals • Portability of portlets between portal implementations • Simple programming model, aligned with J2EE and other Java technologies • Aligned with WebServices for Remote Portlets (WSRP) Result: The “Java Portlet Specification 1.0” • A standard that describes how a portal interacts with Java portlets • Portlet API and deployment unit (portlet WAR file) • It is not a goal of JSR 168 to define a complete standard for portal implementations • leave as much freedom for portal vendors as possible • Not part of the standard: • Aggregation of portlets into pages, layout management • Portal organization and navigation, selection of portlets • Page personalization and configuration engines • Portal administration and configuration, access control…

6. Navigation etc. A B C Scope of JSR 168 JSR 168 scope Portlet A Portal Client Portlet C Portlet B Portal Page

7. The JSR 168 model revisited • JSR 168 is based on a strict separation between portal and portlets • Needs to accommodate many portal vendors coming from different angles • Fits well with a remote portlet setup where portal and portlet are running in different JVMs (like the WSRP standard) • Fits well with a „building bricks“ approach that wants to integrate ready-made components → Idea of a „portlet marketplace“ • Fits well a with „workplace“ approach, where many independent components are combined in a presentation environment (desktop metaphor) • Customer requirements often dictate a solution where portal and portlets are tied together more closely • Portlets should interact with each other • Portlets should influence portal navigation and vice versa • Portal needs to pass more information to the portlets than defined by the spec • JSR 168 does not cover such requirements – but WebSphere Portal provides additional functions to address them

8. Portlet APIs in WebSphere Portal v1.1 v4.1 v5.0.2 v5.1.0.3 (today) • The IBM Portlet API: since version 4.1 • IBM Portlets are servlets, APIs extend the servlet APIs • Many new features were added over time • Planned to be deprecated in the future • Will still be supported for at least two major releases after deprecation • The Java Portlet API (JSR 168): since version 5.0.2 • Fully spec-compliant implementation • IBM extensions for areas that are not covered by the spec • This is the future programming model for portlets • New features will target this API only Jetspeed API IBM Portlet API Java Portlet API

9. Supporting two Portlet APIs • Since 5.0.2, WebSphere Portal supports two portlet containers • “IBM Portlet API” and “Java Portlet API” • Coexistence of portlet types • Portlets of both types can be on the same page • Transparent to the users of the portal • Same deployment and administration UI for both portlet types • Communication between IBM and JSR portlets is not well supported • For new projects, use the JSR 168 API if possible • Some features are still supported only for IBM portlets; use the IBM API if you really need them • You don’t need to migrate your IBM portlets right away • The IBM Portlet API will be supported for several releases to go • More migration tooling may become available over the next releases • Migration of configuration data (portlet data) is not yet supported

10. Content of the Java Portlet Specification A new way to write web components

11. What makes programming portlets special • Portlets are web components and have a lot in common with servlets • A lot of the concepts (like sessions, JSP include etc.) similar for servlets and portlets • This section focuses on what is special for JSR portlets • Some of these concepts are also different from the IBM portlet API • IBM portlet API was a direct extension of the servlet API

12. Request processing phases • Stand-alone webapps are in complete control – portlets have to live in a shared environment • Coordination requires a refined processing model with two phases • Action Request (“processing phase”) processAction (ActionRequest, ActionResponse) • Invoked only when the URL is an action targeted to the portlet, • Render Request (“render phase”) render (RenderRequest, RenderResponse) • Invoked whenever a page with the portlet is displayed (even if user interacts with another portlet on the page) • Produces output to create the portal page • IBM portlets have a distinction between events and rendering too, but the APIs do not make that very explicit

13. Typical Portal Request Portlets A B C User Portal Action on B A processAction B C render These requests may be done in parallel or skipped (caching!) render render A’ B’ C Outside of the scope of the Portlet specification Scope of the Portlet specification

14. Distinction between phases is important • Action phase does the processing • Set session attributes or render parameters, write to the backend • Example: processing an input form should be done in the action phase • Render phase generates output • Assumption: calling render two times with no action inbetween generates the same output  allows caching and parallelization • Portlets that display different output for the first and subsequent render requests are “not well behaved”!

15. Request attributes • Visibility is governed by the spec and different from IBM portlets • Attributes of the portal request are not visible • JSR portlets cannot transfer request attributes from action to render phase • Restrictions make sense when you think of remote portlets • If you really need a dirty trick for attribute passing • The attribute namespaces “java.” and “javax.” directly access the underlying servlet request (as defined by the spec) • You can exploit that e.g. to pass information from theme to portlets • Of course, this only works for local portlets that share the same portal request • The normal communication method for portlets is property broker (see later)

16. Render parameters • Navigational state • For every render call, portal keeps resending the last set of parameters  allow the portlet to store interaction state • Portal is responsible for tracking render parameters • Intention is that render parameters are kept in the URL • Allows to keep interaction state without a session • Render parameters are an explicit API concept, because URL generation is not controlled by the portlet (parameters must be put into every portal URL) • Using render parameters provides enhanced usability • Better use of the browser back button, avoids problems where the session state and the displayed view get out of sync • Bookmarking: internal state of the portlet is part of the bookmark • Portal applies similar techniques for storing portlet mode, window state and other information

17. Bookmark example • Fictous sample: JSR document viewer portlet that displays technotes • Displayed technote is tracked as a render parameter • You can send the URL to a friend and she will see the same technote in the maximized viewer http:/sample.ibm.com/../portlet6/state=max/param.article=12345/… URL stores information that the technote viewer is maximized and that technote 12345 is displayed In reality, of course, URLs are encoded more efficiently

18. Portlet URLs • Portlets need to use API calls to create URLs to themselves • ActionURL – processAction method of portlet is called (state changes) • RenderURL – new render parameters are set, only render is called • URLs for portlets are always generated programmatically • Do not call encodeURL; the implementation takes care of that • Never make any assumptions about the URL format! • URLs may only be tokens that are rewritten later • Caching and remote portlets require this • You can only expect valid URLs in the eventual output, but not in your code • Never do string manipulation (like adding query parameters) on Portlet URLs

19. Portlet URLs • JSR 168 API allows switching between http and https (optional feature) • PortletURL.setSecure(true/false) • Supported since WP 5.1.0.1, if portal is configured appropriately • FORM GET with portlet URLs is ok since WP 5.1 • Portal does not use query strings in its own URLs • But the spec does not guarantee that • Resource URLs (Images etc.) are not portlet URLs • Constructed as strings, but must call encodeURL • No relative URLs allowed • response.encodeURL(request.getContextPath() + “/img/wombat.gif”)

20. Configuration levels in IBM and JSR portlets

21. Some best practices (general) • Separate processing and rendering • Respect action and render phase, use MVC, use JSPs for rendering • Use render parameters where appropriate • Session is not the only way to keep information across requests • Be robust against invalid parameters • Consider outdated bookmarks etc. • Implement edit and help mode • Portal knows what the portlet is doing, can apply access control or enter the mode directly • Use portlet preferences for storing configuration data • Avoid additional property files • Preferences can be modified during runtime, protected by portal access control • Can easily make use of WP multi-layer configuration feature (user/admin)

22. Some best practices (in WebSphere portal) • Specify a unique ID for your portlet in the deployment descriptor • optional “id” attribute for the main <portlet-application> tag • Helps for upgrading and migration • Make judicious use of IBM extensions • Make use of IBM extensions if they are available during runtime • If possible, avoid hard dependencies on IBM extensions – write your portlets so that they can still run on any JSR 168-compliant portal • Don’t spend time to re-invent IBM extensions (like portlet communication etc.) • Don’t rely on anything not defined by the spec or by WP documentation • No calls to non-public IBM code; • Do not depend on behavior that is not explicitly guaranteed • These things may break when you apply the portal fixpack that is absolutely needed to solve your urgent production problem (and when the only developer who knows is not around) • If you think you really need to rely on internals to solve your use case, contact portal support to obtain a “Document of Understanding” (DOU)

23. Outlook on JSR 286 – Java Portlet API 2.0 • A new Java Specification Request that defines the next version of the API • Another full discussion / draft / approval cycle • New reference implementation and compliance testkit • Lead by IBM; all major companies dealing with Java portals are involved • Current ideas for the spec content • Inter-portlet communication as defined in WSRP 2.0 • Public render parameters as defined in WSRP 2.0 • J2EE 1.4 support • Portlet filters (intercept API flow between portal and portlets) • Enhanced caching support and portlet tag library • Alignment with WSRP versions 2.0 and with JSF • Proposed schedule • JSR accepted on Dec 12, 2005 • early public draft beginning of 2006, public draft by mid 2006 • final version by end of 2006.

24. IBM Extensions for JSR Portlets

25. Extensions of the WP container • Parallel portlet rendering (WP 5.0.2) • Improves performance if portlets have latencies (network access) • Possible through tight coupling of portlet container to application server • Fragment caching (WP 5.0.2) • Caches output of individual portlets on the server • Caching definitions in the DD must be set appropriately • Requires that the portlet does not change state during rendering • Full-page caching (WP 5.1) • Pages can be cached on the proxy • Portal can be as fast as a static website • Requires extended caching information supplied by the portlet

26. Programming extensions • Property broker (WP 5.1) • Information exchange between JSR portlets • Output information from one portlet action (like request or session attributes) can trigger actions on other portlets • Output of the source action can be passed as input to the target actions • Information flow is governed by „wires“ between the portlets. These wires can be dynamically configured by portal administrators • Easy to program • Information always flows in and out of portlet actions; you can re-use the same action handling as for GUI interaction • You need to use common data types (Strings are often sufficient ) • You need to declare how information („properties“) flows in and out of actions; this is done declaratively in a WSDL file • No dependency on new APIs! • Portal detects how input and output properties can be matched and lets you define appropriate wires

27. Property Broker – Shipping example Customer info portlet Order list portlet Wire connectssource andtarget for order ID; Selecting an order pushesorder ID Orderdetail portlet Cascaded wiring: Order detail pushes the tracking ID to the tracking portlet Order ID can be entered manually; order ID from wiretriggers the same code!

28. Programming extensions • Multiple configuration levels for portlets • Configuration seen by the portlets is a combination of multiple configuration sources • Administrator can define global values, users can personalize some values • Governed by portal access control • Handling is mostly transparent to the portlet code, logic is triggered by additional portlet modes: • “config” mode: set administrator configuration (affects all pages) • other modes (esp. “edit”): set user configuration (affects only a single user) • If programmed properly, the administrator can decide at deployment time which configuration values may be personalized and which may not

29. Programming extensions • Credential vault (WP 5.0.2) • Portlets often need authentication info to access backed system  common API that allows portlets to manage this information • Helps for realizing a SSO experience while keeping sensitive data under control • CC/PP support (WP 5.1.0.1) • Allows portlets to detect different devices (different types of non-HTML devices like WAP phones, but also different browser types) and produce appropriate markup • Device profile available as request attribute • Puma SPI (WP 5.1.0.1) for extended User/Group functions • JSR 168 covers only retrieval of user attributes • Puma SPI allows to query the group structure and modify user attributes and group assignment

30. Programming extensions • Integration with the portal navigation (WP 5.1.0.1) • Create links to other portlets and pages • Pass parameters to portlets along with those links • Set portlet mode and window state of target portlets • Extensive, feature-rich API in WP 5.1.0.1 (state API) • Model SPI (WP 5.1.0.1) • Allows to query the portal page hierarchy • Useful for dynamic navigation (“Sitemap”) and other customer requirements that dictate a tight integration between portlets and the portal

31. Example – default UI in WebSphere Portal 5.1 • Functions like “edit this page” or “edit user profile” are realized as portlets on special hidden pages • Other places in the portal (theme and portlets) link to these pages and pass information to the portlets • Available as public APIs – custom portal setups can do similar things!

32. Dynamic User Interfaces (WP 5.1.0.1) • Portlets can launch dynamic pages in the portal UI • Pages live in the session (not in the portal DB) and are only visible to the current user • Pages are created as copies of a persistent “template page” • Pages are closed by the user or programmatically • API allows to add portlets to the page and remove them • API allows to set configuration for the portlets • Useful for programming task-oriented applications (“Process portal”) • Multiple tasks can be spawned on separate pages • User can switch between the tasks  temporarily leave the page and later return to the same task context • User does not lose entered data if interrupted by a higher-priority task • Spawned tasks remain visible until they are completed and the page is closed • Generic API, can also be applied to other use cases • A bit similar to the “tabbed browsing” concept in web browsers

33. Example – Travel Booking Launch portlet displays links to start the booking processClicking on a link opens a dynamic page

34. Example – Travel Booking As the user progresses through filling out the form, the flight booking portlet dynamically shows other portlets on its dynamic page.In this case, a specialized portlet is shown for entering departure/ arrival dates Initially, the dynamic page contains the flight booking portlet

35. IBM vs. JSR portlets – reprise • A lot of the differences between the portlet APIs are merely syntactical • like using PortletPreferences instead of PortletData/Settings • Some notable differences • Render parameters, application scope for sessions • Stricter separation from portal issues, e.g. request parameters or attributes • JSR portlet API builds on our experience with the IBM portlet API • Simpler, more explicit APIs • API behavior is now explicitly specified (Not “works as coded”) • Avoid some performance pitfalls (like action objects in the IBM API) • Some IBM portlet features have been added as IBM extension • and maybe more will be, depending on demand • Hacks in IBM portlet implementations don’t translate easily to JSR • Most of the dirty tricks for IBM portlets (like accessing the portal request) do have an equivalent, but try to avoid them

36. Features currently not supported for JSR Portlets • Click-2-Action – hot on the list for future support • Dynamic titles (optional part of JSR168 spec) • Not supported out of the box – JSR portlet API is not compatible with existing portal aggregation tags • Next release will allow a work-around to support dynamic titles; requires changes to skin JSPs and needs DHTML • Solo state – on the list for future support • Portlet filters – waiting for standardization in the next portlet specification • Portlet menus • May be superseded by more general plug-in mechanisms for the portal navigation • PortletSessionListener interface • Same functionality can be achieved with ordinary HTTP session listeners • some more XXXListener interfaces • Currently not considered as important features

37. Conclusion

38. Summary – Revisiting the objectives • Know which concepts and features are supported by the JSR 168 standard and what is not part of the standard • portlets vs. portal front-end • request processing phases • Make good use of portlet-specific programming concepts • render parameters, portlet modes, URL handling • Know additional non-standard features WebSphere Portal provide for portlet programming and what they are good for • programming extensions for interacting with the portal environment • features that you need to create a tightly coupled portal solution • Understand what the transition from IBM to JSR portlets means • differences are not too significant • use JSR portlets for new projects – get all the new features • think carefully when migrating existing solutions – you have plenty of time

39. Resources • JSR 168 specification (Java Portlet API 1.0) • For IBMers http://w3.hursley.ibm.com/java/jim/jsrtechnology/ jsr168portletspecification/index.html (requires approval) • For non-IBMers: http://www.jcp.org/en/jsr/detail?id=168 • JSR 286 progress (Java Portlet API 2.0) • http://www.jcp.org/en/jsr/detail?id=286 • Product information • http://www-306.ibm.com/software/genservers/portal/library • DeveloperWorks • http://www-128.ibm.com/developerworks/websphere/zones/portal/ • Best practices article:www-128.ibm.com/developerworks/websphere/library/techarticles/ 0403_hepper/0403_hepper.html • IBM to JSR API migration:http://www-128.ibm.com/developerworks/websphere/library/techarticles/ 0412_paeffgen/0412_paeffgen.html

40. Resources • Public newsgroup • ibm.software.websphere.portal-server • IBM internal portal developer newsgroup • forums.software.websphere.portal-server • Weekly portal practitioner confcall, Thu 11am ESThosted by Michael Dockter

41. Backup

42. Portlet modes and window states • Portlet mode declares what the portlet does • Normal operation: view • Customizing user configuration: edit • Display help information: help • More optional modes (config, print) • Window state declares how much space the portlet should use for its output • normal, maximized, minimized • Mode and state changes can either be requested by the portlet or be triggered by the portal • You don‘t need to program a „help“ or „edit“ button, the portal does that • Portal may restrict the modes and states a portlet can use • E.g. “only administrators can enter the edit mode of the mail portlet that allows to modify the mailserver settings” • Realized by access control features in WebSphere Portal

43. Portlet Preferences • Provide persistent configuration to the portlet • initialized in the deployment descriptor • can be changed by the portlet (typically in „edit“ mode) • allow to customize appearance of the same portlet in different contexts/on different pages (e.g. Notes mailbox and POP3 mailbox) • Writeable in action phase, read-only in render phase • Preferences can be locked for users („read-only“) • Only the administrator can change such preferences (optional feature, supported by WebSphere Portal) • Simple persistence API for portlets (key-value pairs) • If you need a more sophisticated data model, you can still use JDBC or other persistence mechanisms • Special features in WebSphere Portal (more on that later) • Multiple layers, write access protected by portal access control