Just a quick question about the DocumentWriter's writeAdditionalDocument method. The documentation states that: "The resulting additional document will be included automatically when the Connector returns the top-level document".  I understood this to mean that the document I create using the DocumentWriter returned by this method will be "embedded", essentially allowing me to create a partial graph in one call to getDocumentById().  A quick test show's me that this seems to not be the way it works...

I created a simple connector to test this:

public Document getDocumentById(String id) {

   DocumentWriter writer= this.newDocument("/");
   writer.setPrimaryType(NodeType.NT_UNSTRUCTURED);
   writer.addChild("/child", "additional");

   DocumentWriter additional = writer.writeAdditionalDocument("/child");
   additional.setParent("/");
   additional.setPrimaryType(NodeType.NT_UNSTRUCTURED);

   return document.document();
}

When I call session.getNode("/{projection}/additional") it first asks my connector for the document identified by root ("/") which is fine, but then calls back to get the document identified by ("/child").  I thought that this would not happen, as I created the document when I created the root document using "writerAdditionalDocument".

Is this expected behaviour?  If so, what is the point of this method?  If my connector is writing an additional document it must mean that I can/must create the document at that time, and it would seem redundant to request the document be constructed again on it's own...

What am I missing?

I have tested this with 3.8.1-Final and 4.0.0-Final