Java in Notes/Domino Explained: NotesException


The documentation on NotesException is a little scarse but basically it’s simply an exception like all the others and it inherits from java.lang.Exception via org.omg.CORBA.UserException. It inherits from org.omg.CORBA.UserException since it needs to be throwable when using remote sessions. NotesException has three constructors for you:

  • NotesException()
  • NotesException(int code, String message)
  • NotesException(int code, String message, Throwable t)

The second and third ones has an integer and a string argument which is the error code and error message as you know them from the LotusScript Error statement. The third argument of the third constructor is for throwing nested exceptions. Anyways – you can throw NotesException as you do with any exception using throw new:

try {
   ...do some stuff
} catch (NotesException e) {
   // throw new NotesException();
   // throw new NotesException(99999, "My own error code...");
   // throw new NotesException(99999, "My own error code...", e);
}

What is a little strange though is that the actual error codes for the NotesExceptions throws cannot be found in the NotesException class but is found in the lotus.domino.NotesError class. This means that if you like to test for “human understandable” error codes (e.g. NOTES_ERR_INVALID_DATE) instead of the actual error code (e.g. 4045) you need to use the constants in the NotesError interface since there isn’t a way to include the error codes like you do in LotusScript unless you implement the interface.

I would consider it bad form to implement the NotesError interface simply to get the error codes. Either use it as a static constant or, if using Java 5 outside of Notes/Domino, use static imports.

As a rule of thumb I would recommend that you do not use lotus.domino.NotesException for your own program code but rather use custom exception classes (by extending java.lang.Exception) or use standard exception classes from the JVM as you see fit. That’s how I do it anyways…

More sessions on blogging @ Lotusphere 2007

I have been thinking about the sessions on blogging at last years Lotusphere now as we are nearing the submission deadline for sessions for Lotusphere 2007. At Lotusphere 2006 we had two sessions on blogging:

The first one was a panel discussion on the more general aspects on blogging and how blogging can and will affect the enterprise. The latter was a Birds of a Feather and a relaxed discussion on blogging in general and was in essence a blogger meet-up. I only attended the latter session and my main reason for doing so was to meet my fellow bloggers however it seemed to me that there wasn’t enough time.

That got me thinking – should we have more than one BoF-style session on blogging or maybe simply a longer session? Maybe additional sessions or longer sessions should be held outside of the “official” Lotusphere conference since I guess there is a limit to how many sessions on blogging IBM will allow at Lotusphere. Considering the discussions that has been taking place in last few weeks in the blogosphere it could be that some face-to-face time would be nice and a chance to pick up some of the discussions (i.e. the nifty-fifty).

What do you think? If we need additional sessions, at least inside the scope of Lotusphere, we need to submit abstracts ASAP!

Reverse engineering the Sametime 7.5 business card servlet


Reading in chapter 9 of the Sametime Administration PDF I learned of the UserInfoServlet configured through the UserInfoConfig.xml document in the Domino directory (in the filesystem mind you) on the Sametime 7.5 server. In this post I will not go into the different configuration files but simply describe how the UserInfoServlet works, which parameters it takes and what it returns. You can use this, as I did, for troubleshooting.

Please note: All the information in this post was reverse engineered so use it and treat it accordingly.

Just to get it out of the way. The reason why my initial configuration didn’t work was that the Sametime client contacted a hostname that wasn’t configured in the Internet Sites view in the Domino Directory (I guess it resolved the ip address or hostname wrongly in some way). Anyways – the way to configure the phote part of the business card is perfectly descriped on Grant Binghams blog and in the Sametime 7.5 Administration PDF.

The UserInfoServlet

It appears that the servlet takes 4 arguments:

  • operation (valid values are: 1, 2, 3)
  • userid (the username of the user as listed in the ($Users) view)
  • setid (valid values are the configured blackbox sets; usually 0 and 1)
  • field?? (with ?? being a an incremental number starting a 1)

The operation parameter is the main parameter that controls what the servlet tries to do and what other parameters are required. See below for a description of each operation.

operation=1

This operation is used to get value for specific fields based on the name of the field the Sametime client uses. You can request information from more than one field at a time. The valid names of the fields are the ones from UserInfoConfig.xml and hence the field names shown when you use the operation=2 parameter.

URL syntax: http://hostname/servlet/UserInfoServlet?operation=1&field1=<field name>&userid=<username>

Example URL: http://hostname/servlet/UserInfoServlet?operation=1&field1=Name&field2=Title&userid=jdoe

