Lotus Workplace Products API Toolkit

Lotus Workplace Products API Toolkit Version 1.0 User s Guide G210-1918-00

Note Before using this information and the product it supports, read the information in Notices, on page 43. First Edition (October 2004) This edition applies to ersion 1.0 of IBM Lotus Workplace Products API Toolkit (product number L-GHUS-5ZZLAA) and to all subsequent releases and modifications until otherwise indicated in new editions. Licensed Materials-Property of IBM Copyright International Business Machines Corporation 2004. All rights resered. US Goernment Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents Getting Started with the Toolkit.... 1 Introduction to the IBM Lotus Workplace Products API Toolkit...............1 Contents of the IBM Lotus Workplace Products API Toolkit................2 Deelopment requirements for the IBM Lotus Workplace Products API Toolkit........3 Lotus Workplace APIs User s Guide.. 5 Introducing the Collaboratie Application Component Interfaces...........5 Collaboratie Application Component interfaces oeriew..............5 Before you begin: Understanding LWP Component and Application Deelopment........6 Workplace business components oeriew...6 Business component architecture oeriew...7 Workplace applications oeriew......7 General guidelines for building components with the Lotus Workplace Products API Toolkit...8 General guidelines for packaging components made with the Lotus Workplace Products API Toolkit...............8 General guidelines for deploying components made with the Lotus Workplace Products API Toolkit...............9 Creating Collaboratie Components with the Collaboratie Application Component Interfaces..9 The Collaboratie Application Component Interfaces..............10 About the Collaboratie Application Component Sample...............11 Working with the Collaboratie Application Component Interface files.........11 IBM Lotus Workplace Products API Toolkit Samples 11 The Collaboratie Application Component Sample...............12 The Collaboratie Application Component Sample components..........12 Working with the Collaboratie Application Component Sample in WebSphere Studio...13 Deploying the sample.ear file to the serer..17 Deploying the sample portlet.war file to the serer...............18 Adding the installed portlet to a new application template..............19 Creating and iewing the application from the newly created application template.....20 Instant Messaging SPI User s Guide.. 21 Introducing the Instant Messaging SPI.....21 Getting started.............21 About SIP...............22 Example: Creating a chat logging serlet.... 22 The Contact class............23 Compatibility with future releases of Lotus Workplace...............24 Mail Messaging SPI User s Guide... 25 IBM Lotus Workplace Products API Toolkit Mail Messaging SPI oeriew..........25 Mail Messaging handler oeriew.......25 HandlerExtension interface........26 HandlerExtMessage interface.......27 HandlerExtRecipient interface.......27 ContentSink interface..........28 ChainedContentFilter class (implements ContentSink).............28 Mail Messaging delierer oeriew......29 DelieryExtension interface........29 DeliererExtMessage interface.......29 DeliererExtRecipient interface.......30 Additional aailable Mail Messaging interfaces..30 Extension interface...........31 ExtMessage interface..........31 MessageAddress interface........32 Building a Mail Messaging processing extension..32 Setting the correct classpath to use the Mail Messaging SPI.jar files.........32 Writing a Mail Messaging processing extension 32 Register the mail processing extension....34 Configuring a Mail Messaging processing extension..............35 Running a Mail Messaging processing extension 36 JSP Tags User s Guide........ 37 Custom.JSP tags used with the IBM Lotus Workplace Products API Toolkit, 1.0...... 37 Person tag: syntax and reference...... 37 OnlineCenter tag: syntax and reference.... 39 Appendix. Notices.......... 43 Programming interface information......44 Trademarks..............45 Copyright IBM Corp. 2004 iii

i User s Guide

Getting Started with the Toolkit Introduction to the IBM Lotus Workplace Products API Toolkit The IBM Lotus Workplace Products API Toolkit is designed for deelopers who want to extend the Lotus Workplace platform with new portlets or business components. The toolkit does this by proiding a number of public APIs (Application Programming Interfaces) and SPIs (Serice Proider Interfaces) for customer use. The Workplace public APIs also supplement the public APIs proided by the underlying WebSphere Application Serer and WebSphere Portal platforms (not included in this toolkit). The goal of the Lotus Workplace Products API Toolkit is to allow you to build business components, portlets, and other components using the J2EE programming model. Use the API Toolkit in conjunction with a J2EE deelopment enironment such as WebSphere Studio Application Deeloper. This release of the toolkit includes the following APIs and SPIs: Collaboratie Application Component Interfaces These Jaa interfaces let you build business components that integrate with the Lotus Workplace collaboratie enironment and infrastructure. Lotus Workplace uses these interfaces to interact with your components, manage component life cycle and community membership, and incorporate your components in Lotus Workplace applications and application templates. You implement these interfaces in your collaboratie application component stateless session EJB. Workplace Mail Messaging SPI This Jaa SPI lets you build email message handlers that intercept mail messages before deliery and optionally redirect them or modify message content. Message handlers can perform irus scanning, actie content filtering, spam filtering, or any other desired filtering operations. Workplace Instant Messaging SPI This Jaa SPI lets you build instant message handlers that intercept instant messages before deliery and optionally block them, modify message content, or perform other operations; for example, logging, saing, or translating messages. Lotus Workplace JSP tags The Lotus Workplace JSP tags include the following: Person tag OnlineCenter tag Use these JSP tags to incorporate people and presence awareness into portlet JSPs. Future releases of the API Toolkit will proide additional APIs and SPIs; for example: Component Serices API This API lets you access serices and content proided by existing Lotus Workplace business components. For example, you can naigate or create discussion topics, send mail, schedule a web conference, and so on. You can use the API to integrate Lotus Workplace with other systems. For Copyright IBM Corp. 2004 1

