ibm technology api toolkit · “ibm workplace client technology api toolkit roadmap” on page 2...

IBM Workplace Client Technology API Toolkit

User’s Guide

Version 2.5

G210-1984-00

��

Note

Before using this information and the product it supports, read the information in Appendix B, “Notices,” on page 147.

First Edition (May 2005)

This edition applies to version 2.5 of IBM Workplace Collaboration Services API Toolkit (product number

L-GHUS-653JTG) and to all subsequent releases and modifications until otherwise indicated in new editions.

© Copyright International Business Machines Corporation 2005. All rights reserved.

US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract

with IBM Corp.

Contents

Chapter 1. IBM Workplace Client

Technology API Toolkit User’s Guide . . 1

The IBM Workplace Client Technology API Toolkit . 1

System requirements . . . . . . . . . . . . 2

IBM Workplace Client Technology API Toolkit

roadmap . . . . . . . . . . . . . . . . 2

IBM Workplace Client Technology . . . . . . . 2

Core components . . . . . . . . . . . . . 3

Core platform component . . . . . . . . . 4

User interface component . . . . . . . . . 4

Utilities component . . . . . . . . . . . 4

Security component . . . . . . . . . . . 5

Rich text editor component . . . . . . . . 5

Server-managed client components . . . . . . . 5

Replication support component . . . . . . . 5

Offline support component . . . . . . . . 5

Chapter 2. Building applications for the

platform . . . . . . . . . . . . . . . 7

Setting up the development environment . . . . . 7

Setting up Eclipse . . . . . . . . . . . 8

Setting up the Eclipse development environment 8

Setting up the Rational Application Developer

environment . . . . . . . . . . . . . 9

Configuring a Java Runtime Environment . . . 9

Setting up the runtime environment . . . . . 10

Virtual machine arguments . . . . . . . . 12

Building platform plug-ins and features . . . . . 12

Creating a view plug-in . . . . . . . . . 13

Adding a manifest file to a plug-in . . . . . 13

Creating a perspective . . . . . . . . . . 14

Creating a personality class . . . . . . . . 15

Packaging a plug-in as a feature . . . . . . 16

Creating a manifest file for a feature . . . . . 17

Deploying the plug-in and feature . . . . . . 18

Bundles and plug-ins . . . . . . . . . . 18

Managing applications from a server . . . . . . 19

Client application deployment . . . . . . . 19

Provisioning the client . . . . . . . . . . 28

Initiating application updates . . . . . . . 36

Referencing provisioned rich client resources . . . 37

Chapter 3. Designing an application

layout . . . . . . . . . . . . . . . 39

Creating a custom personality . . . . . . . . 39

Personalities extension point . . . . . . . . 41

Personality Extension extension point . . . . . 42

Personality startup extension point . . . . . 43

Control set extension point . . . . . . . . 44

Application look and feel . . . . . . . . . . 46

Activities . . . . . . . . . . . . . . . 46

Chapter 4. Developing the application

user interface . . . . . . . . . . . . 49

Eclipse components used in the client . . . . . 49

Model View Controller architecture . . . . . . 50

Using JFace to create adapter views . . . . . 51

Threading model . . . . . . . . . . . 52

Design patterns that support view-to-view

communication . . . . . . . . . . . . 53

Adding alerts . . . . . . . . . . . . . . 54

AlertType extension point . . . . . . . . 55

Accessing a Web address in the client browser . . . 56

Accessing a Web address using an LTPA token 57

Action bars . . . . . . . . . . . . . . 60

Creating an action bar . . . . . . . . . . 61

Adding custom buttons to an action bar . . . . 62

Adding editing functionality to an application . . . 63

Contributing to a menu . . . . . . . . . . 64

Implementing keyboard shortcuts . . . . . . . 65

Implementing preference pages . . . . . . . . 65

Chapter 5. Securing a client application 69

IBM Workplace local credential store . . . . . . 69

Logging in to the local credential store . . . . 69

HTTP authentication support . . . . . . . . 72

Logging in to an HTTP authenticated application 72

Single sign-on with the operating system . . . . 74

Configuring Microsoft Windows operating

system single sign-on . . . . . . . . . . 74

Configuring Linux operating system single

sign-on . . . . . . . . . . . . . . . 75

Chapter 6. Calling a remote Enterprise

JavaBean . . . . . . . . . . . . . 77

Building a deployable remote Enterprise JavaBean 77

Installing an Enterprise JavaBean . . . . . . . 77

Starting the remote Enterprise JavaBean . . . . . 78

Calling a remote Enterprise JavaBean . . . . . . 78

Chapter 7. Synchronizing client

application data . . . . . . . . . . . 81

Implementing a custom synchronization engine . . 82

Sync services extension point . . . . . . . 85

Implementing the DB2 Everyplace Synchronization

engine . . . . . . . . . . . . . . . . 85

Chapter 8. Taking a component offline 89

Offline API . . . . . . . . . . . . . . 90

Building offline-aware components . . . . . . 91

Chapter 9. Reference information . . . 93

Coding tips and best practices . . . . . . . . 93

Debugging an application in Eclipse . . . . . 93

Debugging applications remotely . . . . . . 94

Plug-in, fragment, and feature naming

conventions . . . . . . . . . . . . . 95

Logging . . . . . . . . . . . . . . 96

© Copyright IBM Corp. 2005 iii

Adding Help to an application . . . . . . . 99

Client Java API documentation . . . . . . . 101

Client API Extension Points . . . . . . . . 101

Chapter 10. Call Center and Samples

applications . . . . . . . . . . . . 103

Setting up the Call Center and Samples

applications . . . . . . . . . . . . . . 103

Adding the sample applications to the Eclipse

update site . . . . . . . . . . . . . 103

Installing the sample features on WebSphere

Portal . . . . . . . . . . . . . . . 105

Creating portal pages for the samples . . . . 108

Using XML Access to provision the sample

applications . . . . . . . . . . . . . 109

Defining access control levels for the samples 109

Adding parameters to the sample portal pages 110

Call center synchronization . . . . . . . . . 111

Call center preference pages . . . . . . . 112

Implementing the Call Center Enterprise

JavaBean services . . . . . . . . . . . 112

FAQ document library . . . . . . . . . 114

Chapter 11. The Enterprise Offering

runtime environment . . . . . . . . 117

Setting up the Enterprise Offering runtime

environment . . . . . . . . . . . . . . 117

Adding the Order Entry sample to the Eclipse

update site . . . . . . . . . . . . . 118

Provisioning the Enterprise Offering

components . . . . . . . . . . . . . 118

Creating a WebSphere Portal page for the Order

Entry sample . . . . . . . . . . . . 122

Using XML Access to provision the Enterprise

Offering components . . . . . . . . . . 122

Appendix A. IBM Workplace-specific

information . . . . . . . . . . . . 125

IBM Workplace rich client provisioning process 125

IBM Workplace Collaboration Services APIs . . . 125

Deploying a client application that uses server

APIs . . . . . . . . . . . . . . . 126

Enabling an application to use server-side APIs 127

Using the document library service API . . . 127

Using the mail service API . . . . . . . . 130

The IBM Workplace personality . . . . . . . 131

Creating an IBM Workplace personality . . . 132

Retrieving user information . . . . . . . 132

Contributing to the search bar menu . . . . 133

Creating a top-level menu . . . . . . . . 134

Determining available activities . . . . . . . 138

Remote object access . . . . . . . . . . . 139

Accessing a remote server over IIOP . . . . 139

Implementing database support . . . . . . . 140

Initializing database creation . . . . . . . 141

Accessing an encrypted database . . . . . . 144

Appendix B. Notices . . . . . . . . 147

Trademarks . . . . . . . . . . . . . . 148

iv User’s Guide

Chapter 1. IBM Workplace Client Technology API Toolkit

User’s Guide

This programmer’s guide provides information to help application developers use

the toolkit to build applications to run on the IBM® Workplace Client Technology™

platform.

Related concepts

“The IBM Workplace Client Technology API Toolkit”

“IBM Workplace Client Technology API Toolkit roadmap” on page 2

The IBM Workplace Client Technology API Toolkit

The IBM Workplace Client Technology API Toolkit is designed for application

developers who want to extend the IBM Workplace Client Technology platform

with new applications. IBM Workplace Client Technology platform is based on the

Eclipse platform, which serves as a framework on which to build customizable and

extensible applications. IBM Workplace Client Technology is Java™ compatible.

The toolkit provides a number of public APIs (application programming interfaces)

for you to use. It also provides sample plug-ins that you can implement to learn

how to develop plug-ins for the client and documentation that provides guidelines

for developing applications that run on the client.

The public APIs that are currently available for building client applications are

provided in JAR files packaged in the same plug-ins that store the internal APIs

delivered in the client platform. The public APIs are distinguished from the

internal APIs by their namespaces. The namespaces used to identify the APIs are

as follows:

APIs Namespaces

Public APIs com.ibm.rcp.*.api

Internal APIs+ com.ibm.rcp.*

+The internal APIs are subject to change in future releases. Do not implement the

internal APIs in your application.

This release of the toolkit includes the following public APIs:

v com.ibm.rcp.offline.api

v com.ibm.rcp.platform.api

v com.ibm.rcp.rte.api

v com.ibm.rcp.security.api

v com.ibm.rcp.sync.api

v com.ibm.rcp.ui.alerts.api

v com.ibm.rcp.ui.browser.core

v com.ibm.rcp.ui.widgets.api

Related concepts

Chapter 1, “IBM Workplace Client Technology API Toolkit User’s Guide”

© Copyright IBM Corp. 2005 1

System requirements

The IBM Workplace Client Technology API Toolkit has been tested with the IBM

Java 2 SDK 1.4.2 implementation of the Java runtime environment, which is the

default runtime environment for the client. The following operating systems are

supported:

v Microsoft® Windows® 2000 Professional with Service Pack 2

v Microsoft Windows XP with Service Pack 1

v Red Hat Enterprise Linux® WS 3.0 with Update 3; Kernel: 2.4.2.21-27.0.2″;

Compiler: gcc 3.2, glibc 2.3.2; desktop environment: GNOME

You can use the Eclipse 3.0 Software Development Kit (SDK) as the integrated

development environment (IDE) or a development tool built on the Eclipse SDK,

such as one of the Rational® software development tools. Some of the procedures

in this guide describe how to use Rational Application Developer 6.0, which was

formerly known as WebSphere® Studio Application Developer, as the IDE.

IBM Workplace Client Technology API Toolkit roadmap

This roadmap outlines the topics that cover the most common points of interest for

application developers and architects who are evaluating the platform or are

building applications on the platform for the first time.

Technology overview for evaluators

v “IBM Workplace Client Technology”

v “Core components” on page 3

v “Managing applications from a server” on page 19

v Chapter 4, “Developing the application user interface,” on page 49

v Chapter 3, “Designing an application layout,” on page 39

v Chapter 5, “Securing a client application,” on page 69

v Chapter 6, “Calling a remote Enterprise JavaBean,” on page 77

v Chapter 7, “Synchronizing client application data,” on page 81

v Chapter 8, “Taking a component offline,” on page 89

Development guidelines for implementors

v “System requirements”

v “Setting up the development environment” on page 7

v “Building platform plug-ins and features” on page 12

v “Deploying an application” on page 20

v “Provisioning the client” on page 28

v “Coding tips and best practices” on page 93 Related concepts

Chapter 1, “IBM Workplace Client Technology API Toolkit User’s Guide,” on

page 1

IBM Workplace Client Technology

IBM Workplace Client Technology is a platform based on the Eclipse platform,

which serves as a framework on which to build customizable and extensible

applications. An example of an application built on this technology is the IBM

Workplace Messaging™ rich client edition e-mail application. The added value that

2 User’s Guide

IBM Workplace Client Technology brings is its ability to deliver client applications,

provide upgrades to those applications, implement and enforce security protections

such as updated virus protection software, apply and administer policies for users

and groups of users that define and enforce multiple levels of access to data shared

across an organization, and do all this through a centrally-managed administrative

server.

The IBM Workplace™ client provides core functionality. You, the developer,

determine the form and function of the application user interface by supplying the

user interface components as plug-ins.

Plug-ins, which are packaged Java code files, are the lowest-level unit of

organization for client applications. Each plug-in performs a specific application

function. One or more plug-ins that provide a single service comprise a feature.

One or more features comprise an application. You can build plug-ins and features

and do your other development work using the Eclipse development environment

or Rational Application Developer.

The IBM Workplace Client Technology platform provides a customizable rich client

platform that supports sophisticated client applications. It provides support that

cannot be provided by a browser, including implementing a native look-and-feel

by using operating system user interface controls, integrating the application into

the desktop, interacting with the underlying operating system, and communicating

with server components. Using IBM Workplace Client Technology, you can build

applications that:

v Provide a high-performance installed client solution with a responsive user

experience.

v Handle client-side processing and caching to ensure lower server loads.

v Can run concurrently with other client applications.

v Enable working offline.

v Provide local data access.

v Provide authentication with single sign-on support.

v Provide an event-driver user interface.

v Support central server-based application provisioning and policy management.

v Support the model view controller (MVC) framework, alerts, and preferences

frameworks.

v Provide an extensibility framework for Windows and Linux, which enables you

to upgrade or scale back applications as your business needs change.

v Provide integration to underlying operating system services and resources,

including access to rich user interface components that are native to the

operating system on which the application is running.

Related tasks

Chapter 2, “Building applications for the platform,” on page 7

Core components

The following components make up the core IBM Workplace Client Technology

platform:

v “Core platform component” on page 4

v “User interface component” on page 4

v “Utilities component” on page 4

v “Security component” on page 5

Chapter 1. IBM Workplace Client Technology API Toolkit User’s Guide 3

v “Rich text editor component” on page 5

Core platform component

The core platform component provides the platform runtime environment, which

comprises a number of core plug-ins on which all other application plug-ins

depend. The core platform is similar to the core Eclipse platform on which it is

built. The core platform’s runtime environment is responsible for the following

tasks:

v Defining a structure for application plug-ins and their implementation details.

v Finding and running the main application plug-ins and maintaining a registry of

all the plug-ins and their extensions and extension points.

v Providing utilties, such as logging, debugging, adapters, a preference store, and

a concurrency infrastructure, which enables multiple applications to run

simultaneously.

Each plug-in declares in a plugin.xml manifest file what extension points it

provides and extends. The runtime engine uses this information to register all the

available plug-ins. It activates a plug-in only when a function provided by it is

requested by the user. As a result, the platform uses fewer machine resources. Only

active plug-ins use the client machine’s resources.

The core platform component is made up of the following plug-in:

Plug-in name Public API package name

Tasks you can perform

using the plug-in

com.ibm.rcp.platform com.ibm.rcp.platform.api Chapter 3, “Designing an

application layout,” on page

39

User interface component

The user interface component provides user interface controls. It is made up of the

following plug-in:


Tasks you can perform with

the plug-in

com.ibm.rcp.ui.widgets com.ibm.rcp.ui.widget.api “Action bars” on page 60

Utilities component

The utilities component provides common utilities to the IBM Workplace Client

Technology platform, such as HTTP client access. It is made up of the following

plug-in:


Tasks you can perform with

the plug-in

com.ibm.rcp.ui.browser.core com.ibm.rcp.ui.browser.

core.api

“Accessing a Web address in

the client browser” on page

56

4 User’s Guide

Security component

The security platform component provides a plug-in that secures the data accessed

by client applications, protects user identity information, stores user credentials,

and handles authentication. It is made up of the following plug-in:



using the plug-in

com.ibm.rcp.security.core com.ibm.rcp.security.api Chapter 5, “Securing a client

application,” on page 69

Rich text editor component

The rich text editor component provides a Document Object Model (DOM)-based

rich text editor (RTE) that provides HTML and plain text editing functionality.

DOM is an open standard W3C specification for application program interfaces for

accessing the content of HTML and XML documents. The RTE provides support

for the Internet Explorer and Mozilla browsers. The rich text editor component is

made up of the following plug-in:



using the plug-in

com.ibm.rcp.rte com.ibm.rcp.rte.api “Adding editing

functionality to an

application” on page 63

Server-managed client components

The following components comprise the server-managed client for the IBM

Workplace Client Technology platform:

v “Replication support component”

v “Offline support component”

Replication support component

The replication support component provides support for synchronizing data

between the client and server when an offline client returns to the online state. It is

made up of the following plug-in:



using the plug-in

com.ibm.rcp.sync com.ibm.rcp.sync.api Chapter 7, “Synchronizing

client application data,” on

page 81

Offline support component

The offline support component enables you to build client applications that are

dowloaded from and managed by a central server, but that can run in offline mode

by users who do not have unlimited access to a network connection. It is made up

of the following plug-in:

Chapter 1. IBM Workplace Client Technology API Toolkit User’s Guide 5



using the plug-in

com.ibm.rcp.offline com.ibm.rcp.offline.api Chapter 8, “Taking a

component offline,” on page

89

6 User’s Guide

Chapter 2. Building applications for the platform

You can build, run, and test the plug-ins and features that make an IBM Workplace

rich client application by completing the following procedures:

1. “Setting up the development environment”

2. “Building platform plug-ins and features” on page 12

3. “Deploying an application” on page 20

4. “Provisioning the client” on page 28

5. “Referencing provisioned rich client resources” on page 37

Setting up the development environment

This section describes how to install and set up the platform and development

environment you will use to build applications to run on the client and interact

with IBM Workplace. You can use the Eclipse 3.0 Software Development Kit (SDK)

as the Integrated Development Environment (IDE) or you can use a tool built on

the Eclipse 3.0 SDK, such as Rational Application Developer 6.0. These instructions

describe how to set up both development environments.

Note: IBM Workplace Client Technology is a platform-independent technology that

can run on Windows or Linux based operating systems. The instructions

provided in these procedures are written for use on both operating systems,

except where explicitly noted.

Make sure your system meets the requirements.

See “Debugging applications remotely” on page 94 for an alternate way to run and

test applications you build for the client.

Perform the following tasks to set up the development environment:

1. Install IBM Workplace. See the section, ″IBM Workplace installation,″ in the

IBM Workplace Collaboration Services information center at

http://www.lotus.com/ldd/notesua.nsf/find/workplace

2. Provision the client from an IBM Workplace server by logging into the IBM

Workplace server at http://<ibm_workplace_server>/lwp/myworkplace, from

the Downloads section, clicking IBM Workplace rich client, and then clicking

Start Download. See Rich client installation and configuration information in

the IBM Workplace Collaboration Services information center.

3. Perform either of the following procedures:

v “Setting up Eclipse” on page 8.

v Install Rational Application Developer. Go to the following site to download

it:

http://www-128.ibm.com/developerworks/downloads/

r/rad/?S_TACT=105AGX28&S_CMP=DLMAIN

4. Perform either of the following procedures:

v “Setting up the Eclipse development environment” on page 8.

v “Setting up the Rational Application Developer environment” on page 95. Perform the procedure, “Configuring a Java Runtime Environment” on page 9.

6. Complete the task, “Setting up the runtime environment” on page 10.


Related concepts

“System requirements” on page 2 Related tasks

“Creating a custom personality” on page 39

Setting up Eclipse

When you start the Eclipse SDK, you can pass parameters to the program

executable file (Eclipse.exe) that specify how you want Eclipse to run, such as:

v -data <eclipseWorkspaceName> -- Configures Eclipse to start in a new, empty

workspace, specific to your project.

v -vm <path_to_jre> -- Instructs Eclipse to use the preinstalled Java Runtime

Environment (JRE) stored in the specified path.

Note: Eclipse does not include an installed Java Runtime Environment. See

“Configuring a Java Runtime Environment” on page 9 for more

information.

To set up the Eclipse SDK:

1. Download Eclipse 3.0 from www.eclipse.org.

2. Install Eclipse by extracting all files in the installation .zip file into your C drive

or home directory, preserving the file paths specified in the archive.

v On Windows, install eclipse-SDK-3.0-win32.zip.

v On Linux, install eclipse-SDK-3.0-linux-gtk.zip.3. Start Eclipse by doing one of the following steps:

v For Windows, from the directory to which you installed Eclipse, create a

shortcut to the install directory and add the following command as the

shorcut target: C:\eclipse\eclipse.exe -data

"C:\eclipse\workspace\MyWorkspace , and then double click the shortcut

icon.

v For Linux, from the directory to which you installed Eclipse, type the

following command: /home/eclipse -data /home/eclipse/<myWorkspace>

Setting up the Eclipse development environment

Using the Eclipse SDK, you can create a target platform that simulates the client

platform. By specifying the client plug-ins as the source for the target platform,

Eclipse builds a development environment that behaves the same as the client

platform. You can create custom plug-ins to interact with the client platform

plug-ins, and then define a runtime environment in which to run and test your

plug-ins.

To set up the development environment in Eclipse:

1. From the Eclipse menu, select Window → Open Perspective → Other, and then

select Plug-in Development.

2. From the menu, select Window → Preferences.

3. From the Preferences window, expand Plug-In Development, and then click

Target Platform.

4. Click Browse next to the Location field and find the file path for the Workplace

client \eclipse subdirectory. For example, the default installation stores the

client plug-ins in the following file path:

8 User’s Guide

v Windows: C:\Program Files\IBM\Workplace rich client\eclipse

v Linux: root/IBM/Workplace rich client/eclipse

5. Click Reload.

6. Click Select All if any of the plug-ins are not selected.

Note: If a plug-in that should be part of the platform is missing, you may need

to create a link file to reference it. See “Referencing provisioned rich

client resources” on page 37 for more details.

7. Click OK.

Setting up the Rational Application Developer environment

Using the Rational Application Developer IDE, you can create a target platform

that simulates the client platform. By specifying the client plug-ins as the source

for the target platform, the IDE builds a development environment that behaves

the same as the client platform. You can create custom plug-ins to interact with the

client platform plug-ins, and then define a runtime environment in which to run

and test your plug-ins.

To set up the development environment in Rational Application Developer:

1. From the menu, select Window → Open Perspective → Other, check Show all,

and then select Plug-in Development and click OK. If you are prompted to

confirm the enablement of the ″Eclipse Plug-in Development″ capability, click

OK.

2. From the menu, select Window → Preferences.

3. From the Preferences window, expand Plug-In Development, and then click

Target Platform.

4. Click Browse next to the Location field and find the file path for the Workplace

client \eclipse subdirectory. For example, the default installation stores the

client plug-ins in the following file path:

v Windows: C:\Program Files\IBM\Workplace rich client\eclipse

v Linux: root/IBM/Workplace rich client/eclipse

5. Click Reload

6. Click Select All if any plug-ins are not selected.

7. Click OK.

Configuring a Java Runtime Environment

The Eclipse Integrated Development Environment (IDE) that is provided as part of

the Eclipse SDK does not include a Java Runtime Environment (JRE). To run the

Eclipse IDE, Eclipse finds and uses a preinstalled JRE. The Rational Application

Developer IDE asks you to choose a default JRE when you install it. To start an

Eclipse or Rational Application Developer target platform that simulates the IBM

Workplace Client Technology platform, instruct the IDE to use the JRE supported

by the client when you set up the target platform. It is strongly recommended that

you use the supported JRE because it provides the appropriate security context

and uses the appropriate virtual machine. To use the supported JRE in the runtime

configuration, you must first add it to the list of available JRE options.

To add a JRE to the list of available JRE options:

1. From the Plug-in Development menu, select Window → Preferences.

Chapter 2. Building applications for the platform 9

2. From the Preferences window, expand Java, select Installed JREs, and then

click Add.

3. Enter a name, such as RichClient JRE, in the JRE name field, and then do one

of the following:

v To use the JRE that comes with the client on Windows, click Browse next to

the JRE home directory field and navigate to the following directory:

<client_home>\rcp\eclipse\features\

com.ibm.rcp.jre.win32.feature_1.2.0\jre where <client_home> is the

directory to which you downloaded the client. By default, this is C:\Program

Files\IBM\Workplace rich client.

v To use the JRE that comes with the client on Linux, click Browse next to the

JRE home directory field and navigate to the following directory:

<client_home>/rcp/eclipse/features/

com.ibm.rcp.jre.linux.feature_1.2.0/jre where <client_home> is the

directory to which you downloaded the client.4. Click OK twice to return to the Installed JREs list.

5. Select the check box next to the RichClient JRE you just added to set it as the

default JRE, and then click OK.

Setting up the runtime environment

You can use the Eclipse SDK or an application built on it, such as Rational

Application Developer, to test the target platform you defined to simulate the

client platform by setting up a runtime environment. When you configure the

runtime environment, you define which JRE to use, which plug-ins to build, and

any arguments you want to pass to the Java virtual machine.

Before you begin the following procedure, open the rcpinstall.properties file in a

text editor. You can find this file in the following directory:

<client_home>\rcp

Keep this text file accessible. You need the information in this file to supply the

VM arguments in Step 4 below.

To set up the runtime environment:

1. From the Plug-in Development menu, click Run → Run.

2. Click Run-time Workbench, and then click New.

3. In the Arguments tab of the Run-time Workbench details page, perform the

following steps:

v Enter a name for the client runtime configuration, such as Rich Client

Runtime in the Name field.

v Select Clear workspace data before launching and Ask for confirmation

before clearing.

v Select com.ibm.rcp.platform.RCPApplication from the list in the Run an

application field.

v Make sure the RichClient JRE you installed in the previous procedure is

displayed in the JRE field or select it by clicking Installed JREs.

v From the <client_home>\rcp\rcpinstall.properties file, copy and paste the

text beginning with the words Xbootclasspath into the VM Arguments field.

Then modify the text as follows:

– Add a dash (-) in front of the word Xbootclasspath. Replace the period

after Xbootclasspath with a slash (/).

10 User’s Guide

– Shorten the word ″prepend″ to ″p″ and the word ″append″ to ″a.″ Replace

the equal sign (=) after the a and p with a colon (:).

– Enclose any file paths with quotation marks.

– Remove the vm= and cp= statements.

The following text is an example:

-Xbootclasspath/a:"C:/Program Files/IBM/Workplace rich

client/workplace/eclipse/features/

com.ibm.workplace.platform.feature_2.5.0/bootjars/rcpproxy.jar";

"C:/Program Files/IBM/Workplace rich client/workplace/eclipse/

features/com.ibm.workplace.platform.feature_2.5.0/bootjars/properties";

"C:/Program Files/IBM/Workplace rich client/rcp/eclipse/features/

com.ibm.rcp.platform.feature_1.2.0/bootjars/loggerboot.jar";

"C:/Program Files/IBM/Workplace rich client/rcp/eclipse/features/

com.ibm.rcp.platform.feature_1.2.0/bootjars/properties";

"C:/Program Files/IBM/Workplace rich client/rcp/eclipse/plugins/

com.ibm.rcp.net.apache.httpclient_1.2.0/commons-logging.jar"

-Djava.util.logging.config.class=com.ibm.rcp.

core.logger.boot.LoggerConfig

-Xbootclasspath/p:"C:/Program Files/IBM/Workplace rich

client/rcp/eclipse/features/com.ibm.rcp.jre.feature_1.2.0/

bootjars/xalan.jar"

Append to these values the following parameters and provide the specified

information:

– -Drcp.home=<client_home>

– -Drcp.data=<Location_field>

where <Location_field> is the content of the Location field, which

specifies the workspace to be used by the Run-time Workbench when it

runs. If you do not set it, it defaults to a directory called

runtime-workspace in the default project workspace.The following text is an example:

-Drcp.home="C:\Program Files\IBM\Workplace

rich client" -Drcp.data="C:\eclipse\runtime-workspace"

4. Click Apply.

5. In the Plug-ins tab, make sure Launch with all workspace and enabled

external plug-ins is selected.

6. Click Close.

Note: Do not run this runtime workbench configuration until you build

plug-ins to run in it. Be sure one of the plug-ins you create defines a

personality that you can specify as a program argument parameter to the

client platform. Otherwise, the client uses the default IBM Workplace

personality, which takes a long time to start.

You can now import plug-in source projects or create new plug-in projects in the

target platform development environment. When you are ready to test your

plug-ins, you can use this runtime configuration to start the client target platform

in a separate window.

Note: For Linux, you must create an environment variable called

JAVA_HIGH_ZIPFDS and set its value to a high number, such as 500, to tell

the IBM JRE to create that many file descriptors in a separate area of

memory for later use. The rich client executable launcher sets this value as

part of its execution process, but when you run the client within Eclipse or

Rational Application Developer, you must set this value manually or you

may encounter the following errors:


_X11TransSocketOpen: socket() failed for

local _X11TransSocketOpenCOTSClient: Unable to open

socket for local _X11TransOpen: transport open failed

for local/localhost.localdomain:0

Related concepts

“Local provisioning” on page 31 Related tasks

“Testing provisioning locally” on page 32


Virtual machine arguments

You can pass arguments to the client that specify the way you want the client to

start up. You can pass these arguments to the client in one of the following ways:

v Adding them to the VM Arguments field of the Run-time Workbench

configuration.

v Append them manually to the command line you use to start the target

platform.

You can specify the following arguments:

-console

(Optional) Writes error messages to the Java console.

-debug

Ensures that all error messages are written to the console.

-nogui

(Optional) Starts the client by adding a client icon to the systemtray that you

must right-click, and select Workplace Portal Client from.

-pbcache <local directory>

Tells the pagebuilder code to use the local directory as your page cache

directory instead of the

<workspace_home>\.metadata\.plugins\com.ibm.rcp.pagebuilder directory.

-personality <personality id>

Specifies a specific personality. Use to specify a custom personality that you

created.

Building platform plug-ins and features

A good way to test the development environment you set up is by creating a

simple plug-in and running it on the target platform you configured. Applications

built on IBM Workplace Client Technology consist of several plug-ins. A plug-in is

a software component that contains the code that performs the action in an

application. Each plug-in contains code that supports a specific task. You package

one or more plug-ins into a feature. A feature is a collection of one or more

plug-ins and fragments that the platform can treat as a group and the Update

Manager can update as a group. If you build one or more plug-ins into a feature,

you can then export the feature from Eclipse or Rational Applicataion Developer

and provision it to the IBM Workplace Client Technology client. This topic

demonstrates the steps you follow to create a simple plug-in which contains code

that creates a single view.

12 User’s Guide

Before you build an application for the IBM Workplace Client Technology platform,

you should determine which provisioning mechanism you want to use to deploy

the application on the client machine. See “Provisioning the client” on page 28 for

more information on your options. If you choose to provision using the WebSphere

Everyplace® Device Manager, you must complete the steps marked Optional

below.

You can create a plug-in and feature by completing the following tasks:

1. “Creating a view plug-in.”

2. Optional: “Adding a manifest file to a plug-in”

3. Creating a perspective.

4. “Creating a personality class” on page 15.

5. “Packaging a plug-in as a feature” on page 16.

6. Optional: “Creating a manifest file for a feature” on page 17

7. “Deploying the plug-in and feature” on page 18

Related concepts

Chapter 3, “Designing an application layout,” on page 39 Related tasks

“Installing a feature on WebSphere Portal” on page 21

Creating a view plug-in

An Eclipse view presents and organizes the information in a window. An example

of an Eclipse view is the Package Explorer view in the Eclipse SDK and Rational

Application Developer IDEs that display the projects and other resources that you

work with when you create plug-ins in the IDE. The following steps describe how

to create a plug-in that contains code that builds a view.

1. From the Plug-in Development perspective menu, select File → New → Plug-in

Project.

2. Type com.acme.my.view in the Project name field, and then click Next to

display the Plug-in Content page.

3. Click Next.

4. In the Templates page, select Create a plugin using one of the templates, and

then select ″Plug-in with a view″ from the list of available templates.

5. Click Finish.

You can expand the com.acme.my.view\src\com.acme.my.view.views folder in the

Package Explorer view and double-click SampleView.java to look at the source

code. The IDE creates the view by extending the ViewPart class included in the

org.eclipse.swt.widgets.Composite package.

Related concepts

“Plug-in, fragment, and feature naming conventions” on page 95 Related tasks

“Creating an action bar” on page 61

Adding a manifest file to a plug-in

An additional step is required to create a plug-in that can be deployed on the

WebSphere Everyplace Device Manager. You must include a manifest file

(MANIFEST.MF) with the plug-in. A manifest file is a text file that contains


meta-data in the form of header values. The meta-data identifies the archive file

and optionally provides information used by the OSGi runtime when it loads the

plug-in to the runtime environment. The manifest file is also used by bundles in

the OSGi framework to specify the Java package import and export dependency

information for a code bundle. The plugin.xml file serves the same purpose for the

Eclipse platform. To deploy a plug-in bundle using the WebSphere Everyplace

Device Manager, it must have a manifest file that contains the required

information.

Note: Only perform this procedure if you plan to use the WebSphere Everyplace

Device Manager to deploy your plug-in.

To add a manifest file:

1. From the Package Explorer view for the package containing your plug-in,

double-click the plugin.xml file for the plug-in you want to deploy on the

WebSphere Everyplace Device Manager to give it focus.

2. Click the runtime tab at the bottom of the editor.

3. In the Plug-in Activation section, click Create a manifest file.

Note: This option is not available in Eclipse SDK versions earlier than 3.0.

4. From the Package Explorer view, expand the newly added META-INF folder

and double-click the MANIFEST.MF file to open it in the editor.

5. Add the following statement to the list of bundle statements:

RCP-BundleType: ECLIPSE-PLUGIN

Note: If you are creating a fragment, add the following statement instead:

RCP-BundleType: ECLIPSE-FRAGMENT

6. Save and close the MANIFEST.MF file.

Related concepts

“Bundles and plug-ins” on page 18

Creating a perspective

A perspective defines the initial set of views and their layout in the window. A

perspective provides functionality for accomplishing a specific type of task or

working with specific types of resources. An example of a perspective is the

Plug-in Development perspective you work in when you use the Eclipse or

Rational Application Developer IDEs to build plug-ins.

If you are building a standalone application for which you are creating a custom

personality, you can create a perspective according to the instructions below. If you

