Level: Intermediate Katherine Sewell, Software Engineer, IBM
09 Aug 2005 Learn about the IBM Workplace Managed Client Developer Toolkit, currently available on alphaWorks, and how to use it to create IBM Workplace Managed Client applications.
IBM Workplace Managed Client (formerly IBM Workplace Client Technology, Rich Edition) delivers server-managed collaboration to the user's desktop. This collaboration is "managed" from the server where an administrator decides which applications and content are suitable for each user. The client is maintained through provisioning, where application components (such as plug-ins and features) are downloaded to a client machine from an administrative server as required. The Workplace Managed Client is based on the Eclipse architecture, which serves as a framework on which to build customizable and extensible applications.
The IBM Workplace Managed Client Developer Toolkit is an Eclipse toolkit designed for application developers who want to extend the IBM Workplace Managed Client with new applications. The current process to create new applications and deploy them to a Workplace server is designed for an enterprise environment, and is therefore somewhat complicated. In contrast, the toolkit provides the ability to create and deploy a simple application, even if you have no previous Workplace experience. It is aimed at developers new to Managed Client technology and provides features for quickly building visual applications. Developers can test and debug directly on the client without needing extensive knowledge of the deployment process for server-provisioned applications. In addition, the toolkit provides features that simplify server deployment. By using wizards to guide the developer, the toolkit decreases the time needed to create and deploy applications. You can download the toolkit from this Web site.
This article describes the IBM Workplace Managed Client Developer Toolkit. We assume that you're an application developer with some familiarity with IBM Workplace and Eclipse products.
Workplace Managed Client Developer Toolkit
As mentioned previously, the IBM Workplace Managed Client is based on the Eclipse architecture. The IBM Workplace Managed Client Developer Toolkit is provided as an extension of the Eclipse plug-in development environment (PDE). The toolkit can be used with the Eclipse IDE or with the IBM Rational Application Developer IDE.
The purpose of the toolkit is to help you create and develop Workplace Managed Client applications. To this end, an important feature of the toolkit is the Application Wizard. This simplifies the Workplace Managed Client application creation process. A Workplace Managed Client application consists of several individual projects, so the toolkit provides a navigator that allows the application's projects to be visualized in the context of the application itself. A run and debug mechanism provides you with the ability to test or debug applications directly from the Eclipse or Rational Application Developer IDE. To facilitate the deployment of an application to a Workplace Collaboration Services server for managed provisioning to user clients, an export feature is provided for exporting a Workplace Managed Client application deployable set. (A "deployable set" consists of a number of files organized to allow easy deployment to a provisioning server.) We explain these features in further detail in the following sections.
 |
