IBM Workplace Collaboration Services API Toolkit

Transcription

1 IBM Workplace Collaboration Services API Toolkit Version 2.5 User s Guide G

2

3 IBM Workplace Collaboration Services API Toolkit Version 2.5 User s Guide G

4 Note Before using this information and the product it supports, read the information in Notices, on page 79. 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 2004, 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 Collaboration Services API Toolkit Overview of the IBM Workplace Collaboration Services API toolkit Installing the toolkit documentation plug-ins...3 Contents of the toolkit Development requirements Installing the IBM Workplace Collaboration Services API Toolkit runtime files on the IBM Workplace Server New features and additions for this release....8 Chapter 2. IBM Workplace Collaboration Services Server APIs.. 11 Toolkit Server APIs Collaborative Application Component Interfaces..12 Application development using the Collaborative Application Component Interfaces IBM Workplace business components Business component architecture IBM Workplace applications Guidelines for building components Guidelines for packaging components Guidelines for deploying components Creating collaborative components with the Collaborative Application Component Interfaces..16 Collaborative Application Component Interfaces sample Collaborative Application Component Interfaces files Component and Application Infrastructure Services Interfaces Application development using the Component and Application Infrastructure Services Interfaces...19 Common features of the Component and Application Infrastructure Services Interfaces..19 Security in the Component and Application Infrastructure Services APIs Component and Application Infrastructure Services accessed with Java Component and Application Infrastructure Services accessed with Web Services Chapter 3. Toolkit Sample Code Toolkit samples Preparing your development environment...24 Collaborative Application Component sample..26 The Noteboard Component Sample Building your own components and applications 39 Additional information for IBM Rational Application Developer 6.0 users Troubleshooting applications Web Services Sample Web Application Chapter 4. Instant Messaging SPI Instant Messaging SPI Getting started with the Instant Messaging SPI..56 Session Initiation Protocol Chat logging application The Contact class Compatibility with future releases of IBM Workplace Collaboration Services Chapter 5. 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..68 Setting the correct classpath to use the Mail Messaging SPI JAR files Writing a Mail Messaging processing extension 68 Registering the Mail Messaging processing extension Configuring a Mail Messaging processing extension Running a Mail Messaging processing extension 72 Chapter 6. JavaServer Page Tags Custom JavaServer Page tags used with the IBM Workplace Collaboration Services API toolkit...73 Person tag: Syntax and reference OnlineCenter tag: Syntax and reference Appendix. Notices Trademarks Copyright IBM Corp. 2004, 2005 iii

6 iv User s Guide

7 Chapter 1. IBM Workplace Collaboration Services API Toolkit Overview of the IBM Workplace Collaboration Services API toolkit The IBM Workplace Collaboration Services API Toolkit 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 toolkit 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 toolkit). This release of the toolkit 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. IBM Workplace Mail Messaging SPI 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. IBM Workplace Instant Messaging SPI 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. 2004,

8 IBM Workplace Collaboration Services JavaServer Pages tags 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 toolkit also includes the following client APIs: IBM Workplace Client Technology platform APIs The IBM Workplace Client Technology platform APIs provide interfaces and factory classes with which you can build customizable and extensible client applications. These applications provide IBM 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 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 toolkit. The documentation is included as part of this toolkit. 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 toolkit, go to the IBM Workplace Collaboration Services API Toolkit 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 Collaborative Application Component Interfaces on page 12 Instant Messaging SPI on page 55 Mail Messaging SPI on page 61 Custom JavaServer Page tags used with the IBM Workplace Collaboration Services API toolkit on page 73 Development requirements on page 4 2 User s Guide

9 Related information WebSphere Portal documentation library Session Initiation Protocol standards (implemented by the Instant Messaging SPI) WebSphere Software Portal Toolkit information Installing the toolkit documentation plug-ins In addition to the main PDF files, the IBM Workplace Collaboration Services API Toolkit 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 Application 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 lwpapi25\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 Application 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 (WDSC) for iseries installed on their Windows system should copy the contents of lwpapi25\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 Application 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 Viewing the documentation Chapter 1. IBM Workplace Collaboration Services API Toolkit 3