are building an application to run as an IBM Workplace Collaboration Services

offering, you do not need to create a perspective. When you install the plug-ins

that make up your application on the Eclipse Update site on WebSphere Portal, the

Rich Client Platform Markup Language that is generated creates a perspective

programmatically.

To create a perspective:

1. From the Plug-in Development perspective menu, select File → New →

Plug-in Project.

2. Type com.acme.my.perspective in the Project name field, and then click Next

to display the Plug-in Content page.

3. Click Next.

14 User’s Guide

4. In the Templates page, click Finish.

5. From the menu, select File → New → Class to start the New Java Class wizard.

6. Type com.acme.my in the Package field and type MyPerspective in the Name

field.

7. Click Add next to the Interfaces field. In the Choose interfaces field, type

org.eclipse.ui.IPerspectiveFactory, click OK, and then click Finish.

8. Click the MyPerspective.java tab, and in the file editor, change the argument

passed to the createInitialLayout() method to layout if it is not already, and

then add the following code to the method body:

layout.addView("com.acme.my.view.views.SampleView",

IPageLayout.LEFT, (float).50, layout.getEditorArea());

layout.setEditorAreaVisible(false);

9. Save, then close the MyPerspective.java file.

10. Click the Extensions tab. If you don’t see this tab, give focus to your plug-in

package by double-clicking the plugin.xml file for your packace in the

navigator view.

11. Click Add, select org.eclipse.ui.perspectives from the list, and then click

Finish. If no extension points are displayed in the list, deselect Show only

extension points from the required plug-ins.

12. Click the Plugin.xml tab for com.acme.my.perspective, and add the following

tag between the <extension point=″org.eclipse.ui.perspectives″> and the

closing </extension> tags:

<perspective

name="com.acme.my.MyPerspective"

icon="icons/sample.gif"

class="com.acme.my.MyPerspective"

id="com.acme.my.myperspective">

</perspective>

13. Save your changes.

Related tasks

“Creating an action bar” on page 61

Creating a personality class

The personality of an application defines the framework the platform uses to

determine what perspectives or windows, menus, action bar items, and status line

controls are displayed when the application starts, as well as what services are

available and what sequence of events or what life cycle should be applied to the

objects associated with that application.

To create a personality class:

1. From the Plug-in Development menu, select File → New → Plug-in Project.

2. Type com.acme.my.personality in the Project name field, and then click Next

to display the Plug-in Content page.

3. Click Next.

4. In the Templates page, click Finish.

5. Click the Dependencies tab. Click Add, select com.ibm.rcp.platform (1.2.0),

and then click OK. Save your changes.

6. Give com.acme.my.personality focus by expanding its folder in the Package

Explorer view, then from the menu, select File → New → Class to start the New

Java Class wizard.


7. Type com.acme.my in the Package field and MyPersonality in the Name field,

and then click Finish.

8. Double-click plugin.xml in the com.acme.my.personality folder to give the

package focus, then click the Extensions tab, click Add, and then select the

following extension for the list of extension points:

com.ibm.rcp.platform.personalities

Click Finish.

9. Click the plugin.xml tab. Add the following code between the opening

<extension point=″com.ibm.rcp.platform.personalities″> tag and closing

</extension> tag:

<personality

allowMultipleWindows="true"

class="com.acme.my.MyPersonality"

name="My Personality"

id="com.acme.my.mypersonality"/>

Save your changes.

10. Open the MyPersonality.java class in the editor.

11. Add the following import statement:

import com.ibm.rcp.platform.api.*;

Change the MyPersonality class to contain the following code:

