8:48 a.m.
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>