Portal Guide

CHAPTER 12

About Portlet Applications

This chapter provides an introduction to exteNd Director portlet applications. It contains the following sections:

• What is a portlet application?

• Support for dynamic loading of portlets

• How portlet applications work with the exteNd Director portal

• Configuring portlet applications

• Portlet application deployment descriptors

For more information about exteNd Director projects in general, see the chapters that cover working with projects in Developing exteNd Director Applications .

What is a portlet application?

Java Portlet 1.0 defines a portlet application as a Web application that consists at a minimum of one or more portlets, the Web application deployment descriptor (web.xml), and a portlet deployment descriptor (portlet.xml). exteNd Director provides additional portlet deployment descriptors that allow you to:

• Configure a broader range of preferences and settings

• Dynamically load portlets from a resource set

For more information, see Portlet application deployment descriptors.

How portlet applications interact with portal applications

A portlet application must run in conjunction with a portal application. The portal application includes a portal service that interacts with portlet applications in this way:

1. The portal service sends portlet requests to the portlet applications where the portlets reside.

2. The portlets respond by processing actions and generating dynamic content

3. The portal service renders the content generated by portlets on portal pages

   NOTE:   exteNd Director supports several types of portal pages: personal, shared, and container pages. For more information, see the chapter on working with portal pages.

Portlet applications can run externally or locally in relation to the portal application. exteNd Director supports each scenario, as described in How portlet applications work with the exteNd Director portal.

Packaging requirements

Portlet applications are packaged as Web application archives (WARs). When portlet applications need additional resources that cannot be packaged in the WAR file— such as Enterprise JavaBeans (EJBs)—the portlet application may be packaged together with these resources in an EAR file.

Directory structure

Portlet applications use the same directory structure as J2EE Web applications, but require an additional deployment descriptor in WEB-INF, as described in Portlet application deployment descriptors.

Portlet classes and resources must reside in WEB-INF/classes, within a JAR in WEB-INF/lib, or as defined by the resource set class loader (specified in the <libPath> element in resourceset.xml of the portlet application).

In exteNd Director, you can add portlet classes and deployment descriptors locally to the resource set of an exteNd Director portal application or portlet application to enable dynamic loading of updates during development and test cycles.

For more information, see Support for dynamic loading of portlets.

Support for dynamic loading of portlets

exteNd Director supports dynamic loading of portlets if they are stored in the resource set of an exteNd Director portal application. When you enable this feature, exteNd Director dynamically loads portlet changes from disk rather than from the deployed WAR, and reflects the changes at runtime. As a result, dynamic loading speeds development, because you can test modifications without having to redeploy the entire project.

Dynamic loading is enabled by default in the Express Portal project, and when you create a new portal application EAR or WAR using the exteNd Director Project Wizard.

For portlets, dynamic loading is implemented seamlessly when you create pageflows (a type of portlet) with exteNd Director pageflow design tools and when you develop portlets with the exteNd Director Portlet Wizard. These tools automatically create portlet fragment deployment descriptors and store them along with the associated portlet classes at the appropriate locations in the resource set of a portal application.

For more information about resource sets, see the chapter on using the resource set in an exteNd Director application.

For more information about dynamically loading portlet descriptors, see exteNd Director portlet fragment deployment descriptor.

How portlet applications work with the exteNd Director portal

Portlet application WARs can run externally or locally in relation to the exteNd Director portal on an application server.

Running portlet applications externally with the exteNd Director portal

A portlet application is considered to run externally in relation to the portal application when:

• The portlet application is packaged as a standalone application WAR and deployed to the server where the portal application WAR is running in a shared library environment.

  IMPORTANT:   In a shared library environment, only one exteNd Director portal application can be deployed to the server at a time, and no other portal applications can be deployed to the server at the same time.

• The portlet application WAR is packaged with a portal application WAR inside an EAR

For more information see the section on changing a project's shared library configuration.

Running portlet applications locally with the exteNd Director portal

A portlet application is considered to run locally to the portal when its portlets and portlet deployment descriptors reside inside the portal WAR—whether the portal WAR is packaged in an EAR or as its own self-contained application.

In exteNd Director this scenario yields a slight performance advantage because the portal communicates directly with the portlet container within the same context.

Configuring portlet applications

When configuring portlet applications, consider these key decision points:

Configuring portlet applications to run externally with the exteNd Director portal

To configure portlet applications to run externally when deployed as standalone WARs:

