06/11/2008

RPC Monitor plug-in for Notes 8

Category  
Bookmark : del.icio.us  Technorati  Digg This  Add To Furl  Add To YahooMyWeb  Add To Reddit  Add To NewsVine 


I have been working on some old and slow Notes Client applications recently and found the RPC (Remote Procedure Call) debug information from the Notes Client to be a really useful tool for seeing exactly what is going on behind the scenes when a document or view is opened.

For those that don't know, there are a few settings in the notes.ini file which make the client write RPC debug information to a file or console. The information shows each transactions between the client and server, how long it took and how much data was exchanged.

To make it easier to configure and understand the output I thought I'd write a plug-in, so here it is, the RPC Monitor plug-in for Notes. It can be downloaded from the usual place and the source is in the CVS.

I've tested it on Windows OK but I'd be really interested to know if it works OK on Macs and Linux.

A picture named M2

The plug-in code is pretty straight forward, it just monitors the debug file for new data, parses it into transactions and plonks it all in a table. The neat things from a programming point of view is the use of EMF (Eclipse Modelling Framework).

I've used EMF before in the DXLPeek plug-in but that was more black-magic than deliberate programming. The RPC Monitor uses a simple EMF model I built from scratch. It's really made Eclipse programming much easier. All of the model Java code is automatically created and it even generates most of the presentation code.

If anyone's thinking of writing any plug-ins, EMF is definitely the way to go.

06/11/2008

Updated DocViewer plug-in

Category   
Bookmark : del.icio.us  Technorati  Digg This  Add To Furl  Add To YahooMyWeb  Add To Reddit  Add To NewsVine 


If you are using the DocViewer plug-in version 1.0.5 is now available from the usual place. There's nothing new from a functional point of view but there are a few small changes to the user interface.

The main reason for the update is to fix a potential performance problem.

The DocViewer plug-in works by listening  for changes in selection in the Notes Client. When it detects that a new document is selected it reads the values of all the Items on the Document and displays them in a table in the sidebar.

This is all fine, but what happens if the DocViewer or the Sidebar is minimised and not visible in the UI? The answer is that previous versions still listened for changes in selection and still read/displayed all the Items. This is very inefficient because the plug-in is still reading data even if no one is looking at it.

What's needed is some way for DocViewer to know if it is actually visible. If it's not then it can stop responding to changes in selection and save the extra network/server load of reading all the Items.

In Eclipse/Notes the way to do this is to implement the IPartListener2 interface. Our implementation is called DocViewPartListener. By implementing this interface and registering it with the Workbench, the plug-in will be told about changes in it's lifecycle, such as when it becomes visible, hidden or closed.

Creating the new class is a matter of clicking on File -> New -> Class, specifying the name and then specifying that we want to implement the com.eclipse.ui.IPartListener2 interface. Eclipse then creates the class and stubs of all the required methods.

The methods we are interested in are partVisible and partHidden which get called when the plug-in becomes visible or hidden.

   15 public class DocViewerPartListener implements IPartListener2 {
  16
  17         /* A flag wich indicates whether the ViewPart is visible in the UI */
  18         private boolean isVisible = false ;
  19         /* The ViewPart we  are listening to */
  20         private IViewPart viewPart ;
  21
  22         public DocViewerPartListener( IViewPart viewPart ) {
  23                  this.viewPart = viewPart ;
  24         }

  46         public void partHidden(IWorkbenchPartReference part) {
  47                  if ( part.getPart( true ) == viewPart  ) {
  48                           isVisible = false ;
  49                  }
  50         }

  60         public void partVisible(IWorkbenchPartReference part) {
  61                  if ( part.getPart( true ) == viewPart ) {
  62                           isVisible = true ;
  63                  }
  64         }
  65

   69         public boolean isVisible() {
  70                  return isVisible;
  71         }
  72

   76         public void setVisible(boolean isVisible) {
  77                  this.isVisible = isVisible;
  78         }
  79
  80 }


