When people talk about Java in Notes & Domino, they inevitably talk about the .recycle() method. And when they talk about .recycle(), they inevitably talk about “memory.” And when they talk about memory, people glaze over and their minds harken back to the first magazine articles (remember those?) about Java and they say “but I thought Java managed memory for you?”
Here’s the thing you need to know: .recycle() has nothing to do with freeing memory. Don’t let the pedantics fool you; they will say “but it’s memory in the C API!” That’s just leaky abstraction BS. If you’re programming in Java, and you .recycle() your Domino objects, you are not doing something that affects MEMORY. You are doing something that affects HANDLES.
All conception runs on metaphors, so let’s make a metaphor about this. Think about going to a grocery store. When you go to the grocery store, there are thousands and thousands of products on the shelves (well, in some places and at some times, at least.) Think of all the stuff on the shelves as what’s in memory. And every day, new inventory comes into the store and they replenish that memory with new items to put on the shelf.
But at the store, there’s only a certain number of trolleys. There’s a finite pool of carts in the parking lot and in the entrance to the store. And it’s these trolleys that are like your Domino Java object handles.
When you go to the grocery store, and you get a trolley, you can put stuff into it and take stuff out and cart things around and run behind the trolley while jumping on the back of it and do a wheelie or whatever else you can think of. But there’s only so many trolleys to go around for all the shoppers at the store.
That’s what a Domino object handle is in Java — it’s a trolley. You can put various String and Integers and Doubles and arrays and bytes into it, but the point is that the trolley holds things and there are only so many trolleys to go around.
If you fill your trolley up with stuff, and you pay for it, and you take it out to your car, what do you do when you’re done with the trolley?
If you’re a considerate and cooperative shopper, you put the trolley into one of the pens or back in the queue where you got it. If you’re an inconsiderate twat, you leave it whereever you finished with it. And if you’re a vicious asshole, you push it out of the parking lot and into the ditch across the street.
Well, this is what it means to use .recycle() in the Java API: When you .recycle() an object, you’re putting the handle back into the queue, so that other processes can use that handle to put things into. When you don’t .recycle(), but your process runs in a space that cleans up after you (such as XPages), well, that’s the kid that has to roam around the parking lot finding all the trolleys left in the middle of the aisles by thoughtless shoppers. And when you don’t .recycle() in a space that doesn’t clean up for you, well, that’s pushing your handles off into the ditch across the street.
If you’re thinking “why do I have to worry about trolleys at all?” I will agree with you that you shouldn’t have to. .recycle() sucks. As platform developers, we shouldn’t have to do it. The reasons why we have to do it are complex and nuanced and beyond the scope of this conversation. But ultimately, I agree that we should have an infinite number of trolleys and pushing a trolley into the ditch across the street should cause it to simply fall through a portal that exits right back into the store’s queue.
When that happens, I will be the first to celebrate by jumping on the roof of my house and shouting “DOMINO OBJECTS DON’T NEED TO RECYCLE!!!!!” But today is not that day. And until that day, we still have to put our trolleys back in the pens and we still need to recycle our Domino objects.
At least now you know that the reason why isn’t about the memory and the data housed in it, but about the container for the memory. You can have a Walmart or a Costco or a freaking Amazon.com warehouse full of goods, but you still have a fixed number of carts to put them all in and it’s those carts that you are freeing up when you .recycle() in Java. So put your trolley back when you’re finished with it. Your neighbors will thank you when they have a place to put all their groceries when they go to the store.