Me. Me me me. Me too.

Agent Smith was very good at multitasking

One of the best things about computers is that they can do more than one thing at a time. This is such a useful capability that we have a dizzying array of descriptiors for it: multitasking, multiprocessor, multiuser, multiplexing, multithreading — the list goes on. Unfortunately, along with being one of the most useful things about computers, it’s also one of the hardest to get right. This difficulty means that, for many platforms, doing things at the same time is simply not presented as an option.

Our beloved Domino is much like this. Yes, the server can do more than one thing at a time by using distinct processes and threads, but you and I as developers aren’t generally in control of this multithreading and concurrency. And that’s not surprising, since concurrent programming is hard.

It’s particularly tricky in Java and Domino because of something called “thread affinity.” That probably sounds like some kind of knitting technique, so let me elaborate…

A “Thread” is what Java calls a process executing concurrently to other processes, under the context of a single Java virtual machine. In XPages, each time the HTTP server passes along a request, that request is serviced by a Thread that’s then responsible for sending back a response. In classic Notes, you might think of a Thread as an Agent running some particular piece of code. If you have several Agents running at the same time on a server, then they do things independently from each other, but are still on the same server.

Threads are a vital part of large-scale programming; so much so that entire languages have been created specifically to make handling of threads easier. Java’s handling of threads has improved since version 1.0, but can still be pretty obtuse, especially when you aren’t versed in all the subtleties of Runnables, Callables, ThreadPools, Executors, AccessControlContexts, SecurityManagers and ClassLoaders. Frankly, it can all be overwhelming.

To make matters even trickier, the lotus.domino API binds all of its Java objects to a specific Java thread. So when a Domino object is created on a specific thread, it must also be .recycled() on that same thread. An attempt to recycle it on a different thread can lead to some rather spectacular crashes on your servers.

Because of this, when you have some Domino process that you’d like to run in a separate Java Thread, you really want to start with a fresh Session, and make sure you create all your Domino objects from that session, and then recycle that session on the same Thread. It seems kind of natural that you’d like to say “make a session, do some stuff, then release the session when you’re finished” all as one managed multi-threaded process.

Alas, life is never that simple, is it? It turns out there are only a handful of ways to create a Session from a Java Thread. If you’re in an Agent, the AgentContext creates one for you before your process starts. If you’re in an XPage, the NotesContext creates one for you before your process starts. If you’re in DOTS or a Java server addin, you just call NotesFactory.createSession().

What you *can’t* do is just call NotesFactory.createSession() when you’re in an Agent or in an XPage. It’s not allowed. The lotus.domino API walls this off to keep you from making a session directly once certain processes have started. This makes Java multi-threading an enormous pain in the ass, because you end up having to create or copy your Session in one thread, hand it to another thread that does whatever you want to do, then hand it back to the original thread to say “it’s okay for you to recycle this now.” But you better have recycled everything you got from the session in your other thread or you risk some mighty crashes.

Because of all this trouble, almost nobody writes multi-threaded Java programs for Domino. There’s a couple of IBMers and a handful of business partners who will take it on, but for the most part, the platform remains constrained by “what can I do serially with just one process?”

Personally, I’m sick of this. Domino is a very obvious choice for multi-threading processes, given how information is so commonly silo’ed in individual NSFs. And it has lots of great features like full-text searching and cross-server data access that can be quite slow and would benefit greatly from threading.

I’m so sick of it, in fact, that I’ve done something about it. I’ve added a thread management framework to the OpenNTF Domino API that takes all these headaches away. With the next version of the API, you’ll be able to write a Java class that extends XotsBaseTasklet, and simply overrides the .run() method. You just put your Domino code in the .run method, starting with .getSession() to acquire your ThreadLocal session. And you never have to worry about recycling anything at all.

Even better, you can tell your Runnable what kind of Session you want. It can be NATIVE if you want to run the process directly as the server. It can be NAMED if you want to specify a “runAs” name for your process. It can be MANUAL if you want to worry about how to create the Session yourself and just pass it to the process.

Better still, all this works from the XPages JVM. So if you want to write some Java code that runs as the server when you click a button in an XPage, you need a Java class that looks like this…


public class MyTask extends XotsBaseTasklet{

public MyTask() {

this.setDominoSessionType(DominoSessionType.NATIVE);

}

public void run() {

Session session = this.getSession();

//Do whatever the hell you want because you're the server now, baby!

}

}

When you want to run it, you just call…
org.openntf.domino.xots.XotsDaemon.getInstance().queue(new MyTask());

That’s all there is to it. No worrying about where to recycle stuff. No worrying about Java security controls. No worrying about how to deploy the code because you can just define your class as a Java design element. It just works.

You might notice that this is a package called “Xots.” If you’re thinking that this sounds like a cross between XPages and DOTS, you’re exactly right. Putting the Tasklet infrastructure in place is the first step in allowing for template-based scheduled Tasklets that run inside the XPages OSGi context. We have some hardening work to do still, but the end result will be that XPages developers who use the OpenNTF Domino API will be able to do away with scheduled Agents, and execute their scheduled processes inside the same JVM context as all the rest of their code.

I’ve been testing this frantically over the past couple of days and I’m really excited about it. I hope you are too. Feel free to voice your own suggestions, requests, demands and fears in the comments.

Thanks!

‹ The Last Word

His neuralkinetics are way above normal… ›

Posted in Uncategorized