1. No category

How to extend the Sametime
Connect 7.5 client: A step-by-step
guide to developing and installing
plug-ins as miniApps
by Bret Swedeen
The new release 7.5 of Sametime Connect allows administrators and
developers to extend the Sametime Connect client’s features and functions
with Java plug-ins you can create or obtain from other parties. You can also
use plug-ins to reuse Java code within Sametime applications. The plug-ins
can be as simple as custom menu choices that display information in a
dialog box or as complex as full programs. Not a Java programmer? That’s
not an insurmountable problem because with the right tools, just a little
Java knowledge, and patience, you can create some amazing plug-in tools
that add value to your Sametime Connect client.
Bret Swedeen
Systems Tools Developer
IBM Global Services
Bret Swedeen joined IBM in
1997 as a principal knowledge
architect. Bret is a Certified
Netware Engineer and Certified
Lotus Professional System
Administrator and Application
Developer. Currently, he develops
custom monitoring tools for
IBM’s collaborative computing
environment. He wrote the Lotus
Notes 4.5 Administrator’s Guide
(Sybex, 1997) and has written
articles for Lotus Notes Advisor,
Database Advisor, LAN Times,
and LAN Magazine. In his spare
time, Bret blogs about general
computing topics at his Web site,
www.techtraction.com.
This article gets you started by showing you how to develop and install
a useful Sametime administration plug-in called “Total Connections.” This
plug-in takes advantage of the StAdminAct.exe cgi-bin program on all
Sametime servers to display the total number of Sametime connections
(regardless of uniqueness) and the total number of unique user connections
in a mini application (known as a miniApp) right in your Sametime
Connect client. Figure 1 (on the next page) shows the Total Connections
miniApp located just below the Contacts list in the Sametime Connect
client. When this plug-in is installed, the administrator doesn’t need to open
a browser and point to a Hypertext Markup Language (HTML) page for the
connection data. It’s a very simple but powerful and beneficial tool.
In the example case, you use a Perl script to provide the back-end data
collection that displays on an auto-generated Web page, and you create a
front-end miniApp to provide the means to view the collected data.
By following along with the step-by-step instructions, you’ll learn that
developing small Java plug-ins requires attention to detail but is probably
easier than you thought, and you’ll have a useful Sametime administration
tool you can apply right away.
The first part of the article explains how to develop the connectiondata collection in the back end. The software you need to follow along
No portion of this publication may be reproduced without written consent.
85
THE VIEW • November/December 2006
in a hands-on manner is free. You’ll need the
following items:
• An extra computer running a server class version
of Windows (e.g., Windows 2000 Server)
• An Apache Hypertext Transfer Protocol (HTTP)
server for Win32
• Perl for Win32 5.8.x
• A text editor (e.g., Notepad) to create the
Perl script
• A text editor or other HTML design application
(e.g., Dreamweaver) for HTML page prototyping
You should also have some knowledge of setting
up an Apache Web server, Perl, and (provided you
install Apache on a Windows server machine as
I did) some understanding of the Windows Task
Scheduler.
For the miniApp development (creating the actual
Java plug-in), you’ll need the following:
• A basic computer workstation for Java
development
• Eclipse 3.2 or greater installed on the workstation
• The Sametime Connect 7.5 software development
kit (SDK) downloaded and installed
• The J9 Java Development Tool (JDT) launching
plug-in for Eclipse
Installing the tools for developing the plug-in is
often the most challenging part of the process (at least
the first time) so I walk you through the installations
step by step.
You can follow the back-end development
exercise or skip ahead to the miniApp development
exercise in the section “Develop the plug-in
project.” The Perl script used in the first section
is a downloadable .pl file (a simple text file).1
1
86
You can download these files at www.eVIEW.com. From the home
page, click Search → Browse Issue → November/December 2006 →
How to extend the Sametime Connect 7.5 client: A step-by-step guide to
developing and installing plug-ins as miniApps. Scroll to the bottom of
the page for the download files.
Figure 1
The installed Total Connections plug-in
appears below the Contacts list in a
Sametime Connect 7.5 client.
The download also contains several other files,
including an .xml file with the plug-in’s source code.
The example case
In the example case, you create a simple back-end
Web server that serves a Web page with auto-refresh
for displaying the Sametime connection details. Then
you create a Perl script that collects the data returned
from the Sametime server’s StAdminAct.exe cgi-bin
program, parses it, and builds a new HTML page
with that data. When that page appears in a browser
(Figure 1), it displays the latest connectivity data each
time it refreshes, based on the settings in the HTML
code. When you’ve proven the script delivers the
information desired, you’re ready to begin developing
the plug-in.
www.eVIEW.com
©2006 THE VIEW. All rights reserved.
How to extend the Sametime Connect 7.5 client: A step-by-step guide to developing and installing plug-ins as miniApps
The plug-in is a Sametime miniApp you build in
Eclipse with Java code. You can think of it as a minibrowser specifically pointed at the HTML page you
create in the back end. So, the next task is to set up
the plug-in development environment by installing
and configuring the appropriate tools. In Eclipse, you
develop the Total Connections plug-in project, code
the activity, and set runtime properties. Finally, you
install the Total Connections plug-in in the target
Sametime Connect client.
developing the example program and display, my
environment was an older Windows 2000 machine
with the Apache Web server 2 and Perl version
5.8.x.3 You can use any HTTP server on the market
running Windows or Linux.
You can use any text editor to create the Web page
and the HTML code for displaying the connection
details. I used Dreamweaver from Adobe (formerly
Macromedia). You can also use a plain text editor to
create the Perl script.
Unfamiliar with StAdminAct.exe?
Lay out the Web page
The StAdminAct.exe tool is a small, native
executable in the cgi-bin directory of Sametime
servers. You can call this Common Gateway
Interface (cgi) script with four different
arguments to gather instant connectivity
information, such as the number of unique
users currently connected, from the Sametime
server. For more information, please read
my article, “Get instant activity data from
your Sametime server” (THE VIEW, July/
August 2006).
The example Web page serves as a layout template
that displays the information obtained by the Perl
script (developed in a bit). I suggest using dummy
connection data in this HTML page to see if the
layout works well in a browser. When you’re satisfied,
you can extract pieces of the HTML script to use in
the Perl script. The HTML code that formats the
example Web page to look like the table circled in
Figure 1 is called “Sametime Connections Details”
and is shown in Figure 2.
Set up the example program
for updating connectivity
information
Since the example Web server produces a single
page and automatically updates that page every five
minutes, you need only a simple Web server. For
Because this article focuses on plug-in development
and not Web pages, I’ll point out only a few things
in this HTML code. First, as the plug-in program
automatically updates Sametime connection details,
this HTML code automatically refreshes the page
so that the target Sametime Connect user (you or an
administrator) always sees the most current information.
Line 5 tells the page to refresh every 10 minutes.
2
3
Refer to the documentation at www.apache.org for installation and
configuration details.
Refer to the documentation at www.activestate.org for installation
assistance.
1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2. <html xmlns="http://www.w3.org/1999/xhtml">
3. <head>
Continues on next page
Figure 2
The HTML code to format the Sametime Connections Details Web page
No portion of this publication may be reproduced without written consent.
87
THE VIEW • November/December 2006
4. <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
5. <meta http-equiv="refresh" content="600"/>
6. <meta http-equiv="cache-control" content="no-cache"/>
7. <title>Sametime Connections Details</title>
8. <style type="text/css">
9. <!—
10. .style5 {font-family: Verdana, Arial, Helvetica, sans-serif; font-size: x-small; }
11. —>
12. </style>
13. </head>
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
<body>
<table width="240" border="1" cellspacing="0" cellpadding="5">
<tr>
<td colspan="2"><div align="center"><strong>Lotus Sametime</strong></div></td>
</tr>
<tr>
<td width="115"><span class="style5">Total Connections: </span></td>
<td width="119"><span class="style5">25353</span></td>
</tr>
<tr>
<td><span class="style5">Total Users:</span></td>
<td><span class="style5">23365</span></td>
</tr>
</table>
</body>
</html>
Figure 2 (continued)
(The refresh time is specified in seconds, so 600
seconds is equivalent to 10 minutes.)
You need rows that correspond to the totals that
the plug-in program will return. Lines 19 – 22
include the table tags for the row displaying the total
Sametime connections (Total Connections), and
lines 23 – 26 construct the row for displaying the
total unique Sametime users (Total Users). Some
values are hard-coded in lines 21 and 25 to help
you check the layout; this fake data is not part of
the Perl script.
When you’ve completed your page, preview it
in a Web browser (I used Mozilla Firefox) to make
sure it appears as shown in Figure 3.
88
Notice how small the connection details appear
on the page. The smallness of the display gives this
dynamic Web page two main benefits:
• It takes up only a small portion of the contact area
to display the Sametime server’s connectivity
information, leaving most of the room on the page
for the contact list.
• It fits nicely on mobile devices with small screens,
such as BlackBerry devices, which are good
delivery vehicles for administrators.
When you’re satisfied with the page layout, it’s
time to create the Perl script to retrieve the connection
details and update the HTML file.
www.eVIEW.com
©2006 THE VIEW. All rights reserved.
How to extend the Sametime Connect 7.5 client: A step-by-step guide to developing and installing plug-ins as miniApps
Develop the plug-in script
Figure 4 shows the complete Perl script to retrieve
Sametime server connection data and build it into the
HTML file for the Sametime Connections Details
page. You might recall that the SQ argument for
Figure 3
StAdminAct.exe returns values for Total Connections
(regardless of uniqueness) and Total Users (unique
users) on the Sametime server. So, to obtain the
Sametime connection details, the Perl script simply
passes the SQ argument (line 6) when calling
StAdminAct.exe (line 15).
The Web page for displaying the plug-in output
1. #!c:\\perl\\bin
2. use strict;
3. use LWP;
4. use LWP::UserAgent;
5. my $serverURL = "http://192.168.1.152/cgi-bin/StAdminAct.exe";
6. my $cmdoption = "SQ";
7. my $browser = LWP::UserAgent->new;
8. my $headfile = "c:\\www\\pages\\head.txt";
9. my $tcfile = "c:\\www\\pages\\tc.html";
10. my @num = ();
11. my @num2 = ();
12. my @headData = ();
13. my $returndata = "";
14. my @datasplit = ();
15. my $response = $browser->post($serverURL,['op_code' => $cmdoption,],);
16. if($response->is_error){
17.
$num2[1] = "NA";
18.
$num[1] = "NA";
19. }
20. else {
21.
$returndata = $response->content;
Continues on next page
Figure 4
The Perl script for the Total Connections plug-in
No portion of this publication may be reproduced without written consent.
89
THE VIEW • November/December 2006
22.
@datasplit = split('\n',$returndata);
23.
@num = split('=',$datasplit[0]);
24.
@num2 = split('=',$datasplit[1]);
25. }
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
open(HEADFILE,"$headfile") or die print "Cannot open $headfile. Program terminated.\n";
@headData = <HEADFILE>;
close(HEADFILE);
open(HTMLFILE,">$tcfile") or die print "Cannot open $tcfile. Program terminated.\n";
foreach(@headData){
print HTMLFILE $_;
}
print HTMLFILE '<tr><td width="115"><span class="style5">Total Connections:
</span></td><td width="119"><span class="style5">' . $num2[1] .'</span></td></tr>';
print HTMLFILE "\n";
print HTMLFILE '<tr><td><span class="style5">Total Users:</span></td><td><span
class="style5">' . $num[1] . '</span></td></tr>';
print HTMLFILE "\n";
print HTMLFILE '</table></body></html>';
close(HTMLFILE);
Figure 4 (continued)
Notice that line 8 references a file named “head.txt.”
The head.txt file contains lines 1 – 18 of the original
HTML document for the layout of the Web page (refer
to Figure 2).
Tip!
I think it’s easier to keep the static part of the
HTML document for laying out a page in a
separate text file. If you use this technique,
make sure to clearly comment your code. Later,
if you or someone else chooses to change the
page’s design, comments about the separate
HTML code will make updating easier.
posting of the actual update data in the next table cell.
Similar code in line 35 displays the value for Total
Users in the correct cell. These two places are the only
areas on the Web page that change each time the plug-in
program retrieves new data. You would modify these
lines to display other server details if you customize
the plug-in to use other arguments for StAdminAct.exe.
For example, say you add a line of code to call
StAdminAct.exe with the PL argument, which returns
the total number of active places on a Sametime server.
To display the result, you could add another row to the
HTML table for Total Places and then add this line of
code to the Perl script for displaying the value returned:
print HTMLFILE '<tr><td><span class="style5">
Total Places:</span></td><td><span
class="style5">' . $num[1] . '</span></td></tr>';
Also note where this script updates the HTML file
with the retrieved connection data — it happens in the
lines using “print HTMLFILE” at the end of Figure 4.
The embolded code in line 33 is where the code follows
the Total Connections label in one table cell with the
90
Schedule the script
Now schedule this Perl script to retrieve data
automatically. Since my Web server exists on a
www.eVIEW.com
©2006 THE VIEW. All rights reserved.
How to extend the Sametime Connect 7.5 client: A step-by-step guide to developing and installing plug-ins as miniApps
Windows 2000 machine, I used Windows Task
Scheduler to launch this Perl script. If you set
up your Web server on a Linux machine, you
could use the cron utility to automate the
launching of this script. I chose to run the script
every five minutes every day of the week; you
can choose a frequency appropriate for your
environment.
With the Web server in place, the HTML
page created, the Perl code created, and the script
scheduled, your next step is to test the Web page
to ensure it does exactly what you want.
Test the Web page
To test the new program and delivery mechanism,
call up the HTML file in your Web browser (as in
Figure 3) and wait. The Perl script builds a new
HTML file each time it runs. In my case, the page
refreshes itself in 10 minutes (as specified with
<meta http-equiv=“refresh” content=“600”/> in
Figure 2). The latest connection details, which
the Perl script automatically retrieves every five
minutes, should appear in the table. I haven’t run
into any problems with running a more extensive
version of this plug-in every five minutes.
Set up the plug-in
development environment
The first time you create a Sametime plug-in,
it can take more time to set up your development
environment than to code the script or create the
display. Generally, you would develop the Sametime
plug-in on a desktop. When starting from scratch,
take the following steps — all on the local
desktop:
• Install Eclipse 3.2 or greater.
• Download and install the new Sametime Connect
7.5 SDK.
• Install the J9 JDT launching plug-in for Eclipse.
Install Eclipse
As mentioned earlier, the new Sametime Connect 7.5
client is based on the Eclipse platform, so you need
Eclipse or an Eclipse-compatible integrated development environment (IDE) for developing Sametime
Connect plug-ins. Fortunately, like many Domino or
Web page developers, I already had this IDE installed
on my local workstation. If you don’t have Eclipse
yet, follow these steps to download and install this
application:
1. Open a browser and go to the Eclipse home page.4
Note!
2. Near the top of the page, click the Downloads tab.
My Sametime test server has a fair amount
of login and logout activity so a change in
connection details obtained by the plug-in is
obvious. If your Perl script points to a
Sametime server with little to no user
activity, you might not see a change in
connection details each time the page
refreshes.
3. Click the Eclipse SDK link next to Download
Now: This link takes you to a list of mirror
download sites from which you can download the
latest version of Eclipse SDK (as of this writing,
3.2 is the latest).
Creating the program and display are the
easy part. The next task, setting up the environment for creating the plug-in, is often the most
challenging.
No portion of this publication may be reproduced without written consent.
4. Select a mirror site near you and begin the
download.
5. After the download completes, double-click the
file to launch the installation process. This process
decompresses the application and puts it in a
destination folder.
4
www.eclipse.org
91
THE VIEW • November/December 2006
Eclipse downloading notes
• The Eclipse application decompresses to a
folder named “eclipse.” Therefore, if you
want Eclipse extracted to a folder named
“eclipse” under Program Files simple set the
extraction destination to Program Files.
Eclipse will do the rest.
• Eclipse comes with a few tutorials to
help you become familiar with the IDE.
If you’ve never used Eclipse, I suggest
you take some time and go through these
tutorials.
To get the latest copy of the J9 JDT plug-in
for your desktop machine from Eclipse, follow
these steps:
1. If Eclipse is running, shut it down.
2. Open a browser and enter the following URL:
http://dev.eclipse.org/viewcvs/index.cgi/
org.eclipse.ercp/org.eclipse.jdt.launching.j9/
org.eclipse.jdt.launching.j9-plugin.zip?cvsroot=
DSDP_Project
3. Select the latest version of the J9 JDT plug-in
to download (version 1.6 at the time of this
writing).
4. Extract the contents of this download to your
eclipse directory (C:\Program Files\eclipse for
my installation).
Install the Sametime Connect SDK
The Sametime Connect 7.5 SDK is available at the
IBM developerWorks Web site.5 The file size is
163MB. I extracted the toolkit to my desktop’s root
directory, where the SDK decompresses itself to a
new folder named “st75sdk.”
Install the J9 JDT plug-in for Eclipse
The J9 Java Compiled Language (JCL) Desktop
custom runtime environment is the valid Java
runtime environment (JRE) for developing Sametime
plug-ins. This JRE supports most of the features of
the Java 2 Platform, Standard Edition (J2SE) 1.4.2
JRE. Fortunately, the Sametime Connect 7.5 SDK
includes a developer version of the J9 JCL.
However, to make Eclipse recognize the J9 JCL as a
valid runtime environment, you need the J9 JDT
plug-in for Eclipse. I know — things are starting to
sound like alphabet soup. For now, though, push
aside the TLAs (three letter acronyms) and just keep
in mind that without the J9 JDT plug-in, you can’t
use the J9 JCL Desktop to compile, run, or debug
Sametime plug-in code.
When you have everything downloaded and
installed, you must configure your development
environment for creating Sametime plug-ins.
Set up Eclipse for plug-in development
Eclipse is a very flexible IDE that supports a variety
of programming languages. For example, I use Eclipse
as my primary IDE for Perl development and have
just started experimenting with PHP 6 development in
Eclipse. Since Eclipse is so flexible, you must
configure it for the specific type of development you
are doing. To set up a specific type of Eclipse
development environment, you must complete the
following basic tasks:
• Configure the runtime environment.
• Configure the target platform.
• Specify a launch configuration.
The following sections specify what to do in each
task to set up the Sametime plug-in development
environment in Eclipse.
6
5
92
http://www-128.ibm.com/developerworks/lotus/downloads/
toolkits.html.
PHP stands for Personal Home Page (also PHP) Hypertext
Preprocessor — a server-side programming language for efficiently
delivering Web pages and services.
www.eVIEW.com
©2006 THE VIEW. All rights reserved.
How to extend the Sametime Connect 7.5 client: A step-by-step guide to developing and installing plug-ins as miniApps
Configure the runtime environment
6. Click OK.
Since Sametime Connect 7.5 plug-in development
requires the J9 JCL Desktop runtime environment,
you must create a virtual workspace to use J9 JCL.
Follow these steps:
Next, you must add some external JAR files to this
new workspace. Without them, your plug-in can’t
plug in:
1. Start Eclipse (double-click the eclipse.exe
executable file in the eclipse directory).
2. From the menu bar, click Window → Preferences
to open the Preferences dialog box.
3. In the dialog box, expand Java and select Installed
JREs. Click Add on the right to open the Add JRE
dialog box.
4. In the Add JRE dialog box, change the JRE type
to J9 VM and add a name to the ‘JRE name’ field
(I used ST Desktop).
5. Click Browse next to the JRE home directory and
find the j9-runtime\win32 directory under the
st75sdk directory. (In my case, the directory was
C:\st75sdk\client\connect\j9-runtime\win32.) In the
Default VM Arguments field, enter “–jcl:max”.
The Add JRE dialog entries should now appear as
shown in Figure 5.
Figure 5
7. Continuing in the Installed JREs section of the
Preferences dialog box, click Edit.
8. In the Edit JRE dialog box, click Add External JARs.
9. Browse to the \lib\endorsed directory, which is
under the same directory browsed to in step 5.
(In my case, that directory was C:\st75sdk\client\
connect\j9-runtime\win32, so the complete address
for this step was C:\st75sdk\client\connect\
j9-runtime\win32\lib\endorsed.)
10. Select all of the JAR files listed in this directory
and click Open.
11. Back in the Edit JRE dialog box, click Add External
JARs again and browse to the \lib\jclmax\ext
directory under the JRE home directory. (In my
case, that directory was C:\st75sdk\client\connect\
j9-runtime\win32, so the complete address was
C:\st75sdk\client\connect\j9-runtime\win32\
lib\jclmax\ext.)
Configuring the Eclipse runtime environment for J9 JCL
No portion of this publication may be reproduced without written consent.
93
THE VIEW • November/December 2006
12. Select all of the files in this directory and
click Open.
13. In the ‘JRE system libraries’ section of the Edit
JRE dialog box, select the files ending in string.jar,
nio.jar, sound.jar, and harmony_regex.jar; then
click Up until these files are all at the top of the
list (for efficiency at runtime). The Edit JRE
dialog entries should now appear as shown in
Figure 6.
14. Click OK to save this runtime environment.
At this point, Eclipse should return you to the
Preferences dialog box with the Installed JREs
settings (Figure 7). You have only a few more steps to
set the runtime environment and adjust the Java
compiler:
15. Checkmark the new runtime environment to make
it your default runtime environment.
16. In the Navigator on the left, expand Java and
select Compiler.
17. Deselect the ‘Use default compliance settings’
check box and change the remaining options so
that they match those shown in Figure 8.
Figure 6
94
18. Click OK to close the Preferences dialog box.
19. When the Compiler Settings Changed dialog box
prompts you to perform a full rebuild, select Yes
(Figure 9).
Configure the target platform
When using Eclipse to develop, the default target
platform is Eclipse. Since you’re building a plug-in
for Sametime Connect 7.5, you need to change the
target platform to the specific platform where the
plug-in will function. If you forget this step, you
could end up attempting to use the plug-in to extend
Eclipse rather than the Sametime Connect client.
Follow these steps:
1. If you’ve left the environment, restart Eclipse
(double-click eclipse.exe in the eclipse
directory).
2. Click Window → Preferences to bring up the
Preferences dialog box again.
3. Expand Plug-in Development and select Target
Platform.
Adding required external JAR files to the new JRE workspace
www.eVIEW.com
©2006 THE VIEW. All rights reserved.
How to extend the Sametime Connect 7.5 client: A step-by-step guide to developing and installing plug-ins as miniApps
Figure 7
The Installed JRE settings in the Preferences dialog box
Figure 8
Adjusting the Compiler settings in Eclipse
Figure 9
Click Yes to rebuild the Eclipse compiler.
No portion of this publication may be reproduced without written consent.
95
THE VIEW • November/December 2006
4. Click the Browse button next to the Location field
and find the directory in which you installed
Sametime Connect 7.5. (In my case, that directory
was C:\Program Files\IBM\Sametime Connect 7.5.)
5. Click OK.
The end is near, and the real fun is about to begin.
Before starting the development work, however,
remember to set up the plug-in test environment. If
you’re like me, you want to run the plug-in to enjoy
the fruits of your labor, or at least find out what
doesn’t work so you can fix it.
Specify a launch configuration
In Eclipse, you can use a launch configuration to
run a plug-in for testing purposes. Since you’re
creating a plug-in for the Sametime Connect client,
set the launch configuration to start the Sametime
Connect client when you choose Run.
To specify a launch configuration, follow these
steps in Eclipse:
Figure 10
96
1. From the menu bar, select Window → Open
Perspective → Other → Plug-in Development
and click OK.
2. From the menu bar, select Run → Run and select
Eclipse Application from the configuration list.
3. Click the New icon on the far left-hand side
of the Run dialog box (shown circled in
Figure 10).
4. Enter a new configuration name in the Name field.
(For the example case, I entered “ST 7.5”.)
5. Enter a new default location for a new Sametime
Connect workplace in the Location field. (I entered
“${workspace_loc}/../struntime-workspace”.)
6. In the Program to Run section, click the ‘Run
an application’ radio button and select
com.ibm.collaboration.realtime.application.
RTCApplication from the drop-down list.
7. From the Runtime JRE drop-down list, select the J9
JCL Desktop runtime configuration created earlier.
Creating a launch configuration in Eclipse
www.eVIEW.com
©2006 THE VIEW. All rights reserved.
How to extend the Sametime Connect 7.5 client: A step-by-step guide to developing and installing plug-ins as miniApps
(In the example case, I named it “ST Desktop,” as
you can see in Figure 10.)
8. Click the Arguments tab and enter the following
VM arguments:
-Xint Xtrace:none –Xgcpolicy:gencon –Djava.
home=C:\st75sdk\client\connect\j9-runtime\
win32 –Dcom.ibm.pvc.webcontainer.port=7777
9. Select the Plug-ins tab and make sure ‘launch
with workspace and enabled external plug-ins’
is selected.
10. Click Apply to save your changes. Then click Close.
At last, with Eclipse set up with everything you
need for plug-in development downloaded and
installed, the runtime environment configured, the
target platform set, and the launch configuration
specified, you’re ready to create the actual plug-in for
Sametime Connect. Even better news is that this part
is faster than the configuration part.
Develop the plug-in project
3. Give your project a name in a format similar to
com.techtraction.demo.totalconnections and click
Next.
4. In the next dialog box, change the plug-in name to
something meaningful. (I wrote “Totalconnections
Plug-in”.)
5. Make sure that the feature ‘Generate an activator, a
Java class that controls the plug-in’s life cycle’ is
checkmarked.
6. Also checkmark the ‘This plug-in will make
contributions to the UI’ feature to alert Sametime
Connect that the plug-in makes additions to the
user interface (i.e., the Web page for displaying the
connection information).
7. Set the ‘Would you like to create a rich client
application?’ feature to No. (A rich-client
application is a full-blown application based on
Eclipse. The Totalconnections Plug-in project
simply extends an existing rich-client application.)
The dialog box should now look like the one
shown in Figure 11.
8. Click Finish.
The plug-in you’re creating is a small administrative
program that displays the Web page in a miniApp, a
part of the geography for the new Sametime Connect
client that appears at the bottom of the Sametime
contact window. The actual code for this plug-in is
minimal because simple menu selections perform
most of the work. To get started, create and configure
a new plug-in project in Eclipse.
Set up the plug-in project
Some people call the support for creating a project a
“wizard.” I don’t think of it that way because you still
need to make a lot of decisions, but you do need to
click Next and end with Finish.
To set up the project, follow these steps in Eclipse:
1. Choose File → New → Project to open the New
Project dialog box.
2. Choose Plug-in Development → Plug-in Project
and click Next.
No portion of this publication may be reproduced without written consent.
Figure 11
Creating a new plug-in project in Eclipse
97
THE VIEW • November/December 2006
Adjust the manifest file
3. Select the plug-ins listed below:
At this point, the Overview tab for the new project
automatically appears (see Figure 12). This panel
collects environmental information for the plug-in
and stores it as a manifest file (MANIFEST.MF).
The manifest describes the content of the plug-in
environment to Eclipse and allows you to control,
on a pre-package basis, the visibility of the plug-in’s
code to downstream plug-ins. You need to make the
following adjustments to the manifest:
- org.eclipse.ui — for basic Eclipse user
interface capabilities (a default)
- org.eclipse.core.runtime — for basic Eclipse
runtime components (a default)
- com.ibm.collaboration.realtime.core — for
the core Sametime classes like ServiceHub
- com.ibm.collaboration.realtime.imhub —
for obtaining the standard Sametime Connect
miniApp extension point
1. In the Overview tab, click the Dependencies tab
(at the bottom).
2. Click Add. The Plug-in Selection dialog box
appears. Eclipse automatically supplies the plug-in
selections.
Figure 12
98
Then click OK.
4. At the bottom of the Overview tab, click the
Extensions tab.
The Overview tab for a plug-in project in Eclipse
www.eVIEW.com
©2006 THE VIEW. All rights reserved.
How to extend the Sametime Connect 7.5 client: A step-by-step guide to developing and installing plug-ins as miniApps
5. Click Add. The Extension Point Selection dialog
box appears. It lists the available extensions for
Sametime Connect.
When you click Finish, Eclipse creates a basic
class document with nothing more than a package
statement at the top and an empty public class section.
6. Select the com.ibm.collaboration.realtime.imhub
miniApp and click Finish.
Start programming the Java code by importing the
following packages the plug-in needs to work:
7. Click Save to save the updated plug-in manifest.
import org.eclipse.swt.SWT;
import org.eclipse.swt.browser.Browser;
import org.eclipse.swt.widgets.Composite;
Write the plug-in code
Now it’s time to write some new code. In Eclipse,
start by creating a new Java class for the plug-in:
1. In the Package Explorer view, on the left side of
the screen, select your new plug-in project.
2. From the menu bar, select File → New → Class to
open the Java Class dialog box. Since you’ve
already selected your plug-in project from the
Package Explorer view, Eclipse automatically fills
in the class source. A class source is a source-code
framework to which you apply the rest of the code
to make the plug-in.
3. Click the Browse button next to the Package
field and select the new plug-in project from
the Package Selection dialog box.
4. Press OK.
5. Give this new class a name (I named my class
“TcMiniApp,” short for Total Connection Mini
Application).
6. Click Finish.
Figure 13
import org.eclipse.swt.widgets.Control;
import com.ibm.collaboration.realtime.miniapp.
AbstractMiniApp;
Next, since the plug-in extends AbstractMiniApp, a
standard Sametime Connect Java package, change the
‘public class TcMiniApp’ line in the package statement
of your new class to ‘public class TcMiniApp extends
AbstractMiniApp.’ Then create a browser control with
the following code:
public Control createControl(Composite parent) {
Browser browser = new Browser(parent,
SWT.NONE);
browser.setUrl("http://192.168.1.152/pages/
tc.html");
return null;
}
At this point, you should get an error message that
says, “The type TcMiniApp must implement the
inherited abstract method AbstractMiniApp.init().” If
you click on the error indicator next to the problematic
line of code, Eclipse presents the resolution options
shown in Figure 13.
Problem resolution choices offered by Eclipse when making the TcMiniApp class an extension of
the AbstractMiniApp class
No portion of this publication may be reproduced without written consent.
99
THE VIEW • November/December 2006
To solve the problem, double-click the option to
‘Add unimplemented methods.’ This action places a
method stub in your code to handle exceptions there.
You don’t need to add code to the stub at this
moment; later, you can go back and fill in some sort
of error handling if it’s needed. At this point, the
TcMiniApp class should have the Java code shown
in Figure 14.
Add refinements
The code is almost ready to test but first you should
open your manifest file again and add some XML
code that defines some finer characteristics, such as
help support, for your plug-in. I suggest some for the
example case, but to learn about all of the possibilities
of characteristics to add to your own plug-ins, you’ll
have to read the documentation that comes with the
SDK. It also helps to have a deeper understanding of
the Eclipse IDE and plug-in development. I have very
little Eclipse/Java background, and yet I was able to
read the documentation and pull together this
application in a short period of time.
To add Extensible Markup Language (XML) code
to the manifest file for your plug-in, follow these steps:
1. In the Package Explorer view, under your plugin project folder, expand the META-INF folder
and double-click MANIFEST.MF to open it
(Figure 15). It opens in the Overview tab.
2. Select the plugin.XML tab. On the plugin.XML
tab, enter the XML code shown in Figure 16.
3. When finished, save the changes to this file.
Notice the displayName setting, displayName=
“Total Connections”. The Total Connections
value specifies the name that appears in the
Sametime Connect client on the top of the
package com.techtraction.demo.totalconnections;
import
import
import
import
import
org.eclipse.swt.SWT;
org.eclipse.swt.browser.Browser;
org.eclipse.swt.widgets.Composite;
org.eclipse.swt.widgets.Control;
com.ibm.collaboration.realtime.miniapp.AbstractMiniApp;
public class TcMiniApp extends AbstractMiniApp{
public Control createControl(Composite parent) {
Browser browser = new Browser(parent, SWT.NONE);
browser.setUrl("http://192.168.1.153/pages/tc.html");
return null;
}
public void init() throws Exception {
// TODO Auto-generated method stub
}
}
Figure 14
100
The Java code for the TcMiniApp class after clicking ‘Add unimplemented methods’
www.eVIEW.com
©2006 THE VIEW. All rights reserved.
How to extend the Sametime Connect 7.5 client: A step-by-step guide to developing and installing plug-ins as miniApps
Figure 15
Finding the MANIFEST.MF file in the Package Explorer view
Figure 16
The plugin.XML tab for the MANIFEST.MF file
No portion of this publication may be reproduced without written consent.
101
THE VIEW • November/December 2006
miniApp (under the Contacts section). Also notice
the maxHeight setting to “400”. During my development cycle, I changed this setting a few times until
the Web page was small enough to show only the
relevant information when the miniApp was expanded.
If you add more information to the Web page for
this miniApp, you probably need to adjust this
maxHeight setting.
You can change the code or tweak the plug-in’s
basic configuration and appearance. Since the data is
presented in an HTML page, you can customize the
look and feel of that data to whatever extent HTML
allows. You’re only limited by your knowledge of
HTML. To give you an idea of your customization
possibilities, Figure 17 shows a more polished plugin that my company uses.
Test the new Sametime Connect
plug-in
Make the plug-in standalone
When everything appears ready, it’s time to run the
plug-in through the local Sametime Connect client.
To conduct a test run of the plug-in in Eclipse, follow
these steps:
When you’re satisfied with how the plug-in looks and
operates, it’s time to convert the plug-in into a
standalone bit of code that you can permanently add
to your Sametime Connect 7.5 client. Convert the
plug-in as follows:
2. In the Run dialog box, select the Plug-ins tab.
1. In the Package Explorer view, select the project
(in my case, com.techtraction.demo.
totalconnections).
3. Make sure the correct plug-in has a check mark
next to it.
2. From the menu bar, select File → Export to open
the Export dialog box.
4. Click Run.
3. Select ‘Deployable plug-ins and fragments’ and
click Next.
1. From the menu bar, select Run → Run.
At this point, the Sametime Connect 7.5 client
starts to load in Eclipse. You are prompted to log into
your Sametime server. When you log in, you should
see the Total Connections option at the bottom of your
Contacts list. When you click the option, the section
should expand and you should see the Web page being
served by your dedicated Web server. Depending on
your settings (after 10 minutes in the example), this
Web page should auto-refresh and display a new set
of connection data, as shown in the Web page in
Figure 1.
Troubleshooting note
Creating this simple plug-in tests your attention
to detail rather than your programming skills.
The problems I encountered were almost all
typing errors. The second most common cause
of errors is an occasional missed step.
102
4. Checkmark the plug-in from the list of available
Plug-ins and Fragments (again, in my case
com.techtraction.demo.totalconnections).
5. Specify a destination directory (I chose C:\temp).
Accept the rest of the default settings.
6. Click Finish.
Export the plug-in to
Sametime Connect clients
The single plug-in file sits in the destination directory.
Take this file and drop it into the plug-in directory of
the Sametime Connect 7.5 directory. In my case, that
directory was C:\Program Files\IBM\Sametime
Connect 7.5\plugins. Now close Eclipse and start the
Sametime Connect client. Notice how the Total
Connection plug-in appears the same way it did
during the test cycle in Eclipse. Success!
www.eVIEW.com
©2006 THE VIEW. All rights reserved.
How to extend the Sametime Connect 7.5 client: A step-by-step guide to developing and installing plug-ins as miniApps
I stored the Total Connection plug-in file in a local
directory. To share it, I simply send the file to others
in an e-mail message with simple instructions for
where to save the file.
Conclusion
Figure 17
An active plug-in
Around 60% of this plug-in project work involved
installation and configuration. Another 30% was mostly
setting up the back-end Web server to make the Web
page that displays the total connection information.
Only about 10% of the plug-in development work
involved writing Java code. That percentage is not too
bad when you consider the look and functionality of
the final product. Obviously, not all plug-in projects
are this easy, but even a little Java knowledge can take
you far. As your Java skills grow, you can extend the
Sametime Connect 7.5 client farther. Don’t be afraid.
Get in there and see what you can do.
Resources
ActiveState Programmer Network:
www.activestate.org
The Apache Software Foundation:
www.apache.org
Eclipse:
www.eclipse.org
Sametime SDK Download:
http://www-128.ibm.com/developerworks/lotus/downloads/toolkits.html
No portion of this publication may be reproduced without written consent.
103
THE VIEW • November/December 2006
United States Postal Service Statement of Ownership, Management, and Circulation 1.Publication Title THE VIEW. 2.Publication Number #0015-455. 3.Filing Date 10/1/06. 4.Issue
Frequency Bi-monthly. 5.Number of Issues Published Annually 6. 6.Annual Subscription Price $374.00. 7.Complete Mailing Address of Known Office of Publication 11300 Rockville Pike,
Suite 1100, Rockville, Montgomery County, MD 20852-3030. Contact Person Renee Dudash Telephone (301) 287-2212. 8.Complete Mailing Address of Headquarters or General Business
Office of Publisher Same as #7. 9.Full Names and Complete Mailing Addresses of Publisher, Editor, and Managing Editor Publisher Bonnie Penzias, Senior Editor Ann Baker, Editor-inChief Celeste Frey, All located at 990 Washington Street, Suite 308 South, Dedham, MA 02026-6790. 10.Owner Full Name UCG Technology, LLC Bruce Levenson, Edwin Peskowitz,
Robert Koran, Nancy Becker, Daniel Brown, Todd Foreman. Complete Mailing Address All Located At 11300 Rockville Pike, Suite 1100, Rockville, MD 20852-3030. 11.Known
Bondholders, Mortgagees, and Other Security Holders Owning or Holding 1 Percent or More of Total Amount of Bonds, Mortgages, or Other Securities None. 12. n/a. 13.Publication Title
THE VIEW. 14.Issue Date for Circulation Data Jul/Aug 2006. 15.Extent and Nature of Circulation 15a.Total Number of Copies (Net Press Run) Average No. Copies Each Issue During
Preceding 12 Months 2,742, No. Copies of Single Issue Published Nearest to Filing Date 2,418; 15b.Paid Circulation (1)Mailed Outside-County Paid Subscriptions Stated on PS Form 3541
886(average), 886(actual); (2)Mailed In-County Paid Subscriptions Stated on PS Form 3541 0(average), 0(actual); (3)Paid Distribution Outside the Mails Including Sales Through Dealers and
Carriers, Street Vendors, Counter Sales, and Other Paid Distribution Outside USPS 0(average), 0(actual); (4)Paid Distribution by Other Classes of Mail Through the USPS 1,026(average),
951(actual); 15c.Total Paid Distribution 1,912(average), 1,837(actual); 15d.Free or Nominal Rate Distribution (1)Free or Nominal Rate Outside-County Copies Included on PS Form 3541
56(average), 39(actual); (2)Free or Nominal Rate In-county Copies Included on PS Form 3541 0(average), 0(actual); (3)Free or Nominal Rate Copies Mailed at Other Classes Through the
USPS 0(average), 0(actual); (4)Free or Nominal Rate Distribution Outside the Mail 382 (average), 150 (actual); 15e.Total Free or Nominal Rate Distribution 438(average), 189(actual);
15f.Total Distribution 2,350(average), 2,026(actual); 15g.Copies Not Distributed 392(average), 392(actual); 15h.Total 2,742(average), 2,418(actual); 15i.Percent Paid 81.36%(average),
90.67%(actual). 16.Publication of Statement of Ownership If the publication is a general publication, publication of this statement is required. Will be printed in the Nov/Dec 2006 issue of
this publication. Signature and Title of Editor, Publisher, Business Manager, Or Owner Renee M. Dudash, Director of Central Production.
104
www.eVIEW.com
©2006 THE VIEW. All rights reserved.