de.bea.domingo
Interface DSession

All Superinterfaces:

DBase, java.io.Serializable

All Known Implementing Classes:

SessionHttp, SessionProxy

public interface DSession
extends DBase

Is the root of the Notes Objects containment hierarchy, providing access to the other Domino objects, and represents the Domino environment of the current program.

Author:

Kurt Riede

Method Summary

DDatabase	createDatabase(java.lang.String serverName, java.lang.String databaseName) Creates an empty database and opens it.
DDxlExporter	createDxlExporter() Creates a DxlExporter object.
DLog	createLog(java.lang.String name) Creates a new Log object with the name you specify.
java.util.List	evaluate(java.lang.String formula) Evaluates a domino formula.
java.util.List	evaluate(java.lang.String formula, DBaseDocument doc) Evaluates a domino formula.
java.lang.String	getAbbreviatedName(java.lang.String canonicalName) Converts a canonical name to it's abbreviated form.
java.util.List	getAddressBooks() The Domino Directories and Personal Address Books that are known to the current session.
DAgentContext	getAgentContext() Represents the agent environment of the current program, if an agent is running it.
java.lang.String	getCanonicalName(java.lang.String abbreviatedName) Converts a abbreviated name to it's canonical form.
java.lang.String	getCanonicalUserName() returns a String value containing the canonical form of a hierarchical name.
java.lang.String	getCommonUserName() Returns a String value containing the common name (CN=) component of a hierarchical name.
java.util.Calendar	getCurrentTime() Returns the current date/time.
DDatabase	getDatabase(java.lang.String serverName, java.lang.String databaseName) Returns a database interface to a Notes database.
java.lang.String	getEnvironmentString(java.lang.String name) Given the name of an environment variable, retrieves its value.
java.lang.String	getEnvironmentString(java.lang.String name, boolean isSystem) Given the name of an environment variable, retrieves its value.
java.lang.Object	getEnvironmentValue(java.lang.String name) Given the name of an environment variable, retrieves its value.
java.lang.Object	getEnvironmentValue(java.lang.String name, boolean isSystem) Given the name of an environment variable, retrieves its value.
DDatabase	getMailDatabase() Returns the mail database of the current user.
DDatabase	getMailDatabase(java.lang.String username) Returns the mail database of a given user.
java.lang.String	getMailDatabaseName() Returns the file/path of the mail database of the current users.
java.lang.String	getMailDomain() Returns the name of the mail-domain of the current user.
java.lang.String	getMailServer() Returns the name of the mail server of the current user.
java.lang.String	getNotesVersion() The release of Domino the session is running on.
java.lang.String	getPlatform() The name of the platform the session is running on.
java.lang.String	getServerName() Returns the full name of the server that the session is running on.
java.util.TimeZone	getTimeZone() Returns the time zone of calendar instances that are created by domingo.
java.lang.String	getUserName() The full name of the user or server that created the session.
boolean	isOnServer() Indicates if the session is running on a server.
boolean	isValid() Indicates whether an instantiated Session object is still valid.
DBase	resolve(java.lang.String url) Returns the Domino object that a URL addresses.
void	setEnvironmentString(java.lang.String name, java.lang.String value) Sets the value of an environment variable.
void	setEnvironmentString(java.lang.String name, java.lang.String value, boolean isSystem) Sets the value of a string environment variable.
void	setTimeZone(java.util.TimeZone zone) Sets the time zone of calendar instances that are created by domingo.

Methods inherited from interface de.bea.domingo.DBase

equals, hashCode, toString

Method Detail

isOnServer

boolean isOnServer()

Indicates if the session is running on a server.

Returns:

true if the program is running on a server, false if the program is running on a workstation

Usage

A remote (IIOP) session always runs on a server.

A local session is running on a server if it is an agent in a server- based database, and the agent has one of the following triggers:

• When new mail arrives
• When documents have been created or modified
• When documents have been pasted
• On schedule hourly, daily, weekly, or monthly

