From portal-commits at lists.jboss.org Wed Mar 21 14:56:45 2007
Content-Type: multipart/mixed; boundary="===============6440732746993046788=="
MIME-Version: 1.0
From: portal-commits at lists.jboss.org
To: portal-commits at lists.jboss.org
Subject: [portal-commits] JBoss Portal SVN: r6791 -
 docs/trunk/referenceGuide/en/modules.
Date: Wed, 21 Mar 2007 14:56:43 -0400
Message-ID: <E1HU5zH-0005qY-Vi@committer01.frg.pub.inap.atl.jboss.com>

--===============6440732746993046788==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

Author: julien(a)jboss.com
Date: 2007-03-21 14:56:43 -0400 (Wed, 21 Mar 2007)
New Revision: 6791

Modified:
   docs/trunk/referenceGuide/en/modules/contentIntegration.xml
Log:
improved the content integration chapter

Modified: docs/trunk/referenceGuide/en/modules/contentIntegration.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- docs/trunk/referenceGuide/en/modules/contentIntegration.xml	2007-03-21 =
18:22:58 UTC (rev 6790)
+++ docs/trunk/referenceGuide/en/modules/contentIntegration.xml	2007-03-21 =
18:56:43 UTC (rev 6791)
@@ -85,54 +85,297 @@
          </para>
       </sect2>
       <sect2>
-         <title>Example</title>
+         <title>Step by step example of a content driven portlet</title>
          <para></para>
