portals-pluto-scm mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cdore...@apache.org
Subject svn commit: r395454 - /portals/pluto/trunk/pluto-site/src/site/xdoc/v11/deploying.xml
Date Thu, 20 Apr 2006 00:43:55 GMT
Author: cdoremus
Date: Wed Apr 19 17:43:53 2006
New Revision: 395454

URL: http://svn.apache.org/viewcvs?rev=395454&view=rev
Log:
Extensive re-writing including adding an example pom.xml file that does assembly and deployment.

Modified:
    portals/pluto/trunk/pluto-site/src/site/xdoc/v11/deploying.xml

Modified: portals/pluto/trunk/pluto-site/src/site/xdoc/v11/deploying.xml
URL: http://svn.apache.org/viewcvs/portals/pluto/trunk/pluto-site/src/site/xdoc/v11/deploying.xml?rev=395454&r1=395453&r2=395454&view=diff
==============================================================================
--- portals/pluto/trunk/pluto-site/src/site/xdoc/v11/deploying.xml (original)
+++ portals/pluto/trunk/pluto-site/src/site/xdoc/v11/deploying.xml Wed Apr 19 17:43:53 2006
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
-Copyright 2004 The Apache Software Foundation
+Copyright 2004-2006 The Apache Software Foundation
 Licensed  under the  Apache License,  Version 2.0  (the "License");
 you may not use  this file  except in  compliance with the License.
 You may obtain a copy of the License at
@@ -22,6 +22,7 @@
     <title>Deploying Portlet to Pluto Portal</title>
     <author email="zheng.at.apache.D0T.org">ZHENG Zhong</author>
     <author email="ddewolf@apache.org">David DeWolf</author>
+    <author email="cdoremus@apache.org">Craig Doremus</author>
   </properties>
   
   <body>
@@ -29,15 +30,15 @@
     <section name="Deploying Portlet to Pluto Portal">
       
       <p>
-        There are 3 steps of deployment:
+        There are 3 steps for deployment a portlet to Pluto 1.1:
         <ul>
           <li>
             <b>Assembly</b>: All portlet applications must be run through the
             pluto assembler before being deployed. The assembly process injects
             pluto specific information for deployment. Specifically, a servlet
-            and servlet mapping are added to the deployment descriptor. This
-            servlet will be used to dispatch portlet requests to the portlet
-            application.
+            and servlet mapping are added to the deployment descriptor (web.xml). 
+            This servlet (<code>org.apache.pluto.core.PortletServlet</code>)
will be 
+            used to dispatch portlet requests to the portlet application.
           </li>
           <li>
             <b>Deployment</b>: After portlet applications are assembled properly
@@ -48,111 +49,206 @@
             <b>Publishing</b>: All portlet applications that are to be used
             within the Pluto Portal must be published to the Portal. Publishing
             notifies the Portal Application that a portlet application is bound
-            (deployed) to a certain context within the appserver.
+            (deployed) to a certain context within the appserver. This is done
+            by adding records to <code>pluto-portal-driver-config.xml</code>.
           </li>
         </ul>
       </p>
       
-      <subsection name="Portlet Assembly using Maven">
+      <subsection name="Portlet Assembly and Deployment using Maven">
         <p>
-          Portlet assembly is accomplished during war creation by binding the
-          <code>pluto:assemble</code> goal to the process-resources lifecycle.
-          This may be done by adding a <code>plug-in</code> element to the
-          <code>build</code> element in your portlet application pom. An example
-          configuration follows:
+        As of the first beta release of Pluto 1.1, the plugins for assembly and 
+        deploment are partially completed.
+          Right now the maven-pluto-plugin correctly assembles the war with
+          the proper <code>PortletServlet</code> records to web.xml, but the

+          deployment plugin is not yet completed. We have created an example
+          pom.xml below that correctly assembles and deploys the portlet. 
+          This script requires
+          that you have installed the pluto-util, pluto-descriptor-api and
+          pluto-descriptor-impl into your local Maven repository. You can do this by
+          building Pluto from source or installing the files that come with the 
+          binary build and using the install:install-file goal (see the 
+          <a href="http://docs.codehaus.org/display/MAVENUSER/FAQs-1">Maven FAQ</a>).
+          
+          The custom Maven build shown below also deploys
+          a Tomcat context deployment descriptor that has the same name as your
+          artifactId with an xml extension (e.g. HelloWorldPortlet.xml)
         </p>
         <p>
