ibm workplace managed client: isv integration guide

ibm.com/redbooks Redpaper

Front cover

IBM Workplace Managed Client: ISV Integration Guide

Philip MonsonLori Ott

Nishant H. ShahShane O’Sullivan

Develop distributable applications using existing skills

Integrate Swing, Eclipse RCP, Lotus Domino, and Web applications

Fully exploit client and server collaborative components

http://www.redbooks.ibm.com/


International Technical Support Organization


March 2006

© 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 ScheduleContract with IBM Corp.

First Edition (March 2006)

This edition applies to IBM Workplace Managed Client Releases 2.5.1 and 2.6.

Note: Before using this information and the product it supports, read the information in “Notices” on page vii.

Contents

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viiTrademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixThe team that wrote this Redpaper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixBecome a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xComments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .x

Chapter 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.1.1 Important terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.1.2 Suggested reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.1.3 Development environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.2 IBM Workplace Client Technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.3 IBM Workplace Client Technology platform stack. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.4 Integration options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

1.4.1 Coexistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101.4.2 Accommodation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.4.3 Leverage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.4.4 Exploit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

1.5 Types of ISVs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.6 Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141.7 URLs referenced in this chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Chapter 2. ISVs with Eclipse applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

2.1.1 What is Eclipse? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182.1.2 What is Eclipse RCP?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192.1.3 Eclipse RCP, Workplace Client Technology, and Workplace Managed Client . . . 192.1.4 Eclipse RCP integration levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

2.2 Coexist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.3 Accommodate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

2.3.1 Lightweight integration of Eclipse RCP with Workplace Managed Client . . . . . . . 222.3.2 Configuring and provisioning a Workplace Managed Client application . . . . . . . . 24

2.4 Leverage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302.4.1 Enabling server-side definition of an applications view layout . . . . . . . . . . . . . . . 302.4.2 Manually configuring an application page layout . . . . . . . . . . . . . . . . . . . . . . . . . 312.4.3 Configuring an application page layout using Workplace Managed Client Developer

Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372.4.4 Using an action bar to replace the view toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . 382.4.5 Contributing to the Workplace Managed Client menus. . . . . . . . . . . . . . . . . . . . . 392.4.6 Adding a Workplace Managed Client search bar . . . . . . . . . . . . . . . . . . . . . . . . . 402.4.7 Adding a Workplace Managed Client shelf view. . . . . . . . . . . . . . . . . . . . . . . . . . 43

2.5 Exploit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442.6 Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452.7 URLs referenced in this chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Chapter 3. ISVs with AWT or Swing applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

© Copyright IBM Corp. 2006. All rights reserved. iii

3.1.1 What is AWT? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483.1.2 What is Swing? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483.1.3 What is SWT? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483.1.4 Swing integration levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48


3.3.1 Lightweight integration of a Swing or AWT application with Workplace Managed Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

3.3.2 Creating a new IBM Workplace project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513.3.3 Importing the Swing JAR file into the plug-in project. . . . . . . . . . . . . . . . . . . . . . . 543.3.4 Modifying the shutdown sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543.3.5 Displaying the Swing/AWT application within Workplace Managed Client . . . . . . 553.3.6 Deploying the application to Workplace Collaboration Services server . . . . . . . . 59

3.4 Leverage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603.4.1 Contributing to the Workplace Managed Client menus. . . . . . . . . . . . . . . . . . . . . 603.4.2 Status bar integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683.4.3 Defining one portlet per view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713.4.4 Converting Swing or AWT controls to SWT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

3.5 Exploit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753.6 Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763.7 URLs referenced in this chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Chapter 4. ISVs with Web and portal applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 774.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

4.1.1 What are Web and portal applications? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 784.1.2 What is WSRP? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 784.1.3 Web and portal integration levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78


