This problem and solution were found by my esteemed colleague Andrew "Andy C” Cunliffe.

The problem

In Lotus Notes 8.5 java agents that worked fine in past versions was causing server crashes. Specifically when working with richtextitem class in a java agent. 

The code being effectively this (taken from the help)

import lotus.domino.*;

public class JavaAgent extends AgentBase {

 public void NotesMain() {

 try {
 Session session = getSession();
 AgentContext agentContext = session.getAgentContext();

 // (Your code goes here)

 DocumentCollection dc = agentContext.getUnprocessedDocuments();
 Document doc = dc.getFirstDocument();
 RichTextItem rti = (RichTextItem)doc.getFirstItem("Body");
 RichTextNavigator rtnav = rti.createNavigator;
 rtnav.findFirstElement(RichTextItem.RTELEM_TYPE_TEXTPARAGRAPH);
 rti.beginInsert(rtnav);
 rti.appendText("Beginning text.");
 rti.addNewLine(1);
 rti.endInsert();
 doc.save(true,true);
 } catch(Exception e) {
 e.printStackTrace();
 }
}

(Quite distressing that the actual example given in the help causes a server crash.)

Investigation

Andy, was able to find that the command beginInsert was causing the crash. This command has been recently changed it now accepts an optional Boolean argument that works as below.
·    true to put the insertion position at the end of the element 
·    false (default) to put the insertion position at the beginning of the element 
Now this is the sticking point, in previous notes versions there was no option and the behaviour of the beginInsert command was to put the insertion point at the end of the element. 

So you can see they have changed the behaviour of the command having the new function be the default and the original function be the alternative function. This was further exasperated by the realisation that the setting of the optional argument to true (i.e. to pick the original function) stops the server crashing.

The Solution

So to conclude the solution to this problem is to change the beginInsert command from

rti.beginInsert(rtnav); to  rti.beginInsert(rtnav , true);

I can only think that the new "insertion position at the beginning of the element” is massively resource hungry or not properly garbage collected. Our more high spec servers were able to survive this code. While the server in question could only run the code in "insertion position at the end of the element” mode.

Mega busy, so been unable to get to grips with promised blog posts. 

From discussion with others recently it became clear that we really should log lotus notes bugs. Not with IBM source of the infamous "We are aware of this problem. There are no plans currently to deal with this problem.” Somewhere that updates and workarounds can be added. In short here.

I'll try to be as objective as possible, and swear to let my blood cool before posting any.

First up, for no other reason than I came across it (again) most recently is....

The fact that you can not show a newly created document in a frame. (or editDocument ,setFrame and new notesdocument error.)

A little background to this error is that it has been present since release 5 and is still present in 8.5.

In essence the following code will not work.

Dim ws as new notesuiworkspace

call ws.setTargetFrame("NotesView”)

dim session as new notessession

dim doc as notesdocument

set doc = session.currentDatabase.createDocument
doc.form = "myForm”
doc.field1 = "1”


call ws.editDocument(false,doc)

Now it doesn't throw an error as it is valid code. It just doesn't work. Many people will ask why not use the compose method. Firstly why should we have to when this command should work (and does if we don't target a frame.) Secondly as you can see we are trying to pre-fill some fields with data (in this case field1).

Several workarounds exist:

1.use NotesUiWorkspace method compose. Get a handle to the compsed uidoc set any fields you need using uidoc methods than call a refresh of the uidoc. i.e.

Dim ws As New NotesUIWorkspace     Call ws.SetTargetFrame("NotesView")     Dim uidoc As NotesUIDocument     Set uidoc =  ws.ComposeDocument("","","myForm")            Call uidoc.Document.ReplaceItemValue("field1","1")     Call uidoc.Refresh

2.Call a save of the document before calling ws.editDocument. Yes that correct if the document has been saved it works. This however is not appropriate for forms that either shouldn't be saved or or need saving at the users request.

3.Use formula on the form to fill your fields on compose, pass parameters using environment variable.

As you can see none of the workarounds are perfect. The first one is almost their but will cause some screen flicker. IBM have deemed this bug not worthy to fix in 3 whole release and countless updates. Possibly the existence of the above bodges stop them from caring. This however is a common problem in Lotus notes programming that you often come up against cases where something should work but doesn't and you must find the specifc work around for you problem.