de.bea.domingo
Interface DBaseDocument

All Superinterfaces:

DBase, java.io.Serializable

All Known Subinterfaces:

DDocument, DProfileDocument

All Known Implementing Classes:

BaseDocumentHttp, BaseDocumentProxy, DocumentHttp, DocumentProxy, MockDocument, ProfileDocumentProxy

public interface DBaseDocument
extends DBase

Base interface for all concrete document interfaces.

Author:

Kurt Riede

Method Summary

DItem	appendItemValue(java.lang.String name) Creates a new empty item in a document.
DItem	appendItemValue(java.lang.String name, java.util.Calendar value) Creates a new item in a document and sets the item value.
DItem	appendItemValue(java.lang.String name, double value) Creates a new item in a document and sets the item value.
DItem	appendItemValue(java.lang.String name, int value) Creates a new item in a document and sets the item value.
DItem	appendItemValue(java.lang.String name, java.util.List values) Creates a new item in a document and sets the item value.
DItem	appendItemValue(java.lang.String name, java.lang.String value) Creates a new item in a document and sets the item value.
boolean	computeWithForm() Validates a document by executing the default value, translation, and validation formulas, if any are defined in the document form.
boolean	computeWithForm(boolean raiseError) Validates a document by executing the default value, translation, and validation formulas, if any are defined in the document form.
void	copyAllItems(DBaseDocument doc, boolean replace) Copies all items in the current document into the destination document.
DBaseItem	copyItem(DBaseItem item) Copies an item into the current document and optionally assigns the copied item a new name.
DBaseItem	copyItem(DBaseItem item, java.lang.String name) Copies an item into the current document and optionally assigns the copied item a new name.
DDocument	createReplyMessage(boolean toAll) Creates a new document that is formatted as a reply to the current document.
DRichTextItem	createRichTextItem(java.lang.String name) Creates a new rich text item in a document.
void	encrypt() Encrypts a document.
java.lang.String	generateXML() Generates an XML representation of a document to the Writer.
void	generateXML(java.io.Writer writer) Generates an XML representation of a document to the Writer.
DEmbeddedObject	getAttachment(java.lang.String filename) Returns a representation of a file attachment.
java.util.List	getAttachments() Returns all embedded objects that are attachments.
java.util.List	getAuthors() The names of the people who have saved a document.
java.util.List	getColumnValues() A list of values, each element of which corresponds to a column value in the document's parent view.
java.util.Calendar	getCreated() The date a document was created.
java.util.Iterator	getEmbeddedObjects() Returns all embedded objects.
java.util.List	getEncryptionKeys() Returns the key(s) used to encrypt a document.
DBaseItem	getFirstItem(java.lang.String name) Returns the first item of a specified name in a document.
java.util.Iterator	getItems() Iterator for all items in a document.
java.util.List	getItemValue(java.lang.String name) Returns the value of an item.
java.lang.Object	getItemValueCustomData(java.lang.String name) Returns as an object the value of an item containing custom data.
java.lang.Object	getItemValueCustomData(java.lang.String name, java.lang.String dataTypeName) Returns as an object the value of an item containing custom data.
byte[]	getItemValueCustomDataBytes(java.lang.String name, java.lang.String dataTypeName) Returns as a byte array the value of an item containing custom data.
java.util.Calendar	getItemValueDate(java.lang.String name) Returns the value of an item with a single Calendar value.
DDateRange	getItemValueDateRange(java.lang.String name) Returns the value of an item with two Calendar value.
java.util.List	getItemValueDateTimeArray(java.lang.String name) Returns the value of a date-time item in a document.
java.lang.Double	getItemValueDouble(java.lang.String name) Returns the value of an item with a single double value.
java.lang.Integer	getItemValueInteger(java.lang.String name) Returns the value of an item with a single int value.
int	getItemValueSize(java.lang.String name) Returns the number of values of an item.
java.lang.String	getItemValueString(java.lang.String name) Returns the value of an item with a single text value.
java.util.Calendar	getLastAccessed() The date a document was last modified or read.
java.util.Calendar	getLastModified() The date a document was last modified.
java.util.List	getLockHolders() The names of the holders of a lock.
DDatabase	getParentDatabase() Return the database that contains a document.
java.util.List	getReceivedItemText() Gets the text values of the Received items in a mail document.
java.lang.String	getSigner() The name of the person who created the signature, if a document is signed.
int	getSize() The size of a database, in bytes.
java.lang.String	getVerifier() The name of the certificate that verified a signature, if a document is signed.
boolean	hasEmbedded() Indicates whether a document contains one or more embedded objects, object links, or file attachments.
boolean	hasItem(java.lang.String name) Indicates whether an item exists in the document.
boolean	isDeleted() Indicates whether a Document object represents an existing document (not a deletion stub) on an ongoing basis.
boolean	isEncrypted() Indicates whether a document is encrypted.
boolean	isEncryptOnSend() Indicates whether a document is encrypted when mailed.
boolean	isProfile() Indicates whether a Document object is a profile document.
boolean	isSaveMessageOnSend() Indicates whether a document is saved to a database when mailed.
boolean	isSentByAgent() Indicates whether a document was mailed by a Domino program.
boolean	isSigned() Indicates whether a document contains a signature.
boolean	isSignOnSend() Indicates whether a document is signed when mailed.
boolean	isValid() Indicates whether a Document object represents an existing document (not a deletion stub) initially.
boolean	lock() Locks a document.
boolean	lock(boolean provisionalOk) Locks a document.
boolean	lock(java.util.List names) Locks a document.
boolean	lock(java.util.List names, boolean provisionalOk) Locks a document.
boolean	lock(java.lang.String name) Locks a document.
boolean	lock(java.lang.String name, boolean provisionalOk) Locks a document.
boolean	lockProvisional() Locks a document provisionally.
boolean	lockProvisional(java.util.List names) Locks a document provisionally.
boolean	lockProvisional(java.lang.String name) Locks a document provisionally.
void	recycle() The recycle method unconditionally destroys an object and returns its memory to the system.
boolean	remove() Permanently removes a document from a database.
boolean	remove(boolean force) Permanently removes a document from a database.
void	removeItem(java.lang.String name) Removes an item from a document.
boolean	removePermanently(boolean force) Permanently deletes a document from a database, doing a hard deletion even if soft deletions are enabled.
boolean	renderToRTItem(DRichTextItem richtextitem) Creates a picture of a document and places it into a rich-text item that you specify.
DItem	replaceItemValue(java.lang.String name, java.util.Calendar value) Replaces all items of the specified name with one new item, which is assigned the specified value.
DItem	replaceItemValue(java.lang.String name, java.util.Calendar calendar1, java.util.Calendar calendar2) Replaces all items of the specified name with one new item, which is assigned the specified value.
DItem	replaceItemValue(java.lang.String name, DDateRange value) Replaces all items of the specified name with one new item, which is assigned the specified value.
DItem	replaceItemValue(java.lang.String name, double value) Replaces all items of the specified name with one new item, which is assigned the specified value.
DItem	replaceItemValue(java.lang.String name, java.lang.Double value) Replaces all items of the specified name with one new item, which is assigned the specified value.
DItem	replaceItemValue(java.lang.String name, int value) Replaces all items of the specified name with one new item, which is assigned the specified value.
DItem	replaceItemValue(java.lang.String name, java.lang.Integer value) Replaces all items of the specified name with one new item, which is assigned the specified value.
DItem	replaceItemValue(java.lang.String name, java.util.List values) Replaces all items of the specified name with one new item, which is assigned the specified value.
DItem	replaceItemValue(java.lang.String name, java.lang.String value) Replaces all items of the specified name with one new item, which is assigned the specified value.
DItem	replaceItemValue(java.lang.String name, java.util.TimeZone value) Replaces all items of the specified name with one new item, which is assigned the specified value.
DItem	replaceItemValueCustomData(java.lang.String name, java.lang.Object obj) Replaces all items of the specified name with one new item, which is assigned custom data from a byte array.
DItem	replaceItemValueCustomData(java.lang.String name, java.lang.String type, java.lang.Object obj) Replaces all items of the specified name with one new item, which is assigned custom data from a byte array.
DItem	replaceItemValueCustomDataBytes(java.lang.String name, java.lang.String type, byte[] bytes) Replaces all items of the specified name with one new item, which is assigned custom data from a byte array.
boolean	save() Saves any changes you have made to a document.
boolean	save(boolean force) Saves any changes you have made to a document.
boolean	save(boolean force, boolean makeresponse) Saves any changes you have made to a document.
void	setEncryptionKeys(java.util.List keys) Sets the key(s) used to encrypt a document.
void	setUniversalID(java.lang.String unid) The universal ID, which uniquely identifies a document across all replicas of a database.
void	unlock() Unlocks a document.