10 Contents of the toolkit To view the documentation, start your Eclipse-based product and select Help > Help Contents. The books that make up the toolkit documentation are displayed in the left pane of the Help window, below the other documentation supplied with your product. Related concepts Contents of the toolkit The IBM Workplace Collaboration Services API toolkit contains the following pieces: lwpapi25 readme.txt - toolkit contents, requirements, accessing documentation relnotes.txt - release notes for this release doc - toolkit documentation license - license files lwpapi - 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 wsdoc - Web Services documentation imspi - Instant Messaging SPI files javadoc - reference information in Javadoc documentation format lib - Platform-independent Java libraries (JAR files) samples - sample programs mailspi - Mail Messaging SPI files javadoc - reference information in Javadoc documentation format wct - Workplace Client Technology Platform API files applications - Component and Application Infrastructure Services API plugin/feature files javadoc - reference information in Javadoc documentation format samples - sample programs The toolkit 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 toolkit lwpapi25\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 toolkit component directories. Related tasks Installing the toolkit documentation plug-ins on page 3 Development requirements To develop applications with the IBM Workplace Collaboration Services API toolkit, you must have the following software installed: Refer to the readme.txt file included with this release in the lwpapi25 folder for the most recent development requirements. v One of the following operating systems: Microsoft Windows 2000 Microsoft Windows XP Red Hat Linux 8 4 User s Guide

