5.4 Domino objects for Java API

< Day Day Up >

Java Domino classes are created by modifying some of the LotusScript Extension (LSX) architecture to include a Java "adapter" to compose the new Java Domino classes. The Java Domino classes have similar functions to some of the LotusScript Domino back-end objects. You can use these classes from any Java program. Internally, Java Notes classes execute the same C++ code as the LotusScript Domino back-end objects, only the language syntax is different.

Domino objects architecture

The Domino objects class architecture is based on a conceptual containment model, where the containment model defines an object's scope. A container object is always used to access objects it contains. For example, you use a Session object to get Database objects, and a Database object to create Document objects. In Java, you cannot create lotus.domino objects using the "new" modifier. All lotus.domino objects must be created with lotus.domino methods that flow from the root Session object. This is illustrated in Figure 5-11.

click to expand
Figure 5-11: Domino Object Model

Since one Domino object may be contained by several others, a full object diagram is beyond the scope of this document. Complete details about all Domino objects is in the documentation for Domino Toolkit for Java. However, some of the key containment relationships are as shown in Figure 5-11.

In practice, you will implement Notes API to your portlet code, adding a NCSO.jar/NCSOW.jar file (for remote connection) or NOTES.jar (for local connection) to the library. These files can be found in the Domino Toolkit for Java or on the Domino server.

Type import lotus.domino.*; into your portlet code, and you are able to use Notes API classes in your code.

All Domino classes have methods and properties.

Methods

Method names are written with the first character in lower case (for example, getFirstDocument). Of course, there are exceptions (such as FTSearch). One of the most important methods every Domino object has is recycle. The recycle method unconditionally destroys an object and returns its memory to the system.

Properties

To access properties in Java, you also have to use methods. In Java, properties are implemented through methods, known as accessors, which use the following naming convention: The name of a method used to get the value of a non-boolean property is the name of the property prefixed with get.

Recycling Domino objects

The recycle method unconditionally destroys an object and returns its memory to the system. All lotus.domino classes contain the following method:

    public void recycle()

Session contains the following method, where the vector contains the Domino Objects to be recycled. This method effectively batches recycle operations and is especially efficient for remote (IIOP) calls.

    public void recycle(java.util.Vector objects)

You recycle an object by calling the recycle method, for example doc.recycle(); where doc is the object to be recycled.

Important:

Java has no knowledge of the heavyweight back-end Domino objects, only the lightweight Java objects representing them. Garbage collection has no effect on Domino objects unless you first explicitly recycle them.

If your system appears to have memory problems, try to recycle, but adhere to the following guidelines:

Recycle an object only if it is no longer needed.
Recycle an object in the same thread in which it is created.
Recycling a parent recycles all the children.
In Session, call recycle only after all threads exit (local).
Loops enumerating documents or items are good candidates for recycling.

Important:

In a remote (IIOP) environment, recycle releases resources on the server. Although a client-side cache exists, the Java object can no longer communicate with its remote counterpart.

In a remote (IIOP) environment, recycle can be called from any thread on any object. Results are undefined if you attempt to use a recycled object. No error is guaranteed.

Commonly used Domino classes

Here we have gathered some information about the most commonly used Domino classes, which you may need in your Domino portlet developing work.

Complete details about the Domino Java API are in Domino Toolkit for Java product documentation.

Session class

Session class is the root of the Domino Objects containment hierarchy, providing access to the other Domino objects, and representing the Domino environment of the current Java program.

Important:

You must always define at least session to Domino to get any further.

For stand-alone applications, like portlets, use one of the NotesFactory.createSession() methods.

For a local session, the Session object represents the machine on which the code is running. A reference to the current server, such as a null server parameter, means the local Notes/Domino environment. You can access servers connected to the local environment by specifying their names.

For a remote (IIOP) session, the Session object represents the Domino server handling the remote requests. A reference to the current server, such as a null server parameter, means that Domino server. You cannot access other servers.

You have different ways to do that; several are illustrated in the following examples. More samples are in the Domino Toolkit for Java documentation.

Example 5-1: Creating session to Domino using servername

 session = NotesFactory.createSession("<servername>","<username>","<password>")