4.3.1 Creating a new IBM Workplace project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 814.3.2 Launching the embedded browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 834.3.3 Deploying the application to Workplace Collaboration Services server . . . . . . . . 854.3.4 Web Services for Remote Portlets (WSRP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

4.4 Leverage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 884.4.1 HTTP authenticated application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 894.4.2 Adding a Workplace Managed Client search bar . . . . . . . . . . . . . . . . . . . . . . . . . 954.4.3 Enhancing WSRP and converting servlet and JSP applications. . . . . . . . . . . . . . 98

4.5 Exploit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 994.6 Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1014.7 URLs referenced in this chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Chapter 5. ISVs with Lotus Notes and Domino applications . . . . . . . . . . . . . . . . . . . 1035.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

5.1.1 What is Lotus Domino?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1045.1.2 IBM Lotus Domino Web Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1045.1.3 Domino integration options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1055.1.4 Reparenting Notes applications using the Notes plug-in . . . . . . . . . . . . . . . . . . 106

5.2 Coexist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1065.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 . . . . . . . . . . . . . . . . . . . . . . . 1135.4 Leverage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

5.4.1 Exposing a Domino application using Web services. . . . . . . . . . . . . . . . . . . . . . 1175.4.2 Communicating with Web service from Workplace Managed Client. . . . . . . . . . 1225.4.3 Creating a Workplace application project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1285.4.4 Creating the user interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1315.4.5 Deploying the application to a Workplace Collaboration Services server . . . . . . 136

5.5 Exploit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1375.6 Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1375.7 URLs referenced in this chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Chapter 6. Exploiting IBM Workplace Managed Client . . . . . . . . . . . . . . . . . . . . . . . . 1396.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1406.2 Working with document libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

6.2.1 Creating a document library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1426.2.2 Creating a new document in a document library. . . . . . . . . . . . . . . . . . . . . . . . . 1446.2.3 Creating a new folder in a document library . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1456.2.4 Listing the contents of a library or folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

6.3 Messaging and notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1486.4 Online and offline awareness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

6.4.1 The Offline API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1526.4.2 Building offline-aware components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

6.5 Implementing database support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1556.5.1 Creating a local database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1566.5.2 Accessing the database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1586.5.3 Shutting down the database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

6.6 Synchronizing client application data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1606.7 Securing a client application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

6.7.1 Logging in to the local credential store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1666.7.2 Creating a password credential for remote server authentication. . . . . . . . . . . . 1676.7.3 Logging in to an HTTP-authenticated application . . . . . . . . . . . . . . . . . . . . . . . . 1696.7.4 Single sign-on interoperating with the operating system. . . . . . . . . . . . . . . . . . . 172

6.8 Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Appendix A. IBM Workplace Managed Client Version 2.6 . . . . . . . . . . . . . . . . . . . . . . 177Provisioning the application from CD or HTTP server . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Platform and custom personalities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Offline and network awareness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180Live names component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180File type registry component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Customizing the application look and feel along with branding . . . . . . . . . . . . . . . . . . . . . 182Changing the embedded browser’s default Web address . . . . . . . . . . . . . . . . . . . . . . . . . 182Workplace Managed Client Toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182Managed provisioning component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Using XML Access scripts to create the page and portlet . . . . . . . . . . . . . . . . . . . . . . . . . 183Implementing the calendar service API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Creating an alias password credential . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

Appendix B. IBM Workplace 2.5.1 menu IDs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185IBM Workplace menu IDs overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186IBM Workplace menu IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Appendix C. Additional material and feature quick reference . . . . . . . . . . . . . . . . . . 191Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

Contents v

Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192Workplace Managed Client feature quick reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Workplace Client Technology, Micro Edition - Enterprise Offering quick reference. . . . . . 194

Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

vi IBM Workplace Managed Client: ISV Integration Guide

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

TrademarksThe 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 RedpaperThis 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 authorJoin 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 welcomeYour 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:

[email protected]

� Mail your comments to:

IBM Corporation, International Technical Support OrganizationDept. HYTD Mail Station P0992455 South RoadPoughkeepsie, NY 12601-5400

x IBM Workplace Managed Client: ISV Integration Guide

http://www.redbooks.ibm.com/residencies.html

http://www.redbooks.ibm.com/residencies.html



http://www.redbooks.ibm.com/contacts.html

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.

1

© 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 IntroductionIBM 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 terminologyThis 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







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 ClientA 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:


Workplace Collaboration ServicesIBM 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 TechnologyIBM Workplace Client Technology is a client-side framework used for the creation of server-managed business applications.

Workplace Client Technology, Micro Edition - Enterprise OfferingIBM 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 readingIBM 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.





Table 1-1 Recommended reading

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 environmentThe 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

� IBM Lotus Domino Designer® 7

1.2 IBM Workplace Client TechnologyIBM 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

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/products/product5.nsf/wdocs/2c8a33e47eef8d0585256ee60054ddf2

Creating an application with the IBM Workplace Managed Client Developer Toolkit

http://www.ibm.com/developerworks/workplace/library/wmc-toolkit-basic/?ca=dnp-442

IBM Workplace http://www.ibm.com/developerworks/lotus/library/ls-ibmworkplace/index.html

Eclipse Rich Client Tutorial, Part 1 http://www.eclipse.org/articles/Article-RCP-1/tutorial1.html

Note: Chapter 5, “ISVs with Lotus Notes and Domino applications” on page 103 uses the Workplace Managed Client Developer’s Toolkit 2.6.






http://www.ibm.com/developerworks/lotus/library/ls-ibmworkplace/index.html

http://www.eclipse.org/articles/Article-RCP-1/tutorial1.html



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.

1.3 IBM Workplace Client Technology platform stackIBM 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.

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:




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.

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.



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 optionsMany 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.


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.

1.4.1 CoexistenceThe 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 coexistenceBenefits of coexistence include:

� Minimal-to-no development effort� Certified to run side-by-side

Application runs outside Workplace Managed Client.

Data copied into a Workplace Managed Client document can be e-mailed or stored in the secure document storage facility.

Traditional stand-alone application executables fall into this category.

Application can be launched from within Workplace Managed Client.

Updates to the application can be automatically provisioned from the host to the 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.


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.


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 AccommodationAt 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 accommodationBenefits 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 LeverageThe 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 leverageA 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)


1.4.4 ExploitComplete 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 exploitApplication 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 ISVsIBM 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


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

Any existing stand-alone Eclipse based application

Package plug-ins to provision from IBM Workplace/Portal server.

Store plug-in related files to secure, synchronized client storage.

Launch Eclipse applications from within Workplace Managed Client.

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).

Swing Notepad Launch Swing application from within Workplace Managed Client.

Wrap Swing application as a Workplace Managed Client application.

Use Workplace Managed Client UI features, such as file menus, search, and status bars.

Optionally, replace some Swing or AWT UI controls with SWT.

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.

Portal and Web

Any existing HTML file

Create a simple launch application using the embedded browser or Web Services for Remote Portlets (WSRP).

Provisioning.

Enable single sign-on using the Workplace Client Technology credential store.

Enable HTTP authentication.

Write Eclipse plug-ins that make remote calls to the same back-end services to which existing portlets make calls.

Notes/Domino Any existing Notes/Domino application

Embed NSFs using a Notes 7.0 plug-in.

Provisioning.

Wrap Domino Web applications in portlets, then display using WSRP plug-in.

Export Notes agents as Eclipse actions.

Stand-alone Microsoft Office OS registered file extension handler to open files in WebSphere Portal Document Manager through a temp file on disk.

Launch as an OLE embedded object from within Workplace Managed Client.

Provisioning.

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.


1.6 SummaryBy 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 chapterTable 1-4 lists the URLs referred to in this chapter.

Table 1-4 List of URLs referenced in this chapter

Client/server SAPSeibel

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/

Application type

Examples of applications that can coexist

Accomodate Leverage Exploit

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






http://www-306.ibm.com/software/wireless/wctme_eo/



IBM Workplace Managed Client Developer Toolkit information


IBM Workplace Managed Client Developer Toolkit (formerly IBM Workplace Collaboration Services API Toolkit)

http://www.lotus.com/ldd/lwpapi



What you need to know about IBM Workplace: An introduction for developers


Eclipse Rich Client Tutorial, Part 1 http://www.eclipse.org/articles/Article-RCP-1/tutorial1.html

The Eclipse User Interface Guidelines http://www.eclipse.org/articles/Article-UI-Guidelines/Contents.html

Workplace Collaboration Services documentation


Additional information about Workplace Client Technology, Micro Edition - Enterprise Offering


What Where










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

2


2.1 OverviewBenefits 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 From http://www.eclipse.org



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.

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.html?ca=dgr-lnxw09LearnEclipse

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


http://www.ibm.com/developerworks/edu/os-dw-os-rcp1-i.html


