Printed: Dec 8, 2025
From: http://www.jcp.org/en/jsr/detail?id=162

Standard Format

Community
Expert Group

Summary  |  Proposal  |  Detail (Summary & Proposal)
JSRs: Java Specification Requests
JSR 162: Portlet API

Stage Access Start Finish
Withdrawn   20 Jan, 2002  
JSR Review Ballot View results 08 Jan, 2002 22 Jan, 2002
Status: Withdrawn
Reason: Portlet API As there is very significant overlap between JSRs 162 & 167, Sun and IBM have reached a mutual agreement regarding the proposals. We have now reached a point where we feel that we have a mutually acceptable new combined JSR proposal, which we now wish to seek endorsement of from the existing supporters of JSR 162 and 167.
JCP version in use: 2.1
Java Specification Participation Agreement version in use: 1.0


Description:
The Portlet API specification defines an API for components being aggregated in web applications like portals. It includes portlets, portlet container behavior, portlet windows, events, persistent storage and portlet services.

Please direct comments on this JSR to the Spec Lead(s)
Team

Specification Leads
Star Spec Lead Stefan Hepper IBM
Expert Group
  IBM    
   

This JSR has been Withdrawn
Reason: Portlet API As there is very significant overlap between JSRs 162 & 167, Sun and IBM have reached a mutual agreement regarding the proposals. We have now reached a point where we feel that we have a mutually acceptable new combined JSR proposal, which we now wish to seek endorsement of from the existing supporters of JSR 162 and 167.

Original Java Specification Request (JSR)

Identification | Request | Contributions | Additional Information

Section 1. Identification

Submitting Member: IBM

Name of Contact Person: Thomas Schaeck

E-Mail Address: schaeck@de.ibm.com

Telephone Number: +49 171 692 8407

Fax Number: +49 7031 16 4888


Specification Lead: Stefan Hepper

E-Mail Address: sthepper@de.ibm.com

Telephone Number: +49 7031 16 3445

Fax Number: +49 7031 16 4888


Initial Expert Group Membership:

IBM

Supporting this JSR:

IBM



Section 2: Request

2.1 Please describe the proposed Specification:

The Portlet API specification defines an API for web application components that interact with and can be aggregated in web applications like portals. We refer to these components as portlets in the remainder of this text.
Portlets are web components like servlets, but have additional, special properties that allow them to easily plug into and run in enclosing web applications like portals. Portlets are designed to be aggregatable in the larger context of composite pages, e.g. multiple instances of the same portlet parameterized with different per-user, per-instance portlet data can coexist on the same portal page. Usually, many portlets are invoked in the course of handling a single request to aggregate their respective produced markup fragments in a page of markup. The markup fragments generated by portlets often need to contain links to trigger actions in the portlet, therefore URL-rewriting methods are required that allow portlets to transparently create links within the markup fragments they output, without needing to know how URLs are structured in the particular web application.
Portlets rely on the portlet container infrastructure accessible via the Portlet API for functions like access to user profile information for the current user, access to the window object that represents the window in which the portlet is displayed, participation in the portal window and action event model, access to web client information, inter-portlet messaging and a standard way of storing and retrieving per-user/per-instance data persistently.
The Portlet API provides standard interfaces for the functions mentioned above. The Portlet API extends the servlet programming model and defines a common base class and interfaces for portlets and tags for JSPs called by portlets, cleanly separating portlets from the surrounding infrastructure so that portlets can run on different portal servers like servlets can run on different application servers.
The Portlet API specification shall evolve from the portlet concept as developed in the Apache JetSpeed Open Source project. In many aspects, the Portlet API is an extension of the Servlet API, defining additional interfaces for portlet-specific functionality. In some other aspects, it restricts use of functions provided by the Servlet API to the subset that makes sense for portlets just producing aggregatable markup fragments and not having ownership of the entire page that displays them. For example, unlike servlets, portlets may not send errors or redirects as a response, this may only be done by the application that invokes and aggregates the portlets into a larger page.
Portlets can be grouped in Portlet Applications. Portlets in one portlet application can exchange messages via the Portlet API. Portlet Applications are packaged, distributed and deployed using WAR files that include portlet-related meta-information, utilizing existing Servlet infrastructure.
The Portlet API shall be compatible with the Remote Portlet Web Services concept in the sense that portlets written to the Portlet API can act as local proxies in a portal server for remote portlet web services located on other servers and portlets written to the Portlet API can be wrapped into remote portlet web services.

