1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23 package de.bea.domingo;
24
25 import java.util.Calendar;
26 import java.util.List;
27 import java.util.TimeZone;
28
29 /***
30 * Is the root of the Notes Objects containment hierarchy, providing access to
31 * the other Domino objects, and represents the Domino environment of the
32 * current program.
33 *
34 * @author <a href=mailto:kriede@users.sourceforge.net>Kurt Riede</a>
35 */
36 public interface DSession extends DBase {
37
38 /***
39 * Indicates if the session is running on a server.
40 *
41 * @return <code>true</code> if the program is running on a server, <code>false</code> if the program is running
42 * on a workstation
43 *
44 * <p>
45 * <b>Usage </b>
46 * </p>
47 * <p>A remote (IIOP) session always runs on a server.</p>
48 * <p>A local session is running on a server if it is an agent in a server-
49 * based database, and the agent has one of the following triggers:</p>
50 * <p><ul>
51 * <li>When new mail arrives</li>
52 * <li>When documents have been created or modified</li>
53 * <li>When documents have been pasted</li>
54 * <li>On schedule hourly, daily, weekly, or monthly</li>
55 * </ul></p>
56 * <p>All other programs run on a workstation.</p>
57 */
58 boolean isOnServer();
59
60 /***
61 * Returns a database interface to a Notes database.
62 *
63 * @param serverName notes server name
64 * @param databaseName notes database filename
65 * @return DDatabase
66 * @throws DNotesException if the database cannot be opened
67 */
68 DDatabase getDatabase(String serverName, String databaseName) throws DNotesException;
69
70 /***
71 * The full name of the user or server that created the session.
72 *
73 * @return user name
74 */
75 String getUserName();
76
77 /***
78 * Creates an empty database and opens it. Because the new database is
79 * not based on a template, it is blank and does not contain any forms or
80 * views.
81 *
82 * @param serverName notes server name
83 * @param databaseName notes database filename
84 * @return DDatabase
85 */
86 DDatabase createDatabase(String serverName, String databaseName);
87
88 /***
89 * Returns a String value containing the common name (CN=) component
90 * of a hierarchical name.
91 *
92 * <p>Example:<br/>
93 * <pre>Kurt Riede</pre></p>
94 *
95 * @return common user name
96 */
97 String getCommonUserName();
98
99 /***
100 * returns a String value containing the canonical form of a
101 * hierarchical name.
102 *
103 * <p>Example:<br/>
104 * <pre>Kurt Riede/Development/BEAP</pre></p>
105 *
106 * @return canonical user name
107 */
108 String getCanonicalUserName();
109
110 /***
111 * Evaluates a domino formula.
112 *
113 * <p>If the formula contains the name of a field, you must use the
114 * 2-parameter method. The formula takes the field from the document
115 * specified as the <code>doc</code> parameter.</p>
116 *
117 * <p>0x0040Functions that affect the user interface do not work in evaluate.
118 * These include: 0x0040Command, 0x0040DbManager, 0x0040DbName,
119 * 0x0040DbTitle, 0x0040DDEExecute, 0x0041DDEInitiate, 0x0040DDEPoke,
120 * 0x0040DDETerminate, 0x0040DialogBox, 0x0040PickList, 0x0040PostedCommand,
121 * 0x0040Prompt, and 0x0040ViewTitle.</p>
122 *
123 * <p>You cannot change a document with evaluate; you can only get a
124 * result. To change a document, write the result to the document with a
125 * method such as Document.replaceItemValue.</p>
126 *
127 * @param formula The formula
128 * @return The result of the evaluation or <code>null</code> if an error
129 * occurred. A scalar result is returned as the first element.
130 * @throws DNotesException if an error occurs during evaluation of the formula
131 */
132 List evaluate(String formula) throws DNotesException;
133
134 /***
135 * Evaluates a domino formula.
136 *
137 * <p>If the formula contains the name of a field, the formula takes the
138 * field from the document specified as the <code>doc</code> parameter.</p>
139 *
140 * <p>0x0040Functions that affect the user interface do not work in evaluate.
141 * These include: 0x0040Command, 0x0040DbManager, 0x0040DbName,
142 * 0x0040DbTitle, 0x0040DDEExecute, 0x0041DDEInitiate, 0x0040DDEPoke,
143 * 0x0040DDETerminate, 0x0040DialogBox, 0x0040PickList, 0x0040PostedCommand,
144 * 0x0040Prompt, and 0x0040ViewTitle.</p>
145 *
146 * <p>You cannot change a document with evaluate; you can only get a
147 * result. To change a document, write the result to the document with a
148 * method such as Document.replaceItemValue.</p>
149 *
150 * @param formula The formula
151 * @param doc optional document as context for formula
152 * @return The result of the evaluation or <code>null</code> if an error
153 * occurred. A scalar result is returned as the first element.
154 * @throws DNotesException if an error occurs during evaluation of the formula
155 */
156 List evaluate(String formula, DBaseDocument doc) throws DNotesException;
157
158 /***
159 * Given the name of an environment variable, retrieves its value.
160 *
161 * <p><b>Usage</b><br/>
162 * This method retrieves the environment variable from the NOTES.INI file
163 * for the current session.</p>
164 * <p>The method prepends "$" to the name before retrieving its value.</p>
165 * <p>Do not use this method for string values.</p>
166 *
167 * @param name the name of the environment variable to get.
168 * @return the value of the environment variable.
169 */
170 Object getEnvironmentValue(String name);
171
172 /***
173 * Given the name of an environment variable, retrieves its value.
174 *
175 * <p><b>Usage</b><br/>
176 * This method retrieves the environment variable from the NOTES.INI file
177 * for the current session.</p>
178 * <p>Do not use this method for string values.</p>
179 *
180 * @param name the name of the environment variable to get.
181 * @param isSystem If <code>true</code>, the method uses the exact name of the
182 * environment variable. If false or omitted, the method
183 * prepends "$" to the name before retrieving its value.
184 * @return the value of the environment variable.
185 */
186 Object getEnvironmentValue(String name, boolean isSystem);
187
188 /***
189 * Given the name of an environment variable, retrieves its value.
190 *
191 * <p><b>Usage</b><br/>
192 * This method retrieves the environment variable from the NOTES.INI file
193 * for the current session.</p>
194 * <p>The method prepends "$" to the name before retrieving its value.</p>
195 *
196 * @param name the name of the environment variable
197 * @return the value of the environment variable
198 */
199 String getEnvironmentString(String name);
200
201 /***
202 * Given the name of an environment variable, retrieves its value.
203 *
204 * <p><b>Usage</b><br/>
205 * This method retrieves the environment variable from the NOTES.INI file
206 * for the current session.</p>
207 *
208 * @param name the name of the environment variable
209 * @param isSystem If <code>true</code>, the method uses the exact name of the
210 * environment variable. If false or omitted, the method
211 * prepends "$" to the name before retrieving its value.
212 * @return the value of the environment variable
213 */
214 String getEnvironmentString(String name, boolean isSystem);
215
216 /***
217 * Sets the value of an environment variable.
218 * <p>The method prepends "$" to the name before retrieving its value.</p>
219 *
220 * @param name the name of the environment variable
221 * @param value The value of the environment variable.
222 */
223 void setEnvironmentString(String name, String value);
224
225 /***
226 * Sets the value of a string environment variable.
227 *
228 * @param name the name of the environment variable
229 * @param value The value of the environment variable.
230 * @param isSystem If <code>true</code>, the method uses the exact name of the
231 * environment variable. If false or omitted, the method
232 * prepends "$" to the name before retrieving its value.
233 */
234 void setEnvironmentString(String name, String value, boolean isSystem);
235
236 /***
237 * Creates a new Log object with the name you specify.
238 *
239 * @param name a name that identifies the log
240 * @return the newly created log
241 */
242 DLog createLog(String name);
243
244 /***
245 * The Domino Directories and Personal Address Books that are known to the
246 * current session.
247 *
248 * <p><b>Usage</b></p>
249 * <p>To find out if an address book is a Domino Directory or a Personal
250 * Address Book, use {@link de.bea.domingo.DDatabase#isPublicAddressBook()}
251 * and {@link de.bea.domingo.DDatabase#isPrivateAddressBook()} of
252 * {@link de.bea.domingo.DDatabase}.</p>
253 * <p>If the program runs on a workstation, both Domino Directories and
254 * Personal Address Books are included. If the program runs on a server or
255 * through remote (IIOP) calls, only Domino Directories on the server are
256 * included.</p>
257 * <p>A database retrieved through <tt>getAddressBooks</tt> is closed.
258 * The following Database methods are available on the closed database:
259 * {@link de.bea.domingo.DDatabase#getFileName()},
260 * {@link de.bea.domingo.DDatabase#getFilePath()},
261 * {@link de.bea.domingo.DDatabase#isOpen()},
262 * {@link de.bea.domingo.DDatabase#isPrivateAddressBook()},
263 * {@link de.bea.domingo.DDatabase#isPublicAddressBook()},
264 * {@link de.bea.domingo.DDatabase#getSession()}, and
265 * {@link de.bea.domingo.DDatabase#getServer()}.
266 * To access all other properties and methods, you must explicitly open
267 * the database. See {@link de.bea.domingo.DDatabase#open()} in
268 * {@link de.bea.domingo.DDatabase}.</p>
269 *
270 * @return list of DDatabase objects for all known personal address books
271 */
272 List getAddressBooks();
273
274 /***
275 * Converts a canonical name to it's abbreviated form.
276 *
277 * <p>The canonical format for storing hierarchical names displays the
278 * hierarchical attribute of each component of the name.<br/>
279 * Example: <tt>CN=Kurt Riede/OU=Development/O=BEAP</tt><br/>
280 * where:<br/>
281 * <tt>CN</tt> is the common name<br/>
282 * <tt>OU</tt> is the organizational unit<br/>
283 * <tt>O</tt> is the organization<br/>
284 * <tt>C</tt> is the country code</p>
285 *
286 * <p>The abbreviated format of the example above is
287 * <tt>Kurt Riede/Development/BEAP</tt>. </p>
288 *
289 * @param canonicalName a name in canonical form
290 * @return abbreviated form of the name
291 */
292 String getAbbreviatedName(String canonicalName);
293
294 /***
295 * Converts a abbreviated name to it's canonical form.
296 *
297 * <p>The canonical format for storing hierarchical names displays the
298 * hierarchical attribute of each component of the name.<br/>
299 * Example: <tt>CN=Kurt Riede/OU=Development/O=BEAP</tt><br/>
300 * where:<br/>
301 * <tt>CN</tt> is the common name<br/>
302 * <tt>OU</tt> is the organizational unit<br/>
303 * <tt>O</tt> is the organization<br/>
304 * <tt>C</tt> is the country code</p>
305 *
306 * <p>The abbreviated format of the example above is
307 * <tt>Kurt Riede/Development/BEAP</tt>. </p>
308 *
309 * @param abbreviatedName a name in abbreviated form
310 * @return canonical form of the name
311 */
312 String getCanonicalName(String abbreviatedName);
313
314 /***
315 * Represents the agent environment of the current program, if an agent is
316 * running it. If the current program is not running from an agent, this
317 * property returns null.
318 *
319 * @return context of current agent
320 */
321 DAgentContext getAgentContext();
322
323 /***
324 * Returns the current date/time.
325 * <p>If using IIOP or running as a server agent, the server date/time is returned.
326 * If running on the client, the date/time of the client is returned.
327 *
328 * @return current date/time
329 */
330 Calendar getCurrentTime();
331
332 /***
333 * Indicates whether an instantiated Session object is still valid.
334 * For a remote operation, this method determines if the DIIOP server
335 * task considers the session valid.
336 * For a remote operation, iterative use of this method impacts performance.
337 *
338 * @return <tt>true</tt> if the Session object is still valid, else <tt>false</tt>
339 */
340 boolean isValid();
341
342 /***
343 * The release of Domino the session is running on.
344 *
345 * @return version info
346 * @since domingo 1.1
347 */
348 String getNotesVersion();
349
350 /***
351 * The name of the platform the session is running on.
352 *
353 * <p>possible values:</p>
354 * <p><table><tr><th>Value</th><th>Platform</th></tr>
355 * <tr><td>"Macintosh" </td><td>Macintosh</td></tr>
356 * <tr><td>"MS-DOS" </td><td>MS-DOS</td></tr>
357 * <tr><td>"Netware" </td><td>NetWare</td></tr>
358 * <tr><td>"OS/2v1" </td><td>OS/2� 16-bit</td></tr>
359 * <tr><td>"OS/2v2" </td><td>OS/2 32-bit </td></tr>
360 * <tr><td>"OS/400" </td><td>OS/400</td></tr>
361 * <tr><td>"Windows/16" </td><td>Windows 16-bit</td></tr>
362 * <tr><td>"Windows/32" </td><td>Windows 32-bit</td></tr>
363 * <tr><td>"UNIX" </td><td>UNIX (Sun, SCO, AIX�)</td></tr>
364 * </table>
365 *
366 * @return name of platform
367 * @since domingo 1.1
368 */
369 String getPlatform();
370
371 /***
372 * Creates a DxlExporter object.
373 *
374 * @return The newly created DxlExporter object.
375 * @throws DNotesException if the DxlExporter object cannot be created
376 */
377 DDxlExporter createDxlExporter() throws DNotesException;
378
379 /***
380 * Returns the name of the mail server of the current user.
381 *
382 * @return name of mail server
383 */
384 String getMailServer();
385
386 /***
387 * Returns the file/path of the mail database of the current users.
388 *
389 * @return file/path of mail database
390 */
391 String getMailDatabaseName();
392
393 /***
394 * Returns the mail database of the current user.
395 *
396 * @return mail database of current user
397 * @throws DNotesException if the mail database cannot be opened or, in case
398 * of a remote session, is not on the current server
399 */
400 DDatabase getMailDatabase() throws DNotesException;
401
402 /***
403 * Returns the mail database of a given user.
404 *
405 * @param username username
406 * @return mail database of a given user
407 * @throws DNotesException if the mail database cannot be opened or, in case
408 * of a remote session, is not on the current server
409 */
410 DDatabase getMailDatabase(String username) throws DNotesException;
411
412 /***
413 * Returns the name of the mail-domain of the current user.
414 *
415 * @return mail domain
416 */
417 String getMailDomain();
418
419 /***
420 * Returns the Domino object that a URL addresses.
421 *
422 * <p>The general forms of URLs that address Domino objects are as follows:</p>
423 *
424 * <pre>protocol://host/database?OpenDatabase</pre>
425 * <pre>protocol://host/database/view?OpenView</pre>
426 * <pre>protocol://host/database/form?OpenForm</pre>
427 * <pre>protocol://host/database/document?OpenDocument</pre>
428 * <pre>protocol://host/database/agent?OpenAgent</pre>
429 *
430 * <p>For local calls, the protocol is "notes" and the host is empty so
431 * that the URL starts with "notes:///" ("notes," colon, and three slashes).</p>
432 *
433 * <p>The database can be specified by name or replica ID. The name can
434 * include spaces (you can substitute plus signs for the spaces but it is
435 * not necessary). The name need not include the type suffix if it is NSF.
436 * The replica ID can be specified as the 16-digit ID by itself or the
437 * 16-digit ID prefixed by two underscores and suffixed by the file type
438 * (for example, NSF).</p>
439 *
440 * <p>The view, form, document, or agent can be specified by name,
441 * universal ID, or note ID (not recommended because note IDs change between
442 * replicas).</p>
443 *
444 * <p>The action (following the question mark) must be specified.</p>
445 *
446 * <p>You can use getURL to specify the URL.</p>
447 *
448 * @param url a URL that addresses a Domino object
449 * @return a Database, View, Form, Document, or Agent object. You must cast
450 * the return value to the expected type.
451 */
452 DBase resolve(String url);
453
454 /***
455 * Returns the full name of the server that the session is running on.
456 * If the server name is hierarchical, this property returns the fully
457 * distinguished name. This property is null if the session is not running
458 * on a server.
459 *
460 * @return name of the server that the session is running on
461 */
462 String getServerName();
463
464 /***
465 * Sets the time zone of calendar instances that are created by domingo.
466 *
467 * @param zone the time zone
468 *
469 * @see DBaseDocument#getItemValueDate(String)
470 * @see DItem#getValueDateTime()
471 */
472 void setTimeZone(TimeZone zone);
473
474 /***
475 * Returns the time zone of calendar instances that are created by domingo.
476 *
477 * @return zone the time zone
478 *
479 * @see DBaseDocument#getItemValueDate(String)
480 * @see DItem#getValueDateTime()
481 */
482 TimeZone getTimeZone();
483 }