Front cover
Using the Domino
mino JSP
Custom
tom Tags
An Approach to Portalizing Domino Applications
Description of the Domino JSP custom
tag libraries
Portlet concepts and integration
options
Session management and
object pooling
Thomas Reske
ibm.com/redbooks
Redpaper
International Technical Support Organization
Using the Domino JSP Custom Tags
December 2004
Note: Before using this information and the product it supports, read the information in “Notices” on page v.
First Edition (December 2004)
This edition applies to the Domino JSP Custom Tags provided with Lotus Domino 6.0.4/6.5.3 and WebSphere
Portal 5.02.1
This document created or updated on December 1, 2004.
© Copyright International Business Machines Corporation 2004. All rights reserved.
Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule
Contract with IBM Corp.
Contents
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .v
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
The team that wrote this Redpaper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii
Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii
Chapter 1. Integrating Lotus Domino into WebSphere Portal. . . . . . . . . . . . . . . . . . . . .
1.1 General introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.1 Portal technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.2 WebSphere Portal platform. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.3 Lotus Domino platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 Lotus Domino integration into WebSphere Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3 Integration considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.1 General-purpose portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.2 Java API for Lotus Collaborative Components and Lotus Domino . . . . . . . . . . . . .
1.3.3 The Domino JSP custom tag libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.4 Domino custom JSP tags: positioning relative to other integration options . . . . . .
1
2
2
2
3
3
3
4
5
5
5
Chapter 2. J2EE technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1 J2EE platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 Main benefits of the J2EE platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3 JavaServer Pages technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.1 Introduction to JavaServer Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.2 Behind the scenes: invoking JavaServer Pages . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.3 Components of a JavaServer Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4 Servlet technology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5 Portlet technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5.1 Introduction to portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5.2 Introduction to the Portlet class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5.3 Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11
12
12
14
14
14
15
16
16
16
17
17
Chapter 3. The Domino JSP custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.1 JSP tag libraries and custom tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.2 Tag Library Descriptor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.3 The Domino JSP custom tag libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
19
20
20
20
20
Chapter 4. Using the Domino JSP custom tag libraries . . . . . . . . . . . . . . . . . . . . . . . .
4.1 The Lotus Domino object architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2 Core tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3 Data access tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4 Data input tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5 Process control tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.1 Run agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.2 Preserving page arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.3 Reading and authoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.4 Pagination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
25
26
26
28
31
39
39
39
39
40
© Copyright IBM Corp. 2004. All rights reserved.
iii
4.5.5 ACL settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.6 Hierarchical or categorized views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.7 Mailto tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6 Utility tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.7 Programmatic access of underlying Domino Java Objects . . . . . . . . . . . . . . . . . . . . . .
41
42
42
43
44
Chapter 5. Limitations and considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1 Limitations and considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.1 General considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.2 Classification into the MVC paradigm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.3 The attachment tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.4 Considerations for session management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
45
46
46
46
47
47
Chapter 6. Session sharing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1 General overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1.1 Session management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2 Sharing sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2.1 Sharing a session between tags on a JSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2.2 Sharing a session between components of a single Web application . . . . . . . . .
6.2.3 Sharing a session between multiple Web applications . . . . . . . . . . . . . . . . . . . . .
49
50
50
52
52
52
53
Chapter 7. Object pooling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.1 General overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2 Object pooling and Domino JSP custom tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.3 Object pooling and MVC architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
57
58
58
59
Abbreviations and acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Other publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
63
63
63
64
64
64
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
iv
Using the Domino JSP Custom Tags
Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries. Consult
your local IBM representative for information on the products and services currently available in your area. Any
reference to an IBM product, program, or service is not intended to state or imply that only that IBM product,
program, or service may be used. Any functionally equivalent product, program, or service that does not
infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to
evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document. The
furnishing of this document does not give you any license to these patents. You can send license inquiries, in
writing, to:
IBM Director of Licensing, IBM Corporation, North Castle Drive Armonk, NY 10504-1785 U.S.A.
The following paragraph does not apply to the United Kingdom or any other country where such provisions are
inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of
express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made
to the information herein; these changes will be incorporated in new editions of the publication. IBM may make
improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time
without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any
manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the
materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring
any obligation to you.
Information concerning non-IBM products was obtained from the suppliers of those products, their published
announcements or other publicly available sources. IBM has not tested those products and cannot confirm the
accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the
capabilities of non-IBM products should be addressed to the suppliers of those products.
This information contains examples of data and reports used in daily business operations. To illustrate them
as completely as possible, the examples include the names of individuals, companies, brands, and products.
All of these names are fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrates programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs in
any form without payment to IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating platform for which the sample
programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore,
cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, and
distribute these sample programs in any form without payment to IBM for the purposes of developing, using,
marketing, or distributing application programs conforming to IBM's application programming interfaces.
© Copyright IBM Corp. 2004. All rights reserved.
v
Trademarks
The following terms are trademarks of the International Business Machines Corporation in the United States,
other countries, or both:
Domino®
IBM®
Lotus®
Notes®
Redbooks (logo)
Redbooks™
™
WebSphere®
Workplace™
The following terms are trademarks of other companies:
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems,
Inc. in the United States, other countries, or both.
Other company, product, and service names may be trademarks or service marks of others.
vi
Using the Domino JSP Custom Tags
Preface
This IBM® Redpaper discusses the Domino® JSP custom tag libraries and gives a broad
understanding of how to build and integrate portlet applications by using the Domino JSP
custom tags.
It provides an overview of the key technologies, including J2EE, WebSphere® Portal, and
Lotus® Domino. It then provides an in-depth look at using the Domino JSP custom tags as an
alternative to using either general-purpose portlets or the Java™ API for Lotus Collaborative
Components for integrating Lotus Domino applications into the WebSphere Portal framework.
The Redpaper covers the following topics:
򐂰
򐂰
򐂰
򐂰
Options for integrating Lotus Domino applications into WebSphere Portal
Basics of the underlying J2EE technologies
A brief introduction to the portlet concepts
A description of the Domino JSP custom tag libraries
This description includes a general overview of the Domino JSP custom tag libraries and
gives a brief introduction to the various tag groups and their functionality. It also addresses
some of the limitations that restrict the Domino JSP custom tags. Finally, it addresses
advanced development concepts such as session management or sharing and object pooling
in the context of the Domino JSP tags.
The team that wrote this Redpaper
This Redpaper was produced by a team of specialists from around the world working at the
International Technical Support Organization, Cambridge, Massachusetts Center.
Thomas Reske is an intern at the International Technical Support Organization, Cambridge
Center and studies Applied Computer Science at the University for Cooperative Education
(Berufsakademie), Stuttgart. He joined the University Education program of IBM Germany in
2002 and has been working on several projects related to Lotus Software products. His areas
of expertise include J2EE and J2ME development, WebSphere Portal, and Lotus Software.
Thanks to the following people for their contributions to this project:
򐂰 Steve Leland, Sr. Engineer, Messaging and Collaboration, Lotus Software
IBM, Westford, MA
򐂰 John Bergland, Project Leader
IBM International Technical Support Organization, Cambridge Center
򐂰 Peter K Weber, Senior Consultant
IBM Software Services for Lotus (ISSL) EMEA, Munich, Germany
򐂰 Leslie Weng, Senior I/T Specialist
IBM Software Services for Lotus (ISSL) Americas, Cambridge, MA
򐂰 Peter Janzen, Senior Product Manager, Lotus Software
IBM, Cambridge, MA
© Copyright IBM Corp. 2004. All rights reserved.
vii
Become a published author
Join us for a two- to six-week residency program! Help write an IBM Redbook dealing with
specific products or solutions while getting hands-on experience with leading-edge
technologies. You will team with IBM technical professionals, Business Partners, and/or
customers.
Your efforts will help increase product acceptance and customer satisfaction. As a bonus, you
will develop a network of contacts in IBM development labs, and increase your productivity
and marketability.
Find out more about the residency program, browse the residency index, and apply online at:
ibm.com/redbooks/residencies.html
Comments welcome
Your comments are important to us because we want our papers to be as helpful as possible.
Send us your comments about this Redpaper or other Redbooks™ in one of the following
ways:
򐂰 Use the online Contact us review redbook form found at:
ibm.com/redbooks
򐂰 Send your comments in an e-mail to:
redbook@us.ibm.com
򐂰 Mail your comments to:
IBM Corporation, International Technical Support Organization
1 Rodgers Street
Cambridge, MA 02142
viii
Using the Domino JSP Custom Tags
1
Chapter 1.
Integrating Lotus Domino into
WebSphere Portal
Many Lotus Notes®/Domino customers have made a strategic decision to use J2EE as the
platform for their business applications for the open standards, scalability, flexibility, and open
integration capabilities it provides. They are left wondering how their current Domino
infrastructure and existing investments in deployed Notes/Domino applications will fit into
their future IT infrastructure. This paper describes one integration option: how to integrate
Lotus Domino applications into a WebSphere Portal using the custom Domino JSP tag
libraries.
This chapter begins by providing a general introduction to both platforms, WebSphere Portal
and Lotus Domino. We introduce the basic concepts of portal technology and highlight the
key features and benefits offered by WebSphere Portal. We also discuss the primary benefits
and features of the Lotus Domino platform.
After the foundation has been established for each platform, we review a selected number of
possibilities to integrate an existing Lotus Domino application into WebSphere Portal. These
integration options include:
򐂰 General-purpose portlets included with Lotus Domino and WebSphere Portal
򐂰 Java API for Lotus Collaborative Components and Lotus Domino
򐂰 The Domino JSP custom tag libraries
Each option is described briefly, and the pros and cons for each approach are outlined. We
then use the advantages and disadvantages of each integration option as a basis for
positioning the merits of integration using the Domino JSP custom tags.
Finally, we introduce some of the key issues and considerations for exposing and integrating
(portalizing) Domino applications into a WebSphere Portal environment. These
considerations help to evaluate the conditions under which an implementation using the
Domino JSP custom tags is most applicable.
© Copyright IBM Corp. 2004. All rights reserved.
1
1.1 General introduction
The following sections provide a high-level introduction to both platforms, WebSphere Portal
and Lotus Domino. We begin with a review of the basic business and technical requirements
addressed by portal technology and discuss some the features that are offered by
WebSphere Portal. We also provide an overview of the key features and benefits of the Lotus
Domino platform.
1.1.1 Portal technology
During the past several years, demand has increased to integrate disparate content into a
seamless J2EE-based Web application. J2EE has proven to be a popular platform for
business applications because of the open standards, scalability, flexibility, and open
integration capabilities it provides. The technology and framework of a portal enables
developers to build Web applications capable of aggregating and integrating disparate data.
Accordingly, a portal is defined as a server (or set of servers) that aggregate content and
functionality while relying on a scalable infrastructure.
Along with the need to render multiple streams of vibrant data, the application server evolved
and added support for portals. Additionally, most portals are required to deliver personalized
content along with the possibility of customizing the “look and feel” of the application.
Today, portals serve as unified access points to a collection of applications over the Web to a
broad variety of client devices. They provide a secure and scalable environment that can be
extended easily.
1.1.2 WebSphere Portal platform
WebSphere Portal is a fourth-generation portal that is designed to meet the demand for
full-function, Web-enabled business. It offers an out-of-the-box portal solution that can be
customized easily for a heterogeneous community (such as a community that comprises
employees, suppliers, and customers).
A rich set of content and application choice is delivered to multiple client devices, including
pervasive devices through a single user interface. The content is automatically personalized
according to specific business rules and is highly customizable, which enables a single user
to organize his own portal view.
Communication and collaboration choices are extended by means of a real-time workplace,
so that portal users are aware of each other and can instantly work with each other. This
avoids breakdowns in communication, overcomes global logistical barriers, and helps to
exchange knowledge across the portal user community.
From this point of view, WebSphere Portal represents the next-generation desktop, which is
Web-enabled and enables user interaction across the portal. It provides user management
services that facilitate user self-management along with enterprise integration based on
directory services. It offers connection solutions to content management sources supporting
several common content types.
WebSphere Portal builds on an extensible framework tendering services for search and
taxonomy along with accessibility support, internationalization, and site analytics.
2
Using the Domino JSP Custom Tags
1.1.3 Lotus Domino platform
Lotus Domino is a comprehensive application development and deployment platform. It
enables you to quickly develop collaborative applications that unite people, data, and
processes. The Lotus Domino infrastructure offers all necessary resources to easily create
and deploy distributed applications that support a variety of clients. These clients use
replication based on offline and online services to synchronize application data securely.
Lotus Domino provides a document-based object model and supports several programming
languages. Multiple interfaces to the object model enable you to integrate Lotus Domino data
into disparate applications in a flexible way.
1.2 Lotus Domino integration into WebSphere Portal
The history of Lotus Domino reveals why Lotus Domino integration into a portal environment
is so significant.
Over the years, many organizations have utilized Lotus Domino for their internal application
development. Due to the enhancements made during several release cycles, Lotus Domino
products are still commonly used throughout these organizations. The spectrum of these
applications range from document stores to complex workflow tools. Often critical data and
business processes are contained within these Domino-based applications.
The development of a Domino Web application utilizing these existing applications represents
a challenge. Some of the challenging issues often are based on how to maximize scaling and
performance issues for Domino HTTP access. Additionally, delivery of personalized content
increases the number of requirements for an implementation. This makes it difficult to rely
solely on the Domino infrastructure to provide a Web-enabled workplace.
WebSphere Portal is designed to integrate the entire software portfolio offered by IBM. This
includes an organization's infrastructure based upon Lotus Domino and other Lotus
collaborative products. WebSphere Portal relies on open standards to provide a
comprehensive framework, enabling the integration of Lotus Domino assets with a single,
secure portal infrastructure.
More important, WebSphere Portal also utilizes the advanced collaborative capabilities of
Lotus Domino to achieve high levels of productivity. WebSphere Portal provides flexible,
global, and personalized data presentation based on profiles and business rules and helps to
support a global operating organization.
When you consider the strong collaboration, document-based capabilities of Lotus, combined
with the features of a WebSphere Portal environment, it is easy to understand the potential
benefits and the demand for a combination of both.
1.3 Integration considerations
There is an extensive range of different Lotus Domino applications that are utilized
throughout organizations. The main tasks performed in these application are sharing,
collecting, tracking, and organizing of information. There is an extensive number of
parameters that characterize each application. Naming just a few and the most obvious, the
parameters include:
򐂰 User statistics and control
򐂰 Properties of documents and information resources
Chapter 1. Integrating Lotus Domino into WebSphere Portal
3
򐂰 Client types
򐂰 Application complexity
򐂰 Application topology
Combining the benefits of both environments (the Lotus Domino collaborative environment
and the Portal environment) is the primary challenge in moving Lotus Domino applications
into WebSphere Portal. Often this challenge is simplified by focusing on a specific
methodology to embed content into a portal. Keep in mind, however, that running applications
within a portal environment provide more than simply the ability to display and aggregate
content. Most important, it enables different Web applications to cooperate and collaborate
with each other within a single framework. You should give careful consideration to which
integration option to choose in order to find the proper balance among the factors that take
advantage of the portal framework and other parameters, such as the available time frame,
overall environment infrastructure, available skills, performance requirements, and costs.
There are several ways to integrate a Lotus Domino application into WebSphere Portal. Each
differs in its character and integration degree. To provide the proper context and positioning
for the approach using the Domino JSP custom tag libraries, this chapter outlines the
following integration options:
򐂰 Using general-purpose portlets
򐂰 Using the Java API for Lotus Collaborative Components and Lotus Domino
򐂰 Using the Domino custom JSP tags
Attention: In this paper, we provide an overview of each integration approach for
portalizing Domino applications. To review each of these integration approaches in greater
detail, refer to the redbook Portalizing Domino Applications: Integrating with Portal 5.02
and Lotus Workplace, SG24-6466, available at:
http://www.redbooks.ibm.com/abstracts/sg246466.html
1.3.1 General-purpose portlets
The first option to integrate Lotus Domino applications into WebSphere Portal is to use
general-purpose portlets. These portlets are shipped with Lotus Domino, WebSphere Portal,
and Lotus Workplace, and are available from third-party sources. They provide an easy way
to access Domino application and embed content into the portal framework.
The Domino Application Portlet is one example of such a portlet. It acts like a reverse proxy
and delivers content from existing Domino Web applications to the user client through
WebSphere Portal. The content that is produced by the Domino HTTP server is rewritten by
rule-based parsers and displayed to the client.
Attention: To review the functionality and configuration of the Domino Application Portlet
in greater detail, refer to the Redpaper Domino Application Portlet: Configuration and Tips,
REDP-3917, which is available at:
http://www.redbooks.ibm.com/redpieces/abstracts/redp3917.html
Another approach is to use multiple general-purpose portlets and combine their functionality
to create a basic portal application that implements the basic characteristics of the Lotus
Domino application.
If either a single general-purpose portlet or a combination that fulfill the requirements is
available, it is the plainest option and requires the least amount of development skills. Often it
is not even necessary to be familiar with the technologies involved to perform successful
implementations.
4
Using the Domino JSP Custom Tags
On the other hand, the usage is limited by the functional capabilities of the portlets. Even
though possibilities may exist to customize the configuration of the portlets used, the portlets
are often designed to link or display Web-enabled Domino data that restricts the field of
application and may not be suitable to fully utilize the features of the portal framework.
1.3.2 Java API for Lotus Collaborative Components and Lotus Domino
Another, and the by far most advanced option to integrate your Domino application is to utilize
the Java API for Lotus Collaborative Components and Domino. Using Java provides the best
way to overcome certain integration limitations as session management, customizing and
object pooling. But it also requires expertise Java knowledge and increases the development
time in most of the cases.
In general you can implement a Lotus Domino application that takes full advantage of the
WebSphere Portal framework. This includes collaboration services, comprehensive methods
to interact with multiple portlet applications and other benefits provided by the WebSphere
Portal environment.
1.3.3 The Domino JSP custom tag libraries
An intermediate solution is the employment of the Domino JSP custom tag libraries, which
enable WebSphere Portal to access the rich set of collaborative capabilities of Lotus Domino.
They provide a quick and easy technique to incorporate Lotus Domino applications by adding
custom tags to a JavaServer Page that can be displayed on the portal.
While the Domino JSP custom tags can be used to expose Domino data and functionality
easily, it requires a certain expertise to combine and apply the benefits of WebSphere Portal
to the Web application. The use of the Domino custom JSP tag libraries is restricted by
certain limitations that are related to design and performance and is not suitable to
outperform a custom Java implementation. Even though an implementation based on the
Domino JSP custom tags cannot stand to benefit from all of the features that a portal
environment offers, it is capable of supporting some of the key features WebSphere Portal
provides. Using the Domino JSP custom tags introduces any developer to the issues involved
in portalizing Lotus Domino applications. The Domino JSP custom tag library can be used to
enable WebSphere Portal to aggregate Lotus Domino content, combine it with some of the
key features of WebSphere Portal, and render the result on a JSP.
The following chapters cover a detailed introduction to the Domino JSP custom tag libraries
and the technologies that are involved. They point out the possibilities provided, while also
trying to inform developers for the issues that cannot be addressed within the WebSphere
Portal framework.
1.3.4 Domino custom JSP tags: positioning relative to other integration options
One of the key questions asked by Domino developers with limited knowledge of Java is
which option for integration and portalizing Domino applications is the best starting point.
There is not a simple answer, because it is influenced by each individual application and
available skills. At the very least, however, this next section helps provide greater context for
where the custom Domino JSP tags fit, relative to the other technical approaches for
integrating Domino and Portal.
Figure 1-1 on page 6 gives an overview of all options that are available for portalizing Domino
applications. Note that the horizontal axis illustrates an increasing range of customization for
integrating your application, and the vertical axis illustrates the degree of J2EE skills that are
required for each approach. Depending on the knowledge of developing portlets (or Java
Chapter 1. Integrating Lotus Domino into WebSphere Portal
5
applications in general) (shown vertical) and the level of customization needed when
integrating (shown horizontally), numerous options are available.
Figure 1-1 Skills and customization for Integration options
The main message to take from this graphic is that the Domino custom JSP tags approach
represents an excellent option for a high degree of customization, while only requiring
intermediate Java knowledge.
Keep in mind that, depending on the solution you need, a combination of several options may
be required. For example, if portlets built by the IBM Portlet Builder for Domino must be
fine-tuned, it may be necessary to use Domino JSP tags, the Domino Java API, or both.
Here are the key points from each integration approach.
򐂰 Existing portlets
– For using the existing portlets, relatively no J2EE knowledge is necessary. The portlet
can be selected from the portlet catalog.
– Only simple information must be entered (Domino Server name, database name).
– Existing portlets offer a very limited set of functionality for customizing.
– Existing portlets will most likely be used by line-of-business and power users.
򐂰 Lotus Workplace Builder
– The Lotus Workplace Builder offers the user with limited J2EE knowledge the
possibility to integrate a set of portlets into Lotus Workplace.
– Only simple information must be provided to build the workplace content.
– The Lotus Workplace Builder will be used by line-of-business and power users.
6
Using the Domino JSP Custom Tags
򐂰 IBM Portlet Builder for Domino
– The IBM Portlet Builder for Domino provides a complete and rapid integration tool to
bring valuable Domino-based information and data into WebSphere Portal.
– This portlet creates other portlets that are tuned to specific tasks, databases, or sets of
databases.
– IBM Portlet Builder is a subset of WebSphere Portal Application Integrator (WPAI)
technology.
– The target audience includes line-of-business and power users.
򐂰 Bowstreet Portlet Factory
– The Bowstreet Portlet Factory is a third-party portlet building tool. It is comparable to
the IBM Portlet Builder for Domino, but has more possibilities for building and profiling
portlets.
– The target audience is line-of-business and power users, and developers who want to
reduce time in creating portlets.
򐂰 Domino JSP tags
– The Lotus Domino Toolkit for WebSphere Studio is a plug-in for WebSphere Studio
Application Developer and WebSphere Studio Site Developer. It enables you to add
Domino 6 custom tags to JavaServer pages (JSP), providing a simple way to blend
Domino and J2EE applications.
– JSP tags are XML tags embedded in a JSP providing data access, data input, and
process control. The tags abstract the Domino objects for Java (Domino Java API) and
provide a quick development turnaround for building J2EE applications that use
Domino data and services.
– Domino JSP tags can be used for building portlets alone or extending portlets created
with a builder.
– The target audience is Java language developers and Domino developers with Java
language skills.
򐂰 APIs
– There are many APIs that can be used to create portlets for accessing Domino data.
– The target audience is Java language developers and Domino developers with strong
Java language skills.
The following summary illustrates the options to integrate Domino within WebSphere Portal
via portlets, sorting by target audience.
Chapter 1. Integrating Lotus Domino into WebSphere Portal
7
Options for line-of-business and power users
򐂰 Use the out-of-the-box Notes/Domino.
򐂰 Use the Lotus Workplace™ Builder.
򐂰 Use the IBM Portlet Builder for Domino.
Figure 1-2 Options for line-of-business and power users
Options for mid-level script developers
򐂰 Use the IBM Portlet Builder for Domino.
򐂰 Use the Bowstreet Portlet Factory.
򐂰 Use Domino JSP tags (Domino Toolkit for WebSphere Studio).
Figure 1-3 Options for mid-level script developers
8
Using the Domino JSP Custom Tags
Options for professional Domino and J2EE developers
򐂰 Use Bowstreet Portlet Factory.
򐂰 Use Domino JSP tags (Domino Toolkit for WebSphere Studio).
򐂰 Use APIs.
Figure 1-4 Options for professional Domino and J2EE developers
Chapter 1. Integrating Lotus Domino into WebSphere Portal
9
10
Using the Domino JSP Custom Tags
2
Chapter 2.
J2EE technologies
This chapter provides an overview of the J2EE technologies that are involved in the
integration of Lotus Domino applications into WebSphere Portal.
It begins with an introduction to the J2EE platform and briefly discusses the main benefits
J2EE offers.
Additionally, the primary underlying technologies are covered. These are:
򐂰 JavaServer Pages technology
– Introduction to JavaServer Pages
– Behind the scenes: invoking JavaServer Pages
– Components of a JavaServer Page
򐂰 Servlet technology
Within the context of WebSphere Portal, these components are extended by portlets. The
concept of portlets is introduced in order to finalize the overview of the main J2EE
technologies that are involved when exposing Lotus Domino content on WebSphere Portal.
© Copyright IBM Corp. 2004. All rights reserved.
11
2.1 J2EE platform
Java 2 platform, Enterprise Edition (J2EE) is a comprehensive set of synchronized
specifications for designing, developing, deploying, and managing multitier distributed
server-based applications. J2EE describes the runtime environment for a J2EE application.
This environment includes application components, containers, and resource manager
drivers. The elements of this environment communicate with a specified set of standard
services.
2.2 Main benefits of the J2EE platform
The main benefits provided by the J2EE platform include:
򐂰 Modular and standard-based architecture
By offering the possibility to rely on the modular and standard-centric environment
described by the J2EE platform, you can significantly reduce the complexity of developing
and deploying multitier solutions. With predefined services, many application details are
handled automatically. This results in reduced risk during the development cycle.
򐂰 Interoperability and compatibility
By representing a set of technologies that many vendors can implement and extend, J2EE
and its standards guarantee interoperability and compatibility among the J2EE application
vendors. Vendors are invited to develop competing implementations, but all of these
implementations rely on the same standards and APIs. A J2EE Compatibility Test Suite
ensures the portability of J2EE applications and components. Components and
applications that are compliant to the J2EE specifications can be run on any other J2EE
Application Server.
򐂰 Connectivity
J2EE enables applications to connect to external applications through technologies and
standards that let you easily expose business logic to Web applications. J2EE is capable
of delivering data to a set of heterogeneous clients offering the basis of a multi-channel
e-business infrastructure.
򐂰 Tier separation
J2EE is based on containers that provide clear separation of business components and
enterprise services. This enables the developer to focus on business logic rather than
developing infrastructure code, such as Java Servlets and JavaServer Pages (JSP). It
also makes it possible to simplify Web development by providing a flexible infrastructure
for component communication and session management within a Web application that is
integrated with the Web server.
This is the main advantage that J2EE offers from a design point of view: the separation of
tiers that compose an application. While data, business logic, and presentation objects
within a Domino application are held within a single file, J2EE builds on several containers
representing different logical tiers. Figure 2-1 on page 13 illustrates the separation of tiers.
12
Using the Domino JSP Custom Tags
Figure 2-1 Separation of tiers
– Client tier
This tier contains the end-user clients, which interact with the services provided by
server-side components. Clients can include mark-up language pages and applets
running in browsers, Java applications, and other applications that are interoperable
with Java.
– Middle tier
This tier consists of the Web container and the EJB container. Both are J2EE runtime
components.
The EJB container holds the business logic and is designed to provide seamless
access to relational databases and enterprise information systems with transactional
integrity. Along with the data storage and access facilities, it is possible to embed the
business logic of the application within the components of the EJB container because
they offer high performance and availability mechanisms.
The Web container is designed to construct presentation components and to control
the presentation logic. It is based on technologies that offer high-performance,
extendible presentation framework, such as Java Servlets and JavaServer Pages. The
container is also a host to other technologies, such as Web Services and XML-XSLT
applications.
– Enterprise information tier
This tier contains resources such as databases and other information systems. It is
considered to be the provider of data access and storage.
The Web Container and the EJB container are the main blocks that construct a J2EE
application server. The WebSphere Portal allows the construction of Portlet applications
that reside on the Web container, so that the focus remains on this container. This is
important as we discover the options offered by the Domino JSP custom tag libraries for
integrating a Domino application into WebSphere Portal. The portlet components extend
the Servlet component and can present its information using JSP pages. As we are going
to add the custom Domino tags into these JSP pages, it is necessary to explore the
Servlet and JSP technology in more detail.
Chapter 2. J2EE technologies
13
2.3 JavaServer Pages technology
The following sections discuss the underlying technology and components of JavaServer
pages. Additionally, we describe the process that occurs when a JSP file is invoked.
2.3.1 Introduction to JavaServer Pages
A JavaServer Page is a single component of the J2EE Web container. It is similar to an HTML
or XML page but provides the possibility to include and display dynamic content within Web
pages. JSP technology was developed to separate the development of dynamic Web content
from static Web page design. The result of this is that the presentation design can be altered
without the need to change the underlying dynamic page content. This is useful in the
development life cycle, because Web page designers do not have to know how to create the
dynamic content. Instead, they simply have to know where to place the dynamic content
within the page.
To facilitate embedding of dynamic content, JSPs use tags that enable the page designer to
insert the properties of a JavaBean object and Enterprise JavaBeans. Therefore, JSPs
realize the advantages offered by these technologies, such as the inherent reusability. Also,
JavaScript is supported by JSPs and can be used to add page-level functionality to the JSP.
Combined with the portability and platform independence, these features describe the
advantages of the JSP technology over most of the other options for creating dynamic Web
content.
2.3.2 Behind the scenes: invoking JavaServer Pages
A JSP file is stored on the file system in text format. On the first invocation of the file (the first
HTTP request to the page or the first request of the page after changing the underlying JSP
file), the contents of the file are parsed by the JSP engine and translated into servlet source
code by the application server. The generated servlet is responsible for rendering the static
contents of the JSP file at design time, as well as the dynamic components of the Web page.
The source code is compiled into a servlet class file. The servlet is instantiated and executed.
The rendered content specified by the original JSP file is returned through the output stream
of the servlet response object.
Any subsequent request to the page will invoke the generated servlet to serve the content to
the client. The servlet remains in service until the application server is stopped, the underlying
JSP file is altered causing a recompilation, or the servlet is manually unloaded. Figure 2-2 on
page 15 illustrates this process.
14
Using the Domino JSP Custom Tags
Figure 2-2 Invoking a JavaServer Page
2.3.3 Components of a JavaServer Page
JavaServer Pages embed Java code through the use of scripting tags. These tags can be
grouped into five major categories:
Table 2-1 JSP scripting tags
Directives
These elements provide the J2EE Application server global information about the
JSP file. The instructions are processed by the JSP engine on compilation time.
Directives are used to set instructions on page level, insert data from external files,
and to declare custom tag libraries.
The syntax is: <%@ and %>
Declarations
These tags are used to include custom methods or to define variables that can be
used in subsequent expressions or scriptlets. Declared variables map to servlet
instance variables and should not be modified during the request.
The syntax is: <%! and %>
Expressions
The elements are used to display dynamic content. The expression tags are
replaced by the evaluated Java code at runtime.
The syntax is: <%= and %>
Scriptlets
These tags are general purpose Java tags: They are used to embed Java blocks
within a JSP. Java blocks declared within a scriptlet are inserted in the servlet that
is generated from the JSP.
The syntax is: <% and %>
Comments
Comments are stripped from the page by the JSP engine when executed. JSP
comments are not returned to the client.
The syntax is: <%-- and --%>
Additionally, JSPs are capable of embedding XML and HTML tags as well as custom tags.
The concept of custom tags is introduced in Chapter 3, “The Domino JSP custom tags” on
page 19.
Chapter 2. J2EE technologies
15
2.4 Servlet technology
A servlet represents a Java class that extends the capabilities of a J2EE Application Server
through the request-response paradigm. In general, a servlet can respond to any kind of
request, so it is possible to implement any Web application through the use of servlets.
Servlets support dynamic Web content, filter data, provide database access, and can be used
to serve multiple clients. Most servlets are used in a Web environment where HTTP is used
between a Web client device and the application server. Most implementations extend the
HttpServlet class and override the standard methods. These methods are:
򐂰
򐂰
򐂰
򐂰
򐂰
init
service
doGet
doPost
destroy
The init and destroy methods are used to define the beginning and the end of the servlet
lifecycle. Service, doGet and doPost provide servlet-specific behavior that is executed in
response to certain request, such as the HTTP GET or POST request.
2.5 Portlet technology
The following section provides a brief overview of portlets and describes in technical detail
how they are constructed.
2.5.1 Introduction to portlets
Portlets are the heart of a portal. The term portlet refers to a small portal application, usually
depicted as a small box on a Web page. Figure 2-3 on page 17 shows a sample Web page
that contains several portlets.
A portlet is a reusable Web module that runs on a portal server. Portlets have predefined
roles such as retrieving news headlines, searching a database, or displaying a calendar. Web
pages, Web services, applications, and syndicated content feeds can be accessed through
portlets.
16
Using the Domino JSP Custom Tags
Figure 2-3 Dynamic workplace example
2.5.2 Introduction to the Portlet class
Every portlet indirectly extends the abstract Portlet class. The abstract Portlet class extends
the HttpServlet class. Thus, each portlet inherits from the HttpServlet (that is, a portlet is a
special type of servlet). As a result portlets are deployed similar to servlets, but are managed
more dynamically. Changes to portlet settings or even installations or deinstallations of portlet
applications can be performed without the need to restart WebSphere Portal.
2.5.3 Concepts
After deploying a portlet on WebSphere Portal, a concrete portlet is created (a portlet that is
parameterized by a PortletSettings object), which contains configuration data defined in the
Portlet Deployment Descriptor. Multiple concrete portlets are associated to a single portlet,
but a single concrete portlet can be shared across multiple users.
Placing a concrete portlet on a page initializes a concrete portlet instance parameterized by a
single PortletData object. The scope of the PortletData object is dependent on the page. For
each user who has the rights to edit and executes an edit process, a concrete portlet instance
is created. Therefore the PorletData object of a page that is accessed by a group of users
could contain data for several users, but the PortletData of a page that is accessed by a
single user only contains data that is specific for the user.
When a user accesses a page, a user portlet instance is created. During the logon process
WebSphere Portal creates a PortletSession object for each user portlet; that is, the user
portlet instance is a concrete portlet instance that is parameterized by a single
PortletSession. The PortletSession object stores transient information about a single user.
Chapter 2. J2EE technologies
17
18
Using the Domino JSP Custom Tags
3
Chapter 3.
The Domino JSP custom tags
This chapter provides a general introduction to the Domino JSP custom tag libraries.
It consists of the following sections:
򐂰 JSP tag libraries and custom tags
򐂰 Tag Library Descriptor
򐂰 The Domino JSP custom tag libraries
© Copyright IBM Corp. 2004. All rights reserved.
19
3.1 Introduction
This section introduces the concepts of JSP tags, custom tags, and tag library descriptor files.
It then describes the specific Domino JSP custom tag libraries.
3.1.1 JSP tag libraries and custom tags
A JSP tag library is a collection of custom tags. Custom tags invoke custom actions (reusable
modules that perform specific tasks such as form processing, enterprise services, and
accessing databases). These are tasks that recur across multiple Web applications. A main
advantage of implementing a custom tag library is the separation of the Web page design and
the implementation of the Java modules. The collection of tags can include Java content on a
JSP, without getting into the details of the actual Java code invoked by the custom tags.
Recapitulating the library defines a declarative and modular functionality that can be reused
by any JSP.
3.1.2 Tag Library Descriptor
A Tag Library Descriptor is an XML file that defines the tags. This XML document contains
information about the tag library in general as well as each specific custom tag. General
information about the tag library includes version specifications, a shortname, a unique URI
identifier, and a description of the library. Elements describing the tags include the tag
handler class, the object that is invoked to evaluate the custom tag, and tag-dependent
elements. Therefore the Tag Library Descriptor (TLD) is used during the parsing and
compiling of the JSP and defines which Java classes and methods are interpreted.
3.1.3 The Domino JSP custom tag libraries
The Domino JSP custom tag libraries comprise both:
򐂰 Collaboration tags for accessing standard, back-end objects in the Domino data repository
򐂰 Utility tags performing tasks that are common to all J2EE Web containers
The libraries are intended to include Lotus Domino elements into J2EE and Portal
applications.
They were designed both for developers having limited Java knowledge or for developers
having limited knowledge of the Lotus Domino back-end objects. Because the libraries are
enabled to either incorporate Java content or to access Lotus Domino objects, both groups of
developers can extend a Web application to leverage the complex Lotus Domino interactions
by utilizing custom tags. Because it is based on J2EE architecture, WebSphere Portal
enables the inclusion of JSP files, which can be used to expose Lotus Domino applications
within the WebSphere Portal environment.
Defining the Domino JSP custom tags
Two Tag Library Descriptors define the capabilities of the Domino JSP custom tag libraries:
򐂰 domtags.tld
This TLD comprises the interworking collection of tags that can be used to access the
Lotus Domino objects.
򐂰 domutil.tld
This TLD includes utility tags that perform non-Domino-specific operations based on
conditions and expressions. The tags invoke actions that are common to all J2EE Web
containers.
20
Using the Domino JSP Custom Tags
The Domino JSP custom tag library Java archives
The actual Java implementation that is invoked by the Domino JSP custom tags resides on
three Java archive (JAR) files:
򐂰 domtags.jar
򐂰 NCSO.jar
򐂰 Notes.jar
Notes.jar and NCSO.jar contain the core classes of the Java API for Lotus Domino. The
classes within domtags.jar rely on the Java implementation that is provided by these two
archives. Depending on the physical topology of the environment, one of the archives must
be used.
򐂰 If your Domino server is on the same physical machine as your J2EE application server,
Notes.jar has to be used. The classes in Notes.jar assume a local access environment.
򐂰 If the servers reside in different physical locations you have to use NCSO.jar. This archive
includes classes that enable remote access through the Domino Internet Inter-ORB
Protocol (DIIOP).
Alternatively, if you wish to have a testing or development environment that would include
both the Domino Server and the J2EE Application server located on the same physical
machine, you can include both the Notes.jar and NCSO.jar on the same physical machine.
The reasons for doing this could be:
򐂰 You want to perform certain testing or development tasks and wish to take advantage of
performance improvements by accessing the Notes.jar archive locally and not using
Remote Method Invocation (RMI) over IIOP.
򐂰 If you wish to test or develop in an environment that more closely mimics a distributed
environment, you can run the Domino Server locally (with the DIIOP task running) and use
RMI/ IIOP.
Important: WebSphere Portal 5.0.2.2 ships NCSOW.jar. Replace that file with NCSO.jar
from Domino 6.x if going against a Domino 6.x server.
Adding support for Domino JSP custom tags
To use the Domino JSP custom tags in an application, you have to perform the following:
1. Copy domtags.jar from the Lotus/Domino/Data/domino/java directory to the
WebContent/WEB-INF/lib directory for the application.
2. Depending on the environment topology:
a. Using remote access, copy NSCO.jar from the Lotus/Domino/Data/domino/java
directory to the WebContent/WEB-INF/lib directory for the application.
b. Using local access, copy Notes.jar from the Lotus/Domino/ directory to the
WebContent/WEB-INF/lib directory for the application.
c. Alternatively, you can place the jar file in the <was_root>/AppServer/lib directory.
3. Create a new folder, tld, in the WebContent/WEB-INF directory of your application.
4. Copy domtags.tld and domutil.tld from the Lotus/Domino/Data/domino/java directory to
the WebContent/WEB-INF/tld directory of your application.
5. Verify that your WEB-INF folder hierarchy has a structure similar to Figure 3-1 on page 22.
Chapter 3. The Domino JSP custom tags
21
Figure 3-1 Sample folder hierarchy
6. Create the necessary tag library XML tags in the Web Deployment Descriptor of the
application:
a. Switch to the J2EE Hierarchy view.
b. Expand the Web Modules folder and open according the Web Deployment Descriptor.
c. Switch to References, and click the JSP tag libraries tab.
Figure 3-2 Open the JSP tag libraries tab.
d. Click Add, select WebContent/WEB-INF/tld/domtags.tld, and click Finish.
e. Click Add, select WebContent/WEB-INF/tld/domutil.tld, and click Finish.
22
Using the Domino JSP Custom Tags
Figure 3-3 Add Domino JSP custom tag libraries
f. Switch to Source.
g. Verify that the XML tags have been added to your Web Deployment Descriptor as
described in Example 3-1.
Example 3-1 XML tags in the Web Deployment Descriptor
<taglib>
<taglib-uri>/WEB-INF/tld/domtags.tld</taglib-uri>
<taglib-location>/WEB-INF/tld/domtags.tld</taglib-location>
</taglib>
<taglib>
<taglib-uri>/WEB-INF/tld/domutil.tld</taglib-uri>
<taglib-location>/WEB-INF/tld/domutil.tld</taglib-location>
</taglib>
This approach is sufficient if the components that take advantage of the Domino JSP custom
tag library Java archives are defined in the same Web application.
If multiple Web applications use these Java archives, you should place a single set of the
JAR files into the <wp_root>/shared/app directory of the WebSphere Portal. This gives the
components of all Web applications the ability to access the set of JAR files. In this case, it is
not necessary to package the archives in the several applications.
Chapter 3. The Domino JSP custom tags
23
24
Using the Domino JSP Custom Tags
4
Chapter 4.
Using the Domino JSP custom
tag libraries
This chapter contains information about how to use the Domino JSP custom tags. It provides
an overview of existing tags and discusses how some of the tags occur in a specific context.
To discuss the various tags, we approach this by grouping the tags together based on their
functionality. This is the primary focus of this chapter.
After a short introduction to the key relationships in the Lotus Domino containment hierarchy
the major tag groups are covered. These are:
򐂰 Core tags
򐂰 Data access tags
򐂰 Data input tags
򐂰 Process control tags
򐂰 Utility tags
Finally, we cover the issue of “Programmatic access of underlying Domino Java Objects”. This
is another key area of functionality provided by the tags.
After finishing this chapter, the reader will have knowledge on how to use the Domino JSP
tags, and to better understand in which context the use of the Domino JSP custom tags may
be appropriate. This chapter does not cover the various attributes the tags offer. More
importantly, the focus is set on a high-level overview of which tags do exist and when to use
them.
© Copyright IBM Corp. 2004. All rights reserved.
25
4.1 The Lotus Domino object architecture
Domino objects are based on a conceptual containment model. The scope of each object is
defined through this model. Container objects are used to obtain contained objects. Some of
the key containment relationships are shown in Figure 4-1.
Figure 4-1 The Domino Object containment hierarchy
Domino JSP custom tags take advantage of the containment hierarchy described above.
Each Domino JSP custom tag may contain other specific tags. In order to access a low-level
tag, all tags wrapping the specific tag have to be implemented. The context of a Domino JSP
custom tag is parameterized by its wrapping tag. (A single tag defines the context for all
enclosed tags.) Some of the tags are valid only in the context of the enclosing tag.
In general, the tags are divided into four major groups, as shown in Table 4-1.
Table 4-1 Domino JSP custom tag types
Function
Data access tags
Gain access to the most important objects of the Domino hierarchy.
Data input tags
Allow information input from a JSP to the Lotus Domino application.
Process control tags
Modify or query the state or properties of the Lotus Domino application.
Utility tags
Flow control of presentation logic based on conditions and expressions.
4.2 Core tags
The tags that are most commonly used when accessing Domino data are called core tags:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
26
document
form
ftsearch
mailto
runagent
view
Using the Domino JSP Custom Tags
Defining the core tag environment
These sections describe the session and db tags and how to set the default JSP values.
The session and db tags
The environment for the core tags is defined by the session tag. The session tag initializes and
dismantles the Domino session and provides the possibility to wrap tags that access different
databases. More information about Domino sessions and performance-oriented
implementations regarding the Domino JSP custom tags is covered in Chapter 6, “Session
sharing” on page 49, and Chapter 7, “Object pooling” on page 57.
A database context for all enclosed tags is provided by the db tag. These two tags establish
the environment for the top-level Domino JSP custom tags. Top-level tags that use the same
environment should always be wrapped in exactly the same environment, with the same tags.
Example 4-1 Wrapping top-level Domino JSP custom tags
<domino:session
user="<%= username %>"
password="<%= password %>"
host="<%= hostname %>"
duration="<%= duration %>">
<domino:db dbname="<%= firstDb %>"
<%-- Database:specific code --%>
</domino:db>
<domino:db dbname="<%= secondDb %>"
<domino:view viewname="<%= viewName %>">
<%-- View-specific code --%>
</domino:view>
<domino:ftsearch
query="<%= queryString %>"
options="<%= option %>">
<%-- Search-specific code --%>
</domino:ftsearch>
</domino:db>
</domino:session>
Setting default JSP attribute values
There are several ways to define default attributes for the Domino JSP custom tags. The most
commonly used is storing an initialization parameter in the Web Deployment Descriptor. The
Domino JSP custom tags provide the possibility to define default attribute values in the JSP
page. The tags used are:
򐂰 default
򐂰 preset
The default tag can be used to override a specified default value. Both tags can be used to
define global information, such as information about how to handle error occurrences.
Example 4-2 Defining error handling using the default or preset tag
<domino:preset scope="<%= scope %>" onfailure="inline"/>
<%-- or --%>
<domino:preset scope="<%= scope %>" onfailure="exception" />
<%-- or --%>
<domino:default scope="<%= scope %>" onfailure="exception" />
<%-- or --%>
<domino:default scope="<%= scope %>" onfailure="inline" />
Chapter 4. Using the Domino JSP custom tag libraries
27
Using a profile document
The Domino JSP custom tags support the use of profile documents. The properties stored in
the database profile documents can be accessed and used on a page.
Example 4-3 Accessing the database profile documents
<domino:profiledocument
profilename="<%= profileName %>"
profileuser="<%= profileUser %>"
id="profile" />
Using the mechanism described in 4.7, “Programmatic access of underlying Domino Java
Objects” on page 44 enables retrieval of values from the profile document.
4.3 Data access tags
Data access tags enable the user to gain access to several of the most important objects in
the Lotus Domino object hierarchy, described in 4.1, “The Lotus Domino object architecture”
on page 26.
Full-text search
The ftsearch tag performs a full text search of a database. The search parameters are defined
within the attributes of this tag. The returned result consists of a list of documents that fit the
search criteria.
Example 4-4 Performing a full-text search
<domino:ftsearch
query="<%= queryString %>"
options="<%= option %>"
sort="<%= sortOption %>"
max="<%= maxNumOfDocs %>">
<%-- Search-specific code --%>
</domino:ftsearch>
Domino view
A Domino view is a sorted or categorized document list that represents the point of access to
the data stored in the database. In order to access this information use the view tag. The
result of this tag is a list of documents that builds a specific subset of documents. By
specifying additional attributes, the number and type of documents that are returned can be
parameterized.
Iterating through lists of documents
The results of some of the top-level Domino JSP custom tags are in the form of a document
list. This includes the ftsearch, view, and db tags. In addition, some other tags produce lists of
documents that represent the result of a tag, for example a selection. In order to access data
held by each document, it is necessary to iterate through the document sets.
The generic way to iterate through a document collection is the docloop tag. In the context of
a view tag, the viewloop tag should be used because with this tag, you can take advantage of
the data stored in the view index, which leads to an increase of the application performance.
Using the docloop tag enclosed by a view tag requires loading a document for every entry in
the view.
28
Using the Domino JSP Custom Tags
Note: If you use the docloop tag within the context of the view tag, there will be a
performance hit. The viewloop tag is a good alternative to use for views; it evaluates the
body once per entry in the view instead of loading a document for each entry in the view.
Example 4-5 Iterating through lists of documents
<domino:db id="myDb" dbname="<%= dbname%>">
<domino:view viewname="<%= viewname %>">
<domino:viewloop>
<%-- Loop-specific code --%>
</domino:viewloop>
</domino:view>
<domino:ftsearch
query="<%= queryString %>"
options="<%= option %>">
<domino:docloop>
<%-- Loop-specific code --%>
</docloop>
</domino:ftsearch>
<domino:docloop>
<%-- Loop-specific code --%>
</docloop>
</domino:db>
To be able to display content on the JSP even if, for example, the document collection
returned by a view is empty, use the novalues tag.
Example 4-6 Using the novalues tag
<domino:view viewname="<%= viewname %>">
<domino:novalues>No existing entry!</domino:novalues>
</domino:view>
Items
Iterating through document lists enables you to render content repeatedly. To access the data
stored in a document you must access several item objects by using the item tag.
Example 4-7 Using the item tag
<domino:docloop>
<domino:item id="myFirstItem" name="<%= itemName %>"/>
<domino:item id="mySecondItem" name="<%= itemName %>"/>
.
.
</domino:docloop>
Additionally, in the context of a docloop the formula tag can be used. The body of this tag
represents a Domino formula that is evaluated and can be displayed.
Example 4-8 Using the formula tag
<domino:docloop>
<domino:formula
id="myFormula">@function</domino:formula>
.
.
</domino:docloop>
Chapter 4. Using the Domino JSP custom tag libraries
29
In the context of a viewloop, the viewitem tag is recommended. This tag enables access to
the data stored in the columns of the view.
Example 4-9 Using the viewitem tag
<domino:viewloop>
<domino:viewitem id="myFirstItem" col="1"/>
<domino:viewitem id="mySecondItem" col="2"/>
.
.
<%-- or --%>
<domino:viewitem id="myItem" name="<%= itemName %>"/>
</domino:viewloop>
Selection and action handling
Selection
In the context of a viewloop, you can select certain entries of a view by using the selectentry
tag. The tag provides a checkbox that enables selection of multiple entries. The selection
subset is processed by implementing the selectedloop tag.
Action handling
To define the way the selected entries are processed, you can define an action tag to place a
navigation tag on the page that invokes an action on the server. The processing of the action
takes place in an ifserverevent tag, whose event attribute is set to OnAction.
Note: In Example 4-10, we have hard-coded the values for simplicity. In a real code
example, use variable names that reference the proper values in your environment.
Example 4-10 Selection of view entries and action processing
<domino:session host="itso-dom.cam.itso.ibm.com" user="wpsadmin" password="wpsadmin">
<domino:db id="id_name_01" dbname="redbook/sales.nsf">
<domino:view viewname="spNumber" enableselect="true">
<domino:action name="myAction" text="Promote selected Sales Person(s)">
</domino:action>
<domino:ifserverevent event="OnAction" for="myAction">
<domino:runagent name="agntPromote" />
</domino:ifserverevent>
<br>
<br>
<domino:viewloop>
<domino:selectentry />
<domino:viewitem name="Sales Person" />
<br>
</domino:viewloop>
</domino:view>
</domino:db>
</domino:session>
This code example generates a result similar to Figure 4-2 on page 31.
򐂰 This (part of a) JSP displays the content of a view, including selection boxes for each entry.
򐂰 An action link has been placed at the top of the view.
򐂰 Click that link to run a Domino agent (agntPromote).
30
Using the Domino JSP Custom Tags
Figure 4-2 Action link above selection boxes for each entry
4.4 Data input tags
Data input tags enable the input of information from a JSP file to the Domino application. This
section highlights some of the key tags.
Accessing single database documents
There are several ways to display, create, and edit documents. All processes require use of a
unique ID for each document. The unid tag enables access this unique ID, which can be used
to retrieve the specific document from the databases.
This can be achieved by providing the ID to a form or document tag. Both tags can be used to
display or edit the documents in a database context.
If you do not provide the unique ID, a new document is created. Edited or newly created
documents can be saved to the database, so the two tags are considered Data Input Tags.
The difference between the tags is that the form tag enables input validation. Additionally,
other Data Input Tags and action tags are supported.
In the context of the form tag, you can use the nodocument tag. This tag displays an alternate
message in case the specified unique ID attribute cannot be found.
Example 4-11 The nodocument tag
<domino:form id="myForm" unid="<% docUNID">
<%-- form processing --%>
<domino:nodocument>Document does not exist</domino:nocdocument>
</domino:form>
Linking documents
The formlink and parentlink are used to link documents. Both open the linked document in
the context of a documentloop, viewloop, document, or form tag. The formlink tag opens the
current document in a specified form or document tag, and the parentlink tag opens the
parent document of the current one.
Example 4-12 Linking documents
<domino:view viewname="<% viewName %>">
<domino:viewloop>
<domino:formlink href="<%= formURI %>"><domino:viewitem col="1"/></domino:formlink>
</domino:viewloop>
</domino:view>
Chapter 4. Using the Domino JSP custom tag libraries
31
Example 4-12 on page 31 displays the item in the first column as a link to a page that
contains a form. Using the parentlink tag in the context of viewloop tag requires loading a
document for each entry.
Retrieving document responses
The responses tag can be used to acquire all responses to a current document. Using the
docloop tag, the returned document collection can be evaluated.
Example 4-13 Handling document responses
<domino:ftsearch
query="<%= queryString %>"
options="<%= option %>">
<domino:docloop>
.
.
<domino:responses>
<domino:docloop>
<%-- response processing --%>
</domino:docloop>
</domino:responses>
.
.
</docloop>
</domino:ftsearch>
The document tag
The document tag is most suitable for displaying existing documents, as well as creating or
editing documents. The document tag supports the item and formula tags to expose
document data. Formula and item tags were covered in “Items” on page 29.
Example 4-14 Display a document using the document tag
<domino:document
id="myDoc"
unid="<%= docUNID %>">
<%-- document:specific code --%>
<domino:item id="myFirstItem" name="<%= itemName %>"/>
<%-- or --%>
<domino:formula
id="myFormula">@function</domino:formula>
</domino:document>
To edit or update information, use the setitem tag. This tag changes the value of a specified
item immediately, but does not become effective until the document is saved.
If you want to create or edit a new document, you must provide a schema attribute, which
specifies the name of the form in the Domino database. The attribute ensures that initial
values are set, centralized validation takes place, and the input is post-processed before
saving the document.
Example 4-15 Creating a new document using the document tag
<domino:document
id="myDoc"
schema="<%= schema %>">
<%-- document:specific code --%>
<%-- automatically setting item values --%>
<domino:setitem
32
Using the Domino JSP Custom Tags
name="<%= itemName %>"
value="<%= valueString %>"/>
<%-- saving the document --%>
<domino:savenow/>
<%-- or --%>
<% myDoc.save() %>
</domino:document>
The savenow tag is used to save the current document immediately.
If a newly created document is a response to an existing document, the responseto attribute is
used to define the unique ID of the parent document.
The form tag
As described above, the form tag provides extended functions to perform the processing of
database documents. This includes action tag support and client-side input validation, for
example. Additionally, an extended set of tags is provided to render the JSP interface. Some
of the tags are only valid in the context of a form, thus making the form tag a key to a
successful implementation of the Domino JSP custom tags.
The form tag modes
In general, three modes are supported by the form tag:
򐂰 display
򐂰 edit
򐂰 delete
The selected mode defines whether the exposed items are in read-only mode. Setting the
mode to delete ensures that the document is removed from the database. Apart from the
delete mode, the different modes may require a different JSP interface. To test which mode
the form tag the Domino JSP custom tag is in, provide the following tags:
򐂰 ifdisplaymode
򐂰 ifeditmode
Using these tags enables you to implement different representations for each mode.
Example 4-16 Determining the form tag mode
<domino:form id="myForm" clientvalidate="true" editmode="<%= mode %>">
<domino:ifdisplaymode is="true">
<%-- display mode specific code --%>
</domino:ifdisplaymode>
<domino:ifeditmode is="true">
<%-- edit mode specific code --%>
</domino:ifeditmode>
</domino:form>
To switch from display into edit mode, use the editdoc tag. This tag includes a link that invokes
the change of the form tag mode on the JSP page. In case the user has no sufficient rights or
the form is already in edit mode, the link is not enabled or visible.
Example 4-17 Switching form tag modes
<domino:form id="myForm" clientvalidate="true" editmode="<%= mode %>">
<domino:ifdisplaymode is="true">
<%-- Insert switch mode link --%>
<domino:editdoc
text="Switch to edit mode"/>
Chapter 4. Using the Domino JSP custom tag libraries
33
<%-- display mode specific code --%>
</domino:ifdisplaymode>
<domino:ifeditmode is="true">
<%-- edit mode specific code --%>
</domino:ifeditmode>
</domino:form>
Item access and Input control
The formula and item tags, which were covered “Items” on page 29, and the setitem tag can
also be used in the document.
In addition, the textarea tag (sExample 4-18) can be used to create or edit multi-value and
multi-line text items if the document supports an HTML textarea control (is in edit mode).
Example 4-18 Inserting multi-line text areas
<domino:form id="myForm" clientvalidate="true" editmode="edit">
<domino:textarea
name="<%= webControlName %>"
itemName="<%= itemName %>"/>
<%-- form actions --%>
</domino:form>
The tag that is used most frequently for entering data is the input tag (Example 4-19).
Example 4-19 Using the input tag
<domino:form id="myForm" clientvalidate="true" editmode="edit">
<domino:input name="userName" clientvalidate="onsubmit"/>
<%-- input validation --%>
<%-- form actions --%>
</domino:form>
One of the most important tags is the richtext tag, which is used for editing the value of a rich
text item.
Example 4-20 Accessing rich text fields
<domino:form id="myForm" clientvalidate="true" editmode="edit">
<domino:richtext name="<%= richTextItemName%" codepath="<%= codePath%>"/>
<%-- form actions --%>
</domino:form>>
Important: To enable rich text, turn off the XSS/CSS protection of the Portal:
1.
2.
3.
4.
Switch to the <wp_root>/shared/app/config/services directory.
Open the ConfigService.properties file.
Set security.css.protection to false.
Save and close the file.
The select and option tags are used to include a pull-down list or listboxes in the JSP control
appearance.
Example 4-21 Adding pull-down lists and listboxes
<domino:form id="myForm">
<domino:select>
<domino:option value="1" display="1st"/>
<domino:option value="2" display="2nd"/>
34
Using the Domino JSP Custom Tags
.
.
</domino:select>
<%-- form actions --%>
</domino:form>
This tag is supported by the fill tag, which is used to fill input fields of the pull-down list with
selected values automatically.
Example 4-22 Automatically filling input fields
<domino:select>
<domino:option value="1" display="1st">
<domino:fill target="myInput" value="1stValue"/>
</domino:option>
<domino:option value="2" display="2nd">
<domino:fill target="myInput" value="2ndValue"/>
</domino:option>
.
.
</domino:select>
<domino:input
name="myInput" />
A more advanced solution is to use the dbselect and dbfill tags. The dbselect tag can be used
as a select tag and to populate the pull-down list with values extracted from a specified view
or formula. This can be extended by using the dbfill tag, which enables the use of script
controls to populate input items of the page with field values of the documents that are
associated with the pull-down list.
Example 4-23 Combining dbselect, dbfill, and input tags
<domino:dbselect
name="mySelection"
datasrc="<% dbname %>"
view="<% viewname %>"
displayitem="<%= displayItemName %>"
valueitem="<%= valueItemName %>">
<domino:dbfill target="myInput" dbfield="<%= dbfield %>" />
</domino:select>
<domino:input name="myInput" />
Document navigation: form action tags
Action tags, which are supported in the context of a form tag, create navigation tags that
enable a user to invoke a predefined action on the current document. The following action
tags exist:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
saveclosedoc
savedoc
prevdoc
nextdoc
newdoc
deletedoc
The saveclosedoc and savedoc tags are used for saving the current document. savedoc
reposts the current document, and with saveclosedoc, you can define where the request will
be redirected after the document has been saved. Before the current document is saved,
validation takes place.
Chapter 4. Using the Domino JSP custom tag libraries
35
Note: The domino:preserved tag can be added to a query string when these tags do
navigation, as can the prevdoc, nextdoc, and deletedoc tags.
Example 4-24 Saving a current document
<domino:form id="myForm" clientvalidate="true" editmode="edit">
<%-- form-specific code --%>
<%-- form actions to save the current document --%>
<domino:saveclosedoc
validhref="<%= URI %>">Save and Close</domino:saveclosedoc>
<%-- or --%>
<domino:savedoc>Save</domino:savedoc>
</domino:form>
If you are retrieving a specific document from a document collection using the unid attribute of
the form, the prevdoc and nextdoc tag can be used to switch to the previous or next document
of the document collection. These tags do not guarantee that the current document is saved
before switching to the next or previous entry of the collection.
Example 4-25 Switching documents
<domino:form id="myForm">
<%-- form-specific code --%>
<%-- form actions to switch to the previous and next document --%>
<domino:prevdoc text="Previous Doc" />
<domino:nextdoc text="Next Doc" />
</domino:form>
The deletedoc tag is used to insert a navigation tag to delete the current document. The page
that is displayed after the document is deleted is specified either by the nextdoc tag or the
validhref attribute of the deletedoc tag itself or the form tag.
Example 4-26 Delete the current document
<domino:form id="myForm">
<%-- form-specific code --%>
<%-- form action to delete the current document --%>
<domino:deletedoc
text="Delete Doc" validhref="<%= URI %>" />
<%-- form actions to switch to the next document --%>
<domino:nextdoc text="Next Doc" />
</domino:form>
The newdoc tag can be used to insert a link that enables the user to create a new document.
If the new document is intended to create a response to the current document, the
asresponse attribute must be set to true.
Example 4-27 Creating a response to the current document
<domino:form
id="myForm"
unid="<%= docUNID %>">
<%-- form-specific code --%>
<%-- form action to insert a link to create a response --%>
<domino:newdoc
text="Create Response Doc"
36
Using the Domino JSP Custom Tags
asresponse="true" />
</domino:form>
In case of insufficient user rights, neither the deletedoc nor newdoc tag is enabled.
Image-based document navigation
The docnavimg tag enables you to define an image based on navigation links. To define
which action tag is used, use the type attribute.
Example 4-28 Image-based navigation: Create Response
<domino:form
id="myForm"
unid="<%= docUNID %>">
<%-- form-specific code --%>
<%-- form action tags --%>
<domino:docnavimg
type="W"
alttext="Create Response Doc Img not available"
asresponse="true"
enabled="<%= imageFileName %>"/>
</domino:form>
Input validation
The Domino JSP custom tag libraries are used for validating the input in the context of a form
tag. This validation takes place on the client side and helps decrease the server load that is
caused by invalid client requests. To ensure the validation on the client side, set the
clientvalidate attribute of the form tag to true and insert at least one of the following tags:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
validatewith
validatesummary
validaterequired
validaterange
validatepattern
validatelength
validatedate
validatecc
The clientvalidate attribute of the input tags must be set to onblur or to onsubmit.
Example 4-29 Implementing input validation
<domino:form id="myForm" clientvalidate="true">
<%-- form input and validation --%>
<domino:validatesummary caption="Please correct the following errors and resubmit:"/>
.
.
<domino:input name="userName" clientvalidate="onsubmit">
<domino:validaterequired
name="userName" message="Username entry is required!">*</domino:validaterequired>
<domino:validatepattern
name="userName" pattern="[A-Za-z]+"
message="Username must not contain numbers!"/>
<domino:validatelength
name="userName" min="<%= min%>" max="<%= max %>"
message="Invalid length of username!"/>
<domino:input name="dateOfBirth" clientvalidate="onsubmit"/>
<domino:validatedate
name="dateOfBirth"
Chapter 4. Using the Domino JSP custom tag libraries
37
message="Invalid date of birth entry!">*</domino:validatedate>
<domino:input name="ccNumber" clientvalidate="onsubmit">
<domino:validatecc
name="ccNumber" message="Invalid credit card number entry!">*</domino:validatecc>
<domino:input name="itemNumber" clientvalidate="onsubmit">
<domino:validaterequired
name="itemNumber"
message="itemNumber entry is required!">*</domino:validaterequired>
<domino:validatelength
name="itemNumber" min="<%= min %>" max="<%= max %>"
message="Invalid item number entry!">*</domino:validatelength>
<domino:input name="repeatedUserName" clientvalidate="onsubmit"/>
<domino:validatewith
name="repeatedUserName" value="userName"
message="Usernames do not match!">*</domino:validatewith>
.
.
</domino:form>
Miscellaneous
This section describes tags that enable you to get information about a document, such as
who created it, when it was accessed or modified, and who the current user is.
User information
The user tag enables you to access an object that represents the current user or server. The
use of this tag is available in both the data access environment and the input environment.
The steps that are necessary to access the object are described in 4.7, “Programmatic
access of underlying Domino Java Objects” on page 44.
Example 4-30 Accessing the lotus.domino.Name object
<domino:user
id="currentUser" />
Document information
To retrieve information about the document, the following tags are used:
򐂰
򐂰
򐂰
򐂰
authors
created
lastaccessed
lastmodified
The authors tag displays the authors of the current document. Newly created documents
have to be saved once before the tag displays the information properly.
Example 4-31 The authors tag
<domino:authors />
The created tag renders information about when the document was created. Unlike the
authors tag, the information is available immediately when creating new documents.
38
Using the Domino JSP Custom Tags
Example 4-32 The created tag
<domino:created />
These lastaccessed and lastmodified tags return the date on which the document was
accessed or modified.
Example 4-33 Retrieve document access dates
<domino:lastaccessed
id="lastAccessDate" />
<%-- and --%>
<domino:lastmodified
id="lastModifiedDate" />
4.5 Process control tags
The process control tags enable the JSP to query the state or properties of the Domino
application and, based on the result, modify the presentation of our portlet.
4.5.1 Run agents
The runagent tag can be used to invoke an agent that runs on the server, such as agents that
send mail or create a folder. You cannot specify an agent that displays information in the
browser to the user. In case data should be captured, it has to be written to a document first.
After the data has been written, the document can be used to recover the data.
Example 4-34 Run an agent
<domino:runagent name="agent name" />
4.5.2 Preserving page arguments
Techniques, such as pagination, rely on self-navigation. To preserve initial arguments passed
to the page, some of the custom tags require the use of the preserve tag.
Example 4-35 Preserving page arguments
<domino:preserve name="<%= pageParameterName %>" />
Defining the value attribute enables you to override the current value of the specified
parameter.
4.5.3 Reading and authoring
Certain tags can be used to affect the generation of content within the JSP according to the
properties of a document.
The following tags determine whether the user has authoring or reading rights, and then
render document content on the basis of this evaluation. These tags are:
򐂰 ifdocauthor
򐂰 ifdocreader
Chapter 4. Using the Domino JSP custom tag libraries
39
Both tags throw an exception if the user does not have at least reader access to the
database. The recommended way to handle this behavior is to enclose the form or document
tag with an appropriate ACL tag (at least an ifreader tag).
Example 4-36 Using ifdocauthor or ifdocreader
<domino:ifreader is="true">
<%-- Start:Reader-specific code --%>
<domino:document id="myDoc" unid="<%= docUNID %>">
<%-- Start:Document-specific code --%>
<domino:ifdocauthor is="true">
<%-- Author-access-specific-code --%>
</domino:ifdocauthor>
<domino:ifdocreader is="true">
<%-- Reader-access-specific-code --%>
</domino:ifdocreader>
<%-- End:Document-specific code --%>
</domino:document>
<%-- End:Reader-specific code --%>
</domino:ifreader>
4.5.4 Pagination
Rendering collections of documents or view entries creates the need for pagination control. In
the context of views, full-text searches, or databases that include a large number of document
entries, the number of returned documents is higher than the amount that can be rendered on
a JSP without distorting the overall Web page appearance.
With the page tag, the returned documents can be rendered in a frame that consists of
multiple pages:
򐂰 page
Navigation between the collection of pages is guaranteed by the following tags:
򐂰
򐂰
򐂰
򐂰
򐂰
pagebar
pagefirst
pagelast
pagenext
pageprev
Example 4-37 Using pagination
<%-- preserve arguments --%>
<domino:db id="myDb" dbname="<%= dbname %>">
<domino:view id="myView" dbname="<%= viewname %>">
<domino:page id="myPageInfo">
<domino:viewloop>
<%-- Loop-specific code --%>
</domino:viewloop>
<%-- page navigation --%>
<domino:pagefirst text="First Doc"/>
<domino:pageprev text="Previous Doc"/>
<domino:pagenext text="Next Doc"/>
<domino:pagelast text="Last Doc"/>
</domino:page>
</domino:view>
</domino:db>
<%-- or --%>
40
Using the Domino JSP Custom Tags
<%-- preserve arguments --%>
<domino:db id="myDb" dbname="<%= dbname %>">
<domino:view id="myView" dbname="<%= viewname %>">
<domino:page id="myPageInfo">
<domino:viewloop>
<%-- Loop-specific code --%>
</domino:viewloop>
<%-- page navigation --%>
<domino:pagebar navstyle="NextPrev"/>
</domino:page>
</domino:view>
</domino:db>
4.5.5 ACL settings
Every database uses an Access Control List (ACL) to evaluate the level of access that users
and servers have. The specified level of access determines which actions can be performed
or what kind of information can be replicated.
Within the context of the Domino JSP custom tags, you can restrict the generation of JSP
content according to the rights of the current user. The following tags are used to evaluate the
access level of the user and to control the JSP content generation accordingly:
򐂰
򐂰
򐂰
򐂰
򐂰
򐂰
ifdepositor
ifdesigner
ifeditor
ifmanager
ifnoaccess
ifreader
Example 4-38 Using the access level tags
<%-- Start:Session-specific code --%>
<domino:db id="myDb" dbname="<%= dbname %>">
<domino:ifmanager is="true">
<%-- Manager-specific code --%>
</domino:ifmanager>
<domino:ifdesigner is="true">
<%-- Designer-specific code --%>
</domino:ifdesigner>
.
.
<domino:ifdepositor is="true">
<%-- Depositor-specific code --%>
</domino:ifdepositor>
<domino:ifnoaccess is="true">
<%-- NoAccess-specific code --%>
</domino:ifnoaccess>
</domino:db>
<%-- End:Session-specific code --%>
The ifdbrole tag can be used to evaluate its attributes to determine which standard level of
access is necessary to display (or not display) the JSP content specified in its body.
Example 4-39 Using the dbrole tag
<%-- Start:Session-specific code --%>
<domino:db id="myDb" dbname="<%= dbname %>">
Chapter 4. Using the Domino JSP custom tag libraries
41
<domino:ifdbrole name="<%= rolename %>" is="true">
<%-- Role-specific code --%>
</domino:ifdbrole>
</domino:db>
<%-- End:Session-specific code --%>
4.5.6 Hierarchical or categorized views
The following tags are useful when working with views.
Preserving the formatting
To preserve the formatting of a view that contains a hierarchical structure, or is categorized,
use the indent tag.
Evaluating View entries
ViewEntry objects are evaluated in the context of a viewloop. Depending on the properties of
the ViewEntry, a different representation within the JSP could be necessary. These tags
enable you to evaluate the properties of the ViewEntry in a hierarchical or categorized view:
򐂰
򐂰
򐂰
򐂰
ifcategoryentry
iftotalentry
ifconflictentry
ifdocumententry
On the basis of this evaluation, different presentation content can be rendered. The content is
defined in the body of these tags.
Example 4-40 Evaluating ViewEntry properties
<domino:viewloop>
<%-- evaluate ViewEntry --%>
<domino:ifcategoryentry>
<%-- Category-specific code --%>
</domino:ifcategoryentry>
<domino:ifdocumententry>
<%-- Document-specific code --%>
</domino:ifdocumententry>
<domino:ifconflictentry>
<%-- Conflict-Entry-specific code --%>
</domino:ifconflictentry>
<domino:iftotalentry>
<%-- Total-specific code --%>
</domino:iftotalentry>
</domino:viewloop>
4.5.7 Mailto tag
With the mailto tag, you can send a mail message if Domino messaging is enabled on the
server. The author of the message is the currently logged-in user.
Example 4-41 Send messages
<domino:mailto
to="names"
cc="names"
bcc="names"
42
Using the Domino JSP Custom Tags
subject="<%= subject %>"
encoding="text/html">Message content</domino:mailto>
4.6 Utility tags
The utility tags are used to perform actions that are common to all J2EE-compliant Web
containers. These tags are found in domutil.tld and are separated from the other tags,
enabling the developer to choose from a variety of utility tag libraries.
The following tags are included to evaluate Boolean expressions:
򐂰 if
򐂰 elseif
򐂰 else
Both the if and elseif tags create the context for the condition tag, whose body is used to
define the Boolean value as a string. This value can also be defined as an attribute of either
the if or the elseif tag.
The body of the else tag is executed in the case that neither the condition of the if nor the
elseif tag represents a true Boolean value. If no else tag is defined and the condition fails, the
bodies of if and elseif tag are discarded.
Example 4-42 Applying the if, elseif, and else tags
<domutil:if>
<domutil:condition>booleanValue</domutil:condition>
<%-- if-specific processing--%>
</domutil:if><domutil:elseif condition="<%= booleanValue >">
<%-- elseif-specific processing --%>
</domutil:elseif><domutil:else>
<%-- else-specific processing --%>
</domutil:else>
These tags can be used to enable flow control:
򐂰
򐂰
򐂰
򐂰
switch
switchvalue
case
default
The value to be matched is either defined in the switch tag’s value attribute or within the
switchvalue tag. This value is compared to the values defined in the several case tags. If the
values are matched successfully, the body of the corresponding case tag is evaluated.
Example 4-43
<domutil:switch>
<domutil:switchvalue>Value</domutil:switchvalue>
<domutil:case value="<%= firstValue >">
<%-- processing for first case --%></domutil:case>
<domutil:case value="<%= secondValue >">
<%-- processing for second case --%></domutil:case>
<domutil:default>
Chapter 4. Using the Domino JSP custom tag libraries
43
<%-- default processing --%></domutil:default>
</domutil:switch>
Additional tags can be used to evaluate browser capabilities, to format values, to encode or
decode URL strings, and to restrict caching of the current page.
4.7 Programmatic access of underlying Domino Java Objects
These tags enable you to access the underlying Domino Java Objects. This can be useful for
customizing JSP representation or for using these objects in Java scriptlets. To access the
Java object, the id attribute is available in many tags.
Example 4-44 Accessing underlying Domino Java Objects
<%-- open domino session --%>
<domino:session
id="session"
host="<%= hostname %>"
user="<%= username %>" password="<%= password %>"
duration="<%= duration %>">
<%-- connect to domino database --%>
<domino:db id="db" dbname="<%= dbname %>">
<%-- create table header --%>
<div style="margin: 6px">
<table cellspacing="0" cellpadding="0" border="0">
<tr><td class="wpsTableHead">Views:</td></tr>
<%
// get views from database
Vector allViews = db.getViews();
// check for existent view(s)
if (allViews.size() > 0) {
// view(s) exist
String viewName = null;
// iterate through view(s)
Enumeration enum = allViews.elements();
while (enum.hasMoreElements()) {
// get name of current view
View currentView = (View)enum.nextElement();
viewName = currentView.getName();
%>
<%-- create table body displaying the name of the views --%>
<tr ><td><%= viewName %></td></tr>
<%
}
}
%>
</table>
</div>
</domino:db>
</domino:session>
44
Using the Domino JSP Custom Tags
5
Chapter 5.
Limitations and considerations
This chapter discusses the key considerations and limitations that constrain the use of the
Domino JSP custom tags.
After providing a general introduction to the portalizing Lotus Domino process, the restrictions
for the Domino JSP custom tags are covered.
The limitations discussed in this chapter include:
򐂰 Classification into the MVC paradigm
򐂰 The attachment tag
򐂰 Session Management considerations
© Copyright IBM Corp. 2004. All rights reserved.
45
5.1 Limitations and considerations
The following sections describe some of the general limitations to consider when working with
the custom Domino JSP tags, specifically as they relate to the challenge of portalizing a
Domino application.
5.1.1 General considerations
In general, the process of portalizing an application is a challenging process. Often people
determine the state of an application being portalized by checking whether a surface of the
application to portalize is available in the portal. However, if you are considering the concept
of portalizing only in terms of surfacing an application, this is not sufficient. For a fully
portalized application, all features of the application must be combined with the
enhancements of the portal framework.
In order to achieve a successful portal implementation of a Lotus Domino application, you
must decide which degree of portalization is needed. Some of the features that are available
within Lotus Domino cannot be transferred easily into the portal framework. Essential
rewriting of the application may be necessary to componentize parts of the application.
Attention: For complete information about different options and integration methods for
portalizing Domino applications, refer to Portalizing Domino Applications:Integrating with
Portal 5.02 and Lotus Workplace, SG24-6466, which is available at:
http://www.redbooks.ibm.com/redpieces/abstracts/sg246466.html
Portalizing by using the Domino JSP custom tags can be a very useful first step in portalizing
applications from within your Lotus Domino infrastructure. The experience that a user
achieves is helpful to understand not only the key issues in developing portlet applications
that access Domino data, but also to outline some restrictions. Some of these restrictions are
discussed in the following sections in this chapter. As a general best practice
recommendation, you should always consider extensive testing in terms of performance and
functionality when utilizing the Domino JSP custom tag libraries.
5.1.2 Classification into the MVC paradigm
The Model-View-Controller (MVC) architectural pattern is a common design pattern applied
in the development cycles of most enterprise applications.
It is used to overcome problems that arise as a result of coupling the application components
(data access code, business logic code, presentation code). Employing coupled components,
applications are susceptible to strong maintenance efforts. Adding or updating software
components often leads to a reimplementation in all parts of the application.
The MVC design pattern approaches these issues by separating core business logic from
presentation and control logic that applies the functionality described by the business model.
It has been generalized as a pattern for implementing the separation of application layers and
is the main design principle applied in a J2EE environment.
Using the Domino JSP custom tag libraries constrains the design of an application applying
the MVC architecture.
In the context of portlet development, the Controller part consists of the portlet Java classes.
According to the MVC architecture, these classes are responsible for defining the interaction
pattern of the portlet. This includes performing user requests by delegating control to specific
46
Using the Domino JSP Custom Tags
parts of the Model components and passing data objects that represent the result of these
requests to the View. Transactions and requests that are applied by custom actions invoked
by the Domino JSP custom tags can hardly be tracked by means of a self-defined Controller.
The Domino data that is represented by the JSPs is directly accessed by the View parts; that
is, the Controller is not responsible for invoking the according Model objects, but the actions
that are directly invoked from within the JSPs themselves.
A strong coupling between the View and the Model parts exists, making it hard to implement
a Controller component that is appropriate to fulfill the claims of the MVC design pattern. As a
result several benefits of the portal architecture cannot be employed and the portlet’s ability to
adapt to extensions is restricted.
5.1.3 The attachment tag
The attachment tag is not available in the portal environment. The tag uses either a Java
applet or an ActiveX control in the browser, and both of these expect a handshake from the
server before starting to upload another file. But because of the way WebSphere Portal
generates its responses, neither the Java applet nor the ActiveX control running in the
browser can verify the handshake; the response generated by the WebSphere Portal
comprises the entire portal page. The code executed by the browser cannot identify the
handshake message early in the response, and therefore assumes that the upload has failed.
5.1.4 Considerations for session management
With earlier releases of the Domino JSP custom tags, session management capabilities were
limited. Beginning with Domino 6.0.3/6.5.1 and continuing into release 6.04/6.5.3, the session
management capabilities for the Domino JSP custom tags improved significantly. For more
about session management and sharing, see Chapter 6, “Session sharing” on page 49.
HTTP session use
In general, the use of an HTTP session in a portal environment is not recommended. The
HTTP session is not common between nodes in a cluster. Any data that is stored in the
session is solely visible for J2EE resources in exactly the same Application Server instance.
The management and sharing of a Domino session as described in Chapter 6, “Session
sharing” on page 49 rely on the HTTP session, so the restrictions mentioned above apply.
Risk of temporary sessions
Additionally, some of the functionality described in Chapter 6, “Session sharing” on page 49
requires you to change the default implementation of the Portlet JSP directive. To prevent the
JSP compiler from creating temporary sessions if none already exists, the session attribute of
the JSP page directive is set to false in this syntax: <%@page session="false". This
implementation prevents global data from being stored in a session that might not exist past
the current request.
To ensure that JSPs that use Domino JSP custom tags can use their abilities to manage
sessions, set the session attribute to true in this syntax: <%@page session="true"%>.
Note: Working exclusively in a WebSphere Portal environment essentially guarantees that
a session already exists. Accordingly, the risk described above as it relates specifically to
WebSphere Portal is minimal.
Chapter 5. Limitations and considerations
47
48
Using the Domino JSP Custom Tags
6
Chapter 6.
Session sharing
This chapter discusses several approaches to sharing Domino sessions among components
of a single Web application and a collection of Web applications within a WebSphere Portal
environment. The chapter has two sections:
򐂰 General overview
This section gives a high-level overview of Domino sessions in general and discusses the
way Domino sessions can be incorporated by leveraging the Domino session tag, its
attributes, and the DominoSessionManager.
򐂰 Sharing sessions
This section outlines several concepts of session sharing that are provided by the custom
Domino JSP tags. This includes the following:
– Sharing a session between tags on a JSP
– Sharing a session between components of a single Web application
– Sharing a session between multiple Web applications
© Copyright IBM Corp. 2004. All rights reserved.
49
6.1 General overview
Session Management capabilities have been a key area of improvement for the Domino
custom JSP tags. The following section describes the session tag and the attributes that are
associated with it.
6.1.1 Session management
Prior to Domino release 6.0.3/6.5.1, one of the major issues that limited the use of the custom
Domino JSP tags within the WebSphere Portal environment was the limited ability to manage
sessions. However, within more recent releases of Domino, namely 6.0.3/6.5.1 and on to
release 6.04/6.5.3, the session management capabilities for the Domino JSP custom tags
improved significantly.
Domino session
In terms of Java, the Domino session class is the root of the Domino Objects containment
hierarchy. The session provides access to the other Domino objects. It is created in Java
programs and represents the Domino user’s environment of the current program. The session
is where the Domino server stores user-specific data. The custom Domino JSP tag libraries
take advantage of the Domino Objects for Java. The session tag provided by the custom
Domino JSP tag libraries can be used to gain programmatic access to the underlying Domino
Object using the id attribute. (See also 4.7, “Programmatic access of underlying Domino Java
Objects” on page 44.)
Custom Domino JSP session tag
The session tag defines the environment that the top-level tags run in. Its use is recommend
when several top-level tags are used on the same JSP. Wrapping the top-level tags using the
session tag initializes the session only once, resulting in improved performance.
The host attribute
There are two types of Domino sessions: local and remote. You can specify the type by using
the host attribute within the session tag.
A local session manages the user data on the same machine where the Domino server is
running. Using the local Domino classes requires the Java program to call the Domino
back-end code. With local use, you must manage threads. The thread that initialized the local
Domino session must also be the one that terminates the session.
Remote sessions usually manage user data on a different machine than the Domino server,
but can also be used in a local access environment. (See “Defining the Domino JSP custom
tags” on page 20. A remote session is initialized through the use of CORBA classes shipped
with Domino and requires the DIIOP task running on the Domino server. Using the CORBA
classes does not require special thread initialization or termination.
Note: As discussed in “Defining the Domino JSP custom tags” on page 20, you can also
use IIOP even if the Domino Server and the J2EE application server are running on the
same physical machine. This may be beneficial, as the threading mode in IIOP is better.
50
Using the Domino JSP Custom Tags
The duration attribute
To define the lifetime of a Domino session, the duration attribute was introduced. The use of
this attribute can help to decrease the overhead of sessions that are created. The attribute
can have the following values:
򐂰 page
򐂰 request
򐂰 session
The default value is page. With this value, each JSP that uses the custom Domino JSP tags
creates its own session connection.
Using the request value creates a single Domino session that exists until the HTTP request
completes. This enables multiple JSPs to share a Domino session through the span of one
HTTP request.
The session value keeps a remote Domino session open for the duration of the HTTP
session. This value can be used solely for remote sessions, as there is no restriction on
thread initialization or termination. In a local access environment, the value session is
automatically downgraded to request.
This would also happen if you do not supply your application with information about how
many of lengthy remote connections are allowed on the Domino server. There is no
mechanism that permits the server to create a message that indicates that you should stop
establishing long-lasting sessions. When the resources are too limited, the server starts
revoking and refusing connections.
To prevent this, include a RemoteSessions.properties file to your application and declare a
maxPersistentSessions attribute, whose value represents the number of lengthy sessions
allowed on the server per user. When the value is reached, the duration of any newly created
session is downgraded to request.
If you are using remote access and the session duration value, you should decrease the
time-out value for an idle DIIOP session on the Domino server. The custom Domino JSP tags
are capable of re-establishing a timed-out DIIOP session, and a small time-out value helps to
ensure that the Domino back end does not run out of resources, even if there are a large
number of concurrent user requests.
Important: Session durations other than page require using the domino:session tag.
Note: If a JSP solely consists of top-level tags, such as a view tag, and the default session
duration page applies, then you do not necessarily have to use the session tag to wrap
these tags. Instead of wrapping the tags with session tags, you can specify the necessary
parameters to create the session as attributes of the tag. These attributes are host, user,
and password.
If the duration is request or session, then this feature cannot be used and the tags have to be
wrapped by a session tag specifying the necessary attributes.
DominoSessionManager
Even though the session tag is used to create the Domino session from a JSP designer’s
point of view, the session tag passes the task to a Java class called DominoSessionManager.
This factory object takes the host, duration, user, and password attributes and creates the
Domino session.
Chapter 6. Session sharing
51
If the values of these attributes are not specified, or the attributes are not present, the default
values for the Web application are used. These can be specified as container-specific
environment variables in the Web Deployment Descriptor (web.xml) of the Web application.
The way to define a container parameter is described in 6.2.3, “Sharing a session between
multiple Web applications” on page 53.
If there are no predefined default values, the DominoSessionManager creates a default
Domino session (a local session for an anonymous user). The duration attribute is set to
page. If the duration attribute value is not page, the DominoSessionManager caches the
sessions. The identity of a cached session is defined by the provided host, user, password,
and duration attributes.
6.2 Sharing sessions
The following section describes the capabilities for sharing a Domino session using the
Domino custom JSP tags. Session sharing is discussed in terms of sharing between tags on
a JSP, as well as sharing between components of a Web application.
6.2.1 Sharing a session between tags on a JSP
Each custom Domino JSP tag must execute in the context of a Domino session. A JSP tag
runtime provides every tag with a reference to the enclosing tag. In addition, the runtime will
try to bind the top-level tags to the nearest Domino session containing it on the parse tree. (A
top-level tag searches the tree of its ancestors for a containing tag holding a valid Domino
session.) This creates an odd default behavior. If a top-level tag without session tag attributes
searches the parse tree and does not succeed in binding to a valid Domino session, it creates
a local session for the anonymous user.
The process described is the default implementation that is applied, if the duration attribute is
set to page.
6.2.2 Sharing a session between components of a single Web application
This section describes how to share Domino session between the components of a single
Web application (a single portlet). To illustrate the dependencies, consider that a single Web
application is composed of one or a collection of JSPs. Each JSP can invoke another through
the use of the jsp:include directive, which enables inclusion of dynamic content into a JSP.
Each JSP might derive its dynamic content from a Domino backend.
Session sharing between JSPs can take place in two ways:
򐂰 Domino sessions are created by the DominoSessionManager. Sessions lasting longer
than page are cached. The identity of a cached session is defined by the user, password,
host, and duration attributes. If the value of the duration attribute within a session tag is
not page, and the user, password, host, and duration attributes match those of a cached
session, the cached session will be reused instead of creating a new session.
򐂰 If a JSP incorporates another JSP via the jsp:include directive and the include directive is
nested in a custom Domino session tag, it is possible to share a session utilizing the
mechanism described in 6.2.1, “Sharing a session between tags on a JSP” on page 52. In
order for the included JSP to share the session, it must include the parameters that match
52
Using the Domino JSP Custom Tags
the existing one; namely, it must contain a session tag and use the same duration, host,
user, and password attributes in the top-level tags.
For example, imagine A.jsp incorporates the code shown in Example 6-1 to create a
session that lasts for the length of the HTTP session, belongs to a specific user, and could
be local or remote. A jsp:include statement is nested in the session tag.
Example 6-1 Sample code fragment of A.jsp
<domino:session
id="exteriorSession"
user="<%= username %>"
password="<%= password %>"
host="<%= hostname %>"
duration="session">
<%-- Start:Session-specific code --%>
.
<jsp:include page="B.jsp" flush="true" />
.
<%-- End:Session-specific code --%>
</domino:session>
B.jsp comprises the code shown in Example 6-2.
Example 6-2 Sample code fragment of B.jsp
<domino:session
id="innerSession"
user="<%= username %>"
password="<%= password %>"
host="<%= hostname %>"
duration="session">
<%-- Start:Session-specific code --%>
.
<%-- End:Session-specific code --%>
</domino:session>
These JSPs can now share a session through the first mechanism described on page 52.
Using the session tag and the same session attributes in the top-level tags in B.jsp, the
custom Domino JSP tags search the parse tree to find a containing tag holding a valid
session, that is, the session tag of A.jsp.
Note: To share a session, the session must have the same attribute values specified for
host, username, password, and duration values. If these values are not the same, this will
cause a new session to be created.
6.2.3 Sharing a session between multiple Web applications
The processes described in the previous section are sufficient for a single Web application,
but within a portal environment the approach is not sufficient. When deploying portlet
applications (collections of related portlets), WebSphere Portal uses several Web
applications to satisfy a single HTTP request. To share Domino sessions between the
different Web applications (different portlets), the DominoSessionManager must be shared
between the portlets. This section discusses the steps that are necessary to enable the
components of a portlet application to share the DominoSessionManager.
Sharing Domino sessions between different portlets requires the explicit use of the session
tag provided by the custom Domino JSP library. You cannot rely on implicit sessions that are
Chapter 6. Session sharing
53
established by the core top-level tags in case the session tag is missing. In order to share
Domino sessions, the session tags have to specify a duration attribute and, even more
important, a sessionmgrkey attribute. The value of the sessionmgrkey attribute specifies the
name of the HTTP session attribute that holds the DominoSessionManager.
You can also specify this value as a context-specific environment variable in the Web
Deployment Descriptor (web.xml) of the portlet application. Context-specific variables can be
used to provide general information to all components of a Web application. To define a
context parameter for the sessionmgrkey attribute, add the code to the Web Deployment
Descriptor of the portlet application as described either in Example 6-3 or Example 6-4.
Example 6-3 Context parameter for sessionmgrkey attribute
<context-param>
<param-name>lotus.domino.preset.sessionmgrkey</param-name>
<param-value>dominoportalmgr</param-value>
</context-param>
Example 6-4 Context parameter for sessionmgrkey attribute
<context-param>
<param-name>lotus.domino.default.sessionmgrkey</param-name>
<param-value>dominoportalmgr</param-value>
</context-param>
Adding the container parameter to the Web Deployment Descriptor enables the session tags
to access the sessionmgrkey attribute that is specified in the Descriptor. It is used across the
Web applications that build the portlet application. Now multiple Web applications try to use
the same DominoSessionManager, thereby making it possible to work with the same cached
session (to share these sessions).
Attention: Two key points should be noted about context parameters:
򐂰 Adding a context parameter gives the JSP tag author a centralized location to specify
this for all JSPs in a Web application.
򐂰 If the sessionmgrkey attribute is provided, the runtime tag will not create or destroy
DominoSessionManager. The Web application assumes this responsibility.
To ensure that a DominoSessionManager is present at the time a user logs on, the
recommendation is to override the login() method of each portlet that must share the
DominoSessionManager. A sample implementation is given in Example 6-5.
Example 6-5 Sample login() method
/**
* @see org.apache.jetspeed.portlet.PortletSessionListener#login(PortletRequest)
*/
public void login(PortletRequest request) throws PortletException {
super.login(request);
PortletSession ps = request.getPortletSession();
HttpSession hs = ((PortletSessionImpl)ps).getServletSession();
DominoSessionManager dsm = (DominoSessionManager)hs.getAttribute("dominoportalmgr");
if (dsm == null) {
dsm = new DominoSessionManager(false);
hs.setAttribute("dominoportalmgr", dsm);
}
}
54
Using the Domino JSP Custom Tags
The portlet looks for the DominoSessionManager as an attribute of the HTTP session, not the
PortalSession Object. The code implemented in the login() method retrieves the HTTP
session and checks for an existing DominoSessionManager. If no DominoSessionManager
exists, a new one is created and placed as an attribute in the HTTP session. This enables
other portlets to find it in the HTTP session. Therefore it is possible to share a single Domino
session associated with the particular portal user. You cannot define which portlet of the
portlet application is called first and responsible for creating the DominoSessionManager.
In order to clean up, the portlet has to terminate the DominoSessionManager. This can be
performed in the logout() method of the portlet. Example 6-6 shows a sample
implementation.
Example 6-6 Using the logout() method
/**
* @see org.apache.jetspeed.portlet.PortletSessionListener#logout(PortletSession)
*/
public void logout(PortletSession ps) throws PortletException {
HttpSession hs = ((PortletSessionImpl)ps).getServletSession();
DominoSessionManager dsm = (DominoSessionManager)hs.getAttribute("dominoportalmgr");
if (dsm != null) {
hs.removeAttribute("dominoportalmgr");
dsm.term();
}
super.logout(ps);
}
Chapter 6. Session sharing
55
56
Using the Domino JSP Custom Tags
7
Chapter 7.
Object pooling
This chapter introduces the latest enhancement of the Domino JSP custom tags, namely
object pooling and the ability for sharing instantiated objects.
It covers the basics of object pooling and describes how to incorporate custom object pool
implementations in the portlet application. In addition to the performance enhancements that
result out of object pooling, we also discuss the advantages from a design point of view..
The chapter is divided into the following sections:
򐂰 General overview
򐂰 Object pooling and Domino JSP custom tags
򐂰 Object pooling and MVC architecture
© Copyright IBM Corp. 2004. All rights reserved.
57
7.1 General overview
Most pages on a portal consist of portlet collections that access Lotus Domino data, i.e. there
might be multiple portlets accessing the same content. An object pool helps to avoid creating
new Java objects repeatedly (create once, use, reuse). Such an object pool is designed to
pool and reuse instances of objects that are:
򐂰 complex and,
򐂰 frequently instantiated during run time.
An object pool can help to reduce the needed memory of an application (also when cleaning
up). Without efficient use of objects in terms of both instantiation and cleaning up obsolete
objects, this can increase the load on specific parts of the Lotus Domino back end and
eventually lead to problems caused by resource limitations.
Object pooling describes an advanced approach to overcome resource limitations. It allows
sharing of instantiated objects so that processes do not have to reinstantiate the same
objects over and over again. Additionally, objects do not have to be destroyed and recycled by
the processes since these responsibilities are delegated to the object pool. Applying pooling
for objects that require non-trivial amounts of time and memory to create and destroy
increases the performance significantly.
7.2 Object pooling and Domino JSP custom tags
One of the most striking enhancements of the Domino JSP custom tags is their ability to use
custom object pool implementations. The following Domino JSP custom tags support back
end objects held in object pool implementations:
򐂰
򐂰
򐂰
򐂰
session
db
view
document
The dojkey attribute
Each of these tags introduced an new attribute called dojkey. The value of the dojkey attribute
represents the name of an attribute either held in the HTTP Request or the HTTP Session
which holds the according Domino Object for Java.
At first the tags check for an existing object in the HTTP Request. If there is none, then the
tags search the HTTP Session. In case neither HTTP Request nor HTTP Session provide an
object, the specific tag creates the according object and adds the object to an HTTP Request
attribute. The name of this attribute is set to the value of the dojkey attribute.
Object validation and error handling
The object held by the either the HTTP Request or HTTP Session attribute is assumed to be
of the correct type. Furthermore it is assumed to be valid. An invalid object causes an error.
The way the error is handled is defined by the onfailure attribute. The use of this attribute is
described in “Defining the core tag environment” on page 27. In case the onfailure attribute is
not specified the tags delegate the error to the default error page.
In general the Domino JSP custom tags try to reestablish their session in the case of an error.
If the error was generated by a non-valid session, the session for the tag using the particular
dojkey attribute cannot be recreated even though other tag attributes are specified, i.e. host,
password, user, or duration.
58
Using the Domino JSP Custom Tags
Using the dojkey attribute requires the object pool implementation to manage the lifecycle of
the objects. The Domino JSP custom tags will not destroy or terminate the Domino Objects
for Java.
7.3 Object pooling and MVC architecture
The current implementation of the Domino JSP custom tags cannot be classified into the
MVC paradigm. For more information, consult Chapter 5, “Limitations and considerations” on
page 45.
Using object pooling is an significant enhancement in order to implement the architecture of
the MVC pattern. The JSP is not required to acquire the data from the Domino back end itself,
but assumes that the objects are provided in the HTTP Request or HTTP Session attributes.
This requires the developer to implement Java routines within the portlet code that places the
required objects into the attributes, i.e. by extending the application to use object pooling
enforces the implementation of a controller part.
Chapter 7. Object pooling
59
60
Using the Domino JSP Custom Tags
Abbreviations and acronyms
ACL
Access Control List
API
Application Programmer Interface
CORBA
Common Object Request Broker
Architecture
CSS
Cascading Style Sheet
DIIOP
Domino Internet Inter-ORB
Protocol
EJB
Enterprise JavaBeans
HTML
Hypertext Markup Language
HTTP
Hypertext Transfer Protocol
IBM
International Business Machines
Corporation
ITSO
International Technical Support
Organization
J2EE
Java 2 platform, Enterprise Edition
JAR
Java archive file
JSP
JavaServer Page
MVC
Model-View-Controller pattern
TLD
Tag Library Descriptor
XML
Extensible Markup Language
XSLT
Extensible Stylesheet Language
Transformations
XSS
Cross Site Scripting
© Copyright IBM Corp. 2004. All rights reserved.
61
62
Using the Domino JSP Custom Tags
Related publications
The publications listed in this section are considered particularly suitable for a more detailed
discussion of the topics covered in this Redpaper.
IBM Redbooks
For information on ordering these publications, see “How to get IBM Redbooks” on page 64.
Note that some of the documents referenced here may be available in softcopy only.
򐂰 Connecting Domino to the Enterprise Using Java, SG24-5425
򐂰 Design and Implement Servlets, JSPs, and EJBs for IBM WebSphere Application Server,
SG24-5754
򐂰 Domino and WebSphere Together, Second Edition, SG24-5955
򐂰 IBM WebSphere Portal for Multiplatforms V5 Handbook, SG24-6098
򐂰 IBM WebSphere Portal V5 A Guide for Portlet Application Development, SG24-6076
򐂰 Portalizing Domino Applications for WebSphere Portal, SG24-7004
򐂰 Portalizing Domino Applications:Integrating with Portal 5.02 and Lotus Workplace 2.01,
SG24-6466
򐂰 WebSphere Version 5 Application Development Handbook, SG24-6993
Other publications
These publications are also relevant as further information sources:
򐂰 Portlet Development Best Practices and Coding Guidelines
http://www-106.ibm.com/developerworks/websphere/zones/portal/portlet/portletcodingguidel
ines.html
򐂰 Portlet Development Guide: Second Edition
http://www-106.ibm.com/developerworks/websphere/zones/portal/portlet/portletdevelopmentg
uide.html
򐂰 Best Practices: Developing portlets using JSR 168 and WebSphere Portal V5.02
http://www-106.ibm.com/developerworks/websphere/library/techarticles/0403_hepper/0403_he
pper.html
© Copyright IBM Corp. 2004. All rights reserved.
63
Online resources
These Web sites and URLs are also relevant as further information sources:
򐂰 IBM Lotus Domino Developer Domain
http://www-136.ibm.com/developerworks/lotus/
򐂰 IBM WebSphere Portal zone
http://www-106.ibm.com/developerworks/websphere/zones/portal/
򐂰 Information Center for IBM WebSphere Portal for Multiplatforms Version 5.0.2
http://publib.boulder.ibm.com/pvc/wp/502/ent/en/InfoCenter/index.html
򐂰 Lotus Documentation
http://www-10.lotus.com/ldd/notesua.nsf/find/workplace
򐂰 Sun Microsystems - The Java Web Services Tutorial 1.0
http://java.sun.com/webservices/docs/1.0/tutorial/doc/JSPIntro.html
http://java.sun.com/webservices/docs/1.0/tutorial/doc/JSPTags.html
http://java.sun.com/webservices/docs/1.0/tutorial/doc/Servlets.html
How to get IBM Redbooks
You can search for, view, or download Redbooks, Redpapers, Hints and Tips, draft
publications, and Additional materials, as well as order hardcopy Redbooks or CD-ROMs, at
this Web site:
ibm.com/redbooks
Help from IBM
IBM Support and downloads
ibm.com/support
IBM Global Services
ibm.com/services
64
Using the Domino JSP Custom Tags
Index
A
Access Control List 41
action handling 30
agents 39
C
categorized views 42
client-side validation 37
concrete portlet 17
containment model 26
containment relationships 26
context-specific variables 54
CORBA 50
core tag environment 27
core tags 26
D
data access tags 26, 28
Data Input tags 31
data input tags 26
default JSP attribute values 27
DIIOP 21, 50
document information 38
document navigation 35
document responses 32
dojkey attribute 58
Domino Application Portlet 4
Domino Internet Inter-ORB Protocol 21
Domino JSP custom tag libraries 1, 5, 20
limitations 46
Domino JSP custom tags
action 30
adding support 21
authors 38
case 43
created 39
db 27
dbfill 35
dbselect 35
default 27, 43
deletedoc 36
docloop 28
docnavimg 37
document 31–32
editdoc 33
else 43
elseif 43
fill 35
form 31, 33
formlink 31
formula 29
ftsearch 28
if 43
© Copyright IBM Corp. 2004. All rights reserved.
ifcategoryentry 42
ifconflictentry 42
ifdbrole 41
ifdepositor 41
ifdesigner 41
ifdisplaymode 33
ifdocauthor 39
ifdocreader 39
ifdocumententry 42
ifeditmode 33
ifeditor 41
ifmanager 41
ifnoaccess 41
ifreader 41
ifserverevent 30
iftotalentry 42
indent 42
input 34
item 29
lastaccessed 39
lastmodified 39
mailto 42
newdoc 36
nextdoc 36
nodocument 31
novalues 29
option 34
page 40
pagebar 40
pagefirst 40
pagelast 40
pagenext 40
pageprev 40
parentlink 31
preserve 39
preset 27
prevdoc 36
profiledocument 28
responses 32
richtext 34
runagent 39
saveclosedoc 35
savedoc 35
savenow 33
select 34
selectedloop 30
selectentry 30
session 27
setitem 32
switch 43
switchvalue 43
textarea 34
unid 31
user 38
validatecc 37
65
validatedate 37
validatelength 37
validatepattern 37
validaterange 37
validaterequired 37
validatesummary 37
validatewith 37
view 28
viewitem 30
viewloop 28
Domino Session 50
Domino view 28
domtags.jar 21
domtags.tld 20
domutil.tld 20
dynamic Web content 14
EJB container 13
Enterprise JavaBeans 14
Java API for Lotus Collaborative Components and Lotus
Domino 1, 5
Java archive files 21
Java objects
programmatic access 44
JavaBeans 14
JavaServer Pages
comments 15
components 15
declarations 15
directives 15
effectiveness 14
engine 14
expressions 15
introduction 14
parser 14
scriptlets 15
technology 14
JSP custom tag library 20
JSP custom tags 20
JSP tag libraries 20
F
L
E
form action tags 35
form tag modes 33
full-text search 28
G
general-purpose portlets 1, 4
global information 27
H
hierarchical views 42
HttpServlet 16–17
I
image based document navigation 37
input validation 37
integration
considerations 3
Lotus Domino into WebSphere 2
item access and Input control 34
item tag 29
J
J2EE
architecture 12
connectivity 12
containers 12
interoperability and compatibility 12
platform 12
runtime components 13
technologies 11
tier separation 12
J2EE Application Server 12
J2EE Compatibilty Test Suite 12
J2EE specifications 12
66
Using the Domino JSP Custom Tags
limitations 46
attachment tag 47
Model-View-Controller (MVC) 46
session management 47
linking documents 31
lists of documents 28
local session 50
Lotus Domino Object architecture 26
Lotus Domino platform 2
M
mail message 42
N
NCSO.jar 21
Notes.jar 21
O
object pooling
error handling 58
MVC architecture 59
supported objects 58
validation 58
object sharing 58
P
pagination 40
parse tree 52
portal community 2
portal technology 2
portlet
concrete portlets 17
defined 16
login() method 54
logout() method 55
settings 17
technology 16
Portlet Deployment Descriptor 17
PortletData 17
PortletSession 17
PortletSettings 17
preserving page arguments 39
process control tags 26, 39
profile document 28
R
Redbooks Web site 64
Contact us viii
remote session 50
request-response paradigm 16
resource limitations 58
reverse proxy 4
V
View entries 42
W
Web container 13
Web Deployment Descriptor 22, 54
WebSphere
platform 2
portal framework 2–3
WebSphere Portal
concepts 17
X
XSS/CSS protection 34
S
selecting view entries 30
servlet
standard methods 16
technology 16
session lifetime 51
Session Management 50
session tag 50
duration attribute 51
host attribute 50
sessionmgrkey attribute 54
sharing sessions 52
between components of a single Web application 52
between multiple Web applications 53
between tags on a JSP 52
single database documents 31
T
Tag Library Descriptor 20
tags
data access 26
data input 26
process control 26
utility 26
Tier
Client 13
Enterprise Information 13
Middle 13
U
unique document id 31
utility tags 26
case 43
default 43
else 43
elseif 43
if 43
switch 43
switchvalue 43
Index
67
68
Using the Domino JSP Custom Tags
Back cover
®
Using the Domino JSP
Custom Tags
An Approach to Portalizing Domino
Applications
Description of the
Domino JSP custom
tag libraries
This IBM Redpaper discusses the Domino JSP custom tag
libraries and gives a broad understanding of how to build and
integrate portlet applications using the Domino JSP custom tags.
Portlet concepts and
integration options
It provides an overview of the key technologies, including J2EE,
WebSphere Portal, and Lotus Domino. It provides an in-depth
look at using the Domino JSP custom tags as an alternative to
using either general-purpose portlets or the Java API for Lotus
Collaborative Components for integrating Lotus Domino
applications into the WebSphere Portal framework.
Session management
and object pooling
The Redpaper covers the following topics:
򐂰 It provides an outline of options for integrating Lotus Domino
applications into WebSphere Portal.
򐂰 It discusses the basics of the underlying J2EE technologies.
򐂰 It provides a brief introduction to the portlet concepts.
򐂰 It provides a description of the Domino JSP custom tag
libraries.
This description includes a general overview of the Domino JSP
custom tag libraries and gives a brief introduction to the various
tag groups and their functionality. It also addresses some of the
limitations that restrict the Domino JSP custom tags. Finally, it
addresses advanced development concepts such as session
management or sharing and object pooling in the context of the
Domino JSP tags.
Redpaper
INTERNATIONAL
TECHNICAL
SUPPORT
ORGANIZATION
BUILDING TECHNICAL
INFORMATION BASED ON
PRACTICAL EXPERIENCE
IBM Redbooks are developed
by the IBM International
Technical Support
Organization. Experts from
IBM, Customers and Partners
from around the world create
timely technical information
based on realistic scenarios.
Specific recommendations
are provided to help you
implement IT solutions more
effectively in your
environment.
For more information:
ibm.com/redbooks