Creating an instance of our part listener and registering it with the Workbench is done in the DocViewerView class.

 131   // Create a part listener. This listener will be told whenever part of the
 132   // workbench is visible, hidden, closed etc.
 133   partListener = new DocViewerPartListener( this ) ;
 134   workbenchPage = Activator.getDefault().getWorkbench().getActiveWorkbenchWindow().getActivePage() ;
 135   workbenchPage.addPartListener( partListener ) ;


As with all listeners it is best practice to stop listening when the plug-in is closed.

   92  public void dispose() {
  93

   94         // When the view is disposed, ie closed, we need to make sure we stop
  95         // listening to changes in selection.

  97         workbenchPage.removePartListener( partListener ) ;
  98
  99 }



The final step is to change the showSelection method so that we don't bother responding to new Documents if the plug-in is hidden.

  176   // if the DocViewer isn't visible, don't respond to any changes in selection.
 177   if ( !partListener.isVisible() ) {
 178          return ;
 179   }

06/11/2008

Is plug-in development broken in 8.0.2?

Category   
Bookmark : del.icio.us  Technorati  Digg This  Add To Furl  Add To YahooMyWeb  Add To Reddit  Add To NewsVine 


Help! Since 8.0.2 none of my plug-ins work in my development environment! They all worked fine in 8.0.1, 8.0 and 8 beta. Is plug-in development broken in 8.0.2?

Before the weekend someone contacted me and asked for some help with the DocViewer plug-in. They had imported the source code into Eclipse but when they tried to run the plug-in it wasn't working correctly. When a Document is selected in Notes the DocViewer is supposed to show details of all the Items but nothing was happening no Items were being displayed.

Let me be clear, the plug-in works fine from a users point of view when they are installed in Notes 8. The problem only occurs if you are developing plug-ins and launching them from Eclipse.

After a bit of digging around I found the problem. The Notes Session object did not have access to any database. None of them. Uh? Here's what happens every time the plug-in tries to access a Database/Document:

NotesException: Password or other security violation for database Server1/Dev!!names.nsf
    at lotus.domino.local.Session.NgetDatabase(Native Method)
    at lotus.domino.local.Session.getDatabase(Unknown Source)


Very strange since my ID is God in my own development environment. Even stranger when, by definition, the database must already be open in the Client for any documents to be selected!

I tried using the Repton plug-in and it fails too for the same reason. I created a small test plug-in which has the following code on an Action button and it fails...

NotesThread.sinitThread();
Session session = NotesFactory.createSession() ;                        
Database names = session.getDatabase( "Server1/Dev", "names.nsf") ;
View people = names.getView("People") ;
Document person = people.getFirstDocument() ;


Now all of this code runs perfectly on every other version of Notes I have used. It just seems to have broken in 8.0.2.

Does anyone have any idea what might be happening and how it might be fixed? Is anyone using Eclipse/Notes 8.0.2 to develop plug-ins successfully?

06/11/2008

Developing a simple plug-in for Lotus Notes. Part 3

Category   
Bookmark : del.icio.us  Technorati  Digg This  Add To Furl  Add To YahooMyWeb  Add To Reddit  Add To NewsVine 


This is part 3 of a three part tutorial.
Part 1
Part 2

8. Creating an Update Site Project

To create a new Update Site project select File -> New -> Other... from the main menu.
Expand the Plug-in Development section, select Update Site Project and click Next.
tutorial1-49.jpg
On the Update Site Project page enter the name of the project. Give it the same name as the plug-in with .update on the end and then click Finish.
tutorial1-50.jpg
The new update site project can now be seen in the Project Navigator view and site.xml is open for editing.
Select the Site Map tab and click the New Category button. On the Category Properties form change the values of the Name and Label fields to Tutorials.
tutorial1-51.jpg
Select the Tutorials entry in the Managing the Site form, click on the Add Feature... button, select the com.domiclipse.tutorial1.feature feature and click OK.
tutorial1-52.jpg
Click on the Build All button and wait for all the features to be built.
Save and close site.xml
In the Package Explorer we can see that there are two new folders in the update Project, a features folder and a plugins folder. These folders contain the actual jar files that will be installed on the Notes 8 Client.
In addition, the site.xml file defines which plugins and feature are available on the update site.
tutorial1-53.jpg
The tutorial1 feature is now ready to be installed in Notes 8.


