View Javadoc

1   /*
2    * This file is part of Domingo
3    * an Open Source Java-API to Lotus Notes/Domino
4    * hosted at http://domingo.sourceforge.net
5    *
6    * Copyright (c) 2003-2007 Beck et al. projects GmbH Munich, Germany (http://www.bea.de)
7    *
8    * This library is free software; you can redistribute it and/or
9    * modify it under the terms of the GNU Lesser General Public
10   * License as published by the Free Software Foundation; either
11   * version 2.1 of the License, or (at your option) any later version.
12   *
13   * This library is distributed in the hope that it will be useful,
14   * but WITHOUT ANY WARRANTY; without even the implied warranty of
15   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16   * Lesser General Public License for more details.
17   *
18   * You should have received a copy of the GNU Lesser General Public
19   * License along with this library; if not, write to the Free Software
20   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
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 }