Javaf accesses Lotus objects

Using Java, you can access objects in Domino, such as databases, views, and documents. This article briefly describes the basic programming methods for accessing Domino objects using Java. The content in this article is mainly based on Lotus Domino/Notes 6, which is slightly different when R5 is used.

Java accesses Domino objects by calling the Lotus. Domino package. In the runtime environment, interfaces in the Lotus. Domino package are implemented through two packages:

• Lotus. Domino. Local-supports local calls from the computer where notes/Domino is located
• Lotus. Domino. CSO-supports remote connection to the Domino server

For local connections, JavaProgramRun on the computer where the Notes client or Domino server is located, and use JNICode.

For remote connections, Java programs access the services provided by Domino through CORBA. Remote access involves two processes:

• The client obtains the initial object of the server over HTTP as the IOR (interoperable object reference)
• The client uses the IIOP protocol to further obtain other objects on the server.

In Lotus. Domino, The notesfactory class provides createsession and other methods, which can be used to access Domino objects by Java applications or Servlets. Different call Methods Determine whether the access is local or remote.

To use the Lotus. Domino package to compile Java programs, the classpath must contain notes. Jar (local) or ncso. Jar (remote ). For example:

Set classpath = % classpath %; C: \ Lotus \ domino \ notes. Jar

Or

Set classpath = % classpath %; C: \ Lotus \ domino \ data \ domino \ Java \ ncso. Jar

The notes. jar file can be found in the program directory installed in Notes/Domino. Ncso. jar is stored in the data directory of the Domino server or Domino designer and in the domino \ Java subdirectory.

Local call

When createsession is used, no parameter, the first parameter is null, or the first parameter is a Null String, indicating local call. The following code is equivalent:

Session S = notesfactory. createsession () Session S = notesfactory. createsession (string) null) Session S = notesfactory. createsession ("")

To execute local calls from the application and Servlet, the path must contain the Notes/Domino program directory, and the class path (classpath) must contain notes. jar. For example, when Domino is installed in "C: \ Lotus \ domino:

Set path: = % PATH %; C: \ Lotus \ domino
Set classpath: = % classpath %; C: \ Lotus \ domino \ notes. Jar
Notes. jar contains Lotus. Domino and Lotus. Domino. Local packages.

The notesthread class is required for local calls to manage threads. The notesthread class extends java. Lang. Thread and contains the initialization and termination code for Domino. You can use it in three different ways:

• Execute thread through inheritance
• Run the thread through the runnable interface.
• Use static methods to execute threads

Execute thread through inheritance

To execute a thread through inheritance, You need to extend notesthread (instead of thread), including the runnotes method (instead of the run method ). The notesthread thread can be started using the start method like other threads. This method is easy to use and error-prone.

Import Lotus. domino. *;
public class myclass extends notesthread
{< br> Public static void main (string argv [])
{< br> myclass T = new myclass ();
T. start ();
}< br> Public void runnotes () // entry point for notes thread
{< br> try
{< br> session S = notesfactory. createsession ();
// operational code goes here
}< br> catch (exception e)
{< br> E. printstacktrace ();
}< BR >}

Run the thread through the runnable interface.

To execute a thread through the runnable interface, you need to implement runnable and include the run method, which is exactly the same as other classes using the thread. This method can be used when you need to extend other classes and cannot extend the notesthread class.

Import Lotus. Domino .*;
Public class myclass implements runnable
{
Public static void main (string argv [])
{
Myclass T = new myclass ();
Notesthread Nt = new notesthread (runnable) t );
NT. Start ();
}
Public void run () // entry point for Thread
{
Try
{
Session S = notesfactory. createsession ();
// Operational code goes here
}
Catch (exception E)
{
E. printstacktrace ();
}
}
}

Use static methods to execute threads

To execute a thread through a static method, you need to call sinitthread () to initialize the thread and call stermthread () to end the thread. The call of stermthread () must be exactly the same as that of sinitthread. We recommend placing stermthread () in the "finally" block. Static methods are applicable to threads that cannot be inherited or that require event-driven control.

Import Lotus. Domino .*;
Public class myclass
{
Public static void main (string argv [])
{
Try
{
Notesthread. sinitthread (); // start thread
Session S = notesfactory. createsession ();
// Operational code goes here
}
Catch (exception E)
{
E. printstacktrace ();
}
Finally
{
Notesthread. stermthread (); // must terminate every thread
}
}
}

