de.bea.domingo.proxy
Class SessionProxy

java.lang.Object
  de.bea.domingo.monitor.AbstractMonitorEnabled
      de.bea.domingo.proxy.BaseProxy
          de.bea.domingo.proxy.SessionProxy

All Implemented Interfaces:

DBase, DSession, MonitorEnabled, java.io.Serializable

public final class SessionProxy
extends BaseProxy
implements DSession

Notes session.

Author:

Kurt Riede

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class de.bea.domingo.proxy.BaseProxy

BaseProxy.DocumentCollectionIterator

Field Summary

Fields inherited from class de.bea.domingo.proxy.BaseProxy

DATETIME_STRING_LENGTH, EMPTY_STRING, MAX_DATETIME_LENGTH, NUM_DATETIME_VALUES, RESOURCES

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 abreviatedName) 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.
static DSession	getInstance(NotesProxyFactory theFactory, lotus.domino.Session theSession, DNotesMonitor monitor) Creates an encapsulated notes session object.
InternationalProxy	getInternational()
DDatabase	getMailDatabase() Returns the mail database of the current user.
DDatabase	getMailDatabase(java.lang.String username) Returns the mail database of a given user. The mail server of the current user is used as registration server.
java.lang.String	getMailDatabaseName() Returns the file/path of the mail database of the current users. The two methods getMailServer()() and getMailDatabaseName()() are synchronized to prevent double-reading of mail information.
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. The two methods getMailServer()() and getMailDatabaseName()() are synchronized to prevent double-reading of mail information.
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.
(package private) static java.lang.String	parseLocationNoteId(java.lang.String locationValue) Extracts the note-id of the current location from a location value as used in the file notes.ini.
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.
java.lang.String	toString() Returns a short description of an instance.

Methods inherited from class de.bea.domingo.proxy.BaseProxy

checkSession, clearNotesObject, convertCalendarsToNotesDateTime, convertListToVector, convertNotesDateTimesToCalendar, convertVectorToList, createCalendar, createDateRange, createDateTime, decrementDateTimeCounter, finalize, getCountDateTime, getDSession, getFactory, getNotesObject, getParent, incrementDateTimeCounter, newException, newException, newException, newRuntimeException, newRuntimeException, newRuntimeException, recycleDateTimeList, refereceHashCode, toStringGeneric, toStringIntern

Methods inherited from class de.bea.domingo.monitor.AbstractMonitorEnabled

getMonitor, setMonitor

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface de.bea.domingo.DBase

equals, hashCode

Method Detail

getInstance

public static DSession getInstance(NotesProxyFactory theFactory,
                                   lotus.domino.Session theSession,
                                   DNotesMonitor monitor)

Creates an encapsulated notes session object.

Parameters:

theFactory - the controlling factory

theSession - the Notes Session

monitor - the monitor

Returns:

a session object

getInternational

public InternationalProxy getInternational()

Returns:

Returns the international.

isOnServer

public boolean isOnServer()

Indicates if the session is running on a server.

Specified by:

isOnServer in interface DSession

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.

See Also:

DSession.isOnServer()

getDatabase

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

Returns a database interface to a Notes database.

Specified by:

getDatabase in interface DSession

Parameters:

serverName - notes server name

databaseName - notes database filename

Returns:

DDatabase

Throws:

DNotesException - if the database cannot be opened

See Also:

DSession.getDatabase(java.lang.String, java.lang.String)

toString

public java.lang.String toString()

Description copied from interface: DBase

Returns a short description of an instance.

Specified by:

toString in interface DBase

Overrides:

toString in class java.lang.Object

Returns:

a string representation of the object.

See Also:

Object.toString()

getUserName

public java.lang.String getUserName()

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

Specified by:

getUserName in interface DSession

Returns:

user name

See Also:

DSession.getUserName()

createDatabase

public 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.

Specified by:

createDatabase in interface DSession

Parameters:

serverName - notes server name

databaseName - notes database filename

Returns:

DDatabase

See Also:

DSession.createDatabase(java.lang.String, java.lang.String)

getCommonUserName

public java.lang.String getCommonUserName()

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

Example:

Kurt Riede

Specified by:

getCommonUserName in interface DSession

Returns:

common user name

See Also:

DSession.getCommonUserName()

getCanonicalUserName

public java.lang.String getCanonicalUserName()

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

Example:

Kurt Riede/Development/BEAP

Specified by:

getCanonicalUserName in interface DSession

Returns:

canonical user name

See Also:

DSession.getCanonicalUserName()

evaluate

public 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.

Specified by:

evaluate in interface DSession

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

See Also:

DSession.evaluate(java.lang.String)

evaluate

public 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.

Specified by:

evaluate in interface DSession

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

See Also:

DSession.evaluate(java.lang.String, de.bea.domingo.DBaseDocument)

getEnvironmentString

public 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.

Specified by:

getEnvironmentString in interface DSession

Parameters:

name - the name of the environment variable

Returns:

the value of the environment variable

See Also:

DSession.getEnvironmentString(java.lang.String)

getEnvironmentValue

public 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.

Specified by:

getEnvironmentValue in interface DSession

Parameters:

name - the name of the environment variable to get.

Returns:

the value of the environment variable.

See Also:

DSession.getEnvironmentValue(java.lang.String)

