Author: chris.laprun(a)jboss.com Date: 2008-10-27 20:03:17 -0400 (Mon, 27 Oct 2008) New Revision: 12191 Added: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/ docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/coordination.png docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/coordination_event.png docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/create_event_1.png docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/create_event_2.png docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/create_event_3.png docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/create_event_4.png docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/create_event_5.png docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/create_event_6.png docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/wiring_example.png Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/coordination.xml Log: - Started updating coordination chapter. Still needs some work on alias and parameter bindings. Added: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/coordination.png =================================================================== (Binary files differ) Property changes on: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/coordination.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/coordination_event.png =================================================================== (Binary files differ) Property changes on: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/coordination_event.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/create_event_1.png =================================================================== (Binary files differ) Property changes on: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/create_event_1.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/create_event_2.png =================================================================== (Binary files differ) Property changes on: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/create_event_2.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/create_event_3.png =================================================================== (Binary files differ) Property changes on: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/create_event_3.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/create_event_4.png =================================================================== (Binary files differ) Property changes on: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/create_event_4.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/create_event_5.png =================================================================== (Binary files differ) Property changes on: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/create_event_5.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/create_event_6.png =================================================================== (Binary files differ) Property changes on: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/create_event_6.png ___________________________________________________________________ Name: svn:mime-type + image/png Added: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/wiring_example.png =================================================================== (Binary files differ) Property changes on: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/images/coordination/wiring_example.png ___________________________________________________________________ Name: svn:mime-type + image/png Modified: docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/coordination.xml =================================================================== --- docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/coordination.xml 2008-10-27 22:23:32 UTC (rev 12190) +++ docs/branches/JBoss_Portal_Branch_2_7/referenceGuide/en/modules/coordination.xml 2008-10-28 00:03:17 UTC (rev 12191) @@ -7,50 +7,130 @@ <firstname>Boleslaw</firstname> <surname>Dawidowicz</surname> </author> + <author> + <firstname>Chris</firstname> + <surname>Laprun</surname> + </author> </chapterinfo> - <title>JBoss Portal Explicit Coordination</title> + <title>JBoss Portal support for Portlet 2.0 coordination features</title> <sect1> - <title>Explicit vs implicit coordination</title> + <title>Introduction</title> <para> - Portlet 2.0 coordination features are mediated by the portal between several - portlet windows, therefore the portal at runtime needs to be able to define - relationships between windows. Relationship can be established from an implicit - model (i.e a set of predicates applied on some state that will answer TRUE/FALSE - to the question are the portlet windows foo and bar in a relationship) or from an - explicit model (that states that foo and bar have a relationship). The implicit - model is very good for defining default configuration as it does not require much - configuration but is not able to cover the exceptional case, that's why we need - to combine it with an explicit model that will take precedence over the implicit - model, it is the well known principle of convention over configuration. + 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. </para> <para> - Currently all explicit coordination happens only in the scope of the same page. + 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. </para> - </sect1> - <sect1> - <title>Bindings and wirings</title> - <sect2> - <title>Event wiring</title> + <title>Explicit vs. implicit coordination</title> + <para> + Most JSR-286 specification implementations support the coordination features using what is called an + <emphasis>implicit</emphasis> 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. + </para> + <para> + However, such an <emphasis>implicit</emphasis> 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 semnantically compatible portlets, JBoss Portal + introduces an <emphasis>explicit</emphasis> coordination model that takes precedence over the implicit model + when so required. + </para> + <para> + Consider, for example, the following case: we have 3 windows (<literal>A</literal>, <literal>B</literal> + and <literal>C</literal>) on a given page. Each window is associated to a given portlet + (<literal>Portlet A</literal>, <literal>Portlet B</literal> and <literal>Portlet C</literal>, respectively). + <literal>Portlet A</literal> can produce the <literal>Event A</literal> event, while + <literal>Portlet B</literal> and <literal>Portlet C</literal> can consume <literal>Event B</literal> and + <literal>Event C</literal>, respectively. Assuming that these events are semantically equivalent, we would + like to wire these portlets via their events such that when <literal>Portlet A</literal> emits an + <literal>Event A</literal>, it gets converted to the appropriate event and transmitted to both + <literal>Portlet B</literal> and <literal>Portlet C</literal> so that their respective windows can be + appropriately updated. This scenario, as depicted below, is impossible using <emphasis>implicit</emphasis> + wiring of events: + <example> + <mediaobject> + <imageobject> + <imagedata fileref="images/coordination/wiring_example.png" format="png" align="center" + valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + </example> + + </para> <para> - Wires JSR-286 events. With implicit wirings the event producer and the - consumer declares the same event namespace and local name to get event - delivered in the scope of the same page. With explicit wiring any pairs of - Window:Event can be connected. + 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. </para> </sect2> + </sect1> + + <sect1> + <title>General configuration considerations</title> + <para> + As most other features of JBoss Portal, the coordination functionality can be configured either declaratively + using the now familiar <literal>*-object.xml</literal> descriptors (see <xref linkend="xmldescriptors"/> 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. + </note> + </para> + <sect2> - <title>Parameter binding</title> + <title>Overview of the configuration interface</title> + <para> + 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 + <literal>Coordination</literal> action: + <mediaobject> + <imageobject> + <imagedata fileref="images/coordination/coordination.png" format="png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + </para> <para> - Binds JSR-286 shared parameters. With implicit binding parameters with the - same public name are shared. With explicit binding any public parameters can - share values. Windows for which such binding applies are explicitly defined. + 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: + <itemizedlist> + <listitem> + <para>Alias bindings</para> + </listitem> + <listitem> + <para>Parameter bindings</para> + </listitem> + <listitem> + <para>Event wirings</para> + </listitem> + </itemizedlist> + 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: + <mediaobject> + <imageobject> + <imagedata fileref="images/coordination/coordination_event.png" format="png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> </para> </sect2> + </sect1> + + <sect1> + <title>Alias Bindings</title> <sect2> - <title>Alias binding</title> + <title>Definition</title> <para> Explicit alias binding define a name of page scoped parameter that will apply @@ -59,144 +139,280 @@ <programlisting><![CDATA[http://localhost:8080/portal/portal/default/Coordination+Samples?aliasBinding1=someValue]]></programlisting> </sect2> + <sect2> + <title>Configuration via XML</title> + <para>TODO</para> + <programlisting role="XML"><![CDATA[<coordination> + <bindings> + <implicit-mode>FALSE</implicit-mode> + <alias-binding> + <id>aliasBinding1</id> + <qname>foo</qname> + </alias-binding> + <alias-binding> + <id>aliasBinding2</id> + <qname>bar1</qname> + <qname>{urn:jboss:portal:samples:daa2}daa2</qname> + </alias-binding> + </bindings> +</coordination>]]></programlisting> + </sect2> + <sect2> + <title>Graphical configuration</title> + <para>TODO</para> + </sect2> </sect1> + <sect1> - <title>Coordination configuration</title> + <title>Parameter bindings</title> + <sect2> + <title>Definition</title> <para> - Configuration takes place in -object.xml file. The &lt;coordination&gt; tag - can be used in both &lt;page&gt; and &lt;portal&gt; tags. When used in - &lt;portal&gt; tag only &lt;implicit-mode&gt; tag can be defined for wirings - and bindings: + Binds JSR-286 shared parameters. With implicit binding parameters with the + same public name are shared. With explicit binding any public parameters can + share values. Windows for which such binding applies are explicitly defined. </para> + </sect2> + <sect2> + <title>Configuration via XML</title> + <para>TODO</para> + <programlisting role="XML"><![CDATA[<coordination> + <bindings> + <implicit-mode>FALSE</implicit-mode> + <parameter-binding> + <id>parameterBinding1</id> + <window-coordination> + <window-name>SomePortletWindow1</window-name> + <qname>foo</qname> + </window-coordination> + <window-coordination> + <window-name>SomePortletWindow2</window-name> + <qname>foo</qname> + </window-coordination> + <window-coordination> + <window-name>SomePortletWindow2</window-name> + <qname>{urn:jboss:portal:samples:daa1}daa1</qname> + </window-coordination> + </parameter-binding> + </bindings> +</coordination>]]></programlisting> + </sect2> + <sect2> + <title>Graphical configuration</title> + <para>TODO</para> + </sect2> + </sect1> - <programlisting role="XML"><![CDATA[<portal> + <sect1> + <title>Event wirings</title> + <sect2> + <title>Definition</title> - ... + <para> + An <emphasis>event wiring</emphasis> wires an event produced by specified portlet windows to consumer + portlet windows. In the <emphasis>implicit</emphasis> form, this wiring associates producer and consumer + via the event's qualified name (QName). + </para> + </sect2> - <coordination> - <bindings> - <implicit-mode>TRUE</implicit-mode> - </bindings> - <wirings> - <implicit-mode>FALSE</implicit-mode> - </wirings> - </coordination> - -</portal>]]></programlisting> + <sect2> + <title>Configuration via XML</title> <para> - When used within the &lt;page&gt; tag coordination event wirings and bindings - can be defined:&lt;/page&gt;</para> + Explicit event wirings can be defined in any page definition of your <literal>*-object.xml</literal> + descriptors. For example, this is how the example that we detailed above would be implemented, within a + page definition: + </para> + <programlistingco> + <areaspec> + <area id="coordination.wirings.coordination" coords='2' /> + <area id="coordination.wirings.wirings" coords='3' /> + <area id="coordination.wirings.implicit" coords='4' /> + <area id="coordination.wirings.event" coords='5' /> + <area id="coordination.wirings.name" coords='6' /> + <area id="coordination.wirings.sources" coords='7' /> + <area id="coordination.wirings.windowcoord" coords='8' /> + <area id="coordination.wirings.destinations" coords='13' /> + </areaspec> + <programlisting><![CDATA[... +<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>]]></programlisting> + <calloutlist> + <callout arearefs="coordination.wirings.coordination"> + <para> + Coordination configuration is done via the newly introduced <literal>&lt;coordination&gt;</literal> + element. + </para> + </callout> + <callout arearefs="coordination.wirings.wirings"> + <para> + Event wirings are defined using the <literal>&lt;wirings&gt;</literal> element. + </para> + </callout> + <callout arearefs="coordination.wirings.implicit"> + <para> + 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. + </para> + </callout> + <callout arearefs="coordination.wirings.event"> + <para> + An event wiring definition consists of: + <itemizedlist> + <listitem> + <para>a name used to identify it</para> + </listitem> + <listitem> + <para>a list of source events that are to be mapped to the destination ones</para> + </listitem> + <listitem> + <para> a list of destination events that will be mapped from the source events</para> + </listitem> + </itemizedlist> + </para> + </callout> + <callout arearefs="coordination.wirings.name"> + <para>The name of the event wiring which must be unique in the scope of the specified page.</para> + </callout> + <callout arearefs="coordination.wirings.sources"> + <para> + The list of source events, each being identified by a + <literal>&lt;window-coordination&gt;</literal> element. + </para> + </callout> + <callout arearefs="coordination.wirings.windowcoord"> + <para> + A window / event name pair identifying either a source or destination of event to be mapped. + </para> + </callout> + <callout arearefs="coordination.wirings.destinations"> + <para> + The list of destination events, each being identified by a + <literal>&lt;window-coordination&gt;</literal> element. + </para> + </callout> + </calloutlist> + </programlistingco> + </sect2> + <sect2> + <title>Graphical configuration</title> + <para> + 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: + <mediaobject> + <imageobject> + <imagedata fileref="images/coordination/create_event_1.png" format="png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> - <programlisting role="XML"><![CDATA[<coordination> - - <wirings> - <implicit-mode>TRUE</implicit-mode> - <event-wiring> - <name>eventWiring1</name> - <sources> - <window-coordination> - <window-name>ShoppingCatalogPortletWindow1</window-name> - <qname>{urn:jboss:portal:samples:event}CartEvent</qname> - </window-coordination> - </sources> - <destinations> - <window-coordination> - <window-name>ShoppingCartPortletWindow2</window-name> - <qname>{urn:jboss:portal:samples:event}CartEvent</qname> - </window-coordination> - <window-coordination> - <window-name>ShoppingCartPortletWindow3</window-name> - <qname>{urn:jboss:portal:samples:event}CartEvent</qname> - </window-coordination> - </destinations> - </event-wiring> - <event-wiring> - <name>eventWiring2</name> - <sources> - <window-coordination> - <window-name>ShoppingCatalogPortletWindow2</window-name> - <qname>{urn:jboss:portal:samples:event}CartEvent</qname> - </window-coordination> - </sources> - <destinations> - <window-coordination> - <window-name>ShoppingCartPortletWindow1</window-name> - <qname>{urn:jboss:portal:samples:event}CartEvent</qname> - </window-coordination> - <window-coordination> - <window-name>ShoppingCartPortletWindow4</window-name> - <qname>{urn:jboss:portal:samples:event}CartEvent</qname> - </window-coordination> - </destinations> - </event-wiring> - </wirings> - + 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: + <mediaobject> + <imageobject> + <imagedata fileref="images/coordination/create_event_2.png" format="png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> - <bindings> - <implicit-mode>FALSE</implicit-mode> - - <parameter-binding> - <id>parameterBinding1</id> - <window-coordination> - <window-name>SomePortletWindow1</window-name> - <qname>foo</qname> - </window-coordination> - <window-coordination> - <window-name>SomePortletWindow2</window-name> - <qname>foo</qname> - </window-coordination> - <window-coordination> - <window-name>SomePortletWindow3</window-name> - <qname>foo</qname> - </window-coordination> - </parameter-binding> + 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: + <mediaobject> + <imageobject> + <imagedata fileref="images/coordination/create_event_3.png" format="png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> - <parameter-binding> - <id>parameterBinding2</id> - <window-coordination> - <window-name>SomePortletWindow1</window-name> - <qname>bar1</qname> - </window-coordination> - <window-coordination> - <window-name>SomePortletWindow2</window-name> - <qname>{urn:jboss:portal:samples:daa1}daa1</qname> - </window-coordination> - </parameter-binding> + Select a destination event and be presented with the list of windows consuming that event: + <mediaobject> + <imageobject> + <imagedata fileref="images/coordination/create_event_4.png" format="png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> - <alias-binding> - <id>aliasBinding1</id> - <qname>foo</qname> - </alias-binding> + 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 <literal>foo</literal> here: + <mediaobject> + <imageobject> + <imagedata fileref="images/coordination/create_event_5.png" format="png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> - <alias-binding> - <id>aliasBinding2</id> - <qname>bar1</qname> - <qname>{urn:jboss:portal:samples:daa2}daa2</qname> - </alias-binding> - - </bindings> -</coordination>]]></programlisting> + Click on the <literal>Create wiring</literal> button. Your new event wiring has been created and will appear + in the list of existing wirings: + <mediaobject> + <imageobject> + <imagedata fileref="images/coordination/create_event_6.png" format="png" align="center" valign="middle" scalefit="1"/> + </imageobject> + </mediaobject> + </para> + </sect2> + </sect1> - <sect2> - <title>&lt;implicit-mode&gt;</title> + <sect1> + <title>&lt;implicit-mode&gt;</title> - <para> - This tag can be applied for both &lt;bindings&gt; and &lt;wirings&gt; - tags. It defines if implicit coordination is enabled or disabled for - this given portal object. Value of this setting is cascaded to all - children in portal object tree unless overwritten somewhere in the - hierarchy. If no &lt;implicit-mode&gt; is defined in portal object tree - default value is TRUE. - </para> - </sect2> + <para> + While the new <literal>&lt;coordination&gt;</literal> element can be used in both + <literal>&lt;page&gt;</literal> and <literal>&lt;portal&gt;</literal> elements, the only configuration that + can be specified at the portal level is whether to use the implicit mode or not: + </para> + + <programlisting role="XML"><![CDATA[<portal> + ... + + <coordination> + <bindings> + <implicit-mode>TRUE</implicit-mode> + </bindings> + <wirings> + <implicit-mode>FALSE</implicit-mode> + </wirings> + </coordination> + + </portal>]]></programlisting> + + <para> + Specifying this <literal>&lt;implicit-mode&gt;</literal> element at the portal level allows the user to specify + which default behavior to apply to child pages. Quite reasonably, if <literal>&lt;implicit-mode&gt;</literal> + is set to <literal>TRUE</literal> then the implicit mode will be used by default. This does not, however, + preclude specific pages to define explicit associations where needed. Setting + <literal>&lt;implicit-mode&gt;</literal> to <literal>FALSE</literal>, 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 <emphasis>bindings</emphasis> or + <emphasis>wirings</emphasis>. If no value is provided, implicit mode is used by default. + </para> </sect1> <sect1> <title>Coordination Samples</title> <para> - JBoss Portal comes with several examples in 'Coordination Samples' page. Its good - to follow them looking at the configuration file that can be found in - portal-coordination-samples.war/WEB-INF/default-object.xml + As part of the <literal>core-samples</literal> module, JBoss Portal provides several examples of how + coordination can be used. These examples are gathered in the <literal>Coordination Samples</literal> page. You + can look at how the examples are configured using the administration interface or by looking at the + <filename>portal-coordination-samples.war/WEB-INF/default-object.xml</filename> file. </para> </sect1> </chapter> \ No newline at end of file