A JSR168-compliant implementation of inter-portlet communication

How it works

A portlet may have any number of inputs, and any number of outputs. It refers to these inputs and outputs using a local name in the portlet code (eg "person_name", "item_id"). Mappings of input/output names to global message boxes are defined externally to the portlet code - in the portlet preferences.

A message box can hold only one message at a time: sending a new message to it will overwrite the old one. The messages never expire, as we cannot know whether the interested portlets no longer need them (actually, this implementation stores them in the session, so when the user session expires they will be cleaned up). Messages can be any sort of Object, though it may be wise to make them Serializable.

A message input is mapped to a source message box, from which it reads its message.

A message output always sends its message to a local (namespaced to its own portlet window) message box of the same name, but it may also publish it to any number of additional global message boxes.

Still not quite clear? Have a look at the screenshots on the right of this page, or on the Example page.

Limitations

This version of the messaging library allows for messaging between portlets in different portlet applications. However, setting this up will require some configuration and probably coding, as the exact details of how it works will depend on your situation. What you need to do is described in the Cross-Context messaging section.

Caching of portlet views is a problem: if you want the view of another portlet to update because an input message has changed, but the portlet is cached, the portal won't call its 'doView' and you have no way of forcing it to - that I know of, anyway. If you have enabled caching like this, I guess you'll have to add a 'refresh' link to the portlet so that the user can force a reload. However this isn't very user-friendly - another option which works is to disable view caching entirely by setting

       <expiration-cache>0</expiration-cache>

for your portlets in portlet.xml. You will then need to ensure that your 'doView' is as lightweight as possible, as it will be called every time the page loads.

This is not critical, but something to be aware of: Portlets only 'register' their mappings when they first load. The provided mapping configuration form (for use in a portlet's Edit mode) lists message boxes available as sources or targets, but it will only be able to 'see' those that have already been registered in the current session's MessageCentre. So if you haven't visited a portlet's page, its message boxes won't appear yet in another portlet's Edit mode.

How to use it:

• Add portlet-messaging-2.2.jar to your portlet webapp's WEB-INF/lib
• Make sure you call MessageHelper.loadPrefs at the beginning of your portlet's doView.
  • It needs to know a unique ID for the portlet window, and if you're using cross-context communication, a Session ID as well. Both are described in detail later.
• The portlet can read messages using MessageHelper.get(name), and send messages using MessageHelper.send(name). If you're sending messages, and want to avoid problems due to portlets loading out of order/in parallel on the page, make sure you send them in processAction - that way they'll be sent and ready by the time the other portlets get to doView.
• Important step: configure the portlet's message mappings in its entry in portlet.xml. Each input has a Name (local, used in the portlet code), a SourceName, and a SourceNamespace. Each output has a Name (local, used in the portlet code), and any number of additional Publish destinations (which each consist of a PublishName and a PublishNamespace). Source and Publish names are used as 'global' message names at runtime, and are visible to all portlets. Example settings for a portlet with one input and one output are shown below. Note that these are the defaults: if you define a Publish target, and the user later tries to remove it, they won't be able to (although they would be able to re-map it).

  <portlet-preferences>
  	<preference>
  		<name>MsgInput1Name</name>
  		<value>author</value>
  	</preference>
  	<preference>
  		<name>MsgInput1SourceName</name>
  		<value>person</value>
  	</preference>
  	<preference>
  		<name>MsgInput1SourceNamespace</name> 
  		<value></value>
  	</preference>
  	<preference>
  		<name>MsgOutput1Name</name> 
  		<value>book</value>
  	</preference>
  	<preference>
  		<name>MsgOutput1PublishName1</name>
  		<value>title</value>
  	</preference>
  	<preference>
  		<name>MsgOutput1PublishNamespace1</name>
  		<value></value>
  	</preference>
  	<preference>
  		<name>MsgOutput1PublishName2</name>
  		<value>search_term</value>
  	</preference>
  	<preference>
  		<name>MsgOutput1PublishNamespace2</name>
  		<value></value>
  	</preference>
  </portlet-preferences>
  

• Add your portlets to portal pages, and then set up any wiring that is different from the defaults in portlet.xml:
  • If your portal structure will be fixed, and it allows you to directly set the preferences for each portlet window somehow, you can do that to set up the wiring.
  • Or, write an Edit mode that lets the portlet user modify the inputs/outputs in the preferences. Once you've saved the preferences, reload the mappings by calling MessageHelper.setLoadedPrefs (to false) and then MessageHelper.loadPrefs
  • Or, if you want to use the full automatic wiring interface provided (see the screenshots):
    • In doEdit: first load the mappings with MessageHelper.loadPrefs, then call MessageUtils.prepareMappingForm. After this is done, include the edit_mappings.jsp, which draws the edit mappings form.
    • Call MessageUtils.processMappingForm in processAction when you need to process the results of the edit mappings form. This will update the message mappings for the selected portlet, and save them in the portlet's preferences.

What's the Portlet ID?

Lots of the functions and classes in this messaging system require a portlet ID. For the messages to get to the right places, we clearly need a unique ID for each portlet window that appears on a portal page.

There is no direct provision in JSR168 for portlets to find out their own window ID (which the portal will have assigned). However, by setting session variables and inspecting the way the portal namespaces them (which is specified in JSR168), we can attempt to retrieve this portlet window ID. MessageHelper.getPortletWindowID(PortletRequest) does this, and is also now used by default by MessageHelper.getPortletID(PortletRequest).

As a fall-back, another approach is to randomly generate portlet window IDs the first time the portlet is rendered, and cache them in the local portlet's session. The function to do this is MessageHelper.getPortletID, passing useWindowID=false.

You can use either of these approaches, or implement your own solution; as long as each portlet window has a unique ID, it can be any String.

What's the Session ID?

Use MessageHelper.getSessionID to retrieve it.

It's only really relevant for Cross-Context messaging, so if your portlets are all in the same application, just use the MessageHelper function and don't worry about it.

How do I turn on debug messages?

This is managed by commons-logging, which is most likely already included in the application server hosting your portlets. To turn on messages you may not need to do anything, have a look in the server log files first; otherwise you will need to find and modify the server's logging configuration.

Messaging model: Message Centre keeps track of all the mappings between local message names and global message names, allowing dynamic reconfiguration of message 'routes' by the administrator or the portal user.

Three messaging portlets

Multiple windows with instances of the same portlets: they have different mappings, defined in their parameters

Dynamically mapped portlets: initial state

Dynamically mapped portlets: all in Edit mode

Dynamically mapped portlets: sent message from 1st to 2nd

Dynamically mapped portlets: sent message from 2nd to 3rd

Dynamically mapped portlets: changed 3rd to read from author_name

Dynamically mapped portlets: 3rd now does search using author_name