Subject: Release notes for recycle() methods [Comment]
recycle() methods for Notes back end classes [Notes 4.6.1]
Keywords: recycle; Java; back end classes; programmability; memory management; out of memory
When using the Notes 4.6 Java classes in an agent with a large number of objects, sometimes the program runs out of memory. This is due to the inability of the Java Garbage Collector to recover Notes objects. To recover the used memory, Lotus has introduced recycle() methods on all back end object classes with the exception of Session. If you are running into an out of memory situation, recycle objects as they go out of scope, particularly in situations where you are looping through a DocumentCollection pulling information out of documents, or creating new documents. When you are sure that a document is no longer needed, call mydoc.recycle() to recover the memory for the document "mydoc" and its child Items. Since the Domino server conserves resources by reusing its objects whenever possible, this is primarily useful in single threaded agents and applications. However, there are some situations which are useful in a multithreaded environment noted below.
Guidelines for usage:
There is no need to recycle any objects if you are not having memory problems. Many Java agents run fine.
Be absolutely sure that neither the object nor any of its children are accessed after recycling.
Recycle objects only where they are created. You should be able to easily see in the source code where an object is created and where it is recycled. Do not attempt to recycle objects on a different thread,
Recycling a parent implicitly recycles its children.
Look for loops that enumerate Documents in a ollection as good opportunities to recycle objects.
Do not recycle objects that you have not created - for example do not attempt to recycle the objects that you have obtained from the Agent Context, such as the database you get by calling the CurrentDatabase() method.
For any agent even when you need recycle for some things you don't ever need to recycle these two things:
In a multithreaded Java application or agent, it is safe to recycle a database and/or its child objects only if the database is accessed on a single thread. This is because the recycle method directly destroys the heavyweight Back End objects which may be shared among threads, leaving other threads vulnerable to null pointer exceptions..
To these notes, I would add that resources available to Java agents for the 4.61 have been greatly increased, so many agents which could not run in 4.6 will execute unmodified in 4.61.
A caveat on point #1.- as written, this guideline applies to Client or Server based Java agents or apps. However, if your Java agent is to be run as a Web agent under Domino with the Notes.ini flag DOMINOASYNCHRONIZEAGENTS set , the recycle methods should be used whenever possible to minimize the working set of the agent, which shares resources with
other running agents. To elaborate, consider a scenario where several databases are successively accessed to enumerate collections of documents. If none of the collections are very large, one could simply recycle each database at the end of the collection enumeration. But in the Web server case it is better to recycle individual child objects (e..g.
documents) as soon as they become available rather than to recycle the parent database at the end of a collection enumeration (which would implicitly recycle the documents). The objective here, again, is to keep the agent footprint as small as possible in a Web agent situation.
Remember that all resources are automatically ecovered at the end of the agent or application. The recycle() method does not fix a leak, but behaves more like a garbage collector during execution.