de.jakop.lotus.domingo.DSession Maven / Gradle / Ivy
/*
* This file is part of Domingo
* an Open Source Java-API to Lotus Notes/Domino
* originally hosted at http://domingo.sourceforge.net, now available
* at https://github.com/fjakop/domingo
*
* Copyright (c) 2003-2007 Beck et al. projects GmbH Munich, Germany (http://www.bea.de)
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
package de.jakop.lotus.domingo;
import java.util.Calendar;
import java.util.List;
import java.util.TimeZone;
/**
* 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
*/
public interface DSession extends DBase {
/**
* Indicates if the session is running on a server.
*
* @return 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.
*/
boolean isOnServer();
/**
* Returns a database interface to a Notes database.
*
* @param serverName notes server name
* @param databaseName notes database filename
* @return DDatabase
* @throws DNotesException if the database cannot be opened
*/
DDatabase getDatabase(String serverName, String databaseName) throws DNotesException;
/**
* The full name of the user or server that created the session.
*
* @return user name
*/
String getUserName();
/**
* 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.
*
* @param serverName notes server name
* @param databaseName notes database filename
* @return DDatabase
*/
DDatabase createDatabase(String serverName, String databaseName);
/**
* Returns a String value containing the common name (CN=) component
* of a hierarchical name.
*
* Example:
*
Kurt Riede
*
* @return common user name
*/
String getCommonUserName();
/**
* returns a String value containing the canonical form of a
* hierarchical name.
*
* Example:
*
Kurt Riede/Development/BEAP
*
* @return canonical user name
*/
String getCanonicalUserName();
/**
* 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.
*
* @param formula The formula
* @return 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
*/
List evaluate(String formula) 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.
*
* @param formula The formula
* @param doc optional document as context for formula
* @return 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
*/
List evaluate(String formula, DBaseDocument doc) throws DNotesException;
/**
* 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.
*
* @param name the name of the environment variable to get.
* @return the value of the environment variable.
*/
Object getEnvironmentValue(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.
* Do not use this method for string values.
*
* @param name the name of the environment variable to get.
* @param 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.
* @return the value of the environment variable.
*/
Object getEnvironmentValue(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.
* The method prepends "$" to the name before retrieving its value.
*
* @param name the name of the environment variable
* @return the value of the environment variable
*/
String getEnvironmentString(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.
*
* @param name the name of the environment variable
* @param 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.
* @return the value of the environment variable
*/
String getEnvironmentString(String name, boolean isSystem);
/**
* Sets the value of an environment variable.
* The method prepends "$" to the name before retrieving its value.
*
* @param name the name of the environment variable
* @param value The value of the environment variable.
*/
void setEnvironmentString(String name, String value);
/**
* Sets the value of a string environment variable.
*
* @param name the name of the environment variable
* @param value The value of the environment variable.
* @param 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.
*/
void setEnvironmentString(String name, String value, boolean isSystem);
/**
* Creates a new Log object with the name you specify.
*
* @param name a name that identifies the log
* @return the newly created log
*/
DLog createLog(String name);
/**
* 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 {@link DDatabase#isPublicAddressBook()}
* and {@link DDatabase#isPrivateAddressBook()} of
* {@link 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:
* {@link DDatabase#getFileName()},
* {@link DDatabase#getFilePath()},
* {@link DDatabase#isOpen()},
* {@link DDatabase#isPrivateAddressBook()},
* {@link DDatabase#isPublicAddressBook()},
* {@link DDatabase#getSession()}, and
* {@link DDatabase#getServer()}.
* To access all other properties and methods, you must explicitly open
* the database. See {@link DDatabase#open()} in
* {@link DDatabase}.
*
* @return list of DDatabase objects for all known personal address books
*/
List getAddressBooks();
/**
* 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.
*
* @param canonicalName a name in canonical form
* @return abbreviated form of the name
*/
String getAbbreviatedName(String canonicalName);
/**
* 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.
*
* @param abbreviatedName a name in abbreviated form
* @return canonical form of the name
*/
String getCanonicalName(String abbreviatedName);
/**
* 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.
*
* @return context of current agent
*/
DAgentContext getAgentContext();
/**
* 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.
*
* @return current date/time
*/
Calendar getCurrentTime();
/**
* 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.
*
* @return true if the Session object is still valid, else false
*/
boolean isValid();
/**
* The release of Domino the session is running on.
*
* @return version info
* @since domingo 1.1
*/
String getNotesVersion();
/**
* 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�)
*
* @return name of platform
* @since domingo 1.1
*/
String getPlatform();
/**
* Creates a DxlExporter object.
*
* @return The newly created DxlExporter object.
* @throws DNotesException if the DxlExporter object cannot be created
*/
DDxlExporter createDxlExporter() throws DNotesException;
/**
* Returns the name of the mail server of the current user.
*
* @return name of mail server
*/
String getMailServer();
/**
* Returns the file/path of the mail database of the current users.
*
* @return file/path of mail database
*/
String getMailDatabaseName();
/**
* Returns the mail database of the current user.
*
* @return 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
*/
DDatabase getMailDatabase() throws DNotesException;
/**
* Returns the mail database of a given user.
*
* @param username username
* @return 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
*/
DDatabase getMailDatabase(String username) throws DNotesException;
/**
* Returns the name of the mail-domain of the current user.
*
* @return mail domain
*/
String getMailDomain();
/**
* 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.
*
* @param url a URL that addresses a Domino object
* @return a Database, View, Form, Document, or Agent object. You must cast
* the return value to the expected type.
*/
DBase resolve(String url);
/**
* 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.
*
* @return name of the server that the session is running on
*/
String getServerName();
/**
* Sets the time zone of calendar instances that are created by domingo.
*
* @param zone the time zone
*
* @see DBaseDocument#getItemValueDate(String)
* @see DItem#getValueDateTime()
*/
void setTimeZone(TimeZone zone);
/**
* Returns the time zone of calendar instances that are created by domingo.
*
* @return zone the time zone
*
* @see DBaseDocument#getItemValueDate(String)
* @see DItem#getValueDateTime()
*/
TimeZone getTimeZone();
}