Methods inherited from interface de.bea.domingo.DBase

equals, hashCode, toString

Method Detail

getParentDatabase

DDatabase getParentDatabase()

Return the database that contains a document.

Returns:

the database that contains a document

getFirstItem

DBaseItem getFirstItem(java.lang.String name)

Returns the first item of a specified name in a document.

A document may contain more than one item of the same name. To access other than the first item, use the Items property.

If the value of a field is computed for display, the value is not stored as an item and is inaccessible from a Document object. In some cases, you can access the field value another way. For example, if a document has a DateComposed field computed for display with the formula @Created, use getCreated.

Using this method to get normal items (non-rich text)
To get a normal item, explicitly cast the return value from getFirstItem to DItem.

 DDocument doc;
 //...set value of doc...
 DItem item = (DItem)doc.getFirstItem("Body");
 

Using this method to get rich text items
To get a rich text item, explicitly cast the return value from getFirstItem to DRichTextItem.

 DDocument doc;
 //...set value of doc...
 DRichTextItem rtitem = (DRichTextItem)doc.getFirstItem("Body");
 

Parameters:

name - name of an item

Returns:

DBaseItem

getItems

java.util.Iterator getItems()

Iterator for all items in a document.

Note

Values set as int, are handled (by Notes) as a type Number and returned to Java as a Double.

Returns:

Iterator for all items in a document. These are normal DItem as well as DRichTextItems

getCreated

java.util.Calendar getCreated()

The date a document was created.

Returns:

Calendar created date

appendItemValue

DItem appendItemValue(java.lang.String name)

Creates a new empty item in a document. A empty item has a value of type String that is an empty String ("").

Note
In general, replaceItemValue is favored over appendItemValue. If an item of the same name already exists in a document, appendItemValue creates a second item of the same name, and the duplicate items are not accessible through most methods. If you are creating a new document, appendItemValue is safe.

Parameters:

name - name of an item

Returns:

DItem

appendItemValue

DItem appendItemValue(java.lang.String name,
                      java.lang.String value)

Creates a new item in a document and sets the item value.