All other programs run on a workstation.

getDatabase

DDatabase getDatabase(java.lang.String serverName,
                      java.lang.String databaseName)
                      throws DNotesException

Returns a database interface to a Notes database.

Parameters:

serverName - notes server name

databaseName - notes database filename

Returns:

DDatabase

Throws:

DNotesException - if the database cannot be opened

getUserName

java.lang.String getUserName()

The full name of the user or server that created the session.

Returns:

user name

createDatabase

DDatabase createDatabase(java.lang.String serverName,
                         java.lang.String databaseName)

Creates an empty database and opens it. Because the new database is not based on a template, it is blank and does not contain any forms or views.

Parameters:

serverName - notes server name

databaseName - notes database filename

Returns:

DDatabase

getCommonUserName

java.lang.String getCommonUserName()

Returns a String value containing the common name (CN=) component of a hierarchical name.

Example:

Kurt Riede

Returns:

common user name

getCanonicalUserName

java.lang.String getCanonicalUserName()

returns a String value containing the canonical form of a hierarchical name.

Example:

Kurt Riede/Development/BEAP

Returns:

canonical user name

evaluate

java.util.List evaluate(java.lang.String formula)
                        throws DNotesException

Evaluates a domino formula.

If the formula contains the name of a field, you must use the 2-parameter method. The formula takes the field from the document specified as the doc parameter.

0x0040Functions that affect the user interface do not work in evaluate. These include: 0x0040Command, 0x0040DbManager, 0x0040DbName, 0x0040DbTitle, 0x0040DDEExecute, 0x0041DDEInitiate, 0x0040DDEPoke, 0x0040DDETerminate, 0x0040DialogBox, 0x0040PickList, 0x0040PostedCommand, 0x0040Prompt, and 0x0040ViewTitle.

You cannot change a document with evaluate; you can only get a result. To change a document, write the result to the document with a method such as Document.replaceItemValue.

Parameters:

formula - The formula

Returns:

The result of the evaluation or null if an error occurred. A scalar result is returned as the first element.

Throws:

DNotesException - if an error occurs during evaluation of the formula

evaluate

java.util.List evaluate(java.lang.String formula,
                        DBaseDocument doc)
                        throws DNotesException

Evaluates a domino formula.

If the formula contains the name of a field, the formula takes the field from the document specified as the doc parameter.

0x0040Functions that affect the user interface do not work in evaluate. These include: 0x0040Command, 0x0040DbManager, 0x0040DbName, 0x0040DbTitle, 0x0040DDEExecute, 0x0041DDEInitiate, 0x0040DDEPoke, 0x0040DDETerminate, 0x0040DialogBox, 0x0040PickList, 0x0040PostedCommand, 0x0040Prompt, and 0x0040ViewTitle.

You cannot change a document with evaluate; you can only get a result. To change a document, write the result to the document with a method such as Document.replaceItemValue.

Parameters:

formula - The formula

doc - optional document as context for formula

Returns:

The result of the evaluation or null if an error occurred. A scalar result is returned as the first element.

Throws:

DNotesException - if an error occurs during evaluation of the formula

getEnvironmentValue

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

Given the name of an environment variable, retrieves its value.

Usage
This method retrieves the environment variable from the NOTES.INI file for the current session.

The method prepends "$" to the name before retrieving its value.

Do not use this method for string values.

Parameters:

name - the name of the environment variable to get.

Returns:

the value of the environment variable.

getEnvironmentValue

java.lang.Object getEnvironmentValue(java.lang.String name,
                                     boolean isSystem)

Given the name of an environment variable, retrieves its value.

Usage
This method retrieves the environment variable from the NOTES.INI file for the current session.

Do not use this method for string values.

Parameters:

name - the name of the environment variable to get.

isSystem - If true, the method uses the exact name of the environment variable. If false or omitted, the method prepends "$" to the name before retrieving its value.