example, your corporate Help Desk system could be configured to use Lotus Workplace Messaging. Third-party business components can use this API to enhance Lotus Workplace capabilities. For example, you can build a quick mail portlet to send mail from the Lotus Workplace user interface without requiring the screen real estate of the Lotus Workplace mail portlet. This API is implemented as stateless session EJBs and can be accessed remotely ia Jaa or Web serices. Application Infrastructure Serices API This API lets you manage Workplace applications and application templates; for example, you can: Access application and template catalogs. Create and modify applications and templates. Manage application instances. Access community membership. Access collaboratie context. This API is implemented as stateless session EJBs and can be accessed remotely ia Jaa or Web serices. Like the Component Serices API, the Application Infrastructure Serices API can be used by both custom business components and external applications. Workplace Client APIs These APIs let you build components for the Lotus Workplace Client Technology platform and access Workplace Client serices and content. These APIs include Lotus Workplace serer APIs adapted for the Lotus Workplace Client platform, as well as other APIs specific to the Workplace Client. Note: This release of the API Toolkit contains preliminary Jaadoc for the Component Serices and Application Infrastructure Serices APIs, which will be aailable in a future API Toolkit release. The Jaadoc can be found in the lwpapi10\lwpapi\jaadoc\lwpapi25_preiew directory. The Jaadoc proides a preiew of some of the capabilities that we expect to proide in these APIs, but the actual APIs that will be proided may ary from those in the Jaadoc. Other programmability technologies that are aailable and used by Workplace include the following: WebSphere Portlet API and JSR 168 Portlet API (aailable in WebSphere Portal ) Struts portlet framework (aailable in WebSphere Portal ) Cooperatie portlets (aailable in WebSphere Portal ) For more information about this toolkit, isit the Lotus Deeloper Domain (http://www.lotus.com/ldd). The IBM Lotus Workplace Products API Toolkit page (http://www.lotus.com/ldd/lwpapi) contains links to documentation, the latest product information, and pages where you can download the product itself or related material such as sample programs. Contents of the IBM Lotus Workplace Products API Toolkit This topic describes the contents of the Lotus Workplace Products API Toolkit. The Lotus Workplace Products API Toolkit contains the following pieces: 2 User s Guide

lwpapi10 readme.txt - toolkit contents, requirements, installing documentation runtime software, accessing documentation doc - toolkit documentation and runtime files (if installed) license - license files lwpapi - Collaboratie Application Component Interfaces files jaadoc lwpapi10 - Jaadoc for this API Toolkit release lwpapi25_preiew - Preliminary Jaadoc for the next API toolkit release lib - Platform-independent Jaa libraries (JAR files) samples CollabComponent - Collaboratie Application Component sample program files, including project files for WebSphere Studio Application Deeloper imspi - Instant Messaging SPI files jaadoc - Jaadoc lib - Platform-independent Jaa libraries (JAR files) samples chatlogging ChatLoggingApp.Jaa mailspi - Mail Messaging SPI files jaadoc - Jaadoc lib - Platform-independent Jaa libraries (JAR files) Deelopment requirements for the IBM Lotus Workplace Products API Toolkit This topic coers system requirements for deeloping applications with the IBM Lotus Workplace Products API Toolkit. To use the IBM Lotus Workplace Products API Toolkit, you must hae the following installed: One of the following operating systems: Microsoft Windows 2000 Microsoft Windows XP RedHat Linux 8 SuSe Linux 8.1 Jaa Deelopment Kit 1.3.1 Note: Although the API Toolkit can only be used with the operating systems listed aboe, the components and applications you create using the API Toolkit are not restricted to those operating systems. Applications created with this ersion of the toolkit are supported on all platforms supported by Lotus Workplace 2.0. Instant Messaging SPI requirements To use the Instant Messaging SPI, you must install the Jaa Serlet API, aailable as part of the Jaa 2 Platform, Enterprise Edition SDK or separately. Mail Messaging SPI requirements There are no special requirements for deeloping Mail Messaging SPI applications beyond the basic toolkit requirements listed aboe. Getting Started with the Toolkit 3

Lotus Workplace API requirements To create components or applications that use the Lotus Workplace Component Serices API, you must hae the following software installed: A J2EE 1.3 Jaa deelopment enironment that supports the Enterprise Jaa Bean 2.0 specification and uses the Jaa Deelopment Kit 1.3.1. We recommend IBM WebSphere Studio Application Deeloper ersion 5.1.2; ersion 5.0 and later should work, as well. IBM WebSphere Site Deeloper is not supported. If you do not hae the Portlet deelopment enironment in WSAD, you can download and use the separately installable IBM Portal Toolkits (http://www.ibm.com/websphere/portal/toolkit). JSP tag requirements To create portlets that use the JSP tags documented in this toolkit, your deelopment enironment must conform to the requirements described in the documentation for the ersion of WebSphere Portal on which the portlets will be deployed. For more information, see Installing for deelopment in the Installing section of the information center for your WebSphere Portal ersion. Information centers can be accessed here: http://www.ibm.com/deeloperworks/websphere/zones/portal/proddoc.html 4 User s Guide

Lotus Workplace APIs User s Guide Introducing the Collaboratie Application Component Interfaces This topic introduces the Collaboratie Application Component Interfaces. The IBM Lotus Workplace Products API Toolkit is designed for deelopers who want to extend the Lotus Workplace platform with new portlets or business components. The Toolkit does this by proiding a number of public APIs (Application Programming Interfaces) for customer use. The Workplace public APIs and interfaces also supplement the public APIs proided by the underlying WebSphere and Portal platforms (not coered in this Toolkit). Note: For complete reference information on these interfaces, refer to the Lotus Workplace Collaboratie Application Component Interface Jaadoc which is located in the lwpapi10/lwpapi/jaadoc/lwpapi10 directory. Refer also to the Lotus Workplace API 2.5 Preiew Jaadoc in the lwpapi10/lwpapi/jaadoc/lwpapi25_preiew directory for a look at upcoming API features. Collaboratie Application Component interfaces oeriew This topic proides a brief description of the Collaboratie Application Component interfaces. The Collaboratie Application Component Interfaces enable you to build business components that integrate with the Workplace collaboratie infrastructure. These Jaa interfaces are used by Workplace to interact with your components. You implement these interfaces in your collaboratie application component stateless session EJB. The Lotus Workplace Products API Toolkit includes a sample business component with collaboratie application component EJB implementing the Collaboratie Application Component Interfaces. The Collaboratie Application Component Interfaces let Lotus Workplace manage the following component aspects: 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 application is running. Membership - used to notify your component when members are added to or remoed from community roles. Allows the component to grant or reoke member access to resources that it manages. Templatable - used to get information that allows your component to be used in application template. Sensor - used to get information about resources managed by component, for example, disk space usage. This information is used, for example, to enforce Workplace application quotas. Transactional - used to determine whether your component s Lifecycle and Membership methods support global transactions. Copyright IBM Corp. 2004 5

None of these interfaces are required to build a Workplace application component - only use the ones you need. Howeer, if you do implement any of these interfaces, you must implement the Lifecycle interface. Before you begin: Understanding LWP Component and Application Deelopment This topic introduces you to the basic concepts of Workplace component and application deelopment. The topics in this section include the following: Workplace business components oeriew Business component architecture oeriew Workplace applications oeriew General guidelines for building components using the Workplace Toolkit General guidelines for packaging components using the Workplace Toolkit General guidelines for deploying components using the Workplace Toolkit Workplace business components oeriew This topic describes Workplace business components. Business components are the building blocks of Workplace applications. Each component proides an encapsulation of a business concept, process, or serice, for example, mailbox, discussion, trouble ticket, search, etc. Workplace includes many Lotus business components. These include, for example: Discussion Team Calendar Team Task List Contact List Form Document Library Membership/Roles Search People Finder Business components as used in Workplace can be classified as the following: Distributed components including business domain objects (for example, calendar) and serices (for example, search). Distributed components are implemented as stateless session EJBs (Enterprise Jaa Beans) so they can be deployed anywhere and accessed remotely. Collaboratie application components, which are distributed components that integrate with the Workplace collaboratie infrastructure. Collaboratie application component EJBs implement the Collaboratie Application Component Interfaces that allow Workplace to manage component lifecycle, membership, and so on. UI components including portlets, Workplace Client iews, JSPs, tag libraries, etc. Other components, including business delegates used to access business logic. 6 User s Guide

After you use the Toolkit to create your own business components, use Workplace Builder to incorporate your component into Workplace applications and application templates. Business component architecture oeriew This topic proides an oeriew of the architecture used by Lotus business components. The J2EE (Jaa 2 Platform, Enterprise Edition) platform defines the standard for multi-tier enterprise applications. Using multiple tiers is a proen way to deelop highly-scalable applications. The Lotus Workplace platform leerages this architecture. The Lotus Workplace platform uses four tiers: User tier - this tier represents the on the glass or user interface experience. This tier contains code and components used by the user interface, for example, portlets, JSP tag libraries, Workplace Client iews, etc. Workspace tier - this tier is co-located with the user tier. This tier contains business delegates that proide access to business logic in the Serice tier, as well as other business logic that does not require access to the Serice tier. Serice tier - this tier is where most (if not all) of the business logic is implemented. In a typical deployment, the Serice tier would be located on a different serer than the other tiers. In Lotus Workplace, the business logic is implemented in stateless session EJBs (Enterprise Jaa Beans) - particularly in the case of the Collaboratie Application Component Interfaces. The business delegates in the Workspace tier communicate with the Serice-tier EJBs using standard protocols such as RMI/IIOP or Web serice. Because the Serice tier uses stateless session EJBs for improed performance, and session-based caching needs to be handled by the business delegates in the Workspace tier. Resource tier - this tier handles access to shared resources, such as databases and directories, and proides both the storage for those resources and the framework used to access that storage. Like the Serice tier, the Resource tier is typically located on a different than the other tiers. The business components proided by Lotus use this four-tier architecture and it is recommended that your business components do the same in order to maximize scalability. Note that not all business components will require all four tiers. Some business components, for example, do not manage their own storage and will not use the Resource tier. Workplace applications oeriew This topic proides an oeriew of what comprises a Workplace application. A Lotus Workplace application is a template-based assembly of components, such as e-mail, 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. Workplace users can use the applications that are proided with Lotus Workplace or create new ones. Examples of IBM Lotus Workplace applications include the following: Team Projects Lotus Workplace APIs User s Guide 7

Web Conferences Communities of Practice Project Rooms Sales Strategy Planning Customer Rapid Response Team Users who create these applications include the following: Component deeloper - builds Workplace application and business components using the J2EE programming model. This person uses Workplace APIs to integrate custom components with Workplace and access Lotus component serices, and uses external APIs to integrate custom components with other systems. Solutions proider and system integrator - uses Workplace APIs or Workplace Builder to create application templates incorporating Lotus and third-party business components. This person also uses Workplace APIs to access Lotus component serices from other systems. Business user - creates Workplace applications from existing templates, or uses Workplace Builder to create and customize application templates for other users. No coding is required. General guidelines for building components with the Lotus Workplace Products API Toolkit The following topic presents general guidelines for building components with the Workplace Products API Toolkit. Use the following general guidelines for building components with the Workplace Products API Toolkit: Use the collaboratie application component sample proided 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. Refer to the WebSphere Portal InfoCenter at your site for help with creating portlets. The WebSphere Portal InfoCenter proides detailed information on the arious APIs and technologies used to create portlets. Use WebSphere Studio or other J2EE deelopment tools. This Toolkit will proide resources specifically for WebSphere Studio Application Deeloper, along with general documentation you can use for other tools. If you use WebSphere Studio and plan to create portlets, you should also download and install the WebSphere Portal Toolkit for WebSphere Studio, which will make it much easier to deelop and debug your portlets. See www.ibm.com for more information General guidelines for packaging components made with the Lotus Workplace Products API Toolkit The following topic presents general guidelines for packaging components made with the Workplace Products API Toolkit. Use the following general guidelines for packaging components made with the Workplace Products API Toolkit. For more complete instructions, refer to the Toolkit Samples section of this documentation. 8 User s Guide

Use Standard J2EE packaging technologies - - EXCEPT for including the web application (portlet) in an EAR which is not currently supported in WebSphere Portal 5.0.X Package the portlet application in WAR file. This file contains portlet code, deployment descriptors, and other resources Configure component settings such as Select the JNDI name for collaboratie application component EJB and update the deployment descriptor and portlet.xml. Adjust other configuration settings as needed. Package the other parts of the business component (for example, J2EE artifacts like EJBs, jars, deployment descriptors, etc.) in an.ear file. One EAR per serer is recommended for distributed components. Refer to the J2EE specifications for more information. WebSphere Studio automates many of these steps. General guidelines for deploying components made with the Lotus Workplace Products API Toolkit The following topic presents guidelines for deploying components made with the Workplace Products API Toolkit. For more complete instructions, refer to the Toolkit Samples section of this documentation. Use the following general guidelines for deploying components made with the Toolkit: Deploy the portlet.war file to the Workplace serer using the WebSphere Portal Admininstration UI or the XML configuration interface. Deploy the business component.ear file(s) to the serer using the WebSphere Admininstratie Console. Configure portlet access control using Portal Admininstration UI. Only the Portal administrator will hae access to new portlets by default. Use Workplace Builder to incorporate the new component into a new or existing application template. When you add a portlet to a page, Workplace Builder finds the associated collaboratie application component EJB using the JNDI name in portlet.xml. Sae the new or modified template in the template catalog. Creating Collaboratie Components with the Collaboratie Application Component Interfaces This section proides information on creating collaboratie application components with the Collaboratie Application Component Interfaces. The Collaboratie Application Component Interfaces let you build business components that integrate with the Workplace collaboratie infrastructure. The Jaa interfaces that make up this API are used by Workplace to interact with your component. You implement these interfaces in your collaboratie application component stateless session EJB (Enterprise Jaa Bean) and need only to implement the interfaces that you need. The Toolkit includes a sample business component with collaboratie application component EJB. If you do not need to use any of the Collaboratie Application Component Interfaces, you do not need to proide a collaboratie component EJB. Lotus Workplace APIs User s Guide 9

This section contains topics on the following aspects of creating Collaboratie Components with the Collaboratie Application Component Interfaces: The Collaboratie Application Component Interfaces About the Collaboratie Application Component Sample Working with the Collaboratie Application Component Interface files The Collaboratie Application Component Interfaces Although you can add non-collaboratie portlets and components to a Lotus Workplace application, they do not take adantage of Workplace s instance management and collaboratie infrastructure. To use these capabilities, your component must include a stateless session EJB that implements one or more of the Collaboratie Application Component Interfaces. We call a component that has implemented any of these interfaces a collaboratie component. The Collaboratie Application Component Interface methods are essentially callbacks from Lotus Workplace to your component. They make it possible for your component to describe itself to Lotus Workplace so that it can be intelligently managed by the enironment, configured by the user, and used in a template with other components. To make your component collaboratie, you implement any or all of the following interfaces in your component s collaboratie component EJB. If you implement any of these interfaces, you must implement the Lifecycle interface. Lifecycle The Lifecycle interface is used by Lotus Workplace to notify the application component wheneer an instance of that component is created or destroyed. This happens when an application containing that component is created or deleted, or when the component is added to an application template. The component can use this information to create or initialize resources needed while the component is actie. Membership The Membership interface is used by Lotus Workplace to notify the application component wheneer members are added to or remoed from the community associated with the application that contains the component. The component can use this information to grant or reoke access to resources that it manages. In addition, the Membership interface allows the component to proide Workplace with a list of component-specific roles, which can be mapped to community roles using Workplace Builder. Sensor The Sensor interface is used by Lotus Workplace to get information about resources managed by the component, so that policies regarding resource usage (for example, disk space quotas) can be enforced. Templatable The Templatable interface is used by Lotus Workplace to incorporate the application component in an application template. This interface allows the component to sae information about itself when the template is saed in XML format. Transactional The Transactional interface is used by Lotus Workplace to determine if the application component can participate in a global transaction. Specifically, this interface is extended by the Lifecycle and Membership interfaces and 10 User s Guide

is used to determine if the component s implementation of Lifecycle or Membership supports the ability to undo changes if a global transaction is rolled back. For details on using these interfaces, refer to the Collaboratie Application Component Interfaces Jaadoc shipped with this toolkit. About the Collaboratie Application Component Sample The toolkit proides a sample that lets you create a collaboratie application component using the Collaboratie Application Component Interfaces. The Collaboratie Application Component Sample proided to you in this toolkit is designed with the following objecties in mind: To proide a simple code example that highlights what you need to do in order to build a basic collaboratie application component. To allow the integration and use of the Lotus Workplace Builder to create a simple Lotus Workplace template and application that makes use of the sample collaboratie application component using the Collaboratie Application Component Interfaces. To proide a set of recommended best practices for deeloping working Lotus Workplace collaboratie components and applications. For more complete information on how to use this sample, refer to the Toolkit Samples section of this documentation. Working with the Collaboratie Application Component Interface files This topic proides direction for working with the files required for creating your own collaboratie components with the Collaboratie Application Component Interfaces. The following files are required when creating Collaboratie Components with the Collaboratie Application Component Interfaces: Sample files - the sample collaboratie application component files proided with the API Toolkit should be used as the starting point for your own components. The sample consists of the directories under the Toolkit directory lwpapi10\lwpapi\samples\collabcomponent. lwp20api10.jar - archie (.JAR) file containing the public API interfaces. This jar file is in the Toolkit directory lwpapi10\lwpapi\lib and needs to be deployed with your collaboratie application component. lwp20api10_impl.jar - archie (.JAR) file containing the implementation of the public API interfaces. This jar file is also in the Toolkit directory lwpapi10\lwpapi\lib and needs to be deployed on the Workplace serer. For more information on using these files, refer to the Toolkit Samples section of this documentation. IBM Lotus Workplace Products API Toolkit Samples This topic describes the sample collaboratie application component proided in the Lotus Workplace Products API Toolkit. Lotus Workplace APIs User s Guide 11

This section of the documentation proides you with instructions on how to use the sample code. The topics in this section include the following: The Collaboratie Application Component Sample The Collaboratie Application Component Sample components Working with the Collaboratie Application Component Sample in WebSphere Studio Importing the sample files into your WebSphere Studio workspace Setting the sample classpath ariables. Generating the sample.war and.ear files Deploying the sample.ear file to the serer Deploying the sample portlet.war file to the serer Adding the installed portlet to a new application template Creating and iewing the application from the newly created application template Creating additional applications from the sample Troubleshooting applications The Collaboratie Application Component Sample This topic gies brief information on the Collaboratie Application Component sample. The Collaboratie Application Component Sample proided to you in this Toolkit is designed with the following objecties in mind: To proide a simple code example that highlights what you need to do in order to build a basic collaboratie application component. To allow the integration and use of the Lotus Workplace Builder to create a simple Lotus Workplace template and application that makes use of the sample collaboratie application component. To proide a set of recommended best practices for deeloping working Lotus Workplace components and applications. The Collaboratie Application Component Sample components This topic lists the components shipped with the Collaboratie Application Component Sample. The Collaboratie Application Component Sample consists of the following pieces: Collaboratie Application Component EJB (Enterprise Jaa Bean) - a skeletal source implementation is proided that highlights the Collaboratie Applications Component Interfaces: Lifecycle, Membership, Sensor, Transactional, and Templatable. The EJB further demonstrates the workings of a collaboratie application component. Collaboratie Application Component Sample Serice EJB - this is proided to demonstrate a gettext() serice EJB that returns a text message. This serice is used by the sample portlet. Sample Portlet - this sample displays the message retrieed from the gettext() serice. 12 User s Guide

Collaboratie Application Component Adapter EJB - an intermediary between the Collaboratie Application Component EJB and Lotus Workplace. The adapter EJB is used to map the public Collaboratie Application Component Interfaces to the internal ersions of those interfaces currently used by Lotus Workplace. For a ariety of reasons, the internal ersion of these interfaces could not be directly exposed for customer use. The Collaboratie Application Component Sample also demonstrates how to package and deploy business components for Lotus Workplace. Working with the Collaboratie Application Component Sample in WebSphere Studio This topic proides a summary of how to work with the Collaboratie Application Component Sample in WebSphere Studio Application Deeloper (WSAD). This information in this topic applies to WSAD ersions 5.1.1 and 5.1.2, but should work with any ersion of WebSphere Studio 5.1x that supports portlets and EJB projects. The following information proides a general summary of how to work with the Collaboratie Application Component Sample in the IBM WebSphere Studio Application Deeloper (WSAD) deelopment enironment. Use the following general steps to work with the sample: Import the sample files into your WSAD workspace Set the sample classpath ariables (you can perform this step either before or after importing the sample files) Generate the sample.war and.ear files To work with the sample in WSAD, you will need to use the IBM Portal Toolkit, which proides portlet deelopment and debugging tools for WebSphere Studio products. The Portal Toolkit is already included with WSAD Version 5.1.2. If you are using an earlier WSAD ersion, you can download the Portal Toolkit from http://www.ibm.com/software/info1/websphere/index.jsp?tab=products/portaltoolkit. In either case, you ll need to install the Portal Toolkit before you can use it. Although the instructions in this topic and the related ones are specific to WSAD, you should be able to use other J2EE deelopment enironments to work with the sample. The general procedure will be similar in all deelopment enironments; the specific instructions will depend on which deelopment enironment you are using. Importing the sample files into your WebSphere Studio workspace This topic proides instructions for importing the Collaboratie Application Component Sample files into your WebSphere Studio Application Deeloper (WSAD) workspace. The Collaboratie Application Component Sample includes WSAD-specific files that make it easy to work with the sample code in WSAD. To import the sample WSAD project files into your workspace, follow the instructions below. Although you can import the sample files into a workspace that already contains other projects, it is recommended that you use a separate workspace for the sample files. Before you import the samples into your WSAD workspace, make sure you hae installed the IBM Portal Toolkit for WebSphere Studio. The Portal Toolkit is already Lotus Workplace APIs User s Guide 13

included with WSAD Version 5.1.2, but if you are using an earlier WSAD ersion, you can download the Portal Toolkit from http://www.ibm.com/software/info1/websphere/index.jsp?tab=products/portaltoolkit. In either case, you need to install the Portal Toolkit before you can use it. Use the following steps to import the WSAD project files included with the sample into your WSAD workspace: 1. Open the IBM WebSphere Studio Application Deeloper (WSAD) deelopment enironment. 2. From the File menu, select Import, and select Existing Project into Workspace from the list. 3. Select the Browse button and naigate to the Toolkit directory lwpapi10\lwpapi\samples\collabcomponent\collabcomponentejb. 4. Select Finish to import the project file into the workspace. 5. Repeat steps 2-4 for each of the other directories in lwpapi10\lwpapi\samples\collabcomponent. As you import each project, you may see errors about unresoled dependencies or unbound classpath ariables in the WSAD Tasks iew - you can ignore these errors for now. After you import the sample files, you can specify the name that Workplace Builder will display to identify the sample component. The component name is set to Sample Business Component, but you can change it to something more meaningful, as follows: 1. In WSAD, expand the CollabComponentAdapterEJB project. 2. Expand the ejbmodule tree until you see the file ejb.properties. 3. Double-click the file to open it in the editor. 4. Change the alue of the component.display.name property as desired. Do not change any other properties. By using the aboe procedure, you will import the sample files into your WebSphere Studio workspace. Setting the sample classpath ariables This topic proides instructions for setting the classpath ariables in WSAD. Either before or after you import the Collaboratie Application Component Sample project files, you will need to set two classpath ariables in WSAD. Classpath ariables are used to configure the classpath information included with the sample so that the classpaths are set properly for your system. The two classpath ariables used by the sample are LWPAPI_HOME and WAS_HOME. LWPAPI_HOME specifies the location of the top-leel API Toolkit directory lwpapi10 and is used to locate API jar files proided with the Toolkit. The lwpapi10 directory is created under the directory into which you extracted the Toolkit zip file. For example, if you extracted the API Toolkit files to c:\lwpapitoolkit, you would set the LWPAPI_HOME classpath ariable to c:\lwpapitoolkit\lwpapi10. WAS_HOME specifies the location of the WebSphere Application Serer on which Lotus Workplace is installed, and is used to locate WebSphere and Lotus Workplace jar files that are needed to build and run the sample. The necessary jar files are the following: WAS_HOME\AppSerer\lib\jdom.jar 14 User s Guide

WAS_HOME\AppSerer\lib\wmm.jar WAS_HOME\WorkplaceSerer\ps_extdir\lwputil.jar When you work with the sample in WSAD, these jar files will need to be accessible from your deelopment system. You can use one of the following procedures to do this: Ask your Lotus Workplace serer administrator to proide you with these jar files and install them on your deelopment system using the same AppSerer and WorkplaceSerer directory structure shown aboe. If you use this option, set the WAS_HOME classpath ariable to the directory on your system that contains the AppSerer and WorkplaceSerer subdirectories. If you install Lotus Workplace on your deelopment system, set the WAS_HOME classpath ariable to the WebSphere program directory (for example, c:\websphere). After installing the required jar files, use the following steps to set the sample classpath ariables in WSAD: 1. Select Window Preferences from the menu. 2. Expand the Jaa entry on the list and select Classpath Variables. 3. Select the New button and enter LWPAPI_HOME in the Name field. 4. Either enter the Toolkit directory path in the Path field or select the Folder button and naigate to that directory and select OK. 5. Repeat steps 3 and 4 for the WAS_HOME classpath ariable, using the appropriate path alue. 6. Select OK to exit the dialog screens. By using the aboe procedure, you will set the sample classpath ariables in WSAD. Generating the sample.war and.ear files This topic proides instruction on how to use WebSphere Studio Application Deeloper (WSAD) to generate the.ear and.war files that you need to deploy your sample application. Before you can deploy your sample application, you need to generate the required EAR and.war files. You can do this after importing the sample project files into your WSAD workspace and setting classpath ariables. Before generating.ear and.war files, erify that the sample projects and classpath ariables are properly configured by rebuilding all the projects, using the Rebuild All command on the WSAD Project menu. You should see four errors in the WSAD Tasks iew, three of which mention missing required libraries. If you see errors about an unbound classpath ariable called WPS_V5_PLUGINDIR, resole them as follows: 1. If you haen t already installed the IBM Portal Toolkit, do so now. 2. Create a new portlet project using File New Project and select Portlet Deelopment from the list. 3. Enter a name for the project and select Finish. This will create the required classpath ariable. 4. If you wish, you can delete the new project you just created, as well as the corresponding DefaultEAR project, which WSAD created for you. Deleting these projects will not remoe the classpath ariable. Lotus Workplace APIs User s Guide 15

The missing required library errors occur because WSAD ersion 5.1.2 uses different classpaths for the IBM Portal Toolkit jar files than earlier WSAD ersions, and the sample application in the API Toolkit includes classpaths for both WSAD 5.1.2 and earlier ersions. To resole the errors, you ll need to remoe the classpaths that aren t needed for your WSAD ersion, as follows: 1. Right-click on the CollabComponentPortlet project and select Properties from the bottom part of the menu. 2. If necessary, select Jaa Build Path and make sure the Libraries tab is displayed. 3. There are six classpaths that begin with WPS_V5_PLUGINDIR. Three of them should hae a small yellow icon next to them, to indicate that they are inalid. Select the three inalid classpaths and click the Remoe button. If you hae difficulty seeing the icons, remoe the three classpaths that do not include shared\app (or shared/app ) if you are using WSAD 5.1.2, otherwise remoe the other three. After making these changes, use Rebuild All to rebuild all projects again. You should see no errors at this point. If you do see any other errors in your Tasks iew, reiew the topics about importing the sample project files and setting classpath ariables, and make sure you followed the instructions as written. After you resole any errors, use the instructions below to generate the sample.ear and.war files in WSAD. Make sure you use the Rebuild All command on the WSAD Project menu to rebuild all projects before proceeding with these instructions. 1. To generate the.ear file for the sample EJBs: a. Right-click on the CollabComponentSericeEJB project and select Generate Deployment and RMIC code. b. Make sure all listed projects are selected and select Finish to generate the code. c. Right-click on the CollabComponentEAR project and select Export from the menu. d. Select EAR file from the list. e. Verify that the Enterprise Application Project name is CollabComponentEAR. If not, select that project from the list. f. Enter a destination pathname for the.ear file. g. If you want to include the sample source code in the.ear, select the Export source files option. h. Select Finish. 2. To generate the.war file for the sample portlet: a. Right-click on the CollabComponentPortlet project and select Export from the menu. b. Select WAR file from the list. c. Verify that the Web Project name is CollabComponentPortlet. If not, select that project from the list. d. Enter a destination pathname for the.ear file. e. If you want to include the sample source code in the.war, select the Export souree files option. f. Select Finish. By using the aboe steps, you can generate the.ear and.war files that you need to deploy your sample application. 16 User s Guide

Deploying the sample.ear file to the serer This topic proides instruction on how to deploy the sample.ear file to the Lotus Workplace serer. To make the sample application aailable on the Lotus Workplace serer, begin by deploying the sample.ear file. This.EAR file contains the Collabaratie Application Component Adapter EJB, the Collaboratie Application Component EJB, and the Collaboratie Application Component Serice EJB. Use the following steps to do this. You may wish to print out this topic to use it as a guideline. 1. Copy the lwp20api10.jar and lwp20api10_impl.jar files from the Toolkit directory lwpapi10\lwpapi\lib into the <WAS_HOME>\PortalSerer\shared\app\lotusworkplacelib directory on the target serer, where <WAS_HOME> is the WebSphere Application Serer program directory (for example, c:\websphere). You only hae to do this the first time you deploy the sample.ear file to the serer. If you don t hae access to the file system of the WebSphere serer, ask your serer administrator to deploy these jar files for you. 2. Stop and then restart LotusWorkplace_Serer, WebSphere_Portal, and serer1. 3. Run the WebSphere Administratie console of the target deployment machine by browsing to http://machinename.subdomain.domain:9091/admin. Make sure that you specify Port 9091. Console 9091 specifies the Portal Serer where 9090 specifies the Application Serer 4. Logon as a user with administratie priileges. 5. Click Applications-Install New Application in the left-hand panel. Make sure you select a unique application name. 6. At the Preparing for the application installation screen under the Path selection, browse your machine file system for the.ear file that you generated from WSAD and then click Next. This will specify the.ear that you wish to upload and install. 7. Click Next at the Generate Default Bindings screen. 8. Click Next at the Step 1: Proide options to perform the installation screen screen. 9. At the Step 2: Proide options to perform EJB Deploy screen, use <WAS_HOME>\WorkplaceSerer\ps_extdir\lwputil.jar; <WAS_HOME>\PortalSerer\shared\app\lotusworkplacelib\lwp20api10_impl.jar; <WAS_HOME>\PortalSerer\shared\app\lotusworkplacelib\lwp20api10.jar; <WAS_HOME>\appserer\lib\jdom.jar, where <WAS_HOME> is as defined in Step 1 aboe. Note that <WAS_HOME> must be an absolute path (from the root of the drie). Click Next when you hae finished. Note: For installing on Linux, you would specify the following for the classpath, assuming <WAS_HOME> is /opt/websphere: /opt/websphere/workplaceserer/ps_extdir/lwputil.jar: /opt/websphere/portalserer/shared/app/lotusworkplacelib/ lwp20api10_impl.jar:/opt/websphere/portalserer/shared/ app/lotusworkplacelib/lwp20api10.jar:/opt/websphere/appserer/ lib/jdom.jar 10. Click Next at the Step 3: Proide JNDI names for Beans screen. 11. Click Next at the Step 4: Map EJB references to Beans screen. Lotus Workplace APIs User s Guide 17

12. At the Step 5: Map modules to application serers screen, specify the WebSphere Portal serer from the Clusters and Serers list and select all of the checkboxes under Modules. Click Apply and then Next when you hae finished. 13. At the Step 6: Map security roles to users/groups screen, select the lwpuser checkbox under Role. Click Next. 14. At the Step 7: Summary screen, click Next. You are now presented with a results screen. 15. When the results screen has completed and you see the...installed successfully message, click Sae to Master Configuration. 16. At the Sae screen, click Sae. 17. Browse back to the Applications-Enterprise Applications link (left-hand panel), and check the checkbox next to the name of your newly installed application.ear. Click Start to start the application. By using the aboe procedure, you will hae deployed the sample.ear file to the Lotus Workplace serer. Deploying the sample portlet.war file to the serer This topic proides instruction on how to deploy the sample portlet.war file to the Lotus Workplace serer. After you hae deployed the sample.ear file to the Lotus Workplace serer, you will need to deploy the sample portlet.war file in order to make your sample application aailable on the serer. This.WAR file contains all of the files required for deploying the sample application portlet. Use the following steps to do this. You may wish to print out this topic to use it as a guideline. 1. Browse to Lotus WorkPlace using the following URL: http://yourmachinename.yoursubdomain.yourdomain/lwp/workplace.. 2. Logon as a user with administratie priileges. 3. Go to the Workplace Administration user interface by clicking on the Administration tab. 4. At the Workplace Administration user interface, click on the Portlets selection (in the left-hand panel) to expand it. 5. Click Install. 6. At the Install portlets screen, browse your machine file system for the portlet.war file from WSAD and then click Next. This will specify the portlet.war that you wish to upload and install. 7. At the Install portlets screen, you will see The following portlets will be installed: followed by the name of your Sample portlet. Click Install to install the portlet. This may take a few minutes. 8. At the results screen that appears after the portlet has installed, select Portlets-Manage Applications from the left-hand panel. This will allow you to see a screen that will present a list of all successfully installed portlets. 9. Use the following steps to change access control on the new portlet so that other users can see it: a. On the Portal Adminstration Page, click on Access Resource Permissions. b. Select Portlets from the Resource Types list. 18 User s Guide