Generic Lotus Notes export library

I finally got fed up writing ad-hoc export functions for applications so I have written a generic export library for Lotus Notes. The library is written in LotusScript and can be applied to any database.

Below I’ll discuss the concepts I have defined and show how the code is used.

The export library consists of four core concepts that translate into four core (abstract) classes:

  • OutputStream

    OutputStream models where the exported data is written to.
  • ExportSource

    ExportSource models a source of data for export.
  • ExportStrategy

    ExportStrategy models the way (e.g. CSV, XML) we write the exported data to the OutputStream.
  • ExportFormatter

    ExportFormatter models the way data from the NotesDocuments provided by the ExportSource is actually exported.

Below I’ll explain each concept in a little more detail.

OutputStream:

In the most simple form this is a thin wrapper around the built in NotesStream class. The class has been wrapped since it allows me to subclass OutputStream while keeping the classes that use OutputStream unaware of the differences. I have defined three sub-classes so far:

  • FileOutputStream (writes a a file on disk)
  • LineFileOutputStream (as above with each call to write() on a separate line – good for CSV exports)
  • RichTextOutputStream (writes to a NotesRichTextItem)

ExportSource:
At present I have two four implementations:

  • ViewExportSource (exports all the documents in a view)
  • CollectionExportSource (exports the documents in a NotesDocumentCollection)
  • SelectedExportSource (exports the documents the user has selected)
  • SearchExportSource (exports the documents found by the supplied @Formula query)

ExportStrategy:
The class is modelled on the Strategy pattern and I have defined three implementations so far:

  • CsvExportStrategy (exports the data in CSV format)
  • XmlExportStrategy (exports the data in XML format)
  • RssExportStrategy (exports the data in RSS format)

ExportFormatter:
I am a little unsure whether ExportFormatter is the correct name but here goes. I have defined two implementations so far:

  • ViewExportFormatter (exports the data as defined by a view in a database, that is reusing the @Formula for the columns)
  • ConfigurationExportFormatter (exports the data as defined by a set of configuration documents thus allowing the user to define his own export)

You combine the above concepts to export data. If you need to export the selected documents to a CSV-file using the format of the current view you would combine:

  • LineFileOutputStream pointing to a file on disk
  • SelectedExportSource to export the documents the use as selected
  • CsvExportStrategy to write the exported data as CSV
  • ViewExportFormatter to format the data as the current view

Example 1:
Export selected documents based on a view to a CSV-file on disk.

Option Public
Option Explicit
Use "CLASS: ExportSource"
Use "CLASS: OutputStream"
Use "CLASS: ExportFormatter"
Use "CLASS: ExportStrategy"

Sub Initialize
   'declarations
   Dim session As New NotesSession
   Dim db As NotesDatabase
   Dim view As NotesView
   Set db = session.GetDatabase("", "export_db.nsf")
   Set view = db.GetView("ExportDocuments")

   'we want to export selected documents only
   Dim es As New SelectedExportSource()

   'we want to format the documents as the current view (notesTestDocuments)
   Dim formatter As New ViewExportFormatter(Nothing, "notesTestDocuments", Nothing)

   'the documents should be written to a file replacing any existing file
   Dim out As New LineFileOutputStream("d:\export.csv", True)
   Call out.Open()

   'export the data as CSV to the created OutputStream and the ExportSource
   Dim strategy As New CsvExportStrategy(out, es)
   Call strategy.Export(formatter, True)

   'close the OutputStream
   Call out.Close()

End Sub

Example 2:
Export all documents in a view to a richtext item on a document as XML.

Option Public
Option Explicit
Use "CLASS: ExportSource"
Use "CLASS: OutputStream"
Use "CLASS: ExportFormatter"
Use "CLASS: ExportStrategy"

Sub Initialize
   'declarations
   Dim ws As New NotesUIWorkspace
   Dim session As New NotesSession
   Dim db As NotesDatabase
   Dim view As NotesView
   Dim doc As NotesDocument
   Dim rt As NotesRichTextItem

   'get current database and view
   Set db = session.CurrentDatabase
   Set view = ws.CurrentView.View

   'we want to export all documents in the current view
   Dim es As New ViewExportSource(view)

   'we want to format the documents as the current view (notesTestDocuments)
   Dim formatter As New ViewExportFormatter(view, "", Nothing)

   'the documents should be written to a rich text item
   Set doc = db.CreateDocument
   Call doc.ReplaceItemValue("Form", "TestDocument")
   Call doc.ReplaceItemValue("Title", "XML Export " + Now)
   Set rt = New NotesRichTextItem(doc, "Body")
   Dim out As New RichTextOutputStream(rt)
   Call out.Open()

   'export the data as XML to the created OutputStream and the ExportSource
   Dim strategy As New XmlExportStrategy(out, es)
   Call strategy.Export(formatter, True)

   'close the OutputStream
   Call out.Close()

   'save document
   Call doc.Save(True, False)

End Sub

Since some exports (i.e. selected documents as CSV to a file) are done quite frequently I have defined some helper classes (really based on the Facade pattern). These helper classes are called Exporters and wrap the above example 1 on one line of code:

Option Public
Option Explicit
Use "CLASS: Exporter"

Sub Initialize
   Dim exporter As New CsvExporter("d:\export.csv", "notesTestDocuments", True)
End Sub