de.bea.domingo
Interface DDocument

All Superinterfaces:

DBase, DBaseDocument, java.io.Serializable

All Known Implementing Classes:

DocumentHttp, DocumentProxy, MockDocument

public interface DDocument
extends DBaseDocument

Represents a document in a database.

To create a new Document object, use DDatabase.createDocument() in DDatabase.

To access existing documents:

• To get all the documents in a database, use DDatabase.getAllDocuments() in DDatabase.
• To get all documents that are responses to a particular document, use getResponses() in DDocument. To get a response document's parent document, use getParentDocument() in DDocument.
• To get a document based on its note ID or UNID, use DDatabase.getDocumentByID(java.lang.String) or DDatabase.getDocumentByUNID(java.lang.String) in DDatabase.

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.

After you create, modify, or delete a document, you must save the changes by calling the DBaseDocument.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.

Author:

Kurt Riede

Method Summary

DDocument	copyToDatabase(DDatabase database) Copies a document to a specified database.
java.util.List	getFolderReferences() The names of the folders containing a document.
int	getFTSearchScore() The full-text search score of a document, if it was retrieved as part of a full-text search.
java.lang.String	getHttpURL() The Domino URL of a form when HTTP protocols are in effect.
java.lang.String	getNoteID() The note ID of a document, which is a hexadecimal value of up to 8 characters that uniquely identifies a document within a particular database.
java.lang.String	getNotesURL() The Domino URL of a form when Notes protocols are in effect.
DDocument	getParentDocument() The parent document if the document is a response document.
java.lang.String	getParentDocumentUNID() The universal ID of a document's parent, if the document is a response.
DView	getParentView() The view from which a document was retrieved, if any.
java.util.Iterator	getResponses() The immediate responses to a document.
java.lang.String	getUniversalID() The universal ID, which uniquely identifies a document across all replicas of a database.
java.lang.String	getURL() Returns the Domino URL for its parent object.
boolean	isNewNote() Indicates whether a document is new.
boolean	isResponse() Indicates whether a document is a response to another document.
void	makeResponse(DDocument doc) Makes one document a response to another.
void	putInFolder(java.lang.String name) Adds a document to a folder.
void	putInFolder(java.lang.String name, boolean create) Adds a document to a folder.
void	removeFromFolder(java.lang.String name) Removes a document from a folder.
void	replaceHTML(java.lang.String name, java.lang.String value) Replaces a MIMEEntity item with a new item with the given HTML code.
void	send(java.util.List recipients) Mails a document.
void	send(java.lang.String recipient) Mails a document.
void	setEncryptOnSend(boolean flag) Indicates if a document is encrypted when mailed.
void	setSaveMessageOnSend(boolean saveMessageOnSend) Indicates if a document is saved to a database when mailed.
void	setSignOnSend(boolean flag) Indicates if a document is signed when mailed.
void	sign() Signs a document.

Methods inherited from interface de.bea.domingo.DBaseDocument

appendItemValue, appendItemValue, appendItemValue, appendItemValue, appendItemValue, appendItemValue, computeWithForm, computeWithForm, copyAllItems, copyItem, copyItem, createReplyMessage, createRichTextItem, encrypt, generateXML, generateXML, getAttachment, getAttachments, getAuthors, getColumnValues, getCreated, getEmbeddedObjects, getEncryptionKeys, getFirstItem, getItems, getItemValue, getItemValueCustomData, getItemValueCustomData, getItemValueCustomDataBytes, getItemValueDate, getItemValueDateRange, getItemValueDateTimeArray, getItemValueDouble, getItemValueInteger, getItemValueSize, getItemValueString, getLastAccessed, getLastModified, getLockHolders, getParentDatabase, getReceivedItemText, getSigner, getSize, getVerifier, hasEmbedded, hasItem, isDeleted, isEncrypted, isEncryptOnSend, isProfile, isSaveMessageOnSend, isSentByAgent, isSigned, isSignOnSend, isValid, lock, lock, lock, lock, lock, lock, lockProvisional, lockProvisional, lockProvisional, recycle, remove, remove, removeItem, removePermanently, renderToRTItem, replaceItemValue, replaceItemValue, replaceItemValue, replaceItemValue, replaceItemValue, replaceItemValue, replaceItemValue, replaceItemValue, replaceItemValue, replaceItemValue, replaceItemValueCustomData, replaceItemValueCustomData, replaceItemValueCustomDataBytes, save, save, save, setEncryptionKeys, setUniversalID, unlock