Returns:

the value of the environment variable.

getEnvironmentString

java.lang.String getEnvironmentString(java.lang.String name)

Given the name of an environment variable, retrieves its value.

Usage
This method retrieves the environment variable from the NOTES.INI file for the current session.

The method prepends "$" to the name before retrieving its value.

Parameters:

name - the name of the environment variable

Returns:

the value of the environment variable

getEnvironmentString

java.lang.String getEnvironmentString(java.lang.String name,
                                      boolean isSystem)

Given the name of an environment variable, retrieves its value.

Usage
This method retrieves the environment variable from the NOTES.INI file for the current session.

Parameters:

name - the name of the environment variable

isSystem - If true, the method uses the exact name of the environment variable. If false or omitted, the method prepends "$" to the name before retrieving its value.

Returns:

the value of the environment variable

setEnvironmentString

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

Sets the value of an environment variable.

The method prepends "$" to the name before retrieving its value.

Parameters:

name - the name of the environment variable

value - The value of the environment variable.

setEnvironmentString

void setEnvironmentString(java.lang.String name,
                          java.lang.String value,
                          boolean isSystem)

Sets the value of a string environment variable.

Parameters:

name - the name of the environment variable

value - The value of the environment variable.

isSystem - If true, the method uses the exact name of the environment variable. If false or omitted, the method prepends "$" to the name before retrieving its value.

createLog

DLog createLog(java.lang.String name)

Creates a new Log object with the name you specify.

Parameters:

name - a name that identifies the log

Returns:

the newly created log

getAddressBooks

java.util.List getAddressBooks()

The Domino Directories and Personal Address Books that are known to the current session.

Usage

To find out if an address book is a Domino Directory or a Personal Address Book, use DDatabase.isPublicAddressBook() and DDatabase.isPrivateAddressBook() of DDatabase.

If the program runs on a workstation, both Domino Directories and Personal Address Books are included. If the program runs on a server or through remote (IIOP) calls, only Domino Directories on the server are included.

A database retrieved through getAddressBooks is closed. The following Database methods are available on the closed database: DDatabase.getFileName(), DDatabase.getFilePath(), DDatabase.isOpen(), DDatabase.isPrivateAddressBook(), DDatabase.isPublicAddressBook(), DDatabase.getSession(), and DDatabase.getServer(). To access all other properties and methods, you must explicitly open the database. See DDatabase.open() in DDatabase.

Returns:

list of DDatabase objects for all known personal address books

getAbbreviatedName

java.lang.String getAbbreviatedName(java.lang.String canonicalName)

Converts a canonical name to it's abbreviated form.

The canonical format for storing hierarchical names displays the hierarchical attribute of each component of the name.
Example: CN=Kurt Riede/OU=Development/O=BEAP
where:
CN is the common name
OU is the organizational unit
O is the organization
C is the country code

The abbreviated format of the example above is Kurt Riede/Development/BEAP.

Parameters:

canonicalName - a name in canonical form

Returns:

abbreviated form of the name

getCanonicalName

java.lang.String getCanonicalName(java.lang.String abbreviatedName)

Converts a abbreviated name to it's canonical form.

The canonical format for storing hierarchical names displays the hierarchical attribute of each component of the name.
Example: CN=Kurt Riede/OU=Development/O=BEAP
where:
CN is the common name
OU is the organizational unit
O is the organization
C is the country code

The abbreviated format of the example above is Kurt Riede/Development/BEAP.

Parameters:

abbreviatedName - a name in abbreviated form

Returns:

canonical form of the name

getAgentContext

DAgentContext getAgentContext()

Represents the agent environment of the current program, if an agent is running it. If the current program is not running from an agent, this property returns null.

Returns:

context of current agent

getCurrentTime

java.util.Calendar getCurrentTime()

Returns the current date/time.

If using IIOP or running as a server agent, the server date/time is returned. If running on the client, the date/time of the client is returned.

Returns:

current date/time

isValid

boolean isValid()

Indicates whether an instantiated Session object is still valid. For a remote operation, this method determines if the DIIOP server task considers the session valid. For a remote operation, iterative use of this method impacts performance.

Returns:

true if the Session object is still valid, else false

getNotesVersion

java.lang.String getNotesVersion()

The release of Domino the session is running on.

Returns:

version info

Since:

domingo 1.1

getPlatform

java.lang.String getPlatform()

The name of the platform the session is running on.

possible values:

Value	Platform
"Macintosh"	Macintosh
"MS-DOS"	MS-DOS
"Netware"	NetWare
"OS/2v1"	OS/2� 16-bit
"OS/2v2"	OS/2 32-bit
"OS/400"	OS/400
"Windows/16"	Windows 16-bit
"Windows/32"	Windows 32-bit
"UNIX"	UNIX (Sun, SCO, AIX�)

Returns:

name of platform

Since:

domingo 1.1

createDxlExporter

DDxlExporter createDxlExporter()
                               throws DNotesException

Creates a DxlExporter object.

Returns:

The newly created DxlExporter object.

Throws:

DNotesException - if the DxlExporter object cannot be created

getMailServer

java.lang.String getMailServer()

Returns the name of the mail server of the current user.

Returns:

name of mail server

getMailDatabaseName

java.lang.String getMailDatabaseName()

Returns the file/path of the mail database of the current users.

Returns:

file/path of mail database

getMailDatabase

DDatabase getMailDatabase()
                          throws DNotesException

Returns the mail database of the current user.

Returns:

mail database of current user

Throws:

DNotesException - if the mail database cannot be opened or, in case of a remote session, is not on the current server

getMailDatabase

DDatabase getMailDatabase(java.lang.String username)
                          throws DNotesException

Returns the mail database of a given user.

Parameters:

username - username

Returns:

mail database of a given user

Throws:

DNotesException - if the mail database cannot be opened or, in case of a remote session, is not on the current server

getMailDomain

java.lang.String getMailDomain()

Returns the name of the mail-domain of the current user.

Returns:

mail domain

resolve

DBase resolve(java.lang.String url)

Returns the Domino object that a URL addresses.

The general forms of URLs that address Domino objects are as follows:

protocol://host/database?OpenDatabase

protocol://host/database/view?OpenView

protocol://host/database/form?OpenForm

protocol://host/database/document?OpenDocument

protocol://host/database/agent?OpenAgent

For local calls, the protocol is "notes" and the host is empty so that the URL starts with "notes:///" ("notes," colon, and three slashes).

The database can be specified by name or replica ID. The name can include spaces (you can substitute plus signs for the spaces but it is not necessary). The name need not include the type suffix if it is NSF. The replica ID can be specified as the 16-digit ID by itself or the 16-digit ID prefixed by two underscores and suffixed by the file type (for example, NSF).

The view, form, document, or agent can be specified by name, universal ID, or note ID (not recommended because note IDs change between replicas).

The action (following the question mark) must be specified.

You can use getURL to specify the URL.

Parameters:

url - a URL that addresses a Domino object

Returns:

a Database, View, Form, Document, or Agent object. You must cast the return value to the expected type.

getServerName

java.lang.String getServerName()

Returns the full name of the server that the session is running on. If the server name is hierarchical, this property returns the fully distinguished name. This property is null if the session is not running on a server.

Returns:

name of the server that the session is running on

setTimeZone

void setTimeZone(java.util.TimeZone zone)

Sets the time zone of calendar instances that are created by domingo.

Parameters:

zone - the time zone

See Also:

DBaseDocument.getItemValueDate(String), DItem.getValueDateTime()

getTimeZone

java.util.TimeZone getTimeZone()

Returns the time zone of calendar instances that are created by domingo.

Returns:

zone the time zone

See Also:

DBaseDocument.getItemValueDate(String), DItem.getValueDateTime()