Note
In general, replaceItemValue is favored over appendItemValue. If an item of the same name already exists in a document, appendItemValue creates a second item of the same name, and the duplicate items are not accessible through most methods. If you are creating a new document, appendItemValue is safe.

Parameters:

name - name of an item

value - The value of the new item.

Returns:

DItem

appendItemValue

DItem appendItemValue(java.lang.String name,
                      int value)

Creates a new item in a document and sets the item value.

Note
In general, replaceItemValue is favored over appendItemValue. If an item of the same name already exists in a document, appendItemValue creates a second item of the same name, and the duplicate items are not accessible through most methods. If you are creating a new document, appendItemValue is safe.

Note

The value given as int is handled (by Notes) as a type Number and returned to Java as a Double.

Parameters:

name - name of an item

value - The value of the new item.

Returns:

DItem

appendItemValue

DItem appendItemValue(java.lang.String name,
                      double value)

Creates a new item in a document and sets the item value.

Note
In general, replaceItemValue is favored over appendItemValue. If an item of the same name already exists in a document, appendItemValue creates a second item of the same name, and the duplicate items are not accessible through most methods. If you are creating a new document, appendItemValue is safe.

Parameters:

name - name of an item

value - The value of the new item.

Returns:

DItem

appendItemValue

DItem appendItemValue(java.lang.String name,
                      java.util.Calendar value)

Creates a new item in a document and sets the item value. The milliseconds are cut off.

Note
In general, replaceItemValue is favored over appendItemValue. If an item of the same name already exists in a document, appendItemValue creates a second item of the same name, and the duplicate items are not accessible through most methods. If you are creating a new document, appendItemValue is safe.

Parameters:

name - name of an item

value - The value of the new item.

Returns:

DItem

appendItemValue

DItem appendItemValue(java.lang.String name,
                      java.util.List values)

Creates a new item in a document and sets the item value.

Note
In general, replaceItemValue is favored over appendItemValue. If an item of the same name already exists in a document, appendItemValue creates a second item of the same name, and the duplicate items are not accessible through most methods. If you are creating a new document, appendItemValue is safe.

Parameters:

name - name of an item

values - The value of the new item as a list of String, Integer, Double, or java.util.Calendar elements

Returns:

DItem

replaceItemValue

DItem replaceItemValue(java.lang.String name,
                       java.lang.String value)

Replaces all items of the specified name with one new item, which is assigned the specified value.

If the document does not contain an item with the specified name, this method creates a new item and adds it to the document.

Parameters:

name - name of an item

value - The value of the new item.

Returns:

DItem

replaceItemValue

DItem replaceItemValue(java.lang.String name,
                       int value)

Replaces all items of the specified name with one new item, which is assigned the specified value.

If the document does not contain an item with the specified name, this method creates a new item and adds it to the document.

Parameters:

name - name of an item

value - The value of the new item.

Returns:

DItem

replaceItemValue

DItem replaceItemValue(java.lang.String name,
                       java.lang.Integer value)

Replaces all items of the specified name with one new item, which is assigned the specified value.

If the document does not contain an item with the specified name, this method creates a new item and adds it to the document.

Parameters:

name - name of an item

value - The value of the new item.

Returns:

DItem

replaceItemValue

DItem replaceItemValue(java.lang.String name,
                       double value)

Replaces all items of the specified name with one new item, which is assigned the specified value.

If the document does not contain an item with the specified name, this method creates a new item and adds it to the document.

Parameters:

name - name of an item

value - The value of the new item

Returns:

DItem

replaceItemValue

DItem replaceItemValue(java.lang.String name,
                       java.lang.Double value)

Replaces all items of the specified name with one new item, which is assigned the specified value.

If the document does not contain an item with the specified name, this method creates a new item and adds it to the document.

Parameters:

name - name of an item

value - The value of the new item

Returns:

DItem

replaceItemValue

DItem replaceItemValue(java.lang.String name,
                       java.util.Calendar value)

Replaces all items of the specified name with one new item, which is assigned the specified value.

If the document does not contain an item with the specified name, this method creates a new item and adds it to the document.

The milliseconds are cut off.

Parameters:

name - name of an item

value - The value of the new item

Returns:

DItem

replaceItemValue

DItem replaceItemValue(java.lang.String name,
                       java.util.TimeZone value)

Replaces all items of the specified name with one new item, which is assigned the specified value.

If the document does not contain an item with the specified name, this method creates a new item and adds it to the document.

Parameters:

name - name of an item

value - The value of the new item

Returns:

DItem

replaceItemValue

DItem replaceItemValue(java.lang.String name,
                       DDateRange value)

Replaces all items of the specified name with one new item, which is assigned the specified value.

If the document does not contain an item with the specified name, this method creates a new item and adds it to the document.

If both calendars are null, an item with an empty string is created. If only one calendar is not null, this calendar is stored as a single date value.

The milliseconds are cut off.

Parameters:

name - name of an item

value - The value of the new item

Returns:

DItem

replaceItemValue

DItem replaceItemValue(java.lang.String name,
                       java.util.Calendar calendar1,
                       java.util.Calendar calendar2)

Replaces all items of the specified name with one new item, which is assigned the specified value.

If the document does not contain an item with the specified name, this method creates a new item and adds it to the document.

If both calendars are null, an item with an empty string is created. If only one calendar is not null, this calendar is stored as a single date value.

The milliseconds are cut off.

Parameters:

name - name of an item

calendar1 - start date/time of range

calendar2 - end date/time of range

Returns:

DItem

replaceItemValue

DItem replaceItemValue(java.lang.String name,
                       java.util.List values)

