Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

de.bea.domingo
Interface DDatabase

All Superinterfaces:
DBase, java.io.Serializable
All Known Implementing Classes:
DatabaseHttp, DatabaseProxy
public interface DDatabase
extends DBase

Represents a Notes database.

Author:
Kurt Riede

Field Summary
static int FT_DATE_ASCENDING
          Sorts by document creation date in ascending order.
static int FT_DATE_DESCENDING
          Sorts by document creation date in descending order.
static int FT_DATECREATED_ASCENDING
          Sorts by document date in ascending order.
static int FT_DATECREATED_DESCENDING
          Sorts by document date in descending order.
static int FT_FUZZY
          Specifies a fuzzy search.
static int FT_SCORES
          Sorts by relevance score.
static int FT_STEMS
          Uses stem words as the basis of the search.
 
Method Summary
 DDatabase createDatabaseFromTemplate(java.lang.String serverName, java.lang.String newDatabaseName, boolean inherit)
          Create an empty database with the design of the given template.
 DDocument createDocument()
          Creates a document in a database and returns a Document object that represents the new document.
 DDatabase createReplica(java.lang.String server, java.lang.String filePath)
          Creates a replica of the current database at a new location.
 java.util.Iterator fullTextSearch(java.lang.String query)
          Conducts a full-text search of all the documents in a database.
 java.util.Iterator fullTextSearch(java.lang.String query, int max)
          Conducts a full-text search of all the documents in a database.
 java.util.Iterator fullTextSearch(java.lang.String query, int max, int sortopt, int otheropt)
          Conducts a full-text search of all the documents in a database.
 java.util.Iterator fullTextSearchRange(java.lang.String query, int max, int sortopt, int otheropt, int start)
          Conducts a full-text search of all the documents in a database.
 DAgent getAgent(java.lang.String name)
          Finds an agent in a database, given the agent name.
 java.util.Iterator getAllDocuments()
          Returns an An unsorted collection containing all the documents in a database.
 java.lang.String getCategories()
          The categories under which a database appears in the Database Library.
 int getCurrentAccessLevel()
          The current user's access level to a database.
 java.lang.String getDesignTemplateName()
          The name of the design template from which a database inherits its design.
 DDocument getDocumentByID(java.lang.String noteId)
          Finds a document in a database, given the document note ID.
 DDocument getDocumentByUNID(java.lang.String docId)
          Finds a document in a database, given the document universal ID (UNID).
 java.lang.String getFileName()
          The file name of a database, excluding the path.
 java.lang.String getFilePath()
          The path and file name of a database.
 boolean getFolderReferencesEnabled()
          Indicates whether this database maintains folder references for documents.
 DForm getForm(java.lang.String name)
          Returns the form with a given name.
 java.util.List getForms()
          Returns a list of all forms in a database.
 DProfileDocument getProfileDocument(java.lang.String profileName, java.lang.String profileKey)
          Retrieves or creates a profile document.
 java.lang.String getReplicaID()
          A 16-digit hexadecimal number that represents the replica ID of a Notes database.
 java.lang.String getServer()
          The name of the server where a database resides.
 DSession getSession()
          The Notes session that contains a database.
 int getSizeQuota()
          The size quota of a database, in kilobytes.
 java.lang.String getTemplateName()
          The template name of a database, if the database is a template.
 java.lang.String getTitle()
          The title of a database.
 DView getView(java.lang.String viewName)
          Finds a view or folder in a database, given the name or alias of the view or folder.
 java.util.List getViews()
          The views and folders in a database.
 boolean isDelayUpdates()
          Indicates whether updates to a server are delayed (batched) for better performance.
 boolean isDocumentLockingEnabled()
          Indicates whether document locking is enabled for a database.
 boolean isFTIndexed()
          Indicates whether or not a database has a full-text index.
 boolean isOpen()
          Indicates whether a database is open.
 boolean isPrivateAddressBook()
          Indicates if a database is a Personal Address Book.
 boolean isPublicAddressBook()
          Indicates if a database is a Domino Directory.
 boolean open()
          Opens a database.
 boolean remove()
          Permanently deletes the database.
 boolean replicate(java.lang.String server)
          Replicates a local database with its replica(s) on a server.
 java.util.Iterator search(java.lang.String formula)
          Given selection criteria for a document, returns all documents in a database that meet the criteria.
 java.util.Iterator search(java.lang.String formula, java.util.Calendar dt)
          Given selection criteria for a document, returns all documents in a database that meet the criteria.
 java.util.Iterator search(java.lang.String formula, java.util.Calendar dt, int max)
          Given selection criteria for a document, returns all documents in a database that meet the criteria.
 void setDocumentLockingEnabled(boolean flag)
          Sets whether document locking is enabled for a database.
 void setFolderReferencesEnabled(boolean flag)
          Indicates whether this database maintains folder references for documents.
 void setTitle(java.lang.String title)
          Sets the title of a database.
 void updateFTIndex(boolean create)
          Updates the full-text index of a database.
 