2.2 What is the target Java platform? (i.e., desktop, server, personal, embedded, card, etc.)

Server/J2EE

2.3 What need of the Java community will be addressed by the proposed specification?

The lack of standards in the portal space has led many portal software vendors to define proprietary APIs for portal components. The resulting diversity of interfaces creates problems not only for portal customers and ISVs, but also for portal software vendors and companies who wish to provide portlets.

The Portlet API specification is required to achieve interoperability between portlets and Java-based portal servers or other web applications that aggregate portlets. The goal is to allow that portlets can be developed, packaged into WAR files and deployed in a standard way, on Portlet API-compliant portal servers leveraging existing Servlet infrastructure.

The Java Portlet API will also allow portlets acting as proxies for Remote Portlet Web Services and therefore allow integration of visual, user-facing web services

2.4 Why isn't this need met by existing specifications?

The Java Servlet API specification does define servlets and related APIs in general, but does not address the requirements for components that need to be aggregated in composite pages and plug into portal servers, using the portal server environment and yet shall be portable across portal server platforms.
For example, the Servlet API does not provide standard interfaces to access persistent portlet settings and instance data, user profile information, information about the window displaying the portlet, URL rewriting functions to allow portal server agnostic creation of links and actions in page fragments. Furthermore, the Servlet API does not define a standard event model for portals that allows portlets to receive action events, window events or message events.

2.5 Please give a short description of the underlying technology or technologies:

The Portlet API is based on the Servlet API and supports access of portal-related objects from JSPs through appropriate JSP tags. Portlet containers can be implemented as extensions of servlet containers. The portlet concept is based on prior work done in the Apache JetSpeed Open Source Community. The Portlet API will be compatible with the Remote Portlet Web Services and e.g. allow for integration of remote portlet web services in portals.

2.6 Is there a proposed package name for the API Specification? (i.e., javapi.something, org.something, etc.)

javax.servlet.portlet

2.7 Does the proposed specification have any dependencies on specific operating systems, CPUs, or I/O devices that you know of?

No

2.8 Are there any security issues that cannot be addressed by the current security model?

No

2.9 Are there any internationalization or localization issues?

No

2.10 Are there any existing specifications that might be rendered obsolete, deprecated, or in need of revision as a result of this work?

No

2.11 Please describe the anticipated schedule for the development of this specification.

Portlet API Spec community draft: 05/2002
Portlet API Spec public draft: 07/2002
Portlet API final draft: 10/2002
Open source reference implementation at Apache: 12/2002

2.12 Please describe the anticipated working model for the Expert Group working on developing this specification.

Initial Kick-Off Meeting in 03/2002
Collaboration via mailing list and regular conference calls
Regular Meetings every few months





Section 3: Contributions

3.1 Please list any existing documents, specifications, or implementations that describe the technology. Please include links to the documents if they are publicly available.

Portlet API defined in Apache JetSpeed Open Source Project, see http://cvs.apache.org/viewcvs/jakarta-jetspeed/proposals/portletAPI/

3.2 Explanation of how these items might be used as a starting point for the work.

The Portlet API as designed by the Apache JetSpeed community may be used a basis from which the standard Portlet API can evolve.



Section 4: Additional Information (Optional)

4.1 This section contains any additional information that the submitting Member wishes to include in the JSR.

The reference implementation shall be done in open source at Apache.

The Portlet API is related to the Remote Portlet Web Services concept: The Java Portlet API and the Remote Portlet Web Services WSDL interface and contracts are compatible so that Portlets can optionally be exposed as Remote Portlet Web Services by a portal server and a portal server can consume Remote Portlet Web Services using a portlet proxy that behaves like a portlet to the container.