 | Level: Intermediate Brian O’Gorman, Software Engineer, IBM
12 Jul 2005 Learn how to build and deploy a collaborative component for IBM Workplace Collaboration Services 2.5, using IBM Rational Application Developer and the free plug-in, Collaborative Component Wizard for IBM Workplace applications.
This article describes how to create a collaborative component for IBM Workplace Collaboration Services 2.5 and how to deploy it to a Workplace server. To do this, we use a free downloadable plug-in for IBM Rational Application Developer to create the different tiers of the component. (The plug-in also works with IBM Rational Software Architect. Wherever Rational Application Developer is mentioned in this article, Rational Software Architect can be substituted.) By following this article, you can, with minimal effort, have a new component running on a Workplace server.
This article assumes that you're an application developer with some familiarity with IBM Workplace products.
Setting up
Before you get started, you need the following installed:
After you download the API Toolkit and the Collaborative Component Wizard, extract the API Toolkit to a location of your choice. There is no further installation required, so the location you extract it to is its home directory. Then extract the Collaborative Component Wizard to a temporary directory. You then need to copy the plug-in to your Rational Application Developer installation. Close down Rational Application Developer if it is running, then copy the plug-in folder from the temporary directory to <RAD_HOME>\rad\eclipse\plugins where <RAD_HOME> is the installation directory of Rational Application Developer. (On Windows, this defaults to C:\Program Files\IBM\Rational\SDP\6.0).
Before using the wizard, you need to set up some additional classpath variables in Rational Application Developer. These are required so that the compiler can find the imports required from the API Toolkit and the server runtime files. They are:
- LWPAPI_HOME, which should point to the root of the API Toolkit (for example, c:\lwpapi).
- WAS_HOME, which should point to the root of the Workplace Collaboration Services server. That is the folder that contains the AppServer, PortalServer, and WorkplaceServer directories. If your Workplace Collaboration Services server is not on the same machine as Rational Application Developer, you can re-create the directory structure on your machine and copy the required JAR files from the server. Refer to the user guide included with the API Toolkit for more information (lwpapi\doc\lwpapi25ug.pdf). Within the Toolkit Sample Code chapter, there is a section titled, "Preparing your development environment."
To set these variables, launch Rational Application Developer and select Windows - Preferences. Then choose Java - Build Path - Classpath Variables, and select New - Create an entry for each of the two variables.
Using the wizard
Using the CollabComponent sample from the API Toolkit as a template, the wizard creates the projects that make up the tiers of a collaborative component with user supplied names and packages:
- In Rational Application Developer, choose File - New - Project.
- Expand the IBM Workplace category.
- Select Workplace Collaboration Services Component (Tech Preview) and click Next.
- On the first page of the wizard (see figure 1), enter the name of the component. The screen displays the names of the different projects. To accept these names, click Next.
Figure 1. Entering the component name
- On the second page of the wizard (see figure 2), you have the option to modify the class names and the Java packages that will contain the classes:
Figure 2. Modifying names
- When you are done editing, click Finish. The wizard creates and loads the five projects that make up your component (see figure 3).
Figure 3. Project Explorer
Exporting your component
You need to export your projects to archives that can be installed on the server. There is an Enterprise Archive (EAR), which contains the EJBs and associated projects that are installed to the Application Server and a Web Archive that contains the portlet and that is installed on WebSphere Portal. To do this, open the J2EE perspective if you are not already using it (Window - Open Perspective). If Rational Application Developer is not configured to build projects automatically, do that now. (By default, it builds all projects automatically, but this may have been turned off.) Expand the Enterprise Applications folder in Project Explorer. Right-click the EAR project for the component (in our example, this is BriansComponentEAR). If there is a menu item called Build Project, click it. This builds the EJB projects also because they are part of the deployment for the EAR project. Do the same for the portlet project in the Dynamic Web Projects folder (in our example, this is BriansComponentPortlet).
Next, generate deployment code for the EJBs. To do this, right-click the EAR project and choose Deploy. Now you can export the archives. Right-click the portlet project, and choose Export - WAR file. Specify a location and click Finish. Then right-click the EAR project, and choose Export - WAR file. Specify a location and click Finish
Installing your component on the server
Before installing the new component to your Workplace server, you need to install and configure the API Toolkit runtime files on the server. If you have not already done this, do it now. In Chapter 1 of the API Toolkit User Guide (lwpapi\doc\lwpapi25ug.pdf), there is a section titled, "Installing the IBM Workplace Collaboration Services API Toolkit runtime files on the IBM Workplace Server." This section explains how to set up the API Toolkit runtime files on the server. You only need to do this once. Install the EAR and WAR files separately.
Install the EAR file as follows:
- Browse to the WebSphere Application Server Administrative Console (WAS Admin) pages on your server. This URL has the syntax http://<server.subdomain.domain:port>/admin (for instance, http://workplace.foo.com:9044/admin). (The default port for the WAS Admin pages is 9044. If this does not work, contact your server administrator to find out the correct port.)
- Enter your user name and password and click OK.
- In the navigation panel on the left side, expand Applications and choose Install New Application.
- Ensure Local Path is selected and browse to the EAR file that you exported earlier. Click Next.
- Leave the defaults on the page, and click Next. This displays the first of several numbered steps (see figure 4).
Figure 4. Install New Application screen
- Leave defaults for Step 1 and Step 2.
- For Step 3, check both JAR files, select WebSphere_Portal from the server list, then click Apply.
- For Step 5, click Finish.
- If installation has been successful, click the link to Save Master Configuration.
- Go to the next page and click the Save button.
 |