Each thread that calls a local call must initialize a notesthread object. It contains AWT threads that access Domino objects. The listener threads must use static methods because they cannot inherit from notesthread.

Applications that make both local and remote calls can dynamically decide when to use static methods sinitthread and stermthread. When a local thread is running, it can also be called remotely. However, do not use the objects in a session to call other sessions.

Avoid using multiple threads unless there are good reasons. The following principles should be observed:

• Domino objects are automatically shared, synchronized, and recycled between different threads in the same session. If each thread uses different sessions, these functions will be lost, and the synchronization and collection of objects must be clearly managed in each thread.
• Do not use dbdirectory across threads. ? Access to the same existing document in multiple threads is allowed, but access only in one thread simplifies memory management. If you restrict access to existing documents in one thread, You can recycle them without checking other threads ). Creating a new document in multiple threads is always safe, and the objects used can be recycled regardless of the status of other threads (recycle ).
• Brief table files are cached by thread. When multiple threads update the same profile, the modifications made by the last updated thread are saved.
• Note This When deleting a document, because other threads may need this document to traverse the view or document set.
• When the sub-object is used by other threads, the parent thread will end after all sub-threads have ended. Pay special attention to this when using Domino objects in the AWT event processor.

Remote Call

When createsession is called, the first parameter uses a non-null string, which indicates that the call is performed remotely. The first parameter indicates the computer on which the Domino server is located. For example:

Session S = notesfactory. createsession ("myhost.east.acme.com ")

Or

Session S = notesfactory. createsession ("myhost.east.acme.com: 63148 ")

The port number is specified in the following example, so that the Web service does not need to be started on the Domino server. For more information, see "obtain ior.

To execute remote calls from an application or servlet, the class path of the computer on which the program runs must include ncso. jar. Ncso. jar contains the Lotus. Domino package, Lotus. Domino. CSO package, Lotus. Domino. CORBA package, and ORB class. For the installed Domino designer and Domino server, ncso. jar is in the domino \ Java subdirectory under the domino data directory. If Domino Software is not installed on your computer, you must manually copy the file from another computer. The class path must contain ncso. jar, for example:

Set classpath: = % classpath %; C: \ Lotus \ domino \ data \ domino \ Java \ ncso. Jar

Programming

Notesthread is not used for remote calls. You only need to specify the host name and port number in createsession (optional ).

When no thread is used, the program is generally in the following format:

Import Lotus. Domino .*;
Public class myclass
{
Public static void main (string argv [])
{
Try
{
String host = "myhost.east.acme.com: 63148 ";
Session S = notesfactory. createsession (host );
// Operational code goes here
}
Catch (exception E)
{
E. printstacktrace ();
}
}
}

When a thread is used, the program is:

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. createsession (host );
// Operational code goes here
}
Catch (exception E)
{
E. printstacktrace ();
}
}
}

Management

You also need to configure the server for remote access to Domino. The computer running Domino must be accessible through the TCP/IP protocol. In the network settings of the computer, you need to check the settings of the Host Name and domain name in the TCP/IP attribute. You must be able to ping the Internet Name of the Domino server from the client computer. For example, if the host name of the server is myhost and the domain name is east.acme.com, the Internet Name of the server is myhost.east.acme.com. The following command must be able to get a valid response:

> Ping myhost.east.acme.com

In the Domino Directory (names. nsf), enter the above Internet name in the "fully qualified Internet host name" Field of the server document.

In the preceding programming example, the server Internet name is used as the first parameter of createsession. You can also use the IP address of the server.

To perform remote access, the diiop task must be started on the Domino server. HTTP tasks may also need to be started, depending on how the program gets the IOR. To confirm the port number used by HTTP and diiop, open the server document in the Domino Directory and enter "Internet port" under "Port ", the current port number is displayed under the Web tag and diiop tag. By default, the http port is 80 and the diiop port is 63148.

If you do not know the name of the database to be accessed (for example, to use. getfirstdatabase), you must have the permission to browse the database. You can set this permission under the "Internet Protocol"-"HTTP" label and set "allow HTTP client to" yes ".

To make sure that HTTP and diiop tasks are started on the server, you can add them to the servertasks parameter in the notes. ini file. For example, there should be a line like this in notes. ini:

Servertasks = Update, replica, router, amgr, adminp, calconn, sched, diiop, HTTP,
LDAP

If the server has been started, run the following console command to start these two tasks:

> Load HTTP
> Load diiop

You can also use the following console commands to stop these two tasks:

> Tell HTTP quit
> Tell diiop quit

Use this command to update the settings of the diiop task:

> Tell diiop refresh

Run this command to restart the HTTP task:

> Tell HTTP restart

Obtain ior

On the Domino server, IOR is a file named diiop_ior.txt, which is located in the domino \ HTML subdirectory under the domino data directory. Ior is an encoded string that contains the identification information for the server's CORBA access. The client decodes the IOR string and uses it to establish a remote connection.

By default, the remote client requests the IOR through the Web service, and then requests the session through the diiop port. The two requests can be processed separately. For example:

String ior = notesfactory. getior ("myhost.east.acme.com"); // get ior using web server port
Session S = notesfactory. createsessionwithior (IOR); // create session using diiop Port

It is equivalent:
Session S = notesfactory. createsession ("myhost.east.acme.com ");

In the call to notesfactory, you can add a colon and port number after the host name to specify the port used to obtain the IOR. Using this mechanism, you can obtain the IOR through the diiop port instead of the http port. For example:

String ior = notesfactory. getior ("myhost.east.acme.com: 63148"); // get ior using diiop Port
Session S = notesfactory. createsessionwithior (IOR); // create session using diiop Port

It can also be simplified:

Session S = notesfactory. createsession ("myhost.east.acme.com: 63148 ");

Note that you cannot use the diiop port to obtain files other than diiop_ior.txt.

If you use the Web Service port to obtain the IOR, the Web service must allow anonymous access. Open the server document. Under the "Port"-"Internet port"-"Web" label, set "anonymous" to "yes ".

Retrieving ior through the diiop port is a new feature of Notes/Domino 6. In this way, you do not have to allow anonymous access to the HTTP service, or even start the HTTP service.

You can also use other methods to obtain the IOR and then use createsessoinwithior. For example, you can directly copy the diiop_ior.txt file from the server computer to the client computer. If effective diiop_ior.txt already exists on the client, you can use the following code to establish a remote connection with the server:

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. createsessionwithior (IOR );
// Operational code goes here
}
Catch (exception E)
{
E. printstacktrace ();
}
}
}

Note that the IOR may change. The following actions will invalidate the original diiop_ior.txt:

• Change the diiop port number
• Enable or disable a diiop Port
• Change the server's TCP/IP address

To avoid this, open the server document and specify the Internet host name of the server in the Host Name/address field under the "Internet Protocol"-"diiop" tab.

This forces diiop_ior.txt to use the host name instead of the IP address. In this way, the IOR will not change as long as the host name does not change. You can also use the diiopiorhost parameter of notes. ini to force the host name to be used.

Access Control

The access level that the client program can obtain depends on the usage of createsession and the settings of the server/client. Access control is implemented in either of the following ways:

• Username and Internet password in the Domino Directory. This method can be used for both local and remote calls. For local calls, the access must be a Domino server.
• Current Notes ID (the ID specified by the keyfilename parameter in the notes. ini file)

This method can only be used for local calls. The program can be stored on either the Notes client or Domino server. Access through the Domino Directory

Using Domino

When accessing a directory, the code used determines whether to access it as an anonymous user or an existing user in the Domino Directory. In a notesfactory call, if only the host name is specified or an empty string is used as the user name and password, the server will be accessed as an anonymous user. For example:

Session S = notesfactory. createsession ("myhost.east.acme.com: 63148 ");

Or:

Session S = notesfactory. createsession ("myhost.east.acme.com: 63148 ","","");

To access the server as a domino user, you must specify the user name and Internet password in parameters 2 and 3 respectively. The username and password must match a personal document in the Domino Directory. For example:

Session S = notesfactory. createsession ("myhost.east.acme.com: 63148", "Jane Smith/East/Acme ",

"Tops3cr3t ");

When calling the Domino server locally, the host name should be blank: Session S = notesfactory. createsession ("", "Jane Smith/East/Acme", "tops3cr3t") to perform anonymous local calls, all three parameters should be blank:

Session S = notesfactory. createsession ("","","")

During local calling, the server does not have to run. The settings in the server documentation determine whether anonymous or user name/password access is allowed. In the server documentation, under the "Port"-"Internet port"-"diiop" label, the relationship between the verification option and the code is as follows:

 