public class MyPersonality extends Personality {

public String getWindowPerspectiveId() {

return "com.acme.my.myperspective";

}

Note: Be sure to use a lower-case ″d″ in getWindowPerspectiveId()

Save your changes.

12. From the menu, select Run → Run, then click the Run-time Workbench

configuration you created earlier. Add the following parameter to the Program

Arguments field:

-personality com.acme.my.mypersonality

13. Click Run to start the target platform with this personality, which contains a

single perspective displaying the sample view.

Related tasks


Packaging a plug-in as a feature

A feature defines one or more plug-ins that work together to create a single

functioning unit of an application. An application itself is made up of one or more

features. When you package one or more plug-ins into a feature, you can then

export the feature as a deployable feature that can be deployed outside the Eclipse

SDK or Rational Application Developer IDE in which it was created. Packaging

your plug-ins as a feature also enables you to apply a specific version number to

those plug-ins and update them as a package, rather than having to update each

plug-in separately.

To package a plug-in as a feature:

1. From the Plug-in Development perspective menu, select File → New → Feature

Project.

2. On the first page of the New Feature wizard, type com.acme.my.feature in the

Project name field, and then click Next two times.

16 User’s Guide

3. On the Referenced Plug-ins and Fragments page, select

com.acme.my.personality (1.0.0), com.acme.my.perspective (1.0.0), and

com.acme.my.view (1.0.0), and then click Finish to create the

com.acme.my.feature project.

4. From the Package Explorer view, expand com.acme.my.feature, then

double-click feature.xml.

5. Click the Information tab at the bottom of the editor, then click the License

Agreement tab and enter either a Web address that provides licensing

information to the URL field or add licensing information in the Text field. An

example of licensing test follows.

"Use of this feature is subject to the same terms and conditions which govern the use of the P

6. Click Apply, then Save.

7. Click the feature.xml tab at the bottom of the editor to confirm that the text or

Web address you just provided is displayed in the license tag.

Creating a manifest file for a feature

To deploy a feature to the client using the WebSphere Everyplace Device Manager,

you must include a manifest file (MANIFEST.MF) with the feature.

Unlike with plug-ins, the Eclipse SDK and Rational Application Developer IDEs do

not have a built-in method for adding manifest files to features. You must create

the manifest file for your feature.

Note: Only perform this procedure if you plan to use the WebSphere Everyplace

Device Manager to deploy your feature.

To create a manifest file for a feature:

1. From the From the Package Explorer view, right-click your feature folder, and

then select New → Folder from the menu.

2. In the Folder name field of the New Folder wizard, type META-INF, in all

upper case letters, and then click Finish.

3. Right-click the META-INF folder you just added and select New → File from

the menu.

4. In the File name field of the New File wizard, type MANIFEST.MF, in all

upper case letters, and then click Finish.

5. Double-click the MANIFEST.MF file you just created to open it in the text

editor, then add the following statements to the file:

Manifest-Version: 1.0

Bundle-Name: featureID_version

Bundle-Version: version

Bundle-Description: <bsn:featureID>

RCP-BundleType: ECLIPSE-FEATURE

where you supply the italicized values. For example:

Manifest-Version: 1.0

Bundle-Name: com.amce.my.feature_1.0.0

Bundle-Version: 1.0.0

Bundle-Description:<bsn:com.acme.my.feature>

RCP-BundleType: ECLIPSE-FEATURE

6. Save and close the file.

Related concepts

“Bundles and plug-ins” on page 18


Deploying the plug-in and feature

Create an Update Site Project for the plug-in and feature so that the IDE you are

using, Eclipse or Rational Application Developer, can build them into feature and

plug-in archive files that can be deployed outside of the IDE. When you build the

project, the IDE transforms the plug-in and feature into deployable JAR files and

produces a site.xml file that registers the feature. You can copy the JAR files to the

Eclipse Update site on the IBM HTTP Server which is provided with the

WebSphere Application Server, and copy the content of the site.xml file into the

server’s site.xml file that is also stored on the Update site. From the Eclipse Update

site, your feature and plug-in are then available to be provisioned to client

machines. You must deploy your plug-ins and features to the Eclipse Update Site

regardless of whether you plan to use the Eclipse Update site or WebSphere

Everyplace Device Manager to provision them.

To deploy the plug-in and feature:

1. From the Plug-in Development perspective menu, select File → New → Other to

open the New dialog box.

2. Expand Plug-in Development, select Update Site Project, and then click Next.

3. Supply a name for the Update Site Project, then click Finish to create a project

folder with a site.xml in it and display the site.xml editor.

4. Click Add to add a feature to the project. Select com.acme.my.feature (1.0.0)

and then click Finish.

5. In the Features To Publish pane, click New Category.

6. Type WCT in the Name and Label fields, and optionally add a description in

the Description field. Click OK.

Note: Name it WCT; do not create a custom category name.

7. Click and drag the com.acme.my.feature (1.0.0) from the Features to Build pane

to the Features To Publish pane to add it as a child of the WCT category.

8. Click Build all to start the PDE Export process and build the features, plug-ins,

and site.xml file into the Update Site Project’s root directory.

9. You can now deploy the application.

Related tasks

“Deploying an application” on page 20

“Managing applications from a server” on page 19

Bundles and plug-ins

The OSGi framework specification defines a bundle as a collection of files

(resources and code) installed on the platform. Each bundle has a Java class loader,

and includes protocol for starting, stopping, and uninstalling itself. The Eclipse 3.0

platform uses an OSGi runtime platform. As a result, the plug-ins that are

deployed into the runtime environment are treated as bundles. However, there are

differences between a plug-in and a pure OSGi bundle. An OSGi bundle uses OSGi

headers in a META-INF/MANIFEST.MF file as its load descriptors, as opposed to

a plugin.xml file that a plug-in uses to provide implementation details to the

platform. The advantage of using MANIFEST.MF files is that using them, you can

specify the conditions when your plug-in should be activated at run time, thus

potentially reducing overhead and memory footprint. However, using traditional

plug-ins is advantageous if you want to implement the Eclipse Extension Registry

API. Plug-ins can define extensions and extension points, while bundles cannot.

The IBM Workplace Client Technology platform is compatible with both bundles

18 User’s Guide

and plug-ins. However, the WebSphere Everyplace Device Manager requires that

any plug-ins or features it deploys have a manifest.mf file, so it can treat the

feature or plug-in as a bundle.

Related tasks

“Adding a manifest file to a plug-in” on page 13

“Creating a manifest file for a feature” on page 17

Managing applications from a server

Applications that you build on the IBM Workplace Client Technology platform can

be downloaded to multiple clients and managed from a central server.

Administrators can distribute, troubleshoot, and upgrade applications from the

central server.

You can enable central management by performing the following tasks:

1. “Client application deployment”

2. “Provisioning the client” on page 28

Related tasks

“Deploying the plug-in and feature” on page 18

Client application deployment

You can use WebSphere Portal to deploy an application on the client. Client

application deployment is powered by the Rich Client Platform Markup Language

(RCPML), the WebSphere Portal page aggregator, and the page builder component

of the IBM Workplace Client Technology platform. RCPML is an XML-based

markup language that describes an IBM Workplace Client Technology

platform-based application. It specifies the view layout, the services required to

support the application, the required features, and it also provides optional inline

data. The page aggregator is a WebSphere Portal component that determines how

to render a page and its portlets based on the administrative settings for that page.

You can set the page type to be HTML (for browsers), WML (for mobile devices),

and RCPML (for the IBM Workplace Client Technology platform). The page builder

component of the IBM Workplace Client Technology platform reads the RCPML

tags and calls the corresponding features to deploy the application defined in the

portlet as a client application.

To make the page aggregator read the page content as RCPML and generate an

RCPML representation of the page to the requesting client, you set the WebSphere

Portal page to support HTML and rcpml. The root page, the parent page, and any

children of it, must all support RCPML, or the page aggregator will not recognize

a child RCPML page that may be requested. In addition, only portlets on a page

that supports RCPML are rendered to the requesting client.

The client retrieves the resulting RCPML page (containing the data from the

WebSphere Portal pages and portlets that support RCPML) from WebSphere Portal

by connecting to the provisioning server when users log into their client machines.

The client caches the XML files that define the application pages to the

<workspace_home>\.metadata\.plugins\com.ibm.rcp.pagebuilder directory on a

user’s machine.

Related tasks

“Initiating application updates” on page 36


Deploying an application

You use WebSphere Portal to deploy your application to the client. WebSphere

Portal supports the Rich Client Platform Markup Language (RCPML) that powers

the creation of the application on the IBM Workplace Client Technology platform.

Deploy an application by completing the following steps:

1. “Deploying an application”

2. “Installing a feature on WebSphere Portal” on page 21.

3. “Creating a portal page” on page 26.

4. “Defining access control levels” on page 26.

5. “Adding parameters to a WebSphere Portal page” on page 27.

Related tasks

“Deploying the plug-in and feature” on page 18

Adding an application to an Eclipse update site:

When you create and build an Update Site Project in an IDE such as Eclipse or

Rational Application Developer, the IDE builds the plug-ins and features into

deployable JAR files and creates a site.xml file that registers the features and

plug-ins. The build stores the folders containing these files in the workspace you

built the project in. For example, if you built the Update Site Project in a

workspace called IDEWorkspace, you can find the built files in the following

directories:

v Feature JAR files --

<ide_home>\IDEWorkspace\features\com.acme.my.feature_1.0.0.jar

v Plug-in JAR files --

<ide_home>\IDEWorkspace\plugins\com.acme.my.view_1.0.0.jar,

com.acme.my.perspective_1.0.0.jar, com.acme.my.personality_1.0.0.jar

v site.xml file -- <ide_home>\IDEWorkspace\site.xml

You must store copies of the JAR files and the feature tags provided in the site.xml

file on the IBM HTTP Server Eclipse update site directory to ensure that the files

are available to be deployed on WebSphere Portal.

To add an application to the Eclipse Update site:

1. Copy the feature JAR file you produced as part of the Update Site Project to

the C:\IBMHTTPServer\htdocs\en_US\lwpupdate\wct\features directory. For

example, if you completed the tasks described in, ″“Building platform plug-ins

and features” on page 12,″ you should store a copy of the

com.acme.my.feature.jar in the

C:\IBMHTTPServer\htdocs\en_US\lwpupdate\wct\features directory.

2. Copy the plug-in JAR file you produced as part of the Update Site Project to

the \lwpupdate\wct\plugins subdirectory. For example, you should store a

copy of the com.acme.my.view_1.0.0.jar, com.acme.my.perspective_1.0.0.jar, and

com.acme.my.personality_1.0.0.jar files in the

C:\IBMHTTPServer\htdocs\en_US\lwpupdate\wct\plugins directory.

3. With a text editor, open the site.xml file in your Update Site Project and the

site.xml file in the IBM HTTP Server’s Eclipse Update site, stored in the

lwpupdate\wct\ subdirectory. Copy the feature tag from the Update site

project site.xml file, and paste it into the server’s site.xml file. This adds a

feature tag to the site.xml file for the feature that you just added to the

20 User’s Guide

\features\ subdirectory. The following is sample code from the site.xml file that

registers the my.Feature feature with the Eclipse Update site:

<feature

id="com.acme.my.feature"

url="features/com.acme.my.feature_1.0.0.jar"

version="1.0.0">

<category name="WCT">

</category>

</feature>

4. Add an image subdirectory to the \lwpupdate directory. If you are building an

application to run with IBM Workplace Collaboration Services, copy to the

image subdirectory any icon files you want the Switcher bar to display to

represent your application. The Switcher bar is a vertical bar on the left side of

the IBM Workplace rich client window that lists the available applications, each

represented by an icon, from which users can select the service they want to

start.

<HTTPSERVER_HOME>\htdocs\en_US\lwpupdate\images

Installing a feature on WebSphere Portal:

Install the application you exported from the IDE as a feature onto an

RCPML-based portlet on WebSphere Portal.

Perform the following steps to install a feature in a portlet on WebSphere Portal:

1. Log in to the IBM Workplace server as an administrator and click

Administration to access the WebSphere Portal Administration pages.

2. Select Portlets → Manage Portlets.

3. Repeat Steps 4 through 7 to create a portlet for each view and folder that you

want displayed in your application.

4. Find the RCP Portlet - Generic portlet, select it, and then click Copy.

5. Select the copied portlet from the list of portlets, and then click Modify

parameters.

6. Click Set title for selected locale, then type a name that represents your

plug-in in the Title field, and click OK.

7. Provide values for the following parameters. To add a parameter, type the

parameter and value into the pair of fields to the left of the Add button, then

click Add. (You provided a value for the Title parameter in Step 6.)

Parameter name Description Required

Title Displays in the title bar of

the resulting client view or

folder except in views for

which the NO_TITLE style is

specified.

By all portlets.

rcpView Defines an Eclipse view

using the view ID.

By portlets representing

views.

folderid Defines which tab of the

folder that contains a tabbed

view this portlet should

display in the resulting client

application. If you do not

specify a folderID, the client

displays the view as a

standalone view.

By portlets representing

folders or for tabbed views.



rcpUpdate Defines the feature that the

view is associated with.

By views that are not

displayed as tabbed views in

a folder.

fixed A Boolean value (yes/no)

that defines whether the user

can close or move the view.

By views for which only one

instance of the view should

be displayed. Set to ″no″ for

views that you want a user

to be able to run more than

one instance of.

allowMultiple A Boolean value (yes/no)

that defines whether multiple

instances of the same view

can be displayed in the

client.

By views that a user can run

more than one instance of.

visible A Boolean value (yes/no)

that defines whether the

view is visible when the

application is first started in

the client.

By folders and views that a

user can run only one

instance of.

style This tag defines the style of

the title bar that displays in a

standalone view on the

client. It cannot be applied to

a view associated with a

folder. Currently, only one

style option is available:

NO_TITLE. If you specify the

NO_TITLE option, the

resulting standalone view

will be displayed without a

title bar. Otherwise, it will be

displayed with a title bar.

NO_TITLE can be used by

standalone views. It is not

supported on folder or

placeholder views.

ratio Defines the amount of space

the view should take up in

the Eclipse perspective

defined as a decimal value

from 0.0 to 1.0.

By any view or folder that

shares a window with other

views or folders.

id.<featureID> ID of a feature that you want

to require before the feature

being defined in this portlet

is provisioned. The feature

represented by this ID is

specified in a resulting

requirements tag in the

RCPML that defines the

layout of the application.

This parameter works with

the version and match

parameters to define a single

feature. The <featureID>

value should be a unique

value that is consistent

among the three parameters,

such as Feature11.

By any application that

wants to force an update of

an updated feature installed

on the client or prompt the

installation of a new feature.

22 User’s Guide


version.<featureID> Defines the version number

of the feature specified in the

id parameter. This version

number defines the required

version of the feature to be

specified in the requirements

tag. This parameter works

with the id and match






such as Feature11.






Version numbers are

specified as three values

representing

major.minor.service versions.

For example, 3.0.1 indicates

that the feature’s version

number is major = 3, minor

= 0, and service = 1.



match.<featureID> Defines the version filtering

algorithm to be used by the

Eclipse update manager to

determine whether the

feature indicated as required

by its inclusion in the

requirement tag is installed

in the current client

configuration. The match

rule can be one of the

following values:

v perfect -- Instructs the

manager to update the

feature if the dependent

version exactly matches

the specified version.

v equivalent -- Instructs the


feature if the dependent is

at least at the version

specified, or at a higher

service level (major and

minor version levels must

equal the specified

version).

v compatible -- Instructs the



version is at least at the

version specified, or at a

higher service level or

minor level (major version

level must equal the

specified version).

v greaterOrEqual -- Instructs

the manager to update the


version is at least at the

version specified, or at a

higher service, minor or

major level.

This parameter works with

the id and version






such as Feature11.






For example, the following parameters represent the com.acme.my.feature

application:

Parameter name Plug-in value

Title Sample view

rcpView com.acme.my.View.views. SampleView

24 User’s Guide

Parameter name Plug-in value

folderid

rcpUpdate com.acme.my.feature

fixed yes

allowMultiple

visible yes

style

ratio

id.Feature<ID> com.acme.my.feature

version.Feature<ID> 1.0.0

match.Feature<ID> compatible

8. Click Save to save your changes and return to the Manage Portlets pane.

Related tasks

“Building platform plug-ins and features” on page 12

“Specifying a different Eclipse update site Web address”

“Initiating application updates” on page 36

Specifying a different Eclipse update site Web address:

One of the tasks that the server client installer performs is to automatically set the

value of the Workplace Client Provisioning Server URL Provider. The default URL

Provider is supplied to the RCPML that defines the application. If you want to

instruct the client to use a different WebSphere Portal server as the Eclipse update

site, you can do so by specifying the URL Provider as an id.Feature<ID> parameter

on the portlet that represents the application.

To specify a different Eclipse Update site Web address:

Specify the Eclipse Update site Web address by adding the following parameter

and value to the portlet:

v name=id.Feature<ID>

v value=<application_feature>;<Eclipse_update_site_Web_address>

For example: id.Feature2 with the following value:

com.acme.my.feature;http://myibmworkplace.dev.ibm.com/lwpupdate/wct

If you do not want to specify the Eclipse Update site URL in the portlet, set it from

the Websphere Administrative Console, by expanding Resources, then clicking

URL Providers, and creating a URL provider with the following values:

v Name -- Workplace Client Provisioning Server

v JNDI Name -- url/wctprovisioningurl

v Specification -- Web address of the Eclipse Update site. For example:

http://myibmworkplace.dev.ibm.com/lwpupdate/wct

and save the URL Provider.

Related tasks



Creating a portal page:

Now that you have created one or more portlets that contain your application, you

can create a WebSphere Portal page to which you can add the portlets.

To create a portal page:

1. From the IBM WebSphere Administration pages, click Portal User Interface,

and then select Manage Pages.

2. Search on WorkplaceRCPPages to find the Workplace content root page.

3. Click the returned WorkplaceRCPPages page, then click the Edit icon to open

the Edit layout page.

4. Click Edit properties. Expand Avanced options and under This page

supports, select HTML in addition to rcpml. Click OK to save your changes

and close the page.

5. Click Done to close the Edit layout page.

6. Click New page. Give the page a title with a WCT prefix. For example, you

could give it the title, WCT myPage.

7. Select a layout for your portlets.

8. Expand the Advanced options, and under This page supports, select rcpml

and HTML, and then click OK to save the page.

Note: A warning is displayed that says the page has been created, but is not

included in page navigation. You may ignore this warning because the

page was created under the Content Root and not under My Portal.

9. You also need to create a custom name for the page you just saved so that

your XMLAccess script can retrieve it later. Find the page by clicking Portal

Settings → Custom Unique Names → Pages and in the Search for field, type

WCT, and then click Search to find the page.

10. Create a custom name for the page by clicking the Edit icon

on the right

side of the page returned by the search and typing a unique name, and then

clicking Ok. For example, you could type, WCT.mypage as the custom unique

name.

11. From the Portal User Interface → Manage Pages pane, double-click

WorkplaceRCPPages, find your page, and then click the Edit icon

.

12. Click Add portlets and search for your portlets. Find and select the portlets

you created to add them to the page, and then click Done.

13. From the WebSphere Portal Administration pages, click Portal Settings, URL

Mapping, click New context, and then type a name for the context, such as

WCT.

14. Click the Edit mapping icon and then select your page with the context you

just added from the list of Page titles, which includes children of

WorkplaceRCPPages, and then click OK. For example, if your page is myPage,

you would select WCT myPage from the list.

15. To preview the page, open a browser and type the server address in the

Address field, followed by a forward slash, and then the title of the page you

created to display the page in HTML. For example:

http://www.myserver.com/lwp/myworkplace/WCT myPage

Defining access control levels:

26 User’s Guide

The level of access that a user has to portlets and pages hosted by WebSphere

Portal must be set using the WebSphere Portal Administration pages. Applications

that you build to run on the client must specify that all authenticated WebSphere

Portal users can use the portlets and pages that make up your application for the

application to be made available in the client.

To set the access level for portlets and pages to All authenticated WebSphere Portal

users:

1. From the WebSphere Portal Administration pages, click Access → Resource

Permissions → Pages.

2. Search for pages with ″WCT″ to display the page you created.

3. Click the Assign Access key icon of the page you created.

4. Click the Edit Role icon for the User role, and then click Add.

5. Check All authenticated portal users, and then click OK. Click Done, then

click OK to return to the page search results. Click Done to return to the list of

resource types. Click Portlets, and then search for portlets with ″WCT″ to

return the portlets you created.

6. For each portlet, set the User role to All authenticated portal users.

Adding parameters to a WebSphere Portal page:

Add additional parameters to the WebSphere Portal pages you created to further

define how you want your application to display on the client. The only way to

modify page parameters is by using the WebSphere Portal XMLAccess interface to

export the page containing the parameters, update the parameters, and import the

page back into WebSphere Portal. You can use the XMLAccess interface to add the

following page parameters to the page you created:

Parameter name Description

activities Defines which activities to include on the

page when it is started in the client.

default_folder Defines a default folder in which to display

any views for which no associated folderid

has been specified.

iconpath The path to application branding icons that

are specified relative to the base WebSphere

Portal application. This is used by the

switcher to retrieve the graphics that are

cached locally by the pagebuilder code.

To add page parameters to a WebSphere Portal page:

1. From a WebSphere Portal server desktop, create a temporary directory folder,

such as C:\temp.

2. Create a pages definition XML file that defines the pages you want to edit by

referencing them using the unique names you defined for them in Step 10 of

“Creating a portal page” on page 26. Save the file to the temporary directory

you just created. The following code is an example of a pages definition XML

file for the com.acme.my.feature sample application. It is similar to the content

of the exportpages.xml file, which is provided in the

wct\samples\deploy\xmlaccess subdirectory of the toolkit and defines page

parameters for the Call Center and Sample SDK applications:


<?xml version="1.0" encoding="UTF-8"?>

<request

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:noNamespaceSchemaLocation="PortalConfig_1.2.xsd"

type="export">

<portal action="locate">

<content-node action="export" uniquename="WCT.mypage"/>

</portal>

</request>

3. From a command prompt, change to the WebSphere Portal server’s \bin

directory and run the XMLAccess utility to export the page you created to a file

called pages.xml, for example:

xmlaccess -in c:\temp\<pages_definition.xml> -out c:\temp\pages.xml

-user wpsadmin -pwd wpsadmin -url 127.0.0.1:9081/lwp/config

where the -user and -pwd parameters contain the appropriate user name and

password values for WebSphere Portal, and the -url parameter contains the

appropriate IP address and port number for the HTTP port for the IBM

Workplace server. The <pages_definition.xml> file represents the file you

created in Step 2.

4. Open c:\temp\pages.xml in a text editor. This file now contains the settings

and content of the page you created earlier. Search for the bookmarkable

parameter for your page and after it, add the following parameters:

<parameter name="default_folder" type="string"

update="set">main</parameter>

<parameter name="iconpath" type="string"

update="set">/lwpupdate/images/myicon.png</parameter>

The sample feature does not require an activity parameter, since it is a

stand-alone application.

5. Save the file, and then import it into WebSphere Portal using the XMLAccess

interface, by returning to the command prompt opened to the WebSphere

Portal server’s \bin directory and typing the following:

xmlaccess -in c:\temp\pages.xml -out c:\temp\update-results.xml


Note: Example output files are provided in the

wct\samples\deploy\xmlaccess\example output files directory. Related tasks

“Accessing a Web address in the client browser” on page 56

Provisioning the client

Provisioning is the process of downloading application components, such as

plug-ins and features, to a client machine from an administrative server. The

administrative or provisioning server can then manage and upgrade the plug-ins

and features making up the applications running on client machines from a central

location. When you have successfully deployed your application on WebSphere

Portal, you can distribute the application to your users using one of the following

provisioning methods:

v Request or pull upgrades and plug-ins to client machines by completing the

″Provisioning the client using an Eclipse Update site″ procedure.

v Push upgrades and plug-ins to client machines by completing either the

″Provisioning the client using an Eclipse Update site″ or the ″Provisioning using

WebSphere Everyplace Device Manager″ procedure.

After you have initially provisioned your application using a remote server, you

can test the provisioning setup and make changes to it locally.

28 User’s Guide

Related tasks

“Provisioning the client using an Eclipse Update site”

“Provisioning using WebSphere Everyplace Device Manager” on page 30

“Testing provisioning locally” on page 32

Provisioning the client using an Eclipse Update site

Upgrades and new features can be pushed to client machines using an Eclipse

Update site by specifying the following portlet parameters when deploying the

new or updated plug-ins on WebSphere Portal:

v id.<feature_number>

v version.<feature_number>

v match.<feature_number>

For example, add the following portal parameters and set their values as indicated:

v id.Feature1=″com.acme.my.feature″

v version.Feature1=″1.0.0″

v match.Feature1=″compatible″

The next time the user starts up the client, he is informed that new updates are

available for downloading. When he accepts the download, the new or updated

feature is downloaded and its supporting plug-ins and features are added to the

applications subdirectory of the user’s rich client workspace directory.

See “Installing a feature on WebSphere Portal” on page 21for more details.

Related concepts

“Provisioning the client” on page 28

WebSphere Everyplace Device Manager: WebSphere Everyplace Device Manager

is a middleware component that manages end-user devices. It supports the open

standards management protocol, OSGi, among others. You can use the device

manager to provision application plug-ins to the client.

Note: See the IBMWorkplace Collaboration Services information center for details

on installing and setting up the WebSphere Everyplace Device Manager

server at:

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

WebSphere Everyplace Device Manager contains the following components:

v Device Manager Server -- A Java (J2EE) servlet application that runs on

WebSphere Application Server, along with appropriate device plug-ins for the

classes of the devices it manages. The application server handles network and

database access as well as provides the application management interface to

allow the Device Manager to be started and stopped as required. The work of

the Device Manager Server is accomplished through jobs. Jobs are stored in the

Device Manager database, and the server runs these jobs when they are

triggered either by events, such as when a managed device connects to a service

provider’s network, or by an administrative action. The Device Manager Server

is instructed in what device processing is required by the associated device

plug-ins.

v Device plug-ins -- A device plug-in is code that extends the Device Manager

Server. It provides the logic that handles device identification, communications,

job processing, and other high-level management tasks for a particular class of


managed devices. Each plug-in handles a different device class. The Device

Manager comes with plug-ins that support the OSGi-based devices device class,

among others. Plug-ins can be sub-classed to provide specialized handling of

derivative device types. The client provides such a plug-in to support

provisioning client application using WebSphere Everyplace Device Manager.

v Device Manager Database -- The Device Manager Database is the repository for

all device management information. It is implemented in a relational database

and can be accessed through the Device Management API, though the client

does not use any of these APIs. The database contains tables of entries that

describe managed devices and store device-related data, resources and

information, as well as information about the jobs that the Device Manager

Server can perform.

v Device Manager Administration Console -- The Device Manager Administration

Console is an optional graphical user interface for administering device

management operations from a Microsoft Windows client. Administrators may

use this interface to complete tasks such as add and view devices and device

software, submit jobs for devices, and query job status. The console calls

methods of the Device Management API to access information in the Device

Manager Database and perform requested operations.

Provisioning using WebSphere Everyplace Device Manager

You can use the WebSphere Everyplace Device Manager to provision client

features.

Before starting this procedure, be sure you have installed the WebSphere

Everyplace Device Manager. See the IBM Workplace Collaboration Services

information center for more details on updating rich client provisioning

components using WebSphere Everyplace Device Manager. Also, make sure you

have deployed the application on the Eclipse Update site on WebSphere Portal.

You will need to access the following file, which is installed as part of the server

client installation to the /Program Files/Workplace Rich Client

Provisioning/wedm_extensions/bin directory:

v bundlereg.zip -- Zip file containing the bundlereg.bat file that registers bundles

with WebSphere Everyplace Device Manager using the BundleTool.jar Java

program.

To set up provisioning the client using the WebSphere Everyplace Device Manager:

1. Configure the Workplace provisioning server to use the WebSphere Everyplace

Device Manager provisioning provider by editing the requirements.xml file

found in the following directory:

<websphere_install_dir>\AppServer\installedApps\<server_name>\

wps.ear\wps.war\themes\rcpml\

Edit the file by removing the comment designation from the WebSphere

Everyplace Device Manager provider preference setting. The resulting text

should look as follows:

<requirements>

<preference

plugin="com.ibm.rcp.provisioning"

key="com.ibm.rcp.provisioning.feature.provider"

value="com.ibm.rcp.provisioning.wedm.provider.WEDMProvider"/>

</requirements>

2. Set the Workplace Client Provisioning Server equal to the Web address of the

WebSphere Everyplace Device Manager server by completing the following

steps:

30 User’s Guide

a. Log into the WebSphere Administrative Console as an administrator by

adding ″:9091/admin″ to the WebSphere Application Server Web address

and supplying the administrator user name and password.

b. Select Resources/URL Providers, and then click Node and delete the

contents of the Node field.

c. Click Apply, and then click Default URL Provider.

d. Click URLs, and then click Workplace Client Provisioning Server, and edit

the fields as follows:

v Name = Workplace Client Provisioning Server

v JNDI Name = url/wctprovisioningurl

v Specification = <protocol>://<wedmserver

hostname>/dmserver/SyncMLDMServletAuthRequired. For example:

http://testserver.ourdev.acme.com/

dmserver/SyncMLDMServletAuthRequired

3. Find the files listed in the following directory on the machine to which you

installed the IBM Workplace server:

/Program Files/Workplace Rich Client Provisioning/wedm_extensions/bin

v features_list.txt -- Text file that lists the JAR file names of the features to be

registered with WebSphere Everyplace Device Manager. You can create this

by

v plugins_list.txt -- Text file that lists the JAR file names of the plug-ins to be

registered with WebSphere Everyplace Device Manager. You can create this

byUsing a text editor, edit these files to include any plug-ins and features that you

have created in addition to the standard platform plug-ins and features that the

files currently contain. Be sure the files are set to be delimited with a new line,

then save and close the files. Copy the files to the lwpupdate\wct\ directory of

the Eclipse update site; this is the same directory that contains the site.xml file.

4. Create a directory on the WebSphere Everyplace Device Manager server and

unzip the bundlereg.zip file to it.

5. Register the feature and plug-in bundles for your application by running

bundlereg.bat, which is provided in the bundlereg.zip file. Supply the following

information when prompted:

v Path to the WebSphere Everyplace Device Manager server ″_jvm″ directory.

For example: C:\TivDMS15\_jvm.

v Base Web address of the Eclipse Update site. For example:

http://server.mycompany.com/lwpupdate/wct/.

v Web address of the WebSphere Everyplace Device Manager server. For

example: http://<my wedm server>/.

v Path to the Eclipse update site at which the features_list.txt and

plugins_list.txt files reside.

v WebSphere Everyplace Device Manager server administrator user name.

v WebSphere Everyplace Device Manager server administrator password.

Related concepts


Local provisioning

You can set up your development environment to locally provision your

application so you can test how the plug-ins and features that make up your

application will be provisioned by a remote provisioning server.


When you provision your application using a remote provisioning server, the client

writes RCPML files that define the pages and overall configuration of your

application to the

<workspace_home>\.metadata\.plugins\com.ibm.rcp.pagebuilder directory. You

can copy these files to a local directory and edit the files so that you can test

provisioning locally. By testing the provisioning setup locally, you can work out

the dependencies of the features you are planning to deploy without having to

deploy the application from a remote server each time you want to try a new

configuration.

Related tasks

“Testing provisioning locally”

“Setting up the runtime environment” on page 10 Related reference

“Sample RCPML files” on page 33

Testing provisioning locally:

By setting up your development environment to locally provision your application

you can test how the plug-ins and features that make up your application will be

provisioned by a remote provisioning server and make any necessary changes

locally. Provisioning locally prevents you from having to run tests and make

changes to the setup on the remote server.

Be sure you have the client platform installed on the local machine before you start

the following procedure. See the topic, ″Rich client installation and configuration,″

in the IBM Workplace Collaboration Services information center.

To test provisioning locally:

1. Provision your application using a remote server.

2. Copy the pages and config folders in the

<workspace_home>\.metadata\.plugins\com.ibm.rcp.pagebuilder directory to

a local directory, such as C:\mysites.

3. On the C:\ drive, create a directory structure that mirrors the structure of the

Eclipse update site on the IBM HTTP Server, by creating the following

directories:

c:\mysites\

c:\mysites\features

c:\mysites\plugins

4. Copy the existing update site to these directories, copying the site.xml in the

mysites directory, the features into the mysites\features directory, and the

plug-ins into the mysites\plugins directory.

5. Delete the workspace that you created in Step 1, so you can provision again.

6. Edit all of the XML files in the page subdirectory as follows:

v Replace references to a remote server in the server attribute of any feature

tags contained by any updates tags to server=″file:///C:/mysites″

v Replace references to a remote server in the url attribute of any feature tags

contained by any requirements tags to url=″file:///C:/mysites″.7. Save and close the XML files.

8. Start the client using the following command to trigger the pagebuilder system

to download the requested features:

richclient -pbcache C:/mysites -debug

-personality com.ibm.rcp.pagebuilder.personality

32 User’s Guide

9. When you are prompted to restart the client, click Yes.

To re-run the test, delete your workspace directory or just the .config file and

applications subdirectories of your workspace. The local site will be re-created the

next time you start the client.

Related concepts


“Local provisioning” on page 31 Related tasks

“Setting up the runtime environment” on page 10

Sample RCPML files:

When you provision an application, the client caches the XML files that define the

application pages to the

<workspace_home>\.metadata\.plugins\com.ibm.rcp.pagebuilder directory on the

user’s machine. The page builder code, which runs on the client, manages the

RCPML and application pages and reprocesses the pages if it finds that the pages

have changed after comparing the cached versions of the pages to the latest

versions retrieved from WebSphere Portal. For example, when you provision the

Call Center and Samples applications, the page builder component of the client

manages the ″-lwp-myworkplace.xml″ file, which identifies the pages making up

the applications and is stored in the \config subdirectory of the

<workspace_home>\.metadata\.plugins\.com.ibm.rcp.pagebuilder directory. The

-lwp-myworkplace.xml file contains the following text:


<rcp>

<config count="3">

<page name="Content Root"

url="/wct/myworkplace/!ut/p/.cmd/cs/.ce/7_0_A/.s/7_0_A/_s.7_0_A/7_0_A"

markups="html,rcpml,chtml,wml">

<page name="WorkplaceRCPPages"

url="/wct/myworkplace/!ut/p/.cmd/cs/.ce/7_0_A/.s/7_0_LT/_s.7_0_A/7_0_LT"

markups="rcpml">

<parameters>

<param name="rootpage">Yes</param>

</parameters>

<page name="RCPSDK Call Center"

url="/wct/myworkplace/!ut/p/.cmd/cs/.ce/7_0_A/.s/7_0_18L/_s.7_0_A/7_0_18L"

markups="rcpml">

<parameters>

<param name="bookmarkable">Yes</param>

<param name="activities">com.ibm.workplace.demo.callcenter.activity

</param>

<param name="default_folder">main</param>

<param name="iconpath">/lwpupdate/images/callcenter.png</param>

</parameters>

</page>

<page name="RCPSDK Samples"

url="/wct/myworkplace/!ut/p/.cmd/cs/.ce/7_0_A/.s/7_0_1BP/_s.7_0_A/7_0_1BP"

markups="rcpml">

<parameters>

<param name="bookmarkable">Yes</param>

<param name="activities">com.ibm.workplace.samples.activity</param>

<param name="iconpath">/lwpupdate/images/samples.png</param>

</parameters>

</page>

</page>

</page>

</config >


<requirements>



</requirements>

</rcp>

The page builder component of the client also creates XML files to represent each

of the pages and stores them in the \pages subdirectory. The page file names are

identified in the url attributes of the page tags. The following page XML files are

created:

v -lwp-myworkplace-!ut-p-.cmd-cs-.ce-7_0_A-.s-7_0_A-_s.7_0_A-7_0_A

v -lwp-myworkplace-!ut-p-.cmd-cs-.ce-7_0_A-.s-7_0_LT-_s.7_0_A-7_0_LT

v -lwp-myworkplace-!ut-p-.cmd-cs-.ce-7_0_A-.s-7_0_18L-_s.7_0_A-7_0_18L

v -lwp-myworkplace-!ut-p-.cmd-cs-.ce-7_0_A-.s-7_0_1BP-_s.7_0_A-7_0_1BP

The pagebuilder component is also responsible for reprocessing the pages if they

are updated. The following example is the content of the -lwp-myworkplace-!ut-p-.cmd-cs-.ce-7_0_A-.s-7_0_18L-_s.7_0_A-7_0_18L.xml page:


<rcp name="RCPSDK Call Center">

<col_container>

<row_container>

<rcp_view

name="com.ibm.workplace.demo.callcenter.views.BannerView"

folderid=""

ratio=".12"

visible="yes"

fixed="yes"

style="NO_TITLE"

issecondary=""

allowMultiple="">

<updates>

<feature

name="com.ibm.workplace.demo.callcenter.wps.feature"

server="http://mywct.acmedev.ibm.com/lwpupdate/wct"/>

</updates>

<requirements>

<feature

id="com.ibm.workplace.demo.callcenter.wps.feature"

url="http://mywct.acmedev.ibm.com/lwpupdate/wct"

match="compatible" version="2.5.0"/>

</requirements>

<data>

</data>

</rcp_view>

</row_container>

<row_container>

<col_container>

<rcp_view

name="com.ibm.workplace.demo.callcenter.views.NavigatorView"

folderid="navigators"

ratio=".35"

visible="yes"

fixed="yes"

style="" issecondary=""

allowMultiple="">

<updates>

</updates>

<requirements>

</requirements>

<data>

34 User’s Guide

</data>

</rcp_view>

<rcp_view

name=""

folderid="resources"

ratio=".35"

visible="yes"

fixed="yes"

style=""

issecondary=""

allowMultiple="">

<updates>

</updates>

<requirements>

</requirements>

<data>

</data>

</rcp_view>

<rcp_view

name="com.ibm.workplace.demo.callcenter.views.LinksView"


ratio=".35"

visible="yes"

fixed="yes"

style=""

issecondary=""

allowMultiple="">

<updates>

</updates>

<requirements>

</requirements>

<data>

</data>

</rcp_view>

<rcp_view

name="com.ibm.workplace.demo.callcenter.views.FAQView"


ratio=".35"

visible="yes"

fixed="yes"

style=""

issecondary=""

allowMultiple="">

<updates>

</updates>

<requirements>

</requirements>

<data>

</data>

</rcp_view>

</col_container>

<col_container>

<rcp_view

name=""

folderid="main"

ratio=".65"

visible="yes"

fixed="yes"

style=""

issecondary=""

allowMultiple="">

<updates>

</updates>

<requirements>

</requirements>

<data>

</data>


</rcp_view>

<rcp_view

name="com.ibm.workplace.demo.callcenter.views.TicketsView"

folderid="main"

ratio=".65"

visible="yes"

fixed="yes"

style=""

issecondary=""

allowMultiple="">

<updates>

</updates>

<requirements>

</requirements>

<data>

</data>

</rcp_view>

<rcp_view

name="com.ibm.workplace.demo.callcenter.views.FAQFormView"

folderid="main"

ratio=".65"

visible="no"

fixed="no"

style=""

issecondary=""

allowMultiple="yes">

<updates>

</updates>

<requirements>

</requirements>

<data>

</data>

</rcp_view>

<rcp_view

name="com.ibm.workplace.demo.callcenter.views.TicketFormView"

folderid="main"

ratio=".65"

visible="no"

fixed="no"

style=""

issecondary=""

allowMultiple="yes">

<updates>

</updates>

<requirements>

</requirements>

<data>

</data>

</rcp_view>

</col_container>

</row_container>

</col_container>

</rcp>

Related concepts

“Local provisioning” on page 31

Initiating application updates

The IBM Workplace client checks for updates to the following items:

v RCPML that defines the layout of an application -- Every time a user starts the

IBM Workplace client, the pagebuilder system checks its cache to see if it has

valid and current RCPML. If it does not, it retrieves RCPML updates from

36 User’s Guide

WebSphere Portal. The pagebuilder system checks for updates to the RCPML

three minutes after the client starts up and then every hour while the client is

running and online.

v Features and plug-ins that comprise an application -- If you are using the Eclipse

Update Manager and the client is online and updates to an installed feature are

available, when the client performs its scheduled update checks, it detects the

updated features and downloads them. This update check runs after the

pagebuilder system update check is complete.

To initiate an update, do one of the following:

v If you are using WebSphere Portal and an Eclipse Update site to provision the

client, schedule regular updates by selecting File → Preferences → Update/Install

→ Automatic Updates from the client menu. The provisioning server follows the

schedule you set up here to check for any new or updated features that may be

available from the update site and download them. You can also specify whether

to use a wizard when updating, which guides you through the update, or to

update silently, which instructs the update system to download and install the

updates in the background, and then prompts you to restart the client so it can

load the updates.

v To force a feature update or the installation of a new feature, add a

<requirements> tag to the RCPML that specifies this new or updated feature by

supplying the following parameters to the portlet through which the application

is deployed: id.<featureID>, version.<featureID>, and match.<featureID>.

Regardless of the provisioning mechanism you are using, the client checks for

updates to the RCPML that defines the layout of the application. If, while

processing the RCPML, it encounters a requirements tag, it invokes a feature

requirements handler which passes the request to the provisioning system. The

provisioning system checks the current client configuration to determine if the

features and plug-ins specified in the requirements tag are installed. If a required

feature is not currently installed, the feature is downloaded and installed from

the provisioning server.

v If you are using WebSphere Everyplace Device Manager, you can push feature

upgrades and new features to client machines by creating a software distribution

job through the WebSphere Everyplace Device Manager administrative console. Related tasks

“Client application deployment” on page 19


Referencing provisioned rich client resources

To specify the client as the target platform on which you want to build

applications in Eclipse or Rational Application Developer, you must be able to

point to a single directory. However, because the Eclipse platform implements a

directory structure that enables separate, modular development and deployment of

the application and platform features, when you download and provision the rich

client, the platform and application code are installed to the following, separate

directories:

v Core platform installation directory, referred to as <client_home>

\Program Files\IBM\Workplace rich client

v Applications installation directory, referred to as <workspace_home>

\Documents and Settings\<username>\IBM\RCP\<rich client instance ID>\

<username>\applications


After you build an application and provision it to the rich client, you must

reference the workspace sources from the platform source before you can test and

edit it in the IDE. To reference the workspace sources, create a LINK file in the

<client_home>\eclipse\links subdirectory for each application in the applications

directory that you want to include in the platform. These link files tell the client

that applications exist and effectively pulls the applications into the <client_home>

directory.

To reference provisioned rich client application sources, perform the following

steps for each application you want to include in the target platform:

1. Create a LINK file, which is a text file with the extension .link, and give it a

name that identifies the application feature it references. For example, if you

want to reference a feature named com.ibm.rcp.my.app.feature, name the LINK

file as follows:

com.acme.my-feature.link

2. Add to the LINK file one entry, called ″path,″ and set it equal to the absolute

path of the feature. For example:

path=C:/Documents and Settings/<username>/IBM/RCP/<rich

client instance ID>/<username>/applications/com.acme.my.feature

Do not include trailing whitespace at the end of the path.

3. Register the link extension with the client by adding the LINK file to the

<client_home>\RCP\eclipse\links directory. For example:

C:\Program Files\IBM\Workplace rich client

eclipse

features

jre

links

com.acme.my-feature.link

plugins

4. From the IDE menu, select Window → Preferences to open the Preferences

window.

5. Expand Plug-in Development and click Target Platform to see the

<client_home> directory specified in the Location field.

For example, if you are running Windows and accepted the defaults during

installation, the Location field would contain:

C:\Program Files\IBM\Workplace rich client\eclipse

6. Click Reload to parse the plug-ins and refresh the target platform so it includes

the plug-in you are referencing in the LINK file.

38 User’s Guide

Chapter 3. Designing an application layout

The layout of the window that contains the views and folders included in your

application is defined by a perspective, which is the Eclipse equivalent of a

window. You set the perspective that you want the rich client to use by specifying

a personality when you build the layout of your application. The personality of an

application defines the framework the platform uses to determine what

perspectives or windows, menus, action bar items, and status line controls display

when the application starts, as well as what services are available and what

sequence of events or what life cycle should be applied to the objects associated

with that application.

The platform supports the implementation of a custom personality for a standalone

application. A standalone application is an application that uses a single, static

perspective and requires a static set of menu options, action bars, and other user

interface controls. You can define a custom personality using the

com.ibm.rcp.platform.api.Personality API.

The personality API also enables you to specify a presentation factory to apply to

an application. A presentation factory applies a pre-defined set of colors and fonts

to the user interface controls to give the application a uniform appearance. By

using a presentation factory, you can make a feature that you are contributing to a

shared application look consistent with other features hosted by the application.

Related tasks

“Building platform plug-ins and features” on page 12

“Creating a custom personality”

Creating a custom personality

You can define the content of the frame of the application window, its menus and

toolbars, and the presentation factory class to apply to the application using the

personality extension point. An application’s personality also identifies and

addresses the application’s startup sequence dependencies. You can use the

com.ibm.rcp.platform.api package to define a personality for your application. The

design of the com.ibm.rcp.platform plug-in code is based on the

WorkbenchAdvisor code provided by Eclipse as part of the

org.eclipse.ui.applications.WorkbenchAdvisor class. The limitation of the existing

Eclipse WorkbenchAdvisor code is that it allows for only one instance of the

WorkbenchAdvisor per Eclipse instance. 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.

For example, the IBM Workplace rich client uses a personality with the ID

com.ibm.workplace.personality to define the client’s layout and startup sequence.

Note: When you create a custom personality, you cannot use the automatic login

that is built into the IBM Workplace personality. As a result, operations

involving the local credential store are not available until the store is

unlocked through an explicit login operation.

To create a custom personality:


1. Define the perspective you want to use as the main window for the application:

package com.ibm.rcp.sample;

import org.eclipse.ui.IPageLayout;

import org.eclipse.ui.IPerspectiveFactory;

/**

* Test perspective for unit testing API samples.

*/

public class Perspective implements IPerspectiveFactory {

public void createInitialLayout(IPageLayout layout) {

String editorArea = layout.getEditorArea();

layout.addView("com.ibm.sample.views.SampleView",

IPageLayout.BOTTOM, (float).7, editorArea);

layout.setEditorAreaVisible(false);

}

}

2. Extend the com.ibm.rcp.platform.api.Personality package to implement a

personality that associates itself with the perspective you defined in Step 1.

Make sure it implements the getWindowPerspectiveId() method to return the

perspective ID:

package com.ibm.rcp.sample;

import org.eclipse.ui.application.IWorkbenchWindowConfigurer;

import com.ibm.rcp.platform.api.Personality;

public class DevPersonality extends Personality {

public String getWindowPerspectiveId() {

return "com.ibm.sample.Perspective";

}

}

3. Optional: To apply a uniform look and feel to your application, create a custom

presentation factory class and apply it as the

org.eclipse.ui.presentations.AbstractPresentationFactory for the Workbench

window by adding the following code to the preWindowOpen() method:

configurer.setPresentationFactory(new <yourCustomPresentationFactory>());

4. Create an extension to the com.ibm.rcp.platform.personalities extension point

and provide values for the personality class, name, id, and icon attributes.

<extension point="com.ibm.rcp.platform.personalities">

<personality

allowMultipleWindows="true"

class="com.ibm.sample.DevPersonality"

name="Application Development"

id="com.ibm.sample.DevPersonality"/>

</extension>

5. In the Program Arguments field of the runtime configuration page, add

″-personality <personality id>″ to start the client under this new personality. In

this example, you would type:

-personality com.ibm.rcp.sample.DevPersonality

Related concepts

Chapter 3, “Designing an application layout,” on page 39 Related tasks

“Setting up the development environment” on page 7

“Logging in to the local credential store” on page 69

“Setting up the runtime environment” on page 10

“Creating a personality class” on page 15 Related reference

“Control set extension point” on page 44

“Personalities extension point” on page 41

“Personality Extension extension point” on page 42

40 User’s Guide

“Personality startup extension point” on page 43

Personalities extension point

You instruct the client to start up using your personality when you start the client

platform by doing one of the following tasks:

v Append the following parameter to the rich client start command:

<client_home>\rcp\richclient -personality <personalityID>

v Edit the plugin_customization.ini file for your plug-in to include the following

key:

com.ibm.rcp.platform/DEFAULT_PERSONALITY_ID="<personalityID>"

where <personalityID> is the id attribute of the personality you define using the

personalities extension point.

Note: If you do not define a personality for your application, the client uses the

default IBM Workplace personality, com.ibm.workplace.personality. The IBM

Workplace personality uses the LWPPresentationFactory class to give the

application an IBM Workplace look and feel.

Extending the com.ibm.rcp.platform.Personalities extension point

In the plugin.xml file of your personality plug-in, provide values for the following

attributes of the <personality> tag:

v id -- Specifies a unique id for this personality. This id is passed to the command

line to launch the personality. You can specify this id as the parameter after a

-personality flag when starting the platform from the command line.

v name -- Localized name of the personality which only displays in the

personality chooser, which is a popup that you can start from the system tray if

the platform is started without a personality specified.

v class -- Fully qualified name of the class implementing the personality.

v icon -- Image file to display on a personality chooser, which is a window that

you can open from the system tray if the platform is started without a

personality specified.

v allowMultipleWindows -- Boolean value. If a window is already running with

this personality, this attribute specifies whether a command line launch of this

personality should give focus to the existing window or start a second window

with the personality. Specify true to open a new window and false to activate

the existing window. The default value is false.

The following text is an example of plugin.xml file content that declares a new

personality:

<extension point="com.ibm.rcp.platform.personalities">

<personality

icon=""/icons/acme.gif"

name="Acme personality"

id="com.ibm.acme.MyPersonalityImpl"

class="com.ibm.acme.MyPersonalityImpl"

allowMultipleWindows="false"/>

</extension>

Chapter 3. Designing an application layout 41

Window startup life cycle

In your personality class, write a subclass of the com.ibm.rcp.platform.Personality

class that provides the customizations specific to your personality. There is one

abstract method, getWindowPerspectiveID(), which must return the perspective ID

for the window.

A personality that extends this extension point instructs the platform to perform

the following series of events at startup:

v Call the getContinueLaunch() method. If the allowMultipleWindows attribute of

the personality tag is set to false, the client aborts the launch of a new window.

v Call the following methods in sequence:

– getWindowPerspectiveID()

– preWindowOpen()

– fillActionBars()

– createWindowContents()

– postWindowCreate()

– preWindowOpen()

– postWindowOpen()v Call any methods supplied using the PersonalityStartup extension point.

Window shutdown life cycle

A personality that extends this extension point instructs the platform to call the

following series of methods for which you can write code that performs events at

shutdown:

v Calls the preWindowShellClose() method.

v Calls the postWindowClose() method.

There is also a preWorkbenchShutdown() method available. See the Client Java API

documentation for more details on this method.

Related tasks


Personality Extension extension point

Use this extension point to associate one of the following types of contributions

with a personality:

v controlSet -- A set of user interface controls to display in the status line of the

windows controlled by this personality.

v startup -- The class to load and run after the window for a personality has been

loaded.

com.ibm.rcp.platform.personalityExtension

In the plugin.xml file for the personality plug-in you write to extend the

com.ibm.rcp.platform.PersonalityExtension extension point, provide a value for the

following attribute for the <personalityExtension> tag:

v targetID -- Unique personality that this extension extends.

42 User’s Guide

The <personalityExtension> tag contains a tag to represent each contribution

associated with the personality. It can contain the following tag types, each of

which contains an id attribute that specifies the unique ID of the contribution to

associate with this personality:

v <controlSet>

v <startup>

Example plugin.xml file content that declares a new personalityExtension:

<extension

point="com.ibm.rcp.platform.personalityExtension">

<personalityExtension

targetid="com.ibm.acme.MyPersonalityImpl">

<controlSet id="example.ControlSet"/>

<controlSet id="another.example.controlSet"/>

<startup id="com.ibm.acme.exampleplugin.MyStartup"/>

</personalityExtension>

</extension>

Related tasks


Personality startup extension point

The com.ibm.rcp.platform.personalityStartup extension point’s design is based on

the org.eclipse.ui.Startup extension point. The startup code is associated with a

specific personality by specifying the association in the personalityExtension

extension point. If you associate a personality with a personalityStartup extension,

the class defined in the personalityStartup extension point is instantiated at startup

in place of the class specified in the platform plug-in. The platform calls the

earlyStartup() method on the specified class and runs it in a background thread,

not the SWT user interface thread.

com.ibm.rcp.platform.personalityStartup

In the plugin.xml file for the personalityStartup plug-in you write to extend the

com.ibm.rcp.platform.personalityStartup extension point, provide values for the

following attributes for the <personalityStartup> tag:

v class -- Fully qualified name of the class implementing org.eclipse.ui.IStartup.

v id -- Unique name for this personalityStartup extension, which is used in the

personalityExtension tag’s startup tag to identify this contribution.

Example plugin.xml file content that defines what actions to trigger when this

personality is started up:

<extension point="com.ibm.rcp.platform.personalityStartup">

<personalityStartup

id="com.ibm.acme.exampleplugin.MyStartup"

class="com.ibm.acme.exampleplugin.PersonalityStartup" />

</extension>

The class you write to perform custom startup tasks must implement

org.eclipse.ui.IStartup.

Related tasks



Control set extension point

The controlSet extension point is similar to an actionSet extension point in the

Eclipse platform. The Eclipse actionSet extension point enables you to add menus

and actions to menu bars, and actions to tool bars. The controlSet extension point

enables you to contribute sophisticated user interface controls to the status line of a

window in a specific personality.

com.ibm.rcp.platform.controlSet

In the plugin.xml file for the personality plug-in you write to extend the

com.ibm.rcp.platform.controlSet extension point, provide values for the following

attributes for the <controlSet> tag:

v id -- Unique ID of this control set. This ID is used in other extension points to

refer to this control set.

v visible -- Boolean value that defines whether this controlSet is visible globally.

Default is false. Control sets are included in activity bindings. If the visible is set

to true and the id attribute matches an activity binding pattern, the control set

appears if that activity is enabled.

The controlSet tag defines a set of group locations and controls to display in those

locations. To specify the group location and controls, the controlSet tag contains the

following tags:

v groupMarker -- Defines a custom subgroup of status line elements to which you

can add your contribution. A subgroup defines a location on the status line to

which a control can be contributed. There is a groupMarker element in the

actionSet extension point as well. The actionSet groupMarker element serves as

the space on the menu bar or action bar that contains the controls or actions,

and is separated from other groups by a separator element, which displays a

visible separator, such as a horizontal line in a menu, for example. The

groupMarker element in the controlSet extension point defines a space on the

status line that is reserved for controls that are associated with the group. Define

the following attribute for the groupMarker element:

– name -- Name of this groupMarker. This name is referred to in the

statusLinePath attribute of the control element.v control -- Defines a rich control to display in the status line in the Workbench

window. The control element is similar to the action element in the actionSet

extension point, except that a rich control is one that defines arbitrary content,

which cannot be supported by a standard action contribution. Define the

following attributes for the control element:

– statusLinePath -- Defines where the control is displayed in the status line.

This can be defined by specifying one of the following predefined groups:

- BEGIN_GROUP

- MIDDLE_GROUP

- END_GROUP

or by specifying a custom group by referencing a statusLine and

groupMarker element pair. Specify the custom group using the following

format:

statusLine_id/groupMarker_name

where statusLine_id represents the id attribute of the statusLine element and

groupMarker_name represents the name attribute of the groupMarker

element.

44 User’s Guide

– id -- Unique ID of this control. This control ID and the ID of the plug-in

contributing this control are used to filter the display of this control in the

status line of the user interface.

– class -- Fully qualified class name of a class implementing IContributionItem

and implementing the fill(Composite parent) method.v statusLine -- Defines a marker location to which other status line items can be

contributed. This element is similar to the menu element in the actionSet

extension point. Define the following attributes for the statusLine element:

– id -- Unique ID of the statusLine element. This ID is used by the controls and

other statusLine elements that want their control contribution to display in

this location on the status line.

– path -- Defines the path to which this status line is contributed. This can be

defined by specifying one of the following predefined groups:

- BEGIN_GROUP

- MIDDLE_GROUP

- END_GROUP

Example of plugin.xml file content that declares a controlSet extension point:

<extension point="com.ibm.rcp.platform.controlSet">

<controlSet

visible="false"

id="example.ControlSet"

>

<statusLine

path="BEGIN_GROUP"

id="example.statusline" >

<groupMarker

name="additions" />

</statusLine>

<control

statusLinePath="BEGIN_GROUP"

class="com.ibm.acme.example.ContributionItem"

id="example.control" />

<control

statusLinePath="example.statusline/additions"

class="com.ibm.acme.example.ContributionItem2"

id="example.control2" />

<controlSet>

</extension>

API Information

The class you write to implement the control tag

(com.ibm.acme.example.ContributionItem, for example) must implement the

following classes and methods:

v org.eclipse.jface.action.IContributionItem class -- You can implement this by

creating a subclass of org.eclipse.jface.action.ContributionItem.

v fill(Composite parent) method -- This method realizes the user interface widget

in the status line.

v org.eclipse.ui.IPluginContribution -- An interface that descriptor classes may

implement in addition to their descriptor interface. Related tasks



Application look and feel

You can apply a custom look and feel to an application by extending the Eclipse

presentation factory extension point org.eclipse.ui.workbench.presentationFactories

to define a custom presentation factory. A presentation factory defines the

following things:

v Graphic to use for branding.

v Size of the title bar.

v Color to use for the title bar background.

v Color to use for the tab background.

v Color to use for the title bar text.

v Color to use for the tab text.

v Folder view background.

Note: See the Eclipse SDK documentation for more information on extending the

presentationFactories extension point.

You can instantiate the custom presentation factory from your custom personality

by including the setPresentationFactory() method in the preWindowOpen() method

of your custom personality. For example, for a presentation factory class named

MyPresentationFactory, the code would look as follows:

public void preWindowOpen(IWorkbenchWindowConfigurer configurer) {

// set the presentation factory

configurer.setPresentationFactory(new MyPresentationFactory());

For example, the IBM Workplace rich client personality implements a custom

presentation factory called the LWPPresentationFactory.

Activities

Activities are an Eclipse mechanism used in the IBM Workplace Client Technology

platform to associate user interface contributions with applications. Activities

prevent actions and control sets in one application from being displayed in another

application. Activities are associated with user interface contributions using activity

pattern bindings. An activity pattern binding is a pattern that is matched against

the ID of the user interface contributions made by a plug-in. When an activity is

enabled in the platform, the user interface contributions associated with that

activity are shown. When an activity is disabled in the platform, its user interface

contributions are not shown. Through RCPML, application pages can be assigned

an activity. When the user switches to that page, that page’s activity is enabled.

When the user navigates away from the page, the activity is disabled.

You can create an activity using the org.eclipse.ui.activities extension point. For

example, the regional settings editor activity defined in the

com.ibm.myeditor.supereditor.baseview plug-in associates itself with the

com.ibm.supereditor.preferences.documenteditors.RegionalSettingsEditor

contribution:

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

<activity

name="RegionalSettingsEditor"

description="RegionalSettingsEditor Activities"

id="com.ibm.myeditor.RegionalSettingsEditor">

</activity>

<activityPatternBinding

activityId="com.ibm.myeditor.RegionalSettingsEditor"

46 User’s Guide

pattern="com\.ibm\.myeditor\.supereditor\.baseview/com\.ibm\

.supereditor\.preferences\.documenteditors\.RegionalSettingsEditor">

</activityPatternBinding>

</extension>

The patterns used by the Workbench are composed of two parts. The first part uses

the identifier of the plug-in that is contributing the user interface extension. The

second part is the ID used by the plug-in itself when defining the contribution. The

following format is used:

plug-in-identifier + "/" + local-identifier

where the identifiers include a backslash (\) before each period in their

namespaces.

For more information on activities, see the Activities topic in the Platform Plug-in

Developer Guide in the Eclipse Help supplied with the Eclipse SDK.


48 User’s Guide

Chapter 4. Developing the application user interface

This section provides information about how to use the IBM Workplace Client

Technology user interface plug-ins to build user interface components for an IBM

Workplace Client Technology application. This information assumes that you know

how to use the Eclipse SDK or Rational Application Developer to build the basic

user interface components that make up a client application, such as:

v Perspective -- Each Eclipse Workbench window contains one or more

perspectives. A perspective defines the initial set and layout of views in the

Workbench window. Each perspective provides a set of functionality aimed at

accomplishing a specific type of task or works with specific types of resources.

v View -- Views provide alternative presentations as well as ways to navigate the

information in your Workbench. Views also have their own menus. To open the

menu for a view, click the icon at the left end of the view’s title bar. Some views

also have their own toolbars. The actions represented by buttons on view

toolbars only affect the items within that view.

v Tabbed view -- Multiple views stacked on top of each other with only a tab

displaying to identify the view. Tabbed views are built by adding a view to a

perspective with a folder layout.

This guide focuses on describing the user interface controls that the IBM

Workplace Client Technology platform provides in addition to the standard Eclipse

user interface components.

Note: See the Workbench User Guide Help provided with the Eclipse 3.0 SDK for

information on how to build and work with these basic user interface

components.

Note: See the IBM Workplace User Interface Guidelines PDF file included in this

toolkit for details on how to build user interface components and controls

that have the same look and feel as the controls and components used in all

standard IBM Workplace applications.

Related concepts

“Eclipse components used in the client”

“Model View Controller architecture” on page 50

“Action bars” on page 60 Related tasks

“Adding editing functionality to an application” on page 63

“Adding alerts” on page 54


“Contributing to a menu” on page 64

“Implementing keyboard shortcuts” on page 65

Eclipse components used in the client

Eclipse is an open, extensible integrated development environment that developers

can use to create tools that integrate with the Eclipse platform. The IBM Workplace

Client is based on Eclipse and functions as an application platform. As such, it

excludes most of the components that make Eclipse a tool-building platform. One


of the Eclipse components that the IBM Workplace Client uses is the Workbench.

The Eclipse Workbench is the user interface of the Eclipse platform. It manages the

user interface objects that constitute an Eclipse-based application. The core Eclipse

user interface objects are the following:

Workbench User Interface Objects

Perspective

Similar to a main window. The perspective defines the initial set and

layout of views in the Workbench window. Within the window, each

perspective shares the same set of editors. Each perspective provides a set

of functionality aimed at accomplishing a specific type of task or works

with specific types of resources. Perspectives control what is displayed in

certain menus and toolbars. They define which action sets, which are

groups of actions that execute associated code when triggered, are visible.

You can change the action sets that display to customize a perspective.

View Views provide ways to display and navigate the information in your

Workbench. Views also have their own menus and some have their own

toolbars. The actions represented by buttons on view toolbars only affect

the items within that view.

The Workbench provides the low-level coding that associates views with

perspectives and creates basic menus and toolbars that are inactive until you

decide to use them.

The Eclipse Workbench contains the following toolkits to help you build the user

interface for the perspectives, views, and editors that make up your application:

Workbench Components

JFace Operating system-independent set of user interface frameworks for

common user interface tasks. This provides frameworks for completing

more advanced user interface implementations, such as wizards, preference

pages, dialog boxes, structured viewers, actions, and text formats.

SWT -- Standard Widget Toolkit

Provides a thin wrapper over the user interface controls, such as buttons or

menus, available from a machine’s operating system. The advantage is that

the resulting application retains the look and feel of the user’s other

applications on their operating system. SWT uses native controls where

available and emulates those controls if no equivalent control exists for the

operating system.

Another important role of the Workbench is to ensure that all plug-ins included in

an application are activated. The classloader is solely responsible for running the

core plug-ins. Any additional plug-ins, such as those contributed through extension

points are handled by the Workbench.

Related concepts

Chapter 4, “Developing the application user interface,” on page 49

Model View Controller architecture

The Model View Controller (MVC) architecture separates an application’s data

model, user interface, and control logic into separate components so that

modifications to views that display the data can be made with minimal impact to

the data models populating the views and vice versa. The advantage of

implementing an MVC design model in your IBM Workplace Client Technology

50 User’s Guide

application is that you do not have to edit the view that exposes your data every

time you change the data. An additional benefit of the client implementation of the

MVC design model is that, if you follow the recommended design patterns for

building your views, the platform updates the view if the data changes.

Related concepts


“Threading model” on page 52

“Design patterns that support view-to-view communication” on page 53 Related tasks

“Using JFace to create adapter views”

Using JFace to create adapter views

The model view controller architecture usually involves multiple views and a

single data source. Currently, in the Eclipse platform, only one view can be

associated with a single model. The IBM Workplace Client Technology platform

enables you to create multiple views that can access the same data.

To create an adapter view:

1. In the code you write to create the view, instantiate a Viewer using the

createPartControl() method.

public class FAQsView extends ViewPart {

...

public void createPartControl(Composite parent) {

// define a grid layout

GridLayout layout = new GridLayout();

layout.numColumns = 1;

layout.marginHeight = 0;

layout.marginWidth = 0;

layout.horizontalSpacing = 0;

layout.verticalSpacing = 1;

parent.setLayout(layout);

// create widgets

createActionBar(parent);

createTree(parent);

// add context menu and listeners

viewer.addDoubleClickListener(this);

viewer.addSelectionChangedListener(openAction);

// register viewer so actions respond to selection

getSite().setSelectionProvider(viewer);

hookContextMenu();

// show view now if ready

showBusy(!ModelManager.getFaqModel().isAvailable());

ModelManager.getFaqModel().addModelListener(this);

}

private void createTree(Composite parent) {

viewer = new TreeViewer(parent,

SWT.SINGLE | SWT.H_SCROLL | SWT.V_SCROLL | SWT.BORDER);

DrillDownAdapter drillDownAdapter = new DrillDownAdapter(viewer);

viewer.setContentProvider(new FAQsViewContentProvider());

viewer.setLabelProvider(new FAQsViewLabelProvider());

viewer.setSorter(new ViewerSorter());

viewer.setInput(ModelManager.getFaqModel());

viewer.getControl().setLayoutData(new GridData(GridData.FILL_BOTH));

}

...

}

2. In a separate class, implement a ContentProvider, which is an object that

provides data to the view, using the appropriate interface for the viewer type

Chapter 4. Developing the application user interface 51

you are creating. For example, you can implement an

IStructuredContentProvider or an ITreeContentProvider viewer.

Note: See the Eclipse Platform Plugin Developer Guide for information on

viewers.

public class FAQsViewContentProvider

implements ITreeContentProvider, IModelListener {

3. Associate the ContentProvider and Viewer to one another by implementing one

of the following methods in the ContentProvider code:

v getElements(Object parent)

v getChildren(Object element)The JFace framework calls these methods at the right time.

4. Include an inputChanged() method in the ContentProvider class. Whenever the

viewer has a new input set, it uses the inputChanged() method to notify the

ContentProvider. The inputChanged() method accepts a viewer as an input

argument, so multiple views can use a single ContentProvider.

/**

* Register content provider with model.

*/

public void inputChanged(Viewer viewer, Object oldInput,

Object newInput) {

if (newInput != null) {

this.viewer = viewer;

this.model = (FAQDelegate)newInput;

this.model.addModelListener(this);

}

}

Note: If you have a large database with thousands of items and do not want to

retrieve them all for display at once, implement a PageContentProvider to

specify how many data objects to return per page to the display.

Related concepts


Threading model

The threading model for the platform consists of a single user interface thread for

a single application. Use this single thread solely for user interface work, such as

rendering controls. Decouple any data-related, or time-intensive tasks from the

user interface and run it in a non-UI thread. This model complements the

MVC-based view model in that you can run the ContentProvider in a non-UI

thread and the Viewer in the UI thread.

For information on using more than one user interface thread, refer to the Eclipse

org.eclipse.core.runtime.jobs API package in the Eclipse SDK documentation.

If you want to collect user input or display error messages to the user from the

non-UI thread, the framework provides the Runnable interface that calls the user

interface code. There are two methods you can use:

Runnable Methods

syncExec(Runnable)

Best to use when the application code in the non-UI thread depends on the

return value from the user interface code or otherwise needs to ensure that

the process is run to completion before returning to the thread.

52 User’s Guide

asyncExec(Runnable)

Best to use when the application needs to perform some user interface

operations, but does not depend on the operations being complete before

continuing.

Workbench and JFace API code do not check that the caller is running in the UI

thread. SWT triggers a SWTException for all API calls made from a non-UI thread.

The following code demonstrates how to define a viewer that runs in an

asynchronous thread.

public class NavigatorView extends ViewPart ... {

/* * Implementation of IWorkbenchPart.createPartControl(Composite) */


...

... fViewer = (TreeViewer) createViewer(parent);

getViewer().getControl().getDisplay().asyncExec(new Runnable() {

public void run() {

...

Related concepts


Design patterns that support view-to-view communication

The following design patterns supported by the client are useful for

communication between different views in a single perspective.

Design patterns

PropertyChangeListener

The JFace frameworks contain classes that report property change events

for internal state changes that may be of interest to external parties. A

special listener interface (IPropertyChangeListener) is defined for this

purpose

selectionChanged

Classes which implement this interface provide methods that deal with the

events that are generated when selection occurs in a control. public class PreferenceManager implements IPreferenceNames {

private static PreferenceManager _prefMgr = new PreferenceManager ();

...

IPropertyChangeListener _listener = new IPropertyChangeListener() {

public void propertyChange(PropertyChangeEvent event) {

String propertyName = event.getProperty();

...

}

}

};

public void selectionChanged(ActionModelEvent event)

{

...

}

Related concepts



Adding alerts

The com.ibm.rcp.ui.alerts plug-in enables you to display an alert to users to advise

them of an event, such as the arrival of a new mail message in the inbox folder of

an e-mail application. Alert messages can be displayed in an alert bubble that pops

up from the system tray or can be displayed as a text string in the status bar of the

window. The alerts framework provided by the IBM Workplace Client Technology

platform enables you to register an alert and register the consumer of the alert. To

register the alert, you define it using the alertTypes extension point. To register a

consumer for a specific alert type, you associate the consumer with the alert type

using one of the IAlertListener, IAlertBubbleListener, and IAlertStatusListener

interfaces.

To add an alert to your application:

1. Extend the com.ibm.rcp.ui.alerts.alertTypes extension point by including the

following code in the plugin.xml file of the plug-in whose code performs the

action for which you want to trigger an alert:

<extension

point="com.ibm.rcp.ui.alerts.alertTypes"

<alertType

id="com.ibm.rcp.samples.alerts.sample"

name="Sample Alert Name"


image="icons/sample.gif"

timeout="5000">

</alertType>

</extension>

Supply values for the attributes of the <alertType> element.

2. Write code that defines how to call the alert and defines the notification to pass

to the AlertManager when an alert of the type defined in the extension point is

triggered:

public class ShowAlertAction extends AbstractMenuAction {

public void run() {

try {

// get alert defined in extension point

IAlertManager manager = AlertFactory.getAlertManagerInstance();

IAlert alert =

manager.getAlert("com.ibm.rcp.samples.alerts.sample");

alert.setMessage("Sample message");

manager.addAlert(alert);

3. Show the alert using the IAlertBubbleManager interface.

IAlertBubbleManager bubbleManager =

AlertFactory.getAlertBubbleManagerInstance();

bubbleManager.showAlert(alert, new AlertHandler());

} catch (Exception ex) {

ExceptionHandler.handleException(ex);

}

}

}

4. You can trigger the alert from a tool bar using the following code:

private void createToolBar(Composite parent) {

ToolBar bar = new ToolBar(parent, SWT.RIGHT);

ToolBarManager manager = new ToolBarManager(bar);

ActionContributionItem item =

new ActionContributionItem(new ShowAlertAction());

54 User’s Guide

item.setMode(ActionContributionItem.MODE_FORCE_TEXT);

manager.add(item);

manager.update(true);

}

5. Define how to handle alert events that can be called when the alert is triggered.

public class AlertHandler implements IAlertBubbleListener {

public void handleAlertBubbleEvent(AlertBubbleEvent event) {

// respond to events for the sample alert

IAlert alert = event.getAlert();

if ("com.ibm.workplace.samples.alerts.sample".equals(alert.getID())) {

switch (event.getType()) {

case AlertBubbleEvent.ACTION:

showMessage(event, "Alert message clicked");

MessageDialog.openInformation(null, "Alert Clicked",

"...do something");

break;

case AlertBubbleEvent.CLOSE:

showMessage(event, "Alert closed");

break;

case AlertBubbleEvent.OPEN:

showMessage(event, "Alert opened");

break;

case AlertBubbleEvent.RESUME:

showMessage(event, "Alert resumed");

break;

case AlertBubbleEvent.SUSPEND:

showMessage(event, "Alert suspended");

break;

case AlertBubbleEvent.TIMEOUT:

showMessage(event, "Alert expired");

break;

}

}

}

private void showMessage(AlertBubbleEvent event, String msg) {

// TODO Find better place to ouptut messages

System.out.println("[ALERT] Received alert event: " + msg);

}

}

Related concepts

Chapter 4, “Developing the application user interface,” on page 49 Related reference

“AlertType extension point”

AlertType extension point

Enables you to register an alert in the alerts framework. Alerts are named events

that you can trigger from a variety of user interface components.

Extending the com.ibm.rcp.ui.alerts.alertTypes extension point

In the plugin.xml file of the plug-in for which you want to register an alert,

provide values for the following attributes of the <alertType> tag:

v id -- Specifies a unique ID for this alert event.

v name -- Name of this alert, specified as a translatable string.

v image -- Image file used to brand this alert type. Indicates the image file you

want displayed when the event is triggered, such as in the body of a dialog box

or an AlertBubble.


v icon -- Icon file used to brand this alert type. Icons are small images rendered in

labels and title bars.

v timeout -- The length of time, in milliseconds, that the alert will be active.

The following text is an example of plugin.xml file content that registers an alert

event:

<extension point="com.ibm.rcp.ui.alerts.alertTypes">

<alertType

id="my.newmail.alert"

name="%str.newmail.alert"

icon="icons/new_mail_icon.gif"

image="icons/new_mail_image.gif"

timeout="5000">

</alertType>

</extension>

Related tasks

“Adding alerts” on page 54

Accessing a Web address in the client browser

The IBM Workplace Client Technology platform supports running a Web browser

within the client window. You can use the com.ibm.rcp.ui.browser.core.api code to

implement a hypertext link in your application that, when clicked, opens that Web

address in an embedded Web browser.

Use a placeholder in the perspective to indicate what page you want the browser

to display in. A placeholder is an Eclipse concept. For example, you can use the

IPageLayout.addPlaceholder(); method to add a placeholder to a perspective. See

the Eclipse SDK Platform Plug-in Developer Guide for more details. If you are using

RCPML to define the layout of your application, the Web browser opens in the

folder that you specified in the default_folder parameter in the RCPML for the

page the address is requested from.

To access a Web address in the client browser:

1. Import the com.ibm.rcp.ui.browser.core.api plug-in in the plugin.xml file for

your plug-in. For example:

<requires>

...

<import plugin="com.ibm.rcp.ui.browser"/>

</requires>

2. In the class that implements the API, import the following classes:

import com.ibm.rcp.ui.browser.core.api.BrowserFactory;

import com.ibm.rcp.ui.browser.core.api.IBrowser;

import com.ibm.rcp.ui.browser.core.api.LaunchContext;

3. Instantiate the IBrowser using the BrowserFactory class. The following code

demonstrates how to use the browser API:

String url = "http://www.ibm.com";

IBrowser browser = BrowserFactory.getBrowserInstance();

LaunchContext context = new LaunchContext(url);

browser.launch(context);

The following is another example taken from the Samples application’s

LaunchBrowserAction.java class:

import com.ibm.rcp.samples.actions.AbstractMenuAction;

import com.ibm.rcp.samples.util.ExceptionHandler;

import com.ibm.rcp.ui.browser.core.api.ILaunchBrowser;

56 User’s Guide

import com.ibm.rcp.ui.browser.core.api.ILaunchContext;

import com.ibm.rcp.ui.browser.core.api.LaunchBrowserFactory;

/**

* Simple example of launching the browser.

* Browser will open to the default folder on the current page.

*/

public class LaunchBrowserAction extends AbstractMenuAction {

public void run() {

try {

//Get a browser launcher

ILaunchBrowser launchBrowser =

LaunchBrowserFactory.getBrowserInstance();

//make a launch context based on the snoop url

ILaunchContext launchContext =

LaunchBrowserFactory.createLaunchContext("http://www.ibm.com");

// open browser

launchBrowser.launch(launchContext);



}

}

}

Related concepts

Chapter 4, “Developing the application user interface,” on page 49 Related tasks

“Accessing a Web address using an LTPA token”

“Adding parameters to a WebSphere Portal page” on page 27

Accessing a Web address using an LTPA token

When users log into the WebSphere Portal server or IBM Workplace server, they

are authenticated against WebSphere Application Server. If global security for the

WebSphere Application Server is enabled and LTPA authentication is configured,

the WebSphere Application Server generates an LTPA token for users that serves to

prove their identity to services and servers that they subsequently interact with.

You can use this same LTPA token to start a secure browser window. You can use

the com.ibm.rcp.security.api.http.login APIs to retrieve the LTPA token from the

server as a cookie.

Note: This process requires using the class org.apache.commons.httpclient.Cookie,

provided by Jakarta commons HTTP Client project, to get the LTPA Cookie

to be passed into the browser. The client plug-in,

com.ibm.rcp.net.apache.httpclient, wraps the Jakarta commons HTTP client

APIs. The sample application provided in the toolkit uses it. However this

plug-in and the JAR files exported by it are not supported as public APIs

and will change in subsequent releases of the IBM Workplace Client

Technology platform. If you want to maintain binary compatibility in

subsequent releases, create a custom plug-in to wrap the Jakarta commons

HTTP client JAR files.

To provide secure access to a Web address without prompting the user for

credentials:

1. Import the com.ibm.rcp.ui.browser.core and com.ibm.rcp.security.core plug-ins

in the plugin.xml file for your plug-in. For example:


<requires>

<import plugin="com.ibm.rcp.security.core"/>

<import plugin="com.ibm.rcp.ui.browser.core"/>

</requires>

2. In the class that implements the API, import the following classes:

...

import org.apache.commons.httpclient.Cookie; ...

import com.ibm.rcp.platform.api.PlatformContext;

import com.ibm.rcp.samples.SamplesPlugin;

import com.ibm.rcp.samples.actions.AbstractMenuAction;

import com.ibm.rcp.samples.util.ExceptionHandler;

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

Note: The following methods in the com.ibm.rcp.security.api.http.login API

require the use of the Jakarta commons HTTP client API code.

v public org.apache.commons.httpclient.HttpClient getHttpClient()

v public org.apache.commons.httpclient.Cookie

getCredentialCookie(java.lang.String name)3. Use IHttpFormLoginContext to log into the IBM Workplace Collaboration

Services server to get the cookie.

public class SSOBrowserLoginAction

extends AbstractMenuAction {

public void run() {

try {

// get current host and portal URL

String host = PlatformContext.getJNDIHostName();

String url = PlatformContext.getPortalURL();

// get password credential from credential store for the current host

SamplesPlugin.getLogger().info("Extracting credentials to

IBM Workplace Collaboration Services server " + host);

IHostCredentialManager manager =

ICredentialManagerFactory.INSTANCE.getHostCredentialManager();

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

// validate credential

Assert.isNotNull(creds);

if (creds.length == 0) {

throw new IllegalStateException(

"Unable to find any credentials for host " +

host + "\n\n" + "Possible cause: the login server

has been changed after the credential was created");

}

Assert.isTrue(creds[0] instanceof IPasswordCredential,

"Credential is not a password credential");

// get username and password from credential

IPasswordCredential cred = (IPasswordCredential)creds[0];

final String user = cred.getUsername();

final char[] password = cred.getPassword();

SamplesPlugin.getLogger().info("user: " + user);

SamplesPlugin.getLogger().info("password: " +

(!password.equals("") ? "****" : "<null>"));

// build J2EE callback

CallbackHandler handler = new CallbackHandler() {

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

UnsupportedCallbackException {

58 User’s Guide

for (int i=0; i<callbacks.length; i++) {

SamplesPlugin.getLogger().fine("HttpFormLoginContext

callback handler: " + callbacks[i]);

if (callbacks[i] instanceof NameCallback) {

NameCallback nc = (NameCallback)callbacks[i];

nc.setName(user);

} else if (callbacks[i] instanceof PasswordCallback) {

PasswordCallback pc = (PasswordCallback)callbacks[i];

pc.setPassword(password);

} 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

}

}

}

};

// login to the WCT j_security_check using name and

password to get the LTPA cookie

SamplesPlugin.getLogger().info("Authenticating with

/lwp/j_security_check");

IHttpFormLoginContext context =

IHttpFormLoginContextFactory.INSTANCE.create();

context.login(

host,

80,

"/lwp/j_security_check",

false,

handler,

null);

SamplesPlugin.getLogger().info("Authentication successful");

SamplesPlugin.getLogger().info("HttpFormLoginContext

authenticated on port: " + context.getHttpClient().getPort());

// get cookie from the context (an exception would

have occurred if login was unsuccesful)

Cookie cookie =

context.getCredentialCookie(IHttpFormLoginContext.CREDENTIAL_LTPA);

Assert.isNotNull(cookie, "Authentication with host was successful,

but no LTPA cookie was found");

4. Set the context for the browser to a WebSphere Portal snoop site:

// ILaunchContext launchContext =

LaunchBrowserFactory.createLaunchContext("http://"+

PlatformContext.getJNDIHostName()+":9080/snoop");

ILaunchContext launchContext =

LaunchBrowserFactory.createLaunchContext(url);

// assign the LTPA cookie

launchContext.setSingleSignOnCookie(cookie.getValue(),

ILaunchContext.CREDENTIAL_LTPA);

5. Launch the browser using the single sign-on LTPA token you retrieved.

// launch the WCT browser

ILaunchBrowser launchBrowser =

LaunchBrowserFactory.getBrowserInstance();

launchBrowser.launch(launchContext);

} catch (LoginException ex) {

MessageDialog.openWarning(null, "SSO Browser Login", ex.getMessage());

SamplesPlugin.getLogger().log(Level.SEVERE, "", ex);

} catch (IllegalStateException ex) {

MessageDialog.openWarning(null, "SSO Browser Login", ex.getMessage());

SamplesPlugin.getLogger().log(Level.WARNING, "", ex);




}

}

}

Related tasks


“Logging in to an HTTP authenticated application” on page 72

Action bars

The client action bar uses the IActionBarWidgetManager interface, provided by the

com.ibm.rcp.ui.widgets.api code that ships with the toolkit. The

IActionBarWidgetManager interface instantiates an ActionBarWidgetManager object

that is modeled after the Eclipse ActionBarManager class and implements a menu

that looks like a Microsoft Windows menu. The toolbar is represented in the client

user interface as an SWT-based CoolBar control, containing a single ToolBar child

control.

You can incorporate existing Eclipse action bars or action items into a client

application’s user interface. One of the createActionBar() methods available in the

IActionBarWidgetManager interface enables you to pass in an Eclipse toolbar that

you already created to serve as the action bar. You can also use the

createActionBarItem() method to add a standard JFace-based action that you

created using the Eclipse org.eclipse.jface.action.IAction interface to the client

action bar.

Action bar customization

The WidgetFactory class enables you to determine the look and feel of the action

bar by specifying a style parameter with the createActionBar() method. If you do

not specify a style, the SWT.NONE style is applied by default. You can determine

the look and feel of the action bar buttons using the setCustomRenderer() method

of the IActionBarWidgetItem interface. The ActionBarWidgetManager consults the

IActionBarWidgetItem interface when populating the SWT ToolBar with Items that

represent the actions. The ActionBarWidgetManager uses the setControl(Control

control) method of ToolItem to allow ToolItems to be realized as arbitrary SWT

controls.

The com.ibm.rcp.ui.widgets.api code enables you to create your own custom look

and feel for the client action bar and buttons. The ICustomActionBarRenderer

interface provides this API. You can define your own custom renderer or you can

implement one of the following implementations of ICustomActionBarRenderer

which are provided with the toolkit:

v RoundedButtonRenderer -- Implement it using the setRoundedButtonRenderer()

method of IActionBarWidgetManager.

v FlatButtonRenderer -- Implement it using the setFlatButtonRenderer() method of

IActionBarWidgetManager.

Both implementations use the CButtonWidget control. They apply different styles

to the CButtonWidget control to change the appearance of the IAction object

depending on which renderer is used. The text and image of the IAction object are

applied to the CButtonWidget object through the setText() and setImage() methods.

You can make the CButtonWidget appear rounded by applying the setRounded()

method to it.

Related concepts

60 User’s Guide

Chapter 4, “Developing the application user interface,” on page 49 Related tasks

“Creating an action bar”

“Adding custom buttons to an action bar” on page 62

Creating an action bar

You must create a view or perspective to associate an action bar with before you

can create an action bar.

To create an action bar:

1. In the plugin.xml file for the view or perspective you are creating, import the

com.ibm.rcp.ui.widgets plug-in.

<requires>

...

<import plugin="com.ibm.rcp.ui.widgets"/>

</requires>

2. In the code, import the WidgetFactory and IActionBarWidgetManager interface

which enables you to implement one of the following customized buttons:

v RoundedButtonRenderer -- Implements a rectangular button with rounded

corners.

v FlatButtonRenderer -- Implements a control that looks similar to HTML hot

link text, rather than a button.import com.ibm.rcp.ui.widgets.api.WidgetFactory;

import com.ibm.rcp.ui.widgets.api.jface.IActionBarWidgetManager;

3. Create the actions and the action bar group.

public class WidgetsView extends ViewPart {

private IAction

action1,

action2,

action3,

action4;


parent.setLayout(new GridLayout());

makeActions();

createActionBarGroup(parent);

4. Instantiate the action bar group you are going to pass to the

ActionBarWidgetManager.

private void createActionBarGroup(Composite parent) {

// widget group

Group group = new Group(parent, SWT.NONE);

group.setText("WCT Action Bar");

FillLayout layout = new FillLayout();



group.setLayout(layout);

5. Instantiate the ActionBarWidgetManager object.

IActionBarWidgetManager manager =

WidgetFactory.createActionBar(group, SWT.RIGHT | SWT.FLAT);

6. Optional: Change the look of the buttons to be rounded.

manager.setRoundedButtonRenderer();

7. Optional: Set the spacing between each button.

manager.setSpaceWidth(2);

8. Optional: Set the background color.


manager.setControlBackground(

Display.getCurrent().getSystemColor(SWT.COLOR_WHITE));

9. Add the actions to the action bar.

// add actions

manager.add(action1);




Use the ICustomActionBarRenderer interface to implement your own custom

action bar and use the setCustomRenderer() method of IActionBarWidgetManager

to add the buttons to the action bar.

Related concepts

“Action bars” on page 60 Related tasks

“Creating a view plug-in” on page 13

“Creating a perspective” on page 14

Adding custom buttons to an action bar

Using the API included in the com.ibm.rcp.ui.widgets plug-in, you can customize

the buttons that display in an action bar.

To add a custom button to an action bar:

1. Complete the steps for creating an action bar. Then edit the code to include this

import statement:

import com.ibm.rcp.ui.widgets.api.swt.CButtonWidget;

2. Create a button group to add to the action bar:

private void createButtonGroup(Composite parent) {

// widget group


group.setText("WCT Custom Button");

RowLayout layout = new RowLayout();



group.setLayout(layout);

3. Use the CButtonWidget class to create a custom button with an image only.

// create buttons

CButtonWidget button = WidgetFactory.createCbutton(group, SWT.NONE);

button.setImage(PlatformUI.getWorkbench().getSharedImages().

getImage(ISharedImages.IMG_OBJ_ELEMENT));

button.setToolTipText("CButton with image");

button.addSelectionListener(new SelectionListener() {

public void widgetSelected(SelectionEvent event) {

action1.run();

}

public void widgetDefaultSelected(SelectionEvent arg0) {

}

});

4. To add text to the button, include this code in after you instantiate the button:

button.setText("CButton with image and text");

5. If you want the button to appear rounded, include this code:

button.setRounded(true);

6. Force a repaint of the button to see these changes.

Related concepts

62 User’s Guide

“Action bars” on page 60

Adding editing functionality to an application

You can use the rich text editor API provided in the com.ibm.rcp.rte plug-in to

create an editable rich text field in the view of the application you are building.

To create an editable rich text field:

1. Import the com.ibm.rcp.rte plug-in by including it in the <requires> section of

the plugin.xml file. The following example code includes the rich text editor

API plug-in in the plugin.xml file:

<requires>

...

<import plugin="com.ibm.rcp.rte"/>

</requires>

2. In the class that creates the field, import the API package. The following

example Java code imports the rich text editor API package:

import com.ibm.rcp.rte.api.RteControl;

3. Implement an instance of the RteControl class and exercise its methods, such as

the setReadOnly(), setFontBold(), setFontItalic(), and setFontSize(fontSize)

methods in your code. The following example code implements an instance of

the RteControl:

public class RichTextWidget extends Composite {

private RichTextWidgetToolBar bar;

public RichTextWidget(Composite parent, int rteStyle) {

super(parent, SWT.NONE);

GridLayout layout = new GridLayout(1, false);



layout.verticalSpacing = 0;

setLayout(layout);

// add components

bar = new RichTextWidgetToolBar(this, SWT.NONE);

rte = new RteControl(this, rteStyle, false, 0);

rte.setLayoutData(new GridData(GridData.FILL_BOTH));

bar.setRte(rte);

}

}

4. You can instantiate this RichTextWidget in another class, as follows:

import com.ibm.rcp.ui.widgets.api.WidgetFactory;

import com.ibm.rcp.ui.widgets.api.jface.IActionBarWidgetManager;

import com.ibm.workplace.samples.api.widgets.rte.RichTextWidget;


parent.setLayout(new GridLayout());

makeActions();

createActionBarGroup(parent);

createRichTextGroup(parent);

}

private void createRichTextGroup(Composite parent) {


group.setText("WCT Rich Text Editor");

group.setLayout(new FillLayout());

group.setLayoutData(new GridData(GridData.FILL_BOTH));

RichTextWidget rte = new RichTextWidget(group, SWT.NONE);

}

Related concepts



Contributing to a menu

You can write code that performs a task by creating a menu item contribution. You

can enable users to start the task from a corresponding menu item in the user

interface by adding the menu item contribution to an existing menu. You must

contribute at least a File, Edit, and Window menu using Java code. See the Eclipse

SDK Help for information on contributing global menu item contributions.

You can add a menu item to a global menu using the org.eclipse.ui.actionSets

extension point. You can also associate a new action set to a specific view to ensure

that the menu contributions defined in the action set appear in the user interface

whenever the specified view is active using the

org.eclipse.ui.actionSetPartAssociation extension point. See the Eclipse SDK Help

for more information on part associations. The plugin.xml file for the Call Center

core sample application also provides an example.

Note: By default, your menu item contribution is displayed in the menu only

when the view it is associated with is active. However, you can set a menu

contribution to display always by setting the ″visible″ attribute in the

actionSet tag to ″true.″

To contribute to a menu:

1. In the plugin.xml file, extend the actionSets extension point, specifying menu

elements that define which menu items to add your action contribution to. The

following code demonstrates how to contribute an Open Database menu item

contribution to the File → New → Database menu.

<extension point="org.eclipse.ui.actionSets">

<actionSet

label="NotesActions"

visible="false"

id="com.ibm.workplace.notes.menus.actionSet">

<menu

label="%xstr.com.ibm.workplace.notes.menus.database"

path="file/fileNewGroup"

id="com.ibm.workplace.notes.menus.database">

<separator

name="filemenuDatabaseGroup">

</separator>

</menu>

2. Add an action element after the menu element. In the class attribute for the

action element, identify the Java class to run when the user clicks the menu

option that you define in the menubarPath attribute.

<action

label="%xstr.com.ibm.workplace.notes.menus.database.open"

class="com.ibm.workplace.notes.menus.actions.OpenDatabaseAction"

menubarPath=

"file/com.ibm.workplace.notes.menus.database/filemenuDatabaseGroup"

id="com.ibm.workplace.notes.menus.database.open">

</action>

</actionSet>

</extension>

Related concepts


64 User’s Guide

Implementing keyboard shortcuts

Keyboard shortcuts are combinations of keys, such as Ctrl + V, that initiate the

same actions as a menu option or button.

To implement a keyboard shortcut:

In the plugin.xml file for the plug-in that defines the action you want to create a

shortcut for, include an ″accelerator″ attribute. For example, the action tag below is

included in the actionSets extension point definition and defines ″Ctrl+V″ as the

keyboard shortcut for a paste action.

<action

accelerator="Ctrl+V"

label="%str.ae.client.contextmenu.menuitem.paste"

class="com.ibm.workplace.ae.client.actions.AEMenuDelegate"

menubarPath="com.ibm.rcp.ui.actionsmenu/activity/activityGroup3"

tooltip="context_paste"

id="com.ibm.workplace.ae.client.actions.paste">

</action>

Related concepts


Implementing preference pages

The rich client provides a preferences interface and implementation to store and

provide preferences for individual plug-ins. The client’s preference store is based

on the Eclipse implementation of the preference store. The

org.eclipse.core.runtime.preferences package provides infrastructure for storing a

plug-in’s preferences. Preferences map to settings controlled by the user on the

Workbench Preferences page. Plug-in preferences are key and value pairs, where

the key describes the name of the preference, and the value is one of several

different types, including boolean, double, float, int, long, and string. The Eclipse

platform provides support for storing plug-in preferences and showing them to the

user on pages in the Workbench Preferences dialog box.

The client extends the basic Eclipse implementation by providing a separate

workspace, where preference files are stored for each machine user, thus providing

a method for enabling individual machine users to maintain their own preference

settings. One instance of this local preference store is provided by each active

plug-in, and provides an effective preference storage and retrieval mechanism for

storing user preferences on the client.

To implement a preference page:

1. Add a preferences menu item to the menu if one is not already defined. Define

an action to trigger the Preferences dialog box.

<action

label="%Menu.path.preferences"

tooltip="%Menu.path.preferences.tooltip"

class="com.ibm.rcp.<your component’s name>.actions.<youraction>"

menubarPath="yourmenu/YourMenuGroup"

toolbarPath="YourMenuGroup"

id="com.ibm.rcp.<your component’s name>.actions.preferences">

</action>

2. Call the PreferenceManager by adding the following code to the source code

for the component’s actions class:


package com.ibm.rcp.<your component’s name>.actions;

[Import statements]

public class MyActions implements IWorkbenchWindowActionDelegate {

private IWorkbenchWindow window;

private IWorkbench workbench;

/**

* The constructor:

*/

public MyActions() {

}

public void run(IAction action) {

String id = action.getId();

if (id.equals("com.ibm.rcp.<your component’s name>.actions.exit"))

workbench.close();

else if (id.equals

("com.ibm.rcp.<your component’s name>.actions.preferences")) {

PreferenceManager pm = workbench.getPreferenceManager();

if (pm != null) {

PreferenceDialog d =

new PreferenceDialog(window.getShell(), pm);

d.create();

d.open();

}

}

}

...

}

3. Add the content of the preference page itself by extending the

org.eclipse.ui.preferencePages extension point in your plug-in’s plugin.xml

deployment descriptor file. The following code is an example:

<extension point="org.eclipse.ui.preferencePages">

<page

name="%MyPrefPage"

class="com.ibm.rcp.my.preferences.UpdatePreferencePage"

id="com.ibm.rcp.my.preferencePages.Update">

</page>

</extension>

4. In the source code for the com.ibm.rcp.my.preferences.UpdatePreferencePage

class identified above, specify what is displayed on the preference page. The

following code defines a single field:

public class UpdatePreferencePage

extends FieldEditorPreferencePage

implements IWorkbenchPreferencePage, UpdatePreferenceConstants,

IPropertyChangeListener {

private UpdateButtonEditor updateCheckEnabled = null;

...

/**

* constructs a UpdatePreferencePage with GRID layout by default.

* Sets default preferences in preferences store

*

*/

public UpdatePreferencePage() {

super(GRID);

// Set the preference store for the preference page.

IPreferenceStore store =

UpdateUIPlugin.getDefault().getPreferenceStore();

setPreferenceStore(store);

setDescription(UpdateUIPlugin.getString

(UPDATE_PREFERENCES_DESCRIPTION_KEY));

getPreferenceStore().addPropertyChangeListener(this) ;

}

protected void createFieldEditors() {

Composite parent = getFieldEditorParent();

//int span = ((GridLayout)parent.getLayout()).numColumns;

66 User’s Guide

int span = 2;

// Initialize all field editors.

updateCheckEnabled = new UpdateButtonEditor(

AUTO_UPDATE_ENABLED, resource(AUTO_UPDATE_ENABLED_LABEL_KEY),

parent);

addField(updateCheckEnabled);

/**

* enables/disables field editors based on current conditions.

*/

private void refreshFieldEditors(){

boolean enabled = updateCheckEnabled.getBooleanValue();

Composite parent = getFieldEditorParent();

boolean allFeaturesEnabled = updateAllFeaturesEnabled.getBooleanValue();

updateMethod.setEnabled(enabled, parent);

updateAllFeaturesEnabled.setEnabled(enabled, allFeatureComposite);

if(enabled)

checkPeriod.setEnabled(allFeaturesEnabled, allFeatureComposite);

else

checkPeriod.setEnabled(enabled, allFeatureComposite);

Enumeration enum = featuresCollection.elements();

while(enum.hasMoreElements()){

UpdateButtonEditor fieldEdA = (UpdateButtonEditor)enum.nextElement();

if(enabled)

fieldEdA.setEnabled(!allFeaturesEnabled, compositeToScroll);

else

fieldEdA.setEnabled(enabled, compositeToScroll);

}

Enumeration enumCheckPeriod = featuresCheckPeriodCollection.elements();

while(enumCheckPeriod.hasMoreElements()){

IntegerFieldEditor fieldEdB =

(IntegerFieldEditor)enumCheckPeriod.nextElement();

if(enabled)

fieldEdB.setEnabled(!allFeaturesEnabled, compositeToScroll);

else

fieldEdB.setEnabled(enabled, compositeToScroll);

}

allFeatureComposite.setSize

(allFeatureComposite.computeSize(SWT.DEFAULT,SWT.DEFAULT));

allFeatureComposite.layout();

compositeToScroll.setSize(compositeToScroll.computeSize

(SWT.DEFAULT,SWT.DEFAULT));

compositeToScroll.layout();

parent.layout();

}

/**

* initialize the preference page’s contents

*/

protected void initialize(){

super.initialize();

refreshFieldEditors();

}

/**

* Notification that a property has changed.

* <p>

* This method gets called when the observed object fires a property

* change event.

* </p>

*

* @param event the property change event object describing which property

* changed and how

*/

public void propertyChange(PropertyChangeEvent event){

Object source = event.getSource();

if( source.equals(updateCheckEnabled) || source.equals

(updateAllFeaturesEnabled)){



}

else{

if(source instanceof UpdateButtonEditor)

refreshFieldEditor(source);

}

}

/**

* calculates the default preference values and refreshes the field editors

*/

protected void performDefaults(){

UpdateUIPlugin.getDefault().initializeDefaultPreferences

(getPreferenceStore());

super.performDefaults();


}

/**

* @param workbench reference to the Workbench

*/

public void init(IWorkbench workbench) {

}

}

See the Platform Plug-in Developer Guide in the Eclipse SDK Help for more

information on the Eclipse Preferences API.

Related concepts

“Call center preference pages” on page 112

68 User’s Guide

Chapter 5. Securing a client application

The IBM Workplace Client Technology platform is a secure platform that protects

your application data. Single sign-on with the operating system capabilities are

built into the rich client by default.

You must do some additional coding work to take advantage of the following

client security features:

v “Logging in to the local credential store”

v “Logging in to an HTTP authenticated application” on page 72

v “Defining access control levels” on page 26

Related concepts

“Single sign-on with the operating system” on page 74

“IBM Workplace local credential store”

“HTTP authentication support” on page 72

IBM Workplace local credential store

IBM Workplace rich client products use the local credential store to store user

name and password credentials. 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, making it particularly suitable for sensitive credentials, such as

S/MIME signing keys. Desktop clients access the local credential store by

decrypting the store with the password supplied by the user at signon. The

following steps are performed by the client to initially establish trust in the user:

v After IBM Workplace is installed, users are prompted for the IBM Workplace

user name and password when they start a rich client product. The IBM

Workplace user name and password are the same user name and password that

users provide to authenticate with the WebSphere Application Server. When the

user name and password are verified, IBM Workplace creates a local credential

store.

v IBM Workplace uses the password supplied by the user to compose a 3DES key

to encrypt the newly created credential store file. 3DES is a mode of the DES

encryption algorithm that encrypts data three times, using three 64-bit keys.

v IBM Workplace then populates the local credential store with its first credential,

the WebSphere Application Server user name and password just supplied by the

user. Related concepts

Chapter 5, “Securing a client application” Related tasks

“Logging in to the local credential store”

Logging in to the local credential store

The security API provided in the com.ibm.rcp.security plug-in enables you to log

in to the local credential store programmatically.

To log in to the local credential store programmatically:

1. Import the following supporting packages:


...

import com.ibm.rcp.security.api.cred.login.ICredentialStoreLoginContext;

import com.ibm.rcp.security.api.cred.login.ICredentialStoreLoginContextFactory;

...

2. Log in to the credential store using the ICredentialStoreLoginContext.login()

method:

public class MyCredentialStore {

private CredentialStore m_credStore = null;

public MyCredentialStore( String name) {

super( name);

}

protected void setUp( ) {

try {

m_credStore = CredentialStoreFactory.getCredentialStore( );

ICredentialStoreLoginContext loginContext =

ICredentialStoreLoginContextFactory.INSTANCE.create( );

loginContext.login( getTestLoginCallback( ), new Properties( ));

assertNotNull( "Credential Store is null!", m_credStore);

}

catch ( Exception e) {

fail( e.getMessage( ));

}

}

private CallbackHandler getTestLoginCallback( ) {

CallbackHandler callbackHandler = new CallbackHandler( ) {

public void handle( Callback[] cb)

throws IOException, UnsupportedCallbackException {

for ( int i=0;i<cb.length;i++) {

if ( cb[i] instanceof PasswordCallback) {

((PasswordCallback)cb[i]).setPassword(

"wpsadmin".toCharArray( ));

}

}

}

};

return callbackHandler;

}

Related concepts

“IBM Workplace local credential store” on page 69

“Password credentials” Related tasks


“Creating a password credential” on page 71

Password credentials

Using the com.ibm.rcp.security.core plug-in, you can programmatically create

password credentials for authenticating to remote servers. The

com.ibm.rcp.security.api.cred code currently supports the creation of password

credentials only. The CertificateCredential class is included in the plug-in, but you

cannot currently use it. You use the CredentialManagerFactory to implement a

CredentialManager, which creates an HTTP authentication credential. You use an

HTTP authentication credential to authenticate to a specific realm. A realm defines

a collection of servers that partition their protected resources into a set of

protection spaces, each with its own authentication scheme. See

http://www.faqs.org/rfcs/rfc2617.html for details on HTTP authentication. This

form of authentication is often used in Web applications and for securing Web

services.

Related tasks


70 User’s Guide

Creating a password credential

You can programmatically create password credentials for authenticating to remote

servers. When you create a password credential for a remote server, the user is

prompted to supply a user name and password the first time the user accesses the

remote server, but on subsequent use, the client platform provides this credential

to the remote server by retrieving it from the credential store. Creating credentials

prevents the user from being repeatedly prompted for authentication information.

Note: User names and passwords stored in the local credential store are not fully

secure. After it is unlocked, the local credential store can be accessed by any

client plug-in. There is currently no way to sign plug-ins to verify that the

plug-in author is trusted.

To create a password credential for a remote server:

1. Include the security plug-in in the plugin.xml file for the plug-in you are

creating that uses the security code.

<requires>

...

<import plugin="com.ibm.rcp.security.core"/>

</requires>

2. Import the packages containing the credential code into your code.

...

import com.ibm.rcp.security.api.cred.login.ICredentialStoreLoginContext;

import com.ibm.rcp.security.api.cred.login.ICredentialStoreLoginContextFactory;

import com.ibm.rcp.security.api.cred.ICredential;

import com.ibm.rcp.security.api.cred.IPasswordCredential;

...

3. Log in to the credential store using the login() method:

public class MyCredentialStore {

private CredentialStore m_credStore = null;

public MyCredentialStore( String name) {

super( name);

}

protected void setUp( ) {

try {

m_credStore = CredentialStoreFactory.getCredentialStore( );

ICredentialStoreLoginContext loginContext =

ICredentialStoreLoginContextFactory.INSTANCE.create( );

loginContext.login( getTestLoginCallback( ), new Properties( ));

assertNotNull( "Credential Store is null!", m_credStore);

}



}

}






if ( cb[i] instanceof PasswordCallback) {



}

}

}

};


}


4. Create a password credential using the

IHttpCredentialManager.createPassword() method.

public void createMyPasswordCredential( ) {

try {

final String theUsername = "username";

final String thePassword = "password";

CallbackHandler callbackHandler =

getCreationCallback( theUsername, thePassword);

IPasswordCredential cred =

m_credStore.getHttpCredentialManager().

createPassword( new URL("http://authenticationHost.com"),

"AuthRealm", new URL[] {new URL("ibm.com")},

CredentialStore.SCOPE_LOCAL, callbackHandler);

assertEquals( "Input username does not equal input username!",

theUsername, cred.getUsername( ));

assertEquals( "Output password does not equal input password!",

thePassword, new String(cred.getPassword( )));

cred.remove( );

}



}

}

Related tasks


HTTP authentication support

Rich client products use form-based authentication to authenticate with the IBM

Workplace server over HTTP. Form-based authentication uses a custom login form

supplied by the application to collect a user name and password. When a user

supplies a user name and password to log into an IBM Workplace client product,

IBM Workplace passes the user name and password to the WebSphere Application

Server’s user registry to be matched with information stored there. If the user

name and password supplied fail to match the information stored in the user

registry, the login form is redisplayed. If users manually enter an HTTP request for

an IBM Workplace resource, they are redirected to the login form. Users must enter

a valid user name and password before they can access any IBM Workplace system

resources.

Related concepts

Chapter 5, “Securing a client application,” on page 69 Related tasks

“Logging in to an HTTP authenticated application”

Logging in to an HTTP authenticated application

Communication between the client and IBM Workplace server is authenticated

automatically. The security APIs provided with the com.ibm.rcp.security.core

plug-in enable you to log in to an alternate HTTP authenticated application

programmatically.

To log in to an HTTP authenticated application programmatically, perform the

following steps:

1. Import the following supporting packages:

72 User’s Guide

...

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;

...

2. Log in to an HTTP form-based application using the login() method:

protected void loginTry( ) {

IHttpFormLoginContext loginContext =

IHttpFormLoginContextFactory.INSTANCE.create( );

assertNotNull( "HttpFormLoginContext is null!", loginContext);

try {

loginContext.login( "sales.devsite.acme.com",

IHttpFormLoginContext.PORT_UNSPECIFIED, null, false,

getTestLoginCallback( ), null);

}


e.printStackTrace( );

fail( "Could not login: " + e.getMessage( ));

}

}






if ( cb[i] instanceof NameCallback) {

((NameCallback)cb[i]).setName( "wpsadmin");

}

else if ( cb[i] instanceof PasswordCallback) {



}

else if ( cb[i] instanceof LtpaCookieCallback) {

//IGNORE

}

else {

throw new UnsupportedCallbackException( cb[i]);

}

}

)

};


}

3. Retrieve the LTPA token from the authenticated HTTP login context using the

getCredentialCookie() method. This returns the LTPA token encoded as a

cookie, which the browser can store in the HTTP cookie cache:

protected void getLtpaCookieTry( ) {

IHttpFormLoginContext loginContext =

IHttpFormLoginContextFactory.INSTANCE.create( );

assertNotNull( "HttpFormLoginContext is null!", loginContext);

try {

loginContext.login( "sales.devsite.acme.com",

IHttpFormLoginContext.PORT_UNSPECIFIED, null, false,


Cookie ltpaCookie =

loginContext.getCredentialCookie(IHttpFormLoginContext.CREDENTIAL_LTPA);

assertNotNull( "LTPA cookie is null", ltpaCookie);

String ltpaData = ltpaCookie.getValue( );

assertNotNull( "LTPA data is null");

Date expiryDate = ltpaCookie.getExpiryDate( );

assertNotNull( "LTPA expiration is null!", expiryDate);

}





}

}

Related concepts

“HTTP authentication support” on page 72 Related tasks

“Accessing a Web address using an LTPA token” on page 57

Single sign-on with the operating system

Configuring the client to provide single sign-on (SSO) with the operating system

enables a user, who has successfully logged into the operating system, to access

resources protected by the client without having to reauthenticate. The rich client

stores security-related information, such as authentication credentials (passwords),

keys, and certificates in the local credential store. When SSO with the operating

system is enabled, the client checks the user name and password information that

a user provides to log into the operating system against the user name and

password information stored in the local credential store. If the two match, the

client grants access to secure client resources without prompting the user to

provide credentials a second time. Single sign-on with the operating system for

rich client products is supported on the following operating systems:

v Microsoft Windows 2000 Professional with Service Pack 2

v Microsoft Windows XP with Service Pack 1

v Red Hat Enterprise Linux WS 3.0 with Update 3; Kernel: 2.4.2.21-27.0.2″;

Compiler: gcc 3.2, glibc 2.3.2; desktop environment: GNOME

Related concepts


“Configuring Microsoft Windows operating system single sign-on”

“Configuring Linux operating system single sign-on” on page 75

Configuring Microsoft Windows operating system single

sign-on

Before you set up your Microsoft Windows operating system to authenticate the

client at login:

v Ensure that the user name and password credentials for the Microsoft Windows

2000 or Microsoft XP operating system are the same as the user name and

password credentials for the local credential store.

v Make sure you have sufficient access permissions to modify the Windows

registry and add services to the system.

To configure the client for single sign-on with Microsoft Windows, perform the

following tasks.

1. Make sure that the user has installed the rich client.

2. Navigate to the following directory:

<CLIENT_HOME\rcp\eclipse\features\

com.ibm.rcp.security.sso.win32.feature_1.2.0\os\win32\x86

3. Run the ssoinstall.cmd file and then restart the system.

74 User’s Guide

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

Related concepts


Configuring Linux operating system single sign-on

Before you set up your Linux operating system to authenticate the client at log in:

v Ensure that the user name and password credentials for the Linux operating

system users are the same as their user name and password credentials for the

local credential store.

v Make sure you have root privileges allowing you to install and configure

modules.

When you install this feature, you are installing system-level components to the

Linux operating system that can detect logins and securely communicate with the

client. The instructions assume you have some understanding of Linux System

Administration and Linux Security Administration, especially the configuration of

PAM (Pluggable Authentication Modules). See the Linux-PAM System

Administrator’s Guide (http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/pam.html#toc4) for related information.

Note: The rich client single sign-on feature is not intended for use with the root

user ID. The rich client single sign-on PAM module and the rich client single

sign-on daemon ignore login requests from the root user ID.

To configure the client for single sign-on with Linux, perform the following tasks.

1. Make sure that the user has installed the rich client.

2. In a Linux shell, log in as or switch user (su) to root.

3. Navigate to the following directory:

<client_home>/rcp/eclipse/feature/

com.ibm.rcp.security.sso.win32.feature/os/linux/x86

4. Run the installsso script to copy several components to the appropriate system

directories.

5. Navigate to /etc/pam.d to modify the system’s PAM configuration to add the

rich client’s PAM module to the appropriate system files.

6. Add the statements in bold shown in the sample below to either the gdm or

the xdm PAM configuration file.

v If the system is using the GNOME window manager, edit the gdm file. If the

system is using the KDE window manager, edit the xdm file.

Note: If in doubt, edit both files.

v See the Linux-PAM System Administrator’s Guide for more details on file

format and content.The following is a sample /etc/pam.d/gdm file:

#%PAM-1.0auth required pam_unix2.so nullok #set_secrpc

auth required pam_rcpsso.so debug

account required pam_unix2.so

password required pam_unix2.so #strict=false


password required pam_rcpsso.so debug

session required pam_unix2.so debug # trace or none

session required pam_devperm.so

session required pam_resmgr.so

session required pam_rcpsso.so debug

Add the following line to the password file.

password required pam_rcpsso.s debug

7. Restart the system.

Related concepts


76 User’s Guide

Chapter 6. Calling a remote Enterprise JavaBean

The IBM Workplace Client Technology platform provides the ability to call remote

Enterprise JavaBeans™ (EJBs) from within a client application. Remote EJBs

encapsulate business tasks that rely on server-based resources. They can be used

by one or more applications. The use of EJBs promotes code reuse by allowing

developers to write business logic code that can be used from both client and

server-based applications. For example, you can call a remote EJB to request the

synchronization of data in a database hosted by the server with that of a database

hosted by the client.

You can implement and call a remote EJB by completing these tasks:

1. “Building a deployable remote Enterprise JavaBean”

2. “Installing an Enterprise JavaBean”

3. “Starting the remote Enterprise JavaBean” on page 78

4. “Calling a remote Enterprise JavaBean” on page 78

Building a deployable remote Enterprise JavaBean

Use the Rational Application Developer tool or another Java development tool to

write the Enterprise JavaBean (EJB) code. Be sure to include an interface for calling

the EJB remotely. You must use Rational Application Developer or the Application

Assembly Toolkit (AAT) provided with the WebSphere Application Server to

package the EJB JAR files as an EAR file. Only EAR files can be deployed on the

WebSphere Application Server.

To generate an EAR file for one or more remote EJBs:

1. In Rational Application Developer, create an EJB EAR project that contains the

EJB projects for the one or more EJBs you created. Rational Application

Developer creates an application.xml file to define the EJBs in the EJB EAR

project.

2. Open the EJB Deployment Descriptor for your EJBs and ensure that the correct

JNDI name is displayed for each in the JNDI name field.

3. Validate the EJB code by right-clicking the EJB EAR project and its

corresponding EJB projects and selecting Run Validation.

4. Generate the deployable code by right-clicking the EJB EAR project and

selecting Generate Deployment Code.

5. Export the EJB EAR project as an EAR file to a directory on your machine from

which you can subsequently retrieve it.

Installing an Enterprise JavaBean

You must install the EJB on the WebSphere Portal server for the client application

to be able to call it remotely.

To install an EJB in WebSphere Portal:

1. Log in to the WebSphere Administrative Console as an administrator.

2. Click Applications → Install New Application.


3. Select Local path and type the path name to the EAR file you exported from

Rational Application Developer, and then click Next. For example, for the Call

Center application, select a local copy of the rcp.callCenterappSvc.ear file

(copied from the \samples\deploy\ear subdirectory of the toolkit).

4. Select Generate Default Bindings, and then click Next.

5. On the Provide options to perform the installation page, provide an

application name in the Application Name field, and then select any options

for preparing or installing the EJB that you want to apply. Click Next. For the

Call Center application, type Call Center Services.

6. From the Promote JNDI Names for Beans page, verify that the correct JNDI

name is displayed in the JNDI Name field, and then click Next. For the Call

Center application, the JNDI Name fields should contain the following names:

v ejb/ejbModule/com/ibm/rcp/demo/callcenter/hashmap/ejb/

HashmapEjbServiceHome

v ejb/ejbModule/com/ibm/rcp/demo/callcenter/cloudscape/ejb/

CloudscapeEjbServiceHome 7. On the Map modules to application servers page, from the Clusters and

Servers list, select

WebSphere:cell=<yourserverroot>,node=<yourserverroot>,server=WebSphere_Portal.

Choose your EJB file from the Module list, and then click Apply. For

example, for the Call Center application, select the following modules:

v com.ibm.rcp.demo.callcenter.ejb.cloudscape

v com.ibm.rcp.demo.callcenter.ejb.hashmap 8. On the same page, verify that the server that is displayed in the Server

column for your EJB file module is WebSphere Portal, and then click Next.

9. Click Next on the page entitled Step 4 and click Finish on the page entitled

Step 5 to accept the defaults.

10. Click Save to Master Configuration.

11. After the Application Call Center EJB Services install successfully, click Save to

update the master configuration.

Starting the remote Enterprise JavaBean

After you install the remote Enterprise JavaBeans (EJBs) on the server, you must

start them before a client application can access them.

To start a remote EJB:

1. From the WebSphere Administrative Console, select Applications → Enterprise

Applications.

2. Select the EJBs that you installed on WebSphere Portal from the list, and click

Start to run them. For example, when the Call Center Services are running, a

green arrow icon is displayed next to Call Center Services.

You can now call the EJB from the client application.

Calling a remote Enterprise JavaBean

You use a factory class to call a remote service. The factory classes provided with

the Call Center application, for example, locate the EJBs on the server, and then

cast them to an ITicketsService, which is the service interface the Call Center uses

to communicate with the ticket stores.

78 User’s Guide

Note: Due to limitations in the current API, the code that accesses the remote EJBs

in the Call Center sample application is somewhat basic and does not

support advanced security and clustering features enjoyed by some of the

workplace applications.

To call a remote EJB:

1. Specify the platform plug-in as a required plug-ins in the plugin.xml file for the

plug-in you write to call the remote EJB service. The following code provides

an example:

<requires>

...

<import plugin="com.ibm.rcp.platform"/>

...

</requires>

Note: The com.ibm.rcp.websphere.runtime and com.ibm.rcp.services.locator

plug-ins are internal client plug-ins that contains some basic Java

libraries that support code compilation.

2. Import the PlatformContext API by including the following line of code in the

class you write that calls the service:


3. Perform a JNDI call to call the remote EJB service. The following code from the

Call Center application’s HashmapEjbServiceFactory.java class provides an

example:

static private Log log =

LogFactory.getLog(HashMapEJBServiceFactory.class);

public ITicketsService createService() throws Exception {

log.debug("Looking up Hashmap EJB");

// Changes the Context classloader so that it can load

// the InitialContext factory.

Thread thread = Thread.currentThread();

ClassLoader cl = thread.getContextClassLoader();

HashmapEjbService ejb;

try{

thread.setContextClassLoader(CallCenterPlugin.

getDefault().getClass().getClassLoader());

Hashtable newEnv = new Hashtable();

newEnv.put(Context.INITIAL_CONTEXT_FACTORY,

"com.ibm.websphere.naming.WsnInitialContextFactory");

newEnv.put(Context.PROVIDER_URL, "iiop://" +

PlatformContext.getJNDIHostName() + ":" +

PlatformContext.getJNDIPort());

Context ic = new InitialContext(newEnv);

Object obj = ic.lookup("ejb/ejbModule/com/ibm/rcp/demo/

callcenter/hashmap/ejb/HashmapEjbServiceHome");

HashmapEjbServiceHome home =

(HashmapEjbServiceHome)PortableRemoteObject.

narrow(obj, HashmapEjbServiceHome.class);

ejb = home.create();

} finally {

// Reset to default context class loader

thread.setContextClassLoader(cl);

}

log.debug("Found Hashmap EJB");

return (ITicketsService)ejb;

Chapter 6. Calling a remote Enterprise JavaBean 79

80 User’s Guide

Chapter 7. Synchronizing client application data

You can enable a client application to synchronize data between a data store

running on the client and a secondary data store or HashMap, also running on the

client or running on the server. The IBM Workplace Client Technology platform

provides extensions for synchronizing the data of an offline store. The supported

client-side data stores are Cloudscape™ and IBM DB2® Everyplace. The supported

synchronization engines are engines built using a standard protocol, like SyncML,

as well as custom engines, like the Portal Document Manager (PDM) and the DB2

Everyplace Synchronization client (iSync). The synchronization framework also

supports calls to remote EJBs running on the server. The client provides the

framework to call your code when synchronization is initiated.

The client provides a synchronization framework made up of the following

packages:

v Synchronization Manager API -- A public interface for managing data

synchronization that contains the following interfaces:

– ISynchronizationManager -- Manages data synchronization through one or

more registered synchronization services.

– IReplicaSubscription -- Creates a value object representing a single data store

to be synchronized. Each synchronization service must supply a

service-specific IReplicaSubscription implementation and must supply

mechanisms for creating instances.v 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.

– ISyncService -- An interface implented by a synchronization service or

protocol agent.

The client does not provide the code that handles the synchronization itself. You

must supply the factory or other code that defines the synchronization logic,

including creating service-specific IReplicaSubscription objects representing

individual data stores that can be synchronized using the service. This object

should define service-specific attributes required for the underlying data

synchronization process.

The Synchronization Manager initializes the synchronization of all registered data

stores. You cannot replicate a single data store or document. When you trigger

synchronization, all data stores registered with the Synchronization Manager are

replicated.

The synchronization server on WebSphere Portal only accepts authenticated

connections. A user making a request for data to be synchronized must be logged

in. No other authentication or access control level requirements are built into the

synchronization component of the client. If you want to check who users are and

what access levels they have before they can receive data, you must implement this

logic in your application. When the user logs in and is authenticated, the


authentication restrictions enforced by WebSphere Application Server are applied

to that user. To better secure the data transferred between the client and server,

you should set up the server to use the Secure Sockets Layer (SSL) protocol, and

use SSL when provisioning your client applications.

Related tasks

“Implementing a custom synchronization engine”

“Implementing the DB2 Everyplace Synchronization engine” on page 85 Related reference

“Sync services extension point” on page 85

Implementing a custom synchronization engine

Instruct the client on how to handle your data by providing a protocol agent that

implements the IReplicationService interface. The IReplicationService interface is

included in the com.ibm.rcp.sync plug-in. In the protocol agent, you can define the

behavior specific to the synchronization engine you are using for the methods

specified in the IReplicationService interface. This tells the com.ibm.rcp.sync.api

code how to handle your data.

The ReplicationSubscription object represents a protocol-specific synchronizable

data store and is used by the API to identify what data needs synchronizing. The

existing API defines only those attributes shared by all protocols, so you may have

to implement a ReplicaSubscription class that includes additional attributes

required by the protocol you are using. For example, a ReplicaSubscription class

used to represent objects replicated by the syncML protocol would include a

getTargetURI() method that defines an attribute of the data store that is required

specifically by the SyncML protocol agent.

To add a custom synchronization protocol agent to the platform:

1. Import the com.ibm.rcp.sync plug-in into your plug-in’s plugin.xml file by

using the following tag:

<requires>

...

<import plugin="com.ibm.rcp.sync"/>

</requires>

2. Extend the com.ibm.rcp.sync.syncservices extension point to add a custom

synchronization engine as follows:

<extension point="com.ibm.rcp.sync.syncservices">

<servicefactory

type="unique id to give to this service,

such as com.ibm.workplace.demo.callcenter.lwp.sync.TicketSyncService"

factoryClass=

"com.ibm.workplace.demo.callcenter.lwp.sync.TicketSyncServiceFactory"

id="com.ibm.workplace.demo.callcenter.lwp.sync.TicketSyncService">

</servicefactory>

</extension>

3. Write a factory class that creates your custom synchronization protocol agent by

implementing the SyncServiceFactory interface. Identify the class in the

factoryClass attribute of the replfactory tag for the extension point. The

following is example code for implementing the SyncServiceFactory interface:

/*

* Example SyncServiceFactory

*/

package com.ibm.workplace.demo.callcenter.lwp.sync;

import java.util.logging.Logger;

82 User’s Guide

import com.ibm.rcp.sync.api.exception.SyncException;

import com.ibm.rcp.sync.api.service.ISyncService;

import com.ibm.rcp.sync.api.service.ISyncServiceFactory;

/**

* Implement the ISyncServiceFactory

*/

public class TicketSyncServiceFactory implements ISyncServiceFactory {

/**

* The <code>Log</code> instance for the SyncService

*/

private static Logger logger =

Logger.getLogger(CallCenterSyncManager.class.getPackage().getName());

public ISyncService getSyncService() throws SyncException {

logger.entering(this.getClass().toString(),"");

logger.info("Synchronization starting: Call Center");

return new TicketSyncService();

}

public String getServiceType() {


return TicketSyncService.SERVICE_TYPE;

}

}

4. Implement the ISyncService interface to add replication subscriptions that

identify what data to replicate. In the code you write, define the following

methods:

v getReplicaSubscription()

v sync()

v getSyncStatus()The following is example code taken from the Call Center application that

demonstrates how the sync protocol agent implements the ISyncService

interface. This code uses a CallCenterSyncManager class that is not shown here.

The CallCenterSyncManager class performs the actual synchronization:


...

import com.ibm.rcp.sync.api.data.IReplicaSubscription;

import com.ibm.rcp.sync.api.data.ISyncStatus;

import com.ibm.rcp.sync.api.service.ISyncService;

/**

* Implement SyncService

*/

public class TicketSyncService implements ISyncService {

/**

* The <code>Log</code> instance for the SyncManager

*/

private static Logger logger


private int SYNC_STATE = ISyncStatus.STATUS_IN_PROGRESS;

private CallCenterSyncManager syncMgr = new CallCenterSyncManager();

public static String SERVICE_TYPE =

"com.ibm.workplace.demo.CallCenter.sync.TicketSyncService";

public void addReplicaSubscription(IReplicaSubscription arg0)

throws Exception, RemoteException {


}

public void cancelSync(String arg0) throws Exception,

RemoteException {


}

public void cancelSyncAll() throws Exception, RemoteException {


logger.info("Synchronization cancelled: Call Center");

}

Chapter 7. Synchronizing client application data 83

public void deleteReplicaSubscription(IReplicaSubscription arg0)



}

public String getLastError(String arg0) throws Exception,

RemoteException {


return null;

}

public IReplicaSubscription getReplicaSubscription(String arg0)



return null;

}

public int getSyncStatus(String arg0) throws Exception,

RemoteException {


// TODO return an actual sync status instead of always 0

return 0;

}

public IReplicaSubscription[] getUserReplicaSubscriptions(String arg0)



TicketReplicaSubscription[] repSub = new TicketReplicaSubscription[1];

repSub[0] = new TicketReplicaSubscription(null,null,null,null,null);

return repSub;

}

public void sync(IReplicaSubscription arg0, boolean arg1)

throws Exception,

RemoteException {

// Initialize the sync service


logger.info("Synchronization started: Call Center");

// Initialize the syncManager

// This will perform the custom synchronization

this.syncMgr.init();

logger.info("Synchronization finished: Call Center");

}

public void syncAll(String arg0, String arg1, boolean arg2)



}

public void updateReplicaSubscription(IReplicaSubscription arg0,

boolean arg1)



}

}

5. Create a class that implements the IReplicaSubscription interface to represent

your data store:

/*

* TicketReplicaSubscription

*/


import java.util.logging.Logger;

import com.ibm.rcp.sync.api.data.ReplicaSubscriptionBase;

/**

* Extend the ReplicaSubscriptionBase

*/

public class TicketReplicaSubscription extends ReplicaSubscriptionBase {

/**

* The <code>Log</code> instance for the SyncManager

*/

private static Logger logger =


public TicketReplicaSubscription(String arg0, String arg1, String arg2,

84 User’s Guide

String arg3, String arg4) {

super(arg0, arg1, arg2, arg3, arg4);


}

public String getType() {


return TicketSyncService.SERVICE_TYPE;

}

}

Related concepts

Chapter 7, “Synchronizing client application data,” on page 81

Sync services extension point

The sync services extension point enables you to register external data

synchronization services with the Workplace Synchronization Manager. Each

contribution to the extension point identifies a service factory class that is used by

the Synchronization Manager to create instances of the synchronization service.

Extending the com.ibm.rcp.sync.syncservices extension point

In the plugin.xml file of your synchronization plug-in, provide values for the

following attributes of the <servicefactory> tag:

v id -- Specifies a unique ID for this service.

v name -- Localized name of the synchronization service.

v factoryClass -- Fully qualified name of the Java class that implements a factory

for creating instances of the external synchronization service. This factory class

must implement the com.ibm.rcp.sync.api.service.SyncServiceFactory interface.

v type -- Unique name to represent the service.

The following text is an example of plugin.xml file content that registers a new

synchronization service:

<extension point="com.ibm.rcp.sync.syncservices">

<servicefactory

name=

type="com.ibm.rcp.sync.service.syncml.SyncmlService"

factoryClass="com.ibm.rcp.sync.service.syncml.SyncmlServiceFactory"

id="com.ibm.rcp.sync.service.syncml.SyncmlService">

</servicefactory>

</extension>

Related concepts


Implementing the DB2 Everyplace Synchronization engine

The IBM Workplace Client Technology synchronization framework supports

initializing the synchronization of a DB2 Everyplace Synchronization (ISync) client

application. A rich client user can then start the synchronization of ISync

applications at the same time as mail, calendar, document libraries, and any other

data stores registered with the Synchronization Manager.

See the DB2 Everyplace SDK documentation provided with DB2 Everyplace for

details on building applications and synchronization.

To implement the DB2 Everyplace Synchronization (ISync) client:


1. Create a new or update an existing application that uses the DB2 Everyplace

Synchronization engine and is compatible with the rich client.

2. In the application, create a class that implements the

com.ibm.rcp.isync.IBridgeData interface and implements the methods

getSyncProperties(String username) and eventIssued(ISyncEvent arg). Make the

getSyncProperties() method return a Properties object containing the same

name/value pairs specified in the sample properties files provided by the DB2e

SDK. The IBridgeData object acts as a listener interface and all synchronization

events initiate a call to eventIssued().

For example, the following sample code reads the properties file stored at the

base of the application plug-in and returns the result as a Properties object. The

username parameter being passed is the client platform username which you

can use to map to the properties for the current user. The specific event and

conflict handling is not shown in these examples because event and conflict

handling is application specific.

public class SampleBridgeData implements IBridgeData {

private static final String FILE_NAME="iSync.properties";

public Properties getSyncProperties(String username) {

Properties prop = new Properties();

try {

InputStream input =

ISyncSamplePlugin.getDefault().openStream(new Path(FILE_NAME));

prop.load(input);

} catch (IOException ioe){

prop.clear();

ioe.printStackTrace();

}

return prop;

}

public int eventIssued(ISyncEvent arg0) {

// Place conflict code here

// Let the sync engine take default action

return ISync.RTNCB_DEFAULT;

}

}

3. In the plug-in’s plugin.xml file extend the com.ibm.rcp.isync.iSyncBridge

extension point, specifying the class you wrote that implements the IBridgeData

interface. For example:

<extension

point="com.ibm.rcp.isync.iSyncBridge">

<properties class="com.ibm.rcp.isync.sample.SampleBridgeData"/>

</extension>

4. Also in the plugin.xml file, import the following plug-ins:

v com.ibm.db2e

v com.ibm.mobileservices.isync

v com.ibm.rcp.isync5. Add the com.ibm.rcp.isync.feature to the Eclipse Update site on the IBM HTTP

Server. From the toolkit, copy the

\lwpapi25\wct\samples\deploy\updatesite\features\com.ibm.rcp.isync.feature_2.5.0.jar

file into <http server document root>\lwpupdate\wct\features and copy the

\lwpapi25\wct\samples\deploy\updatesite\features\com.ibm.rcp.isync_2.5.0.jar

file into <http server document root>\lwpupdate\wct\plugins.

6. Create or update the <http server document root>\lwpupdate\wct\site.xml file

to include the following feature tag:

86 User’s Guide

<feature id="com.ibm.rcp.isync.feature" patch="false"

url="features/com.ibm.rcp.isync.feature_2.5.0.jar" version="2.5.0">

<category name="WCT"></category>

</feature>

<category-def label="WCT" name="WCT">

<description>IBM Workplace Client Technology Applications</description>

</category-def>

7. When you provision your application, you must specify that the

com.ibm.db2e.feature, com.ibm.mobileservices.isync.feature, and

com.ibm.rcp.isync.feature features are required by adding the following

parameters to the WebSphere Portal portlet that you create to represent the

application:

v id.Feature<ID1> -- com.ibm.db2e.feature

v version.Feature<ID1> -- 8.2.0

v match.Feature<ID1> -- compatible

v id.Feature<ID2> -- com.ibm.mobileservices.isync.feature

v version.Feature<ID2> -- 8.2.0

v match.Feature<ID2> -- compatible

v id.Feature<ID3> -- com.ibm.rcp.isync.feature

v version.Feature<ID3> -- 2.5

v match.Feature<ID3> -- compatiblewhere <ID1>, <ID2>, and <ID3> are ID numbers that you supply for the three

sets of feature attributes.

8. Due to an incorrect manifest file, to use the

com.ibm.mobileservices.isync.db2e.jni.DB2eISyncProvider synchronization

driver, you must make the following change to the

com.ibm.mobileservices.isync_8.2.0 plugin:

Note: This step is required only if you are using a DB2 Everyplace database as

a local data store.

Modify the META-INF/MANIFEST.MF file and add the line in bold text:

Provide-Package: com.ibm.mobileservices.isync,

com.ibm.mobileservices.isync.sql,

com.ibm.mobileservices.isync.event,

com.ibm.mobileservices.isync.db2e.jni

Related concepts



88 User’s Guide

Chapter 8. Taking a component offline

IBM Workplace Client Technology supports building applications that are able to

operate while disconnected from a network. Applications that are disconnected

from a network use data stored locally on the client to seemlessly interact with

users. The local data is a replica of data stored on the server and that is

synchronized using the data synchronization facilities provided by the platform.

Taking the 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:

v Offline Manager -- 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.

The series of states that the OfflineManager transitions through are the

following:

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.


State Description

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.

The state transitions sequence is figured below:

v Offline Service -- Provides interfaces and helper classes, including the

IOfflineService, that an application can use to identify what state it is currently

in and what tasks it can perform in the current state.

v Offline User Interface -- 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. Related concepts

“Offline API” Related tasks

“Building offline-aware components” on page 91

Offline API

The client’s offline capability is provided by the following APIs:

OfflineManager -- Responsible for controling the offline state of the client. It

includes the following interface and factory class:

v IOfflineManager -- An interface for managing the offline state of the client. It

defines methods to get and set the client’s offline state.

90 User’s Guide

v IOfflineManagerFactory -- A factory for creating an instance of the

OfflineManager.

OfflineService -- Used to build offline aware components that behave appropriately

depending on the client’s offline state and that are capable of responding to offline

state changes. It includes the following interfaces and classes:

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

v IOfflineServiceHelper -- An interface provided by a helper class that registers

offline events and manages a component’s offline state.

v IOfflineServiceHelperFactory -- A factory for creating an offline helper for

business delegates.

v OfflineServiceBase -- An abstract base class that implements the IOfflineService

interface from which you can derive concrete Offline aware service classes. Related concepts

Chapter 8, “Taking a component offline,” on page 89

Building offline-aware components

The OfflineHelper interface written for offline-capable applications is responsible

for determining the following:

v Does the component currently have access to a server?

v 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 OfflineHelper interface to handle business delegates or

user interface components. The Helper interfaces register component offline

event handlers and manage component offline states.

public class TicketFormView extends

ViewPart implements IModelListener, IOfflineService {

/** Ticket object this form acts on. */

private Ticket ticket;

...

/** 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 OfflineService interface with event handler methods to provide

custom offline behavior to respond to offline events signaled by the

OfflineManager.

/**

* Prompt user to save, discard, or cancel going offline if offline is requested.

*/

public boolean offlineRequested() {

if (editMode) {

try {

// bring this form into focus

ViewUtil.focusView(this);

// prompt user for action

String[] buttons = new String[] {

IDialogConstants.YES_LABEL,

Chapter 8. Taking a component offline 91

IDialogConstants.NO_LABEL,

IDialogConstants.CANCEL_LABEL};

MessageDialog dialog = new MessageDialog(

getSite().getShell(), getPartName(), null,

CallCenterPlugin.getResourceString("str.msg.offlinesavechanges"),

MessageDialog.QUESTION, buttons, 0);

int choice = dialog.open();

// choice id is based on the order of button labels

switch (choice) {

case 0: //yes

saveAction.run();

return true;

case 1: //no

cancelAction.run();

return true;

default:

case 2: //cancel

return false;

}



}

}

return true;

}

public void offlineRequestCancelled() {

}

public void goOffline() {

}

public void offlineStateChanged() {

}

public boolean onlineRequested() {

return true;

}

public void onlineRequestCancelled() {

}

public void goOnline() {

}

}

3. Call the appropriate remote service Enterprise JavaBean (EJB) based on its own

offline state. The following code is taken from the TicketsBusinessDelegate.java

class in the Call Center application:

/**

* Checks to see if the current service is an online service.

* @return Returns true if the service is an online service and false if the

* service is an offline service.

*/

public boolean isOnlineService() throws Exception {

return service.isOnlineService();

}

Related concepts

Chapter 8, “Taking a component offline,” on page 89

92 User’s Guide

Chapter 9. Reference information

Coding tips and best practices

This section provides tips and best practices to help you develop IBM Workplace

Client applications.

Related concepts

“Plug-in, fragment, and feature naming conventions” on page 95

“Logging” on page 96

“Client Java API documentation” on page 101

“Client API Extension Points” on page 101 Related tasks

“Debugging an application in Eclipse”

“Debugging applications remotely” on page 94

“Adding Help to an application” on page 99

Debugging an application in Eclipse

You can use the Eclipse development environment to debug your applications.

Before debugging, you must install the IBM Workplace rich client.

To debug your application:

1. Start Eclipse.

2. Select Window → Open Perspective → Other, and then select Plug-in

Development perspective.

3. From the menu, select Windows → Preferences.

4. From the Preferences window, select Plug-In Development → Target Platform.

5. Click Browse next to the Location field and type the path to the Workplace

rich client \eclipse folder. For example, the default Windows installation

stores the client plug-ins in the following directory:


6. Click Select All, and then click OK.

7. From the Eclipse menu, select Window → Open Perspective → Debug.

8. From the Debug Perspective menu, select Run → Debug.

9. Click Runtime-Workbench, and then click New.

10. On the Arguments tab of the Run-time Workbench configuration page, enter

the following information:

v A Name for the Client Debug Runtime configuration.

v Select Clear workspace data before launching.

v In the Application Name field, select com.ibm.rcp.platform.RCPApplication

from the list.

v Add the following arguments to the VM Arguments field:

-Xbootclasspath/p:"C:/Program Files/IBM/Workplace rich

client/rcp/eclipse/features/com.ibm.rcp.jre.feature_1.4.2/bootjars/

xalan.jar"

-Xbootclasspath/a:"C:/Program Files/IBM/Workplace rich

client/workplace/eclipse/features/


com.ibm.workplace.platform.feature_2.5.0/bootjars/rcpproxy.jar;

C:/Program Files/IBM/Workplace richclient/workplace/eclipse/features/

com.ibm.workplace.platform.feature_2.5.0/bootjars/properties;

C:/Program Files/IBM/Workplace rich client/rcp/eclipse/features/

com.ibm.rcp.platform.feature_1.2.0/bootjars/loggerboot.jar;

C:/Program Files/IBM/Workplace rich client/rcp/eclipse/features/

com.ibm.rcp.platform.feature_1.2.0/bootjars/properties"

-Djava.util.logging.config.class=com.ibm.rcp.core.logger.boot.LoggerConfig

-Drcp.home="C:\Program Files\IBM\Workplace rich client"

-Drcp.data="D:\Dev\workspaces\<wct runtime daily provision local>"

where -Drcp.data represents the path of your local Eclipse workspace.

v Add the following arguments to the Program arguments field after the -nl

argument:

-os win32 -ws win32 -arch x86 -nl en_US -clean -pbcache

"d:\provisioning"

where -pbcache represents the path to your provisioned files.

v Click Apply.11. On the Plug-ins and Fragments tab, select Launch with all workspace and

enabled external plug-ins.

12. Click Apply, and then click Debug.

After a few moments, the application is displayed.

Use the Eclipse Debug Perspective to test the application.

Related concepts

“Coding tips and best practices” on page 93

Debugging applications remotely

If you need to debug a provisioned client or want to see an error that is only

reproducible on a particular machine, you can debug the application running on

that machine remotely. The JVM and Eclipse JDT provide remote debugging

capabilities. For example, if an operation a user is trying to perform fails, ask the

user to retrieve the the .log file in the .metadata directory of their workspace. This

file provides a stack trace for the most recent user actions. After you pinpoint the

problem, run the application in debug mode to capture more information.

To run an application in remote debug mode:

1. Restart the client supplying the following arguments to the JVM:

-vmargs "-Xdebug -Xnoagent -Djava.compiler=NONE

-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8080"

2. Attach the Eclipse JDT debugger to the running client by starting Eclipse.

3. From the menu, select Window → Open Perspective → Debug.

4. From the Debug Perspective menu, select Run → Debug.

5. From the Debug Configuration page, select Remote Java Application and

click New.

6. In the Host field, enter the IP address of the machine on which the target

client process is running. You can also enter localhost to attach to an instance

of the client process running on the same machine if you want to debug a

locally running application.

7. In the Port field, enter ″8080″ or the port you specified in the address value as

a JVM argument earlier.

94 User’s Guide

8. Click the Source tab to attach the sources for the component you want to

debug.

9. Click Advanced, then select Add External Folder.

10. Browse to the build directory for your sources and make sure you select

sources that match the build you provisioned to the client.

11. Navigate to the parent directory of the plug-in’s source code; this is often

called ″src.″

12. Click Ok, then Debug.

13. Once the application is running in debug mode, set a breakpoint in the file

and line that was specified in the .log file.

Related concepts


Plug-in, fragment, and feature naming conventions

The building blocks that comprise client applications are the following:

v Plug-in -- Software components that contain the code that performs the action in

an application.

v Fragment -- Plug-in fragments are separately packaged files whose contents are

treated as if they were in the original plug-in archive file. They are useful for

adding plug-in functionality, such as additional national language translations,

to an existing plug-in after it has been installed. Fragments are ideal for

shipping function that may trail the initial product release, since they can be

used to add function without repackaging or reinstalling the original plug-in.

When a fragment is detected by the platform, its contents are merged with the

function in the original plug-in. In other words, if you query the platform

plug-in registry, you would see the extensions and other function provided in

the fragment as if it was in the original plug-in. Fragments are described using a

fragment manifest file, fragment.xml. It is similar to the plug-in manifest file.

Since a fragment shares many properties with its plug-in, some attributes in the

plug-in manifest are not valid, such as the plug-in class and plug-in imports.

v Feature -- A collection of one or more plug-ins and fragments that the platform

can treat as a group and the Update Manager can update as a group. Features

have a manifest, feature.xml, that provides basic information about the feature

and its content.

Use the following guidelines when naming the plug-ins, fragments, features, and

bundles that you create to run on the client:

Plug-in and fragment IDs

v Do not use characters other than the set [a-z0-9_.].

v Do not use uppercase letters.

A sample standard plug-in ID is:

com.ibm.rcp.myplugin

v Create a source directory name that matches the plug-in ID.

v Write version attributes using the format [0-9]*\.[0-9]*\.[0-9]*

For example: ″2.0.0″ or ″2.1.12″

v For plug-in or fragment names, use the format: <plugin id>_<version>

For example: com.ibm.rcp.systemtray_1.0.0.

v Do not use localizable strings.

Chapter 9. Reference information 95

v Build and deploy plug-ins and fragments to directories or jars with names that

match the plug-in or feature name.

For example: com.ibm.rcp.systemtray_1.0.0 or com.ibm.rcp.systemtray_1.0.0.jar

Feature IDs

v Write the feature ID in the format <logical id>.feature.

For example: com.ibm.rcp.platform.feature

v Do not use characters other than the set [a-z0-9_.].

v Do not use uppercase letters.

v Match the source directory name to the feature ID.

v Write the feature version attribute using the format [0-9]*\.[0-9]*\.[0-9]*

For example: ″2.0.0″ or ″2.1.12″

v There are no requirements for feature labels, but try to make them concise and

meaningful or repeat the feature ID.

For example: ″Workplace Client Technology″

v Build and deploy the feature to directories and jars that have names with the

format: <feature id>_<version>[.jar].

For example: com.ibm.rcp.platform.feature_1.0.0 or

com.ibm.rcp.platform.feature_1.0.0.jar

v Set the collocation-affinity attribute where applicable.

For example, language and platform-specific fragment features should specify

affinity to their parent feature. Sub-function features should also use this. For

example, the com.ibm.rcp.provisioning.feature should specify

collocation-affinity=″com.ibm.rcp.platform″ because it should be installed with

the platform feature.

v Features that do not need to be installed with the platform (applications) should

set their default.install.path property in their feature.properties file even if they

specify a collocation-affinity. For example, the com.ibm.workplace.mail.feature’s

feature.properties file might include ″default.install.path = file:IBM

Workplace/Mail.″ This settings installs it in ${rcp.home}/applications/IBM

Workplace/Mail/features/com.ibm.workplace.mail.feature_2.0.0. Related concepts

“Coding tips and best practices” on page 93 Related tasks

“Creating a view plug-in” on page 13

Logging

Use the standard Java logging package, java.util.logging, to handle logging in your

client application. The IBM Workplace Client Technology platform uses the Java

Runtime Environment (JRE) 1.4, which recognizes the classes and methods

provided by this standard logging package. You can find more information on the

logging package at the following site:

http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/package-summary.html

The WebSphere Application Server uses the Java Runtime Environment (JRE) 1.3,

instead of the JRE 1.4, which does not include java.util.logging. If you want to use

the same code to log events in both the client and the IBM Workplace server, you

can use the Jakarta commons logging API. The client plug-in,

com.ibm.rcp.net.apache.httpclient, wraps the Jakarta commons logging API. The

sample application provided in the toolkit uses this plug-in.

96 User’s Guide

Note: However, this plug-in and the JAR files exported by it are not supported as

public APIs and will change in subsequent releases of platform.

The Jakarta commons logging itself wraps underlying loggers while providing a

consistent logging interface. On the client, the Jakarta commons logging uses the

underlying java.util.logging runtime. On the WebSphere Application Server, Jakarta

commons logging API on the server uses the underlying TrLog logging runtime.

You can find more information on the Jakarta commons logging API at the

following site:

http://jakarta.apache.org/commons/logging/api/index.html

When you use the standard java.logging.util package on the client, the launcher

passes the following command to the Java virtual machine on startup:

-Djava.util.logging.config.class=com.ibm.rcp.core.logger.boot.LoggerConfig.

The LoggerConfig configuration class performs the following functions:

v Defines handlers for the LogManager object that set up logging specifically for

IBM Workplace Client Technology platform-based applications -- the

java.util.logging.ConsoleHandler and the

com.ibm.rcp.core.logger.boot.RCPFileHandler.

v Sets the following default levels, which are based on the java.util.logging class

conventions and behaviors:

– sun.level=WARNING

– com.level=INFO

– com.ibm.level=INFO

– org.level=INFO

– org.eclipse.level=INFO

– httpclient.wire.level=WARNINGv Defines plugin_customization.ini as the file in which to override configuration

settings.

Note: You can also define the default values of the plugin_customization.ini file

on a site-wide basis when you are customizing the steps performed by the

server client installer by updating the pluginvalues.properties file installed

as part of the wctInstall.ear.

The Logger object included in the package is especially useful in plug-in

development because it can log messages for a specific system or application

component. Use the Logger object to initialize the logger as opposed to the

LogManager object. The Logger object is more reliable in a framework that

supports lazy initialization, which is a framework in which an object is not

initialized until it is needed by the application.

For more information on the Logger class, see the following Web site:

http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/Logger.html

For more information on the LogManager class, see the following Web site:

http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/LogManager.html

A logger object has a level property that defines the filtering to apply to log

messages sent to the log by the application. You can set the level for specific

message types in the following ways:

v By defining their default values in the plugin_customization.ini file.

v By setting them dynamically using the Logger.setLevel() method.


The logging properties file is stored in the following directory:

<client_home>\rcp\plugin_customization.ini

The following log files are created by IBM Workplace Client Technology

applications:

Location Log file name Description

<workspace_home>\logs SystemOut.log Captures any log statements

written to System.out.

<workspace_home>\logs SystemErr.log Captures any log statements

written to System.err,

including statements sent by

the logger to the console log.

<workspace_home>\logs rcp.log.0 Captures the log data written

by the RCPFileHandler for

the current or most recent

session.

<workspace_home>\logs rcp.log.1 Captures the log data written

by the RCPFileHandler for

the previous run of the

client.

<workspace_home>\

metadata\ .log

Captures log data written to

the Eclipse IEvent

infrastructure.

<workspace_home>\.config\

*.log

Captures log data specific to

OSGi-specific problems.

Related concepts

“Coding tips and best practices” on page 93 Related tasks

“Implementing logging”

Implementing logging

The following sample code defines how to implement logging in your IBM

Workplace Client Technology application.

To implement a logger:

1. In the class you are writing for which you want to record logging events,

implement the following pattern in the code to initialize the logger:

private static final String CLAZZ_NAME =

PersonalityRegistry.class.getName();

private static final String PKG =

PersonalityRegistry.class.getPackage().getName();

private static final String LOG_RB = PKG + "." +

PKG.substring(PKG.lastIndexOf(’.’)+1);

private static Logger _logger = Logger.getLogger(PKG,LOG_RB);

where PersonalityRegistry is the name of your package. The following code

defines variables for the logger levels:

private static final Level FINEST = Level.FINEST;

private static final Level FINER = Level.FINER;

private static final Level FINE = Level.FINE;

private static final Level CONFIG = Level.CONFIG;

98 User’s Guide

private static final Level INFO = Level.INFO;

private static final Level WARNING = Level.WARNING;

private static final Level SEVERE = Level.SEVERE;

The following code demonstrates how to send messages to the logger:

private void buildRegistry(){

if (_logger.isLoggable(Level.FINER)){

_logger.entering(PersonalityRegistry.class.getName(),

"buildRegistry");

}

IExtensionRegistry registry = Platform.getExtensionRegistry();

IConfigurationElement elements[] = registry

.getConfigurationElementsFor(PERSONALITY_EXTENSION_ID);

for (int i = 0; i < elements.length; i++){

PersonalityDescriptor desc = new PersonalityDescriptor(elements[i]);

if (_logger.isLoggable(Level.FINEST)){

_logger.finest("Adding personality id= " + desc.getId());

}

personalityStore.put(desc.getId(), desc);

}

if (_logger.isLoggable(Level.FINER)){

_logger.exiting(PersonalityRegistry.class.getName(),"buildRegistry");

}

}

2. Create a properties file with the same name as the package.

3. If you want to limit the log messages returned by a package, add the package

as an entry to plugin_customization.ini and set the value for the package to

SEVERE; this limits the number of messages it logs to only those that warn of

errors that could potentially interrupt a user’s ability to use the application.

4. To use your own logging handlers and configuration settings, override the

default configuration by specifying values for the desired handlers or other

configuration properties in the <client_home>/rcp/plugin_customization.ini

file. If you add new handlers, be sure to specify them in the system classpath.

Related concepts

“Logging” on page 96

Adding Help to an application

You can add Help files that describe how to use the application you are

contributing to the IBM Workplace client by creating an Eclipse Help plug-in. The

client Help system is designed to enable a user to access multiple Help books, each

contributed by a plug-in and installed in the appropriate directory on the client

machine.

To contribute Help content:

1. Write your topics using any standard Help processing tool that can generate

the topics as HTML files. Zip the resulting HTML files into a doc.zip file.

2. Using a standard text editor, create an XML file called ″toc″ to define the

contents of the Table of Contents for the Help plug-in. Add to the toc.xml file

an opening toc element and include the following two attributes:

v label -- Defines the Help plug-in name

v topic -- Specifies which topic to show by default in the right pane when the

Help plug-in opens.

The following example contains a sample toc element:

<?xml version="1.0" encoding="utf-8"?>

<toc label="My Application Help" topic="titlepage.html">


3. Add to the toc.xml file topic elements that represent each HTML file you want

to include in the plug-in. Each topic element must have the following two

attributes:

v label -- Specifies the text you want to display as the hyperlink text in the

table of contents pane that displays on the left of the resulting Help window.

v href -- References the HTML file containing the topic content. The href

contains a relative path to the HTML file. Though the referenced HTML files

are zipped into the doc.zip file, you do not need to start the path with

″doc\.″ The platform extracts the zipped up files when it accesses the Help

plug-in.The following example contains some sample topic elements:

<topic label="Terms of Use" href="copyright.html"/>

<topic label="Introduction to My Application" href="appintro.html"/>

<topic label="System requirements" href="sysreqs.html"/>

4. You can impose a structure to the Table of Contents hypertext links by adding

secondary topic elements within primary topic elements. For example, the

following ″Adding a filter″ and ″Scooping coffee″ topics would appear indented

below the ″How to make coffee″ topic because the ″How to make coffee″ topic

element contains the other two topic elements.

<toc label="My Help" topic="intro.html">

<topic label="How to make coffee" href="coffeeintro.html">

<topic label="Adding a filter to the grinds tray" href="filter"/>

<topic label="Scooping coffee into the filter" href="grinds"/>

</topic>

</toc>

Be sure to end the toc.xml file with a closing toc element </toc>

5. Create a plugin.xml file and an associated plugin.properties file for your Help

plug-in. The plugin.xml must contain the following attributes:

v name -- Defines the name of the Help plug-in. This name displays as the

book title in the Help system’s table of contents to distinguish one Help

plug-in from others that may be available for the platform. You can specify a

key for this name to enable the Help plug-in name to be translated.

v id -- Defines an ID for the plug-in.

v version -- Defines the version number of the plug-in.

v provider-name -- Defines the organization that created the plug-in.Include an extension point reference to ″org.eclipse.help.toc,″ as demonstrated

below:


<plugin

name = "%name"

id = "com.ibm.acme.help"

version = "2.5.0"

provider-name = "Acme">

<extension point="org.eclipse.help.toc">

<toc file="toc.xml" primary="true" />

</extension>

</plugin>

6. To finish creating the Help plug-in, in a folder named with the ID you specified

in the id attribute of the plugin element in the plugin.xml file, add the files that

you just created:

v doc.zip

v plugin.properties

v plugin.xml

v toc.xml

100 User’s Guide

7. Add the plug-in file to the following directory on the client machine to display

your Help files in the Help window when a user selects Help → Help contents

from the client menu.

On Windows:

C:\Program Files\IBM\Workplace rich client\eclipse\plugins

On Linux:

root/IBM/Workplace rich client/eclipse/plugins

Related concepts


Client Java API documentation

The following APIs have corresponding files in Javadoc documentation format. Go

to the lwpapi25/wct/javadoc directory and double-click index.html to open the

files.

v com.ibm.rcp.offline.api

v com.ibm.rcp.platform.api

v com.ibm.rcp.rte.api

v com.ibm.rcp.security.api

v com.ibm.rcp.sync.api

v com.ibm.rcp.ui.alerts.api

v com.ibm.rcp.ui.browser.core.api

v com.ibm.rcp.ui.widgets.api

Related concepts


Client API Extension Points

The following client API extension points are public:

v “AlertType extension point” on page 55

v “Control set extension point” on page 44

v “Personalities extension point” on page 41

v “Personality Extension extension point” on page 42

v “Personality startup extension point” on page 43

v “Sync services extension point” on page 85

Related concepts



102 User’s Guide

Chapter 10. Call Center and Samples applications

The toolkit includes sample applications, called the Call Center and Samples

applications that exercise the public APIs provided in the toolkit.

Related concepts

“Call center synchronization” on page 111 Related tasks

“Setting up the Call Center and Samples applications”

Setting up the Call Center and Samples applications

The Call Center and Samples applications included in the toolkit demonstrate how

to use the public client APIs. They also serve as an example of how to provision a

client application.

You can provision the Call Center and Samples applications by completing the

following steps:

1. “Deploying an application” on page 20

2. “Installing a feature on WebSphere Portal” on page 21

3. “Creating a portal page” on page 26

4. “Defining access control levels” on page 26

5. “Adding parameters to a WebSphere Portal page” on page 27

An alternative to installing the sample feature on WebSphere Portal and creating

portal page for the samples using the WebSphere Portal Administration pages, is to

use XML Access to create the portlets and pages. See “Using XML Access to

provision the sample applications” on page 109 for more details.

To access the document library component of the Call Center application, you must

copy the IBM Workplace Collaboration Services API package included in the

com.ibm.workplace.api feature to the applications directory on your client

machine. See “IBM Workplace Collaboration Services APIs” on page 125 for more

information. Another important step in setting up the Call Center application is to

install the supporting remote Enterprise JavaBean (EJB) files on the server to

support remote EJB calls.

Related concepts

Chapter 10, “Call Center and Samples applications” Related tasks

Chapter 6, “Calling a remote Enterprise JavaBean,” on page 77

Adding the sample applications to the Eclipse update site

To ensure that the plug-ins that comprise the call center application and samples

are available to be deployed on WebSphere Portal, you must add them to an

Eclipse update site, which is a directory on the IBM HTTP Server that is installed

as part of WebSphere Portal. The update directory is referred to as the Eclipse

update site because it is the directory to which client applications refer when an

administrator looks for plug-ins that are new or updated and available for

provisioning to the client.


Be sure you have installed the IBM Workplace rich client before you begin the

following procedure.

To add the sample applications to the Eclipse update site:

1. Copy the following files from the

lwpapi25\wct\samples\deploy\updatesite\features directory to the

<HTTPSERVER_HOME>\htdocs\en_US\lwpupdate\wct\feaures directory:

v com.ibm.workplace.demo.callcenter.feature_2.5.0.jar

v com.ibm.workplace.samples.feature_2.5.0.jar2. Copy the following files from the

lwpapi25\wct\samples\deploy\updatesite\plugins directory to the

<HTTPSERVER_HOME>\htdocs\en_US\lwpupdate\wct\plugins directory:

v com.ibm.workplace.demo.callcenter_2.5.0.jar

v com.ibm.workplace.samples_2.5.0.jar

v com.ibm.rcp.demo.callcenter.core_2.5.0.jar

v com.ibm.rcp.demo.callcenter.help_2.5.0.jar

v com.ibm.rcp.samples_2.5.0.jar3. Copy the following file from the

lwpapi25\wct\applications\eclipse\updatesite\plugins directory to the


com.ibm.workplace.api_2.5.0.jar

4. Copy the following file from the

lwpapi25\wct\applications\eclipse\updatesite\features directory to the

<HTTPSERVER_HOME>\htdocs\en_US\lwpupdate\wct\features directory:

com.ibm.workplace.api.feature_2.5.0.jar

5. From the <HTTPSERVER_HOME>\htdocs\en_US\lwpupdate\wct directory,

locate, back up, and edit the site.xml file to include a feature tag for the Call

Center application and a feature tag for the Samples application. The site.xml

tag registers the update features. The following is example code that adds the

Call Center and Samples application feature tags as entries after the other

feature tags in the site.xml file:

<feature

id="com.ibm.workplace.demo.callcenter.feature"

url="features/com.ibm.workplace.demo.callcenter.feature_2.5.0.jar"

version="2.5.0">

<category name="WCT"/>

</feature>

<feature

url="features/com.ibm.workplace.samples.feature_2.5.0.jar"

id="com.ibm.workplace.samples.feature"

version="2.5.0">


</feature>

<feature

url="features/com.ibm.workplace.api.feature_2.5.0.jar"

id="com.ibm.workplace.api.feature"

version="2.5.0">


</feature>

6. Save the site.xml file.

7. Add an images subdirectory to the IBM HTTP Server

\htdocs\en_US\lwpupdate directory to store the icon graphics that the client

can retrieve and display in the switcher bar to represent your application.

8. Copy all of the image files from the lwpapi25\wct\samples\deploy\images

directory to the images subdirectory you just created:

104 User’s Guide

<HTTPSERVER_HOME>\htdocs\en_US\lwpupdate\images

Installing the sample features on WebSphere Portal

Install the sample application plug-ins and features onto RCPML-based portlets on

WebSphere Portal and arrange the layout of the portlets on a page to define the

layout of your application. When the plug-ins you created run on the client, the

client maps the Portal page you define here to a single rich client application and

maps each portlet you define here to a view or folder in that application.

Perform the following steps to install the features to a portlet on WebSphere Portal:

1. Log in to the IBM Workplace server as an administrator and click

Administration.

2. Select Portlets → Manage Portlets to access the Portal Aministration Pages.

3. The following pages represent the views and folders that make up the Call

Center and Samples applications:

v RCPSDK Call Center - Banner 3_1_IP

v RCPSDK Call Center - FAQ Form 3_0_M1

v RCPSDK Call Center - FAQs 3_0_M0

v RCPSDK Call Center - Links 3_0_LV

v RCPSDK Call Center - Main Folder 3_0_IQ

v RCPSDK Call Center - Navigation 3_0_IP

v RCPSDK Call Center - Resource Folder 3_0

v RCPSDK Call Center - Ticket Form 3_0_LT

v RCPSDK Call Center - Tickets 3_0_M2

v RCPSDK Samples - Main Folder 3_0_LT

v RCPSDK Samples - Widgets 3_0_M4

Repeat the following steps to create each of these pages:

a. In the list of portlets, find the RCP Portlet - Generic portlet, select it, and

then click Copy.

b. Select the copied portlet from the list of portlets and click Modify

parameters.

c. Change the portlet name to a name in the Title parameter row in the

following table.

d. Click Set title for selected locale, and then type the value specified in the

Title parameter row in the table below into the Title field, and click OK.

e. Add the parameters and values specified in the table below to the portlet.

To add a parameter, type the parameter name and value into the pair of

fields to the left of the Add button, and then click Add.

Table 1. Call Center application page parameters

Parameter name Parameter value Parameter value Parameter value Parameter value

Title RCPSDK Call

Center - FAQ

Form

RCPSDK Call

Center - FAQs

RCPSDK Call

Center - Links

RCPSDK Call

Center - Main

Folder

rcpView com.ibm.rcp.

demo.callcenter.

core.views.

FAQFormView

com.ibm.rcp.

demo.callcenter.

core.views.

FAQsView

com.ibm.rcp.

demo.callcenter.

core.views.

LinksView

folderid main resources resources main

Chapter 10. Call Center and Samples applications 105

Table 1. Call Center application page parameters (continued)


rcpUpdate

fixed no yes yes

allowMultiple yes

visible no yes yes

style

ratio .25



Title RCPSDK Call

Center -

Navigation

RCPSDK Call

Center -

Resource Folder

RCPSDK Call

Center - Ticket

Form

RCPSDK Call

Center - Tickets

rcpView com.ibm.rcp.

demo.callcenter.

core.views.

NavigatorView

com.ibm.rcp.

demo.callcenter.

core.views.

TicketFormView

com.ibm.rcp.

demo.callcenter.

core.views.

TicketsView

folderid main resources main main

rcpUpdate com.ibm.

workplace.demo.

callcenter.feature

fixed yes no yes

allowMultiple yes

visible yes no yes

style

ratio .35 .4

id.Feature1 com.ibm.

workplace.demo.

callcenter.feature

version.Feature1 2.5.0

match.Feature1 compatible


workplace.api.

feature



id.Feature3 com.ibm.lwp.

wct.mymail

common.feature



id.Feature4 com.ibm.pdm.

feature



106 User’s Guide

Table 2. Call Center application page parameters (continued) (continued)



workplace.cai.

ui.feature




Parameter name Parameter value

Title RCPSDK Call Center - Banner

rcpView com.ibm.rcp.demo.callcenter.core.

views.BannerView

folderid

rcpUpdate

fixed yes

allowMultiple

visible yes

style NO_TITLE

ratio .10

id.Feature1

version.Feature1

match.Feature1

Table 4. Sample application page parameters

Parameter name Parameter value Parameter value

Title RCPSDK Samples - Main

Folder

RCPSDK Samples - Widgets

rcpView com.ibm.rcp.samples. api.

widgets.WidgetsView

folderid main main

rcpUpdate com.ibm.workplace.samples.

feature

fixed yes

allowMultiple

visible yes

style

ratio

id.Feature1 com.ibm.workplace.samples.

feature



4. Click Save to save your changes and return to the Manage Portlets pane.


Creating portal pages for the samples

Now that you have created portlets that represent the sample application views

and folders, you can create WebSphere Portal pages on which to lay out the

portlets.

To create portal pages for the sample applications:

1. From the Portal Administration pages, expand Portal User Interface, and then

select Manage Pages.


3. Click the returned WorkplaceRCPPages page, then click the Edit icon

to

open the Edit layout page.



and close the page.


6. Click New Page. Name the page RCPSDK Call Center.



Note: A warning is displayed that says the page has been created but is not

included in page navigation. This is ok because the page was created

under the Content Root and not under My Portal.

8. Repeat Steps 6 and 7, naming the new page RCPSDK Samples.

9. Create custom names for the pages so that your XMLAccess script can later

retrieve the pages by clicking Portal Settings → Custom Unique Names →

Pages and in the Search for field, type RCPSDK, and then click Search to find

the pages you just created.

10. Click the pencil icon to the right of each page returned by the search and type

a unique custom name for the page, and then click OK. For example, type

rcpsdk.callcenter for the RCPSDK Call Center page and rcpsdk.samples for the

RCPSDK Samples page.


WorkplaceRCPPages, find the RCPSDK Call Center page, and then select

Edit Page Layout.

12. Choose the two column layout with a top spanning header pane, then click

Add Portlets and search on ″Call Center″ to find and add the RCPSDK Call

Center portlets to the page. After adding them all, arrange them as illustrated

in the tables below, and then click Done.

Spanning header at top of RCPSDK Call Center application page

RCPSDK Call Center - Banner

Left column Right column

RCPSDK Call Center - Navigation RCPSDK Call Center - Main Folder

RCPSDK Call Center - Resource Folder RCPSDK Call Center - Tickets

RCPSDK Call Center - Links RCPSDK Call Center - Ticket Form

RCPSDK Call Center - FAQs RCPSDK Call Center - FAQ Form

108 User’s Guide

13. Find the RCPSDK Samples page, select Edit Page Layout, and then choose

the single column layout, and click Add Portlets. Add the RCPSDK Samples

portlets to the page layout, and then click Done.

RCPSDK Samples application

RCPSDK Samples - Main Folder

RCPSDK Samples - Widgets

Using XML Access to provision the sample applications

You can also use the WebSphere Portal XML Access interface to programmatically

create a portlet and page that provision the Call Center and Sample SDK

application features to the client.

To use XML Access:


such as D:\temp.

2. Copy the add_rcpsdk_portlets.xml and add_rcpsdk_pages.xml files from the

\lwpapi25\WCT\samples\deploy\xmlaccess directory on your local machine

to the temporary directory you just created on the WebSphere Portal server.

The add_rcpsdk_portlets.xml file is a simple XMLAccess input file that contains

tags that tell WebSphere Portal to create portlets that represent the Call Center

and Samples SDK applications’ default views. The add_rcpsdk_pages.xml file is

a simple XMLAccess input file that contains tags that tell WebSphere Portal to

create two pages with unique names; one with the name rcpsdk.callcenter,

which represents the Call Center application’s perspective and another with the

name rcpsdk.samples, which represents the Sample SDK application’s

perspective.


directory and run the XMLAccess utility:

xmlaccess -in D:\temp\add_rcpsdk_portlets.xml





Workplace server.

4. From the same WebSphere Portal server’s \bin directory run the XMLAccess

utility:

xmlaccess -in D:\temp\add_rcpsdk_page.xml





Workplace server.

Defining access control levels for the samples

The level of access that a user has to portlets and pages hosted by WebSphere

Portal must be set using the WebSphere Portal Adminstration pages. Set all

authenticated WebSphere Portal users to have access to the portlets and pages that

make up the Call Center and Samples applications.


To set the access level for portlets and pages to all authenticated WebSphere Portal

users:

1. From the WebSphere Portal Administration pages, click Access → Resource

Permissions → Pages.

2. Search for pages with ″RCPSDK″ to return the Call Center and Samples pages

you created.

3. Click the Assign Access key icon of the RCPSDK Call Center page.


5. Check all authenticated portal users and then click OK. Click Done, and then

click OK to return to the page search results.

6. Repeat Steps 3 to 5 for the RCPSDK Samples page.

7. Click Done to return to the list of resource types. Click Portlets, then search for

portlets with ″RCPSDK″ to return the portlets you created.

8. For each portlet, set the User role to all authenticated portal users, and then

save your changes.

Adding parameters to the sample portal pages

Parameters can only be added to a Portal page by running XMLAccess scripts. You

can add page parameters to the WebSphere Portal pages you created for the Call

Center and Samples applications to further define how you want the applications

they represent to display in the client. For example, you can use an XMLAccess

script to define a value for the iconpath parameter, which informs the client where

to get the icon graphic to display in the switcher bar to represent the application.

XMLAccess is a command-line configuration interface to WebSphere Portal. Using

the WebSphere Portal XMLAccess interface, you can export a Portal page, update

its parameters, and import it back into WebSphere Portal. The following

parameters can be added to a portal page using XMLAccess:

Note: See the WebSphere Portal Information Center for more information on

XMLAccess.

Parameter name Description

activities Defines which activities to include on the

page when it is started in the client. The

personality defined for an application is an

example of an activity.

default_folder Defines a default folder in which to display

any views for which no associated folderid

has been specified.

iconpath The path to application branding icons that

are specified relative to the base WebSphere

Portal application. These are used by the

switcher and are cached locally by the

Pagebuilder code.

To add page parameters to a WebSphere Portal page:


such as C:\temp.

2. Copy the exportpages.xml file from the

\lwpapi25\wct\samples\deploy\xmlaccess directory on your local machine to

the temporary directory you just created on the WebSphere Portal server. The

110 User’s Guide

exportpages.xml file is a simple XMLAccess input file that contains tags that

tell Portal to export the specifies pages, in this case, the RCPSDK Call Center

and RCPSDK Samples pages. The pages.xml file is example output of running

exportpages.xml.


directory and run the XMLAccess utility to export the pages you created to a

file called pages.xml:

xmlaccess -in c:\temp\exportpages.xml -out c:\temp\pages.xml





Workplace server.

4. Open c:\temp\pages.xml in a text editor. This file now contains the settings

and content of the pages you created earlier. Search for the bookmarkable

parameter for the RCPSDK Call Center page and after it, add the following

parameters:

<parameter name="activities" type="string"

update="set">com.ibm.rcp.demo.callcenter.core.activity</parameter>

<parameter name="default_folder" type="string"

update="set">main</parameter>


update="set">/lwpupdate/images/callcenter.png</parameter>

5. Search for the bookmarkable parameter for the RCPSDK Samples page and

after it, add the following parameters:

<parameter name="activities" type="string"

update="set">com.ibm.rcp.samples.activity</parameter>


update="set">/lwpupdate/images/samples.png</parameter>

Note: You do not need to set a value for the default_folder because there are

no folders in the Samples application.

6. Save the file, and then import it into WebSphere Portal using the XMLAccess

interface, by returning to the command prompt opened to the WebSphere

Portal server’s \bin directory and type the following:

xmlaccess -in c:\temp\pages.xml -out c:\temp\update-results.xml


Note: Example output files are provided in

<SAMPLES_HOME>\deploy\xmlaccess\example output files directory.

Call center synchronization

The Call Center views demonstrates the following synchronization methods:

v Tickets view -- User preference-driven synchronization

v FAQ view -- Document library synchronization

The FAQ view demonstrates how to use the document library service API to

perform synchronization. The Ticket view demonstrates how to enable a user to

specify, through preference pages, which data source to use for synchronization.

You cannot choose a specific data store to synchronize. You can register a source

with the Synchronization Manager and when synchronization is started, all

registered data sources are replicated, including data stores synchronized using the


syncML protocol, all document libraries, including the FAQ document library, and

whichever data store the user selects for the Ticket view.

Related concepts

Chapter 10, “Call Center and Samples applications,” on page 103

“Call center preference pages”

“FAQ document library” on page 114

Call center preference pages

The Tickets view demontrates how to create a view that can be synchronized to a

remote data source using a remote EJB call to a server or to a local data source.

The user can decide which type of synchronization to perform by specifying it in a

preference page. The Call Center Tickets view is supported by the following

preference pages:

v Call Center -- Lists the supporting data stores that are possible targets for Ticket

synchronization. The user can select a data store and click Apply to get the

application to switch to the selected data store and display its contents in the

Trouble Tickets view. A dialog box pops up if the data store is not available. This

can occur if a server side data store is chosen and the server is either down or

unreachable. You can check Remember Last Ticket Filter to force the application

use the same data source as a synchronization target every time it is opened.

v Custom Synchronization Options -- Lists the supporting data stores that are

possible source stores for Ticket synchronization. When synchronization is

initiated in the client, data from the sync source specified on this page is

synchronized with the target source specified on the Call Center preferences

page. If you specify a local synchronization source, such as POJO Derby, and a

remote synchronization target, such as EJB Cloudscape (Server Side), the ticket

data is available when the client is offline, and a copy is safely stored on the

server. You can click Clear Last Synchronization Data to ensure that a full

synchronization is performed. This option should be used if the data in the

synchronization source does not match the data in the synchronization target.

Related concepts

“Call center synchronization” on page 111 Related tasks

Chapter 6, “Calling a remote Enterprise JavaBean,” on page 77

“Implementing preference pages” on page 65

Implementing the Call Center Enterprise JavaBean services

The Call Center application included in the IBM Workplace Client Technology API

toolkit contains example code that accesses Enterprise JavaBean (EJB) services

running on the server from the client. The sample code demonstrates how to use

the platform to call remote stateless EJBs running on an IBM Workplace

Collaboration Services server. Remote EJBs encapsulate business tasks that rely on

server-based resources and are used by one or more applications. The use of EJBs

promotes code reuse by allowing developers to write business logic code that can

be used from both client and server-based applications. For example, you can call a

remote EJB to request the synchronization of data in a database hosted by the

server with that of a database hosted by the client.

The Call Center application accesses the following EJB services remotely:

v Cloudscape EJB Service -- Uses a stateless EJB to store ticket data in a

Cloudscape database on the server using JDBC calls.

112 User’s Guide

v Hashmap EJB Service -- Uses a stateless EJB to store ticket data to an in-memory

hash map. This data is only persistent for the life of the application. If the

application or server is stopped or restarted, the data is lost.

In order to use the EJBs provided with the Call Center application, you must

install them on the server that will be used by the client for provisioning. You also

need to create a supporting Cloudscape database and set it up on the server.

To implement the Call Center Enterprise JavaBean services:

1. “Creating the Call Center database in Cloudscape”

2. “Setting up the Call Center Cloudscape data source” on page 114

3. Copy the rcp.callCenterappSvc.ear file from the \samples\deploy\ear

subdirectory of the toolkit to a local directory on the WebSphere Application

Server machine, then complete the following procedure: “Installing an

Enterprise JavaBean” on page 77

Related concepts

“Call center preference pages” on page 112 Related tasks

“Setting up the Call Center and Samples applications” on page 103

Creating the Call Center database in Cloudscape

You can use the ij tool provided with Cloudscape to create a database. The ij tool is

a simple utility for running scripts against a Cloudscape database. You can use it

to create tables based on the SQL statements you pass to it in an SQL file.

To create the Call Center database in Cloudscape:

1. Create an environment variable for the home directory of the Cloudscape

database, calling it DB2J_HOME.

v On Windows, in a command prompt, type the following:

set DB2J_HOME=<WP_ROOT>\shared\app\cloudscape

v On Linux, from the Cloudscape home directory, which by default is

<WebSpherePoral_ROOT>/shared/app/cloudscape, type the following:

export DB2J_HOME=/<WP_ROOT>/shared/app/cloudscape

2. Edit the CLASSPATH variable to include Cloudscape libraries.

v On Windows, from a command prompt, type the following:

set CLASSPATH=%DB2J_HOME%\db2j.jar;

%DB2J_HOME%\db2jtools.jar;

%DB2J_HOME%\db2jcview.jar;

%CLASSPATH%

v On Linux, type the following:

export CLASSPATH=$DB2J_HOME/db2j.jar:

$DB2J_HOME/db2jtools.jar:

$DB2J_HOME/db2jcview.jar:

$CLASSPATH

3. Copy the callcenter.sql file from the \lwpapi25\wct\samples\call-center\plugins\com.ibm.rcp.demo.callcenter.core\scripts directory to the

<WebSpherePoral_ROOT>\shared\app\cloudscape\bin directory.

4. Run the ij tool that comes with Cloudscape and runs in a separate shell:

v On Windows, from the bin subdirectory in the DB2J_HOME directory, type

the following in a command prompt:

setcp.bat


then

ij.bat

v On Linux, from the DB2J_HOME directory, type the following:

ij.ksh

5. In the ij shell, type the following command to create the Call Center database.

connect ’jdbc:db2j:CALLCENTER;create=true’;

6. To create tables using the supplied SQL file, type:

run ’bin\callcenter.sql’;

7. To exit the ij program, type:

exit;

Setting up the Call Center Cloudscape data source

You must create a JDBC provider and configure its data source in the WebSphere

Portal Administration pages before you can communicate with the Call Center

Cloudscape database from a client application.

To set up the Call Center Cloudscape database JDBC provider and data source:

1. Log in to the WebSphere Administration Console

(http://myserver.com:9091/admin) as an administrator.

2. From the WebSphere Administration Console pages, expand Resources, and

then click JDBC Providers.

3. Click New, and then choose Cloudscape JDBC Provider.

4. Click Apply and type the Cloudscape classpath information:

<DB2J_HOME>/db2j.jar

Click Apply.

5. Click Data Sources, click New, and then provide the following information:

v Name -- CALLCENTER

v JNDI Name -- jdbc/callcenter

Click Apply.

6. Click Custom Properties and select the database name, then provide the

following information:

<DB2J_HOME>/CALLCENTER

7. Save your settings and test the connection to the Call Center data source you

just configured by clicking JDBC Providers → Cloudscape JDBC Provider →

Data Source, then selecting the CALLCENTER check box and clicking Test

Connection.

FAQ document library

The Call Center application includes a Frequently Asked Questions (FAQ) view

that lists a series of commonly asked questions and their answers. You can

configure the FAQ view entries to be stored in the following ways:

v In an FAQ document library created on the IBM Workplace server and

synchronized with the client.

v In a client-only document library owned by the current user.

v In a hashmap, which does not persist data between sessions. Related concepts

“Call center synchronization” on page 111

114 User’s Guide

Implementing the FAQ document library on the server

The standard configuration model for the Call Center application is to implement

the FAQ store as an FAQ document library created on the IBM Workplace server

and set it up to synchronize with the client.

See “Using the document library service API” on page 127 for information on

creating a document library.

The name of the document library used by the FAQ service is declared in the

document-library.properties file for the com.ibm.workplace.demo.callcenter plug-in.

For example, the PROPERTIES file contains the following code:

# document-library.properties

# name of the Call Center’s FAQ Document Library

DocumentLibraryName=FAQ

To implement the FAQ document library on the server for synchronization with

the client:

1. From the IBM Workplace server, create a document library and name it ″FAQ.″

2. Grant access to the database to all users.

3. Optional: From the IBM Workplace rich client Navigator view, click the down

arrow next to Document Libraries and select Organize Favorites Libraries.

Note: The Call Center uses the FAQ library even if it is not made available

offline.

4. Optional: Find the FAQ document library and select Available Offline to flag

the document library for synchronization with the client.

Implementing a client-only document library

If the client cannot find the document library having the name specified in the

document-library.properties file, it defaults to using a local document library.

To implement a client-only document library:

The name of the document library used by the FAQ service is declared in the

document-library.properties file for the com.ibm.workplace.demo.callcenter plug-in.

For example, the PROPERTIES file contains the following code:

# document-library.properties

# name of the Call Center’s FAQ Document Library

DocumentLibraryName=FAQ

Do not create a document library on the server named ″FAQ.″

Implementing a hashmap for the FAQ document library

The FAQ service is declared in the com.ibm.rcp.demo.callcenter.core.faqservice

extension point in the plugin.xml file for the com.ibm.workplace.demo.callcenter

plug-in. If you do not declare the FAQ service, the client defaults to using a

HashMap to store the FAQs for the length of the current session.

To implement a HashMap for the FAQ document library:

In the plugin.xml file for com.ibm.workplace.demo.callcenter, comment out the

extension point named com.ibm.rcp.demo.callcenter.core.faqService. For example,

comment out the following code from the plugin.xml file:


<extension point="com.ibm.rcp.demo.callcenter.core.faqService">

<service

name="Workplace Document Library Service"

factoryClass=

"com.ibm.workplace.demo.callcenter.model.faq.FAQDocLibServiceFactory"

id="lwp-docs"/>

</extension>

116 User’s Guide

Chapter 11. The Enterprise Offering runtime environment

The Enterprise Offering platform provides a way to plug in and manage multiple

applications, and provide windows in which the applications are able to control

the available display mechanisms. You can run the Enterprise Offering runtime

environment on the client.

To set up the environment and run a custom application in it, perform the

following steps:

v Use the Application_Developers_Guide.pdf to build a custom Enterprise

Offering application.

v Add your custom application features and plug-ins to the Eclipse Update site.

v Create a portlet and page on the WebSphere Portal server to represent your

application.

v Download or restart the rich client and launch the Enterprise Offering

environment and your custom application from the switcher bar.

Setting up the Enterprise Offering runtime environment

The following steps demonstrate how to set up the Enterprise Offering runtime

environment by describing how to provision the Order Entry sample application in

the Enterprise Offering runtime environment:

1. Install IBM Workplace Collaboration Services. See the section, ″IBM Workplace

installation,″ in the IBM Workplace Collaboration Services information center.

You can find the information center on the IBM Workplace product site at:

http://www.lotus.com/ldd/notesua.nsf/find/workplace, then download the

IBM Workplace rich client from the IBM Workplace server. See the topic, ″Rich

client installation and configuration,″ in the IBM Workplace Collaboration

Services information center.

2. “Adding the Order Entry sample to the Eclipse update site” on page 118

3. Create a portlet and page on the WebSphere Portal server to provision the

client with the supporting Enterprise Offering features by completing one of

the following procedures:

v “Provisioning the Enterprise Offering components” on page 118

“Creating a WebSphere Portal page for the Order Entry sample” on page 122

or

v “Using XML Access to provision the Enterprise Offering components” on

page 1224. Start the client and download available updates if prompted. When the rich

client window is displayed, click the Order Entry Rich Client Application icon

on the switcher bar to start the Enterprise Offering runtime environment.

5. See the Enterprise Offering documentation, Application_Developers_Guide.pdf,

for information on developing applications for the Enterprise Offering runtime

environment.

Note: When you define a stand alone perspective in an Enterprise Offering

application, be sure to set the perspective’s fixed attribute to true in the

plugin.xml file for your application plug-in. For example:


<extension

point="org.eclipse.ui.perspectives">

<perspective

name="%perspectiveName"

icon="icons/myapplication.gif

fixed="true"

class="com.ibm.acme.MyRcpPerspective"

id="com.ibm.acme.MyRcpPerspective">

</perspective>

</extension>

Adding the Order Entry sample to the Eclipse update site

To ensure that the plug-ins that make up the Order Entry sample application are

available to be deployed from WebSphere Portal server, you must add them to an

Eclipse update site, which is a directory on the IBM HTTP Server that is installed

as part of WebSphere Portal server. The update directory is referred to as the

Eclipse update site because it is the directory from which the server provisions rich

client machines with client applications.

To add the sample application to the Eclipse update site:

1. Copy the following file from the

lwpapi25\WCT\samples\deploy\updatesite\features directory to the


com.ibm.eswe.orderentry.bin_5.8.1.1.jar

2. Copy the following files from the

lwpapi25\WCT\samples\deploy\updatesite\plugins directory to the


com.ibm.eswe.orderentry.common_5.8.1.jar

com.ibm.eswe.orderentry.hybrid_5.8.1.jar

com.ibm.eswe.orderentry.service_5.8.1.jar

com.ibm.eswe.orderentry.webapp_5.8.1.jar


locate, back up, and edit the site.xml file to include a feature tag for the Order

Entry sample. The site.xml tag registers the update features. The following

example code adds the Order Entry sample feature tag as an entry after the

other feature tags in the site.xml file:

<feature

id="com.ibm.eswe.orderentry.bin"

patch="false"

url="features/com.ibm.eswe.orderentry.bin_5.8.1.1.jar"

version="5.8.1.1">

<category

name="WCT">

</category>

</feature>

4. Save the site.xml file.

Provisioning the Enterprise Offering components

Create an RCPML-based portlet on the WebSphere Portal server that will provision

clients with the plug-ins that make up the WCT Application and WCT Web

Application runtime environments.

To set up provisioning for the Enterprise Offering components:

1. Log in to the IBM Workplace server as an administrator, and click

Administration to access the WebSphere Portal Administration pages.

118 User’s Guide

2. Select Portlets → Manage Portlets.

3. Find the RCP Portlet - Generic portlet, select it, and click Copy.

4. Select the copied portlet from the list of portlets, and then click Modify

parameters.

5. Click Set title for selected locale, then type EO_OrderEntry_Sample_Portlet

in the Title field, and click OK.

6. For each of the following parameters and values, type the parameter and

value into the pair of fields to the left of the Add button, and then click Add.

Parameter Value

id.Feature1 com.ibm.rcp.platform.feature



id.Feature2 com.ibm.rcp.eclipse.platform.feature

version.Feature2 3.0.0.2


id.Feature3 com.ibm.rcp.db2j.feature



id.Feature4 com.ibm.rcp.j2ee.feature



id.Feature5 com.ibm.rcp.pagebuilder.feature



id.Feature6 com.ibm.rcp.provisioning.feature



id.Feature7 com.ibm.rcp.security.feature



id.Feature8 com.ibm.workplace.credentialstore.feature



id.Feature9 com.ibm.workplace.platform.feature



id.Feature10 com.ibm.workplace.util.feature



id.Feature11 com.ibm.rte.feature



Chapter 11. The Enterprise Offering runtime environment 119

Parameter Value

id.Feature12 com.ibm.rcp.security.sso.feature



id.Feature13 com.ibm.rcp.eclipse.emf.feature



id.Feature14 com.ibm.rcp.eclipse.gef.feature



id.Feature15 com.ibm.rcp.eclipse.xsd.feature



id.Feature16 com.ibm.sdo.jdbcmediator.feature



id.Feature17 com.ibm.workplace.provisioned.feature



id.Feature18 com.ibm.esupport.client.lwp.feature



id.Feature19 com.ibm.db2e.feature



id.Feature20 com.ibm.pvc.util.feature



id.Feature21 com.ibm.osg.service.metatype.feature



id.Feature22 com.ibm.osg.service.cm.feature



id.Feature23 com.ibm.osg.service.log.feature



id.Feature24 com.ibm.mobileservices.isync.feature



id.Feature25 com.ibm.mqe.jms.feature


120 User’s Guide

Parameter Value


id.Feature26 com.ibm.mqe.feature



id.Feature27 com.ibm.pvc.jms.feature



id.Feature28 com.ibm.osg.service.useradmin.feature



id.Feature29 com.ibm.pvcws.osgi.feature



id.Feature30 com.ibm.eswe.preference.feature



id.Feature31 com.ibm.osg.webapp.feature



id.Feature32 com.ibm.pvc.servlet.feature



id.Feature33 com.ibm.pvc.webcontainer.feature



id.Feature34 com.ibm.pvc.webhttpservice.feature



id.Feature35 com.ibm.eswe.workbench.feature



id.Feature36 com.ibm.pvc.eo.feature_5.8.1.1



id.Feature37 com.ibm.eswe.orderentry.bin



7. Click Save and return to the Manage Portlets pane.

8. Click Access → Resource Permissions → Portlets.

9. Search for the portlet you created, then click the Assign Access key icon.



11. Check All authenticated portal users, and then click OK. Click Done, then

click OK to return to the portlet search results.

Creating a WebSphere Portal page for the Order Entry sample

Create a WebSphere Portal page to contain the portlet that requires the Enterprise

Offering platform plug-ins and set the page content to be RCPML.

To create a WebSphere Portal page for the Order Entry sample:

1. From the IBM WebSphere Administration pages, click Portal User Interface,

and then select Manage Pages.


3. Click the returned WorkplaceRCPPages page, then click the Edit icon to open

the Edit layout page.



and close the page.


6. Click New page. Name the page EOOrderEntryApplication.

7. Select the one column layout option.



Note: A warning is displayed that says the page has been created, but is not

included in page navigation. You may ignore this warning because the

page was created under the Content Root and not under My Portal.

9. Create a custom name for the page in case you want to write an XMLAccess

script later to retrieve the page, by clicking Portal Settings → Custom Unique

Names → Pages, and in the Search for field, type EOOrderEntryApplication,

and then click Search to find the page you just created.

10. Click the Edit icon

on the right side of the page returned by the search

and type lwp.RCP Order entry as the unique custom name, and then click

OK.


WorkplaceRCPPages, find the EOOrderEntryApplication page, and click the

Edit icon

.

12. Click Add portlets and search on EO_OrderEntry_Sample_Portlet to find and

select the portlet you created to add it to the page, and then click Done.

Using XML Access to provision the Enterprise Offering

components

You can also use the WebSphere Portal XML Access interface to programmatically

create a portlet and page that provision the Enterprise Offering features to the

client.

To use XML Access:


such as D:\temp.

122 User’s Guide

2. Copy the add_eoorderentry_portlets.xml and add_eoorderentry_page.xml files

from the \lwpapi25\WCT\samples\deploy\xmlaccess directory on your local

machine to the temporary directory you just created on the WebSphere Portal

server.

The add_eoorderentry_portlets.xml file is a simple XMLAccess input file that

contains tags that tell WebSphere Portal to create a portlet that represents the

Enterprise Offering runtime environment’s default view, and the

add_eoorderentry_page.xml file is a simple XMLAccess input file that contains

tags that tell WebSphere Portal to create a page with a unique name of

lwp.RCP Order entry, which represents the Enterprise Offering runtime

environment’s perspective.


directory and run the XMLAccess utility:

xmlaccess -in D:\temp\add_eoorderentry_portlets.xml





Workplace server.

4. From the same WebSphere Portal server’s \bin directory run the XMLAccess

utility:

xmlaccess -in D:\temp\add_eoorderentry_page.xml





Workplace server.


124 User’s Guide

Appendix A. IBM Workplace-specific information

The information in this section applies specifically to building applications for the

IBM Workplace rich client specifically. Many of the topics link to topics in the main

document that provide more information.

IBM Workplace rich client provisioning process

When an administrator enables access to the IBM Workplace rich client, the IBM

Workplace server performs the following tasks:

v Adds a tab to the IBM Workplace user interface called Rich client, which

contains a download link from which you can download the client installer.

v Deploys Rich Client Markup Language (RCPML) support to WebSphere Portal

by adding rcpml folders containing source files to the screens, skins, and themes

folders under the WebSphere Portal wps.ear\wps.war directory.

v Creates an Eclipse update site on the IBM HTTP Server, which is included with

WebSphere Portal. The Eclipse update site is a directory from which updates to

plug-ins and features can be downloaded to client machines.

IBM Workplace Collaboration Services APIs

You can call all of the IBM Workplace Collaboration Services APIs from the client

as remote services. To do so, you must install the IBM Workplace Collaboration

Services API EAR file and other supporting files on the server. See ″Installing the

IBM Workplace Collaboration Services API Toolkit runtime files on the IBM

Workplace Server″ in the IBM Workplace Collaboration Services API Toolkit User’s

Guide for more details on how to set this up. You also must provision the

com.ibm.rcp.workplace.api plug-in and com.ibm.rcp.workplace.api.feature feature

to the client machine on which you are doing your development work.

In addition to calling remote services, you can implement the following IBM

Workplace Collaboration Services on the client:

v Document library

v Mail

Note: This release of the toolkit does not support the use of the calendar service

API on the client.

The code to enable these services on the client is packaged in the following JAR

files and provided to the client in the com.ibm.workplace.api plug-in:

v lwpapi25_plugin.jar

v lwpapi25_wct.jar

The IBM Workplace Collaboration Services APIs are packaged for deployment in a

feature called com.ibm.workplace.api.feature.

Related tasks

“Using the document library service API” on page 127

“Using the mail service API” on page 130


Deploying a client application that uses server APIs

To deploy a client application that uses IBM Workplace Collaboration Services

APIs:

1. Install the supporting JAR files on the Eclipse update site on WebSphere Portal

by copying the following file from the

lwpapi25\wct\applications\eclipse\updatesite\plugins directory to the


com.ibm.workplace.api_2.5.0.jar

and copying the following file from the

lwpapi25\wct\applications\eclipse\updatesite\features directory to the


com.ibm.workplace.api.feature_2.5.0.jar


locate, backup, and edit the site.xml file to include a feature tag for the IBM

Workplace Collaboration Services API feature. The site.xml tag registers the

update features.

The following is example code that adds the IBM Workplace Collaboration

Services API feature tag as an entry after the other feature tags in the site.xml

file:

<feature

url="features/com.ibm.workplace.api.feature_2.5.0.jar"

id="com.ibm.workplace.api.feature"

version="2.5.0">


</feature>

Save the site.xml file.

3. See “Deploying an application” on page 20 for information on deploying an

application. When you create a portlet to represent the application you are

building which uses the IBM Workplace Collaboration Services APIs, specify

the following features as being required for that application: by adding the

following parameters to the portlet:

v com.ibm.workplace.api.feature

v com.ibm.lwp.wct.mymailcommon.feature

v com.ibm.pdm.feature

v com.ibm.workplace.cai.ui.feature

You can indicate that these features are required by adding the following

parameters to the portlet:


id.Feature<ID1> com.ibm.workplace.api.feature

version.Feature<ID1> 2.5.0

match.Feature<ID1> compatible

id.Feature<ID2> com.ibm.lwp.wct.mymailcommon.feature



id.Feature<ID3> com.ibm.pdm.feature



id.Feature<ID4> com.ibm.workplace.cai.ui.feature

126 User’s Guide




where you specify the number of the <ID1> through <ID4> features based on

how many features your application already requires.

4. Restart the client and accept the available updates.

Enabling an application to use server-side APIs

After you accept the available updates to the client, the client installs a new

com.ibm.workplace.api.feature to the client machine in the

<workspace_home>\applications directory.

To enable an application to use the IBM Workplace Collaboration Services APIs

that are supported on the rich client:

1. Create a LINK file with the following name:

com.ibm.workplace.api-feature.link

2. Add to the LINK file one entry, called ″path,″ and set it equal to the absolute

path of the IBM Workplace Collaboration Services API feature. For example:

path=C:/Documents and Settings/<username>/IBM/RCP/<rich client

instance ID>/<username>/applications/com.ibm.workplace.api.feature

Do not include trailing whitespace at the end of the path.

3. Register the link extension with the client by adding the link file to the

<client_home>\RCP\eclipse\links directory. For example:

C:\Program Files\IBM\Workplace rich client

eclipse

features

jre

links

com.ibm.workplace.api-feature.link

plugins

4. In Eclipse, select Window → Preferences to open the Preferences window.

5. Expand Plug-in Development and click Target Platform to see the

<client_home> directory specified in the Location field.

For example, if you are running Windows and accepted the defaults during

installation, the Location field would contain:


6. Click Reload to parse the plug-ins and refresh the target platform so it includes

the plug-ins you added.

7. You are now ready to create and test plug-ins that use IBM Workplace

Collaboration Services APIs.

Related tasks

“Using the document library service API”

“Deploying an application” on page 20

Using the document library service API

You can use the document library service API provided with the IBM Workplace

Collaboration Services API Toolkit to manage a document library on the client.

Keep the following things in mind when managing a library:

Appendix A. IBM Workplace-specific information 127

v The IBM Workplace Collaboration Services APIs use a model that depends on

factories that create data and services. The FactoryCreator class creates these

factories.

v Use an appropriate service and data factory for the task you want to perform.

For example, to manage the contents of a document library, use the

DocumentLibraryService and the DocumentFactory.

v When you make a request to the document library service, it provides a

snapshot of the current state of the library. Before you implement an action that

requires current document library state information, you must explicitly retrieve

the latest information from the library.

You must complete the steps in “Deploying a client application that uses server

APIs” on page 126 before you can complete this procedure.

To use the Document Library Service API:

1. Import the Workplace API plug-in into your plug-in by specifying it as a

dependency. The plugin.xml file for your plug-in should include it with the

following code:

<requires>

...

<import plugin="com.ibm.workplace.api"/>

</requires>

2. In the class you write to manage the document library using the API, import

the appropriate supporting API classes in the following packages:

import com.ibm.workplace.api.common.data.*;

import com.ibm.workplace.api.common.exception.*;

import com.ibm.workplace.api.document.data.*;

import com.ibm.workplace.api.document.service.*;

import com.ibm.workplace.api.factory.*;

3. In the code you write, get the document service by creating a ServiceFactory,

and then a DocumentLibraryService. Get a document factory by creating a

DocumentFactory object. For example:

// Create a document library service

ServiceFactory sf = FactoryCreator.createServiceFactory();

DocumentLibraryService dls = sf.createDocumentLibraryService();

// Create a document factory

DocumentFactory df = FactoryCreator.createDocumentFactory();

4. You can use the DocumentLibraryService.getLibrayDescriptions() method to

return the ID of a document library. For example:

String libraryId = null;

DataObjectList libraryDescriptions =

dls.getLibraryDescriptions();

List descriptions = libraryDescriptions.getObjects();

Iterator descriptionIterator = descriptions.iterator();

while (descriptionIterator.hasNext())

{

DocumentLibraryDescription dld =

(DocumentLibraryDescription) descriptionIterator.next();

String name = dld.getName();

if (name!=null && name.equals("testLibrary"))

{

libraryId = dld.getId();

break;

}

}

128 User’s Guide

5. You can use the DocumentLibraryService.getEntry() method to return an

individual folder or document you specify by passing a folder or document ID

to the method. For example, to get a folder and all its contents in the folder

hierarchy:

DocumentRetrievalOptions retrievalOptions =

df.createDocumentRetrievalOptions();

retrievalOptions.setDescendantDepth(DocumentRetrievalOptions.DEPTH_ALL);

retrievalOptions.setIncludeDocumentContent(true);

retrievalOptions.setRetrieveCompleteMembers(true);

String libraryId = "..."; // See Step 4.

String folderId = "/folder";

DocumentLibraryEntry dle =

dls.getEntry(libraryId,folderId,retrievalOptions);

DocumentFolder folder = (DocumentFolder) dle;

or to get a document:

DocumentRetrievalOptions retrievalOptions =

df.createDocumentRetrievalOptions();

retrievalOptions.setDescendantDepth(DocumentRetrievalOptions.DEPTH_SELF);

retrievalOptions.setIncludeDocumentContent(true);

retrievalOptions.setRetrieveCompleteMembers(true);

String libraryId = "..."; // See Step 4.

String documentId = "/folder/document.txt";

DocumentLibraryEntry dle =

dls.getEntry(libraryId,documentId,retrievalOptions);

Document document = (Document) dle;

6. You can update a folder or document using the

DocumentLibraryService.updateEntry() method. For example, to update the

folder that was retrieved in the previous example, use the following code:

folder.setDescription("Updated folder description");

dls.updateEntry(folder);

To update the document that was retrieved in the previous example, use the

following code:

byte[] content = document.getContent();

int contentLength = content.length;

byte[] updatedContent = new byte[contentLength+4];

for (int i=0; i<contentLength; i++)

{

updatedContent[i] = content[i];

}

updatedContent[contentLength] = ’ ’;

updatedContent[contentLength+1] = ’1’;



document.setContent(updatedContent);

dls.updateEntry(document);

7. You can create a new folder or document using the

DocumentLibraryService.addEntry() method. For example, to create a new

folder:

DocumentFolder subfolder = df.createDocumentFolder();

subfolder.setLibraryId("...");

subfolder.setParentFolderId("/folder");

subfolder.setName("subfolder");

subfolder.setDescription("This is a test subfolder");

dls.addEntry(subfolder);

To create a new document:

Document doc = df.createDocument();

doc.setLibraryId("...");

doc.setParentFolderId("/folder");

doc.setName("document.txt");


doc.setDescription("This is a test document");

byte[] content = {’t’,’h’,’i’,’s’,’ ’,’i’,’s’,’ ’,’a’,’ ’,’t’,’e’,’s’,’t’};

doc.setContent(content);

dls.addEntry(doc);

8. You can delete a folder or document using the

DocumentLibraryService.deleteEntry() method. For example, to delete a folder:

String libraryId = "...";

String folderId = "/folder/subfolder";

dls.deleteEntry(libraryId,folderId);

or to delete a document:

String libraryId = "...";

String docId = "/folder/document.txt";

dls.deleteEntry(libraryId,docId);

Related concepts

“IBM Workplace Collaboration Services APIs” on page 125 Related tasks

“Enabling an application to use server-side APIs” on page 127

Using the mail service API

You can use the mail service API provided with the IBM Workplace Collaboration

Services API Toolkit to manage a mailbox on the client. Keep the following things

in mind when managing a mailbox:

v The IBM Workplace Collaboration Services APIs use a model that depends on

factories that create data and services. The FactoryCreator class creates these

factories.

v Use an appropriate service and data factory for the task you want to perform.

For example, to manage the contents of a mailbox, use the MailService and the

MailFactory.

v When you make a request to the mail service, it provides a snapshot of the

current state of the mailbox. Before you implement an action that requires

current mailbox state information, you must explicitly retrieve the latest

information from the mailbox.

You must complete the steps in “Deploying a client application that uses server

APIs” on page 126 before you can complete this procedure.

To use the mail service API:

1. Import the Workplace API plug-in into your plug-in by specifying it as a

dependency. The plugin.xml file for your plug-in should include it with the

following code:

<requires>

...

<import plugin="com.ibm.workplace.api"/>

</requires>

2. In the class you write to manage the document library using the API, import

the appropriate supporting API classes in the following packages:

import com.ibm.workplace.api.common.data.*;

import com.ibm.workplace.api.common.exception.*;

import com.ibm.workplace.api.mail.data.*;

import com.ibm.workplace.api.mail.service.*;

import com.ibm.workplace.api.factory.*;

130 User’s Guide

3. In the code you write, get the mail service by creating a ServiceFactory, and

then a MailService. Get a mail factory by creating a MailFactory object. For

example:

// Create a mail service

ServiceFactory sf = FactoryCreator.createServiceFactory();

MailService ms = sf.createMailService();

// Create a mail factory

MailFactory mf =

FactoryCreator.createMailFactory();

4. You can use the MailService.sendMessage() method and the MailMessage class

to send an email.

For example:

MailMessage mailMessage = mf.createMailMessage();

List toList = mailMessage.getTo();

toList.add("[email protected]");

List ccList = mailMessage.getCc();

ccList.add("[email protected]");

List bccList = mailMessage.getBcc();

bccList.add("[email protected]");

mailMessage.setSender("[email protected]");

mailMessage.setSubject("Details for the new project");

String msgText = "This is the body of the message";

mailMessage.setBodyText(msgText);

ms.sendMessage(mailMessage,null);

Related concepts

“IBM Workplace Collaboration Services APIs” on page 125

The IBM Workplace personality

The layout of your application is defined by a perspective, which is the Eclipse

equivalent of a window. You set the perspective you want the IBM Workplace rich

client to use by specifying a personality. The personality of an application defines

the framework the platform uses to determine what perspectives, menus, toolbars,

action bar items, and status line controls display when the application starts, as

well as what services are available and what sequence of events or what life cycle

should be applied to the objects associated with that application.

The client provides a default IBM Workplace personality. In order for applications

to plug into the IBM Workplace rich client environment, have a consistent look and

feel with other rich client offerings, be available from the Switcher bar, and

participate seamlessly with the life cycle events of the platform, you must specify

the IBM Workplace personality. The Switcher bar is a vertical bar on the left side of

the client window that lists the available applications, each represented by an icon,

from which users can select the service they want to start. You instruct the client to

start up using the IBM Workplace rich client personality by doing one of the

following actions:

v Append the following parameter to the rich client start command:

<client_home>\rcp\richclient -personality com.ibm.workplace.personality

v Edit the plugin_customization.ini file for your plug-in to include the following

key:

com.ibm.rcp.platform/DEFAULT_PERSONALITY_ID="com.ibm.workplace.personality"

where com.ibm.workplace.personality is the ID of the IBM Workplace personality.

Related tasks

“Creating an IBM Workplace personality” on page 132

“Retrieving user information” on page 132


“Contributing to the search bar menu” on page 133

“Creating a top-level menu” on page 134

Creating an IBM Workplace personality

If you are building an application to run on IBM Workplace, use an IBM

Workplace personality that you define through RCPML to specify the layout of

your application.

To create an IBM Workplace personality:

1. Define the views using the stub portlet and creating a portal page on the IBM

Workplace server.

2. Provision the client from the server. See the topic, ″Rich client installation and

configuration,″ in the IBM Workplace Collaboration Services information center.

3. Copy the cached RCPML in

<workspace_home>\.metadata\.plugins\com.ibm.rcp.pagebuilder to another

folder, such as c:\rcpml

4. In the Program Arguments field of the Eclipse runtime environment page, add

″-pbcache c:\rcpml.″ Now you can make edits to the local RCPML files to test

minor changes without having to repeat the provisioning process.

Related concepts

Chapter 3, “Designing an application layout,” on page 39

“The IBM Workplace personality” on page 131

Retrieving user information

The com.ibm.rcp.platform plug-in includes APIs that you can use to retrieve user

information such as the current user’s name and the URL of the currently specified

provisioning server.

To retrieve user information:

1. In the plugin.xml file for the plug-in from which you want to access user

information, specify the com.ibm.rcp.platform plug-in as a required plug-in:

<requires>

...

<plugin name="com.ibm.rcp.platform"/>

</requires>

2. In the code, import the com.ibm.rcp.platform.api.PlatformContext class.


3. To retrieve the current user’s name, use the getPlatformUserName method.

public static String getPlatformUserName() throws NoDataAvailableException {

}

4. To retrieve the provisioning URL, use the getPortalURL() method.

public static String getPortalURL() throws NoDataAvailableException {

}

Related concepts

“The IBM Workplace personality” on page 131

132 User’s Guide

Contributing to the search bar menu

You use the searchbarAdapters extension point to add a custom contribution to the

search menu that performs a customized search and displays its results in a

custom view. You can do the following:

v Populate the search menu with your custom contribution.

v Contribute code to perform a custom search that is triggered when the

corresponding menu action is selected.

v Display the search results in a custom view.

To add a custom search bar contribution:

1. In the plugin.xml file for your plug-in, import the com.ibm.rcp.ui.searchbar and

com.ibm.rcp.platform plug-ins.

<requires>

...

<import plugin="com.ibm.rcp.ui.searchbar"/>

<import plugin="com.ibm.rcp.platform"/>

</requires>

2. Also in the plugin.xml file, extend the searchbarAdapters extension point

defined in the com.ibm.rcp.ui.searchbar.api code and provide values for the

required attributes as tags.

<extension

point="com.ibm.rcp.ui.searchbar.api.searchbarAdapaters">

<adapter

class="com.ibm.acme.ui.searchbar.mySearchBarContribution"

label="%mySearchBarContrib.menulabel"

data="<user data variables passed to the class as parameters when called>">

id="<id that identifies this extension. For example,

com.ibm.acme.ui.searchbar.mySearchBarContribution>

</adapter>

</extension>

3. Write the code that defines the action you want the client to perform when

your search bar action is triggered in the mySearchBarContribution.java class.

Implement the ISearchDataAdapter interface in the class.

4. Specify the translation string for %mySearchBarContrib.menulabel in the

appropriate language .properties files for the plug-in.

Related concepts

“The IBM Workplace personality” on page 131 Related reference

“Search bar adapters extension point”

Search bar adapters extension point

Enables you to enable you to to add a custom contribution to the search menu that

performs a customized search and displays its results in a custom view.

com.ibm.rcp.ui.searchbar.searchbarAdapters

To extend the com.ibm.rcp.ui.searchbar.searchbarAdapters

extension point:

In the plugin.xml file of your searchbar plug-in, provide values for the following

attributes of the <adapter> tag:

v id -- Specifies a unique id for this search bar adapter.


v label -- Localized text to display as the search menu item contribution.

v class -- Fully qualified name of the Java class that implements the search bar

adapter.

v data -- User data values to pass as parameters to the class when it is called.

The following text is an example of plugin.xml file content that contributes a

custom contribution to the search menu:

<extension point="com.ibm.rcp.ui.searchbar.searchbarAdapters">

<adapter

label="%str.searchbar.tickets"

data="1"

class="com.ibm.rcp.demo.callcenter.core.actions.SearchTicketsAction"

id="com.ibm.rcp.example.SearchbarAdapter" />

</extension>

Related tasks

“Contributing to the search bar menu” on page 133

Creating a top-level menu

You can write code that performs a task by creating a menu item contribution. You

can enable users to start the task from a corresponding menu item in the user

interface by adding the menu item contribution to an existing menu. If you

implement an IBM Workplace personality, a set of top-level global menu items

automatically appear in the user interface. These include the File, Edit, View,

Actions, Tools, Windows, and Help menus. You can contribute a menu item that

displays at the top-level as well.

To create a new top-level menu:

1. Extend the org.eclipse.ui.actionSets extension point.

<extension point="org.eclipse.ui.actionSets">

<actionSet

label="com.ibm.pdm.superodc.calc.actionSet.menu"

visible="false"

id="com.ibm.pdm.superodc.calc.actionSet.menu">

2. Add a menu tag that specifies ″wctadditions″ for the value of the path

attribute.

<menu

label="%Insert"

path="wctadditions"

id="OSMCInsert">

3. Use a groupMarker tag to group actions together and reference the marker in

the menubarPath attribute of the following action tag.

<groupMarker

name="groupMarker_InsertBreak_One">

</groupMarker>

...

</menu>

<action

label="%Insert_InsertRows"

class="com.ibm.pdm.superodc.baseview.actions.CommonActions"

menubarPath="OSMCInsert/groupMarker_InsertBreak_One"

id="sc_InsertRows">

</action>

...

4. To add a submenu to the OSMCInsert menu, use a forward slash in the path

attribute value to distinguish between the main menu and the submenu.

134 User’s Guide

<menu

label="%Insert_InsertBreak"

path="OSMCInsert/groupMarker_InsertBreak_Two"

id="InsertBreak">

<separator

name="Types">

</separator>

</menu>

<action

label="%Insert_InsertBreak_InsertColumnBreak"

class="com.ibm.pdm.superodc.baseview.actions.CommonActions"

menubarPath="OSMCInsert/InsertBreak/Types"

id="sc_InsertColumnBreak">

</action>

Related concepts

“The IBM Workplace personality” on page 131 Related tasks

“Contributing to a menu” on page 64 Related reference

“IBM Workplace menu IDs”

IBM Workplace menu IDs

You 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. You can use these constants

to determine where you can display your action in the user interface.

The following table contains the top-level menu items that are consistent with

Eclipse menu items:

Constant value Reference in menu tag as

FILE_MENUID = ″file″/

*IWorkbenchActionConstants.M_FILE*/

path=″additions″ and id=″file″

EDIT_MENUID = ″edit″/

*IWorkbenchActionConstants.M_EDIT*/

path=″edit/<submenutitle>″ and

id=″<customString>″

WINDOW_MENUID = ″window″/

*IWorkbenchActionConstants.M_WINDOW*/

HELP_MENUID = ″help″/

*IWorkbenchActionConstants.M_HELP*/

id=″help″

The following table contains the IBM Workplace Collaboration Services-specific

top-level menu items:


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

The following table contains group markers for adding to menus and end groups:

Constant value Reference in menu tag as Use to

MB_ADDITIONS =

IWorkbenchActionConstants.

MB_ADDITIONS

path = ″additions″ Add top level group marker

contributions. For example:

path=″additions″ id=

″com.ibm.rcp.ui.viewmenu″

Or add contributions to top

level group markers. For

example: path=

″com.ibm.rcp.ui.toolsmenu/

additions″

id=″MyStatusMenu″>

ENDGROUP_SUFFIX =

″_end″

path = ″_end″ Specifies that a contribution

should appear at the end of

an existing menu.

MB_WCTADDITIONS =

″wctadditions″

path = ″wctadditions″ Add top level group marker

contributions after the tools

menu. For example:

path=″wctadditions″

id=″OSMWInsert″>

The following table contains the File menu group markers:

Constant value

FILE_NEW_GROUP = ″fileNewGroup″

FILE_OPEN_GROUP = ″fileOpenGroup″

FILE_OPENINNEWTAB_GROUP = ″fileOpenInNewTabGroup″

FILE_FOLDER_GROUP = ″fileFolderGroup″

FILE_MENU_GROUP = ″fileMenuGroup″

FILE_MENUADDITIONS_GROUP = ″fileMenuAdditionsGroup″

FILE_IMPORT_GROUP = ″fileImportGroup″;

FILE_EXPORT_GROUP = ″fileExportGroup″;

FILE_EXPORTASPDF_GROUP = ″fileExportAsPDFGroup″

FILE_PRINT_GROUP = ″filePrintGroup″

FILE_PRINTPREVIEW_GROUP = ″filePrintPreviewGroup″

FILE_PROPERTIES_GROUP = ″filePropertiesGroup″

FILE_PREFERENCES_GROUP = ″filePreferencesGroup″

FILE_EXIT_GROUP = ″fileExitGroup″

136 User’s Guide

The following table contains common File menu actions:

Constant value

FILE_CLOSE_ACTION_ID = ″com.ibm.rcp.ui.filemenu.close″

FILE_EXIT_ACTION_ID = ″com.ibm.rcp.ui.filemenu.exit″

FILE_PREFERENCES_ACTION_ID = ″com.ibm.rcp.ui.filemenu.preferences″

FILE_OPEN_ACTION_ID = ″com.ibm.rcp.ui.filemenu.open″

FILE_PRINT_ACTION_ID = ″com.ibm.rcp.ui.filemenu.print″

FILE_PRINTPREVIEW_ACTION_ID = ″com.ibm.rcp.ui.filemenu.printpreview″

FILE_PAGESETUP_ACTION_ID = ″com.ibm.rcp.ui.filemenu.pagesetup″

The following table contains the Edit menu group markers:

Constant value

EDITMENU_UNDO_GROUP = ″editmenuUndoGroup″

EDITMENU_GROUP1 = ″editmenuGroup1″



The following table contains the common Edit menu actions:

Constant value

EDIT_REDO_ACTION_ID = ″com.ibm.rcp.ui.editmenu.redo″

EDIT_UNDO_ACTION_ID = ″com.ibm.rcp.ui.editmenu.undo″

EDIT_CUT_ACTION_ID = ″com.ibm.rcp.ui.editmenu.cut″

EDIT_COPY_ACTION_ID = ″com.ibm.rcp.ui.editmenu.copy″

EDIT_PASTE_ACTION_ID = ″com.ibm.rcp.ui.editmenu.paste″

EDIT_FIND_ACTION_ID = ″com.ibm.rcp.ui.editmenu.find″

EDIT_DELETE_ACTION_ID = ″com.ibm.rcp.ui.editmenu.delete″

EDIT_SELECT_ALL_ACTION_ID = ″com.ibm.rcp.ui.editmenu.selectall″

EDIT_MOVETOFOLDER_ACTION_ID = ″com.ibm.rcp.ui.editmenu.movetofolder″

The following table contains the View menu group markers:

Constant value

VIEWMENU_GROUP1 = ″viewmenuGroup1″





VIEWMENU_MAXIMIZETAB_GROUP = ″viewmenuMaximizeTabGroup″


The following table contains common View menu actions:

Constant value

VIEW_SHOW_ACTION_ID = ″com.ibm.rcp.ui.viewmenu.show″

VIEW_SHOW_STATUSBAR_ACTION_ID = ″com.ibm.rcp.ui.viewmenu.show.statusbar″

VIEW_SHOW_PREVIEWPANE_ACTION_ID =

″com.ibm.rcp.ui.viewmenu.show.previewpane″

VIEW_SHOW_SEARCHBAR_ACTION_ID = ″com.ibm.rcp.ui.viewmenu.show.searchbar″

VIEW_SHOW_SWITCHERBAR_ACTION_ID =

″com.ibm.rcp.ui.viewmenu.show.switcherbar″

VIEW_SHOW_SWITCHERLABELS_ACTION_ID =

″com.ibm.rcp.ui.viewmenu.show.switcherlabels″

VIEW_SHOW_SIDEBAR_ACTION_ID = ″com.ibm.rcp.ui.viewmenu.show.sidebar″

VIEW_MAXIMIZECURRENTTAB_ACTION_ID =

″com.ibm.rcp.ui.viewmenu.maximizecurrenttab″

The following table contains the Actions menu group markers:

Constant value

ACTIONSMENU_GROUP1 = ″actionsmenuGroup1″

ACTIONSMENU_CANCEL_GROUP = ″actionsCancelGroup″

ACTIONSMENU_EDIT_GROUP = ″editGroup″

ACTIONSMENU_ACTIONS_GROUP = ″actionsGroup″

ACTIONSMENU_RESOLVECONFLICT_GROUP = ″resolveConflictGroup″

ACTIONSMENU_SLIDESHOW_GROUP = ″slideShowGroup″;



The following table contains the Tools menu group markers:

Constant value

TOOLSMENU_GROUP1 = ″toolsmenuGroup1″

TOOLSMENU_LIBRARY_GROUP = ″toolsmenuLibraryGroup″

The following table contains the Help menu group markers:

Constant value

HELP_ABOUT_ACTION_ID = ″com.ibm.workplace.client.common.ui.aboutaction″

BOOKMARKS_MENUID = ″bookmarks″

Determining available activities

An activity sets up associations between different tasks and the user interface

controls that trigger those tasks. You can create an activity or incorporate an

activity defined by another application plug-in into your application by specifying

the activity in the RCPML that defines the application. You can also determine

138 User’s Guide

what activities are activated for an application by reviewing the RCPML for the

applications that you provision from the server.

To determine what activities are available to an application:

1. Provision the plug-ins and features for the desired client applications to your

client machine.

2. In a text editor, open the -lwp-myworkplace.xml file from the

<workspace_home>\.metadata\.plugins\com.ibm.rcp.pagebuilder\config

directory of the client machine.

3. Search for the following text to find the activities available for you to

incorporate into your application:

<param name="activities">

The code package that defines the activity is identified within the param tag.

For example, the <param

name=″activities″>com.ibm.workplace.demo.callcenter.activity</param> tag

identifies the com.ibm.workplace.demo.callcenter.activity code package.

4. Look at the plugin.xml files for the plug-ins in the search results returned to

determine which activities are available for use.

Related concepts

“Activities” on page 46

Remote object access

IBM Workplace rich client products must call Enterprise JavaBean (EJB) code on

the server to perform certain tasks. An Object Request Broker (ORB), whose basic

function is to pass a method invocation request to the correct remote object and

return the result to the caller, is used to make remote calls from the client. To

support remote calls, the ORB must be able to identify and locate objects, handle

connections from an invoker and the data returned from methods. Internet

Inter-ORB Protocol (IIOP) is the protocol through which ORBs communicate with

each other. Using IIOP, an ORB may request method invocations from a remote

object.

Related concepts


“Accessing a remote server over IIOP”

Accessing a remote server over IIOP

When a user first starts an IBM Workplace rich client product, the client

automatically creates a local credential store for the user and adds a Workplace

credential to it. The platform then automatically uses that credential to log onto the

server over IIOP. The security APIs provided with the com.ibm.rcp.security.core

plug-in enable you to log in to an alternate remote server over IIOP

programmatically.

To programmatically access a remote server over IIOP:

1. Import the required supporting packages:

...

import com.ibm.rcp.security.api.iiop.login.IOrbLoginContext;

import com.ibm.rcp.security.api.iiop.login.IOrbLoginContextFactory;

...


2. Access the sales.devsite.acme.com server, to which the client already has a

client ORB connection using the login() method:

public void loginTry( ) {

IOrbLoginContext loginContext = IOrbLoginContextFactory.INSTANCE.create( );

assertNotNull( "OrbLoginContext is null!", loginContext);

try {

loginContext.login( "sales.devsite.acme.com", 2810,


}




}

}






if ( cb[i] instanceof NameCallback) {

((NameCallback)cb[i]).setName( "wpsadmin");

}

else if ( cb[i] instanceof PasswordCallback) {



}

else {

throw new UnsupportedCallbackException( cb[i]);

}

}

}

};


}

