Level: Intermediate Hardy Groeger, Senior Software Engineer, IBM Corporation
Mel Gorman, Software Engineer
20 Dec 2004 Part two of our three-article series on application development with IBM Workplace focuses on the Lotus Workplace Products API Toolkit, including the SPIs, JSP tags, and Collaborative Application Component Interfaces, and the component architecture.
[Editor's note: IBM Workplace is synonymous with Lotus Workplace. In this article, we refer to IBM Workplace, or simply Workplace, but we refer to the Workplace Products API Toolkit 1.0 as the Lotus Workplace Products API Toolkit. Other products previously known by the Lotus Workplace brand, such as Lotus Workplace Team Collaboration, are referred to by Workplace: Workplace Team Collaboration, Workplace Messaging, and so on.]
After introducing you to the general IBM Workplace server architecture and some key concepts around application development in part 1, we now take a more detailed look at the overall programming model for IBM Workplace and specifically, what is required to implement new custom components and to integrate them with the IBM Workplace application infrastructure.
The Lotus Workplace Products API Toolkit provides a set of development tools as well as documentation and samples. (You can download the toolkit from the Lotus Workplace Products API Toolkit page.) In this article, we introduce the various APIs and SPIs that comprise the toolkit. Before diving into the Collaborative Application Component Interfaces, we review and reinforce the business component reference architecture that was briefly introduced in part 1. Finally, we explain the required steps to use the new custom components in Workplace templates and applications.
The Lotus Workplace Products API Toolkit supplements other J2EE, WebSphere, and WebSphere Portal specific development tools that are not covered in this article. The reader should already be familiar with the basics of J2EE development (especially EJBs) as well as portlet development for WebSphere Portal.
Lotus Workplace Products API Toolkit 1.0
The success of a collaborative application infrastructure such as IBM Workplace is highly dependent on the ability of developers, customers, business partners, ISVs, and solution providers to build new applications, to extend the existing applications to meet their needs, and to integrate with other systems. To fulfill these requirements, Lotus provides the Lotus Workplace Products API Toolkit 1.0 for the IBM Workplace 2.0 product family. The toolkit is a collection of several application programming interfaces (APIs) and service provider interfaces (SPIs) that you can leverage to extend or integrate IBM Workplace functionality.
Workplace Mail Messaging SPI
The Workplace Mail Messaging SPI provides you with extensions to the IBM Workplace Messaging mail service. These mail service extensions take the form of Java classes that conform to either of two specific interfaces referred to as handlers and deliverers. Typical use cases for the SPI are mail anti-virus, anti-spam tools, and more.
A handler extension can examine the envelope and content of any message that passes through the mail service. A handler can then modify the contents of the message by either adding or removing data. A handler can also reject mail, so it will not be delivered. A deliverer extension can modify which folder a message is delivered to.
All handler and deliverer extensions are made known to the Workplace Messaging server by entries in the Workplace Messaging workplace.properties file.
Workplace Instant Messaging SPI
The Workplace Instant Messaging SPI is used to build instant message handlers that intercept instant messages before they are delivered to recipients. You can use this Java SPI to block or modify instant messages in IBM Workplace 2.0 or 2.0.1. The most common use of the SPI is chat logging, but you can also use the SPI to perform other tasks, such as message translation.
The Workplace Instant Messaging SPI is part of the presence and instant messaging services of IBM Workplace 2.0. The SPI is reachable via a servlet installed on WebSphere Portal, one of the three servers that are part of IBM Workplace 2.0. The main interfaces of the SPI are:
- MessagingListener to receive events for each message going through the instant messaging server
- MessagingService to manage all MessagingListener instances
- Contact, which represents a SIP (Session Initiation Protocol) contact, to examine to whom messages are being sent
Workplace JSP tags
In addition to the APIs and SPIs for back-end integration, the toolkit also provides two JSP tags that allow you to enhance custom portlets built for the IBM Workplace server with additional collaborative features.
Person tag
The Person tag is used for creating people awareness in your application. The Person tag provides contextual collaboration functionality related to a named person. You can use the tag to generate a link menu of collaborative actions, such as sending email to a person. The Person tag generates HTML and requires Java and JavaScript to be enabled on the client. The IBM Workplace Person tag is an extension of the existing WebSphere Portal PersonTag.
Online Center tag
The Online Center tag is required to provide presence awareness. It is already embedded at the top of the page in the IBM Workplace theme, but if you create a portlet in a popup window, you need this tag for presence awareness on the page. The Person tag does not provide awareness in popup windows unless this tag is used on the same page. From the Online Center, the user can change his or her online status and also open the Customize Status popup to change the status message that other people see in the Person tag menu and in their hover help text.
Collaborative Application Component Interfaces
For the focus of this article, the Collaborative Application Component Interfaces (CACI) are the most important part of the Lotus Workplace Products API Toolkit 1.0. These interfaces enable developers to implement business components that are fully integrated with the Workplace templates and application infrastructure introduced in part 1.
IBM Workplace requires component developers to implement the CACIs as stateless session EJBs to allow the application infrastructure to control certain aspects of the component's runtime. Each aspect is encapsulated in a separate interface: Lifecycle, Membership, Templatable, Sensor, and Transactional. A component can choose which of these aspects it needs to implement to fulfill its business requirements, but to leverage Membership, Templatable, and Sensor, you need to implement at least the Lifecycle interface.
In the future, the Workplace Products API Toolkit 2.5 will add component services APIs to allow you to leverage services from existing IBM Workplace components, such as discussion, messaging, calendar, and so on. Furthermore, the 2.5 release of the toolkit will expose an API to interact with the application infrastructure service and allow you to programmatically instantiate applications as well as manipulate templates and application instances. And finally, the 2.5 release will debut IBM Workplace Client APIs, which will provide infrastructure services as well as a subset of the component services for the client platform of the IBM Workplace Client Technology rich client edition.
After looking at the various APIs and SPIs of the Lotus Workplace API Toolkit, let's focus on what's required to implement custom application components for the IBM Workplace server again. As we already stated, the key to integrating a custom component into the Workplace application infrastructure is to implement the CACIs. But before we look at each of these interfaces in more detail, we should review and reinforce the architectural pattern of a business component and its advantages for component providers again.
Business component reference architecture
Problems like remoteability and scalability--as well as maintainability, speed, and flexibility to adapt to changing business needs--are nonfunctional requirements that each of us has struggled with at some point when architecting a software system. One way to address these requirements is component-based development, which is a key concept within the Workplace architecture.
The Workplace business component reference architecture describes a pattern for the organization, structure, and behavior of Workplace components. It clearly separates responsibilities within a component into four different tiers. We will take a closer look at each of these tiers in the context of a sample noteboard component and explain which artefacts manifest each specific tier within a business component. The noteboard component allows applications to have their own message boards with application-specific notes posted to it. In part 3 of our series, we will implement parts of this component based on the toolkit sample. While the implementation in part 3 leaves out some aspects like persistence for the sake of simplicity, we will assume a full-fledged implementation of all tiers right now.
Figure 1. Four-tier architecture for noteboard component
Let's start with the Resource tier. In order to persist noteboard instances and notes posted to the message boards, the application requires a persistence framework. At this point, we assume a relational database was chosen for the noteboard component. The Resource tier defines the persistence framework the component is using. For our sample, this would be templated SQL and JDBC to manipulate data in relational databases. Furthermore, the schema for the noteboard database, table definitions, and so on are part of the Resource tier. The schema and the database are not accessible from outside the component, only the Service tier of the business component itself is interacting with the Resource tier. The usage of data sources allows us to use either a local or remote database based on the scalability requirements of the component.
The Service tier implements the business logic of the noteboard component and accesses the Resource tier to retrieve data or to change it persistently. Methods such as updateNotice() or deleteNotice(), for example, are part of the service interface implemented in the Service tier. The Service tier also enforces access control and other business logic requirements. For remoteability and therefore additional scalability as well as container managed transaction support, the Service tier in the Workplace components is implemented as stateless session EJBs. In the case of an EJB-based implementation, components should expose both local and remote bindings to leverage the advantages of either local or remote access as necessary.
In a three-tier architecture, the User tier would directly interact with the Service tier. But the disadvantage of doing so is that details about transport and protocol to communicate with the service are being exposed to the UI code. The fact that a Service tier is implemented as a stateless session EJB or a Web service should not matter to a user interface implementation at all. To hide these transport and protocol details, the Workspace tier has been established in IBM Workplace to leverage the Business Delegate pattern combined with the Service Locator pattern. While a call to the Service tier could be either a remote call to a remotely deployed EJB or to a Web service or a local call to a local EJB, the user interface code is always interacting with a local proxy, the Business Delegate only. The Delegate can either expose the same service interfaces or provide additional functionality like caching or simplification of interfaces, but the key is that it does not expose any protocol specifics such as RemoteExceptions or typical EJB exceptions. To loosely couple the user interface and the Service tier, the Business Delegate should leverage a Service Locator to look up the Service tier implementation. That way changes in the deployment topology do not require any code changes, but simply a reconfiguration of the Service Locator. The Lotus Workplace Products API Toolkit does not provide a public Service Locator implementation.
Finally, the User tier is responsible for implementing the user interface according to the client strategy of the component. The noteboard component provides a WebSphere Portal-based user interface through the Noteboard portlet. The portlet allows users to view lists of notes on a board as well as create new notes or delete existing ones. It leverages the Person tag to demonstrate how easily applications may be enhanced with the collaborative features provided by IBM Workplace.
An alternative implementation of the User tier could be a Workplace client view, but for our sample, we chose a portlet-based implementation. To leverage the business component as a collaborative application component within the Workplace application infrastructure in 2.0.1, a portal-based User tier implementation is required.
Now that we know how to organize and structure our noteboard component, how can we make it a collaborative component that can be reused in Workplace templates and applications?
From business component to collaborative application component
Based on the business component reference architecture, we could already build a noteboard component that allowed us to create a single message board to be used by all Workplace users on a server. But instead of one global message board, we would rather provide teams with separate message boards in each Workplace application they are working in. In fact, we want to add the noteboard component to any Workplace template or application; and the noteboard should always show the notes posted to this specific application instance only. We would also like to leverage the membership information of an application instance to define who can delete notes from an existing noteboard instance.
How can we make the noteboard a collaborative application component? What is missing from our business component to promote it to that level of integration?
From the toolkit overview, we already know one part of the answer to this question. We need to implement the CACIs in a stateless session EJB.
Figure 2. Collaborative Application Component
The CACIs defined by the public API are slightly different from the corresponding interfaces used by the application infrastructure internally. This requires component developers to use the CollabComponentAdapterEJB that is provided as part of the toolkit sample. The CollabComponentAdapterEJB implements the internal interfaces that the application infrastructure is expecting and in turn, calls a local stateless session bean, which we called CollabCompEJB here, implementing the public CACIs. By implementing the public interfaces within the CollabCompEJB, the application infrastructure can notify the noteboard component whenever a relevant event has occurred that the component needs to react to. Both the Noteboard Service EJB as well as the CollabCompEJB use a set of data access classes wrapped in the Noteboard Resource API to access or manipulate data in the Resource tier.
To call an EJB, the application infrastructure needs more than just the certainty that the component implements the required interfaces. It needs a JNDI name to look up the home interface of the EJB.
In part 1, we introduced Workplace Builder, the browser-based tool that allows you to create and manage Workplace templates and applications. To add a new component to a template or application, Workplace Builder lets you pick components from the Portlet Catalog to add them to pages. Thus, collaborative application components have to implement their User tier as a portlet in order for Workplace Builder to add it to a template. Furthermore, the portlet of a collaborative application component has to specify a special portlet parameter in its portlet.xml, namely WP_BUSINESS_OBJECT, which has to contain the JNDI name of the component's CollabComponentAdapterEJB as its value. By introspecting the portlet.xml, Workplace Builder can then add the required information about both the portlet and the adapter EJB as well as its JNDI name to the template and therefore, enable the application infrastructure to notify the component via the CACIs at runtime.
Collaborative Application Component Interfaces
Now that we have everything, we need to implement the Collaborative Application Component Interfaces and to integrate our noteboard component with the Workplace application infrastructure. So let's take a closer look at each of the interfaces and what value-add is provided by implementing each of them.
LifecycleLocal
The LifecycleLocal interface notifies your component when the containing application is created or destroyed or when the component is added to a template. It consists of the two methods: String createInstance(InstanceDescription description) and removeInstance(String id), which allow the component to create and destroy any resources needed while the application is running. The String returned from createInstance() has to be a unique identifier for this specific instance of your component and is used in all the other interfaces to identify the component instance that the corresponding event is targeted at.
For our noteboard component, we want to have one message board per application instance. Thus, createInstance() needs to create a new message board dataset in our persistence store and to return the unique identifier for this new noteboard instance to the application infrastructure. The noteboard portlet could then call the Noteboard Service EJB to retrieve all messages posted to this specific noteboard instance by specifying its unique instance identifier.
But wait, how does the portlet know about the unique identifier of the corresponding noteboard instance within an application instance? When instantiating a new application, two things happen. First, the application infrastructure calls createInstance() on all components of the application. Then it creates the portal pages defined in the corresponding template and deploys concrete portlet instances of the component portlets to these pages. As part of this step, the application infrastructure stores the instance identifier of each component within the PortletData in a parameter called BcId for the corresponding concrete portlet instance. Your component's portlet code can then use the IBM WebSphere Portal API to retrieve this parameter from its PortletData and to pass it on when interacting with the Noteboard Service EJB.
MembershipLocal
The MembershipLocal interface is used to notify your component when members are added to or removed from community roles via the addMembers(String id, DataObjectList members) and removeMembers(String id, DataObjectList members) methods. These methods allow the component to grant or revoke member access to resources that a specific instance of the component manages. Furthermore, it provides Workplace Builder with information about which component specific roles your component is supporting via the DataObjectList getRoles(String id) method.
Our noteboard sample component is defining two component roles, namely Administrator and User. Only Administrators should be allowed to delete notes from a noteboard, while both Administrators and Users can post new notes. Therefore, the noteboard component has to implement all three methods of the MembershipLocal interface. The getRoles() method is implemented to pass the information about the Administrator and User roles to Workplace Builder. Template editors or application owners can then use the Role mapping mechanism in Workplace Builder to map the noteboard roles to whichever application roles the template defines.
Whenever a member is added to or removed from an application instance that contains a noteboard, addMembers() or removeMembers() is called on the noteboard component, and it can then add or revoke access for the corresponding members.
TemplatableLocal
You can use the TemplatableLocal interface for two different purposes. On the one hand, it allows your component to specify so-called points of variability that it supports. These can be leveraged in a template to configure your component differently within the context of each specific template. On the other hand, the TemplatableLocal interface allows your component to have arbitrary runtime data persisted in a template and passed into the createInstance() method when an application instance based on that template is created.
The TemplatableLocal interface has not been implemented for the noteboard sample component. Nevertheless, implementing this interface can boost the reusability of a component. It would allow you to adapt the component to different business requirements via points of variability or templated content that can be reused in different contexts.
An extended noteboard sample could allow you to make certain base messages, such as company guidelines or a welcome message, part of each new noteboard instance. Or it could expose a point of variability to allow template editors to change the access control rules more flexibly and to define on a per-template level whether or not Administrators and/or Users should be allowed to delete notes from a noteboard.
SensorLocal
The SensorLocal interface is used to get information about resources managed by a component via the DataObjectList getSensorValues(String id) method. This information can be used to enforce Workplace application quotas. In IBM Workplace 2.0 and 2.0.1, four different sensor values are supported; these are: disk size, date when the instance was created, date when last accessed, and date when last modified.
The IBM Workplace server collects this information from all existing component instances periodically and allows Workplace administrators to monitor the usage as well as disk size of applications and components.
TransactionalLocal
The TransactionalLocal interface is extended by the LifecycleLocal and MembershipLocal interfaces and is used to determine whether or not your component's LifecycleLocal and MembershipLocal methods support global transactions.
Creating custom templates and applications
To use your new custom component in Workplace applications, a few more steps are required after implementing the CACIs. For very detailed documentation of the required steps, refer to part 3 of our article series or check the Lotus Workplace Products API Toolkit documentation.
In general there are three more steps required before you can use your new component in a Workplace application. Given that a collaborative application component, built along the business component reference architecture, consists of several J2EE artefacts, you need to package them correctly so that you can deploy them to your IBM Workplace server. While the portlet needs to be separately packaged in a Web application archive (WAR file), the EJBs and any additional Java classes need to packaged in an enterprise application archive (EAR file).
Once both archive files are created, you can deploy the EAR file to the IBM Workplace server via the Workplace server administration console, while the portlet can be either installed via xmlaccess or the WebSphere Portal Administration portlets. In case your component uses any data sources or other resources, these need to be defined and configured accordingly.
After you package and deploy all J2EE artefacts of your component, you can add your new component to a collaborative template using Workplace Builder. Simply select your component's portlet in the Component Catalog and configure your component for role mappings and points of variability. That's it! You are ready to create Workplace applications including your own custom application component.
Summary
In parts 1 and 2 of this article series, we have explained the concepts and architecture of component-based application development for the IBM Workplace 2.0.1 server. In part 3, we will take you through the complete process of extending the Lotus Workplace Products API Toolkit sample to implement the sample noteboard component to demonstrate how easy it is to extend IBM Workplace and to fulfill your own custom requirements, while leveraging the collaborative features and componentization approach of the Workplace platform.
Resources
- Read part 1 of our IBM Workplace application development series: "IBM Workplace as a collaborative application framework" and part 3: "Putting it all together and sticking it on a noteboard."
- The developerWorks: Lotus article, "Exploring the application development options for IBM Lotus Workplace 2.0," provides a brief overview of the public APIs and SPIs, the JSP tags, and the Collaboration Application Component Interfaces in the Lotus Workplace Products API Toolkit.
- Get the latest version of the Lotus Workplace Products API Toolkit from Lotus.com.
- Download the Lotus Workplace Products API Toolkit User's Guide.
- To learn more about IBM Workplace, visit the IBM Workplace Resource Center. You'll find
technical documentation, how-to articles, educational materials, downloads, product information, and more.
- Get involved in the developerWorks community by participating in developerWorks blogs.
-
Browse for books on these and other technical topics.
About the authors  | | | Hardy Groeger is a Senior Software Engineer in the Lotus Workplace Application Tools development team. Since he joined IBM in 2001, he has worked on various internal and external projects including WebSphere Portal Collaboration Center, specifically People Finder, the Lotus Workplace Team Task List component, and the workflow strategy for Lotus Workplace. |
| | | Mel Gorman is a Software Engineer in the Lotus Workplace Application Tools development team. He has worked with IBM since 2003 as a Software Engineer on the Team Task List component of Lotus Workplace. |
Rate this page
| 