The relationship between verification options and code is as follows: Code Verification options Createsession (host ,"","") Createsession (host, name, password) The name and password of the server must be set to "yes" to access the server.

For name and password verification, the name must be the user name in a personal document in the Domino Directory, And the password must be the Internet password in this personal document. The administrator can also set the "force use server access settings" option to "yes" to force diiop access to follow the "server access" setting under the security label of the server document.

The following fields in the server documentation can be used to control the security of Internet sessions. Essentially, the access permission for Internet sessions created by local or remote Java classes is equivalent to that for Web users.

 

The following fields in the server document can be used to control the security of Internet sessions. Domain Description Server access permission Access Server Users who make remote or local calls must be listed in this domain Prohibit access to the server If a user is listed in this domain, no remote or local connection can be established. Create databases and templates Can I use the background method to create a new database and template? Create a new copy Can I use the background method to create a duplicate database? Create a master Template Can I use the background method to create a master template? Programming restrictions Unlimited methods and operations Users listed in this field can run restricted Java methods on the Domino server *. If the user used by the program is not listed in this domain, you cannot execute these methods on the Domino server, such as accessing the file system of the Domino server, however, you can still execute various methods on the computer where the program is located, including accessing the local file system. The signature will represent the proxy run by others The proxy that runs as a Web user will run as a user in an Internet session The signature indicates the proxy that the caller of the proxy runs. The proxy that runs as a Web user will run as a user in an Internet session Internet access Internet Verification Restrict which names can be used as user names to log on

* For restrictions on the methods, see "restricted Lotus script and Java agent operations" in Domino 6 designer help ".

In the server documentation, the fields in the diiop label under "Port"-"Internet port" are described as follows:

 

Description of the fields in the diiop label under "Port"-"Internet port" in the server documentation Domain Description (Tcpi/IP) name and password Diiop authentication requires the user name and password (TCP/IP) Anonymous diiop User name and password not required for verification (SSL) name and password Diiop SSL authentication requires the user name and password (SSL) Anonymous Diiop SSL authentication does not require the user name and password Enforce server access settings Does diiop force server access settings under the security label?

The following notes. ini parameters also affect the security of Internet sessions established by remote or local Java classes:

 

The notes. ini parameter also affects the security of Internet sessions established by remote or local Java classes. Notes. ini settings Description Noambiguouswebnames When noambiguouswebnames = 1, if the username used to log on to diiop has multiple matches in the $ users view, the logon fails. Webnameauthentic When webnameauthentic = 1, the user name used to log on to diiop should be the user's full name. Nabweblookupview When nabweblookupview = "XXX" is set, Domino searches for the username used for Logon in the "XXX" view of the Domino Directory.

Note: In the database access control table, the "Maximum permissions of Internet users" setting also affects the permissions of Internet sessions. The permissions of login users of diiop cannot exceed this setting.

The server refreshes the secure cache every 30 minutes. After modifying the Security Settings, you can use the console command "Tell diiop refresh" to force refresh.

Access through the Notes ID

To access the server using the current Notes ID, do not specify any parameters when calling:

Session S = notesfactory. createsession ()

In this case, if you need to verify (such as when you open the database), a dialog box is displayed, prompting you to enter the password for the Notes ID. The used Notes ID is specified by the keyfilename variable in the first notes. ini file that can be found in the search path. For example, if notes. ini contains the following parameters, the program uses Admin. ID to access the server:

Keyfilename = Admin. ID

You must enter the password for this ID or press "cancel" to continue the program. You can also specify the second parameter as "(string) null", and specify the password for this Notes ID in the third parameter:

Session S = notesfactory. createsession (string) null, (string) null, "tops3cr3t ")

On the server, the above method restricts access by the reader domain. To perform full access, you can use the following method:

Session S = notesfactory. createsessionwithfullaccess ()

Or

Session S = notesfactory. createsessionwithfullaccess ("tops3cr3t ")

Conclusion

Now you know the basic methods for using Java applications to locally call and remotely call Domino objects. For more complex access methods, such as SSL encryption, Servlet, connection pool, single logon, firewall, timeout control, resource recovery, and problem diagnosis, see the followingArticle:

Http://www-10.lotus.com/ldd/today.nsf/lookup/Java_access_2 (USA)