Nice Notes 8.5.2 feature – upgrading multiple local databases to a new ODS

Please note: The following is from the release notes of Notes 8.5.2 so I don’t take credit for writing this. Lotus Notes 8.5.2 is in beta and there are no guarantees that the features described here will be in the final product that IBM ships.

In the latest code drop of Notes 8.5.2, using either the Notes Client, Domino Administrator Client, or Domino Designer Client, a customer can force the client to perform ODS upgrades of all local databases. For most non-essential databases, the ODS upgrade will take place in a background process and while a database is upgraded, the end user will not be able to use the database. For essential databases that are in use at the point that an upgrade is attempted, the ODS upgrade will be done at the next first time open which will typically occur at client restart.

Configuration Options – Required

The following new NOTES.INI setting performs the upgrade:

NSF_UpdateODS=1

With this set, the client will do a one time pass to upgrade local databases using the compact task.

Configuration Options – Optional

In addition, the specific ODS level that is desired should be set (if none set, ODS51 will be forced):

To create ODS 51 databases:
Create_R85_Databases=1

To create ODS 48 databases:
Create_R8_Databases=1

User Feedback

For databases compacted in the background, there will not be any user visible indication that the database compacts are in progress. If a user attempts to use a database while the compact is in progress, they will see the error:

"Database is being Compacted; Compact must finish before use"

For databases that are in use at the time the compact is attempted (names.nsf, cache.ndk, log.nsf, and possibly user mail files), the compact will occur at the next client restart. When the database is compacted at restart, progress will be shown in the splash screen or in the status bar, depending on when the database is opened.

For each database that is compacted, a “Compacting…” and “Compacted….” will appear in the log.

11/12/2009 03:01:49 PM  Compacting dummy.nsf (dummy),  -r -C
11/12/2009 03:01:52 PM  Compacted  dummy.nsf, 0K bytes recovered (0%)

For each database that is at the desired ODS (or later), only “Compacting…” will appear in the log

11/12/2009 03:01:49 PM  Compacting dummy.nsf (dummy),  -r -C

At the end of the upgrade, the following will appear in the log:

10 databases had an older NSF ODS version. 8 of
those databases were successfully upgraded to a
later NSF ODS.

Book keeping Options

NSF_UpdatedToODS=#

After the upgrade is attempted for all local databases, this will be set to the ODS level that was requested. Deleting this setting will cause the code to attempt to perform upgrades. If upgrades are not necessary, the database will be skipped. If the client is shut down before all databases are completed and processed, then this is not set, and the next retry will attempt compacts on databases that are not at the desired ODS.

Clarifications/Not in scope

If there is an error during the compact, the database ODS will not be changed. There will not be any retry logic. If there is not enough space, which can be one of the errors, then the database ODS will not be changed. If a database takes a while to compact then the user does not have access to that Db during the compact. For always in use databases, their compact will be done on the next client restart, and will block user usage.

Limitations

Only Windows and Linux are supported. Macintosh support will be available in a later code drop.

Configure Eclipse 3.5 for Notes 8.5.2

As for previous versions I maintain a document outlining how to configure a vanilla Eclipse install to work with Lotus Notes for Java extension development (with install_id and rcp.base). I have made the first version for Notes 8.5.2 as of code drop 5 so please see Configure Eclipse 3.5 for Notes 8.5.2 if this is of use to you.

Please Lotus that Notes 8.5.2 is in beta and there are no guarantees that the features described here will be in the final product that IBM ships.

Notes 8.5.2 – preload on startup

Disclaimer: Lotus Notes 8.5.2 is in beta and there are no guarantees that the features described here will be in the final product that IBM ships.

Being part of the design partner program for Lotus Notes 8.5.2 I just received code drop 5 i.e. the latest beta of Lotus Notes 8.5.2. Part of this release you are asked a new question while installing which is whether you want to enable preloading Lotus Notes when starting Windows (don’t know if this goes for other platforms).

Now I’m on a SSD drive so my experience may be different from others on a “normal” spinning drive but it will be interesting to see how it performs and if it makes a noticeable difference.

Complete guide to manually uninstalling “plugins” from Lotus Notes

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:

  1. Eclipse plugin(s)
    The plugin is where the actual code and functionality is stored together with additional resources such as images, string translation etc.
  2. Eclipse feature
    The feature is what’s actually installed from a Lotus Notes perspective. The feature points to the Eclipse plugins that provides the actual functionality. It’s almso important to note that a single feature may reference multiple plugins.

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:

  1. Close Lotus Notes
  2. Open the “features”-directory (<Notes data dir>workspaceapplicationseclipsefeatures)
  3. Locate the Eclipse features to uninstall.
  4. For each Eclipse feature you need to open it and edit the feature.xml file. Locate the <plugin>-tags and fine the names of the referenced plugins. Note that there might be more than one. Combining the plugin id and the plugin version will give the full filename of the plugin (<plugin id>_<plugin version>.jar).
  5. Delete the Eclipse features you’re uninstalling.
  6. Open the “plugins”-directory (<Notes data dir>workspaceapplicationseclipseplugins).
  7. Delete the plugin JAR-file(s) you recorded in the step above.
  8. Open the directory containing the platform.xml file (<Notes data dir>workspace.configorg.eclipse.update).
  9. Edit platform.xml and go to the end of the file.
  10. Remove each entry you see for the features you deleted in the step above.
  11. Save and close the file.
  12. Since Lotus Notes also keeps a record of which Java extensions to load it’s best to start Notes with some parameters to make it recompute the Java extension registry: notes.exe -RPARAMS -clean

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.

Developing Java plugins and applications for Notes on 64 bit

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.

Notes is a 32 bit application

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+

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.

  1. Open the target platform setup
  2. Edit the “Environment” settings
  3. Set the architecture to “x86”

Once this is done the workspace will be rebuilt and everything should work just fine. Mine did anyway… 🙂

Back to our standalone Java application

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.

Conclusion

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.