1. Configure your application server to use a full shared library configuration, as described in procedures for changing the project configuration.

2. Create an exteNd Director portal application EAR or WAR project, as described in creating an exteNd Director project.

3. Configure the exteNd Director portal application project to use shared libraries, as described in procedures for changing the project configuration.

4. Deploy the exteNd Director portal application project to the application server.

5. Configure one or more existing portlet applications to work with the exteNd Director portal, as described configuring a portlet application project.

6. If you want to package the portlet applications inside an EAR, follow the instructions for adding projects.

   NOTE:   Java Portlet 1.0-compatible portlet applications can also be deployed as standalone WARs.

7. Deploy the portlet application WARs or EAR to the application server.

To configure portlet applications to run externally when deployed within a portal EAR:

1. Create an exteNd Director portal application EAR project, as described in creating an exteNd Director project.

2. With the portal application EAR project open in the exteNd Director development environment, select File>New>Project.

   The New Project dialog displays.

3. Select Portlet Application and click OK.

   The Add to Current Project dialog displays, asking if you want to add the portlet application to the currently open EAR project.

4. Select Yes and click Next.

   

   The Select Existing Web App WAR dialog displays.

5. Enter the path to your portlet application WAR, as in this example:

   

6. Click Finish.

   The portlet application WAR is configured to work with the exteNd Director portal and is added to your EAR project.

7. Deploy the portal application EAR to your application server.

Configuring portlet applications to run locally in an exteNd Director portal application

To run portlet applications locally in an exteNd Director portal application:

1. Create an exteNd Director WAR or EAR project using the exteNd Director Project Wizard, as described in creating an exteNd Director project.

   NOTE:   The wizard creates a project that includes a portal, portlet runtime artifacts, and resource set. The portlet runtime artifacts include the portlet deployment descriptors portlet.xml and novell-portlet.xml, as described in Portlet application deployment descriptors.

2. With the exteNd Director portal application WAR or EAR open, create Java Portlet 1.0-compliant portlets using either of the following exteNd Director design tools:

   1. Pageflow Modeler

   2. Portlet Wizard.

   NOTE:   Each of these tools automatically adds the new portlets to the resource set of the portal application, along with a portlet fragment deployment descriptor for each portlet. Each fragment descriptor stores both Java Portlet 1.0 and exteNd Director configuration information for its associated portlet; there is no need to update portlet.xml and novell-portlet.xml.

3. Rebuild and redeploy the project.

Portlet application deployment descriptors

exteNd Director provides support for the following deployment descriptors for portlet applications:

NOTE:   When you use the exteNd Director Project Wizard to create an exteNd Director WAR or EAR project, portlet.xml and novell-portlet.xml are automatically included in your project. See the chapter on developing portlets.

Determining which deployment descriptors to use

The following chart presents guidelines for determining which portlet deployment descriptors to include in your portlet applications.

Web application deployment descriptor

Recall that the Web application deployment descriptor web.xml contains the standard settings for a WAR and resides in the /WEB-INF directory of your application WAR. This descriptor specifies all standard Web resources including servlets, JSP pages, HTML pages, Java classes, and static documents.

Because web.xml is not extensible, portlet resources must be specified in a separate file, described in Standard portlet deployment descriptor. However, the following portlet application properties can be set in the web.xml deployment descriptor:

Standard portlet deployment descriptor

The standard portlet deployment descriptor portlet.xml must be included in the /WEB-INF directory of every portlet application. It specifies configuration and deployment information for all portlets in the application.

For more information about the standard portlet deployment descriptor, see the Java Portlet 1.0 specification. You can also view the schema in:

  extend5 install directory\Common\Resources\SchemaCatalog\portlet-app_1_0.xsd

exteNd Director portlet deployment descriptor

When you run portlet applications with the exteNd Director portal, you have the option of including the exteNd Director portlet deployment descriptor novell-portlet.xml in your portlet applications. This optional descriptor extends portlet.xml by providing settings and additional preferences that are interpreted by the exteNd Director portal, as described in A look inside novell-portlet.xml.

novell-portlet.xml contains the following types of information:

• Additional descriptor elements for standard preferences defined in portlet.xml

• exteNd Director value-added preferences

• exteNd Director settings

  NOTE:   Although settings can be specified in novell-portlet.xml at design time, they can also be modified by an administrator after deployment when portlet definitions are registered and when portlet registrations are assigned to pages, as described in the section on portlet settings.

