All you wanted to know about the Notes directory structure is explained here: “Understanding the IBM Lotus Notes 8.5.x client directory structure” via Stephan Wissel.
“This article explains the changes that were introduced in the IBM Lotus Notes 8.5 File System installation and describes them with respect to the installation, setup/launch/run, and uninstall phases in the client’s life cycle. Also included are answers to some FAQs on the client file system.”
I get a lot of questions (via e-mail and IM) on how to get started with plugin development for the Lotus Notes platform. Instead of answering them all individually I thought I would (finally) write a general purpose blog post to try and answer these questions in general terms.
First of I’m sorry to say that the current state of affairs for someone who want to get started doing plugin development for the Lotus Notes platform is grim. There is as you might have experienced very little material available for programmers new to the Eclipse world to build stuff for Lotus Notes 8+ clients. To make things worse the material that is available often cut corners or simply start out too advanced. That being said I am hearing muffled voices mention some material being developed and that IBM Lotus is focusing on this matter but it will be yet some time before it’s out. Until that time and until we can upload information directly into the brain like martial arts skills are given to Nemo in The Matrix I suggest the following.
My suggestions for someone getting started would be to start by realizing that programming for Eclipse and hence in SWT for the Lotus Notes 8 client has nothing, what so ever, to do with traditional Notes programming. It sounds obvious but once you have accepted this it gets easier. Maybe not easier technically but easier to accept that this is a completely new field you’re venturing into. If nothing else you stop looking to IBM Lotus for help and instead turn to the Eclipse side of the internet.
Before you start to whine I think this is just fine and how it should be. Really. Initially most of the stuff you need to know to get started has nothing to do with IBM Lotus but is general purpose Eclipse development information. It’s like blaming Toyota for not telling you how to repair their cars. Toyota can be expected to tell you and document what’s so special about their cars. They can’t be expected to teach you the basics – you go to a car repair classes for that.
It’s the same with Eclipse development. Learn the basics and specialize from there. You could say that we could expect information about the various ways to extend the client to readily available and better documented. I’ll give you that… 🙂
Once you’re past that and before you embark on your journey first realize this. In Eclipse and SWT we build everything our selves and we’re left to the mercy of the client and the differences that exist across the different platforms (Notes 8.0.x vs. Notes 8.5 across Mac / Linux / Windows XP / Windows Vista / Windows 7). We’re close to the metal with all the benefits, worries and problems that entail.
So if I had to come up with an action plan for learning about Eclipse / Expeditor / Notes 8+ development it would be something like the following:
As you can see it’s no small adventure you’re starting into. The learning curve may be steep but it’s also rewarding to be able to extend the client beyond belief. If only you’d started learning Java earlier…
As you probably know installing and uninstalling Java extensions (“plugins”) into the Lotus Notes client is easy using either File >> Application >> Install, File >> Application >> Application Management or the widget catalog. Sometimes however this doesn’t work and you’ll have to resort to a manual uninstall. This blog post outlines the way to perform a manual uninstall.
We have to start with some basics though. A Java extension in Lotus Notes (also known as a “plugin”) consists of two things:
Both an Eclipse plugin and an Eclipse feature are represented in the file system as JAR-files (files with an extension of “JAR”) and both of them are kept in the file system. A JAR-file is just a fancy ZIP-file with a predefined folder structure. Eclipse Features and plugins are stored in two directories beneath your Notes data directory (<Notes data dir.>/workspace/applications/eclipse/features for the features and <Notes data dir.>/workspace/applications/eclipse/plugins for the plugins).
From the above it may seem obvious that simply deleting these files will uninstall a Java extension – unfortunately there’s a final piece to the puzzle. Lotus Notes also keeps a record of what’s installed in a file called platform.xml (stored in <Notes data dir>workspace.configorg.eclipse.update). Simply deleting the feature(s) and plugin(s) may seem to work but will misbehave for instance when activating the File >> Application >> Application Management interface. The solution is to edit this file as well.
The complete steps to manually uninstalling a Java extension is therefore as follows:
Let me know if the above doesn’t work for you.
Please note: Manually uninstalling a Java extension installed via a widget descriptor via a widget catalog/policy will probably just make it reinstall once uninstalled.
So I have an iPhone and work with calendars on a daily basis so I’m constantly looking for new ways to work with them. For a long time I have been pondering the separation of calendar usage between my work and private life. Ideally they should be separate but viewable together. Up to now I haven’t really found a solution that worked and have been using my Notes calendar for everything using it both from my Notes client and my portable device (aka cellphone). The main problem with that was that there was no easy way to allow my wife, family or others to peek into my calendar on an adhoc basis. I know there’s stuff like Tungle but lets face it – it’s still in beta and it will be some time before it’s Wife certified… 🙂
As of yesterday I think I have the solution though.
Part of Notes 8 is how easy it is to federate calendars into the product calendar by adding either iCal, Google calendars or the like into the calendar using calendar overlays (much has been written about that so Google away if you need more info). I have been perfectly happy with my current setup (using my Notes calendar and Lotus Traveler for everything) up to now but using an iPhone finally pushed me over the edge. The reason? Well there is no way to mark an appointment on the iPhone as private. It does however have the concept of multiple calendars. Whether that’s a shortcoming in the iPhone I’ll leave up to you.
However much I like my colleagues I don’t think they necessarily should have the possibility to see, or be burdened with, what I’m doing on my own time so not being able to mark appointments from the iPhone as private has been an issue for me. When I created appointments on my iPhone (during my weekly calendar sync with my paper-calendar using wife) I had to remember to edit the appointments afterwards in Notes and set the private flag which was cumbersome and a hassle. Plus forgetting it made me ripe for ridicule from my colleagues when they saw what my wife made me agree to!
Yesterday I decided to do something about it and investigated it again. I moved my private calendar to my Google calendar after discussing it on Twitter with members of the community incl. Per Henrik Lausten (who is also my new McDaddy and Mac pusher). Now I’m using CalDAV to federate/sync my Google calendar to my iPhone. My Notes calendar is already there using Lotus Traveler and appointments are easily distinguishable as work appointments are in red and private appointments are in blue. In my Notes calendar I simply use a calendar overlay to display my private calendar alongside my work calendar using the same color scheme. My private calendar is even available offline by checking a box – does it get any sweeter? For me it’s as near to perfect as seems possible now.
I want to thank the community on Twitter for pointing me in the right direction. If you want to see how to configure CalDAV on your iPhone I suggest ‘How to Sync Google Calendar With iPhone Calendar‘ as an easy way to get started. Happy Friday!
From time to time I come across some functionality I think should be part of the Notes client but isn’t. If it’s really a big pain point for me and I can implement it myself I do so as a Notes plugin. I’ve implemented a number of such plugins over time but few have ever been published. Since I get requests for similar functionality from time to time I decided to create a page and publish the functionality there as I find the time and dig out the code and polish it of. I envision the list growing over time so do come back! 🙂
If you got suggestions let me know.
Further reading: Notes 8 Utilities
If you’re developing console applications in Java that access Notes resources and you’re testing them in Eclipse you have experienced the following. You run your application to test it from Eclipse. It accesses a Notes resource and you haven’t granted 3rd party applications access in the Security settings so it causes Notes to ask you for the password – only the Console view doesn’t accept input… Bummer! 🙁
Fortunately there’s a solution to this which I’ll show below.
Disclaimer: I can in no way take credit for this tip as I didn’t discover it. The credit goes to Karsten Lehmann who posted it in the Design Partner forum.
The solution is not to make the password prompt go to the Console view but pop up a password entry dialog instead. The way to do this is to initialize the Swing UI framework before running your application as I do below (see code in bold).
import javax.swing.SwingUtilities;
import lotus.domino.Session;
import lotus.domino.Database;
import lotus.domino.DocumentCollection;
import lotus.domino.NotesFactory;
import lotus.domino.NotesThread;
public class Main {
public static void main(String[] args) {
try {
SwingUtilities.invokeLater(new Runnable() {
public void run() {}
});
NotesThread.sinitThread();
s s = NotesFactory.creates();
System.out.println("Name: " + s.getUserName());
Database db = s.getDatabase("server1/Example", "names.nsf");
DocumentCollection dc = db.getAllDocuments();
System.out.println("Docs: " + dc.getCount());
} catch (Throwable t) {
t.printStackTrace();
} finally {
NotesThread.stermThread();
}
}
}
I just upgraded my Thinkpad from Windows Vista 32 bit to Windows 7 64 bit and besides being amazed at the speed improvements (thanks to moving of Windows Vista) I needed to think about how I develop Java for Notes in general. When moving to 64 bits there are some things you need to consider if, and only if, you install the 64 bit version of the Java Development Kit (JDK) as I did. You need to consider stuff for two reasons which I’ll address in turn.
Please note: This blog post will focus on 64 bits Windows 7 as that’s what I’m running now but I suspect it will apply to other Notes platforms such as Windows Vista, Linux and Mac as well. I’m not using Lotus Expeditor Toolkit so I can’t confirm the following is but a wise man told me that XPD Toolkit doesn’t support 64 bit JDK’s so in that case you need this as well as my “Configure Eclipse 3.4 for Notes 8.5.1”-guide as well.
Say you install a 64 bit JDK and try to run an application that access Notes using local address (NRPC; a client or server installed on the same machine) such as the following:
import lotus.domino.Session;
import lotus.domino.Database;
import lotus.domino.DocumentCollection;
import lotus.domino.NotesFactory;
import lotus.domino.NotesThread;
public class Main {
public static void main(String[] args) {
NotesThread.sinitThread();
Session s = NotesFactory.createSession();
System.out.println("Name: " + s.getUserName());
Database db = s.getDatabase("server1/Example", "names.nsf");
DocumentCollection dc = db.getAllDocuments();
System.out.println("Docs: " + dc.getCount());
} catch (Throwable t) {
t.printStackTrace();
} finally {
NotesThread.stermThread();
}
}
}
The code will compile fine but when you run it you’ll see a message like the following (plus a stacktrace):
java.lang.UnsatisfiedLinkError: C:Notes8nlsxbe.dll: Can't load IA 32-bit .dll on a AMD 64-bit platform
The problem is, as the message explains, that you cannot load a 32 bit DLL (remember Notes is a 32 bit application) into a 64 bit Java Virtual Machine (JVM). The solution is to install a 32 bit JDK instead and run the application using this JDK. Remember that it is perfectly valid and possible to install multiple JDK’s on a single machine and it fact that’s what I’m doing.
Developing plugins for Notes 8+ on 64 bit Windows is also somewhat different from doing it on a 32 bit Windows system. Of course you need Eclipse but here’s the first difference – you need to use a 64 bit version of Eclipse if you’re using a 64 bit JDK. The reason is that Eclipse uses SWT (Standard Widget Toolkit) for the user interface widgets. The reason SWT looks so nice on any supported platform is because it wraps the native, C-code, platform widgets. So remember that and grab a 64 bit Eclipse. Once that’s installed and working with your 64 bit JDK configure Eclipse as you normally would but with a small difference that will cause your code not to compile (my Eclipse complained about not be able to resolve org.eclipse.swt.widgets.Shell).
As you may know, you specify the bundles you depend on when developing your plugin and in turn you also specify which environment you run in. This is how Eclipse knows which versions to the bundles to put on the class path but since you’re running 64 bit Windows and Notes is 32 bits it will be a problem. The fix is however very easy to implement and only means tweaking the target platform setup to explicitly set the architecture you’re running on to “x86” and not “x86_64” which is the default if you’re on a 64 bit JVM. Where to set this differs a little between Eclipse 3.4 and Eclipse 3.5 but the concept is the same.
Once this is done the workspace will be rebuilt and everything should work just fine. Mine did anyway… 🙂
If you need to run a Java application that accesses Notes locally from within an Eclipse instance (lets face it – who writes Java code without an IDE these days?) you also need to use a 32 bit JVM although you very well may be running 64 bit Eclipse in a 64 bit JVM. The JVM used to execute an application from within Eclipse is the JVM you setup in the build path. To set it simply right-click the project, choose Build Path -< Configure Build Path… and replace/edit the JVM library used.
I hope the above is clear – if not let me know using the comment system. I’ll soon be blogging about using Eclipse 3.5 for your Eclipse development instead of the current version 3.4. Stay tuned.
Part of my new LotusScript.doc release is of course finding ways to make it even easier to use and use the API that’s now supplied as part of LotusScript.doc. Central to all this is extending DDE to make LotusScript.doc accessible in a variety of ways. Today I’ll show you how to add context, i.e. right-click, menus to the DDE navigator on the left as you can see below.
Doing this is actually very easy and only comprises of an IViewActionDelegate (the code; implement org.eclipse.ui.IViewActionDelegate) and a entry in plugin.xml to indicate where to stick the action. In this case it’s an objectContribution to org.eclipse.ui.popupMenus:
<extension point="org.eclipse.ui.popupMenus">
<objectContribution adaptable="true"
id="com.lekkimworld.dde.navctxmenu.objectContribution"
objectClass="org.eclipse.core.resources.IFile">
<action
class="com.lekkimworld.dde.navctxmenu.MyContextAction"
enablesFor="2+"
id="com.lekkimworld.dde.navctxmenu.action"
label="DDE context stuff (select min. 2 design elements)"
menubarPath="additions"
style="push">
</action>
</objectContribution>
</extension>
The above should be pretty much self-explanatory.
The example code is available for download as an Eclipse project: com.lekkimworld.dde.navctxmenu.zip
2009 is drawing to a close and in less than 10 hours I’ll be in my tuxedo and drinking champagne. What a year from a personal and a professional perspective.
On the personal front the highlight of 2009, by far, was on 22 August where I got married to my lovely wife. 4 months into our marriage we’re having a blast. Not much have changed in our relationship which I take as a good thing. I’m looking forward to January and once again bringing her along for Lotusphere. I think she’s growing used to staying in the Swan and the fact that return guests get some good deals at the spa… 🙂 Apparently some sun and warm weather (crossing my fingers) in January doesn’t hurt either.
On the professional front it’s been a year of both many changes and new challenges. As previously the year really got kicked of at Lotusphere and it was very nice seeing all of my “collegues” again and hooking up. I’ll remember BALD, being part of the blogger program in those yellow bean bags, frost in Florida in January and the associated state-wide “panic”, giving a session with good reviews though having a high fever and missing 1,5 days due to sickness as the highlights of my Lotusphere 2009. Of couse being in the US for the inauguration also made it special. Being “on location” in Florida bar for Superbowl was also a very nice experience.
The rest of the year has been filled with a lot of consulting on Notes and Domino, Lotus Connections and other related Lotus products. It’s been very nice being able to share experience and consult on a wide variety of subjects. 2009 was also the year where I started doing a lot of teaching and we started doing Notes 8.5 Application Development workshops. I’ve been giving the workshop a number of times across Denmark during 2009 and it has always been a good experience. Of course some workshops has been better than others but I have always felt that I’ve given the attendees what they signed up for and all attendees have gone home amazed at the potential of the new Notes releases. If only more would take the time to learn Java – that’s still the Achilles Heel of IBM Lotus…
Towards the end of 2009 I have also assumed the day to day management of some of the developers in the company. It’s been a big change from billing out 40-50 hours a week to mostly managing and planning. It’s also meant spending far more hours in the office which has been weird. I set a personal record this winter by having lunch in the office 12 days in a row. That’s a first in my 2+ years at IntraVision. The change of role has been fun but also a big change and challenge and something that I’m finding myself enjoying very much. I’m looking forward to the new year and getting more into that role.
In 2009 I have also enjoyed still being part of the Design Partner programme with IBM. It’s fun, educational and inspiring to be part of these conference calls and getting the inside story. The calls are something I look forward to attending and the debate is good and lively. Of course it’s also frustrating sometimes when IBM Lotus do something that we design partners just don’t get but that’s part of the deal. All in all I still find it very positive that IBM Lotus listens and lotusknows it makes a difference! 🙂
On the whole lotusknows thing I find it very positive that IBM Lotus finally got the message and starting being offensive. We still haven’t seen much, if any, of it here in Denmark but hopefully it’s coming at some point. There’s still a big need for air cover.
In November this blog turned 5 years and it was a milestone that were reached. As I wrote on that day, this blog is something I cannot imagine not having today. The blog and way it connects me with the community is amazing. Of course more and more communication moves from blogs to Twitter these days but it’s all good.
2009 was also the year where I finally got to finish LotusScript.doc version 2. It’s been a long time coming and it was very nice finally to get the new version out there. Expect interesting stuff to be coming your way in 2009 when I start leveraging the LotusScript.doc Java API in other contexts.
In three months TwitNotes turns 2 years – wow! Has it already been that long? Besides, of course, being my Twitter client of choice it has also served as a very good example in all of my speaking gigs as one of those new applications that are possible in the “new” Notes client. TwitNotes is an application that builds on the Notes foundation but reads and writes data in the cloud. Showing it as an example always raises some eyebrows until people “get it”. I used it as an example for the big IBM Software Day event here in Denmark this fall.
As 2009 draws to a close I’m doing another sidebar application that I hope will be useful for many of you out there although I’m mainly doing it for myself to increase my productivity. I hope to be able to reveal it by Lotusphere. It’s again a cloud-based application that integrates into the Notes experience to showcase just what’s possible with the “new” platform. Stay tuned…
Before I write too much I’ll wrap it up by wishing you all a very happy new year – see you on the other side. For those of you going to Lotusphere – see you there!
Bye, bye 2009…
If you don’t want to show the Gettting Started page for new client installations you may set the following property using plugin_customization.ini or using policies:
com.ibm.rcp.jfaceex/overrideAutoStart=
com.ibm.rcp.gettingstarted.GettingstartPerspective