Ben Poole

Some useful Domino Java code?

I am told that this could be useful to other newb Java Domino coders. Basically, it’s a wee chunk of code to drop into a Domino Java agent, which sets out a recommended approach for document looping and the whole recycle() thing. I don’t know if it’s utterly correct, and I really don’t want to get into the innards of the Domino JVM—Bob is doing sterling work there—but It Works For Me.

 // Here we iterate documents in a view
 try
 {
 Document doc = view.getFirstDocument();
 Document docTmp = null;
 
 while (null != doc)
 {
 // Your doc processing code here
 
 docTmp = view.getNextDocument(doc);
 
 doc.save(); // assuming changes
 doc.recycle();
 doc = docTmp;
 }
 
 /*
 * Could do this in 'finally' if you like,
 * but you need to declare objects
 * outside the try... catch in that case
 */
 if (null != doc) doc.recycle();
 if (null != docTmp) docTmp.recycle();
 if (null != session) session.recycle();
 }
 catch (NotesException e)
 {
 // TODO error handling
 }
 finally
 {
 try
 {
 view.recycle();
 db.recycle();
 }
 catch (NotesException n)
 {
 // Don't care
 }
 } 

Hope this is useful for someone. Feel free to comment away and improve!

Posted at 03:39 PDT on 12 Jun 2009  |  Categories:   |   (11 comments)

Comments

1. Seem to remember its not a good idea to recycle the session within a java agent. But my brains not good enough to remember the hell why (aside from the fact the agent will do that anyway - so maybe thats the reason) :)
   on 12 Jun 2009 by Steve Castledine (#)
2. Steve: it won’t break anything, but similarly it’s possible overkill. My understanding used to be that you only recycle objects that your code explicitly “creates”, e.g. Database, Document, View, etc. In other words, you leave Session and AgentContext alone.
   
   But then IBM directly contradict this in their own support documentation. So all I know now is that the code above works, and doesn’t leak. Which for Domino Java is the main deal
   
   The moral of this story is that Java in Domino is overlooked and poorly-documented. If it weren’t for the likes of Mikkel, Julian and Bob, we’d be in a very poor position.
   on 12 Jun 2009 by Ben Poole (#)
3. Further reading!
   
   http://www-01.ibm.com/support/docview.wss?rs=203&uid=swg21097861
   
   http://www.nsftools.com/blog/blog-02-2004.htm#02-20-04
   on 12 Jun 2009 by Ben Poole (#)
4. Ben, this looks pretty good and probably a good code snip for new java developers working in Domino.
   One small point, I would set my docTmp first off in the view. That way if something just happens to go wrong in the processing code, you've already got your handle to the next guy.
   I would remove the unnecessary session recycle and move the view recycle up in it's place. This assumes of course that you are down with the view after looping through its docs.
   on 12 Jun 2009 by Mac Guidera (#)
5. * I would set my docTmp first off in the LOOP.
   on 12 Jun 2009 by Mac Guidera (#)
6. You should only have to recycle what your code creates.
   
   Personally I would go with a view entry as well. That way you can do a check on the columns and if it is a document to be edited then pull the document. Speeds everything up and saves memory.
   
   Also move those recycles to the finally block. In the event something goes wrong then that code will execute and clean up memory. Stops the server from crashing from locked up JNI/LSXBE references.
   on 12 Jun 2009 by Simon O'Doherty (#)
7. We used to have a similar piece of code. It ran fine on most views but would abend on some views. It took longer than it should have to figure out the cause but we eventually got there. The problem was when the same doc appeared back to back in the view. This could happen in a categorized view with the document in consecutive categories. I think that you can see the same behavior if you set a view column to show multiple values as separate lines in the view.
   
   The fix was to check to make sure that doc and docTmp were not the same document before doing the doc.recycle(). If that next document (docTmp) is the same as your current document (doc) you don't want to do the recycle. If you do then as soon as you access doc on the next run through the loop you'll be accessing a recycled document which will make for a sad java program.
   
   Hope my explanation makes sense.
   on 12 Jun 2009 by Jamie Moore (#)
8. Great comments, thanks! Simon: I often use ViewEntry objects as you’re quite correct, skimming an index is often more efficient. You have to be mindful of the underlying Document object too.
   
   I tend to do most if not all recycle() calls in the finally block, but sometimes it makes sense to move them elsewhere.
   
   With regards recycling the session and AgentContext interfaces, see the NSFTools link in my earlier comment. Whilst I don’t think there is a need to recycle sessions, I’ve seen enough weird behaviour (in Domino 7) to wonder—and IBM themselves state that all objects / interfaces should be recycled. So there you go.
   
   More tips here: http://benpoole.com/wiki/Pages/DominoJava
   
   Jamie: noted. This example is for simple flat views, and as you rightly point out, you can get some head-scratching moments in views which feature the same document multiple times if you’re not careful. Along the same lines, be mindful processing documents in such a way that your changes alter the document’s state with regards view selection.
   on 12 Jun 2009 by Ben Poole (#)
9. Nice job, Ben! (and thanks for the link!)
   Only thing I would add is:
   view.setAutoUpdate(false);
   
   It's optional, but if you don't, you sometimes get odd results, especially if others are modifying the view contents.
   
   Regarding Session.recycle() - you should never do that in an agent (though I think Notes is smart enough to ignore it in that situation). As was said above, only recycle stuff you actually create. Same goes for the "current" db, don't recycle() it.
   
   on 12 Jun 2009 by Bob Balaban (#)
10. Wotcha Bob! You touch upon my last comment above. Specifically, in a current project I loop stacks of documents for processing by a web service client framework, and view.setAutoUpdate(false); is a must. Once processed, the docs fall out of the view in question, and if that flag wasn’t set, well we’d have a lot of duplicate processing going on.
    
    A definitive set of rules / best practices for Domino Java would be really useful I reckon, especially where Java diverges somewhat from received best practice in Lotusscript (for example).
    on 12 Jun 2009 by Ben Poole (#)
11. @Bob: isn't setAutoupdate = false blocking other agents that want to read the same view?
    on 14 Jun 2009 by Stephan Wissel (#)

Ben on twitter