9. Installing the plug-in in the Notes 8 Client

Before any plug-ins can be installed in Notes 8 the client needs to be configured correctly. Locate the file {notes install dir}\framework\rcp\plugin_customization.ini, add the line com.ibm.notes.branding/enable.update.ui=true and restart the client.
From the main menu select File -> Application -> Install.
Select Search for new features to install
Create a new Local Update Site which points to the site.xml file in the update site project.
tutorial1-54.jpg
Select the new location and click Finish.
tutorial1-55.jpg
Select the Tutorial1 Feature, click Next and agree with all subsequent dialogs. Finally, allow Notes 8 to restart.
tutorial1-56.jpg
Once the client has restarted you should see the plug-in in the Sidebar.
tutorial1-57.jpg



10. Creating a Notes Application Update Site


The local update site we created in the previous section is fine for testing purposes but if we want to make our plug-in available to the world there are two choices.
  1. Copy the update site folder onto a web server and publish the address of the site.xml file.
  2. Create a Update Site Notes Application and replicate it onto a web server.

In this section we will create a Notes Application Update Site and replicate it onto a web server.
Open the Notes 8 client and select File -> Application -> New... from the main menu.
Specify the Title and Filename, select the Show advanced templates option, select the Eclipse Update Site (8) template and click OK.
tutorial1-58.jpg
Once the new application has opened, click on the Import Local Update Site... action.
tutorial1-59.jpg
Browse to the site.xml file in the update site project and click OK.
tutorial1-60.jpg
After a few moments the local update site is imported into the database.
tutorial1-61.jpg
After setting the ACL appropriately, create a new replica on a web server. I made a replica on the Domiclipse server. The URL is http://www.domiclipse.com/domiclipse/TutorialUpdateSite.nsf
Accessing the site via a web browser displays the default web page that describes how to use it and what features are available.
tutorial1-66.jpg
To use the new update site we need to create a new Remote Update Site that points to http://www.domiclipse.com/domiclipse/TutorialUpdateSite.nsf/site.xml and then install the plug-ins as normal.
tutorial1-63.jpg


11. Conclusion


This tutorial has shown how to configure Eclipse and Lotus Expeditor for the development of Lotus Notes 8 plug-ins. We have seen how to create a simple plug-in and test it in Notes 8. We have also seen how to package the plug-in for deployment via a Local Update Site and a Notes Database Update Site.

Future tutorials will explain some of the fundamental Eclipse concepts and look in more detail exactly how the plug-in works.

06/11/2008

Developing a simple plug-in for Lotus Notes. Part 1

Category   
Bookmark : del.icio.us  Technorati  Digg This  Add To Furl  Add To YahooMyWeb  Add To Reddit  Add To NewsVine 

  1. Introduction
  2. Installing Lotus Notes 8
  3. Installing and configuring Eclipse and Expeditor
  4. Creating a simple plug-in
  5. Testing the plug-in
  6. Customising the plug-in
  7. Creating a Feature Project
  8. Creating an Update Site Project
  9. Installing the plug-in in the Notes 8 Client
  10. Creating a Notes Application Update Site
  11. Conclusion

This is part 1 of a three part tutorial.
Part 2
Part 3

1. Introduction

 

This tutorial will show you how to create, test and deploy a simple Sidebar plug-in for Lotus Notes 8.

This tutorial is focused on the process of creating, testing and deploying the plug-in rather than explaining how to write the plug-in itself. In fact we will not see any Java code in this tutorial. That will be the subject of further tutorials. In this tutorial we will let Eclipse write all the code for us.

After creating and testing the plug-in it will be packaged onto an Update Site and installed into the Notes 8 Client.

The finished plug-in looks like this in the Notes 8 Sidebar:

tutorial1-57.jpg

2. Installing Lotus Notes 8

 

The tutorial assumes that you already have the Notes 8 client installed. I have only tested this tutorial on Notes 8.0.2 but it should run fine in 8.0, 8.0.1 and 8.5.
There is no need to have access to a Domino server unless you want to replicate your update site to a web server as described in section 10.

