Java in Notes/Domino Explained: The story on recycle()

As with everything what you see is typically only the tip of the iceberg. This is also true for the Java objects for Notes/Domino since they are only thin wrappers around the underlying, more heavyweight, C++ objects. Since the Java garbage collector has no knowledge of this, all classes in the Notes/Domino API inherit a method called recycle() from the lotus.domino.Base class. The purpose of this method is to explictly tell the C++ object to free any memory it is using. A part from freeing its own memory, the object will also call recycle() on any object that it created. This means that calling recycle() on a database object will also recycle() a view object obtained opened through it.

If you do not realize that calling recycle() will cascade down through the object hierarchy like this you’re going to experience some “interesting” exceptions and unexpected behaviour at runtime.

It is important to note that the only reason for calling recycle() is to release memory while the agent (or other Java program) is running.

If your agent only does a small piece of work it’s probably not worth the effort of calling recycle() since people normally get into a lot more trouble calling recycle() than what they actually accomplish. My recommendation is to recycle document objects when you loop a document collection or view and otherwise not spend time thinking of recycle() unless you start experiencing java.lang.OutOfMemoryError errors.

To recycle() documents while looping a document collection or view you can use a loop-construct like the one below:

DocumentCollection dc = agentContext.getUnprocessedDocuments();
Document doc = dc.getFirstDocument();
Document docTemp = null;
while (null != doc) {
   // do stuff with the document

   // get next document into docTemp
   docTemp = dc.getNextDocument(doc);

   // recycle doc

   // transfer reference to keep loop going
   doc = docTemp;

Update: As mentioned on this comment recycling is more important in servlets than in agents. When I post on servlets I’ll give some more pointers.

2 thoughts on “Java in Notes/Domino Explained: The story on recycle()”

  1. From Designer help:

    If you create more than one object to represent the same Domino element, recycling one recycles all. For example:

    View v1 = db.getView(“All”);
    View v2 = db.getView(“All”);

    v1.recycle(); // also recycles v2

    If I set v1 to null, there is no issue, v2 continues to work since it’s only the java object thats marked for garbage collection. However calling recycle() on v1 destroys the C++ object, the only one that was possibly created for both v1 and v2.


  2. Lotus Notes/Domino R6 claims to have solved the recycle problem: It has an internal Map of weak references to potentially allow automatic recycling as soon as a Notes object is not referenced anymore. But this still depends on how often and fast the garbage collector is running. So even with R6 you can run out of handles if you are e.g. instantiating tens of thousands of ViewEntries.
    With domingo (you might have read about), this problem is truly solved. Your loop would not need any explicit recycle anymore (and looks much more like Java than Notes):

    DView view = db.getView("MyView");
    Iterator i = view.getAllDocuments();
    while (i.hasNext()) {
        DDocument doc = (DDocument);
       // do stuff with the document


Comments are closed.