Replaces all items of the specified name with one new item, which is assigned the specified value.

If the document does not contain an item with the specified name, this method creates a new item and adds it to the document.

Parameters:

name - name of an item

values - The new value of the item as a list of String, Integer, Double, or java.util.Calendar elements

Returns:

DItem

save

boolean save()
             throws DNotesRuntimeException

Saves any changes you have made to a document.

Note If the document is a DProfileDocument, a call to the save method is only successful to a newly created document if a item was appended.

Returns:

true of successfully saved, else false

Throws:

DNotesRuntimeException - if the document cannot be saved

See Also:

save(boolean), save(boolean, boolean)

save

boolean save(boolean force)
             throws DNotesRuntimeException

Saves any changes you have made to a document.

Note If the document is a DProfileDocument, a call to the save method is only successful to a newly created document if a item was appended.

Parameters:

force - If true, the document is saved even if someone else edits and saves the document while the program is running. The last version of the document that was saved wins; the earlier version is discarded. If false, and someone else edits the document while the program is running, the makeresponse argument determines what happens.

Returns:

true of successfully saved, else false

Throws:

DNotesRuntimeException - if the document cannot be saved

See Also:

save(), save(boolean, boolean)

save

boolean save(boolean force,
             boolean makeresponse)
             throws DNotesRuntimeException

Saves any changes you have made to a document.

Note If the document is a DProfileDocument, a call to the save method is only successful to a newly created document if a item was appended.

Parameters:

force - If true, the document is saved even if someone else edits and saves the document while the program is running. The last version of the document that was saved wins; the earlier version is discarded. If false, and someone else edits the document while the program is running, the makeresponse argument determines what happens.

