Deploying Portlet to Pluto Portal

There are 2 steps involved in deploying a portlet application in Pluto 2.0:

  • Assembly: 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 (web.xml). This servlet org.apache.pluto.container.driver.PortletServlet will be used to dispatch portlet requests to the portlet application.
  • Deployment: After portlet applications are assembled properly they must be deployed to the servlet engine within which the portal application is running. The current bundled distribution uses Tomcat 7.0.21 as the servlet engine.

Portlet Assembly

The maven-pluto-plugin can be used to assemble a portlet application war. It will place the proper PortletServlet configuration in web.xml.

The custom Maven 2 build shown below requires a Tomcat context deployment descriptor that has the same name as your artifactId with an xml extension (e.g. HelloWorldPortlet.xml).

To properly assemble your portlet using the Maven 2 plugin, your project's directory structure and artifact placement must conform to Maven's standard:

	HelloWorldPortlet (top level directory)
	|- pom.xml (the pom file)
	|- src (Subdir containing main subdirectory)
	    |- main (Subdir containing java, resources and webapp subdirs)
	    	|- java (java source code goes under here)
		    |       `- com
		    |           `- mycompany
		    |               `- portlet
		    |                   `- HelloWorldPortlet.java (portlet source)
		    |- webapp  (webapp resources (jsp, css, images) go under here)
		    	`- jsp 
		    		`- HelloWorldPortletView.jsp (for view mode)		    			    
		    		`- HelloWorldPortletEdit.jsp (for edit mode)		    			    
		    	`- META-INF
		    		`- HelloWorldPortlet.xml (Tomcat context deployment descriptor)
		    	`- WEB-INF
			    	`- portlet.xml (JSR-168 deployment descriptor)
			    	`- web.xml (This will be modified by maven-pluto-plugin)
          

This is an example of what the Tomcat context deployment descriptor will contain:

		<Context path="/HelloWorldPortlet"
			docBase="HelloWorldPortlet" 
			crossContext="true"/>
          

To configure the maven-pluto-plugin, you must configure it in your pom. For easy of setup, use this as you pom file, changing the groupId, artifactId and version to values appropriate to your custom portlet.

<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>
    <pluto.version>2.0.3</pluto.version>
    <portlet-api.version>1.0</portlet-api.version>
    <servlet-api.version>2.4</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><!-- Prevents addition to war file -->
    </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.portals.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 to use Java 6 to compile (change to your JDK) --> 
      <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-compiler-plugin</artifactId>
          <configuration>
              <source>1.6</source>
              <target>1.6</target>
          </configuration>
       </plugin>
      <!-- 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 'pluto2:assemble' goal to 'generate-resources' lifecycle -->
      <plugin>
        <groupId>org.apache.portals.pluto</groupId>
        <artifactId>maven-pluto-plugin</artifactId>
        <version>${pluto.version}</version>
        <executions>
          <execution>
            <phase>generate-resources</phase>
            <goals>
              <goal>assemble</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  
</project>
          

Once configured, the war generated by an 'mvn package' (or install) command will contain the appropriate pluto configuration.

Portlet Deployment

To deploy a portlet application, simply deploy the application war using any standard mechanism for your application server. There are many maven plugins and ant tasks that can assist with this, or you can use an administrative web console. This console is the Tomcat manager webapp in the Pluto bundled distribution and is accessed via the 'Upload and deploy portlet war' link on the page administration portlet. See the Help link on that portlet for more details.

In the bundled distribution that uses Tomcat, deployment of an assembled war can simply be done by dropping the war into the webapps directory. You can automatically achive this by adding the following code within the plugins section of your maven pom.xml:

       <plugin>
        <artifactId>maven-antrun-plugin</artifactId>
        <executions>
          <execution>
            <phase>integration-test</phase>
            <configuration>
              <tasks>
                  <property environment="env"/>
                   <!-- This assumes that you have set a CATALINA_HOME environmental variable -->
                  <property name="pluto.home" value="${env.CATALINA_HOME}"/>
                  <copy file="target/${pom.name}.war" todir="${pluto.home}/webapps"/>
              </tasks>
            </configuration>
            <goals>
              <goal>run</goal>
            </goals>
          </execution>
        </executions>
      </plugin>          
          

Once the pom.xml file has been updated with this plugin, you can run the full build and deployment using the command: mvn integration-test. The code assumes that you have set the environmental variable CATALINA_HOME to the Pluto home directory. If that has not been done, just set pluto.home from the command line with the -D flag. The command line would then be: mvn -Dpluto.home=C:/pluto integration-test.

Portlet Publishing

As soon as the portlet application (war) is deployed to the servlet container the portlet application will be available to the portal and can be added to pages using the page administration portlet. See the help mode in this portlet for details on its use.

Portal Page Configuration

If you'd like for your page configuration to be consistent throughout restarts of the application server (currently placements made through the page administration portlet is not persistent), you should then configure the page layout in the portal-driver configuration file (pluto-portal-driver-config.xml).

The page can then be configured by adding a page child element of the render-config element, like this:

<render-config default="Test Page">
  ... ...
  <page name="Your Portal Page Name" uri="/WEB-INF/fragments/portlet.jsp">
    <portlet context="/your_portlet_app_context_path"
             name="your_portlet_1"/>
    <portlet context="/your_portlet_app_context_path"
             name="your_portlet_2"/>
  </page>
</render-config>
          

The uri attribute defines the theme of your portal page. If you use /WEB-INF/fragments/portlet.jsp (which is the default theme of Pluto Testsuite portlet app), your portlets will be displayed in two columns. You can clone this file to customize your layout. If you do so, make sure the uri attribute points to the new file.