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.Iterator;
26 import java.util.List;
27
28 /***
29 * Represents a document in a database.
30 *
31 * <p>To create a new Document object, use
32 * {@link de.bea.domingo.DDatabase#createDocument()} in DDatabase.</p>
33 *
34 * <p>To access existing documents:
35 * <ul>
36 * <li>To get all the documents in a database, use
37 * {@link de.bea.domingo.DDatabase#getAllDocuments()} in DDatabase.</li>
38 * <li>To get all documents that are responses to
39 * a particular document, use {@link de.bea.domingo.DDocument#getResponses()} in
40 * DDocument. To get a response document's parent document, use
41 * {@link de.bea.domingo.DDocument#getParentDocument()} in DDocument.</li>
42 * <li>To get a document based on its note ID or UNID, use
43 * {@link de.bea.domingo.DDatabase#getDocumentByID(java.lang.String)} or
44 * {@link de.bea.domingo.DDatabase#getDocumentByUNID(java.lang.String)}
45 * in DDatabase.</li></ul></p>
46 *
47 * <p>Once you have a view, you can navigate to a specific document using
48 * methods in the View class.</p>
49 *
50 * <p>Once you have a collection of documents, you can navigate to a specific
51 * document using methods in the DocumentCollection class.</p>
52 *
53 * <p>After you create, modify, or delete a document, you must save the changes
54 * by calling the {@link de.bea.domingo.DDocument#save()} method.
55 * If you don't call save before the program finishes, all of your changes to
56 * a Document are lost.</p>
57 *
58 * <p>If you create and save a new document without adding any items to it, the
59 * document is saved with one item "$UpdatedBy." This item contains the name of
60 * the creator of the document.</p>
61 *
62 * @author <a href=mailto:kriede@users.sourceforge.net>Kurt Riede</a>
63 */
64 public interface DDocument extends DBaseDocument {
65
66 /***
67 * Indicates whether a document is new.
68 * A document is new if it has not been saved.
69 *
70 * @return Boolean <code>true</code> if the document was created, but has
71 * not been saved
72 */
73 boolean isNewNote();
74
75 /***
76 * The universal ID, which uniquely identifies a document across all
77 * replicas of a database.
78 *
79 * <p>In character format, the universal ID is a 32-character combination of
80 * hexadecimal digits (0-9, A-F). The universal ID is also known as the
81 * unique ID or UNID.</p>
82 *
83 * @return String
84 */
85 String getUniversalID();
86
87 /***
88 * The note ID of a document, which is a hexadecimal value of up to
89 * 8 characters that uniquely identifies a document within a particular
90 * database.
91 *
92 * <p>A typical note ID looks like this: 20FA. A note ID represents the
93 * location of a document within a specific database file, so documents that
94 * are replicas of one another generally have different note IDs. A note ID
95 * does not change, unless the document is deleted.</p>
96 *
97 * @return the notes ID
98 */
99 String getNoteID();
100
101 /***
102 * Mails a document.
103 *
104 * <p>The following rules apply to specification of the recipient or
105 * recipients:
106 * <ul>
107 * <li>Ignored if the document contains a SendTo item, in which case the
108 * document is mailed to recipients listed in SendTo.</li>
109 * <li>Required if the document does not contain a SendTo item.</li>
110 * <li>May include people, groups, or mail-in databases.</li></ul></p>
111 * <p>If you have only Reader access to a database, you can run an agent
112 * that creates and sends a document, but the agent will not work if you
113 * attach a file to that document.</p>
114 * <p>Two kinds of items can affect the mailing of the document when you
115 * use send:
116 * <ul>
117 * <li>If the document contains additional recipient items, such as CopyTo
118 * or BlindCopyTo, the documents mailed to those recipients.</li>
119 * <li>If the document contains items to control the routing of mail, such
120 * as DeliveryPriority, DeliveryReport, or ReturnReceipt, they are used
121 * when sending the document.</li></ul></p>
122 * <p>The IsSaveMessageOnSend property controls whether the sent document
123 * is saved in the database. If IsSaveMessageOnSend is true and you attach
124 * the form to the document, the form is saved with the document.</p>
125 * <p>The send method automatically creates an item called $AssistMail on
126 * the sent document. The SentByAgent property uses this item to determine
127 * if a document was mailed by an agent.</p>
128 * <p>If a program runs on a workstation, the mailed document contains the
129 * current user's name in the From item. If a program runs as an agent
130 * on a server, the mailed document contains the server's name in the
131 * From item.</p>
132 *
133 * @param recipient name of recipient
134 */
135 void send(String recipient);
136
137 /***
138 * Mails a document.
139 *
140 * @param recipients list of Strings with recipients
141 * @see #send(java.lang.String)
142 */
143 void send(List recipients);
144
145 /***
146 * Copies a document to a specified database.
147 *
148 * @param database The database to which you want to copy the document.
149 * Cannot be null.
150 * @return The new document in the specified database or <code>null</code> if the document cannot be created
151 */
152 DDocument copyToDatabase(DDatabase database);
153
154 /***
155 * Indicates whether a document is a response to another document.
156 *
157 * @return <code>true</code> if the document is a response to another
158 * document, else <code>false</code>
159 */
160 boolean isResponse();
161
162 /***
163 * The universal ID of a document's parent, if the document is a response.
164 * Returns an empty string if a document doesn't have a parent.
165 *
166 * @return the universal ID
167 */
168 String getParentDocumentUNID();
169
170 /***
171 * The parent document if the document is a response document.
172 *
173 * @return the parent document or <code>null</code> if the document is not
174 * a response document.
175 */
176 DDocument getParentDocument();
177
178 /***
179 * Makes one document a response to another. The two documents must be in the same database.
180 *
181 * @param doc The document to which the current document becomes a response.
182 */
183 void makeResponse(DDocument doc);
184
185 /***
186 * The immediate responses to a document.
187 *
188 * <p>Each document returned is an immediate response to the first document.
189 * Responses-to-responses are not included.
190 * If the current document has no responses, the vector contains zero
191 * documents.</p>
192 *
193 * <p><b>Responses-to-Responses</b><br/>
194 * This property returns only immediate responses to a document, but you
195 * can write a recursive sub or function to access all the descendants of
196 * a particular document. A recursive sub calls itself in the same way that
197 * a non-recursive sub calls any other sub or function.</p>
198 *
199 * @return The immediate responses to a document.
200 */
201 Iterator getResponses();
202
203 /***
204 * Indicates if a document is saved to a database when mailed.
205 * Applies only to new documents that have not yet been saved.
206 * <p>When SaveMessageOnSend is true, the document is saved just after
207 * being mailed.</p>
208 *
209 * @param saveMessageOnSend <code>true</code> if the document is saved when
210 * mailed, else <code>false</code>.
211 */
212 void setSaveMessageOnSend(boolean saveMessageOnSend);
213
214 /***
215 * Indicates if a document is encrypted when mailed.
216 * <p>To encrypt a document when mailed, this method looks for the public
217 * key of each recipient in the Domino Directory. If it cannot find a
218 * recipient's public key, the method sends an unencrypted copy of the
219 * document to that recipient. All other recipients receive an encrypted
220 * copy of the document.</p>
221 * <p>This property has no effect on whether a document is encrypted when
222 * saved to a database.</p>
223 *
224 * @param flag <code>true</code> if the document is encrypted when mailed,
225 * else <code>false</code>.
226 */
227 void setEncryptOnSend(boolean flag);
228
229 /***
230 * Indicates if a document is signed when mailed.
231 *
232 * @param flag <code>true</code> if the document is signed when mailed;
233 * else <code>false</code>.
234 */
235 void setSignOnSend(boolean flag);
236
237 /***
238 * Signs a document.
239 * <p>If you want the signature to be saved, you must call the Save method
240 * after signing the document.</p>
241 * <p>If the program is running on a server, this method has no effect.</p>
242 */
243 void sign();
244
245 /***
246 * Replaces a MIMEEntity item with a new item with the given HTML code.
247 * <p>If the document does not contain an item with the specified name, this
248 * method creates a new MIMEEntity item and adds it to the document.</p>
249 *
250 * @param name name of an item
251 * @param value HTML code for the new item
252 */
253 void replaceHTML(String name, String value);
254
255 /***
256 * The full-text search score of a document, if it was retrieved as part of
257 * a full-text search.
258 *
259 * <p><b>Usage</b></p>
260 * <p>The score is determined by the number of target words that are found in
261 * the document, the term weights assigned to the target words, and any
262 * proximity operators in the search query. If the document is not retrieved
263 * as part of a full-text search, returns 0. If the document is retrieved
264 * using an FTSearch method on a database without a full-text index, returns
265 * an unpredictable number.</p>
266 * <p>If a document is in more than one DocumentCollection or
267 * ViewEntryCollection, its score is that of the last collection from which
268 * it was retrieved. The score is correct unless you get the score from the
269 * current object after retrieving the same document from another
270 * collection.</p>
271 * <p>Documents added to a collection have a search score of 0.</p>
272 * <p>Documents deleted from a view have a search score of 0.</p>
273 *
274 * @return The full-text search score of a document, if it was retrieved as
275 * part of a full-text search
276 */
277 int getFTSearchScore();
278
279 /***
280 * The view from which a document was retrieved, if any.
281 *
282 * <p>If the document was retrieved directly from the database or a
283 * document collection, getParentView returns null.</p>
284 *
285 * @return view from which a document was retrieved
286 */
287 DView getParentView();
288
289 /***
290 * The names of the folders containing a document.
291 *
292 * <p>The database must have the hidden views <code>$FolderInfo</code>
293 * and <code>$FolderRefInfo</code> to support folder references. These
294 * views can be copied from the mail template. This property does not return
295 * view references.</p>
296 *
297 * <p>Folder references must be enabled for the database. See the
298 * FolderReferencesEnabled property of Database.</p>
299 *
300 * @return names of the folders containing a document
301 *
302 * @see DDatabase#getFolderReferencesEnabled()
303 */
304 List getFolderReferences();
305
306 /***
307 * Adds a document to a folder. If the folder does not exist, it is created.
308 *
309 * <p>If the document is already inside the folder you specify, putInFolder
310 * does nothing. If you specify a path to a folder, and none of the folders
311 * exists, the method creates all of them for you. For example:</p>
312 *
313 * <pre>doc.putInFolder( "Vehicles//Bikes" );</pre>
314 *
315 * <p>If neither Vehicles nor Bikes exists, putInFolder creates both,
316 * placing the Bikes folder inside the Vehicles folder.</p>
317 *
318 * <p>This method cannot add the first document to a folder that is
319 * "Shared, Personal on first use."</p>
320 *
321 * @param name The name of the folder in which to place the document. The
322 * folder may be personal if the program is running on a
323 * workstation. If the folder is within another folder, specify a
324 * path to it, separating folder names with backslashes. For
325 * example: "Vehicles//Bikes"
326 *
327 * @see #putInFolder(String, boolean)
328 */
329 void putInFolder(String name);
330
331 /***
332 * Adds a document to a folder. If the folder does not exist, it is created.
333 *
334 * <p>If the document is already inside the folder you specify, putInFolder
335 * does nothing. If you specify a path to a folder, and none of the folders
336 * exists, the method creates all of them for you. For example:</p>
337 *
338 * <pre>doc.putInFolder( "Vehicles//Bikes" );</pre>
339 *
340 * <p>If neither Vehicles nor Bikes exists, putInFolder creates both,
341 * placing the Bikes folder inside the Vehicles folder.</p>
342 *
343 * <p>This method cannot add the first document to a folder that is
344 * "Shared, Personal on first use."</p>
345 *
346 * @param name The name of the folder in which to place the document. The
347 * folder may be personal if the program is running on a
348 * workstation. If the folder is within another folder, specify a
349 * path to it, separating folder names with backslashes. For
350 * example: "Vehicles//Bikes"
351 * @param create If <code>true</code> (default), creates the folder if it
352 * does not exist.
353 */
354 void putInFolder(String name, boolean create);
355
356 /***
357 * Removes a document from a folder.
358 *
359 * <p>The method does nothing if the document is not in the folder you
360 * specify, or if the folder you specify does not exist.</p>
361 *
362 * @param name The name of the folder from which to remove the document. The
363 * folder may be personal if the program is running on a
364 * workstation. If the folder is within another folder, specify a
365 * path to it, separating folder names with backslashes. For
366 * example: "Vehicles//Bikes"
367 */
368 void removeFromFolder(String name);
369
370 /***
371 * Returns the Domino URL for its parent object.
372 *
373 * <p>See {@link DSession#resolve(String)} for additional information and examples.</p>
374 *
375 * @return Domino URL
376 *
377 * @see #getHttpURL()
378 * @see #getNotesURL()
379 * @see #getURL()
380 * @see de.bea.domingo.DSession#resolve(String)
381 */
382 String getURL();
383
384 /***
385 * The Domino URL of a form when Notes protocols are in effect.
386 *
387 * <p>If Notes protocols are not available, this property returns an empty
388 * string.</p>
389 *
390 * <p>See {@link DSession#resolve(String)} for additional information and examples.</p>
391 *
392 * @return Domino Notes URL
393 *
394 * @see #getHttpURL()
395 * @see #getURL()
396 * @see de.bea.domingo.DSession#resolve(String)
397 */
398 String getNotesURL();
399
400 /***
401 * The Domino URL of a form when HTTP protocols are in effect.
402 *
403 * <p>If HTTP protocols are not available, this property returns an empty
404 * string.</p>
405 *
406 * <p>See {@link DSession#resolve(String)} for additional information and examples.</p>
407 *
408 * @return The Domino HTTP URL
409 *
410 * @see #getNotesURL()
411 * @see #getURL()
412 * @see de.bea.domingo.DSession#resolve(String)
413 */
414 String getHttpURL();
415 }