3. Retrieve the user name of the currently authenticated user from the WebSphere

Application Server security context using the getUniqueSecurityName()

method:

protected void getUniqueSecurityNameTry( ) {

IOrbLoginContext ctx = IOrbLoginContextFactory.INSTANCE.create( );

assertNotNull( "OrbLoginContext is null!", ctx);

try {

ctx.login( "sales.devsite.acme.com", 2810,


if ( ctx.isLoggedIn( )) {

String name = ctx.getUniqueSecurityName( );

assertNotNull( "Unique name is null!", name);

}

}




}

}

Implementing database support

The IBM Workplace Client Technology platform supports creating, accessing, and

migrating database data from and to the client. The client supports the use of any

JDBC-compliant database. The toolkit includes a sample IBM Cloudscape database

implementation and plug-ins that demonstrate how to access a database from the

client. Your applications do not have to use an IBM Cloudscape database.

140 User’s Guide

The toolkit includes the IBM Cloudscape database, version 10, which is the

database that is included with IBM Workplace Collaboration Services 2.5, because

it provides the following advantages:

v Pure Java relational database.

v Requires no administration; put the JAR file (db2j.jar) on the client system and

use it.

v Has a size of approximately 2 MB.

v The database is embeddable.

v Fully supports SQL-92.

v Provides its own tools to simplify data manipulation.

