de.bea.domingo.proxy
Class AgentProxy

java.lang.Object
  de.bea.domingo.monitor.AbstractMonitorEnabled
      de.bea.domingo.proxy.BaseProxy
          de.bea.domingo.proxy.AgentProxy

All Implemented Interfaces:

DAgent, DBase, MonitorEnabled, java.io.Serializable

public final class AgentProxy
extends BaseProxy
implements DAgent

Represents a notes agent.

Author:

Kurt Riede

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class de.bea.domingo.proxy.BaseProxy

BaseProxy.DocumentCollectionIterator

Field Summary

Fields inherited from class de.bea.domingo.proxy.BaseProxy

DATETIME_STRING_LENGTH, EMPTY_STRING, MAX_DATETIME_LENGTH, NUM_DATETIME_VALUES, RESOURCES

Fields inherited from interface de.bea.domingo.DAgent

ERROR_RUN, TARGET_ALL_DOCS, TARGET_ALL_DOCS_IN_VIEW, TARGET_NEW_DOCS, TARGET_NEW_OR_MODIFIED_DOCS, TARGET_NONE, TARGET_RUN_ONCE, TARGET_SELECTED_DOCS, TARGET_UNREAD_DOCS_IN_VIEW, TRIGGER_AFTER_MAIL_DELIVERY, TRIGGER_BEFORE_MAIL_DELIVERY, TRIGGER_DOC_PASTED, TRIGGER_DOC_UPDATE, TRIGGER_MANUAL, TRIGGER_NONE, TRIGGER_SCHEDULED

Constructor Summary

AgentProxy(NotesProxyFactory theFactory, DBase theParent, lotus.domino.Agent agent, DNotesMonitor monitor)
Constructor.

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.
static DAgent	getInstance(NotesProxyFactory theFactory, DatabaseProxy database, lotus.domino.Agent theAgent, DNotesMonitor monitor) Factory method for instances of this class.
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.
java.lang.String	toString() Returns a short description of an instance.

Methods inherited from class de.bea.domingo.proxy.BaseProxy

checkSession, clearNotesObject, convertCalendarsToNotesDateTime, convertListToVector, convertNotesDateTimesToCalendar, convertVectorToList, createCalendar, createDateRange, createDateTime, decrementDateTimeCounter, finalize, getCountDateTime, getDSession, getFactory, getNotesObject, getParent, incrementDateTimeCounter, newException, newException, newException, newRuntimeException, newRuntimeException, newRuntimeException, recycleDateTimeList, refereceHashCode, toStringGeneric, toStringIntern

Methods inherited from class de.bea.domingo.monitor.AbstractMonitorEnabled

getMonitor, setMonitor

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface de.bea.domingo.DBase

equals, hashCode

Constructor Detail

AgentProxy

public AgentProxy(NotesProxyFactory theFactory,
                  DBase theParent,
                  lotus.domino.Agent agent,
                  DNotesMonitor monitor)

Constructor.

Parameters:

theFactory - the controlling factory

theParent - the parent

agent - the notes agent object

monitor - the monitor

Method Detail

getInstance

public static DAgent getInstance(NotesProxyFactory theFactory,
                                 DatabaseProxy database,
                                 lotus.domino.Agent theAgent,
                                 DNotesMonitor monitor)

Factory method for instances of this class.

Parameters:

theFactory - the controlling factory

database - the database that contains the agent

theAgent - Notes agent object

monitor - the monitor that handles logging

Returns:

Returns a DDatabase instance of type DatabaseProxy

getComment

public java.lang.String getComment()

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

Specified by:

getComment in interface DAgent

Returns:

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

See Also:

DAgent.getComment()

getCommonOwner

public java.lang.String getCommonOwner()

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

Specified by:

getCommonOwner in interface DAgent

Returns:

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

See Also:

DAgent.getCommonOwner()

isEnabled

public 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.

Specified by:

isEnabled in interface DAgent

Returns:

true if the agent can be run, else false

See Also:

DAgent.isEnabled()

setEnabled

public 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.

Specified by:

setEnabled in interface DAgent

Parameters:

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

See Also:

DAgent.setEnabled(boolean)

isNotesAgent

public boolean isNotesAgent()

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

Specified by:

isNotesAgent in interface DAgent

Returns:

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

See Also:

DAgent.isNotesAgent()

isPublic

public boolean isPublic()

Indicates if an agent is public or personal.

Specified by:

isPublic in interface DAgent

Returns:

true if an agent is public, else false.

See Also:

DAgent.isPublic()

isWebAgent

public boolean isWebAgent()

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

Specified by:

isWebAgent in interface DAgent

Returns:

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

See Also:

DAgent.isWebAgent()

getLastRun

public java.util.Calendar getLastRun()

The date that an agent last ran.

Specified by:

getLastRun in interface DAgent

Returns:

the date that an agent last ran

See Also:

DAgent.getLastRun()

getName

public java.lang.String getName()

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

Specified by:

getName in interface DAgent

Returns:

the name of an agent

See Also:

DAgent.getName()

getOwner

public 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.

Specified by:

getOwner in interface DAgent

Returns:

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

See Also:

DAgent.getOwner()

getParameterDocID

public 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.

Specified by:

getParameterDocID in interface DAgent

Returns:

the NoteID of a document passed in by Run or RunOnServer

See Also:

DAgent.getParameterDocID()

getQuery

public 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.

Specified by:

getQuery in interface DAgent

Returns:

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

See Also:

DAgent.getQuery()

getServerName

public java.lang.String getServerName()

The name of the server on which an agent runs.

Specified by:

getServerName in interface DAgent

Returns:

the name of the server on which an agent runs

See Also:

DAgent.getServerName()

setServerName

public 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.

Specified by:

setServerName in interface DAgent

Parameters:

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

See Also:

DAgent.setServerName(java.lang.String)

getTarget

public 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")

Specified by:

getTarget in interface DAgent

Returns:

indicates which documents this agent acts on

See Also:

DAgent.getTarget()

getTrigger

public int getTrigger()

Indicates when this agent runs.

Specified by:

getTrigger in interface DAgent

Returns:

indicates when this agent runs

See Also:

DAgent.getTrigger()

remove

public void remove()

Permanently deletes an agent from a database.

Specified by:

remove in interface DAgent

See Also:

DAgent.remove()

run

public 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.

Specified by:

run in interface DAgent

See Also:

DAgent.run()

run

public 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.

Specified by:

run in interface DAgent

Parameters:

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

See Also:

DAgent.run(java.lang.String)

runOnServer

public 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.

Specified by:

runOnServer in interface DAgent

Returns:

status of the operation where 0 indicates success.

See Also:

DAgent.runOnServer()

runOnServer

public 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.

Specified by:

runOnServer in interface DAgent

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.

See Also:

DAgent.runOnServer(java.lang.String)

save

public 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.

Specified by:

save in interface DAgent

See Also:

DAgent.save()

toString

public java.lang.String toString()

Description copied from interface: DBase

Returns a short description of an instance.

Specified by:

toString in interface DBase

Overrides:

toString in class java.lang.Object

Returns:

the name of the agent

See Also:

Object.toString()