3. Installing and configuring Eclipse and Expeditor

 

There are various different packages of Eclipse that can be downloaded from eclipse.org, each one tailored for a different audience. However, the Lotus Expeditor Toolkit 6.1.2 only seems to install correctly on Eclipse 3.2.2. Newer version of Eclipse don't work because Expeditor has dependencies on older  version of Equinox.

Eclipse 3.2.2 can be found here. For Windows eclipse-SDK-3.2.2-win32.zip is the file you need.

Eclipse doesn't need installing like a normal Windows program. Just unzip the file to a suitable location of your hard-drive. That's it, no need to run any install program.
To run Eclipse just double-click on eclipse.exe.

Top Tip: On Windows file paths can only be 260 characters long. If you try and unzip the file on your Desktop you might get error messages about files needing passwords or warnings that filenames are too long. Try extracting the files to a location with a shorter filepath, eg c:\temp.

The Lotus Expeditor toolkit can be downloaded for free from the Lotus Download site but you will need an IBM User ID. Download the Lotus Expeditor Toolkit 6.1.2 Multiplatform Multilingual. There appear to be two identical versions of the toolkit for download so I downloaded the first in the list.
Unzip the Lotus Expeditor 6.1.2.zip file to a local folder.
The Expeditor Toolkit is installed from within Eclipse so launch the program by double-clicking on eclipse.exe.
The first time you start Eclipse you will be asked for the location of the workspace. This is the directory that will contains all you Eclipse projects.
Top Tip: If you have lots of different projects and plug-ins you can have different Workspaces and switch between them.
tutorial1-2.jpg
When the Welcome page appears, click on the Workbench icon.
tutorial1-4.jpg
Now we need to install the Expeditor Toolkit. The toolkit is distributed as a set of plug-ins in an Update Site. We will see how to create our own Update Site later in this tutorial.
From the main menu select Help -> Software Updates -> Find and Install...
Select Search for new features to install and click on the Next button.
Click on the New Local Site... button and navigate to the Expeditor_Toolkit_install folder within the folder where you unziped the toolkit and click OK.
tutorial1-10.jpg
Make sure that the new update site is selected and click Finish.
tutorial1-12.jpg
The next dialog show all the different features in the toolkit. What do they all do? No idea... but it's all very clever so we might as well install the lot.
Select the top level checkbox and click on the Next button. Accept the license and click Finish. Then wait as about a zillion plug-in are downloaded and installed.
tutorial1-14.jpg
When prompted to restart the Workbench, click Yes.
After Eclipse has restarted you will be asked to configure the Expeditor Toolkit. Select Lotus Notes 8 as the Test Environment and click OK.
tutorial1-16.jpg
That's it, Eclipse and Expeditor are now configured for developing Notes 8 plug-ins.


4. Creating a simple plug-in

 

Now let's get Eclipse to write a plug-in for us.
Form the main menu select File -> New -> Other.
Expand the Plug-in Development section, select Plug-in Project and click on the Next button.
tutorial1-18.jpg
Give the plug-in an ID, mine is called com.domiclipse.tutorial1. Click on the Next button.
tutorial1-20.jpg
On the Templates page select Plug-in with a view and click Finish.
tutorial1-24.jpg
After a few moments our plug-in is opened in the workbench.
On the left hand side of the screen is the Package Navigator view which shows all the Projects in the Workbench. The most important bits are the src folder which contains all the Java code and the plugin.xml file which defines how our plug-in fits into the Eclipse environment.
To add our view to the Lotus Notes 8 Sidebar we need to define an Extension.
Click on the Extensions tab of the plugin.xml file and click on the Add... button.
tutorial1-28.jpg
De-select the Show only extension points from the required plug-ins checkbox and in the Extension Point filter field start typing com.ibm.rcp.ui.
Select the com.ibm.rcp.ui.shelfView Extension Point and click Finish.
tutorial1-29.jpg
Select Yes to add the com.ibm.rcp.ui plug-in to the dependencies.
tutorial1-30.jpg
Right-click on the new extension point and select New -> shelfView.
In the Extension Element Details form enter the class name of our view in the id and view fields. In this case the view is called com.domiclipse.tutorial1.views.SampleView. Note, class names are case sensitive.
tutorial1-31.jpg
Save and close the plugin.xml file.
Our plug-in is now finished. Time to test it.

