Master Table of Contents
Understanding the basic terminology and architectures of the applications becomes important especially when we want to extend the applications to provide our own customization. In this chapter, we introduce you to the fundamentals of creating customized components for Lotus Notes, Symphony, and Sametime. We explain where and how these customized components fit by introducing the architectures of these Lotus applications from the customization and extensibility standpoint. We address the following topics:
- Eclipse customization fundamentals
We present the basics of eclipse plugin development and eclipse architecture and how it enables extensibility and customization.
- Architecture of Notes/Symphony/Sametime vis-a-vis Eclipse extensibility architecture
In this section, we introduce the architecture of Notes, Symphony, and Sametime and how these applications leverage the eclipse extensibility to provide the support for developing customized applications.
In this section, we introduce the common design patterns used to develop customized components for Notes, Sametime, and Symphony. We also provide a brief introduction into packaging and versioning of the custom applications.
- Frequently asked questions on architecture and design
In this section, we provide answers for some of the frequently asked questions around architectural details for Notes, Symphony, and Sametime as well as application design questions.
Please note that this chapter is intended to be used as background and supplementary material. There are many concepts presented here to give you a solid understanding on creating customized applications. Although this chapter is not mandatory for understanding subsequent chapters, we recommend that you get familiar with the concepts presented in this chapter before proceeding further.
Eclipse customization fundamentals
Eclipse, an open source community, provides tools and frameworks that can help create applications. It presents an integrated development environment and an extensible plug-in system. In general, a plug-in is a software component used to add specific capabilities to an application. Eclipse uses plug-ins to provide all of its functionality. This very architecture and its extensible nature lets us contribute our desired customization in the form of plugins.
The figure below depicts an overview of the Eclipse Architecture.
The Eclipse Plug-in Development Environment (PDE
) provides tools to develop, test, debug, build and deploy Eclipse plug-ins, fragments, features, update sites and RCP products. Eclipse provides the concept of Extension points
that allows plugins to contribute desired functionality to other plug-ins.
A plug-in declares an "extension point" which defines the contract to extend plug-in functionality and thereby opens itself up for other plug-ins. The plug-in which defines the extension point is also responsible for validating the contributions of other plug-ins.
A plugin which defines an "extension" contributes to the defined "extension point". The information about the list of extension points and the extensions are available in the Eclipse Extension Registry
The process of creating extensions and extension points are covered in details in the subsequent chapters.
Following figure shows "My Plug-in" contributing both the extension and the extension point.
So in order to create a plug-in extension to Eclipse, you need to decide on the functionality that the plug-in must provide. Commonly used extensions
are to create are Perspectives, Views, Actions, Wizards, and Editors. After creating your plug-in extension, it can be deployed by creating a "feature" and an "update site". A feature is a logical unit that contains a list of plugins and other features. You associate your plug-in extension to an existing feature or to a newly created feature. An Update site contains feature and plug-in versions to be installed in the application using the Eclipse Update Manager.
The figure below shows how the features and plugins are packaged under update site.
Deployment Guide Chapter
explains the deployment in detail for Notes, Symphony and Sametime.
Now after getting a decent overview of eclipse architecture and its extension capabilities, its time to understand the basic architectures of Notes, Symphony and Sametime from the eclipse's extensibility standpoint.
Architecture of Notes/Symphony/Sametime vis-a-vis Eclipse extensibility architecture
The IBM Lotus Clients like Notes, Symphony and Sametime are built on IBM Lotus Expeditor which in-turn is built on Eclipse. IBM Lotus Expeditor
is family of “managed” clients that provide an application framework for applications written in Java.
The following figure shows an higher level architecture of the IBM Lotus clients.
Lotus Expeditor is a universal desktop client integration framework; it helps you integrate a wide variety of client and server applications in business mashups. It is an Eclipse-based Java Enterprise Edition (JavaEE) client application development and runtime platform. IBM Lotus Expeditor also provides the core client technology for the latest versions of IBM Lotus Notes, Lotus Sametime, and IBM Lotus Symphony. Click here
to know more on IBM Lotus Expeditor.
The Lotus Expeditor toolkit gives you the capability to develop Java Enterprise Edition and Eclipse applications for Lotus Expeditor, Lotus Sametime, Lotus Notes, and Lotus Symphony. The toolkit lets you select the target client platform, and then it automatically configures the development environment with the features needed to develop applications for the selected platform. For example, when you develop a plug-in for Lotus Sametime, you can select the Embedded Sametime target. Click here
to know more on IBM Lotus Expeditor Toolkit.
Inheriting the extensibility
The fact that Expeditor is based on Eclipse, brings in all the extension capabilities of Eclipse to Expeditor.
In addition to supporting eclipse extension points, Expeditor provides a set of its own APIs and Extension points.
You can notice from the architecture of IBM Lotus Clients ( Notes, Symphony and Sametime) that they are built on Expeditor. This makes them leverage both Eclipse and Expeditor extensions points. Leveraging Notes-specific APIs
, Leveraging Symphony-specific APIs
, Leveraging Sametime-specific APIs
chapters introduce you the different APIs and extension points that are specific to Notes, Symphony and Sametime respectively.
In this section, we introduce you to the common design patterns when it comes to developing customized components for Notes, Sametime and Symphony. . We also give you a brief introduction into packaging and versioning of the custom applications.
Model view controller
Model–View–Controller (MVC) is an architectural pattern used in software engineering that isolates application logic from presentation logic (UI) permitting independent development, testing and maintenance of two. This section provides you with a set of guidelines or best practices on separating your model / domain logic from the UI logic. In the discussion below, UI refers to both the view and controller logic. This initial discussion focuses more on isolating the model logic from the view / controller as opposed to separating the view from controller logic.
When running in an Expeditor based platform that always contains both model and UI components, it is easy to create model bundles that end up referencing UI classes. The model bundle will run (because the referenced UI components are always in the runtime). So then why is it important to separate the model from the UI? There are environments where your model logic may be useful that DO NOT contain any UI components. Such an environment is referred to as headless. In this case, the model component should not be referencing any of the UI classes.
- Place model packages and UI packages in separate bundles. Model logic should be packaged separately from UI content at the bundle level. That is, a bundle either contains only model logic (and no UI), or it contains UI logic (and hopefully no model logic). This allows the model to be used in a headless platform simply by adding the appropriate model bundles (and not the UI bundles). This dichotomy is rigorously followed by the Eclipse development folks. Typically, the bundle name for a model bundle will describe the model, and the ui bundles will add "ui" to the model bundle name. For example, the Eclipse Java Development tools model classes are in bundle org.eclipse.jdt, and their corresponding UI classes are in bundle org.eclipse.jdt.ui.
- Include "ui" in the package name of any public ui packages, and include "ui" in the bundle name of UI bundles. This convention makes it easier for users to identify the UI bundles / packages from the model bundles / packages.
- After creating a core set of model packages, and a separate set of ui packages, you may find that client "ui" code that uses the model ends up with a fair amount of helper classes to simplify accessing the model. If this "helper" logic is something that you foresee other clients having to re-write, consider moving these helper classes back into the model.
Detecting whether or not a given model bundle is truly free of any UI dependencies is simply a matter of analyzing the bundle's OSGi dependencies, as defined in the bundle's Manifest. The Eclipse tools manifest editor displays these dependencies on its dependencies tab. If any of the bundle or package dependencies are to bundles / packages that contain UI content, then the bundle in question has UI dependencies. Typically, UI packages and bundles will contain "ui" in their name. org.eclipse.swt* and org.eclipse.jface* are 2 exceptions to this convention.
If you have an Eclipse development environment set up that has set the Plug-in Development target platform to a given headless platform, then Eclipse will automatically inform you, through errors in the Problems view, of any references to UI classes your bundle project is making, since they will not be available in the target platform.
Extension points vs. OSGi services
Ever since, Eclipse adopted the OSGi runtime in version 3.0, there has been a lot of discussions around the Eclipse Extension Registry and OSGi Service layer because of a overlap between these two models, to some extent, in terms of the problems they address. Until the recent version of Eclipse, the tooling provided by the PDE provided a lot of support for extensions, extension points and registry and not much for services. But to make things little more interesting, the gap between the two models is diminishing with the recent developments in OSGi and appropriate support provided by recent eclipse tools. This leaves the developer to make a choice between two models during application development.
For the Expeditor based clients like Notes, Symphony and Sametime, we recommend focusing on Eclipse Extension Points and avoiding OSGi Services as much as possible for following reasons.
- allows for lazy start
- removes need for service trackers (but might require extension listeners)
Having said that, in general, you should not use Services nor Extensions unless you have a clear requirement for their capabilities. Do not make your code overly complex just to be "extensible" unless you really need it.
Packaging and versioning
This section will introduce you to some of the do's and don'ts while developing/packaging Lotus Client plugins and features. These best practices are
Packaging Best Practices for Plugins
As we discussed previously, a plugin is a functional unit of Eclipse. In general modularity (sharing classes and resources between plugins) and plugin collaboration must be considered while designing a plugin.
While packaging a plugin it is not recommended to package java classes as inner jars. Following are some of the issues that may surface with this practice.
Packaging Best Practices for Features
- In order for eclipse to access that inner jar it has to extract the inner jar from the plugin jar into a directory in your workspace which ends up taking extra time on boot and also doubling the amount of disk space you need for your plugin.
- Inner jars cannot be accessed by the compiler when developing/building against your plugin.
- By default, inner jars require extra platform memory (heap space) to maintain the manifest for package attributes.
- In addition to signature verification on the jar, signature verification will have to be performed on the classes loaded from the inner jar.
Features collect sets of plug-ins that go together to form some coherent unit of function. Here are some tips that we would like you to consider when you want to decide between creating a new feature and reusing an existing one.
Versioning Best Practices
- Create a new feature when your plugin or plugins can be installed separately and provide some form of component level value
- Create a new feature when you want to be able to separately manage the plugins in this feature and feature patches are not part of your update strategy - If your applications cannot leverage feature patches as a means of providing updates/fixes for plugins then grouping many plugins in the same feature will cause the update to be much larger than needed since the entire feature and all of its plugins must be provided in order to update it.
- Create a new feature when you need to use a different install handler than the one currently being used by your target feature - Since Eclipse only allows for the use of one install handler per feature if you need to use another install handler you would need to create a new feature for this plugin.
- Create a new feature when you need to provide a different license than the one being currently used in the existing feature for the plugin you are providing.
- Reuse an existing feature when your plugin must be installed with another plugin or else it won't resolve and/or provide value
contains a set of guidelines expressing how to evolve plug-in version numbers in a way that captures the nature of the changes that have been made.
Frequently asked questions on architecture and design
This section lists you some of the frequently asked questions on Lotus Clients Architecture and on building customized application.
1) What are the most customized components in Notes?
Here are some of the frequently customized components for Notes. Samples for few of them can be found in the Leveraging Notes-specific APIs
- Sidebars/ShelfViews that are context senstive with Notes Java UI APIs + backend data access via notes.jar
- Custom Menus - To Menu bar or Context Menu actions
2) What are the most customized components in Symphony?
Here are some of the frequently customized components for Symphony. Samples for few of them can be found in the Leveraging Symphony-specific APIs
- Ability to create a text document using a template and exporting data in to it, with automated rules based on the current user context; to accomplish this target we need to work with Paragraph, Bookmarks and Fields
- Ability to create a spreadsheet using a template and exporting data in to it, with automated rules based on the current user context; to accomplish this target we need to work with Sheets, Cells, Datapilot tables and Charts
- Ability to get data from an existing spreadsheet with automated rules based on the current user context; to accomplish this target we need to work with Sheets and Cells
3) What are the most customized components in Sametime?
Here are some of the frequently customized components for Sametime. Samples for few of them can be found in the Leveraging Sametime-specific APIs
- Announcement Sender Enhancements
- Action buttons (during chat)
- Handlers for intercepting sametime messages before/after they are sent,
- "Magic Carpet" message bus
- Quick Find and Location Services
- Context actions to sametime contacts