<?xml version="1.0" encoding="UTF-8"?>
<userinfo>
   <user id ="lekkim">
      <field name="Name" type="text/plain">John Doe</field>
      <field name="Title" type="text/plain">Marketing Manager</field>
   </user>
</userinfo>

operation=2

This operation gives you a list of the fields configured for the required field set. If you leave out the optional setid-parameter a value of 0 will be implied.

URL syntax: http://hostname/servlet/UserInfoServlet?operation=2&setid=<set id>

Example URL: http://hostname/servlet/UserInfoServlet?operation=2&setid=0

<?xml version="1.0" encoding="UTF-8"?>
<userinfo>
   <field name="MailAddress" type="text/plain" />
   <field name="Telephone" type="text/plain" />
   <field name="Company" type="text/plain" />
   <field name="Title" type="text/plain" />
   <field name="Name" type="text/plain" />
   <field name="Photo" type="image/jpeg" />
   <field name="Location" type="text/plain" />
</userinfo>

Example URL: http://hostname/servlet/UserInfoServlet?operation=2&setid=1

<?xml version="1.0" encoding="UTF-8"?>
<userinfo>
   <field name="Photo" type="image/jpeg" />
   <field name="Name" type="text/plain" />
   <field name="Title" type="text/plain" />
   <field name="MailAddress" type="text/plain" />
   <field name="Telephone" type="text/plain" />
</userinfo>

operation=3

This operation is the workhorse of the servlet and the one that the Sametime client calls. This operation returns, as the others do, a XML document containing the business card of the requested user. The photo data is base64 encoded and the type attribute indicates whether it is a jpeg or a gif image.

URL syntax: http://hostname/servlet/UserInfoServlet?operation=3&userid=<username>

Example URL: http://hostname/servlet/UserInfoServlet?operation=3&userid=jdoe

<?xml version="1.0" encoding="UTF-8"?>
   <userinfo>
      <user id="John Doe/Acme">
         <field name="MailAddress" type="text/plain">jdoe@example.com</field>
         <field name="Telephone" type="text/plain">555-9921</field>
         <field name="Company" type="text/plain">Acme Corp.</field>
         <field name="Title" type="" error="UNAVAILABLE"/>
         <field name="Name" type="text/plain">John Doe</field>
         <field name="Photo" type="image/gif">R0lGODlhoQCjAOf==</field>
         <field name="Location" type="" error="UNAVAILABLE"/>
      </user>
   </userinfo>

Multiple communities in Sametime 7.5

How nice is this! Now that we are running Sametime 7.5 internally I have configured an additional Sametime community by following the guidelines from Chris Pipin. This means that I now have my uncle from IBM in Denmark in my Sametime client as well. Nice! Only caveat is that you cannot lookup the address of the contact using the “Lookup…” button as you would expect. You have to simply enter the address, check “External address” and click the “Add” button.

There was a caveat for him to add me as well. My IBM id is “lekkim” but he has to append “@dk.ibm.ext” to the IBM id in order for him to find me.

Does anyone know it this means that bloggers can IM each other using the IBM Sametime community? I’m up for the test so feel free to try and add me (lekkim@dk.ibm.ext) to your Sametime client.

Happy IM’ing!!

developerWorks: The Java XML Validation API

"Validation reports whether a document adheres to the rules specified by the schema. Different parsers and tools support different schema languages such as DTDs, the W3C XML Schema Language, RELAX NG, and Schematron. Java 5™ adds a uniform validation Application Programming Interface (API) that can compare documents to schemas written in these and other languages. Learn about this XML validation API."

The Java XML Validation API

Sametime server upgraded to 7.5

Well I took the plunge and upgraded our internal Sametime 3.1 server to Sametime 7.5 and it was almost a dissapointing experience. Not a single issue. Not one… It was super easy – click, click, click and the server was upgraded without any problems – all users retain their buddylists and some hasn’t even noticed the upgrade. Only a few users have had the new client installed but we will be rolling the client out soon as well.

Although it was a very pleasant experience I did notice two things:

  • When running the UI in Danish the “Paste” command in the Edit-menu is incorrectly translated to “Klistre”. The Danish translation in other programs is “Sæt ind”.
  • If attempting a file transfer of a file that exceeds the maximum filesize set in the policy, the filesizes are shown in bytes and not in megebytes as one would expect (see image below).

Apart from that – Happy Sametime Friday!! 🙂