The IBM Workplace Client Technology platform adds to the standard Cloudscape

database the capability of encrypting access to the database using keys stored in

the local credential store.

Related tasks

“Initializing database creation”

“Accessing an encrypted database” on page 144

Initializing database creation

Use standard Java and Eclipse plug-ins to initialize a database on the client at the

time that the database is needed and not before. The following code is taken from

the Call Center sample application DbCreateUtil.java class and is specific to the

Call Center application database, but can be used as a model for how to initialize

the database.

To initialize a database:

1. In the code that intializes the database, import the following standard Java and

Eclipse packages:

import java.io.BufferedReader;

import java.io.FileReader;

import java.sql.Connection;

import java.sql.SQLException;

import java.util.ArrayList;

import java.util.Iterator;

import java.util.StringTokenizer;

import org.eclipse.core.runtime.IProgressMonitor;

import org.eclipse.jface.dialogs.ProgressMonitorDialog;

import org.eclipse.jface.operation.IRunnableWithProgress;

import org.eclipse.jface.preference.IPreferenceStore;

import org.eclipse.swt.widgets.Display;

import org.eclipse.swt.widgets.Shell;

import org.eclipse.ui.PlatformUI;

2. The code calls out some constant values, uses exception handlers, and accesses

a preference store that are defined by other components of the call center

