Reading a View in Java: Don't Open a Whole Document Just to Read One Column

Reading a View in Java: Don't Open a Whole Document Just to Read One Column

Nov 7, 2026 765 words

You have a view with 50,000 orders in it. You need a report listing three columns — order number, customer, total. The reflex: get the view, getFirstDocument(), walk getNextDocument(), and getItemValueString("OrderNo") on each one.

In Java that opens 50,000 documents — every getNextDocument() pulls a whole Document out of the back end, and you have to recycle() each one. But those three column values are already computed and sitting right there in the view.

A row in a view is a ViewEntry, and it carries this row’s column values. getColumnValues() hands you the whole row’s values at once, without opening a single document. This piece covers how to get a view in Java, how to read from entries instead of documents, how to look up by key, and the one switch to flip before you iterate.


Get the view first: two small traps in getView

database.getView(name) gets a View — the official description is plain: “Represents a view or folder of a database.” Two things that trip people up:

  1. It finds a view or a folder. The same getView("Inbox") might hand you a folder rather than a view. If your logic only holds for a view, check isFolder() on what you got back.
  2. Name or alias both work — but don’t combine them. The parameter is case-insensitive and takes the display name or an alias; but the docs are explicit: “do not combine the view name and an alias” — don’t throw the whole name|alias design value, pipes and all, at it.

One contrast worth drawing with getting a Database handle in Java: getDatabase has that “hands you a non-null shell even when it didn’t open (isOpen is false)” trap; getView has no such createonfail shell — the docs just say it returns the one “whose name or alias matches.” Take what you get, but still guard it before you walk on.

Reading a row’s columns: use a ViewEntry, not a Document

This is the habit most worth changing when you read a view in Java. A row is a ViewEntry — the docs define it as “Represents a view entry. A view entry describes a row in a view.” Its getColumnValues() returns every column value for that row at once (a Vector), in the view’s column order:

ViewEntryCollection col = view.getAllEntries();
ViewEntry entry = col.getFirstEntry();
while (entry != null) {
Vector<?> cols = entry.getColumnValues(); // the whole row, no document opened
System.out.println(cols.elementAt(0) + " / " + cols.elementAt(2));
ViewEntry next = col.getNextEntry(entry); // grab next first
entry.recycle(); // then recycle the current one
entry = next;
}

Against “getNextDocument() then getItemValue per row,” the gap is large: the first touches only the view index, where the column values already live; the second pulls a whole document out of the back end for every row. For reports, lists, and exports, if an entry can give you the value, don’t open the document.

When do you still open the document? When the value you need isn’t in any view column (no column shows it, or you need the raw item value rather than the column’s displayed/computed value). Then call entry.getDocument() — but that’s “open it when you need it,” not “open one per row by default.”

Looking up by key: getAllEntriesByKey

A view is already sorted and indexed on its columns, so using it as a lookup is far faster than FTSearch or a full scan. getAllEntriesByKey matches a key against the sorted columns and returns a ViewEntryCollection:

Vector<String> keys = new Vector<>();
keys.add("ACME"); // matched against the first sorted column
ViewEntryCollection hits = view.getAllEntriesByKey(keys, true); // true = exact

The docs spell out the parameters: key can be a single value (matched against the first sorted column) or a Vector (matched column by column); and the trailing boolean exact — true is an exact match; false or omitting it does a partial match (a prefix hit counts). Want one entry, use getEntryByKey; want all matches, getAllEntriesByKey. The full picture of keyed lookups against categorized views is in the by-key piece, from the LotusScript side — Java rides the same index.

While iterating: setAutoUpdate(false) first

A view auto-updates by default — if another process changes the underlying documents while your loop runs, the view index shifts under you, and getNextEntry can skip, repeat, or land on a position that has moved. For a stable snapshot, turn it off before you iterate:

view.setAutoUpdate(false); // for this loop, don't move under my feet

Clean up what you opened, as always. View, entries, and collections are all back-end handles — recycle() them when done, and don’t recycle the view while you’re still holding its entries (recycle the parent and the entries under it die with it). The full per-iteration discipline is in the Java recycle blow-up piece and the recycle deep-dive; here just the one rule: grab the next entry, then recycle the current (that’s the order in the example above).

What about LotusScript and SSJS?

The same view, by class name in each language:

  • LotusScript: NotesView, with NotesViewEntry / NotesViewEntryCollection / NotesViewNavigator; no recycle chore.
  • SSJS / XPages: NotesView (or just View), with the same getAllEntriesByKey and ViewEntry.getColumnValues; the XPages request manages the lifecycle, so you don’t recycle by hand.
  • The Java-specific part is this piece’s subject: reading columns off entries saves a mountain of document opens, but the recycle chain across entry / collection / view is yours to keep — the full picture is in the Java recycle blow-up piece.

Sources

← Back to all posts