IBM Workplace Software Development Kit

Transcription

1 IBM Workplace Software Development Kit Version 2.6 User s Guide G

2

3 IBM Workplace Software Development Kit Version 2.6 User s Guide G

4 Note Before using this information and the product it supports, read the information in Notices, on page 103. First Edition (January, 2006) This edition applies to version 2.6 of the IBM Workplace Software Development Kit (product number L-GHUS-6FYV7H) 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.

5 Contents Chapter 1. IBM Workplace Software Development Kit Overview of the IBM Workplace Software Development Kit Installing the IBM Workplace SDK documentation plug-ins Contents of the IBM Workplace Software Development Kit Development requirements Installing the IBM Workplace Software Development Kit runtime files on the IBM Workplace Server...6 New features, enhancements, and changes for this release Chapter 2. Developing applications for the IBM Workplace environment Developing applications for the IBM Workplace environment Application components Business components Collaborative application components IBM Workplace applications and templates...14 Choosing a platform: server, client, or both?..15 Application development tools Chapter 3. Component and Application Infrastructure Services APIs Component and Application Infrastructure Services APIs Services API design overview General usage model Object model Factories Services Common data objects Retrieval options Working with lists Choosing to work with Java or Web Services..26 Chapter 4. Collaborative Application Component Interfaces Collaborative Application Component Interfaces..29 Interfaces summary Guidelines for building, installing, and using collaborative components Chapter 5. SDK Sample Code IBM Workplace Software Development Kit samples 37 Preparing your development environment...38 Collaborative Application Component sample..41 The Noteboard Component Sample The Collaborative Component Wizard Building your own components and applications 59 Troubleshooting applications Web Services Sample Web Application Web Services Sample Standalone Java Application Java API Sample Portlets Chapter 6. Instant Messaging SPI Instant Messaging SPI Getting started with the Instant Messaging SPI..81 Session Initiation Protocol Chat logging application Compatibility with future releases of IBM Workplace Collaboration Services Chapter 7. Mail Messaging SPI Mail Messaging SPI Mail Messaging handler HandlerExtension interface HandlerExtMessage interface HandlerExtRecipient interface ContentSink interface ChainedContentFilter class Mail Messaging deliverer DeliveryExtension interface DeliveryExtMessage interface DelivererExtRecipient interface Additional Mail Messaging interfaces Extension interface ExtMessage interface MessageAddress interface Building a Mail Messaging processing extension..92 Setting the correct classpath to use the Mail Messaging SPI JAR files Writing a Mail Messaging processing extension 92 Registering the Mail Messaging processing extension Configuring a Mail Messaging processing extension Running a Mail Messaging processing extension 96 Chapter 8. JSP tags for IBM Workplace Server ProductsJSP tags for IBM Workplace Server Products JSP tags for IBM Workplace Server Products...97 Person tag: Syntax and reference OnlineCenter tag: Syntax and reference Appendix. Notices Trademarks Copyright IBM Corp. 2005, 2006 iii

6 iv User s Guide

7 Chapter 1. IBM Workplace Software Development Kit Overview of the IBM Workplace Software Development Kit The IBM Workplace Software Development Kit is designed for developers who want to use or extend the IBM Workplace Collaboration Services platform. An example of this would be creating new portlets or business components. The IBM Workplace SDK provides a number of public APIs (application programming interfaces) and SPIs (service provider interfaces) for developer use. The IBM Workplace public APIs also supplement the public APIs provided by the underlying IBM WebSphere Application Server and IBM WebSphere Portal platforms (not included in this SDK). This release of the SDK includes the following server APIs, SPIs, and JSP tags: Collaborative Application Component Interfaces With these Java interfaces, you can build business components that integrate with the IBM Workplace Collaboration Services collaborative infrastructure. IBM Workplace Collaboration Services uses these interfaces to interact with your components, manage component life cycle and community membership, and incorporate your components in IBM Workplace applications and application templates. You implement these interfaces in your collaborative application component stateless session EJB. Component and Application Infrastructure Services APIs You can use the Component and Application Infrastructure Services APIs to access services and content provided by existing IBM Workplace business components as well as manage IBM Workplace applications and templates. For example, you can navigate or create discussion topics, send mail, schedule a Web conference, create a new application from a template, or change membership for an existing application. You can use the APIs to integrate IBM Workplace Collaboration Services with other systems. For example, you could configure your corporate Help Desk system to use IBM Workplace Messaging. Third-party business components can use these APIs to enhance IBM Workplace Collaboration Services capabilities. For example, you can build a mail portlet to send mail from the IBM Workplace Collaboration Services user interface without requiring the screen real estate of the IBM Workplace mail portlet. The Component and Application Infrastructure Services APIs can be accessed using either Java or Web Services. Mail Messaging SPI for IBM Workplace Collaborative Services This Java SPI lets you build message handlers that intercept mail messages before delivery and redirect them or modify message content. Message handlers can perform virus scanning, active content filtering, spam filtering, or any other types of filtering. Instant Messaging SPI for IBM Workplace Server Products This Java SPI lets you build instant message handlers that intercept instant messages before delivery and block them, modify message content, or perform other operations; for example, logging, saving, or translating messages. Copyright IBM Corp. 2005,

