JBoss.org Community Documentation

- Prev
- Next

## Chapter 8. JBoss Portal support for Portlet 2.0 coordination features

### Boleslaw Dawidowicz

### Chris Laprun

## 8.1. Introduction

While the Portlet 2.0 specification provides for more advanced coordination between portlets than the 1.0 version of the specification, it is left up to specific implementations how portlets are wired together. This chapter will look into how the coordination features are implemented in JBoss Portal.

If you are interested in these features, we strongly encourage you to read the Portlet 2.0 (JSR-286) specification as we will assume in this chapter that you are familiar with the different coordination concepts.

### 8.1.1. Explicit vs. implicit coordination

Most JSR-286 specification implementations support the coordination features using what is called an implicit coordination model. This model is called implicit because the relations between the different interacting portlets are inferred based on the event or parameter names that are used to pass information between the portlets. This follows the well-known principle of convention over configuration and provides a good default behavior as it doesn't require explicit user action to wire portlets.

However, such an implicit model of how portlets are wired together fails to handle more complex cases. In particular, it is often the case that semantically related events or public parameters are named differently by different portlet providers. As it is not always possible to modify the portlets to adjust for this minor naming difference of otherwise semantically compatible portlets, JBoss Portal introduces an explicit coordination model that takes precedence over the implicit model when so required.

Consider, for example, the following case: we have 3 windows (`A`, `B` and `C`) on a given page. Each window is associated to a given portlet (`Portlet A`, `Portlet B` and `Portlet C`, respectively). `Portlet A` can produce the `Event A` event, while `Portlet B` and `Portlet C` can consume `Event B` and `Event C`, respectively. Assuming that these events are semantically equivalent, we would like to wire these portlets via their events such that when `Portlet A` emits an `Event A`, it gets converted to the appropriate event and transmitted to both `Portlet B` and `Portlet C` so that their respective windows can be appropriately updated. This scenario, as depicted below, is impossible using implicit wiring of events:

Example 8.1.

We look at how to bypass the default implicit model using JBoss Portal's explicit model in the rest of this chapter. It is, however, interesting to note that JBoss Portal can function with both models at the same time. More precisely, it is possible to use the implicit handling of coordination while still specifying explicit wirings, as we will see later.

## 8.2. General configuration considerations

As most other features of JBoss Portal, the coordination functionality can be configured either declaratively using the now familiar `*-object.xml` descriptors (see Chapter 6, XML Descriptors for a refresher on these descriptors) or, at runtime, using the administration configuration GUI. We detail, below, both configuration options for each type of coordination entities.

## Note

Explicit coordination is currently scoped only at the page level. More specificially, explicit coordination between portlets is only supported between portlets located on the same page.

### 8.2.1. Overview of the configuration interface

Launching JBoss Portal's administration interface, you will notice a few changes. In particular, a new option is available on page configuration screens: the ability to configure coordination using the `Coordination` action:

Figure 8.1.

Clicking on that link will bring you to the coordination configuration for that particular page. The interface is organized in three sections, each of which is collapsible by clicking on the section header. These sections detail the configuration for each coordination element that can be controlled by JBoss Portal:

- Alias bindings

- Parameter bindings

- Event wirings

We will look at the specific configuration and what each of these concepts mean later. Here is how the interface looks like for a page, with both the alias and parameter bindings section collapsed:

Figure 8.2.

## 8.3. Alias Bindings

### 8.3.1. Definition

Alias bindings are a JBoss Portal specific feature which allows users to define an alias to a public render parameter that can be used in URLs to pass a value to all portlet windows reacting to the aliased public parameter(s). The syntax for the URL is as follows: `{portal URL}/{page name}?{alias name}={alias value}`.

It is, for example, possible to alias public render parameters `paramA` and `paramC` to the "`alias`" name so that JBoss Portal's event bus can transmit that value to interested portlets on a given page when the requested page URL contains a value for the appropriate URL parameter:

Example 8.2.

### 8.3.2. Configuration via XML