Workplace Managed Client applications
A Workplace Managed Client application is a new project type provided by the toolkit. It is an extension of the Eclipse plug-in development environment feature project type and maintains the elements of the feature project, but also allows the specification of an application title and an application icon. The application title and icon are displayed in the client's application switcher bar user interface to represent the application.
The application project references a page layout project and plug-ins that provide the physical views for each section of the page layout. The conceptual structure of a Workplace Managed Client application is shown in figure 1:
Figure 1. Structure of a Workplace Managed Client application
As described in the section titled Application Navigator later in this article, the physical structure of the application does not reflect this conceptual view. The toolkit provides an Application Wizard to simplify the creation of these Workplace Managed Client applications (see figure 2).
Figure 2. Application Wizard
By using the Application Wizard, a developer is guided quickly through the process of creating a new Workplace Managed Client application project. The first step is to specify the application title and an application icon, which are used to identify the application when it is running on the client. By default, the wizard creates a new page layout project for the application. To perform this step, the Application Wizard launches a second wizard, the Page Layout Wizard.
The page layout project provides the overall layout for the application page. You can choose from a number of predefined layouts when creating the application. Each of these layouts is represented by an image button, which describes its arrangement, as shown in figure 3. Users of the Rational Application Developer IDE can define layouts in addition to those predefined in the toolkit, or can edit the layout of an existing page.
Figure 3. Defining the page layout
Each segment of the layout can contain one or more views. When multiple views are selected, they can be displayed in the application; either stacked one above the other or selectable from a tab bar. View attributes can be set with the toolkits to control how views are displayed. The Page Layout Wizard allows these views to be defined, as shown in figure 4:
Figure 4. Defining views for the page layout
Views are standard Eclipse user interface components. You can use the toolkit to create an initial view for each segment of the layout, or existing views can be selected, or references can be specified for views that already exist on the client or the server update site. The views that are automatically created by the toolkit contain a simple "Hello Planet" text control located on a composite in the view. The composite can then be edited using the Eclipse visual editor for Java. The visual editor is an Eclipse feature for designing applications that have a graphical user interface.
The Page Layout Editor component can be accessed after the application has been created to redesign the application layout. It provides a similar user interface to the Page Layout Wizard, as shown in figure 5. Using this editor, you can rearrange the views or create new ones. It also enables you to modify the parameters of each view, which affects the way the view is displayed in the client.
Figure 5. Page Layout Editor
With the Application Wizard, you can easily create a new Workplace Managed Client application, using the Page Layout Wizard to create the layout and create or select the application views. Now that we have an application, let’s move on to the Application Navigator component.
Application Navigator
The existing navigators in Eclipse are project-orientated. There is no way of viewing a collection of projects (such as those that make up a Workplace Managed Client application) as a distinct entity. Instead, the application project contains an XML file detailing the component projects of the application. As mentioned previously, the Workplace Managed Client application project is based on the existing Eclipse feature project type. This XML file, which details the component projects of the application, is called feature.xml. Each of these component projects is shown as another project in the view. So it can be hard to see the structure of the applications, as illustrated in figure 6:
Figure 6. The existing Eclipse Resource Navigator
Our solution was to create a new navigator tailored to display Workplace Managed Client applications. This navigator provides a clear view of the application structure by presenting components of an application as sub-projects of the application project (see figure 7).
Figure 7. Workplace Managed Client Application Navigator view of the same workspace
Both navigators represent the same workspace, but the Application Navigator has assembled the projects into Workplace Managed Client Application projects. Then, within the hierarchy of each Workplace Managed Client Application project, you can see the component Page Layout and View Projects. Component projects of the application project can be expanded and edited (see figure 8). This is only a representation of the workspace; the projects remain physically separate as displayed in other views, such as the Resource Navigator.
Figure 8. Component projects of a Workplace Managed Client application
Only Workplace Managed Client Application projects are displayed in the Application Navigator; other projects are hidden from this view to reduce clutter. The navigator also provides context-sensitive menus that allow the developer to conduct tasks against the application project. Now that we have an application and can easily develop it using the navigator, we move on to testing it on the Workplace Managed Client.
Running applications on the client
The usual process to test a Workplace Managed Client application is basically the same as deploying that application in an enterprise environment. As such, it is complicated and time-consuming. It requires that an application be deployed to a Workplace server (as described in the next section) and then provisioned to the client in order to test it. There is also an alternative process that uses the creation of a new perspective to define the layout, and a custom personality that uses this perspective. But, these steps must be performed manually by the user. Neither of these solutions is ideally suited to iterative development.
In contrast, with the Workplace Managed Client Developer Toolkit, it is possible to easily run an application directly on the client. This means that you can eliminate the configuration process needed to get an application successfully deployed to a Workplace server and then provisioned to the client. Instead, this step only needs to be done once, when you are satisfied that the application is functioning correctly.
One of the main reasons that provisioning to the Workplace server was necessary before an application could be tested is that the client requires information about how to lay out the page and the classes to run for each view. This information is provided in the form of a file in the Rich Client Platform Markup Language (RCPML). RCPML is an XML-based markup language that describes a Workplace Managed Client application. It specifies the view layout, the services required to support the application, and the required features. It also provides optional inline data. In this way, it enables the client to determine the layout of an application and the necessary features and plug-ins to produce the application interface. The toolkit generates the required RCPML and runs the application directly from a temporary workspace. The client, when running in this test mode, does not display or interfere with the applications that are available when the client is running standalone.
The Workplace Managed Client application contains a layout file (ibm-portal-topology.xml), in the page layout project, that describes how the application should be displayed on the client. When the toolkit builds a Workplace Managed Client application, it performs an XML transformation on this layout file and outputs RCPML, which represents the layout.
Another inconvenience of the default launch process is that the user must manually add configuration details such as classpaths, location of the client, and arguments for the client in order to get the client to launch successfully, which is an error-prone process. The solution was to create a new launch configuration type tailored for Workplace Managed Client applications. This new configuration automates the process by populating the required fields (see figure 9).
Figure 9. Workplace Managed Client launch configuration
The Workplace Managed Client launch configuration is based on the existing Eclipse PDE launch configuration. While most of the fields can be left at their default settings, some merit further explanation.
To delete the workspace data before each launch, select "Clear workspace data before launching." This will, however, delete the credentials for the client, requiring a connection to the server to re-authenticate. To be given the choice of whether to delete the workspace data for a given launch of this configuration, select "Ask for confirmation before clearing" and a confirmation dialog box will be displayed for each run of this configuration.
When using the PDE launch configuration, the Program to Run field is set to org.eclipse.ui.ide.workbench, which launches the run-time workbench (another copy of Eclipse with plugins in the workspace included). In contrast, the default program to run when using the Workplace Managed Client Developer Toolkit launch configuration is com.ibm.rcp.platform.RCPApplication. This launches the Workplace Managed Client with the selected Workplace Managed Client application.
The Eclipse SDK does not include a Java Runtime Environment (JRE) and instead it uses a preinstalled JRE. The version of the JRE used when launching the client should be set to the version supplied with the client, because it provides the appropriate security context and uses the appropriate virtual machine. When using Windows, this JRE can be found in <Client>\rcp\eclipse\features\com.ibm.rcp.jre.win32.feature_1.2.0\jre. Similarly, in Linux, the JRE can be found in <Client>/rcp/eclipse/features/com.ibm.rcp.jre.linux.feature_1.2.0/jre, where <Client> is the location of the Workplace Managed Client.
As mentioned earlier, to launch the client, you must set various arguments for the Java virtual machine and the client program itself. For the virtual machine, these include classpath settings for the client (to provide the necessary JAR files) and the location of the client on the machine.
Most notable among the arguments for the client program is the pbcache argument, which tells the client pagebuilder code to use the specified directory as the page cache directory instead of the default location of <workspace>\.metadata\.plugins\com.ibm.rcp.pagebuilder. The page cache directory contains the RCPML that describes the applications to display. When running applications on the client, we want the page cache directory to be the RCPML directory located in the Workplace Managed Client application’s page layout project. For example:
<Eclipse_workspace>\viewInteraction\com.ibm.wcttoolkit.sample.viewInteraction.MainPage\PortalConfiguration\.RCPML
For more information on the available arguments, see the IBM Workplace Client Technology API Toolkit User's Guide supplied with the IBM Workplace Collaboration Services API Toolkit.
To greatly simplify the process of launching an application, these argument fields are automatically populated when a new IBM Workplace Managed Client launch configuration is created. After the JRE and Target Platform are set correctly (see the toolkit documentation for instructions on doing this), all you need to do is select your application, create a new launch configuration (no editing needed) and click Run. The Workplace Managed Client will then launch and run your selected application (see figure 10).
Figure 10. Workplace Managed Client Application running on the client
Note: Although the toolkit does not require a server to run the application, the Workplace Managed Client must be authenticated against a server at least once before it can run. So developers need access to a server when they initially install the client, or when they run applications from a new workspace for the first time.
After the application has been tested fully and is functioning correctly, the next step is to deploy it to a Workplace Collaboration Services server, from which it can be provisioned to the Workplace Managed Client on the user's machines.
Deploying the Workplace Managed Client application to a Workplace server
To extend the Workplace Managed Client user interface with new applications, each application must be deployed to an IBM Workplace Collaboration Services server and then provisioned to the Workplace Managed Client from there. Portlets are used to represent the views of an application. The portlets produce RCPML, which describes each section of the layout. The client interprets this RCPML and builds the perspective and views accordingly, pulling down new components as required.
To deploy your Workplace Managed Client application to a Workplace server and provision it to the client, you will need an update site for the component files (features, plugins, and images), a portal page, and “placeholder” portlets for that page. These portlets contain the information needed to generate RCPML on the server. Each view is represented by an instance of the placeholder portlet.
To facilitate the deployment of an application to a Workplace Collaboration Services server for managed provisioning to user clients, an Export Wizard (see figure 11) has been included in the toolkit. This wizard is provided for exporting a Workplace Managed Client application as a deployable set.
Figure 11. Export Wizard
The first step in the deployment process is to run the Export Wizard, which packages the Workplace Managed Client application project into JAR files for the update site. This results in a features directory containing the feature JAR for the application, a plugins directory containing the view plug-in JAR files (one for each view in the Page Layout), and an images directory containing the icon for the application.
The next step is to update the update site with these files. The files must be manually copied up to the server. The update site’s site.xml, which provides a manifest of files on the site, must be updated to include the new content. Although it does not automatically update this file, the wizard does provide an XML fragment to be added to it. (For more on update sites, see the developerWorks: Lotus article, "Deploying updates in IBM Workplace.")
The final step in the deployment process is to create and populate pages and portlets for the application on the server. This is the most complicated step. Thankfully, the wizard creates an appropriate XMLAccess script, based on the Page Layout project, to deploy the application to the server. It also provides instructions on how to deploy the application given the created files.
So, using the wizard, the steps to perform to deploy a Workplace Managed Client application to a server are:
- Copy files to the update site.
- Update site.xml file with the supplied XML fragment.
- Run the supplied XMLAccess script, according to the supplied instructions.
Conclusion
Using the Workplace Managed Client Developer Toolkit, you can quickly and easily set up an application to extend the client. The toolkit then supports you as you test and debug the application by automating the process of launching an application on the client. After the application is working properly, the toolkit assists you in the deployment process. Each of these features greatly simplifies the client application development process.
Resources
About the author  | | | Katherine Sewell is a Software Engineer working for the Dublin Software Lab within IBM Software Group. She has an MSc in Computer Science from University College Dublin, Ireland. She joined IBM in September 2002. |
Rate this page
| 
