The Session Class
We've seen so far how Notes and Domino use the NotesThread class to implement the startup and shutdown of the Notes and Domino environment. After this environment is set up, however, one additional class must be used to initiate access to Domino. This class is the Session class, which corresponds to the NotesSession class of LotusScript. I introduce the Session class in this section, but you can find more details in Chapter 16, "The NotesThread, NotesFactory, NotesException, Session, and Agent Classes."
The Session class is at the top of the Domino Object Model hierarchy. All other classes are obtained via the Session, either directly or indirectly. For example, from a Session object, you can get a DbDirectory object, through which you can access Domino databases. You can also obtain an AgentContext object (in an agent) from the Session, which gives you information about the current agent's context.
Okay, if the Session class is so important, how do you create one? Good question. There are two ways to get a Session object. You can either create one from scratch or you can obtain one from another class that happens to have one. When you are writing an agent, Notes will create a Session object for you, and you can just obtain it. When you are writing any other type of Java program, you must create it from scratch. Creating a new Session in Java from scratch is similar to using the LotusScript statement Dim session As New NotesSession. In Java, you use the CreateSession method of the NotesFactory class. Here is how you do it with Java:
Session s = NotesFactory.CreateSession();
NOTE
In release 4.6 of Notes and Domino, you used the static Session.newInstance method to create a new Session variable from scratch. The NotesFactory method now takes the place of Session.newInstance.
I mentioned that when you are writing code for an agent, you can obtain the Session object that was created for you. Within an agent context, you must do two things. First, your agent must extend the AgentBase class, and then you must have a NotesMain method. Within the NotesMain method, you use
Session s = this.getSession();
I describe this in more detail in the next section.