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.io.Writer;
26 import java.util.Calendar;
27 import java.util.Iterator;
28 import java.util.List;
29 import java.util.TimeZone;
30
31 /***
32 * Base interface for all concrete document interfaces.
33 *
34 * @author <a href=mailto:kriede@users.sourceforge.net>Kurt Riede</a>
35 */
36 public interface DBaseDocument extends DBase {
37
38 /***
39 * Return the database that contains a document.
40 *
41 * @return the database that contains a document
42 */
43 DDatabase getParentDatabase();
44
45 /***
46 * Returns the first item of a specified name in a document.
47 *
48 * <p>A document may contain more than one item of the same name.
49 * To access other than the first item, use the Items property.</p>
50 * <p>If the value of a field is computed for display, the value is not
51 * stored as an item and is inaccessible from a Document object.
52 * In some cases, you can access the field value another way.
53 * For example, if a document has a DateComposed field computed for display
54 * with the formula @Created, use getCreated.</p>
55 *
56 * <p><b>Using this method to get normal items (non-rich text)</b><br/>
57 * To get a normal item, explicitly cast the return value from getFirstItem to DItem.
58 * <pre>
59 * DDocument doc;
60 * //...set value of doc...
61 * DItem item = (DItem)doc.getFirstItem("Body");
62 * </pre></p>
63 *
64 * <p><b>Using this method to get rich text items</b><br/>
65 * To get a rich text item, explicitly cast the return value from getFirstItem to DRichTextItem.
66 * <pre>
67 * DDocument doc;
68 * //...set value of doc...
69 * DRichTextItem rtitem = (DRichTextItem)doc.getFirstItem("Body");
70 * </pre></p>
71 *
72 * @param name name of an item
73 * @return DBaseItem
74 */
75 DBaseItem getFirstItem(String name);
76
77 /***
78 * Iterator for all items in a document.
79 *
80 * <p><b>Note</b></p>
81 * Values set as <code>int</code>, are handled (by Notes) as a type
82 * Number and returned to Java as a Double.
83 *
84 * @return Iterator for all items in a document. These are normal
85 * <code>DItem</code> as well as <code>DRichTextItems</code>
86 */
87 Iterator getItems();
88
89 /***
90 * The date a document was created.
91 *
92 * @return Calendar created date
93 */
94 Calendar getCreated();
95
96 /***
97 * Creates a new empty item in a document. A empty item has a value of type
98 * String that is an empty String ("").
99 *
100 * <p><b>Note</b><br/>
101 * In general, replaceItemValue is favored over appendItemValue. If an
102 * item of the same name already exists in a document, appendItemValue
103 * creates a second item of the same name, and the duplicate items are not
104 * accessible through most methods. If you are creating a new document,
105 * appendItemValue is safe.</p>
106 *
107 * @param name name of an item
108 * @return DItem
109 */
110 DItem appendItemValue(String name);
111
112 /***
113 * Creates a new item in a document and sets the item value.
114 *
115 * <p><b>Note</b><br/>
116 * In general, replaceItemValue is favored over appendItemValue. If an
117 * item of the same name already exists in a document, appendItemValue
118 * creates a second item of the same name, and the duplicate items are not
119 * accessible through most methods. If you are creating a new document,
120 * appendItemValue is safe.</p>
121 *
122 * @param name name of an item
123 * @param value The value of the new item.
124 * @return DItem
125 */
126 DItem appendItemValue(String name, String value);
127
128 /***
129 * Creates a new item in a document and sets the item value.
130 *
131 * <p><b>Note</b><br/>
132 * In general, replaceItemValue is favored over appendItemValue. If an
133 * item of the same name already exists in a document, appendItemValue
134 * creates a second item of the same name, and the duplicate items are not
135 * accessible through most methods. If you are creating a new document,
136 * appendItemValue is safe.</p>
137 *
138 * <p><b>Note</b></p>
139 * The value given as <code>int</code> is handled (by Notes) as a type
140 * Number and returned to Java as a Double.
141 *
142 * @param name name of an item
143 * @param value The value of the new item.
144 * @return DItem
145 */
146 DItem appendItemValue(String name, int value);
147
148 /***
149 * Creates a new item in a document and sets the item value.
150 *
151 * <p><b>Note</b><br/>
152 * In general, replaceItemValue is favored over appendItemValue. If an
153 * item of the same name already exists in a document, appendItemValue
154 * creates a second item of the same name, and the duplicate items are not
155 * accessible through most methods. If you are creating a new document,
156 * appendItemValue is safe.</p>
157 *
158 * @param name name of an item
159 * @param value The value of the new item.
160 * @return DItem
161 */
162 DItem appendItemValue(String name, double value);
163
164 /***
165 * Creates a new item in a document and sets the item value.
166 * The milliseconds are cut off.
167 *
168 * <p><b>Note</b><br/>
169 * In general, replaceItemValue is favored over appendItemValue. If an
170 * item of the same name already exists in a document, appendItemValue
171 * creates a second item of the same name, and the duplicate items are not
172 * accessible through most methods. If you are creating a new document,
173 * appendItemValue is safe.</p>
174 *
175 * @param name name of an item
176 * @param value The value of the new item.
177 * @return DItem
178 */
179 DItem appendItemValue(String name, Calendar value);
180
181 /***
182 * Creates a new item in a document and sets the item value.
183 *
184 * <p><b>Note</b><br/>
185 * In general, replaceItemValue is favored over appendItemValue. If an
186 * item of the same name already exists in a document, appendItemValue
187 * creates a second item of the same name, and the duplicate items are not
188 * accessible through most methods. If you are creating a new document,
189 * appendItemValue is safe.</p>
190 *
191 * @param name name of an item
192 * @param values The value of the new item as a list of String, Integer,
193 * Double, or java.util.Calendar elements
194 * @return DItem
195 */
196 DItem appendItemValue(String name, List values);
197
198 /***
199 * Replaces all items of the specified name with one new item, which is
200 * assigned the specified value.
201 * <p>If the document does not contain an item with the specified name, this
202 * method creates a new item and adds it to the document.</p>
203 *
204 * @param name name of an item
205 * @param value The value of the new item.
206 * @return DItem
207 */
208 DItem replaceItemValue(String name, String value);
209
210 /***
211 * Replaces all items of the specified name with one new item, which is
212 * assigned the specified value.
213 * <p>If the document does not contain an item with the specified name, this
214 * method creates a new item and adds it to the document.</p>
215 *
216 * @param name name of an item
217 * @param value The value of the new item.
218 * @return DItem
219 */
220 DItem replaceItemValue(String name, int value);
221
222 /***
223 * Replaces all items of the specified name with one new item, which is
224 * assigned the specified value.
225 * <p>If the document does not contain an item with the specified name, this
226 * method creates a new item and adds it to the document.</p>
227 *
228 * @param name name of an item
229 * @param value The value of the new item.
230 * @return DItem
231 */
232 DItem replaceItemValue(String name, Integer value);
233
234 /***
235 * Replaces all items of the specified name with one new item, which is
236 * assigned the specified value.
237 * <p>If the document does not contain an item with the specified name, this
238 * method creates a new item and adds it to the document.</p>
239 *
240 * @param name name of an item
241 * @param value The value of the new item
242 * @return DItem
243 */
244 DItem replaceItemValue(String name, double value);
245
246 /***
247 * Replaces all items of the specified name with one new item, which is
248 * assigned the specified value.
249 * <p>If the document does not contain an item with the specified name, this
250 * method creates a new item and adds it to the document.</p>
251 *
252 * @param name name of an item
253 * @param value The value of the new item
254 * @return DItem
255 */
256 DItem replaceItemValue(String name, Double value);
257
258 /***
259 * Replaces all items of the specified name with one new item, which is
260 * assigned the specified value.
261 * <p>If the document does not contain an item with the specified name, this
262 * method creates a new item and adds it to the document.</p>
263 *
264 * The milliseconds are cut off.
265 *
266 * @param name name of an item
267 * @param value The value of the new item
268 * @return DItem
269 */
270 DItem replaceItemValue(String name, Calendar value);
271
272 /***
273 * Replaces all items of the specified name with one new item, which is
274 * assigned the specified value.
275 * <p>If the document does not contain an item with the specified name, this
276 * method creates a new item and adds it to the document.</p>
277 *
278 * @param name name of an item
279 * @param value The value of the new item
280 * @return DItem
281 */
282 DItem replaceItemValue(String name, TimeZone value);
283
284 /***
285 * Replaces all items of the specified name with one new item, which is
286 * assigned the specified value.
287 * <p>If the document does not contain an item with the specified name, this
288 * method creates a new item and adds it to the document.</p>
289 * <p>If both calendars are null, an item with an empty string is created.
290 * If only one calendar is not null, this calendar is stored as a single
291 * date value.</p>
292 *
293 * The milliseconds are cut off.
294 *
295 * @param name name of an item
296 * @param value The value of the new item
297 * @return DItem
298 */
299 DItem replaceItemValue(String name, DDateRange value);
300
301 /***
302 * Replaces all items of the specified name with one new item, which is
303 * assigned the specified value.
304 * <p>If the document does not contain an item with the specified name,
305 * this method creates a new item and adds it to the document.</p>
306 * <p>If both calendars are null, an item with an empty string is created.
307 * If only one calendar is not null, this calendar is stored as a single
308 * date value.</p>
309 * The milliseconds are cut off.
310 *
311 * @param name name of an item
312 * @param calendar1 start date/time of range
313 * @param calendar2 end date/time of range
314 * @return DItem
315 */
316 DItem replaceItemValue(String name, Calendar calendar1, Calendar calendar2);
317
318 /***
319 * Replaces all items of the specified name with one new item, which is
320 * assigned the specified value.
321 * <p>If the document does not contain an item with the specified name, this
322 * method creates a new item and adds it to the document.</p>
323 *
324 * @param name name of an item
325 * @param values The new value of the item as a list of String, Integer,
326 * Double, or java.util.Calendar elements
327 * @return DItem
328 */
329 DItem replaceItemValue(String name, List values);
330
331 /***
332 * Saves any changes you have made to a document.
333 *
334 * <p><b>Note</b>
335 * If the document is a <code>DProfileDocument</code>, a call to the
336 * <code>save</code> method is only successful to a newly created document
337 * if a item was appended.
338 * </p>
339 *
340 * @return <code>true</code> of successfully saved, else <code>false</code>
341 * @throws DNotesRuntimeException if the document cannot be saved
342 * @see #save(boolean)
343 * @see #save(boolean, boolean)
344 */
345 boolean save() throws DNotesRuntimeException;
346
347 /***
348 * Saves any changes you have made to a document.
349 *
350 * <p><b>Note</b>
351 * If the document is a <code>DProfileDocument</code>, a call to the
352 * <code>save</code> method is only successful to a newly created document
353 * if a item was appended.
354 * </p>
355 *
356 * @param force If true, the document is saved even if someone else edits
357 * and saves the document while the program is running. The
358 * last version of the document that was saved wins; the
359 * earlier version is discarded. If false, and someone else
360 * edits the document while the program is running, the
361 * makeresponse argument determines what happens.
362 * @return <code>true</code> of successfully saved, else <code>false</code>
363 * @throws DNotesRuntimeException if the document cannot be saved
364 * @see #save()
365 * @see #save(boolean, boolean)
366 */
367 boolean save(boolean force) throws DNotesRuntimeException;
368
369 /***
370 * Saves any changes you have made to a document.
371 *
372 * <p><b>Note</b>
373 * If the document is a <code>DProfileDocument</code>, a call to the
374 * <code>save</code> method is only successful to a newly created document
375 * if a item was appended.
376 * </p>
377 *
378 * @param force If true, the document is saved even if someone else edits
379 * and saves the document while the program is running. The
380 * last version of the document that was saved wins; the
381 * earlier version is discarded. If false, and someone else
382 * edits the document while the program is running, the
383 * makeresponse argument determines what happens.
384 * @param makeresponse If true, the current document becomes a response to
385 * the original document (this is what the replicator does
386 * when there's a replication conflict). If false, the save is
387 * canceled. If the force parameter is true, the makeresponse
388 * parameter has no effect.
389 * @return <code>true</code> of successfully saved, else <code>false</code>
390 * @throws DNotesRuntimeException if the document cannot be saved
391 * @see #save()
392 * @see #save(boolean)
393 */
394 boolean save(boolean force, boolean makeresponse) throws DNotesRuntimeException;
395
396 /***
397 * Returns a representation of a file attachment.
398 * You can use this method to find file attachments that are not contained
399 * in a rich text item (such as an attachment in a Release 2 database) as
400 * well as file attachments that are contained in a rich text item.
401 *
402 * <p>The Parent property for the returned EmbeddedObject returns null,
403 * since it was not accessed through a RichTextItem.</p>
404 *
405 * @param filename The file name of the file attachment.
406 * @return A representation of the file attachment. Returns null if an
407 * attachment with the specified name is not found.
408 */
409 DEmbeddedObject getAttachment(String filename);
410
411 /***
412 * Returns all embedded objects.
413 *
414 * This method does include OLE/2 and OLE/1 objects created in Release 4
415 * and higher. It also includes objects in the document that were
416 * originally embedded in the document's form. Such objects must have been
417 * activated, modified, and re-saved in order to be returned by this
418 * property (otherwise they remain a part of the form, not the document).
419 *
420 * <p>The list is empty if the document contains no embedded objects.</p>
421 *
422 * <p><b>Note:</b></p>
423 * <p>Embedded objects and object links are not supported for OS/2, UNIX, and
424 * the Macintosh. File attachments are supported on all platforms.</p>
425 *
426 * @return an iterator supplying all embedded objects
427 */
428 Iterator getEmbeddedObjects();
429
430 /***
431 * Returns all embedded objects that are attachments.
432 *
433 * The list is empty if the document contains no attachments.
434 * @return a list of all embedded objects
435 */
436 List getAttachments();
437
438 /***
439 * Removes an item from a document.
440 *
441 * @param name The name of the item to remove from the document. If more
442 * than one item has the specified name, all items with this name are
443 * removed. If there is no item with the specified name, the method does
444 * nothing.
445 *
446 * <p>You can achieve the same result with remove in Item.
447 * To keep the changes to the document, you must call save after removing
448 * the item.</p>
449 */
450 void removeItem(String name);
451
452 /***
453 * Permanently removes a document from a database.
454 *
455 * If another user modifies the document after your program opens it,
456 * the document is not removed.
457 *
458 * @return <code>true</code> if the document is successfully removed or if
459 * the document is not contained in a database (then a exception should be
460 * logged),
461 * <code>false</code> if the document is not deleted because another user
462 * modified it and the force parameter is set to false.
463 */
464 boolean remove();
465
466 /***
467 * Permanently removes a document from a database.
468 *
469 * @param force If true, the document is removed even if another user
470 * modifies the document after your program opens it.
471 * If false, the document is not removed if another user
472 * modifies it.
473 * @return <code>true</code> if the document is successfully removed or if
474 * the document is not contained in a database (then a exception should be
475 * logged),
476 * <code>false</code> if the document is not deleted because another user
477 * modified it and the force parameter is set to false.
478 */
479 boolean remove(boolean force);
480
481 /***
482 * Creates a new rich text item in a document.
483 *
484 * @param name The name of the new rich-text item.
485 * @return The newly created item.
486 */
487 DRichTextItem createRichTextItem(String name);
488
489 /***
490 * Returns the value of an item.
491 *
492 * <p>If multiple items have the same name, this method returns the value of
493 * the first item. Use the Items property to get all the items.</p>
494 * <p>If the item has no value, this method returns an empty vector.</p>
495 * <p>If no item with the specified name exists, this method returns an
496 * empty vector. It does not throw an exception. Use hasItem to verify the
497 * existence of an item.</p>
498 * <p>This property returns the same value(s) for an item as getValues in
499 * Item.</p>
500 *
501 * @param name name of an item
502 * @return The value or values contained in the item. The data type of the
503 * value depends on the data type of the item.
504 */
505 List getItemValue(String name);
506
507 /***
508 * Returns the value of an item with a single text value.
509 *
510 * <p>If multiple items have the same name, this method returns the value of
511 * the first item. Use the Items property to get all the items.</p>
512 * <p> The value of the item cannot be null, but
513 * if the value is numeric or Calendar, this method returns an empty String.</p>
514 * <p>If no item with the specified name exists, this method returns null.
515 * It does not throw an exception. Use hasItem to verify the existence of an
516 * item.</p>
517 * <p>If the item has multiple values, this method returns the first
518 * value.</p>
519 *
520 * @param name The name of the item.
521 * @return The value of the item as a String.
522 */
523 String getItemValueString(String name);
524
525 /***
526 * Returns the value of an item with a single Calendar value.
527 * The date/time value of the item is stored in the calendar in the default
528 * time zone of the client.
529 *
530 * <p>If multiple items have the same name, this method returns the value of
531 * the first item. Use the Items property to get all the items.</p>
532 * <p>If value is numeric or text, this method returns <code>null</code>.</p>
533 * <p>If no item with the specified name exists, this method returns
534 * <code>null</code>.
535 * It does not throw an exception. Use hasItem to verify the existence of an
536 * item.</p>
537 * <p>If the item has multiple values, this method returns the first
538 * value.</p>
539 *
540 * @param name The name of the item.
541 * @return The value of the item as a Calendar or <tt>null</tt> if the item doesn't contain a date/time value
542 */
543 Calendar getItemValueDate(String name);
544
545 /***
546 * Returns the value of an item with two Calendar value.
547 *
548 * <p>If multiple items have the same name, this method returns the value of
549 * the first item. Use the Items property to get all the items.</p>
550 * <p>If value is numeric or text, this method returns <code>null</code>.</p>
551 * <p>If no item with the specified name exists, this method returns
552 * <code>null</code>.
553 * It does not throw an exception. Use hasItem to verify the existence of an
554 * item.</p>
555 *
556 * @param name The name of the item.
557 * @return The value of the item as DDateRange or <tt>null</tt> if the
558 * item doesn't contain any date/time information.The second value may be
559 * <code>null</code> if only one date/time was specified.
560 */
561 DDateRange getItemValueDateRange(String name);
562
563 /***
564 * Returns the value of an item with a single int value.
565 *
566 * <p>If multiple items have the same name, this method returns the value of
567 * the first item. Use the Items property to get all the items.</p>
568 * <p>If the value is text and is empty, this method
569 * returns <code>null</code>.</p>
570 * <p>If the value is text and cannot be converted to am integer, this
571 * method returns <code>null</code>.</p>
572 * <p>If no item with the specified name exists, this method
573 * returns <code>null</code>.
574 * It does not throw an exception. Use hasItem to verify the existence of
575 * an item.</p>
576 * <p>If the item has multiple values, this method returns the first
577 * value.</p>
578 * <p>A decimal number is rounded down if the fraction is less than 0.5 and
579 * up if the fraction is 0.5 or greater.</p>
580 *
581 * @param name The name of the item.
582 * @return The value of the item, rounded to the nearest integer
583 * or <code>null</code>
584 */
585 Integer getItemValueInteger(String name);
586
587 /***
588 * Returns the value of an item with a single double value.
589 *
590 * <p>If multiple items have the same name, this method returns the value of
591 * the first item. Use the Items property to get all the items.</p>
592 * <p>If the value is text and is empty, this method
593 * returns <code>null</code>.</p>
594 * <p>If the value is text and cannot be converted to a double, this
595 * method returns <code>null</code>.</p>
596 * <p>If no item with the specified name exists, this method returns <code>null</code>.
597 * It does not throw an exception. Use hasItem to verify the existence of
598 * an item.</p>
599 * <p>If the item has multiple values, this method returns the first
600 * value.</p>
601 *
602 * @param name The name of the item.
603 * @return The value of the item as a Double
604 * or <code>null</code>
605 */
606 Double getItemValueDouble(String name);
607
608 /***
609 * Indicates whether an item exists in the document.
610 *
611 * @param name The name of an item.
612 * @return <code>true</code> if an item with name exists in the document,
613 * else <code>false</code>
614 */
615 boolean hasItem(String name);
616
617 /***
618 * The names of the people who have saved a document.
619 *
620 * <p>If a name is hierarchical, this property returns the fully
621 * distinguished name.</p>
622 * <p>This property does not return the names of people who have permission
623 * to edit a document (as found in an item of type Authors).
624 * Therefore, the people returned by the Authors property and the people
625 * listed in an Authors item may differ.</p>
626 *
627 * @return List of Strings with authors names. In case of a normal document
628 * this method call returns a empty list for a not-saved-document.
629 * In case of a profile document, this method call returns a list
630 * with one entry, even if the profile document is requested for
631 * the first time.
632 */
633 List getAuthors();
634
635 /***
636 * The date a document was last modified or read.
637 *
638 * <p>The value returned is exact only to the day, not the hour.
639 * If the document is edited, the property is always updated.
640 * If the document is read more than once during the same 24hour period,
641 * the value is only updated the first time accessed.</p>
642 *
643 * @return last accessed date
644 */
645 Calendar getLastAccessed();
646
647 /***
648 * The date a document was last modified.
649 *
650 * @return last modified date. In case of a normal document
651 * this method call returns a empty list for a not-saved-document.
652 * In case of a profile document, this method call returns a list
653 * with one entry, even if the profile document is requested for
654 * the first time.
655 */
656 Calendar getLastModified();
657
658 /***
659 * Returns the number of values of an item.
660 *
661 * <p>If multiple items have the same name, this method returns the number of
662 * values in the first item. Use the Items property to get all the items.</p>
663 * <p>If the item has no value, this method returns <code>0</code>.</p>
664 * <p>If no item with the specified name exists, this method returns
665 * <code>0</code>. It does not throw an exception. Use hasItem to verify the
666 * existence of an item.</p>
667 * <p>This property returns the same value for an item as getSize() in
668 * DItem.</p>
669 *
670 * @param name name of an item
671 * @return The number of values contained in the item.
672 */
673 int getItemValueSize(String name);
674
675 /***
676 * Copies all items in the current document into the destination document.
677 * The item names are unchanged.
678 *
679 * <p>If you are not copying to a newly created document, you should
680 * probably specify true for the second parameter. See appendItemValue for
681 * a note about appending items to existing documents.</p>
682 *
683 * @param doc The destination document
684 * @param replace If <code>true</code>, the items in the destination
685 * document are replaced. If <code>false</code>, the items in the
686 * destination document are appended.
687 */
688 void copyAllItems(DBaseDocument doc, boolean replace);
689
690 /***
691 * Validates a document by executing the default value, translation, and
692 * validation formulas, if any are defined in the document form.
693 *
694 * <p><b>Usage</b><p>
695 * The form is as follows:
696 * <ol>
697 * <li>The form stored in the document, if any.</li>
698 * <li>The value of the Form item, if no form is stored in the document.</li>
699 * <li>The database default form, if the document does not have a Form
700 * item.</li>
701 * </ol>
702 * In the user interface, you must use a form to create a document. The
703 * document must meet the form requirements for input validation, and the
704 * user interface informs you if the document does not meet these
705 * requirements. Programatically you can create a document without a form.
706 * The computeWithForm method provides a means of checking that the data you
707 * placed in a document meets the requirements of a form, although (unlike
708 * in the user interface) you can still save a document if computeWithForm
709 * returns false or throws an exception.</p>
710 *
711 * @param raiseError If true, an error is raised if the validation fails. If
712 * false, no error is raised; instead, the method returns false
713 * if validation fails.
714 * @return <code>true</code> if there are no errors in the document, else
715 * <code>false</code>
716 * @throws DNotesRuntimeException if the parameter raiseError is
717 * <code>true</code> and if there are errors in the document
718 */
719 boolean computeWithForm(boolean raiseError) throws DNotesRuntimeException;
720
721 /***
722 * Validates a document by executing the default value, translation, and
723 * validation formulas, if any are defined in the document form.
724 *
725 * <p><b>Usage</b><p>
726 * The form is as follows:
727 * <ol>
728 * <li>The form stored in the document, if any.</li>
729 * <li>The value of the Form item, if no form is stored in the document.</li>
730 * <li>The database default form, if the document does not have a Form
731 * item.</li>
732 * </ol>
733 * In the user interface, you must use a form to create a document. The
734 * document must meet the form requirements for input validation, and the
735 * user interface informs you if the document does not meet these
736 * requirements. Programatically you can create a document without a form.
737 * The computeWithForm method provides a means of checking that the data you
738 * placed in a document meets the requirements of a form, although (unlike
739 * in the user interface) you can still save a document if computeWithForm
740 * returns false or throws an exception.</p>
741 *
742 * @return <code>true</code> if there are no errors in the document, else
743 * <code>false</code>
744 *
745 * @see #computeWithForm(boolean)
746 */
747 boolean computeWithForm();
748
749 /***
750 * The recycle method unconditionally destroys an object and returns its
751 * memory to the system.
752 *
753 * <p>Different to the Notes Java-API, usually it is not necessary to use
754 * this method. One remaining case might be a document that was changed in
755 * another session (e.g. by a server agent) while still keeping a reference
756 * to the document.</p>
757 */
758 void recycle();
759
760 /***
761 * Copies an item into the current document and optionally assigns the
762 * copied item a new name.
763 *
764 * @param item The item, usually from another document, that you want to
765 * copy. Cannot be null.
766 * @param name The name to assign to the copied item. Specify null to retain
767 * the existing name of the item.
768 * @return A copy of the specified item parameter, identical except for its
769 * newname.
770 */
771 DBaseItem copyItem(DBaseItem item, String name);
772
773 /***
774 * Copies an item into the current document and optionally assigns the
775 * copied item a new name.
776 *
777 * @param item The item, usually from another document, that you want to
778 * copy. Cannot be null.
779 * @return A copy of the specified item parameter
780 */
781 DBaseItem copyItem(DBaseItem item);
782
783 /***
784 * Creates a new document that is formatted as a reply to the current
785 * document.
786 *
787 * <p>The new document does not contain a Subject item. If you want one,
788 * the program must explicitly add it to the document.</p>
789 *
790 * <p>The new document does not automatically get mailed. If you want to
791 * mail it, the program must explicitly call the send method.</p>
792 *
793 * @param toAll If <code>true</code>, the new document recipient list
794 * contains all the recipients of the original. If
795 * <code>false</code>, the new document recipient list
796 * contains only the sender of the original.
797 * @return A reply to the current document.
798 */
799 DDocument createReplyMessage(boolean toAll);
800
801 /***
802 * Encrypts a document.
803 *
804 * <p>The encrypted document is not saved until you call save. Only the
805 * items for which isEncrypted is true are encrypted. Items for which
806 * isEncrypted is false remain visible to any user, even if the user does
807 * not have the proper encryption key.</p>
808 *
809 * <p>If the EncryptionKeys property is set with one or more named keys,
810 * those keys are used to encrypt the document. Any user who has one of the
811 * encryption keys can decrypt the document. If there are no encryption keys
812 * specified, the document is encrypted with the user's public key, in which
813 * case only the user who encrypted the document can decrypt it.</p>
814 *
815 * <p>If the program is running on a server, it must have permission to use
816 * Encrypt.</p>
817 *
818 * <p>Since mail encryption works differently, do not use this method if
819 * you want to mail an encrypted document. Instead, set the EncryptOnSend
820 * property to true, and use the send method.</p>
821 *
822 * <p>You cannot use the encrypt method on a Document object returned by
823 * getDocumentContext.</p>
824 */
825 void encrypt();
826
827 /***
828 * A list of values, each element of which corresponds to a column value in
829 * the document's parent view. The first value in the vector is the value
830 * that appears in the view's first column for the document, the second
831 * value is the one that appears in the second column, and so on. The value
832 * of each element of the vector is the result of the corresponding column's
833 * formula and the items on the current document. Some elements in the
834 * vector might have no value.
835 *
836 * @return column values
837 */
838 List getColumnValues();
839
840 /***
841 * Returns the key(s) used to encrypt a document. The encrypt method uses
842 * these keys when it encrypts the document.
843 *
844 * <p>Each element in EncryptionKeys contains the name of an encryption key
845 * that you want to use to encrypt the document. The document can be
846 * decrypted by any user who posesses one of the keys. If there are no
847 * encryption keys specified for a document, the document is encrypted with
848 * the current user's public key and can only be decrypted by that user.</p>
849 *
850 * <p>You must call the encrypt and save methods to actually encrypt the
851 * document. Since encryption works differently when a document is mailed,
852 * the EncryptionKeys property has no effect when a document is encrypted
853 * when mailed.</p>
854 *
855 * <p>The name of each encryption key in a document is stored in a text
856 * item called SecretEncryptionKeys. This property returns the contents of
857 * the item.</p>
858 *
859 * @return the key(s) used to encrypt a document
860 */
861 List getEncryptionKeys();
862
863 /***
864 * Sets the key(s) used to encrypt a document. The encrypt method uses these
865 * keys when it encrypts the document.
866 *
867 * @param keys the key(s) used to encrypt a document
868 * @see #getEncryptionKeys()
869 */
870 void setEncryptionKeys(List keys);
871
872 /***
873 * Returns as an object the value of an item containing custom data.
874 *
875 * @param name The name of the item.
876 * @return An object that receives the value of the item. Must have the same
877 * class definition as the object written to the item.
878 * @since Notes/Domino Release 6
879 */
880 Object getItemValueCustomData(String name);
881
882 /***
883 * Returns as an object the value of an item containing custom data.
884 *
885 * @param name The name of the item.
886 * @param dataTypeName The name of the data type. If specified, this name
887 * must match the data type name specified when the item was
888 * written. If omitted, no name checking occurs
889 * @return An object that receives the value of the item. Must have the same
890 * class definition as the object written to the item.
891 * @since Notes/Domino Release 6
892 */
893 Object getItemValueCustomData(String name, String dataTypeName);
894
895 /***
896 * Returns as a byte array the value of an item containing custom data.
897 *
898 * @param name The name of the item.
899 * @param dataTypeName The name of the data type. If specified, this name
900 * must match the data type name specified when the item was
901 * written. If omitted, no name checking occurs
902 * @return Array of type Byte. The value of the item.
903 * @since Notes/Domino Release 6
904 */
905 byte[] getItemValueCustomDataBytes(String name, String dataTypeName);
906
907 /***
908 * Returns the value of a date-time item in a document.
909 *
910 * @param name The name of the item.
911 * @return The value or values contained in the item. Each element in the
912 * vector corresponds to a value in the item and is of type DateTime
913 * or DateRange. If the item contains a single value, the vector has
914 * one element.
915 * @since Notes/Domino Release 6.5
916 */
917 List getItemValueDateTimeArray(String name);
918
919 /***
920 * The name of the person who created the signature, if a document is
921 * signed.
922 *
923 * <p>If a document is not signed, returns an empty string.</p>
924 *
925 * <p>If the signer is not trusted, returns an empty string.</p>
926 *
927 * @return the signer
928 */
929 String getSigner();
930
931 /***
932 * The size of a database, in bytes.
933 *
934 * @return size of a database, in bytes
935 */
936 int getSize();
937
938 /***
939 * The universal ID, which uniquely identifies a document across all
940 * replicas of a database. In character format, the universal ID is a
941 * 32-character combination of hexadecimal digits (0-9, A-F).
942 *
943 * <p>If two documents in replica databases share the same universal ID,
944 * the documents are replicas.</p>
945 *
946 * <p>If you modify the UNID of an existing document, it becomes a new
947 * document.</p>
948 *
949 * <p>Saving a document with the same UNID as an existing document an
950 * exception.</p>
951 *
952 * @param unid The universal ID is also known as the unique ID or UNID.
953 */
954 void setUniversalID(String unid);
955
956 /***
957 * The name of the certificate that verified a signature, if a document is
958 * signed.
959 *
960 * <p>This property is an empty string if the document is not signed.</p>
961 *
962 * <p>This property is an empty string if the signer is not trusted.</p>
963 *
964 * @return name of the certificate that verified a signature
965 */
966 String getVerifier();
967
968 /***
969 * Indicates whether a document contains one or more embedded objects,
970 * object links, or file attachments.
971 *
972 * <p>Note Embedded objects and object links are not supported for OS/2,
973 * UNIX, and the Macintosh. File attachments are.</p>
974 *
975 * @return <code>true</code> if the document contains one or more embedded
976 * objects, object links, or file attachments , else
977 * <code>false</code>
978 */
979 boolean hasEmbedded();
980
981 /***
982 * Indicates whether a document is encrypted.
983 *
984 * @return <code>true</code> if the document is encrypted, else
985 * <code>false</code>
986 */
987 boolean isEncrypted();
988
989 /***
990 * Indicates whether a document is encrypted when mailed.
991 *
992 * @return <code>true</code> if the document is encrypted when mailed,
993 * else <code>false</code>
994 */
995 boolean isEncryptOnSend();
996
997 /***
998 * Indicates whether a Document object is a profile document.
999 *
1000 * @return <code>true</code> if the document is a profile document, else
1001 * <code>false</code>
1002 */
1003 boolean isProfile();
1004
1005 /***
1006 * Indicates whether a document contains a signature.
1007 *
1008 * @return <code>true</code> if the document contains one or more
1009 * signatures, else <code>false</code>
1010 */
1011 boolean isSigned();
1012
1013 /***
1014 * Indicates whether a Document object represents an existing document (not
1015 * a deletion stub) initially.
1016 *
1017 * @return <code>true</code> if the document represents an existing
1018 * document, else <code>false</code>
1019 */
1020 boolean isValid();
1021
1022 /***
1023 * Indicates whether a document is saved to a database when mailed. Applies
1024 * only to new documents that have not yet been saved.
1025 *
1026 * @return <code>true</code> if the document is saved when mailed, else
1027 * <code>false</code>
1028 */
1029 boolean isSaveMessageOnSend();
1030
1031 /***
1032 * Indicates whether a document was mailed by a Domino program.
1033 *
1034 * @return <code>true</code> if the document was mailed by a program, else
1035 * <code>false</code>
1036 */
1037 boolean isSentByAgent();
1038
1039 /***
1040 * Indicates whether a document is signed when mailed.
1041 *
1042 * @return <code>true</code> if the document is signed when mailed, else
1043 * <code>false</code>
1044 */
1045 boolean isSignOnSend();
1046
1047 /***
1048 * Indicates whether a Document object represents an existing document (not
1049 * a deletion stub) on an ongoing basis.
1050 *
1051 * @return <code>true</code> if the document is a deletion stub
1052 * <code>false</code> if the document exists
1053 */
1054 boolean isDeleted();
1055
1056 /***
1057 * Permanently deletes a document from a database, doing a hard deletion
1058 * even if soft deletions are enabled.
1059 *
1060 * <p>This method does a hard deletion even if "Allow soft deletions" is
1061 * enabled. See remove to do a soft deletion.</p>
1062 *
1063 * <p>If you access a NotesDocument object through the Document property of
1064 * NotesUIDocument, you can't delete the back-end document. If you could,
1065 * the UI rendition would have no basis. You must access the document
1066 * strictly through the back-end.</p>
1067 *
1068 * <p>A deleted document cannot be used as a basis for navigation in a view
1069 * or a document collection.</p>
1070 *
1071 * <p>You cannot use the remove method on a Document object returned by
1072 * {@link DAgentContext#getDocumentContext()}.</p>
1073 *
1074 * @param force If <code>true</code>, the document is deleted even if
1075 * another user modifies the document after the program opens it.
1076 * If <code>false</code>, the document is not deleted if
1077 * another user modifies it.
1078 * @return <code>true</code> if the document is successfully deleted,
1079 * <code>false</code> if the document is not deleted, because
1080 * another user modified it and the force parameter is set to false
1081 */
1082 boolean removePermanently(boolean force);
1083
1084 /***
1085 * Creates a picture of a document and places it into a rich-text item that
1086 * you specify.
1087 *
1088 * <p>The picture is created using both the document and its form.
1089 * Therefore, the input translation and validation formulas of the form are
1090 * executed.</p>
1091 *
1092 * <p>If the target rich text item is in a new document, you must save the
1093 * document before calling renderToRTItem.</p>
1094 *
1095 * @param richtextitem The destination for the picture. Cannot be null.
1096 * @return If <code>true</code>, the method is successful. If
1097 * <code>false</code>, the method is not successful and the rich
1098 * text item remains unchanged. This can happen if an input
1099 * validation formula fails on the document form.
1100 */
1101 boolean renderToRTItem(DRichTextItem richtextitem);
1102
1103 /***
1104 * Replaces all items of the specified name with one new item, which is
1105 * assigned custom data from a byte array. If the document does not contain
1106 * an item with the specified name, this method creates a new item and adds
1107 * it to the document.
1108 *
1109 * @param name the name of the item
1110 * @param type name for the data type. When getting custom data, use this
1111 * name for verification.
1112 * @param obj object that contains the custom data. The class that defines
1113 * this object must implement Serializable. If desired, you can
1114 * override readObject and writeObject.
1115 * @return DItem
1116 */
1117 DItem replaceItemValueCustomData(String name, String type, Object obj);
1118
1119 /***
1120 * Replaces all items of the specified name with one new item, which is
1121 * assigned custom data from a byte array. If the document does not contain
1122 * an item with the specified name, this method creates a new item and adds
1123 * it to the document.
1124 *
1125 * @param name the name of the item
1126 * @param obj object that contains the custom data. The class that defines
1127 * this object must implement Serializable. If desired, you can
1128 * override readObject and writeObject.
1129 * @return DItem
1130 */
1131 DItem replaceItemValueCustomData(String name, Object obj);
1132
1133 /***
1134 * Replaces all items of the specified name with one new item, which is
1135 * assigned custom data from a byte array. If the document does not contain
1136 * an item with the specified name, this method creates a new item and adds
1137 * it to the document.
1138 *
1139 * @param name the name of the item
1140 * @param type name for the data type. When getting custom data, use this
1141 * name for verification.
1142 * @param bytes byte array that contains the custom data
1143 * @return DItem
1144 */
1145 DItem replaceItemValueCustomDataBytes(String name, String type, byte[] bytes);
1146
1147 /***
1148 * Generates an XML representation of a document to the Writer. The XML
1149 * conforms to the Domino Document DTD.
1150 *
1151 * <p>This method takes the same arguments as the transformXML method in
1152 * EmbeddedObject, Item, MIMEEntity, and RichTextItem. The transformXML
1153 * method reads the XML from an item, attachment, MIMEEntity, or rich text
1154 * item and transforms the XML. The generateXML method generates the XML
1155 * from the document and then transforms it.</p>
1156 *
1157 * <p>The generateXML method supports the following simple items: Text,
1158 * Text list, Number, Number list, Datetime, Datetime list</p>
1159 *
1160 * <p>To generate form semantics, you must call computeWithForm method
1161 * before calling the generateXML method.</p>
1162 *
1163 * @return The XML representation of the document.
1164 */
1165 String generateXML();
1166
1167 /***
1168 * Generates an XML representation of a document to the Writer. The XML
1169 * conforms to the Domino Document DTD.
1170 *
1171 * <p>This method takes the same arguments as the transformXML method in
1172 * EmbeddedObject, Item, MIMEEntity, and RichTextItem. The transformXML
1173 * method reads the XML from an item, attachment, MIMEEntity, or rich text
1174 * item and transforms the XML. The generateXML method generates the XML
1175 * from the document and then transforms it.</p>
1176 *
1177 * <p>The generateXML method supports the following simple items: Text,
1178 * Text list, Number, Number list, Datetime, Datetime list</p>
1179 *
1180 * <p>To generate form semantics, you must call computeWithForm method
1181 * before calling the generateXML method.</p>
1182 *
1183 * @param writer The Writer that will receive the result XML.
1184 */
1185 void generateXML(Writer writer);
1186
1187 /***
1188 * Gets the text values of the Received items in a mail document.
1189 *
1190 * <p>This method applies to Received items generated from an Internet mail
1191 * message. The items can be in MIME or Notes format.</p>
1192 *
1193 * <p>If the document has no Received items, this method returns a vector
1194 * of one element whose value is an empty string.</p>
1195 *
1196 * <p>A Received item with an incorrect format (not an Internet mail
1197 * message) throws an exception.</p>
1198 *
1199 * @return List of strings. The text values of the Received items, one item
1200 * per element.
1201 * @since Notes/Domino Release 6.5
1202 */
1203 List getReceivedItemText();
1204
1205 /***
1206 * The names of the holders of a lock.
1207 *
1208 * <p>If the document is locked, the vector contains the names of the lock
1209 * holders. The document can be locked by one or more users or groups.</p>
1210 *
1211 * <p>If the document is not locked, the vector contains one element whose
1212 * value is an empty string ("").</p>
1213 *
1214 * @return names of the holders of a lock.
1215 * @since Notes/Domino Release 6.5
1216 */
1217 List getLockHolders();
1218
1219 /***
1220 * Locks a document.
1221 *
1222 * @return <code>true</code> if the lock is placed, <code>false</code>
1223 * if the lock is not placed
1224 * @see #lock(List, boolean)
1225 * @since Notes/Domino Release 6.5
1226 */
1227 boolean lock();
1228
1229 /***
1230 * Locks a document.
1231 *
1232 * @param provisionalOk <code>true</code> to permit the placement of a
1233 * provisional lock, <code>false</code> (default) to not permit
1234 * a provisional lock
1235 * @return <code>true</code> if the lock is placed, <code>false</code>
1236 * if the lock is not placed
1237 * @see #lock(List, boolean)
1238 * @since Notes/Domino Release 6.5
1239 */
1240 boolean lock(boolean provisionalOk);
1241
1242 /***
1243 * Locks a document.
1244 *
1245 * @param name the name of the lock holder
1246 * @return <code>true</code> if the lock is placed, <code>false</code>
1247 * if the lock is not placed
1248 * @see #lock(List, boolean)
1249 * @since Notes/Domino Release 6.5
1250 */
1251 boolean lock(String name);
1252
1253 /***
1254 * Locks a document.
1255 *
1256 * @param name the name of the lock holder
1257 * @param provisionalOk <code>true</code> to permit the placement of a
1258 * provisional lock, <code>false</code> (default) to not permit
1259 * a provisional lock
1260 * @return <code>true</code> if the lock is placed, <code>false</code>
1261 * if the lock is not placed
1262 * @see #lock(List, boolean)
1263 * @since Notes/Domino Release 6.5
1264 */
1265 boolean lock(String name, boolean provisionalOk);
1266
1267 /***
1268 * Locks a document.
1269 *
1270 * @param names the names of the lock holders
1271 * @return <code>true</code> if the lock is placed, <code>false</code>
1272 * if the lock is not placed
1273 * @see #lock(List, boolean)
1274 * @since Notes/Domino Release 6.5
1275 */
1276 boolean lock(List names);
1277
1278 /***
1279 * Locks a document.
1280 *
1281 * <p> IsDocumentLockingEnabled in Database must be true or this method
1282 * throws an exception.</p>
1283 *
1284 * <p>This method:</p>
1285 *
1286 * <ul><li>places a persistent lock if the administration (master lock)
1287 * server is available.</li> <li>places a provisional lock if the
1288 * administration server is not available and the second parameter is true.</li>
1289 * <li>throws an exception if the administration server is not available
1290 * and the second parameter is false.</li> </ul>
1291 *
1292 * <p>The following actions occur depending on the current lock status:</p>
1293 *
1294 * <ul> <li>If the document is not locked, this method places the lock and
1295 * returns true.</li> <li>If the document is locked and the current user
1296 * is one of the lock holders, this method returns true.</li> <li>If the
1297 * document is locked and the current user is not one of the lock holders,
1298 * this method returns false.</li> </ul> <p>If the document is modified by
1299 * another user before the lock can be placed, this method throws an
1300 * exception.</p>
1301 *
1302 * @param names The names of the lock holders. Each lock holder must be a
1303 * user or group. Defaults to one lock holder: the effective
1304 * user. The empty string ("") is not permitted.
1305 * @param provisionalOk <code>true</code> to permit the placement of a
1306 * provisional lock, <code>false</code> (default) to not permit
1307 * a provisional lock
1308 * @return <code>true</code> if the lock is placed, <code>false</code>
1309 * if the lock is not placed
1310 * @since Notes/Domino Release 6.5
1311 */
1312 boolean lock(List names, boolean provisionalOk);
1313
1314 /***
1315 * Locks a document provisionally.
1316 *
1317 * @return <code>true</code> if the lock is placed, <code>false</code>
1318 * if the lock is not placed
1319 * @see #lock(List, boolean)
1320 * @since Notes/Domino Release 6.5
1321 */
1322 boolean lockProvisional();
1323
1324 /***
1325 * Locks a document provisionally.
1326 *
1327 * @param name The name of the lock holders. The lock holder must be a user
1328 * or group. Defaults to the effective user. The empty string
1329 * ("") is not permitted.
1330 * @return <code>true</code> if the lock is placed, <code>false</code>
1331 * if the lock is not placed
1332 * @see #lock(List, boolean)
1333 * @since Notes/Domino Release 6.5
1334 */
1335 boolean lockProvisional(String name);
1336
1337 /***
1338 * Locks a document provisionally.
1339 *
1340 * @param names The names of the lock holders. Each lock holder must be a
1341 * user or group. Defaults to one lock holder: the effective
1342 * user. The empty string ("") is not permitted.
1343 * @return <code>true</code> if the lock is placed, <code>false</code>
1344 * if the lock is not placed
1345 * @see #lock(List, boolean)
1346 * @since Notes/Domino Release 6.5
1347 */
1348 boolean lockProvisional(List names);
1349
1350 /***
1351 * Unlocks a document.
1352 *
1353 * <p>{@link DDatabase#isDocumentLockingEnabled()} in Database must be true or this
1354 * method throws an exception. This method throws an exception if the
1355 * current user is not one of the lock holders and does not have lock
1356 * breaking authority.</p>
1357 * @see #lock(List, boolean)
1358 * @since Notes/Domino Release 6.5
1359 */
1360 void unlock();
1361 }