You include novell-portlet.xml in the /WEB-INF directory of your portlet application, along with portlet.xml. and web.xml.

Whereas portlet.xml requires that you include descriptors for all portlet definitions in your application, novell-portlet.xml has no such restriction. You include only the portlet definitions that require additional settings, but you cannot include portlets that haven't been defined in portlet.xml.

A look inside novell-portlet.xml

Here is a high-level view of the novell-portlet.xml schema:

You can view the novell-portlet.xml schema in:

  extend5 install directory\Common\Resources\SchemaCatalog\novell-portlet.xsd

The following table describes the elements you can define in novell-portlet.xml for any portlets in your application

<portlet name="TextMessagePortlet">
...
  <enable-title-bar>1</enable-title-bar>
...

<portlet name="TextMessagePortlet">
...
  <supported-option>edit</supported-option>
  <supported-option>help</supported-option>
...

<portlet name="BookmarkPortlet">
...
  <style>
    <name>BookmarkPortletDefault</name>
    <display-name>Default Bookmark Portlet Style</display-name>
    <user-agent>
      <device-name>Generic_HTML</device-name>
      <file-name>$RESOURCE_SET$/portal-style/BookmarkPortlet.xsl</file-name>
    </user-agent>
  </style>
...

<preview-image>$RESOURCE_URL$/images/PortletPreview.gif</preview-image>

<portlet name="TextMessagePortlet">
...
  <portlet-preferences>
    <preference name="min-timeout">
      <data-type>Integer</data-type>
      <required>true</required>
      <multi-valued>false</multi-valued>
    </preference>
    <preference name="max-timeout">
      <data-type>Integer</data-type>
      <required>true</required>
      <multi-valued>false</multi-valued>
    </preference>
    <preference name="scrollbar">
      <data-type>Boolean</data-type>
    </preference>
  </portlet-preferences>
...

<portlet name="TextMessagePortlet">
...
  <synchronous>1</synchronous>
...

<portlet name="TextMessagePortlet">
...
  <requires-authentication>0</requires-authentication>
...

<portlet name="TextMessagePortlet">
...
  <auto-register enabled="true">
    <registration-id>AdminTextMessagePortlet</registration-id>
    <category>General Portlets</category>
    <restrict-list>true</restrict-list>
    <restrict-execute>true</restrict-execute>
  </auto-register>
...

<portlet name="TextMessagePortlet">
...
  <max-timeout>-1</max-timeout>
...

<portlet name="TextMessagePortlet">
...
  <hidden-from-user>true</hidden-from-user>
...

exteNd Director portlet fragment deployment descriptor

The exteNd Director portlet fragment deployment descriptor enables dynamic loading of portlets during the development cycle. Dynamic loading allows you to update portlets and test your changes without redeploying your entire application, as described in Support for dynamic loading of portlets.

IMPORTANT:   You can use the portlet fragment deployment descriptor only if your portlet application contains a resource set and runs with the exteNd Director portal.

The portlet fragment deployment descriptor is an XML descriptor that is stored in the portal-portlet directory of the resource set in your portlet application. Each descriptor describes the preferences and settings for a single portlet.You must include one portlet fragment deployment descriptor for each portlet you want to dynamically load. The name of the portlet fragment descriptor file should match the name of the portlet class it describes, following this convention:

  name of portlet class.xml

For example, the portlet fragment deployment descriptor for the portlet class TextMessagePortlet should be calledTextMessagePortlet.xml.

Contents of portlet fragment deployment descriptor

A portlet fragment deployment descriptor represents the union of portlet.xml and novell-portlet.xml for a particular portlet. It consolidates in one location the following configuration information about its associated portlet:

• Java Portlet 1.0 settings and preferences (normally stored in portlet.xml)

• Value-added exteNd Director settings and preferences (normally stored in novell-portlet.xml)

For a detailed look at the portlet fragment deployment descriptor schema, see:

  extend5 install directory\Common\Resources\SchemaCatalog\portlet-fragment.xsd

Automatic generation of portlet fragment deployment descriptors

The exteNd Director Pageflow Modeler and Portlet Wizard automatically generate a portlet fragment deployment descriptor for each pageflow or portlet you create. The descriptor file is automatically stored it in the appropriate location in the resource set to enable dynamic loading.

For more information, see the chapter on developing custom portlets.

Copyright © 2003 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved.  more ...