Methods inherited from interface de.bea.domingo.DBase
equals, hashCode, toString
 

Field Detail

FT_SCORES

static final int FT_SCORES
Sorts by relevance score. When a collection is sorted by relevance, the highest relevance appears first. To access the relevance score of each document in the collection, use the DDocument.getFTSearchScore() property in Document.

See Also:
Constant Field Values

FT_DATE_DESCENDING

static final int FT_DATE_DESCENDING
Sorts by document creation date in descending order.

See Also:
Constant Field Values

FT_DATE_ASCENDING

static final int FT_DATE_ASCENDING
Sorts by document creation date in ascending order.

See Also:
Constant Field Values

FT_DATECREATED_DESCENDING

static final int FT_DATECREATED_DESCENDING
Sorts by document date in descending order.

See Also:
Constant Field Values

FT_DATECREATED_ASCENDING

static final int FT_DATECREATED_ASCENDING
Sorts by document date in ascending order.

See Also:
Constant Field Values

FT_FUZZY

static final int FT_FUZZY
Specifies a fuzzy search.

See Also:
Constant Field Values

FT_STEMS

static final int FT_STEMS
Uses stem words as the basis of the search.

See Also:
Constant Field Values
Method Detail

getSession

DSession getSession()
The Notes session that contains a database.

Returns:
the Notes session that contains a database.

replicate

boolean replicate(java.lang.String server)
Replicates a local database with its replica(s) on a server.

Parameters:
server - The name of the server with which you want to replicate. Any replica of the source database that exists on the server will replicate.
Returns:
true if the database replicates without errors false if replication errors occur

remove

boolean remove()
Permanently deletes the database.

Returns:
true if the database was removed successfully, else false

getAllDocuments

java.util.Iterator getAllDocuments()
Returns an An unsorted collection containing all the documents in a database.

Returns:
Iterator

getDocumentByUNID

DDocument getDocumentByUNID(java.lang.String docId)
Finds a document in a database, given the document universal ID (UNID).

If the document document is already loaded, this method might return the same instance of the document or a new instance representing the same document. Mostly via local call, the same instance is returned and mostly via remote calls a new instance is returned. Your code should not rely on this behaviour.

Parameters:
docId - Universal ID of a document
Returns:
DDocument or null if the document was not found

getDocumentByID

DDocument getDocumentByID(java.lang.String noteId)
Finds a document in a database, given the document note ID.

If the document document is already loaded, this method might return the same instance of the document or a new instance representing the same document. Mostly via local call, the same instance is returned and mostly via remote calls a new instance is returned. Your code should not rely on this behaviour.

Parameters:
noteId - NoteID
Returns:
DDocument

getProfileDocument

DProfileDocument getProfileDocument(java.lang.String profileName,
                                    java.lang.String profileKey)
Retrieves or creates a profile document.

Parameters:
profileName - name of a profile
profileKey - The unique key associated with the profile document. Usually the userName. Can be null which indicates that the returned document is a public profile.
Returns:
DProfileDocument or null if the document was not found

createDocument

DDocument createDocument()
Creates a document in a database and returns a Document object that represents the new document.

