Writing Java Applications

To write standalone Java applications that access Domino, you must download and install the Java Development Kit (JDK) from http://java.sun.com. The Gold release of Notes and Domino 6 supports version 1.3.1 of the JDK, although this might change with each maintenance release. As of this writing, the latest SDK is version 1.4.1, but until Notes explicitly supports SDK 1.4 and later, you should probably download the latest 1.3 version.

After you've installed the SDK, you need to make sure that your PATH statement includes the SDK bin directory. Also, if you're using Notes locally and not CORBA, you must add the Notes directory to your path. Here's an example:

set PATH=%PATH%;c:lotus
otes;c:jdk1.3.1in

You also need to append your Java CLASSPATH to include NOTES.JAR (if you're using Notes locally) or NCSO.JAR (if you're using CORBA).

Be sure to restart your machine or log back in to make these changes effective.

Java applications must run in their own JVM, so we'll use Sun's java.exe, which you can find in the JDK's bin directory, to run our application. To run a Java application, drop to the command prompt and type Java followed by the name of the class you want to run as well as any command-line parameters you want to pass into the class. If you want to run a Java program called AddRecord and pass one command-line parameter, you'd type

Java AddRecord 887432

If you have trouble running Java programs, you should check your PATH and CLASSPATH system variables to ensure that they include the Java installation on your system. When this is configured correctly, you can run your Java applications from any directory on your system.

Using FavoriteBooks

The example in this section, FavoriteBooks, is a standalone Java application that opens a Domino database and displays a list of favorite books at the command prompt. This application takes several parameters that dictate how the application runs and what it does. The first parameter is required and is used to determine the set of books shown. To display all the books, pass ALL . To search the database, enter a query, such as the name of an author or the title of a book. We use the FTSearch method of the Database class to search the database for it.

Keep in mind that if you want to enter a query that has spaces in it, you must enclose the text in quotes so that Java doesn't think you're trying to pass multiple parameters.

The remaining three parameters, Address , Username , and Password , are optional and are used to specify a remote server, username, and password if CORBA is to be used. If the Address parameter isn't specified, a local connection will be made.

To run this application on a system that has Notes/Domino installed and also contains the Books database, enter the following:

java FavoriteBooks all

This should generate output similar to that shown in Figure 19.1.

Figure 19.1. Output from the FavoriteBooks application.

When FavoriteBooks is executed, it either generates a list of books or returns an informative error message.

FavoriteBooks Source

When FavoriteBooks is run, it starts the main() method, which tries to create an instance of the FavoriteBooks class and passes the command-line parameters entered in pArgs to the FavoriteBooks constructor.

The constructor parses the arguments and ensures that the proper parameters were passed. Otherwise , an IllegalArgumentException is thrown and the program terminates after displaying an error message to the user .

What happens next depends on the address parameter. If none was supplied, this is a local run, so the app object is passed to a NotesThread constructor. Otherwise, it's a CORBA run and the app object is passed to a normal Thread constructor. Note that the FavoriteBooks class implements Runnable , so either is allowed. The new thread is started, which results in run() being called.

In run() , the address field is again checked to determine whether to create a CORBA session or a normal one. The Books database is then opened and listBooks() is called to begin the process of writing the list of books. If a book title is supplied as a parameter, the FTSearch() method of the database class is used to find documents that match; otherwise, all documents are displayed.

Listing 19.1 illustrates writing a Java application to process data stored in a Domino database.

Listing 19.1 A Standlone Java Application That Lists the Books in a Domino Database