Explicit alias bindings can be defined in any page definition of your `*-object.xml` descriptors. For example, this is how the example that we detailed above would be implemented, within a page definition:

    ...
    <coordination>
       <bindings>
          <implicit-mode>FALSE</implicit-mode>
          <alias-binding>
             <id>alias</id>
             <qname>paramA</qname>
             <qname>paramC</qname>
          </alias-binding>
       </bindings>
    </coordination>

| Coordination configuration is done via the newly introduced `<coordination>` element.
| Alias bindings are defined using the `<bindings>` element. Note that this element is also where parameter bindings are defined.
| We specify here that we want JBoss Portal to send parameter values when an explicit bindings are defined (`<implicit-mode>` set to `FALSE`).
| An alias binding definition consists of: an id used to identify it a list of public render parameter names or previously defined alias or parameter binding names In this example, we defined an alias binding named "`alias`" which aliases the public render parameters `paramA` and `paramC`.

### 8.3.3. Graphical configuration

Creating a new alias binding is done by first selecting one or more public parameters that will be used for the binding:

Figure 8.3.

The interface will prompt you for a name for this new binding:

Figure 8.4.

Clicking on `Create alias` will create the new binding and it will appear in the existing binding lists:

Figure 8.5.

## 8.4. Parameter bindings

### 8.4.1. Definition

A parameter binding allows users to specify that public render parameters with different names are semantically equivalent so that when one such parameter is updated, all the portlets that can handle such a parameter receive the update, regardless of the name of the parameter that got updated. In the implicit case, portlets can only react to changes of values in parameters whose name they know.

Consider the following example. We are deploying two portlets, `Portlet A` and `Portlet B`, from different vendors and assign them to `Window A` and `Window B`, respectively. Each portlet can react to a specific public render parameter (`{nsA}paramA` and `{nsB}paramB`, respectively). Under the implicit coordination model, these portlets wouldn't be able to communicate even if both parameters were semantically equivalent. JBoss Portal's explicit coordination model allows users to explicit the semantic link between both parameter names such that, when `Portlet A` updates the value of `{nsA}paramA`, `Portlet B` gets notified of the update via a change of value of `{nsB}paramB`:

Example 8.3.

### 8.4.2. Configuration via XML

Explicit parameter bindings can be defined in any page definition of your `*-object.xml` descriptors. For example, this is how the example that we detailed above would be implemented, within a page definition:

    ...
    <coordination>
       <bindings>
          <parameter-binding>
             <id>parameterBinding</id>
             <window-coordination>
                <window-name>Window A</window-name>
                <qname>{nsA}paramA</qname>
             </window-coordination>
             <window-coordination>
                <window-name>Window B</window-name>
                <qname>{nsB}paramB</qname>
             </window-coordination>
          </parameter-binding>
       </bindings>
    </coordination>

| Coordination configuration is done via the newly introduced `<coordination>` element.
| Parameter bindings are defined using the `<bindings>` element. Note that this element is also where alias bindings are defined. Note here that we don't specify a value for the `<implicit-mode>` element, it will thus default to `TRUE`, meaning that implicit binding of parameters will also be performed by JBoss Portal in addition to the explicit binding we are defining here.
| A parameter binding definition consists of: an id used to identify it a list of `<window-coordination>` elements identifying which parameters will be bound for which portlets In this example, we defined a parameter binding named "`parameterBinding`" which specifies that whenever `Window A` or `Window B` updates the value of the public parameter `{nsA}paramA` or `{nsA}paramA` (respectively), the other will receive the new value for the public render parameter it knows about.
| A window / parameter name pair identifying either a public parameter to be wired.

### 8.4.3. Graphical configuration

Creating a new parameter binding is done by first selecting a public parameter / window from the list:

Figure 8.6.

The interface will prompt you for a name for this new binding:

Figure 8.7.

Clicking on `Create binding` will create the new binding and it will appear in the existing binding lists:

Figure 8.8.

## 8.5. Event wirings

