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.Iterator;
27
28 /***
29 * Represents the agent environment of the current program, if an agent is running it.
30 *
31 * @author <a href="mailto:kriede@users.sourceforge.net">Kurt Riede</a>
32 */
33 public interface DAgentContext {
34
35 /***
36 * Marks a given document as processed.
37 *
38 * @param document a document
39 */
40 void updateProcessedDoc(DDocument document);
41
42 /***
43 * Performs a full-text search within the unprocessed documents.
44 *
45 * @param query The full-text query
46 * @param maxDocs The maximum number of documents you want returned; 0 means all matching documents
47 * @return An interator of documents that are not yet processed and match the query
48 */
49 Iterator unprocessedFTSearch(String query, int maxDocs);
50
51 /***
52 * Performs a full-text search within the unprocessed documents.
53 * <dl>
54 * <dt>sortOpt</dt>
55 * <dd>Use one of the following to specify a sorting option:
56 * <ul>
57 * <li>Database.FT_SCORES (default) sorts by relevance score with highest relevance first.</li>
58 * <li>Database.FT_DATECREATED_DES sorts by document creation date in descending order.</li>
59 * <li>Database.FT_DATECREATED_ASC sorts by document creation date in ascending order.</li>
60 * <li>Database.FT_DATE_DES sorts by document date in descending order.</li>
61 * <li>Database.FT_DATE_ASC sorts by document date in ascending order.</li>
62 * </ul>
63 * </dd>
64 * </dl>
65 * <dl>
66 * <dt>otherOpt</dt>
67 * <dd>Use the following constants to specify additional search options.
68 * To specify more than one option, use a logical OR operation:
69 * <ul>
70 * <li>Database.FT_DATABASE includes Lotus Domino databases in the search scope.</li>
71 * <li>Database.FT_FILESYSTEM includes files other than Lotus Domino databases in the search scope.</li>
72 * <li>Database.FT_FUZZY specifies a fuzzy search.</li>
73 * <li>Database.FT_STEMS uses stem words as the basis of the search.</li>
74 * </ul>
75 * </dl>
76 *
77 * @param query The full-text query
78 * @param maxDocs The maximum number of documents you want returned; 0 means all matching documents
79 * @param sortOpt sorting options
80 * @param otherOpt other options
81 * @return An iterator of documents that are not yet processed and match the query
82 */
83 Iterator unprocessedFTSearch(String query, int maxDocs, int sortOpt, int otherOpt);
84
85 /***
86 * Searches for unprocessed documents which were created or modified since the cutoff date.
87 * The resulting collection is sorted by relevance with highest relevance first.
88 *
89 * @param query A Lotus Domino formula that defines the selection criteria
90 * @param dateTime A cutoff date
91 * @param maxDocs The maximum number of documents you want returned; 0 means all matching documents
92 * @return An iteratorof documents that are not yet processed, match the selection criteria,
93 * and were created or modified after the cutoff date.
94 */
95 Iterator unprocessedSearch(String query, Calendar dateTime, int maxDocs);
96
97 /***
98 * The user name that is in effect for the current agent.
99 *
100 * In general, <tt>getEffectiveUserName</tt> and
101 * {@link DSession#getUserName() DSession.getUserName()}return the same
102 * value for a given program.
103 * The exceptions are agents that run on a server, where
104 * <tt>getEffectiveUserName</tt> is the name of the script's owner and
105 * getUserName is the name of the server on which the script is running.
106 * If the user name is hierarchical, this property returns the fully
107 * distinguished name.
108 *
109 * @return effective user name
110 */
111 String getEffectiveUserName();
112
113 /***
114 * The agent that's currently running.
115 *
116 * @return current agent
117 */
118 DAgent getCurrentAgent();
119
120 /***
121 * The database in which the current agent resides.
122 *
123 * @return current database
124 */
125 DDatabase getCurrentDatabase();
126
127 /***
128 * The in-memory document when an agent starts.
129 *
130 * <b>Usage</b><br/>
131 *
132 * For an agent activated in a view through the Notes client UI, the
133 * in-memory document is the document highlighted in the view. For an agent
134 * run from a browser with the OpenAgent URL command, the in-memory document
135 * is a new document containing an item for each CGI (Common Gateway
136 * Interface) variable supported by Lotus Domino. Each item has the name and
137 * current value of a supported CGI variable. (No design work on your part
138 * is needed; the CGI variables are available automatically.) For an agent
139 * run from a browser with <tt>Command([RunAgent])</tt> or <tt>Command[ToolsRunMacro]</tt>,
140 * the in-memory document is the current document. In the case of
141 * WebQueryOpen, this is the document before Lotus Domino converts it to
142 * HTML and sends it to the browser; in the case of WebQuerySave, this is
143 * the document before Lotus Domino saves it. If the form on which the
144 * document is based contains a field named the same as a Lotus
145 * Domino-supported CGI variable, the in-memory document also contains the
146 * value of that variable. (You must explicitly design the CGI variables
147 * into the form, for example, as hidden fields.). You cannot
148 * use the encrypt and remove methods on the Document object returned by
149 * getDocumentContext, nor use the compact method on the Database object
150 * that contains the Document object returned by getDocumentContext.
151 *
152 * @return The in-memory document when an agent starts.
153 */
154 DDocument getDocumentContext();
155
156 /***
157 * The exit status code returned by the Agent Manager the last time the current agent ran.
158 *
159 * @return last exit status
160 */
161 int getLastExitStatus();
162
163 /***
164 * The date and time when the current agent was last executed.
165 *
166 * @return date and time of last run
167 */
168 Calendar getLastRun();
169
170 /***
171 * A document that an agent uses to store information between invocations.
172 * The agent can use the information in this document the next time the
173 * agent runs.
174 *
175 * @return SavedData document
176 */
177 DDocument getSavedData();
178
179 /***
180 * The documents in a database that the current agent considers to be
181 * unprocessed. The type of agent determines which documents are
182 * considered unprocessed.
183 *
184 * @return iterator of unprocessed documents
185 */
186 Iterator getUnprocessedDocuments();
187 }