Front cover
IBM Workplace
Managed Client: ISV
Integration Guide
Develop distributable applications using
existing skills
Integrate Swing, Eclipse RCP, Lotus
Domino, and Web applications
Fully exploit client and server
collaborative components
Philip Monson
Lori Ott
Nishant H. Shah
Shane O’Sullivan
ibm.com/redbooks
Redpaper
International Technical Support Organization
IBM Workplace Managed Client: ISV Integration Guide
March 2006
Note: Before using this information and the product it supports, read the information in “Notices” on
page vii.
First Edition (March 2006)
This edition applies to IBM Workplace Managed Client Releases 2.5.1 and 2.6.
© Copyright International Business Machines Corporation 2006. All rights reserved.
Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule
Contract with IBM Corp.
Contents
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
The team that wrote this Redpaper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .x
Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .x
Chapter 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.1 Important terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.2 Suggested reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1.3 Development environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.2 IBM Workplace Client Technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.3 IBM Workplace Client Technology platform stack. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.4 Integration options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.4.1 Coexistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.4.2 Accommodation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.4.3 Leverage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.4.4 Exploit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.5 Types of ISVs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.6 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
1.7 URLs referenced in this chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Chapter 2. ISVs with Eclipse applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.1.1 What is Eclipse? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.1.2 What is Eclipse RCP? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.1.3 Eclipse RCP, Workplace Client Technology, and Workplace Managed Client . . . 19
2.1.4 Eclipse RCP integration levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.2 Coexist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.3 Accommodate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.3.1 Lightweight integration of Eclipse RCP with Workplace Managed Client . . . . . . . 22
2.3.2 Configuring and provisioning a Workplace Managed Client application . . . . . . . . 24
2.4 Leverage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.4.1 Enabling server-side definition of an applications view layout . . . . . . . . . . . . . . . 30
2.4.2 Manually configuring an application page layout . . . . . . . . . . . . . . . . . . . . . . . . . 31
2.4.3 Configuring an application page layout using Workplace Managed Client Developer
Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
2.4.4 Using an action bar to replace the view toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . 38
2.4.5 Contributing to the Workplace Managed Client menus. . . . . . . . . . . . . . . . . . . . . 39
2.4.6 Adding a Workplace Managed Client search bar . . . . . . . . . . . . . . . . . . . . . . . . . 40
2.4.7 Adding a Workplace Managed Client shelf view . . . . . . . . . . . . . . . . . . . . . . . . . . 43
2.5 Exploit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
2.6 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
2.7 URLs referenced in this chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Chapter 3. ISVs with AWT or Swing applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
© Copyright IBM Corp. 2006. All rights reserved.
iii
3.1.1 What is AWT? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.2 What is Swing? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.3 What is SWT? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.4 Swing integration levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2 Coexist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3 Accommodate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.1 Lightweight integration of a Swing or AWT application with Workplace Managed
Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.2 Creating a new IBM Workplace project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.3 Importing the Swing JAR file into the plug-in project. . . . . . . . . . . . . . . . . . . . . . .
3.3.4 Modifying the shutdown sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.5 Displaying the Swing/AWT application within Workplace Managed Client . . . . . .
3.3.6 Deploying the application to Workplace Collaboration Services server . . . . . . . .
3.4 Leverage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.1 Contributing to the Workplace Managed Client menus. . . . . . . . . . . . . . . . . . . . .
3.4.2 Status bar integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.3 Defining one portlet per view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.4 Converting Swing or AWT controls to SWT . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5 Exploit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7 URLs referenced in this chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
48
48
48
48
49
50
51
51
54
54
55
59
60
60
68
71
74
75
76
76
Chapter 4. ISVs with Web and portal applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
4.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
4.1.1 What are Web and portal applications? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
4.1.2 What is WSRP? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
4.1.3 Web and portal integration levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
4.2 Coexist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
4.3 Accommodate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
4.3.1 Creating a new IBM Workplace project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
4.3.2 Launching the embedded browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
4.3.3 Deploying the application to Workplace Collaboration Services server . . . . . . . . 85
4.3.4 Web Services for Remote Portlets (WSRP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
4.4 Leverage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
4.4.1 HTTP authenticated application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
4.4.2 Adding a Workplace Managed Client search bar . . . . . . . . . . . . . . . . . . . . . . . . . 95
4.4.3 Enhancing WSRP and converting servlet and JSP applications. . . . . . . . . . . . . . 98
4.5 Exploit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
4.6 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
4.7 URLs referenced in this chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Chapter 5. ISVs with Lotus Notes and Domino applications . . . . . . . . . . . . . . . . . . . 103
5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
5.1.1 What is Lotus Domino? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
5.1.2 IBM Lotus Domino Web Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
5.1.3 Domino integration options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
5.1.4 Reparenting Notes applications using the Notes plug-in . . . . . . . . . . . . . . . . . . 106
5.2 Coexist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
5.3 Accommodate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
5.3.1 Running Domino applications in Workplace Managed Client using the Lotus Notes
plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
5.3.2 Launching a Notes/Domino application in its native window using Workplace
Managed Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
iv
IBM Workplace Managed Client: ISV Integration Guide
5.3.3 Displaying a Notes application in an Eclipse View . . . . . . . . . . . . . . . . . . . . . . .
5.4 Leverage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.1 Exposing a Domino application using Web services. . . . . . . . . . . . . . . . . . . . . .
5.4.2 Communicating with Web service from Workplace Managed Client. . . . . . . . . .
5.4.3 Creating a Workplace application project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.4 Creating the user interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.5 Deploying the application to a Workplace Collaboration Services server . . . . . .
5.5 Exploit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.6 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.7 URLs referenced in this chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
113
116
117
122
128
131
136
137
137
137
Chapter 6. Exploiting IBM Workplace Managed Client . . . . . . . . . . . . . . . . . . . . . . . .
6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2 Working with document libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2.1 Creating a document library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2.2 Creating a new document in a document library. . . . . . . . . . . . . . . . . . . . . . . . .
6.2.3 Creating a new folder in a document library . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2.4 Listing the contents of a library or folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3 Messaging and notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.4 Online and offline awareness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.4.1 The Offline API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.4.2 Building offline-aware components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.5 Implementing database support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.5.1 Creating a local database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.5.2 Accessing the database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.5.3 Shutting down the database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.6 Synchronizing client application data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.7 Securing a client application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.7.1 Logging in to the local credential store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.7.2 Creating a password credential for remote server authentication. . . . . . . . . . . .
6.7.3 Logging in to an HTTP-authenticated application . . . . . . . . . . . . . . . . . . . . . . . .
6.7.4 Single sign-on interoperating with the operating system. . . . . . . . . . . . . . . . . . .
6.8 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
139
140
141
142
144
145
146
148
150
152
153
155
156
158
159
160
166
166
167
169
172
175
Appendix A. IBM Workplace Managed Client Version 2.6 . . . . . . . . . . . . . . . . . . . . . .
Provisioning the application from CD or HTTP server . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Platform and custom personalities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Offline and network awareness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Live names component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
File type registry component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Customizing the application look and feel along with branding . . . . . . . . . . . . . . . . . . . . .
Changing the embedded browser’s default Web address . . . . . . . . . . . . . . . . . . . . . . . . .
Workplace Managed Client Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managed provisioning component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using XML Access scripts to create the page and portlet . . . . . . . . . . . . . . . . . . . . . . . . .
Implementing the calendar service API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating an alias password credential . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
177
178
178
180
180
181
182
182
182
183
183
183
184
Appendix B. IBM Workplace 2.5.1 menu IDs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
IBM Workplace menu IDs overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
IBM Workplace menu IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Appendix C. Additional material and feature quick reference . . . . . . . . . . . . . . . . . . 191
Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Contents
v
Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Workplace Managed Client feature quick reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Workplace Client Technology, Micro Edition - Enterprise Offering quick reference. . . . . . 194
Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
vi
IBM Workplace Managed Client: ISV Integration Guide
197
197
197
199
199
Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries. Consult
your local IBM representative for information on the products and services currently available in your area. Any
reference to an IBM product, program, or service is not intended to state or imply that only that IBM product,
program, or service may be used. Any functionally equivalent product, program, or service that does not
infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to
evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document. The
furnishing of this document does not give you any license to these patents. You can send license inquiries, in
writing, to:
IBM Director of Licensing, IBM Corporation, North Castle Drive Armonk, NY 10504-1785 U.S.A.
The following paragraph does not apply to the United Kingdom or any other country where such provisions are
inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of
express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made
to the information herein; these changes will be incorporated in new editions of the publication. IBM may make
improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time
without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any
manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the
materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring
any obligation to you.
Information concerning non-IBM products was obtained from the suppliers of those products, their published
announcements or other publicly available sources. IBM has not tested those products and cannot confirm the
accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the
capabilities of non-IBM products should be addressed to the suppliers of those products.
This information contains examples of data and reports used in daily business operations. To illustrate them
as completely as possible, the examples include the names of individuals, companies, brands, and products.
All of these names are fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrates programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs in
any form without payment to IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating platform for which the sample
programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore,
cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, and
distribute these sample programs in any form without payment to IBM for the purposes of developing, using,
marketing, or distributing application programs conforming to IBM's application programming interfaces.
© Copyright IBM Corp. 2006. All rights reserved.
vii
Trademarks
The following terms are trademarks of the International Business Machines Corporation in the United States,
other countries, or both:
Cloudscape™
DB2®
developerWorks®
Domino Designer®
Domino®
Everyplace®
IBM®
Lotus Notes®
Lotus®
Notes®
PartnerWorld®
Rational®
Redbooks (logo)
Redbooks™
WebSphere®
Workplace Client Technology™
Workplace Managed Client™
Workplace Messaging®
Workplace™
™
The following terms are trademarks of other companies:
Enterprise JavaBeans, EJB, Java, JavaBeans, JavaServer, JavaServer Pages, JDBC, JSP, JVM, J2EE, and all
Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
Microsoft, Windows, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries,
or both.
Linux is a trademark of Linus Torvalds in the United States, other countries, or both.
Other company, product, or service names may be trademarks or service marks of others.
viii
IBM Workplace Managed Client: ISV Integration Guide
Preface
This IBM® Redpaper provides a high-level overview of the integration paths available for
independent software vendors (ISVs) who are considering moving their existing applications
to the IBM Workplace™ Managed Client platform. We begin with a high-level overview of the
four different levels of integration, coexist, accommodate, leverage, and exploit, as well as the
considerations for each level and the benefits involved. The following chapters outline
specific integration paths for four ISV types, IBM Eclipse Rich Client Platform (RCP), Swing,
Web and portal, and IBM Lotus® Notes® applications, including step-by-step actions and
code samples. There is an in-depth chapter about fully exploiting the IBM Workplace
Managed Client™ platform and descriptions of the features in the latest release of IBM
Workplace Managed Client.
The audience for this Redpaper is primarily application developers who have some
experience with Java™. Knowledge of Eclipse is helpful but not necessary.
The team that wrote this Redpaper
This Redpaper was produced by a team of specialists from around the world working at the
International Technical Support Organization, Cambridge Center.
Philip Monson is a Project Leader at the ITSO Lotus Center in Cambridge, MA. Phil has
been with IBM Lotus for 15 years, joining the company when the early versions of Notes were
rolled out for internal use. He has served in management, technical, and consulting roles in
the IT, Sales, and Development organizations.
Lori Ott is an ISV Enablement Specialist with the Lotus IBM Workplace ISV Technical
Enablement Team. Prior to this, she was a Curriculum Developer for the Lotus Education,
Application Development team. She has been involved in computer education for more than
12 years. She has also taught computer science at Phillips Exeter Academy.
Nishant H. Shah is a Software Engineer and currently works with the Workplace Managed
Client platform development team in India Software Labs. He has a bachelor’s degree in
Computer Science from Pune University, India and has about five years of industry
experience in diversified fields of application software development. He has worked
extensively in the areas of Eclipse plug-in development, Java 2 Platform, Enterprise Edition
(J2EE™), Web services, and databases. Additionally, he has worked with IBM ISVs, guiding
the effort to enable ISVs to develop their own custom applications on the Workplace Managed
Client platform.
Shane O’Sullivan is a Software Developer in Dublin, Ireland. He has two years of experience
in IBM WebSphere® and J2EE development and currently works as an open source
researcher in the Dublin Software Lab, Ireland. He received a degree in Computer Systems
and a master of science in Artificial Intelligence and Mobile Robotics from the University of
Limerick, Ireland. His areas of expertise include J2EE technologies, particularly Enterprise
JavaBeans™ (EJB™) and database development on IBM WebSphere Portal, Eclipse
development, and search technologies such as Lucene and Juru. He has written a number of
academic papers in the area of artificial intelligence and mobile robotics, and this is his first
Redpaper.
© Copyright IBM Corp. 2006. All rights reserved.
ix
Thanks to the following people for their contributions to this project:
Craig Wolpert, Senior Software Engineer, IBM Software Group, Lotus
Jo Grant, Senior, Software Engineer, IBM Software Group, Lotus
Jean-Noel Koval, IT Project Manager, IBM Software Group, Lotus
Jane L. Wilson, Knowledge System Architect, IBM Software Group, Lotus
Peter Janzen, Senior Product Manager, IBM Software Group, Lotus
Become a published author
Join us for a two- to six-week residency program! Help write an IBM Redbook dealing with
specific products or solutions, while getting hands-on experience with leading-edge
technologies. You'll team with IBM technical professionals, Business Partners, and/or clients.
Your efforts will help increase product acceptance and customer satisfaction. As a bonus,
you'll develop a network of contacts in IBM development labs, and increase your productivity
and marketability.
Find out more about the residency program, browse the residency index, and apply online at:
ibm.com/redbooks/residencies.html
Comments welcome
Your comments are important to us!
We want our papers to be as helpful as possible. Send us your comments about this
Redpaper or other Redbooks™ in one of the following ways:
򐂰 Use the online Contact us review redbook form found at:
ibm.com/redbooks
򐂰 Send your comments in an email to:
redbook@us.ibm.com
򐂰 Mail your comments to:
IBM Corporation, International Technical Support Organization
Dept. HYTD Mail Station P099
2455 South Road
Poughkeepsie, NY 12601-5400
x
IBM Workplace Managed Client: ISV Integration Guide
1
Chapter 1.
Introduction
IBM Workplace Managed Client extends IBM Workplace servers by delivering rich client
capabilities in a fully integrated collaborative environment for the end user's desktop. It
provides flexibility and portability of client-side applications, combined with server-side control
and cost savings traditionally associated with Web-based computing.
Rich client-side applications enabled by IBM Workplace Managed Client deliver the following
benefits:
򐂰 Rich user experiences with all the functionality of the native desktop client, coupled with
improved manageability and easier deployment
򐂰 Fast user response for time-sensitive and complex processes with real-time data
validation and manipulation
򐂰 A strong security model with a local, encrypted data store that synchronizes to a secure,
server environment, providing a “walled garden” to protect against viruses and other
security risks
򐂰 Flexible integration with desktop productivity applications
򐂰 Support for a variety of operating systems
򐂰 Reusable and consistent user-interface design, where both application content and
transactions can be mixed seamlessly
򐂰 Single client architecture to execute in both online and offline modes (support for
disconnected and connected operations)
In this IBM Redpaper, we show how independent software vendors (ISVs) can increase of the
value of their solutions by integrating their applications with IBM Workplace Managed Client.
With IBM Workplace Managed Client, developers can move from stand-alone applications to
collaborative applications that bring together a number of different systems related to a user’s
role. This move brings new opportunities for developers by enabling them to expose their
products to a new audience interested in the capabilities of the Workplace Managed Client
and leverage their current skills by integrating existing applications and recombining them in
new and interesting ways.
© Copyright IBM Corp. 2006. All rights reserved.
1
Specifically, this paper addresses:
򐂰 Different levels of integration that are available with this technology
򐂰 High-level benefits of the various integration methods
򐂰 Evolution paths for moving through the integration spectrum for ISVs with the following
application types:
– Eclipse Rich Client Platform (RCP)
– Swing and Abstract Windowing Toolkit (AWT)
– Web and portal
– IBM Lotus Notes and Domino®
2
IBM Workplace Managed Client: ISV Integration Guide
1.1 Introduction
IBM Workplace Managed Client is a fully integrated, collaborative, client-side environment
that is centrally managed and deployed. Workplace Managed Client was developed using
IBM Workplace Client Technology™.
“Out of the box,” Workplace Managed Client provides benefits, such as:
򐂰 A comprehensive server-managed desktop
򐂰 Online and offline access to messaging, documents, productivity tools, and data access
򐂰 Online access to instant messaging and Activity Explorer
򐂰 The ability to leverage and extend existing technologies, for example, Lotus Notes and
Domino or traditional applications
򐂰 A rich platform for application development
Figure 1-1 shows the rich user interface for Workplace Managed Client with out-of-the-box
capabilities.
Figure 1-1 Workplace Managed Client out-of-the-box capabilities
With Workplace Managed Client, instead of having to create the infrastructure necessary to
deploy secure, enterprise-ready applications, developers can focus on building the
application itself. Visit the Workplace Managed Client product page for more details at:
http://www.ibm.com/software/workplace/products/product5.nsf/wdocs/workplaceclienttech
Chapter 1. Introduction
3
1.1.1 Important terminology
This paper uses the following terms and applications:
API
Application programming interface.
AWT
Abstract Windowing Toolkit, a Java-based graphic user interface toolkit
used to build interfaces, such as pop-up windows and buttons. AWT uses
native system controls, which can lead to user interface (UI) differences,
for example, if an application is created on Linux® and run on Microsoft®
Windows®, a button might be rendered in a different spot or look
different.
Cloudscape™
IBM Cloudscape is a small-footprint, standards-based Java relational
database (RDB) from IBM that can be tightly embedded into any
Java-based solution. For more information about Cloudscape, see:
http://www.ibm.com/software/data/cloudscape/
Derby
There is no difference in core functionality between Apache Derby and
IBM Cloudscape. Beginning with Version 10, IBM Cloudscape became a
commercial implementation of the database being developed as part of
the Apache Derby Project. Workplace Managed Client uses Derby for its
local data store. For more information, see:
http://db.apache.org/derby/
Eclipse
Eclipse is an open platform for rich client development upon which IBM
Workplace Client Technology is based. For more information about
Eclipse, see:
http://www.eclipse.org
EJB
The Enterprise JavaBeans (EJB) technology is a server-side component
architecture that provides an objective, vendor-neutral framework for
developing enterprise-class distributed applications.
ISV
Independent software vendor.
JFace
The JFace toolkit, a platform-independent API that interoperates with the
Standard Widget Toolkit (SWT), adds the model view controller (MVC)
framework to SWT controls. This library provides a set of components
and helper utilities that simplify many of the common tasks in developing
SWT user interfaces.
OLE
Object Linking and Embedding.
Plug-in
An Eclipse platform feature component. For more information about
Eclipse plug-ins, see:
http://www.eclipse.org/community/plugins.php
RCP
Rich client platform.
RDB
Relational database.
SyncML
An industry initiative to develop and promote a single, common data
synchronization protocol that can be used industry-wide. For more
information about SyncML, see:
http://www.openmobilealliance.org/tech/affiliates/syncml/syncmlindex.html
4
IBM Workplace Managed Client: ISV Integration Guide
Swing
Swing is also a Java-based, graphic user interface (GUI) toolkit. It is used
it to build platform independent GUI widgets, for example, forms and
dialog boxes. Unlike the Abstract Windowing Toolkit (AWT), components
built using Swing are considered lightweight, meaning that instead of
relying on the host system's user interface APIs, Swing mimics them,
which can lead to some UI discrepancies.
SWT
The Standard Widget Toolkit (SWT) provides a platform-independent
Java API that is tightly integrated with the operating system’s native
windowing environment.
TCO
Total cost of ownership.
UI
User interface.
Workplace Managed Client
A fully integrated, collaborative, client-side environment that is centrally
managed and deployed. IBM Workplace Managed Client was developed
using IBM Workplace Client Technology. Visit the Workplace Managed
Client product page at:
http://www.ibm.com/software/workplace/products/product5.nsf/wdocs/workp
laceclienttech
Workplace Collaboration Services
IBM Workplace Collaboration Services provides a wide range of
powerful, completely integrated collaboration capabilities, such as e-mail,
calendar services and scheduling, awareness, instant messaging,
learning, team spaces, Web conferencing, and document and Web
content management.
Workplace Client Technology
IBM Workplace Client Technology is a client-side framework used for the
creation of server-managed business applications.
Workplace Client Technology, Micro Edition - Enterprise Offering
IBM Workplace Client Technology, Micro Edition - Enterprise Offering
provides a runtime environment and integrated middleware components
for extending many enterprise applications to server-managed laptop
computers and desktop systems. For more information about Workplace
Client Technology, Micro Edition - Enterprise Offering, see:
http://www.ibm.com/software/wireless/wctme_eo/
WSRP
Oasis Web Services for Remote Portlets (WSRP) is a Web services
standard that enables the plug-and-play of portals, other intermediary
Web applications that aggregate content, and applications from
disparate sources. For more information about WSRP, see:
http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp
1.1.2 Suggested reading
IBM Workplace Managed Client consists of and builds on several IBM products. Developers
do not need to be experts in Eclipse, Java, or the Workplace API. However, familiarity with
these topics and developing greater skills in these topics will help to more fully use the depth
of the product.
Table 1-1 on page 6 suggests reading and tutorials that you can use to better acquaint
yourself with different aspects of Workplace Managed Client.
Chapter 1. Introduction
5
Table 1-1 Recommended reading
Title
URL
IBM Workplace Managed Client Developer
Toolkit
http://alphaworks.ibm.com/tech/wmctoolkit
IBM Workplace Software Development Kit
(formerly IBM Workplace Collaboration Services
API Toolkit)
http://www.ibm.com/software/workplace/prod
ucts/product5.nsf/wdocs/2c8a33e47eef8d0585
256ee60054ddf2
Creating an application with the IBM Workplace
Managed Client Developer Toolkit
http://www.ibm.com/developerworks/workplac
e/library/wmc-toolkit-basic/?ca=dnp-442
IBM Workplace
http://www.ibm.com/developerworks/lotus/li
brary/ls-ibmworkplace/index.html
Eclipse Rich Client Tutorial, Part 1
http://www.eclipse.org/articles/Article-RC
P-1/tutorial1.html
IBM Workplace Client Technology is built on the Eclipse platform, which has its own user
interface guidelines that should be followed in addition to these guidelines. The Eclipse User
Interface Guidelines are available at:
http://www.eclipse.org/articles/Article-UI-Guidelines/Contents.html
IBM Workplace Client Technology user interface design and interaction guidelines are
intended for designers and developers who use IBM Workplace Client Technology to build
applications for IBM Workplace Managed Client. The guidelines provide information and
examples of the common user interface components used to build the user interface of the
Managed Client products provided with IBM Workplace Software Development Kit (formerly
IBM Workplace Collaboration Services API Toolkit).
To find more information about the IBM Workplace Client Technology user interface design
and interaction guidelines, go to:
http://www.ibm.com/developerworks/workplace/documentation/collaborationservices/
1.1.3 Development environment
The examples and applications referred to in this paper were developed in the Redbooks lab
environment using:
򐂰 Eclipse 3.0.2 and 3.1
򐂰 IBM Workplace Managed Client Developer Toolkit 2.5.1
Note: Chapter 5, “ISVs with Lotus Notes and Domino applications” on page 103 uses
the Workplace Managed Client Developer’s Toolkit 2.6.
򐂰 IBM Lotus Domino Designer® 7
1.2 IBM Workplace Client Technology
IBM Workplace Client Technology is a framework for developing, deploying, and maintaining
server-managed client software.
With Workplace Client Technology, applications can be developed that combine the benefits
of a rich user experience with the ease of deployment and manageability of browser-based
6
IBM Workplace Managed Client: ISV Integration Guide
applications. Workplace Client Technology follows a components-based assembly model to
build rich, reusable client applications that IT administrators can centrally and securely deliver
and manage.
Some examples of Workplace Client Technology include:
򐂰 A secure, Java relational database (RDB) data store
򐂰 An Eclipse-based Java rich client framework
򐂰 The ability to read layouts and download applications and components from a portal
server
IBM is actively engaging ISVs to help shape additional tools and APIs for this platform to be
published with future releases of this technology. This paper is designed to assist all ISVs that
are interested in learning how they will be able to integrate their products with IBM Workplace
Managed Client, extend it, or build applications of their own that use this new platform.
Note: IBM Workplace Client Technology, Micro Edition - Enterprise Offering V5.8 is a
significant addition to the IBM Workplace family of products. Workplace Client Technology,
Micro Edition - Enterprise Offering provides a runtime environment and integrated
middleware components for extending many enterprise applications to server-managed
laptop computers and desktop systems.
IBM Workplace Managed Client supports running the Enterprise Offering runtime
environment on the IBM Workplace Managed Client platform, which means that ISVs can
run Enterprise Offering applications on the IBM Workplace Managed Client platform. See
Appendix C, “Additional material and feature quick reference” on page 191 for a Workplace
Client Technology, Micro Edition - Enterprise Offering feature list.
For additional information about Workplace Client Technology, Micro Edition - Enterprise
Offering, refer to:
http://www.ibm.com/software/wireless/wctme_eo/
1.3 IBM Workplace Client Technology platform stack
IBM Workplace Client Technology is fundamentally built as extensions to the Eclipse tools
platform. On top of this core Eclipse platform, IBM Workplace Client Technology then adds
extra infrastructure services, such as a managed store with security features, accounts, and a
unified approach to people and integration with Workplace Collaboration Services (based on
IBM WebSphere Portal). IBM Workplace Client Technology also provides a server-based
management system for client updates and administration that will leverage the work done for
pervasive device management.
Along with all of this, IBM is building generic parts for Web Services for Remote Portlets
(WSRP), document editing, and navigation.
Client-side dynamic aggregation is tied closely to the portal aggregation model. Portal pages
become client pages and portlets identify which view to display. Portlets will also be able to
pass configuration information from the server to the client. With the generic WSRP part,
back-end portlets can even be directly referenced.
Figure 1-2 on page 8 is a graphic representation of the Workplace Client Technology platform
model.
Chapter 1. Introduction
7
Note: This section introduces Web Services for Remote Portlets (WSRP). The WSRP
Technology Preview 2.5.1 is part of the IBM Workplace Managed Client 2.5.1 Technology
Preview package. IBM Business Partners will be able to obtain the IBM Workplace
Managed Client 2.5.1 Technology Preview package through the IBM Software Access
Catalog on PartnerWorld® at:
http://www.developer.ibm.com/isv/welcome/guide/value.htm
Clients who want to obtain the IBM Workplace Managed Client 2.5.1 Technology Preview
package should contact their IBM Sales representative.
We include the complete instructions and details in the WSRP Technology Preview
described in 4.3.4, “Web Services for Remote Portlets (WSRP)” on page 85.
Figure 1-2 IBM Workplace Client Technology platform stack
The core platform is based on Eclipse technology, which provides the Java runtime
environment for general desktop applications, an application user interface, and a flexible
architecture that is easily extended and supports multiple operating systems.
Add-on generic contributions are being developed through a cooperative effort between IBM
and Eclipse.
IBM extension services consists of value-added capabilities, such as synchronization,
credential store for security, single-sign-on for user convenience and simplified access
management, and more. WebSphere Portal technology is used as the aggregation
framework.
8
IBM Workplace Managed Client: ISV Integration Guide
The IBM user interface layer provides reusable components, such as a rich text editor and
live names, that tie into extension services and can be used in applications built either by IBM
or other providers.
IBM Workplace shared application components comprise the Workplace collaboration
platform and can be assembled to create products such as IBM Workplace Messaging® and
IBM Workplace Documents and other applications that third parties can build.
Throughout this paper, we use the terms Workplace Managed Client and Workplace Client
Technology; these terms are not interchangeable:
򐂰 Workplace Client Technology is the framework upon which products and applications are
built and managed.
򐂰 Workplace Managed Client is a product that the end user uses to access the built-in and
custom ISV applications.
1.4 Integration options
Many corporations have existing applications that have suited their business needs, or at
least provided basic functionality for their business processes. However, as technology
increases and the business needs change or other companies and processes are acquired,
some of the existing applications might become too cumbersome to manage. Workplace
Managed Client provides a medium that allows multiple disparate applications to coexist. The
level of this coexistence is determined by the application developer and can range from
simple coexistence to a full-fledged conversion to the Workplace Managed Client
programming model.
Trade-offs must be made between how quickly an application can be re-tooled and how well
it can be integrated with Workplace Managed Client. A developer or organization can follow a
path of integration in Workplace Client Technology that balances the amount of time and
effort needed to achieve the desired level of integration. Immediate benefits can be gained
quickly though minimal effort. Additional benefits can be gained through further efforts.
The four different integration levels are:
򐂰 Coexist
򐂰 Accommodate
򐂰 Leverage
򐂰 Exploit
Table 1-2 illustrates some examples of the spectrum of integration option benefits and the
application skill level needed to integrate with Workplace Managed Client.
Table 1-2 Integration benefits and programming levels
Coexist
Accommodate
Leverage
Exploit
Programming skill level:
򐂰 None.
Programming skill level:
򐂰 Java: Proficient.
򐂰 Eclipse: Minimal.
Programming skill level:
򐂰 Java: Proficient.
򐂰 Eclipse: Proficient.
Programming skill level:
򐂰 Java: Proficient.
򐂰 Eclipse: Proficient.
򐂰 Workplace Client
Technology/Portal: API
knowledge required.
Chapter 1. Introduction
9
Coexist
Accommodate
Leverage
Exploit
Application runs outside
Workplace Managed
Client.
Application can be
launched from within
Workplace Managed
Client.
Leverages client-side
functionalities, such as the
search bar, action bar,
credential store, and
menus.
Leverages client- and
server-side functionalities,
such as the online/offline
awareness, secure data
access, document library,
synchronization, and
notification.
Data copied into a
Workplace Managed Client
document can be e-mailed
or stored in the secure
document storage facility.
Updates to the application
can be automatically
provisioned from the host to
the client.
Traditional stand-alone
application executables fall
into this category.
It is also worth mentioning that all of these options are a spectrum of non-exclusive states, so
an ISV can enter at any point in this spectrum and then choose to address other parts of the
spectrum over time. It will not be uncommon for ISVs to occupy several points on the
spectrum simultaneously. This flexibility should be assumed so that ISVs can focus on
integration levels that are best optimized to the business scenarios in which they want to
engage without artificially having to start integrating only at one point in the spectrum.
Note: All examples in this paper assume that the com.ibm.workplace.personality
personality is used as the default personality to run Workplace Managed Client. The IBM
Workplace personality is the default personality applied to a provisioned application if no
other personality is specified. It builds the perspective used by the application based on the
Rich Client Platform Markup Language (RCPML) it retrieves from the server.
To use the IBM Workplace personality:
1. When initially building the application plug-ins, concentrate on the functionality of the
application, not its look and feel. The personality defines the look and feel of the
application.
2. When testing the application in the IDE, specify -personality
com.ibm.workplace.personality as a program argument to make the application run
within an IBM Workplace Managed Client runtime environment.
For more information about personalities in the Workplace Managed Client, see
Appendix A, “IBM Workplace Managed Client Version 2.6” on page 177 and the
documentation that comes with the IBM Workplace Client Technology API Toolkit.
1.4.1 Coexistence
The simplest level of integration is coexistence. This requires no changes at the code level.
The application remains installed and runs the same as it always has. However, after
Workplace Client Technology has been added to the client's environment, how the
application is used can be changed.
Benefits of coexistence
Benefits of coexistence include:
򐂰 Minimal-to-no development effort
򐂰 Certified to run side-by-side
10
IBM Workplace Managed Client: ISV Integration Guide
At this level, ISVs that have existing applications might find significant value simply in the
side-by-side execution of their applications with IBM Workplace Managed Client.
This is equivalent to the current desktop computing environment where basic interaction is
defined by the operating system functionality, such as the ability to drag and drop documents
or application shortcuts, cut, copy, and paste data, and create file viewer associations. These
basic mechanisms for integration might be sufficient for some ISVs to tap into significant
value simply by certifying applications and encouraging side-by-side execution without other
specific integration features.
The other three types of integration offer progressively tighter integration options.
1.4.2 Accommodation
At the accommodate integration level, ISVs reconfigure their applications to use mechanisms
such as provisioning, modifying the shut-down sequence and reparenting, as well as
interoperability mechanisms such as WSRP or OLE. These mechanisms can help achieve
simple, “on-the-glass” integration, for example, displaying within a frame of IBM Workplace
Client Technology.
Benefits of accommodation
Benefits of accommodation include:
򐂰 Simple, but effective blended user experience
򐂰 Ability to access a secure replicated file store through round-trip editing
򐂰 Component provisioning by policy
At the accommodate level of integration, components can begin to share visual context such
as language or font settings with other application components. In addition, two key aspects
of Workplace Managed Client can be leveraged, provisioning and a secure, synchronized
data store. Overall, an accommodation approach can be an excellent first step to a
customer-driven exploration of deeper integration directions.
1.4.3 Leverage
The next level of integration is to leverage more deeply the capabilities of the platform
services that are available in IBM Workplace Client Technology. For example, an ISV could
leverage the provisioning frameworks, install facilities, and access the extensible
synchronization management facilities of IBM Workplace Client Technology by packaging an
external program with a wrapper plug-in. In this case, only the wrapper parts have to be
written to the Workplace programming model in order to take advantage of significant new
capabilities.
It should be noted that Java wrappers can be readily applied to blend in a user interface (UI)
component that originally was not written in Java, enabling integration options that can
appear nearly seamless.
Benefits of leverage
A key benefit from even this level of integration is that the Workplace role-based policies
apply immediately, even to the simplest wrapper plug-in. Benefits include:
򐂰 Platform-independent UI integration approach
򐂰 Component provisioning by policy
򐂰 Client management frameworks (search, synchronization, and storage)
Chapter 1. Introduction
11
1.4.4 Exploit
Complete seamless integration occurs as an ISV chooses to write plug-ins that are more than
simple wrappers, where most or even all of the code is structured to the Workplace
programming model in order to exploit the client technologies fully. By employing the APIs
and available models, an ISV can write a matched set of portlets, plug-ins, EJB services, and
data source definitions that take full advantage of all attributes of IBM Workplace Client
Technology infrastructure.
Benefits of exploit
Application components that are written in this manner gain several benefits, such as the
ability to dynamically share capabilities (such as online awareness), participate in spanning
services (such as synchronization), and improved security (such as the credential store).
In most cases, ISVs that have existing applications or components are expected to gradually
extend into this space as they match needs and requirements to the appropriate
programming model constructs. Benefits include:
򐂰 Full total cost of ownership (TCO) improvement realizations
򐂰 Exploitation of rich repository spanning services, UI components, and business
components
We provide a thorough examination of the exploit model in Chapter 6, “Exploiting IBM
Workplace Managed Client” on page 139.
1.5 Types of ISVs
IBM has a large and diverse ISV community, and each particular ISV will be looking at
integration options with IBM Workplace Client Technology from the unique perspective of its
own specific business context, development skills, and existing application assets. For
example, an ISV that builds Swing-based Java applications will approach IBM Workplace
Client Technology very differently from an ISV that builds Lotus Notes NSF-based
applications.
Although there are many more ISV types than are represented in this paper, the examples
used are designed to provide a road map and not be the only guide.
This paper addresses the integration options for the following types of ISVs:
򐂰
򐂰
򐂰
򐂰
Eclipse applications
Swing-based Java applications
Portal and Web applications
Notes and Domino applications
In addition, Table 1-3 on page 13 shows an overview of these integration options and several
other types of ISV integration:
򐂰 Stand-alone desktop applications
򐂰 Classic client/server applications
򐂰 Mobile applications
12
IBM Workplace Managed Client: ISV Integration Guide
Table 1-3 Examples of different ISV type integration options
Application
type
Examples of
applications that
can coexist
Accomodate
Leverage
Exploit
Eclipse RCP
IBM Rational
Application
Developer
Package plug-ins to
provision from IBM
Workplace/Portal
server.
Store plug-in related
files to secure,
synchronized client
storage.
Develop native
Workplace Managed
Client applications using
plug-ins that take
advantage of Workplace
Client Technology
infrastructure, for
example, local and
remote data access (call
Web services).
Any existing
stand-alone
Eclipse based
application
Swing
Notepad
Launch Eclipse
applications from within
Workplace Managed
Client.
Launch Swing
application from within
Workplace Managed
Client.
Wrap Swing application
as a Workplace
Managed Client
application.
Portal and
Web
Any existing HTML
file
Create a simple launch
application using the
embedded browser or
Web Services for
Remote Portlets
(WSRP).
Use Workplace
Managed Client UI
features, such as file
menus, search, and
status bars.
Optionally, replace
some Swing or AWT UI
controls with SWT.
Enable single sign-on
using the Workplace
Client Technology
credential store.
Develop native
Workplace Managed
Client applications using
plug-ins that take
advantage of Workplace
Client Technology
infrastructure, for
example, document
libraries, mail, single
sign-on, and secure
data stores that
Workplace Managed
Client provides.
Write Eclipse plug-ins
that make remote calls
to the same back-end
services to which
existing portlets make
calls.
Enable HTTP
authentication.
Provisioning.
Notes/Domino
Any existing
Notes/Domino
application
Embed NSFs using a
Notes 7.0 plug-in.
Provisioning.
Stand-alone
Microsoft Office
OS registered file
extension handler to
open files in
WebSphere Portal
Document Manager
through a temp file on
disk.
Wrap Domino Web
applications in portlets,
then display using
WSRP plug-in.
Export Notes agents as
Eclipse actions.
Use Workplace
Managed Client
extensions to wrap OLE
control in custom Ecipse
view to allow for direct
access to repository.
Eclipse plug-in
extended to publish
more attributes of the
wrapped program.
Notification.
Launch as an OLE
embedded object from
within Workplace
Managed Client.
Provisioning.
Chapter 1. Introduction
13
Application
type
Examples of
applications that
can coexist
Accomodate
Leverage
Exploit
Client/server
SAP
Seibel
Launch as an OLE
embedded object from
within Workplace
Managed Client.
Wrap client binaries in
Eclipse plug-ins to
support server-side
deployment.
Developing native
Workplace Managed
Client applications using
plug-ins that take
advantage of Workplace
Client Technology
infrastructure, for
example,
synchronization and
notification.
Publish extension points
so that other
applications can
contribute or leverage
application functionality.
Mobile
For more information, refer to: http://www-306.ibm.com/software/wireless/wctme_eo/
1.6 Summary
By the end of this paper, ISVs should have a clearer understanding of the different integration
paths that are available to them, as well as strategies for adapting these options. The
remaining chapters provide more technical details about ISVs with the following applications
and information about exploiting IBM Workplace Managed Client:
򐂰 Eclipse Rich Client Platform (RCP)
򐂰 Swing and Abstract Windowing Toolkit (AWT)
򐂰 Web and portal
򐂰 IBM Lotus Notes and Domino
1.7 URLs referenced in this chapter
Table 1-4 lists the URLs referred to in this chapter.
Table 1-4 List of URLs referenced in this chapter
14
What
Where
Information about Cloudscape
http://www.ibm.com/software/data/cloudscape/
Information about Apache Derby
http://db.apache.org/derby/
Eclipse Foundation
http://www.eclipse.org
Information about Eclipse plug-ins
http://www.eclipse.org/community/plugins.php
Information about SyncML
http://www.openmobilealliance.org/tech/affiliates
/syncml/syncmlindex.html
Information about WSRP
http://www.oasis-open.org/committees/tc_home.php?
wg_abbrev=wsrp
IBM Workplace Managed Client: ISV Integration Guide
What
Where
IBM Workplace Managed Client
Developer Toolkit information
http://alphaworks.ibm.com/tech/wmctoolkit
IBM Workplace Managed Client
Developer Toolkit (formerly IBM
Workplace Collaboration Services API
Toolkit)
http://www.lotus.com/ldd/lwpapi
Creating an application with the IBM
Workplace Managed Client Developer
Toolkit
http://www.ibm.com/developerworks/workplace/libra
ry/wmc-toolkit-basic/?ca=dnp-442
What you need to know about IBM
Workplace: An introduction for
developers
http://www.ibm.com/developerworks/lotus/library/l
s-ibmworkplace/index.html
Eclipse Rich Client Tutorial, Part 1
http://www.eclipse.org/articles/Article-RCP-1/tut
orial1.html
The Eclipse User Interface Guidelines
http://www.eclipse.org/articles/Article-UI-Guidel
ines/Contents.html
Workplace Collaboration Services
documentation
http://www.ibm.com/developerworks/workplace/docum
entation/collaborationservices/
Additional information about Workplace
Client Technology, Micro Edition Enterprise Offering
http://www.ibm.com/software/wireless/wctme_eo/
Chapter 1. Introduction
15
16
IBM Workplace Managed Client: ISV Integration Guide
2
Chapter 2.
ISVs with Eclipse applications
This chapter introduces the steps an ISV should take to integrate an Eclipse Rich Client
Platform (RCP) application into the IBM Workplace Client Technology framework. Even
without the time or the resources to do a full Eclipse RCP conversion, ISVs can quickly gain
benefits from the central management and security that Workplace Client Technology offers.
ISVs that build and sell Eclipse-based applications can approach the integration spectrum
using methods discussed in this chapter. These include:
򐂰 Packaging plug-ins to activate an IBM Workplace Managed Client configuration, versus a
generic Eclipse configuration
򐂰 Deploying and provisioning Workplace Managed Client applications
򐂰 Integrating with the Workplace Managed Client framework
򐂰 Fully exploiting Workplace Managed Client features such as security, storage, and
synchronization
© Copyright IBM Corp. 2006. All rights reserved.
17
2.1 Overview
Benefits for migrating an Eclipse RCP application to Workplace Client Technology include:
򐂰 Opportunity for lower total cost of ownership (TCO) because the application is
server-managed and provisioned
򐂰 Integration with other applications provided by the application switcher
򐂰 Leveraging the features and functionality provided by Workplace Client Technology such
as its credential store, offline manager, sync manager, and locally encrypted databases
To simulate the conditions of many ISV experiences, we base this chapter on the following
assumptions:
򐂰 The application is included in a series of plug-ins and feature projects.
򐂰 The application source code is available.
This chapter uses the example of a van delivery management application, referred to as
Delivery Manager. Delivery Manager keeps track of warehouses, stores, vans, the orders
from the stores to the warehouses, and stock as it is delivered both to the warehouse and by
van to the stores. In this chapter, you will see how this application changes as it is moved
through the various stages of application integration.
2.1.1 What is Eclipse?
“Eclipse is an open source community whose projects are focused on providing an extensible
development platform and application frameworks for building software. Eclipse provides
extensible tools and frameworks that span the software development life cycle, including
support for modeling, language development environments for Java, C/C++ and others,
testing and performance, business intelligence, rich client applications and embedded
development. A large, vibrant ecosystem of major technology vendors, innovative start-ups,
universities and research institutions and individuals extend, complement and support the
Eclipse Platform.”1
Figure 2-1 shows a high-level outline of the Eclipse architecture.
Figure 2-1 Eclipse architecture
1
18
From http://www.eclipse.org
IBM Workplace Managed Client: ISV Integration Guide
Note: For more information about Eclipse, see:
򐂰 http://www.eclipse.org
򐂰 http://www.eclipsecon.org
򐂰 http://www.ibm.com/developerworks/opensource/top-projects/eclipse-starthere.ht
ml?ca=dgr-lnxw09LearnEclipse
2.1.2 What is Eclipse RCP?
The Eclipse Rich Client Platform (RCP) is a set of plug-ins that can be used to build a rich
client application; for example, both the Eclipse Integrated Design Environment (IDE) and
Workplace Managed Client are rich client applications.
For more information regarding Eclipse and the Eclipse RCP, see the following sites:
򐂰 The Eclipse Foundation home page:
http://www.eclipse.org/
򐂰 The Eclipse Foundation Rich Client Platform home page:
http://wiki.eclipse.org/index.php/Rich_Client_Platform
򐂰 The IBM developerWorks® article, Eclipse's Rich Client Platform, Part 1: Getting started:
http://www.ibm.com/developerworks/edu/os-dw-os-rcp1-i.html
2.1.3 Eclipse RCP, Workplace Client Technology, and Workplace Managed
Client
To enable a viable client application for real-world, enterprise-level use, additional
components are required beyond what the Eclipse RCP provides.
These components can include, but are not limited to, a platform launcher, rich text editor,
page switcher, and multiple personalities. These types of components and others are
available through Workplace Managed Client. Workplace Managed Client is built on top of
Workplace Client Technology.
Because Workplace Client Technology is built on top of the Eclipse platform, the process of
integrating an Eclipse RCP application with Workplace Managed Client is relatively
straightforward. We explain Workplace Client Technology in detail in Chapter 1, “Introduction”
on page 1.
Important: Do not confuse Eclipse RCP with Workplace Client Technology RCP:
򐂰 Eclipse RCP offers the foundation for creating a rich, Eclipse-based application.
򐂰 Workplace Client Technology RCP provides a comprehensive platform on which
Workplace Managed Client applications are built and executed.
Workplace Managed Client personalities allow the managed coexistence of several
Eclipse-based applications in a single window. For more information, see “Platform and
custom personalities” on page 178.
Chapter 2. ISVs with Eclipse applications
19
2.1.4 Eclipse RCP integration levels
As stated in the introduction, there are trade-offs involved when deciding how integrated an
existing Eclipse RCP application should be with Workplace Managed Client. Table 2-1
provides an illustration.
Table 2-1 Example of various integration levels for Eclipse RCP applications
Increase of time, effort, and synergy →
Coexist
Accommodate
Leverage
Exploit
Copy and paste data into a
document stored in the
Workplace Managed Client
document library.
Package plug-ins to
provision from IBM
Workplace/Portal server.
Store plug-in related files to
secure, synchronized client
storage.
Write plug-ins that take
advantage of Workplace
Client Technology
infrastructure, for example,
local and remote data
access (call Web services).
2.2 Coexist
The simplest level of integration is coexistence. This requires no changes at the code level.
The application remains installed and runs on the client’s desktop just as it always has.
For example, the Delivery Manager application can be extended to create and generate a
warehouse status report. The report's content can be copied and pasted manually into the
document library in Workplace Managed Client. This makes use of the secure and central
data management of Workplace Client Technology to store data from the application. This
stored data, or references to it, can be e-mailed to other people or added to an activity.
Figure 2-2 on page 21 shows an example of running the Delivery Manager alongside
Workplace Managed Client.
For more information, refer to 1.4.1, “Coexistence” on page 10.
20
IBM Workplace Managed Client: ISV Integration Guide
Figure 2-2 Example of running the Delivery Manager alongside Workplace Managed Client
2.3 Accommodate
At the accommodate integration level, the application can be enhanced or modified to use
mechanisms such as provisioning, the shut-down sequence, and reparenting. These
mechanisms can help achieve simple, “on-the-glass” integration, such as displaying within a
frame of IBM Workplace Client Technology. The benefit to this level of integration is that
components begin to share visual context such as language or font settings with other
application components. Overall, an accommodation approach can be an excellent first step
to a customer-driven exploration of deeper integration directions.
For more information, refer to 1.4.2, “Accommodation” on page 11.
Workplace Managed Client and the Eclipse RCP
Workplace Managed Client uses Eclipse RCP standards to organize code units into plug-ins
and features. A plug-in is the smallest unit of Eclipse that can be developed and delivered
separately. All Eclipse-based applications consist of plug-ins that provide functionality to that
application. Plug-ins are grouped into features. A feature is the smallest unit of separately
downloadable and installable functionality. Features are a requirement of Workplace
Managed Client, but not Eclipse RCP. If the plug-ins of an Eclipse RCP application are not
Chapter 2. ISVs with Eclipse applications
21
organized into features, one or more features must be created and the plug-ins moved in to
them. Fortunately, features are a minor construct; it takes very little effort to create a feature
and add plug-ins to it.
Both Workplace Managed Client and the Eclipse RCP use views to organize user interface
(UI) deployment. In an Eclipse RCP application, views are organized into pages of UI code,
each known as a perspective. In Workplace Managed Client, views are first registered as
portlets in the administration tool. See 2.3.2, “Configuring and provisioning a Workplace
Managed Client application” on page 24 for a detailed explanation of this.
Behind the scenes, Workplace Managed Client uses dynamic perspectives to create page
layouts in the client. A complete integration of an Eclipse RCP application would separate all
of the Eclipse RCP views and manage them as individual portlets in Workplace Managed
Client.
2.3.1 Lightweight integration of Eclipse RCP with Workplace Managed Client
For the purposes of accommodating an existing application, there is a quicker, less
time-consuming way to bring Eclipse RCP perspectives directly into Workplace Managed
Client. If the code to select an Eclipse-based perspective is invoked, Workplace Managed
Client will show the content of that perspective. However, views can only be managed
through Workplace Managed Client. In order to leverage an Eclipse perspective in a
Workplace Client Technology view, you must create a Workplace Managed Client view whose
sole purpose is to switch to an Eclipse perspective.
The most efficient approach is to wrap the Eclipse view code in Example 2-1 in a separate
plug-in. Subsequently, create a single portlet for the view on the Workplace Collaboration
Services server and place it on a page. See the 2.3.2, “Configuring and provisioning a
Workplace Managed Client application” on page 24 for information about how this is
achieved.
Example 2-1 Eclipse view code to switch to a perspective
package com.ibm.wcttool.sldlv2.views;
import com.ibm.wcttool.sldlv1.DMPerspective;
//...
public class SwitcherView extends ViewPart {
public SwitcherView() {
}
public void createPartControl(Composite parent) {
}
public void setFocus() {
try {
getViewSite().getWorkbenchWindow().getWorkbench()
.showPerspective(DMPerspective.ID, getViewSite().getWorkbenchWindow());
} catch (WorkbenchException e1) {
e1.printStackTrace();
}
}
}
When the client provisions from the server, it brings down the feature with the plug-in in it.
When the page is selected, it places this view on the window. This forces the setFocus()
function to be called, which switches the perspective to the one defined by the application.
Figure 2-3 on page 23 shows an example integration.
22
IBM Workplace Managed Client: ISV Integration Guide
Figure 2-3 Delivery Manager integrated with the Workplace Managed Client through a simple wrapper plug-in
With very little work, some of the most powerful mechanisms in Workplace Managed Client,
provisioning and management, have been leveraged, instantly reducing the total cost of
ownership and maintenance effort required. Rather than using a traditional installation or
upgrade method to provide this application to users, such as distributing a disc or a
user-initiated download, Workplace Managed Client provides a low-touch mechanism for
deciding who gets this application or update.
Note: Eclipse RCP provides its own update mechanism, but ISVs must perform a
considerable amount of work to integrate their applications with this system. Much of this
work involves writing infrastructure code, rather than focusing on writing the unique code
that adds business value.
By using Workplace Client Technology provisioning, ISVs can focus more on the business
application and not concern themselves with infrastructure considerations. Additionally,
Workplace Client Technology provisioning is “enterprise capable,” that is, Workplace Client
Technology supports role-based provisioning as explained in the following section.
Chapter 2. ISVs with Eclipse applications
23
2.3.2 Configuring and provisioning a Workplace Managed Client application
Applications on the Workplace Managed Client differ from stand-alone applications in one
very significant regard. Although they execute locally on a client’s desktop, they are centrally
managed by a remote Workplace Collaboration Services server. This enables an
administrator to control a number of factors:
򐂰 Application layout and configuration
򐂰 Centralized rollout of new applications and updates
Each Workplace Managed Client application consists of client-side and server-side
components. The client-side components are arranged in terms of views and perspectives,
while the server-side components are arranged using portlets and pages.
A portlet is a collection of code that runs on the server and is served up through a portal. The
portlet outputs Hypertext Markup Language (HTML) code that renders a managed view in a
Web client, also referred to as a thin portlet. In addition to registering these thin portlets,
Workplace Client Technology adds the capability to register thick portlets. Thick portlets are
Eclipse views that can be downloaded and rendered by the rich client.
A page is a collection of portlets to be grouped together with a specified layout. It provides
similar functionality to that of an Eclipse perspective.
Note: The steps listed in the following sections describing application deployment are
manual, require some effort on the part of the developer, and do not cover every possible
facet of the deployment process. For a fully detailed tutorial, see the paper by Nishant
Shah, Configuring and deploying a rich client application on IBM Workplace Collaboration
Services server, on developerWorks:
http://www.ibm.com/developerworks/workplace/library/deploy-client-application-workpla
ce/index.html
It is possible to achieve the same results less laboriously using the Workplace Managed
Client Developer Toolkit, available at:
http://www.alphaworks.ibm.com/tech/wmctoolkit
For a detailed tutorial about using the toolkit, see:
http://www.ibm.com/developerworks/workplace/library/wmc-toolkit-basic
Application layout and configuration
When an existing Eclipse RCP application is being accommodated within Workplace
Managed Client, it is necessary to rework the application's layout. Rather than using a
perspective, a page must be created on the Workplace Collaboration Services server that
launches the application. This page represents the application’s Eclipse perspective and
contains a layout that specifies the arrangement of the views on the client.
Follow these steps in order to create a page that launches an Eclipse application:
1. Wrap each Eclipse view as a thick portlet.
2. Assign access permissions to the portlet.
3. Create a page in Workplace Collaboration Services.
4. Select a layout for the page.
5. Add portlets to the page.
24
IBM Workplace Managed Client: ISV Integration Guide
Wrapping an Eclipse view as a thick portlet
The first step in accommodating an Eclipse RCP application to Workplace Managed Client is
to create a thick portlet for each view. Follow these steps to create a portlet:
1. Log in to the Workplace server as an administrator using the following URL:
http://<http_server>/lwp/myworkplace
2. Click Administration → Portlets → Manage Portlets → Search for Portlets. See
Figure 2-4.
Note: Administrator access is required in order to create and configure portlets and
pages. If you do not have sufficient access permissions, speak to the system
administrator.
Figure 2-4 Workplace Collaboration Services Administration link
3. Type generic in the Title contains field and press Enter.
4. Select the portlet named RCP Portlet - Generic and click Copy. The result is that a new
copy of the generic portlet is created. This new portlet must now be modified to refer to the
switcher view created earlier.
5. Select the new portlet created and click Modify Parameters to modify the new portlet.
6. Click Set Title for Selected Locale to change the portlet name. Type SwitcherView in the
Title field and click OK.
This modifies the name of the view as displayed in the Workplace Managed Client, the
view name in the plugin.xml file.
7. Select the check box next to the rcpView parameter and type
com.ibm.wcttool.sldlv2.views.SwitcherView in the Value field.
Note: This configures the switcher portlet and corresponds to the switcher view defined
in Figure 2-1 on page 18.
The page should now look similar to the one shown in Figure 2-5 on page 26.
Chapter 2. ISVs with Eclipse applications
25
View ID of the Eclipse view to display,
SwitcherView
Figure 2-5 Workplace Collaboration Services portlet configuration page
8. Click Save.
Assign user policy to Workplace portlets
A Workplace administrator must assign access to the applications portlets and pages in order
to allow users to provision and use the application. The following steps describe how to
assign access to the Workplace Managed Client portlets:
1. Click Administration and click the Access tab.
2. Click Resource permissions and select Portlets under Resource Types.
3. Type SwitcherView in the Search for field to find the Workplace portlet page created in
“Wrapping an Eclipse view as a thick portlet” on page 25.
4. Click the Assign Access icon to assign the user policy, as shown in Figure 2-6.
Figure 2-6 Assign Access for portlets
5. Click the Edit Role icon to the right of User.
26
IBM Workplace Managed Client: ISV Integration Guide
6. Click Add and select all authenticated portal users, as in shown in Figure 2-7. The
figure shows the available user policies that can be applied to the portlet. This is the
default Workplace policy created by the Workplace administrator. (Alternatively, you can
select the new Workplace user policy created using the WebSphere administration
console). Click OK.
Figure 2-7 Workplace user policies
Creating the Workplace page
Perform the following steps to create a subpage of the WorkplaceRCPPages page, called
Delivery Manager, in Workplace Collaboration Services and add a portlet to the page:
1. In the Workplace Collaboration Services administration console, click the Portal User
Interface tab.
2. Click Manage Pages. Type workplaceRCP in the Search for field.
Note: This adds the Delivery Manager application page under the Workplace content
root.
3. Click the Edit Page Layout icon for the WorkplaceRCPPages page, as shown in
Figure 2-8.
Assign
Edit
Policy
Layout
Figure 2-8 Accessing page layout and user policy in Workplace Collaboration Services server console
4. Click Edit Properties. In the Advanced Options section, make sure that the HTML and
RCPML check boxes are selected in the page support option. If not, select both and click
OK → OK → Done. This means that the sample application will support both RCPML
layout and HTML.
Chapter 2. ISVs with Eclipse applications
27
Important: Do not leave either the RCPML or HTML check boxes cleared. This will lead
to pages and applications not being displayed.
5. Click WorkplaceRCPPages and then click New Page under the WorkplaceRCPPages
category to create a subpage that will host the Workplace application.
6. Type Delivery Manager in the name field. In the Advanced Options section, make sure
that the HTML and RCPML check boxes are selected in the page support option. If not,
select both and click OK.
Important: Make sure that your portlet names are unique.
Assign access to the Workplace page
Follow these steps to assign access permissions to the Delivery Manager page:
1. Click the Access tab at the top of the page.
2. Select Resource permission → Pages. Search for the page name Delivery Manager.
3. Click the Assign Access icon to assign the user policy.
4. Click the Edit Role icon to the right of User.
5. Click Add and select all authenticated portal users. Click OK → Done.
Adding a portlet to a page
After the creating the portlet, you must add it to a page in order for it to be accessible to users.
Perform the following steps:
1. Click Portal User Interface → Manage Pages.
2. Search for Delivery Manager. Click the Edit Page Layout icon for the Delivery Manager
page.
3. In the layout panel of the page, click Add portlets. Search for the newly created switcher
view portlet. Click OK → Done. See Figure 2-9 on page 29.
28
IBM Workplace Managed Client: ISV Integration Guide
Figure 2-9 Workplace Collaboration Services page layout for Delivery Manager application
Centralized rollout of new applications and updates
As discussed earlier in the chapter, one of the primary advantages of Workplace Managed
Client is its provisioning capability. Rather than manually installing and updating applications,
applications are instead automatically downloaded and installed for the user from the
Workplace Collaboration Services server, with no effort required on the user’s part.
To make the application plug-ins available for client provisioning, the application-specific JAR
files must be installed on the Workplace Collaboration Services update site.
When a user starts the Workplace Managed Client in online mode, the user will be asked to
download the new updates. When the user accepts the download, the new or updated feature
is downloaded and installed.
Note: For detailed instructions about deploying the application on the update site
manually, see the paper by Nishant Shah, Configuring and deploying a rich client
application on IBM Workplace Collaboration Services server, on developerWorks:
http://www.ibm.com/developerworks/workplace/library/deploy-client-application-workpla
ce/index.html
The Workplace Managed Client Developer Toolkit provides a more automated approach.
See the following Web page for more information:
http://www.ibm.com/developerworks/workplace/library/wmc-toolkit-basic/index.html
Chapter 2. ISVs with Eclipse applications
29
2.4 Leverage
The next level of integration is to leverage more of the capabilities of the platform services that
are available in IBM Workplace Client Technology. This involves using more fully the extra
capabilities offered by Workplace Managed Client. Some of these include:
򐂰 Enabling server-side definition of an applications view layout by creating one portlet per
view
򐂰 Action bars, used to replace view toolbars
򐂰 Workplace Managed Client menus
򐂰 Search bar
򐂰 Custom UI widgets
– Rich text editor
– Alerts
– Collapse bar
򐂰 Custom views
– Shelf views
򐂰 Personalities and personality startup
A number of these capabilities are discussed in the following sections.
Note: For more information, refer to the following developerWorks articles:
򐂰 Working with application layouts in the IBM Workplace Managed Client
http://www.ibm.com/developerworks/lotus/library/wmc-layouts/index.html
򐂰 Introducing the IBM Workplace Client Technology API
http://www.ibm.com/developerworks/lotus/library/wcs-toolkit/index.html
For more information, refer to 1.4.3, “Leverage” on page 11.
Note: The steps explained in each of the following sections assume that an Eclipse plug-in
project with a view class has already been created, as demonstrated in 2.3,
“Accommodate” on page 21.
We also assume that you are familiar with the steps required for deploying a Workplace
Managed Client application to the Workplace Collaboration Services server, also shown in
2.3, “Accommodate” on page 21.
2.4.1 Enabling server-side definition of an applications view layout
In 2.3, “Accommodate” on page 21, an Eclipse RCP application was modified to take
advantage of the Workplace Managed Client provisioning engine. The application perspective
was wrapped in a single Eclipse view and defined as a single portlet on the Workplace
Collaboration Services server.
This approach is relatively simple but does not take advantage of more powerful capabilities
of Workplace Managed Client such as centralized management of a client application’s
layout. After a portlet is defined for each view, it is easy to rearrange the application as
needed and be automatically provisioned to client machines. This change requires no extra
30
IBM Workplace Managed Client: ISV Integration Guide
coding; after an application is deployed correctly, layout modifications can be handled by
non-technical users with the appropriate Workplace Collaboration Services access.
Figure 2-10 shows the Delivery Manager application after its views have been added as
individual portlets on the Workplace Collaboration Services server.
Application views rearranged using
centralized server-side management
Figure 2-10 Arranging application views with different folder IDs: Centralized server-side management
You can take two possible paths when defining the layout of an application:
򐂰 Manually configuring all aspects of the application, including:
– Pages
– Portlets
򐂰 Auto-configuration using the Workplace Managed Client Developer Toolkit
We discuss both of these approaches in the following sections.
2.4.2 Manually configuring an application page layout
In order to take advantage of the page layout features of Workplace Managed Client, you
need to create individual portlets. The Delivery Manager application has six different views:
򐂰 NavigationView
򐂰 WarehouseView
Chapter 2. ISVs with Eclipse applications
31
򐂰 VanView
򐂰 OrderView
򐂰 StoreView
򐂰 PaletteView
Perform the following steps to manually configure an application’s page layout:
1. Deploy the application feature to the HTTP server.
2. Create a single portlet for each of the Eclipse views in the application.
3. Edit the portlet configuration parameters.
4. Create a single page with a two-pane layout.
5. Add the portlets to the page.
Deploying the application feature to the HTTP server
The feature and plug-in JAR files of the Eclipse RCP application must be deployed to the
Workplace Collaboration Services HTTP server in order to enable the Workplace Managed
Clients to download them. These JAR files are generated from an Eclipse Update Site
project. For details about how to create this project and deploy the resulting files, see the
paper by Nishant Shah, Configuring and deploying a rich client application on IBM Workplace
Collaboration Services server, on developerWorks:
http://www.ibm.com/developerworks/workplace/library/deploy-client-application-workplace/
index.html
Note that if the application contains any Eclipse activities, each activity must be mapped to
that application by running an xmlaccess script on the server. The developerWorks article
provides instructions for this.
Creating a single portlet for each Eclipse view
In the case of the Delivery Manager, there are six different views, NavigationView,
WarehouseView, VanView, OrderView, StoreView, and PaletteView. For this reason, six
separate portlets must be created and each one associated with one of the Eclipse views.
Note: See the “Wrapping an Eclipse view as a thick portlet” on page 25 for detailed
information about portlet configuration. Note that the rcpView parameter in each portlet
should be identical to the view ID for the corresponding Eclipse view.
All portlets with the same tab folder ID will be grouped together in the UI. For example, in
Figure 2-10 on page 31, the Warehouse and Van views use the pane2 folder ID, while the
Order, Store and Palette views use the pane3 folder ID.
Follow these steps to create a portlet:
1. Log in to the Workplace server as an administrator using the following URL:
http://<http_server>/lwp/myworkplace
2. Click Administration in the top-right corner of the page.
3. Click Portlets → Manage Portlets and search for the term generic in the Title contains
text box.
4. Select the portlet named RCP Portlet - Generic, and click Copy and then Modify
Parameters to modify the parameters for the new portlet created.
32
IBM Workplace Managed Client: ISV Integration Guide
5. Click Set Title for Selected Locale to change the portlet name.Type NavigationView in
the Title field and click OK.
6. Select the check box next to the rcpView parameter and type
com.ibm.wcttool.sldlv2.views.NavigationView in the Value field. This maps the new
portlet to the Eclipse view ID as defined in the plugin.xml file of the application.
Note: This configures the switcher portlet and corresponds to the switcher view defined
in Figure 2-1 on page 18.
7. Click Save to return to the Manage Portlets pane.
8. Repeat steps 4 through 7 with the parameter value changes for Title and rcpView shown
in Table 2-2.
Table 2-2 rcpView parameter values
Portlet title
rcpView parameter
WarehouseView
com.ibm.wcttool.sldlv2.views.WarehouseView
VanView
com.ibm.wcttool.sldlv2.views.VanView
OrderView
com.ibm.wcttool.sldlv2.views.OrderVIew
StoreView
com.ibm.wcttool.sldlv2.views.StoreView
PaletteView
com.ibm.wcttool.sldlv2.views.PaletteView
You should now have six new portlets.
Edit the portlet configuration parameters
After the new portlets have been created, you must define some portlet variables. For this
application, these include:
򐂰 Mapping each portlet to an Eclipse feature. This ensures that the feature and all its
plug-ins are provisioned to the client machine.
򐂰 Defining the relative size of each of the view panes by setting the ratio parameter.
򐂰 Defining how views are to be grouped using Eclipse view tabs by setting the folderid
parameter.
򐂰 Defining whether or not a view can be closed by setting the fixed parameter.
򐂰 Defining whether or not a view should always be visible by setting the visible parameter.
Table 2-3 lists the variable parameters and their functions.
Table 2-3 Available Workplace Collaboration Services portlet parameters and their functions
Parameter
Function
rcpUpdate
Defines the Eclipse feature ID on which the portlet depends.
id.feature_1
Defines the ID of the feature.
version.feature_1
Defines the preferred version.
match.feature_1
Indicates how to select other versions that might be available; the choices
are compatible and exact.
rcpView
Defines the view ID to display.
Chapter 2. ISVs with Eclipse applications
33
Parameter
Function
ratio
Controls the size of the view in relation to the page.
fixed
Indicates whether the layout of the personality is fixed. The default is no.
If set to yes, the view is not closeable and cannot be moved.
folderid
Groups portlets into a tabbed view. This is similar to the IFolderLayout
class used in a perspective. When portlets with the same folderid
appear together in one column in a layout, they are grouped into a tabbed
display.
visible
Controls whether the view is visible or not. The default is yes.
style
Defines the style of the title bar of the view. In Release 2.5.1, the only
supported style is NO_TITLE, which tells the client not to display a title bar
for the view.
Note: For more information about the application parameters, see the developerWorks
article at:
http://www.ibm.com/developerworks/lotus/library/wmc-layouts/index.html
For provisioning and application update information, see the paper by Nishant Shah,
Configuring and deploying a rich client application on IBM Workplace Collaboration
Services server, on developerWorks:
http://www.ibm.com/developerworks/workplace/library/deploy-client-application-workpla
ce/index.html
Mapping each portlet to an Eclipse feature
Map each portlet to all features it requires to be provisioned down to the client machine. The
provisioning engine on the Workplace Collaboration Services server uses these mappings to
decide which JAR files should be downloaded by Workplace Managed Client. The three
parameters that are used to map a portlet to a feature are id, version, and match. Each of
these should be followed by an identifier, for example, feature_1, which can essentially be
defined however you want as long as the same identifier is used for all three parameters.
Table 2-3 on page 33 gives an example of this.
If the parameter match.feature_1 is set to compatible and the version number on disk is
changed to 1.0.1, the feature update is automatically processed when the clients connect. If
match.feature_1 is set to exact, only that version is used. If there is more than one feature,
additional variables can be added to identify them. The client will not display the UI unless all
needed features are available. This protects the user from seeing a broken UI.
Perform the following steps:
1. Select Portlets → Manage Portlets, and search for the NavigationView portlet. Click
Modify parameters.
2. Type rcpUpdate in the blank field to the left of the Add button. Type
com.ibm.wcttool.sldlv in the blank value field next to rcpUpdate and click Add. This
maps the portlet to the Eclipse feature com.ibm.wcttool.sldlv, as defined in the
application’s feature.xml file.
3. Create the three parameters defined in Table 2-4 on page 35. To do this, type the
parameter name and value into the blank text fields to the left of the Add button, and click
Add.
4. Repeat steps 1 to 3 for the other five portlets.
34
IBM Workplace Managed Client: ISV Integration Guide
Table 2-4 Three portlet parameters used to map a portlet to a feature
Parameter
Value
match.Feature_1
compatible
version.Feature_1
1.0.0
id.Feature_1
com.ibm.wcttool.sldlv
Defining the relative size of each of the view panes
In the NavigationView portlet, replace the existing ratio parameter with .20. This causes the
leftmost pane of the page to occupy 20% of the horizontal workbench area. The ratio
parameter does not have to be modified for the other portlets.
Defining how views are to be grouped using Eclipse view tabs
The folderid parameter controls how portlets are grouped into a tabbed view. This is similar to
the IFolderLayout class used in a perspective. When portlets with the same folderid appear
together in one column in a layout, they are grouped into a tabbed display. For the Delivery
Manager application, perform the following two steps:
1. Modify the WarehouseView and VanView portlets by adding the following parameter and
value:
Parameter: folderid
Value: pane2
2. Modify the OrderView, StoreView and PaletteView portlets by adding the following
parameter and value:
Parameter: folderid
Value: pane3
Figure 2-10 on page 31 shows the result of arranging the views and portlets in such a way.
Defining whether or not a view can be closed
For all six portlets, set the value of the fixed field to yes. This means that none of the views
can be closed by the user.
Defining whether or not a view should always be visible
For all six portlets, set the value of the visible field to yes. This means that all of the views will
be visible.
Figure 2-11 on page 36 shows the complete configuration for the StoreView portlet. Other
portlets will be quite similar to this.
Chapter 2. ISVs with Eclipse applications
35
Figure 2-11 Portlet configuration for the StoreView Eclipse view
Adding multiple portlets to a page
After creating the portlets, add them to the Delivery Manager page created in “Creating the
Workplace page” on page 27.
Follow these steps to modify the Delivery Manager page:
1. In the Workplace Collaboration Services administration console, click the Portal User
Interface tab.
2. Click Manage Pages and search for WorkplaceRCPPages.
3. Click WorkplaceRCPPages → New Page.
4. Type Delivery Manager_All in the Title field and click OK.
5. Search for the Delivery Manager_All page and click the Edit Page Layout icon.
6. Click Add portlets in the left column.
7. Add the NavigationView portlet and click OK.
Tip: Search for the portlet name.
8. Repeat steps 6 and 7 to add the remaining five portlets to the right column and click Done.
Your page should look similar to the page shown in Figure 2-12 on page 37.
36
IBM Workplace Managed Client: ISV Integration Guide
Figure 2-12 Page layout for the Delivery Manager application
2.4.3 Configuring an application page layout using Workplace Managed Client
Developer Toolkit
Configuring an application layout manually can be very time-consuming. An alternative is to
use the Workplace Managed Client Developer Toolkit. The Workplace Managed Client
Developer Toolkit is an Eclipse-based UI tool that automatically configures many default
parameters. It also makes deploying an application to a Workplace Collaboration Services
server much simpler.
Follow these steps to create the layout for the Delivery Manager application using the
Workplace Managed Client Developer Toolkit:
1. Install the toolkit. You can download it from:
http://www.alphaworks.ibm.com/tech/wmctoolkit
2. Create a new Workplace Managed Client project using the toolkit.
3. Select a page layout with two columns, a small left column and a large right column. This
automatically creates a page layout with a left column that has a ratio of 0.2.
4. Add the NavigationView to the left column and all other views to the right column.
5. Deploy the application to the server.
Figure 2-13 on page 38 shows a page layout configuration using the Workplace Managed
Client Developer Toolkit.
For detailed information about how to perform each of these steps, see the following
developerWorks article and the documentation that comes with the toolkit:
http://www.ibm.com/developerworks/lotus/library/wmc-toolkit
Chapter 3, “ISVs with AWT or Swing applications” on page 47 also contains a much more
comprehensive description of using the Workplace Managed Client Developer Toolkit.
Chapter 2. ISVs with Eclipse applications
37
Figure 2-13 Page layout configuration using the Workplace Managed Client Developer Toolkit
2.4.4 Using an action bar to replace the view toolbar
Workplace Managed Client manages view toolbars and tabbed views differently from Eclipse
RCP. For example, in Figure 2-3 on page 23, the toolbars from the original Eclipse RCP
application were missing from the UI after it was incorporated into Workplace Managed
Client.
Note: Future releases of Workplace Client Technology, 2.6 and later, will have the ability to
turn on view toolbars even in tabbed views. This will be an even quicker way to get an
application up and running in Workplace Client Technology.
The action bar is a custom Workplace Client Technology widget. By switching an application’s
UI to the action bar, the application retains a lot of its functionality, as well as having its
features, looks and operations being more deeply integrated with Workplace Managed Client.
The action bar is a special toolbar that conforms to Workplace Client Technology styling and
is very easy to use. Eclipse actions are contributed to it just like any other toolbar manager.
Perform the following steps to add an action bar to the Eclipse view:
1. Add a dependency on the com.ibm.rcp.ui plug-in to the application’s plugin.xml file, as
shown in Example 2-2.
Example 2-2 Partial plugin.xml file containing a dependency on the com.ibm.rcp.ui plug-in
<plugin>
<requires>
<import plugin="com.ibm.rcp.ui"/>
</requires>
...
</plugin>
38
IBM Workplace Managed Client: ISV Integration Guide
2. Modify the Eclipse view class to add the action bar instead of the view toolbar and
drop-down menu. Example 2-3 shows how this is done.
Example 2-3 Eclipse view code to create an action bar and add Eclipse actions
//Both the IActionBarWidgetManager and WidgetFactory classes are defined in the
//com.ibm.rcp.ui.widgets plugin
import com.ibm.rcp.ui.widgets.api.jface.IActionBarWidgetManager;
import com.ibm.rcp.ui.widgets.api.WidgetFactory;
//...
private IActionBarWidgetManager mActionBar;
private Action mActNew, mActEdit, mActDel, mActReport;
public void createPartControl(Composite parent) {
parent.setLayout(new GridLayout(2, false));
mActionBar = WidgetFactory.createActionBar(parent, SWT.RIGHT | SWT.FLAT);
//...
makeActions();
contributeToActionBars();
}
private void makeActions(){
//Make the Eclipse Actions here...
}
private void contributeToActionBars() {
mActionBar.add(mActNew);
mActionBar.add(mActEdit);
mActionBar.add(mActDel);
mActionBar.add(mActReport);
}
Applying the code in Example 2-3 results in an action bar being created, replacing the
Eclipse toolbar for the tabbed view, as shown in Figure 2-14.
Figure 2-14 Delivery Manager action bar
3. Deploy the application to the Workplace Collaboration Services server and provision it
down to the client. We describe how to do this in “Deploying the application feature to the
HTTP server” on page 32.
2.4.5 Contributing to the Workplace Managed Client menus
As with toolbars, Workplace Managed Client handles top-level menus differently from the
Eclipse RCP. Both platforms specify menu commands and their contents using the actionSet
and menu tags. However, Workplace Managed Client uses different menu IDs. If an Eclipse
RCP application is built with actions that are nested under standard menu commands such as
File or Edit, those items will not be available through standard Workplace Managed Client
menus.
Chapter 2. ISVs with Eclipse applications
39
The IWorkplaceActionConstants class defines Workplace Managed Client menu IDs.
Table 2-5 illustrates some of these IDs.
Table 2-5 Menu IDs defined in the IWorkplaceConstants class
Constant value
Reference in menu tag as
FILE_MENUID = “file”
IWorkbenchActionConstants.M_FILE
path=“additions” and id=“file”
EDIT_MENUID = “edit”
IWorkbenchActionConstants.M_EDIT
path=“edit/<submenutitle>” and id=“<customString>
WINDOW_MENUID = “window”
IWorkbenchActionConstants.M_WINDOW
HELP_MENUID = “help”
IWorkbenchActionConstants.M_HELP
id=“help”
For a complete listing of all available menu items, refer to the Workplace Collaboration
Services 2.5.1 API documentation and Appendix B, “IBM Workplace 2.5.1 menu IDs” on
page 185.
Example 2-4 shows the Eclipse plugin.xml code to add a Warehouse submenu to the File
menu in Workplace Managed Client.
Example 2-4 Eclipse plugin.xml code
<actionSet
label="Warehouse"
visible="false"
id="com.ibm.wcttool.sldlv2.Warehouse.actionSet"
>
<menu
label="Warehouse"
id="com.ibm.wcttool.sldlv2.Warehouse.actionSet.menu"
path="file/filePrintGroup">
<separator
name="sampleGroup">
</separator>
</menu>
<action
label="Report"
menubarPath="file/com.ibm.wcttool.sldlv2.
Warehouse.actionSet.menu/sampleGroup"
icon="icons/report.gif"
class="com.ibm.wcttool.sldlv2.act.wh.ActWarehouseReport"
id="com.ibm.wcttool.sldlv2.act.wh.ActWarehouseReport"/>
</actionSet>
2.4.6 Adding a Workplace Managed Client search bar
Workplace Managed Client exposes an extension point that any application can implement in
order to place a search bar above the main view. The search bar consists of:
򐂰 A combo box listing search categories
򐂰 A text box for the string to be searched
򐂰 A button to activate the search
40
IBM Workplace Managed Client: ISV Integration Guide
Figure 2-15 shows a search bar.
Figure 2-15 The search bar as extended by the Delivery Manager application
The searchbarAdapters extension point adds a custom contribution to the search menu that
performs a customized search and displays its results in a custom view. To create a search
bar in Workplace Managed Client, perform the following steps:
򐂰 Populate the search menu with the custom contribution.
򐂰 Contribute code to perform a custom search that is triggered when the corresponding
menu action is selected.
򐂰 Display the search results in a custom view.
Follow these steps to add a custom search bar contribution:
1. Edit the plugin.xml file by importing the com.ibm.rcp.ui.searchbar and
com.ibm.rcp.platform plug-ins, as shown in Example 2-5.
Example 2-5 Eclipse plugin.xml code with plug-in dependencies for a search bar extension
<plugin>
<requires>
<import plugin="com.ibm.rcp.ui.searchbar"/>
<import plugin="com.ibm.rcp.platform"/>
</requires>
...
</plugin>
2. Extend the searchbarAdapters extension point defined in the
com.ibm.rcp.ui.searchbar.api code and provide values for the required attributes as
tags, as shown in Example 2-6.
Example 2-6 Eclipse plugin.xml code to extend searchBarAdapters
<plugin>
<extension id="com.ibm.wcttool.sldlv2.search.VanSearch"
name="searchbar extension point"
point="com.ibm.rcp.ui.searchbar.searchbarAdapters">
<adapter
label="Van"
data="1"
class="com.ibm.wcttool.sldlv2.search.VanSearch"
id="com.ibm.wcttool.sldlv2.search.VanSearch" />
</extension>
...
</plugin>
3. Map the adapter id parameter in Example 2-6 to the Delivery Manager activity pattern
binding. Example 2-7 on page 42 shows how to do this.
Chapter 2. ISVs with Eclipse applications
41
Example 2-7 Eclipse plugin.xml code to map the Id parameter
<plugin>
<extension point="org.eclipse.ui.activities">
<activity
description="This is sldv activity"
name="com.ibm.workplace.deliverymgr"
id="com.ibm.workplace.deliverymgr"/>
<activityPatternBinding
activityId="com.ibm.workplace.deliverymgr"
pattern="com\.ibm\.wcttool\.sldlv2/com\.ibm\.wcttool\.sldlv2\.search\..*" />
</extension>
...
</plugin>
4. Create a new class that implements the ISearchDataAdapter interface. The class and
package should match the class parameter defined in the searchbarAdapters extension
created in step 2 on page 41. In the Delivery Manager example, we use the
com.ibm.wcttool.sldlv2.search.VanSearch class, as shown in Figure 2-8 on page 27.
Example 2-8 Partial implementation of the ISearchDataAdapter interface in VanSearch.java
package com.ibm.wcttool.sldlv2.search;
//The ISearchDataAdapter interface is defined in the com.ibm.rcp.ui.searchbar plug-in
import com.ibm.rcp.ui.searchbar.api.ISearchDataAdapter;
public class VanSearch implements ISearchDataAdapter{
public boolean isMenuVisible() {
return true;
}
public void run(String arg0, String arg1) {
//Search logic goes here
//Non-UI operation
//...
// UI Operation should be performed using syncExec() or asyncExec()
Display.getDefault().asyncExec(new Runnable(){
public void run() {
// The UI Operation
}
}
//......
}
Note: While implementing the run() method for ISearchDataAdaper, make sure that the
UI operations are performed using the syncExec() or asyncExec() thread. Perform the
non-UI operations using normal Java Thread.
5. Deploy the application to the Workplace Collaboration Services server and provision it
down to the client. “Deploying the application feature to the HTTP server” on page 32
describes how this is accomplished.
42
IBM Workplace Managed Client: ISV Integration Guide
2.4.7 Adding a Workplace Managed Client shelf view
Workplace Managed Client provides a side bar to which applications can add custom views.
These are referred to as shelf views. Figure 2-16 on page 44 shows an example of a shelf
view. To add a shelf view to the side bar, perform the following steps:
1. Create the Eclipse view to be displayed in the side bar.
2. Add a dependency to the plug-in com.ibm.rcp.ui to the view plug-in project. Example 2-9
shows a partial plugin.xml file with this dependency added.
3. The com.ibm.rcp.ui.shelfViews extension point must be extended. Example 2-9 shows
this.
4. If the shelf view should only appear when a particular application has the focus, you must
map the existing Eclipse view id to the shelf view view attribute. Example 2-9 shows the
view id attribute and the shelfView view attribute are identical, with the value
com.ibm.wcttool.sldlv2.views.VanInfoView.
5. Create an Eclipse activity and map the shelf view ID to the Eclipse activity ID just created.
If the shelf view is not mapped to a particular application’s activity, it will always be visible
in the side bar; the Instant Contacts view is an example of this.
Example 2-9 shows how a shelf view is added to the Delivery manager application.
Example 2-9 Eclipse plugin.xml code to add a shelf view and map it to an Eclipse activity
<requires>
<import plugin="com.ibm.rcp.platform"/>
</requires>
<extension
point="org.eclipse.ui.views">
<view
name="Van Information"
class="com.ibm.wcttool.sldlv2.views.VanInfoView"
id="com.ibm.wcttool.sldlv2.views.VanInfoView">
</view>
</extension>
<extension
point="com.ibm.rcp.platform.shelfViews">
<shelfView view="com.ibm.wcttool.sldlv2.views.VanInfoView"
id="com.ibm.wcttool.sldlv2.views.VanInfoView" />
</extension>
<extension point="org.eclipse.ui.activities">
<activity
description="This is sldv activity"
name="com.ibm.workplace.deliverymgr"
id="com.ibm.workplace.deliverymgr"/>
<activityPatternBinding
activityId="com.ibm.workplace.deliverymgr"
pattern="com\.ibm\.wcttool\.sldlv2/com\.ibm\.wcttool\.sldlv2\.views\..*" />
<!--The pattern parameter maps the shelf view id to the Delivery Manager activity-->
</extension>
6. Deploy the application to the Workplace Collaboration Services server and provision it
down to the client. “Deploying the application feature to the HTTP server” on page 32
describes how this is accomplished.
Figure 2-16 on page 44 shows the Workplace Managed Client shelf view anchored in the side
bar.
Chapter 2. ISVs with Eclipse applications
43
Figure 2-16 Workplace Managed Client shelf view anchored in the side bar
2.5 Exploit
As stated in the introduction, complete seamless integration occurs when an ISV chooses to
fully exploit the capabilities of Workplace Managed Client. For example, when writing plug-ins
that are more than simple wrappers, most or even all of the code is structured to the
Workplace programming model in order to exploit the client technologies fully. By employing
the APIs and available models, an ISV can write a matched set of portlets, plug-ins, EJB
services, and data source definitions that take full advantage of all the attributes of the IBM
Workplace Client Technology infrastructure.
Application components that are written in this manner gain several benefits, for example, the
ability to dynamically share capabilities, such as online awareness, and participate in
spanning services, such as full text indexing. In most cases, ISVs that have existing
applications or components are expected to gradually extend into this space as they match
needs and requirements to the appropriate programming model constructs.
Workplace Managed Client provides a number of features that enable an ISV to extend its
application in very powerful ways.
Document libraries for remote storage and document sharing
Workplace Managed Client document libraries consist of both local and remote data storage
in a folder structure designed for sharing documents among a group or team. Workplace
Managed Client provides an API for manipulating files and folders in a document library. The
Delivery Manager application can be modified to generate a report and store it in a remote
document library using these APIs.
44
IBM Workplace Managed Client: ISV Integration Guide
Online awareness
There is a online/offline awareness API that can be used to inform an application when the
client is online, offline, or when it is about to transition between the two. This can be useful for
completing transactions if connectivity is about to change and close down open connections.
After the operation has completed, the connection to the database can be reestablished. The
Delivery Manager application can use these APIs to offer report generation capabilities only
when the client is online.
Synchronizing client application data
There is an API that taps into the client's synchronization framework. Based on timetables set
in the client’s preferences, the application can be told when to synchronize its data. The
actual data synchronization is performed by the application itself.
Database access, both local and remote
The Delivery Manager application uses a relational database on the server to manage its
data and post updates. Workplace Managed Client comes with its own Cloudscape relational
database. After the application is fully moved to the Workplace Managed Client platform, it
does not need to always have a connection to the remote database; it simply needs to
connect to the local Cloudscape database. The rest of the application code does not need to
be changed.
Messaging and notifications
Workplace Managed Client provides a full mail API for sending and manipulating mail
messages. The Delivery Manager application can be altered to send a notification e-mail to a
specified recipient when a report is generated.
Securing a client application
The IBM Workplace Client Technology platform is a secure platform that protects application
data. Single sign-on with the operating system capabilities are built into the rich client by
default. The local Cloudscape database is encrypted using the users credentials, which must
be retrieved using the credential store API.
All of these steps apply to any fully integrated Workplace Managed Client application. They
are not specific to integrating an Eclipse RCP application. We cover all of these points in
detail in Chapter 6, “Exploiting IBM Workplace Managed Client” on page 139.
2.6 Summary
This chapter has shown how an Eclipse RCP application can be gradually merged with the
Workplace Managed Client as time, finances, and resources allow. At each of the four levels
of integration, we show how an Eclipse RCP application can benefit from integration with the
Workplace Managed Client, what the integration points are, and what new features and
services the Workplace Managed Client offers to ISVs with Eclipse applications.
2.7 URLs referenced in this chapter
Table 2-6 on page 46 provides a list of the URLs referred to in this chapter.
Chapter 2. ISVs with Eclipse applications
45
Table 2-6 URLs referenced in this chapter
46
What
Where
Information about how IBM originally developed
Eclipse
http://www.ibm.com/developerworks/opensour
ce/top-projects/eclipse-starthere.html?ca=
dgr-lnxw09
Eclipse Foundation home page
http://www.eclipse.org
Eclipse Rich Client Platform
http://wiki.eclipse.org/index.php/Rich_Cli
ent_Platform
Get started with Eclipse
http://www.ibm.com/developerworks/opensour
ce/top-projects/eclipse-starthere.html?ca=
dgr-lnxw09LearnEclipse
Detailed tutorial about deploying Workplace
Managed Client, the paper by Nishant Shah,
Configuring and deploying a rich client
application on IBM Workplace Collaboration
Services server, on developerWorks
http://www.ibm.com/developerworks/workplac
e/library/deploy-client-application-workpl
ace/index.html
Workplace Managed Client Developer Toolkit
http://www.alphaworks.ibm.com/tech/wmctool
kit
Creating an application with the IBM Workplace
Managed Client Developer Toolkit
http://www.ibm.com/developerworks/workplac
e/library/wmc-toolkit-basic
Working with application layouts in the IBM
Workplace Managed Client, including a full
description of all portlet variables
http://www.ibm.com/developerworks/lotus/li
brary/wmc-layouts/index.html
IBM Workplace Managed Client: ISV Integration Guide
3
Chapter 3.
ISVs with AWT or Swing
applications
This chapter introduces the steps to integrate an Abstract Windowing Toolkit (AWT) or Swing
application into Workplace Client Technology's framework. This chapter addresses:
򐂰 The levels of integration available with IBM Workplace Client Technology
򐂰 High-level considerations for integrating a Swing application with Workplace Client
Technology
򐂰 Specific examples of integration paths that can be taken
© Copyright IBM Corp. 2006. All rights reserved.
47
3.1 Overview
This chapter describes how an ISV can migrate an existing AWT or Swing application to the
Workplace Managed Client framework. Benefits of such a migration include:
򐂰 Opportunity for lower total cost of ownership (TCO) because the application is server
managed and provisioned
򐂰 Integration with other applications provided by the application switcher
򐂰 Leveraging the features and functionality provided by Workplace Client Technology such
as its credential store, offline manager, synchronization manager, and locally encrypted
databases
This chapter uses a Digital Elevation Map (DEM) application, referred to as DEM Viewer.
DEM Viewer maintains a table of height elevations. Users click and drag sliders to modify the
image's appearance, which in turn, modifies the data on which the various elevation points
are based. This chapter shows how the application changes as it is moved through the
various stages of application integration.
3.1.1 What is AWT?
The Abstract Windowing Toolkit (AWT) is a Java-based, platform-independent UI widget
toolkit. AWT is wrapped around native UI widgets. By providing a light layer, AWT renders
graphic objects, such as toolbars or buttons, quickly. However, this can be a problem if an
application is going to be opened on a number of different operating systems that do not
support the same widget set, for example, Microsoft Windows and Linux. AWT is designed for
simple applications.
3.1.2 What is Swing?
Swing is also a Java-based, graphic user interface (GUI) toolkit. It is used it to build
platform-independent GUI widgets, for example, forms and dialog boxes. Unlike the Abstract
Windowing Toolkit (AWT), components built using Swing are considered lightweight, meaning
that instead of relying on the host system's user interface APIs, Swing mimics them.
3.1.3 What is SWT?
The Standard Widget Toolkit (SWT) provides a platform-independent Java API that is tightly
integrated with the operating system’s native windowing environment. It was initially
developed by IBM for use with the Eclipse IDE. SWT-based Java applications have native
GUIs and can be integrated with other native applications and components. To fully exploit the
functionality of Workplace Managed Client, Swing or AWT applications will need to convert to
SWT.
3.1.4 Swing integration levels
Although both Swing and SWT are Java-based toolkits, their UI models are different. For
example, they both employ different event handling mechanisms. Although integrating the two
models takes work, ISVs can choose how involved they want this work to be and revisit or
upgrade the model as their needs change.
Table 3-1 on page 49 shows the benefits of the integration levels.
48
IBM Workplace Managed Client: ISV Integration Guide
Table 3-1 The benefits of the various integration levels
Increase of time, effort, and synergy →
Coexist
Accommodate
Leverage
Exploit
Notepad.
Launch DEM Viewer from
within Workplace Managed
Client.
Use Workplace Managed
Client UI features, such as
file menus, search, and
status bars.
Use the document libraries,
mail, single sign-on, and
secure data stores that
Workplace Managed Client
provides.
Wrap DEM Viewer as a
Workplace Managed Client
application.
Optionally, replace some
Swing or AWT UI controls
with SWT.
3.2 Coexist
The simplest level of integration is coexistence. This requires no changes at the code level.
For example, the DEM Viewer application can be extended to store a table of elevations in a
spreadsheet in the Workplace Client Technology Document Manager. Its content can be
copied and pasted directly into the DEM Viewer application that runs alongside Workplace
Client Technology. This makes use of the secure and central data management of the
Document Manager in Workplace Client Technology to store the data for the application. This
stored data, or references to it, can be e-mailed to other people using the Workplace
Managed Client messaging application or can be added to an activity using a Workplace
Managed Client Activity Manager application.
Figure 3-1 on page 50 shows running the DEM Viewer alongside Workplace Client
Technology copying data from a spreadsheet and pasting into the DEM Viewer.
Chapter 3. ISVs with AWT or Swing applications
49
Figure 3-1 Running the DEM Viewer next to Workplace Client Technology
Similarly, if the stand-alone application is tied to a particular file type, the files can be stored in
the Workplace Managed Client document library. From within Workplace Managed Client or
the browser, double-clicking those files launches the application. Its content can be edited
and saved. Closing the application prompts to re-import the file changes. If new data is
created for the application, the data needs to be saved to a temporary location and then
imported into the Workplace Managed Client document library. With no coding work involved,
the Workplace Managed Client capabilities are used to distribute and manage data viewed by
the application.
3.3 Accommodate
At the accommodate integration level, the application can be enhanced to use mechanisms
such as provisioning, modifying the shut-down sequence, and reparenting.
For the purposes of accommodating an existing AWT or Swing application, there is a quick
way to bring up the application directly into Workplace Managed Client.
Because most Swing and AWT applications are pure Java, they can be:
򐂰 Entirely included in one or more JAR files.
򐂰 Executed on any platform.
These two conditions set the scene for using one of the most valuable features of Workplace
Client Technology, provisioning. See the 2.3.1, “Lightweight integration of Eclipse RCP with
Workplace Managed Client” on page 22 for information about how provisioning can be
achieved manually. In 3.3.1, “Lightweight integration of a Swing or AWT application with
Workplace Managed Client” on page 51, we describe how a Swing or AWT application can be
50
IBM Workplace Managed Client: ISV Integration Guide
provisioned using the IBM Workplace Managed Client Developer Toolkit, which can be
downloaded from:
http://www.alphaworks.ibm.com/tech/wmctoolkit
Note: The following sections describe actions to be performed using the IBM Workplace
Managed Client Developer Toolkit on either Eclipse or IBM Rational® Application
Developer. They should be installed before attempting to follow the instructions provided.
3.3.1 Lightweight integration of a Swing or AWT application with Workplace
Managed Client
There are two types of lightweight integration of Swing and AWT applications with Workplace
Managed Client. The simplest is to use the provisioning components of Workplace Managed
Client, using a simple wrapper plug-in to launch the application externally. This ensures that
all the UI features of the application remain intact and that it is provisioned and installed to all
users with access rights. However, it does not run within the Workplace Managed Client
platform, and it is still quite clear that it is a separate application, without the same look and
feel. In 3.3.2, “Creating a new IBM Workplace project” on page 51, we provide an example
implementation.
An alternative to launching the Swing or AWT application separately from Workplace
Managed Client is to reparent its UI into the Workplace Managed Client UI in addition to
provisioning the application. This means that the application will launch within the Workplace
Managed Client itself and appear more like a native Workplace Managed Client application.
However, it still keeps its own Swing or AWT controls. This approach takes a little more coding
than the first approach, but results in a much more integrated look and feel for the application.
We discuss this approach in “Reparenting a Swing or AWT application into the Workplace
Managed Client UI” on page 56.
In order to use the Workplace Managed Client Developer Toolkit to wrap an existing AWT or
Swing application as a Workplace Managed Client application so that it can be provisioned,
perform the following steps:
1. In Eclipse or Rational Application Developer, create a new IBM Workplace project with a
single view.
2. Import the JAR file of the existing Swing application into the newly created plug-in project.
3. Modify the shut down sequence to remove all calls to System.exit in the existing code.
4. Display the Swing application from within the Workplace Managed Client. As mentioned
earlier, there are two possible methods of doing this:
– Displaying the Swing application in a separate window
– Reparenting the Swing application within Workplace Managed Client
We discuss these two methods individually later in this chapter.
5. Deploy the application to the Workplace Collaboration Services server.
3.3.2 Creating a new IBM Workplace project
To create a new IBM Workplace project, perform the following steps:
1. Select File → New → Project → IBM Workplace → Workplace Managed Client
Application Project, and click Next. See Figure 3-2 on page 52.
Chapter 3. ISVs with AWT or Swing applications
51
Figure 3-2 Creating a new IBM Workplace Eclipse project
2. Give the project a name, for example, com.ibm.wcttool.demviewer, and a Display Name,
such as DEM Viewer, as shown in Figure 3-3. If there is an icon that needs to be associated
with the application, you can select this in this window. Click Next.
Figure 3-3 Setting the Project name and Display Name
Note: The application Display Name and icon appear on the application switcher bar on
the left side of Workplace Managed Client. See Figure 3-6 on page 57 for an illustration
of this.
3. Choose the single view page layout and Automatically create default views, as shown
Figure 3-4 on page 53. Click Finish.
52
IBM Workplace Managed Client: ISV Integration Guide
Figure 3-4 Selecting the single view layout and to automatically create the default view class
These steps create three new projects, a feature project, a page layout project, and a
plug-in project, as shown in Figure 3-5:
– The feature project, com.ibm.wcttool.demviewer, defines what plug-ins should be
packaged as part of the application.
– The page layout project, com.ibm.wcttool.demviewer.MainPage, manages the different
pages and views (though only one of each is used in this example).
– The plug-in project, com.ibm.wcttool.demviewer.pane1, contains the Eclipse view
class to be placed in the single page,
com.ibm.wcttool.demviewer.pane1.views.Pane1View.
Feature project
Page layout
project
Plug-in project
Eclipse View class
Figure 3-5 The initial project view of the IBM Workplace Managed Client application project
Chapter 3. ISVs with AWT or Swing applications
53
3.3.3 Importing the Swing JAR file into the plug-in project
Now that the projects are created, the JAR file of the existing application needs to be
imported into the com.ibm.wcttool.demviewer.pane1 plug-in project. This is so the Pane1View
class can launch the DEM Viewer application. Perform the following steps:
1. Click File → Import → File System. Browse to find the srtm.jar file. Ensure that the value
in the Into Folder text box is the name of the plug-in project,
com.ibm.wcttool.demviewer.pane1.
2. Click Finish.
3. Add the new JAR file to the plug-in’s class path. Use one of the following methods:
– Add the text in Example 3-1 to the plugin.xml file. Example 3-1 shows a piece of the
plugin.xml file for the com.ibm.wcttool.demviewer.pane1 plug-in, showing the
dependency on the srtm.jar file, which contains the Swing-based DEM Viewer
application.
Example 3-1 A piece of the plugin.xml file
//plugin.xml
...
<runtime>
<library name="Pane1.jar"> <!--This dependency is auto-generated by the toolkit-->
<export name="*"/>
</library>
<library name="srtm.jar"><!-- This is the dependency on the DEM Viewer application-->
<export name="*"/>
</library>
</runtime>
– If an Open Services Gateway Initiative (OSGI) manifest was created for the plug-in (if a
build.properties file exists), add the text in Example 3-2 to the build.properties file.
Example 3-2 Adding the dependency on the JAR file to the build.properties file
//build.properties
...
jars.extra.classpath = srtm.jar
3.3.4 Modifying the shutdown sequence
In order to remove all calls to System.exit in the existing code, you must modify the shut
down sequence. Most stand-alone Swing and AWT applications will, at some point, call
System.exit () when the application should be shut down. However, because they are now
running within the Workplace Managed Client JVM™, this will cause the entire Workplace
Managed Client to shut down.
The cleanest way to remove these calls is to subclass the existing classes and remove the
System.exit call. In the case of the DEM Viewer application, the method call occurs in the
JFrame class that all the UI controls have been added to,
com.ibm.wctdemo.srtm.view.SRTMFrame, in its doFrameShut method.
In the original Swing application, an instance of the SRTMFrame class would be created and
used to contain all of the Swing UI controls. Now this class will be subclassed, and the child
class will be invoked instead of the parent class.
54
IBM Workplace Managed Client: ISV Integration Guide
Example 3-3 shows how the DEMView1Frame class was created for this purpose: The
DEMView1Frame class subclasses the original JFrame implementation, SRTMFrame, and
overrides the doFrameShut method in order to remove the System.exit() method.
Example 3-3 The DEMView1Frame class
//DEMView1Frame.java
package com.ibm.wctdemo.awtint.step1.views;
import com.ibm.wctdemo.srtm.logic.SessionLogic;
import com.ibm.wctdemo.srtm.view.SRTMFrame;
public class DEMView1Frame extends SRTMFrame{
private static final long serialVersionUID = -1711774321572959L;
//Override the method containing the System.exit method call
protected void doFrameShut(){
//This is all existing code from the DEM Viewer application
SessionLogic.endSession(getSession());
setVisible(false);
//Comment out the System.exit(0) call
//System.exit(0);
}
}
In some cases, it might not be possible to simply subclass the class containing the
System.exit() call, and in those cases, it is necessary to alter the source code to remove
those lines.
3.3.5 Displaying the Swing/AWT application within Workplace Managed Client
As mentioned previously, there are two options to be considered when deciding how to
display a Swing or AWT application using the Workplace Managed Client:
򐂰 Displaying the Swing application in a separate window
򐂰 Reparenting the Swing application within the Workplace Managed Client
Displaying a Swing or AWT application in a separate window
To display a Swing or AWT application in a window outside the Workplace Managed Client
workspace, modify the setFocus method of the Eclipse view created by the toolkit Pane1View.
When the Eclipse view receives the focus, it creates the JFrame if it has not already done so
and makes sure that it is visible. Also, when the Eclipse view is disposed, it disposes the
JFrame. Example 3-4 shows how this was done for the DEM Viewer application.
Example 3-4 Eclipse view for launching a stand-alone Swing or AWT application
//Pane1View.java
package com.ibm.wcttool.demviewer.pane1.views;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.ui.part.ViewPart;
public class Pane1View extends ViewPart {
private DEMView1Frame mFrame;
public Pane1View() {}
public void createPartControl(Composite parent) {}
Chapter 3. ISVs with AWT or Swing applications
55
public void setFocus() {
//Create a new frame if it has not been previously created, or is no longer valid
if ((mFrame == null) || !mFrame.isValid()){
mFrame = new DEMView1Frame();
}
if (mFrame.isVisible()){
mFrame.toFront();
}
else{
mFrame.setVisible(true);
}
}
public void dispose(){
super.dispose();
if(mFrame != null){
//dispose of the frame when the Eclipse view is disposed
mFrame.dispose();
mFrame = null;
}
}
}
Reparenting a Swing or AWT application into the Workplace Managed
Client UI
In the spectrum of application integration, having an application appear in a separate window
is relatively simple to program but does not present the best user experience. The better
option is to have the application appear inside the Workplace Managed Client framework.
Normally, an application resides within a frame, or JFrame for Swing, and all subsidiary
controls reside in that frame. SWT provides a utility function that enables a Swing frame to be
embedded inside of a SWT composite object; this is the SWT equivalent of panel or JPanel.
For the DEM Viewer, the application's frame will be imbedded inside the main control for a
view. This is known as reparenting. Figure 3-6 on page 57 shows the DEM Viewer application
reparented within Workplace Managed Client.
56
IBM Workplace Managed Client: ISV Integration Guide
Workplace Managed Client application switcher
Figure 3-6 The DEM Viewer reparented within an Eclipse view
Reparenting is more complex than just simply wrapping the Swing or AWT application for
provisioning. The utility function SWT provides does not allow an application to place just any
frame inside a composite. Instead, it passes the SWT_AWT class a Composite and it returns
back a Frame. Anything added to this frame appears inside the composite. Architecturally, this
method might differ from the way that many Swing and AWT applications are built, and some
restructuring might be required.
One way to restructure a Swing or AWT application is to re-create the top level Frame object
inside a Panel or a JPanel. Typically, it is feasible to copy the code completely from the
original frame to this new panel. This will probably work for about 90% of the code in the
frame. The other 10% uses features only available from a frame.
The code in Example 3-5 shows a complete Eclipse view class wrapping an AWT Frame
object.
Example 3-5 An Eclipse view wrapping a an AWT Frame object
//Pane1View.java
package com.ibm.wcttool.demviewer.pane1.views;
import java.awt.BorderLayout;
import java.awt.Frame;
import
import
import
import
import
org.eclipse.swt.SWT;
org.eclipse.swt.awt.SWT_AWT;
org.eclipse.swt.layout.GridLayout;
org.eclipse.swt.widgets.Composite;
org.eclipse.ui.part.ViewPart;
public class Pane1View extends ViewPart {
private static Frame
mFrame;
private static DEMViewPanel2 mPanel;
Chapter 3. ISVs with AWT or Swing applications
57
public Pane1View() {}
public void createPartControl(Composite parent) {
parent.setLayout(new GridLayout(1, true));
//Create a new Composite which will contain the AWT frame.
//Note: The style SWT.EMBEDDED should be used when creating this composite
Composite client = new Composite(parent, SWT.EMBEDDED);
GridUtils.setLayoutData(client,"fill=hv");
//Create a new AWT frame using the SWT utility class, SWT_AWT
//passing in the Composite that will contain that frame
mFrame = SWT_AWT.new_Frame(client);
mFrame.setLayout(new BorderLayout());
//Create the new AWT Panel, passing in the frame to its constructor
mPanel = new DEMViewPanel2(mFrame);
mFrame.add("Center", mPanel);
}
public void setFocus() {
mFrame.requestFocusInWindow();
}
}
In the DEM Viewer example application, there are two instances where a frame is required.
First, passing a frame to an internal variable by adding a WindowListener to perform a special
setup and cleanup and to capture when the frame is invoked and dismissed. Instead of
adding the listener to the class in which the code is, it is added to the passed-in frame.
Example 3-6 shows the difference between the old and new methods of adding
WindowListeners to the Frame.
Example 3-6 Difference between the old and new methods for adding WindowListeners to the Frame
//Old code
//SRTMFrame.java
this.addWindowListener(new WindowAdapter(){
public void windowClosing(WindowEvent e) { doFrameShut();
public void windowOpened(WindowEvent e) { doFrameStart();
}
);
//New Code
//DEMViewPanel2.java
mFrame.addWindowListener(new WindowAdapter(){
public void windowClosing(WindowEvent e) { doFrameShut();
public void windowOpened(WindowEvent e) { doFrameStart();
}
);
}
}
}
}
Note: The Frame passed back does not behave exactly the same as a normal AWT frame.
Some events might not occur as expected. Be sure to test for all conditions, or integrate
more fully, for example, expose the methods that the event listeners are calling, and then
trap the SWT equivalent message in the view and call the exposed functionality.
In the second instance, the original application is Swing based and uses a JFrame, not a
Frame. Menus are created then attached to a JMenuBar, which is then added to the JFrame.
Although a JMenuBar cannot be added to a Frame, in Swing, a JMenuBar is a control and can be
58
IBM Workplace Managed Client: ISV Integration Guide
added to a JPanel. If the JFrame has already been migrated to a JPanel, add the JMenuBar like
a normal control to the top of the JPanel. Figure 3-7 shows this.
Duplicated Menus
Duplicate Status Bars
Figure 3-7 The DEM Viewer application
In an AWT-based application, it might be more complicated, because adding menus to the
Frame created by SWT_AWT is not displayed. In addition, it is worth noting that when adding a
JMenuBar to a JPanel, the menus do not appear in the top menu bar. Instead, they are
duplicated within the Eclipse view, as shown in Figure 3-7. The status bar has also been
duplicated.
For a more seamless integration, where UI features such as menu bars and status bars are
reused rather than duplicated, see the next level of integration in 3.4, “Leverage” on page 60.
3.3.6 Deploying the application to Workplace Collaboration Services server
For instructions about how to export and deploy a Workplace Managed Client application to
the Workplace Collaboration Services server, follow the instructions in the white paper
Creating an application with the IBM Workplace Managed Client Developer Toolkit, available
at:
http://www.ibm.com/developerworks/workplace/library/wmc-toolkit-basic
Information is also provided by the Workplace Managed Client Developer Toolkit, accessible
through Eclipse by clicking Help → Help Contents → IBM Workplace Managed Client Tool
for Eclipse → Distributing applications and following the instructions.
After completing this, the application will be fully deployed to the server and will be
provisioned down the next time the Workplace Managed Client is loaded.
An alternative to doing a full deployment to a server is to test the application locally, using the
IBM Workplace Managed Client Developer Toolkit. The Creating an application with the IBM
Workplace Managed Client Developer Toolkit white paper also contains detailed instructions
about how to test a Workplace Managed Client application without deploying it to a Workplace
Collaboration Services server.
Chapter 3. ISVs with AWT or Swing applications
59
3.4 Leverage
Applications that more fully leverage the features of Workplace Managed Client provide a
more rich and uniform user experience and gain increased functionality and usability.
Features that the Workplace Managed Client provides include:
򐂰 Workplace Managed Client menus
򐂰 Workplace Managed Client status bar
򐂰 Enabling server-side definition of an application’s view layout by creating one portlet per
view
򐂰 Action bars, used to replace view toolbars
򐂰 Search bar
򐂰 Custom UI widgets
– Rich text editor
– Alerts
– Collapse bar
򐂰 Custom views
– Shelf views
We discuss the first three of these, menus, status bar, and centralized management of an
application’s layout, in the following sections. We discuss all of the remaining features in 2.4,
“Leverage” on page 30.
Note: The steps explained in each of the following sections assume that you have already
created an IBM Workplace application, as described in 3.3.1, “Lightweight integration of a
Swing or AWT application with Workplace Managed Client” on page 51. Also, we assume
that you created a view class that uses the utility function that SWT provides for Swing or
AWT application integration, as described in Example 3-5 on page 57.
We also assume that you have read through and performed the Workplace Managed
Client application configuration and provisioning steps described in 3.3.1, “Lightweight
integration of a Swing or AWT application with Workplace Managed Client” on page 51.
3.4.1 Contributing to the Workplace Managed Client menus
The utility function that SWT provides for Swing or AWT application integration is a quick and
easy way to have the DEM Viewer application appear within the Workplace Client Technology
workspace. However, using this method means that some Workplace Client Technology UI
features, such as the Workplace Client Technology context menus, are included and the
application might appear with duplicate UI features, which does not present the best user
experience. As shown in Figure 3-7 on page 59, in the Accommodate section, the File and
Edit menus are duplicated when the DEM Viewer application was reparented within the
Workplace Managed Client.
You can integrate the menu with Workplace Managed Client in one of the following ways:
򐂰 The menus can be integrated using existing Workplace Managed Client menu IDs.
򐂰 The menus can entirely replace the existing default Workplace Client Technology menus.
60
IBM Workplace Managed Client: ISV Integration Guide
Menus integrated with Workplace Managed Client menu bar using
existing Workplace Managed Client menu IDs
Integrating Swing or AWT application menus with the Workplace Managed Client menu bar
requires mapping application-specific menus to specific Workplace Managed Client menu
IDs. The IWorkplaceActionConstants class defines the Workplace Managed Client menu
IDs. Table 3-2 shows some of these.
Table 3-2 Menu IDs defined in the IWorkplaceConstants class
Constant value
Reference in menu tag as
FILE_MENUID = “file”
IWorkbenchActionConstants.M_FILE
path=“additions” and id=“file”
EDIT_MENUID = “edit”
IWorkbenchActionConstants.M_EDIT
path=“edit/<submenutitle>” and id=“<customString>
WINDOW_MENUID = “window”
IWorkbenchActionConstants.M_WINDOW
HELP_MENUID = “help”
IWorkbenchActionConstants.M_HELP
id=“help”
A complete listing of all available menu items is available in the Workplace Collaboration
Services 2.5.1 API documentation and also available in Appendix B, “IBM Workplace 2.5.1
menu IDs” on page 185.
Figure 3-8 shows the Swing-based DEM Viewer application menu integration with the
Workplace Managed Client menu bar.
DEM Viewer File -> Open menu
Figure 3-8 DEM Viewer Open menu integrated with Workplace Managed Client menu bar
Chapter 3. ISVs with AWT or Swing applications
61
Follow these steps to integrate the Swing or AWT menus with the Workplace Managed Client
menu bar:
1. Create an Eclipse action class in the Eclipse plug-in, created in 3.3.2, “Creating a new IBM
Workplace project” on page 51, to accommodate the Swing or AWT application within
Workplace Managed Client.
Note: The Eclipse action class must implement the IWorkbenchWindowActionDelegate
interface.
2. Copy the invoking code from the Swing listener class into the run() method of an inline
created Thread class.
The resulting class looks similar to the DEMFileOpenAction class in Figure 3-8 on page 61,
which creates a new Thread object to open a JFileChooser dialog box. Separate threads
are necessary because of conflicts that result from the different threading models used by
Swing and SWT. Direct calls from a SWT thread to a Swing thread (and vice versa) are
problematic.
If it is necessary for the SWT code to wait for the Swing code to terminate before
proceeding, a simple wait/notify mechanism can be used, as shown in Example 3-7.
Example 3-7 Partial implementation of an Eclipse action class
import com.ibm.wctdemo.awtint.step3.DEMViewPanel3;
import com.ibm.wctdemo.awtint.step3.DEMView3;
...
public class DEMFileOpenAction implements IWorkbenchWindowActionDelegate {
private IWorkbenchWindow window;
public DEMFileOpenAction() {
}
public void run(IAction action) {
Thread thread = new Thread(){
public void run() {
// get the Swing JPanel instance
DEMViewPanel3 mPanel = DEMView3.getMPanel();
mPanel.doFileOpen();
//notify the enclosing class instance that the thread has finished executing
DEMOpenAction.this.notify();
}
};
thread.start();
try {
//wait until the thread has finished executing
this.wait();
} catch (InterruptedException e) {
e.printStackTrace();
}
}
public void selectionChanged(IAction action, ISelection selection) {
}
public void dispose() {
}
public void init(IWorkbenchWindow window) {
this.window = window;
}
62
IBM Workplace Managed Client: ISV Integration Guide
Important Note: Using the syncExec() or asyncExec() functions on the SWT Display
class to get the Swing or AWT code to run in the SWT thread or using Thread.join()
for synchronization can cause UI threading issues. Rather than using these methods,
use a simple wait/notify mechanism.
3. The DEMFileOpen action calls the implementation of the doFileOpen() inline method in the
DEMViewPanel3 class, as shown in Example 3-8.
Example 3-8 The partial implementation of DEMViewPanel.java
//DEMViewPanel3.java
import javax.swing.JFileChhoser;
import javax.swing.JPanel;
mport com.ibm.wctdemo.srtm.view.SRTMFrame;
import com.ibm.wctdemo.srtm.view.SRTMPanel;
//...
public class DEMViewPanel3 extends JPanel implements PropertyChangeListener{
private Frame
mFrame;
private SRTMPanel mPanel;
private SRTMSession mSession;
public DEMViewPanel3(Frame frame){
mFrame = frame;
mStatus = new JLabel();
setLayout(new BorderLayout());
mPanel = new SRTMPanel();
add("Center", mPanel);
setSize(640, 480);
mFrame.addWindowListener(new WindowAdapter(){
public void windowClosing(WindowEvent e) {
doFrameShut();
}
public void windowOpened(WindowEvent e) {
doFrameStart();
}
});
setSession(SessionLogic.startSession());
}
public void doFileOpen(){
JFileChooser chooser = new javax.swing.JFileChooser();
chooser.setApproveButtonText("Open");
int returnVal = chooser.showOpenDialog(this);
if (returnVal != javax.swing.JFileChooser.APPROVE_OPTION){
return;
}
String fname = chooser.getSelectedFile().getAbsolutePath();
try {
FileLogic.loadMap(mSession, fname);
}
catch (IOException e){
SessionLogic.setStatus(mSession, e.toString());
}
}
//...
}
Chapter 3. ISVs with AWT or Swing applications
63
4. Modify the plugin.xml file of the Eclipse plug-in project in order to create the
org.eclipse.ui.actionSets extensions. Example 3-9 shows the Eclipse plugin.xml file
with an org.eclipse.ui.actionsets extension point definition.
Note: Action sets specify and organize the menu items being added into groups.
Example 3-9 Partial plugin.xml file for DEM Viewer with org.eclipse.ui.actionsets extension point
<plugin>
<extension
point="org.eclipse.ui.actionSets">
<actionSet
label="Sample Action Set"
visible="true"
id="com.ibm.wctdemo.awtint.step3.menus.actionSet">
<action
label="&amp;DEM File Open"
icon="icons/sample.gif"
class="com.ibm.wctdemo.awtint.step3.menus.actions.DEMOpenAction"
menubarPath="file/fileOpenGroup"
id="com.ibm.wctdemo.awtint.step3.menus.actions.DEMOpenAction">
</action>
</actionSet>
</extension>
...
</plugin>
Note: To learn more about the org.eclipse.ui.actionsets extension point, see:
http://help.eclipse.org/help31/index.jsp?topic=/org.eclipse.platform.doc.isv/guide
/workbench_basicext_actionSets.htm
5. Map the Action id parameter shown in Example 3-9 to the application-specific activity
pattern. This is required only when ISVs do not want the Swing or AWT
application-specific menus to be visible in rest of the Workplace Managed Client
applications.
For example, you might want the File → Open DEM menu to be globally visible so that the
user can open a DEM file from any context. But the File → Save DEM menu should only
be visible when user is viewing a DEM application.
Example 3-10 shows the sample Eclipse plugin.xml file with the Eclipse activities
extension point defined.
Example 3-10 Partial plugin.xml file showing mapping of Eclipse action ID with Eclipse activity pattern
<plugin>
<extension point="org.eclipse.ui.activities">
<activity
description="This is srtm activity"
name="com.ibm.workplace.srtm.activity"
id="com.ibm.workplace.srtm.activity"/>
<activityPatternBinding
activityId="com.ibm.workplace.srtm.activity"
pattern="com\.ibm\.wctdemo\.awtint\.step3\.menus/
com\.ibm\.wctdemo\.awtint\.step3\.menus\..*" />
</extension>
...
<plugin>
64
IBM Workplace Managed Client: ISV Integration Guide
Note: The mapping is performed using a activityPatternBinding. For more
information, refer to:
http://help.eclipse.org/help31/index.jsp?topic=/org.eclipse.platform.doc.isv/refer
ence/extension-points/org_eclipse_ui_activities.html
6. Configure and provision the Eclipse plug-in from the Workplace server. See 3.3,
“Accommodate” on page 50 for more details about application configuration and
provisioning.
Menus that entirely replace existing default Workplace Client
Technology menus
An alternate method for integrating Swing or AWT application menus with Workplace
Managed Client is to replace the existing Workplace Managed Client menus such as File and
Edit with the application-specific menus.
Note: Take care when replacing existing Workplace Managed Client platform menus.
Some menus such as Edit → Copy are context dependent. It makes sense to replace this
menu when the application’s context is in control. Other menus such as File → Open are
active for all contexts. We strongly discouraged modifying these because other Workplace
Managed Client applications might depend on these menus and their functionality can be
affected as a consequence.
Workplace Managed Client File -> Open menu replaced
with DEM Viewer menu
Figure 3-9 Workplace Managed Client Open menu replaced with DEM Viewer Open menu
To create a menu that replaces an existing menu, you need to create an inline Eclipse action
class within an Eclipse view class. The view class is stored within an Eclipse plug-in. For the
DEM Viewer example, the DEMFileOpenAction class, created in Example 3-7 on page 62, is
created within the DEMViewPanel3.java class created in Example 3-8 on page 63.
Chapter 3. ISVs with AWT or Swing applications
65
Follow these steps to replace the default Workplace Client Technology menus for the Swing
or AWT application:
1. Create an Eclipse action class by copying the code from the Swing listener into an inline
Eclipse action class. Example 3-11 shows the sample Eclipse view class with an inline
Eclipse action class defined to open the javax.swing.JFileChooser dialog box.
Note: The action class, DEMFileOpenAction, was created in Example 3-7 on page 62 to
display the Swing or AWT application within Workplace Managed Client.
Example 3-11 Partial implementation of DEMView3.java class with inner action class
//DEMView3.java
import java.awt.BorderLayout;
import java.awt.Frame;
import
import
import
import
import
import
...
org.eclipse.jface.action.Action;
org.eclipse.swt.SWT;
org.eclipse.swt.awt.SWT_AWT;
org.eclipse.swt.layout.GridLayout;
org.eclipse.swt.widgets.Composite;
org.eclipse.ui.part.ViewPart;
public class DEMView3 extends ViewPart{
private Frame
mFrame;
private DEMViewPanel3 mPanel;
public void createPartControl(Composite parent) {
parent.setLayout(new GridLayout(1, true));
Composite client = new Composite(parent, SWT.EMBEDDED);
GridUtils.setLayoutData(client, "fill=hv");
mFrame = SWT_AWT.new_Frame(client);
mFrame.setLayout(new BorderLayout());
mPanel = new DEMViewPanel3(mFrame);
Action openAction = new Action() {
public void run(){
Thread thread = new Thread(){
public void run() {
mPanel.doFileOpen();
DEMView3.this.notify();
}
};
thread.start();
try {
this.wait();
} catch (InterruptedException e) {
e.printStackTrace();
}
}
};
//...
}
...
}
66
IBM Workplace Managed Client: ISV Integration Guide
Example 3-8 on page 63 shows the actual implementation for the inline method
doFileOpen() of class DEMViewPanel3.
2. Call the setGlobalActionHandler() method on the action bar attached to the view site and
pass it the ID of the action just created. The Eclipse view class shown in Example 3-11 on
page 66 is modified in order to set the Eclipse global action handler.
Note: Example 3-12 shows the partially implemented Eclipse view class that replaces
the existing Workplace Managed Client File → Open menu with the DEM Viewer
specific File → Open menu.
Example 3-12 The partial implementation of Eclipse View class to set the Eclipse global action handler
import java.awt.BorderLayout;
import java.awt.Frame;
import org.eclipse.jface.action.Action;
import org.eclipse.swt.SWT;
import org.eclipse.swt.awt.SWT_AWT;
import org.eclipse.swt.layout.GridLayout;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.ui.part.ViewPart;
...
public class DEMView3 extends ViewPart{
private static Frame
mFrame;
private static DEMViewPanel3 mPanel;
public void createPartControl(Composite parent) {
parent.setLayout(new GridLayout(1, true));
Composite client = new Composite(parent, SWT.EMBEDDED);
GridUtils.setLayoutData(client, "fill=hv");
mFrame = SWT_AWT.new_Frame(client);
mFrame.setLayout(new BorderLayout());
mPanel = new DEMViewPanel3(mFrame);
//create a new Action class
Action openAction = new Action() {
public void run(){
mPanel.doFileOpen();
}
};
//replace the global action handler with the DEM Viewer action handler
getViewSite().getActionBars().setGlobalActionHandler(
"com.ibm.rcp.ui.filemenu.open", openAction);
//...
}
//...
}
Table 3-2 on page 61 shows the menu IDs to replace the existing Workplace Managed
Client menus with Swing or AWT application-specific menus.
3. Deploy the Eclipse plug-in to a Workplace Collaboration Services server and provision it
down to a client machine.
Chapter 3. ISVs with AWT or Swing applications
67
Note: See 3.3.6, “Deploying the application to Workplace Collaboration Services
server” on page 59 for more details about application configuration and provisioning.
Alternatively, launch the application locally using the Workplace Managed Client
Developer Toolkit. The following paper contains full instructions about how to do this:
http://www.ibm.com/developerworks/workplace/library/wmc-toolkit-basic
3.4.2 Status bar integration
The Swing-based DEM Viewer application uses its own status bar rather than the standard
Workplace Managed Client status bar. Figure 3-7 on page 59 shows this in the Accommodate
section. SWT provides a utility function to integrate Swing and AWT applications; it is a quick
way to have the DEM Viewer application appear within the Workplace Client Technology
context. However, using the utility also means that Workplace Client Technology UI features,
such as the Workplace Managed Client status bar, might appear more than once.
If all that is needed is a text-only status bar, it is relatively straightforward to create a
Workplace Managed Client status bar. In the status message handling code, an
IStatusBarManager must be retrieved and the text passed to it instead of the Swing status bar
control.
The IStatusBarManager can be retrieved from a variety of locations using Eclipse APIs. In the
DEMViewer example, IStatusBarManager was retrieved from the Eclipse ViewSite attached to
the ViewPart. A property was created for it on the main panel; this is where the status
handling code is kept. The view initialization makes the connection.
Figure 3-10 shows Swing-based DEM Viewer application with and application-specific status
message displayed on Workplace Managed Client status bar.
SWT application status message
displayed on Workplace Managed Client status bar
Figure 3-10 Swing-based DEM Viewer application with status messages
68
IBM Workplace Managed Client: ISV Integration Guide
Note: This Swing-based DEM Viewer example displays the application-specific status
messages on Workplace Managed Client status bar. In a more complicated example,
where the status bar contains several other controls for displaying different types of
information or buttons to invoke other actions, it is necessary to convert those controls to
SWT. They can then be added as contributors to the system status bar.
To set the text into the Workplace Managed Client status bar, perform the following steps:
1. Modify the Eclipse ViewPart in the Eclipse plug-in that was created in Example 3-7 on
page 62 to display the Swing or AWT application within the Workplace Managed Client.
Use the same view class created in Example 3-11 on page 66.
Note: Setting the Eclipse StatusLineManager for the JPanel implementation displays
the application status message on the Workplace Managed Client status bar rather
than on a custom status bar.
Example 3-13 shows the Eclipse view class modified in order to set the Eclipse
StatusLineManager for a Jpanel instance.
Example 3-13 The partial implementation of Eclipse view class to set StatusLineManager
//DEMView3.java
import java.awt.BorderLayout;
import java.awt.Frame;
import org.eclipse.jface.action.Action;
import org.eclipse.swt.SWT;
import org.eclipse.swt.awt.SWT_AWT;
import org.eclipse.swt.layout.GridLayout;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.ui.part.ViewPart;
import com.ibm.wctdemo.awtint.step3.DEMViewPanel3;
import com.ibm.wctdemo.awtint.step3.Step3Plugin;
//...
public class DEMView3 extends ViewPart{
private Frame
mFrame;
private DEMViewPanel3 mPanel;
public void createPartControl(Composite parent){
parent.setLayout(new GridLayout(1, true));
Composite client = new Composite(parent, SWT.EMBEDDED);
GridUtils.setLayoutData(client, "fill=hv");
mFrame = SWT_AWT.new_Frame(client);
mFrame.setLayout(new BorderLayout());
mPanel = new DEMViewPanel3(mFrame);
mFrame.add("Center", mPanel);
Step3Plugin.getDefault().setSession(mPanel.getSession());
//retrieve the statusLineManager and store it
mPanel.setStatusLineManager(getViewSite().getActionBars().getStatusLineManager());
//...
}
//...
}
2. Remove the JLabel that acted as the Swing status bar.
Chapter 3. ISVs with AWT or Swing applications
69
Note: Updates to status messages are triggered by a property changing on the session
object. A listener is registered to listen for property change events and must be rerouted
to fill the IStatusBarManager object instead of JLabel. At this point, it is no longer
needed.
Make these changes in the DEMViewpanel3 class shown in Example 3-8 on page 63.
Example 3-14 shows the implementation for the DEMViewPanel3 class that is called from
DEMView3 action.
Example 3-14 Partial implementation of DEMViewPanel3.java with JPanel status message integration
import javax.swing.JPanel;
import org.eclipse.jface.action.IStatusLineManager;
import org.eclipse.swt.SWT;
import com.ibm.wctdemo.srtm.view.SRTMFrame;
import com.ibm.wctdemo.srtm.view.SRTMPanel;
public class DEMViewPanel3 extends JPanel implements PropertyChangeListener{
private Frame
mFrame;
private SRTMPanel
mPanel;
private SRTMSession
mSession;
private IStatusLineManager mStatusLineManager;
public DEMViewPanel3(Frame frame){
mFrame = frame;
/* this was used before WMC StatusLine integ
mStatus = new JLabel(); */
setLayout(new BorderLayout());
mPanel = new SRTMPanel();
add("Center", mPanel);
setSize(640, 480);
mFrame.addWindowListener(new WindowAdapter(){
public void windowClosing(WindowEvent e) {
doFrameShut();
}
public void windowOpened(WindowEvent e) {
doFrameStart();
}
});
//start a new session, which will be used to notify listeners of changes
//to generic properties
setSession(SessionLogic.startSession());
}
public void setSession(SRTMSession session){
if (mSession != null){
mSession.removePropertyChangeListener(this);
}
mSession = session;
mPanel.setSession(mSession);
if (mSession != null){
//register this class as a listener on the session object
mSession.addPropertyChangeListener(this);
}
}
70
IBM Workplace Managed Client: ISV Integration Guide
//this method is called by the Session object when a property change event is fired
public void propertyChange(PropertyChangeEvent ev){
/* was used before integrating with WMC StatusBar
if (ev.getPropertyName().equals("status")){
mStatus.setText(mSession.getStatus());
doLayout();
}*/
if (ev.getPropertyName().equals("status")){
Display.getDefault().asyncExec(new Runnable(){
public void run() {
mStatusLineManager.setMessage(mSession.getStatus());
doLayout();
}
});
}
}
public IStatusLineManager getStatusLineManager(){
return mStatusLineManager;
}
public void setStatusLineManager(IStatusLineManager statusLineManager){
mStatusLineManager = statusLineManager;
}
//...
}
Note: Code in an AWT or Swing thread cannot directly invoke methods on SWT objects
because they use different threading models. Instead, all code must be invoked using
either the Display.syncExec() or Display.asyncExec() methods.
3. Deploy the Eclipse plug-in to the Workplace server and provision it down to a client
machine. See 3.3.6, “Deploying the application to Workplace Collaboration Services
server” on page 59 for more details about application configuration and provisioning.
3.4.3 Defining one portlet per view
In 3.3, “Accommodate” on page 50, we modified the Swing-based DEM Viewer application to
take advantage of the Workplace Managed Client provisioning engine. The application was
wrapped in a single Eclipse view and automatically defined as a single portlet when deployed
on the Workplace Collaboration Services server using the mechanisms supplied by the
Workplace Managed Client Developer Toolkit.
This approach does not take advantage of more powerful capabilities of Workplace Managed
Client such as centralized management of a client application’s layout. You can achieve this
functionality by separating an application into multiple Eclipse views and arranging the layout
of those views using the Developer Toolkit’s Page Layout Editor. See Figure 3-12 on page 73.
With one portlet per view, ISVs can also control layout based on roles.
After this has been done, layout modifications to the application can be handled by
non-technical users on the Workplace Collaboration Services server, with the changes being
automatically propagated to all users.
Chapter 3. ISVs with AWT or Swing applications
71
Note: Administrator access is required to alter the layout of an application.
Rearranging a Swing user interface using multiple Eclipse views
To enable centralized management of an application’s layout, partition the user interface into
multiple Eclipse views, arranging the various controls into their logical groupings. The DEM
Viewer application can be arranged into two logical groups:
򐂰 User controls
򐂰 Graphical display
Create a Swing JPanel instance for each group of controls and integrate it with the Workplace
Managed Client application using an Eclipse view, as described in “Reparenting a Swing or
AWT application into the Workplace Managed Client UI” on page 56.
Creating a page layout project with multiple Eclipse views
Perform the following steps to create a new IBM Workplace project:
1. In the Eclipse IDE, select File → New → Project → IBM Workplace → Workplace
Managed Client Application Project, and click Next. See Figure 3-2 on page 52.
2. Give the project a name, for example, com.ibm.wcttool.demviewer, and a Display Name,
for example, DEM Viewer, as shown in Figure 3-3 on page 52. Select an icon to be
associated with the application if necessary. Click Next.
3. Choose the two-pane view page layout highlighted in Figure 3-11. Make sure that the
Automatically create default views option is not selected. Click Next.
Figure 3-11 Selecting two-pane view and not automatically creating the default views
4. At this point, the application plug-in with the two views should be already present in the
Eclipse workspace. Now, select the views that will be inserted into each of the place
holders in the page layout. To do this:
a. Click Browse Workspace.
b. Choose the ID of the view to be placed in the layout. Click Next.
c. Repeat step b for each view to be added to the page layout, and click Finish.
This creates a page layout project, which can be manipulated using the Page Layout
Editor, as shown in Figure 3-12 on page 73.
72
IBM Workplace Managed Client: ISV Integration Guide
Figure 3-12 Page Layout Editor with two views arranged vertically
5. Specify the desired configuration parameters for each view using the Page Layout Editor.
Table 2-3 on page 33 describes the available parameters. For a full description of all
portlet variables, see:
http://www.ibm.com/developerworks/lotus/library/wmc-layouts/index.html
For the DEM Viewer sample, set the style parameter for the bottom view to NO_TITLE.
This removes the title bar from the view.
6. Deploy the Workplace Managed Client application to the Workplace Collaboration
Services server and provision it down to a client machine. Figure 3-13 on page 74 shows
the Swing-based DEM Viewer application with separate Eclipse views provisioned to a
client’s desktop.
Chapter 3. ISVs with AWT or Swing applications
73
Eclipse View with
Swing Slider
Controls
Eclipse View with
Swing Graphics Control
Figure 3-13 DEM Viewer application with multiple Eclipse views, arranged using a page layout
3.4.4 Converting Swing or AWT controls to SWT
For complete user interface integration with the Workplace Managed Client, at some point all
controls should be converted to SWT. This does not have to be done immediately. As seen in
this chapter, a fully working application can be integrated in Workplace Managed Client with a
minimal use of SWT.
However, there are several compelling reasons to build and modify the Swing-based
applications with the full integration in mind:
򐂰 From a visual standpoint, full integration removes a disconnect between the Swing or AWT
interface and the SWT interface. The integrated application would appear the same as the
rest of the platform.
򐂰 Attributes set globally by the platform, such as colors, fonts, and other “skin” elements,
can be unintentionally inherited by Swing-based application.
򐂰 Doing an additional pass to render everything in SWT allows for the original richness to be
reestablished.
򐂰 As explained earlier in this chapter, the differences in threading event models might also
cause complications. Not all of these are readily apparent. When fully converted over to
SWT, all the code resides in one model, and there are no interaction errors.
򐂰 From a functional standpoint, the Swing-based application integrated with SWT will
perform faster and with less errors. The SWT libraries are based on native platform
libraries, which are generally faster and less memory hungry than AWT and Swing.
򐂰 SWT gives the applications raw components for UI rendering. On top of that are JFace
components that provide more abstract methods of dealing with certain, usually list-based,
components. AWT/Swing contains a subset of the features of both solutions.
If the original application was written using the model view controller (MVC) design pattern, it
is not hard to replace just the view layer. The conversion process is relatively straightforward.
74
IBM Workplace Managed Client: ISV Integration Guide
Notes:
򐂰 To learn more about Eclipse, see:
http://www.eclipse.org/
򐂰 To learn more about Eclipse SWT, see:
http://www.eclipse.org/swt
3.5 Exploit
As stated in the introduction, complete seamless integration occurs as an ISV chooses to fully
exploit the capabilities of Workplace Managed Client. For example, if writing plug-ins that are
more than simple wrappers, most or even all of the code is structured to the Workplace
programming model in order to exploit the client technologies fully. By employing the APIs and
available models, an ISV can write a matched set of portlets, plug-ins, EJB services, and data
source definitions that take full advantage of all attributes of the IBM Workplace Client
Technology infrastructure.
Application components that are written in this manner gain several benefits, for example, the
ability to dynamically share capabilities such as online awareness, and participate in
spanning services, such as full text indexing. In most cases, ISVs that have existing
applications or components are expected to gradually extend into this space as they match
needs and requirements to the appropriate programming model constructs.
Workplace Managed Client provides a number of features that enable an ISV to extend its
application in very powerful ways:
򐂰 Document libraries for remote storage and document sharing
Workplace Managed Client document libraries consist of both local and remote storage in
a folder structure for sharing documents among a group or team. Workplace Managed
Client provides an API for manipulating files and folders in a document library.
򐂰 Online awareness
There is a online/offline awareness API that can be used to inform an application when the
client is online, offline, or when it is about to transition between the two. This can be useful
for completing transactions if connectivity is about to change and close down open
connections. After the operation has completed, the connection to the database can be
reestablished.
򐂰 Synchronizing client application data
There is an API that taps into the client's synchronization framework. Based on timetables
set in the client’s preferences, the application can be informed of when to synchronize its
data. The actual data synchronization is performed by the application itself.
򐂰 Database access, both local and remote
Workplace Managed Client comes with its own Cloudscape relational database. After the
application is fully moved to the Workplace Managed Client platform, it does not need to
always have a connection to the remote database; it simply needs to connect to the local
Cloudscape database. The rest of the application code does not need to be changed.
򐂰 Messaging and notifications
Workplace Managed Client provides a full mail API for sending and manipulating mail
messages.
Chapter 3. ISVs with AWT or Swing applications
75
򐂰 Securing a client application
The IBM Workplace Client Technology platform is a secure platform that protects
application data. Single sign-on with the operating system capabilities are built into the
rich client by default. The local Cloudscape database is encrypted using the users’
credentials, which must be retrieved using the credential store API.
All of these features apply to any fully integrated Workplace Managed Client application. They
are not specific to integrating an existing Swing or AWT application. We cover all of these
points in detail in Chapter 6, “Exploiting IBM Workplace Managed Client” on page 139.
3.6 Summary
This chapter has shown how an existing Swing or AWT application can be gradually merged
with the Workplace Managed Client as time, finances, and resources allow. At each of the
four levels of integration, we describe how a Swing or AWT application can benefit from an
integration with Workplace Managed Client, what the integration points are, and what new
features and services Workplace Managed Client offers to ISVs.
3.7 URLs referenced in this chapter
Table 3-3 lists the URLs referred to in this chapter.
Table 3-3 List of URLs referred to in this chapter
76
What
Where
IBM Workplace Managed Client Developer
Toolkit
http://www.alphaworks.ibm.com/tech/wmctool
kit
Creating an application with the IBM Workplace
Managed Client Developer Toolkit
http://www.ibm.com/developerworks/workplac
e/library/wmc-toolkit-basic
To learn more about
org.eclipse.ui.actionsets extension points
http://help.eclipse.org/help31/index.jsp?t
opic=/org.eclipse.platform.doc.isv/guide/w
orkbench_basicext_actionSets.htm
Information about mapping using an
activityPatternBinding
http://help.eclipse.org/help31/index.jsp?t
opic=/org.eclipse.platform.doc.isv/referen
ce/extension-points/org_eclipse_ui_activit
ies.html
Full description of portlet variables
http://www.ibm.com/developerworks/lotus/li
brary/wmc-layouts/index.html
IBM Workplace Managed Client: ISV Integration Guide
4
Chapter 4.
ISVs with Web and portal
applications
This chapter describes the various options for integrating Web and portal applications with
the IBM Workplace Client Technology framework. We explain how, with very little effort or
coding, Web and portal applications can take advantage of features such as:
򐂰 Wrapping a Web or portal application as an Eclipse application
򐂰 Authentication
򐂰 Web Services for Remote Portlets
© Copyright IBM Corp. 2006. All rights reserved.
77
4.1 Overview
This chapter discusses how a Web or portal application can take advantage of the features
offered by the Workplace Managed Client. These include:
򐂰 Wrapping a Web application as a Workplace Managed Client application in order to
present it in the same manner as all other applications in the platform. This removes the
shift in context necessary for traditional Web-based applications where, for example, a
user would have to go from a separate Web browser to a word processor, both of which
are completely disconnected. In this case, they all run on the same platform, and all are
simply applications that the user can use to perform their job with no distinction being
made between them.
򐂰 Automatic authentication with the Web or portal server.
򐂰 Using the Workplace Managed Client as a Web Services for Remote Portlet consumer.
4.1.1 What are Web and portal applications?
Web and portal applications are applications that run on an application or portal server. The
user interface (UI) is rendered in a Web browser on the client machine. This type of
application provides excellent reach and a low total cost of ownership compared to the
expense of a rich native UI and experience.
4.1.2 What is WSRP?
Web Services for Remote Portlets (WSRP) is a Web services standard that allows for the
plug-and-play of portals, other intermediary Web applications that aggregate content, and
applications from disparate sources. For more information about WSRP, see:
http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp
4.1.3 Web and portal integration levels
Trade-offs must be made between how quickly an existing application can be deployed on a
new platform and how well it can be integrated with that platform.
This chapter describes how the Workplace Managed Client can be used to access portal
applications. Multiple techniques are explained for accessing applications at different levels of
integration. This includes the embedded Web browser to access Workplace Collaboration
Services and WSRP to access JSR 168 portlets. We use the different techniques to explain
the various stages of application integration.
Table 4-1 on page 79 lists the benefits of the various integration levels and provides some
examples of their application.
78
IBM Workplace Managed Client: ISV Integration Guide
Table 4-1 The benefits of the various integration levels
Increase of time, effort, and synergy →
Coexist
Accommodate
Leverage
Exploit
Minimal to no development
effort.
Simple but effective
blended user experience.
Client management
frameworks (HTTP
authentication).
Separate browser, interact
using copy/paste and file
storage.
Component provisioning by
policy.
Exploitation of rich
repository spanning
services, UI components,
and business components.
Displayed in embedded
browser.
Authentication with Web or
portal platform.
Custom WSRP viewer and
producer.
Use document libraries,
mail notification, data store,
synchronization, and so on.
Provisioned WSRP
portlets.
4.2 Coexist
The simplest level of integration is coexistence. This requires no changes at the code level.
The application runs on the client’s desktop through a browser, just as it always has.
Web and portal applications are accessed in a browser and operations such as copying to the
clipboard can be used to share information. Two coexist integration options are:
򐂰 A separate browser can be launched from the user's desktop.
򐂰 The Workplace Managed Client can launch an embedded Web browser that provides
access to the applications.
Figure 4-1 on page 80 shows an application that is launched through a Web browser from
within Workplace Managed Client.
Chapter 4. ISVs with Web and portal applications
79
Embedded Browser
Figure 4-1 The Web application launched within Workplace Managed Client
4.3 Accommodate
In many cases, it might make sense to launch a Web or portal application from the application
launcher side bar, rather than opening a browser and finding and selecting a bookmarked
URL. For example, because many portal servers do not offer much support for bookmarking
individual applications, if there is a Web application that people fulfilling a certain role use
very frequently, it is useful to provide just those people with a custom Workplace Managed
Client application that can launch a browser directly to the online application.
Launching a Web or portal application using a switcher view
Programmatically launching the Workplace Managed Client’s embedded browser and
executing this code from a Workplace Managed Client application is most easily achieved
using a switcher view. A switcher view is a very simple Eclipse view class that, upon receiving
the window focus, transfers control to another Eclipse view or Composite class. In 2.3,
“Accommodate” on page 21, we show how a switcher view can be used to display an Eclipse
perspective. This section describes how a simple switcher view can be used to launch an
embedded browser that opens the Workplace Collaboration Services server login page.
Three simple steps are required in order to create a switcher view that loads a browser to a
given URL:
1. Create an IBM Workplace project with a single, automatically generated view.
2. Launch the embedded browser from the view’s setFocus method.
3. Deploy the application to the Workplace Collaboration Services server.
80
IBM Workplace Managed Client: ISV Integration Guide
4.3.1 Creating a new IBM Workplace project
To create a new IBM Workplace project, perform the following steps:
1. Select File → New → Project → IBM Workplace → Workplace Managed Client
Application Project, and click Next. See Figure 4-2.
Figure 4-2 Creating a new IBM Workplace Eclipse project
2. Give the project a name, for example,. com.ibm.wcttool.web and a Display Name, such
as MyWorkplace, as shown in Figure 4-3. If there is an icon that needs to be associated
with the application, you can also select that in this window. Click Next.
Figure 4-3 Setting the Project name and Display Name
Note: The application Display Name and icon appear on the application switcher bar on
the left side of Workplace Managed Client. See Figure 4-6 on page 85.
3. Choose the single view page layout and Automatically create default views, as shown
in Figure 4-4 on page 82. Click Finish.
Chapter 4. ISVs with Web and portal applications
81
Figure 4-4 Selecting the single view layout and to automatically create the default view class
The result of these actions creates three new projects, a feature project, a page layout
project, and a plug-in project, as shown in Figure 4-5 on page 83:
– The feature project, com.ibm.wcttool.web, defines what plug-ins should be packaged
as part of the Workplace Managed Client application.
– The page layout project, com.ibm.wcttool.web.MainPage, manages the different pages
and views (though only one of each is used in this example).
– The plug-in project, com.ibm.wcttool.web.pane1, contains the Eclipse view class to be
placed in the single page, com.ibm.wcttool.web.pane1.views.Pane1View.
The view at the top left of Figure 4-5 on page 83 shows the standard Package Explorer
view for the plug-in perspective with which many Eclipse users are familiar. At the bottom
left is a view provided by the Workplace Managed Client Developer Toolkit, which nicely
groups all the projects belonging to a single Workplace Managed Client application
together and can be used either instead of, or in addition to, the Package Explorer. To
show this view, select Window → Show → View → Other → WMC Tools → WMC
Application Navigator.
82
IBM Workplace Managed Client: ISV Integration Guide
Feature Project
Page Layout Project
Plug-in Project
Workplace Managed Client Application Navigator View
Figure 4-5 Initial project view of application project, showing both Package Explorer and Application Navigator views
4.3.2 Launching the embedded browser
In the previous section, a default Eclipse view was created by the Developer Toolkit wizards
called com.ibm.wcttool.web.pane1.views.Pane1View. This class contains a method,
setFocus, that is called by the platform when the view receives the focus. In order to launch
the embedded browser, this setFocus method must be augmented with the code in
Example 4-1 on page 84.
This particular example opens the Workplace Managed Client embedded browser at the URL
of the Workplace Collaboration Services server to which the client is connected, but it can be
opened at any valid URL:
1. First, an instance of the ILaunchContext interface is created using the
LaunchBrowserFactory, passing the URL to be opened to the createLaunchContext
method.
2. Second, an instance of the ILaunchBrowser interface is instantiated using the
LaunchBrowserFactory.getBrowserInstance method.
Chapter 4. ISVs with Web and portal applications
83
3. Finally, the ILaunchBrowser.launch method is called, with the launch context being
passed to it.
Example 4-1 Eclipse view class launches Workplace Managed Client browser
import
import
import
import
import
import
org.eclipse.swt.widgets.Composite;
org.eclipse.ui.part.ViewPart;
com.ibm.rcp.platform.api.PlatformContext;
com.ibm.rcp.ui.browser.core.api.ILaunchBrowser;
com.ibm.rcp.ui.browser.core.api.ILaunchContext;
com.ibm.rcp.ui.browser.core.api.LaunchBrowserFactory;
public class Pane1View extends ViewPart {
//constructor
public Pane1View() {
}
//nothing to do in this method
public void createPartControl(Composite parent) {
}
//
public void setFocus() {
handleLaunchSimple();
}
private void handleLaunchSimple() {
try {
String portalUrl = PlatformContext.getPortalURL();
//make sure that the portal url points to the Workplace URL
if(!portalUrl.endsWith("/lwp/workplace") &&
!portalUrl.endsWith("/lwp/myworkplace")){
portalUrl += "/lwp/myworkplace";
}
portalUrl.replaceAll("//lwp","/lwp");
ILaunchContext launchContext = LaunchBrowserFactory. createLaunchContext (
portalUrl);
// launch the WCT browser
ILaunchBrowser launchBrowser = LaunchBrowserFactory.getBrowserInstance();
launchBrowser.launch(launchContext);
} catch (Exception e) {
e.printStackTrace();
}
}
...
}
This code is all that is necessary to launch the embedded browser with a simple URL. One
drawback of this method is that it does not authenticate with the portal server, so users are
required to enter their credential information, as in Figure 4-6 on page 85. Given that the
users are already logged in to the Workplace Managed Client, this should technically not be
necessary. In the next section, we discuss mechanisms that allow automatic authentication
with the portal server, which enable a browser to be opened directly to a Web or portal
application without having to authenticate manually.
84
IBM Workplace Managed Client: ISV Integration Guide
Figure 4-6 Embedded browser launched from a Workplace Managed Client application
4.3.3 Deploying the application to Workplace Collaboration Services server
For instructions for how to export and deploy a Workplace Managed Client application to the
Workplace Collaboration Services server, follow the instruction in the white paper Creating an
application with the IBM Workplace Managed Client Developer Toolkit, available at:
http://www.ibm.com/developerworks/workplace/library/wmc-toolkit-basic
Information is also provided by the Workplace Managed Client Developer Toolkit, accessible
through Eclipse by clicking Help → Help Contents → IBM Workplace Managed Client Tool
for Eclipse → Distributing applications and following the instructions.
After completing this, the application is fully deployed to the server and will be provisioned
down the next time the Workplace Managed Client is loaded.
An alternative to doing a full deploy to a server is to test the application locally, using the IBM
Workplace Managed Client Developer Toolkit. The Creating an application with the IBM
Workplace Managed Client Developer Toolkit white paper also contains full instructions for
testing a Workplace Managed Client application without deploying it to a Workplace
Collaboration Services server.
4.3.4 Web Services for Remote Portlets (WSRP)
WSRP support for the rich client is currently available as a Technology Preview for IBM
Workplace Client Technology V2.5.1. It enables server-managed deployment and client-side
aggregation of WSRP applications. This Technology Preview is the initial IBM Workplace
offering of technology based on the WSRP standard. The Technology Preview consists of a
WSRP viewer for the rich client. The WSRP viewer is an implementation of the WSRP
consumer, as defined by the WSRP Version 1.0 specification. WSRP viewer runs on both the
Microsoft Windows and Linux versions of the managed client. Using these components as
Chapter 4. ISVs with Web and portal applications
85
building blocks, ISVs can build new features and applications by seamlessly aggregating
remote WSRP application views with other types of rich client platform views.
One of the benefits of the WSRP viewer is the ability to render JSR 168 portlets without
Important: This section provides an overview and describes some of the important
concepts of WSRP. The WSRP Technology Preview provides complete instructions and
details. The Web Services for Remote Portlets (WSRP) Technology Preview for
Workplace Managed Client will be made available for use with IBM Workplace Managed
Client 2.6. The WSRP Technology Preview 2.5.1 is part of the IBM Workplace Managed
Client 2.5.1 Technology Preview package. This package will remain at the 2.5.1 level and
will not be updated for Release 2.6. Instructions of how to make the WSRP Technology
Preview work with Release 2.6 will be posted on developerWorks at:
http://www.ibm.com/developerworks/workplace/products/clienttechnology/
IBM Business Partners will be able to obtain the IBM Workplace Managed Client 2.5.1
Technology Preview package and the IBM Workplace Managed Client 2.6 through the IBM
Software Access Catalog on IBM PartnerWorld at:
http://www.developer.ibm.com/isv/welcome/guide/value.htm
Clients who want to obtain the IBM Workplace Managed Client 2.5.1 Technology Preview
package should contact their IBM Sales representative.
developing or modifying any code. Instead, the viewer is provided and must be configured to
render specific portlets in the appropriate layout.
The Java Standardization Request 168 (JSR 168) defines a portlet specification, for example,
the window state, portlet mode, or different mechanisms for the portlet to access transient
and persistent data.
The WSRP viewer is a Workplace Managed Client feature and can be configured and
deployed like any other feature. Each WSRP viewer can access one JSR 168 portlet.
Figure 4-7 on page 87 displays two WSRP viewers on a single page embedded within a
Workplace Managed Client application.
86
IBM Workplace Managed Client: ISV Integration Guide
WSRP Viewer 1
WSRP Viewer 2
Figure 4-7 WSRP viewers embedded in Workplace Managed Client
In order to create these views in Workplace Managed Client, two new portlets need to be
defined with WSRP viewer parameters. The portlets and page can be created using the
Workplace Managed Client Developer Toolkit, as described in 4.3.1, “Creating a new IBM
Workplace project” on page 81.
The WSRP Technology Preview includes instructions and xmlaccess scripts for creating and
provisioning two portlets stacked horizontally on a page. In addition to this setup, the
following configuration is also required:
򐂰 Each portlet that is going to be consumed must be enabled for WSRP and its handle
retrieved. For IBM WebSphere Portal server, refer to the WebSphere Portal for
Multiplatforms Information Center, available at:
http://publib.boulder.ibm.com/pvc/wp/502/ent/en/InfoCenter/index.html
򐂰 JSR 168 and WSRP must be enabled on the WebSphere Portal server included with
Workplace Collaboration Services.
After the WSRP equivalent portlets and the application page is created, the Web application
needs to be deployed to the Workplace Collaboration Services server using the instructions
described in 4.3.3, “Deploying the application to Workplace Collaboration Services server” on
page 85.
Chapter 4. ISVs with Web and portal applications
87
Notes:
򐂰 Learn more about Web Services for Remote Portlets (WSRP) in the following
developerWorks article:
http://www.ibm.com/developerworks/webservices/library/ws-wsrp/
򐂰 For the final JSR 168 specification, see:
http://www.jcp.org/aboutJava/communityprocess/final/jsr168/
http://developers.sun.com/prodtech/portalserver/reference/techart/jsr168/
4.4 Leverage
The next level of integration is to leverage more of the capabilities of the platform services
that are available in IBM Workplace Client Technology. This involves using more fully the
extra capabilities offered by Workplace Managed Client. Some of these include:
򐂰 Enabling server-side definition of an application’s view layout by creating one portlet per
view
򐂰 Authentication
򐂰 Workplace Managed Client menus
򐂰 Search bar
򐂰 Custom UI widgets
– Rich text editor
– Alerts
– Collapse bar
򐂰 Custom views
– Shelf views
򐂰 Personalities and personality startup
This chapter discusses server authentication and adding a search bar that integrates with a
browser. For example, an ISV with a Web or portal application might want to add single
sign-on capabilities for an HTTP service using the credential store, or they might want to use
Workplace Managed Client custom controls such as search bar for a unique look and feel.
We discuss the other features in the proceeding chapters.
Note: Workplace Managed Client also contains support to run and develop applications for
Workplace Client Technology, Micro Edition - Enterprise Offering. This includes an
integrated Web application container to run servlets and JSPs locally.
To learn more about how to develop applications using Workplace Client Technology, Micro
Edition - Enterprise Offering, refer to the IBM Redbook IBM Workplace Client Technology
Micro Edition Version 5.7.1: Application Development and Case Study, SG24-6496,
available at:
http://www.redbooks.ibm.com/abstracts/sg246496.html
The steps explained in each of the following sections assume that an IBM Workplace
application has already been created, as described in 4.3, “Accommodate” on page 80. Also,
we assume that you created an Eclipse view class to launch the Embedded browser within
88
IBM Workplace Managed Client: ISV Integration Guide
Workplace Managed Client, as described in 4.3.2, “Launching the embedded browser” on
page 83.
We also assume that you have read through and performed the Workplace Managed Client
application configuration and provisioning steps, as described in 4.3.3, “Deploying the
application to Workplace Collaboration Services server” on page 85.
4.4.1 HTTP authenticated application
In 4.3, “Accommodate” on page 80, we discuss an example that launches the embedded
browser directed at http://<workplaceServerURL>/lwp/myworkplace. As can be seen, the
URL points to the protected site, and the user will be always prompted to supply a user name
and password. This request for user credential information can be programmatically satisfied
using the credential store, form-based authentication, and the LTPA token support provided
by the Workplace Managed Client.
Note: Lightweight Third Party Authentication (LTPA) is specific to IBM Lotus Domino and
IBM WebSphere products. The LTPA token is a cookie that can be added to the embedded
browser to authenticate with a Domino or WebSphere server. For more information, see:
http://www.ibm.com/developerworks/ibm/library/it-0101art2
To authenticate with other platforms, see the documentation that comes with those
products.
IBM Workplace rich client products use the local credential store to store user name and
password credentials. Credentials stored within the local store are available only to the
system that hosts the file, making it particularly suitable for sensitive credentials. The first
time a user successfully authenticates with Workplace Managed Client, which also
authenticates with Workplace Collaboration Services, the user name and password are
stored in the credential store. This credential is used in the next example, where the browser
is launched to open the Workplace Collaboration Services home page. By using the LTPA
token, the user is not challenged for their user name and password.
The LTPA token is retrieved from IHttpFormLoginContext, which is then assigned to the
browser ILaunchContext.
Note: By storing the credential, a user is only prompted once for a user name and
password and all subsequent logins can be accomplished programmatically.
We use the application example described in 4.3.2, “Launching the embedded browser” on
page 83 as a starting point for the following examples. To log in to an HTTP authenticated
application programmatically, perform the following steps:
1. Add com.ibm.rcp.security.core and com.ibm.rcp.apache.httpclient as plug-in
dependencies in the Eclipse plugin.xml file. This plugin.xml file was generated when the
Workplace Managed Client application project was created, as described in 4.3.1,
“Creating a new IBM Workplace project” on page 81. Example 4-2 on page 90 shows the
Eclipse plugin.xml file with the added dependency for these plug-ins.
Chapter 4. ISVs with Web and portal applications
89
Example 4-2 Partial Eclipse plugin.xml file with dependencies
<requires>
<import plugin="com.ibm.rcp.security.core"/>
<!-- needs to import the plugin com.ibm.rcp.net.apache.httpclient to work
with httpclient Cookie. -->
<import plugin="com.ibm.rcp.net.apache.httpclient"/>
<!-- needs to add the browser dependencies to launch the embedded browser -->
<import plugin="com.ibm.rcp.ui"/>
<import plugin="com.ibm.rcp.ui.browser"/>
<import plugin="com.ibm.rcp.ui.browser.core"/>
...
</requires>
2. Modify the Eclipse view class that was created in 4.3.2, “Launching the embedded
browser” on page 83 to retrieve the credentials for the HTTP form-based application.
This Eclipse view class was automatically generated when the Workplace Managed Client
application project was created. The method retrieveCredential() in Example 4-3
shows how to get the user credentials for the HTTP host.
Example 4-3 Partial implementation of view class with method to retrieve credentials for HTTP host
//Pane1View.java
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.NameCallback;
import javax.security.auth.callback.PasswordCallback;
import javax.security.auth.callback.UnsupportedCallbackException;
import javax.security.auth.login.LoginException;
import com.ibm.rcp.platform.api.PlatformContext;
import com.ibm.rcp.platform.api.PlatformContext.NoDataAvailableException;
import com.ibm.rcp.security.api.cred.ICredential;
import com.ibm.rcp.security.api.cred.ICredentialManagerFactory;
import com.ibm.rcp.security.api.cred.IHostCredentialManager;
import com.ibm.rcp.security.api.cred.IPasswordCredential;
import com.ibm.rcp.security.api.http.login.IHttpFormLoginContext;
import com.ibm.rcp.security.api.http.login.IHttpFormLoginContextFactory;
import com.ibm.rcp.security.api.login.LtpaCookieCallback;
import org.apache.commons.httpclient.Cookie;
//...
public class Pane1View extends ViewPart {
private String
private char[]
mUser;
mPassword;
// Callback handler used for http form-based authentication
private CallbackHandler mHandler;
// LTPA token retreived from loginContext and then assigned to launchContext
private Cookie
mCookie;
public Pane1View() {
}
private void retrieveCredential(String host) {
try {
// get password credential from credential store for the current host
IHostCredentialManager manager = ICredentialManagerFactory.INSTANCE
.getHostCredentialManager();
ICredential[] creds = manager.findByHost(host);
90
IBM Workplace Managed Client: ISV Integration Guide
// validate credential
Assert.isNotNull(creds);
if (creds.length == 0) {
throw new IllegalStateException(
"Unable to find any credentials for host "+ host + "\n\n"
+ "Possible cause: the login server has been changed after the
credential was created");
}
Assert.isTrue(creds[0] instanceof IPasswordCredential,
"Credential is not a password credential");
// get username and password from credential
IPasswordCredential cred = (IPasswordCredential) creds[0];
mUser = cred.getUsername();
mPassword = cred.getPassword();
} catch (Exception ex) {
ex.printStackTrace();
}
}
...
}
The retrieveCredential() method can access the credential store because the store
was unlocked by the IBM Workplace personality. The findByHost() method is used to
retrieve the credential for this host that was created by the Workplace Managed Client the
first time the user logs in. The user name and password are retrieved and assigned as
instance data to be used in CallbackHandler.
Note: Workplace Managed Client uses a local credential store to store user name and
password credentials. Workplace Managed Client applications can access the local
credential store by decrypting it using the password supplied by the user at sign-on and
can create password credentials for authenticating with remote servers.Workplace Client
Technology also provides security APIs that enable an application to log in to a Web or
portal application programmatically.
3. Add a getCallBackHandler() method in the same Eclipse view class shown in
Example 4-3 on page 90. This method creates the
javax.security.auth.callback.CallbackHandler instance used by form-based
authentication to provide the user name and password. Example 4-4 shows the partially
implemented Eclipse view class with a method to create a CallBackHandler instance.
Example 4-4 Partially implemented Eclipse view class with method to create CallBackHandler instance
//Pane1View.java
//...
public class Pane1View extends ViewPart {
//...
private void createHandler() {
// build J2EE callback
mHandler = new CallbackHandler() {
public void handle(Callback[] callbacks) throws IOException,
UnsupportedCallbackException {
Chapter 4. ISVs with Web and portal applications
91
for (int i = 0; i < callbacks.length; i++) {
if (callbacks[i] instanceof NameCallback) {
NameCallback nc = (NameCallback) callbacks[i];
nc.setName(mUser);
} else if (callbacks[i] instanceof PasswordCallback) {
PasswordCallback pc = (PasswordCallback) callbacks[i];
pc.setPassword(mPassword);
} else if (callbacks[i] instanceof LtpaCookieCallback) {
LtpaCookieCallback cookie = (LtpaCookieCallback) callbacks[i];
// could pass in a cookie if we had one with this call
// back
// however the goal of this sample is to get the cookie
// after a successful login
}
}
}
};
}
...
}
This callback can also provide an LTPA cookie, but it is not included in this example
because the LTPA token has not been retrieved. The mHandler instance data is set and
used by the retrieveCookie method to log in and then retrieve the LPTA token.
4. Add a retriveCookie() method in the same Eclipse view class shown in Example 4-4 on
page 91. This method logs in to a special servlet defined by the URL,
/lwp/j_security_check. This servlet is used by form-based authentication to authenticate
a user. Example 4-5 shows the partially implemented Eclipse view class with a method to
retrieve credential cookies for the HTTP form application.
Example 4-5 Partially implemented Eclipse view class with a method to retrieve credential cookies
//Pane1View.java
//...
public class Pane1View extends ViewPart {
//...
// login to j_security_check using name and password to get the LTPA cookie
private void retrieveCookie(String host) {
IHttpFormLoginContext context = IHttpFormLoginContextFactory.INSTANCE.create();
try {
context.login(host, 80, "/lwp/j_security_check", false, mHandler,null);
} catch (LoginException ex) {
MessageDialog.openWarning(null, "SSO Browser Login", ex.getMessage());
}
// get cookie from the context (an exception would have occurred if
// login was unsuccesful)
mCookie = context.getCredentialCookie(IHttpFormLoginContext.CREDENTIAL_LTPA);
Assert .isNotNull(mCookie,“Authentication with host was successful, but no LTPA
cookie was found");
}
}
92
IBM Workplace Managed Client: ISV Integration Guide
When authenticated, the LTPA token can be retrieved from IHttpFormLoginContext. It can
then be assigned to a browser launch context.
5. Add a launchBrowser() method in the same Eclipse view class shown in Example 4-5 on
page 92. This method assigns the LTPA token to ILaunchContext using the
setSingleSignOnCookie() method. This allows access to a portal or Web application
without additional user name and password prompts. Example 4-6 shows the partially
implemented Eclipse view class with a method to create a launch context to the desired
URL and launch the embedded browser within Workplace Managed Client with single
sign-on enabled.
Example 4-6 Partially implemented Eclipse view class with method to create launch context to URL
//Pane1View.java
//...
public class Pane1View extends ViewPart {
//...
// create a launch context to the desired URL
private void launchBrowser(String url) {
// create a launch context to the snoop servlet
ILaunchContext launchContext = LaunchBrowserFactory.createLaunchContext(url);
// assign the LTPA cookie
launchContext.setSingleSignOnCookie(mCookie.getValue(),
ILaunchContext.CREDENTIAL_LTPA);
// launch the WCT browser
ILaunchBrowser launchBrowser = LaunchBrowserFactory
.getBrowserInstance();
try {
launchBrowser.launch(launchContext);
} catch (Exception ex) {
ex.printStackTrace();
}
}
}
Note: In the Workplace Managed Client 2.5.1 release, LTPA cookies set by the
ILaunchBrowser API are persisted. The user might need to manually clear the cookies
for the Web applications that do not want the cookies to be persisted.
The Workplace Managed Client 2.6 release has a support for both persistent and
non-persistent LTPA cookies.
6. Create a handleLaunchLTPA() method in the same Eclipse view class shown in
Example 4-6. This method brings together all the methods defined in the previous steps to
launch the embedded browser enabled with form-based authentication and the LTPA
token support provided by Workplace Managed Client. Call the handleLaunchLTPA()
method when the Eclipse view receives the window focus. See Example 4-7 on page 94
for the handleLaunchLTPA implementation.
Chapter 4. ISVs with Web and portal applications
93
Example 4-7 Partially implemented Eclipse view class to launch embedded browser with SSO enabled
//Pane1View.java
//...
public class Pane1View extends ViewPart {
//...
private void handleLaunchLTPA() {
try {
// get the current host, used to retrieve the credential and then
// login
String host = PlatformContext.getJNDIHostName();
// Retrieve the credential which will be used in the callback
// handler
retrieveCredential(host);
// Create the Callback handler needed to login to j_security_check
createHandler();
// login to the j_security_check using name and password to
// retrieve the LTPA cookie
retrieveCookie(host);
// Launch the browser at the URL using the LTPA token
String portalUrl = PlatformContext.getPortalURL();
if(!portalUrl.endsWith("/lwp/workplace") &&
!portalUrl.endsWith("/lwp/myworkplace")){
portalUrl += "/lwp/myworkplace";
}
portalUrl.replaceAll("//lwp","/lwp");
launchBrowser(portalUrl);
} catch (IllegalStateException ex) {
MessageDialog.openWarning(null, "SSO Browser Login", ex
.getMessage());
} catch (Exception ex) {
ex.printStackTrace();
}
}
// Launch Embedded browser on setFocus
public void setFocus() {
// comment the method to launch simple browser and call the method to launch the
// browser with HTTP form authentication and LTPA support enabled
// handleLaunchSimple();
handleLaunchLTPA();
}
}
7. Deploy the application to the Workplace Collaboration Services server and provision it
down to a client.
Figure 4-8 on page 95 shows the Workplace Managed Client Web-based application that is
launched within the embedded browser. The user is not prompted for a user name and
password as SSO is enabled for HTTP form-based application.
94
IBM Workplace Managed Client: ISV Integration Guide
Figure 4-8 HTTP form-based application with LTPA support launched in Workplace Managed Client
More complex business logic might require storing credentials for multiple systems that
support form-based authentication over HTTP and browser access using LTPA tokens. In this
case, the application must prompt the user for additional credentials and store them using the
createPassword method on the IHostCredentialManager interface. A user name and
password is not passed into the createPassword method, instead a CallbackHandler, as
defined in createHandler, is used. The findByHost method can be used to retrieve the
required credential. In 6.7, “Securing a client application” on page 166, we describe how to
create the HTTP credentials and store them to local credential store.
Note: Currently, Workplace Managed Client only supports form-based authentication over
HTTP and browser access using an LTPA token.
4.4.2 Adding a Workplace Managed Client search bar
Workplace Managed Client exposes an extension point that any application can implement in
order to place a search bar above the main view. The search bar consists of:
򐂰 A combo box listing search categories
򐂰 A text box for the string to be searched
򐂰 A button to activate the search
The Web applications can extend the Workplace Managed Client search bar and perform the
Web search to display search results within Workplace Managed Client using an embedded
Web browser.
Chapter 4. ISVs with Web and portal applications
95
Figure 4-9 shows the Web application embedded in Workplace Managed Client that uses the
Workplace Client search bar.
Figure 4-9 The search bar extended by a Workplace Managed Client Web application
The searchbarAdapters extension point adds a custom contribution to the search menu that
performs a customized search and displays the results in a custom view. In order to create a
search bar in Workplace Managed Client, perform the following steps:
1. Populate the search menu with the custom contribution.
2. Contribute code to perform a custom search that is triggered when the corresponding
menu action is selected.
3. Display the search results in a custom view.
Follow these steps to add a custom search bar contribution:
1. Add com.ibm.rcp.ui.searchbar and com.ibm.rcp.platform as plug-in dependencies in
the Eclipse plugin.xml file. This plugin.xml file was generated when the Workplace
Managed Client application project was created, as described in 4.3.1, “Creating a new
IBM Workplace project” on page 81. Example 4-8 shows the Eclipse plugin.xml file with
the added dependency for these plug-ins.
Example 4-8 Eclipse plugin.xml code with plug-in dependencies for a search bar extension
<plugin>
<requires>
<import plugin="com.ibm.rcp.ui.searchbar"/>
<import plugin="com.ibm.rcp.platform"/>
</requires>
...
</plugin>
96
IBM Workplace Managed Client: ISV Integration Guide
2. Extend the searchbarAdapters extension point defined in the
com.ibm.rcp.ui.searchbar.api code and provide values for the required attributes as
tags, as shown in Example 4-9.
Example 4-9 Eclipse plugin.xml code to extend the searchBarAdapters
<plugin>
<extension id="com.ibm.wcttool.web.search.IBMSearch.internet"
name="searchbar extension point"
point="com.ibm.rcp.ui.searchbar.searchbarAdapters">
<adapter
label="IBM Internet"
data="1"
class="com.ibm.wcttool.web.search.IBMSearch"
id="com.ibm.wcttool.web.search.IBMSearch.internet" />
</extension>
...
</plugin>
3. Map the adapter id parameter in Example 4-8 on page 96 with the Web application
activity pattern binding. Example 4-10 shows how to do this.
Example 4-10 Eclipse plugin.xml code to map the id parameter
<plugin>
<extension point="org.eclipse.ui.activities">
<activity
description="This is web activity"
name="com.ibm.wcttool.web.activity"
id="com.ibm.wcttool.web.activity"/>
<activityPatternBinding
activityId="com.ibm.wcttool.web.activity"
pattern="com\.ibm\.wcttool\.web\.pane1/com\.ibm\.wcttool\.web\..*" />
</extension>
...
</plugin>
4. Create a new class that implements the ISearchDataAdapter interface. The class and
package should match the class parameter defined in the searchbarAdapters extension
created in step 2. In the Workplace Managed Client Web application example, we use the
com.ibm.wcttool.web.search.IBMSearch class, as shown in Example 4-11.
Example 4-11 Partial implementation of the ISearchDataAdapter interface in IBMSearch.java
import
import
import
import
//...
public
com.ibm.rcp.ui.browser.core.api.ILaunchBrowser;
com.ibm.rcp.ui.browser.core.api.ILaunchContext;
com.ibm.rcp.ui.browser.core.api.LaunchBrowserFactory;
com.ibm.rcp.ui.searchbar.api.ISearchDataAdapter;
class IBMSearch implements ISearchDataAdapter {
public boolean isMenuVisible() {
return true;
}
public void run(String arg0, String arg1) {
final String search = arg0;
Display.getDefault().asyncExec(new Runnable(){
public void run() {
handleLaunchSimple(search);
Chapter 4. ISVs with Web and portal applications
97
}
});
}
// create a launch context to the desired URL
private void handleLaunchSimple(String searchString) {
try {
ILaunchContext launchContext = LaunchBrowserFactory
.createLaunchContext("www.mycmpny.com/Search?searchString="
+ searchString +
""");
// launch the WCT browser
ILaunchBrowser launchBrowser = LaunchBrowserFactory
.getBrowserInstance();
launchBrowser.launch(launchContext);
} catch (Exception e) {
e.printStackTrace();
}
}
//...
}
Note: While implementing the run() method for ISearchDataAdaper, make sure that the
UI operations are performed using the syncExec() or asyncExec() thread. Perform the
non-UI operations using normal Java Thread.
5. Deploy the application to the Workplace and provision it, as described in 4.3.3, “Deploying
the application to Workplace Collaboration Services server” on page 85.
4.4.3 Enhancing WSRP and converting servlet and JSP applications
Converting servlet and JavaServer™ Pages™ (JSP™) applications to JSR 168 portlets is
another technique for integrating applications into Workplace Managed Client. After being
converted to portlets, they can be accessed from the WSRP viewer, as described in 4.1.2,
“What is WSRP?” on page 78.
WSRP can also be extended using container-specific markup, allowing customization and
personalization on the glass. The WSRP specification is defined by a producer, consumer,
and end user. The producer is responsible for implementing the following interfaces: service
description, markup, portlet management, and registration. The WSRP viewer implements
both the consumer and end user and calls the interfaces on the producer to render the
appropriate UI.
Figure 4-10 on page 99 shows a graphic representation of the WSRP viewer.
98
IBM Workplace Managed Client: ISV Integration Guide
Figure 4-10 WSRP Viewer - Producer and consumer architecture
Container-specific markup can be added by a WSRP producer and interpreted by some
WSRP viewers while being ignored by other WSRP viewers that cannot process the markup.
To maximize extensibility, externally developed plug-ins can be developed that process this
container-specific markup to improve integration with Workplace Managed Client and the
WSRP viewer. This markup can be used for light UI integration, enabling some bridging of
state and data between the Web container and the client container contexts. For example,
this can enable a portlet to have custom Eclipse Java menu entries or Workplace Managed
Client action bar items. This technique can also be used for deeper client integration and
would be considered appropriate for the exploit phase.
4.5 Exploit
When the ISV seeks to fully exploit IBM Workplace Client Technology and to reuse shared UI
components or publish capabilities to other applications, the approach would be nearly
identical to what IBM itself did when enhancing Workplace Messaging from being a portal
Web application to also having a rich desktop mode.
For Web and portal applications to exploit Workplace Managed Client, the first step is to write
Eclipse plug-ins that make remote calls to the same back-end services that existing portlets
do. This might suffice, particularly if offline operation is not a requirement. Figure 4-11 on
page 100 illustrates this.
Chapter 4. ISVs with Web and portal applications
99
Figure 4-11 Client-side applications accessing server-side services in online mode
If offline support is required, a single-user version of the business logic and its corresponding
local data store can be straightforwardly derived from the existing server versions.
Figure 4-12 shows this configuration.
Figure 4-12 Client-side applications accessing local services that synchronize data
Example
The end result of extending a portlet-based application can be seen by examining what IBM
did with IBM Workplace Messaging. In IBM Workplace Messaging, it has a full, rich desktop
100
IBM Workplace Managed Client: ISV Integration Guide
experience that has the TCO of a browser combined with a secure store and rich
cross-platform integration framework.
ISVs that have written portlet applications can look at this example as a precedent for what is
possible if they choose to completely exploit all options of IBM Workplace Client Technology.
It is worth reiterating, however, that such exploitation can be done in stages, and in many
cases, might never need to go to through to full exploitation.
Features provided by Workplace Managed Client that enable an ISV to extend their
application in very powerful ways include:
򐂰 Document libraries for remote storage and document sharing
Workplace Managed Client document libraries consist of both local and remote storage in
a folder structure for sharing documents among a group or team. Workplace Managed
Client provides an API for manipulating files and folders in a document library.
򐂰 Online awareness
There is a online/offline awareness API that can be used to inform an application when the
client is online, offline, or when it is about to transition between the two. This can be useful
for completing transactions if connectivity is about to change and close down open
connections. After the operation has completed, the connection to the database can be
reestablished.
򐂰 Synchronizing client application data
There is an API that taps into the client's synchronization framework. Based on timetables
set in the client’s preferences, the application can be informed of when to synchronize its
data. The actual data synchronization is performed by the application itself.
򐂰 Database access, both local and remote
Workplace Managed Client comes with its own Cloudscape relational database. After the
application is fully moved to the Workplace Managed Client platform, it does not need to
always have a connection to the remote database; it simply needs to connect to the local
Cloudscape database. The rest of the application code does not need to be changed.
򐂰 Messaging and notifications
Workplace Managed Client provides a full mail API for sending and manipulating mail
messages.
򐂰 Securing a client application
The IBM Workplace Client Technology platform is a secure platform that protects
application data. Single sign-on with the operating system capabilities are built into the
rich client by default. The local Cloudscape database is encrypted using the users’
credentials, which must be retrieved using the credential store API.
All of these features apply to any fully integrated Workplace Managed Client application. They
are not specific to integrating a Web or portal application. We cover all of these points in detail
in Chapter 6, “Exploiting IBM Workplace Managed Client” on page 139.
4.6 Summary
IBM Workplace Client Technology framework provides for a variety of ISV integration paths
for Web and portal applications. These paths range from simple coexistence to full-blown
exploitation of the Workplace Client Technology infrastructure. Following this path balances
the amount of time needed to convert these applications with the greater flexibility and
Chapter 4. ISVs with Web and portal applications
101
seamlessness of the newly ported application. ISVs can start at any point along the spectrum
and more fully integrate as your schedule and needs change.
4.7 URLs referenced in this chapter
Table 4-2 lists the URLs referenced in this chapter.
Table 4-2 Table of URLs used in this chapter
102
What
Where
Information about WSRP
http://www.oasis-open.org/committees/tc_ho
me.php?wg_abbrev=wsrp
Creating an application with the IBM Workplace
Managed Client Developer Toolkit
http://www.ibm.com/developerworks/workplac
e/library/wmc-toolkit-basic
IBM WebSphere Portal Information Center
http://publib.boulder.ibm.com/pvc/wp/502/e
nt/en/InfoCenter/index.html
More information about WSRP
http://www.ibm.com/developerworks/webservi
ces/library/ws-wsrp/
Final JSR 168 specification
http://www.jcp.org/aboutJava/communityproc
ess/final/jsr168/
http://developers.sun.com/prodtech/portals
erver/reference/techart/jsr168/
IBM Redbook IBM Workplace Client Technology,
Micro Edition Version 5.7.1: Application
Development and Case Study, SG24-6496
http://www.redbooks.ibm.com/abstracts/sg24
6496.html
More information about LTPA
http://www.ibm.com/developerworks/ibm/libr
ary/it-0101art2
IBM Workplace Managed Client: ISV Integration Guide
5
Chapter 5.
ISVs with Lotus Notes and
Domino applications
This chapter introduces the steps you can take to integrate an IBM Lotus Notes or Lotus
Domino application into the Workplace Client Technology framework. Even if there is neither
the time nor the resources to do a full Eclipse Rich Client Platform (RCP) conversion,
significant benefits can be quickly gained from the central management and security that
Workplace Client Technology offers.
ISVs that build and sell Lotus Notes/Domino-based applications can approach the integration
spectrum using methods discussed in this chapter. These include:
򐂰 Deploying and provisioning Workplace Managed Client applications
򐂰 Integrating with the Workplace Managed Client framework
򐂰 Fully exploiting Workplace Managed Client features such as security, storage, and
synchronization
© Copyright IBM Corp. 2006. All rights reserved.
103
5.1 Overview
This chapter describes how an ISV can migrate an existing Lotus Notes/Domino application
to the Workplace Managed Client framework. Benefits of such a migration include:
򐂰 Integration with other applications provided by the application switcher
򐂰 Leveraging the features and functionality provided by Workplace Client Technology
This chapter uses the example of a book merchant application, booklist.nsf. Booklist.nsf
stores information about the merchant’s current book inventory. We shows how this
application changes as it is moved through the various stages of integration with Workplace
Managed Client.
5.1.1 What is Lotus Domino?
IBM Lotus Domino provides enterprise-grade collaboration capabilities, including a host of
integrated messaging and directory services that provide world-class e-mail, calendar and
scheduling capabilities, discussion databases, and address books in a unified,
easy-to-manage architecture. Lotus Domino is a member of the IBM Workplace product
family. Version 7 supports more users with fewer servers to simplify administration and to
provide tighter integration with Web standards.
Beyond messaging, the Lotus Domino server provides a robust platform for developing and
deploying collaborative applications on a wide variety of operating systems. With IBM Lotus
Notes and Lotus Domino software, collaborative solutions can be built and executed, such as
project management tracking and customer support processes, that can help an organization
to be more responsive and productive.
With Version 7, IBM extends the reach of Lotus Notes and Lotus Domino messaging and
collaboration solutions while continuing to leverage existing IT and application investments.
The new and advanced administrative, performance, and security features of Lotus Domino 7
server can help lower your total cost of ownership. Native support for Web services and
enhanced support for industry standards can extend the reach of rapid application
development and deployment.
5.1.2 IBM Lotus Domino Web Access
With Lotus Domino Web Access, users can access traditional Notes features, such as e-mail
and discussion forums, from a variety of clients using a Web browser. Lotus Domino Web
Access is a Web client that provides access to Domino-based .nsf files through browsers
such as Mozilla Firefox, Mozilla, and Microsoft Internet Explorer through Dynamic HTML
(DHTML).
Lotus Domino Web Access 7 combines access to a robust, reliable, enterprise-class
messaging and collaboration platform, with the ease of simply opening a browser. Highlights
of Lotus Domino Web Access 7 include:
򐂰 Opportunity for improved client and server performance
򐂰 Enhanced security features
򐂰 Expanded presence awareness and instant messaging integration
򐂰 Updated user interface
򐂰 Added mail and calendar productivity features
򐂰 Enhanced support for Linux
104
IBM Workplace Managed Client: ISV Integration Guide
򐂰 New administration and management features
򐂰 Improved offline access to personal data
5.1.3 Domino integration options
As stated in the introduction, there are trade-offs involved when deciding the level of
integration between an existing Lotus Notes/Domino application and the Workplace Managed
Client. Table 5-1 highlights some of the considerations when examining the different
integration paths.
Table 5-1 Integration paths for Lotus Notes/Domino applications
Increase of time, effort, and synergy →
Coexist
Accommodate
Leverage
Exploit
Copy and paste data
from any existing
Notes/Domino
application.
Access NSFs using
the Notes 7.0 plug-in.
Access Domino
databases through
Web services and
native APIs.
Make use of advanced
Workplace Managed
Client features such as
document libraries,
single sign-on, secure
data store, and so on.
Wrap Domino Web
applications in portlets,
and then display using
Notes plug-in.
Add new features
specific to Workplace
Managed Client.
Provisioning.
Why integrate?
Achieving the first two levels of integration is a relatively simple task, because IBM has done
much of the groundwork by developing the Notes 7.0 plug-in for the Workplace Managed
Client. After the Notes 7.0 plug-in is provisioned to Workplace Managed Client, a check is
performed to determine whether Notes Version 7.0 is installed on the client machine. If it is,
the Notes 7.0 UI is dynamically “reparented” to operate within the Workplace Managed Client
UI.
At a very high level, the architecture of Notes consists of several independent processes, for
example, managing user interactions, the Notes desktop, displaying views, and editing Notes
documents. Together, all the processes make use of a private interprocess communication
(IPC) facility for coordinating their activities. Figure 5-1 shows the high-level architecture of
Notes.
Figure 5-1 High-level architecture of Notes
In order to run Notes applications in Workplace Managed Client, the Notes application plug-in
interfaces with the main Notes process using the private IPC already built into Notes. See
Figure 5-2 on page 106. The plug-in is implemented as a standard Eclipse view extension,
written in Java, and uses JNI to call into a DLL with the Notes IPC facility written in C.
Chapter 5. ISVs with Lotus Notes and Domino applications
105
Figure 5-2 Notes Eclipse plug-in and the Notes IPC
5.1.4 Reparenting Notes applications using the Notes plug-in
Workplace Managed Client provides an extremely powerful and simple to use tool for
integrating with Lotus Notes 7.0 called the Notes plug-in. The Notes plug-in enables
developers to extend their Notes applications—applications designed specifically to run in the
Lotus Notes client—to IBM Workplace Managed Clients, with no additional coding work
required.
The plug-in enables any Notes application to run with full capability and fidelity in Workplace
Managed Client without any need for code modification. Notes applications can be run
seamlessly with a variety of other applications through the unified UI provided by Workplace
Managed Client.
Developers leverage their existing LotusScript and other Domino skills while taking advantage
of the benefits of the Workplace Managed Client Eclipse-based platform. In addition, all of the
Notes 7 out-of-the-box templates are supported from within Workplace Managed Client. The
plug-in also provides the option to integrate Lotus Notes applications with the instant
messaging capabilities of IBM Workplace Collaboration Services software.
Highlights of the Lotus Notes plug-in for Workplace Managed Client include:
򐂰 Lotus Notes is accessible through the application switcher of the Workplace Managed
Client.
򐂰 Lotus Notes has its own “page/perspective” with bookmarks and tabs for documents,
similar to Notes tabs.
򐂰 Lotus Notes menus are integrated in the Managed Client.
򐂰 Lotus Notes status bar messages appear as usual in Workplace Managed Client.
򐂰 Lotus Notes server and local databases are accessible and work the same as within the
Lotus Notes client.
5.2 Coexist
The simplest level of integration is coexistence. This requires no changes at the code level.
Lotus Notes remains installed and runs on the client’s desktop just as it always has.
For Notes and Workplace Managed Client, a user opens Lotus Notes and copies and pastes
data into a Workplace Managed Client document. Prior to Notes Version 7, this was the only
106
IBM Workplace Managed Client: ISV Integration Guide
option for coexistence. If a user has Version 7 or later, the Notes plug-in automatically
bypasses the coexist stage and goes straight to accommodate.
5.3 Accommodate
At the accommodate level, there are three paths that you can follow:
򐂰 Running Domino applications within Workplace Managed Client using the Notes plug-in.
򐂰 Launching a Notes/Domino application in its native window using Workplace Managed
Client.
򐂰 Using the Workplace Managed Client Developer Toolkit to create a Workplace Managed
Client application that displays a Domino application in one or more Eclipse views. This
feature is available in Version 2.6 and later of Workplace Managed Client.
This section discusses all these approaches, which can be achieved with little to no coding
work.
5.3.1 Running Domino applications in Workplace Managed Client using the
Lotus Notes plug-in
To run a Domino application in Workplace Managed Client using the Notes plug-in, perform
the following three steps:
1. Install the Notes 7.0 client if not already installed.
2. Enable the Notes plug-in to be provisioned to clients on the Workplace Collaboration
Services server form which Workplace Managed Client was installed.
3. Open the Domino application using the Workplace Managed Client Notes plug-in.
Installing the Notes 7.0 client
A trial version of the Notes 7.0 client is available at:
http://www.ibm.com/developerworks/downloads/ls/lsds/?S_TACT=105AGX13&S_CMP=LSDL
For more information, see:
http://www.ibm.com/software/sw-lotus/products/product4.nsf/wdocs/noteshomepage
Configuring and provisioning the Notes application plug-in
Follow these steps to deploy the Notes application plug-in:
1. Log in to the WebSphere administrative console using the following link:
http://<your_server>:<admin_port>/admin
Note that <admin_port> is by default 9091.
Note: Administrator access rights are required to use the administrative console.
Figure 5-3 on page 108 shows the administrative console login page for WebSphere
Portal server.
Chapter 5. ISVs with Lotus Notes and Domino applications
107
Figure 5-3 WebSphere Portal Administrative Console
2. In the side navigation bar, click Lotus Workplace → Users → Manage User Policies →
Default User Policy. See Figure 5-4.
3. Scroll through the list of General Properties and select Allow Notes application plug-in,
as shown in Figure 5-4.
Figure 5-4 Select Allow Notes application plug-in
4. Click Apply → Save → Save to save the administrative changes.
5. Provision the Workplace Managed Client from a Workplace Collaboration Services server.
See the following link for instructions:
http://publib.boulder.ibm.com/infocenter/iwphelp/v2r5m1/index.jsp?topic=/com.ibm.wcs.ic.
doc_2.5.1/infocenter/i_inst_t_install_rich_client_user.html
Opening the Domino application using the Notes plug-in
To open the booklist.nsf Domino application using the Notes plug-in, perform the following
steps:
1. Log in to Workplace Managed Client.
108
IBM Workplace Managed Client: ISV Integration Guide
2. Click the Lotus Notes icon in the application switcher side bar to open the Notes plug-in,
as shown in Figure 5-5.
3. Open the database in the usual manner. Click File → Database → Open to open the
usual Notes dialog box for opening a database, just as in the normal Notes client.
Notes Plug-in
Application Switcher
Figure 5-5 The booklist.nsf application displayed using the Notes plug-in
5.3.2 Launching a Notes/Domino application in its native window using
Workplace Managed Client
Another option for accommodating a Lotus Notes application within Workplace Managed
Client is to programatically launch a Notes application in its native window. Perform the
following steps:
1. Create a Workplace Managed Client application project with a single Eclipse view using
the Workplace Managed Client Developer Toolkit.
2. Modify the auto-generated Eclipse view to launch a separate Notes application when the
user clicks a button.
3. Deploy the application to a Workplace Collaboration Services server.
Creating a Workplace application project
To create a Workplace Managed Client application project using the Workplace Managed
Client Developer Toolkit, perform the following steps:
1. Select File → New → Project → IBM Workplace → Workplace Managed Client
Application Project, and click Next. See Figure 5-6 on page 110.
Chapter 5. ISVs with Lotus Notes and Domino applications
109
Figure 5-6 Creating a new IBM Workplace Eclipse project
2. Give the project a name, for example, com.ibm.wcttool.bookdatabase, and a Display
Name, such as Book Database, as shown in Figure 5-7.
3. Associate the book.png file with the projects icon by clicking Browse next to the icon text
box and choosing the file. Click Next.
Figure 5-7 Setting the Project name and Display Name
Note: The application Display Name and icon appear on the application switcher bar on
the left side of Workplace Managed Client. See Figure 3-6 on page 57 for an illustration
of this.
4. Choose the single view page layout and select Automatically create default views, as
shown in Figure 5-8 on page 111. Click Finish.
110
IBM Workplace Managed Client: ISV Integration Guide
Figure 5-8 Auto-generating a single Eclipse view
These steps create three projects in the Eclipse workspace:
򐂰 Eclipse feature project
򐂰 Workplace Managed Client page layout project
򐂰 Eclipse view project
Modifying the Eclipse view to launch a Notes native window
The previous step created an Eclipse view project named
com.ibm.wcttool.bookdatabase.pane1 containing an Eclipse view class
com.ibm.wcttool.bookdatabase.pane1.views.Pane1View and a class called MyComposite that
extends the org.eclipse.swt.widgets.Composite class. The MyComposite class defines the
user interface layout. You must now modify the MyComposite class to launch the Notes
database within its native application window. The following steps outline how this is
accomplished:
1. Add a button to the UI.
2. Add a listener to the button that launches the Book Manager Notes application in the
native Notes window when a user clicks the button.
Example 5-1 shows the MyComposite class after these changes have been made.
Example 5-1 MyComposite class with single button that launches Book Manager Notes database
//MyComposite.java
//...
public class MyComposite extends Composite {
private Button mLaunch = null;
public MyComposite(Composite parent, int style) {
super(parent, style);
initialize();
}
private void initialize() {
//create a new Button
mLaunch = new Button(this, SWT.PUSH);
mLaunch.setText("Launch");
mLaunch.setBounds(new Rectangle(10,45,60,25));
Chapter 5. ISVs with Lotus Notes and Domino applications
111
//add a SelectionListener that launches the native notes application
mLaunch.addSelectionListener(new SelectionListener() {
public void widgetDefaultSelected(SelectionEvent ev) {
widgetSelected(ev);
}
public void widgetSelected(SelectionEvent ev) {
Program.launch("notes://<your-server>/booklist.nsf/Books?OpenView");
}
});
setSize(new org.eclipse.swt.graphics.Point(300,200));
}
}
Deploying the application to Workplace Collaboration Services server
For instructions about how to export and deploy a Workplace Managed Client application to
the Workplace Collaboration Services server, follow the instructions in the white paper
Creating an application with the IBM Workplace Managed Client Developer Toolkit, available
at:
http://www.ibm.com/developerworks/workplace/library/wmc-toolkit-basic
Information is also provided by the Workplace Managed Client Developer Toolkit, accessible
through Eclipse by clicking Help → Help Contents → IBM Workplace Managed Client Tool
for Eclipse → Distributing applications and following the instructions.
After accomplishing this, the application is fully deployed to the server and will be provisioned
down the next time Workplace Managed Client is loaded.
An alternative to doing a full deploy to a server is to test the application locally, using the IBM
Workplace Managed Client Developer Toolkit. The Creating an application with the IBM
Workplace Managed Client Developer Toolkit white paper also contains instructions about
how to test a Workplace Managed Client application without deploying it to a Workplace
Collaboration Services server.
Figure 5-9 on page 113 shows the Book Database launched from a launch button.
112
IBM Workplace Managed Client: ISV Integration Guide
Launch Button
Figure 5-9 Using a button to launch a Notes application in its native window
5.3.3 Displaying a Notes application in an Eclipse View
Workplace Client Technology Version 2.6 and later provides an enhanced version of the
Notes plug-in that enables specific template views of Notes applications to be displayed as
Eclipse views. Perform the following steps to display a Notes application in an Eclipse view:
1. Install Workplace Managed Client Developer Toolkit Version 2.6.
2. Provision the Notes application plug-in.
3. Create a Workplace Managed Client application and create an Eclipse view that displays a
Domino application.
4. Deploy the application to a Workplace Collaboration Services server.
Installing Workplace Managed Client Developer Toolkit Version 2.6
IBM Workplace Managed Client Developer Toolkit is an Eclipse toolkit designed for
application developers who want to extend IBM Workplace Managed Client with new
applications. The toolkit provides a developer who has little to no Workplace experience with
the tools needed to create and deploy an application. Developers can test and debug directly
on the client without needing extensive knowledge of the deployment process for
server-provisioned applications. In addition, the toolkit provides features that simplify server
deployment. By using wizards to guide the developer, the toolkit reduces the time needed to
create and deploy applications.
For more information, see Introduction to the IBM Workplace Managed Client Developer
Toolkit, available at:
http://www.ibm.com/developerworks/lotus/library/wmc-toolkit
Chapter 5. ISVs with Lotus Notes and Domino applications
113
To install the Workplace Managed Client Developer Toolkit Version 2.6, download the
Workplace Managed Client 2.6 SDK from the following site and follow the installation
instructions:
http://www.ibm.com/software/workplace/products/product5.nsf/wdocs/2c8a33e47eef8d0585256e
e60054ddf2
Provisioning the Notes application plug-in
See steps 1 and 2 in 5.3.1, “Running Domino applications in Workplace Managed Client
using the Lotus Notes plug-in” on page 107 for the actions required to enable the Notes
plug-in.
Adding a Notes application to a Workplace Managed Client view
Follow these steps to use the toolkit wizards to create a Workplace Managed Client
application with a single view that points to an existing Notes application, booklist.nsf.
Important: The Notes plug-in feature is designed to work with Lotus Notes Version 7 and
Workplace Managed Client V2.6 and later. It will not work as expected with earlier releases
of either product.
1. Open the Eclipse IDE.
2. Click File → New → Project → IBM Workplace → Workplace Managed Client
Application Project, and click Next.
3. Type com.ibm.wcttool.bookdatabase in the Project Name field.
4. Type Book Database in the Display Name field. This is the name that will appear in the
application switcher bar in Workplace Managed Client.
5. Click Browse next to the icon field to choose an icon to display in the switcher bar. Click
Next.
6. Choose the single view page layout and clear the Automatically create default views
option, as shown in Figure 5-10. Click Next.
Figure 5-10 Select a page layout for the Notes application view
7. Click Create New → Notes Template. Click Next. See Figure 5-11 on page 115.
114
IBM Workplace Managed Client: ISV Integration Guide
Figure 5-11 Select Notes Template
8. Under View Type, select Data View → Get Database.
Note: Data View allows different Notes elements, such as a particular view, to be
opened. Another useful option is the Opened Item View, which displays any opened
item.
9. Provide the appropriate information in the Server Name, User Name and Password fields
and click Get Databases to retrieve a list of databases available on the server, as shown
in Figure 5-12.
Note: Clicking Get Databases without inputting any information in the Server Name,
User Name, and Password fields retrieves local databases.
Figure 5-12 Select Database window
10.Click OK → Finish → Finish.
The Notes URL field is filled with the appropriate Notes URL, for example:
notes:///<your-server>/booklist.nsf/Books?OpenView
As an alternative to using the Developer Toolkit you can build a view from scratch using
Eclipse. Refer to the following article, Creating a Notes/Domino plug-in with Eclipse, available
at:
http://www.ibm.com/developerworks/lotus/library/notes-plugin-eclipse
Deploying the application to a Workplace Collaboration Services server
See “Deploying the application to Workplace Collaboration Services server” on page 112 for
information about how to deploy the Workplace application to a Workplace Collaboration
Services server.
Chapter 5. ISVs with Lotus Notes and Domino applications
115
Figure 5-13 shows the Book Database application as reparented through Workplace
Managed Client.
Figure 5-13 Book Database launched as a Workplace Managed Client application
5.4 Leverage
The next level of integration with the Workplace Managed Client is leverage. As previously
described in 5.3, “Accommodate” on page 107, in order to display a Notes/Domino natively
within Workplace Managed Client, it can be wrapped with the Notes plug-in. This displays the
application in its original form and, in addition, integrates it with the Workplace Managed
Client toolbars, status bar, and so on. In many instances, the accommodate level of
integration will be more than adequate.
There are many other features of Workplace Managed Client available to an application that
are not available through the Notes plug-in however. These include:
򐂰 Enabling server-side definition of an application’s view layout by creating one portlet per
view
򐂰 Tabbed views
򐂰 Action bars
򐂰 Search bar
򐂰 Custom UI widgets
– Rich text editor
– Alerts
– Collapse bar
򐂰 Custom views
– Shelf views
To leverage these components, you must implement a Java-based user interface. All data
remains in a Domino database, with the Workplace Managed Client application accessing it
either locally or remotely. There are two methods for remotely accessing a Domino server
from a Java application:
򐂰 Using the public Notes/Domino Java APIs
򐂰 Exposing a Domino application using Web services
For additional information regarding using the Notes Java APIs, see:
http://www.higs.net/85256C89006A03D2/web/pageDominoJavaToolkit
116
IBM Workplace Managed Client: ISV Integration Guide
We perform five steps to write a Workplace Managed Client application that accesses a
Domino server for its storage needs:
1. Expose the Domino application using Web services.
2. Write the code for receiving and sending data to and from the Domino Web service.
3. Create a Workplace application project.
4. Write user interface code to display the data retrieved from the Web service.
5. Deploy the application on the Workplace Collaboration Services server.
We describe these steps in the following sections.
5.4.1 Exposing a Domino application using Web services
Web services are a new design element in Lotus Domino 7 that ISVs can develop using either
the LotusScript or Java programming languages. ISVs can find Web services in the Shared
Code section of the database design pane. The Web services design element implementation
looks much like regular Domino agent design and has the same programming logic.
The same basic security rules apply to Web services as apply to agents:
򐂰 A database access control list (ACL) for verifying access
򐂰 Run as Web User, as Signer, on Behalf of
򐂰 Restricted/unrestricted access to resources
򐂰 Public Access option
Perform the following steps to expose the Notes/Domino database as a simple Web service.
For these steps, we assume that you already created the Notes/Domino database
Booklist.nsf, which stores information about a merchant’s current book inventory.
Notes:
򐂰 To learn more about Lotus Notes and Domino 7 Web services, including how to expose
a Notes/Domino database as a Web service, see the Redpaper Lotus Domino 7
Application Development, REDP-4102, at:
http://www.redbooks.ibm.com/abstracts/redp4102.html
򐂰 For more information about using Notes APIs from Eclipse, refer to the developerWorks
article, Creating a Notes/Domino plug-in with Eclipse, available at:
http://www.ibm.com/developerworks/lotus/library/notes-plugin-eclipse/
1. Open an existing Notes/Domino database using Domino Designer 7. Figure 5-14 on
page 118 shows the Booklist.nsf database opened using Domino Designer 7.
Chapter 5. ISVs with Lotus Notes and Domino applications
117
The action button to
create Web service
Link to create
Web service
Figure 5-14 The existing Notes/Domino database opened with Domino Designer 7
2. Click the Web Services link in the booklist database panel. Figure 5-14 shows the Web
Services link in the booklist database panel to the left.
This opens the Web services designer panel tab on the right side.
3. Click New Web Service in the action bar of the Web services designer panel to expose
the Notes/Domino database application as a Web service. Figure 5-14 shows the New
Web Service button on top of the Web services designer panel.
This opens the Web Service properties dialog box.
4. On the Basic tab, specify the Web service's Name, Alias, and PortType class. Figure 5-15
on page 119 shows the Basic tab for the booklist application. The value set for Name,
Alias, and PortType fields is BookManager for this example.
Note: Selecting the option Warn if the WSDL interface is modified causes the
service to display a message if the implied WSDL structure changes, such as revised
class names, changed names of methods or functions, or added or removed class
variables. In a production environment, such changes can cause existing software
clients consuming your Web service to stop working because of errors in parsing the
changed Web service response structure. Setting this option also prevents you from
saving such changes and gives you a chance to review and change your code back.
ISVs do not need to set this option during the creation and testing period.
118
IBM Workplace Managed Client: ISV Integration Guide
Figure 5-15 Web Service dialog box: Basic tab
5. Click the Security tab. The Security tab, shown in Figure 5-16, looks the same as the
Security tab in an agent's properties. Here, you can set the security options for the Web
service.
Figure 5-16 Web Service dialog box: Security tab
6. Go to the Advanced tab to specify the programming model and SOAP message format.
Figure 5-17 shows the Advance tab properties set for the booklist application.
Figure 5-17 Web Service dialog box: Advanced tab
7. Configuring the Web service parameters as explained in steps 4, 5, and 6 opens the Web
Service tab for the Notes/Domino application. In the Web Service Options section, select
LotusScript as the programming language. Note that LotusScript is set as the default
language. Figure 5-18 on page 120 shows the Web Service Options section for the
BookManager Web service.
Chapter 5. ISVs with Lotus Notes and Domino applications
119
Figure 5-18 BookManager Web Service Options
8. Copy the simple LotusScript Web service code from Example 5-2 and paste it into the
Declarations section of the Web service, as shown in Figure 5-19.
Figure 5-19 BookManager Web Service Declarations
Example 5-2 shows the code for the simple LotusScript Web service.
Example 5-2 Code for the simple LotusScript Web service
%INCLUDE "lsxsd.lss"
Class BookManager
Public Function getBookList () As String
Dim
Dim
Dim
Dim
session As New NotesSession
db As NotesDatabase
dc As NotesDocumentCollection
doc As NotesDocument
Dim count As Integer
count = 0
Set db = session.CurrentDatabase
Set dc = db.AllDocuments
Set doc = dc.GetFirstDocument()
While Not(doc Is Nothing)
If doc.booktitle(0) <> "" Then
If count <> 0 Then getBooklist = getBooklist + ","
getBooklist = getBooklist + doc.booktitle(0)
count = count + 1
End If
Set doc = dc.GetNextDocument(doc)
Wend
End Function
120
IBM Workplace Managed Client: ISV Integration Guide
Function getBookInfo(bookTitle As String) As String
Dim session As NotesSession
Set session = New NotesSession
Dim db As notesdatabase
Dim view As notesview
Dim doc As notesdocument
Set db = session.GetDatabase("","booklist.nsf")
Set view = db.GetView("Books")
Dim doccol As NotesDocumentCollection
Set doccol =db.FTSearch(bookTitle,1)
If doccol.Count =0 Then
getBookInfo = ""
End If
Set doc = doccol.GetFirstDocument
If doc Is Nothing Then
getBookInfo = ""
Else
getBookInfo =
doc.booktitle(0)+","+doc.bookauthor(0)+","
+doc.bookdescription(0)+","+"12345678"
End If
End Function
End Class
9. Save the Web service and validate the WSDL file for the Web service using the following
link:
http://<your-server>/<database-name>/<WebService-name>?WSDL
Figure 5-20 on page 122 shows the WSDL file created for the BookManager Web service.
Chapter 5. ISVs with Lotus Notes and Domino applications
121
Figure 5-20 Partial WSDL file for BookManager Web service
5.4.2 Communicating with Web service from Workplace Managed Client
As shown in 5.4.1, “Exposing a Domino application using Web services” on page 117, an
agent is exposing a Domino database using a Web service called BookManager. Two remote
calls are supported:
򐂰 GETBOOKLIST: This returns a comma-separated string of book titles.
򐂰 GETBOOKINFO: This accepts a single parameter, a book title, and returns a single book
record in a comma-separated string.
For the more technically minded, Example 5-3 shows the WSDL snippet describing the
methods and parameters. This is auto-generated by Domino and is not necessary to
comprehend.
Example 5-3 WSDL snippet describing the two methods exposed by the Domino BookManager agent
<wsdl:message name="GETBOOKLISTRequest"/>
<wsdl:message name="GETBOOKLISTResponse">
<wsdl:part name="GETBOOKLISTReturn" type="xsd:string"/>
</wsdl:message>
<wsdl:message name="GETBOOKINFORequest">
<wsdl:part name="BOOKTITLE" type="xsd:string"/>
</wsdl:message>
<wsdl:message name="GETBOOKINFOResponse">
<wsdl:part name="GETBOOKINFOReturn" type="xsd:string"/>
</wsdl:message>
122
IBM Workplace Managed Client: ISV Integration Guide
Perform the following steps to access the Web service:
1. Set up the development environment, including installing the Workplace Managed Client
Developer Toolkit, setting the target platform, and so on. For complete instructions about
how to do this, refer to:
http://www.ibm.com/developerworks/workplace/library/wmc-toolkit-basic
Download the toolkit from:
http://www.alphaworks.ibm.com/tech/wmctoolkit
It also comes as part of the Workplace Managed Client 2.6 SDK.
2. Create a new plug-in project:
a. Click File → New → Project → Plug-in Development → Plug-in Project.
b. Give the project a name, for example, com.ibm.wcttool.bookdatabase.delegate.
c. Click Finish.
This creates a new plug-in project with a plug-in class called DelegatePlugin. This project
contains all the code that communicates with the Web service.
3. Add a dependency on the com.ibm.rcp.websphere.runtime plug-in. This contains all the
classes that will be used to communicate with the Web service server.
a. Open the plug-in descriptor file. This is either the plugin.xml file or the
META-INF/MANIFEST.MF file, depending on whether or not the plug-in was created
with an OSGI manifest or not.
b. Click the Dependencies tab.
c. Click Add and type com.ibm.rcp.websphere.runtime, as shown in Figure 5-21. Click
OK.
Add button
Plug-in descriptor
Plug-in dependency
Figure 5-21 Adding the com.ibm.rcp.websphere.runtime plug-in as a dependency
4. Create a simple class to contain the information for a single book:
a. Click File → New → Class.
b. Give the class a name, for example, BookInfo, and a package,
com.ibm.wcttool.bookdatabase.delegate.
c. Add four private instance variables, title, author, description, and datePublished,
as shown in Example 5-4 on page 124, as well as getter and setter methods for each of
the variables.
Chapter 5. ISVs with Lotus Notes and Domino applications
123
Example 5-4 Partial implementation of the BookInfo value object
//BookInfo.java
package com.ibm.wcttool.bookdatabase.delegate;
import java.util.Date;
public class BookInfo {
private String title
private String author
private String description
private Date datePublished
=
=
=
=
null;
null;
null;
null;
//getter and setter methods go here....
}
5. Create an interface that contains all the methods exposed by the Web service. This is
more of a design choice, and not absolutely necessary. However, it is good practice to hide
the details of the type of communication used.
a. Select File → New → Interface
b. Give it a name, for example, IBookDatabaseDelegate, and a package,
com.ibm.wcttool.bookdatabase.delegate. Click Finish.
c. Add two methods, getTitles and getInfo, as shown in Example 5-5.
Example 5-5 The Java interface class listing the methods that the Web service exposes
//IBookDatabaseDelegate.java
package com.ibm.wcttool.bookdatabase.delegate;
import java.util.List;
public interface IBookDatabaseDelegate {
List getTitles();
BookInfo getInfo(String title);
}
6. Create an implementation of the IBookDatabaseDelegate interface that communicates with
the Web service and returns the requested information:
a. Select File → New → Class.
b. Give it a name, for example, BookDatabaseDelegateImpl, and a package,
com.ibm.wcttool.bookdatabase.delegate.impl.
c. Select IBookDatabaseDelegate as an interface that it implements. Click Add and type
in IBookDatabaseDelegate. Click OK. The two required methods will be automatically
created.
d. Click Finish.
7. Add a generic method to the BookDatabaseDelegateImpl class that accepts the following
values:
– URL of the Web service
– Operation name to invoke
– Return type of the operation
– Names of the parameters to pass to the Web service if any
– Types of the parameters
– Modes of the parameters
124
IBM Workplace Managed Client: ISV Integration Guide
– Values of the parameters
Example 5-6 shows the implementation of this method.
Example 5-6 Generic method to invoke a Web service
//BookDatabaseDelegateImpl.java
import com.ibm.ws.webservices.engine.client.Call;
import com.ibm.ws.webservices.engine.client.Service;
import com.ibm.ws.webservices.engine.encoding.XMLType;
import javax.xml.namespace.QName;
import javax.xml.rpc.ParameterMode;
import javax.xml.rpc.ServiceException;
//...
private Object call(String url, QName opName, QName retType, String[] paramNames,
QName[] paramTypes, ParameterMode[] paramModes, Object[] paramValues)
throws RemoteException, ServiceException{
Service service = new Service();
Call call = (Call) service.createCall();
call.setTargetEndpointAddress (url);
call.setOperationName( opName );
call.setReturnType(retType);
//this method makes the assumption that the four arrays are all of the same length
if(paramNames!=null && paramTypes!=null && paramModes!=null && paramValues!=null){
for(int i = 0; i < paramNames.length; i++){
call.addParameter(paramNames[i], paramTypes[i], paramModes[i]);
}
}
if(paramValues == null){
paramValues = new Object[]{};
}
Object responseObj = call.invoke(paramValues);
return responseObj;
}
8. Write the implementation of the getTitles method, which invokes the call method
defined in the previous step. The GETBOOKLIST Web service returns a
comma-separated list of book titles, and this is tokenized with a StringTokenizer. Note
how, because no parameters are being passed to the Web service, the last four
parameters of the call method are null.
Example 5-7 Using call method to invoke getBookList Web service and tokenizing the resulting string
//BookDatabaseDelegateImpl.java
//...
public List getTitles(){
List titles = new ArrayList();
try {
Object responseObj = call(url,new QName("urn:DefaultNamespace",
"getBooklist"),XMLType.XSD_STRING,null,null,null,null);
//The response type is a String, as defined by the WSDL as shown earlier
//The String contains a comma-separated list of book titles, which must be
//tokenized
String titlesString = (String) responseObj;
Chapter 5. ISVs with Lotus Notes and Domino applications
125
if (titlesString != null){
StringTokenizer tok = new StringTokenizer(titlesString,",");
while(tok.hasMoreTokens()){
titles.add(tok.nextToken());
}
}
} catch (Exception e) {
e.printStackTrace();
}
return titles;
}
9. Implement the getBookInfo method of the BookDatabaseDelegateImpl class. This method
takes a string as a parameter, passes that parameter to the getBookInfo Web service. The
value returned is a comma-separated string containing the title, author, description, and
date published, in that order. Example 5-8 gives the full implementation of this method.
Note how the parameter name is BOOKTITLE, the parameter type is XMLType.XSD_STRING,
the parameter mode is IN, and the value is the title parameter.
Note: Java API for XML (JAX)-RPC uses pass by value semantics for parameter
passing in a remote method invocation. Object-by-reference mode is not supported for
remote method invocations. JAX-RPC specifies three rules for parameter passing and
return values, IN, OUT, and INOUT:
򐂰 An IN parameter is passed as copy. The parameters value is copied before the
remote method invocation.The return value is created as a copy and returned to the
caller.
򐂰 The OUT and INOUT parameters are also passed by value. JAX-RPC uses the
Holder classes to support the OUT and INOUT parameters. The client provides an
instance of a Holder class that is passed by value for either the OUT or INOUT
parameter. The contents of the Holder class are modified in the remote method
invocation and the client uses the changed contents after the method invocation
returns.
Example 5-8 Implementation of getInfo method
public BookInfo getInfo(String title) {
BookInfo bookinfo = null;
try {
Object responseObj = call(
url,
// url of the web service
new QName("urn:DefaultNamespace", "getbookinfo") , //name of web service
XMLType.XSD_STRING,
// return type
new String[]{"BOOKTITLE"},
// parameter name
new QName[]{XMLType.XSD_STRING},
// parameter type
new ParameterMode[]{ParameterMode.IN}, // parameter mode
new Object[]{title} );
// parameter value
String titlesString = (String) responseObj;
if (titlesString != null){
bookinfo = new BookInfo();
StringTokenizer tok = new StringTokenizer(titlesString,",");
if(tok.countTokens() < 4){
return null;
}
126
IBM Workplace Managed Client: ISV Integration Guide
bookinfo.setTitle(tok.nextToken());
bookinfo.setAuthor(tok.nextToken());
bookinfo.setDescription(tok.nextToken());
bookinfo.setDatePublished(new Date(Long.parseLong(tok.nextToken())));
}
} catch (Exception e) {
e.printStackTrace();
}
return bookinfo;
}
10.Add a method to the DelegatePlugin class to return an instance of the
BookDatabaseDelegateImpl class. All other plug-ins will use this method to retrieve the
delegate. In this sample implementation, one delegate instance is created for each Web
service URL, with the delegate storing the URL in a private instance variable. Example 5-9
shows the partial implementation of the DelegatePlugin class and the
BookDatabaseDelegateImpl class.
Example 5-9 Partial implementations of the DelegatePlugin and BookDatabaseDelegateImpl classes
//DelegatePlugin.java
public class DelegatePlugin extends Plugin {
private Map delegates = new HashMap();
//...
public IBookDatabaseDelegate getDelegate(String notesUrl){
IBookDatabaseDelegate delegate = (IBookDatabaseDelegate)delegates.get(notesUrl);
if(delegate == null){
delegate = new BookDatabaseDelegateImpl(notesUrl);
delegates.put(notesUrl,delegate);
}
return delegate;
}
}
//---------------------------------------------------------------------------------------//BookDatabaseDelegateImpl.java
import com.ibm.wcttool.bookdatabase.delegate.IBookDatabaseDelegate;
public class BookDatabaseDelegateImpl implements IBookDatabaseDelegate {
private String url = null;
//...
public BookDatabaseDelegateImpl(String url) {
this.url = url;
}
//...
}
11.Export the com.ibm.wcttool.bookdatabase.delegate package so that other plug-ins can
access the classes contained in it:
a. Open the plug-in descriptor file. This is either the plugin.xml file or the
META-INF/MANIFEST.MF file, depending on whether or not the plug-in was created
with an OSGI manifest or not
b. Click the Runtime tab.
c. Click Add and choose the com.ibm.wcttool.bookdatabase.delegate package. Click
OK.
Figure 5-22 on page 128 shows these steps.
Chapter 5. ISVs with Lotus Notes and Domino applications
127
Click Add and choose package
com.ibm.wcttool.bookdatabase.delegate
Plug-in descriptor
Runtime tab
Figure 5-22 Exporting a package to make it visible to other plug-ins
After completing these tasks, the com.ibm.wcttool.bookdatabase.delegate plug-in will
contain a fully functional, albeit not precisely enterprise-ready, Web services client.
5.4.3 Creating a Workplace application project
The next step is to create a new Workplace application project. To create the project, perform
the following steps:
1. Select File → New → Project → IBM Workplace → Workplace Managed Client
Application Project, and click Next. See Figure 5-23.
Figure 5-23 Creating a new IBM Workplace Eclipse project
2. Give the project a name, for example, com.ibm.wcttool.bookdatabase, and a Display
Name, such as Book Database, as shown in Figure 5-24 on page 129.
3. Associate the book.png file with the projects icon by clicking Browse next to the icon text
box and choosing the file. Click Next.
128
IBM Workplace Managed Client: ISV Integration Guide
Figure 5-24 Setting the Project name and Display Name
Note: The application Display Name and icon appear on the application switcher bar on
the left side of Workplace Managed Client. See Figure 3-6 on page 57 for an illustration
of this.
4. Choose the multiple view page layout and do not select Automatically create default
views, as shown in Figure 5-25. Click Next.
Figure 5-25 Selecting the multiple view layout and to not Automatically create the default view classes
5. Now, create the three views.
For the topmost view:
a. Click Create New, choose the Basic Template, and click Next.
b. Set the project name to com.ibm.wcttool.bookdatabase.address.
c. Set the view ID to com.ibm.wcttool.bookdatabase.views.AddressView and click
Finish.
Chapter 5. ISVs with Lotus Notes and Domino applications
129
For the leftmost view:
a. Click Create New, choose the List View template, and click Next.
b. Set the project name to com.ibm.wcttool.bookdatabase.titlelist.
c. Set the view ID to com.ibm.wcttool.bookdatabase.views.TitlelistView and click
Finish.
For the rightmost view:
a. Click Create New, choose the Basic Template, and click Next.
b. Set the project name to com.ibm.wcttool.bookdatabase.bookinfo.
c. Set the view ID to com.ibm.wcttool.bookdatabase.views.BookinfoView and click
Finish.
This creates five new projects, a feature project, a page layout project, and three plug-in
projects representing the three views to be shown, as shown in Figure 5-26:
– The feature project, com.ibm.wcttool.bookdatabase, defines what plug-ins should be
packaged as part of the application.
– The page layout project, com.ibm.wcttool.bookdatabase.MainPage, manages the
different pages and views (though only one of each is used in this example).
– The three plug-in projects, com.ibm.wcttool.bookdatabase.address,
com.ibm.wcttool.bookdatabase.titlelist, and
com.ibm.wcttool.bookdatabase.bookinfo, contain the Eclipse view classes to be
displayed.
6. For each of the three views, set the style to NO_TITLE, as shown in Figure 5-26. This
removes the title bars from all three Eclipse views and gives the application a less
segregated look and feel.
View projects
Page layout descriptor
Feature descriptor
Style set to NO_TITLE
Figure 5-26 Initial layout of the projects for the Book Database sample application
130
IBM Workplace Managed Client: ISV Integration Guide
5.4.4 Creating the user interface
The previous section showed how to create a Workplace Managed Client application project
and how to automatically generate three view projects based on existing templates, with a
single view (AddressView) on top, and two views (TitlelistView and BookinfoView) horizontally
laid out below, as shown in Figure 5-26 on page 130. For the user interface:
򐂰 AddressView will contain a label, a text box, and a button. The user will enter the URL of
the Notes Web service in the text box and click the button to submit it.
򐂰 TitlelistView will contain a list of all available books. This is populated when the user clicks
the Submit button in AddressView.
򐂰 BookinfoView will display the information for a single book when the user double-clicks a
boot title in TitlelistView.
Inter-view communication
Communication between views is performed using property listeners. For a quick introduction
to using property listeners, see:
http://www.ibm.com/developerworks/opensource/library/os-ecllink/
Or:
http://java.sun.com/developer/onlineTraining/Beans/beans02/page3.html
The central concept to take from this article is that there is a central object, called
PropertyChangeSupport, on which listeners can be registered. These listeners are notified
when a particular property is changed, a property that is identified by a String name.
Each view has the ability to register one or more listeners and also to fire
PropertyChangeEvents that other views will receive. In this sample application, we use two
properties:
򐂰 PROPERTY_NOTES_URL, which contains the URL of the Web service being accessed
򐂰 PROPERTY_CURRENT_TITLE, which contains the title of the book being displayed
This sample project uses a simple wrapper around the PropertyChangeSupport class, called
PCSBean, as shown in Example 5-10. Use a single instance of this class, and to ensure this,
the PCSBean class is instantiated by DelegatePlugin, and all views retrieve it from there.
Example 5-10 shows this. Note that PCSBean caches all values in a HashMap object called
propertyValues.
Example 5-10 The PCSBean class
//PCSBean.java
public class PCSBean{
private java.beans.PropertyChangeSupport pcs;
private Map propertyValues = new HashMap();
public PCSBean(){
pcs = new java.beans.PropertyChangeSupport(this);
}
public void addListener(String prop, java.beans.PropertyChangeListener pcl){
pcs.addPropertyChangeListener(prop, pcl);
}
public void firePropertyChange(String name, Object newVal){
pcs.firePropertyChange(new java.beans.PropertyChangeEvent(this,name,null,newVal));
}
public Object getPropertyValue(String name){
return propertyValues.get(name);
Chapter 5. ISVs with Lotus Notes and Domino applications
131
}
}
//--------------------------------------------------------------------------------------//DelegatePlugin.java
public class DelegatePlugin extends Plugin {
public static final String PROPERTY_NOTES_URL = "notesurl";
public static final String PROPERTY_CURRENT_TITLE = "currenttitle";
//...
public PCSBean getSession() {
if(session == null){
session = new PCSBean();
}
return session;
}
}
Implementing the address view
The address view user interface is specified using a Composite class. In 5.4.3, “Creating a
Workplace application project” on page 128, a Composite class was automatically generated
in the com.ibm.wcttool.bookdatabase.address project called MyComposite. Rename this by
right-clicking the file, selecting Refactor → Rename, and typing the new name
AddressComposite. This helps avoid confusion later in the chapter, because the other two
auto-generated views also contain classes named MyComposite.
AddressComposite is a visual class that can be altered using the Visual Editor for Eclipse.
Note: Download Visual Editor for Eclipse from the following site if it is not already installed:
http://www.eclipse.org/vep
For numerous documents explaining its use, refer to:
http://www.eclipse.org/vep/WebContent/docs/doc.html
Perform the following steps to complete the AddressComposite class:
1. The three controls, a label, a text box and a button, must be added to the UI. To do this,
use the palette located on the right of the Eclipse window. Figure 5-27 shows the controls.
Figure 5-27 The AddressComposite as seen in the Visual Editor
2. Add a SelectionListener to the Submit button, which retrieves the text typed into the text
box and fires a property change event. Example 5-11 shows how to do this. Note the
parameters passed to the firePropertyChange method. The first parameter specifies the
property that has changed, and the second specifies the new value of the property.
Listeners for this property change will be notified of this new value.
Example 5-11 Adding a SelectionListener to the Submit button to fire a property change event
//AddressComposite.java
//...
public class AddressComposite extends Composite {
//..
btnSubmit.addSelectionListener(new SelectionListener(){
132
IBM Workplace Managed Client: ISV Integration Guide
public void widgetSelected(SelectionEvent ev) {
if(textAddr.getText() != null ){
DelegatePlugin.getDefault().getSession().
firePropertyChange(DelegatePlugin.PROPERTY_NOTES_URL,textAddr.getText());
}
}
public void widgetDefaultSelected(SelectionEvent ev) {widgetSelected(ev);}
});
//...
}
Implementing the title list view
In 5.4.3, “Creating a Workplace application project” on page 128, we created the project
com.ibm.wcttool.bookdatabase.titlelist, which contains one Eclipse view class,
TitlelistView, and a SWT Composite class, MyComposite. As mentioned in the previous
section, it is advisable to rename MyComposite. Right-click the file, select Refactor →
Rename, and enter the new name TitleComposite.
TitleComposite already contains an org.eclipse.swt.widgets.List widget, because it was
created using the List template by the Workplace Managed Client Developer Toolkit. Three
simple tasks must now be performed:
1. Add a PropertyChangeListener that listens for a change to the PROPERTY_NOTES_URL
property.
2. Populate the list box with the titles of the books when the PROPERTY_NOTES_URL property
changes.
3. Modify the existing listener on the list box to fire a property change event, notifying all
listeners that the currently selected book has changed.
Adding a PropertyChangeListener for the PROPERTY_NOTES_URL property
In the createPartControl method of the TitlelistView class, place the code shown in
Example 5-12 to refresh the list of books when the URL to the Web service changes. Note
how the first parameter of the addListener method specifies the property change being
listened for, while the second parameter specifies the action to be taken when the event
occurs.
Example 5-12 Adding a listener for a change in the PROPERTY_NOTES_URL property
//TitlelistView.java
public class TitlelistView extends ViewPart {
//...
public void createPartControl(Composite parent) {
composite = new TitleComposite(parent, parent.getStyle());
composite.redraw();
DelegatePlugin.getDefault().getSession().addListener(
DelegatePlugin.PROPERTY_NOTES_URL, //the property change to listen for
new PropertyChangeListener(){
//the action to perform when the event occurs
public void propertyChange(PropertyChangeEvent ev) {
refreshList(ev.getNewValue());//refreshes the list. Shown in next section
}
}
);
}
}
Chapter 5. ISVs with Lotus Notes and Domino applications
133
Populating the list box
To populate the list box with the titles of the books in the database, the Web service must be
accessed using the delegate plug-in. Define two methods:
򐂰 refreshList in the TitlelistView class to access the delegate plug-in and retrieve the list
of books
򐂰 setList in the TitleComposite class to add the list of books to the list box
Example 5-13 shows both these methods.
Example 5-13 Retrieve the list of book titles from the Web service and populate the list box with them
//TitlelistView.java
public class TitlelistView extends ViewPart {
//...
private void refreshList(Object value){
if(value == null || value.toString().equals("")){
composite.setList(new ArrayList());
return;
}
IBookDatabaseDelegate delegate =
DelegatePlugin.getDefault().getDelegate(value.toString());
composite.setList(delegate.getTitles());
}
//---------------------------------------------------------------------------------------//TitleComposite.java
public class TitleComposite extends Composite {
//...
public void setList(java.util.List newlist) {
this.list.removeAll();
//clear any items currently in the list box
for(Iterator it = newlist.iterator(); it.hasNext();){
this.list.add((String)it.next());
}
}
}
Modifying the existing list box listener
Example 5-14 shows how to add a listener to the list box that fires a PropertyChangeEvent for
the PROPERTY_CURRENT_TITLE property when the user double-clicks an item in the list box.
Example 5-14 Adding a listener that fires a property change for PROPERTY_CURRENT_TITLE
//TitleComposite.java
//...
public class TitleComposite extends Composite {
private org.eclipse.swt.widgets.List list;
//...
private void addListeners(){
list.addListener(SWT.MouseDoubleClick, new Listener() {
public void handleEvent(Event event) {
String item = list.getItem(list.getSelectionIndex());
if (item != null) {
DelegatePlugin.getDefault().getSession().
firePropertyChange(DelegatePlugin.PROPERTY_CURRENT_TITLE,item);
}
}
});
}
}
134
IBM Workplace Managed Client: ISV Integration Guide
Implementing the book information view
The book information view displays four pieces of information about the currently selected
book:
򐂰 Title
򐂰 Author
򐂰 Date published
򐂰 Description
The project com.ibm.wcttool.bookdatabase.bookinfo was automatically generated when
creating the Workplace Managed Client application project in 5.4.3, “Creating a Workplace
application project” on page 128 and contains a Composite class called MyComposite. Perform
the following steps to design the view to display the book information:
1. Rename the file InfoComposite.
2. Design the layout.
3. Add listeners for property changes.
4. Retrieve book information for a single book and update the view with it.
Renaming the MyComposite class
As with the previous two views, rename this class:
1. Right-click the MyComposite file.
2. Select Refactor → Rename and type the name InfoComposite.
Designing the layout
InfoComposite is a visual class that can edited using the visual editor. Using the palette bar to
the right of the Eclipse workbench, design the layout similar to that shown in Figure 5-28.
Figure 5-28 Layout of the InfoComposite class
Adding listeners for property changes
The book information view listens for a change in the
DelegatePlugin.PROPERTY_CURRENT_TITLE property. When this property changes, it retrieves
the information for a single book using DelegatePlugin and updates the InfoComposite class.
Example 5-15 shows how this is implemented in the sample code.
Example 5-15 Adding a PropertyChangeListener for the property PROPERTY_CURRENT_TITLE
//BookinfoView.java
public class BookinfoView extends ViewPart {
//...
public void createPartControl(Composite parent) {
Chapter 5. ISVs with Lotus Notes and Domino applications
135
mycomposite = new InfoComposite(parent, parent.getStyle());
mycomposite.redraw();
DelegatePlugin.getDefault().getSession().addListener(
DelegatePlugin.PROPERTY_CURRENT_TITLE,//The property to listen for
new PropertyChangeListener(){
//The action to perform
public void propertyChange(PropertyChangeEvent ev) {
setInfo(ev.getNewValue());
//This is defined in the next section
}
}
);
}
}
Retrieving book information and updating the view
The code that uses DelegatePlugin to retrieve book information is placed inside the setInfo
method, which is invoked when the PROPERTY_CURRENT_TITLE property changes, as shown in
Example 5-15 on page 135. Example 5-16 shows the changes necessary in the
BookinfoView and InfoComposite classes.
Example 5-16 Retrieving book information and updating the user interface
//BookinfoView.java
public class BookinfoView extends ViewPart {
//...
private void setInfo(Object val){
String url = (String)DelegatePlugin.getDefault().getSession().
getPropertyValue(DelegatePlugin.PROPERTY_NOTES_URL);
BookInfo info= DelegatePlugin.getDefault().getDelegate(url).getInfo(val.toString());
mycomposite.setInfo(info);
}
}
//-------------------------------------------------------------------------------------//InfoComposite.java
public class InfoComposite extends Composite {
//...
public void setInfo(BookInfo newInfo){
this.info = newInfo;
labelTitle2.setText(info.getTitle());
labelAuthor2.setText(info.getAuthor());
labelDate2.setText(info.getDatePublished().toString());
labelDesc2.setText(info.getDescription());
}
}
5.4.5 Deploying the application to a Workplace Collaboration Services server
See “Deploying the application to Workplace Collaboration Services server” on page 112 for
information about how to deploy the Workplace application to a Workplace Collaboration
Services server.
After completing all the necessary tasks, the user interface should look similar to the one
shown in Figure 5-29 on page 137.
136
IBM Workplace Managed Client: ISV Integration Guide
Address View
List View
Book Info View
Figure 5-29 Final Workplace Managed Client acting as Web service client to Domino database
5.5 Exploit
As stated in the introduction, complete seamless integration occurs as an ISV chooses to fully
exploit the capabilities of Workplace Managed Client.
One option for exploitation of Workplace Managed Client is to create Eclipse plug-in views as
alternative front ends to a Domino portlet. If continued evolution is desired, the Notes data
also can be accessed by custom server-side adaptors, with a complete re-implementation of
the experience and service logic as IBM Workplace Managed Client parts. For example,
Notes workflow agents contained in server-side databases can be activated as remote Web
services.
For more information about fully exploiting the Workplace Managed Client, see Chapter 6,
“Exploiting IBM Workplace Managed Client” on page 139.
5.6 Summary
There are several options for integrating an existing Lotus Notes/Domino application.
Workplace Managed Client V2.6 comes with a prebuilt plug-in to help ease the speed and
seamlessness of a Notes integration, which might prove to be more than enough to fill many
ISV business needs. Further integration options include keeping the data stored on a Notes
database while creating a Java front end.
5.7 URLs referenced in this chapter
Table 5-2 on page 138 lists the URL referenced in this chapter.
Chapter 5. ISVs with Lotus Notes and Domino applications
137
Table 5-2 List of URLs referred to in this chapter
138
What
Where
Creating a Notes/Domino plug-in with Eclipse
http://www.ibm.com/developerworks/lotus/li
brary/notes-plugin-eclipse/
IBM Workplace Collaboration Services
http://www.ibm.com/lotus/workplace
Introduction to the IBM Workplace Managed
Client Developer Toolkit
http://www.ibm.com/developerworks/lotus/li
brary/wmc-toolkit/index.html
IBM Workplace Managed Client Developer
Toolkit
http://www.alphaworks.ibm.com/tech/wmctool
kit
A quick introduction to using property listeners
http://java.sun.com/developer/onlineTraini
ng/Beans/beans02/page3.html
Visual Editor for Eclipse
http://www.eclipse.org/vep
Document library for using Visual Editor for
Eclipse
http://www.eclipse.org/vep/WebContent/docs
/doc.html
IBM Workplace Managed Client: ISV Integration Guide
6
Chapter 6.
Exploiting IBM Workplace
Managed Client
This chapter describes a number of the ways in which you can enhance an application to fully
exploit the many services that the IBM Workplace Managed Client platform offers. ISVs that
want to tightly integrate their applications with Workplace Managed Client can then use the
numerous features that add greatly to the functionality of any application. These include:
򐂰 Document libraries for sharing documents with team members
򐂰 Messaging and notification
򐂰 Online awareness
򐂰 Synchronization between local and remote data stores, enabling offline operation
򐂰 Secure database access
򐂰 Security through the client credential store
© Copyright IBM Corp. 2006. All rights reserved.
139
6.1 Overview
The Workplace Managed Client platform offers numerous powerful features to applications
that run on the platform. You can achieve a full, seamless integration of an existing
application into Workplace Managed Client by exploiting all the elements of the framework
that add value and functionality to the product. What services should be used will vary from
product to product. Some of the most useful services are:
򐂰 Document libraries for sharing documents with teammates
򐂰 Messaging and notification
򐂰 Online awareness
򐂰 Secure database access
򐂰 Synchronization between local and remote data stores, enabling offline operation
򐂰 Securing the client application
A number of the code samples in this chapter use the IBM Workplace Software Development
Kit (formerly IBM Workplace Collaboration Services API Toolkit), which can be downloaded
at:
http://www.lotus.com/ldd/lwpapi
By following the instructions that come with the kit after it is installed, you must add it as a
dependency to the application. Define two dependencies:
򐂰 Add the com.ibm.workplace.api plug-in as a dependency in the plugin.xml file. This
ensures that the API class files can be found both at compile and run time. Example 6-1
shows how this is done.
Example 6-1 Partial plugin.xml file defining the dependency on the com.ibm.workplace.api plug-in
<!--plugin.xml-->
<requires>
<import plugin="com.ibm.workplace.api"/>
...
</requires>
򐂰 Add the com.ibm.workplace.api.feature feature as a dependency in the feature.xml file
that defines the plug-ins included in the application. This ensures that when the
application is provisioned from the server to the client, the
com.ibm.workplace.api.feature feature will also be provisioned. This is necessary
because the server only sends the features that are required. Therefore, if no feature
specifies that it requires the public APIs, they will not be downloaded and installed. See
Example 6-2.
Example 6-2 XML snippet from the feature.xml file adding com.ibm.workplace.api.feature
<!--feature.xml-->
<requires>
<import feature="com.ibm.workplace.api.feature" version="2.5.1"/>
...
</requires>
Figure 6-1 on page 141 shows the location of the two XML files that must be modified.
140
IBM Workplace Managed Client: ISV Integration Guide
Figure 6-1 The feature.xml and plugin.xml files
6.2 Working with document libraries
Document libraries enable users to store files in a shared file store, organized into folders and
secured using access control policies. Document libraries can work in both offline and online
modes and can greatly enhance and simplify the secure sharing of files among a group of
users. Users can create libraries both locally on their workstation and remotely on a
Workplace Collaborative Services server. They can also choose to make any document
library available in offline mode, which results in remote libraries being replicated to the client
machine. The Workplace Collaborative APIs for document libraries support both online and
offline modes of operation and present a single interface for applications using the API.
Adding support for document libraries to an application is a relatively easy task. There are a
number of operations that can be performed with the Workplace Collaborative APIs. These
include:
򐂰 Create document library
򐂰 Create document
򐂰 Create folder
򐂰 List the contents of a library or folder
This list is far from complete, and it merely lists the aspects that we discuss in this chapter.
For a complete list, see the documentation that comes with the kit. The examples in this
section build on the Delivery Manager application described in Chapter 2, “ISVs with Eclipse
applications” on page 17. The document library functionality is built into its report generation
facility, where a generated report can be saved into any document library to which the user
has access. Figure 6-2 on page 142 shows how the Delivery Manager application can store
reports in an existing document library, create a new library, and create folders in a library.
The user also has the option of creating a new document library by opening the Warehouse
view, clicking the Report button, clicking the Create Library button, and giving the library a
name.
Chapter 6. Exploiting IBM Workplace Managed Client
141
Click to generate a report
List of available document libraries
Click to save to a document library
Click to create a
new document library
Figure 6-2 The Delivery Manager application with document libraries
6.2.1 Creating a document library
A document library is a specialized type of IBM Workplace application; others are team
spaces, chat rooms, and so on. For this reason, the ApplicationService class is used to
create a document library rather than the DocumentLibraryService class. To create a
document library using the Delivery Manager sample application, select a warehouse in the
navigation pane, click the Report button in the Warehouse view, and then click the Create
Library button.
Note: For more information about IBM Workplace collaborative applications, see:
http://publib.boulder.ibm.com/infocenter/iwphelp/v2r5m1/index.jsp?topic=/com.ibm.wcs.
ic.doc_2.5.1/infocenter/i_ovr_r_whatsnew.html
Perform the following steps to create a document library.
1. Create the factory and service classes. Example 6-3 on page 143 shows how to do this.
142
IBM Workplace Managed Client: ISV Integration Guide
Example 6-3 Creating the service and factory classes
//DlgReport.java
import com.ibm.workplace.api.app.service.ApplicationService;
import com.ibm.workplace.api.app.service.ApplicationTemplateService;
//...
ApplicationService appService = mServiceFactory.createApplicationService();
ApplicationFactory appFactory = FactoryCreator.createApplicationFactory();
2. Retrieve the application template for document libraries. A template is defined by both a
category and a name within that category. The default template categories and names are
defined in the
com.ibm.workplace.api.app.template.data.ApplicationTemplateConstants class. As
shown in Example 6-4, ApplicationTemplateRetrievalOptions can be created for more
fine-grained control over how much data is pulled from the server.
Tip: For more information about IBM Workplace templates, see the Redpaper Building
a Component for IBM Workplace, REDP-3952:
http://www.redbooks.ibm.com/abstracts/redp3952.html
Example 6-4 Retrieving the document library standard template
//DlgReport.java
import com.ibm.workplace.api.app.template.data.ApplicationTemplate;
import com.ibm.workplace.api.app.template.data.ApplicationTemplateConstants;
import com.ibm.workplace.api.app.template.data.ApplicationTemplateRetrievalOptions;
//...
ApplicationTemplateService appTemplateService =
mServiceFactory.createApplicationTemplateService();
ApplicationTemplateFactory appTemplateFactory =
FactoryCreator.createApplicationTemplateFactory();
ApplicationTemplateRetrievalOptions atro =
appTemplateFactory.createApplicationTemplateRetrievalOptions();
atro.setIncludeUsers(false);
atro.setIncludeEditors(false);
atro.setRetrieveCompleteMembers(false);
// Retrieve the ApplicationTemplate using the TEMPLATE_CATEGORY_DOCUMENTLIBRARY
// and TEMPLATE_NAME_DOCUMENTLIBRARY constants from the
// ApplicationTemplateConstants class
ApplicationTemplate template = appTemplateService.getTemplateByName(
ApplicationTemplateConstants.TEMPLATE_CATEGORY_DOCUMENTLIBRARY,
ApplicationTemplateConstants.TEMPLATE_NAME_DOCUMENTLIBRARY,
atro);
3. Use the application template to create the document library. An
ApplicationCreationOptions object is used to specify the various parameters for the
library, such as its name, description, and template ID, as shown in Example 6-5.
Example 6-5 Setting the library parameters and creating the document library application
//DlgReport.java
import com.ibm.workplace.api.app.application.data.ApplicationCreationOptions;
//...
String name = “NewLibrary”;
String description = “New Library Description”;
Chapter 6. Exploiting IBM Workplace Managed Client
143
ApplicationCreationOptions opt = appFactory.createApplicationCreationOptions();
opt.setName(name);
opt.setDescription(description);
opt.setTemplateId(template.getId());//set the template id retrieved earlier
opt.setAlias(name);
appService.createApplication(opt);//create the document library
Important: The com.ibm.workplace.api.document.service.DocumentLibraryService
interface contains the method addLibrary(DocumentLibrary). It is worth noting that this
does not create a document library that a user can access through the user interface. To
create a proper document library application, follow the steps outlined in this section.
6.2.2 Creating a new document in a document library
Workplace Managed Client allows files to be created programmatically and stored in a
document library. In the Delivery Manager sample application, this can be seen when
generating and saving a warehouse report. To do this:
1. Select a warehouse from the navigation pane on the left.
2. In the Warehouse view, click Report → Save.
3. Choose a document library and optionally a folder in which to save the document from the
list that is presented.
If the user has selected a document library, a folder named WarehouseReports is created, for
instructional purposes, and the report saved to that folder. If the user has selected a folder,
the report is simply saved to that folder.
Perform the following steps to create a new document in a document library:
1. Instantiate DocumentLibraryService and DocumentFactory objects.
DocumentLibraryService provides services to manage IBM Workplace document libraries.
You can use this service to create, delete, and modify folders and documents.
DocumentFactory creates data objects used by the Workplace Collaboration Services
DocumentLibraryService API. Example 6-6 shows how to create these two objects.
Example 6-6 Creating DocumentLibraryService and DocumentFactory objects
//DlgReport.java
import com.ibm.workplace.api.document.service.DocumentLibraryService;
import com.ibm.workplace.api.factory.DocumentFactory;
import com.ibm.workplace.api.factory.FactoryCreator;
//...
DocumentLibraryService mDocLibService =
FactoryCreator.createServiceFactory().createDocumentLibraryService();
DocumentFactory mDocFactory = FactoryCreator.createDocumentFactory();
2. Create a new Document object using the DocumentFactory object and save it using the
DocumentLibraryService object created earlier, as shown in Example 6-7 on page 145.
144
IBM Workplace Managed Client: ISV Integration Guide
Example 6-7 Creating a new document in a document library
//DlgReport.java
import com.ibm.workplace.api.document.data.Document;
//....
private boolean createDocument(String libId,String folderId,String docName,byte[] contents)
{
try {
//First create the document
Document doc = mDocFactory.createDocument();
//Set the various parameters on the document
doc.setLibraryId(libId);
doc.setParentFolderId(folderId);
doc.setContent(mHTML.getBytes());
doc.setName(docName);
doc.setFileName(docName);
doc.setDescription("This is a Warehouse Report created on "+
(new Date()).toString());
//Tell the DocumentLibraryService to add the new document to the library
mDocLibService.addEntry(doc);
return true;
} catch (WorkplaceException e) {
e.printStackTrace();
return false;
}
}
6.2.3 Creating a new folder in a document library
You can create folders programmatically in Workplace Managed Client using the
DocumentLibraryService class. In the Delivery Manager sample application, a folder named
WarehouseReports is created when the user saves a report to the root folder of a document
library. To do this:
1. Select a warehouse from the navigation pane on the left.
2. In the Warehouse view, click Report → Save.
3. Choose a document library in which to save the document from the list that is presented.
To programmatically create a new folder in a document library:
1. Instantiate DocumentLibraryService and DocumentFactory objects, as shown in
Example 6-6 on page 144.
2. Create a new DocumentFolder object and add it to the document library, as shown in
Example 6-8.
Example 6-8 Creating a new folder in a document library
//DlgReport.java
import com.ibm.workplace.api.document.data.DocumentFolder;
//...
private DocumentFolder createFolder(String libId, String folderId,
String parentFolder,String description) throws WorkplaceException{
DocumentFolder reportFolder = mDocFactory.createDocumentFolder();
reportFolder.setLibraryId(libId);
reportFolder.setName(REPORT_FOLDER);
Chapter 6. Exploiting IBM Workplace Managed Client
145
reportFolder.setDescription("Folder for storing Warehouse Reports");
reportFolder.setParentFolderId("/");//place it at the root folder
mDocLibService.addEntry(reportFolder);
return reportFolder;
}
6.2.4 Listing the contents of a library or folder
Whether to display the contents of a document library in a tree or list view, or perhaps to scan
for a particular file, there are many reasons why you might want to list the contents of a library
or a folder within a library. There are three different methods for listing the contents of
document libraries:
򐂰 Listing all the document libraries to which the current user has access
򐂰 Listing the contents of the base folder of a library
򐂰 Listing the contents of any subfolder of a library
Each of these is performed slightly differently, and we explain each in the following three
sections. All of the examples use the same retrieval options, specified in a
DocumentRetrievalOptions object. In Example 6-9, the object is instantiated and set up to
retrieve just the child objects one level down from the currently retrieved entries. This allows a
programmer to fill the list of contents of a document library gradually as required.
Example 6-9 shows a partial implementation of the ITreeContentProvider interface, which a
JFace TreeViewer uses to request data for its tree display.
Example 6-9 Partial implementation of the ITreeContentProvider interface
//DocLibContentProvider.java
import com.ibm.workplace.api.document.service.DocumentLibraryService;
import com.ibm.workplace.api.factory.DocumentFactory;
import com.ibm.workplace.api.factory.FactoryCreator;
import org.eclipse.jface.viewers.ITreeContentProvider;
public class DocLibContentProvider implements ITreeContentProvider{
private DocumentFactory
mFactory;
private DocumentRetrievalOptions
mRetrievalOptions;
private DocumentLibraryService
mService;
public DocLibContentProvider(){
try {
mFactory = FactoryCreator.createDocumentFactory();
mRetrievalOptions = mFactory.createDocumentRetrievalOptions();
//don’t download the contents of files. If just the metadata is required
//then this is a much faster option
mRetrievalOptions.setIncludeDocumentContent(false);
mRetrievalOptions.setRetrieveCompleteMembers(true);
//only get one more level of information each time it is requested
mRetrievalOptions.setDescendantDepth(DocumentRetrievalOptions.DEPTH_CHILDREN);
}
catch (WorkplaceException e){
e.printStackTrace();
}
}
public void inputChanged(Viewer viewer, Object oldInput, Object newInput){
mService = (DocumentLibraryService)newInput;
}
//....
}
146
IBM Workplace Managed Client: ISV Integration Guide
Listing all document libraries
To get a list of the available document libraries, use the
DocumentLibraryService.getLibraryDescriptions method. Example 6-10 shows how an array of
DocumentLibraryDescription objects is retrieved in the Delivery Manager application.
Example 6-10 Retrieving a list of document library description objects
//DocLibContentProvider.java
//....
public class DocLibContentProvider implements ITreeContentProvider{
//...
private DocumentLibraryDescription[] getDocumentLibraryDescriptions(
DocumentLibraryService dls)
throws WorkplaceException{
//get the list of
DataObjectList dol = dls.getLibraryDescriptions();
List objs = dol.getObjects();
DocumentLibraryDescription[] contents = new
DocumentLibraryDescription[objs.size()];
for(int i = 0; i< contents.length; i++){
contents[i] = (DocumentLibraryDescription)objs.get(i);
}
return contents;
}
//...
}
Listing the contents of a document library root folder
To retrieve the list of files and folders in a document library’s root folder, use
DocumentLibraryService.getEntries(String libraryId, DocumentRetrievalOptions). This
returns a DataObjectList value object containing a list of DocumentFolderEntry objects, each
of which can be either a folder or a file. Example 6-11 shows how this is performed in the
Delivery Manager application.
To see this in effect in the Delivery Manager application:
1. Select a warehouse from the navigation pane on the left.
2. In the Warehouse view, click Report → Save.
3. Click the + sign beside a document library to expand its root folder contents. This assumes
that document libraries exist to which the user has access and that folders exist within that
document library.
Example 6-11 Retrieving the list of files and folders in a document library’s root folder
//DocLibContentProvider.java
//....
public class DocLibContentProvider implements ITreeContentProvider{
//...
private DocumentFolderEntry[] getDocumentLibraryContents(DocumentLibraryDescription desc)
throws WorkplaceException{
String libraryId = desc.getId();
//get the list of library entries in a library
DataObjectList dol = mService.getEntries(libraryId, mRetrievalOptions);
List newList = dol.getObjects();
DocumentFolderEntry[] contents = new DocumentFolderEntry[newList.size()];
int pos = 0;
Chapter 6. Exploiting IBM Workplace Managed Client
147
for (Iterator i = newList.iterator(); i.hasNext(); pos++){
DocumentLibraryEntry entry = (DocumentLibraryEntry)i.next();
contents[pos] = entry;
}
return contents;
}
//...
Listing the contents of a subfolder of a document library
Retrieving the contents of a folder differs from retrieving the contents of the root folder of a
document library. The DocumentFolder.getEntries method is used to get a list of
DocumentFolderEntry objects. DocumentFolderEntry is a super interface of both Document and
DocumentFolder, and therefore getEntries can return both documents and folders.
Example 6-12 shows how a list of DocumentFolders contents are retrieved in the Delivery
Manager application. To list the contents of a subfolder in the Delivery Manager application:
1. Select a warehouse from the navigation pane on the left.
2. In the Warehouse view, click Report → Save.
3. Click the + sign beside a document library to expand its root folder contents.
4. Click the + sign beside one the folders to display its subfolders. This assumes that
document libraries exist to which the user has access and that folders exist within that
document library that have other folders within them.
Example 6-12 Getting the content list of a folder in the Delivery Manager application
//DocLibContentProvider.java
//....
public class DocLibContentProvider implements ITreeContentProvider{
//...
private DocumentFolderEntry[] getDocumentFolderContents(DocumentFolder folder){
if(folder == null || folder.getEntries().size() == 0){
return new DocumentFolderEntry[0];
}
List newList = folder.getEntries();
DocumentFolderEntry[] contents = new DocumentFolderEntry[newList.size()];
int pos = 0;
for (Iterator i = newList.iterator(); i.hasNext(); pos++){
DocumentFolderEntry entry = (DocumentFolderEntry)i.next();
contents[pos] = entry;
}
return contents;
}
//...
6.3 Messaging and notification
You can use the mail service API provided in the Workplace Software Development Kit
(formerly Workplace Collaboration Services API Toolkit) to manage the mailbox on the
Workplace Managed Client.
148
IBM Workplace Managed Client: ISV Integration Guide
In order to use the mail APIs in a Workplace Managed Client application:
򐂰 A dependency must be created between the application’s feature Workplace API feature.
This ensures that the Software Development Kit is provisioned down to the client, because
it will only be installed if another application requires it. See Example 6-2 on page 140 for
more information.
򐂰 A dependency must be created between each plug-in using the API and the API plug-in.
This ensures both that the application will compile and that it can find the Collaborative
API classes at run time. See Example 6-1 on page 140 for more details about how to do
this.
Example 6-13 shows how the Delivery Manager application sends mail notifications when a
warehouse report is generated. This requires the following steps:
1. Import the required classes.
2. Instantiate a ServiceFactory class. This class is used to create all other service classes in
the Collaborative APIs, for example, MailService, DocumentLibaryService, and
DiscussionService.
3. Instantiate a MailService class. MailService provides access to IBM Workplace
Messaging services. It can be used to send mail messages and to create, delete, and
modify folders and messages in the currently-authenticated user's mailbox.
4. Instantiate a MailFactory class. MailFactory creates data objects used by the Workplace
Collaboration Services MailService API such as mail messages, folders, and
attachments.
5. Create a MailMessage object using the MailFactory, and set the values of the To, Subject,
Body, and Sender fields. A number of other fields can also be set, for example, the
attachments and CC list.
6. Send the message using the MailService object.
Note: At no point is it necessary to log in to the mail server. This is because the mail API
uses the credentials of the currently authenticated user, and the ability to access or modify
data is determined by that user’s permissions.
Example 6-13 Sending a mail message using the Collaborative APIs
//DlgReport.java
import org.eclipse.jface.viewers.ITreeContentProvider;
import com.ibm.workplace.api.factory.FactoryCreator;
import com.ibm.workplace.api.factory.MailFactory;
import com.ibm.workplace.api.factory.ServiceFactory;
import com.ibm.workplace.api.mail.data.MailMessage;
import com.ibm.workplace.api.mail.data.MailSendOptions;
import com.ibm.workplace.api.mail.service.MailService;
//...
public class DocLibContentProvider implements ITreeContentProvider{
private ServiceFactory
mServiceFactory = null;
private MailService
mMailService
= null;
private MailFactory
mMailFactory
= null;
//...
private void sendEmail(String to,String from,String subject,String body,boolean saveMsg)
throws WorkplaceException{
if(mServiceFactory == null){
mServiceFactory = FactoryCreator.createServiceFactory();
}
Chapter 6. Exploiting IBM Workplace Managed Client
149
if(mMailService
mMailService
}
if(mMailFactory
mMailFactory
}
MailMessage msg
== null){
= mServiceFactory.createMailService();
== null){
= FactoryCreator.createMailFactory();
= mMailFactory.createMailMessage();
msg.setBodyText(body);
msg.getTo().add(to);
msg.setSubject(subject);
msg.setSender(sender);
MailSendOptions opt = mMailFactory.createMailSendOptions();
opt.setSaveMessage(saveMsg);
mMailService.sendMessage(msg,opt);
}
}
Note: When using methods in MailService that create or update resources, the objects
are not automatically synchronized with the corresponding resources. This means that the
objects do not necessarily reflect the current state of their corresponding resources, even if
no other user has made changes to those resources since they were retrieved.
If the updated objects are intended to be used in future operations, they should be
retrieved again after they have been altered. For example, after calling
addEntry(MailFolderEntry) or updateEntry(MailboxEntry), the MailFolderEntry or
MailboxEntry objects should be retrieved again if they are to be used again.
Important: Note the following caveats to using the mail APIs:
򐂰 The mail API methods cannot access a user's mailbox until the mailbox has been
created, for example, when the user accesses the mailbox for the first time in the IBM
Workplace user interface.
򐂰 Mailbox updates made using these methods might not be visible in the user interface
until the next time the user logs in.
򐂰 There is a defect in the 2.5.1 IBM Workplace Collaboration Services API Toolkit where
certain internal initialization steps are not performed correctly until the messaging
application has been opened. Therefore, before the mail API can be used each time the
client is booted, the messaging application must be opened; otherwise, the APIs will not
function correctly. This has been fixed for the 2.6 release.
See the Release Notes in the toolkit for more information.
For more information about the mail API, see the documentation that comes with the
Workplace Software Development Kit.
6.4 Online and offline awareness
IBM Workplace Client Technology supports building applications that are able to operate
while disconnected from a network. Applications that are disconnected from a network use
data stored locally on the client to seamlessly interact with users. The local data is a replica of
150
IBM Workplace Managed Client: ISV Integration Guide
data stored on the server and that is synchronized using the data synchronization facilities
provided by the Workplace Client Technology platform.
Taking the Workplace Managed Client offline is a user-initiated and controlled process. The
offline capability is not designed to react to unplanned network connection losses.
The offline capabilities of the client are provided by the following APIs:
򐂰 Offline Manager: This provides a public API for initiating transitions in the client’s
disconnected operating mode and is responsible for coordinating the transition of the client
to a disconnected state and for notifying applications of such state changes so that
applications can prepare for the change. Some applications need to complete tasks before
the client can go offline. For example, an application using a remote store must switch to
using a local one or another application that is relying on network resources or services,
such as instant messaging, must disable those functions. Applications register for offline
state change notifications by implementing the IOfflineService interface.
The Offline Manager generates a sequence of state-change events to prompt any
applications registered to receive such notifications to transition to the next state.
Table 6-1 shows the series of states through which the Offline Manager transitions.
Table 6-1 The various states of an offline aware application
State
Description
Online
The client is connected to the network and applications are operating in
a connected operating mode.
OfflineRequested
The user requests to disconnect from the network. On entry into this
state, the OfflineRequested event is signaled to notify applications of the
request. This is a transient state.
OfflinePending
The Offline Manager has finished notifying applications of the
OfflineRequested event and the request has not been cancelled. On
entry into this state, the GoOffline event is signaled to notify applications
to switch to disconnected operating mode. This is a transient state.
Offline
The client is connected to the network and applications are operating in
a disconnected operating mode.
OnlineRequested
A user requests to go online. On entry into this state, the
OnlineRequested event is signaled to notify applications of the request.
This is a transient state.
OnlinePending
The Offline Manager has finished notifying applications of the
OnlineRequested event and the request has not been cancelled. On
entry into this state, the GoOnline event is signaled to notify applications
to switch to connected operating mode. This is a transient state.
Figure 6-3 on page 152 shows the state transitions sequence.
Chapter 6. Exploiting IBM Workplace Managed Client
151
Figure 6-3 The offline life cycle
򐂰 Offline Service: This provides interfaces and helper classes, including IOfflineService,
that an application can use to identify what state it is currently in and what tasks it can
perform in the current state.
򐂰 Offline User Interface: This adds a File → Work Offline menu option or an Offline toggle
button in the status bar that triggers the transition in the state of the application from online
to offline. When a user clicks the Offline button or selects the Work Offline menu item, the
Offline User Interface API calls the Offline Manager to start transitioning the client to a
disconnected state. This class is provided in the com.ibm.workplace.offline plug-in.
6.4.1 The Offline API
The Workplace Managed Client’s offline capability is provided by the following APIs, available
in the com.ibm.rcp.offline plug-in.
OfflineManager
The OfflineManager API is responsible for controlling the offline state of Workplace Managed
Client. It includes the following interface and factory class:
򐂰 IOfflineManager. An interface for managing the offline state of Workplace Managed
Client. It defines methods to get and set the client’s offline state.
򐂰 IOfflineManagerFactory. A factory for creating an instance of the OfflineManager.
OfflineService
The OfflineService API is used to build offline aware components that behave appropriately
depending on the Workplace Managed Client’s offline state and that are capable of
responding to offline state changes. It includes the following interfaces and classes:
򐂰 IOfflineService. An interface that must be implemented by the class that is representing
the offline aware component. It defines the event handlers for offline events.
152
IBM Workplace Managed Client: ISV Integration Guide
򐂰 IOfflineServiceHelper. An interface provided by a helper class that registers offline
events and manages a component’s offline state.
򐂰 IOfflineServiceHelperFactory. A factory for creating an offline helper for business
delegates.
򐂰 OfflineServiceBase. An abstract base class that implements the IOfflineService
interface from which you can derive concrete offline-aware service classes.
6.4.2 Building offline-aware components
The OfflineHelper interface written for offline-capable applications is responsible for
determining the following items:
򐂰 Does the component currently have access to a server?
򐂰 Can the component access services?
To build an offline-aware component, create a component class and include code designed to
perform the following tasks:
1. Create an instance of a IOfflineHelper interface to handle business delegates or user
interface components. The helper interfaces register component offline event handlers
and manage component offline states. Example 6-14 shows instantiating the
IOfflineManager and IOfflineServiceHelper implementations in the Delivery manager
application.
Example 6-14 Instantiating the IOfflineManager and IOfflineServiceHelper implementations
//WarehouseView.java
import com.ibm.rcp.offline.api.manager.*;
import com.ibm.rcp.offline.api.service.*;
//...
public class WarehouseView extends ViewPart implements IOfflineService {
private IOfflineManager mOfflineMgr = IOfflineManagerFactory.INSTANCE.create();
/** Enables form to respond to offline events via Offline Manager. */
private IOfflineServiceHelper offlineHelper =
IOfflineServiceHelperFactory.INSTANCE.create(this);
//...
public IOfflineServiceHelper getOfflineServiceHelper() {
return offlineHelper;
}
}
2. Implement the IOfflineService interface with event handler methods to provide custom
offline behavior to respond to offline events signaled by the OfflineManager.
Example 6-15 shows how the Delivery Manager application enables or disables UI
controls depending on the online state of the client.
Example 6-15 Implementation of the IOfflineService interface in Delivery Manager application
//WarehouseView.java
//...
public class WarehouseView extends ViewPart implements IOfflineService {
//..
//When the client goes online, enable the Report button
public void goOnline() {
if(mActReport != null){
mActReport.setEnabled(true);
Chapter 6. Exploiting IBM Workplace Managed Client
153
}
}
//When the client goes offline, disable the “Report” button
public void goOffline() {
if(mActReport != null){
mActReport.setEnabled(false);
}
}
public boolean offlineRequested() {return true;}
public void offlineRequestCancelled() {}
public void offlineStateChanged() {}
public boolean onlineRequested() {return true;}
public void onlineRequestCancelled() {}
3. At any point, an application can check the online status of the client in order to determine
its execution flow. The OfflineManager.isOffline method can be used for this, as shown
in Example 6-16.
Example 6-16 Checking the online status of the client
//WarehouseView.java
//...
public class WarehouseView extends ViewPart implements IOfflineService {
private Action mActReport;
//....
public void setWarehouse(WarehouseBean warehouse){
//...
//only enable the Report button if we are online
mActReport.setEnabled(mOfflineMgr.isOnline());
}
}
4. An application can force the client of go online or offline using the
OfflineManager.goOnline and OfflineManager.goOffline methods, as shown in
Example 6-17.
Example 6-17 Requesting Workplace Managed Client to go online based on its current state
//DlgReport.java
public class DlgReport extends MessageDialog{
private DocumentLibraryService mDocLibService;
private IOfflineManager mOfflineMgr = IOfflineManagerFactory.INSTANCE.create();
//...
private boolean init(){
//...
if(mOfflineMgr.isOffline()){
MessageBox msg = new MessageBox(getShell(),SWT.YES | SWT.NO);
msg.setText("Error");
msg.setMessage("You are currently offline. Would you like to go online?");
if(msg.open() == SWT.YES){
try {
//Use the OfflineManager to request that the client switch to online mode
mOfflineMgr.goOnline();
//...
} catch (OfflineException e) {
e.printStackTrace();
return false;
}
//...
154
IBM Workplace Managed Client: ISV Integration Guide
6.5 Implementing database support
IBM Workplace Managed Client supports creating, accessing, and migrating database data to
and from the client. Workplace Managed Client supports the use of any JDBC™-compliant
database. Workplace Managed Client comes with an embedded IBM Cloudscape database,
currently at Version 10. Although it is not obligatory for Workplace Managed Client
applications to use the IBM Cloudscape database, it is well worth considering because it
provides a number of advantages, including:
򐂰 Pure Java relational database.
򐂰 Requires no administration on the client system.
򐂰 Has a very compact size of approximately 2 MB.
򐂰 Can embed database.
򐂰 Fully supports SQL-92.
򐂰 Provides its own tools such as ij to simplify data manipulation.
򐂰 The IBM Workplace Client Technology platform adds additional functionality to the
standard Cloudscape database, such as encrypted access to the database using keys
stored in the local credential store.
Useful links:
򐂰 For Cloudscape information, see:
http://www.ibm.com/software/data/cloudscape
򐂰 IBM developerWorks Cloudscape information
http://www.ibm.com/developerworks/db2/zones/cloudscape/
򐂰 The IBM Cloudscape Information Center provides in-depth details about Apache Derby
(open source Cloudscape) and Cloudscape:
http://publib.boulder.ibm.com/infocenter/cscv/v10r1/index.jsp
The Delivery Manager application uses a relational database on the server to manage its
data and post updates. After the application is fully moved to the Workplace Managed Client
platform, it does not need to always have a connection to the remote database; it can simply
connect and access the local Cloudscape database for local data storage and can further use
the Workplace Managed Client synchronization capability, as described in 6.6,
“Synchronizing client application data” on page 160, to synchronize the data between a data
store running on the client and a secondary data store running on the client or running on the
server.
Note: The majority of the mechanics of database access in Workplace Managed Client are
identical to everyday JDBC usage. This section is, therefore, not intended as a tutorial on
JDBC or SQL, and it focuses instead on the details particular to Workplace Managed
Client.
Chapter 6. Exploiting IBM Workplace Managed Client
155
6.5.1 Creating a local database
Creating a database is an operation that is usually performed once. It is standard to place it in
some initialization code, either during installation or in a plug-in start() method. To create a
local database, perform the following steps:
1. Import the plug-ins com.ibm.workplace.database.db2j.jdbc, com.ibm.rcp.database and
com.ibm.rcp.database.db2j as required plug-ins in the Eclipse plugin.xml file, as shown in
Example 6-18.
Example 6-18 Partial plugin.xml file with plug-in dependencies for database access and initialization
<requires>
<import plugin="com.ibm.workplace.database.db2j.jdbc" />
<import plugin="com.ibm.rcp.database"/>
<import plugin="com.ibm.rcp.database.db2j"/>
...
</requires>
2. Create a class called DatabaseUtil with a method to load the Workplace Managed Client
database driver com.ibm.workplace.db2j.jdbc.WCTDB2jDriver required during the
database initialization. Example 6-19 does this using the loadDbDriver method.
Example 6-19 Partial implementation of DatabaseUtil.java to load the database driver
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
public class DatabaseUtil {
private static final String CSDRIVER = "com.ibm.workplace.db2j.jdbc.WCTDB2jDriver";
//The loadDbDriver
//using the String
public static void
java.sql.Driver
}
method loads the WMC specific JDBC database driver
specified in CSDRIVER
loadDbDriver() throws Exception {
driver = (java.sql.Driver) Class.forName(CSDRIVER).newInstance();
public static Connection getConnection(String dbname,boolean isCreateDB)
throws Exception {
loadDBDriver();
// database connection code goes here
//.....
}
public static void shutdownDbDriver()
throws Exception {
// database shutdown code goes here
}
}
3. In the same DatabaseUtil class, create a method to retrieve the database connection. In
the connection URI, set the value for the connection property create to true in order to
create the new database. If the local data store must be encrypted, the value for
connection property encryption should be set to true. Otherwise, set it to false.
Format the connection URI as follows, delimiting the properties with semicolons, where
connection_property can be one or more of the properties described in Table 6-2 on
page 157:
jdbc:wct:<database_name>;<connection_property1>; <connection_property2>
156
IBM Workplace Managed Client: ISV Integration Guide
Table 6-2 Database connection URI properties available to Workplace Managed Client applications
Connection property
Description
create
Boolean value that specifies whether or not the JDBC driver should create
the specified database if it does not exist. The default value is false.
shutdown
Boolean value that specifies whether or not the database should be
unloaded from the Java virtual machine. The default value is false.
encryption
Boolean value that specifies whether or not the JDBC driver should open
or create an encrypted database. If the value of this property is true, the
JDBC driver retrieves the encryption key from the local credential store to
open the database and encrypt the it.
Example 6-20 shows the partial implementation of the DatabaseUtil class with a method
that creates the DeliveryManager database.
Example 6-20 Partial implementation of DatabaseUtil.java with method to create the database
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
public class DatabaseUtil {
private static final String CSDRIVER =
"com.ibm.workplace.db2j.jdbc.WCTDB2jDriver";
public static void loadDbDriver()
throws Exception {
java.sql.Driver driver = (java.sql.Driver) Class.forName(CSDRIVER).newInstance();
}
public static Connection getConnection(String dbname,boolean isCreateDB)
throws Exception {
loadDbDriver();
String createStr = “false”;
if (isCreateDB){
createStr = “true”;
}
return DriverManager.getConnection("jdbc:wct:" + dbname
+ ";create=” + createStr + “;encryption=" + "false" +";");
}
}
Note: The local database will be automatically created in the Workplace Managed
Client run-time workspace. The default location for the Workplace Managed Client
run-time workspace is <user-home>\IBM\RCP\<identifier>\<user name>. For example,
in Microsoft Windows, this location is generally C:\Documents and Settings\<user
name>\IBM\RCP\<identifier>\<user name>.
4. Call the method getConnection() of the DatabaseUtil class from the Eclipse plug-in code
where the database creation code is to be executed. Example 6-21 on page 158 gives an
example of an Eclipse Action class retrieving the database connection and initializing the
database.
Chapter 6. Exploiting IBM Workplace Managed Client
157
Example 6-21 Sample Eclipse Action class to create local database
import java.sql.*;
public class DBCreateAction extends Action implements IWorkbenchWindowActionDelegate{
public void run(){
Thread dbCreation = new Thread(){
Public void run(){
try {
DatabaseUtil.getConnection("DeliveryManager",true);
}
catch (Exception e) {
e.printStackTrace();
}
}
};
dbCreation.start();
}
}
Note: The database creation should always be performed in the background using a
non-UI thread.
5. Finally, the database connection should always be cleanly closed using the
connection.close() method after the database operation has completed.
6.5.2 Accessing the database
A database designed for Workplace Managed Client can be encrypted to secure the data
contained within it. Workplace Managed Client databases are encrypted with a key derived
from the password of the authenticated user. Developers can access an encrypted IBM
Cloudscape database using the standards-based Java Database Connectivity (JDBC)
connector driver that the client provides in the com.ibm.workplace.database.db2j.jdbc
plug-in. To access the encrypted database, the client JDBC driver retrieves the authenticated
user's key from the local credential store, uses it to decrypt the database, and then accesses
the decrypted database.
To connect to a local, encrypted IBM Cloudscape database using the client JDBC driver,
perform the following steps:
1. Add the required plug-ins com.ibm.workplace.database.db2j.jdbc,
com.ibm.rcp.database, and com.ibm.rcp.database.db2j to the Eclipse plugin.xml file.
See Example 6-18 on page 156 for detailed instructions.
2. Create the DatabaseUtil class with a method to load the Workplace Managed Client
database driver com.ibm.workplace.db2j.jdbc.WCTDB2jDriver required for database
access. Use the same DatabaseUtil class created during database initialization. See
Example 6-19 on page 156 for more details.
3. In the DatabaseUtil class, create a method to get the database connection. In the
connection URI set the value for connection property create as false since the database
already exists. See Example 6-20 on page 157 for more details.
4. Call the method getConnection() of the DatabaseUtil class to retrieve the database
connection object. All operations that use the connection object to access the database
are written using all the standard JDBC method calls, such as
Connection.createStatement, Statement.executeQuery, and Statement.executeUpdate.
158
IBM Workplace Managed Client: ISV Integration Guide
5. After finishing accessing the database, close the database connection using
connection.close(). The method should look similar to the method shown in
Example 6-22.
Example 6-22 Sample Java class to access the Delivery Manager database using DatabaseUtil class
import
import
import
import
import
java.sql.Connection;
java.sql.Driver;
java.sql.DriverManager;
java.sql.SQLException;
com.ibm.wcttool.sldlv2.sync.Van;
public class DlvMgrDBUtil
{
public void storeVanInfo(String VanID,Van vanObj){
final Van vanObj = vanObj;
final Connection connection;
Thread dbCreation = new Thread(){
Public void run(){
try {
connection = DatabaseUtil.getConnection("DeliveryManager",false);
String SELECT_QUERY = " SELECT * from VAN where VANID='" + VanID + "'";
Statement statement = conn.createStatement();
ResultSet rs = statement.executeQuery(SELECT_QUERY);
while (rs.next()) {
// the application logic goes here
vanObj.setVanID(rs.getString(“VANID“));
vanObj.setOwner(rs.getString(“OWNER“));
...
}
} catch (Exception e) {
e.printStackTrace();
} finally {
//Connection cleanup should always be in a finally block, so it
//will always be executed
if(connection != null)connection.close();
}
}
};
dbCreation.start();
}
}
Note: The database access operation must always be performed in the background using
a non-UI thread.
6.5.3 Shutting down the database
The database connection must be shut down when the user exits from Workplace Managed
Client. Perform the following steps in order to shut down the database:
1. As in the previous examples, include the required plug-ins
com.ibm.workplace.database.db2j.jdbc, com.ibm.rcp.database, and
com.ibm.rcp.database.db2j. See Example 6-18 on page 156.
Chapter 6. Exploiting IBM Workplace Managed Client
159
2. Add a method in the DatabseUtil class to shut down the local database. Use the same
DatabaseUtil class created during database initialization. In the connection URI, set the
value for connection property shutdown as true, as shown in Example 6-23.
Example 6-23 Partial implementation of DatabaseUtil.java with method to shut down the database
import
import
import
import
java.sql.Connection;
java.sql.Driver;
java.sql.DriverManager;
java.sql.SQLException;
public class DatabaseUtil {
public static void loadDbDriver() throws Exception {
// Load the WMC cloudscape Driver
}
public static Connection getConnection(String dbname,boolean isCreateDB)
throws Exception {
// Db connection code goes here
}
public static void shutdownDbDriver()
throws Exception {
try {
Connection conn= java.sql.DriverManager.getConnection("jdbc:wct:;shutdown=true");
} catch (SQLException e) {
}
}
}
3. Call the DatabaseUtil.shutdownDbDriver() method. In a generic Java application, this
can be from a shutdown hook. However, in Eclipse, it generally makes sense to place this
code in the plug-in’s stop() method, as shown in Example 6-24.
Example 6-24 Sample Eclipse plug-in class to shut down the Workplace Managed Client database
import java.sql.SQLException;
public class SldlvPlugin extends AbstractUIPlugin
{
public void stop(BundleContext context) throws Exception{
try {
DatabaseUtil.shutdownDbDriver();
} catch (SQLException e) {
}
}
//...
}
6.6 Synchronizing client application data
A Workplace Managed Client application can be enabled to synchronize data between a data
store running on the client and a secondary data store also running locally on the client or
running remotely on a server. Workplace Managed Client provides extensions for triggering
160
IBM Workplace Managed Client: ISV Integration Guide
the synchronization of its data. The client provides a framework that schedules the execution
of application-specific synchronization code:
򐂰 Synchronization Manager UI
The Workplace Client Technology Synchronization Manager UI enables a user to initiate
and control synchronization of local data stores through one or more application-supplied
data synchronization services. The local data stores to be synchronized are registered by
an application using the Workplace Client Technology Synchronization Manager API.
򐂰 Synchronization Manager
The Workplace Client Technology Synchronization Manager provides a programmatic
interface for registering, initiating, and controlling the synchronization of local data stores
through one or more application-supplied data synchronization services.
򐂰 Synchronization Service
An application-supplied software component that handles all aspects of data
synchronization using a well-defined service protocol. This includes registration of local
data stores to be synchronized, as well as initiation and control of synchronization
sessions.
Figure 6-4 shows the Workplace Client Technology synchronization framework and
application-specific components.
Workplace Client
Technology
Framework
Layer
Application
Layer
Figure 6-4 Synchronization framework and application-specific components
The synchronization framework supports the following APIs:
򐂰 Synchronization Manager API
A public interface for managing data synchronization that contains the following interfaces:
– SynchronizationManager
Public interface to the Workplace Client Technology Synchronization Manager. The
Workplace Client Technology SynchronizationManager provides methods to:
•
Define which client replica data stores are available to be synchronized
•
Initiate and terminate synchronization of one or all known replica data stores
•
Determine the status of synchronization tasks in progress
Chapter 6. Exploiting IBM Workplace Managed Client
161
– IReplicaSubscription
Interface type for a data object representing a protocol-specific replica subscription,
that is, a synchronizable data store on the client.
Synchronization protocol agents that implement the ISyncService interface must
supply a concrete implementation of IReplicaSubscription to represent the
protocol-specific data store replicas that it handles.
򐂰 Synchronization Service SPI
A service API for adding a custom data synchronization service or protocol agent to an
application that contains the following items:
– An extension point called com.ibm.rcp.sync.syncservices that implements the
ISyncServiceFactory interface.
– ISyncServiceFactory
An interface implemented by the factories that create instances of a synchronization
service or protocol agent.
– SyncService
An interface implemented by a synchronization service or protocol agent.
Note: Workplace Managed Client does not provide the code that handles the
synchronization itself. A synchronization factory class must be implemented that defines
the application-specific synchronization logic, including creating service-specific
IReplicaSubscription objects representing individual data stores that can be
synchronized using the service.
The Workplace Managed Client Synchronization Manager initializes the synchronization of all
registered data stores. It is not possible to just replicate a single data store or document.
When Workplace Managed Client synchronization is triggered either manually or
automatically, all data stores registered with the Synchronization Manager are replicated.
The Delivery Manager application can be enabled to synchronize the data between a data
store running on the client and a secondary data store running on the server after it is fully
moved to the Workplace Managed Client platform and is enabled to use the local data store.
Implementing a custom synchronization engine
Workplace Managed Client must be instructed how to handle data synchronization by
providing a protocol agent. In the protocol agent, the behavior specific to the synchronization
engine is defined. This tells the com.ibm.rcp.sync.api code how to handle
application-specific data to be synchronized.
The ReplicationSubscription object represents a protocol-specific synchronizable data
store and is used by the API to identify what data needs synchronizing.
To add a custom synchronization protocol agent to the platform, perform the following steps:
1. Add the dependency for the com.ibm.rcp.sync plug-in to the Eclipse plugin.xml file, as
shown in Example 6-25.
Example 6-25 Partial plugin.xml file with the plug-in dependency on com.ibm.rcp.sync plug-in
<requires>
<import plugin="com.ibm.rcp.sync"/>
...
</requires>
162
IBM Workplace Managed Client: ISV Integration Guide
2. Extend the com.ibm.rcp.sync.syncservices extension point in the plugin.xml file to add a
custom synchronization engine, as shown in Example 6-26.
Example 6-26 Partial eclipse plugin.xml file with com.ibm.rcp.sync.syncservices extension point
<extension point="com.ibm.rcp.sync.syncservices">
<servicefactory type="com.ibm.wcttool.sldlv2.sync.StoreSyncService"
factoryClass= "com.ibm.wcttool.sldlv2.sync.StoreSyncServiceFactory"
id=" com.ibm.wcttool.sldlv2.sync.StoreSyncService">
</servicefactory>
</extension>
3. Implement a factory class that creates the custom synchronization protocol agent by
implementing the ISyncServiceFactory interface. As shown in Example 6-26, the
factoryClass parameter must be identical to the absolute class name of the
ISyncServiceFactory implementation contained in the plug-in. Example 6-27 shows the
example code for implementing the ISyncServiceFactory interface.
Example 6-27 Example code for implementing the ISyncServiceFactory implementation
package com.ibm.wcttool.sldlv2.sync;
import
import
import
import
com.ibm.rcp.sync.api.exception.SyncException;
com.ibm.rcp.sync.api.service.ISyncService;
com.ibm.rcp.sync.api.service.ISyncServiceFactory;
com.ibm.wcttool.sldlv2.sync.StoreSyncService;
public class StoreSyncServiceFactory implements ISyncServiceFactory {
public ISyncService getSyncService() throws SyncException {
return new StoreSyncService();
}
public String getServiceType() {
return StoreSyncService.SERVICE_TYPE;
}
}
4. As shown in Example 6-28, implement the ISyncService interface to add replication
subscriptions that identify what data to replicate. Remember, in Example 6-26, the type
parameter must be identical to the absolute class name of the ISyncService
implementation.
Example 6-28 Example code for implementing the ISyncService interface implementation
package com.ibm.wcttool.sldlv2.sync;
import com.ibm.rcp.sync.api.data.*;
import com.ibm.rcp.sync.api.service.ISyncService;
import com.ibm.wcttool.sldlv2.sync.*;
public class StoreSyncService implements ISyncService {
private static String SERVICE_TYPE = "com.ibm.wcttool.sldlv2.sync.StoreSyncService";
private int syncState = 0;
public void addReplicaSubscription(IReplicaSubscription arg0)
throws Exception, RemoteException {
}
public void cancelSync(String arg0) throws Exception, RemoteException {
}
public void cancelSyncAll() throws Exception, RemoteException {
Chapter 6. Exploiting IBM Workplace Managed Client
163
}
public void deleteReplicaSubscription(IReplicaSubscription arg0)
throws Exception, RemoteException {
}
public String getLastError(String arg0) throws Exception, RemoteException {
return null;
}
public IReplicaSubscription getReplicaSubscription(String arg0)
throws Exception, RemoteException {
return null;
}
public int getSyncStatus(String arg0) throws Exception, RemoteException {
//return an actual sync status instead of always 0
return syncState;
}
public IReplicaSubscription[] getUserReplicaSubscriptions(String arg0)
throws Exception, RemoteException {
StoreReplicaSubscription[] repSub = new StoreReplicaSubscription[1];
repSub[0] = new StoreReplicaSubscription(null,null,null,null,null);
return repSub;
}
public void sync(IReplicaSubscription arg0, boolean arg1)
throws Exception, RemoteException {
syncState = ISyncStatus.STATUS_IN_PROGRESS;
// Initialize and execute the syncManager that will
// perform the custom synchronization
//...
syncState = ISyncStatus.STATUS_OK;
}
public void syncAll(String arg0, String arg1, boolean arg2)
throws Exception, RemoteException {
}
public void updateReplicaSubscription(IReplicaSubscription arg0, boolean arg1)
throws Exception, RemoteException {
}
}
As mentioned earlier in this section, Workplace Managed Client does not provide the code
that handles the synchronization itself. There are a few approaches an ISV can take for
data management, read-only, queued writing, and local cache, as shown in Table 6-3.
Table 6-3 Considerations for using the data management options
164
Scenario
Consideration
Read-only
Synchronize into the local database the minimum data with which application
wants to work when disconnected.
Only read-only operations are supported.
In the Delivery Manager example, a replica of the Warehouse, Van, and
Store data can be created, but not the Orders or Stock data when
synchronization occurs.
If offline, the local database can be queried for data display, but operations
such as New and Edit are disabled. This can be done with very little code
change.
Synchronization conflicts cannot occur, because the database is read-only.
IBM Workplace Managed Client: ISV Integration Guide
Scenario
Consideration
Queued writing
This scenario builds on the read-only scenario.
Still only synchronize the basic data, but instead of disabling write operations
when offline, they can take place.
Instead of writing the results to the normal tables, queue them up in different
tables.
When back online, those queue tables are emptied and the contents are
pushed to the corporate server just as though they had all been entered at
that moment.
More code needs to be written for this approach, but Workplace Client
Technology provides the structures to organize it all.
Conflicting business logic is managed server-side when the client is back
online and each modification is processed.
Local cache
In this scenario, the application always reads and writes from the local
database.
Parity is maintained with the corporate servers through synchronization
when online.
This is a very good option for circumstances where the data set to which any
individual has access is not very large and real-time information is not
required, for example, when a user is likely to be disconnected much more
than they are connected.
This does not require a lot of code to be changed in the application.
The bulk of the code for supporting this goes into the handlers registered with
the synchronization API.
Conflicting business logic must accommodate changes to both the local and
remote database.
5. Create a class that implements the IReplicaSubscription interface to represent the
application-specific data. The getUserReplicaSubscriptions() method in the
synchronization service class refers to the IReplicaSubscription implementation, as
shown in Example 6-29.
Example 6-29 Example code for implementing the IReplicaSubscriptionBasr interface
import com.ibm.rcp.sync.api.data.ReplicaSubscriptionBase;
import com.ibm.wcttool.sldlv2.sync.StoreSyncService;
public class StoreReplicaSubscription extends ReplicaSubscriptionBase {
public StoreReplicaSubscription(String arg0, String arg1,
String arg2, String arg3, String arg4) {
super(arg0, arg1, arg2, arg3, arg4);
}
public String getType() {
return StoreSyncService.SERVICE_TYPE;
}
}
The Workplace Client Technology Synchronization Manager UI calls the Workplace Client
Technology Synchronization Manager to synchronize all registered data stores. The
Workplace Client Technology Synchronization Manager calls each registered
Synchronization Service to synchronize the data stores registered with them.
Chapter 6. Exploiting IBM Workplace Managed Client
165
6.7 Securing a client application
Workplace Client Technology provides a secured platform that protects application data.
Capabilities for single sign-on (SSO) with the operating system are built into Workplace
Managed Client by default.
Workplace Client Technology uses the local credential store to store user name and password
credentials. Workplace Managed Client applications can access the local credential store by
decrypting the store with the password supplied by the user at sign-on and can create
password credentials for authenticating with remote servers.
Workplace Client Technology also provides the security APIs that enable you to log in to the
HTTP-authenticated application programmatically.
6.7.1 Logging in to the local credential store
Workplace Client Technology uses the local credential store to store user name and
password credential information. The local credential store is a local encrypted XML file.
Credentials stored within the local store are available only to the system that hosts the file.
Users are prompted for the IBM Workplace user name and password when they start a rich
client product. After the user name and password are verified, IBM Workplace creates a local
credential store.
The security API provided in the com.ibm.rcp.security.core plug-in enables an application
to log in to the local credential store programmatically. To log in to the local credential store
programmatically, perform the following steps:
1. Add the dependency on the com.ibm.rcp.security.core plug-in in the Eclipse plugin.xml
file, as shown in Example 6-30.
Example 6-30 Partial plugin.xml file with the added depends on com.ibm.rcp.security.core plug-in
<requires>
<import plugin="com.ibm.rcp.security.core"/>
...
</requires>
2. Use the login() method of an ICredentialStoreLoginContext instance to log in to the
local credential store, as shown in Example 6-31.
Example 6-31 Partial implementation for MyCredentialStore.java class to log in to local credential store
import java.io.IOException;
import java.util.Properties;
import com.ibm.rcp.security.api.cred.login.ICredentialStoreLoginContext;
import com.ibm.rcp.security.api.cred.login.ICredentialStoreLoginContextFactory;
import
import
import
import
import
javax.security.auth.callback.Callback;
javax.security.auth.callback.CallbackHandler;
javax.security.auth.callback.NameCallback;
javax.security.auth.callback.PasswordCallback;
javax.security.auth.callback.UnsupportedCallbackException;
public class MyCredentialStore {
String usr = "wpsadmin";
String passwd = "wpsadmin";
166
IBM Workplace Managed Client: ISV Integration Guide
public MyCredentialStore(String userName, String password){
usr = userName;
passwd = password;
}
protected void accessLocalCredentialStore() {
try {
ICredentialStoreLoginContext loginContext =
ICredentialStoreLoginContextFactory.INSTANCE.create();
loginContext.login(getLoginCallback(usr,passwd),new Properties());
} catch (Exception e) {
e.printStackTrace();
}
}
private CallbackHandler getLoginCallback(final String username,
final String password) {
CallbackHandler callbackHandler = new CallbackHandler() {
public void handle(Callback[] cb) throws IOException,
UnsupportedCallbackException {
for (int i = 0; i < cb.length; i++) {
if (cb[i] instanceof NameCallback) {
((NameCallback) cb[i]).setName(username);
} else if (cb[i] instanceof PasswordCallback) {
((PasswordCallback) cb[i]).setPassword(password.toCharArray());
} else {
throw new UnsupportedCallbackException(cb[i]);
}
}
}
};
return callbackHandler;
}
}
3. Call the method accessLocalCredentialStore() of class MyCredentialStore from the
Eclipse plug-in class that wants to access the local credential store, as shown in
Example 6-32.
Example 6-32 Partial implementation of MyCredCheck.java class
import com.ibm.wcttool.sldlv2.security.MyCredentialStore;
...
public class MyCreadCheck {
public void loginToLocalCredStore() {
new MyCredentialStore("wpsadmin", "wpsadmin")
.accessLocalCredentialStore();
}
}
6.7.2 Creating a password credential for remote server authentication
Using com.ibm.rcp.security.core APIs, the password credentials can be created to
authenticate with the remote servers. The user must be prompted to supply a user name and
password the first time that user tries to access the remote server. The application can store
the user name and password in the credential store. On subsequent use, the application
provides this credential to the remote server by retrieving it from the credential store.
Chapter 6. Exploiting IBM Workplace Managed Client
167
Note: Creating credentials prevents the user from being repeatedly prompted for
authentication information.
To create a password credential for a remote server, perform the following steps:
1. Add the dependency on the com.ibm.rcp.security.core plug-in in the plugin.xml file of
the Eclipse plug-in project created for the application that wants to use Workplace Client
Technology security APIs. See Example 6-30 on page 166 for further details.
2. Use the login() method of an ICredentialStoreLoginContext instance to log in to the
local credential store. See Example 6-31 on page 166 for further details.
3. Call the method accessLocalCredentialStore() of class MyCredentialStore from the
Eclipse plug-in class that wants to access the local credential store. See Example 6-32 on
page 167 for further details.
4. As shown in Example 6-33, create a password credential using the
IHttpCredentialManager.createPassword() method in the MyCredentialStore.java
class. Modify the existing MyCredentialStore.java class shown previously in
Example 6-31 on page 166.
Example 6-33 Partial implementation of MyCredentialStore.java to create password credentials
import
import
import
import
import
....
com.ibm.rcp.security.api.cred.IPasswordCredential;
com.ibm.rcp.security.api.cred.login.ICredentialStoreLoginContext;
com.ibm.rcp.security.api.cred.login.ICredentialStoreLoginContextFactory;
com.ibm.rcp.security.internal.CredentialStore;
com.ibm.rcp.security.internal.CredentialStoreFactory;
public class MyCredentialStore {
String usr = "wpsadmin";
String passwd = "wpsadmin";
public MyCredentialStore(String userName, String password) {
usr = userName;
passwd = password;
}
protected void accessLocalCredentialStore() {
// The code to access local credential store goes here
}
private CallbackHandler getLoginCallback(final String username,
final String password) {
// The callback handler implementation
}
public void createMyPasswordCredential() {
try {
CallbackHandler callbackHandler = getLoginCallback(usr,
passwd);
IPasswordCredential cred = CredentialStoreFactory.getCredentialStore( ).
getHttpCredentialManager().createPassword(
new URL("http://authenticationHost.com"),
"AuthRealm", new URL[] { new URL("ibm.com") },
CredentialStore.SCOPE_LOCAL, callbackHandler);
cred.remove();
} catch (Exception e) {
e.printStackTrace();
}
}
}
168
IBM Workplace Managed Client: ISV Integration Guide
5. Call the method createMyPasswordCredential() of class MyCredentialStore.java from
the Eclipse plug-in class that wants to create the password credentials to access the
remote server, as shown in Example 6-34.
Example 6-34 Partial implementation of MyCredCheck.java class
import com.ibm.wcttool.sldlv2.security.MyCredentialStore;
...
public class MyCreadCheck {
public void createRemoteCredentials(){
new MyCredentialStore().createMyPasswordCredential();
}
}
6.7.3 Logging in to an HTTP-authenticated application
The communication between Workplace Managed Client and an IBM Workplace
Collaboration Services server is authenticated automatically. The security APIs provided with
the com.ibm.rcp.security.core plug-in enable a Workplace Managed Client application to
log in to an alternate HTTP-authenticated application. The security APIs provided with the
com.ibm.rcp.security.core plug-in also enable the single sign-on (SSO) capability for
remote HTTP applications.
To log in to an HTTP-authenticated application programmatically, perform the following steps:
1. Add the dependencies on the com.ibm.rcp.security.core and
com.ibm.rcp.apache.httpclient plug-ins in the Eclipse plugin.xml file, as shown in
Example 6-35.
Example 6-35 Partial Eclipse plugin.xml file with added dependencies
<requires>
<import plugin="com.ibm.rcp.security.core"/>
<!-- needs to import the plugin com.ibm.rcp.net.apache.httpclient to work
with httpclient Cookie. -->
<import plugin="com.ibm.rcp.net.apache.httpclient"/>
<!-- needs to add the browser dependancies to launch the
embedded browser -->
<import plugin="com.ibm.rcp.ui"/>
<import plugin="com.ibm.rcp.ui.browser"/>
<import plugin="com.ibm.rcp.ui.browser.core"/>
...
</requires>
2. Use the login() method of the IHttpFormLoginContext instance to log in to an HTTP
form-based application, as shown in Example 6-36.
Example 6-36 Partial implementation of MyCredentialStore.java class
import com.ibm.rcp.security.api.http.login.IHttpFormLoginContext;
import com.ibm.rcp.security.api.http.login.IHttpFormLoginContextFactory;
import com.ibm.rcp.security.api.login.LtpaCookieCallback;
...
public class MyCredentialStore {
String usr = "wpsadmin";
Chapter 6. Exploiting IBM Workplace Managed Client
169
String passwd = "wpsadmin";
String host = "myworkplace.ibm.com";
public MyCredentialStore(String userName, String password) {
usr = userName;
passwd = password;
}
public MyCredentialStore() {
// The empty constructor
}
private CallbackHandler getLoginCallback(final String username,
final String password) {
CallbackHandler callbackHandler = new CallbackHandler() {
public void handle(Callback[] cb) throws IOException,
UnsupportedCallbackException {
for (int i = 0; i < cb.length; i++) {
if (cb[i] instanceof NameCallback) {
((NameCallback) cb[i]).setName(username);
} else if (cb[i] instanceof PasswordCallback) {
((PasswordCallback) cb[i]).setPassword(password
.toCharArray());
} else if (cb[i] instanceof LtpaCookieCallback){
// do nothing
}
else {
throw new UnsupportedCallbackException(cb[i]);
}
}
}
};
return callbackHandler;
}
protected void HTTPLogin() {
IHttpFormLoginContext loginContext = IHttpFormLoginContextFactory.
INSTANCE.create();
try {
loginContext.login( host,
80,
"/lwp/j_security_check",
false,
getLoginCallback(usr,passwd),
null);
} catch ( Exception e) {
e.printStackTrace();
}
}
}
3. As shown in Example 6-37 on page 171, retrieve the LTPA token from the authenticated
HTTP login context using the getCredentialCookie() method. This returns the LTPA
token encoded as a cookie.This token can be used further to enable the single sign-on
(SSO) capability for remote HTTP applications using the method
launchContext.setSingleSignOnCookie(cookie.getValue(),
ILaunchContext.CREDENTIAL_LTPA). Update the existing HTTPLogin() method in the
MyCredentialStore.java class shown previously in Example 6-22 on page 159 to achieve
the same result.
170
IBM Workplace Managed Client: ISV Integration Guide
Example 6-37 Partial implementation of MyCredentialStore.java class to retrieve the LTPA token
import javax.security.auth.callback.*;
import javax.security.auth.login.LoginException;
import org.apache.commons.httpclient.Cookie;
mport com.ibm.rcp.platform.api.PlatformContext;
import com.ibm.rcp.security.api.cred.*;
import com.ibm.rcp.security.api.http.login.IHttpFormLoginContext;
import com.ibm.rcp.security.api.http.login.IHttpFormLoginContextFactory;
import com.ibm.rcp.security.api.login.LtpaCookieCallback;
import com.ibm.rcp.ui.browser.core.api.*;
//...
public class MyCredentialStore {
private String usr = "wpsadmin";
private String passwd = "wpsadmin";
private String host = "myworkplace.ibm.com";
private String url = "http://myworkplace.ibm.com/lwp/myworkplace";
public MyCredentialStore(String userName, String password) {
usr = userName;
passwd = password;
}
public MyCredentialStore() {
// The empty constructor
}
private CallbackHandler getLoginCallback(final String username,
final String password) {
// impmement the callback handler
}
protected void HTTPLogin() {
IHttpFormLoginContext loginContext = IHttpFormLoginContextFactory.INSTANCE.create();
try {
loginContext.login( host,
80,
"/lwp/j_security_check", //servlet used to authenticate a user
false,
getLoginCallback(usr,passwd),
null);
Cookie ltpaCookie = loginContext
.getCredentialCookie(IHttpFormLoginContext.CREDENTIAL_LTPA);
String ltpaData = ltpaCookie.getValue();
Date expiryDate = ltpaCookie.getExpiryDate();
ILaunchContext launchContext = LaunchBrowserFactory.createLaunchContext(url);
launchContext.setSingleSignOnCookie(ltpaCookie.getValue(),
ILaunchContext.CREDENTIAL_LTPA);
ILaunchBrowser launchBrowser = LaunchBrowserFactory.getBrowserInstance();
launchBrowser.launch(launchContext);
} catch ( Exception e) {
e.printStackTrace();
}
}
}
Note: Retrieving the LTPA token from the authenticated HTTP login context and using
the same enables single sign-on (SSO) for the remote HTTP application.
Chapter 6. Exploiting IBM Workplace Managed Client
171
Note: The /lwp/j_security_check servlet is used by form-based authentication to
authenticate a user.
4. Call the HTTPLogin() method of the MyCredentialStore class from the Eclipse plug-in
class that wants to retrieve the LTPA token from the authenticated HTTP login context, as
shown in Example 6-38.
Example 6-38 Partial implementation of MyCredCheck.java file
import com.ibm.wcttool.sldlv2.security.MyCredentialStore;
...
public class MyCreadCheck {
public void getLTPAToken(){
new MyCredentialStore().HTTPLogin();
}
}
6.7.4 Single sign-on interoperating with the operating system
Using single sign-on (SSO) with the operating system enables a Workplace Managed Client
user to access resources protected by the client without having to reauthenticate after they
have logged in to their workstation. If the user name and password provided by the user while
logging in to the operating system are identical to the ones stored in the local credential store,
the client grants access to secure client resources without prompting the user to provide
credentials a second time.
Using single sign-on with the operating system is enabled for rich client products and
supported on the following operating systems:
򐂰 Microsoft Windows 2000 Professional with Service pack 2
򐂰 Microsoft Windows XP with Service Pack 1
򐂰 Red Hat Enterprise Linux WS 3.0 with Update 3
Important: Before enabling the single sign-on (SSO) feature provided by Workplace
Managed Client on Windows and Linux, ensure that:
򐂰 The user name and password credentials for the Windows or Linux operating system
are the same as the user name and password credentials for the local credential store.
򐂰 The operating system user has sufficient access permissions to modify the Windows
registry and add services to the system.
Single sign-on with Microsoft Windows
After Workplace Managed Client is installed on the desktop, perform the following steps to
configure the client for single sign-on (SSO) with Microsoft Windows:
1. Go to the Workplace Managed Client installation location and navigate to the following
directory:
<WMC_HOME>\rcp\eclipse\features\com.ibm.rcp.security.sso.win32.feature_1.2.1\os\wi
n32\x86
2. Run the ssoinstall.cmd file, as shown in Figure 6-5 on page 173.
172
IBM Workplace Managed Client: ISV Integration Guide
Execute this
command
Need to
reboot
Figure 6-5 Command execution to enable SSO on windows
3. Restart the system.
Important: To verify that the single sign-on service is running, click Start → Settings →
Control Panel, open the Administrative Tools folder and click Services. The single sign-on
feature is running if the list of services includes IBM Rich Client Platform Single Logon with
a status of Started, a startup type of Automatic, and the Log On As value set to
LocalSystem, as shown in Figure 6-6.
Chapter 6. Exploiting IBM Workplace Managed Client
173
Workplace Managed Client SSO
enablement
Figure 6-6 Workplace Managed Client single sign-on (SSO) verification for Windows
Single sign-on with Linux
The following instructions assume that you have some understanding of Linux system
administration and Linux security administration, especially the configuration of Pluggable
Authentication Modules (PAM). See the following site for the Linux PAM configuration:
http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/pam.html#toc4
After Workplace Managed Client is installed on the desktop, perform the following steps to
configure the client for SSO with Linux:
1. Log in as the user (su) to root in Linux shell.
2. Go to the Workplace Managed Client installation location and navigate to the following
directory:
<WMC_HOME>\rcp\eclipse\features\com.ibm.rcp.security.sso.win32.feature_1.2.1\os\lin
ux\x86
3. Run the installsso script.
4. Open the /etc/pam.d/gdm file and add the extra lines shown in bold italics in
Example 6-39.
Example 6-39 Modified /etc/pam.d/gdm file to enable SSO on linux
#%PAM-1.0
auth
auth
auth
auth
account
password
password
session
session
session
174
required
required
required
required
required
required
required
required
optional
required
pam_unix2.so nullok #set_secrpc
pam_env.so
pam_stack.so service=system-auth
pam_nologin.so
pam_stack.so service=system-auth
pam_rcpsso.so debug
pam_stack.so service=system-auth
pam_stack.so service=system-auth
pam_console.so
pam_rcpsso.so debug
IBM Workplace Managed Client: ISV Integration Guide
5. Open the /etc/pam.d/xdm file and add the extra lines shown in bold italics in
Example 6-39 on page 174.
6. Open the /etc/pam.d/passwd file and add the extra lines shown in bold italics in
Example 6-40.
Example 6-40 Modified /etc/pam.d/passwd file to enable SSO on linux
#%PAM-1.0
auth
account
password
password
required
required
required
required
pam_stack.so
pam_stack.so
pam_stack.so
pam_rcpsso.s
service=system-auth
service=system-auth
service=system-aut
debug
7. Restart the system.
The Workplace Managed Client security aspects described throughout this section were done
by the Redpaper team for an example application. To fully implement all Workplace Managed
Client security features, see the documentation that comes with the kit.
6.8 Summary
This chapter has shown a number of ways in which an application can be enhanced to fully
exploit the many services offered by Workplace Managed Client, such as document libraries,
messaging and notification, online/offline awareness, local data storage, synchronization, and
securing Workplace Managed Client application. ISVs that want to tightly integrate their
applications with Workplace Managed Client can use the numerous features that greatly add
to the functionality of any application.
Chapter 6. Exploiting IBM Workplace Managed Client
175
176
IBM Workplace Managed Client: ISV Integration Guide
A
Appendix A.
IBM Workplace Managed Client
Version 2.6
This appendix discusses the various changes and additions that the IBM Workplace
Managed Client Version 2.6 provides. These include:
򐂰 Provisioning
򐂰 Personalities
򐂰 Online and network awareness
򐂰 Live names
򐂰 File type registry
򐂰 Branding
򐂰 IBM Workplace Managed Client Tool for Eclipse
򐂰 Managed provisioning component
򐂰 The calendar service API
򐂰 Alias password credential
The following topics address new features, feature enhancements, or changes since
Version 2.5.1.
© Copyright IBM Corp. 2006. All rights reserved.
177
Note: The Web Services for Remote Portlets (WSRP) Technology Preview for Workplace
Managed Client is available for use with IBM Workplace Managed Client 2.6. The WSRP
Technology Preview 2.5.1 is part of the IBM Workplace Managed Client 2.5.1 Technology
Preview package. This package will remain at the 2.5.1 level and will not be updated for
Release 2.6. For instructions to make the WSRP Technology Preview work with Release
2.6, see:
http://www.ibm.com/developerworks/workplace/products/clienttechnology/
IBM Business Partners are able to obtain the IBM Workplace Managed Client 2.5.1
Technology Preview package and the IBM Workplace Managed Client 2.6 through the IBM
Software Access Catalog on PartnerWorld at:
http://www.developer.ibm.com/isv/welcome/guide/value.htm
Clients who want to obtain the IBM Workplace Managed Client 2.5.1 Technology Preview
package should contact their IBM Sales representative.
Provisioning the application from CD or HTTP server
Customers can deploy the client and custom applications from a CD or HTTP server without
having to first install Workplace Collaboration Services. Using this mechanism, ISVs can do
initial deployments with low bandwidth connectivity.
To learn more about how to create the installation image of an application and how to deploy
and provision the application from CD or HTTP server, refer to IBM Workplace Managed
Client API Toolkit User’s Guide, Version 2.6, wmcapi26_ug.pdf, that comes with the IBM
Workplace Software Development Kit at:
http://www.lotus.com/ldd/lwpapi
Platform and custom personalities
Eclipse has a nice mechanism involving pluggable applications and workbench advisors,
enabling consumers of the Eclipse platform to customize the life cycle and the look and feel of
the platform. The problem is that there is only one instance of the WorkbenchAdvisor per
Eclipse instance. Workplace Managed Client must support multiple, simultaneous
applications running, each with one or more window of their own, with customized look and
feel.
The term application is already used in the Eclipse platform, so Workplace Managed Client
defines the term personality instead, that is, a window with a set of widgets, a life cycle, and
other such features.
Personalities are classes contributed by extension point. Each personality extends the base
class com.ibm.platform.Personality. The personality class corresponds to a subset of the
functionally available on the org.eclipse.ui.applications.WorkbenchAdvisor class.
178
IBM Workplace Managed Client: ISV Integration Guide
Note: The IBM Workplace personality is the default personality applied to a provisioned
application if no other personality is specified. It builds the perspective used by the
application based on the RCPML it retrieves from the server.
To test the application in the IDE, specify -personality com.ibm.workplace.personality
as a program argument to make it run within a Workplace Managed Client runtime
environment.
Workplace Managed Client provides the API that ISVs can use to implement a custom
personality and it also provides a standard Platform personality that you can extend to create
a custom personality. The advantage of extending the Platform personality instead of creating
a personality from scratch is that the Platform personality implements the following features:
򐂰 Enables the ISV to plug into the IBM Workplace Managed Client provisioning framework.
The provisioning framework requires support for dynamic perspectives built by RCPML.
Note: There are no public APIs exposing the RCPML mechanism for building pages, so
ISVs cannot implement RCPML-derived perspectives on the platform unless the ISV
application uses the IBM Workplace personality or a custom personality that extends
the Platform personality.
򐂰 Populates the switcher bar with applications having RCPML-based or standard Eclipse
perspectives.
򐂰 Builds the following user interface components for an application:
– Menu bar
– Toolbar
– Banner area
– Status bar
– Switcher bar
– Side bar
– Tabbed view
– Embedded browser
The base personality framework is only good for creating stand-alone Workplace Managed
Client applications. Support for custom personalities is provided in the com.ibm.rcp.platform
plug-in. The IBM Workplace Client Technology com.ibm.rcp.platform.api code supports
running multiple applications, each with its own frameset and look and feel, simultaneously in
the same JVM.
To learn more about how to use the Platform personality
com.ibm.rcp.platform.PlatformPersonality and custom personality
com.ibm.rcp.platform.personality, refer to IBM Workplace Managed Client API Toolkit
User’s Guide, Version 2.6, wmcapi26_ug.pdf, that comes with the IBM Workplace Software
Development Kit at:
http://www.lotus.com/ldd/lwpapi
Appendix A. IBM Workplace Managed Client Version 2.6
179
Offline and network awareness
The platform’s offline capability is provided by the following APIs:
򐂰 OfflineManager
Responsible for controlling the offline state of the platform. It includes the following
interface and factory class:
– IOfflineManager
An interface for managing the offline state of the platform. It defines methods to get and
set the platform’s offline state.
– OfflineManagerFactory
A factory for creating an instance of OfflineManager.
򐂰 NetworkAware
Used to build offline-aware components that behave appropriately depending on the
platform’s offline state and that are capable of responding to offline state changes. It
includes the following interfaces and classes:
– INetworkAware
An interface that must be implemented by the class that is representing the
offline-aware component. It defines the event handlers for offline events.
– OfflineServiceHelper
An interface provided by a helper class that registers offline events and manages a
component’s offline state.
– IOfflineServiceHelperFactory
A factory for creating an offline helper for business delegates.
– NetworkAwareBase
An abstract base class that implements the INetworkAware interface from which you
can derive concrete offline-aware service classes.
Note: The INetworkAware interface replaces the IOfflineService in Version 2.6.
To learn more about how to enable the Workplace Client Technology platform’s offline and
network awareness capability using the com.ibm.rcp.offline plug-in, refer to IBM Workplace
Managed Client API Toolkit User’s Guide, Version 2.6, wmcapi26_ug.pdf, that comes with the
IBM Workplace Software Development Kit.
Live names component
The live names component adds presence awareness to user interface components. It adds
presence information to data items that you identify as name objects, such as user names
and e-mail address, and enables other users to interact with the name object to get
information, such as the user’s online status. It also enables users to initiate tasks, such as
chats.
180
IBM Workplace Managed Client: ISV Integration Guide
The Workplace Managed Client LiveNames API consists of the following interfaces and
classes:
򐂰 LiveNameController
A class that implements a single lightweight live name object on a page. Instantiate an
object of this class instead of the LiveNameViewer class when it is required to display a
large number of live names on a single page. This class requires you to implement the
ILiveNameListener interface to listen for status changes and that you draw the user
interface.
򐂰 LiveNameViewer
A class that implements each live name in a list of live name objects on a page. Instantiate
an object of this class instead of the LiveNameController class when it is required to
display a finite list of live names on a page. The advantage of using the LiveNamesViewer
class instead of the LiveNameController class is that the API does the work of drawing the
user interface and is therefore easier to implement.
򐂰 ILiveNameListener
An interface that returns the status of a user represented by a live name and that must be
implemented by consumers of the LiveNameController API. This interface must be
implemented before instantiating a LiveNameController object because the implemented
listener must be passed, along with a user name or e-mail address, into the
LiveNameController class. When the LiveNameController object receives an object
containing user data, it returns the user data to the listener, so the listener methods have
access to the data they need to draw the user interface.
򐂰 ILiveNameSelection
An interface identifying live name objects to which you can define object contributions to
contribute actions to the live names context menu by extending the
org.eclipse.ui.popupMenus extension point.
To learn more about how to use the Workplace Client Technology platform’s live name
component using the com.ibm.rcp.ui.livenames and com.ibm.rcp.ui.livenames.widgets
plug-ins, refer to IBM Workplace Managed Client API Toolkit User’s Guide, Version 2.6,
wmcapi26_ug.pdf, that comes with the IBM Workplace Software Development Kit.
File type registry component
The file type registry component provides a repository for storing file types supported by the
platform. The IBM Workplace Messaging, IBM Workplace Documents, and IBM Workplace
productivity tools can only view and edit documents with file types defined in the registry. The
file type registry API enables an ISV application to add custom file types to the registry.
After adding a file type in the Workplace Managed Client registry, and associated actions and
handlers for it to the registry, the application needs to establish support for files of that type in
the registry. Other IBM Workplace applications can use the handlers provided to perform
actions on documents having the same file type in their own implementations.
To learn more about how to add the file type in the registry and how to access it using the
com.ibm.rcp.registry.filetype and com.ibm.rcp.registry.filetype.ui plug-ins, refer to
IBM Workplace Managed Client API Toolkit User’s Guide, Version 2.6, wmcapi26_ug.pdf,
that comes with the IBM Workplace Software Development Kit.
Appendix A. IBM Workplace Managed Client Version 2.6
181
Customizing the application look and feel along with branding
An important step in designing a custom application is to apply a look and feel to the
application user interface that makes the application identifiable as your product. The look
and feel is determined by the window titles, banner graphics, background colors, and font
styles the application uses. A custom theme to an application can be applied using the
org.eclipse.ui.themes extension point to customize the appearance of the user interface.
Themes allow the applications to define color and font entities and theme entities and they
allow applications to selectively override default color and font specifications.
The IBM Workplace Managed Client platform uses the org.eclipse.core.runtime.products
extension point to define the com.ibm.rcp.platform plug-in as the core product plug-in for the
platform. It also specifies the plugin_customization.ini file stored in this plug-in as the
initialization file. The client retrieves the window preference settings from the core products
plug-in’s initialization file.
To customize the brand identify of an application, do one of the following actions:
򐂰 Use the product plug-in defined for the IBM Workplace Managed Client platform by
default, and overwrite the preferences that it sets using org.eclipse.ui.themes extension
point.
򐂰 Identify a new application plug-in as the product plug-in and provide an initialization file to
define the color and font settings.
To learn more about how to change the application look and feel using the custom branding
and custom theme supported by the com.ibm.rcp.platform plug-in, refer to IBM Workplace
Managed Client API Toolkit User’s Guide, Version 2.6, wmcapi26_ug.pdf, that comes with the
IBM Workplace Software Development Kit.
Changing the embedded browser’s default Web address
The rich client embedded browser always opens the http://www.ibm.com Web site when a
user first starts the browser. Users can click the home button to switch to a Web address that
they have defined as the default address in the browser preferences, but the next time they
start the embedded browser, it again defaults to the IBM site. You can change the default Web
address setting for the embedded browser to display your own Web address instead of the
IBM Web address.
To learn more about how to change the embedded Web browser’s default Web address, refer
to IBM Workplace Managed Client API Toolkit User’s Guide, Version 2.6, wmcapi26_ug.pdf,
that comes with the IBM Workplace Software Development Kit.
Workplace Managed Client Toolkit
The name of this product has changed from IBM Workplace Managed Client Toolkit to IBM
Workplace Managed Client Tool for Eclipse.
The following features are new:
򐂰 When you choose a graphic to serve as the application branding icon, it is displayed in the
dialog box, so you can verify that it is the correct graphic file.
򐂰 All page RCPML parameters can be edited, except the rcpView parameter. The
feature-related parameters that were not editable previously can now be edited.
182
IBM Workplace Managed Client: ISV Integration Guide
򐂰 More than one application can be exported at a time.
򐂰 Multilingual display names can be provided for applications and views.
򐂰 RCPML parameters can be added to the application as well as the views.
򐂰 You can use the WMC Properties pane to edit application settings made using the New
Application wizard.
򐂰 You can define a desktop icon to enable an application to be started in stand-alone mode
and to be selected from the switcher bar in Workplace Managed Client.
򐂰 You can resize panes in a page layout by dragging the pane separators in the Layout
properties editor, instead of having to change the ratio parameter values of the views
occupying the panes.
򐂰 A perspective can be generated from an application.
򐂰 An application can be packaged for deployment and installed on an IBM WebSphere
Portal server using a single wizard.
򐂰 Any personality available from the target platform can be applied to the application when
setting up the launch configuration.
򐂰 Samples of using live names, document library APIs, and databases have been provided
with the SDK.
Managed provisioning component
The managed provisioning component provides a means for installing, updating, and
managing client applications from a central administrative server. To learn more about how to
use the managed provisioning component, refer to IBM Workplace Managed Client API
Toolkit User’s Guide, Version 2.6, wmcapi26_ug.pdf, that comes with the IBM Workplace
Software Development Kit.
Using XML Access scripts to create the page and portlet
To use XML Access scripts to create the page and portlet that represent the Workplace
Collaboration Services API component on IBM WebSphere Portal, refer to IBM Workplace
Managed Client API Toolkit User’s Guide, Version 2.6, wmcapi26_ug.pdf, that comes with the
IBM Workplace Software Development Kit.
Implementing the calendar service API
You can use the calendar service API provided with the IBM Workplace Software
Development Kit to manage a calendar on the client. Keep the following things in mind when
managing a calendar:
򐂰 The IBM Workplace Software Development Kit APIs use a model that depends on
factories that create data and services. The FactoryCreator class creates these factories.
򐂰 Use an appropriate service and data factory for the task you want to perform. For example,
to manage the contents of a calendar, use the CalendarService and the CalendarFactory.
򐂰 When you make a request to the calendar service, it provides a snapshot of the current
state of the calendar. Before you implement an action that requires the current calendar
state information, you must explicitly retrieve the latest information from the calendar.
Appendix A. IBM Workplace Managed Client Version 2.6
183
To learn more about implementing the calendar service API, refer to IBM Workplace
Managed Client API Toolkit User’s Guide, Version 2.6, wmcapi26_ug.pdf, that comes with the
IBM Workplace Software Development Kit.
Creating an alias password credential
You can use an “alias” to identify credentials. The only credentials currently supported in the
platform credential store are password credentials that consist of a user name and password
combination. Using an alias to identify the credential helps to protect it. To learn more about
creating an alias password credential, refer to IBM Workplace Managed Client API Toolkit
User’s Guide, Version 2.6, wmcapi26_ug.pdf, that comes with the IBM Workplace Software
Development Kit.
184
IBM Workplace Managed Client: ISV Integration Guide
B
Appendix B.
IBM Workplace 2.5.1 menu IDs
This appendix provides details about the menu IDs defined for IBM Workplace Collaboration
Services. The items described here include:
򐂰 Top-level menu items
򐂰 IBM Workplace Collaboration Services-specific top-level menu items
򐂰 Group markers for adding to menus and end groups
򐂰 Menu actions
© Copyright IBM Corp. 2006. All rights reserved.
185
IBM Workplace menu IDs overview
An application can contribute an action item to an existing menu path in the IBM Workplace
user interface by extending the actionSets extension point and supplying a corresponding
IBM Workplace menu ID in the path attribute of the menu element. The menu IDs defined for
the IBM Workplace Collaboration Services are defined as constants in the
IWorkplaceActionConstants.java file.The application can use these constants to determine
where an action will be displayed in the user interface.
IBM Workplace menu IDs
The following tables provide details about the menu IDs.
Table B-1 Top-level menu items consistent with Eclipse menu items
Constant value
Reference in menu tag as
FILE_MENUID = file /
*IWorkbenchActionConstants.M_FILE*/
path= “additions” and id=”file“
EDIT_MENUID = edit /
*IWorkbenchActionConstants.M_EDIT*/
path= “edit/<submenutitle>” and id= “<customString>”
WINDOW_MENUID = window /
*IWorkbenchActionConstants.M_WINDOW*/
HELP_MENUID = help /
*IWorkbenchActionConstants.M_HELP*/
id= “help”
Table B-2 IBM Workplace Collaboration Services-specific top-level menu items
Constant value
Reference in menu tag as
VIEW_MENUID = com.ibm.rcp.ui.viewmenu
path= “additions” id= “com.ibm.rcp.ui.viewmenu” or path=
“edit” id= “com.ibm.rcp.ui.viewmenu” or path=
“com.ibm.rcp.ui.viewmenu/<submenutitle>” id=
“<customString>”
ACTIONS_MENUID = com.ibm.rcp.ui.actionsmenu
path= “com.ibm.rcp.ui.viewmenu” id=
“com.ibm.rcp.ui.actionsmenu” or path=
“com.ibm.rcp.ui.actionsmenu/additions” id=
“<customString>”
TOOLS_MENUID = com.ibm.rcp.ui.toolsmenu
path= “com.ibm.rcp.ui.actionsmenu” id=
“com.ibm.rcp.ui.toolsmenu” or path=
“com.ibm.rcp.ui.toolsmenu/ <submenutitle>” id=
“<customString>”
186
IBM Workplace Managed Client: ISV Integration Guide
Table B-3 Group markers for adding to menus and end groups
Constant value
Reference in menu tag as
Use to
MB_ADDITIONS =
IWorkbenchActionConstants.
MB_ADDITIONS
path = “additions”
Add top level group marker contributions.
For example: path= “additions” id=
“com.ibm.rcp.ui.viewmenu”
Or add contributions to top level group
markers.
For example: path=
“com.ibm.rcp.ui.toolsmenu/ additions” id=
“MyStatusMenu” >
ENDGROUP_SUFFIX = _end
path = “_end”
Specifies that a contribution should appear at
the end of an existing menu.
MB_WCTADDITIONS = wctadditions
path = “wctadditions”
Add top level group marker contributions after
the tools menu.
For example: path= “wctadditions” id=
“OSMWInsert” >
Table B-4 File menu group markers
Constant value
FILE_NEW_GROUP = “fileNewGroup”
FILE_OPEN_GROUP = “ fileOpenGroup”
FILE_OPENINNEWTAB_GROUP = “fileOpenInNewTabGroup”
FILE_FOLDER_GROUP = “fileFolderGroup”
FILE_MENU_GROUP = “ fileMenuGroup”
FILE_MENUADDITIONS_GROUP = “fileMenuAdditionsGroup”
FILE_IMPORT_GROUP = “fileImportGroup” ;
FILE_EXPORT_GROUP = “fileExportGroup” ;
FILE_EXPORTASPDF_GROUP = “fileExportAsPDFGroup”
FILE_PRINT_GROUP = “ filePrintGroup”
FILE_PRINTPREVIEW_GROUP = “ filePrintPreviewGroup”
FILE_PROPERTIES_GROUP = “filePropertiesGroup”
FILE_PREFERENCES_GROUP = “filePreferencesGroup”
FILE_EXIT_GROUP = “fileExitGroup”
Table B-5 Common File menu actions
Constant value
FILE_CLOSE_ACTION_ID = “com.ibm.rcp.ui.filemenu.close”
FILE_EXIT_ACTION_ID = “com.ibm.rcp.ui.filemenu.exit”
FILE_PREFERENCES_ACTION_ID = “com.ibm.rcp.ui.filemenu.preferences”
FILE_OPEN_ACTION_ID = “ com.ibm.rcp.ui.filemenu.open”
FILE_PRINT_ACTION_ID = “com.ibm.rcp.ui.filemenu.print”
Appendix B. IBM Workplace 2.5.1 menu IDs
187
FILE_PRINTPREVIEW_ACTION_ID = “com.ibm.rcp.ui.filemenu.printpreview”
FILE_PAGESETUP_ACTION_ID = “com.ibm.rcp.ui.filemenu.pagesetup”
Table B-6 Edit menu group markers
Constant value
EDITMENU_UNDO_GROUP = “editmenuUndoGroup”
EDITMENU_GROUP1 = “editmenuGroup1”
EDITMENU_GROUP2 = “editmenuGroup2”
EDITMENU_GROUP3 = “editmenuGroup3”
Table B-7 Common Edit menu actions
Constant value
EDIT_REDO_ACTION_ID = “com.ibm.rcp.ui.editmenu.redo”
EDIT_UNDO_ACTION_ID = “com.ibm.rcp.ui.editmenu.undo”
EDIT_CUT_ACTION_ID = “com.ibm.rcp.ui.editmenu.cut”
EDIT_COPY_ACTION_ID = “com.ibm.rcp.ui.editmenu.copy”
EDIT_PASTE_ACTION_ID = “com.ibm.rcp.ui.editmenu.paste”
EDIT_FIND_ACTION_ID = “com.ibm.rcp.ui.editmenu.find”
EDIT_DELETE_ACTION_ID = “com.ibm.rcp.ui.editmenu.delete”
EDIT_SELECT_ALL_ACTION_ID = “com.ibm.rcp.ui.editmenu.selectall”
EDIT_MOVETOFOLDER_ACTION_ID = “com.ibm.rcp.ui.editmenu.movetofolder”
Table B-8 View menu group markers
Constant value
VIEWMENU_GROUP1 = “viewmenuGroup1”
VIEWMENU_GROUP2 = “viewmenuGroup2”
VIEWMENU_GROUP3 = “ viewmenuGroup3”
VIEWMENU_GROUP4 = “viewmenuGroup4”
VIEWMENU_GROUP5 = “viewmenuGroup5”
VIEWMENU_MAXIMIZETAB_GROUP = “viewmenuMaximizeTabGroup”
188
IBM Workplace Managed Client: ISV Integration Guide
Table B-9 Common View menu actions
Constant value
VIEW_SHOW_ACTION_ID = “com.ibm.rcp.ui.viewmenu.show”
VIEW_SHOW_STATUSBAR_ACTION_ID = “com.ibm.rcp.ui.viewmenu.show.statusbar”
VIEW_SHOW_PREVIEWPANE_ACTION_ID = “com.ibm.rcp.ui.viewmenu.show.previewpane”
VIEW_SHOW_SEARCHBAR_ACTION_ID = “com.ibm.rcp.ui.viewmenu.show.searchbar”
VIEW_SHOW_SWITCHERBAR_ACTION_ID = “com.ibm.rcp.ui.viewmenu.show.switcherbar”
VIEW_SHOW_SWITCHERLABELS_ACTION_ID = “com.ibm.rcp.ui.viewmenu.show.switcherlabels”
VIEW_SHOW_SIDEBAR_ACTION_ID = “com.ibm.rcp.ui.viewmenu.show.sidebar”
VIEW_MAXIMIZECURRENTTAB_ACTION_ID = “com.ibm.rcp.ui.viewmenu.maximizecurrenttab”
Table B-10 Actions menu group markers
Constant value
ACTIONSMENU_GROUP1 = “actionsmenuGroup1”
ACTIONSMENU_CANCEL_GROUP = “actionsCancelGroup”
ACTIONSMENU_EDIT_GROUP = “editGroup”
ACTIONSMENU_ACTIONS_GROUP = “actionsGroup”
ACTIONSMENU_RESOLVECONFLICT_GROUP = “resolveConflictGroup”
ACTIONSMENU_SLIDESHOW_GROUP = “slideShowGroup”;
ACTIONSMENU_GROUP2 = “actionsmenuGroup2”
ACTIONSMENU_GROUP3 = “actionsmenuGroup3”
Table B-11 Tools menu group markers
Constant value
TOOLSMENU_GROUP1 = “ toolsmenuGroup1”
TOOLSMENU_LIBRARY_GROUP = “ toolsmenuLibraryGroup”
Table B-12 Help menu group markers
Constant value
HELP_ABOUT_ACTION_ID = “com.ibm.workplace.client.common.ui.aboutaction”
BOOKMARKS_MENUID = “bookmarks”
Appendix B. IBM Workplace 2.5.1 menu IDs
189
190
IBM Workplace Managed Client: ISV Integration Guide
C
Appendix C.
Additional material and feature
quick reference
This section refers to additional material that can be downloaded from the Internet. We also
provide a quick reference for the various features provided by IBM Workplace Managed
Client explained in this paper.
© Copyright IBM Corp. 2006. All rights reserved.
191
Locating the Web material
The Web material associated with this Redpaper is available in softcopy on the Internet from
the IBM Redbooks Web server. Point your Web browser to:
ftp://www.redbooks.ibm.com/redbooks/REDP4119
Alternatively, you can go to the IBM Redbooks Web site at:
ibm.com/redbooks
Select the Additional materials and open the directory that corresponds with the Redpaper
form number, REDP4119.
Using the Web material
The additional Web material that accompanies this Redpaper includes the following files:
File name
EclipseRCP.zip
Notes.zip
Swing.zip
Web.zip
AllCombined.zip
Description
Eclipse RCP example code
Notes and Domino example code
Swing example code
Web and portal example code
All example code
Each of the first four ZIP files corresponds to an individual chapter.
How to use the Web material
Create a directory (folder) and unzip the contents of the Web material zip files into this folder.
There are four individual archive files, with the AllCombined.zip file containing all four. Each
contains two or more of the following folders:
1. Coexist
2. Accommodate
3. Leverage
4. Exploit
Each of these folders correspond to the documented level of integration in each of the
appropriate chapters. Each of these folders contains two subfolders, src and deploy.
The src folder in each contains one or more Eclipse projects that can be imported into an
Eclipse workspace with an IBM Workplace Client Technology development environment
installed, as described in the developerWorks article located at:
http://www.ibm.com/developerworks/workplace/library/wmc-toolkit-basic
To do this:
1. Select File → Import → Existing Projects Into Workspace.
2. For each project under the src folder, select it and click Finish.
The deploy folder contains either complete applications, or a Workplace Managed Client
deployable set, which can be easily installed on a Workplace Collaborative Services server
by following the DeployInstructions.txt file that is packaged with each project.
192
IBM Workplace Managed Client: ISV Integration Guide
For example, Example C-1 shows how the EclipseRCP archive is laid out, with greater detail
provided for the Accomodate folder.
Example: C-1 Partial layout of the EclipseRCP archive file
EclipseRCP
- 1. Coexist
- deploy
- src
- 2. Accomodate
- deploy
- com.ibm.wcttool.sldv2
- features
com.ibm.wcttool.sldv2_1.0.0.jar
- images
van.png
- plugins
com.ibm.wcttool.sldlv1_1.0.0.jar
com.ibm.wcttool.sldv2.switcher_1.0.0.jar
DeleteScript.xml
DeployInstructions.txt
siteFragment.xml
- src
- com.ibm.wcttool.sldv1
- com.ibm.wcttool.sldv2
- com.ibm.wcttool.sldv2.MainPage
- com.ibm.wcttool.sldv2.switcher
- 3. Leverage
- deploy
- src
- 4. Exploit
- deploy
- src
To execute a Workplace Managed Client application project from Eclipse or IBM Rational
Application Developer, follow the instructions at:
http://www.ibm.com/developerworks/workplace/library/wmc-toolkit-basic
Workplace Managed Client feature quick reference
Table C-1 Feature quick reference
Feature
Code package
Documentation section
Action bar
EclipseRCP/3
Leverage/src.com.ibm.wcttool.sldv2
2.4.4, “Using an action bar to replace the
view toolbar” on page 38
Menus
EclipseRCP/3
Leverage/src.com.ibm.wcttool.sldv2
2.4.5, “Contributing to the Workplace
Managed Client menus” on page 39
Swing/2
Accomodate/src/embeddedApp/com.ibm.
wcttool.demviewer.pane1
3.4.1, “Contributing to the Workplace
Managed Client menus” on page 60
EclipseRCP/3
Leverage/src.com.ibm.wcttool.sldv2
2.4.6, “Adding a Workplace Managed
Client search bar” on page 40
Web/3
Leverage/src/com.ibm.wcttool.web.pane1
4.4.2, “Adding a Workplace Managed
Client search bar” on page 95
Search bar
Appendix C. Additional material and feature quick reference
193
Feature
Code package
Documentation section
Shelf view
EclipseRCP/3
Leverage/src.com.ibm.wcttool.sldv2
2.4.7, “Adding a Workplace Managed
Client shelf view” on page 43
Status bar
Swing/3
Leverage/src/com.ibm.wctdemo.awtint.ste
p3
3.4.2, “Status bar integration” on page 68
Embedded Web browser
Web/2
Accomodate/src/com.ibm.wcttool.web.pan
e1
4.3.2, “Launching the embedded browser”
on page 83
HTTP authentication
Web/3
Leverage/src/com.ibm.wcttool.web.pane1
4.4.1, “HTTP authenticated application” on
page 89
Document libraries
EclipseRCP/4
Exploit/src/com.ibm.wcttool.sldlv2
6.2, “Working with document libraries” on
page 141
Messaging and notification
EclipseRCP/4
Exploit/src/com.ibm.wcttool.sldlv2
6.3, “Messaging and notification” on
page 148
Online/offline awareness
EclipseRCP/4
Exploit/src/com.ibm.wcttool.sldlv2
6.4, “Online and offline awareness” on
page 150
Database/JDBC
EclipseRCP/4
Exploit/src/com.ibm.wcttool.sldlv2
6.5, “Implementing database support” on
page 155
Synchronization
EclipseRCP/4
Exploit/src/com.ibm.wcttool.sldlv2
6.6, “Synchronizing client application data”
on page 160
Security
N/A
6.7, “Securing a client application” on
page 166
Workplace Client Technology, Micro Edition - Enterprise
Offering quick reference
IBM Workplace Client Technology, Micro Edition - Enterprise Offering provides a runtime
environment and integrated middleware components for application developers to extend
many line of business enterprise applications to server-managed laptop computers and
desktop systems for connected or disconnected usage. These applications can be optionally
deployed within Workplace Managed Client along with other Workplace collaboration
capabilities described in this Redpaper.
The Enterprise Offering platform offers following services:
򐂰 An Eclipse-based Java rich client framework
򐂰 Relational database services through IBM DB2® Everyplace® or Cloudscape, and
synchronization support through DB2 Everyplace Sync Client APIs
򐂰 Transactional, assured messaging services through IBM WebSphere MQ Everyplace
򐂰 Web application support through integrated browser controls and an integrated Web
application container
򐂰 Web services client and hosting capabilities
For additional information about Workplace Client Technology, Micro Edition - Enterprise
Offering, refer to:
http://www.ibm.com/software/wireless/wctme_eo/
194
IBM Workplace Managed Client: ISV Integration Guide
IBM Workplace Managed Client supports running the Enterprise Offering runtime
environment on the IBM Workplace Managed Client platform, which means that ISVs can run
Enterprise Offering applications on the IBM Workplace Managed Client platform. To learn
how to deploy the Enterprise Offering applications on the Workplace Collaboration Services
server, refer to IBM Workplace Managed Client API Toolkit User's Guide, wmcapi26_ug.pdf,
that comes with the IBM Workplace Software Development Kit.
Be aware that IBM Workplace Client Technology, Micro Edition - Enterprise Offering is being
replaced by IBM WebSphere Everyplace Deployment. WebSphere Everyplace Deployment
provides an updated Web container that supports Servlet 2.4 and JSP 2.0, an embedded
transaction container that supports a subset of EJB 2.0, and tools that integrate into IBM
Rational Software Development Platform. Developers might want to consider building
applications for WebSphere Everyplace Deployment depending on the server from which
they plan to deploy. In a future release, the IBM Workplace Managed Client and IBM
WebSphere Everyplace Deployment will converge. For more information about WebSphere
Everyplace Deployment, refer to:
http://www.ibm.com/software/pervasive/ws_everyplace_deployment_client/
Appendix C. Additional material and feature quick reference
195
196
IBM Workplace Managed Client: ISV Integration Guide
Related publications
The publications listed in this section are considered particularly suitable for a more detailed
discussion of the topics covered in this Redpaper.
IBM Redbooks
For information about ordering these publications, see “How to get IBM Redbooks” on
page 199. Note that some of the documents referenced here may be available in softcopy
only.
򐂰 IBM Workplace Client Technology Micro Edition Version 5.7.1: Application Development
and Case Study, SG24-6496
򐂰 Lotus Domino 7 Application Development, REDP-4102
򐂰 Building a Component for IBM Workplace, REDP-3952
򐂰 IBM Workplace Client Technology (Rich Client Edition) ISV Integration Guide,
REDP-3883
Online resources
These Web sites and URLs are also relevant as further information sources:
򐂰 IBM Workplace Managed Client product page
http://www.ibm.com/software/workplace/products/product5.nsf/wdocs/workplaceclienttech
򐂰 IBM Workplace Managed Client trial
http://www.ibm.com/software/workplace/products/product5.nsf/wdocs/wmctrial
򐂰 IBM Workplace Managed Client Developer Toolkit
http://alphaworks.ibm.com/tech/wmctoolkit
򐂰 IBM Workplace Collaboration Services
http://www.ibm.com/lotus/workplace
򐂰 IBM Cloudscape
http://www.ibm.com/software/data/cloudscape/
򐂰 IBM developerWorks Cloudscape information
http://www.ibm.com/developerworks/db2/zones/cloudscape/
򐂰 IBM Cloudscape Information Center
http://publib.boulder.ibm.com/infocenter/cscv/v10r1/index.jsp
򐂰 IBM Lotus Notes
http://www.ibm.com/software/sw-lotus/products/product4.nsf/wdocs/noteshomepage
򐂰 Workplace Collaboration Services documentation
http://www.ibm.com/developerworks/workplace/documentation/collaborationservices/
򐂰 Workplace Client Technology, Micro Edition - Enterprise Offering
http://www.ibm.com/software/wireless/wctme_eo/
© Copyright IBM Corp. 2006. All rights reserved.
197
򐂰 WebSphere Everyplace Deployment
http://www.ibm.com/software/pervasive/ws_everyplace_deployment_client/
򐂰 How IBM originally developed Eclipse
http://www.ibm.com/developerworks/opensource/top-projects/eclipse-starthere.html?ca=dgrlnxw09
򐂰 IBM WebSphere Portal for Multiplatforms Information Center
http://publib.boulder.ibm.com/pvc/wp/502/ent/en/InfoCenter/index.html
򐂰 More information about LTPA
http://www.ibm.com/developerworks/ibm/library/it-0101art2
򐂰 IBM Workplace collaborative applications
http://publib.boulder.ibm.com/infocenter/iwphelp/v2r5m1/index.jsp?topic=/com.ibm.wcs.ic.
doc_2.5.1/infocenter/i_ovr_r_whatsnew.html
򐂰 Detailed tutorial about deploying the Workplace Managed Client: IBM developerWorks
paper by Nishant Shah, Configuring and deploying a rich client application on IBM
Workplace Collaboration Services server
http://www.ibm.com/developerworks/workplace/library/deploy-client-application-workplace/
index.html
򐂰 WebSphere and Domino single sign-on
http://www.ibm.com/developerworks/ibm/library/it-0101art2
򐂰 Creating a Notes/Domino plug-in with Eclipse
http://www.ibm.com/developerworks/lotus/library/notes-plugin-eclipse/
򐂰 Introduction to the IBM Workplace Managed Client Developer Toolkit
http://www.ibm.com/developerworks/lotus/library/wmc-toolkit
򐂰 Creating an application with the IBM Workplace Managed Client Developer Toolkit
http://www.ibm.com/developerworks/workplace/library/wmc-toolkit-basic/?ca=dnp-442
򐂰 What you need to know about IBM Workplace: An introduction for developers
http://www.ibm.com/developerworks/lotus/library/ls-ibmworkplace/index.html
򐂰 Developing and debugging Workplace Managed Client applications with IBM Rational
Application Developer
http://www.ibm.com/developerworks/rational/library/05/1206_min/
򐂰 Working with application layouts in the IBM Workplace Managed Client, including full
description of portlet variables
http://www.ibm.com/developerworks/lotus/library/wmc-layouts/index.html
򐂰 Introducing the IBM Workplace Client Technology API
http://www.ibm.com/developerworks/lotus/library/wcs-toolkit/index.html
򐂰 Introduction to Web Services for Remote Portlets: Use WSRP in a Service-Oriented
Architecture
http://www.ibm.com/developerworks/webservices/library/ws-wsrp/
򐂰 Make your Eclipse applications richer with view linking: It's easy to link UI views and adapt
view linking to non-UI settings
http://www.ibm.com/developerworks/opensource/library/os-ecllink/
򐂰 Apache Derby
http://db.apache.org/derby/
198
IBM Workplace Managed Client: ISV Integration Guide
򐂰 Eclipse Rich Client Platform
http://wiki.eclipse.org/index.php/Rich_Client_Platform
򐂰 Eclipse Foundation
http://www.eclipse.org
򐂰 Eclipse plug-ins
http://www.eclipse.org/community/plugins.php
򐂰 Eclipse help system
http://help.eclipse.org/help31/index.jsp
򐂰 Eclipse SWT
http://www.eclipse.org/swt
򐂰 Eclipse Rich Client Tutorial Part 1
http://www.eclipse.org/articles/Article-RCP-1/tutorial1.html
򐂰 Eclipse User Interface Guidelines
http://www.eclipse.org/articles/Article-UI-Guidelines/Contents.html
򐂰 Visual Editor for Eclipse
http://www.eclipse.org/vep
򐂰 Visual Editor Documents
http://www.eclipse.org/vep/WebContent/docs/doc.html
򐂰 JSR 168 specification
http://www.jcp.org/aboutJava/communityprocess/final/jsr168/
http://developers.sun.com/prodtech/portalserver/reference/techart/jsr168/
򐂰 Web Services for Remote Portlets (WSRP)
http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp
򐂰 SyncML
http://www.openmobilealliance.org/tech/affiliates/syncml/syncmlindex.html
򐂰 OASIS Web Services for Remote Portlets (WSRP)
http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp
򐂰 Lotus Domino Toolkit for Java/CORBA 2.1
http://www.higs.net/85256C89006A03D2/web/pageDominoJavaToolkit
򐂰 JavaBeans 101, Part II: Writing a Simple JavaBean
http://java.sun.com/developer/onlineTraining/Beans/beans02/page3.html
How to get IBM Redbooks
You can search for, view, or download Redbooks, Redpapers, Hints and Tips, draft
publications and Additional materials, as well as order hardcopy Redbooks or CD-ROMs, at
this Web site:
ibm.com/redbooks
Help from IBM
IBM Support and downloads
ibm.com/support
IBM Global Services
ibm.com/services
Related publications
199
200
IBM Workplace Managed Client: ISV Integration Guide
Back cover
IBM Workplace Managed
Client: ISV Integration
Guide
Develop distributable
applications using
existing skills
Integrate Swing,
Eclipse RCP, Lotus
Domino, and Web
applications
Fully exploit client
and server
collaborative
components
IBM Workplace Managed Client delivers fully integrated,
server-managed collaboration to the end user's desktop. It
provides the flexibility and portability of client-side applications,
combined with the server-side control and cost savings
traditionally associated with Web-based computing. IBM
Workplace Managed Client is built on IBM Workplace Client
Technology, the foundation for next-generation, network-centric
computing.
This IBM Redpaper will assist all IBM Business Partners and ISVs
interested in learning how they can integrate their applications
with IBM Workplace Managed Client, extend it, or build
applications of their own that use this new platform. This paper
expands on the original Redpaper, IBM Workplace Client
Technology (Rich Client Edition) ISV Integration Guide,
REDP-3883.
®
Redpaper
INTERNATIONAL
TECHNICAL
SUPPORT
ORGANIZATION
BUILDING TECHNICAL
INFORMATION BASED ON
PRACTICAL EXPERIENCE
IBM Redbooks are developed
by the IBM International
Technical Support
Organization. Experts from
IBM, Customers and Partners
from around the world create
timely technical information
based on realistic scenarios.
Specific recommendations
are provided to help you
implement IT solutions more
effectively in your
environment.
For more information:
ibm.com/redbooks