Beyond The Yellow Bubble

The NotesDocumentCollection class has a few attributes that can be rather annoying:-

1. The Notesdatabase object from which the NotesDocumentCollection is derived must remain in memory.  e.g. A function that returns a NotesDocumentCollection will return an empy object if the NotesDatabase used to create the collection is local to the function.  The NotesDatabase must be either passed as a parameter to the function, or be a global variable.
2. Documents can only be added to the collection if they are from the same NotesDatabase from which the NotesDocumentCollection was created.

As a way around these issues the following represents an alternate way  to represent a document collection.  This is to store the collection as an array of NotesURLs.  Not only does this technique remove the issues above but it also has the added advantage that it can be easily serialized. e.g. Being an array of strings the values can be easily stored as a field in a Notes document or can be passed back from a Web service.  Of course your application must understand this representation of a document collection and how to process such a collection.

The following function demonstrates how an array of NotesURLs can be created from an Notesdocumentcollection:-

' */
' *  Convert collection to an array of NotesURLs
' */
Function toArray(iDocumentCollection As NotesDocumentCollection) As Variant
 Dim Doc  As NotesDocument
 Dim Results As Variant
 Set Doc = iDocumentCollection.GetFirstDocument
 While Not Doc Is Nothing
  If Isarray(Results) Then Redim Preserve Results(Ubound(Results)+1) Else Redim Results(0)
  Results(Ubound(Results)) = Doc.NotesURL$
  Set Doc = iDocumentCollection.GetNextDocument(Doc)
 Wend
 toArray = Results
End Function

I favor the NotesURL format for representing a document because of the ease in which it can be converted to a NotesDocument via the NotesSession.Resolve method.  Unlike a NotesDocumentCollection the array of NotesURLs is enumerated so requires less code to process:-

Forall DocURL In Results
 Set Doc = Session.Resolve(DocURL$)
 ' code to process document
End Forall

The DominoDocumentCollection class within the .Domino Framework provides a toArray method to convert an existing NotesDocumentCollection.  The constructor of the DominoDocumentCollection class is able to accept an array of NotesURLs to create a NotesDocumentCollection from the NotesURLs.  Note: If documents exist in multiple databases only documents from the first database found are added.