IBM Workplace Client Technology API Toolkit

Transcription

1 IBM Workplace Client Technology API Toolkit Version 2.5 User s Guide G

2

3 IBM Workplace Client Technology API Toolkit Version 2.5 User s Guide G

4 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 All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Contents Chapter 1. IBM Workplace Client Technology API Toolkit User s Guide.. 1 The IBM Workplace Client Technology API Toolkit.1 System requirements IBM Workplace Client Technology API Toolkit roadmap IBM Workplace Client Technology Core components Core platform component User interface component Utilities component Security component Rich text editor component Server-managed client components Replication support component Offline support component Chapter 2. Building applications for the platform Setting up the development environment Setting up Eclipse Setting up the Eclipse development environment 8 Setting up the Rational Application Developer environment Configuring a Java Runtime Environment...9 Setting up the runtime environment Virtual machine arguments Building platform plug-ins and features Creating a view plug-in Adding a manifest file to a plug-in Creating a perspective Creating a personality class Packaging a plug-in as a feature Creating a manifest file for a feature Deploying the plug-in and feature Bundles and plug-ins Managing applications from a server Client application deployment Provisioning the client Initiating application updates Referencing provisioned rich client resources...37 Chapter 3. Designing an application layout Creating a custom personality Personalities extension point Personality Extension extension point Personality startup extension point Control set extension point Application look and feel Activities Chapter 4. Developing the application user interface Eclipse components used in the client Model View Controller architecture Using JFace to create adapter views Threading model Design patterns that support view-to-view communication Adding alerts AlertType extension point Accessing a Web address in the client browser...56 Accessing a Web address using an LTPA token 57 Action bars Creating an action bar Adding custom buttons to an action bar Adding editing functionality to an application...63 Contributing to a menu Implementing keyboard shortcuts Implementing preference pages Chapter 5. Securing a client application 69 IBM Workplace local credential store Logging in to the local credential store HTTP authentication support Logging in to an HTTP authenticated application 72 Single sign-on with the operating system Configuring Microsoft Windows operating system single sign-on Configuring Linux operating system single sign-on Chapter 6. Calling a remote Enterprise JavaBean Building a deployable remote Enterprise JavaBean 77 Installing an Enterprise JavaBean Starting the remote Enterprise JavaBean Calling a remote Enterprise JavaBean Chapter 7. Synchronizing client application data Implementing a custom synchronization engine..82 Sync services extension point Implementing the DB2 Everyplace Synchronization engine Chapter 8. Taking a component offline 89 Offline API Building offline-aware components Chapter 9. Reference information Coding tips and best practices Debugging an application in Eclipse Debugging applications remotely Plug-in, fragment, and feature naming conventions Logging Copyright IBM Corp iii

6 Adding Help to an application Client Java API documentation Client API Extension Points Chapter 10. Call Center and Samples applications Setting up the Call Center and Samples applications Adding the sample applications to the Eclipse update site Installing the sample features on WebSphere Portal Creating portal pages for the samples Using XML Access to provision the sample applications Defining access control levels for the samples 109 Adding parameters to the sample portal pages 110 Call center synchronization Call center preference pages Implementing the Call Center Enterprise JavaBean services FAQ document library Chapter 11. The Enterprise Offering runtime environment Setting up the Enterprise Offering runtime environment Adding the Order Entry sample to the Eclipse update site Provisioning the Enterprise Offering components Creating a WebSphere Portal page for the Order Entry sample Using XML Access to provision the Enterprise Offering components Appendix A. IBM Workplace-specific information IBM Workplace rich client provisioning process 125 IBM Workplace Collaboration Services APIs Deploying a client application that uses server APIs Enabling an application to use server-side APIs 127 Using the document library service API Using the mail service API The IBM Workplace personality Creating an IBM Workplace personality Retrieving user information Contributing to the search bar menu Creating a top-level menu Determining available activities Remote object access Accessing a remote server over IIOP Implementing database support Initializing database creation Accessing an encrypted database Appendix B. Notices Trademarks iv User s Guide

7 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 v v v v v v v com.ibm.rcp.offline.api com.ibm.rcp.platform.api com.ibm.rcp.rte.api com.ibm.rcp.security.api com.ibm.rcp.sync.api com.ibm.rcp.ui.alerts.api com.ibm.rcp.ui.browser.core com.ibm.rcp.ui.widgets.api Related concepts Chapter 1, IBM Workplace Client Technology API Toolkit User s Guide Copyright IBM Corp

8 System requirements The IBM Workplace Client Technology API Toolkit has been tested with the IBM Java 2 SDK 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: ; 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 IBM Workplace Client Technology 2 User s Guide Chapter 1, IBM Workplace Client Technology API Toolkit User s Guide, on page 1 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 application. The added value that

9 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

10 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: Plug-in name Public API package name 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: Plug-in name Public API package name com.ibm.rcp.ui.browser.core com.ibm.rcp.ui.browser. core.api Tasks you can perform with the plug-in Accessing a Web address in the client browser on page 56 4 User s Guide

11 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: Plug-in name Public API package name Tasks you can perform 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: Plug-in name Public API package name Tasks you can perform 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: Plug-in name Public API package name Tasks you can perform 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

12 Plug-in name Public API package name Tasks you can perform 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

13 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 Deploying an application on page Provisioning the client on page 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 2. Provision the client from an IBM Workplace server by logging into the IBM Workplace server at 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: 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 9 5. Perform the procedure, Configuring a Java Runtime Environment on page Complete the task, Setting up the runtime environment on page 10. Copyright IBM Corp

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

15 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

16 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

17 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: Chapter 2. Building applications for the platform 11

18 _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 Creating a custom personality on page 39 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

19 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 Packaging a plug-in as a feature on page Optional: Creating a manifest file for a feature on page 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 Chapter 2. Building applications for the platform 13

20 14 User s Guide 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 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.

21 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. Chapter 2. Building applications for the platform 15

22 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 Creating a custom personality on page 39 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

23 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: 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 Chapter 2. Building applications for the platform 17

24 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

25 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 Chapter 2. Building applications for the platform 19