Java Domino Classes

     

The Java classes and interfaces in the lotus.domino package provide access to Domino objects as if the Domino server were performing the action. The lotus.domino objects are used to access and manipulate actual Domino databases and data elements within those databases. However, though the access is directly to Domino data, it does not bypass the Domino access control mechanism. The lotus.domino objects must be used in the context of a client session so that the access is still subject to the access controls defined for the session's user identity. The session access can be made in two ways: "local," where the lotus.domino objects access Domino data on the same system as the objects are running, and "remote," where the access is from the program's system to a remote Domino server. (Remote sessions are established using a CORBA mechanism via the Internet Inter-Object Protocol (IIOP). The HTTP and DIIOP server tasks must be running on the Domino server that is the target of a remote session.) The type of access for a lotus.domino session is determined by the signature of the createSession method of the Session class. See Table 10-2 for how the signatures of the createSession method map to the type of session access.

Table 10-2. lotus.domino.Session.createSession() Signatures

createSession Signature

Type of Session/User Identity

() ( null, null, null )

Local session, user identity set from ID file pointed to by first notes.ini file in system path .

( null, null, String Pw )

Same as above, except String must match password of ID file.

createSessionWithFullAccess() " ( String Pw )

Same as above, except document access (on server) is not restricted by Readers fields. String must match password of ID file.

( null, "", "" )

Local session, user identity is Anonymous if Server record in local Domino directory permits Anonymous access.

( String Host, "", "" )

Remote (IIOP) session where Host is TCP/IP host name of the remote Domino server (Domino 6 allows host names suffixed with a port number, such as " host:port "). User identity is Anonymous if permitted as above.

( null, String User, String Pw )

Local session, user identity is that of given user name if it matches a Person record in the local Domino directory and password matches Internet password.

( String Host, String User, String Pw )

Remote session, Host as above. User identity is that of given user name if it matches a Person record in remote Domino directory and password matches Internet password.

( null, String Token )

Local session, user identity is that associated with the Token string. The Token string must be in LTPA token format as used for Single Sign-On. (See Chapter 12 for a discussion of SSO.)

( String Host, String Token )

Remote session, user identity set as above.

( null, Credentials Cr )

Local session, user identity is that associated with the org.omg.SecurityLevel2 . Credentials object passed as the Cr parameter. This Credentials object is used in the loginHelper servlet supplied with WAS.

( String Host, Credentials Cr )

Remote session, user identity set as above.

( null, null )

Local session, user identity is set from the default ”Credentials object within the JVM environment. This signature can be used within an EJB to establish identity based on the default Credentials associated with the EJB container.

( String Host, null )

Remote session, user identity set as above.

( null, HttpServletRequest Req )

Local session, user identity is set by the Domino HTTP server from the HTTP client authentication data in the request header.

( String Host, HttpServletRequest Req )

Remote session, user identity set as above.


In addition to the two types of client access, the lotus.domino sessions can be established in three major contexts. You can think of session context as the type of JVM environment under which the lotus.domino program runs. The three context types are Application, Agent, and Applet. Agent session context is where the Java program is written as a Domino database agent and runs under the JVM established by the Domino server (or Notes client). We saw examples of Agent context in the previous chapter on accessing J2EE elements from Domino applications. Applet session context naturally applies to Java programs coded as applets and which run under a Web browser JVM. Application session context is for all other types of Java programs that run under a JVM outside of Domino or a Web browser. One most often writes J2EE programs that invoke Domino objects using Application context. The client session context is established by the type of lotus.domino base class under which the session object is created or obtained. Application context is set by using the NotesFactory class, Agent context via AgentBase , and Applet context via AppletBase .

