5:53 p.m.
Author: julien(a)jboss.com
Date: 2007-04-28 18:53:07 -0400 (Sat, 28 Apr 2007)
New Revision: 7126
Added:
docs/trunk/referenceGuide/en/images/portalapi/
docs/trunk/referenceGuide/en/images/portalapi/Mode.png
docs/trunk/referenceGuide/en/images/portalapi/PortalNode.png
docs/trunk/referenceGuide/en/images/portalapi/PortalNodeURL.png
docs/trunk/referenceGuide/en/images/portalapi/PortalSession.png
docs/trunk/referenceGuide/en/images/portalapi/PortalURL.png
docs/trunk/referenceGuide/en/images/portalapi/WindowState.png
Modified:
docs/trunk/referenceGuide/en/master.xml
docs/trunk/referenceGuide/en/modules/portalapi.xml
Log:
started to put content in the portal api chapter
Added: docs/trunk/referenceGuide/en/images/portalapi/Mode.png
===================================================================
(Binary files differ)
Property changes on: docs/trunk/referenceGuide/en/images/portalapi/Mode.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: docs/trunk/referenceGuide/en/images/portalapi/PortalNode.png
===================================================================
(Binary files differ)
Property changes on: docs/trunk/referenceGuide/en/images/portalapi/PortalNode.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: docs/trunk/referenceGuide/en/images/portalapi/PortalNodeURL.png
===================================================================
(Binary files differ)
Property changes on: docs/trunk/referenceGuide/en/images/portalapi/PortalNodeURL.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: docs/trunk/referenceGuide/en/images/portalapi/PortalSession.png
===================================================================
(Binary files differ)
Property changes on: docs/trunk/referenceGuide/en/images/portalapi/PortalSession.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: docs/trunk/referenceGuide/en/images/portalapi/PortalURL.png
===================================================================
(Binary files differ)
Property changes on: docs/trunk/referenceGuide/en/images/portalapi/PortalURL.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: docs/trunk/referenceGuide/en/images/portalapi/WindowState.png
===================================================================
(Binary files differ)
Property changes on: docs/trunk/referenceGuide/en/images/portalapi/WindowState.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Modified: docs/trunk/referenceGuide/en/master.xml
===================================================================
--- docs/trunk/referenceGuide/en/master.xml 2007-04-28 16:05:14 UTC (rev 7125)
+++ docs/trunk/referenceGuide/en/master.xml 2007-04-28 22:53:07 UTC (rev 7126)
@@ -26,6 +26,7 @@
<!ENTITY security SYSTEM "modules/security.xml">
<!ENTITY troubleshooting SYSTEM "modules/troubleshooting.xml">
<!ENTITY contentIntegration SYSTEM
"modules/contentIntegration.xml">
+ <!ENTITY portalapi SYSTEM "modules/portalapi.xml">
]>
<book lang="en">
<bookinfo>
@@ -67,6 +68,7 @@
<!-- deployment desc --> &xmldescriptors;
<!-- understanding urls --> &urls;
<!-- Content integration --> &contentIntegration;
+ <!-- Portal API --> &portalapi;
<!-- IPC --> &ipc;
<!-- clustering configuration --> &clustering;
<!-- WSRP --> &wsrp;
Modified: docs/trunk/referenceGuide/en/modules/portalapi.xml
===================================================================
--- docs/trunk/referenceGuide/en/modules/portalapi.xml 2007-04-28 16:05:14 UTC (rev 7125)
+++ docs/trunk/referenceGuide/en/modules/portalapi.xml 2007-04-28 22:53:07 UTC (rev 7126)
@@ -10,28 +10,135 @@
<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 of the API is tied to the major
version which means
+ 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
+ very early before the official Portal API framework was created.</para>
+ <para>The Portlet API defines two classes that represents a portion of the
visual state of a Portlet which
+ 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>
+ </itemizedlist>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center"
fileref="images/portalapi/Mode.png" format="png"/>
+ </imageobject>
+ <caption>
+ <para>The Mode class</para>
+ </caption>
+ </mediaobject>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center"
fileref="images/portalapi/WindowState.png" format="png"/>
+ </imageobject>
+ <caption>
+ <para>The WindowState class</para>
+ </caption>
+ </mediaobject>
+ <note>In the Portal API, the <emphasis>Mode</emphasis> interface
is named like this because it does
+ represent the mode of some visual object. The Portlet API names it
<emphasis>PortletMode</emphasis> because
+ it makes the assumption that the underlying object is of type
Portlet.</note>
</sect1>
<sect1>
<title>Portal session</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata 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>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center"
fileref="images/portalapi/PortalURL.png" format="png"/>
+ </imageobject>
+ <caption>
+ <para>The PortalURL interface</para>
+ </caption>
+ </mediaobject>
+ <itemizedlist>
+ <listitem>The <emphasis>setAuthenticated(Boolean
wantAuthenticated)</emphasis> methods defines if the
+ URL requires the authentication of the user. If the argument value is true then
the user must be authenticated
+ to access the URL, if the argument value is false then the user should not be
authenticated. Finally if the argument value is
+ null then it means that the URL authenticated mode should reuse the current
mode.</listitem>
+ <listitem>The <emphasis>setSecure(Boolean
wantSecure)</emphasis> methods defines the same as above but for the
+ transport guarantee offered by the underlying protocol which means most of the
time the secure HTTP protocol.</listitem>
+ <listitem>The <emphasis>setRelative(boolean
relative)</emphasis> defines the output format of the URL and
+ whether the created URL will be an URL relative to the same web server or will
be the full URL.</listitem>
+ <listitem>The <emphasis>toString()</emphasis> method will
create the URL as a string.</listitem>
+ </itemizedlist>
</sect1>
<sect1>
<title>Portal nodes</title>
- <para>The portal structure is a tree formed by nodes. It is possible to
access that tree in order to
+ <para>The portal structure is a tree formed by nodes. It is possible to
programmatically access the portal tree in order to
</para>
<itemizedlist>
<listitem>discover the tree structure of the portal</listitem>
<listitem>create URL that will render the different portal
nodes</listitem>
<listitem>access the properties of a specific node</listitem>
</itemizedlist>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center"
fileref="images/portalapi/PortalNode.png" format="png"/>
+ </imageobject>
+ <caption>
+ <para>The PortalNode interface</para>
+ </caption>
+ </mediaobject>
+ <para>As usual with tree structures, the main interface to study is the
<emphasis>org.jboss.portal.api.node.PortalNode</emphasis>. That interface
+ is intentionally intended for obtaining useful information from the tree. It is not
possible to use it to modify
+ the tree shape because it is not intended to be a management
interface.</para>
<programlisting><![CDATA[
-
+public interface PortalNode
+{
+ int getType();
+ String getName();
+ String getDisplayName(Locale locale);
+ Map getProperties();
+ PortalNodeURL createURL(PortalRuntimeContext portalRuntimeContext);
+ ...
+}
]]></programlisting>
+ <para>The interface offers methods to retrieve informations for a given node
such as the node type, the node name
+ or the properties of the node. The noticeable node types are:</para>
+ <itemizedlist>
+ <listitem>PortalNode.TYPE_PORTAL : the node represents a
portal</listitem>
+ <listitem>PortalNode.TYPE_PAGE : the node represents a portal
page</listitem>
+ <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>
+ <para>The interface also offers methods to navigate the node
hierarchy:</para>
+ <programlisting><![CDATA[
+public interface PortalNode
+{
+ ...
+ PortalNode getChild(String name);
+ Collection getChildren();
+ PortalNode getRoot();
+ PortalNode getParent();
+ ...
+}
+]]></programlisting>
</sect1>
<sect1>
<title>Portal events</title>