makeresponse - If true, the current document becomes a response to the original document (this is what the replicator does when there's a replication conflict). If false, the save is canceled. If the force parameter is true, the makeresponse parameter has no effect.

Returns:

true of successfully saved, else false

Throws:

DNotesRuntimeException - if the document cannot be saved

See Also:

save(), save(boolean)

getAttachment

DEmbeddedObject getAttachment(java.lang.String filename)

Returns a representation of a file attachment. You can use this method to find file attachments that are not contained in a rich text item (such as an attachment in a Release 2 database) as well as file attachments that are contained in a rich text item.

The Parent property for the returned EmbeddedObject returns null, since it was not accessed through a RichTextItem.

Parameters:

filename - The file name of the file attachment.

Returns:

A representation of the file attachment. Returns null if an attachment with the specified name is not found.

getEmbeddedObjects

java.util.Iterator getEmbeddedObjects()

Returns all embedded objects. This method does include OLE/2 and OLE/1 objects created in Release 4 and higher. It also includes objects in the document that were originally embedded in the document's form. Such objects must have been activated, modified, and re-saved in order to be returned by this property (otherwise they remain a part of the form, not the document).

The list is empty if the document contains no embedded objects.

Note:

Embedded objects and object links are not supported for OS/2, UNIX, and the Macintosh. File attachments are supported on all platforms.

Returns:

an iterator supplying all embedded objects

getAttachments

java.util.List getAttachments()

Returns all embedded objects that are attachments. The list is empty if the document contains no attachments.

Returns:

a list of all embedded objects

removeItem

void removeItem(java.lang.String name)

Removes an item from a document.

Parameters:

name - The name of the item to remove from the document. If more than one item has the specified name, all items with this name are removed. If there is no item with the specified name, the method does nothing.

You can achieve the same result with remove in Item. To keep the changes to the document, you must call save after removing the item.

remove

boolean remove()

Permanently removes a document from a database. If another user modifies the document after your program opens it, the document is not removed.

Returns:

true if the document is successfully removed or if the document is not contained in a database (then a exception should be logged), false if the document is not deleted because another user modified it and the force parameter is set to false.

remove

boolean remove(boolean force)

Permanently removes a document from a database.

Parameters:

force - If true, the document is removed even if another user modifies the document after your program opens it. If false, the document is not removed if another user modifies it.

Returns:

true if the document is successfully removed or if the document is not contained in a database (then a exception should be logged), false if the document is not deleted because another user modified it and the force parameter is set to false.

createRichTextItem

DRichTextItem createRichTextItem(java.lang.String name)

Creates a new rich text item in a document.

Parameters:

name - The name of the new rich-text item.

Returns:

The newly created item.

getItemValue

java.util.List getItemValue(java.lang.String name)

Returns the value of an item.

If multiple items have the same name, this method returns the value of the first item. Use the Items property to get all the items.

If the item has no value, this method returns an empty vector.

If no item with the specified name exists, this method returns an empty vector. It does not throw an exception. Use hasItem to verify the existence of an item.

This property returns the same value(s) for an item as getValues in Item.

Parameters:

name - name of an item

Returns:

The value or values contained in the item. The data type of the value depends on the data type of the item.

getItemValueString

java.lang.String getItemValueString(java.lang.String name)

Returns the value of an item with a single text value.

If multiple items have the same name, this method returns the value of the first item. Use the Items property to get all the items.

The value of the item cannot be null, but if the value is numeric or Calendar, this method returns an empty String.

If no item with the specified name exists, this method returns null. It does not throw an exception. Use hasItem to verify the existence of an item.

If the item has multiple values, this method returns the first value.

Parameters:

name - The name of the item.

Returns:

The value of the item as a String.

getItemValueDate

java.util.Calendar getItemValueDate(java.lang.String name)

Returns the value of an item with a single Calendar value. The date/time value of the item is stored in the calendar in the default time zone of the client.

If multiple items have the same name, this method returns the value of the first item. Use the Items property to get all the items.

If value is numeric or text, this method returns null.

If no item with the specified name exists, this method returns null. It does not throw an exception. Use hasItem to verify the existence of an item.

If the item has multiple values, this method returns the first value.

Parameters:

name - The name of the item.

Returns:

The value of the item as a Calendar or null if the item doesn't contain a date/time value

getItemValueDateRange

DDateRange getItemValueDateRange(java.lang.String name)

Returns the value of an item with two Calendar value.

If multiple items have the same name, this method returns the value of the first item. Use the Items property to get all the items.

If value is numeric or text, this method returns null.

If no item with the specified name exists, this method returns null. It does not throw an exception. Use hasItem to verify the existence of an item.

Parameters:

name - The name of the item.

Returns:

The value of the item as DDateRange or null if the item doesn't contain any date/time information.The second value may be null if only one date/time was specified.

getItemValueInteger

java.lang.Integer getItemValueInteger(java.lang.String name)

Returns the value of an item with a single int value.

If multiple items have the same name, this method returns the value of the first item. Use the Items property to get all the items.

If the value is text and is empty, this method returns null.

If the value is text and cannot be converted to am integer, this method returns null.

If no item with the specified name exists, this method returns null. It does not throw an exception. Use hasItem to verify the existence of an item.

If the item has multiple values, this method returns the first value.

A decimal number is rounded down if the fraction is less than 0.5 and up if the fraction is 0.5 or greater.

Parameters:

name - The name of the item.

Returns:

The value of the item, rounded to the nearest integer or null

getItemValueDouble

java.lang.Double getItemValueDouble(java.lang.String name)

Returns the value of an item with a single double value.

If multiple items have the same name, this method returns the value of the first item. Use the Items property to get all the items.

If the value is text and is empty, this method returns null.

If the value is text and cannot be converted to a double, this method returns null.

If no item with the specified name exists, this method returns null. It does not throw an exception. Use hasItem to verify the existence of an item.

If the item has multiple values, this method returns the first value.

Parameters:

name - The name of the item.

Returns:

The value of the item as a Double or null

hasItem

boolean hasItem(java.lang.String name)

Indicates whether an item exists in the document.

Parameters:

name - The name of an item.

Returns:

true if an item with name exists in the document, else false

getAuthors

java.util.List getAuthors()

The names of the people who have saved a document.

If a name is hierarchical, this property returns the fully distinguished name.

This property does not return the names of people who have permission to edit a document (as found in an item of type Authors). Therefore, the people returned by the Authors property and the people listed in an Authors item may differ.

Returns:

List of Strings with authors names. In case of a normal document this method call returns a empty list for a not-saved-document. In case of a profile document, this method call returns a list with one entry, even if the profile document is requested for the first time.

getLastAccessed

java.util.Calendar getLastAccessed()

The date a document was last modified or read.

The value returned is exact only to the day, not the hour. If the document is edited, the property is always updated. If the document is read more than once during the same 24hour period, the value is only updated the first time accessed.

Returns:

last accessed date

getLastModified

java.util.Calendar getLastModified()

The date a document was last modified.

Returns:

last modified date. In case of a normal document this method call returns a empty list for a not-saved-document. In case of a profile document, this method call returns a list with one entry, even if the profile document is requested for the first time.

getItemValueSize

int getItemValueSize(java.lang.String name)

Returns the number of values of an item.

If multiple items have the same name, this method returns the number of values in the first item. Use the Items property to get all the items.

If the item has no value, this method returns 0.

If no item with the specified name exists, this method returns 0. It does not throw an exception. Use hasItem to verify the existence of an item.

This property returns the same value for an item as getSize() in DItem.

Parameters:

name - name of an item

Returns:

The number of values contained in the item.

copyAllItems

void copyAllItems(DBaseDocument doc,
                  boolean replace)

Copies all items in the current document into the destination document. The item names are unchanged.

If you are not copying to a newly created document, you should probably specify true for the second parameter. See appendItemValue for a note about appending items to existing documents.

Parameters:

doc - The destination document

replace - If true, the items in the destination document are replaced. If false, the items in the destination document are appended.

computeWithForm

boolean computeWithForm(boolean raiseError)
                        throws DNotesRuntimeException

Validates a document by executing the default value, translation, and validation formulas, if any are defined in the document form.

Usage

The form is as follows:

1. The form stored in the document, if any.
2. The value of the Form item, if no form is stored in the document.
3. The database default form, if the document does not have a Form item.

In the user interface, you must use a form to create a document. The document must meet the form requirements for input validation, and the user interface informs you if the document does not meet these requirements. Programatically you can create a document without a form. The computeWithForm method provides a means of checking that the data you placed in a document meets the requirements of a form, although (unlike in the user interface) you can still save a document if computeWithForm returns false or throws an exception.

Parameters:

raiseError - If true, an error is raised if the validation fails. If false, no error is raised; instead, the method returns false if validation fails.

Returns:

true if there are no errors in the document, else false

Throws:

DNotesRuntimeException - if the parameter raiseError is true and if there are errors in the document

computeWithForm

boolean computeWithForm()

Validates a document by executing the default value, translation, and validation formulas, if any are defined in the document form.

Usage

The form is as follows:

1. The form stored in the document, if any.
2. The value of the Form item, if no form is stored in the document.
3. The database default form, if the document does not have a Form item.

In the user interface, you must use a form to create a document. The document must meet the form requirements for input validation, and the user interface informs you if the document does not meet these requirements. Programatically you can create a document without a form. The computeWithForm method provides a means of checking that the data you placed in a document meets the requirements of a form, although (unlike in the user interface) you can still save a document if computeWithForm returns false or throws an exception.

Returns:

true if there are no errors in the document, else false

See Also:

computeWithForm(boolean)

recycle

void recycle()

The recycle method unconditionally destroys an object and returns its memory to the system.

Different to the Notes Java-API, usually it is not necessary to use this method. One remaining case might be a document that was changed in another session (e.g. by a server agent) while still keeping a reference to the document.

copyItem

DBaseItem copyItem(DBaseItem item,
                   java.lang.String name)

Copies an item into the current document and optionally assigns the copied item a new name.

Parameters:

item - The item, usually from another document, that you want to copy. Cannot be null.

name - The name to assign to the copied item. Specify null to retain the existing name of the item.

Returns:

A copy of the specified item parameter, identical except for its newname.

copyItem

DBaseItem copyItem(DBaseItem item)

Copies an item into the current document and optionally assigns the copied item a new name.

Parameters:

item - The item, usually from another document, that you want to copy. Cannot be null.

Returns:

A copy of the specified item parameter

createReplyMessage

DDocument createReplyMessage(boolean toAll)

Creates a new document that is formatted as a reply to the current document.

The new document does not contain a Subject item. If you want one, the program must explicitly add it to the document.

The new document does not automatically get mailed. If you want to mail it, the program must explicitly call the send method.

Parameters:

toAll - If true, the new document recipient list contains all the recipients of the original. If false, the new document recipient list contains only the sender of the original.

Returns:

A reply to the current document.

encrypt

void encrypt()

Encrypts a document.

The encrypted document is not saved until you call save. Only the items for which isEncrypted is true are encrypted. Items for which isEncrypted is false remain visible to any user, even if the user does not have the proper encryption key.

If the EncryptionKeys property is set with one or more named keys, those keys are used to encrypt the document. Any user who has one of the encryption keys can decrypt the document. If there are no encryption keys specified, the document is encrypted with the user's public key, in which case only the user who encrypted the document can decrypt it.

If the program is running on a server, it must have permission to use Encrypt.

Since mail encryption works differently, do not use this method if you want to mail an encrypted document. Instead, set the EncryptOnSend property to true, and use the send method.

You cannot use the encrypt method on a Document object returned by getDocumentContext.

getColumnValues

java.util.List getColumnValues()

A list of values, each element of which corresponds to a column value in the document's parent view. The first value in the vector is the value that appears in the view's first column for the document, the second value is the one that appears in the second column, and so on. The value of each element of the vector is the result of the corresponding column's formula and the items on the current document. Some elements in the vector might have no value.

Returns:

column values

getEncryptionKeys

java.util.List getEncryptionKeys()

Returns the key(s) used to encrypt a document. The encrypt method uses these keys when it encrypts the document.

Each element in EncryptionKeys contains the name of an encryption key that you want to use to encrypt the document. The document can be decrypted by any user who posesses one of the keys. If there are no encryption keys specified for a document, the document is encrypted with the current user's public key and can only be decrypted by that user.

You must call the encrypt and save methods to actually encrypt the document. Since encryption works differently when a document is mailed, the EncryptionKeys property has no effect when a document is encrypted when mailed.

The name of each encryption key in a document is stored in a text item called SecretEncryptionKeys. This property returns the contents of the item.

Returns:

the key(s) used to encrypt a document

setEncryptionKeys

void setEncryptionKeys(java.util.List keys)

Sets the key(s) used to encrypt a document. The encrypt method uses these keys when it encrypts the document.

Parameters:

keys - the key(s) used to encrypt a document

See Also:

getEncryptionKeys()

getItemValueCustomData

java.lang.Object getItemValueCustomData(java.lang.String name)

Returns as an object the value of an item containing custom data.

Parameters:

name - The name of the item.

Returns:

An object that receives the value of the item. Must have the same class definition as the object written to the item.

Since:

Notes/Domino Release 6

getItemValueCustomData

java.lang.Object getItemValueCustomData(java.lang.String name,
                                        java.lang.String dataTypeName)

Returns as an object the value of an item containing custom data.

Parameters:

name - The name of the item.

dataTypeName - The name of the data type. If specified, this name must match the data type name specified when the item was written. If omitted, no name checking occurs

Returns:

An object that receives the value of the item. Must have the same class definition as the object written to the item.

Since:

Notes/Domino Release 6

getItemValueCustomDataBytes

byte[] getItemValueCustomDataBytes(java.lang.String name,
                                   java.lang.String dataTypeName)

Returns as a byte array the value of an item containing custom data.

Parameters:

name - The name of the item.

dataTypeName - The name of the data type. If specified, this name must match the data type name specified when the item was written. If omitted, no name checking occurs

Returns:

Array of type Byte. The value of the item.

Since:

Notes/Domino Release 6

getItemValueDateTimeArray

java.util.List getItemValueDateTimeArray(java.lang.String name)

Returns the value of a date-time item in a document.

Parameters:

name - The name of the item.

Returns:

The value or values contained in the item. Each element in the vector corresponds to a value in the item and is of type DateTime or DateRange. If the item contains a single value, the vector has one element.

Since:

Notes/Domino Release 6.5

getSigner

java.lang.String getSigner()

The name of the person who created the signature, if a document is signed.

If a document is not signed, returns an empty string.

If the signer is not trusted, returns an empty string.

Returns:

the signer

getSize

int getSize()

The size of a database, in bytes.

Returns:

size of a database, in bytes

setUniversalID

void setUniversalID(java.lang.String unid)

The universal ID, which uniquely identifies a document across all replicas of a database. In character format, the universal ID is a 32-character combination of hexadecimal digits (0-9, A-F).

If two documents in replica databases share the same universal ID, the documents are replicas.

If you modify the UNID of an existing document, it becomes a new document.

Saving a document with the same UNID as an existing document an exception.

Parameters:

unid - The universal ID is also known as the unique ID or UNID.

getVerifier

java.lang.String getVerifier()

The name of the certificate that verified a signature, if a document is signed.

This property is an empty string if the document is not signed.

This property is an empty string if the signer is not trusted.

Returns:

name of the certificate that verified a signature

hasEmbedded

boolean hasEmbedded()

Indicates whether a document contains one or more embedded objects, object links, or file attachments.

Note Embedded objects and object links are not supported for OS/2, UNIX, and the Macintosh. File attachments are.

Returns:

true if the document contains one or more embedded objects, object links, or file attachments , else false

isEncrypted

boolean isEncrypted()

Indicates whether a document is encrypted.

Returns:

true if the document is encrypted, else false

isEncryptOnSend

boolean isEncryptOnSend()

Indicates whether a document is encrypted when mailed.

Returns:

true if the document is encrypted when mailed, else false

isProfile

boolean isProfile()

Indicates whether a Document object is a profile document.

Returns:

true if the document is a profile document, else false

isSigned

boolean isSigned()

Indicates whether a document contains a signature.

Returns:

true if the document contains one or more signatures, else false

isValid

boolean isValid()

Indicates whether a Document object represents an existing document (not a deletion stub) initially.

Returns:

true if the document represents an existing document, else false

isSaveMessageOnSend

boolean isSaveMessageOnSend()

Indicates whether a document is saved to a database when mailed. Applies only to new documents that have not yet been saved.

Returns:

true if the document is saved when mailed, else false

isSentByAgent

boolean isSentByAgent()

Indicates whether a document was mailed by a Domino program.

Returns:

true if the document was mailed by a program, else false

isSignOnSend

boolean isSignOnSend()

Indicates whether a document is signed when mailed.

Returns:

true if the document is signed when mailed, else false

isDeleted

boolean isDeleted()

Indicates whether a Document object represents an existing document (not a deletion stub) on an ongoing basis.

Returns:

true if the document is a deletion stub false if the document exists

removePermanently

boolean removePermanently(boolean force)

Permanently deletes a document from a database, doing a hard deletion even if soft deletions are enabled.

This method does a hard deletion even if "Allow soft deletions" is enabled. See remove to do a soft deletion.

If you access a NotesDocument object through the Document property of NotesUIDocument, you can't delete the back-end document. If you could, the UI rendition would have no basis. You must access the document strictly through the back-end.

A deleted document cannot be used as a basis for navigation in a view or a document collection.

You cannot use the remove method on a Document object returned by DAgentContext.getDocumentContext().

Parameters:

force - If true, the document is deleted even if another user modifies the document after the program opens it. If false, the document is not deleted if another user modifies it.

Returns:

true if the document is successfully deleted, false if the document is not deleted, because another user modified it and the force parameter is set to false

renderToRTItem

boolean renderToRTItem(DRichTextItem richtextitem)

Creates a picture of a document and places it into a rich-text item that you specify.

The picture is created using both the document and its form. Therefore, the input translation and validation formulas of the form are executed.

If the target rich text item is in a new document, you must save the document before calling renderToRTItem.

Parameters:

richtextitem - The destination for the picture. Cannot be null.

Returns:

If true, the method is successful. If false, the method is not successful and the rich text item remains unchanged. This can happen if an input validation formula fails on the document form.

replaceItemValueCustomData

DItem replaceItemValueCustomData(java.lang.String name,
                                 java.lang.String type,
                                 java.lang.Object obj)

Replaces all items of the specified name with one new item, which is assigned custom data from a byte array. If the document does not contain an item with the specified name, this method creates a new item and adds it to the document.

Parameters:

name - the name of the item

type - name for the data type. When getting custom data, use this name for verification.

obj - object that contains the custom data. The class that defines this object must implement Serializable. If desired, you can override readObject and writeObject.

Returns:

DItem

replaceItemValueCustomData

DItem replaceItemValueCustomData(java.lang.String name,
                                 java.lang.Object obj)

Replaces all items of the specified name with one new item, which is assigned custom data from a byte array. If the document does not contain an item with the specified name, this method creates a new item and adds it to the document.

Parameters:

name - the name of the item

obj - object that contains the custom data. The class that defines this object must implement Serializable. If desired, you can override readObject and writeObject.

Returns:

DItem

replaceItemValueCustomDataBytes

DItem replaceItemValueCustomDataBytes(java.lang.String name,
                                      java.lang.String type,
                                      byte[] bytes)

Replaces all items of the specified name with one new item, which is assigned custom data from a byte array. If the document does not contain an item with the specified name, this method creates a new item and adds it to the document.

Parameters:

name - the name of the item

type - name for the data type. When getting custom data, use this name for verification.

bytes - byte array that contains the custom data

Returns:

DItem

generateXML

java.lang.String generateXML()

Generates an XML representation of a document to the Writer. The XML conforms to the Domino Document DTD.

This method takes the same arguments as the transformXML method in EmbeddedObject, Item, MIMEEntity, and RichTextItem. The transformXML method reads the XML from an item, attachment, MIMEEntity, or rich text item and transforms the XML. The generateXML method generates the XML from the document and then transforms it.

The generateXML method supports the following simple items: Text, Text list, Number, Number list, Datetime, Datetime list

To generate form semantics, you must call computeWithForm method before calling the generateXML method.

Returns:

The XML representation of the document.

generateXML

void generateXML(java.io.Writer writer)

Generates an XML representation of a document to the Writer. The XML conforms to the Domino Document DTD.

This method takes the same arguments as the transformXML method in EmbeddedObject, Item, MIMEEntity, and RichTextItem. The transformXML method reads the XML from an item, attachment, MIMEEntity, or rich text item and transforms the XML. The generateXML method generates the XML from the document and then transforms it.

The generateXML method supports the following simple items: Text, Text list, Number, Number list, Datetime, Datetime list

To generate form semantics, you must call computeWithForm method before calling the generateXML method.

Parameters:

writer - The Writer that will receive the result XML.

getReceivedItemText

java.util.List getReceivedItemText()

Gets the text values of the Received items in a mail document.

This method applies to Received items generated from an Internet mail message. The items can be in MIME or Notes format.

If the document has no Received items, this method returns a vector of one element whose value is an empty string.

A Received item with an incorrect format (not an Internet mail message) throws an exception.

Returns:

List of strings. The text values of the Received items, one item per element.

Since:

Notes/Domino Release 6.5

getLockHolders

java.util.List getLockHolders()

The names of the holders of a lock.

If the document is locked, the vector contains the names of the lock holders. The document can be locked by one or more users or groups.

If the document is not locked, the vector contains one element whose value is an empty string ("").

Returns:

names of the holders of a lock.

Since:

Notes/Domino Release 6.5

lock

boolean lock()

Locks a document.

Returns:

true if the lock is placed, false if the lock is not placed

Since:

Notes/Domino Release 6.5

See Also:

lock(List, boolean)

lock

boolean lock(boolean provisionalOk)

Locks a document.

Parameters:

provisionalOk - true to permit the placement of a provisional lock, false (default) to not permit a provisional lock

Returns:

true if the lock is placed, false if the lock is not placed

Since:

Notes/Domino Release 6.5

See Also:

lock(List, boolean)

lock

boolean lock(java.lang.String name)

Locks a document.

Parameters:

name - the name of the lock holder

Returns:

true if the lock is placed, false if the lock is not placed

Since:

Notes/Domino Release 6.5

See Also:

lock(List, boolean)

lock

boolean lock(java.lang.String name,
             boolean provisionalOk)

Locks a document.

Parameters:

name - the name of the lock holder

provisionalOk - true to permit the placement of a provisional lock, false (default) to not permit a provisional lock

Returns:

true if the lock is placed, false if the lock is not placed

Since:

Notes/Domino Release 6.5

See Also:

lock(List, boolean)

lock

boolean lock(java.util.List names)

Locks a document.

Parameters:

names - the names of the lock holders

Returns:

true if the lock is placed, false if the lock is not placed

Since:

Notes/Domino Release 6.5

See Also:

lock(List, boolean)

lock

boolean lock(java.util.List names,
             boolean provisionalOk)

Locks a document.

IsDocumentLockingEnabled in Database must be true or this method throws an exception.

This method:

• places a persistent lock if the administration (master lock) server is available.
• places a provisional lock if the administration server is not available and the second parameter is true.
• throws an exception if the administration server is not available and the second parameter is false.

The following actions occur depending on the current lock status:

• If the document is not locked, this method places the lock and returns true.
• If the document is locked and the current user is one of the lock holders, this method returns true.
• If the document is locked and the current user is not one of the lock holders, this method returns false.

If the document is modified by another user before the lock can be placed, this method throws an exception.

Parameters:

names - The names of the lock holders. Each lock holder must be a user or group. Defaults to one lock holder: the effective user. The empty string ("") is not permitted.

provisionalOk - true to permit the placement of a provisional lock, false (default) to not permit a provisional lock

Returns:

true if the lock is placed, false if the lock is not placed

Since:

Notes/Domino Release 6.5

lockProvisional

boolean lockProvisional()

Locks a document provisionally.

Returns:

true if the lock is placed, false if the lock is not placed

Since:

Notes/Domino Release 6.5

See Also:

lock(List, boolean)

lockProvisional

boolean lockProvisional(java.lang.String name)

Locks a document provisionally.

Parameters:

name - The name of the lock holders. The lock holder must be a user or group. Defaults to the effective user. The empty string ("") is not permitted.

Returns:

true if the lock is placed, false if the lock is not placed

Since:

Notes/Domino Release 6.5

See Also:

lock(List, boolean)

lockProvisional

boolean lockProvisional(java.util.List names)

Locks a document provisionally.

Parameters:

names - The names of the lock holders. Each lock holder must be a user or group. Defaults to one lock holder: the effective user. The empty string ("") is not permitted.

Returns:

true if the lock is placed, false if the lock is not placed

Since:

Notes/Domino Release 6.5

See Also:

lock(List, boolean)

unlock

void unlock()

Unlocks a document.

DDatabase.isDocumentLockingEnabled() in Database must be true or this method throws an exception. This method throws an exception if the current user is not one of the lock holders and does not have lock breaking authority.

Since:

Notes/Domino Release 6.5

See Also:

lock(List, boolean)