Methods inherited from interface de.bea.domingo.DBase

equals, hashCode, toString

Method Detail

isNewNote

boolean isNewNote()

Indicates whether a document is new. A document is new if it has not been saved.

Returns:

Boolean true if the document was created, but has not been saved

getUniversalID

java.lang.String getUniversalID()

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). The universal ID is also known as the unique ID or UNID.

Returns:

String

getNoteID

java.lang.String getNoteID()

The note ID of a document, which is a hexadecimal value of up to 8 characters that uniquely identifies a document within a particular database.

A typical note ID looks like this: 20FA. A note ID represents the location of a document within a specific database file, so documents that are replicas of one another generally have different note IDs. A note ID does not change, unless the document is deleted.

Returns:

the notes ID

send

void send(java.lang.String recipient)

Mails a document.

The following rules apply to specification of the recipient or recipients:

• Ignored if the document contains a SendTo item, in which case the document is mailed to recipients listed in SendTo.
• Required if the document does not contain a SendTo item.
• May include people, groups, or mail-in databases.

If you have only Reader access to a database, you can run an agent that creates and sends a document, but the agent will not work if you attach a file to that document.

Two kinds of items can affect the mailing of the document when you use send:

• If the document contains additional recipient items, such as CopyTo or BlindCopyTo, the documents mailed to those recipients.
• If the document contains items to control the routing of mail, such as DeliveryPriority, DeliveryReport, or ReturnReceipt, they are used when sending the document.

The IsSaveMessageOnSend property controls whether the sent document is saved in the database. If IsSaveMessageOnSend is true and you attach the form to the document, the form is saved with the document.

The send method automatically creates an item called $AssistMail on the sent document. The SentByAgent property uses this item to determine if a document was mailed by an agent.

If a program runs on a workstation, the mailed document contains the current user's name in the From item. If a program runs as an agent on a server, the mailed document contains the server's name in the From item.

Parameters:

recipient - name of recipient

send

void send(java.util.List recipients)

Mails a document.

Parameters:

recipients - list of Strings with recipients

See Also:

send(java.lang.String)

copyToDatabase

DDocument copyToDatabase(DDatabase database)

Copies a document to a specified database.

Parameters:

database - The database to which you want to copy the document. Cannot be null.

Returns:

The new document in the specified database or null if the document cannot be created

isResponse

boolean isResponse()

Indicates whether a document is a response to another document.

Returns:

true if the document is a response to another document, else false

getParentDocumentUNID

java.lang.String getParentDocumentUNID()

The universal ID of a document's parent, if the document is a response. Returns an empty string if a document doesn't have a parent.

Returns:

the universal ID

getParentDocument

DDocument getParentDocument()

The parent document if the document is a response document.

Returns:

the parent document or null if the document is not a response document.

makeResponse

void makeResponse(DDocument doc)

Makes one document a response to another. The two documents must be in the same database.

Parameters:

doc - The document to which the current document becomes a response.

getResponses

java.util.Iterator getResponses()

The immediate responses to a document.

Each document returned is an immediate response to the first document. Responses-to-responses are not included. If the current document has no responses, the vector contains zero documents.

Responses-to-Responses
This property returns only immediate responses to a document, but you can write a recursive sub or function to access all the descendants of a particular document. A recursive sub calls itself in the same way that a non-recursive sub calls any other sub or function.

Returns:

The immediate responses to a document.

setSaveMessageOnSend

void setSaveMessageOnSend(boolean saveMessageOnSend)

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

When SaveMessageOnSend is true, the document is saved just after being mailed.

Parameters:

saveMessageOnSend - true if the document is saved when mailed, else false.

setEncryptOnSend

void setEncryptOnSend(boolean flag)

Indicates if a document is encrypted when mailed.

To encrypt a document when mailed, this method looks for the public key of each recipient in the Domino Directory. If it cannot find a recipient's public key, the method sends an unencrypted copy of the document to that recipient. All other recipients receive an encrypted copy of the document.

This property has no effect on whether a document is encrypted when saved to a database.

Parameters:

flag - true if the document is encrypted when mailed, else false.

setSignOnSend

void setSignOnSend(boolean flag)

Indicates if a document is signed when mailed.

Parameters:

flag - true if the document is signed when mailed; else false.

sign

void sign()

Signs a document.

If you want the signature to be saved, you must call the Save method after signing the document.

