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
27 /***
28 * Represents notes agents.
29 *
30 * @author <a href=mailto:kriede@users.sourceforge.net>Kurt Riede</a>
31 */
32 public interface DAgent extends DBase {
33
34 /*** Trigger constant: NONE. */
35 int TRIGGER_NONE = 0;
36
37 /*** Trigger constant: TRIGGER_SCHEDULED. */
38 int TRIGGER_SCHEDULED = 1;
39
40 /*** Trigger constant: TRIGGER_AFTER_MAIL_DELIVERY. */
41 int TRIGGER_AFTER_MAIL_DELIVERY = 2;
42
43 /*** Trigger constant: TRIGGER_DOC_PASTED. */
44 int TRIGGER_DOC_PASTED = 3;
45
46 /*** Trigger constant: TRIGGER_MANUAL. */
47 int TRIGGER_MANUAL = 4;
48
49 /*** Trigger constant: TRIGGER_DOC_UPDATE. */
50 int TRIGGER_DOC_UPDATE = 5;
51
52 /*** Trigger constant: TRIGGER_BEFORE_MAIL_DELIVERY. */
53 int TRIGGER_BEFORE_MAIL_DELIVERY = 6;
54
55 /*** Target constant: TARGET_NONE. */
56 int TARGET_NONE = 0;
57
58 /*** Target constant: TARGET_ALL_DOCS. */
59 int TARGET_ALL_DOCS = 1;
60
61 /*** Target constant: TARGET_NEW_DOCS. */
62 int TARGET_NEW_DOCS = 2;
63
64 /*** Target constant: TARGET_NEW_OR_MODIFIED_DOCS. */
65 int TARGET_NEW_OR_MODIFIED_DOCS = 3;
66
67 /*** Target constant: TARGET_SELECTED_DOCS. */
68 int TARGET_SELECTED_DOCS = 4;
69
70 /*** Target constant: TARGET_ALL_DOCS_IN_VIEW. */
71 int TARGET_ALL_DOCS_IN_VIEW = 5;
72
73 /*** Target constant: TARGET_UNREAD_DOCS_IN_VIEW. */
74 int TARGET_UNREAD_DOCS_IN_VIEW = 6;
75
76 /*** Target constant: TARGET_RUN_ONCE. */
77 int TARGET_RUN_ONCE = 8;
78
79 /*** Return value of method runOnServer if an exception occurred. */
80 int ERROR_RUN = 1000;
81
82 /***
83 * The comment that describes an agent, as entered by the agent's designer.
84 *
85 * @return the comment that describes an agent, as entered by the agent's
86 * designer
87 */
88 String getComment();
89
90 /***
91 * The common name of the person who last modified and saved an agent.
92 *
93 * @return the common name of the person who last modified and saved an agent
94 */
95 String getCommonOwner();
96
97 /***
98 * Indicates if an agent is able to run or not.
99 *
100 * <p><b>Usage</b></p>
101 * <p>This property is intended for use with scheduled agents, which can
102 * be enabled and disabled. This property always returns true for hidden
103 * agents and agents that are run from a menu.</p>
104 * <p>You must call Save to make any change effective.</p>
105 * <p>If the agent is open in the UI, a change is not immediately
106 * reflected. The agent must be closed and reopened.</p>
107 *
108 * @return <code>true</code> if the agent can be run, else <code>false</code>
109 */
110 boolean isEnabled();
111
112 /***
113 * Indicates if an agent is able to run or not.
114 *
115 * <p><b>Usage</b></p>
116 * <p>This property is intended for use with scheduled agents, which can
117 * be enabled and disabled. This property always returns true for hidden
118 * agents and agents that are run from a menu.</p>
119 * <p>You must call Save to make any change effective.</p>
120 * <p>If the agent is open in the UI, a change is not immediately
121 * reflected. The agent must be closed and reopened.</p>
122 *
123 * @param enabled <code>true</code> if the agent can be run, else <code>false</code>
124 */
125 void setEnabled(boolean enabled);
126
127 /***
128 * Indicates if an agent can run in the Notes client environment.
129 *
130 * @return <code>true</code> if the agent can run in the Notes client environment, else <code>false</code>
131 */
132 boolean isNotesAgent();
133
134 /***
135 * Indicates if an agent is public or personal.
136 *
137 * @return <code>true</code> if an agent is public, else <code>false</code>.
138 */
139 boolean isPublic();
140
141 /***
142 * Indicates if an agent can run in a Web browser environment.
143 *
144 * @return <code>true</code> if an agent can run in a Web browser environment, else <code>false</code>.
145 */
146 boolean isWebAgent();
147
148 /***
149 * The date that an agent last ran.
150 *
151 * @return the date that an agent last ran
152 */
153 Calendar getLastRun();
154
155 /***
156 * The name of an agent. Within a database, the name of an agent may not be unique.
157 *
158 * @return the name of an agent
159 */
160 String getName();
161
162 /***
163 * The name of the person who last modified and saved an agent.
164 *
165 * <p><b>Usage</b></p>
166 * <p>If the owner's name is hierarchical, this property returns the fully
167 * distinguished name.</p>
168 * <p>Saving the agent changes the owner immediately. However, if you
169 * subsequently call Agent.owner within the same Session, the previous
170 * owner's name will be returned. The ownership change is not reflected
171 * in properties until the next time a Session is obtained.</p>
172 *
173 * @return the name of the person who last modified and saved an agent
174 */
175 String getOwner();
176
177 /***
178 * Returns the NoteID of a document passed in by Run or RunOnServer.
179 *
180 * <p><b>Usage</b></p>
181 * <p>Use getDocumentByID in Database to get a document through its NoteID.</p>
182 *
183 * @return the NoteID of a document passed in by Run or RunOnServer
184 */
185 String getParameterDocID();
186
187 /***
188 * The text of the query used by an agent to select documents.
189 * <p>In the Agent Builder, a query is defined by the searches
190 * added to the agent using the Add Search button.</p>
191 * <p>If no query is defined with the Add Search button, the Query
192 * property returns an empty string, even if the agent runs a formula
193 * that has its own SELECT statement or a script that selects specific
194 * documents.</p>
195 *
196 * @return the text of the query used by an agent to select documents
197 */
198 String getQuery();
199
200 /***
201 * The name of the server on which an agent runs.
202 *
203 * @return the name of the server on which an agent runs
204 */
205 String getServerName();
206
207 /***
208 * The name of the server on which an agent runs.
209 * <p><b>Usage</b></p>
210 * <p>The value returned by getServerName depends upon whether the agent is scheduled:
211 * <ul>
212 * <li>If the agent is scheduled, the property returns the name of the
213 * server that the scheduled agent runs on. Since scheduled agents can
214 * only run on a single replica of a database, you designate a server
215 * name for the agent under Schedule in the Agent Builder. Therefore,
216 * the ServerName property may represent the parent database's server,
217 * or it may represent a replica's server.</li>
218 * <li>If the agent is not scheduled, this property returns an empty
219 * string.</li>
220 * <li>You can set ServerName to the asterisk (*) to indicate that the
221 * agent can run on any server.</li>
222 * <li>A null ServerName means the local workstation.</li>
223 * <li>You must call Save to make any change effective.</li></ul></p>
224 *
225 * @param serverName the name of the server on which the agent should runs
226 */
227 void setServerName(String serverName);
228
229 /***
230 * Indicates which documents this agent acts on.
231 *
232 * <p><b>Usage</b></p>
233 * <p>This property corresponds to "Which document(s) should it act on?"
234 * in the Designer UI for agents. The trigger limits the target
235 * possibilities. The TARGET_NONE targets are the only possibilities for
236 * their corresponding triggers.</p>
237 *
238 * <p><b>Legal values</b>
239 * <ul>
240 * <li>Agent.TARGET_ALL_DOCS ("All documents in database")</li>
241 * <li>Agent.TARGET_ALL_DOCS_IN_VIEW ("All documents in view")</li>
242 * <li>Agent.TARGET_NEW_DOCS (Not used)</li>
243 * <li>Agent.TARGET_NEW_OR_MODIFIED_DOCS ("All new and modified documents
244 * since last run")</li>
245 * <li>Agent.TARGET_NONE ("Each incoming mail document," "Newly received
246 * mail documents," "Newly modified documents," "Pasted documents")</li>
247 * <li>Agent.TARGET_SELECTED_DOCS ("Selected documents")</li>
248 * <li>Agent.TARGET_UNREAD_DOCS_IN_VIEW ("All unread documents in view")</li>
249 * <li>Agent.TARGET_RUN_ONCE ("Run once")</li></ul></p>
250 *
251 * @return indicates which documents this agent acts on
252 */
253 int getTarget();
254
255 /***
256 * Indicates when this agent runs.
257 *
258 * @return indicates when this agent runs
259 */
260 int getTrigger();
261
262 /***
263 * Permanently deletes an agent from a database.
264 */
265 void remove();
266
267 /***
268 * Runs the agent.
269 *
270 * <p><b>Usage</b></p>
271 * <p>You cannot run an agent recursively (cannot call it from itself).</p>
272 * <p>The user cannot interact directly with a called agent. User output
273 * goes to the Domino log.</p>
274 * <p>You cannot debug a called agent.</p>
275 * <p>For local operations, the agent runs on the computer running the
276 * current program. See runOnServer to do otherwise.</p>
277 * <p>For remote (IIOP) operations, the agent runs on the server handling
278 * the remote calls.</p>
279 */
280 void run();
281
282 /***
283 * Runs the agent.
284 *
285 * <p><b>Usage</b></p>
286 * <p>You cannot run an agent recursively (cannot call it from itself).</p>
287 * <p>The user cannot interact directly with a called agent. User output
288 * goes to the Domino log.</p>
289 * <p>You cannot debug a called agent.</p>
290 * <p>For local operations, the agent runs on the computer running the
291 * current program. See runOnServer to do otherwise.</p>
292 * <p>For remote (IIOP) operations, the agent runs on the server handling
293 * the remote calls.</p>
294 *
295 * @param noteId the NoteID of a document. The value is passed to the ParameterDocID property of the called agent.
296 */
297 void run(String noteId);
298
299 /***
300 * Runs the agent on the computer containing the database.
301 *
302 * <p><b>Usage</b></p>
303 * <p>You cannot run an agent recursively (cannot call it from itself)..</p>
304 * <p>The rules governing the access level required to run an agent using
305 * the runOnServer method are the same as for any other server-based agent.
306 * For information regarding agent security, see "Setting up agent security"
307 * in Application Development with Domino Designer..</p>
308 * <p>The user cannot interact directly with a called agent. User output
309 * goes to the Domino log..</p>
310 * <p>You cannot debug a called agent..</p>
311 * <p>On a local database, the runOnServer method works like the run method,
312 * that is, runs the agent on the local computer or the server handling the
313 * remote (IIOP) calls..</p>
314 * <p>Note This behavior is new with Release 5.0.2. The former behavior
315 * was to issue the error message "runOnServer must be used with a remote
316 * database.".</p>
317 * <p>If a Notes client invokes runOnServer, security is through the signer
318 * of the agent.</p>
319 *
320 * @return status of the operation where 0 indicates success.
321 */
322 int runOnServer();
323
324 /***
325 * Runs the agent on the computer containing the database.
326 *
327 * <p><b>Usage</b></p>
328 * <p>You cannot run an agent recursively (cannot call it from itself)..</p>
329 * <p>The rules governing the access level required to run an agent using
330 * the runOnServer method are the same as for any other server-based agent.
331 * For information regarding agent security, see "Setting up agent security"
332 * in Application Development with Domino Designer..</p>
333 * <p>The user cannot interact directly with a called agent. User output
334 * goes to the Domino log..</p>
335 * <p>You cannot debug a called agent..</p>
336 * <p>On a local database, the runOnServer method works like the run method,
337 * that is, runs the agent on the local computer or the server handling the
338 * remote (IIOP) calls..</p>
339 * <p>Note This behavior is new with Release 5.0.2. The former behavior
340 * was to issue the error message "runOnServer must be used with a remote
341 * database.".</p>
342 * <p>If a Notes client invokes runOnServer, security is through the signer
343 * of the agent.</p>
344 *
345 * @param noteId the NoteID of a document. The value is passed to the ParameterDocID property of the called agent.
346 * @return status of the operation where 0 indicates success.
347 */
348 int runOnServer(String noteId);
349
350 /***
351 * Saves changes made to the agent.
352 *
353 * <p><b>Usage</b></p>
354 * <p>Saving the agent changes the owner immediately. However, if you
355 * subsequently call Agent.owner within the same Session, the previous
356 * owner's name will be returned. The ownership change is not reflected
357 * in properties until the next time a Session is obtained.</p>
358 * <p>You must call Save after setServerName and setEnabled, or the new
359 * value is lost.</p>
360 */
361 void save();
362 }