-         <programlisting><![CDATA[
-
-public class FileContentPortlet extends GenericPortlet
+         <sect3>
+            <title>The Portlet skeleton</title>
+            <para>Here is the base skeleton of the content portlet. The FS=
ContentDrivenPortlet shows the files which are
+            in the war file in which the portlet is deployed. The arbitrar=
y name <emphasis>filesystem</emphasis>
+            will be the content type interpreted by the portlet.
+            </para>
+            <programlisting><![CDATA[
+public class FSContentDrivenPortlet extends GenericPortlet
 {
 =

+   /** The edit_content mode. */
    public static final PortletMode EDIT_CONTENT_MODE =3D new PortletMode("=
edit_content");
 =

-   /**
-    * Additional dispatch for the edit content mode.
-    */
-   protected void doDispatch(RenderRequest req, RenderResponse resp) throw=
s PortletException, PortletSecurityException, IOException
+   ...
+
+}
+]]></programlisting>
+         </sect3>
+         <sect3>
+            <title>Overriding the dispatch method</title>
+            <para>First the <emphasis>doDispatch(RenderRequest req, Render=
Response resp)</emphasis> is overriden in order
+            to branch the requeset flow to a method that will take care of=
 displaying the editor.</para>
+            <programlisting><![CDATA[
+protected void doDispatch(RenderRequest req, RenderResponse resp) throws P=
ortletException, PortletSecurityException, IOException
+{
+   if (EDIT_CONTENT_MODE.equals(req.getPortletMode()))
    {
-      if (EDIT_CONTENT.equals(req.getPortletMode()))
+      doEditContent(req, resp);
+   }
+   else
+   {
+      super.doDispatch(req, resp);
+   }
+}
+]]></programlisting>
+         </sect3>
+         <sect3>
+            <title>Utilities methods</title>
+            <para>The portlet also needs a few utilities methods which tak=
e care of converting content URI to a file
+            back and forth. There is also an implementation of a file filt=
er that keep only text files and avoid the
+            WEB-INF directory of the war file for security reasons.</para>
+            <programlisting><![CDATA[
+protected File getFile(String contentURI) throws IOException
+{
+   String realPath =3D getPortletContext().getRealPath(contentURI);
+   if (realPath =3D=3D null)
+   {
+      throw new IOException("Cannot access war file content");
+   }
+   File file =3D new File(realPath);
+   if (!file.exists())
+   {
+      throw new IOException("File " + contentURI + " does not exist");
+   }
+   return file;
+}
+]]></programlisting>
+            <programlisting><![CDATA[
+   protected String getContentURI(File file) throws IOException
+   {
+      String rootPath =3D getPortletContext().getRealPath("/");
+      if (rootPath =3D=3D null)
       {
-         doEditContent(req, resp);
+         throw new IOException("Cannot access war file content");
       }
-      else
+
+      // Make it canonical
+      rootPath =3D new File(rootPath).getCanonicalPath();
+
+      // Get the portion of the path that is significant for us
+      String filePath =3D file.getCanonicalPath();
+      return filePath.length() >=3D rootPath.length() ? filePath.substring=
(rootPath.length()) : null;
+   }
+]]></programlisting>
+            <programlisting><![CDATA[
+   private final FileFilter filter =3D new FileFilter()
+   {
+      public boolean accept(File file)
       {
-         super.doDispatch(req, resp);
+         String name =3D file.getName();
+         if (file.isDirectory())
+         {
+            return !"WEB-INF".equals(name);
+         }
+         else if (file.isFile())
+         {
+            return name.endsWith(".txt");
+         }
+         else
+         {
+            return false;
+         }
       }
+   };
+]]></programlisting>
+         </sect3>
+         <sect3>
+            <title>The editor</title>
+            <para>The editor is probably the longest part of the portlet. =
It tries to stay simple though and goes directly
+            to the point.</para>
+            <programlisting><![CDATA[
+protected void doEditContent(RenderRequest req, RenderResponse resp) throw=
s PortletException, PortletSecurityException, IOException
+{
+   // Get the uri value optionally provided by the portal
+   String uri =3D req.getParameter("content.uri");
+
+   // Get the working directory directory
+   File workingDir;
+   if (uri !=3D null)
+   {
+      workingDir =3D getFile(uri).getParentFile();
    }
+   else
+   {
+      // Otherwise try to get the current directory we are browsing, if no=
 current dir exist we use the root
+      String currentDir =3D req.getParameter("current_dir");
+      if (currentDir =3D=3D null)
+      {
+         currentDir =3D "/";
+      }
+      workingDir =3D getFile(currentDir);
+   }
 =

-   protected void doEditContent(RenderRequest req, RenderResponse resp) th=
rows PortletException, PortletSecurityException, IOException
+   // Get the parent path
+   String parentPath =3D getContentURI(workingDir.getParentFile());
+
+   // Get the children of the selected file, we use a filter to retain onl=
y text files and avoid WEB-INF dir
+   File[] children =3D workingDir.listFiles(filter);
+
+   // Configure the response
+   resp.setContentType("text/html");
+   PrintWriter writer =3D resp.getWriter();
+
+   //
+   writer.print("Directories:<br/>");
+   writer.print("<ul>");
+   PortletURL choseDirURL =3D resp.createRenderURL();
+   if (parentPath !=3D null)
    {
-      // Get the uri value either provided by the portal or by ourself
-      String uri =3D req.getParameter("content.uri");
-      File root =3D null;
-      if (uri =3D=3D null)
+      choseDirURL.setParameter("current_dir", parentPath);
+      writer.print("<li><a href=3D\"" + choseDirURL + "\">..</a></li>");
+   }
+   for (int i =3D 0;i < children.length;i++)
+   {
+      File child =3D children[i];
+      if (child.isDirectory())
       {
-         root =3D "/";
+         choseDirURL.setParameter("current_dir", getContentURI(child));
+         writer.print("<li><a href=3D\"" + choseDirURL + "\">" + child.get=
Name() + "</a></li>");
       }
-      else
+   }
+   writer.print("</ul><br/>");
+
+   //
+   writer.print("Files:<br/>");
+   writer.print("<ul>");
+   PortletURL selectFileURL =3D resp.createActionURL();
+   selectFileURL.setParameter("content.action.select", "select");
+   for (int i =3D 0;i < children.length;i++)
+   {
+      File child =3D children[i];
+      if (child.isFile())
       {
-         root =3D new File(uri).getParentFile().getCanonicalPath();
+         selectFileURL.setParameter("content.uri", getContentURI(child));
+         writer.print("<li><a href=3D\"" + selectFileURL + "\">" + child.g=
etName() + "</a></li>");
       }
+   }
+   writer.print("</ul><br/>");
 =

-      // Get the children of the selected file
-      File fic =3D new File(uri);
-      File[] children =3D fic.listFiles();
+   //
+   writer.close();
+}
+]]></programlisting>
+         </sect3>
+         <sect3>
+            <title>Viewing content at runtime</title>
+            <para>Last but not least the portlet needs to implement the <e=
mphasis>doView(RenderRequest req, RenderResponse resp)</emphasis>
+            method in order to display the file that the portal window wan=
ts to show.</para>
+            <programlisting><![CDATA[
+protected void doView(RenderRequest req, RenderResponse resp) throws Portl=
etException, PortletSecurityException, IOException
+{
+   // Get the URI provided by the portal
+   String uri =3D req.getParameter("uri");
 =

+   // Configure the response
+   resp.setContentType("text/html");
+   PrintWriter writer =3D resp.getWriter();
+
+   //
+   if (uri =3D=3D null)
+   {
+      writer.print("No selected file");
    }
+   else
+   {
+      File file =3D getFile(uri);
+      FileInputStream in =3D null;
+      try
+      {
+         in =3D new FileInputStream(file);
+         FileChannel channel =3D in.getChannel();
+         byte[] bytes =3D new byte[(int)channel.size()];
+         ByteBuffer buffer =3D ByteBuffer.wrap(bytes);
+         channel.read(buffer);
+         writer.write(new String(bytes, 0, bytes.length, "UTF8"));
+      }
+      catch (FileNotFoundException e)
+      {
+         writer.print("No such file " + uri);
+         getPortletContext().log("Cannot find file " + uri, e);
+      }
+      finally
+      {
+         if (in !=3D null)
+         {
+            in.close();
+         }
+      }
+   }
 =

-
+   //
+   writer.close();
 }
-
 ]]></programlisting>
+         </sect3>
+         <sect3>
+            <title>Hooking the portlet into the portal</title>
+            <para>Finally we need to make the portal aware of the fact tha=
t the portlet can edit and interpret. For that
+            we need various descriptors. The <emphasis>portlet.xml</emphas=
is> descriptor will define our portlet, the
+            <emphasis>portlet-instances.xml</emphasis> will create a singl=
e instance of our portlet and finally the
+            <emphasis>web.xml</emphasis> descriptor will contain a servlet=
 context listener that will hook the content
+            type in the portal content type registry.</para>
+            <programlisting><![CDATA[
+<?xml version=3D"1.0" encoding=3D"UTF-8"?>
+<portlet-app
+   xmlns=3D"http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
+   xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance"
+   xsi:schemaLocation=3D"http://java.sun.com/xml/ns/portlet/portlet-app_1_=
0.xsd http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
+   version=3D"1.0">
+   ...
+   <portlet>
+      <description>File System Content Driven Portlet</description>
+      <portlet-name>FSContentDrivenPortlet</portlet-name>
+      <display-name>File System Content Driven Portlet</display-name>
+      <portlet-class>org.jboss.portal.core.portlet.test.FSContentDrivenPor=
tlet</portlet-class>
+      <supports>
+         <mime-type>text/html</mime-type>
+      </supports>
+      <portlet-info>
+         <title>File Portlet</title>
+         <keywords>sample,test</keywords>
+      </portlet-info>
+   </portlet>
+   ...
+</portlet-app>
+]]></programlisting>
+            <para>The portlet.xml descriptor</para>
+            <programlisting><![CDATA[
+<deployments>
+   ...
+   <deployment>
+      <instance>
+         <instance-id>FSContentDrivenPortletInstance</instance-id>
+         <portlet-ref>FSContentDrivenPortlet</portlet-ref>
+      </instance>
+   </deployment>
+   ...
+</deployments
+]]></programlisting>
+            <para>The portlet-instances.xml descriptor</para>
+            <programlisting><![CDATA[
+<web-app>
+   ...
+   <context-param>
+      <param-name>org.jboss.portal.content_type</param-name>
+      <param-value>filesystem</param-value>
+   </context-param>
+   <context-param>
+      <param-name>org.jboss.portal.portlet_instance</param-name>
+      <param-value>FSContentDrivenPortletInstance</param-value>
+   </context-param>
+   <listener>
+      <listener-class>org.jboss.portal.core.servlet.jsp.ContentTypeRegistr=
ation</listener-class>
+   </listener>
+   ...
+</web-app>
+]]></programlisting>
+            <para>The web.xml descriptor</para>
+         </sect3>
       </sect2>
    </sect1>
 </chapter>


--===============6440732746993046788==--