If the program is running on a server, this method has no effect.

replaceHTML

void replaceHTML(java.lang.String name,
                 java.lang.String value)

Replaces a MIMEEntity item with a new item with the given HTML code.

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

Parameters:

name - name of an item

value - HTML code for the new item

getFTSearchScore

int getFTSearchScore()

The full-text search score of a document, if it was retrieved as part of a full-text search.

Usage

The score is determined by the number of target words that are found in the document, the term weights assigned to the target words, and any proximity operators in the search query. If the document is not retrieved as part of a full-text search, returns 0. If the document is retrieved using an FTSearch method on a database without a full-text index, returns an unpredictable number.

If a document is in more than one DocumentCollection or ViewEntryCollection, its score is that of the last collection from which it was retrieved. The score is correct unless you get the score from the current object after retrieving the same document from another collection.

Documents added to a collection have a search score of 0.

Documents deleted from a view have a search score of 0.

Returns:

The full-text search score of a document, if it was retrieved as part of a full-text search

getParentView

DView getParentView()

The view from which a document was retrieved, if any.

If the document was retrieved directly from the database or a document collection, getParentView returns null.

Returns:

view from which a document was retrieved

getFolderReferences

java.util.List getFolderReferences()

The names of the folders containing a document.

The database must have the hidden views $FolderInfo and $FolderRefInfo to support folder references. These views can be copied from the mail template. This property does not return view references.

Folder references must be enabled for the database. See the FolderReferencesEnabled property of Database.

Returns:

names of the folders containing a document

See Also:

DDatabase.getFolderReferencesEnabled()

putInFolder

void putInFolder(java.lang.String name)

Adds a document to a folder. If the folder does not exist, it is created.

If the document is already inside the folder you specify, putInFolder does nothing. If you specify a path to a folder, and none of the folders exists, the method creates all of them for you. For example:

doc.putInFolder( "Vehicles\\Bikes" );

If neither Vehicles nor Bikes exists, putInFolder creates both, placing the Bikes folder inside the Vehicles folder.

This method cannot add the first document to a folder that is "Shared, Personal on first use."

Parameters:

name - The name of the folder in which to place the document. The folder may be personal if the program is running on a workstation. If the folder is within another folder, specify a path to it, separating folder names with backslashes. For example: "Vehicles\\Bikes"

See Also:

putInFolder(String, boolean)

putInFolder

void putInFolder(java.lang.String name,
                 boolean create)

Adds a document to a folder. If the folder does not exist, it is created.

If the document is already inside the folder you specify, putInFolder does nothing. If you specify a path to a folder, and none of the folders exists, the method creates all of them for you. For example:

doc.putInFolder( "Vehicles\\Bikes" );

If neither Vehicles nor Bikes exists, putInFolder creates both, placing the Bikes folder inside the Vehicles folder.

This method cannot add the first document to a folder that is "Shared, Personal on first use."

Parameters:

name - The name of the folder in which to place the document. The folder may be personal if the program is running on a workstation. If the folder is within another folder, specify a path to it, separating folder names with backslashes. For example: "Vehicles\\Bikes"

create - If true (default), creates the folder if it does not exist.

removeFromFolder

void removeFromFolder(java.lang.String name)

Removes a document from a folder.

The method does nothing if the document is not in the folder you specify, or if the folder you specify does not exist.

Parameters:

name - The name of the folder from which to remove the document. The folder may be personal if the program is running on a workstation. If the folder is within another folder, specify a path to it, separating folder names with backslashes. For example: "Vehicles\\Bikes"

getURL

java.lang.String getURL()

Returns the Domino URL for its parent object.

See DSession.resolve(String) for additional information and examples.

Returns:

Domino URL

See Also:

getHttpURL(), getNotesURL(), getURL(), DSession.resolve(String)

getNotesURL

java.lang.String getNotesURL()

The Domino URL of a form when Notes protocols are in effect.

If Notes protocols are not available, this property returns an empty string.

See DSession.resolve(String) for additional information and examples.

Returns:

Domino Notes URL

See Also:

getHttpURL(), getURL(), DSession.resolve(String)

getHttpURL

java.lang.String getHttpURL()

The Domino URL of a form when HTTP protocols are in effect.

If HTTP protocols are not available, this property returns an empty string.

See DSession.resolve(String) for additional information and examples.

Returns:

The Domino HTTP URL

See Also:

getNotesURL(), getURL(), DSession.resolve(String)