06/11/2008

Developing a simple plug-in for Lotus Notes. Part 2

Category   
Bookmark : del.icio.us  Technorati  Digg This  Add To Furl  Add To YahooMyWeb  Add To Reddit  Add To NewsVine 


This is part 2 of a three part tutorial.
Part 1
Part 3

5. Testing the plug-in

 
Click on the Run button tutorial1-32.jpg or select Run -> Run... from the main menu.
In the Run dialog select Client Services and click on the New tutorial1-34.jpg icon.      
Expeditor will do most of the work to setup the new run configuration. All we need to do is name it Notes 8 instead of the default New_configuration and click on the Run button.
tutorial1-67.jpg
Note. Only one instance of Notes 8 can be open at once. If you already have your 'real' copy of Notes 8 open the development instance will fail to launch with the following error.
tutorial1-36.jpg
Once Notes 8 is open our new plug-in will show in the Sidebar. If it doesn't, select View -> Sidebar Panels -> Sample View from the main menu.
tutorial1-37.jpg


We have now written our first Lotus Notes 8 plug-in.

6. Customising the plug-in

 

Now it's time to make a few changes to the plug-in. We are not going to write any code but we will change the views icon and name.

Close the development instance of Notes 8 and return to Eclipse.
Double-click on plugin.xml file in the Project Navigator.
Select the Extensions tab and expand the org.eclipse.ui.views extension and select the Sample View (view) entry.
Change the value of the name field from Sample View to Tutorial 1.
Change the value of the icon field from icons/sample.gif to icons/tutorial1.gif. Note: Images names are case sensitive.
Save and close plugin.xml.
tutorial1-38.jpg
Download this icon tutorial1.gif, save it as tutorial1.gif and paste it into the icons folder of the plug-in.
Click on the Run button tutorial1-32.jpg to test the plug-in in Notes.    
Here's how the plug-in looks now. Note the new icon and title.
tutorial1-40.jpg


Our plug-in masterpiece is finished. In the next section we will see how to package it so that it can be installed in the Notes 8 client.

7. Creating a Feature Project


This section will explain how to package our plug-in so that it can be installed into the Notes 8 client. We will create a feature plug-in, an update site and an update site database.

Earlier on in the tutorial we installed the Lotus Expeditor toolkit and I said that we were installing loads of plug-ins. That's only partly true. In Eclipse we never actually install plug-ins, we install Features. So, before anyone can install our plug-in we need to create a feature which will hold the plug-in.
To create a new feature project select File -> New -> Other... from the main menu.
Expand the Plug-in Development section, select Feature Project and click Next.
tutorial1-41.jpg
On the Feature Properties page enter the name of the project. Give it the same name as the plug-in with .feature on the end and then click Next.
tutorial1-42.jpg
On the References Plug-ins page select the com.domiclipse.tutorial1 plug-in and click Finish.
tutorial1-43.jpg
The new feature project can now be seen in the Project Navigator view and feature.xml is open for editing.
Select the Overview tab and change the Name of the feature from the default Feature Feature to Tutorial1 Feature.
tutorial1-46.jpg
Select the Information tab and enter the description, copyright and license of the feature.
tutorial1-45.jpg
Select the Plug-ins tab. This tab shows which plug-in are included in the feature.
tutorial1-48.jpg
Save and close feature.xml.
The feature is now ready to be deployed to an Update Site.

06/11/2008

This one's gotta work or I'm shooting myself.

Category
Bookmark : del.icio.us  Technorati  Digg This  Add To Furl  Add To YahooMyWeb  Add To Reddit  Add To NewsVine 


Luckily Part 2 of the tutorial now woks so I won't be shooting myself... not yet anyway...

I've struggled for hours to get my rich-text blog posts to display correctly. Tutorial part 2 was especially troublesome.

It seems that having a combination of imported pictures and an attachment confused the Blogsphere engine. Moving all the images into a separate document and referring to them by pass-thru HTML has fixed the problem.