Creating a simple portlet | HCL Digital Experience

Writing the portlet code

package com.ibm.wps.samples.jsr;

import javax.portlet.*;
import java.io.*;

public class HelloWorld extends GenericPortlet {
	
   public void init (PortletConfig portletConfig) throws UnavailableException, PortletException
   {
      super.init(portletConfig);
   }

   public void doView(RenderRequest request, RenderResponse response)
                      throws PortletException, IOException
   {

      // set return content type 
      response.setContentType("text/html");
      PrintWriter writer = response.getWriter();
      writer.println("<p class='wpsPortletText'>Hello Portal World!</p>");
    }

}

Compiling Java source

   appserver\java\bin\javac -classpath %WAS_CLASSPATH%;path_to\portletapi_20.jar 
        com.ibm.wps.samples.jsr.HelloWorld.java  

   appserver\java\bin\javac -classpath %WAS_CLASSPATH%;path_to\portletapi_20.jar 
        com.ibm.wps.samples.v4.HelloWorld.java  

Loading classes for portlets

HCL DX class loading follows the WebSphere® Application Server hierarchy for class paths and search orders. You can reference a class if the parent class loader can reference it or your own class loader can reference it. You cannot reference a class if a child class loader references it. The graphic illustrates where HCL DX and portlet applications fit into the class loading hierarchy.

In the following graphic runtime class path patches (RCP) are at the beginning of the hierarchy. Runtime class path (RP) branches from runtime class path patches. Runtime extensions (RE) branches from runtime class path, and application extensions (AEX) branch from runtime extensions. Application class loaders (AC1), application class loaders (AC2), and application class loaders (AC3) are portlet applications that branch from application extensions.

As illustrated, HCL DX is an application extension (AEX) in WebSphere® Application Server. The HCL DX core classes are in the class path PortalServer_root/shared/app. If an installed portlet application includes a class loader, the portlet application class loader is an application class loader (ACx) in HCL DX.

If you suspect a classloading problem, ensure that the required classes are in the appropriate class path according to the classloading hierarchy.

Creating the JAR file

Next, the portlet must be packaged in the JAR file format. To create a JAR file with the name HelloWorld.jar, enter the following command:

   jar -cf HelloWorld.jar HelloWorld.class

Refer to the JDK documentation for more information about the JAR command.

Writing the portlet descriptors

The following samples can be packaged with the Hello World portlet.

Web application deployment descriptor for standard portlets:

According to the Java Portlet Specification, only web resources that are not portlets must be declared in the web.xml. However, the following properties must be set to correspond to the portlet descriptor:

• <description/>

  describes the portlet application.

• <display-name/>

  indicates the portlet application name.

• <security-role/>

  indicates the portlet application security role mapping. Omit this tag if the portlet does not use this feature.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" 
                         "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app id="WebApp">
	<display-name>Hello World (JSR)</display-name>
	<description>Basic JSR 168 portlet</description>
</web-app>

Standard portlet deployment descriptor:

The following shows the minimum elements that are required for the standard portlet deployment descriptor.

<?xml version="1.0" encoding="UTF-8"?>
<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" version="2.0" 
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
             xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd 
                                 http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd">
   <portlet>
      <portlet-name>HelloWorld portlet name</portlet-name>
      <display-name>Hello World portlet (JSR)</display-name>
      <display-name xml:lang="en">Hello World portlet (JSR)</display-name>
      <portlet-class>com.ibm.wps.samples.jsr.jsrHelloWorld</portlet-class>
      <supports>
         <mime-type>text/html</mime-type>
         <portlet-mode>view</portlet-mode>
      </supports>
      <supported-locale>en</supported-locale>
      <portlet-info>
         <title>Hello World (JSR)</title>
      </portlet-info>
   </portlet>
</portlet-app>

The standard portlet descriptor is defined by an XML schema and does not require a DTD.

Setting up the WAR file directory structure

Before you package your portlet, the class files and resources must be arranged in the WAR file directory structure described here. A portlet application exists as a structured hierarchy of directories.

/

The root directory of the portlet file structure.

/images

Location for any images the required by the portlet.

/WEB-INF