http://www.eclipsecon.org

http://www.ibm.com/developerworks/opensource/top-projects/eclipse-starthere.html?ca=dgr-lnxw09LearnEclipse



2.1.4 Eclipse RCP integration levelsAs 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

2.2 CoexistThe 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.

Increase of time, effort, and synergy →


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).


Figure 2-2 Example of running the Delivery Manager alongside Workplace Managed Client

2.3 AccommodateAt 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 RCPWorkplace 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


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 ClientFor 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.


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.


2.3.2 Configuring and provisioning a Workplace Managed Client applicationApplications 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.

Application layout and configurationWhen 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.

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-workplace/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





Wrapping an Eclipse view as a thick portletThe 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.

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.

The page should now look similar to the one shown in Figure 2-5 on page 26.

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.

Note: This configures the switcher portlet and corresponds to the switcher view defined in Figure 2-1 on page 18.


Figure 2-5 Workplace Collaboration Services portlet configuration page

8. Click Save.

Assign user policy to Workplace portletsA 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.

View ID of the Eclipse view to display,SwitcherView


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 pagePerform 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.

3. Click the Edit Page Layout icon for the WorkplaceRCPPages page, as shown in Figure 2-8.

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.

Note: This adds the Delivery Manager application page under the Workplace content root.

Edit AssignPolicy

Layout


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.

Assign access to the Workplace pageFollow 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 pageAfter 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.

Important: Do not leave either the RCPML or HTML check boxes cleared. This will lead to pages and applications not being displayed.

Important: Make sure that your portlet names are unique.


Figure 2-9 Workplace Collaboration Services page layout for Delivery Manager application

Centralized rollout of new applications and updatesAs 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:


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



http://www.ibm.com/developerworks/workplace/library/wmc-toolkit-basic/index.html

2.4 LeverageThe 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.

For more information, refer to 1.4.3, “Leverage” on page 11.

2.4.1 Enabling server-side definition of an applications view layoutIn 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

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

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.




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.

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 layoutIn 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

Application views rearranged usingcentralized server-side management


� 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 serverThe 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:


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 viewIn 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.

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.

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.



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.

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

You should now have six new portlets.

Edit the portlet configuration parametersAfter 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

Note: This configures the switcher portlet and corresponds to the switcher view defined in Figure 2-1 on page 18.

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

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.


Mapping each portlet to an Eclipse featureMap 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.

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:


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:


Parameter Function





Table 2-4 Three portlet parameters used to map a portlet to a feature

Defining the relative size of each of the view panesIn 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 tabsThe 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: folderidValue: pane2

2. Modify the OrderView, StoreView and PaletteView portlets by adding the following parameter and value:

Parameter: folderidValue: 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 closedFor 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 visibleFor 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.

Parameter Value

match.Feature_1 compatible

version.Feature_1 1.0.0

id.Feature_1 com.ibm.wcttool.sldlv


Figure 2-11 Portlet configuration for the StoreView Eclipse view

Adding multiple portlets to a pageAfter 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.

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.

Tip: Search for the portlet name.


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:


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.




Figure 2-13 Page layout configuration using the Workplace Managed Client Developer Toolkit

2.4.4 Using an action bar to replace the view toolbarWorkplace 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.

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>

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.


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 pluginimport 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 menusAs 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.


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

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

<actionSetlabel="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 barWorkplace 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

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”


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.


Example 2-7 Eclipse plugin.xml code to map the Id parameter

<plugin><extension point="org.eclipse.ui.activities">

<activitydescription="This is sldv activity"name="com.ibm.workplace.deliverymgr"id="com.ibm.workplace.deliverymgr"/>

<activityPatternBindingactivityId="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-inimport 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

}}//......

}

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.

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.


2.4.7 Adding a Workplace Managed Client shelf viewWorkplace 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\..*" />



</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.

Figure 2-16 Workplace Managed Client shelf view anchored in the side bar

2.5 ExploitAs 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 sharingWorkplace 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.


Online awarenessThere 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 dataThere 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 remoteThe 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 notificationsWorkplace 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 applicationThe 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 SummaryThis 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 chapterTable 2-6 on page 46 provides a list of the URLs referred to in this chapter.


Table 2-6 URLs referenced in this chapter

What Where

Information about how IBM originally developed Eclipse

http://www.ibm.com/developerworks/opensource/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_Client_Platform

Get started with Eclipse http://www.ibm.com/developerworks/opensource/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


Workplace Managed Client Developer Toolkit http://www.alphaworks.ibm.com/tech/wmctoolkit



Working with application layouts in the IBM Workplace Managed Client, including a full description of all portlet variables











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

3


3.1 OverviewThis 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


� 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 levelsAlthough 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.


Table 3-1 The benefits of the various integration levels

3.2 CoexistThe 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.



Notepad. Launch DEM Viewer from within Workplace Managed Client.

Wrap DEM Viewer as a Workplace Managed Client application.

Use Workplace Managed Client UI features, such as file menus, search, and status bars.

Optionally, replace some Swing or AWT UI controls with SWT.

Use the document libraries, mail, single sign-on, and secure data stores that Workplace Managed Client provides.

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 AccommodateAt 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


provisioned using the IBM Workplace Managed Client Developer Toolkit, which can be downloaded from:


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 projectTo 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.

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.



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

3. Choose the single view page layout and Automatically create default views, as shown Figure 3-4 on page 53. Click Finish.

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.


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.

Figure 3-5 The initial project view of the IBM Workplace Managed Client application project

Feature project

Page layout

Plug-in project

Eclipse View class

project


3.3.3 Importing the Swing JAR file into the plug-in projectNow 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"> <export name="*"/>

</library><library name="srtm.jar">