application, so include the following packages also:

import com.ibm.workplace.demo.callcenter.CallCenterPlugin;

import com.ibm.workplace.demo.callcenter.Constants;

import com.ibm.workplace.demo.callcenter.exception.ExceptionHandler;

3. Check the preference store to see if a database has already been created.

public class DbCreateUtil {

public static void initDatabases() throws Exception {

IPreferenceStore store =

CallCenterPlugin.getDefault().getPreferenceStore();

CallCenterPlugin.getLogger().fine("Checking to see if callcenter


databases need to be created");

for (int i = 0; i < Constants.ALL_DBS.length; i++) {

String db = Constants.ALL_DBS[i];

String dbname =

CallCenterPlugin.getRequiredResourceString(db);

CallCenterPlugin.getLogger().fine("Checking to see if

the " + dbname + " database exists");

if (store.getBoolean(dbname)) {

CallCenterPlugin.getLogger().fine("The " +

dbname + " database does not need to be created");

} else {

CallCenterPlugin.getLogger().fine(

"The " + dbname + " database will be created

because it does not exist");

if (DbCreateUtil.createDatabase(db)) {

store.setValue(dbname, true);

CallCenterPlugin.getLogger().fine("The creation of the "

+ dbname + " database was successfull");

}

}

}

}

4. If a database does need to be created, create it using the createDatabase()

method. This method initializes the database by executing all the SQL

statements in an external file.

private static boolean createDatabase(String db)

throws Exception {

/** Get the resourced database name */

final String dbname =

CallCenterPlugin.getRequiredResourceString(db);

final String scriptFile =

CallCenterPlugin.getRequiredResourceString(db + ".script");

String encryptSetting =

CallCenterPlugin.getRequiredResourceString(db + ".encrypt");

/** Encypt the database if no encryption value is specified.*

*/

final String encrypt =

(encryptSetting.equals("true") ||

encryptSetting.equals("false")) ? encryptSetting : "true";

// search is invoked from non-UI thread

Display display = PlatformUI.getWorkbench().getDisplay();

display.syncExec(new Runnable() {

public void run() {

try {

new ProgressMonitorDialog(new Shell()).run(true,

false, new IRunnableWithProgress() {

public void run(IProgressMonitor pm) {

try {

pm.beginTask(CallCenterPlugin.

getRequiredResourceString

("str.dialog.createdatabase")

+ " " + dbname, IProgressMonitor.UNKNOWN);

pm.subTask(CallCenterPlugin.

getRequiredResourceString

("str.dialog.retrievingschema"));

ArrayList dbcommands = getDbCommands(scriptFile);

pm.subTask(CallCenterPlugin.

getResourceString("str.dialog.buildingdb"));

if (dbcommands != null && !dbcommands.isEmpty()) {

DatabaseUtil.loadDbDriver();

Connection conn =

java.sql.DriverManager.getConnection("jdbc:wct:"

+ dbname + ";create=true;encryption=" + encrypt);

conn.setAutoCommit(false);

142 User’s Guide

if (conn != null) {

for (Iterator iter =

dbcommands.iterator(); iter.hasNext();) {

try {

String sql = (String)iter.next();


"Executing the following creation SQL

command for " + dbname + ":/n" + sql);

conn.createStatement().execute(sql);


"SQL command executed successfully");

} catch (SQLException e) {


"SQL command failed");

conn.rollback();

conn.close();

pm.subTask(CallCenterPlugin

.getResourceString(

"str.dialog.dbcreationfailure"));

throw e;

}

}

conn.commit();

conn.close();

pm.subTask(CallCenterPlugin

.getResourceString

("str.dialog.dbcreationsuccess"));

}

}

pm.done();


ExceptionHandler.handleException(ex, true);

}

}

});


ExceptionHandler.handleException(ex, true);

}

}

});

return true;

}

private static ArrayList getDbCommands(String scriptFile)

throws Exception {

ArrayList dbCommands = new ArrayList();

String buffline = "";

StringBuffer sql = new StringBuffer();

String temp =

CallCenterPlugin.getDefault().getBundle().getLocation() +

scriptFile;

FileReader file = new FileReader(temp.substring(8));

BufferedReader buff = new BufferedReader(file);

while (buffline != null) {

buffline = buff.readLine();

sql.append(buffline);

}

StringTokenizer st = new StringTokenizer(sql.toString(), ";");

while (st.hasMoreTokens()) {

String token = st.nextToken();

CallCenterPlugin.getLogger().fine(token);

if (!(token.equals("") || token.equals("null") ||

token == null)) {

dbCommands.add(token);

}


}

return dbCommands;

}

}

Accessing an encrypted database

A database designed for the IBM Workplace Client Technology platform can be

encrypted to secure the data contained within it. Client databases are encrypted

with a key derived from the password of the authenticated user. Developers can

access an encrypted IBM Cloudscape database during design using the

standards-based Java Database Connectivity (JDBC) connector driver that the client

provides in the com.ibm.workplace.database.db2j.jdbc plug-in. The client JDBC

driver is an extension of the standard IBM Cloudscape JDBC driver that adds to its

standard functionality the capability of connecting to an encrypted database. 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 an encrypted IBM Cloudscape database using the client JDBC driver,

perform the following steps:

1. Include the com.ibm.workplace.database.db2j.jdbc plug-in as a required plug-in

in the plugin.xml file for your application plug-in.

<requires>

<import plugin="com.ibm.workplace.database.db2j.jdbc" />

...

</requires>

2. Write a class that contains code to connect to the database. If you want to

enable the user to start the connection using a menu action, define an action to

connect to the database by using the IWorkbenchWindowActionDelegate.

Import the following classes:

import org.eclipse.ui.IWorkbenchWindow;

import org.eclipse.ui.IWorkbenchWindowActionDelegate;

...

3. When you write the action code, implement

IWorkbenchWindowActionDelegate. Include a constructor in the class.

public class MyJDBCDriverAction

implements IWorkbenchWindowActionDelegate {


public MyJDBCDriverAction() {

}

4. Also include a run() method. In it, specify a connection uniform resource

identifier (URI) to load the JDBC driver. The connection URI should be

formatted as follows:

jdbc:wct:<database_name>;<connection_property1>;

<connection_property2>

where the connection_property values can be one of the following:

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 instance

144 User’s Guide

should be unloaded from the Java virtual machine. The default value is

false. This property should only be used when you want the

application to shut down.

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. When this property is set to true

and is specified in a connection URI with the create value set to true,

the combination instructs the JDBC driver to create an encrypted

database if one does not exist.For example, the code that accesses the ″mydatabase″ database and creates it if

it does not exist would be written as follows:

public class MyJDBCDriverAction

implements IWorkbenchWindowActionDelegate {


...

public void run(IAction action) {

try {

// load the JDBC Driver

Class.forName("com.ibm.workplace.db2j.jdbc.WCTDB2jDriver", true,

this.getClass().getClassLoader()).newInstance();

// Connect the database ’mydatabase’, create it if it doesn’t exist yet

java.sql.Connection connection =

java.sql.DriverManager.getConnection("jdbc:wct:mydatabase;create=true");

// read the Meta information to get the Database Type

String databaseProductName =

connection.getMetaData().getDatabaseProductName();

// close the connection

connection.close();

...

}

}

5. Be sure to include the action definition in the plugin.xml file for the plug-in

that defines the action. The following code is sample plugin.xml code to define

and action to display in the menu:

<extension

point="org.eclipse.ui.actionSets">

<actionSet

label="Sample Action Set"

visible="true"

id="com.ibm.workplace.sample.MyJDBCDriver.actionSet">

<menu

label="Sample &Menu"

id="sampleMenu">

<separator

name="sampleGroup">

</separator>

</menu>

<action

label="&Sample Action"


class="com.ibm.workplace.sample.actions.MyJDBCDriverAction"

tooltip="Connect to a database"

menubarPath="sampleMenu/sampleGroup"

toolbarPath="sampleGroup"

id="com.ibm.workplace.sample.actions.MyJDBCDriverAction">

</action>

</actionSet>

</extension>


146 User’s Guide

Appendix B. 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 grant 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.

For license inquiries regarding double-byte (DBCS) information, contact the IBM

Intellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia Corporation

Licensing

2-31 Roppongi 3-chome, Minato-ku

Tokyo 106-0032, Japan

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.


Licensees of this program who wish to have information about it for the purpose

of enabling: (i) the exchange of information between independently created

programs and other programs (including this one) and (ii) the mutual use of the

information which has been exchanged, should contact:

IBM Corporation

Office 4360

One Rogers Street

Cambridge, MA 02142

U.S.A.

Such information may be available, subject to appropriate terms and conditions,

including in some cases, payment of a fee.

The licensed program described in this information and all licensed material

available for it are provided by IBM under terms of the IBM Customer Agreement,

IBM International Program License Agreement, or any equivalent agreement

between us.

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.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which

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

Trademarks

The following terms are trademarks of International Business Machines

Corporation in the United States, other countries, or both:

IBM

Cloudscape

DB2

Everyplace

Lotus

Lotus Notes

Notes

Rational

WebSphere

Workplace

Workplace Client Technology

Workplace Managed Client

Workplace Messaging

148 User’s Guide

Intel, Intel Inside (logos), MMX, and Pentium are trademarks of Intel Corporation

in the United States, other countries, or both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of

Microsoft Corporation in the United States, other countries, or both.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the

United States, other countries, or both.

Linux is a trademark of Linus Torvalds in the United States, other countries, or

both.

UNIX is a registered trademark of The Open Group in the United States and other

countries.

Other company, product, or service names may be trademarks or service marks of

others.

Appendix B. Notices 149

150 User’s Guide

��

Part Number: C80P6IE

Program Number: 5724i2

Printed in USA

G210-1984-00

(1P)

P/

N: C8

0P6I

E