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
Document doc = view.getFirstDocument();
Document docTmp = null;

while (null != doc)
// Your doc processing code here

docTmp = view.getNextDocument(doc);; // assuming changes
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
catch (NotesException n)
// Don't care

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


  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) :)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.Ben Poole#
  3. Further reading! 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.Mac Guidera#
  5. * I would set my docTmp first off in the LOOP.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. 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.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:

    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.Ben Poole#
  9. Nice job, Ben! (and thanks for the link!)
    Only thing I would add is:

    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.
    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).Ben Poole#
  11. @Bob: isn't setAutoupdate = false blocking other agents that want to read the same view?Stephan Wissel#
  12. Quick question, hope it's not too late…

    From Technote #1097861 ​:
    "When using objects in an agent, all objects (both Java and C++) are destroyed when the agent ends. When using servlets, .jsp's, or standalone applications, recycle must be used since Domino will never clean up these backend objects."

    When using Java Web Service Providers, do they behave exactly like agents? (all Java and C++ objects are destroyed when the Web Service ends, so no need to recycle if it's a simple Web Service with no loop).

    Or do they behave more like Servlets where I should recycle everything manually?

    Thanks!S. Macgowan#
  13. Good question! As far as the NSF is concerned, web service notes are agents with a different flag set on the note.

    Whilst XPages and servlets in Domino both run in their own servlet engines, web service providers and agents don’t (whether Java-based or not). So I would say that the same rules apply for both agents and web service design elements.Ben Poole#
  14. That's what I think too… but I was never able to find a clear answer regarding web services.

    Often discussions about recycle are old and talks about R4/R5/R6/R7.

    I was wondering if some things have changed in 8.5 for agents… and also how web services behave.

    I posted my question here a while ago:

    Again, I agree with you (and others) that web services should behave like agents… but I haven't yet found a confirmation or official documentation from IBM.

    Thanks!S. Macgowan#

Comments on this post are now closed.


I’m a software architect / developer / general IT wrangler specialising in web, mobile web and middleware using things like node.js, Java, C#, PHP, HTML5 and more.

Best described as a simpleton, but kindly. You can read more here.