To compile a Java program using the lotus.domino package, the Notes.jar Java archive file must be specified to the Java compiler. (In WSAD, you can specify Notes.jar as an external jar file in the project's Java build path.) To run the program, you must make either the Notes.jar (for local sessions), NCSO.jar (for remote sessions), or both accessible via the JVM's class path, the system path, or the java.library.path property value. If the program uses local session access, then the Domino server (or client) platform-specific library files must also be accessible. We've found that the only means of specifying the runtime libraries that works on all platforms is via the java.library.path property. For example, on a Unix/Linux system, you would specify it in this way:

 

 java -Djava.library.path=$PATH:/opt/lotus/notes/latest/linux/:/local/notesdata <class> 

A program using local session access will use the Domino installation corresponding to the first Domino configuration file (notes.ini) found on the system path. Thus, if a Domino server and Notes client are installed on the same system, a local session will be established to the server if its notes.ini file is found first in the system path and vice versa. If the local session is established without a user identity specified, the user identity defaults to the Domino ID file pointed to by the notes.ini file (usually the server ID file for a server installation and a client ID file for the client).

Remote session access is made via the Internet Inter-Object Protocol (IIOP) and requires the Domino server DIIOP task be running on the target server (as well as the HTTP server task). With Domino R6, it is now possible to specify the server port on which the IIOP communication is conducted , making it easier to accommodate firewall restrictions. Keep in mind that the DIIOP task will terminate the remote Domino session due to inactivity. Your Java code should check the status of the Domino session object (via Session.IsValid() ) before accessing any Domino objects, or handle the CORBA/IIOP exception thrown if the session is terminated .

Let's now look at the specific classes and interfaces available in the lotus.domino package. The classes can be categorized into three main groups: session- related , Domino objects, and utilities. Table 10-1 shows the classes and interfaces in this grouping.

Table 10-1. lotus.domino Class Categories

Category

Classes/Interfaces

Session Related

NotesFactory, NotesThread, AgentBase, AgentContext, AppletBase, Session

Domino Object Model

ACL, ACLEntry, Agent, Database, DateRange,.DateTime, DbDirectory, Document, DocumentCollection,.EmbeddedObject, Form, International, Item, MIMEEntity, MIMEHeader, Name, Newsletter, Outline, OutlineEntry,.Registration, Replication, RichTextItem,.RichTextParagraphStyle, RichTextStyle, View,.ViewColumn, ViewEntry, ViewEntryCollection, ViewNavigator

Utility

AgentLauncher, AgentLoader, AgentRunner, Log, Parser,.Processor, Stream, XSLTResultTarget


When using the Domino Java classes from J2EE applications, you will most often use the session-related classes of NotesThread , NotesFactory , and Session . The NotesThread class serves to establish the thread context under which Domino objects are managed. You must establish the NotesThread context for your application if it will access Domino objects via a local session (it is not required for remote session access). For J2EE applications running under the control of a Web or EJB container, the thread context setup is done by using the NotesThread static methods sinitThread() and stermThread() , since the container controls the thread setup for the servlet, JSP, or EJB. We will see an example of using the NotesThre ad static methods for servlets and EJBs in the following sections.

The NotesFactory class is used to establish the Domino session context for the Domino Java classes. Specifically, the createSession() method is used for session setup. The createSession method is multi- faceted , each method signature resulting in a particular type of session and user identity being established. Table 10-2 shows the various signatures of createSession and the resulting session type and user identity.

For application processing, the most often used interfaces from the Domino Object Model are Database, Document, and Item. The Database interface represents a single Domino database file (.nsf or .ntf) and can be obtained from either the AgentContext (if running as a Domino agent), DbDirectory , or Session object (if not running as an agent). The Document interface represents a single document within a database and can be obtained from the Database , DocumentCollection , Newsletter , or View objects. (Used within a program, a View object acts as a document search or query function.) The Item interface represents a single data element within a document. Using these three interfaces, you can access and manipulate most any data within Domino databases, including the databases used for address book, mail, calendar, and discussion functions.

If you are using a local session for Domino access, you are responsible for managing the "garbage collection" of the Domino Java objects. This is because the Domino Java objects in a local session use the Java Native Interface (JNI) to invoke Domino libraries via the Domino C API. Each Domino Java class makes a recycle() method available for freeing the JNI resources. You should invoke the recycle() method on an object when it is no longer used to avoid using up system memory. Any Domino object obtained should be freed via the recycle() method, especially objects acquired in a collection class. For parent/child structures, recycling the parent recycles the children. Objects should be recycled in the same thread in which they are obtained. Recycling of objects is not needed for remote sessions since the Domino access is done at the Domino server.



IBM WebSphere and Lotus Implementing Collaborative Solutions
IBM(R) WebSphere(R) and Lotus: Implementing Collaborative Solutions
ISBN: 0131443305
EAN: 2147483647
Year: 2003
Pages: 169

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net