Deploying Portlet to Pluto Portal

There are 2 involved in deploying a portlet application Pluto 1.1:

  • 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.core.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 binary distribution uses Tomcat 5.5 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 also deploys 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)
		    |- resources
		    |	`- HelloWorldPortlet.xml (Tomcat context deployment descriptor)
		    |- webapp  (webapp resources (jsp, css, images) go under here)
		    	`- jsp 
		    		`- HelloWorldPortletView.jsp (for view mode)		    			    
		    		`- HelloWorldPortletEdit.jsp (for edit mode)		    			    
		    	`- 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="../PlutoDomain/HelloWorldPortlet.war" 
			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>
  	<!-- Change this for a new Pluto version -->
    <pluto.version>1.1.0</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.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>
        <groupId>org.apache.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) 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 a manager web console. This console is pointed to the Tomcat manager webapp in the Pluto binary 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.

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 portlet application should be first configured in pluto-portal-driver-config.xml by adding a portlet-app element with appropriate child elements like this:

<portlet-app>
    <context-path>/your_portlet_app_context_path</context-path>
    <portlets>
      <portlet name="your_portlet_1"/>
      <portlet name="your_portlet_2"/>
    </portlets>
</portlet-app>
			

The page can then be configured by adding a page element in 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.

The value of the context-path element within the portlet-app record must correspond to the value of the context attribute in the portlet element. In addition, the value of the name attribute in the portlet child element of portlet-app must correspond to the value of the name attribute of the portlet child element of page.