Portal Guide

CHAPTER 13

About Portlet Applications

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

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:

The portal service sends portlet requests to the portlet applications where the portlets reside.
The portlets respond by processing actions and generating dynamic content
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

In the Director Designer, the Project Wizard allows you to create several types of portlet applications that work with the exteNd Director portal:

Type of portlet application	Packaging	How deployed	Advantages
Director EAR or WAR project	Portlets and portlet deployment descriptors are packaged inside the portal application.	As a single application	Yields a slight performance advantage because the portal communicates directly with the portlet container within the same context
Portlet application project	Portlets and portlet deployment descriptors are packaged as a standalone portlet application WARs.	There are two ways to deploy a portlet application project: With the portal application inside an EAR—like the ExpressPortal application, for example As a standalone portlet application, while your portal runs on a server in shared library mode For information about shared libraries, see the section about shared library configurations.	Allows you to deploy third-party portlets or your own portlets independently, without needing to add them directly to the portal application. Allows you to create modular portlet applications that you can reuse.

Type of portlet application

Packaging

How deployed

Advantages

Director EAR or WAR project

Portlets and portlet deployment descriptors are packaged inside the portal application.

As a single application

Yields a slight performance advantage because the portal communicates directly with the portlet container within the same context

Portlet application project

Portlets and portlet deployment descriptors are packaged as a standalone portlet application WARs.

There are two ways to deploy a portlet application project:

With the portal application inside an EAR—like the ExpressPortal application, for example
As a standalone portlet application, while your portal runs on a server in shared library mode

For information about shared libraries, see the section about shared library configurations.

Allows you to deploy third-party portlets or your own portlets independently, without needing to add them directly to the portal application.

Allows you to create modular portlet applications that you can reuse.

Portlet application deployment descriptors

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

Deployment descriptor	Name of descriptor file	Comments
Web application deployment descriptor	web.xml	Required for all WARs See Web application deployment descriptor.
Standard portlet deployment descriptor, defined by Java Portlet 1.0	portlet.xml	Required for all portlet application WARs See Standard portlet deployment descriptor.
exteNd Director extension to standard portlet deployment descriptor	novell-portlet.xml	Optional Allows you to add exteNd Director value-added extensions to standard preferences Allows you to define an extended set of preferences and settings Used by portlet applications that run with the exteNd Director portal Extends portlet.xml See exteNd Director portlet deployment descriptor.
exteNd Director portlet fragment deployment descriptor	portlet name.xml	Optional Provides the union of all specifications in portlet.xml and novell-portlet.xml Allows you to dynamically load portlets during development Can be used only in portlet applications that run with the exteNd Director portal Requires that the portlet application have a resource set NOTE: The Portlet Application Wizard automatically adds a resource set to an existing portlet application Cannot be used in portlet applications that run with third-party portals Preference values take precedence over portlet.xml and novell-portlet.xml See exteNd Director portlet fragment deployment descriptor.

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.

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:

Portlet application property to specify in web.xml	Tag
Portlet application description	<description>
Portlet application name	<display>
Portlet application security role mapping	<security-role>

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:

novell portlet xml schema

For more information 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

Element	Description	Example
enable-title-bar	A setting that specifies whether to display the portlet with or without a title bar: 1 = enable 0 = disable NOTE: This setting must be enabled if you want the options defined in supported-options to be displayed in the portlet window	<portlet name="TextMessagePortlet"> ... <enable-title-bar>1</enable-title-bar> ...
supported-option	A setting that specifies which of the options defined in the portal are supported by the portlet. All options defined by the portal are described in the portal-option directory of the portal application resource set. NOTE: If you want options to be displayed in the portlet window, you must set enable-title-bar For more information, see the chapter on working with portal options.	<portlet name="TextMessagePortlet"> ... <supported-option>edit</supported-option> <supported-option>help</supported-option> ...
style	A configuration option that specifies a style for the portlet. Only one style element can be specified per portlet, but each style can contain multiple user agents that point to device-specific XSL style sheets.	<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	A configuration option that provides an image for previewing the portlet.	<preview-image>$RESOURCE_URL$/images/PortletPreview.gif</preview-image>
portlet-preferences	A preference that allows you to extend the configuration choices for standard preferences defined in portlet.xml	<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> ...
synchronous	A preference that specifies whether the portlet executes synchronously or asynchronously 0 = asynchronous 1 = synchronous Asynchronous (multithreaded) execution is the default. For more information see the section on synchronous versus asynchronous processing	<portlet name="TextMessagePortlet"> ... <synchronous>1</synchronous> ...
requires-authentication	A setting that specifies whether or not an authenticated user is required to run the portlet 0 = does not require authentication 1 = requires authentication	<portlet name="TextMessagePortlet"> ... <requires-authentication>0</requires-authentication> ...
auto-register	A preference that indicates whether or not the portlet should be registered automatically at deployment enabled = "false": do not register automatically enabled = "true": register automatically You may want to enable auto-register for: System portlets and other portlet registrations that are permanent parts of your application Portlets that need to be available to users immediately, without administrator intervention You may want to disable auto-register when you don't know how a portlet will be used at runtime—for example, if the portlet will communicate with a back-end mail server that hasn't been configured yet NOTE: If you remove a portlet that has been automatically registered, the portal will reregister the portlet at server restart	<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> ... NOTE: In this example, an instance of TextMessagePortlet called AdminTextMessagePortlet will be registered automatically at deployment time and added to the General Portlets category. List and execute permissions will be restricted to portal administrators.
max-timeout	A setting that specifies the maximum number of milliseconds the portal should wait for this portlet to return its content. The portlet container can use this value or ignore it. >= 0: no timeout set; the request timeout takes precedence >0: number of milliseconds to wait before timing out	<portlet name="TextMessagePortlet"> ... <max-timeout>-1</max-timeout> ...
hidden-from-user	A setting that indicates whether or not the portlet should be displayed in a selection list to authorized users who are not portal administrators true = hide from all users except portal administrators false = show portlet to all authorized users	<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 more information 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.