8 JSP tags for IBM Workplace Server Products IBM Workplace Collaboration Services also includes the following JSP tags: v Person tag v OnlineCenter tag Use these JSP tags to incorporate awareness into portlet JSPs. The SDK also includes the following client APIs: IBM Workplace Client Technology platform The IBM Workplace Client Technology platform APIs provide interfaces and factory classes with which you can build customizable and extensible client applications. These applications provideibm Workplace Client Technology services and content. For example, with this API you can build an IBM Workplace Messaging application. The client APIs include IBM Workplace Component Services APIs adapted for the IBM Workplace Client Technology platform, as well as other APIs specific to IBM Workplace Client Technology. Any application you build using the client APIs provides support beyond the reach of the browser, including an IBM Workplace look-and-feel. In addition, you can: v access operating system-specific user interface controls v interact with the underlying operating system, encrypted local data sources, and mechanisms for offline use v communicate with server components From a centrally managed administrative server, you can provide delivery and upgrades, implement and enforce security protections, apply and administer policies for all your client applications. The APIs include their own documentation, which provides information on how to use the APIs as well as use the IBM Workplace Client Technology platform API sample code that ships with this SDK. The documentation is included as part of this SDK. Note: For more information on how to use the IBM Workplace Collaboration Services APIs with the IBM Workplace Client Technology platform, refer to the IBM Workplace Client Technology platform documentation that is also included in this SDK. The following other programming technologies are available in WebSphere Portal and used by IBM Workplace Collaboration Services: v WebSphere Portlet API and JSR 168 Portlet API v Struts portlet framework v Cooperative portlets For more information about this SDK, go to the IBM Workplace Software Development Kit page ( This page contains links to documentation, the latest product information, and pages from which you can download the product or related material. Related concepts Instant Messaging SPI on page 81 Mail Messaging SPI on page 85 2 User s Guide

9 JSP tags for IBM Workplace Server Products on page 97 Development requirements on page 4 Related information WebSphere Portal documentation library Session Initiation Protocol standards (implemented by the Instant Messaging SPI) WebSphere Software Portal Toolkit information Installing the IBM Workplace SDK documentation plug-ins In addition to the main PDF files, the IBM Workplace Software Development Kit documentation is also provided in an Eclipse plug-in format that you can view in the help system of any Eclipse-based environment, such as WebSphere Studio Site Developer, the IBM Workplace Client Technology platform, or the Eclipse IDE (available at The documentation plug-ins are designed to accommodate people who have physical challenges, such as restricted mobility or limited vision. If you need fully accessible documentation, use the documentation plug-ins rather than the PDF files. Adding the documentation to your Eclipse-based product To view the Eclipse plug-in version of the documentation, copy or move all folders in wcsapi26\doc\eclipse\plugins (with their contents) to the plugins folder of your Eclipse-based product. The following are the locations of the plugins folder for each product on Windows and Linux. In all cases, <install_dir> is the program directory where you installed your Eclipse-based product; for example, c:\program Files\IBM or /home/user/eclipsesdk Windows WebSphere Studio Site Developer: <install_dir>\websphere Studio\Application Developer\<version>\eclipse\plugins Eclipse IDE: <install_dir>\eclipse\plugins IBM Workplace Client Technology: <install_dir>\workplace rich client\eclipse\plugins IBM i5/os users with WebSphere Development Studio Client Advanced Edition for iseries or later versions of Websphere Development Studio Client Advanced Edition for iseries installed on their Windows system should copy the contents of wcsapi26\doc\eclipse\plugins to the one of the following locations: <WDSC_install_directory>\iSeries\eclipse\plugins or <Associated_WSAD_install_directory>\eclipse\plugins. Linux WebSphere Studio Site Developer: /opt/ibm/webspherestudio/applicationdeveloper/v5.1.2/eclipse/plugins Eclipse IDE: <install_dir>/eclipse/plugins IBM Workplace Client Technology: <install_dir>/workplace rich client/eclipse/plugins Chapter 1. IBM Workplace Software Development Kit 3

10 Viewing the documentation To view the documentation, start your Eclipse-based product and select Help > Help Contents. The books that make up the SDK documentation are displayed in the left pane of the Help window, below the other documentation supplied with your product. Related concepts Contents of the IBM Workplace Software Development Kit Contents of the IBM Workplace Software Development Kit The IBM Workplace Software Development Kit contains the following pieces: wcsapi26 readme.txt - SDK contents, requirements, accessing documentation relnotes.txt - release notes for this release doc - SDK documentation (PDF and documentation plugins) license - SDK license files imspi - WCS Instant Messaging SPI files javadoc - IM SPI reference information in Javadoc documentation format lib - platform-independent Java libraries (JAR files) samples - IM SPI sample programs mailspi - WCS Mail Messaging SPI files javadoc - reference information in Javadoc documentation format wcsapi - WCS Collaborative Application Component Interfaces and Component and Applicaton Infrastructure Services API files javadoc - reference information in Javadoc documentation format lib - platform-independent Java libraries (JAR files) samples - sample programs tools - tools for building WCS Applications Collaborative Component Wizard - tools for building a Collaborative Component wsdoc - Web Services documentation wmc - Workplace Managed Client API files applications - Component and Application Infrastructure Services API plugin/feature files javadoc - reference information in Javadoc documentation format samples - sample programs tools - tools for building WMC Applications WMC Tool - tool for Eclipse The SDK includes the following documentation: v User guides and application development guides -- available both as PDF files and as Eclipse documentation plug-ins that can be installed in Eclipse-based products. This documentation is in the SDK wcsapi26\doc folder. v API reference documentation for each component -- available as reference information in Javadoc documentation format for Java interfaces and in HTML format for Web Services. This documentation is in the SDK component directories. Related tasks Installing the IBM Workplace SDK documentation plug-ins on page 3 Development requirements This release of the IBM Workplace Software Development Kit supports the following IBM Workplace products: v IBM Workplace Collaboration Services 2.6 v IBM Workplace Managed Client User s Guide

11 The IBM Workplace SDK does not support earlier releases of these products. As new releases of IBM Workplace products become available, check the IBM Workplace SDK Web site at for information about compatibility with this SDK release. To develop applications with the IBM Workplace SDK, you must have the following software installed: v One of the following operating systems: Microsoft Windows 2000 Microsoft Windows XP RedHat Enterprise AS for Linux SuSe Linux 8.1 v a Java development environment Note: Although the SDK can only be used with the operating systems listed, the components and applications you create using the SDK are not restricted to those operating systems. Applications created with this release of the SDK are supported on all operating systems supported by IBM Workplace Collaboration Services and IBM Workplace Managed Client. Refer to the readme.txt file included with this release in the wcsapi26 folder for the most recent development requirements. The following sections list additional requirements for specific SDK components. IBM Workplace Managed Client Software Development Kit requirements The IBM Workplace Managed Client Software Development Kit 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 4 v Microsoft Windows XP with Service Pack 2 v Red Hat Enterprise Linux WS 3.0 with Update 4 only with Gnome desktop manager You can use the Eclipse 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 procedures describe how to use Rational Application Developer 6.0, which was formerly known as WebSphere Studio Application Developer, as the IDE. Refer to the readme.txt file included with this release for the most recent development requirements. Instant Messaging SPI for IBM Workplace Server Products requirements To use the Instant Messaging SPI, you must install the Java Servlet API, which is available separately or as part of the Java 2 Platform, Enterprise Edition SDK. Chapter 1. IBM Workplace Software Development Kit 5

12 Mail Messaging SPI for IBM Workplace Collaborative Services requirements There are no additional requirements for developing Mail Messaging SPI applications beyond the basic SDK requirements. IBM Workplace Collaboration Services API requirements To create server components or applications that use the SDK Collaborative Application Component Interfaces or Component and Application Infrastructure Services APIs, you must have the following software installed: v A J2EE 1.3 Java development environment that supports the Enterprise Java Bean 2.0 specification and uses the Java Development Kit 1.3.1, such as IBM Rational Application Developer v If you do not have the portlet development environment, you can download and use the separately installable IBM Portal Toolkit ( IBM i5/os users can also use the WebSphere Development Studio Client Advanced Edition for iseries to create server components or applications. JSP tags for IBM Workplace Server Products requirements To create portlets that use the JSP tags documented in this SDK, your development environment must conform to the requirements described in the documentation for the version of WebSphere Portal on which the portlets will be deployed. For more information, see the installation topics in the information center for your WebSphere Portal version. Information centers are located at Sample server code requirements The sample server component code in the SDK directory wcsapi26\wcsapi\samples requires one of the following Java development environments: v IBM Rational Application Developer with WebSphere test environment V5.x and WebSphere Portal V5.0 test environment. v IBM WebSphere Development Studio Client Advanced Edition for iseries or later versions of WebSphere Development Studio Client Advanced Edition for iseries, with the IBM Portal Toolkit Related concepts Overview of the IBM Workplace Software Development Kit on page 1 Installing the IBM Workplace Software Development Kit runtime files on the IBM Workplace Server The IBM Workplace Software Development Kit includes runtime files that are required by any applications using the IBM Workplace Collaboration Services APIs. These files are installed when you first install IBM Workplace Collaboration Services. The runtime files installed on the server are in the wcsapi26\wcsapi\lib SDK directory and include the following files: 6 User s Guide

13 v wcsapi_core.jar -- Data object API and Collaborative Application Component Interfaces. v wcsapi_core_impl.jar -- Data object and Collaborative Application Component implementation. v wcsapi_delegates.jar -- Component and Application Infrastructure Services API delegates. These delegates provide access to the services APIs without requiring you to access the services EJBs directly. v wcsapi_services.jar -- Component and Application Infrastructure Services API Interfaces. v wcsapi_services.ear -- Component and Application Infrastructure Services EJBs and implementation. In the event that you should need to manually install these runtime files (for example, if you needed to update the files), the following additional information is provided. To manually install the SDK runtime files You install the IBM Workplace SDK API JAR files on your IBM Workplace Server first, and then you install the IBM Workplace SDK services EAR file on the server. Installing these files requires administrative privileges so your server administrator might have to perform these tasks. To install the API JAR files on the server, do the following steps: Note: You must install the API JAR files before you install the services EAR file. 1. Copy all JAR files (*.jar) in the SDK directory wcsapi26\wcsapi\lib to the <WAS_HOME>\WorkplaceServer\lwp_lib directory on the IBM Workplace server, where <WAS_HOME> is the IBM WebSphere Application Server program directory containing the IBM Workplace Server installed files (for example, c:\websphere). If you do not have access to the file system of the WebSphere server, ask your server administrator to copy these JAR files for you. Note: If you have installed an earlier version of the IBM Workplace SDK API JAR files in a different directory on the server, you must remove them. Note: IBM i5/os users should copy the API JAR files to /qibm/userdata/webas5/base/<instance>/workplaceserver/lwp_lib. 2. From the IBM WebSphere Administrative Console on the server, browse to (for example, 3. Log in as a user with administrative privileges. 4. Click Environment Shared Libraries in the left panel. 5. Click LotusWorkplaceLib in the list of shared libraries. 6. On the Configuration screen, the Classpath field lists all of the shared libraries in the same directory you copied the API JAR files to. Add the four API JAR files you copied in Step 1. (<WAS_HOME> is as defined in Step 1). The easiest way to do this is to copy and paste one of the other entries, and then edit the JAR file name. For example: <WAS_HOME>\WorkplaceServer/lwp_lib/wcsapi_core.jar <WAS_HOME>\WorkplaceServer/lwp_lib/wcsapi_core_impl.jar <WAS_HOME>\WorkplaceServer/lwp_lib/wcsapi_delegates.jar <WAS_HOME>\WorkplaceServer/lwp_lib/wcsapi_services.jar 7. Make sure all of your entries are correct, and click OK when you are finished. Chapter 1. IBM Workplace Software Development Kit 7

14 8. Click Save at the top of the Shared Libraries screen. 9. At the Save to Master Configuration screen, click Save. 10. After you install the API JAR files on the server, stop and restart the IBM Workplace Server before installing the services EAR file. To complete the installation, install the services EAR file, update the Web Server plug-in (if you are using IBM HTTP Server), and start the services application. To install the services EAR file, do the following steps: 1. Run the WebSphere Administrative Console as described in the preceding task, and log in as a user with administrative privileges. 2. If you installed an earlier version of the services EAR file, uninstall it by following these steps: a. Click Applications Enterprise Applications in the left panel. b. At Enterprise Applications, click the + icon next to Filter, type wcsapi* in the input field to the left of the Go button, and then click Go. c. Click the check box next to the name of the services EAR file (for example, wcsapi_services), and then click Stop to stop the application. d. Type wcsapi* in the filter field again, and click Go. e. Click the check box next to name of the services EAR file, and then click Uninstall to remove the application. f. You can save changes now, or wait until you have installed the new version of the EAR file. 3. Click Applications - Install New Application in the left panel. 4. On the first Preparing for the application installation screen under the Path selection, browse to the SDK directory wcsapi26\wcsapi\lib and select wcsapi_services.ear (make sure you do not select wcsapi_services.jar by mistake). Click Next when you have finished. 5. Click Next at the Generate Default Bindings screen. 6. On the Step 1: Provide options to perform the installation screen, make sure both Deploy EJBs and Deploy WebServices are unchecked, and click Next when you have finished. 7. Click Next at the Step 2: Provide JNDI names for Beans screen. 8. On the Step 3: Map virtual hosts for web modules screen, select the Web Module check box, and click Next 9. On the Step 4: Map modules to application servers screen, select the WebSphere_Portal server from the Clusters and Servers list and select the Modules check box to select all the modules. Click Apply, and then Next when you have finished. 10. On the Step 5: Map security roles to users/groups screen, select the lwpuser check box under Role, and click Next. 11. On the Step 6: Summary screen, click Finish. 12. When the results screen has completed and you see the Application wcsapi_services installed successfully message, click Save to Master Configuration. 13. On the Save to Master Configuration screen, click the Save button. If you are using the IBM HTTP Server, you must update the Web Server plug-in to recognize the API Web Services endpoints by doing the following steps: 8 User s Guide

15 1. On the WebSphere Administrative Console home page, click Environment Update Web Server Plugin in the left panel. 2. Click OK on the Update web server plugin configuration screen. The Update web server plugin configuration screen is displayed again, with a message at the top indicating that the plug-in configuration was updated successfully. After you have installed the services EAR and updated the Web Server plug-in (if necessary), start the services EAR application as follows: 1. On the Enterprise Applications screen, click the + icon next to Filter, type wcsapi* in the input field to the left of the Go button, and then click Go. 2. Click the check box next to wcsapi_services, and then click Start to start the application. The application list is displayed again, with a message at the top indicating that the wcsapi_services application started successfully. New features, enhancements, and changes for this release This release of the IBM Workplace Software Development Kit includes new features, enhancements, and changes from the previous release. See the file relnotes.txt, included with this release, for additional information about new features, enhancements, and changes from the previous release. The 2.6 release of the SDK provides the following new features: v The Collaborative Component Wizard a tool for the creation of a basic collaborative application component v New samples that access IBM Workplace Collaboration Services (WCS) including Sample standalone Java application that accesses the Component Services via the Web Service API. Sample portlets that access the Component Services via the Java API. All samples are now based on IBM Rational Application Developer instead of IBM WebSphere Application Developer, so that developers have the latest available development tools. This will also let them upgrade the tools if necessary in the future. The 2.6 release of the SDK provides the following enhancements: v A new ApplicationTemplateService.getTemplateId method was added that will return a template ID given the category and name. See the wcsapi26\wcsapi\javadoc for details. v The membership interface was enhanced to include the ability to notify a collaborative component of ownership changes. v Support for the platform file system based FileResources has been added including the following: Mail: - When using methods that create attachments, for example calling sendmessage(mailmessage, MailSendOptions), setting MailAttachment.setFileLoadedByService(boolean) will result in the content of the attachment coming from IBM Workplace Collaboration Services platform s file system. See FileResource.setFileLoadedByService(boolean) in the wcsapi26\wcsapi\javadoc for more information. - When using methods that retrieve attachments, for example calling getmessage(string, MailRetrievalOptions), setting the attribute, MailRetrievalOptions.setFileStorageDirectory(String), will result in the Chapter 1. IBM Workplace Software Development Kit 9

16 content of the attachment being deposited into the IBM Workplace Collaboration Services platform s file system in the specified directory. - A new service method MailService.getAttachmentAsFile(String, String) was added to allow retrieval of Mail Attachments into the IBM Workplace Collaboration Services platform s file system in the specified directory. Document Library: - When using methods that create documents, as opposed to folders, for example calling addentry(documentlibraryentry), setting the attribute, Document.setFileLoadedByService(boolean), will result in the content of the document coming from IBM Workplace Collaboration Services platform s file system when the object is used by the service method. See FileResource.setFileLoadedByService(boolean) in the wcsapi26\wcsapi\javadoc for more information. - When using methods that retrieve documents, as opposed to folders, for example calling getentries(string, DocumentRetrievalOptions), setting DocumentRetrievalOptions.setFileStorageDirectory(String) will result in the content of the document being deposited into the IBM Workplace Collaboration Services platform s file system in the specified directory. See FileResourceRetrievalOptions.setFileStorageDirectory(String) in the wcsapi26\wcsapi\javadoc for more information. v A new method, MailService.updateMessage, has been added. It returns a replacement messageid. See the wcsapi26\wcsapi\javadoc for details. v The ability to send s with an HTML message body in addition to previously supported plain text has been added. v The ability to sort retrieved Application objects not only by name but by alias, creation date, last modified date, creator, last modifier, and owner has been added. See the wcsapi26\wcsapi\javadoc for details. v Error handling has been improved. You now receive exceptions that occur below the API layer. The 2.6 release of the SDK contains the following changes from the previous release: v Calling MailRetrievalOptions.setIncludeAttachmentContent with a false value (the default setting) causes MailAttachment objects to be retrieved without their content. MailAttachment objects no longer contain MIME header information. v On the IBM Workplace Managed Client, you no longer need to access the mailbox in the user interface before you use MailService methods. 10 User s Guide

17 Chapter 2. Developing applications for the IBM Workplace environment Developing applications for the IBM Workplace environment The IBM Workplace Software Development Kit is one of many tools that you can use to develop applications for the IBM Workplace environment. The IBM Workplace environment includes both server platforms (IBM Workplace Collaboration Services and IBM Workplace Services Express) and the IBM Workplace Client Technology platform (sometimes called the rich client platform). Although the information in this guide is intended to describe the use of APIs on the server platforms, many of the concepts can also be applied to the client platform. Note: For more information on how to use the IBM Workplace Collaboration Services APIs with the IBM Workplace Client Technology platform, refer to the IBM Workplace Client Technology platform documentation that is also included in this SDK. The term application has a number of different meanings and different types of applications require different development tools. In the IBM Workplace environment, you work with application components, business components, and applications. These are defined as follows: v Application components - the basic building blocks of applications. The application components used in the IBM Workplace environment include servlets, portlets, Eclipse plug-ins, collaborative components, forms, and so on. Most application components are created by writing or generating code. v Business components - collections of application components that encapsulate a business concept, process, or service. IBM Workplace Collaboration Services includes a number of business components. These include Discussion, Mail, and Calendar components. v Applications - collections of application components that provide a unified set of related capabilities, for example, Web conferencing or document management. On the server platforms, applications are IBM Workplace applications, which are template-based assemblies of application components, such as portlets, collaborative application components, and forms. IBM Workplace applications are created using tools like the IBM Workplace Template and Application Editor or IBM Workplace Designer, usually without writing any code. On the client platform, applications are collections of Eclipse plug-ins and features, which are assembled using integrated development environments such as IBM Rational Application Developer or Eclipse. Applications are combined to make business components, which can be combined to make complete applications. The topics in this chapter provide more detail about these concepts and general information about developing application components and applications for the IBM Workplace environment, focusing on the IBM Workplace server platforms. For more information about building applications for the IBM Workplace Client Technology platform, refer to the documentation provided in this SDK for the IBM Workplace Client Technology platform. Copyright IBM Corp. 2005,

18 Application Business components There are many types of application components that you can use in the IBM Workplace environment. Examples include servlets, portlets, collaborative components, and forms. Most application components are created by writing code or by generating code using development tools. These components then can use the APIs and SPIs provided by the IBM Workplace Software Development Kit. Some components, like forms, do not require writing any code and do not use APIs. In the IBM Workplace environment, application components are typically used to construct business components which encapsulate a business concept, process, or service. The next topics in this chapter describe business components in much more detail. components A business component is a collection of application components that encapsulate a business concept, process, or service. IBM Workplace Collaboration Services consists of many business components, including the following: v v v Discussion Calendar Mail v Web Conference v Team Task List v Contact List v Document Library v Activity Explorer v Search The IBM Workplace SDK enables you to build your own business components, and to access data and services managed by some of the IBM Workplace business components. In the IBM Workplace environment, business components consist of a combination of user interface components (for example, portlets or IBM Workplace Managed Client views) and service components (for example, EJBs (Enterprise JavaBeans)). On the IBM Workplace server platform, a business component can integrate with the IBM Workplace collaborative environment by including a collaborative component EJB, which is described in more detail in the Collaborative application components topic. Business component architecture The J2EE (Java 2 Platform, Enterprise Edition) platform defines the standard for multi-tier enterprise applications. The use of multiple tiers is a proven way to develop highly-scalable distributed applications. The IBM Workplace platform takes advantage of this architecture. The IBM Workplace platform uses four tiers: v User tier - contains code and components used by the user interface, for example, portlets, JSP tag libraries, IBM Workplace Client Technology platform views, and so on. 12 User s Guide

19 v Workspace tier - (collocated with the User tier) contains business delegates that provide access to business logic in the Service tier, as well as other business logic that does not require access to the Service tier. v Service tier - contains most (if not all) of the application business logic. v Resource tier - handles access to shared resources, such as databases and directories, and provides both the storage for those resources and the framework used to access that storage. The figure below depicts the multi-tiered architecture of an IBM Workplace business component: In the IBM Workplace platform, the business logic in the Service tier is typically implemented in stateless session EJBs (Enterprise JavaBeans). On IBM Workplace server platforms, the User and Workspace tiers are located on the same server, while the Service and Resource tiers can each be located on different servers. (Current releases of IBM Workplace server products install User, Workspace, and Service tier components on a single server.) On the IBM Workplace Client Technology platform, all tiers are collocated on the same client machine, although components on the client can also access server-based components. Components on different servers can communicate using standard protocols such as Web Services or RMI/IIOP (Remote Method Invocation technology run over the Internet Inter-Orb Protocol). To maximize scalability and flexibility, it is recommended (though not required) that you use this architecture when building your own business components. Collaborative application components A collaborative application component (collaborative component, for short) is used to integrate a business component with the IBM Workplace collaborative environment. Collaborative components are used only on the IBM Workplace server platforms. The IBM Workplace Client Technology platform provides different mechanisms to allow components to integrate with that platform. A collaborative component is a stateless session EJB (Enterprise JavaBean) that implements one or more of the Collaborative Application Component Interfaces, which are described in detail in Chapter 4 of this guide. These interfaces allow IBM Workplace Collaboration Services to interact with a business component, manage the component life cycle, application membership, and incorporate the Chapter 2. Developing applications for the IBM Workplace environment 13

20 component with IBM Workplace applications and templates. By using a collaborative component, a business component and its resources can be created and destroyed at the appropriate times. A collaborative component is associated with a portlet. When you use the IBM Workplace Template and Application Editor to add the portlet to a template or application page, IBM Workplace Collaboration Services locates the collaborative component EJB and calls the appropriate Collaborative Application Component Interface methods. This mechanism is explained in more detail in Chapter 4. IBM Workplace applications and templates An IBM Workplace application is a template-based assembly of components, such as portlets, collaborative application components, and forms. On the IBM Workplace server platforms, you create an IBM Workplace application by instantiating a template. You can use one of the templates included with the IBM Workplace server products, or you can create your own, using the IBM Workplace Template and Application Editor (also called Workplace Builder). After you create an application instance from a template, you can customize the application using the IBM Workplace Template and Application Editor, without impacting the original template. You can also save an application as a new template, from which you can instantiate other applications. IBM Workplace Collaboration Services includes a number of templates, including the following: v Team Project v Document Library v Discussion v Domino Application Access v Chat Room v Event Planning v Sales Team v Course Collaboration v Blank Template You can use these or the other templates included with the IBM Workplace server products as the starting point for your own templates. Each template can be associated with a template category, for example, Team Space or Learning. The category is used to group applications in the user interface of the IBM Workplace server product. You can use one of the categories included with IBM Workplace server product, or create your own categories. Each template also can use parameters, or points of variability, that allow you to customize the behavior of each application created from the template. For example, if the template includes a portlet that accesses data in a Domino database, you could use parameters for the Domino server and database name, so that each application created from the template could access a different database. To create and manage applications and templates programmatically, use the Component and Application Infrastructure Services APIs provided with the SDK, which are described in more detail in Chapter 3 of this guide. 14 User s Guide

21 To create your own collaborative components that can be used in templates, use the Collaborative Application Component Interfaces, which are described in Chapter 4. For more information about using application and templates, refer to the Information Center for your IBM Workplace server product. Choosing a platform: server, client, or both? In the IBM Workplace environment, you can choose to build application components for the server platforms, IBM Workplace Client Technology platform, or both. The platform(s) you choose will depend on a number of factors, including requirements of the products you build, development skills, and features of the platform. Application components for the IBM Workplace server platform run in the IBM WebSphere Portal environment. The User-tier user interface components are portlets and pages, which are accessed via Web browsers. Portlets are built using technologies such as JSP (JavaServer Pages), Apache Struts, or JSF (JavaServer Faces). User interface components integrate with the IBM WebSphere Portal environment using either the IBM WebSphere Portlet API or the standard JSR (Java Specification Request) 168 Portlet API. User interface components can (but are not required to) take advantage of other server platform features, such as cooperative portlets or JSP tags that provide presence awareness. Other application components are built using Java and Service-tier components typically use EJB (Enterprise JavaBeans) technology. All application components are packaged and deployed to the server using standard J2EE (Java 2 Platform, Enterprise Edition) technologies. Application components for the IBM Workplace Client Technology platform run in the Eclipse Platform. The User-tier user interface components are views and perspectives, which are built using technologies such as SWT (Standard Widget Toolkit). Application components are built as Eclipse plug-ins, and can use a variety of services provided by other Eclipse and IBM Workplace Client Technology platforms, as well as services provided by the underlying operating system. Server-managed application components are installed to an IBM Workplace server platform and automatically deployed to IBM Workplace Client Technology platform machines, based on centrally-managed user policies. Since the IBM Workplace Client Technology platform can be used in both connected and offline modes, application components that access the network need to behave appropriately in offline mode. If you wish to build business components or other products that can be used on both the server and client platforms, you should be able to share some application components between the two platforms. To do this, use the following guidelines: v Separate your platform-independent code from other code that depends on either server or client features. Bear in mind that the client can be offline, with no network connection, so platform-independent code should not require network access. v Package your platform-independent code in separate JAR files, which can be used by both EJBs on the server or plug-ins on the client. Although the IBM Workplace Client Technology platform provides an EJB container, the IBM Workplace SDK does not yet enable you deploy your own EJBs into that container. v Although you will need to create different user interface components for the server and client platforms, avoid using user interface constructs that are Chapter 2. Developing applications for the IBM Workplace environment 15

22 difficult to support on both platforms. For example, excessive use of Eclipse custom menus or toolbar buttons on the client might make it difficult to create a user interface for the server. Application development tools IBM provides a number of different tools that you can use to build IBM Workplace applications and application components, including the following: v IBM Rational Application Developer (formerly IBM WebSphere Studio Application Developer) a feature-rich integrated development environment that enables you to create application components for both server and client platforms. IBM Rational Application Developer is based on the open-source Eclipse Platform. For more information, see v Collaborative Component Wizard for IBM Workplace Applications a wizard for IBM Rational Application Developer that enables you to easily build collaboration components for IBM Workplace applications. For more information on how to use this wizard, refer to the SDK Sample Code section of this guide. v IBM Workplace Managed Client Tool for Eclipse a wizard for any Eclipse based development environment that enables you to build applications and application components for the IBM Workplace Managed Client platform. For more information on how to use this wizard, refer to the IBM Workplace Managed Client platform documentation found in this SDK. v IBM Workplace Designer an Eclipse-based development tool that enables you to create server application components for IBM Workplace applications. IBM Workplace Designer runs on the IBM Workplace Managed Client platform. For more information, see v IBM Workplace Template and Application Editor (also known as Workplace Builder) enables you to create and modify IBM Workplace templates and applications, and is included with IBM Workplace Collaboration Services. To create application components for the IBM Workplace Client Technology platform, you can also use the open-source Eclipse SDK (Software Development Kit), version 3.0 or later. For more information, see The URLs listed above were valid when this was written, but may change over time. For the latest URLs, refer to the IBM Workplace Software Development Kit home page at 16 User s Guide

23 Chapter 3. Component and Application Infrastructure Services APIs Component and Application Infrastructure Services APIs The Component and Application Infrastructure Services APIs (Services APIs for short) enable application components to access to the services and content provided by the IBM Workplace Collaboration Services business components and application infrastructure. You can use the Services APIs to access, create, delete, or modify the following: v meetings and other calendar entries v discussion forums and postings v document libraries, folders, and documents v mail messages and folders v Web conferences v applications and templates In addition, you can use the Services APIs to do the following: v send mail messages v search applications and Web conferences v get the URL for an application The Services APIs can be accessed using either Java or Web Services. The Java APIs can be used by applications running on either the IBM Workplace server or the IBM Workplace Client Technology platform. Applications running on other server or client platforms can use Web Services APIs to access services on a remote IBM Workplace server. For details on the available Services APIs, see the API Javadoc in the SDK directory lwpapi26\lwpapi\javadoc or the Web Services API documentation in lwpapi26\lwpapi\wsdoc. Services API design overview The Component and Application Infrastructure Services APIs were designed to meet a number of key requirements, including the following: v Ease of use The API must be easy to use. For example, the object model is based on concepts you see in the user interface, rather than internal architecture. v Consistency The API uses consistent naming conventions, and common objects are used in the same way throughout the object model. For example, the Member interface is always used to represent a person or group, and all data retrieval service methods support the use of common retrieval options. Security: Authentication is required in order to access the Services APIs. The APIs do not provide access to data that you would not otherwise have access to. v Supportability and maintainability Almost all of the Java APIs are exposed as interfaces rather than classes, to decouple the API from its implementation. This makes it possible to extend the API in future releases, while retaining both source and binary compatibility with existing applications. In addition, the API Copyright IBM Corp. 2005,

24 only exposes features that are both necessary to meet customer requirements and not likely to change in any significant way. These goals also apply to the Collaborative Application Component Interfaces, which are described in Chapter 4. The Services APIs use service-oriented architecture (SOA) design principles. This means, among other things, that the services are stateless, and separate from the data they manipulate. The topics that follow provide some details on the design of the API. General usage model The general usage model for the Component and Application Infrastructure Services APIs is summarized as follows: Object 1. Your application component calls one of the Service API retrieval methods to request data. You can specify retrieval options that control how much data will be retrieved. 2. You manipulate the data locally, in other words, wherever your application component resides. You use methods on the data object interfaces to manipulate the objects. Note that none of the data object methods makes Service API calls, meaning you don t need a connection to the server to work with the data. 3. If you have made changes to the data objects that you wish to save, your application component calls one of the Service API update methods, passing it the modified data. The update method saves the changes in the appropriate persistent data store. Unless you call the appropriate Service API update method, any changes you make to the data will have no effect. 4. If you need to continue working with the same data, you should call the Service API retrieval method to request the data again. When you call an update method, the underlying data may change in ways that will not be reflected in the data objects you retrieved earlier. For example, if you create new data objects and then call an update method, your copy of the data objects will not include any object IDs that were generated during the update. Specific usage information for Java and Web Services is provided in the topic Choosing to work with Java or Web Services. model The API object model was deigned to be easy to use and maintainable. The objects are based on familiar concepts exposed in the user interface of the IBM Workplace products, not on the underlying architecture. In the Java APIs, objects are exposed using interfaces rather than classes (except in a few cases where this wasn t technically possible), to separate the API from its implementation. The design of the API object model was influenced by the SDO (Service Data Objects) programming model. SDO, which supports service-oriented architecture, is a data application development framework that allows you to work with data in a unified way, regardless of where that data is stored. SDO provides metadata that allows SDO-aware tools to easily manipulate SDO data. For more information on SDO, refer to the IBM developerworks article Introduction to Service Data Objects, which you can find at 18 User s Guide

25 Although the Component and Application Infrastructure Services APIs do not use SDO today, the API object model is designed to be compatible with the SDO programming model, so that SDO support can be added in the future. SDO is not a Java-specific technology, and does not support Java-specific data types that have no counterpart in other programming environments. Therefore, Java APIs that support the SDO programming model must adhere to certain restrictions: v The only supported data types are String, List, Date, primitive types (such as int), the objects that wrap primitive types (such as Integer), and byte arrays. v All fields of a data object must be either one of the supported types, or an object composed of the supported types. v All multi-valued fields must be represented using List objects. v Java collection classes and arrays should not be used as input or output parameters for service methods that can be called remotely. In general, remote method parameters should be SDO data objects, String objects, or primitive types. The API object model adheres to these restrictions, which means it cannot take full advantage of Java data types, for example, java.util.locale. The use of lists is also restricted, as described in the Working with Lists topic. Factories The Java APIs use interfaces rather than classes to separate the API from its implementation. This also makes the API easier to extend in future releases, without impacting existing applications. The Java APIs include a number of factories that you use to create instances of the API data objects. Factories are not used for the Web Services APIs, which use a different mechanism for instantiating objects. The following figure depicts the factory object interfaces and their relationship: The FactoryCreator class is a static class that creates instances of the other factories which are interfaces like the other API objects. Because FactoryCreator is static, you do not need to create an instance of the class in order to use it. The ServiceFactory creates instances of service delegates. These are used to access the API services in the Service tier. The ServiceFactory automatically creates the appropriate type of delegate for the server or client platform, and the delegate handles the details of communicating with the Service tier via remote or local interfaces. For more information on the service delegates, refer to the Services topic. Chapter 3. Component and Application Infrastructure Services APIs 19

26 The WorkplaceFactory creates instances of common data objects that are used throughout the Java APIs. For more information on the common data objects, refer to the Common data objects topic. In addition to the common data objects, each service uses its own set of data objects specific to that service. Each service has a corresponding data factory that creates instances of the service-specific data objects. For example, the CalendarService API uses a number of calendar data objects and the CalendarFactory is used to create instances of those data objects. Each of these service data factories extends (inherits from) WorkplaceFactory, as shown in the figure above. This allows you to use the service data factories to create both service-specific and common data objects. In other words, each service data factory can do everything that WorkplaceFactory does, so it is not necessary to use WorkplaceFactory if you already have one of the service data factories. The following code example illustrates the use of API factories: // Use the static FactoryCreator class to create a ServiceFactory object. ServiceFactory servicefactory = FactoryCreator.createServiceFactory(); // Use the ServiceFactory to create a CalendarService delegate object. // (Use of CalendarService methods is not shown in this example.) CalendarService calendarservice = servicefactory.createcalendarservice(); // Use FactoryCreator to create a CalendarFactory object. CalendarFactory calendarfactory = FactoryCreator.createCalendarFactory(); // Use the CalendarFactory to create a Member object. Member is a common // data object, and the creatememberfrom address method used below // is inherited from WorkplaceFactory. Member member = calendarfactory.creatememberfrom address("johndoe@ibm.com"); // Use the CalendarFactory to create a Participant object from the Member // object we obtained above. The Participant interface is only used by the // CalendarService API, so the createparticipant method is defined in // CalendarFactory, not inherited from WorkplaceFactory. Participant participant = calendarfactory.createparticipant(member); For more examples of using the API factories, refer to the SDK sample programs. Services The Component and Application Infrastructure Services API provides access to services and content provided by the IBM Workplace Collaboration Services business components and application infrastructure. The API services are implemented in the IBM Workplace Service tier, using a combination of EJBs (Enterprise JavaBeans) and POJO (Plain Old Java Objects) classes. On both the server and client platforms, the services are accessed using service API delegates, which handle the details of communicating with the Service tier via remote or local interfaces. You create service delegates using the ServiceFactory, as described in the Factories topic. The following figure illustrates the service delegate object interfaces and their relationship: 20 User s Guide

27 WorkplaceService provides access to common services, for example, getting information about the currently-authenticated user. All of the other service interfaces extend WorkplaceService, so that you can access the common services from any service delegate. BusinessComponentService provides access to services common to all business components, for example, determining if the business component is available on the IBM Workplace server. Each business component has its own service interface, which provides access to services and content specific to that component. For example, CalendarService provides access to calendar-specific services and content. As indicated in the figure above, each component service interface extends BusinessComponentService (which, in turn, extends WorkplaceService). ApplicationService and ApplicationTemplateService provide access to application infrastructure services used to manage applications and templates. Because they are infrastructure services rather than component services, ApplicationService and ApplicationTemplateService do not extend BusinessComponentService. The following code example illustrates the use of the service delegates: // Use the factories to create a CalendarService delegate object. ServiceFactory servicefactory = FactoryCreator.createServiceFactory(); CalendarService calendarservice = servicefactory.createcalendarservice(); // Use the CalendarFactory to create a Meeting object. CalendarFactory calendarfactory = FactoryCreator.createCalendarFactory(); Meeting meeting = calendarfactory.createmeeting(); // Set the meeting properties. Note that CalendarService is used to // call the getcurrentuser method inherited from WorkplaceService. meeting.setchairperson(calendarservice.getcurrentuser()); meeting.setsubject( SDK meeting ); //... set other properties as needed // Use CalendarService to add the new meeting to the current user s // calendar. The addcalendarentry method returns the ID of the new // meeting entry. String id = calendarservice.addcalendarentry(meeting); For more examples of using the service delegates, refer to the SDK sample programs. Common data objects The Collaborative Application Component Interfaces and Component and Application Infrastructure Services APIs include a number of common data objects used throughout the APIs. For example, all API methods use a Member object to Chapter 3. Component and Application Infrastructure Services APIs 21

28 represent a person or group. You create common data objects using the WorkplaceFactory, as described in the Factories topic. The following figure illustrates some of the common data object interfaces and their relationship. There are many other common data objects not shown in this figure. WorkplaceObject is the base interface for all API data objects, including the service-specific data objects such as Calendar. WorkplaceObject implements java.io.serializable, which allows all API data objects to be serialized, which is required when services are accessed remotely. WorkplaceObject does not currently provide any public methods, but may include common methods in future API releases. WorkplaceDataObject, which extends WorkplaceObject, is the base interface for all API data objects that can be used as input or output parameters for service API methods. The Object model topic describes the role of Service Data Objects (SDO) in the design of the API object model. Although the API does not currently use SDO technology, the data objects that extend WorkplaceDataObject are those that correspond to SDO data objects. Like WorkplaceObject. WorkplaceDataObject does not currently provide any public methods, but this may change in future API releases. WorkplaceResource is the base interface for API data objects that represents an IBM Workplace resource with associated persistent storage; for example, a document, folder, calendar, or mailbox. WorkplaceResource is extended by other interfaces for the specific resource types. WorkplaceResource provides methods common to all persistent resources, for example, access to the unique identifier and creation date. WorkplaceDocument is the base interface for all API data objects that represent a document, either a discussion posting, document library document, mail message, or Web conference. WorkplaceDocument is extended by other interfaces that represent the specific document types, either directly or indirectly. WorkplaceDocument does not currently provide any public methods, but this may change in future API releases. The RetrievalOptions and DataObjectList interfaces are described in the Retrieval options and Working with lists topics, respectively. For more information on the API data objects, refer to the Javadoc in the wcsapi26\wcsapi\javadoc SDK directory. 22 User s Guide