de.bea.domingo
Interface DAgent

All Superinterfaces:

DBase, java.io.Serializable

All Known Implementing Classes:

AgentHttp, AgentProxy

public interface DAgent
extends DBase

Represents notes agents.

Author:

Kurt Riede

Field Summary

static int	ERROR_RUN Return value of method runOnServer if an exception occurred.
static int	TARGET_ALL_DOCS Target constant: TARGET_ALL_DOCS.
static int	TARGET_ALL_DOCS_IN_VIEW Target constant: TARGET_ALL_DOCS_IN_VIEW.
static int	TARGET_NEW_DOCS Target constant: TARGET_NEW_DOCS.
static int	TARGET_NEW_OR_MODIFIED_DOCS Target constant: TARGET_NEW_OR_MODIFIED_DOCS.
static int	TARGET_NONE Target constant: TARGET_NONE.
static int	TARGET_RUN_ONCE Target constant: TARGET_RUN_ONCE.
static int	TARGET_SELECTED_DOCS Target constant: TARGET_SELECTED_DOCS.
static int	TARGET_UNREAD_DOCS_IN_VIEW Target constant: TARGET_UNREAD_DOCS_IN_VIEW.
static int	TRIGGER_AFTER_MAIL_DELIVERY Trigger constant: TRIGGER_AFTER_MAIL_DELIVERY.
static int	TRIGGER_BEFORE_MAIL_DELIVERY Trigger constant: TRIGGER_BEFORE_MAIL_DELIVERY.
static int	TRIGGER_DOC_PASTED Trigger constant: TRIGGER_DOC_PASTED.
static int	TRIGGER_DOC_UPDATE Trigger constant: TRIGGER_DOC_UPDATE.
static int	TRIGGER_MANUAL Trigger constant: TRIGGER_MANUAL.
static int	TRIGGER_NONE Trigger constant: NONE.
static int	TRIGGER_SCHEDULED Trigger constant: TRIGGER_SCHEDULED.

Method Summary

java.lang.String	getComment() The comment that describes an agent, as entered by the agent's designer.
java.lang.String	getCommonOwner() The common name of the person who last modified and saved an agent.
java.util.Calendar	getLastRun() The date that an agent last ran.
java.lang.String	getName() The name of an agent.
java.lang.String	getOwner() The name of the person who last modified and saved an agent.
java.lang.String	getParameterDocID() Returns the NoteID of a document passed in by Run or RunOnServer.
java.lang.String	getQuery() The text of the query used by an agent to select documents.
java.lang.String	getServerName() The name of the server on which an agent runs.
int	getTarget() Indicates which documents this agent acts on.
int	getTrigger() Indicates when this agent runs.
boolean	isEnabled() Indicates if an agent is able to run or not.
boolean	isNotesAgent() Indicates if an agent can run in the Notes client environment.
boolean	isPublic() Indicates if an agent is public or personal.
boolean	isWebAgent() Indicates if an agent can run in a Web browser environment.
void	remove() Permanently deletes an agent from a database.
void	run() Runs the agent.
void	run(java.lang.String noteId) Runs the agent.
int	runOnServer() Runs the agent on the computer containing the database.
int	runOnServer(java.lang.String noteId) Runs the agent on the computer containing the database.
void	save() Saves changes made to the agent.
void	setEnabled(boolean enabled) Indicates if an agent is able to run or not.
void	setServerName(java.lang.String serverName) The name of the server on which an agent runs.

Methods inherited from interface de.bea.domingo.DBase

equals, hashCode, toString

Field Detail

TRIGGER_NONE

static final int TRIGGER_NONE

Trigger constant: NONE.

See Also:

Constant Field Values

TRIGGER_SCHEDULED

static final int TRIGGER_SCHEDULED

Trigger constant: TRIGGER_SCHEDULED.

See Also:

Constant Field Values

TRIGGER_AFTER_MAIL_DELIVERY

static final int TRIGGER_AFTER_MAIL_DELIVERY

Trigger constant: TRIGGER_AFTER_MAIL_DELIVERY.

See Also:

Constant Field Values

TRIGGER_DOC_PASTED

static final int TRIGGER_DOC_PASTED

Trigger constant: TRIGGER_DOC_PASTED.

See Also:

Constant Field Values

TRIGGER_MANUAL

static final int TRIGGER_MANUAL

Trigger constant: TRIGGER_MANUAL.

See Also:

Constant Field Values

TRIGGER_DOC_UPDATE

static final int TRIGGER_DOC_UPDATE

Trigger constant: TRIGGER_DOC_UPDATE.

See Also:

Constant Field Values

TRIGGER_BEFORE_MAIL_DELIVERY