<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 sequenceIn 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.

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.javapackage 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 callprotected void doFrameShut(){

//This is all existing code from the DEM Viewer applicationSessionLogic.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 ClientAs 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 windowTo 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.javapackage 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) {}


public void setFocus() {//Create a new frame if it has not been previously created, or is no longer validif ((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 disposedmFrame.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.


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.javapackage com.ibm.wcttool.demviewer.pane1.views;

import java.awt.BorderLayout;import java.awt.Frame;

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 Pane1View extends ViewPart {

private static Frame mFrame;private static DEMViewPanel2 mPanel;

Workplace Managed Client application switcher


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 compositeComposite 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 framemFrame = SWT_AWT.new_Frame(client);mFrame.setLayout(new BorderLayout());

//Create the new AWT Panel, passing in the frame to its constructormPanel = 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.javathis.addWindowListener(new WindowAdapter(){

public void windowClosing(WindowEvent e) { doFrameShut(); } public void windowOpened(WindowEvent e) { doFrameStart(); }

});//New Code//DEMViewPanel2.javamFrame.addWindowListener(new WindowAdapter(){

public void windowClosing(WindowEvent e) { doFrameShut(); }public void windowOpened(WindowEvent e) { doFrameStart(); }

});

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

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.


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.

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 serverFor 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:


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.

Duplicated Menus

Duplicate Status Bars



3.4 LeverageApplications 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 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



– 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.

3.4.1 Contributing to the Workplace Managed Client menusThe 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.

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.


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

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.

Figure 3-8 DEM Viewer Open menu integrated with Workplace Managed Client menu bar


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”

DEM Viewer File -> Open menu


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.

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 instanceDEMViewPanel3 mPanel = DEMView3.getMPanel();mPanel.doFileOpen();//notify the enclosing class instance that the thread has finished executingDEMOpenAction.this.notify();}

};thread.start();try {

//wait until the thread has finished executingthis.wait();

} catch (InterruptedException e) {e.printStackTrace();

}}public void selectionChanged(IAction action, ISelection selection) {}public void dispose() {}public void init(IWorkbenchWindow window) {this.window = window;}

Note: The Eclipse action class must implement the IWorkbenchWindowActionDelegate interface.


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.javaimport 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());}

}//... }

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.


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.

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">

<actionlabel="&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>

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


<activitydescription="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>

Note: Action sets specify and organize the menu items being added into groups.

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




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.

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.

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/reference/extension-points/org_eclipse_ui_activities.html

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




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.

Example 3-11 Partial implementation of DEMView3.java class with inner action class

//DEMView3.javaimport 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 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();}

}};//...

}...

}

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-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.

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 classAction openAction = new Action() {

public void run(){mPanel.doFileOpen();

}};//replace the global action handler with the DEM Viewer action handlergetViewSite().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.

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.


3.4.2 Status bar integrationThe 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.

Figure 3-10 Swing-based DEM Viewer application with status messages

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:


SWT application status message displayed on Workplace Managed Client 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.

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.javaimport 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 itmPanel.setStatusLineManager(getViewSite().getActionBars().getStatusLineManager());//...

}//...

}

2. Remove the JLabel that acted as the Swing status bar.

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.

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.


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 integmStatus = 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 propertiessetSession(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 objectmSession.addPropertyChangeListener(this);

}}

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.


//this method is called by the Session object when a property change event is firedpublic void propertyChange(PropertyChangeEvent ev){

