The Bookmark Portlet Locator

Download BookmarkPortletLocator.war

Download  BookmarkPortletLocator.pdf


This WLS JEE Shared Library has been developed in the context of   a customer portal engagement that use WebLogic Portal 10.x (WLP).


Basically we needed a solution to address the recurring problem of plumbing into content html properties some content portal hyperlinks,

  • As plain standard http urls, not as server side scriptlets / custom tags;
  • Shortened, simplified and portable but yet interpretable by (any) wlp portal instance ‘s navigation context (more on this later);
  • The map of such friendly portal urls had also to be exposed to external clients ;

We than implemented a portal url pattern based on generic portlet instances’ bookmarks, instead of on pageLabels: any portlet instance (besides of its parent netuix control) can be administratively labelled via a specific portlet preference, and from that moment on, reachable via a simplified, shortened http url:


Secondly, more project-scoped, we had also to get an easy way to profile 3.rd party CMS items, when no VCR ‘s SPI were at disposal (in our case we dealt with Interwoven’s TeamSite, still lacking of a fully fledged VCR connector implementation: the only choice was bulk loading), using entities acknowledged by wlp’s UserInteraction API and Tools: those values had to be exposed from portal, retrieved and included in IW forms and then resubmitted to portal, as content item’s metadata.


This solution has not been –yet- tested in a production environment.

We did some internal performance tests using jrockit ‘s MC tools (basically to get an idea of latency gain in custom cache usage) that showed reassuring results (the overhead of url computing / decoding is in terms of milliseconds…….)

We lend to consider the solution – at this stage –more likely to be wlp code hacking than a real world solution, but yet hope that the underlying idea can be leveraged to develop a similar feature in future wlp releases (we do need it…..)

Following, see comparative results among tests with disabled / enabled url resolution caches



In our solution, those urls should also can carry / support a (unpredictable) number of further additional parameters (as querystring params), eventually parsed by the portlet instance’s jsp, to further parameterize –on user request basis - the behaviour of the target jsp portlet’s algorithms (more on this hint on next sections): in our case we needed to customize cm query logic with some external CMS item’s properties.

Another requisite we had to address (which is somehow out of scope for the Locator itself, but still useful set of methods) was also to define and expose (towards 3.rd party CMS), some WLP personalization entities used by WLP Framework and/or WLP UserInteraction personalization engines (i.e. we decided respectively to use streaming Portals / Desktops name-paths, or UserSegments’ rulesets names), so that personalization reasoning logic externally defined could work inside WLP User Interaction engines, even in absence of any VCR SPI implementation.

As said, we than ought to design –on Locator- some logic to

  • Intercept, parse and interpret back the friendly, shortened urls, and redirect user to the right portal’s page currently[1] embedding the specific portlet instance, and to forward it also any further CM-specific additional parameters eventually found in friendly url’s querystring.


  • Use portals’ p13n or PortalFrameworks API to apply any further personalization / interaction logic to the imported (=bulk loaded…..) CM items.

Last but not least, the solution should grant

  • Portability (i.e. moving the target portlet instance to a new portal definition, or promoting it to a different portal instance should not break the semantics and related interpretation of the friendly urls since they had previously loaded and stored into CMS provider…..), considered that no assumption should be done on any sync capabilities between both CM’s metadata repositories (WLP dbms repository and the external one): i.e. the friendly urls should work also when changing portal web context url, or book/pages/portlet instance graph from original.)


  • Simplicity: a solution really ready to plug-and-use (both dummy proof but at same time usable without a master degree in wlp / wls): it’s not a “convention over configuration” approach, just we try not to waste time on understanding the syntax of the nth custom xml based configuration file. ;-)
[1] The frendlyUrl-to-pageUrl resolution must be dynamic and based on a indirection entity (bookmark) not on portlet instance id, because portlet instance could reasonably get moved among different pages/desktops/portals in the interval the information is exposed and the item is bulkloaded back to portal…..

Architecture and Components

As said, the Locator consists in a WebLogic JEE Shared Library (PortletLocator.war)

As you link this library, you will find basically three kinds of components:

  • 2 web services (….yes, Nino was able to include web services in a web library, can you believe it?)
    • PortalStructureService and UserSegmentService

The interfaces that export wlp-related information towards external clients

  • 1 ServletFilter
    • The object that parse and interpret portlet instance’s “friendly” url


  • 1 Custom Control:
    • ExposureCoordinatorControl (we warmly hope that Beehive will survive next release of PortletLocator……) , which is the delegator of webservices’s methods, and also a useful interface to some specific computation logic eventually needed from wlp webapp
    • i.e. it can answer questions like: “which usersegment list is current user in?” or “which streaming portal path am currently in?”, etc