static final int TRIGGER_BEFORE_MAIL_DELIVERY

Trigger constant: TRIGGER_BEFORE_MAIL_DELIVERY.

See Also:

Constant Field Values

TARGET_NONE

static final int TARGET_NONE

Target constant: TARGET_NONE.

See Also:

Constant Field Values

TARGET_ALL_DOCS

static final int TARGET_ALL_DOCS

Target constant: TARGET_ALL_DOCS.

See Also:

Constant Field Values

TARGET_NEW_DOCS

static final int TARGET_NEW_DOCS

Target constant: TARGET_NEW_DOCS.

See Also:

Constant Field Values

TARGET_NEW_OR_MODIFIED_DOCS

static final int TARGET_NEW_OR_MODIFIED_DOCS

Target constant: TARGET_NEW_OR_MODIFIED_DOCS.

See Also:

Constant Field Values

TARGET_SELECTED_DOCS

static final int TARGET_SELECTED_DOCS

Target constant: TARGET_SELECTED_DOCS.

See Also:

Constant Field Values

TARGET_ALL_DOCS_IN_VIEW

static final int TARGET_ALL_DOCS_IN_VIEW

Target constant: TARGET_ALL_DOCS_IN_VIEW.

See Also:

Constant Field Values

TARGET_UNREAD_DOCS_IN_VIEW

static final int TARGET_UNREAD_DOCS_IN_VIEW

Target constant: TARGET_UNREAD_DOCS_IN_VIEW.

See Also:

Constant Field Values

TARGET_RUN_ONCE

static final int TARGET_RUN_ONCE

Target constant: TARGET_RUN_ONCE.

See Also:

Constant Field Values

ERROR_RUN

static final int ERROR_RUN

Return value of method runOnServer if an exception occurred.

See Also:

Constant Field Values

Method Detail

getComment

java.lang.String getComment()

The comment that describes an agent, as entered by the agent's designer.

Returns:

the comment that describes an agent, as entered by the agent's designer

getCommonOwner

java.lang.String getCommonOwner()

The common name of the person who last modified and saved an agent.

Returns:

the common name of the person who last modified and saved an agent

isEnabled

boolean isEnabled()

Indicates if an agent is able to run or not.

Usage

This property is intended for use with scheduled agents, which can be enabled and disabled. This property always returns true for hidden agents and agents that are run from a menu.

You must call Save to make any change effective.

If the agent is open in the UI, a change is not immediately reflected. The agent must be closed and reopened.

Returns:

true if the agent can be run, else false

setEnabled

void setEnabled(boolean enabled)

Indicates if an agent is able to run or not.

Usage

This property is intended for use with scheduled agents, which can be enabled and disabled. This property always returns true for hidden agents and agents that are run from a menu.

You must call Save to make any change effective.

If the agent is open in the UI, a change is not immediately reflected. The agent must be closed and reopened.

Parameters:

enabled - true if the agent can be run, else false

isNotesAgent

boolean isNotesAgent()

Indicates if an agent can run in the Notes client environment.

Returns:

true if the agent can run in the Notes client environment, else false

isPublic

boolean isPublic()

Indicates if an agent is public or personal.

Returns:

true if an agent is public, else false.

isWebAgent

boolean isWebAgent()

Indicates if an agent can run in a Web browser environment.

Returns:

true if an agent can run in a Web browser environment, else false.

getLastRun

java.util.Calendar getLastRun()

The date that an agent last ran.

Returns:

the date that an agent last ran

getName

java.lang.String getName()

The name of an agent. Within a database, the name of an agent may not be unique.

Returns:

the name of an agent

getOwner

java.lang.String getOwner()

The name of the person who last modified and saved an agent.

Usage

If the owner's name is hierarchical, this property returns the fully distinguished name.

Saving the agent changes the owner immediately. However, if you subsequently call Agent.owner within the same Session, the previous owner's name will be returned. The ownership change is not reflected in properties until the next time a Session is obtained.

Returns:

the name of the person who last modified and saved an agent

getParameterDocID

java.lang.String getParameterDocID()

Returns the NoteID of a document passed in by Run or RunOnServer.

Usage

Use getDocumentByID in Database to get a document through its NoteID.

Returns:

the NoteID of a document passed in by Run or RunOnServer

getQuery

java.lang.String getQuery()

The text of the query used by an agent to select documents.

In the Agent Builder, a query is defined by the searches added to the agent using the Add Search button.

If no query is defined with the Add Search button, the Query property returns an empty string, even if the agent runs a formula that has its own SELECT statement or a script that selects specific documents.

Returns:

the text of the query used by an agent to select documents

getServerName

java.lang.String getServerName()

The name of the server on which an agent runs.

Returns:

the name of the server on which an agent runs