Returns:
DDocument

getView

DView getView(java.lang.String viewName)
Finds a view or folder in a database, given the name or alias of the view or folder.

Parameters:
viewName - name of a view
Returns:
DView

getFilePath

java.lang.String getFilePath()
The path and file name of a database.

Returns:
String

getFileName

java.lang.String getFileName()
The file name of a database, excluding the path.

Returns:
String

createDatabaseFromTemplate

DDatabase createDatabaseFromTemplate(java.lang.String serverName,
                                     java.lang.String newDatabaseName,
                                     boolean inherit)
                                     throws DNotesException
Create an empty database with the design of the given template.

Parameters:
serverName - notes server name
newDatabaseName - notes database filename
inherit - Specify true if you want the new database to inherit future design changes from the template; otherwise, specify false.
Returns:
DDatabase
Throws:
DNotesException - if current database is not a template

createReplica

DDatabase createReplica(java.lang.String server,
                        java.lang.String filePath)
                        throws DNotesException
Creates a replica of the current database at a new location. The new replica has an identical access control list.

Usage
If a database with the specified file name already exists, an exception is thrown. Programs running on a server or making remote (IIOP) calls to a server can't create or access databases on other servers. In these cases, the server parameter must correspond to the server the program is running on. There are two ways to do this:

Programs running on a workstation can access several different servers in a single program.

Parameters:
server - The name of the server where the replica will reside. Specify null or an empty string ("") to create a replica on the current computer.
filePath - The file name of the replica.
Returns:
The new replica
Throws:
DNotesException - if creation of the new replica failed

getCurrentAccessLevel

int getCurrentAccessLevel()
The current user's access level to a database.

If a program runs on a workstation or is remote (IIOP), CurrentAccessLevel is determined by the access level of the current user.

If a program runs on a server, CurrentAccessLevel is determined by the access level of the person who last saved the program (the owner).

Legal values:

DACL.LEVEL_AUTHOR
 DACL.LEVEL_DEPOSITOR
 DACL.LEVEL_DESIGNER
 DACL.LEVEL_EDITOR
 DACL.LEVEL_MANAGER
 DACL.LEVEL_NOACCESS
 DACL.LEVEL_READER

Returns:
access level
See Also:
DACL

getServer

java.lang.String getServer()
The name of the server where a database resides.

If the database is on a workstation, the property returns an empty string.

Returns:
name of the server

getAgent

DAgent getAgent(java.lang.String name)
Finds an agent in a database, given the agent name.

The return value is null if the current user (as obtained by Session.getUserName) is not the owner of the private agent.

Parameters:
name - the name of the agent.
Returns:
the agent whose name matches the parameter.

isPublicAddressBook

boolean isPublicAddressBook()
Indicates if a database is a Domino Directory.

This property is available for Database objects retrieved by DSession.getAddressBooks() in DSession. For other Database objects, this property has no value and evaluates to false.

Returns:
true if the database is a Domino Directory, false if the database is not a Domino Directory

isPrivateAddressBook

boolean isPrivateAddressBook()
Indicates if a database is a Personal Address Book.

This property is available for Database objects retrieved by DSession.getAddressBooks() in DSession. For other Database objects, this property has no value and evaluates to false.

Returns:
true if the database is a Personal Address Book, false if the database is not Personal Address Book

isOpen

boolean isOpen()
Indicates whether a database is open.

Usage

A database must be open to use the Database methods except: getCategories(), isDelayUpdates(), getDesignTemplateName(), getFileName(), getFilePath(), isOpen(), isPrivateAddressBook(), isPublicAddressBook(), getSession(), getReplicaID(), getServer(), getSizeQuota(), getTemplateName(), and getTitle().

The following methods do not open a database: DbDirectory.getFirstDatabase, DbDirectory.getNextDatabase, and Session.getAddressBooks. You must explicitly call Database.open.

Returns:
true if the database is open, false if the database is not open

open

boolean open()
Opens a database.

A database must be open to use the Database properties and methods with some exceptions. Most methods that access a database open it, but some do not. See isOpen for details.