All the further supporting / helper / cache logic is packaged in a .jar in the WEB-INF/lib




Just proceed as a normal shared lib:

1) install the web library in your wlp server / cluster


1) then, add the standard library reference tags in weblogic.xml of your portal web app:









(or use a Deployment Plan)


3) Congratulations! You’re done.

Of course, in a DEV environment, you can include it in the WLS JEE Library list:



The library has a complete default configuration: if you don’t have special requirements, it’s all there. You can skip to Usage section.

If you really have to, you can still configure a bunch of parameters (read Usage section to understand the underlying semantics in there; for now just pick up the list):

We didn’t use any new, nth xml configuration file: to override the default configuration you just work on

  1. web.xml (context-params)
    1. exposure-scheme
      • this optional parameter is used to set the scheme used to generate the pageurl that the Locator computes before a portal redirect : i.e.
      • accepted values: http | https
    2. exposure-host
      • this optional parameter is used to set the hostname part of the pageurl that the Locator generates before a portal redirect : i.e.
      • accepted values: an ip address or a hostname
      • if this param is not set, the Locator retrieve it from:
        • wls frontend cluster value, OR
        • wls frontend server host value, OR
        • value returned from getServerName method invoked by Locator filter on current http request
    3. exposure-port
      • this optional parameter is used to set the port part of the pageUrl generated by Locator: needs to be set if specified “exposure-host”
      • accepted values: any valid tcp port
    4. exposure-log-enabled
      • this optional parameter is used to set the log of the Locator framework
      • log file defaults to PortletLocator.log and is placed on domain root folder (this behaviour can be overridden by a proper log configuration on weblogic.xml of referencing portal app –see below).
      • accepted values: true (default) OR false
    5. exposure-production-mode
      • accepted values: true OR false
      • this param defaults to domain’s current runtime mode (production vs. development) being retrieved straight from domain configuration itself.
      • IF explicitly set to false in a production environment, enables DEBUG trace level on log file (viceversa on prod configuration, debug level is disabled for performance reason
      • exposure-log-enabled param needs to be enabled and set to true.
    6. exposure-portal-servlet-mapping
      • anybody should have changed the /appmanager url pattern of wlp portal servlet, this parameter allows to configure PortletLocator accordingly about the new PortalServlet ‘s servlet url mapping.
      • defaults to /appmanager
      • accepts any string value
    7. exposure-portlet-preference-name
      • the preference name of the portlet preference that – on a portlet instance - identify the bookmark itself
      • defaults to: “bookmark”
      • accepted values: any string
    8. exposure-cache-enabled
      • accepted values: true (default) OR false
      • this parameter enables Locator’s url resolution caches: EXPOSURE_CACHE and EXPOSURE_CACHE_URL, administerable from Portal Admin Console
    9. exposure-redirect-request-enabled

      • accepted values: true (default) OR false

      • this parameter enables Locator to redirect  users to target portlet  via a http 302  status code send-redirect (when landing on target portlet, the browser address url is the portal one); choosing false enables servlet container internal forwarding mechanism (when landing on target portlet, the browser address url is the locator one)
    10. you can also modify url pattern value of Locator’s servlet filter
      • default: “portletlocator”
      • this values can be overridden by adding in web.xml of portalWebApp these lines:
      • i.e. .














       2  weblogic.xml











Defaults, the PortletLocator creates 2 new portal caches with 1h TTL:

  • EXPOSURE_CACHE with max entries 100
  • EXPOSURE_CACHE_URL with max Entries 500


Let’s distinguish Locator’s usage into 2 different context / use cases:

  • Implementation of portal friendly url,
  • External content item’s personalization

Friendly urls implementation

Phase 1 : create friendly urls

(WLP Portal side; role: PortalAdministrator; tool: PortalAdminTool)

  1. Configure your 1-n streaming portal(s), each with related desktops / books / etc
  2. For each portlet instance (among those eligible as friendly url” ‘s target, i.e. to CM display views),
    • Add a portlet instance.
    • Add a portlet preference named “bookmark” (this is default but can be customized), with a unique value [1]
    • i.e. : simple1
    • Add a preference description
    • i.e.: “upper left portlet, 3rd column, new articles annoncements….” Etc
[1] By now no control is made on bookmark’s preference value uniqueness: we didn’t find an efficient solution to automate this control on portal lifecycle stages (i.e. web app deployment time, new preference insertion, etc)



From this moment on, with PortletLocator deployed and configured, you can reach this portlet instance by composing this url on a browser:



When you hit a non existing bookmark, the filter send back a Http Error Code 436 (to let you customize error handling with a friendly page / error handler)

Phase 2 : exposition of portlet instances friendly url map to third party consumer

Navigate to Web Service ‘s PortalStructureService WSDL and test operation availablePortletsBookmark: an invocation returns the full map of bookmarked portlets: a list of following key/values

  • bookmark’s preference description
  • bookmark’s preference values associated with each bookmarked portlet

following an example of returned values:



Phase 3: inclusion of bookmark map into CM contribution tool

This key/value list can then be easily embedded in external CM contribution tool (in our case, into TeamSite’s forms) in the form of a combo box: the options key being the bookmark value, while the options value being the portlet instance description.

The redactor, when he needs to plumb an hyperlink on an html body of a cm item, can than select a bookmark’s value by selecting his description.

Note that any duplicated entry of bookmark_value / portlet instance description has to be handled manually with a fix in wlp’s portal admin tool.

Just store this picked value (the bookmark’s preference value) in a cm specific item property / metadata (i.e. WLP_BOOKMARK)

Phase 4: hyperlink compilation

(CM side; role: CM developer)

At export time (i.e when preparing content item for wlp’s bulkloading) in our solution, Interwoven developers just parsed html content for any CM proprietary hyperlinks;

If present, they queried the target’s item WLP_BOOKMARK property with that value, they invoked again Locator’s PortalStructureService , just a different operation: getContextUrlFromBookmark[1]:

  • this operation returns the (relative) context path of a given bookmark (es. /myportalWeb/portletlocator/p1).

In this way the bookmark definition itself is decoupled from current portalweb-scoped configuration, that can differ among different environments, deployments, evolutions, etc), use the result to compose href attribute of resulting anchor tag inside cm item html property.