-          <source><![CDATA[
-<build>
-  ... ...
-  <plugins>
-    ... ...
-    <plugin>
-      <artifactId>maven-pluto-plugin</artifactId>
-      <version>1.1.0-SNAPSHOT</version>
-      <executions>
-        <execution>
-          <phase>generate-resources</phase>
-          <goals>
-            <goal>assemble</goal>
-          </goals>
-        </execution>
-      </executions>
-    </plugin>
-    ... ...
-  <plugins>
-  ... ...
-</build> 
-          ]]></source>
-        </p>
-        <p>
-          The <code>pluto:assemble</code> goal will parse your portlet
-          application's <code>portlet.xml</code> and update <code>web.xml</code>
-          to include the appropriate resources. The updated <code>web.xml</code>
-          will reside in your project's <code>target/pluto-resources</code>
-          directory.
+          To properly assemble and deploy your portlet using the Maven script (pom.xml) below,

+          your project's directory structure and artifact placement must conform to Maven's
standard:
         </p>
         <p>
-          To include the updated <code>web.xml</code> in the final war artifact,
-          you should also configure the <code>maven-war-plugin</code> by telling
-          it where to find the webapp descriptor. An example configuration
-          follows:
           <source><![CDATA[
-<build>
-  ... ...
-  <plugins>
-    ... ...
-    <plugin>
-      <artifactId>maven-war-plugin</artifactId>
-      <configuration>
-        <webXml>${project.build.directory}/pluto-resources/web.xml</webXml>
-      </configuration>
-    </plugin>
-    ... ...
-  <plugins>
-  ... ...
-</build> 
+	MyPortlet (top level directory)
+	|- pom.xml (the pom file)
+	|- src (Subdir containing main subdirectory)
+	    |- main (Subdir containing java, resource and webapp subdirs)
+	    	|- java (java source code goes under here)
+		    |       `- com
+		    |           `- mycompany
+		    |               `- portlet
+		    |                   `- MyPortlet.java (portlet source)
+		    |- resource
+		    |	`- MyPortlet.xml (Tomcat context DD)
+		    |- webapp  (webapp resources (jsp, css, images) go under here)
+		    	`- jsp 
+		    		`- MyPortletView.jsp (for view mode)		    			    
+		    		`- MyPortletEdit.jsp (for edit mode)		    			    
+		    	`- WEB-INF
+			    	`- portlet.xml (JSR-168 deployment descriptor)
+			    	`- web.xml (This will be modified by maven-pluto-plugin)
           ]]></source>
         </p>
-      </subsection>
-      
-      <subsection name="Portlet Assembly using Ant Task">
-        <p>TBD</p>
-      </subsection>
-      
-      <subsection name="Portlet Deployment using Maven">
+
         <p>
-          You may deploy your proper-assembled portlet application to appserver
-          by using your favorite Maven appserver plugin or by invoking the
-          following:
+        This is an example of what the Tomcat context DD will contain:
           <source><![CDATA[
-$> cd <PORTLET-APP-HOME>
-$> maven pluto:deploy
+		<Context path="HelloWorldPortlet" 
+			docBase="..\PlutoDomain\HelloWorldPortlet.war" 
+			crossContext="true"/>        
           ]]></source>
         </p>
         <p>
-          NOTE: The deployment plugin is currently undergoing modifications
-          and may not be 100% functional.
+        The Maven pom file (pom.xml) is what defines the build. Our example overrides
+        the integration-test lifecycle phase in addition to using the maven-pluto-plugin
+        to assemble the war:
+          <source><![CDATA[
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+  
+  <!-- Change this to something akin to your java package structure -->
+  <groupId>com.mycompany.portlet</groupId>
+  <modelVersion>4.0.0</modelVersion>
+  <!-- Version of this app -->
+  <version>0.1-alpha1</version>
+  <!-- Base name of the war file without .war ext -->
+  <artifactId>HelloWorldPortlet</artifactId>
+  <packaging>war</packaging>
+  <name>${pom.artifactId}</name>
+  
+  <!-- Dependency Version Properties ======================================= -->
+  <properties>
+  	<!-- Change this for a new Pluto version -->
+    <pluto.version>1.1.0-beta1</pluto.version>
+    <portlet-api.version>1.0</portlet-api.version>
+    <servlet-api.version>2.3</servlet-api.version>
+    <jsp-api.version>2.0</jsp-api.version>
+    <junit.version>3.8.1</junit.version>
+  </properties>
+  
+  <dependencies>
+    <dependency>
+      <groupId>javax.portlet</groupId>
+      <artifactId>portlet-api</artifactId>
+      <version>${portlet-api.version}</version>
+      <scope>provided</scope>
+    </dependency>
+    <dependency>
+      <groupId>javax.servlet</groupId>
+      <artifactId>servlet-api</artifactId>
+      <version>${servlet-api.version}</version>
+      <scope>provided</scope>
+    </dependency>
+    <dependency>
+      <groupId>junit</groupId>
+      <artifactId>junit</artifactId>
+      <version>${junit.version}</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.apache.pluto</groupId>
+      <artifactId>pluto-util</artifactId>
+      <version>${pluto.version}</version>
+      <scope>provided</scope>
+    </dependency>
+    <!-- Any other build or deployment dependancies go here -->
+  </dependencies>
+  <build>
+    <finalName>${pom.name}</finalName>
+    <plugins>
+      <!-- configure maven-war-plugin to use updated web.xml -->
+      <plugin>
+        <artifactId>maven-war-plugin</artifactId>
+        <configuration>
+          <webXml>${project.build.directory}/pluto-resources/web.xml</webXml>
+        </configuration>
+      </plugin>
+      <!-- bind 'pluto:assemble' goal to 'process-resources' lifecycle -->
+      <plugin>
+        <artifactId>maven-pluto-plugin</artifactId>
+        <version>${pluto.version}</version>
+        <executions>
+          <execution>
+            <phase>generate-resources</phase>
+            <goals>
+              <goal>assemble</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+      <plugin>
+      	<!-- Override the 'integration-test' lifecycle phase
+      	with a custom one that runs a simple Ant script -->
+        <artifactId>maven-antrun-plugin</artifactId>
+        <executions>
+          <execution>
+            <phase>integration-test</phase>
+            <configuration>
+              <tasks>
+              	<!-- Set tomcat.home to CATALINA_HOME environmental variable 
+              	Use this to skip -Dpluto.home=/path/to/pluto on command line -->
+              	<property environment="env"/>
+              	<property name="pluto.home" value="${env.CATALINA_HOME}"/>
+              	<echo message="pluto.home=${pluto.home}"/>
+              	<!-- Remove former deployment because sometimes
+              	tomcat does not fully redeploy a war -->
+                <delete
+                  dir="${pluto.home}/webapps/${pom.name}"
+                  failonerror="true"
+                />
+              	<!-- Deploy war file -->
+                <copy
+                  file="${project.build.directory}/${pom.name}.war"		
+                  todir="${pluto.home}/PlutoDomain"
+                  overwrite="true"
+                />
+              	<!-- Deploy context deployment descriptor for Tomcat -->
+                <copy
+                  file="${basedir}/src/main/resource/${pom.name}.xml"		
+                  todir="${pluto.home}/conf/Catalina/localhost"
+                  overwrite="false"
+                />
+              </tasks>
+            </configuration>
+            <goals>
+              <goal>run</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+  
+</project>
+          ]]></source>
         </p>
       </subsection>
-      
+            
       <subsection name="Portlet Publishing">
         <p>
-          NOTE: Currently the only way to publish an application to the portal
-          is to manually update the Portal's configuration file. An automated
-          approach is in development and should be available before the ALPHA-1
-          release.
-        </p>
-        <p>
-          To publish your portlets to Pluto Portal, you should manually update
-          the Portal's configuration file <code>pluto-portal-driver-config.xml</code>.
+          Currently, as of Pluto-1.1-beta1, the only way to publish an application to the
portal
+          is to manually update the Portal's configuration file <code>pluto-portal-driver-config.xml</code>
+          located in the WEB-INF directory of the pluto webapp.
+          Here's how to do it: 
         </p>
         
         <p><b>Step 1: Portlet App Config</b></p>
         <p>
-          You should firstly add a <code>portlet-app</code> config element to
+          First, add a <code>portlet-app</code> config element to
           notify the Portal which portlet application is deployed to the
-          appserver. In this element, you should specify the context path of
+          appserver (Tomcat). In this element, you should specify the context path of
           your portlet app, as well as the names of portlets deployed. Here is
           an example:
           <source><![CDATA[
@@ -169,9 +265,9 @@
         
         <p><b>Step 2: Portal Page Config</b></p>
         <p>
-          You should then configure a portal page within which your portlets
-          will be displayed. You may do this by adding a <code>page</code>
-          element in the <code>render-config</code> element, like this:
+          You should then configure a portal page to display your portlets.
+          Do this by adding a <code>page</code> element in the <code>render-config</code>

+          element, like this:
           <source><![CDATA[
 <render-config default="Test Page">
   ... ...
@@ -188,7 +284,8 @@
           The <code>uri</code> attribute defines the theme of your portal page.
           If you use <code>/WEB-INF/fragments/portlet.jsp</code> (which is the
           default theme of Pluto Testsuite portlet app), your portlets will be
-          displayed in two columns.
+          displayed in two columns. You can clone this file to customize your layout.
+          If you do so, make sure the <code>uri</code> attribute points to the
new file.
         </p>
       </subsection>
       



Mime
View raw message