### 8.5.1. Definition

An event wiring wires an event produced by specified portlet windows to consumer portlet windows. In the implicit form, this wiring associates producer and consumer via the event's qualified name (QName).

### 8.5.2. Configuration via XML

Explicit event wirings can be defined in any page definition of your `*-object.xml` descriptors. For example, this is how the example that we detailed above would be implemented, within a page definition:

    ...
    <coordination>
     <wirings>
         <implicit-mode>TRUE</implicit-mode>
         <event-wiring>
             <name>wiring</name>
             <sources>
                 <window-coordination>
                     <window-name>Window A</window-name>
                     <qname>Event A</qname>
                 </window-coordination>
             </sources>
             <destinations>
                 <window-coordination>
                     <window-name>Window B</window-name>
                     <qname>Event B</qname>
                 </window-coordination>
                 <window-coordination>
                     <window-name>Window C</window-name>
                     <qname>Event C</qname>
                 </window-coordination>
             </destinations>
         </event-wiring>
      </wirings>
    </coordination>

| Coordination configuration is done via the newly introduced `<coordination>` element.
| Event wirings are defined using the `<wirings>` element.
| We specify here that we default to implicit wiring of events for this page. However, we will define one explicit event wiring that will take precedence over the implicit wiring when needed.
| An event wiring definition consists of: a name used to identify it a list of source events that are to be mapped to the destination ones a list of destination events that will be mapped from the source events
| The name of the event wiring which must be unique in the scope of the specified page.
| The list of source events, each being identified by a `<window-coordination>` element.
| A window / event name pair identifying either a source or destination of event to be mapped.
| The list of destination events, each being identified by a `<window-coordination>` element.

### 8.5.3. Graphical configuration

Creating a new event wiring is fairly easy as the interface will guide you. First, it will present a list of available produced events on this page:

Figure 8.9.

Select an event. The interface will display the list of all windows producing this event for this page. Note also that your selection is summarized on the right side of the screen:

Figure 8.10.

Selecting one or more windows (here we selected two) will continue the process. The interface will now present you with the list of consumed events on this page, while your new event wiring is still be being built up on the right side of the screen:

Figure 8.11.

Select a destination event and be presented with the list of windows consuming that event:

Figure 8.12.

Select one or more destination windows to which the source event will be mapped via the destination event. You will now be ask to name your new event wiring after having the opportunity to review what will be created. We name our new event wiring `foo` here:

Figure 8.13.

Click on the `Create wiring` button. Your new event wiring has been created and will appear in the list of existing wirings:

Figure 8.14.

## 8.6. <implicit-mode>

While the new `<coordination>` element can be used in both `<page>` and `<portal>` elements, the only configuration that can be specified at the portal level is whether to use the implicit mode or not:

    <portal>

          ...

          <coordination>

             <bindings>

                <implicit-mode>TRUE</implicit-mode>

             </bindings>

             <wirings>

                <implicit-mode>FALSE</implicit-mode>

             </wirings>

          </coordination>

          ...

    </portal>

Specifying this `<implicit-mode>` element at the portal level allows the user to specify which default behavior to apply to child pages. Quite reasonably, if `<implicit-mode>` is set to `TRUE` then the implicit mode will be used by default. This does not, however, preclude specific pages to define explicit associations where needed. Setting `<implicit-mode>` to `FALSE`, however, completely deactivates the implicit handling of coordination features, leaving it up to users to configure only the associations that need to be made. Note also that the implicit mode can be set for either bindings or wirings. If no value is provided, implicit mode is used by default.

## 8.7. Coordination Samples

As part of the `core-samples` module, JBoss Portal provides several examples of how coordination can be used. These examples are gathered in the `Coordination Samples` page. You can look at how the examples are configured using the administration interface or by looking at the `portal-coordination-samples.war/WEB-INF/default-object.xml` file.

- PrevChapter 7. Portal URLs
- Top of page
- Front page
- NextChapter 9. Error Handling Configuration