getEnvironmentString

public 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.

Specified by:

getEnvironmentString in interface DSession

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

See Also:

DSession.getEnvironmentString(java.lang.String, boolean)

getEnvironmentValue

public 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.

Specified by:

getEnvironmentValue in interface DSession

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.

See Also:

DSession.getEnvironmentValue(java.lang.String, boolean)

setEnvironmentString

public 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.

Specified by:

setEnvironmentString in interface DSession

Parameters:

name - the name of the environment variable

value - The value of the environment variable.

See Also:

DSession.setEnvironmentString(java.lang.String, java.lang.String)

setEnvironmentString

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

Sets the value of a string environment variable.

Specified by:

setEnvironmentString in interface DSession

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.

See Also:

DSession.setEnvironmentString(java.lang.String, java.lang.String, boolean)

createLog

public DLog createLog(java.lang.String name)

Creates a new Log object with the name you specify.

Specified by:

createLog in interface DSession

Parameters:

name - a name that identifies the log

Returns:

the newly created log

See Also:

DSession.createLog(java.lang.String)

getAddressBooks

public 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.

Specified by:

getAddressBooks in interface DSession

Returns:

list of DDatabase objects for all known personal address books

See Also:

DSession.getAddressBooks()

getAbbreviatedName

public 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.

Specified by:

getAbbreviatedName in interface DSession

Parameters:

canonicalName - a name in canonical form

Returns:

abbreviated form of the name

See Also:

DSession.getAbbreviatedName(java.lang.String)

getCanonicalName

public java.lang.String getCanonicalName(java.lang.String abreviatedName)

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.

Specified by:

getCanonicalName in interface DSession

Parameters:

abreviatedName - a name in abbreviated form

Returns:

canonical form of the name

See Also:

DSession.getCanonicalName(java.lang.String)

getAgentContext

public 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.

Specified by:

getAgentContext in interface DSession

Returns:

context of current agent

See Also:

DSession.getAgentContext()

getCurrentTime

public 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.

Specified by:

getCurrentTime in interface DSession

Returns:

current date/time

See Also:

DSession.getCurrentTime()

isValid

public 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.

Specified by:

isValid in interface DSession

Returns:

true if the Session object is still valid, else false

See Also:

DSession.isValid()

getNotesVersion

public java.lang.String getNotesVersion()

The release of Domino the session is running on.

Specified by:

getNotesVersion in interface DSession

Returns:

version info

See Also:

DSession.getNotesVersion()

getPlatform

public 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�)

Specified by:

getPlatform in interface DSession

Returns:

name of platform

See Also:

DSession.getPlatform()

createDxlExporter

public DDxlExporter createDxlExporter()
                               throws DNotesException

Creates a DxlExporter object.

Specified by:

createDxlExporter in interface DSession

Returns:

The newly created DxlExporter object.

Throws:

DNotesException - if the DxlExporter object cannot be created

See Also:

DSession.createDxlExporter()

getMailServer

public java.lang.String getMailServer()

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

The two methods getMailServer()() and getMailDatabaseName()() are synchronized to prevent double-reading of mail information. The field fMailInfoMutex is used as the locking mutex.

Specified by:

getMailServer in interface DSession

Returns:

name of mail server

See Also:

DSession.getMailServer()

getMailDatabaseName

public java.lang.String getMailDatabaseName()

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

The two methods getMailServer()() and getMailDatabaseName()() are synchronized to prevent double-reading of mail information. The field mailServer is used as the locking mutex.

Specified by:

getMailDatabaseName in interface DSession

Returns:

file/path of mail database

See Also:

DSession.getMailDatabaseName()

getMailDatabase

public DDatabase getMailDatabase()
                          throws DNotesException

Returns the mail database of the current user.

Specified by:

getMailDatabase in interface DSession

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

See Also:

DSession.getMailDatabase()

getMailDatabase

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

Returns the mail database of a given user.

The mail server of the current user is used as registration server.

Specified by:

getMailDatabase in interface DSession

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

See Also:

DSession.getMailDatabase(), DSession.getMailDatabase(String)

getMailDomain

public java.lang.String getMailDomain()

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

Specified by:

getMailDomain in interface DSession

Returns:

mail domain

See Also:

DSession.getMailDomain()

resolve

public 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.

Specified by:

resolve in interface DSession

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.

See Also:

DSession.resolve(String)

parseLocationNoteId

static java.lang.String parseLocationNoteId(java.lang.String locationValue)

Extracts the note-id of the current location from a location value as used in the file notes.ini.

The note-id is between the last two commas in the string.

Example from notes.ini: Location=Office (Network),9EA,CN=Kurt Riede/O=acme

Parameters:

locationValue -

Returns:

note-Id of location value

getServerName

public 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.

Specified by:

getServerName in interface DSession

Returns:

name of the server that the session is running on

See Also:

DSession.getServerName()

setTimeZone

public void setTimeZone(java.util.TimeZone zone)

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

Specified by:

setTimeZone in interface DSession

Parameters:

zone - the time zone

See Also:

DSession.setTimeZone(java.util.TimeZone)

getTimeZone

public java.util.TimeZone getTimeZone()

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

Specified by:

getTimeZone in interface DSession

Returns:

zone the time zone

See Also:

DSession.getTimeZone()