An error is returned if the user does not have access rights to the database or server.

Returns:
true if the database exists and is opened, false if no database with this name exists

getCategories

java.lang.String getCategories()
The categories under which a database appears in the Database Library. Multiple categories are separated by a comma or semicolon.

Returns:
categories as a string

isDelayUpdates

boolean isDelayUpdates()
Indicates whether updates to a server are delayed (batched) for better performance.

If DelayUpdates is false, the program waits for updates to the server to be posted. If you set DelayUpdates to true, server updates are cached and the program proceeds immediately. At a convenient time, the cached updates are posted. This makes for better performance but risks losing the cached updates in the event of a crash. This method applies to save and remove operations on documents.

Set this property each time you open a database. The property is not saved.

Returns:
true if server delays updates, false if server posts updates immediately

getReplicaID

java.lang.String getReplicaID()
A 16-digit hexadecimal number that represents the replica ID of a Notes database. Databases with the same replica ID are replicas of one another.

Returns:
replica ID

getSizeQuota

int getSizeQuota()
The size quota of a database, in kilobytes.

The size quota for a database specifies the amount of disk space that the server administrator is willing to provide for the database. Therefore, the SizeQuota property can only be set by a program that has administrator access to the server on which the database resides. The size quota is not the same as the size limit that a user specifies when creating a new database.

If the database has no size quota, this property returns 0.

Returns:
size quota of a database in kilobytes

getTemplateName

java.lang.String getTemplateName()
The template name of a database, if the database is a template. If the database is not a template, returns an empty string.

Returns:
template name

getTitle

java.lang.String getTitle()
The title of a database. The database does not need to be open to use this property.

Returns:
database title.

setTitle

void setTitle(java.lang.String title)
Sets the title of a database. A program cannot change the title of the database in which the program is currently running. The database does not need to be open to use this property.

Parameters:
title - new database title

getDesignTemplateName

java.lang.String getDesignTemplateName()
The name of the design template from which a database inherits its design. If the database does not inherit its design from a design template, returns an empty string.

If a database inherits a specific design element (such as a form) but not its entire design from a template, this property returns an empty string.

Returns:
name of the design template from which a database inherits its design

search

java.util.Iterator search(java.lang.String formula,
                          java.util.Calendar dt,
                          int max)
Given selection criteria for a document, returns all documents in a database that meet the criteria.

Usage
This method returns a maximum of 5,000 documents by default. The Notes.ini variable FT_MAX_SEARCH_RESULTS overrides this limit for indexed databases or databases that are not indexed but that are running an agent on the client. For a database that is not indexed and is running in an agent on the server, you must set the TEMP_INDEX_MAX_DOC Notes.ini variable as well. The absolute maximum value is 2,147,483,647.

Parameters:
formula - Notes @-function formula that specifies the selection criteria
dt - A cutoff date. The method searches only documents created or modified since the cutoff date. Can be null to indicate no cutoff date.
max - The maximum number of documents you want returned. Specify 0 to receive all matching documents (up to 5,000. See Usage section.).
Returns:
An unsorted collection of documents that match the selection criteria.

search

java.util.Iterator search(java.lang.String formula,
                          java.util.Calendar dt)
Given selection criteria for a document, returns all documents in a database that meet the criteria.

Usage
This method returns a maximum of 5,000 documents by default. The Notes.ini variable FT_MAX_SEARCH_RESULTS overrides this limit for indexed databases or databases that are not indexed but that are running an agent on the client. For a database that is not indexed and is running in an agent on the server, you must set the TEMP_INDEX_MAX_DOC Notes.ini variable as well. The absolute maximum value is 2,147,483,647.

Parameters:
formula - Notes @-function formula that specifies the selection criteria
dt - A cutoff date. The method searches only documents created or modified since the cutoff date. Can be null to indicate no cutoff date.
Returns:
An unsorted collection of documents that match the selection criteria.

search

java.util.Iterator search(java.lang.String formula)
Given selection criteria for a document, returns all documents in a database that meet the criteria.