Example 5-2: Creating session to Domino using IOR

 session = NotesFactory.createSessionWithIOR("<IOR>","<username>","<password>")

Session class has properties like Addresbooks, NotesVersion, Platform, or UserName.

Some of the most useful methods are getDatabase, getDbDirectory, getEnvirnomentalValue, and recycle.

Database class

Database class represents a Domino database. A database must be open before you can use all the properties and methods in the corresponding database object. In most cases, the class library automatically opens a database for you.

Use isOpen properties to do the proper checking and add handling for the exceptions.

Notes throws an exception when you attempt to perform an operation for which the user does not have appropriate access. The NotesException class is discussed later in this section.

The properties and methods that you can successfully use on a Database object are determined by the user's access level to the database, as specified in the database access control list. The ACL determines if the user can open a database, add documents to it, remove documents from it, modify the ACL, and so on.

The user's access level to the server on which the database resides is determined by the Server document in the Domino Directory.

Example 5-3: Using the isOpen method

 Database db = session.getDatabase("servername", "names");       if (!db.isOpen())           getPortletLog().debug("Database does not exist on server");       else           getPortletLog().debug("Title of the database is : \"" + db.getTitle()+ "\"") ;

The Database class has properties like getACL, Agents, Views, and Forms, just to mention a few.

The Database class includes methods like createDocument, getDocumentByID, getView, and replicate, among others.

View class

The View class represents a view or folder of a database and provides access to documents within it.

You access a view or folder through the Database object that contains it, in one of the following ways:

To access a view or folder when you know its name or alias, use getView.
To access all the views and folders in a database, use getViews.

Returned is a View object or a vector of View objects that represent public views and folders in the database. To access a view or folder when you have a view entry, use getParent in ViewEntry.

A View object provides access to ViewEntry, ViewEntryCollection, and ViewNavigator objects:

A ViewEntry object represents a row in the view and can be a document, category, or total. A document entry provides a handle to the associated Document object.
A ViewEntryCollection object provides access to selected or all document ViewEntry objects. (Excluded are category and total ViewEntry objects.)
A ViewNavigator object provides methods for navigating through selected or all ViewEntry and Document objects.

A View object provides access to ViewColumn objects, which contain information on each column in the view.

The code in Example 5-4 finds the "($All)" hidden view in a database, gets the first document in the view, and finally gets an item value from the document.

