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>