Usage
This method returns a maximum of 5,000 documents by default. The Notes.ini variable FT_MAX_SEARCH_RESULTS overrides this limit for indexed databases or databases that are not indexed but that are running an agent on the client. For a database that is not indexed and is running in an agent on the server, you must set the TEMP_INDEX_MAX_DOC Notes.ini variable as well. The absolute maximum value is 2,147,483,647.

Parameters:
formula - Notes @-function formula that specifies the selection criteria
Returns:
An unsorted collection of documents that match the selection criteria.

isFTIndexed

boolean isFTIndexed()
Indicates whether or not a database has a full-text index.

Returns:
true if the database has a full-text index, else false

updateFTIndex

void updateFTIndex(boolean create)
Updates the full-text index of a database.

Usage

An exception is thrown if you attempt to create a full-text index on a database that is not local. A database must contain at least one document in order for an index to be created, even if the create parameter is set to true.

Parameters:
create - Specify true if you want to create an index if none exists (valid only for local databases). Otherwise, specify false.

fullTextSearchRange

java.util.Iterator fullTextSearchRange(java.lang.String query,
                                       int max,
                                       int sortopt,
                                       int otheropt,
                                       int start)
Conducts a full-text search of all the documents in a database.

Usage

This method is the same the same as fullTextSearch(String, int, int, int) plus the start parameter. If the database is not full-text indexed, this method works, but less efficiently. To test for an index, use the isFTIndexed() property. To create an index on a local database, use the updateFTIndex(boolean) method. This method returns a maximum of 5,000 documents by default. The Notes.ini variable FT_MAX_SEARCH_RESULTS overrides this limit for indexed databases or databases that are not indexed but that are running in an agent on the client. For a database that is not indexed and is running in an agent on the server, you must set the TEMP_INDEX_MAX_DOC Notes.ini variable as well. The absolute maximum is 2,147,483,647. This method searches all documents in a database. To search only documents found in a particular view, use the DView.fullTextSearch(String, int) method in View. To search only documents found in a particular document collection, use the DDocumentCollection.fullTextSearch(String, int) method in class DDocumentCollection. If you don't specify any sort options, you get the documents sorted by relevance score. If you ask for a sort by date, you don't get relevance scores. A Newsletter object formats its doclink report with either the document creation date or the relevance score, depending on the sort options you use in the document collection. If the database has a multi-database index, you get a multi-database search. Navigation through the resulting document collection may be slow, but you can create a newsletter from the collection.

Query syntax

To search for a word or phrase, enter the word or phrase as is, except that search keywords must be enclosed in quotes. Remember to escape quotes if you are inside a literal. Wildcards, operators, and other syntax are permitted. For the complete syntax rules, see "Finding documents in a database" in Lotus Notes 6 Help.

Parameters:
query - The full-text query. See the "Query Syntax" for details
max - The maximum number of documents you want returned from the query. Set this parameter to 0 to receive all matching documents
sortopt - Use one of the following constants to specify a sorting option: FT_SCORES, FT_DATECREATED_DESCENDING, FT_DATE_DESCENDING or FT_DATE_ASCENDING
otheropt - Use the following constants to specify additional search options. To specify more than one option, use a logical or operation: FT_FUZZY or FT_STEMS
start - The starting document to return.
Returns:
An iterator over documents that match the full-text query, sorted by the selected option. If no matches are found, the iterator has no elements.
Since:
Notes/Domino Release 6

fullTextSearch

java.util.Iterator fullTextSearch(java.lang.String query)
Conducts a full-text search of all the documents in a database.

See fullTextSearch(String, int, int, int) for more details.

Parameters:
query - The full-text query. See the "Query Syntax" for details
Returns:
An iterator over documents that match the full-text query, sorted by the selected option. If no matches are found, the iterator has no elements.

fullTextSearch

java.util.Iterator fullTextSearch(java.lang.String query,
                                  int max)
Conducts a full-text search of all the documents in a database.

See fullTextSearch(String, int, int, int) for more details.