11 SuSe Linux 8.1 v a Java development environment Note: Although the toolkit can only be used with the operating systems listed, the components and applications you create using the toolkit are not restricted to those operating systems. Applications created with this release of the toolkit are supported on all operating systems supported by IBM Workplace Collaboration Services. The following sections list additional requirements for specific toolkit components. IBM Workplace Client Technology platform API 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 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 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. Mail Messaging SPI requirements There are no additional requirements for developing Mail Messaging SPI applications beyond the basic toolkit requirements. IBM Workplace Collaboration Services API requirements To create server components or applications that use the toolkit 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 WebSphere Studio Application Developer or later, including Rational Application Developer 6.0. v If you do not have the portlet development environment in WebSphere Studio Application Developer, you can download and use the separately installable IBM Portal Toolkits ( Chapter 1. IBM Workplace Collaboration Services API Toolkit 5

12 IBM i5/os users can also use the WebSphere Development Studio Client Advanced Edition for iseries to create server components or applications. JSP tag requirements To create portlets that use the JSP tags documented in this toolkit, 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 toolkit directory lwpapi25\lwpapi\samples requires one of the following Java development environments: v IBM WebSphere Studio Application Developer 5.1.2, with the IBM Portal Toolkit v IBM WebSphere Development Studio Client Advanced Edition for iseries, 5.1.2, with the IBM Portal Toolkit v IBM Rational Application Developer 6.0 Related concepts Overview of the IBM Workplace Collaboration Services API toolkit on page 1 Installing the IBM Workplace Collaboration Services API Toolkit runtime files on the IBM Workplace Server The IBM Workplace Collaboration Services API toolkit includes runtime files that are required by any applications using the IBM Workplace Collaboration Services APIs. Before you can run these applications on an IBM Workplace Server, you must install the toolkit runtime files on that server. You need to do this only once for each server, before you install any API applications. The runtime files that you need to install on the server are in the lwpapi25\lwpapi\lib toolkit directory and include the following files: v lwpapi25_core.jar -- Data object API and Collaborative Application Component Interfaces. v lwpapi25_core_impl.jar -- Data object and Collaborative Application Component implementation. v lwpapi25_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 lwpapi25_services.jar -- Component and Application Infrastructure Services API Interfaces. v lwpapi25_services.ear --Component and Application Infrastructure Services EJBs and implementation. You install the toolkit API JAR files on your IBM Workplace Server first, and then you install the toolkit services EAR file on the server. Installing these files requires administrative privileges so your server administrator might have to perform these tasks. 6 User s Guide

13 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 toolkit directory lwpapi25\lwpapi\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 toolkit 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/lwpapi25_core.jar <WAS_HOME>\WorkplaceServer/lwp_lib/lwpapi25_core_impl.jar <WAS_HOME>\WorkplaceServer/lwp_lib/lwpapi25_delegates.jar <WAS_HOME>\WorkplaceServer/lwp_lib/lwpapi25_services.jar 7. Make sure all of your entries are correct, and click OK when you are finished. 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 lwpapi* in the input field to the left of the Go button, and then click Go. c. Click the check box next to lwpapi25_services, and then click Stop to stop the application. d. Type lwpapi* in the filter field again, and click Go. e. Click the check box next the lwpapi25_services, and then click Uninstall to remove the application. Chapter 1. IBM Workplace Collaboration Services API Toolkit 7

14 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 toolkit directory lwpapi25\lwpapi\lib and select lwpapi25_services.ear (make sure you do not select lwpapi25_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 Deploy EJBs is unchecked and select the Deploy WebServices check box. 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. Click Next at the Step 6: Provide options to perform actions on the WebServices deployment screen. 12. On the Step 7: Summary screen, click Finish. 13. When the results screen has completed and you see the Application lwpapi25_services installed successfully message, click Save to Master Configuration. 14. 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: 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 lwpapi* in the input field to the left of the Go button, and then click Go. 2. Click the check box next to lwpapi25_services, and then click Start to start the application. The application list is displayed again, with a message at the top indicating that the lwpapi25_services application started successfully. New features and additions for this release 8 User s Guide This release of the IBM Workplace Collaboration Services API Toolkit contains the following new features and additions that differentiate it from Release 1.0 of the Toolkit: v Component and Application Infrastructure Services APIs -- Use these APIs to access services and content provided by existing IBM Workplace business components and to manage IBM Workplace applications and templates. For

15 example, you can navigate or create discussion topics, send mail, schedule a Web conference, create a new application from a template, change membership for an existing application, and so on. 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 that uses less screen space than the IBM Workplace mail portlet. The Component and Application Infrastructure Services APIs can be accessed using either Java or Web Services. v IBM Workplace Client Technology platform APIs -- Use these APIs to build components for the IBM Workplace Client Technology platform and access Workplace Client services and content. These APIs include IBM Workplace server APIs adapted for the IBM Workplace Client Technology platform, as well as other APIs specific to the Workplace Client. v Additional toolkit sample code For brief descriptions of the new APIs, see Overview of the IBM Workplace Collaboration Services API toolkit. Chapter 1. IBM Workplace Collaboration Services API Toolkit 9

16 10 User s Guide

17 Chapter 2. IBM Workplace Collaboration Services Server APIs Toolkit Server APIs The IBM Workplace Collaboration Services API Toolkit is designed for developers who want to extend the IBM Workplace platform with new portlets or business components. The toolkit provides the following public server APIs (Application Programming Interfaces) for developer use: Collaborative Application Component Interfaces You can use these Java interfaces to build business components that integrate with the IBM Workplace collaborative environment and infrastructure. IBM Workplace Collaboration Services uses these interfaces to interact with your components, manage component life cycle and community membership, and incorporate your components with 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 Services API to access services and content provided by existing IBM Workplace Collaboration Services business components. For example, you can navigate or create discussion topics, send mail, schedule a Web conference, and so on. You can use the API 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 this API to enhance IBM Workplace Collaboration Services capabilities. For example, you can build a quick mail portlet to send mail from the IBM Workplace Collaboration Services user interface that uses less of the screen than the IBM Workplace Collaboration Services mail portlet. The Component Services API is implemented as stateless session EJBs, which can be accessed remotely through Java, using delegates, or Web Services. You can use the Application Infrastructure Services API to manage IBM Workplace applications and application templates. For example, you can do the following activities: v Access application and template catalogs. v Create and modify applications and templates. v Manage application instances. The Application Infrastructure Service API is implemented as stateless session EJBs and can be accessed remotely through Java, using delegates, or Web services. Like the Component Services API, the Application Infrastructure Services API can be used by both custom business components and external applications. For more information about this toolkit, go to the IBM Workplace Collaboration Services API Toolkit page athttp:// in the Lotus Developer Domain. This page contains links to documentation, the latest product information, and pages where you can download the product itself or related material such as sample programs. Copyright IBM Corp. 2004,

18 Collaborative Application Component Interfaces The IBM Workplace Collaboration Services API Toolkit is designed for developers who want to extend the IBM Workplace Collaboration Services with new portlets or business components. The toolkit provides a number of public APIs (application programming interfaces) for developer use. One group of these APIs is called the Collaborative Application Component Interfaces. These Java interfaces let you build business components that integrate with the IBM Workplace collaborative environment and infrastructure. The Collaborative Application Component Interfaces let IBM Workplace manage the following component aspects: v Lifecycle - used to notify your component when the containing application is created or destroyed, or when the component is added to a template. Allows the component to create and destroy any resources needed while the application is running. If you implement any of these interfaces, you must implement the Lifecycle interface. v Membership - used to notify your component when members are added to or removed from community roles. Allows the component to grant or revoke member access to resources that it manages. v Templatable - used to get information that allows your component to be used in an application template. v Sensor - used to get information about resources managed by a component, for example, disk space usage. This information is used, for example, to enforce Workplace application quotas. v Transactional - used to determine whether your component s Lifecycle and Membership methods support global transactions. You implement these interfaces in your collaborative application component stateless session EJB. None of these interfaces are required to build a IBM Workplace application component. However, if you do implement any of these interfaces, you must implement the Lifecycle interface. The Workplace public APIs and interfaces also supplement the public APIs provided by the underlying WebSphere and Portal platforms (not covered in this toolkit). For complete reference information on these interfaces, refer to the IBM Workplace Collaborative Application Component Interface Javadoc in the lwpapi25\lwpapi\javadoc directory. Related concepts Overview of the IBM Workplace Collaboration Services API toolkit on page 1 Application development using the Collaborative Application Component Interfaces on page 13 IBM Workplace business components on page 13 Business component architecture on page User s Guide

19 Application development using the Collaborative Application Component Interfaces The topics in this section include the following information about application development using the Collaborative Application Component Interfaces: v IBM Workplace business components v Business component architecture on page 14 v IBM Workplace applications on page 14 v Guidelines for building components on page 15 v Guidelines for packaging components on page 15 v Guidelines for deploying components on page 16 Related concepts Collaborative Application Component Interfaces on page 12 IBM Workplace business components Business components are the building blocks of IBM Workplace applications. Each component provides an encapsulation of a business concept, process, or service, for example, mailbox, discussion, support trouble ticket, search, and so on. IBM Workplace includes many business components, such as the following examples: v Discussion v Team Calendar v Team Task List v Contact List v Form v Document Library v v Membership/Roles Search v People Finder IBM Workplace business components can be classified in the following categories: v Distributed components, including business domain objects (for example, calendar) and services (for example, search). Distributed components are implemented as stateless session EJBs (Enterprise Java Beans) so they can be deployed anywhere and accessed remotely. v Collaborative application components, which are distributed components that integrate with the IBM Workplace collaborative infrastructure. Collaborative application component EJBs implement the Collaborative Application Component Interfaces that allow IBM Workplace to manage component life cycle, membership, and so on. v User interface components including portlets, IBM Workplace Client views, JSPs, tag libraries, and so on. v Other components, including business delegates used to access business logic in an application. After you use the toolkit to create your own business components, use IBM Workplace Templates and Applications to incorporate your component into IBM Workplace applications and application templates. Chapter 2. IBM Workplace Collaboration Services Server APIs 13

20 Related concepts Business component architecture Business component architecture The Java 2 Platform, Enterprise Edition (J2EE) platform defines the standard for multi-tier enterprise applications. Using multiple tiers is a proven way to develop highly-scalable applications. The IBM Workplace platform leverages 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, Workplace Client Technology views, and so on. 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. In a typical deployment, the Service tier is located on a different server from the other tiers. In the IBM Workplace platform, the business logic is implemented in stateless session EJBs (Enterprise Java Beans). The business delegates in the Workspace tier communicate with the Service-tier EJBs using standard protocols such as RMI/IIOP (Java Remote Method Invocation technology run over the Internet Inter-Orb Protocol). 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. Like the Service tier, the Resource tier is typically located on a different server from the other tiers. Your business components should use this four-tier architecture to maximize scalability. Not all business components require all four tiers. For example, some business components do not manage their own storage and do not use the Resource tier. Related concepts IBM Workplace business components on page 13 IBM Workplace applications An IBM Workplace application is a template-based assembly of components, such as , chat, discussions, document libraries, tasks, and forms. The intent of the application is to bring together people, content, and processes in order to complete a task more efficiently. IBM Workplace Collaboration Services users can use the applications that are provided or create their own applications with the templates provided in IBM Workplace Collaboration Services. IBM Workplace applications include the following types of applications: v Team projects v Web conferences v Communities of practice v Project rooms v Sales strategy planning 14 User s Guide

21 v Customer rapid response team The following types of users create these applications: v Component developer -- builds IBM Workplace application and business components using the J2EE programming model. This person uses IBM Workplace APIs to integrate custom components with IBM Workplace and access Lotus component services, and uses external APIs to integrate custom components with other systems. v Solutions provider and system integrator -- uses IBM Workplace APIs or IBM Workplace Templates and Applications to create application templates incorporating Lotus and third-party business components. This person also uses IBM Workplace APIs to access IBM component services from other systems. v Business user -- creates IBM Workplace applications from existing templates, or uses IBM Workplace Templates and Applications to create and customize application templates for other users. No coding is required. Related concepts IBM Workplace business components on page 13 Guidelines for building components Use the following general guidelines for building components with the IBM Workplace Collaboration Services API Toolkit: v Use the collaborative application component sample provided with the toolkit as the starting point for your own component. For step-by-step instructions on how to create an application using the sample shipped with the toolkit, refer to the toolkit samples section of this documentation. v Refer to the WebSphere Portal Information Center at your site for detailed information on the various APIs and technologies used to create portlets. v Use WebSphere Studio or other J2EE development tools. This toolkit provides resources specifically for WebSphere Studio Application Developer, along with general documentation you can use for other tools. v If you use WebSphere Studio for creating portlets, download and install the WebSphere Portal Toolkit for WebSphere Studio to facilitate developing and debugging your portlets. See for more information. Related concepts Guidelines for packaging components Guidelines for deploying components on page 16 Toolkit samples on page 23 Guidelines for packaging components Use the following general guidelines for packaging components made with the IBM Workplace Collaboration Services API Toolkit. For more complete instructions, refer to the toolkit samples section of this documentation. v Use Standard J2EE packaging technologies, except for including the Web application (portlet) in an EAR file, which is not currently supported in WebSphere Portal 5.0 and higher. v Package the portlet application in a WAR file, which contains portlet code, deployment descriptors, and other resources. v Configure component settings such as: Selecting the JNDI name for collaborative application component EJB and updating the deployment descriptor and portlet.xml. Chapter 2. IBM Workplace Collaboration Services Server APIs 15

22 Adjusting other configuration settings as needed. v Package the other parts of the business component (for example, J2EE artifacts such as EJBs, jars, deployment descriptors, and so on) in an EAR file. One EAR file per server is recommended for distributed components. Refer to the J2EE specifications for more information. WebSphere Studio automates many of these steps. Related concepts Guidelines for building components on page 15 Toolkit samples on page 23 Guidelines for deploying components Guidelines for deploying components Use the following general guidelines for deploying components made with the IBM Workplace Collaboration Services API Toolkit: v Deploy the portlet WAR file to the IBM Workplace server using the IBM WebSphere Portal Administration user interface or the XML configuration interface. v Deploy the business component EAR files to the server using the WebSphere Administrative Console. v Configure portlet access control using the WebSphere Portal Administration user interface. By default, only the Portal administrator has access to new portlets. v Use IBM Workplace Templates and Applications to incorporate the new component into a new or existing application template. When you add a portlet to a page, IBM Workplace Templates and Applications finds the associated collaborative application component EJB using the JNDI name in the portlet.xml file. v Save the new or modified template in the template catalog. For more complete instructions, refer to the toolkit samples section of this documentation. Related concepts Guidelines for building components on page 15 Guidelines for packaging components on page 15 Toolkit samples on page 23 Creating collaborative components with the Collaborative Application Component Interfaces The Collaborative Application Component interfaces let you build business components that integrate with the IBM Workplace collaborative infrastructure. The Java interfaces that make up this API are used by IBM Workplace to interact with your component. You access the Collaborative Application Component interfaces through your collaborative application component stateless session EJB (Enterprise Java Bean) and need only to implement the specific interfaces that you need. The toolkit includes a sample business component with a collaborative application component EJB. If you do not need to use any of the Collaborative Application Component Interfaces, you do not need to provide a collaborative component EJB. Related concepts 16 User s Guide

23 Toolkit samples on page 23 Collaborative Application Component Interfaces files Collaborative Application Component Interfaces sample The toolkit provides a sample that you can use to create a collaborative application component using the Collaborative Application Component Interfaces. The Collaborative Application Component Sample is designed with the following objectives in mind: v Show the code elements needed to build a basic collaborative application component. v Demonstrate how to integrate with and use the IBM Workplace Templates and Applications editors to create a simple IBM Workplace template and application that makes use of the sample collaborative application component using the Collaborative Application Component Interfaces. v Provide a set of recommended best practices for developing IBM Workplace collaborative components and applications. Related concepts Toolkit samples on page 23 Collaborative Application Component Interfaces files The following files are required when creating Collaborative Components with the Collaborative Application Component Interfaces: v Sample files -- these sample collaborative application component files are used as the starting point for your own components. The sample consists of files in directories under the toolkit directory lwpapi25\lwpapi\samples\collabcomponent. v lwpapi25_core.jar -- Data object API and Collaborative Application Component interfaces. v lwpapi25_core_impl.jar -- Data object API implementation. v lwpapi25_delegates.jar -- Component and Application Infrastructure Services API delegates that provide access to the services APIs without requiring you to access the services EJBs directly. v lwpapi25_services.jar -- Component and Application Infrastructure Services API interfaces. v lwpapi25_services.ear -- Component and Application Infrastructure Services API implementation. Related concepts Toolkit samples on page 23 Component and Application Infrastructure Services Interfaces The IBM Workplace Collaboration Services API Toolkit provides the following service APIs: Component Services API You can use this API to access services and content provided by existing IBM Workplace business components. For example, you can do the following: v Get a discussion thread v Create a document Chapter 2. IBM Workplace Collaboration Services Server APIs 17

24 v Send mail v Schedule meetings You also can use this API to integrate IBM Workplace with other systems. For example, your corporate help desk system could be configured to use IBM Workplace Messaging. Third-party business components can use this API to enhance IBM Workplace capabilities. For example, you can build a mail portlet to send mail from the IBM Workplace user interface without requiring the screen real estate of the IBM Workplace mail portlet. You can also use this API in custom components or external applications. These APIs are implemented as service-tier stateless session EJBs and can be accessed remotely through Java, using delegates, or Web services. The following list summarizes the Component Services API based on the specific component being accessed: v Calendar -- create, delete, and modify calendar entries; schedule, cancel, and reschedule meetings; search calendar. v Discussion - create, delete, and modify forums and postings; search and navigate forums. v Document Library - create, delete, and modify documents and folders; search and navigate documents. v Mail - create, delete, and modify messages, folders, and file attachments; send and search mail. v Web Conferences - manage, schedule, search, cancel, and reschedule web conferences. Application Infrastructure Services API With this API you can manage IBM Workplace applications and application templates. For example, you can do the following tasks: v Access application and template catalogs v Create and modify applications and templates v Manage application instances The Application Infrastructure Services API is implemented as stateless session EJBs and can be accessed remotely through Java, using delegates, or Web services. Like the Component Services API, the Application Infrastructure Services API can be used by both custom business components and external applications. For complete reference information on these interfaces, refer to the IBM Workplace Component and Application Infrastructure Services Interfaces Javadoc which is included with this toolkit in the lwpapi25\lwpapi\javadoc directory. Related concepts Component and Application Infrastructure Services accessed with Java on page 20 Component and Application Infrastructure Services accessed with Web Services on page 21 IBM Workplace business components on page User s Guide

25 Application development using the Component and Application Infrastructure Services Interfaces The topics in this section include the following information to help you to understand application development using the Component and Application Infrastructure Services Interfaces : v Common features of the Component and Application Infrastructure Services Interfaces v Security with Component and Application Infrastructure Services v Component and Application Infrastructure Services accessed with Java v Component and Application Infrastructure Services accessed with Web Services Related concepts IBM Workplace business components on page 13 Common features of the Component and Application Infrastructure Services Interfaces The following features and options are common to the Component Services API and the Application Services Infrastructure API: v Common data retrieval options for all IBM Workplace Collaboration Services components including the ability to Request as much or as little data as you want Limit the number of objects returned Limit the size of each object returned v Common search options for all IBM Workplace components through a Search query string that supports both full-text and parametric searches (for example, java +ibm -coffee and IBM Workplace.) Different IBM Workplace components support different options for search strings. v Public APIs based on internal public APIs. These Public APIs are exposed through service-tier stateless session EJBs. v API services and data objects are exposed through Java interfaces. v APIs are accessed through EJBs and delegates. v Data retrieval implementation uses Web Data Object (WDO) mediators for each component. These mediators construct data graphs to transfer data. Security in the Component and Application Infrastructure Services APIs Application security with the Component and Application Infrastructure Services APIs is handled in the following ways: v Authentication -- J2EE container-managed security governs access to service EJBs. v Access control and policy -- Internal public component APIs handle all access control. These APIs cannot be used to bypass access control or policies that would be enforced by IBM Workplace Collaboration Services. v Encryption and signing -- Encryption keys are not currently available in the Service tier. As a result, policies for encryption cannot be fully enforced (except to fail operations that require an encryption key) v Active content, viruses, and spam -- The Mail and Instant Messaging SPIs handle content filtering. The Component and Application Infrastructure Services APIs do not do automatic content filtering. Chapter 2. IBM Workplace Collaboration Services Server APIs 19