At this stage the CM developer can choose to add further querystring parameters(as the result of additional target cm metadata enquiry, i.e. ITEM_ID, Locale, WLP_PortalPath, WLP_UserSegments, more on that following)

The resulting url could be:


[1] In next release the bookmark-to-webcontext url resolution could be moved inside the portal itself, using some Ajax feature at click time
Phase 5: url parsing (WLP side)

After bulkloaded the item(s), and CM display temaplates / jsp implemented and deployed, any /portletlocator links get intercepted by PortletLocator’s ServletFilter;

This filter picks up the bookmark value in servletpath and compute the actual and current pageUrl on which target portlet instance is – currently – instantiated in.


The user is redirected or forwarded (based on exposure-redirect-request-enabled configuration parameter) to portal’s page url .

Should any additional querystring parameters be present in url, the filter copies them in (Outer)Request scope (or Sessione scope, if configured), so that target portlet can take advantage of them to further customize the default behaviour of i.e. content display logic: for instance you can use item_id request parameter to select a specific content item (given you provided a corresponding cm property / metadata and that this id is really unique across the CM Repository).

Content items personalization

Phase 1 : define and implement your personalization entities

(WLP side)

First you had to identify which portal entities you will use to as personalization discriminating data useful to profile your cm item: you can decide to “tag” target user segments using both

  • wlp user segments, or
  • wlp streaming portal path(s)


Locator expose those two list in two different web services:

  1. in PortalStructureService
    • availablePortalPath : returns a key/value list of currently configured streaming portals’ path/name
    • availableDesktopPath : given an (optional) portal path, returns a key/value list of currently configured desktops’ path/name
  2. in UserSegmentService
    • availableSegments : returns the list of currently configured user segments


Phase 2: inclusion of portal path list / user segments list into CM contribution tool

You can follow same guidelines to include to external CM tool those lists: the redactor would than just pickup the current usersegment / current portal that specific item is targeted to, and store it this value in a specific cm item property / metadata (i.e. WLP_USERSEGMENTS, or WLP_PORTAL_PATH).

Phase 3: cm personalization property evaluation

(WLP side)

On wlp side, when implementing cm display templates or jsps, you can select the cm item to show by comparing:

  • current item / node ‘s personalization property (i.e. WLP_USERSEGMENTS, or WLP_PORTAL_PATH)
  • with current user ‘s user segment or current portal path

The latter being a portlet instance’s preference while the former the result of a dynamic evaluation leveraging Locator’s custom control API:


String[] segmentOfUserFromRequest(HttpServletRequest request)

  • Given an instance of HttpRequest, returns the list of usersegments this current user (both anonymous or logged) is in.
  • NB: this latter method makes no use of any cache. Use it with awareness…..

Furthermore there are many specific features that can be used, we suggest to consult this pdf documentation.

Enjoy ...

Nino Guarnacci & Gabriele Folchi



Very good post. Thanks for sharing.

Posted by Adrien Wank on January 20, 2010 at 03:06 PM CET #

Interesting point you make, very well thought out.

Posted by Corina Guerena on January 23, 2010 at 06:18 PM CET #

Post a Comment:
  • HTML Syntax: NOT allowed

.. useful blog on java and middleware technologies.


« July 2016