Interfaces and Implementations
If you're a Java expert, interfaces and implementations are old hat.
If you're coming to org.openntf.domino from a traditional Domino development background with just a bit of experience of managed beans you'll have one big question when trying to use the code in Java: you type "Session" and the Java editor puts the red cross by the line, but when you click on that red cross, which org.openntf.domino class should you select? org.openntf.domino.impl.Session or org.openntf.domino.Session? What's the difference between the two?
If you've created managed beans or simple classes, everything is in one .java file: both the structure of the class and the business logic to be implemented. You can create another class that extends it, if required, to add additional functionality. But your extension falls back to the code in the parent class.
An interface, however, is just a schema. It defines core methods that must be implemented when the interface class is used, but it doesn't have any business logic of what those methods should do. Consequently, you can't create an instance of that interface class. You have to create another class that implements the interface and write code for each of the methods. You then create an instance of that second class and use that.
Think of it like a vehicle. You don't buy a Vehicle, you drive an implementation of Vehicle - Ford Mondeo, Volkswagen Beetle, Aston Martin Vanquish, Land Rover Freelander. Each are an implementation of a Vehicle, each have their own additional features, so Land Rover Freelander has four wheel drive and may have diesel engine, neither of which are base features of Vehicle. But they all implement core features, like a big wheel to determine the direction of travel, an accelerator pedal on the right, a turn signal activated by the driver. Each will have their own idiosyncrasies in the implementation of those core features of the Vehicle interface, but there is an underlying requirement that something that's a Vehicle should have them. But there are much bigger differences between a Volkswagen Beetle and a Volvo FH16 lorry. You could say the first implements Car and Vehicle, while the second implements Lorry and Vehicle. Yet both are implementations of Vehicle.
The classes in the org.openntf.domino are interfaces. They just give the skeleton for our Domino classes. They define the methods that are then implemented in org.openntf.domino.impl.
So you use org.openntf.domino.impl, right? No. Our code does that all for you. All the entry points into our code - Factory.getSession(), Factory.fromLotus() etc. - call the relevant org.openntf.domino.impl classes and return an org.openntf.domino object for you?
So you use this code today to interact with your Domino server and NSF. But in the future you want to use an OrientDb backend. Or Oracle. Or SQL.
Now you need to completely rewrite your code.
You could. Or you could create an implementation of the Domino objects for that backend, telling them what each of the methods need to do. Or we might already have done it for you by them. Now you just need to point to a different Factory class, that retrieves the alternative implementation, and the rest of your business logic doesn't need to change. You can use the same business logic for a variety of databases, just changing one class, because everywhere else you reference the interface, not the implementation. This is a bit over-simplified, but you get the idea.
There may be some places where using the Domino Object Model is unnecessary. But this is the benefit of interfaces.
So use org.openntf.domino rather than org.openntf.domino.impl.