Author: julien(a)jboss.com Date: 2007-04-29 09:48:37 -0400 (Sun, 29 Apr 2007) New Revision: 7131 Added: docs/trunk/referenceGuide/en/images/content/all.png docs/trunk/referenceGuide/en/images/portalapi/NavigationalStateContext.png docs/trunk/referenceGuide/en/images/portalapi/PortalEvent.png docs/trunk/referenceGuide/en/images/portalapi/PortalEventContext.png docs/trunk/referenceGuide/en/images/portalapi/PortalEventListener.png docs/trunk/referenceGuide/en/images/portalapi/PortalRuntimeContext.png Modified: docs/trunk/referenceGuide/en/modules/installation.xml docs/trunk/referenceGuide/en/modules/portalapi.xml Log: more portal api doc Added: docs/trunk/referenceGuide/en/images/content/all.png =================================================================== (Binary files differ) Property changes on: docs/trunk/referenceGuide/en/images/content/all.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: docs/trunk/referenceGuide/en/images/portalapi/NavigationalStateContext.png =================================================================== (Binary files differ) Property changes on: docs/trunk/referenceGuide/en/images/portalapi/NavigationalStateContext.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: docs/trunk/referenceGuide/en/images/portalapi/PortalEvent.png =================================================================== (Binary files differ) Property changes on: docs/trunk/referenceGuide/en/images/portalapi/PortalEvent.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: docs/trunk/referenceGuide/en/images/portalapi/PortalEventContext.png =================================================================== (Binary files differ) Property changes on: docs/trunk/referenceGuide/en/images/portalapi/PortalEventContext.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: docs/trunk/referenceGuide/en/images/portalapi/PortalEventListener.png =================================================================== (Binary files differ) Property changes on: docs/trunk/referenceGuide/en/images/portalapi/PortalEventListener.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: docs/trunk/referenceGuide/en/images/portalapi/PortalRuntimeContext.png =================================================================== (Binary files differ) Property changes on: docs/trunk/referenceGuide/en/images/portalapi/PortalRuntimeContext.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Modified: docs/trunk/referenceGuide/en/modules/installation.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/installation.xml 2007-04-29 13:00:50 UTC (rev 7130) +++ docs/trunk/referenceGuide/en/modules/installation.xml 2007-04-29 13:48:37 UTC (rev 7131) @@ -40,9 +40,9 @@ Application Server 4.0.4.GA) that prevents the complete deployment of JBoss Portal's WSRP service if the user is not online or behind a firewall/proxy. This, in turn, prevents the deployment of JBoss Portal. If you do not need the WSRP service, you can remove the - <emphasis>portal-wsrp.sar</emphasis> + <filename>portal-wsrp.sar</filename> file from the - <emphasis>jboss-portal.sar</emphasis> + <filename>jboss-portal.sar</filename> file. If you'd like to use the WSRP service, the JBoss WS issue has been addressed in version 1.0.2.GA of JBoss WS. Please follow the instructions on <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=WSRP_UpdateJBossWS&quo... to upgrade JBoss WS</ulink> @@ -73,13 +73,13 @@ <para> <emphasis role="bold">Extract the bundle:</emphasis> Extract the zip archive to a directory of your choosing. In windows, we - recommend, C:\jboss-X.X.X + recommend, <command>C:\jboss-X.X.X</command> </para> </listitem> <listitem> <para> <emphasis role="bold">Start the Server:</emphasis> - Go to JBOSS_INSTALL_DIRECTORY/bin and execute run.bat (run.sh, if + Go to JBOSS_INSTALL_DIRECTORY/bin and execute <command>run.bat</command> (<command>run.sh</command>, if Linux) </para> </listitem> @@ -103,7 +103,7 @@ <sect1 id="install_binary"> <title>Installing from Binary Download</title> <para>The binary download package typically consists of the - <emphasis>jboss-portal.sar</emphasis> + <filename>jboss-portal.sar</filename> , documentation (which you are already reading), and a set of preconfigured datasource descriptors that allow JBoss Portal to communicate with a database. </para> @@ -169,7 +169,7 @@ <emphasis role="bold">Deploy your JDBC connector:</emphasis> You must make available a JDBC connector for JBoss Portal to communicate with your database. The connector lib should be placed in - <emphasis>JBOSS_INSTALL_DIRECTORY/server/default/lib/*</emphasis> + <filename>JBOSS_INSTALL_DIRECTORY/server/default/lib/*</filename> </para> </listitem> </orderedlist> @@ -219,13 +219,13 @@ Copy the datasource descriptor file (*-ds.xml) you modified above AND the <emphasis>jboss-portal.sar</emphasis> from the download folder to - <emphasis>JBOSS_INSTALL_DIRECTORY/server/default/deploy/.</emphasis> + <filename>JBOSS_INSTALL_DIRECTORY/server/default/deploy/.</filename> </para> </listitem> <listitem> <para> <emphasis role="bold">Start the Server:</emphasis> - Go to JBOSS_INSTALL_DIRECTORY/bin and execute run.bat (run.sh, if + Go to <filename>JBOSS_INSTALL_DIRECTORY/bin</filename> and execute <command>run.bat</command> (<command>run.sh</command>, if Linux) </para> </listitem> @@ -309,7 +309,7 @@ <sect3 id="install_source_env"> <title>Operating System Environment Setting</title> <para>For the build targets to work, you must first set the - <emphasis>JBOSS_HOME</emphasis> + <filename>JBOSS_HOME</filename> environment variable in your operating system, to the root directory of the JBoss Application Server installation. </para> @@ -320,7 +320,7 @@ section, click <emphasis>New</emphasis> . You will be setting the - <emphasis>JBOSS_HOME</emphasis> + <filename>JBOSS_HOME</filename> environment variable to the location of your JBoss Application Server installation: <mediaobject> <imageobject> @@ -330,7 +330,7 @@ </para> <para> On a Unix-like Operating System, you would accomplish this by typing: - <programlisting>export JBOSS_HOME=/path/to/your/jboss/directory</programlisting> + <command>export JBOSS_HOME=/path/to/your/jboss/directory</command> </para> </sect3> <sect3> @@ -357,7 +357,7 @@ <emphasis role="bold">Deploy your JDBC connector:</emphasis> You must make available a JDBC connector for JBoss Portal to communicate with your database. The connector lib should be placed in - <emphasis>JBOSS_HOME/server/default/lib/*</emphasis> + <filename>JBOSS_HOME/server/default/lib/*</filename> </para> </listitem> </orderedlist> @@ -373,7 +373,7 @@ </para> <para> Navigate to - <emphasis>JBOSS_PORTAL_HOME_DIRECTORY/core</emphasis> + <filename>JBOSS_PORTAL_HOME_DIRECTORY/core</filename> and type: <programlisting>build datasource</programlisting> <mediaobject> @@ -411,14 +411,14 @@ Now <emphasis role="bold">copy</emphasis> your datasource descriptor to - <emphasis>JBOSS_HOME/server/default/deploy</emphasis> + <filename>JBOSS_HOME/server/default/deploy</filename> </para> </sect3> </sect2> <sect2> <title>Building/Deploying from Sources</title> <para>To build and deploy the JBoss Portal service, go to - <emphasis>JBOSS_PORTAL_HOME_DIRECTORY/build</emphasis> + <filename>JBOSS_PORTAL_HOME_DIRECTORY/build</filename> and type: <programlisting>build deploy</programlisting> <mediaobject> @@ -427,23 +427,23 @@ </imageobject> </mediaobject> <note>To build the clustered version, you will need to go to - <emphasis>JBOSS_PORTAL_HOME_DIRECTORY/build</emphasis> + <filename>JBOSS_PORTAL_HOME_DIRECTORY/build</filename> and type: - <programlisting>build main</programlisting> + <command>build main</command> Then, go to - <emphasis>JBOSS_PORTAL_HOME_DIRECTORY/core</emphasis> + <filename>JBOSS_PORTAL_HOME_DIRECTORY/core</filename> and type: - <programlisting>build deploy-ha</programlisting> + <command>build deploy-ha</command> This will copy the - <emphasis>jboss-portal-ha.sar</emphasis> + <filename>jboss-portal-ha.sar</filename> to your - <emphasis>all</emphasis> + <filename>all</filename> configuration for you. </note> At the end of the build process, the - <emphasis>jboss-portal.sar</emphasis> + <filename>jboss-portal.sar</filename> is copied to - <emphasis>JBOSS_HOME/server/default/deploy</emphasis> + <filename>JBOSS_HOME/server/default/deploy</filename> : <mediaobject> <imageobject> @@ -451,7 +451,7 @@ </imageobject> </mediaobject> Please verify that your - <emphasis>JBOSS_HOME/server/default/deploy</emphasis> + <filename>JBOSS_HOME/server/default/deploy</filename> directory, contains both necessary files before starting JBoss Application Server. </para> <para> @@ -505,7 +505,7 @@ </listitem> <listitem> <para>After you have downloaded the installer jar, you can execute it with - <emphasis>java -jar xxxx-installer.jar</emphasis> + <command>java -jar xxxx-installer.jar</command> </para> </listitem> <listitem> @@ -564,7 +564,7 @@ </listitem> <listitem> <para>Now, start JBoss AS, by executing - <emphasis>INSTALL_PATH/bin/run.bat</emphasis> + <command>INSTALL_PATH/bin/run.bat</command> . The initial startup process will create all of the necessary portal tables in the embedded Hypersonic database. <note>This will require JDK5+</note> Modified: docs/trunk/referenceGuide/en/modules/portalapi.xml =================================================================== --- docs/trunk/referenceGuide/en/modules/portalapi.xml 2007-04-29 13:00:50 UTC (rev 7130) +++ docs/trunk/referenceGuide/en/modules/portalapi.xml 2007-04-29 13:48:37 UTC (rev 7131) @@ -46,21 +46,6 @@ it makes the assumption that the underlying object is of type Portlet.</note> </sect1> <sect1> - <title>Portal session</title> - <mediaobject> - <imageobject> - <imagedata width="28em" align="center" fileref="images/portalapi/PortalSession.png" format="png"/> - </imageobject> - <caption> - <para>The PortalSession interface</para> - </caption> - </mediaobject> - <para>It is possible to have access to a portion of the portal session to store objects. The <emphasis>org.jboss.portal.api.PortalSession</emphasis> - interface defines its API and is similar to the <emphasis>javax.servlet.http.HttpSession</emphasis> except that it does - not offer methods to invalidate the session as the session is managed by the portal. - </para> - </sect1> - <sect1> <title>Portal URL</title> <para>The Portal API defines the <emphasis>org.jboss.portal.api.PortalURL</emphasis> interface to represent URL managed by the portal.</para> @@ -85,6 +70,39 @@ </itemizedlist> </sect1> <sect1> + <title>Portal session</title> + <mediaobject> + <imageobject> + <imagedata width="28em" align="center" fileref="images/portalapi/PortalSession.png" format="png"/> + </imageobject> + <caption> + <para>The PortalSession interface</para> + </caption> + </mediaobject> + <para>It is possible to have access to a portion of the portal session to store objects. The <emphasis>org.jboss.portal.api.session.PortalSession</emphasis> + interface defines its API and is similar to the <emphasis>javax.servlet.http.HttpSession</emphasis> except that it does + not offer methods to invalidate the session as the session is managed by the portal. + </para> + </sect1> + + <sect1> + <title>Portal runtime context</title> + <mediaobject> + <imageobject> + <imagedata width="28em" align="center" fileref="images/portalapi/PortalRuntimeContext.png" format="png"/> + </imageobject> + <caption> + <para>The PortalRuntimeContext interface</para> + </caption> + </mediaobject> + <para>The <emphasis>org.jboss.portal.api.PortalRuntimeContext</emphasis> gives access to state or operations + associated at runtime with the current user of the portal. It allows to retrieve the user id when the method + <emphasis>String getUserId()</emphasis> returns a non null string. It also gives access to the + <emphasis>PortalSession</emphasis> instance associated with the current user. Finally it gives access to the + <emphasis>NavigationalStateContext</emphasis> associated with the current user.</para> + </sect1> + + <sect1> <title>Portal nodes</title> <para>The portal structure is a tree formed by nodes. It is possible to programmatically access the portal tree in order to </para> @@ -123,10 +141,11 @@ <listitem>PortalNode.TYPE_WINDOW : the node represents a page window</listitem> </itemizedlist> <para>The <emphasis>org.jboss.portal.api.node.PortalNodeURL</emphasis> is an extension of the <emphasis>PortalURL</emphasis> interface - which adds additional methods useful for setting - parameters on the URL. There are no guarantees that the portal node will use the parameters. So far portal node - URL parameters are only useful for nodes of type <emphasis>PortalNode.TYPE_WINDOW</emphasis> and they should - be treated as portlet render parameters in the case of the portlet is a local portlet and is not a remote portlet.</para> + which adds additional methods useful for setting parameters on the URL. There are no guarantees that the + portal node will use the parameters. So far portal node URL parameters are only useful for nodes of type + <emphasis>PortalNode.TYPE_WINDOW</emphasis> and they should be treated as portlet render parameters in the case of + the portlet is a local portlet and is not a remote portlet. The method that creates portal node URL requires + as parameter an instance of <emphasis>PortalRuntimeContext</emphasis>.</para> <para>The interface also offers methods to navigate the node hierarchy:</para> <programlisting><![CDATA[ public interface PortalNode @@ -141,22 +160,81 @@ ]]></programlisting> </sect1> <sect1> + <title>Portal navitational state</title> + <para>The navigational state is a state managed by the portal that associates to each user the state triggered + by its navigation. A well known part of the navigational state are the render parameters provided at runtime + during the call of the method <emphasis>void render(RenderRequest req, RenderResponse resp)</emphasis>. The portal + API offers an interface to query and update the navigational state of the portal. For now the API only exposes + mode and window states of portal nodes of type window.</para> + <mediaobject> + <imageobject> + <imagedata width="28em" align="center" fileref="images/portalapi/NavigationalStateContext.png" format="png"/> + </imageobject> + <caption> + <para>The NavigationalStateContext interface</para> + </caption> + </mediaobject> + </sect1> + <sect1> <title>Portal events</title> - <para>todo</para> + <para>Portal events are a powerful mechanism to be aware of what is happening in the portal at runtime. The base + package for event is <emphasis>org.jboss.portal.api.event</emphasis> and it contains the common event classes + and interfaces. + </para> + <mediaobject> + <imageobject> + <imagedata width="28em" align="center" fileref="images/portalapi/PortalEvent.png" format="png"/> + </imageobject> + <caption> + <para>The PortalEvent class</para> + </caption> + </mediaobject> + <para>The <emphasis>org.jboss.portal.api.event.PortalEvent</emphasis> abstract class is the base class for + all kind of portal events. + </para> + <mediaobject> + <imageobject> + <imagedata width="28em" align="center" fileref="images/portalapi/PortalEventContext.png" format="png"/> + </imageobject> + <caption> + <para>The PortalEventContext interface</para> + </caption> + </mediaobject> + <para> + The <emphasis>org.jboss.portal.api.event.PortalEventContext</emphasis> interface defines the context in which + an event is created and propagated. It allows to retrieve the <emphasis>PortalRuntimeContext</emphasis> in + order to obtain the portal context. Note that this method may return null if no context is available. + </para> + <mediaobject> + <imageobject> + <imagedata width="28em" align="center" fileref="images/portalapi/PortalEventListener.png" format="png"/> + </imageobject> + <caption> + <para>The PortalEventListener interface</para> + </caption> + </mediaobject> + <para> + The <emphasis>org.jboss.portal.api.event.PortalEventListener</emphasis> interface defines the contract that + 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> + <important> + The event propagation model is to use 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> <sect2> <title>Portal node events</title> - <para>todo</para> + <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, a corresponding + event will be fired.</para> </sect2> <sect2> <title>Portal user events</title> - <para>todo</para> + <para>The life cycle of the user can also raise events such as .</para> </sect2> </sect1> <sect1> - <title>Portal navitational state</title> - <para>todo</para> - </sect1> - <sect1> <title>Examples</title> <para>todo</para> </sect1>