Parameters:
query - The full-text query. See the "Query Syntax" for details
max - The maximum number of documents you want returned from the query. Set this parameter to 0 to receive all matching documents (up to 5,000. See Usage)
Returns:
An iterator over documents that match the full-text query, sorted by the selected option. If no matches are found, the iterator has no elements.

fullTextSearch

java.util.Iterator fullTextSearch(java.lang.String query,
                                  int max,
                                  int sortopt,
                                  int otheropt)
Conducts a full-text search of all the documents in a database.

Usage

This method is the same the same as fullTextSearchRange(String, int, int, int, int) minus the start parameter. If the database is not full-text indexed, this method works, but less efficiently. To test for an index, use the isFTIndexed() property. To create an index on a local database, use the updateFTIndex(boolean) method. This method returns a maximum of 5,000 documents by default. The Notes.ini variable FT_MAX_SEARCH_RESULTS overrides this limit for indexed databases or databases that are not indexed but that are running in an agent on the client. For a database that is not indexed and is running in an agent on the server, you must set the TEMP_INDEX_MAX_DOC Notes.ini variable as well. The absolute maximum is 2,147,483,647. This method searches all documents in a database. To search only documents found in a particular view, use the DView.fullTextSearch(String, int) method in View. To search only documents found in a particular document collection, use the DDocumentCollection.fullTextSearch(String, int) method in class DDocumentCollection. If you don't specify any sort options, you get the documents sorted by relevance score. If you ask for a sort by date, you don't get relevance scores. A Newsletter object formats its doclink report with either the document creation date or the relevance score, depending on the sort options you use in the document collection. If the database has a multi-database index, you get a multi-database search. Navigation through the resulting document collection may be slow, but you can create a newsletter from the collection.

Query syntax

To search for a word or phrase, enter the word or phrase as is, except that search keywords must be enclosed in quotes. Remember to escape quotes if you are inside a literal. Wildcards, operators, and other syntax are permitted. For the complete syntax rules, see "Finding documents in a database" in Lotus Notes 6 Help.

Parameters:
query - The full-text query. See the "Query Syntax" for details
max - The maximum number of documents you want returned from the query. Set this parameter to 0 to receive all matching documents (up to 5,000. See Usage)
sortopt - Use one of the following constants to specify a sorting option: FT_SCORES, FT_DATECREATED_DESCENDING, FT_DATE_DESCENDING or FT_DATE_ASCENDING
otheropt - Use the following constants to specify additional search options. To specify more than one option, use a logical or operation: FT_FUZZY or FT_STEMS
Returns:
An iterator over documents that match the full-text query, sorted by the selected option. If no matches are found, the iterator has no elements.

isDocumentLockingEnabled

boolean isDocumentLockingEnabled()
Indicates whether document locking is enabled for a database.

Returns:
true if document locking is enabled, false if document locking is not enabled
Since:
Notes/Domino Release 6.5

setDocumentLockingEnabled

void setDocumentLockingEnabled(boolean flag)
Sets whether document locking is enabled for a database.

Parameters:
flag - true if document locking is enabled, false if document locking is not enabled
Since:
Notes/Domino Release 6.5

getFolderReferencesEnabled

boolean getFolderReferencesEnabled()
Indicates whether this database maintains folder references for documents.

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

The database must be at the Release 5 file format level or greater.

Maintaining folder references impacts performance.

Returns:
true maintains folder references, false doesn't

setFolderReferencesEnabled

void setFolderReferencesEnabled(boolean flag)
Indicates whether this database maintains folder references for documents.

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

The database must be at the Release 5 file format level or greater.

Maintaining folder references impacts performance.

Parameters:
flag - true maintains folder references, false doesn't

getViews

java.util.List getViews()
The views and folders in a database. Each element of the list represents a public view or folder in the database. If the database is local, personal folders are also included. The database must be open to use this property.

Returns:
list of views and folders in a database

getForms

java.util.List getForms()
Returns a list of all forms in a database.

Returns:
list of DForm

getForm

DForm getForm(java.lang.String name)
Returns the form with a given name. The database must be open to use this property.

Parameters:
name - name of the form
Returns:
DForm
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Domingo Java-API