import lotus.domino.*; public class FavoriteBooks implements Runnable{ // constants static final String NOTES_EXCEPTION_MSG = "Notes Exception "; static final String LISTING_ALL_DOCS_MSG = "Listing All Books"; static final String LISTING_DOCS_FOR_MSG = "Listing Books For: "; static final String MISSING_USER_PASS_MSG = "Missing user name or password"; static final String BOOK_MSG="Book: "; static final String BAD_CMD_PARAM_MSG="Enter ALL for all books, or the title of a book"; static final String SYNTAX_ERROR_MSG = "Use the following form: java FavoriteBooks {ALL} [

]"; // item name constants static final String AUTHOR_ITEM = "Author"; static final String TITLE_ITEM = "Title"; static final String PUBDATE_ITEM = "PubDate"; // value constants static final String BOOKS_DB_NAME = "FileLibrary.NSF"; static final String ALL_PARAM = "ALL"; // Domino objects protected Session m_nsCurrent; protected Database m_ndbBooks; protected String m_strCmd; protected String m_strCmdParam; protected String m_strAddress; protected String m_strUser; protected String m_strPassword; public static void main(String[] pArgs){ Thread thrCurrent; try{ // initialize runnable app object with command-line args FavoriteBooks fbCurrent = new FavoriteBooks(pArgs); // create local or remote thread for runnable app object if (fbCurrent.m_strAddress != null){ thrCurrent = new Thread(fbCurrent); }else{ thrCurrent = new NotesThread(fbCurrent); } thrCurrent.start(); } catch(IllegalArgumentException e){ // print exception message & syntax reminder System.out.println(); System.out.print(e.getMessage() + " - "); System.out.println(SYNTAX_ERROR_MSG); } } public FavoriteBooks(String[] pArgs) throws IllegalArgumentException { // parse command-line arguments in reverse order. switch(pArgs.length){ case 4: m_strPassword = pArgs[3]; case 3: m_strUser = pArgs[2]; case 2: m_strAddress = pArgs[1]; case 1: m_strCmdParam = pArgs[0]; } // no parameter specified if (m_strCmdParam == null){ throw new IllegalArgumentException(BAD_CMD_PARAM_MSG); } // if no user or password if (m_strAddress != null && (m_strUser == null m_strPassword == null)){ throw new IllegalArgumentException(MISSING_USER_PASS_MSG); } } public void run(){ try{ // if no address, create a normal session, otherwise create a CORBA one. if (m_strAddress == null){ m_nsCurrent = NotesFactory.createSession(); }else{ m_nsCurrent = NotesFactory.createSession(m_strAddress, m_strUser, m_strPassword); } m_ndbBooks = m_nsCurrent.getDatabase(m_nsCurrent.getServerName(), BOOKS_DB_NAME); listBooks(); } catch(NotesException e){ System.err.println( NOTES_EXCEPTION_MSG + e.id + " -- " + e.text ); } } public void listBooks() throws NotesException{ DocumentCollection ndcBooks; Document ndocBook; long lngBooks=0; System.out.println(); // if command param is "ALL" then get all documents if (m_strCmdParam.equalsIgnoreCase(ALL_PARAM)){ ndcBooks = m_ndbBooks.getAllDocuments(); System.out.println(LISTING_ALL_DOCS_MSG + " ... "); }else{ ndcBooks = m_ndbBooks.FTSearch(m_strCmdParam); System.out.println(LISTING_DOCS_FOR_MSG + m_strCmdParam + " ... "); } ndocBook = ndcBooks.getFirstDocument(); while(ndocBook!=null){ lngBooks++; writeLine(ndocBook); ndocBook = ndcBooks.getNextDocument(); } System.out.println(lngBooks + " found"); } public void writeLine(Document ndocBook) throws NotesException{ System.out.print(BOOK_MSG + ndocBook.getItemValueString(TITLE_ITEM)); System.out.print(" -- " + ndocBook.getItemValueString(AUTHOR_ITEM) + " -- "); System.out.print(ndocBook.getItemValueString(PUBDATE_ITEM)); System.out.println(); } }

You should also be aware that you're not restricted to developing command-line apps such as this one. With Java's Abstract Windowing Toolkit (AWT), you can build full-featured GUI apps. Additionally, you can use the Swing class library to build powerful, easy-to-use windowing interfaces.