#Java
Posts tagged #Java · 24 posts
- ViewEntryCollection in Java: stampAll to Bulk-Edit, FTSearch to Narrow, Set Ops to Combine
You get a batch of view-ordered document entries with view.getAllEntries() or getAllEntriesByKey(key), and now you need to do something to them: set one field to the same value across all of them, narrow the range with a full-text search, or subtract 'query B's results' from 'query A's'. The reflex is a loop — getDocument and save on each. But ViewEntryCollection has batch and set operations of its own: stampAll sets one field across the whole batch at once, FTSearch narrows the collection in place to the matches, and intersect/merge/subtract do set operations. This covers those three, getNthEntry by position, and the two edges of walking: turn the view's autoupdate off (or you hit 'Entry not found in index') and recycle each entry.
2026.11.21 - Changing the ACL in Java: Without save(), Your Changes Vanish When the Database Closes
In Java you change a database's ACL programmatically: bump someone to Editor, enable a role for them, add a new entry. Every API call succeeds, nothing throws. Then you reopen the database and nothing changed. The reason is that ACL edits don't persist automatically — the docs say it plainly: if you don't call save before closing the database, the changes you made to its ACL are lost, with no warning. This covers getting the ACL, changing an entry's level, the fact that roles are two layers (define on the ACL, enable on the entry), the big save trap, and why you shouldn't mix Database.grantAccess with an ACL object you're holding.
2026.11.19 - QueryResultsProcessor in Java: Merge and Sort Results Across Databases into a View or JSON
You have document collections from three different databases, and you need them merged into one, sorted by the same field, a subtotal computed, and finally a chunk of JSON for the front end or a view to save. The hand-rolled way is to pull all three into memory, merge, and sort yourself — across databases, with any real volume, that doesn't hold up. QueryResultsProcessor (since R12) does it server-side: the docs put it as "Aggregates, computes, sorts, and formats collections of documents across any set of Domino databases." You feed in multiple sources with addCollection / addDominoQuery (each under a unique name), define the output columns and sorting with addColumn, then executeToView to materialize a results view that auto-expires, or executeToJSON to get JSON directly. This covers that many-in, one-out shape, the two output modes and their traps, and the create-method name (the one the docs get wrong).
2026.11.18 - Comparing Notes User Names in Java: Same Person, Not Equal? Normalize First
In Java you compare two Notes user names — the logged-in user from session.getUserName() and an approver stored in a document. Same person, yet string equals returns false. The reason: the same person's name takes different forms in different places — one is canonical, CN=John B Goode/O=Acme/C=US, another is abbreviated, John B Goode/Acme/US, another is just the common John B Goode. Compared as strings they're obviously unequal. The fix is to normalize both with session.createName to the same form (e.g. both getCanonical) and compare that. This covers the Name's three forms, comparing correctly, pulling a name apart into its components (OU, O, C) to decide whether someone is in a given org unit, and that it also parses RFC 821/822 internet addresses.
2026.11.16 - ViewNavigator in Java: for Big Views, Turn Off autoupdate and Set CacheSize
A view with a few hundred thousand entries, and in Java you need to walk every row and do something. getAllDocuments pulls the whole batch into memory first and blows the heap on a big view. ViewNavigator is different — it walks the view's index one row at a time, handing you ViewEntry objects (index-level row data) without opening each Document. But to make it actually fast there are three knobs to turn yourself: set IsAutoUpdate to false (background auto-update degrades performance and can invalidate the navigator's entries), set CacheSize for remote operations to cut server round-trips, and use the goto methods instead of the get methods when you only need to move the pointer or count (the docs state plainly that a goto method does not create a ViewEntry object). This covers building the right navigation scope, those three performance knobs, and recycling each entry as you go.
2026.11.14 - Reading MIME in Java: Without setConvertMIME(false), You're Not Reading MIME
Modern Domino mail stores the Body as MIME (multipart, with headers), not the classic composite rich text. Read it in Java with getFirstItem("Body") and Domino, by default, converts the MIME to rich text before handing it over — so what you get is the converted thing, with the original MIME structure, headers, and per-part encodings flattened away. To get the real MIME, you first call session.setConvertMIME(false) to turn that conversion off, then getMIMEEntity. This covers the correct order for reading MIME, walking a multipart tree part by part, reading headers, and a biting invalidation rule: a MIMEEntity goes invalid once you apply save / computeWithForm / sign to the Document.
2026.11.13 - Files in Java with Stream: the Default Charset Is System, Not Unicode
In Java you want to write a document's text out to a file, or read a file in. Domino's Stream (session.createStream) is the path that's integrated with Domino's own encoding, and it's what MIMEEntity and attachments use underneath. But it has a trap that quietly mojibakes non-ASCII text: a freshly created Stream reports its Charset as Unicode, yet open(path) with no charset argument defaults to System — the server's platform encoding — not Unicode. This covers getting a Stream, the open charset trap, writeText defaulting to no line ending (EOL_NONE), binary mode and bridging to java.io with getContents/setContents, and the two edges that bite: thread confinement and recycle.
2026.11.11 - Attachments in Java: Stream with getInputStream, and Two Traps That Bite
In Java you want an attachment's bytes — to stream to a browser, hash it, push it to object storage. The reflex is to extractFile to a temp file and read that back; but EmbeddedObject in Java has getInputStream, which reads the attachment's content straight as a stream, no temp file at all. This covers the streaming approach and two traps the docs state plainly but people still hit: extractFile throws on anything that isn't a file attachment (embedded objects / object links), and Document.getEmbeddedObjects doesn't return file attachments at all — you get those off the RichTextItem. Plus a platform reality: UNIX/Mac Domino only supports file attachments, not embedded objects.
2026.11.10 - Reading Rich Text in Java: Cast First, Then Mind the MIME and the Dropped Attachments
To touch a rich text field like Body in Java, getFirstItem hands you an Item, and you have to cast it to RichTextItem before you can do anything — and that cast hides two surprises: a modern Body is often MIME, not classic rich text (so you go through getMIMEEntity); and when you read the content to plain text with getFormattedText, it quietly drops the attachments and images. This covers getting at it in Java (the cast and the MIME case), reading rich text to plain text (getFormattedText's three parameters and what it throws away), and building one with createRichTextItem.
2026.11.08 - Reading a View in Java: Don't Open a Whole Document Just to Read One Column
To list a few columns per row out of a view for a report, the reflex is to walk getNextDocument and getItemValue each one — in Java that's thousands of NotesDocuments pulled from the back end and recycled one by one. But those column values already sit in each row: a ViewEntry's getColumnValues() reads the whole row without opening a single document. This covers getting a view in Java (the view/folder and name/alias traps in getView), why you read columns off a ViewEntry instead of a Document, looking up by key with getAllEntriesByKey, and why you call setAutoUpdate(false) before iterating.
2026.11.07 - Opening a Notes Database in Java: Many Paths, One Trap
In LotusScript, session.GetDatabase returns Nothing when the open fails, and your reflex Is Nothing check covers you. The same line in Java does NOT return null — getDatabase hands you a Database object anyway, one whose isOpen is false, a shell pointing at a database that isn't there. This covers how to get and hold a Database handle in Java: where it comes from, the open paths (getCurrentDatabase / getDatabase / DbDirectory), how to catch the 'returned an object but didn't open' trap, and where Database sits in the recycle parent-child chain — recycle it too early and the Views and Documents you're holding die with it.
2026.11.05 - DXL in Java: Exporting and Importing Domino Data with DxlExporter / DxlImporter
To move design elements between databases, or snapshot documents as XML for diffing/backup, DXL is Domino's XML representation. In Java the two workhorses are DxlExporter (Domino→DXL, exportDxl returns a String) and DxlImporter (DXL→Domino, importDxl writes into a target DB). The catch: import isn't just 'load the XML' — you tell it how to handle design, documents, and ACL (create/replace/update/ignore) with setDesignImportOption / setDocumentImportOption / setAclImportOption, and whether the replica must match. This covers both classes, the import options, and the relationship to the LotusScript version.
2026.10.04 - XPages Managed Beans: Giving SSJS a Real Java Object You Use Like database
SSJS in a script library is fine as glue, but logic gets unwieldy fast — no real types, hard to test, and serialization headaches when you stash it in scope. A managed bean lets you declare a Java class in faces-config.xml, and it becomes a top-level variable in SSJS and EL that you use just like database or session — bean.method(), #{bean.prop}. This covers how to declare one (the name/class/scope elements), the three class requirements (no-arg constructor, get/set, Serializable), the scope lifecycle, and when logic should move out of SSJS into a bean.
2026.10.03 - NotesThread: The Rules for Background Threads in Domino — init Each Thread, Give It Its Own Session
Want to run Domino local calls on a background thread in Java? A plain new Thread won't do — it has no Notes runtime. You either extend NotesThread and override runNotes(), implement Runnable handed to NotesThread, or call sinitThread()/stermThread() yourself. And every thread needs its own Session and its own recycle — you can't share across threads. This covers the three NotesThread patterns, the sinitThread/stermThread pairing rule, the one-session-per-thread law, and why a background thread can't get sessionAsSigner.
2026.09.30 - The Java Fix for Domino IQ Timeouts: LLMReq.completionStream, and How XPages SSJS Calls It
Yesterday's piece used LotusScript's CompletionStream to get past Domino IQ's 5-minute timeout; if your code is Java (an agent, a bean) or XPages (SSJS), you hit the same timeout. This is the Java version: LLMReq.completionStream with the CompletionStreamCallback interface (return Continue/Stop to control the stream), plus a key fact — SSJS has no native LLM class, but SSJS's session IS a lotus.domino.Session, so you call the Java API directly or wrap the streaming in a Java class and reference it from SSJS. With a three-language comparison table.
2026.09.06 - Java's NotesException: .id, .text, and try/catch/finally
LotusScript error handling is On Error Goto, Err.Number, Resume. In Java, nearly every lotus.domino method throws a checked NotesException — the compiler forces you to handle it — and it carries .id (the Notes error code) and .text (the message). This piece covers Java exception handling: NotesException's fields, using .id against NotesError constants for targeted handling, and the rule that ties this whole Java data-layer series together — recycle belongs in finally, so it still runs when something throws.
2026.08.17 - Looping a DocumentCollection in Java: Get the Next One First, Then recycle This One
In LotusScript you loop a DocumentCollection with Set doc = coll.GetNextDocument(doc) and never think about memory. In Java the same loop over tens of thousands of documents exhausts the agent's memory — unless you recycle each one inside the loop, in an order you can't get wrong: fetch the next document using the current one, then recycle the current one. This piece covers the correct Java iteration idiom: DocumentCollection's getFirstDocument/getNextDocument, the isValid deletion-stub check, when to switch to the leaner ViewNavigator, and the recycle ordering LotusScript never makes you think about.
2026.08.16 - Why Can't You Just Use java.util.Date for Notes Dates in Java?
To work with a Notes date in Java you can't just use java.util.Date — there's a lotus.domino.DateTime in the way. It's a heavyweight back-end object with a handle behind it, so it leaks memory in a loop if you don't recycle it; it stores dates as strings and throws on bad input; and toJavaDate() is the bridge that converts it into Java's own date type so you can reach java.time. This piece covers how Java's DateTime is created, read, and written, how it crosses into Java's time world, and the recycle burden LotusScript doesn't carry over.
2026.08.15 - Reading and Writing Notes Items in Java: getItemValue Hands You a Vector, Not the Array You Know
In LotusScript, doc.GetItemValue returns a Variant array and you loop over it without a second thought. In Java, the same call returns a java.util.Vector — you have to know the element type, a missing item comes back empty instead of throwing, and if it holds DateTime objects it leaks memory. This piece covers reading and writing items on the Java Document: getItemValue and the typed getters and their missing-item behavior, what Java types replaceItemValue accepts and how it auto-creates an item, why appendItemValue quietly makes duplicate items, and three instincts LotusScript won't carry over.
2026.08.14 - Anatomy of a Java Agent: Triggers, Rights, Output, Debugging
The first three pieces assume the agent is already running — you can recycle, you have a Session, you run DQL. But how does a Java agent get triggered, whose rights does it run with, where does System.out go, and how do you debug it? This fills in the step before NotesMain(): the AgentBase skeleton, Trigger and unprocessedDocuments, the signer that decides an agent's rights, restricted vs unrestricted, and the System.out-to-log.nsf debugging path.
2026.08.10 - Running DQL from Java: DominoQuery and QueryResultsProcessor
The site's DQL trilogy teaches the query language, but it runs DQL from LotusScript or the console. In Java, DQL goes through two classes: DominoQuery compiles, tunes, and runs; QueryResultsProcessor sorts, aggregates, joins across databases, and outputs JSON. And a common first-time trip-up: you get both from the Database, not the Session. A field report on how DQL actually runs from Java.
2026.08.09 - Getting a Session in Java: NotesFactory, Local, and Remote
LotusScript's session is a global you never create; Java has no such thing. Before you touch a single document you have to obtain a Session yourself — and how you get one depends on whether your code runs as an agent, a standalone program, or remotely. A field report on NotesFactory's three paths, local (JNI) vs remote (DIIOP), the who-creates-recycles rule, and the two traps: JVM bitness and one session per thread.
2026.08.08 - Rewrote LotusScript in Java and Memory Blew Up? You Forgot recycle()
The same logic runs forever in LotusScript, then blows up the agent's memory the first time you loop it over tens of thousands of documents in Java. The reason is that every Java Domino object is backed by a native handle the garbage collector can't see. A field report on the mechanism, the four official rules, the loop leak pattern and its fix, NotesThread's role, and how local vs remote sessions change the cost.
2026.08.07 - NSF ODP Tooling: Build Domino NSFs from Source, No Designer Required
NSF ODP Tooling is an OpenNTF project that turns a binary NSF into a file-system On-Disk Project you can keep in Git, then compiles it back into a full NSF without Domino Designer — bringing real version control and CI/CD to Domino. Here's what it is, how the Maven plugin and container-based compilation work, and what the 4.1.0 release actually changed.
2026.06.27