Example 5-4: Accessing the views of the database.

 Database db = session.getDatabase ("servername", "names");       View view = db.getView("($All)");       Document doc = view.getFirstDocument();           getPortletLog().debug((doc.getItemValueString("Subject"));

The View class has properties that include aliases, columns, iscalendar, and Rowlines, among others.

Some of the View class methods are FTSearch, getdocumentByKey, getFirstDocument, and getChild.

Document class

The Document class represents a document in a database.

To create a new Document object, use createDocument in Database.

To access existing documents, do one of the following:

To get all the documents in a database, use getAllDocuments in Database.
To get a document based on its position in a view, use a View object.
To get a document based on its position in a response hierarchy, use a View object. To get all documents that are responses to a particular document, use getResponses in Document. To get a response document's parent document, use getParentDocumentUNID in Document followed by getDocumentByUNID in Database.
To get all the documents that match a full-text search query, use FTSearch in Database or FTSearch in View.
To get all the documents in a database that meet search criteria, where the criteria are defined using the formula language, use search in Database.
To get a document based on its Note ID or UNID, use getDocumentByID or getDocumentByUNID in Database.

Once you have a view, you can navigate to a specific document using methods in the View class.

Once you have a collection of documents, you can navigate to a specific document using methods in the DocumentCollection class.

Important:

After you create, modify, or delete a document, you must save the changes by calling the save method. If you don't call save before the program finishes, all of your changes to a Document are lost.

If you create and save a new document without adding any items to it, the document is saved with one item "$UpdatedBy". This item contains the name of the creator of the document.

The code in Example 5-5 first creates a new document and then sets values for two fields in the document. Finally, the code saves the document.

Example 5-5: Use of Document class

      Document doc = db.createDocument();      doc.replaceItemValue("Form", "Main Topic");      doc.replaceItemValue("Subject", "New building");      doc.save(true,true);

Item class

The Item class represents a discrete value or set of values in a document.

The client interface displays items in a document through fields on a form. When a field on a form and an item in a document have the same name, the field displays the item (for example, the Subject field displays the Subject item).

All items in a document are accessible programmatically, regardless of what form is used to display the document in the user interface.

To create a new Item object:

To create a new Item object from scratch, use replaceItemValue in Document. The method appendItemValue also creates an item, but creates another item of the same name if the specified item exists. Use replaceItemValue unless your intent is to create another item with the same name (not recommended).
To create a new Item object from one that already exists, use copyItemToDocument, copyItem, or replaceItemValue in Document.

You must call save on the document if you want the modified document to be saved to disk. The document won't display the new item in the user interface unless there is a field of the same name on the form used to display the document.

Explicitly call setSummary and specify true if you want the value to be displayed in a view or folder.

To access Item objects:

To access an item when you know its name, use getFirstItem in Document.
To access all the items in a document, use getItems in Document.

Document has methods to access items without creating an Item object. You need to know the name of the item.

To get an item's value, use getItemValue.
To create a new item or set an item's value, use replaceItemValue.
To check for the existence of a particular item in a document, use hasItem.
To delete an item from a document, use removeItem.

RichTextItem inherits the properties and methods of Item and has additional properties and methods you can use to manipulate rich text.

After you create or modify an item, you must save the changes by calling the parent document's save method.

If you don't call save before the program finishes, all of your changes to an Item object are lost.

The code in Example 5-6 first creates a document, creates a text item without specifying data type and then one with a data type. isSummary(True) specifies that the item can be shown in a view. Finally, the document is saved.

Example 5-6: Using Item class in code

    Document doc = db.createDocument();     // Create text item with implied data type       doc.replaceItemValue("Subject", "Creating items ...");     // Create text item explicitly specifying data type       Item textItem = doc.replaceItemValue("textItem", null);      textItem.setValueString("Finland");      textItem.setSummary(true);      // Save the document      doc.save(true, true);

Item class includes properties such as isAuthors, Lastmodified, Reader, and ValueString.

Some of the Item class methods are copyItemToDocument, getMIMEEntity, parseXML, and transformXML.

ACL class

ACL class represents the access control list (ACL) of a database. Every Database object contains an ACL object representing the access control list of that database. To get it, use getACL in Database, as shown in Example 5-7. getFirstEntry() returns an ACL entry object.

Example 5-7: Example using ACL class

       Database db = session.getDatabase("servername", "names");       if (!db.isOpen())           getPortletLog().debug("Database does not exist on server");       else           getPortletLog().debug("Title of the database is : \"" + db.getTitle()+ "\"") ;       ACL acl = db.getACL();       ACLEntry entry = acl.getFirstEntry();       do {          getPortletLog().debug(entry.getName()); }       while ((entry = acl.getNextEntry(entry)) != null);

The Database class has three methods you can use to access and modify an ACL without getting an ACL object: queryAccess, grantAccess, and revokeAccess. However, using these methods at the same time that an ACL object is in use may produce errors.

ACL class properties include Roles, InternetLevel, and UniformAccess.

Among the ACL classes are methods like addRole, createACLEntry, RemoveACLEntry, and save.

NotesException class

The NotesException class extends java.lang.Exception to include exception handling for Domino. The NotesError class defines public static final variables for Domino error codes.

To catch a Domino exception, specify the parameter of the catch clause as type NotesException. The NotesException class contains the following public variables:

NotesException.id, of type int, contains the error code.
NotesException.text, of type String, contains the error text.

The following code example demonstrates how to catch a Domino exception. The code prints the error code and error text if a Domino exception is thrown.

Example 5-8: Using NotesExcpetion

 public Collection testViews()       throws NotesException ArrayList views = new ArrayList();       try {          View view = db.getView("ViewName"");          Document doc = view.getFirstDocument();          while (doc != null) {             String systemName =doc.getItemValueString("FieldOne");             String showName =doc.getItemValueString("FieldTwo");                       doc = view.getNextDocument(doc);          }       } catch (NotesException e) {          Log.error(this.getClass(),"Could not get the list of views. NotesException occured: id = "                 + e.id+ ", text = "+ e.text,e);    }

< Day Day Up >