IBM: DeveloperWorks China website: All topic: Lotus
Java Access to Domino Objects, Part 1
content:
Overview Locally calls through inheritance to perform threads through the Runnable interface to perform threads through static methods to perform thread remote call coding management Get IOR Access Control Visualization through the Domino Directory Access to Note Author's Review
related information:
Java Access to Domino Objects, Part 2 Java / Corba Toolkit DocumentationJava and Domino: Building E-Business Applications for the WebConnecting Domino to The Enterprise Using Java RedbookDomino Designer Help
Level: Advanced
Robert Perron
, Document architect, Lotus
Steve Nikopoulos
, Senior Software Engineer, Lotus
Kevin Smith
, Consultant software engineer, Lotus, December 2004
This article will introduce Domino Objects to Java programmers and describe some basic knowledge of local access and remote access, and then introduce access control. The focus of this article is to develop Java applications.
If there is no basic knowledge described in this article, it may be more difficult to turn from Java to Domino Objects. Not only the code must be accurate, but the client and server environment must also be accurate. This article first introduces some of the basic knowledge of local access and remote access, and then explains access control. The focus of this article is the Java application. In the next continuation, we will discuss SSL encryption, servlets, connect pools, single sign-on, firewalls, timeouts, and recycling, and also include troubleshooting parts. This article assumes that you are familiar with the Domino Java API. Overview Java Access to Domino Objects is conducted by a high-level package Lotus.domino. According to the runtime environment, the interface in this package is implemented in a package in the other two packages:
Lotus.Domino.local provides calls from Notes / Domino software on the same computer. Lotus.domino.cso provides a Domino server that is accessed via a remote connection. For local access, the Java program runs on a computer installed with a Notes client or a Domino server. Local categories are built by JNI (Java Native Interface) to access NOTES / DOMINO binaries in the same process as JVM (Java Virtual Machine). For remote access, the Java program uses CORBA (Common Object Request Broker Architecture) requesting the Domino server. Remote class uses CORBA access to the server via TCP / IP network. Remote Access consists of two parts:
The client obtains the initial object of the server via the HTTP protocol, as an IOR (Interoperable Object Reference). The client further obtains other objects through the IIOP connection. Figure 1. Java Remote Access to HTTP and IIOP In Lotus.Domino, the NotesFactory class provides CreateSession and other methods to enable access to Domino Objects in the Java application and servlet. Special call modes determine that access is local or remote. To compile the Java programs that use the Lotus.domino package, class paths must contain notes.jar (local) or ncso.jar. For example: set classpath =% classpath%; c: /lotus/domino/notes.jar or set classpath =% classpath%; c: /lotus/domino/data/domino/java/ncso.ja where notes.jar can be in any NOTES / DOMINO installed program directory found. Ncso.jar can be found in the Domino / Java directory in the Domino Designer or Domino server data directory. There is no parameter in the call of CreateSession locally, and the first parameter is null or the first parameter is a null string represents a local call. The following code is equivalent: session s = notesfactory.createsis ()
Session s = notesfactory.creatession (String) NULL
Session s = notesfactory.createsis ("") Convert NULL to String to avoid overload conflicts. To implement local calls from the application and servlet, the Path must contain the NOTES / DOMINO program directory, and you must include Notes.jar in the Notes / Domino program directory. For example: SET PATH: =% PATH%; C: / Lotus / Dominoset ClassPath: =% classpath%; C: /lotus/domino/notes.jar Notes.jar contains Lotus.domino and Lotus.Domino.loca packages. Local calls need to use Notesthread class to manage threads. The Notesthread class extends java.lang.thread, which contains initialization and termination code specifically for Domino. You have the following three options:
The thread is performed by inheritance. Threads are performed through the Runnable interface. The thread is performed by a static method. The thread is performed by inheritance to perform threads by inheritance, and need to expand NotesThread instead of thread, and need to include Runnotes methods, not the RUN method. The NotSthread thread can be started by the START method as any other thread. This approach is easier than the static method (discussed later), and it is not easy to erode.
Import Lotus.domino. *;
Public Class Myclass Extends NotSthread
{
Public static void main (String Argv [])
{
Myclass t = new myclass ();
T.Start ();
}
Public void runnotes () // entry point for notes three
{
Try
{
Session s = notesfactory.creatession (); // Operational code Goes Here
}
Catch (Exception E)
{
E.PrintStackTrace ();
}
}
} Through the runnable interface to perform threads to perform threads through the runnable interface, you need to implement RunNable and include the RUN method, which is the same as any class using the thread. This approach can be used when you cannot extend NOTESTHREAD because you are expanding other classes.
Import Lotus.domino. *;
Public Class Myclass Implements Runnable
{
Public static void main (String Argv [])
{
Myclass t = new myclass ();
NoteSthread NT = New NotSthread ((runnable) T);
Nt.start ();
}
Public void run () // entry point for thread
{
Try
{
Session s = notesfactory.createsis ();
// Operational Code Goes Here
}
Catch (Exception E)
{
E.PrintStackTrace ();
}
}
} Through the static method to perform threads to perform threads by static methods, you need to call SinitThread () to initialize the thread, call StermThread () to terminate the thread. Stermthread () call must be strictly coupled to the call of sinitthread (); it is recommended to place StermThread in the "Finally" block. The static method is suitable for threads that are impossible to inherit, or suitable for more event-based threads.
Import Lotus.domino. *;
Public Class Myclass
{
Public static void main (String Argv [])
{
Try
{
NotSthread.sinitthread (); // start thread
Session s = notesfactory.createsis ();
// Operational Code Goes Here
}
Catch (Exception E)
{
E.PrintStackTrace ();
}
Finally
{
NotSthread.stermthread (); // Must Terminate Every Thread
}
}
} Threads of each application for local calls must initialize a NotesThread object. It contains AWT threads that visit Domino Objects. The listener thread must use a static method because they cannot inherit them from NotesThread. Dynamically determine when both local calls and remote calls can dynamically determine when using static methods Sinitthread and Stermthread. Remote calls can also be performed when running your local thread; however, not to be used through a session for calls to other sessions. You should avoid using multithreading unless there is a very good reason, such as processing file input / output and web requests, continue to operate. Observe the following guidelines:
In the same session, you can share, synchronize, and recycle Domino Objects across threads. If each thread uses a different session, then these functions will be lost; the synchronization and recycling must be managed on the basis of each thread. Do not use dbdirectory across threads. Allow access to existing documents in multi-thread, but only access documents in one thread will simplify memory management. Limit access to a thread so that you can do not check the other threads directly for recycling. Creating a document across thread is always secure, and these objects can be recycled regardless of other threads. The configuration file document is cached based on each thread. If you update competition, you will keep the last thread update. Note Do not delete the documents required to navigate through views or collections in other threads. When the child object is used for other threads other than its parent object, all sub-threads such as the parent thread can end. This is especially important when using Domino Objects in the AWT event handler. Remote call When you perform a remote call, the first parameter of the CreateSession signature is a non-empty string. The first parameter is usually used to identify the computer where the Domino server is located. For example: session s = notesfactory.createsis ("myhost.east.acme.com") or session s = notesfactory.createsis ("myhost.east.acme.com: 63148") The second example specifies the port number, so There is no need to run the Domino web server on myhost.east.acme.com. For more information, see the "Get IOR" section later in this article. To perform remote calls from an application or servlet, NcSo.jar must be included in the classpath of the client computer. Ncso.jar contains the Lotus.domino package, Lotus.Domino.cso package, Lotus.domino.corba package, and ORB classes, the ORB class contains implementation code for remote classes. For the installed Domino Designer and Domino server software, ncso.jar is located in the Domino / Java subdirectory in the Domino data directory. For computers that do not have Domino software installed, you must copy archived files from your computer installed. Class paths must contain archive files, for example: set classpath: =% classpath%; C: /lotus/domino/data/domino/java/ncso.jar encoded encoding is relatively simple. Remote call does not use Notesthread. Just use the host name and (optional) port number to make CreateSession calls. When not using threads, the template will look like this: Import Lotus.domino. *;
Public Class Myclass
{
Public static void main (String Argv [])
{
Try
{
String host = "myhost.east.acme.com:63148";
Session s = notesfactory.creatession (host);
// Operational Code Goes Here
}
Catch (Exception E)
{
E.PrintStackTrace ();
}
}
} The following templates will use threads:
Import Lotus.domino. *;
Public Class Myclass Implements Runnable
{
Public static void main (String Argv [])
{
Myclass t = new myclass ();
Thread NT = New Thread (Runnable) T); nt.start ();
}
Public void Run ()
{
Try
{
String host = "myhost.east.acme.com:63148";
Session s = notesfactory.creatession (host);
// Operational Code Goes Here
}
Catch (Exception E)
{
E.PrintStackTrace ();
}
}
} Management Remote Access also requires setting the Domino server and perform TCP / IP connections. The computer that installs the server must be able to access through TCP / IP. In the network settings of the computer, you need to check the DNS configuration of the host and domain name in the TCP / IP property. You must be able to use the Internet name from the client computer PING to the server computer. For example, if the host name of the Domino server is MyHost, then the domain name will be east.acme.co: Figure 2. TCP / IP Properties box The following commands should get the valid response of the client computer:> ping myhost.east.acme.com Server Domino Directory (Names.nsf) Server Document BSISCS tab For the Fully Qualified Internet Host Name field, hosts and domains must be displayed. Typically, host names have been set up when installing the server installation, for example: Figure 3. Server Document - Basic tab As shown in previous encoding examples, the Internet name is the (first) parameter of the CreateSession host. You can also use the IP address of the server. For example, if the IP address of myhost.east.acme.com is 9.95.73.30, then any of the following calls are valid: session s = notesfactory.createsis ("myhost.east.acme.com: 63148) or session s = notesfactory .CREATESSSION ("9.95.73.30:63148") must run the DIIOP (Domino IIOP) task on the server. HTTP tasks may also be run, depending on how I get IOR. Check the Server document in Domino Directory. Go to the Ports tab and then turn to the Internet Ports tab. View the Web tab (for http) and find the DIIOP tab. These parts have fields for specifying port numbers and enable / disable ports. Typically, HTTP's port number is 80, and the port number of DIIOP is 63148. The following screens show the DIIOP tab: Figure 4. Server Document - DIIOP tab If you access the database, you don't know the file name (for example, to use dbdirectory.getfirstDatabase, you must allow the file name over the web. Go to the Internet Protocols tab, HHTP tab, and R5 Basics tab. Then set "Allow Http Clients to Browse Database" to Yes. Figure 5. Server Document - HTTP tab To start HTTP and DIIOP tasks on the server, you need to make sure that these tasks are in the task list of the Notes.ini file serverTasks variable, if the Server document is properly configured, then these tasks should contain In the task list.
NOTES.INI files should include similar to the following lines: Servertasks = Update, Replica, Router, AMGR, AdMinp, Calconn, Sched, DIIOP, HTTP, LDAP From the running server, you can enter the following commands in the console to load the task:> Load Http> Load Diiop You can stop the task in the control desk TELL command:> Tell Http Quit> Tell Diiop Quit can refresh DIIOP tasks:> Tell Diiop Refresh can restart HTTP tasks:> Tell HTTP Restart Gets IOR on the Domino server, IOR It is a file called diiop_ior.txt, located in the Domino / HTML subdirectory in the Domino data directory. The IOR is a string encoding of an object, which contains identification information for CORBA access to the server. The client will decode the string IOR and use it to establish a remote session. By default, remote clients request server IOR via a web server port (which typically supports HTTP requests), and then performs session request via DIIOP ports. These two requests can be performed separately. For example: string iOR = notesfactory.getior ("myhost.east.acme.com");
// Get IOR Using Web Server Port
Session s = notesfactory.createssionwithior (iOR);
// CREATE session Using Diiop Port is equivalent to: session s = notesfactory.createsis; in the NotesFactory call, you can add a colon and port number after the host name or IP address is added to specify Used to get the host port of the IOR. If the web server is not run, you can use this mechanism to support the IOR's HTTP request via the DIIOP port, for example:
String iOR = notesfactory.getior ("myhost.east.acme.com: 63148");
// Get IOR Using Diiop Port
Session s = notesfactory.createssionwithior (iOR);
// Create Session Using Diiop Port However, the sequence of two-step coding is not required. It can be simplified to: session s = notesfactory.createsis; cannot be used to obtain text files other than Diiop_ior.txt with a Diiop port. If you get the IOR, Web server port through the web server port, you must allow anonymous access. In the Server documentation of Domino Directory, go to the Ports tab, then go to the Web tab. Make sure the Anonymous field under Authentication Option is set to Yes. Figure 6. Authentication options Specifies the DIIOP port to get the ability of the IOR is the new feature of Notes / Domino 6. Now you can use remote calls, there is no need to allow anonymous access to the web server, and even do not start the web server. I can also get IOR by other methods, then use CreateSessionWithior. For example, you can copy the DIIOP_IOR.TXT file from the server computer to the client computer. If the client contains a Diiop_ior.txt file that is valid for the server that will be used, you can use the following code: import lotus.domino. *;
Import java.io. *;
Public Class Platformior
{
Public static void main (String Argv [])
{
Try
{
FileInputStream Fin = New FileInputStream
"c: //lotus//notesr6//diiop_ior.txt");
InputStreamReader Fisr = New InputStreamReader (FIN);
BufferedReader Br = New BufferedReader (FISR);
String iOR = br.readline ();
Fin.close ();
Session s = notesfactory.createssionwithior (iOR);
// Operational Code Goes Here
}
Catch (Exception E)
{
E.PrintStackTrace ();
}
}
} Note that IOR settings may fail. Any changes to the server will fail to invalidate the diiop_ior.txt file on the client:
Change the DIIOP port number. Enable or disable the DIIOP port. Change the TCP / IP address. The last item can be avoided by specifying the server host name instead of the server. In the Server documentation, go to the Internet Protocols tab, then go to the DIIOP tab. Specify the server's Internet hostname in the "Host Name / Address" field. Figure 7. Host Name / Address field in the DIIOP tab This will force Diiop_ior.txt to use the server's hostname instead of using the IP address. You can also use the host name by notes.ini variable diiopiorhost. Access control grants the user's access level to the Domino server or Notes / Domino software on the client depends on how CreateSession is encoded and the server or client settings. Access control is achieved by one of two ways:
Names and related Internet passwords in Domino Directory are used in local or remote access. For locally access, the computer running code must be configured as a Domino server. The current Notes ID (specified by the KeyFileName variable in notes.ini) is only used in local calls. The computer running code can include a Notes client or a Domino server. Access to Domino Directory Access to Domino Directory, the code will determine that the user is an anonymous access server with an Anonymous or the user listed in the Domino Directory to access the server. In the NotesFactory call, if only the host name is specified, or the empty string is specified as a username and password, the server will be accessed in an Anonymous. For example: session s = notesfactory.creatession ("myhost.east.acme.com: 63148"); or session s = notesfactory.createsis ("MyHost.east.acme.com: 63148", "", ""); Access the server with a Domino user, you need to specify the username and the Internet password as parameter 2 and parameter 3. The username and password must match the Person document in Domino Directory on the server, for example: session s = notesfactory.creatession ("MyHost.East.acme.com: 63148", "Jane Smith / East / Acme", "TOPS3CR3T"); If you have a local access to the Domino server installed on the computer running code, you need to specify the host name empty string, for example: session s = notesfactory.createsis ("Jane Smith / East / Acme", "TOPS3CR3T") Anonymous Access, you need to specify the username and password for empty string: session s = notesfactory.createsis (",", ") For local access, no need to run the server. The settings in the Server document of Domino Directory are controlled by anonymous access or name visits. In the Server documentation, go to the Ports tab, the Internet Ports tab, and DIIOP tab. The following table specifies the settings:
The client code Authentication optionScreateSession (Host, "," ") Anonymous must be YES to access server createSession (Host, Name, Password) Name & Password must be YES so that the server must be a server for the server for Name & Password. The username in the Person document in Domino Directory, the password must be the Internet password in the same Person document. You can further restrict access, the method is to set the Enforce Server Access Settings field to YES under the Ports tab and the Internet Ports tab in the Ports tab and the Internet of Internet. To use the DIIOP port. Then specify the desired access in the Server Access tab under the Security tab. The Server document contains the following fields to control the security of the Internet session created by a remote or local Java class. When CreateSession uses a username and password or SSO token, the Internet session is accessible to the web user. The following table lists the fields in the Security Tab. Field Remarks Security Settings Access Server To access the server via a remote or local Internet session, you must be in this list if you are in this list, you cannot remotely or local Internet sessions Create Databases & Templates allow through the backend method Creating a new database and template CREATE New Replicas Allows Creating Database Copy Creatment CREATE MASTER TEMPLATES Allows Creating Main Templates by Back-end Method ProgramMability RESTRICTIONSRUN UNRESTRICTED METHODS AND OPERSRUN UNRESTRICED METHODS AND Operations This list can run a privileged Java method . This setting does not apply to a local Java operation, such as executing a write file system locally, which is executed on the remote Java program. (In other words, this setting has only impact on the Domino server access, and the client using the remote class will be used to access the file in the native file system.) Sign Agents to run on behalf of someone else acts as a web user running Internet Session Login User Valid User Name Logging in Sign Agents To Run On Behalf Of The Invoker Of The Agent runs as a web user Running a valid username of the Internet session to log in (TCP / IP) AnonymousDIIOP verification No name And Password (SSL) Name and PasswordDiiop SSL Verification Requires Name and Password (SSL) AnonymousDIIOP SSL Verification No Name and Password Internet AccessInternet Authentication For Internet Session Login User Name. For additional instructions, see Field Help or Document The following table lists the fields in the DIIOP tab:
Field Remarks (TCP / IP) Name and PasswordDiiop Verification Require Names and Passwords (TCP / IP) AnonymousDIIOP Verification No Names and Passwords (TCP / IP) Enforce Server Access SettingsDiop Using the Server Access Settings (SSL) Name and PasswordDiiop SSL Verification Require Name and Password (SSL) AnonymousDIIOP SSL Verification No Name and Password The following Notes.ini settings affect security Notes.ini settings for Internet sessions through remote or local Java classes NOAMBIGUOPWEBNAMES If Diiop login user name $ users view there are multiple matching names, NoAmbiguousWebNames = 1 would lead to the validation fails WebNameAuthenticWebNameAuthentic = 1 will be considered DIIOP login name to identify the user's name NABWebLookupViewNABWebLookupView = "xxx" will make the Domino Directory "XXX" to search DIIOP Login Name At the same time, the database ACL "Maximum Internet Name and Password Access" will affect the security of Internet sessions obtained through remote or local Java classes, because DIIOP login users are restricted to this access level. The server refreshes the cache of a security option for approximately half an hour. The console command "TELL DIIOP Refresh" can be forced to refresh now. Access to access to the current Notes ID, no specified parameters: session s = notesfactory.createsis () When you need authentication (for example, access the database), the dialog box is displayed, and the dialog is displayed Enter the Notes ID password. The selected Notes ID is specified in the keyFileName variable of the first Notes.ini file in the search path. Users must enter the correct password or click Cancel to continue follow-up. In addition to not specifying parameters, you can specify a second parameter as NULL (converted to string), the third parameter is a notes ID: session s = notesfactory.createsis (String) Null, (String) Null, "TOPS3CR3T ") On the server, the above method limits access according to the Readers field. To perform full access, you can use the following methods: session s = notesfactory.createssionwithfullaccess () or session s = notesfactory.createssionwithfullaccess ("TOPS3CR3T") Conclusion Some basic questions now know some of the basic or remote from Java applications to use Domino Objects know how. In the next article, you will learn about SSL encryption, servlet, connect pool, single sign-on (SSO), firewall, timeout, recycling, and troubleshooting. Reference
You can see this article in our website on our world. Java access to the Domino Objects, Part 2 Java / CORBA toolkit documentation Java and Domino: Building e-Business Applications for the Web Connecting Domino to the Enterprise Using Java Redbook Domino Designer Help Author Robert Perron is located in Westford, Massachusetts Lotus Documents Architect. He has been developing documents for Lotus Notes and Domino since the early 1990s, mainly to develop programmable. He has developed a document for LotusScript and Java Notes, and with others with 60 minute guide to lotusscript 3 - Programming for Notes 4 book. He has written many articles for LDD Today. Last year, he wrote the article "A Comprehens / Domino 6" for the View. Steve Nikopoulos is a senior software engineer of the Domino Server Programmability team. His recent work includes remote Domino Objects, Domino / WebSphere integration, and single sign-on. He likes to ride a bicycle with his family in the air time. Kevin Smith is a consultant software engineer in Westford IBM Messaging & Collaboration Development, and is currently responsible for the development of programmable functions of Domino servers. He entered Lotus in 1990, which is a technical support engineer of Lotus 1-2-3 / M. One of the Lotus Adventure Investment Project.
Page