Location for all protected resources. The /WEB-INF directory stores the portlet descriptor document and all of the run time executable JAR files and classes that the packaged portlet requires.

The portlet information directory is not part of the public document tree of the application. Files that are in /WEB-INF are not served directly to a client.

/WEB-INF/lib

Location for storing portlet JAR files.

/WEB-INF/jsp

Location for JSP files. This is a suggested path name. Your JSPs can be packaged in any location. JSPs that are included inside the portlet markup must be placed under the /WEB-INF directory. Place them outside the /WEB-INF directory if you create direct links to them.

/WEB-INF/classes

Location for portlet class files. Individual class file must be stored in a directory structure within /WEB-INF/classes that reflects the class package. For example, the class HelloWorld.class, in package com.ibm.wps.samples, would be stored in /WEB-INF/classes/com/ibm/wps/samples/HelloWorld.class.

/META-INF

Location for the manifest file, manifest.mf, and the Java 2 security file, was.policy (if present). The manifest is in the standard JAR file format as defined by the Java 1.3 specification. The Java 2 security policy file is used to allow a portlet to execute operations that might be restricted if Java 2 security is enabled. The contents of the /META-INF directory is not served to clients.

Packaging and deploying portlets

Packaging a portlet and resources into a WAR file

Any JAR file utility can be used to build a WAR file. The following are examples of how to use the JAR file utility that is provided by WebSphere® Application Server.

• To create a WAR file with the name HelloWorld.war and include all of the files in the /WEB-INF and /images directories:

     jar -cf HelloWorld.war images WEB-INF
  

• To update an existing WAR file, HelloWorld.war with a revised portlet descriptor:

     jar -uf HelloWorld.war WEB-INF/portlet.xml
  

• To extract the portlet descriptor from the WAR file, HelloWorld.war:

     jar -xf HelloWorld.war WEB-INF/portlet.xml
  

• To extract all files from an existing WAR file, HelloWorld.war:

     jar -xf HelloWorld.war
  

After the WAR file is created, it can be installed to HCL DX as described in Portal administration portlets.

Preparing the portlet application for installation

To facilitate deployment of portlet applications and complex portlets, you can provide a portlet configuration file that can be invoked by the XML configuration interface (XMLAccess). The XML configuration interface allows the portlet developer to specify places, pages, themes, skins, supported markups and clients, and other settings for a portlet application. This is especially useful for portlets that use messaging because these portlets must be placed on the same page. For more information, see The XML configuration interface.

When you construct XMLAccess scripts for use in installing standard portlets, use the following values:

• uid attribute for the <web-app> element:

  Use the uid attribute of the <portlet-app/> subelement with a .webmod suffix. As described later in this topic, the uid attribute of the <portlet-app/> subelement is dependent on the presence of the id attribute of the <portlet-app/> element from the portlet.xml.

• uid attribute for the <portlet-app> element:

  Use the id attribute of the <portlet-app/> element from the portlet.xml. If this value has not been specified, specify the WAR file name of the portlet application in its place. For portlet updates, the WAR file name must be the original name of the WAR file used to install the portlet application. That is, the WAR file name can be changed, but the uid must indicate the original uid used during portlet installation.

• name attribute for the <portlet> element:

  Use the content of the <portlet-name/> element from the portlet.xml.

• referenceid attribute of the <servlet> element:

  Use the content of the <portlet-name/> element from the portlet.xml appended with the .servlet suffix.

For example, a portlet application might use a portlet descriptor:

<portlet-app 
    xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
    version="1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation=
        "http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd
         http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd">
        <portlet>
        <portlet-name>Banner Ad</portlet-name>
        ...

In this example, there is no ID attribute that is provided on the <portlet-app/> element. Therefore, the <portlet-app/> element of the XMLAccess script would use the WAR file name:

 <web-app action="update" active="true" uid="com.ibm.wps.banner">
     <url>file:///$server_root$/bp/wp.bp.bannerad/installableApps/bannerad.war</url>
     <servlet action="update" 
              active="true" 
              referenceid="Banner Ad.servlet"/>
     <portlet-app action="update" active="true" uid="com.ibm.wps.banner">
         <portlet action="update" active="true" name="Banner Ad">
     </portlet-app>
 </web-app>