setServerName

void setServerName(java.lang.String serverName)

The name of the server on which an agent runs.

Usage

The value returned by getServerName depends upon whether the agent is scheduled:

• If the agent is scheduled, the property returns the name of the server that the scheduled agent runs on. Since scheduled agents can only run on a single replica of a database, you designate a server name for the agent under Schedule in the Agent Builder. Therefore, the ServerName property may represent the parent database's server, or it may represent a replica's server.
• If the agent is not scheduled, this property returns an empty string.
• You can set ServerName to the asterisk (*) to indicate that the agent can run on any server.
• A null ServerName means the local workstation.
• You must call Save to make any change effective.

Parameters:

serverName - the name of the server on which the agent should runs

getTarget

int getTarget()

Indicates which documents this agent acts on.

Usage

This property corresponds to "Which document(s) should it act on?" in the Designer UI for agents. The trigger limits the target possibilities. The TARGET_NONE targets are the only possibilities for their corresponding triggers.

Legal values

• Agent.TARGET_ALL_DOCS ("All documents in database")
• Agent.TARGET_ALL_DOCS_IN_VIEW ("All documents in view")
• Agent.TARGET_NEW_DOCS (Not used)
• Agent.TARGET_NEW_OR_MODIFIED_DOCS ("All new and modified documents since last run")
• Agent.TARGET_NONE ("Each incoming mail document," "Newly received mail documents," "Newly modified documents," "Pasted documents")
• Agent.TARGET_SELECTED_DOCS ("Selected documents")
• Agent.TARGET_UNREAD_DOCS_IN_VIEW ("All unread documents in view")
• Agent.TARGET_RUN_ONCE ("Run once")

Returns:

indicates which documents this agent acts on

getTrigger

int getTrigger()

Indicates when this agent runs.

Returns:

indicates when this agent runs

remove

void remove()

Permanently deletes an agent from a database.

run

void run()

Runs the agent.

Usage

You cannot run an agent recursively (cannot call it from itself).

The user cannot interact directly with a called agent. User output goes to the Domino log.

You cannot debug a called agent.

For local operations, the agent runs on the computer running the current program. See runOnServer to do otherwise.

For remote (IIOP) operations, the agent runs on the server handling the remote calls.

run

void run(java.lang.String noteId)

Runs the agent.

Usage

You cannot run an agent recursively (cannot call it from itself).

The user cannot interact directly with a called agent. User output goes to the Domino log.

You cannot debug a called agent.

For local operations, the agent runs on the computer running the current program. See runOnServer to do otherwise.

For remote (IIOP) operations, the agent runs on the server handling the remote calls.

Parameters:

noteId - the NoteID of a document. The value is passed to the ParameterDocID property of the called agent.

runOnServer

int runOnServer()

Runs the agent on the computer containing the database.

Usage

You cannot run an agent recursively (cannot call it from itself)..

The rules governing the access level required to run an agent using the runOnServer method are the same as for any other server-based agent. For information regarding agent security, see "Setting up agent security" in Application Development with Domino Designer..

The user cannot interact directly with a called agent. User output goes to the Domino log..

You cannot debug a called agent..

On a local database, the runOnServer method works like the run method, that is, runs the agent on the local computer or the server handling the remote (IIOP) calls..

Note This behavior is new with Release 5.0.2. The former behavior was to issue the error message "runOnServer must be used with a remote database.".

If a Notes client invokes runOnServer, security is through the signer of the agent.

Returns:

status of the operation where 0 indicates success.

runOnServer

int runOnServer(java.lang.String noteId)

Runs the agent on the computer containing the database.

Usage

You cannot run an agent recursively (cannot call it from itself)..

The rules governing the access level required to run an agent using the runOnServer method are the same as for any other server-based agent. For information regarding agent security, see "Setting up agent security" in Application Development with Domino Designer..

The user cannot interact directly with a called agent. User output goes to the Domino log..

You cannot debug a called agent..

On a local database, the runOnServer method works like the run method, that is, runs the agent on the local computer or the server handling the remote (IIOP) calls..

Note This behavior is new with Release 5.0.2. The former behavior was to issue the error message "runOnServer must be used with a remote database.".

If a Notes client invokes runOnServer, security is through the signer of the agent.

Parameters:

noteId - the NoteID of a document. The value is passed to the ParameterDocID property of the called agent.

Returns:

status of the operation where 0 indicates success.

save

void save()

Saves changes made to the agent.

Usage

Saving the agent changes the owner immediately. However, if you subsequently call Agent.owner within the same Session, the previous owner's name will be returned. The ownership change is not reflected in properties until the next time a Session is obtained.

You must call Save after setServerName and setEnabled, or the new value is lost.