Starting the application
Now you can start the application that you just installed. While still in the WAS Admin pages, in the navigation panel on the left, click the Enterprise Applications link within Applications. You should see a list of installed applications similar to figure 5.
Figure 5. Enterprise Applications screen
Browse to the application that you just installed. (You can use the filter to search for the application using part of or the entire name.) There should be a red X icon in the status column to the right of the application name. This means that the application is not running. Check the box to the left of the application name and click the Start button. After the application is started, you should see a green arrow icon like the other applications in the list. You can now log out of the Administrative Console.
Installing the WAR file
Next, install the WAR file on WebSphere Portal. Browse to your Workplace server (for example, http://workplace.foo.com:9081/lwp/workplace) and log in with administration rights. Then select Administration from the links at the top of the screen. This results in figure 6.
Figure 6. Workplace Administration screen
Select Portlets from the button bar, and select Install from the options in the left panel. Browse to the WAR file you exported earlier, and click Next. Then click Install. You should now see a message saying that the portlet installed successfully.
Testing
To test your component, you need to create an application template that uses the component, and then create an application using that template. To do this, click the Templates link at the top of the screen, and click the New button. Enter a template name, and select Workplace Application as the category. Then click OK.
On the left side, click Pages and Layout, then click Page 2. (You can add/remove pages here if you like. In our example, we work with Page 2 to keep things simple.) Here you have the option to change the name and layout of the page. We only have one portlet, so the default layout is fine for our purposes. Click Add Portlets. Then browse or search for your newly installed portlet. Check the box to the left of the portlet name, and click OK. Then click Done, and click Save and Close from the button bar at the top of the screen. This creates the template. Now create an application using the template:
- Click the My Work link at the top of the screen.
- Click Team Collaboration in the left panel.
- Click Applications in left panel.
- Click the New button.
- Enter an application name.
- Select the template the you just created.
- Click OK.
- You can change the "New member notification" action if you want and supply a parameter for the component. These are optional. Afterward, click OK.
- Your application should now appear in the list. Click the application name.
- Click Page 2 (or the page you added your portlet to if you changed it). Figure 7 should appear:
Figure 7. Sample portlet
More detailed information regarding installing the component on the Workplace server and creating the template and application can be found in Chapter 3 (Collaborative Application Component sample section) of the API Toolkit’s User Guide.
Conclusion
Your component for IBM Workplace Collaboration Services 2.5 is now deployed on the Workplace server and is ready for your users to work with. By following the steps described in this article, you can deploy additional portlets to your Workplace environment. Bear in mind that our procedures are also applicable to Rational Software Architect as well as Rational Application Developer.
We hope you find this article useful. Please let us know if you want additional information on this subject and feel free to suggest related topics you want to see for future articles.
Resources
About the author | | | Brian O’Gorman is a Software Engineer working for the Dublin Software Lab within IBM Software Group. He has a BSc in Computer Science and Information Systems from University of Limerick, Ireland. He joined IBM in November 2004, having worked previously at Cylon Controls, Agilent Technologies, Hewlett Packard, and Lotus. |
Rate this page
| |