/* was used before integrating with WMC StatusBarif (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;}//...

}

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 viewIn 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.

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.


Rearranging a Swing user interface using multiple Eclipse viewsTo 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 viewsPerform 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.

Note: Administrator access is required to alter the layout of an application.


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:


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.



Figure 3-13 DEM Viewer application with multiple Eclipse views, arranged using a page layout

3.4.4 Converting Swing or AWT controls to SWTFor 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.

Eclipse View withSwing Slider Controls

Eclipse View with Swing Graphics Control


3.5 ExploitAs 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.

Notes:

� To learn more about Eclipse, see:


� To learn more about Eclipse SWT, see:

http://www.eclipse.org/swt




� 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 SummaryThis 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 chapterTable 3-3 lists the URLs referred to in this chapter.

Table 3-3 List of URLs referred to in this chapter

What Where





To learn more about org.eclipse.ui.actionsets extension points


Information about mapping using an activityPatternBinding


Full description of portlet variables http://www.ibm.com/developerworks/lotus/library/wmc-layouts/index.html








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

4


4.1 OverviewThis 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:


4.1.3 Web and portal integration levelsTrade-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.



Table 4-1 The benefits of the various integration levels

4.2 CoexistThe 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.



Minimal to no development effort.

Separate browser, interact using copy/paste and file storage.

Simple but effective blended user experience.

Component provisioning by policy.

Displayed in embedded browser.

Provisioned WSRP portlets.

Client management frameworks (HTTP authentication).

Authentication with Web or portal platform.

Custom WSRP viewer and producer.

Exploitation of rich repository spanning services, UI components, and business components.

Use document libraries, mail notification, data store, synchronization, and so on.

Chapter 4. ISVs with Web and portal applications 79

Figure 4-1 The Web application launched within Workplace Managed Client

4.3 AccommodateIn 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 viewProgrammatically 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.

Embedded Browser


4.3.1 Creating a new IBM Workplace projectTo 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.


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.


3. Choose the single view page layout and Automatically create default views, as shown in Figure 4-4 on page 82. Click Finish.

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.


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.


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.

Feature Project

Page Layout Project

Plug-in Project

Workplace Managed Client Application Navigator View


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 org.eclipse.swt.widgets.Composite;import org.eclipse.ui.part.ViewPart;import com.ibm.rcp.platform.api.PlatformContext;import com.ibm.rcp.ui.browser.core.api.ILaunchBrowser;import com.ibm.rcp.ui.browser.core.api.ILaunchContext;import com.ibm.rcp.ui.browser.core.api.LaunchBrowserFactory;

public class Pane1View extends ViewPart {//constructorpublic Pane1View() {}//nothing to do in this methodpublic 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 URLif(!portalUrl.endsWith("/lwp/workplace") &&

!portalUrl.endsWith("/lwp/myworkplace")){portalUrl += "/lwp/myworkplace";

}portalUrl.replaceAll("//lwp","/lwp");

ILaunchContext launchContext = LaunchBrowserFactory. createLaunchContext (portalUrl);

// launch the WCT browserILaunchBrowser 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.


Figure 4-6 Embedded browser launched from a Workplace Managed Client application

4.3.3 Deploying the application to Workplace Collaboration Services serverFor 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:



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



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

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.

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:






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.

WSRP Viewer 1

WSRP Viewer 2



4.4 LeverageThe 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:


� Authentication


� Search bar



– 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.

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

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/

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




http://www.jcp.org/aboutJava/communityprocess/final/jsr168/

http://developers.sun.com/prodtech/portalserver/reference/techart/jsr168/

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 applicationIn 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.

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.

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.

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.

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.



Example 4-2 Partial Eclipse plugin.xml file with dependencies

<requires><import plugin="com.ibm.rcp.security.core"/> <import plugin="com.ibm.rcp.net.apache.httpclient"/>

<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.javaimport 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;//...


private String mUser;private char[] mPassword;

// Callback handler used for http form-based authenticationprivate CallbackHandler mHandler;// LTPA token retreived from loginContext and then assigned to launchContextprivate Cookie mCookie;

public Pane1View() {}private void retrieveCredential(String host) {

try {// get password credential from credential store for the current hostIHostCredentialManager manager = ICredentialManagerFactory.INSTANCE

.getHostCredentialManager();ICredential[] creds = manager.findByHost(host);

// validate credentialAssert.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 credentialIPasswordCredential 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.

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//...


//...

private void createHandler() {// build J2EE callbackmHandler = new CallbackHandler() {

public void handle(Callback[] callbacks) throws IOException,UnsupportedCallbackException {

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.


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



//...

// login to j_security_check using name and password to get the LTPA cookieprivate 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 LTPAcookie was found");

}}


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



//...

// create a launch context to the desired URLprivate void launchBrowser(String url) {

// create a launch context to the snoop servletILaunchContext launchContext = LaunchBrowserFactory.createLaunchContext(url);// assign the LTPA cookielaunchContext.setSingleSignOnCookie(mCookie.getValue(),

ILaunchContext.CREDENTIAL_LTPA);

// launch the WCT browserILaunchBrowser launchBrowser = LaunchBrowserFactory

.getBrowserInstance();try {

launchBrowser.launch(launchContext);} catch (Exception ex) {

ex.printStackTrace();}

}}

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.

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.


Example 4-7 Partially implemented Eclipse view class to launch embedded browser with SSO enabled



//...

private void handleLaunchLTPA() {try {

// get the current host, used to retrieve the credential and then// loginString host = PlatformContext.getJNDIHostName();

// Retrieve the credential which will be used in the callback// handlerretrieveCredential(host);

// Create the Callback handler needed to login to j_security_checkcreateHandler();

// login to the j_security_check using name and password to// retrieve the LTPA cookieretrieveCookie(host);

// Launch the browser at the URL using the LTPA tokenString 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 setFocuspublic 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.


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.

4.4.2 Adding a Workplace Managed Client search barWorkplace 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.

Note: Currently, Workplace Managed Client only supports form-based authentication over HTTP and browser access using an LTPA token.


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>


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


<activitydescription="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 com.ibm.rcp.ui.browser.core.api.ILaunchBrowser;import com.ibm.rcp.ui.browser.core.api.ILaunchContext;import com.ibm.rcp.ui.browser.core.api.LaunchBrowserFactory;import com.ibm.rcp.ui.searchbar.api.ISearchDataAdapter;//...public 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);


}});

}// create a launch context to the desired URLprivate void handleLaunchSimple(String searchString) {

try {ILaunchContext launchContext = LaunchBrowserFactory

.createLaunchContext("www.mycmpny.com/Search?searchString="+ searchString + """);

// launch the WCT browserILaunchBrowser launchBrowser = LaunchBrowserFactory

.getBrowserInstance();launchBrowser.launch(launchContext);


}}//...

}

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 applicationsConverting 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.

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.


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 ExploitWhen 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.


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

ExampleThe 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


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.


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 SummaryIBM 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


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 chapterTable 4-2 lists the URLs referenced in this chapter.

Table 4-2 Table of URLs used in this chapter

What Where

Information about WSRP http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wsrp



IBM WebSphere Portal Information Center http://publib.boulder.ibm.com/pvc/wp/502/ent/en/InfoCenter/index.html

More information about WSRP http://www.ibm.com/developerworks/webservices/library/ws-wsrp/

Final JSR 168 specification http://www.jcp.org/aboutJava/communityprocess/final/jsr168/ http://developers.sun.com/prodtech/portalserver/reference/techart/jsr168/

IBM Redbook IBM Workplace Client Technology, Micro Edition Version 5.7.1: Application Development and Case Study, SG24-6496


More information about LTPA http://www.ibm.com/developerworks/ibm/library/it-0101art2











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

5


5.1 OverviewThis 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:


� 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 AccessWith 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


� New administration and management features

� Improved offline access to personal data

5.1.3 Domino integration optionsAs 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

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.



Copy and paste data from any existing Notes/Domino application.

Access NSFs using the Notes 7.0 plug-in.

Wrap Domino Web applications in portlets, and then display using Notes plug-in.

Provisioning.

Access Domino databases through Web services and native APIs.

Add new features specific to Workplace Managed Client.

Make use of advanced Workplace Managed Client features such as document libraries, single sign-on, secure data store, and so on.

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-inWorkplace 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 CoexistThe 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


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 AccommodateAt 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 clientA 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.

Figure 5-3 on page 108 shows the administrative console login page for WebSphere Portal server.

Note: Administrator access rights are required to use the administrative console.


http://www.ibm.com/developerworks/downloads/ls/lsds/?S_TACT=105AGX13&S_CMP=LSDL


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-inTo open the booklist.nsf Domino application using the Notes plug-in, perform the following steps:

1. Log in to Workplace Managed Client.


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

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.

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 projectTo 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.

Notes Plug-in Application Switcher



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.


4. Choose the single view page layout and select Automatically create default views, as shown in Figure 5-8 on page 111. Click Finish.



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 windowThe 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 ButtonmLaunch = new Button(this, SWT.PUSH);mLaunch.setText("Launch");mLaunch.setBounds(new Rectangle(10,45,60,25));


//add a SelectionListener that launches the native notes applicationmLaunch.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 serverFor 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:



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.



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 ViewWorkplace 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.6IBM 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:


Launch Button



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:


Provisioning the Notes application plug-inSee 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 viewFollow 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.

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.

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.



Figure 5-11 Select Notes Template

8. Under View Type, select Data View → Get Database.

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.

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 serverSee “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.

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.

Note: Clicking Get Databases without inputting any information in the Server Name, User Name, and Password fields retrieves local databases.


http://www.ibm.com/developerworks/lotus/library/notes-plugin-eclipse

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 LeverageThe 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:


� Tabbed views

� Action bars

� Search bar



– 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



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 servicesWeb 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.

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.

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/




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.

The action button tocreate Web service

Link to createWeb service


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.


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 session As New NotesSessionDim db As NotesDatabase Dim dc As NotesDocumentCollectionDim doc As NotesDocument

Dim count As Integercount = 0

Set db = session.CurrentDatabaseSet dc = db.AllDocumentsSet doc = dc.GetFirstDocument()While Not(doc Is Nothing)

If doc.booktitle(0) <> "" ThenIf count <> 0 Then getBooklist = getBooklist + ","getBooklist = getBooklist + doc.booktitle(0)count = count + 1

End IfSet doc = dc.GetNextDocument(doc)

Wend

End Function


Function getBookInfo(bookTitle As String) As StringDim session As NotesSessionSet session = New NotesSessionDim db As notesdatabaseDim view As notesviewDim doc As notesdocumentSet db = session.GetDatabase("","booklist.nsf")Set view = db.GetView("Books")Dim doccol As NotesDocumentCollectionSet doccol =db.FTSearch(bookTitle,1)If doccol.Count =0 Then

getBookInfo = ""

End If Set doc = doccol.GetFirstDocumentIf doc Is Nothing Then

getBookInfo = ""Else

getBookInfo = doc.booktitle(0)+","+doc.bookauthor(0)+","+doc.bookdescription(0)+","+"12345678"

End If

End FunctionEnd 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.


Figure 5-20 Partial WSDL file for BookManager Web service

5.4.2 Communicating with Web service from Workplace Managed ClientAs 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>


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:


Download the toolkit from:


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.

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.

Plug-in descriptor

Plug-in dependency

Add button




Example 5-4 Partial implementation of the BookInfo value object

//BookInfo.javapackage com.ibm.wcttool.bookdatabase.delegate;

import java.util.Date;

public class BookInfo {private String title = null;private String author = null;private String description = null;private Date datePublished = 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.javapackage 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


– Values of the parameters

Example 5-6 shows the implementation of this method.

Example 5-6 Generic method to invoke a Web service

//BookDatabaseDelegateImpl.javaimport 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 lengthif(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 //tokenizedString titlesString = (String) responseObj;


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.

Example 5-8 Implementation of getInfo method

public BookInfo getInfo(String title) {BookInfo bookinfo = null;try {

Object responseObj = call(url, // url of the web servicenew QName("urn:DefaultNamespace", "getbookinfo") , //name of web serviceXMLType.XSD_STRING, // return typenew String[]{"BOOKTITLE"}, // parameter namenew QName[]{XMLType.XSD_STRING}, // parameter typenew ParameterMode[]{ParameterMode.IN}, // parameter modenew 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;}

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.


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.javaimport 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.


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 projectThe 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.


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.

Plug-in descriptor

Click Add and choose packagecom.ibm.wcttool.bookdatabase.delegate

Runtime tab



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.



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.

Figure 5-26 Initial layout of the projects for the Book Database sample application

Feature descriptor

View projects

Page layout descriptor

Style set to NO_TITLE


5.4.4 Creating the user interfaceThe 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 communicationCommunication 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.javapublic 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);




}}//---------------------------------------------------------------------------------------//DelegatePlugin.javapublic 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 viewThe 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.

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(){

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




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 viewIn 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 propertyIn 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.javapublic 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 fornew PropertyChangeListener(){ //the action to perform when the event occurs

public void propertyChange(PropertyChangeEvent ev) {refreshList(ev.getNewValue());//refreshes the list. Shown in next section

}}

);}

}


Populating the list boxTo 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.javapublic 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.javapublic class TitleComposite extends Composite {

//...public void setList(java.util.List newlist) {

this.list.removeAll(); //clear any items currently in the list boxfor(Iterator it = newlist.iterator(); it.hasNext();){

this.list.add((String)it.next());}

}}

Modifying the existing list box listenerExample 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);

}}

});}

}


Implementing the book information viewThe 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 classAs 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 layoutInfoComposite 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 changesThe 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.javapublic class BookinfoView extends ViewPart {

//...public void createPartControl(Composite parent) {


mycomposite = new InfoComposite(parent, parent.getStyle());mycomposite.redraw();

DelegatePlugin.getDefault().getSession().addListener(DelegatePlugin.PROPERTY_CURRENT_TITLE,//The property to listen fornew 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 viewThe 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.javapublic 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.javapublic 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 serverSee “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.


Figure 5-29 Final Workplace Managed Client acting as Web service client to Domino database

5.5 ExploitAs 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 SummaryThere 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 chapterTable 5-2 on page 138 lists the URL referenced in this chapter.

Address View

Book Info View

List View


Table 5-2 List of URLs referred to in this chapter

What Where

Creating a Notes/Domino plug-in with Eclipse http://www.ibm.com/developerworks/lotus/library/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/library/wmc-toolkit/index.html



A quick introduction to using property listeners http://java.sun.com/developer/onlineTraining/Beans/beans02/page3.html

Visual Editor for Eclipse http://www.eclipse.org/vep

Document library for using Visual Editor for Eclipse




http://www.ibm.com/lotus/workplace

http://www.ibm.com/developerworks/lotus/library/wmc-toolkit/index.html





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


� Synchronization between local and remote data stores, enabling offline operation

� Secure database access

� Security through the client credential store

6


6.1 OverviewThe 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


� 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:


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

<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

<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.

Figure 6-1 The feature.xml and plugin.xml files

6.2 Working with document librariesDocument 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

Figure 6-2 The Delivery Manager application with document libraries

6.2.1 Creating a document libraryA 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.

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.

Click to generate a report

Click to save to a document library

Click to create a new document library

List of available document libraries

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




Example 6-3 Creating the service and factory classes

//DlgReport.javaimport 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.

Example 6-4 Retrieving the document library standard template

//DlgReport.javaimport 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 classApplicationTemplate 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.javaimport com.ibm.workplace.api.app.application.data.ApplicationCreationOptions;//...

String name = “NewLibrary”;String description = “New Library Description”;

Tip: For more information about IBM Workplace templates, see the Redpaper Building a Component for IBM Workplace, REDP-3952:




ApplicationCreationOptions opt = appFactory.createApplicationCreationOptions();opt.setName(name);opt.setDescription(description);opt.setTemplateId(template.getId());//set the template id retrieved earlieropt.setAlias(name);

appService.createApplication(opt);//create the document library

6.2.2 Creating a new document in a document libraryWorkplace 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.javaimport 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.

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.


Example 6-7 Creating a new document in a document library

//DlgReport.javaimport com.ibm.workplace.api.document.data.Document;//....

private boolean createDocument(String libId,String folderId,String docName,byte[] contents) {

try {//First create the documentDocument doc = mDocFactory.createDocument();

//Set the various parameters on the documentdoc.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 librarymDocLibService.addEntry(doc);return true;

} catch (WorkplaceException e) {e.printStackTrace();return false;

}}

6.2.3 Creating a new folder in a document libraryYou 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:



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.javaimport 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);


reportFolder.setDescription("Folder for storing Warehouse Reports");reportFolder.setParentFolderId("/");//place it at the root foldermDocLibService.addEntry(reportFolder);return reportFolder;

}

6.2.4 Listing the contents of a library or folderWhether 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.javaimport 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 optionmRetrievalOptions.setIncludeDocumentContent(false);mRetrievalOptions.setRetrieveCompleteMembers(true);

//only get one more level of information each time it is requestedmRetrievalOptions.setDescendantDepth(DocumentRetrievalOptions.DEPTH_CHILDREN);

}catch (WorkplaceException e){


}

public void inputChanged(Viewer viewer, Object oldInput, Object newInput){mService = (DocumentLibraryService)newInput;

}//....

}


Listing all document librariesTo 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 folderTo 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:



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 libraryDataObjectList dol = mService.getEntries(libraryId, mRetrievalOptions);List newList = dol.getObjects();DocumentFolderEntry[] contents = new DocumentFolderEntry[newList.size()];int pos = 0;


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 libraryRetrieving 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:



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 notificationYou 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.


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.

Example 6-13 Sending a mail message using the Collaborative APIs

//DlgReport.javaimport 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();

}

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.


if(mMailService == null){mMailService = mServiceFactory.createMailService();

}if(mMailFactory == null){

mMailFactory = FactoryCreator.createMailFactory();}MailMessage msg = 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);

}}

For more information about the mail API, see the documentation that comes with the Workplace Software Development Kit.

6.4 Online and offline awarenessIBM 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

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.


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

Figure 6-3 on page 152 shows the state transitions sequence.

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 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 APIThe Workplace Managed Client’s offline capability is provided by the following APIs, available in the com.ibm.rcp.offline plug-in.

OfflineManagerThe 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.

OfflineServiceThe 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.


� 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 componentsThe 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.javaimport 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 buttonpublic void goOnline() {

if(mActReport != null){mActReport.setEnabled(true);


}}//When the client goes offline, disable the “Report” buttonpublic 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 onlinemActReport.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 modemOfflineMgr.goOnline();//...

} catch (OfflineException e) {e.printStackTrace();return false;

}//...


6.5 Implementing database supportIBM 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.

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.

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

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.


http://www.ibm.com/software/data/cloudscape



6.5.1 Creating a local databaseCreating 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 method loads the WMC specific JDBC database driver//using the String specified in CSDRIVERpublic 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();// 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>


Table 6-2 Database connection URI properties available to Workplace Managed Client applications

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;


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" +";");

}}

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.

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.

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>.


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) {


}};dbCreation.start();

}}

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 databaseA 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.

Note: The database creation should always be performed in the background using a non-UI thread.


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 java.sql.Connection;import java.sql.Driver;import java.sql.DriverManager;import java.sql.SQLException;import 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“));...}


} finally {//Connection cleanup should always be in a finally block, so it //will always be executedif(connection != null)connection.close();

}}

};dbCreation.start();

}}

6.5.3 Shutting down the databaseThe 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.

Note: The database access operation must always be performed in the background using a non-UI thread.


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 java.sql.Connection;import java.sql.Driver;import java.sql.DriverManager;import java.sql.SQLException;


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 dataA 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


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.

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

ApplicationLayer

Workplace Client

Layer

TechnologyFramework


– 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.

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 engineWorkplace 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>

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.


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 com.ibm.rcp.sync.api.exception.SyncException; import com.ibm.rcp.sync.api.service.ISyncService;import com.ibm.rcp.sync.api.service.ISyncServiceFactory; import 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 {


}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

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.


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.

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.

Scenario Consideration


6.7 Securing a client applicationWorkplace 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 storeWorkplace 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 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;

public class MyCredentialStore {

String usr = "wpsadmin";String passwd = "wpsadmin";


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());


}}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 authenticationUsing 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.


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 com.ibm.rcp.security.api.cred.IPasswordCredential;import com.ibm.rcp.security.api.cred.login.ICredentialStoreLoginContext;import com.ibm.rcp.security.api.cred.login.ICredentialStoreLoginContextFactory;import com.ibm.rcp.security.internal.CredentialStore;import 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) {


}}

Note: Creating credentials prevents the user from being repeatedly prompted for authentication information.


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



public void createRemoteCredentials(){new MyCredentialStore().createMyPasswordCredential();

}}

6.7.3 Logging in to an HTTP-authenticated applicationThe 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"/> <import plugin="com.ibm.rcp.net.apache.httpclient"/>



<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";

String passwd = "wpsadmin";String host = "myworkplace.ibm.com";


}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.


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() {

// 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 userfalse, 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.


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



public void getLTPAToken(){new MyCredentialStore().HTTPLogin();

}}

6.7.4 Single sign-on interoperating with the operating systemUsing 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

Single sign-on with Microsoft WindowsAfter 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\win32\x86

2. Run the ssoinstall.cmd file, as shown in Figure 6-5 on page 173.

Note: The /lwp/j_security_check servlet is used by form-based authentication to authenticate a user.

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.


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.

Execute thiscommand

Need to reboot


Figure 6-6 Workplace Managed Client single sign-on (SSO) verification for Windows

Single sign-on with LinuxThe 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\linux\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.0auth required pam_unix2.so nullok #set_secrpcauth required pam_env.soauth required pam_stack.so service=system-authauth required pam_nologin.soaccount required pam_stack.so service=system-authpassword required pam_rcpsso.so debugpassword required pam_stack.so service=system-authsession required pam_stack.so service=system-authsession optional pam_console.sosession required pam_rcpsso.so debug

Workplace Managed Client SSOenablement


http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/pam.html#toc4

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.0auth required pam_stack.so service=system-authaccount required pam_stack.so service=system-authpassword required pam_stack.so service=system-autpassword required pam_rcpsso.s 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 SummaryThis 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.


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.

A


Provisioning the application from CD or HTTP serverCustomers 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:


Platform and custom personalitiesEclipse 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.

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:


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:







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.

� 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:


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.

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.

Appendix A. IBM Workplace Managed Client Version 2.6 179


Offline and network awarenessThe 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.

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 componentThe 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.

Note: The INetworkAware interface replaces the IOfflineService in Version 2.6.


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 componentThe 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.


Customizing the application look and feel along with brandingAn 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 addressThe 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 ToolkitThe 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.


http://www.ibm.com

� 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 componentThe 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 portletTo 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 APIYou 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.


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 credentialYou 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.


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

B


IBM Workplace menu IDs overviewAn 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 IDsThe following tables provide details about the menu IDs.

Table B-1 Top-level menu items consistent with Eclipse menu items

Table B-2 IBM Workplace Collaboration Services-specific top-level menu items


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”


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>”


Table B-3 Group markers for adding to menus and end groups

Table B-4 File menu group markers

Table B-5 Common File menu actions

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” >

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”

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

Table B-6 Edit menu group markers

Table B-7 Common Edit menu actions

Table B-8 View menu group markers

FILE_PRINTPREVIEW_ACTION_ID = “com.ibm.rcp.ui.filemenu.printpreview”

FILE_PAGESETUP_ACTION_ID = “com.ibm.rcp.ui.filemenu.pagesetup”

Constant value

EDITMENU_UNDO_GROUP = “editmenuUndoGroup”

EDITMENU_GROUP1 = “editmenuGroup1”



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”

Constant value

VIEWMENU_GROUP1 = “viewmenuGroup1”


VIEWMENU_GROUP3 = “ viewmenuGroup3”



VIEWMENU_MAXIMIZETAB_GROUP = “viewmenuMaximizeTabGroup”


Table B-9 Common View menu actions

Table B-10 Actions menu group markers

Table B-11 Tools menu group markers

Table B-12 Help menu group markers

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”

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”;



Constant value

TOOLSMENU_GROUP1 = “ toolsmenuGroup1”

TOOLSMENU_LIBRARY_GROUP = “ toolsmenuLibraryGroup”

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

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.

C


Locating the Web materialThe 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 materialThe additional Web material that accompanies this Redpaper includes the following files:

File name DescriptionEclipseRCP.zip Eclipse RCP example code Notes.zip Notes and Domino example codeSwing.zip Swing example codeWeb.zip Web and portal example codeAllCombined.zip All example code

Each of the first four ZIP files corresponds to an individual chapter.

How to use the Web materialCreate 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:


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.


ftp://www.redbooks.ibm.com/redbooks/REDP4119




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.jarcom.ibm.wcttool.sldv2.switcher_1.0.0.jar

DeleteScript.xmlDeployInstructions.txtsiteFragment.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:


Workplace Managed Client feature quick referenceTable 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

Swing/2 Accomodate/src/embeddedApp/com.ibm.wcttool.demviewer.pane1

2.4.5, “Contributing to the Workplace Managed Client menus” on page 39

3.4.1, “Contributing to the Workplace Managed Client menus” on page 60

Search bar EclipseRCP/3 Leverage/src.com.ibm.wcttool.sldv2

Web/3 Leverage/src/com.ibm.wcttool.web.pane1

2.4.6, “Adding a Workplace Managed Client search bar” on page 40

4.4.2, “Adding a Workplace Managed Client search bar” on page 95

Appendix C. Additional material and feature quick reference 193


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:


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.step3

3.4.2, “Status bar integration” on page 68

Embedded Web browser Web/2 Accomodate/src/com.ibm.wcttool.web.pane1

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

Feature Code package Documentation section



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


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 RedbooksFor 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 resourcesThese Web sites and URLs are also relevant as further information sources:

� IBM Workplace Managed Client product page


� IBM Workplace Managed Client trial

http://www.ibm.com/software/workplace/products/product5.nsf/wdocs/wmctrial

� IBM Workplace Managed Client Developer Toolkit


� IBM Workplace Collaboration Services


� IBM Cloudscape


� IBM developerWorks Cloudscape information


� IBM Cloudscape Information Center


� IBM Lotus Notes


� Workplace Collaboration Services documentation


� Workplace Client Technology, Micro Edition - Enterprise Offering




http://www.ibm.com/software/workplace/products/product5.nsf/wdocs/wmctrial









� WebSphere Everyplace Deployment


� How IBM originally developed Eclipse


� IBM WebSphere Portal for Multiplatforms Information Center


� More information about LTPA


� IBM Workplace collaborative applications


� 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


� WebSphere and Domino single sign-on


� Creating a Notes/Domino plug-in with Eclipse


� Introduction to the IBM Workplace Managed Client Developer Toolkit


� Creating an application with the IBM Workplace Managed Client Developer Toolkit


� What you need to know about IBM Workplace: An introduction for developers


� 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


� Introducing the IBM Workplace Client Technology API


� Introduction to Web Services for Remote Portlets: Use WSRP in a Service-Oriented Architecture


� Make your Eclipse applications richer with view linking: It's easy to link UI views and adapt view linking to non-UI settings


� Apache Derby




http://www.ibm.com/developerworks/rational/library/05/1206_min/
















� Eclipse Rich Client Platform


� Eclipse Foundation


� Eclipse plug-ins


� Eclipse help system

http://help.eclipse.org/help31/index.jsp

� Eclipse SWT


� Eclipse Rich Client Tutorial Part 1


� Eclipse User Interface Guidelines


� Visual Editor for Eclipse


� Visual Editor Documents


� 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)


� SyncML


� OASIS Web Services for Remote Portlets (WSRP)


� Lotus Domino Toolkit for Java/CORBA 2.1


� JavaBeans 101, Part II: Writing a Simple JavaBean


How to get IBM RedbooksYou 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 IBMIBM Support and downloads

ibm.com/support

IBM Global Servicesibm.com/services

Related publications 199



http://www.ibm.com/support/

http://www.ibm.com/support/

http://www.ibm.com/services/

http://www.ibm.com/services/








http://help.eclipse.org/help31/index.jsp









®

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

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

Redpaper


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.

Back cover


