Author: julien(a)jboss.com Date: 2007-04-30 07:39:50 -0400 (Mon, 30 Apr 2007) New Revision: 7146 Added: docs/trunk/referenceGuide/en/images/portalapi/PortalNodeEvent.png docs/trunk/referenceGuide/en/images/portalapi/PortalNodeEventContext.png docs/trunk/referenceGuide/en/images/portalapi/PortalSessionEvent.png docs/trunk/referenceGuide/en/images/portalapi/eventpropagation.png docs/trunk/referenceGuide/en/images/portalapi/user.event.png Modified: docs/trunk/referenceGuide/en/modules/portalapi.xml Log: more work on portalapi chatper Added: docs/trunk/referenceGuide/en/images/portalapi/PortalNodeEvent.png =================================================================== (Binary files differ) Property changes on: docs/trunk/referenceGuide/en/images/portalapi/PortalNodeEvent.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: docs/trunk/referenceGuide/en/images/portalapi/PortalNodeEventContext.png =================================================================== (Binary files differ) Property changes on: docs/trunk/referenceGuide/en/images/portalapi/PortalNodeEventContext.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: docs/trunk/referenceGuide/en/images/portalapi/PortalSessionEvent.png =================================================================== (Binary files differ) Property changes on: docs/trunk/referenceGuide/en/images/portalapi/PortalSessionEvent.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: docs/trunk/referenceGuide/en/images/portalapi/eventpropagation.png =================================================================== (Binary files differ) Property changes on: docs/trunk/referenceGuide/en/images/portalapi/eventpropagation.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: docs/trunk/referenceGuide/en/images/portalapi/user.event.png =================================================================== (Binary files differ) Property changes on: docs/trunk/referenceGuide/en/images/portalapi/user.event.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Modified: docs/trunk/referenceGuide/en/modules/portalapi.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/portalapi.xml 2007-04-30 11:20:53 UTC (rev 7145) +++ docs/trunk/referenceGuide/en/modules/portalapi.xml 2007-04-30 11:39:50 UTC (rev 7146) @@ -9,10 +9,12 @@ <title>Portal API</title> <sect1> <title>Introduction</title> + <para>JBoss Portal provides an Application Programming Interface (API) which allows to write code that interacts with the portal. The life time and validity of the API is tied to the major version which means that no changes should be required when code is written against the API provided by the JBoss Portal 2.x versions and used in a later version of JBoss Portal 2.x.</para> + <para>The Portal API package prefix is <emphasis>org.jboss.portal.api</emphasis> and all the classes part of the API are prefixed with that package except for two of them which are the <emphasis>org.jboss.portal.Mode</emphasis> and <emphasis>org.jboss.portal.WindowState</emphasis> classes, the main reason being that twose two classes were defined @@ -21,6 +23,7 @@ are <emphasis>javax.portlet.PortletMode</emphasis> and <emphasis>javax.portlet.WindowState</emphasis>. Likewise the Portal API defines similar classes named <emphasis>org.jboss.portal.Mode</emphasis> and <emphasis>org.jboss.portal.WindowState</emphasis> which offer comparable characteristics, the main differences are:</para> + <itemizedlist> <listitem>Usage of factory methods to obtain instances.</listitem> <listitem>Classes implements the <emphasis>java.io.Serializable</emphasis> interface.</listitem> @@ -218,8 +221,12 @@ class can implement in order to receive portal event notifications. It contains the method <emphasis>void onEvent(PortalEvent event)</emphasis> called by the portal framework. </para> + <para> + Listeners declaration requires a service to be deployed in JBoss that will instantiate the service implementation + and register it with the service registry. We will see how to achieve that in the example section of this chapter. + </para> <important> - The event propagation model is to use one instance of a listener class to receive all portal events that + The event propagation model uses one instance of a listener class to receive all portal events that may be routed to that class when appropriate. Therefore implementors needs to be aware of that model and must provide implementations that are thread safe. </important> @@ -228,17 +235,100 @@ <para>Portal node events extends the abstract portal event framework in order to provide notifications about user interface events happening at runtime. For instance when the portal renders a page or a window, a corresponding event will be fired.</para> - <sect3>Portal node event propagation model</sect3> - <para> - A portal node event is fired when an event of interest happens to a portal node of the portal tree. The - notification model is comparable to the <ulink url="http://en.wikipedia.org/wiki/DOM_Events#Event_flow">bub... propagation model </ulink> - defined by the DOM specification. When an event is fired, the event is propagated in the hierarchy from the most - inner node where the event happens to the root node of the tree. - </para> + <mediaobject> + <imageobject> + <imagedata width="40em" align="center" fileref="images/portalapi/PortalNodeEvent.png" format="png"/> + </imageobject> + <caption> + <para>The portal node event class hierarchy</para> + </caption> + </mediaobject> + <para>The <emphasis>org.jboss.portal.api.node.event.PortalNodeEvent</emphasis> class extends the + <emphasis>org.jboss.portal.api.node.PortalEvent</emphasis> class and is the base class for all events + of portal nodes. It defines a single method <emphasis>PortalNode getNode()</emphasis> which can be + used to retrieve the node targetted by the event.</para> + <para>The <emphasis>org.jboss.portal.api.node.event.WindowEvent</emphasis> is an extension for portal nodes + of type window. It provides access to the mode and window state of the window. It has 3 subclasses which + represent different kind of event that can target windows.</para> + <para>The <emphasis>org.jboss.portal.api.node.event.WindowNavigationEvent</emphasis> is fired when the + window navigational state changes. For a portlet it means that the window is targetted by an URL of type + render.</para> + <para>The <emphasis>org.jboss.portal.api.node.event.WindowActionEvent</emphasis> is fired when the + window is targetted by an action. For a portlet it means that the window is targetted by an URL of type + action.</para> + <para>The <emphasis>org.jboss.portal.api.node.event.WindowRenderEvent</emphasis> is fired when the + window is going to be rendered by the portal.</para> + <para>The <emphasis>org.jboss.portal.api.node.event.PageEvent</emphasis> is an extension for portal nodes + of type page.</para> + <para>The <emphasis>org.jboss.portal.api.node.event.PageRenderEvent</emphasis> is fired when the + page is going to be rendered by the portal.</para> + <sect3> + <title>Portal node event propagation model</title> + <para> + A portal node event is fired when an event of interest happens to a portal node of the portal tree. The + notification model is comparable to the <ulink url="http://en.wikipedia.org/wiki/DOM_Events#Event_flow">bub... propagation model </ulink> + defined by the DOM specification. When an event is fired, the event is propagated in the hierarchy from the most + inner node where the event happens to the root node of the tree. + </para> + <mediaobject> + <imageobject> + <imagedata width="40em" align="center" fileref="images/portalapi/eventpropagation.png" format="png"/> + </imageobject> + <caption> + <para>The portal node event propagation model</para> + </caption> + </mediaobject> + </sect3> + <sect3> + <title>Portal node event listener</title> + <para>The <emphasis>org.jboss.portal.api.node.event.PortalNodeEventListener</emphasis> interface should + be used instead of the too generic <emphasis>org.jboss.portal.api.event.PortalEventListener</emphasis> when + it comes down of listening portal node events. Actually it does not replace it, the <emphasis>PortalEventListener</emphasis> + interface semantic allows only traditional event delivering. The <emphasis>PortalNodeEventListener</emphasis> + interface is designed to match the bubbling effect during an event delivery.</para> + <para>The <emphasis>PortalNodeEvent onEvent(PortalNodeEventContext context, PortalNodeEvent event)</emphasis> + declare a <emphasis>PortalNodeEvent</emphasis> as return type. In normal circumstances it will return the + null value, however if the method call returns an event then this event should be considered by the portal + as behavior replacing the current one. + </para> + </sect3> + <sect3> + <title>Portal node event context</title> + <mediaobject> + <imageobject> + <imagedata width="28em" align="center" fileref="images/portalapi/PortalNodeEventContext.png" format="png"/> + </imageobject> + <caption> + <para>The PortalNodeEventContext interface</para> + </caption> + </mediaobject> + <para>The <emphasis>org.jboss.portal.api.node.event.PortalNodeEventContext</emphasis> interface extends + the <emphasis>PortalEventContext</emphasis> interface and plays an important role + in the event delivery model explained in the previous section. That interface gives full control over the + delivery of the event to ascendant nodes in the hierarchy, even more it gives the possiblity to replace + the current event being delivered by a new event that will be transformed into the corresponding portal + behavior. However there are no guarantees that the portal will turn the returned event into a portal + behavior, here the portal provides a best effort policy, indeed sometime it is not possible to achieve + the substitution of one event by another.</para> + <para>Here the simplest implementation of a listener that does nothing except than correctly passing + the control to a parent event listener if there is one.</para> + <programlisting><![CDATA[ +public PortalNodeEvent onEvent(PortalNodeEventContext context, PortalNodeEvent event) +{ + return context.dispatch(); +} +]]></programlisting> + <para>The method <emphasis>PortalNode getNode()</emphasis> returns the current node being selected + during the event bubbler dispatching mechanism.</para> + </sect3> </sect2> <sect2> + <title>Portal session events</title> + <para>The life cycle of the session of the portal associated with the user can also raise events.</para> + </sect2> + <sect2> <title>Portal user events</title> - <para>The life cycle of the user can also raise events such as .</para> + <para>The life cycle of the user can also raise events such as its authentication.</para> </sect2> </sect1> <sect1>