IBM Press Rapid Portlet Developme With WebSphere Portlet Factory Step By Step Guide For Building Your Own Portlets Sep 2008 ISBN 0137134460 pdf
IBM PRESS NEWSLETTER
Sign up for the monthly IBM PRESS NEWSLETTER at
ibmpressbooks.com/newsletters
LEARN
• NEW PODCASTS
from your favorite authors
• ARTICLES & INTERVIEWS
with authors
• SPECIAL OFFERS
from IBM Press and partners
• NOTICES & REMINDERS
about author appearances and conferences
WIN
Sign up for the IBM PRESS NEWSLETTER and
you will be automatically entered into a
QUARTERLY GIVE-AWAY
for 3 months access to Safari Books Online –
online access to more than 5000 books
A $150 VALUE!
Sign up at ibmpressbooks.com/newsletter
REGISTER YOUR BOOK
ibmpressbooks.com/ibmregister
REGISTRATION ENTITLES YOU TO:
• Supplemental materials that may be available
• Advance notice of forthcoming editions
• A coupon that can be used on your next purchase from ibmpressbooks.com
Visit ibmpressbooks.com
for all product information
Related Books of Interest
Service-Oriented
Architecture (SOA) Compass
WebSphere Business
Integration Primer
Business Value, Planning,
and Enterprise Roadmap
Process Server, BPEL, SCA, and SOA
by Norbert Bieberstein, Sanjay Bose,
Marc Fiammante, Keith Jones, and Rawn Shah
ISBN: 0-13-187002-5
®
In this book, IBM Enterprise Integration Team
experts present a start-to-finish guide to planning, implementing, and managing ServiceOriented Architecture. Drawing on their extensive
experience helping enterprise customers migrate
to SOA, the authors share hard-earned lessons
and best practices for architects, project managers, and software development leaders alike.
Well-written and practical, Service-Oriented
Architecture Compass offers the perfect blend of
principles and “how-to” guidance for transitioning
your infrastructure to SOA. The authors clearly
explain what SOA is, the opportunities it offers,
and how it differs from earlier approaches. Using
detailed examples from IBM consulting engagements, they show how to deploy SOA solutions
that tightly integrate with your processes and
operations, delivering maximum flexibility and
value. With detailed coverage of topics ranging
from policy-based management to workflow
implementation, no other SOA book offers
comparable value to workingIT professionals.
by Ashok Iyengar, Vinod Jessani,
and Michele Chilanti
ISBN: 0-13-224831-X
Using WebSphere® Business Integration (WBI)
technology, you can build an enterprise-wide
Business Integration (BI) infrastructure that makes
it easier to connect any business resources and
functions, so you can adapt more quickly to the
demands of customers and partners. Now there’s
an introductory guide to creating standards-based
process and data integration solutions with WBI.
WebSphere Business Integration Primer
thoroughly explains Service Component
Architecture (SCA), basic business processes,
and complex long-running business flows, and
guides you to choose the right process integration
architecture for your requirements. Next, it introduces the key components of a WBI solution and
shows how to make them work together rapidly
and efficiently. This book will help developers,
technical professionals, or managers understand
today’s key BI issues and technologies, and
streamline business processes by combining
BI with Service Oriented Architecture (SOA).
Sign up for the monthly IBM Press newsletter at
ibmpressbooks/newsletters
Related Books of Interest
The New Language
of Business
SOA & Web 2.0
by Sandy Carter
ISBN: 0-13-195654-X
Executing SOA
A Practical Guide for the ServiceOriented Architect
by Norbert Bieberstein, Robert G. Laird,
Dr. Keith Jones, and Tilak Mitra
ISBN: 0-13-235374-1
In The New Language of Business, senior IBM
executive Sandy Carter demonstrates how to
leverage SOA, Web 2.0, and related technologies
to drive new levels of operational excellence and
business innovation.
In Executing SOA, four experienced SOA
implementers share realistic, proven, “from-thetrenches” guidance for successfully delivering on
even the largest and most complex SOA initiative.
You’ll learn how to organize your business into
reusable process components — and support
them with cost-effective IT services that adapt
quickly and easily to change. Then, using
extensive examples — including a detailed case
study describing IBM’s own experience — Carter
identifies best practices, pitfalls, and practical
starting points for success.
This book follows up where the authors’ bestselling Service-Oriented Architecture Compass
left off, showing how to overcome key obstacles
to successful SOA implementation and identifying
best practices for all facets of execution—
technical, organizational, and human. Among
the issues it addresses: introducing a services
discipline that supports collaboration and
information process sharing; integrating services
with preexisting technology assets and strategies;
choosing the right roles for new tools; shifting
culture, governance, and architecture; and
bringing greater agility to the entire organizational
lifecycle, not just isolated projects.
Listen to the author’s podcast at:
ibmpressbooks.com/podcasts
Listen to the author’s podcast at:
ibmpressbooks.com/podcasts
Writing for executives and business leaders inside
and outside IT, Carter explains why flexibility and
responsiveness are now even more crucial to
success — and why services-based strategies
offer the greatest promise for achieving them.
Visit ibmpressbooks.com
for all product information
Related Books of Interest
IBM WebSphere
and Lotus
Lamb, Laskey, Indurkhya
ISBN: 0-13-144330-5
Enterprise Messaging
Using JMS and IBM
WebSphere
Enterprise Java
Programming with
IBM WebSphere
Second Edition
Yusuf
ISBN: 0-13-146863-4
IBM WebSphere System
Administration
by Kyle Brown, Dr. Gary Craig, Greg Hester,
David Pitt, Russell Stinehour, Mark Weitzel,
Jim Amsden, Peter M. Jakab, and Daniel Berg
Williamson, Chan, Cundiff,
Lauzon, Mitchell
ISBN: 0-321-18579-X
Outside-in Software
Development
Enterprise Java™ Programming with IBM
WebSphere, Second Edition is the definitive guide
to building mission-critical enterprise systems
with J2EE™, WebSphere, and WebSphere
Studio Application Developer. Fully updated for
Versions 5.x of WebSphere Application Server
and WebSphere Studio Application Developer,
it combines expert architectural best practices
with a case study that walks you through
constructing an entire system.
The authors are an extraordinary team of
WebSphere insiders: developers, consultants,
instructors, and IBM WebSphere development
team members. Together, they offer unprecedented insight into the use and behavior of
WebSphere’s APIs in real-world environments
— and systematic guidance for delivering
systems of exceptional performance,
robustness, and business value.
Sign up for the monthly IBM Press newsletter at
ibmpressbooks/newsletters
ISBN: 0-13-144604-5
Kessler, Sweitzer
ISBN: 0-13-157551-1
Enterprise Master
Data Management
Dreibelbis, Hechler, Milman,
Oberhofer, van Run, Wolfson
ISBN: 0-13-236625-8
Rapid Portlet
Development
with WebSphere
Portlet Factory
®
Requirements
Requirements
This page intentionally left blank
IBM WebSphere
Rapid Portlet
Development with
®
Deployment
and Advanced
WebSphere
Configuration
Portlet Factory
[SUBTITLE ]
Step-by-Step Guide for Building
Roland Barcia,
Bill Hines,
TomPortlets
Alcott, and Keys Botzum
Your
Own
David Bowley
IBM Press
Pearson plc
Upper Saddle River, NJ • Boston • Indianapolis • San Francisco
New York • Toronto • Montreal • London • Munich • Paris • Madrid
Cape Town • Sydney • Tokyo • Singapore • Mexico City
Ibmpressbooks.com
The author and publisher have taken care in the preparation of this book, but make no expressed or implied
warranty of any kind and assume no responsibility for errors or omissions. No liability is assumed for
incidental or consequential damages in connection with or arising out of the use of the information or
programs contained herein.
© Copyright 2009 by International Business Machines Corporation. All rights reserved.
Note to U.S. Government Users: Documentation related to restricted right. Use, duplication, or disclosure
is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corporation.
IBM Press Program Managers: Tara Woodman, Ellice Uffer
Cover Design: IBM Corporation
Associate Publisher: Greg Wiegand
Marketing Manager: Kourtnaye Sturgeon
Publicist: Heather Fox
Acquisitions Editor: Katherine Bull
Development Editor: Kevin Howard
Managing Editor: Kristy Hart
Designer: Alan Clements
Senior Project Editor: Lori Lyons
Copy Editor: Deadline Driven Publishing
Indexer: WordWise Publishing Services
Compositor: Nonie Ratcliff
Proofreader: Water Crest Publishing
Manufacturing Buyer: Dan Uhrig
Published by Pearson plc
Publishing as IBM Press
IBM Press offers excellent discounts on this book when ordered in quantity for bulk purchases or special
sales, which may include electronic versions and/or custom covers and content particular to your business,
training goals, marketing focus, and branding interests. For more information, please contact:
U. S. Corporate and Government Sales
1-800-382-3419
[email protected]
For sales outside the U.S., please contact:
International Sales
[email protected]
The following terms are trademarks or registered trademarks of International Business Machines
Corporation in the United States, other countries, or both: IBM, the IBM logo, IBM Press, DB2, Domino,
Domino Designer, Lotus, Lotus Notes, Rational, and WebSphere. Java and all Java-based trademarks are
trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Microsoft, Windows,
Windows NT, and the Windows logo are trademarks of the Microsoft Corporation in the United States,
other countries, or both. Linux is a registered trademark of Linus Torvalds. Intel, Intel Inside (logo), MMX,
and Pentium are trademarks of Intel Corporation in the United States, other countries, or both. Other
company, product, or service names may be trademarks or service marks of others.
Library of Congress Cataloging-in-Publication Data
Bowley, David.
Rapid portlet development with WebSphere portlet factory : step-by-step guide for building your own
portlets / David Bowley.
p. cm.
Includes index.
ISBN 0-13-713446-0 (hardback : alk. paper) 1. Web portals—Computer programs. 2. User interfaces
(Computer systems) Computer programs. 3. Web site development. 4. WebSphere. I. Title.
TK5105.8885.W43B69 2008
006.7’6—dc22
2008029014
All rights reserved. This publication is protected by copyright, and permission must be obtained from the
publisher prior to any prohibited reproduction, storage in a retrieval system, or transmission in any form or
by any means, electronic, mechanical, photocopying, recording, or likewise. For information regarding
permissions, write to:
Pearson Education, Inc
Rights and Contracts Department
501 Boylston Street, Suite 900
Boston, MA 02116
Fax (617) 671 3447
ISBN-13: 978-0-13-713446-5
ISBN-10: 0-13-713446-0
Text printed in the United States on recycled paper at R.R. Donnelley in Crawfordsville, Indiana.
First printing September 2008
This page intentionally left blank
Contents at a Glance
Foreword
xxvii
Preface
xxix
Acknowledgments
xxxiii
About the Author
xxxv
Chapter 1
Introduction to WebSphere Portlet Factory
Chapter 2
Providing and Consuming Services
37
Chapter 3
Using Data from a Relational Data Source
53
Chapter 4
Using Domino Data
77
Chapter 5
Customizing Portlet Appearance
107
Chapter 6
Adding Basic User Interface Controls to Your Portlets
149
Chapter 7
Communicating Between Portlets
165
Chapter 8
Using Java in Portlets
195
Chapter 9
Using Web Services and Manipulating XML
239
Chapter 10
Using Charts in Portlets
267
Chapter 11
Field Validation, Formatting, and Translation
293
Chapter 12
Profiling Portlets
323
Chapter 13
Using Ajax and Dojo
345
Chapter 14
Error Handling, Logging, and Debugging Portlets
371
Chapter 15
Performance and Process Optimization
393
Chapter 16
More Techniques for Domino
413
Appendix A
Setting Up your Environment
439
Appendix B
Portlet Factory Properties
461
Glossary
475
Index
493
xi
1
This page intentionally left blank
Contents
Foreword
xxvii
Preface
Chapter 1
xxix
Acknowledgments
xxxiii
About the Author
xxxv
Introduction to WebSphere Portlet Factory
What Is a Portal and What Are Portlets?
Portal Key Benefits
What Is WPF?
WPF Key Benefits
WPF Architecture
Builders
Models
Profiles
Generating and Executing the WebApp
Portlet Factory WAR Files
Deployment Configurations
Introduction to the WebSphere Portlet Factory Designer
The User Interface
Folder Structure
Building Your First Portlet
Creating a Project
Manual Deployment
Creating a Model
Testing the Application
Summary
Important Points
xiii
1
2
3
4
4
5
5
6
7
7
11
12
13
13
17
21
21
26
30
31
35
35
xiv
Contents
Chapter 2
Providing and Consuming Services
The Service Provider/Consumer Pattern
Creating a Service Provider
Creating a Model
Defining the Service
Adding Roster Data
Adding an Action to Retrieve a Roster
Adding a Service Operation
Testing the Service Provider
Creating a Service Consumer
Creating a Model
Configuring the Portlet Adapter
Testing the Service Consumer
Creating a Stub Service
Applying the Service Provider/Consumer Pattern
Summary
Important Points
Chapter 3
Using Data from a Relational Data Source
Using Data Services
Creating a Service Provider
Creating a Model
Defining the Service
Specifying the First Operation
Specifying the Second Operation
Specifying the Third Operation
Specifying the Fourth Operation
Specifying the Fifth Operation
Testing the Service Provider
Testing the retrieveContactsView Operation
Testing the getContactDetail Operation
Testing the createContact Operation
Testing the setContact Operation
Testing the deleteContact Operation
Creating a Contacts Portlet
Creating a Model
Configuring the Portlet Adapter
Adding Update Functionality
Adding Delete Functionality
Adding Create Functionality
Testing the Contacts Portlet
Summary
Important Points
37
37
39
40
41
42
43
43
44
45
46
47
47
48
49
51
51
53
53
54
54
55
55
55
56
57
58
60
61
62
63
63
63
63
64
65
65
66
69
72
74
75
Contents
Chapter 4
xv
Using Domino Data
Portalizing Notes Functionality
Configuring Your Environment
Configuring the Domino Properties File
Testing the Connection to Domino
Creating a Service Provider
Creating a Model
Defining the Service
Specifying Operations
Adding a Delete Operation
Testing the Service Provider
Testing the readSupplierView Operation
Testing the readSupplierDocument Operation
Testing the updateSupplierDocument Operation
Testing the createSupplierDocument Operation
Testing the deleteSupplierDocument Operation
Creating a Suppliers Portlet
Creating a Model
Configuring the Portlet Adapter
Adding Update Functionality
Adding Delete Functionality
Adding Create Functionality
Removing Unwanted Fields
Testing the Service Consumer
Using a Stub Service
Creating a Stub Model
Using the Stub Model
Summary
Important Points
Chapter 5
Customizing Portlet Appearance
Customizing Portlet Appearance
Creating a Service Provider
Creating a Model
Defining the Service
Adding an Asset Schema
Adding Asset Data
Adding an Action to Retrieve a List of Assets
Specifying the getAssetsList Operation
Testing the Service Provider
Creating an Assets Portlet
Creating a Model
Adding a Portlet Adapter
77
78
79
80
81
82
82
83
83
85
88
88
89
90
90
90
91
91
93
94
94
97
99
100
102
103
104
105
105
107
108
108
109
109
109
110
112
112
113
114
114
114
xvi
Contents
Consuming the Service
Displaying Assets Data
Testing the Assets Portlet
Pagination
Turning on Pagination
Modifying the Paging Buttons
Data Modifiers
The Data Column Modifier Builder
The Data Hierarchy Modifier Builder
The Data Field Modifier Builder
The Form Layout Builder
Working with Web Pages
HTML Builders
JSP Builders
JavaScript
HTML Templates
Cascading Style Sheets
Adding a Style Sheet
Summary
Important Points
Chapter 6
Adding Basic User Interface Controls
to Your Portlets
User Interface Controls in WPF
Creating a Survey Portlet
Creating a Model
Modifying the Page
Adding a Portlet Adapter
Testing the Survey Portlet
Summary
Important Points
Chapter 7
Communicating Between Portlets
The Benefits of Inter-Portlet Communication
The WebSphere Property Broker
Creating a Service Provider
Creating a Model
Defining the Service
Adding Loan Data
Adding an Action to Retrieve a List of Loans
Specifying the getLoansList Operation
Adding a Method to Retrieve a Specific Loan
Specifying the getLoanDetail Operation
114
114
117
119
120
120
122
122
124
124
127
132
133
135
135
137
142
144
146
146
149
149
151
151
152
153
160
163
164
165
166
166
167
168
168
168
169
170
170
171
Contents
xvii
Testing the Service Provider
Creating a List Portlet
Creating a Model
Specifying the Service
Specifying List and Detail Operations
Configuring the Portlet Adapter
Defining the Portlet as a Cooperative Source
Testing the List Portlet
Creating a Detail Portlet
Creating a Model
Adding a Default Message Page
Adding a main Action
Adding an Interface for Loan Details
Defining the Portlet as a Cooperative Target
Handling an Inter-Portlet Communication Event
Testing the Detail Portlet
Configuring the WebSphere Property Broker
Testing Inter-Portlet Communication
Alternative Communication Methods
Property Broker Action
WPF Event Model
Shared Variables
Configuring Actions for loansList
Running selectLoan
Using the Shared Variable in the loanDetail Model
Click-to-Action (C2A)
When to Use Inter-Portlet Communication
Summary
Important Points
Chapter 8
Using Java in Portlets
Java Development Considerations
Java Methods
Inline Java
Action Lists
The Method Builder
The Linked Java Object Builder
Java Application Programming Interfaces
com.bowstreet.WebApp.WebAppAccess
com.bowstreet.webapp.Variables
com.bowstreet.webapp.RequestInputs
com.bowstreet.util.IXml and com.bowstreet.util.XmlUtil
javax.servlet.http.HttpServletRequest and javax.servlet.http.HttpServletResponse
171
173
173
173
174
175
176
177
177
178
179
179
179
180
181
182
183
184
184
185
186
189
191
192
192
192
192
193
193
195
196
198
198
200
200
201
202
203
206
207
208
209
xviii
Contents
Java Beans
Creating a Java Bean and Bean Manager
Creating a Shopping Cart Item Bean
Creating a Shopping Cart Item Manager
Creating a Service Provider
Creating a Model
Defining the Service
Adding a Linked Java Object
Adding a Java to XML Converter
Clearing a Shopping Cart
Viewing a Shopping Cart
Viewing a Shopping Cart Item
Adding a Shopping Cart Item
Updating a Shopping Cart Item
Deleting a Shopping Cart Item
Testing the Service Provider
Testing the addShoppingCartItem Operation
Testing the viewShoppingCart Operation
Testing the viewShoppingCartItem Operation
Testing the updateShoppingCartItem Operation
Testing the deleteShoppingCartItem Operation
Testing the clearShoppingCart Operation
Creating a Shopping Cart Portlet
Creating a Model
Configuring the Portlet Adapter
Implementing the updateShoppingCartItem Operation
Implementing the addShoppingCartItem Operation
Implementing the clearShoppingCart Operation
Implementing the deleteShoppingCartItem Operation
Testing the Shopping Cart Portlet
Testing the Add Item Button
Testing the Edit Item Button
Testing the Delete Item Button
Testing the Clear Cart Button
Java Archives
Importing JARs
Excluding JARs from WAR Files
Summary
Important Points
210
210
211
213
216
217
217
217
217
218
219
221
222
223
223
224
225
225
225
226
226
226
226
226
228
228
229
229
230
232
232
233
233
233
234
234
235
236
236
Contents
Chapter 9
xix
Using Web Services and Manipulating XML
Web Services in WPF
Creating an Order Stock Web Service
Creating a Model
Defining the Service
Defining the Request Object
Defining the Response Object
Adding Order Data
Adding a Method to Place a Stock Order
Adding a Service Operation
Testing the orderStockWebService Web Service
Creating a Service Provider
Creating a Model and Defining the Service
Calling the Web Service
Adding a Service Operation
Testing the Service Provider
Creating an Order Stock Portlet
Creating a Model
Modifying the Page
Adding a Portlet Adapter
Consuming the Service
Creating a Variable to Store the Request
Displaying the Interface
Adding Submit Functionality
Testing the Order Stock Portlet
XML Transform Builders
Transform
Transform - Filter
Transform - Rename
Transform - Sort
Summary
Important Points
Chapter 10 Using Charts in Portlets
Charting Data in WPF
Creating a Service Provider
Creating a Model
Defining the Service
Adding Sales Data
Adding a Sales Schema
Adding an Action to Retrieve Sales Data
Specifying the getSales Operation
Testing the Service Provider
239
240
242
243
243
243
245
246
246
251
252
255
255
256
257
258
258
259
259
260
260
260
260
261
262
263
263
263
264
264
264
264
267
268
269
269
270
270
271
271
271
272
xx
Contents
Creating a Sales Chart Portlet
Creating a Model
Modifying the Page
Modifying the Main Action List
Adding a Portlet Adapter
Consuming the Service
Adding a Chart
Configuring the Data Transformation
Specifying Chart Properties
Specifying Minimum Scale Values
Testing the Test Data Portlet
Adding Drill-Down Capabilities
Adding Temporary Variables
Defining the Transform
Specifying a Method to Get the Current Sales Item
Specifying an Action for the getSalesArea Operation
Specifying the getSalesArea Operation
Testing the getSalesArea Operation
Adding a Page for the Sales Area Chart
Adding an Action to Display the salesAreaPage
Configuring the Click Action
Populating the salesAreaPage Page
Testing the Drill-Down from the salesChart Model
Custom Chart Styles
Displaying TargetSales
Using the Custom Style
Upgrading to a Deployment License
Summary
Important Points
Chapter 11 Field Validation, Formatting, and Translation
Validating, Translating, and Formatting Fields
Schema Typed and Non-Schema Typed Fields
Formatter Classes
Client-Side and Server-Side Validation
Creating a Projects Portlet
Creating a Model
Modifying the Page
Adding a Portlet Adapter
Organizing Builders for page1
Adding a Schema
Adding a Variable to Hold User Input
Modifying the Main Action List
Creating a Form
273
273
273
274
274
275
275
276
277
277
278
279
280
280
282
283
283
284
284
285
285
285
287
288
289
290
291
292
292
293
293
294
295
295
296
296
297
297
297
298
299
299
299
Contents
Adding a Submit Button
Adding a Confirmation Page
Modifying the Submit Button
Displaying the User’s Inputs
Adding a Link to Return to the Project Form
Running a Preliminary Test
Adding Formatting, Validation, and Translation
Testing the Projects Portlet
Writing a Formatter Class
Adding a Formatter Class
The CustomFormatter Class
Adding a Linked Java Object
Adding a Data Field Modifier
Further Validation Customizations
Adding a Resource Bundle
Changing Messages for Regular Expressions
Creating the Post-Save Action
Modifying the Post-Save Action Code
Running the Post-Save Action
Summary
Important Points
Chapter 12 Profiling Portlets
Profiling Builder Inputs
Creating an Announcements Portlet
Creating a Model
Modifying the Page
Adding a Portlet Adapter
Creating a Default Resource Bundle
Creating a US English Resource Bundle
Creating an ES Spanish Resource Bundle
Localizing the Announcement Headings
Profiling the Language Input
Profiling the Country Input
Setting a Selection Handler
Placing Headings on the Page
Adding English Announcements
Adding Spanish Announcements
Importing the Announcements
Displaying the Announcements
Running a Preliminary Test
Testing the Selection Handler
Profiling the hrHeader Based on Department
Profiling the itHeader Based on Department
xxi
299
300
300
301
301
302
303
309
312
312
315
316
316
316
316
318
318
319
321
321
322
323
323
325
326
326
327
327
327
328
328
329
332
332
334
335
335
336
336
337
338
339
340
xxii
Contents
Profiling the hrAnnouncements Based on Department
Profiling the itAnnouncements Based on Department
Configuring the userDepartment Profile Set
Testing the companyAnnouncements Portlet
Summary
Important Points
Chapter 13 Using Ajax and Dojo
Using Ajax
Creating a Service Provider
Creating a Model
Defining the Service
Adding Performance Data
Adding Functionality for Retrieving Performance Data
Specifying the getPerformanceData Operation
Adding Functionality for Updating Performance Data
Specifying the updatePerformanceData Operation
Testing the Service Provider
Testing the getPerformanceData Operation
Creating a Performance Portlet
Creating a Model
Modifying the Page
Adding a Portlet Adapter
Consuming the Service
Displaying the Interface
Hiding and Showing a Column Using Ajax
Responding to a Change in the Checkbox Value
Adding an Area Select Field
Adding Submit Functionality
Adding Ajax Type Ahead
Testing the Performance Portlet
Using Dojo
Enabling Dojo Capabilities
Adding an Action to Save Comments
Adding Inline Edit Capabilities
Adding Tooltips
Adding a Feedback Bar
Summary
Important Points
Chapter 14 Error Handling, Logging, and Debugging Portlets
Error Handling
Creating a Model
Modifying the Results Page
340
340
340
341
342
342
345
345
346
347
347
347
348
350
351
352
353
353
354
354
355
355
356
357
357
358
359
359
360
360
362
363
363
365
366
367
369
369
371
371
373
374
Contents
Adding Division Variables
Defining the Division Process
Displaying the Result
Running a Preliminary Test
Creating a Custom Exception
Throwing the Custom Exception
Adding an Error Page
Adding an Error Flag
Adding an Error Action
Adding an Error Handler
Testing the Division Model
Debugging
Debugging Statements
Using Eclipse Debugging
Logging
Debug Tracing
Using a Custom Logging Category
Server Stats
Summary
Important Points
Chapter 15 Performance and Process Optimization
Performance
Caching
Data Set Size
Builder Calls
Session Size
Profiling
Using Ajax and Dojo
Custom Builders
Creating a Model
Modifying the Page
Adding a Portlet Adapter
Creating a Terms & Conditions Builder
Defining Builder Inputs for the Custom Builder
Generating the Custom Builder Artifacts
Modifying the Custom Builder’s Functionality
Modifying the Coordinator
Using the Terms & Conditions Builder
Testing the Information Model
Creating a New Model Wizard
Testing the New Model Wizard Builder
Summary
Important Points
xxiii
374
374
375
375
376
377
377
378
379
379
380
380
381
382
385
385
388
389
391
391
393
393
394
395
395
395
398
398
399
400
400
401
401
403
404
405
407
407
408
409
410
411
411
xxiv
Contents
Chapter 16 More Techniques for Domino
Adding Common Notes Functionality
Notes Formulas, Validation, and Translation
Notes Agents
Keyword Lookups
Categorized Views
Hide-When Fields
Rich Text
Attachments
Domino Data Access Methods
getDominoSession() and getDominoDatabase()
setComputeWithFormEnabled(boolean)
getUserName()
sendDocument(IXml, boolean, boolean) and getDocumentData(String)
Summary
Important Points
Appendix A Setting Up Your Environment
Installing WebSphere Portlet Factory
Configuring WebSphere Portal
Setting Up a New Target Page
Setting Up Access
Configuring Lotus Domino
Start the DIIOP and HTTP Tasks
Enable HTTP Clients to Browse Databases
Creating a Test Database in DB2
Creating a Test Database in SQL Server
Configuring a JDBC Resource
Setting Up a DB2 Database Driver Provider
Setting Up a SQL Server Driver Provider
Configuring the Driver
Configuring a DB2 Data Source
Configuring a SQL Server Data Source
Configuring an Authentication Mechanism
Testing the Data Source
Appendix B Portlet Factory Properties
Properties Files
bowstreet.properties, cluster.properties, and server.properties
jdbcDrivers.properties, pageprocessors.properties, persistentstore.properties
log4j.properties
logging.properties
migrate-profilesets.properties
413
413
414
419
424
428
433
433
434
434
435
435
435
435
436
436
439
439
441
441
443
443
444
444
446
448
451
452
453
453
454
455
456
458
461
461
462
462
462
462
462
Contents
xxv
Using Properties
Domino Server Settings
File Upload Settings
Specifying an Alternate Compiler
Dynamic Class Loading
SOAP and Proxy Access for Web Services
Avoiding Errors Caused by File Length Limitations
The WPF Cache
log4j Logging
Debug Tracing
Event Logging
Server Statistics Logging
Page Automation
464
465
466
466
466
467
468
468
469
470
471
471
472
Glossary
475
Index
493
This page intentionally left blank
Foreword
Building good software applications is hard. Improvements in languages, frameworks, and tools
do make things easier, and there are more of these improvements each year.
But at the same time, the technology landscape that developers live in keeps changing and
getting more complex. Just when you get productive with one set of tools and technology, there’s
something new that you have to adapt to or integrate with. And there’s a perpetual demand for
“more software quicker”—organizations can never get all the software they want as soon as they
want it.
WebSphere® Portlet Factory was created to apply concepts of software automation to help
address this ongoing problem of software development complexity. This software automation
moves the developer up a level, above the level of individual code artifacts. Instead of directly
manipulating elements such as JSP, Java™, JavaScript, and XML files, the developer interacts
with builders in a model, and the builders then generate all the necessary code artifacts in
response to the developer’s high-level instructions.
You can think of builders as encapsulations of software features or design patterns. Each
builder implements one feature of an application, controlled by instructions provided by the
developer in a wizard-like user interface. An application is built by successively adding and modifying features (builders) until the application works as intended. The net effect for developers is
that they can rapidly develop complex applications without having to learn (and remember) all
the underlying technology.
In the past several years working with this technology, we’ve found that developers can
consistently get big productivity gains from this software automation. We’ve seen the technology
adopted by an ever-increasing customer base, first at Bowstreet (where the software was initially
developed), and now at IBM, which acquired Bowstreet in late 2005. At IBM, the technology has
xxvii
xxviii
Foreword
also been adopted by a number of other product groups that build products on top of Portlet Factory technology and take advantage of its software automation. For example, the Lotus®
ActiveInsight Dashboard Framework is built on Portlet Factory and provides a set of builders that
implement high-level design patterns tailored for dashboard-style applications.
We’ve also found that automation makes it possible to quickly add support for new technology, such as integrating new back-end services or generating new user interface technologies.
One example is support for Ajax (Asynchronous Java and XML) user interfaces. Implementing
an Ajax user interface through hand-coding is quite complex and involves coordinated client-side
code (JavaScript) and server-side code. Using builder technology, a small team with Ajax expertise was able to capture their expertise in a set of builders that automate common Ajax patterns
and generate the necessary client and server code. Once the builders were created, those Ajax patterns became easily accessible to any developer using Portlet Factory.
In this book, David Bowley gives a clear “soup-to-nuts” guide to building applications with
Portlet Factory, from creating your first project, to back-end integration, to user interface and
Ajax techniques. Each chapter tackles one aspect of application development, and for each task
David shows you which builders you need and how to use them. In his examples, I think you’ll
see that David has found just the right level of complexity—the examples are simple enough to
easily understand, but not unrealistically simple or trivial.
Portlet Factory development—using builders and models instead of working directly with
code—represents a different development paradigm than with other tools. I hope you find as
much value in this automation paradigm as we have. You can use this book as your guide as you
learn your way around Portlet Factory and get comfortable with this way of working.
Jonathan Booth
Senior Architect
WebSphere Portlet Factory
IBM
Preface
Portlet development can often be arduous and complicated; indeed, the word “rapid” is not normally associated with building portlets. IBM’s award-winning1 WebSphere Portlet Factory
(WPF), however, provides developers with a wizard-based development environment that greatly
expedites the process of building, testing, and deploying portlets. WPF shields developers from
much of the complexity of traditional portlet development, and portlets built using WPF often
require little or no coding—enlarging the potential pool of people who are able to build portlet
applications. Having said this, WPF developers also have the full power of Java 2 Enterprise Edition (J2EE) available to them should they choose to use it, making WPF a flexible (and powerful)
development tool.
This book is about how to use WPF to rapidly build portlets. No previous development
experience is required to understand this book, and anyone with a remote interest in portlet development should find something of interest here. The book is structured to facilitate rapid portlet
development: It is a collection of independent chapters, each walking through the process of creating a portlet while focusing on a particular aspect of WPF. Due to the independent nature of the
chapters (and the nature of portlet development using WPF), you can skip to the chapters that
interest you without needing to read chapter after chapter of abstract theory and/or background
information beforehand. For example, if you want to learn how to build a portlet that displays a
graphical chart, skip to Chapter 10, “Using Charts in Portlets;” if you want to find out how to
work Ajax into your portlets, skip to Chapter 13, “Using Ajax and Dojo.” If you are completely
new to WPF (or portals and portlets) and are looking for some basic information to get you
started in WPF, Chapter 1, “Introduction to WebSphere Portlet Factory,” provides an overview of
1
WebSphere Portlet Factory won the 2006 JavaPro readers’ choice award for “Best Java Enterprise Portal Technology”
(www.fawcette.com/javapro/).
xxix
xxx
Preface
portal terminology, WPF architecture, and the WPF Designer interface. Chapter 1 also walks you
through the process of creating, testing, and deploying a simple Hello World! portlet. Other introductory information is available in Appendix A, which contains some useful information for setting up your WPF development environment, and there is a glossary at the back of the book that
defines common WPF terms.
This book also contains useful tidbits that I have picked up during my time with WPF—the
sort of things developers need to know but normally wouldn’t without a great deal of experimentation and frustration. These snippets of information are highlighted as follows:
TIP
Tips contain useful information that can be employed in WPF, usually with the purpose of
expediting portlet development. Tips are useful, but they are not critically important and can
be skipped if desired.
WARNING
Warnings are important points that usually obviate a common sticking point, and heeding
them may spare you future frustration.
Due to the width of the book’s printed page, some lines of code might be too long to fit on
only one line. If a line of code wraps to another line(s), and it’s not obvious it’s part of the preceding line, we have inserted a code continuation character ([ccc]) at the beginning of the runover
line to indicate that the code is part of the line preceding it. (You should type lines of code that
have this character as one long line without breaking it.) For example,
WebAppAccess remoteWebAppAccess =
➥webAppAccess.getModelInstance(“modelPath/ModelName”, “”,
➥false);
All the examples discussed in this book are available for download from ibmpressbooks.
com/title/9780137134465. More advanced readers can import what they want from these
examples directly into their projects, without necessarily consulting the book itself—although
you are encouraged to follow along with the examples to increase your understanding of WPF.
By walking through each example, you will learn how to build portlets in WPF by actually building them, and not just reading about it; so, by the end of each chapter, you should have a practical
understanding of how to work the discussed features into your own portlets.
Although this book does discuss the theory of WPF portlet development, this information is
discussed in the context of the practical examples in the book, which gives you a more concrete
Preface
xxxi
understanding of how the abstract side of portlet development is applied. Readers unconcerned
with what is going on under the covers can skip the theory sections without adversely affecting
their portlets. Indeed, one of the advantages of using WPF is that you don’t need to learn vast
amounts of theory to begin development—you can start building portlets right away. The focus of
this book, then, is on the practical side of portlet development, with an emphasis on rapidly building portlets with certain functionality—this is not intended as a book of theory. Similarly, given
its short length, this book is not intended to cover every aspect of portlet development—only
those areas that are deemed most useful to portlet developers (and WPF developers, in particular).
I hope you find this book useful and enjoyable to read; I certainly enjoyed writing it. At the
least, I would like this book to go some way toward expediting your portlet development process
and increasing your understanding of WPF. If you have any comments about the content or structure of the book, feel free to drop me a line at [email protected]
This page intentionally left blank
Acknowledgments
I’d like to extend my sincerest appreciation to everyone who supported me during the process of
writing this book. In particular, I’d like to thank John Bergland and Dee Zepf for their early support of the concept, and Jonathan Booth and Louise Simonds for their insightful comments and
advice. I’m eternally grateful to Katherine Bull, my acquisitions editor, for her continual support
and direction throughout the project; and to Kevin Howard, my development editor, who carefully surveyed each chapter and made many helpful suggestions. Thanks also to Carlos Llopart
for the Spanish translations in Chapter 12, and to my sister Kirsten for providing several of the
diagrams that appear in this book.
Of course, a thank you is also due to you, the reader, for purchasing this book and investing
the time to read it. I hope that this book increases your understanding of WebSphere Portlet Factory and provides you with a valuable portlet development resource.
xxxiii
This page intentionally left blank
About the Author
David Bowley is a consultant for e-Centric Innovations, an e-business solution provider in Melbourne, Australia. Over the last nine years, David has worked extensively with IBM technologies,
particularly WebSphere Portal and WebSphere Portlet Factory. David has a bachelor’s degree in
computing and holds numerous I.T. certifications in areas such as WebSphere Portal, WebSphere
Portlet Factory, Java, Lotus Notes, .Net, DB2, Rational, SOA, and RUP. David is a frequent contributor to various technical publications, including The View and Lotus Advisor.
xxxv
This page intentionally left blank
C
H A P T E R
1
Introduction to
WebSphere Portlet
Factory
This chapter explains basic portal concepts (such as what portals and portlets are), and introduces
the fundamentals of portlet development using WebSphere Portlet Factory (WPF). By the end of
the chapter, you will have a working Hello World! portlet and you will understand the basic concepts and techniques required to build, deploy, and test portlets using WPF. This chapter is
intended for WPF newcomers, but those who are interested in brushing up on the basics of WPF
should also find something of interest in it. If you already feel confident using WPF, feel free to
skip ahead to any of the later chapters—you can always come back to this chapter if you need to.
The files used in this chapter are available for download from ibmpressbooks.com/title/
9780137134465 under the Chapter 1 folder (instructions for copying these files into your project
are included in a readme.txt file in the same folder); however, to increase your understanding of
the topics discussed, it is recommended that you create these files yourself by following the
example in this chapter. Doing so will give you a good understanding of the basics of WPF and
position you to tackle some of the other chapters in this book.
The following topics are covered in this chapter:
• What is a portal and what are portlets?
• Portal key benefits
• What is WebSphere Portlet Factory?
• WebSphere Portlet Factory key benefits
• WebSphere Portlet Factory architecture
• Introduction to the WebSphere Portlet Factory Designer
• Building your first portlet
1
2
Chapter 1 Introduction to WebSphere Portlet Factory
What Is a Portal and What Are Portlets?
A portal is a user interface (UI) for people to interact with information and processes, often via
Web pages accessed using a Web browser (such as the portal shown in Figure 1.1). Portals are
provided by a portal server, such as WebSphere Portal Server, in a similar way to how Web pages
are provided by an ordinary Web server. Portals usually aim to streamline business operations by
bringing together information and processes from disparate parts of an organization. For
example, an online bookstore may provide a portal for customers to preview new releases, purchase new books, check the status of any current orders, and even chat with other customers to
share their thoughts on a particular book. Portal functionality is normally provided through one
or more portlets, which are UI components of the portal that serve a particular function (similar
to how a window offers a particular function—or suite of functions—within a Microsoft® Windows® application). In the case of an online bookstore, then, a portal might include a New
Releases portlet and a Forum portlet.
Figure 1.1
An example portal at www.ibm.com/developerworks/.
Portlets are laid out onto various pages within the portal, each page effectively containing a
set of portlets that serves a common purpose. So, a Purchase page might contain portlets for
Portal Key Benefits
3
browsing a catalogue and for buying new books, and a Community page might contain portlets
that facilitate communication with other customers. Portals don’t necessarily have to be customer
facing; for example, an intranet portal might be available only to employees, and an extranet portal might be available only to suppliers. A portal can be anything from a simple front-end to a
backend data source, to a complex collaborative tool integrating several different departments
across an enterprise.
Due to the current bandwidth limitations of the Web, portals are usually kept relatively
simple in comparison with more traditional rich clients (like Microsoft Word, for example). Similarly, portlets are not normally as packed with features as their rich client cousins, and they offer
a more focused service. As a result, portlets normally satisfy some key business requirement or
process (either individually or in conjunction with other portlets). Having said this, portals available through a Web browser can be accessed on a wide variety of platforms, using a number of
different devices, and from anywhere in the world; so, potential exposure to a portal available
through a Web browser is vastly superior to that gained through a rich client. Careful consideration, then, needs to be applied to the portal design process, and a portal should aim to supplement
rich client applications rather than replace them.
Portal Key Benefits
Depending on its exact nature, a portal usually offers one or more of the following key benefits:
• Integration of Business Functions—Probably the most common use for a portal is as
an integrator of business functions, usually across departmental or technological boundaries within an enterprise. For example, a portal might provide portlets for accessing
accounting applications in SAP, reports on a SQL server, and email capabilities from
Lotus Domino®, and it can enable you to use these portlets (and even send information
between them) as if they were all part of the same system. This sort of integration promotes standardization of business processes and discourages the practice of viewing an
organization as a collection of isolated business units.
• Aggregation of Information—Another popular use for a portal is as an aggregator of
information—that is, as a means to bring together information from disparate locations
or data sources into a single interface (again, giving the impression that all of the information is stored in the same place). A portal can save users from needing to use several
different programs to hunt through multiple systems in search of information.
• Collaboration between Users—Portals often provide functionality that facilitates
communication and information sharing across an enterprise (such as document sharing, email, blogs, and project team rooms).
• Accessibility of Information and Services—One of the greatest features of the Web is
how it quickly and easily facilitates communication between people from vastly different locations and backgrounds. As a result, portals often provide an experience tailored
4
Chapter 1 Introduction to WebSphere Portlet Factory
to the context in which they are accessed. For example, a portal may be offered in several different languages, and different markups (such as HTML and WML) may be used
to allow access to the portal using different devices (such as mobile phones, laptops,
PCs, and PDAs).
Portal servers also provide mechanisms to restrict accessibility through customizable
authentication and authorization mechanisms that can leverage an organization’s existing security methods (such as Lightweight Directory Access Protocol [LDAP] and
Lotus Notes® Access Control Lists [ACL]). Putting this into practice, an employee from
a sales department might be able to see only the sales portion of a portal, and an unauthorized person might not be able to log on at all.
• User Interface Personalization—Portals often provide a certain degree of personalization, such as allowing customers to specify the information they see and how it should
be displayed. For example, a portal can provide facilities for end users to choose the
position of portlets on the page or to add and remove portlets as required.
What Is WPF?
WPF is a tool for Eclipse-based Integrated Development Environments (IDE) that facilitates
rapid application development. This is achieved primarily through the use of wizard-based,
reusable components called builders, which can be parameterized based on different contexts and
automatically built into executable code.
Developers can create WPF applications by creating a WPF project in an Eclipse-based
IDE (such as Rational® Software Architect [RSA], Rational Application Developer [RAD], or
Eclipse itself), which has WPF installed into it. After it is installed, WPF adds new design artifacts to the IDE that enable the development of WPF applications. WPF projects can then be
automatically assembled into Web ARrchive (WAR) files (a WAR file is an archive of Java design
artifacts for a Web application) from the IDE and deployed to local or remote application servers
or portal servers.
Note that although you can use any version of WPF to complete the examples in this book,
it is assumed that you are using WPF 6.0.2.
WPF Key Benefits
Some of the key benefits of WPF are:
• Reduced Need for Hand Coding—Developers can build standards-based applications
(such as portlets, Web services, or Java 2 Enterprise Edition [J2EE] applications) with
little or no coding. Given the reduced need to write code, the skill set required to build
complex applications (in J2EE, for example) is drastically reduced.
• Faster Development Times—As WPF development is mostly wizard-based, it is less
error prone than traditional development and can greatly speed up the development
WPF Architecture
5
process. WPF applications are also more flexible than traditional Java applications in
that they are easier to maintain and extend.
• Best Practices—WPF encourages component- and service-based design, and can be
used to enforce architectural patterns and best practices.
• Powerful Capabilities—WPF has a suite of around 160 wizard-like builders that can be
used to automate many common development tasks. These builders have strong integration capabilities with a broad range of backend data sources.
WPF Architecture
At design time, WPF applications consist of three main building blocks: builders, models, and
profiles. Developers work with these elements (along with other design elements like HTML
pages, XML documents, and Java classes) in a special type of project called a WebSphere Portlet
Factory project (see the “Introduction to the Eclipse IDE” sidebar later in this chapter if you are
unfamiliar with projects in Eclipse). Using all of these elements, a WPF mechanism known as the
Factory generation engine can automatically generate executable applications called WebApps.
WPF can also automatically package these WebApps
Sign up for the monthly IBM PRESS NEWSLETTER at
ibmpressbooks.com/newsletters
LEARN
• NEW PODCASTS
from your favorite authors
• ARTICLES & INTERVIEWS
with authors
• SPECIAL OFFERS
from IBM Press and partners
• NOTICES & REMINDERS
about author appearances and conferences
WIN
Sign up for the IBM PRESS NEWSLETTER and
you will be automatically entered into a
QUARTERLY GIVE-AWAY
for 3 months access to Safari Books Online –
online access to more than 5000 books
A $150 VALUE!
Sign up at ibmpressbooks.com/newsletter
REGISTER YOUR BOOK
ibmpressbooks.com/ibmregister
REGISTRATION ENTITLES YOU TO:
• Supplemental materials that may be available
• Advance notice of forthcoming editions
• A coupon that can be used on your next purchase from ibmpressbooks.com
Visit ibmpressbooks.com
for all product information
Related Books of Interest
Service-Oriented
Architecture (SOA) Compass
WebSphere Business
Integration Primer
Business Value, Planning,
and Enterprise Roadmap
Process Server, BPEL, SCA, and SOA
by Norbert Bieberstein, Sanjay Bose,
Marc Fiammante, Keith Jones, and Rawn Shah
ISBN: 0-13-187002-5
®
In this book, IBM Enterprise Integration Team
experts present a start-to-finish guide to planning, implementing, and managing ServiceOriented Architecture. Drawing on their extensive
experience helping enterprise customers migrate
to SOA, the authors share hard-earned lessons
and best practices for architects, project managers, and software development leaders alike.
Well-written and practical, Service-Oriented
Architecture Compass offers the perfect blend of
principles and “how-to” guidance for transitioning
your infrastructure to SOA. The authors clearly
explain what SOA is, the opportunities it offers,
and how it differs from earlier approaches. Using
detailed examples from IBM consulting engagements, they show how to deploy SOA solutions
that tightly integrate with your processes and
operations, delivering maximum flexibility and
value. With detailed coverage of topics ranging
from policy-based management to workflow
implementation, no other SOA book offers
comparable value to workingIT professionals.
by Ashok Iyengar, Vinod Jessani,
and Michele Chilanti
ISBN: 0-13-224831-X
Using WebSphere® Business Integration (WBI)
technology, you can build an enterprise-wide
Business Integration (BI) infrastructure that makes
it easier to connect any business resources and
functions, so you can adapt more quickly to the
demands of customers and partners. Now there’s
an introductory guide to creating standards-based
process and data integration solutions with WBI.
WebSphere Business Integration Primer
thoroughly explains Service Component
Architecture (SCA), basic business processes,
and complex long-running business flows, and
guides you to choose the right process integration
architecture for your requirements. Next, it introduces the key components of a WBI solution and
shows how to make them work together rapidly
and efficiently. This book will help developers,
technical professionals, or managers understand
today’s key BI issues and technologies, and
streamline business processes by combining
BI with Service Oriented Architecture (SOA).
Sign up for the monthly IBM Press newsletter at
ibmpressbooks/newsletters
Related Books of Interest
The New Language
of Business
SOA & Web 2.0
by Sandy Carter
ISBN: 0-13-195654-X
Executing SOA
A Practical Guide for the ServiceOriented Architect
by Norbert Bieberstein, Robert G. Laird,
Dr. Keith Jones, and Tilak Mitra
ISBN: 0-13-235374-1
In The New Language of Business, senior IBM
executive Sandy Carter demonstrates how to
leverage SOA, Web 2.0, and related technologies
to drive new levels of operational excellence and
business innovation.
In Executing SOA, four experienced SOA
implementers share realistic, proven, “from-thetrenches” guidance for successfully delivering on
even the largest and most complex SOA initiative.
You’ll learn how to organize your business into
reusable process components — and support
them with cost-effective IT services that adapt
quickly and easily to change. Then, using
extensive examples — including a detailed case
study describing IBM’s own experience — Carter
identifies best practices, pitfalls, and practical
starting points for success.
This book follows up where the authors’ bestselling Service-Oriented Architecture Compass
left off, showing how to overcome key obstacles
to successful SOA implementation and identifying
best practices for all facets of execution—
technical, organizational, and human. Among
the issues it addresses: introducing a services
discipline that supports collaboration and
information process sharing; integrating services
with preexisting technology assets and strategies;
choosing the right roles for new tools; shifting
culture, governance, and architecture; and
bringing greater agility to the entire organizational
lifecycle, not just isolated projects.
Listen to the author’s podcast at:
ibmpressbooks.com/podcasts
Listen to the author’s podcast at:
ibmpressbooks.com/podcasts
Writing for executives and business leaders inside
and outside IT, Carter explains why flexibility and
responsiveness are now even more crucial to
success — and why services-based strategies
offer the greatest promise for achieving them.
Visit ibmpressbooks.com
for all product information
Related Books of Interest
IBM WebSphere
and Lotus
Lamb, Laskey, Indurkhya
ISBN: 0-13-144330-5
Enterprise Messaging
Using JMS and IBM
WebSphere
Enterprise Java
Programming with
IBM WebSphere
Second Edition
Yusuf
ISBN: 0-13-146863-4
IBM WebSphere System
Administration
by Kyle Brown, Dr. Gary Craig, Greg Hester,
David Pitt, Russell Stinehour, Mark Weitzel,
Jim Amsden, Peter M. Jakab, and Daniel Berg
Williamson, Chan, Cundiff,
Lauzon, Mitchell
ISBN: 0-321-18579-X
Outside-in Software
Development
Enterprise Java™ Programming with IBM
WebSphere, Second Edition is the definitive guide
to building mission-critical enterprise systems
with J2EE™, WebSphere, and WebSphere
Studio Application Developer. Fully updated for
Versions 5.x of WebSphere Application Server
and WebSphere Studio Application Developer,
it combines expert architectural best practices
with a case study that walks you through
constructing an entire system.
The authors are an extraordinary team of
WebSphere insiders: developers, consultants,
instructors, and IBM WebSphere development
team members. Together, they offer unprecedented insight into the use and behavior of
WebSphere’s APIs in real-world environments
— and systematic guidance for delivering
systems of exceptional performance,
robustness, and business value.
Sign up for the monthly IBM Press newsletter at
ibmpressbooks/newsletters
ISBN: 0-13-144604-5
Kessler, Sweitzer
ISBN: 0-13-157551-1
Enterprise Master
Data Management
Dreibelbis, Hechler, Milman,
Oberhofer, van Run, Wolfson
ISBN: 0-13-236625-8
Rapid Portlet
Development
with WebSphere
Portlet Factory
®
Requirements
Requirements
This page intentionally left blank
IBM WebSphere
Rapid Portlet
Development with
®
Deployment
and Advanced
WebSphere
Configuration
Portlet Factory
[SUBTITLE ]
Step-by-Step Guide for Building
Roland Barcia,
Bill Hines,
TomPortlets
Alcott, and Keys Botzum
Your
Own
David Bowley
IBM Press
Pearson plc
Upper Saddle River, NJ • Boston • Indianapolis • San Francisco
New York • Toronto • Montreal • London • Munich • Paris • Madrid
Cape Town • Sydney • Tokyo • Singapore • Mexico City
Ibmpressbooks.com
The author and publisher have taken care in the preparation of this book, but make no expressed or implied
warranty of any kind and assume no responsibility for errors or omissions. No liability is assumed for
incidental or consequential damages in connection with or arising out of the use of the information or
programs contained herein.
© Copyright 2009 by International Business Machines Corporation. All rights reserved.
Note to U.S. Government Users: Documentation related to restricted right. Use, duplication, or disclosure
is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corporation.
IBM Press Program Managers: Tara Woodman, Ellice Uffer
Cover Design: IBM Corporation
Associate Publisher: Greg Wiegand
Marketing Manager: Kourtnaye Sturgeon
Publicist: Heather Fox
Acquisitions Editor: Katherine Bull
Development Editor: Kevin Howard
Managing Editor: Kristy Hart
Designer: Alan Clements
Senior Project Editor: Lori Lyons
Copy Editor: Deadline Driven Publishing
Indexer: WordWise Publishing Services
Compositor: Nonie Ratcliff
Proofreader: Water Crest Publishing
Manufacturing Buyer: Dan Uhrig
Published by Pearson plc
Publishing as IBM Press
IBM Press offers excellent discounts on this book when ordered in quantity for bulk purchases or special
sales, which may include electronic versions and/or custom covers and content particular to your business,
training goals, marketing focus, and branding interests. For more information, please contact:
U. S. Corporate and Government Sales
1-800-382-3419
[email protected]
For sales outside the U.S., please contact:
International Sales
[email protected]
The following terms are trademarks or registered trademarks of International Business Machines
Corporation in the United States, other countries, or both: IBM, the IBM logo, IBM Press, DB2, Domino,
Domino Designer, Lotus, Lotus Notes, Rational, and WebSphere. Java and all Java-based trademarks are
trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Microsoft, Windows,
Windows NT, and the Windows logo are trademarks of the Microsoft Corporation in the United States,
other countries, or both. Linux is a registered trademark of Linus Torvalds. Intel, Intel Inside (logo), MMX,
and Pentium are trademarks of Intel Corporation in the United States, other countries, or both. Other
company, product, or service names may be trademarks or service marks of others.
Library of Congress Cataloging-in-Publication Data
Bowley, David.
Rapid portlet development with WebSphere portlet factory : step-by-step guide for building your own
portlets / David Bowley.
p. cm.
Includes index.
ISBN 0-13-713446-0 (hardback : alk. paper) 1. Web portals—Computer programs. 2. User interfaces
(Computer systems) Computer programs. 3. Web site development. 4. WebSphere. I. Title.
TK5105.8885.W43B69 2008
006.7’6—dc22
2008029014
All rights reserved. This publication is protected by copyright, and permission must be obtained from the
publisher prior to any prohibited reproduction, storage in a retrieval system, or transmission in any form or
by any means, electronic, mechanical, photocopying, recording, or likewise. For information regarding
permissions, write to:
Pearson Education, Inc
Rights and Contracts Department
501 Boylston Street, Suite 900
Boston, MA 02116
Fax (617) 671 3447
ISBN-13: 978-0-13-713446-5
ISBN-10: 0-13-713446-0
Text printed in the United States on recycled paper at R.R. Donnelley in Crawfordsville, Indiana.
First printing September 2008
This page intentionally left blank
Contents at a Glance
Foreword
xxvii
Preface
xxix
Acknowledgments
xxxiii
About the Author
xxxv
Chapter 1
Introduction to WebSphere Portlet Factory
Chapter 2
Providing and Consuming Services
37
Chapter 3
Using Data from a Relational Data Source
53
Chapter 4
Using Domino Data
77
Chapter 5
Customizing Portlet Appearance
107
Chapter 6
Adding Basic User Interface Controls to Your Portlets
149
Chapter 7
Communicating Between Portlets
165
Chapter 8
Using Java in Portlets
195
Chapter 9
Using Web Services and Manipulating XML
239
Chapter 10
Using Charts in Portlets
267
Chapter 11
Field Validation, Formatting, and Translation
293
Chapter 12
Profiling Portlets
323
Chapter 13
Using Ajax and Dojo
345
Chapter 14
Error Handling, Logging, and Debugging Portlets
371
Chapter 15
Performance and Process Optimization
393
Chapter 16
More Techniques for Domino
413
Appendix A
Setting Up your Environment
439
Appendix B
Portlet Factory Properties
461
Glossary
475
Index
493
xi
1
This page intentionally left blank
Contents
Foreword
xxvii
Preface
Chapter 1
xxix
Acknowledgments
xxxiii
About the Author
xxxv
Introduction to WebSphere Portlet Factory
What Is a Portal and What Are Portlets?
Portal Key Benefits
What Is WPF?
WPF Key Benefits
WPF Architecture
Builders
Models
Profiles
Generating and Executing the WebApp
Portlet Factory WAR Files
Deployment Configurations
Introduction to the WebSphere Portlet Factory Designer
The User Interface
Folder Structure
Building Your First Portlet
Creating a Project
Manual Deployment
Creating a Model
Testing the Application
Summary
Important Points
xiii
1
2
3
4
4
5
5
6
7
7
11
12
13
13
17
21
21
26
30
31
35
35
xiv
Contents
Chapter 2
Providing and Consuming Services
The Service Provider/Consumer Pattern
Creating a Service Provider
Creating a Model
Defining the Service
Adding Roster Data
Adding an Action to Retrieve a Roster
Adding a Service Operation
Testing the Service Provider
Creating a Service Consumer
Creating a Model
Configuring the Portlet Adapter
Testing the Service Consumer
Creating a Stub Service
Applying the Service Provider/Consumer Pattern
Summary
Important Points
Chapter 3
Using Data from a Relational Data Source
Using Data Services
Creating a Service Provider
Creating a Model
Defining the Service
Specifying the First Operation
Specifying the Second Operation
Specifying the Third Operation
Specifying the Fourth Operation
Specifying the Fifth Operation
Testing the Service Provider
Testing the retrieveContactsView Operation
Testing the getContactDetail Operation
Testing the createContact Operation
Testing the setContact Operation
Testing the deleteContact Operation
Creating a Contacts Portlet
Creating a Model
Configuring the Portlet Adapter
Adding Update Functionality
Adding Delete Functionality
Adding Create Functionality
Testing the Contacts Portlet
Summary
Important Points
37
37
39
40
41
42
43
43
44
45
46
47
47
48
49
51
51
53
53
54
54
55
55
55
56
57
58
60
61
62
63
63
63
63
64
65
65
66
69
72
74
75
Contents
Chapter 4
xv
Using Domino Data
Portalizing Notes Functionality
Configuring Your Environment
Configuring the Domino Properties File
Testing the Connection to Domino
Creating a Service Provider
Creating a Model
Defining the Service
Specifying Operations
Adding a Delete Operation
Testing the Service Provider
Testing the readSupplierView Operation
Testing the readSupplierDocument Operation
Testing the updateSupplierDocument Operation
Testing the createSupplierDocument Operation
Testing the deleteSupplierDocument Operation
Creating a Suppliers Portlet
Creating a Model
Configuring the Portlet Adapter
Adding Update Functionality
Adding Delete Functionality
Adding Create Functionality
Removing Unwanted Fields
Testing the Service Consumer
Using a Stub Service
Creating a Stub Model
Using the Stub Model
Summary
Important Points
Chapter 5
Customizing Portlet Appearance
Customizing Portlet Appearance
Creating a Service Provider
Creating a Model
Defining the Service
Adding an Asset Schema
Adding Asset Data
Adding an Action to Retrieve a List of Assets
Specifying the getAssetsList Operation
Testing the Service Provider
Creating an Assets Portlet
Creating a Model
Adding a Portlet Adapter
77
78
79
80
81
82
82
83
83
85
88
88
89
90
90
90
91
91
93
94
94
97
99
100
102
103
104
105
105
107
108
108
109
109
109
110
112
112
113
114
114
114
xvi
Contents
Consuming the Service
Displaying Assets Data
Testing the Assets Portlet
Pagination
Turning on Pagination
Modifying the Paging Buttons
Data Modifiers
The Data Column Modifier Builder
The Data Hierarchy Modifier Builder
The Data Field Modifier Builder
The Form Layout Builder
Working with Web Pages
HTML Builders
JSP Builders
JavaScript
HTML Templates
Cascading Style Sheets
Adding a Style Sheet
Summary
Important Points
Chapter 6
Adding Basic User Interface Controls
to Your Portlets
User Interface Controls in WPF
Creating a Survey Portlet
Creating a Model
Modifying the Page
Adding a Portlet Adapter
Testing the Survey Portlet
Summary
Important Points
Chapter 7
Communicating Between Portlets
The Benefits of Inter-Portlet Communication
The WebSphere Property Broker
Creating a Service Provider
Creating a Model
Defining the Service
Adding Loan Data
Adding an Action to Retrieve a List of Loans
Specifying the getLoansList Operation
Adding a Method to Retrieve a Specific Loan
Specifying the getLoanDetail Operation
114
114
117
119
120
120
122
122
124
124
127
132
133
135
135
137
142
144
146
146
149
149
151
151
152
153
160
163
164
165
166
166
167
168
168
168
169
170
170
171
Contents
xvii
Testing the Service Provider
Creating a List Portlet
Creating a Model
Specifying the Service
Specifying List and Detail Operations
Configuring the Portlet Adapter
Defining the Portlet as a Cooperative Source
Testing the List Portlet
Creating a Detail Portlet
Creating a Model
Adding a Default Message Page
Adding a main Action
Adding an Interface for Loan Details
Defining the Portlet as a Cooperative Target
Handling an Inter-Portlet Communication Event
Testing the Detail Portlet
Configuring the WebSphere Property Broker
Testing Inter-Portlet Communication
Alternative Communication Methods
Property Broker Action
WPF Event Model
Shared Variables
Configuring Actions for loansList
Running selectLoan
Using the Shared Variable in the loanDetail Model
Click-to-Action (C2A)
When to Use Inter-Portlet Communication
Summary
Important Points
Chapter 8
Using Java in Portlets
Java Development Considerations
Java Methods
Inline Java
Action Lists
The Method Builder
The Linked Java Object Builder
Java Application Programming Interfaces
com.bowstreet.WebApp.WebAppAccess
com.bowstreet.webapp.Variables
com.bowstreet.webapp.RequestInputs
com.bowstreet.util.IXml and com.bowstreet.util.XmlUtil
javax.servlet.http.HttpServletRequest and javax.servlet.http.HttpServletResponse
171
173
173
173
174
175
176
177
177
178
179
179
179
180
181
182
183
184
184
185
186
189
191
192
192
192
192
193
193
195
196
198
198
200
200
201
202
203
206
207
208
209
xviii
Contents
Java Beans
Creating a Java Bean and Bean Manager
Creating a Shopping Cart Item Bean
Creating a Shopping Cart Item Manager
Creating a Service Provider
Creating a Model
Defining the Service
Adding a Linked Java Object
Adding a Java to XML Converter
Clearing a Shopping Cart
Viewing a Shopping Cart
Viewing a Shopping Cart Item
Adding a Shopping Cart Item
Updating a Shopping Cart Item
Deleting a Shopping Cart Item
Testing the Service Provider
Testing the addShoppingCartItem Operation
Testing the viewShoppingCart Operation
Testing the viewShoppingCartItem Operation
Testing the updateShoppingCartItem Operation
Testing the deleteShoppingCartItem Operation
Testing the clearShoppingCart Operation
Creating a Shopping Cart Portlet
Creating a Model
Configuring the Portlet Adapter
Implementing the updateShoppingCartItem Operation
Implementing the addShoppingCartItem Operation
Implementing the clearShoppingCart Operation
Implementing the deleteShoppingCartItem Operation
Testing the Shopping Cart Portlet
Testing the Add Item Button
Testing the Edit Item Button
Testing the Delete Item Button
Testing the Clear Cart Button
Java Archives
Importing JARs
Excluding JARs from WAR Files
Summary
Important Points
210
210
211
213
216
217
217
217
217
218
219
221
222
223
223
224
225
225
225
226
226
226
226
226
228
228
229
229
230
232
232
233
233
233
234
234
235
236
236
Contents
Chapter 9
xix
Using Web Services and Manipulating XML
Web Services in WPF
Creating an Order Stock Web Service
Creating a Model
Defining the Service
Defining the Request Object
Defining the Response Object
Adding Order Data
Adding a Method to Place a Stock Order
Adding a Service Operation
Testing the orderStockWebService Web Service
Creating a Service Provider
Creating a Model and Defining the Service
Calling the Web Service
Adding a Service Operation
Testing the Service Provider
Creating an Order Stock Portlet
Creating a Model
Modifying the Page
Adding a Portlet Adapter
Consuming the Service
Creating a Variable to Store the Request
Displaying the Interface
Adding Submit Functionality
Testing the Order Stock Portlet
XML Transform Builders
Transform
Transform - Filter
Transform - Rename
Transform - Sort
Summary
Important Points
Chapter 10 Using Charts in Portlets
Charting Data in WPF
Creating a Service Provider
Creating a Model
Defining the Service
Adding Sales Data
Adding a Sales Schema
Adding an Action to Retrieve Sales Data
Specifying the getSales Operation
Testing the Service Provider
239
240
242
243
243
243
245
246
246
251
252
255
255
256
257
258
258
259
259
260
260
260
260
261
262
263
263
263
264
264
264
264
267
268
269
269
270
270
271
271
271
272
xx
Contents
Creating a Sales Chart Portlet
Creating a Model
Modifying the Page
Modifying the Main Action List
Adding a Portlet Adapter
Consuming the Service
Adding a Chart
Configuring the Data Transformation
Specifying Chart Properties
Specifying Minimum Scale Values
Testing the Test Data Portlet
Adding Drill-Down Capabilities
Adding Temporary Variables
Defining the Transform
Specifying a Method to Get the Current Sales Item
Specifying an Action for the getSalesArea Operation
Specifying the getSalesArea Operation
Testing the getSalesArea Operation
Adding a Page for the Sales Area Chart
Adding an Action to Display the salesAreaPage
Configuring the Click Action
Populating the salesAreaPage Page
Testing the Drill-Down from the salesChart Model
Custom Chart Styles
Displaying TargetSales
Using the Custom Style
Upgrading to a Deployment License
Summary
Important Points
Chapter 11 Field Validation, Formatting, and Translation
Validating, Translating, and Formatting Fields
Schema Typed and Non-Schema Typed Fields
Formatter Classes
Client-Side and Server-Side Validation
Creating a Projects Portlet
Creating a Model
Modifying the Page
Adding a Portlet Adapter
Organizing Builders for page1
Adding a Schema
Adding a Variable to Hold User Input
Modifying the Main Action List
Creating a Form
273
273
273
274
274
275
275
276
277
277
278
279
280
280
282
283
283
284
284
285
285
285
287
288
289
290
291
292
292
293
293
294
295
295
296
296
297
297
297
298
299
299
299
Contents
Adding a Submit Button
Adding a Confirmation Page
Modifying the Submit Button
Displaying the User’s Inputs
Adding a Link to Return to the Project Form
Running a Preliminary Test
Adding Formatting, Validation, and Translation
Testing the Projects Portlet
Writing a Formatter Class
Adding a Formatter Class
The CustomFormatter Class
Adding a Linked Java Object
Adding a Data Field Modifier
Further Validation Customizations
Adding a Resource Bundle
Changing Messages for Regular Expressions
Creating the Post-Save Action
Modifying the Post-Save Action Code
Running the Post-Save Action
Summary
Important Points
Chapter 12 Profiling Portlets
Profiling Builder Inputs
Creating an Announcements Portlet
Creating a Model
Modifying the Page
Adding a Portlet Adapter
Creating a Default Resource Bundle
Creating a US English Resource Bundle
Creating an ES Spanish Resource Bundle
Localizing the Announcement Headings
Profiling the Language Input
Profiling the Country Input
Setting a Selection Handler
Placing Headings on the Page
Adding English Announcements
Adding Spanish Announcements
Importing the Announcements
Displaying the Announcements
Running a Preliminary Test
Testing the Selection Handler
Profiling the hrHeader Based on Department
Profiling the itHeader Based on Department
xxi
299
300
300
301
301
302
303
309
312
312
315
316
316
316
316
318
318
319
321
321
322
323
323
325
326
326
327
327
327
328
328
329
332
332
334
335
335
336
336
337
338
339
340
xxii
Contents
Profiling the hrAnnouncements Based on Department
Profiling the itAnnouncements Based on Department
Configuring the userDepartment Profile Set
Testing the companyAnnouncements Portlet
Summary
Important Points
Chapter 13 Using Ajax and Dojo
Using Ajax
Creating a Service Provider
Creating a Model
Defining the Service
Adding Performance Data
Adding Functionality for Retrieving Performance Data
Specifying the getPerformanceData Operation
Adding Functionality for Updating Performance Data
Specifying the updatePerformanceData Operation
Testing the Service Provider
Testing the getPerformanceData Operation
Creating a Performance Portlet
Creating a Model
Modifying the Page
Adding a Portlet Adapter
Consuming the Service
Displaying the Interface
Hiding and Showing a Column Using Ajax
Responding to a Change in the Checkbox Value
Adding an Area Select Field
Adding Submit Functionality
Adding Ajax Type Ahead
Testing the Performance Portlet
Using Dojo
Enabling Dojo Capabilities
Adding an Action to Save Comments
Adding Inline Edit Capabilities
Adding Tooltips
Adding a Feedback Bar
Summary
Important Points
Chapter 14 Error Handling, Logging, and Debugging Portlets
Error Handling
Creating a Model
Modifying the Results Page
340
340
340
341
342
342
345
345
346
347
347
347
348
350
351
352
353
353
354
354
355
355
356
357
357
358
359
359
360
360
362
363
363
365
366
367
369
369
371
371
373
374
Contents
Adding Division Variables
Defining the Division Process
Displaying the Result
Running a Preliminary Test
Creating a Custom Exception
Throwing the Custom Exception
Adding an Error Page
Adding an Error Flag
Adding an Error Action
Adding an Error Handler
Testing the Division Model
Debugging
Debugging Statements
Using Eclipse Debugging
Logging
Debug Tracing
Using a Custom Logging Category
Server Stats
Summary
Important Points
Chapter 15 Performance and Process Optimization
Performance
Caching
Data Set Size
Builder Calls
Session Size
Profiling
Using Ajax and Dojo
Custom Builders
Creating a Model
Modifying the Page
Adding a Portlet Adapter
Creating a Terms & Conditions Builder
Defining Builder Inputs for the Custom Builder
Generating the Custom Builder Artifacts
Modifying the Custom Builder’s Functionality
Modifying the Coordinator
Using the Terms & Conditions Builder
Testing the Information Model
Creating a New Model Wizard
Testing the New Model Wizard Builder
Summary
Important Points
xxiii
374
374
375
375
376
377
377
378
379
379
380
380
381
382
385
385
388
389
391
391
393
393
394
395
395
395
398
398
399
400
400
401
401
403
404
405
407
407
408
409
410
411
411
xxiv
Contents
Chapter 16 More Techniques for Domino
Adding Common Notes Functionality
Notes Formulas, Validation, and Translation
Notes Agents
Keyword Lookups
Categorized Views
Hide-When Fields
Rich Text
Attachments
Domino Data Access Methods
getDominoSession() and getDominoDatabase()
setComputeWithFormEnabled(boolean)
getUserName()
sendDocument(IXml, boolean, boolean) and getDocumentData(String)
Summary
Important Points
Appendix A Setting Up Your Environment
Installing WebSphere Portlet Factory
Configuring WebSphere Portal
Setting Up a New Target Page
Setting Up Access
Configuring Lotus Domino
Start the DIIOP and HTTP Tasks
Enable HTTP Clients to Browse Databases
Creating a Test Database in DB2
Creating a Test Database in SQL Server
Configuring a JDBC Resource
Setting Up a DB2 Database Driver Provider
Setting Up a SQL Server Driver Provider
Configuring the Driver
Configuring a DB2 Data Source
Configuring a SQL Server Data Source
Configuring an Authentication Mechanism
Testing the Data Source
Appendix B Portlet Factory Properties
Properties Files
bowstreet.properties, cluster.properties, and server.properties
jdbcDrivers.properties, pageprocessors.properties, persistentstore.properties
log4j.properties
logging.properties
migrate-profilesets.properties
413
413
414
419
424
428
433
433
434
434
435
435
435
435
436
436
439
439
441
441
443
443
444
444
446
448
451
452
453
453
454
455
456
458
461
461
462
462
462
462
462
Contents
xxv
Using Properties
Domino Server Settings
File Upload Settings
Specifying an Alternate Compiler
Dynamic Class Loading
SOAP and Proxy Access for Web Services
Avoiding Errors Caused by File Length Limitations
The WPF Cache
log4j Logging
Debug Tracing
Event Logging
Server Statistics Logging
Page Automation
464
465
466
466
466
467
468
468
469
470
471
471
472
Glossary
475
Index
493
This page intentionally left blank
Foreword
Building good software applications is hard. Improvements in languages, frameworks, and tools
do make things easier, and there are more of these improvements each year.
But at the same time, the technology landscape that developers live in keeps changing and
getting more complex. Just when you get productive with one set of tools and technology, there’s
something new that you have to adapt to or integrate with. And there’s a perpetual demand for
“more software quicker”—organizations can never get all the software they want as soon as they
want it.
WebSphere® Portlet Factory was created to apply concepts of software automation to help
address this ongoing problem of software development complexity. This software automation
moves the developer up a level, above the level of individual code artifacts. Instead of directly
manipulating elements such as JSP, Java™, JavaScript, and XML files, the developer interacts
with builders in a model, and the builders then generate all the necessary code artifacts in
response to the developer’s high-level instructions.
You can think of builders as encapsulations of software features or design patterns. Each
builder implements one feature of an application, controlled by instructions provided by the
developer in a wizard-like user interface. An application is built by successively adding and modifying features (builders) until the application works as intended. The net effect for developers is
that they can rapidly develop complex applications without having to learn (and remember) all
the underlying technology.
In the past several years working with this technology, we’ve found that developers can
consistently get big productivity gains from this software automation. We’ve seen the technology
adopted by an ever-increasing customer base, first at Bowstreet (where the software was initially
developed), and now at IBM, which acquired Bowstreet in late 2005. At IBM, the technology has
xxvii
xxviii
Foreword
also been adopted by a number of other product groups that build products on top of Portlet Factory technology and take advantage of its software automation. For example, the Lotus®
ActiveInsight Dashboard Framework is built on Portlet Factory and provides a set of builders that
implement high-level design patterns tailored for dashboard-style applications.
We’ve also found that automation makes it possible to quickly add support for new technology, such as integrating new back-end services or generating new user interface technologies.
One example is support for Ajax (Asynchronous Java and XML) user interfaces. Implementing
an Ajax user interface through hand-coding is quite complex and involves coordinated client-side
code (JavaScript) and server-side code. Using builder technology, a small team with Ajax expertise was able to capture their expertise in a set of builders that automate common Ajax patterns
and generate the necessary client and server code. Once the builders were created, those Ajax patterns became easily accessible to any developer using Portlet Factory.
In this book, David Bowley gives a clear “soup-to-nuts” guide to building applications with
Portlet Factory, from creating your first project, to back-end integration, to user interface and
Ajax techniques. Each chapter tackles one aspect of application development, and for each task
David shows you which builders you need and how to use them. In his examples, I think you’ll
see that David has found just the right level of complexity—the examples are simple enough to
easily understand, but not unrealistically simple or trivial.
Portlet Factory development—using builders and models instead of working directly with
code—represents a different development paradigm than with other tools. I hope you find as
much value in this automation paradigm as we have. You can use this book as your guide as you
learn your way around Portlet Factory and get comfortable with this way of working.
Jonathan Booth
Senior Architect
WebSphere Portlet Factory
IBM
Preface
Portlet development can often be arduous and complicated; indeed, the word “rapid” is not normally associated with building portlets. IBM’s award-winning1 WebSphere Portlet Factory
(WPF), however, provides developers with a wizard-based development environment that greatly
expedites the process of building, testing, and deploying portlets. WPF shields developers from
much of the complexity of traditional portlet development, and portlets built using WPF often
require little or no coding—enlarging the potential pool of people who are able to build portlet
applications. Having said this, WPF developers also have the full power of Java 2 Enterprise Edition (J2EE) available to them should they choose to use it, making WPF a flexible (and powerful)
development tool.
This book is about how to use WPF to rapidly build portlets. No previous development
experience is required to understand this book, and anyone with a remote interest in portlet development should find something of interest here. The book is structured to facilitate rapid portlet
development: It is a collection of independent chapters, each walking through the process of creating a portlet while focusing on a particular aspect of WPF. Due to the independent nature of the
chapters (and the nature of portlet development using WPF), you can skip to the chapters that
interest you without needing to read chapter after chapter of abstract theory and/or background
information beforehand. For example, if you want to learn how to build a portlet that displays a
graphical chart, skip to Chapter 10, “Using Charts in Portlets;” if you want to find out how to
work Ajax into your portlets, skip to Chapter 13, “Using Ajax and Dojo.” If you are completely
new to WPF (or portals and portlets) and are looking for some basic information to get you
started in WPF, Chapter 1, “Introduction to WebSphere Portlet Factory,” provides an overview of
1
WebSphere Portlet Factory won the 2006 JavaPro readers’ choice award for “Best Java Enterprise Portal Technology”
(www.fawcette.com/javapro/).
xxix
xxx
Preface
portal terminology, WPF architecture, and the WPF Designer interface. Chapter 1 also walks you
through the process of creating, testing, and deploying a simple Hello World! portlet. Other introductory information is available in Appendix A, which contains some useful information for setting up your WPF development environment, and there is a glossary at the back of the book that
defines common WPF terms.
This book also contains useful tidbits that I have picked up during my time with WPF—the
sort of things developers need to know but normally wouldn’t without a great deal of experimentation and frustration. These snippets of information are highlighted as follows:
TIP
Tips contain useful information that can be employed in WPF, usually with the purpose of
expediting portlet development. Tips are useful, but they are not critically important and can
be skipped if desired.
WARNING
Warnings are important points that usually obviate a common sticking point, and heeding
them may spare you future frustration.
Due to the width of the book’s printed page, some lines of code might be too long to fit on
only one line. If a line of code wraps to another line(s), and it’s not obvious it’s part of the preceding line, we have inserted a code continuation character ([ccc]) at the beginning of the runover
line to indicate that the code is part of the line preceding it. (You should type lines of code that
have this character as one long line without breaking it.) For example,
WebAppAccess remoteWebAppAccess =
➥webAppAccess.getModelInstance(“modelPath/ModelName”, “”,
➥false);
All the examples discussed in this book are available for download from ibmpressbooks.
com/title/9780137134465. More advanced readers can import what they want from these
examples directly into their projects, without necessarily consulting the book itself—although
you are encouraged to follow along with the examples to increase your understanding of WPF.
By walking through each example, you will learn how to build portlets in WPF by actually building them, and not just reading about it; so, by the end of each chapter, you should have a practical
understanding of how to work the discussed features into your own portlets.
Although this book does discuss the theory of WPF portlet development, this information is
discussed in the context of the practical examples in the book, which gives you a more concrete
Preface
xxxi
understanding of how the abstract side of portlet development is applied. Readers unconcerned
with what is going on under the covers can skip the theory sections without adversely affecting
their portlets. Indeed, one of the advantages of using WPF is that you don’t need to learn vast
amounts of theory to begin development—you can start building portlets right away. The focus of
this book, then, is on the practical side of portlet development, with an emphasis on rapidly building portlets with certain functionality—this is not intended as a book of theory. Similarly, given
its short length, this book is not intended to cover every aspect of portlet development—only
those areas that are deemed most useful to portlet developers (and WPF developers, in particular).
I hope you find this book useful and enjoyable to read; I certainly enjoyed writing it. At the
least, I would like this book to go some way toward expediting your portlet development process
and increasing your understanding of WPF. If you have any comments about the content or structure of the book, feel free to drop me a line at [email protected]
This page intentionally left blank
Acknowledgments
I’d like to extend my sincerest appreciation to everyone who supported me during the process of
writing this book. In particular, I’d like to thank John Bergland and Dee Zepf for their early support of the concept, and Jonathan Booth and Louise Simonds for their insightful comments and
advice. I’m eternally grateful to Katherine Bull, my acquisitions editor, for her continual support
and direction throughout the project; and to Kevin Howard, my development editor, who carefully surveyed each chapter and made many helpful suggestions. Thanks also to Carlos Llopart
for the Spanish translations in Chapter 12, and to my sister Kirsten for providing several of the
diagrams that appear in this book.
Of course, a thank you is also due to you, the reader, for purchasing this book and investing
the time to read it. I hope that this book increases your understanding of WebSphere Portlet Factory and provides you with a valuable portlet development resource.
xxxiii
This page intentionally left blank
About the Author
David Bowley is a consultant for e-Centric Innovations, an e-business solution provider in Melbourne, Australia. Over the last nine years, David has worked extensively with IBM technologies,
particularly WebSphere Portal and WebSphere Portlet Factory. David has a bachelor’s degree in
computing and holds numerous I.T. certifications in areas such as WebSphere Portal, WebSphere
Portlet Factory, Java, Lotus Notes, .Net, DB2, Rational, SOA, and RUP. David is a frequent contributor to various technical publications, including The View and Lotus Advisor.
xxxv
This page intentionally left blank
C
H A P T E R
1
Introduction to
WebSphere Portlet
Factory
This chapter explains basic portal concepts (such as what portals and portlets are), and introduces
the fundamentals of portlet development using WebSphere Portlet Factory (WPF). By the end of
the chapter, you will have a working Hello World! portlet and you will understand the basic concepts and techniques required to build, deploy, and test portlets using WPF. This chapter is
intended for WPF newcomers, but those who are interested in brushing up on the basics of WPF
should also find something of interest in it. If you already feel confident using WPF, feel free to
skip ahead to any of the later chapters—you can always come back to this chapter if you need to.
The files used in this chapter are available for download from ibmpressbooks.com/title/
9780137134465 under the Chapter 1 folder (instructions for copying these files into your project
are included in a readme.txt file in the same folder); however, to increase your understanding of
the topics discussed, it is recommended that you create these files yourself by following the
example in this chapter. Doing so will give you a good understanding of the basics of WPF and
position you to tackle some of the other chapters in this book.
The following topics are covered in this chapter:
• What is a portal and what are portlets?
• Portal key benefits
• What is WebSphere Portlet Factory?
• WebSphere Portlet Factory key benefits
• WebSphere Portlet Factory architecture
• Introduction to the WebSphere Portlet Factory Designer
• Building your first portlet
1
2
Chapter 1 Introduction to WebSphere Portlet Factory
What Is a Portal and What Are Portlets?
A portal is a user interface (UI) for people to interact with information and processes, often via
Web pages accessed using a Web browser (such as the portal shown in Figure 1.1). Portals are
provided by a portal server, such as WebSphere Portal Server, in a similar way to how Web pages
are provided by an ordinary Web server. Portals usually aim to streamline business operations by
bringing together information and processes from disparate parts of an organization. For
example, an online bookstore may provide a portal for customers to preview new releases, purchase new books, check the status of any current orders, and even chat with other customers to
share their thoughts on a particular book. Portal functionality is normally provided through one
or more portlets, which are UI components of the portal that serve a particular function (similar
to how a window offers a particular function—or suite of functions—within a Microsoft® Windows® application). In the case of an online bookstore, then, a portal might include a New
Releases portlet and a Forum portlet.
Figure 1.1
An example portal at www.ibm.com/developerworks/.
Portlets are laid out onto various pages within the portal, each page effectively containing a
set of portlets that serves a common purpose. So, a Purchase page might contain portlets for
Portal Key Benefits
3
browsing a catalogue and for buying new books, and a Community page might contain portlets
that facilitate communication with other customers. Portals don’t necessarily have to be customer
facing; for example, an intranet portal might be available only to employees, and an extranet portal might be available only to suppliers. A portal can be anything from a simple front-end to a
backend data source, to a complex collaborative tool integrating several different departments
across an enterprise.
Due to the current bandwidth limitations of the Web, portals are usually kept relatively
simple in comparison with more traditional rich clients (like Microsoft Word, for example). Similarly, portlets are not normally as packed with features as their rich client cousins, and they offer
a more focused service. As a result, portlets normally satisfy some key business requirement or
process (either individually or in conjunction with other portlets). Having said this, portals available through a Web browser can be accessed on a wide variety of platforms, using a number of
different devices, and from anywhere in the world; so, potential exposure to a portal available
through a Web browser is vastly superior to that gained through a rich client. Careful consideration, then, needs to be applied to the portal design process, and a portal should aim to supplement
rich client applications rather than replace them.
Portal Key Benefits
Depending on its exact nature, a portal usually offers one or more of the following key benefits:
• Integration of Business Functions—Probably the most common use for a portal is as
an integrator of business functions, usually across departmental or technological boundaries within an enterprise. For example, a portal might provide portlets for accessing
accounting applications in SAP, reports on a SQL server, and email capabilities from
Lotus Domino®, and it can enable you to use these portlets (and even send information
between them) as if they were all part of the same system. This sort of integration promotes standardization of business processes and discourages the practice of viewing an
organization as a collection of isolated business units.
• Aggregation of Information—Another popular use for a portal is as an aggregator of
information—that is, as a means to bring together information from disparate locations
or data sources into a single interface (again, giving the impression that all of the information is stored in the same place). A portal can save users from needing to use several
different programs to hunt through multiple systems in search of information.
• Collaboration between Users—Portals often provide functionality that facilitates
communication and information sharing across an enterprise (such as document sharing, email, blogs, and project team rooms).
• Accessibility of Information and Services—One of the greatest features of the Web is
how it quickly and easily facilitates communication between people from vastly different locations and backgrounds. As a result, portals often provide an experience tailored
4
Chapter 1 Introduction to WebSphere Portlet Factory
to the context in which they are accessed. For example, a portal may be offered in several different languages, and different markups (such as HTML and WML) may be used
to allow access to the portal using different devices (such as mobile phones, laptops,
PCs, and PDAs).
Portal servers also provide mechanisms to restrict accessibility through customizable
authentication and authorization mechanisms that can leverage an organization’s existing security methods (such as Lightweight Directory Access Protocol [LDAP] and
Lotus Notes® Access Control Lists [ACL]). Putting this into practice, an employee from
a sales department might be able to see only the sales portion of a portal, and an unauthorized person might not be able to log on at all.
• User Interface Personalization—Portals often provide a certain degree of personalization, such as allowing customers to specify the information they see and how it should
be displayed. For example, a portal can provide facilities for end users to choose the
position of portlets on the page or to add and remove portlets as required.
What Is WPF?
WPF is a tool for Eclipse-based Integrated Development Environments (IDE) that facilitates
rapid application development. This is achieved primarily through the use of wizard-based,
reusable components called builders, which can be parameterized based on different contexts and
automatically built into executable code.
Developers can create WPF applications by creating a WPF project in an Eclipse-based
IDE (such as Rational® Software Architect [RSA], Rational Application Developer [RAD], or
Eclipse itself), which has WPF installed into it. After it is installed, WPF adds new design artifacts to the IDE that enable the development of WPF applications. WPF projects can then be
automatically assembled into Web ARrchive (WAR) files (a WAR file is an archive of Java design
artifacts for a Web application) from the IDE and deployed to local or remote application servers
or portal servers.
Note that although you can use any version of WPF to complete the examples in this book,
it is assumed that you are using WPF 6.0.2.
WPF Key Benefits
Some of the key benefits of WPF are:
• Reduced Need for Hand Coding—Developers can build standards-based applications
(such as portlets, Web services, or Java 2 Enterprise Edition [J2EE] applications) with
little or no coding. Given the reduced need to write code, the skill set required to build
complex applications (in J2EE, for example) is drastically reduced.
• Faster Development Times—As WPF development is mostly wizard-based, it is less
error prone than traditional development and can greatly speed up the development
WPF Architecture
5
process. WPF applications are also more flexible than traditional Java applications in
that they are easier to maintain and extend.
• Best Practices—WPF encourages component- and service-based design, and can be
used to enforce architectural patterns and best practices.
• Powerful Capabilities—WPF has a suite of around 160 wizard-like builders that can be
used to automate many common development tasks. These builders have strong integration capabilities with a broad range of backend data sources.
WPF Architecture
At design time, WPF applications consist of three main building blocks: builders, models, and
profiles. Developers work with these elements (along with other design elements like HTML
pages, XML documents, and Java classes) in a special type of project called a WebSphere Portlet
Factory project (see the “Introduction to the Eclipse IDE” sidebar later in this chapter if you are
unfamiliar with projects in Eclipse). Using all of these elements, a WPF mechanism known as the
Factory generation engine can automatically generate executable applications called WebApps.
WPF can also automatically package these WebApps