com.mindoo.remote.api.jobs
Interface IRemoteJobTools

public interface IRemoteJobTools

Collection of useful methods to schedule jobs to visualize and execute background processes in the Notes UI

Nested Class Summary

static class

IRemoteJobTools.ConstantsType Use this enum to create standard IRemoteQualifiedNames of Eclipse and the Remote API

Field Summary

static java.lang.String	AGENT_PROPERTY_PREFIX Qualifier to be used to create and set Notes agent job properties (e.g. to pass parameters)
static java.lang.String	ECLIPSE_PROPERTY_PREFIX Qualifier to be used to create and set standard Eclipse job properties
static java.lang.String	JS_PROPERTY_PREFIX Qualifier to be used to create and set JavaScript job properties (e.g. to pass parameters)

Method Summary

IRemoteNotesBGAgentJob	createAgentJob(java.lang.String server, java.lang.String dbPath, java.lang.String agentName, boolean agentReportsProgress) Creates a IRemoteNotesBGAgentJob to execute a Notes agent as an Eclipse job in the background.
IRemoteJavascriptAction	createJavaScriptInLibAction(java.lang.String server, java.lang.String dbPath, java.lang.String ssjsLibName, java.lang.String methodCallJS, java.lang.String description) Creates an action that can be registered as a job action via IRemoteJob.setProperty(IRemoteQualifiedName, Object).
IRemoteJavascriptJob	createJavascriptInLibJob(java.lang.String jobName, java.lang.String server, java.lang.String filePath, java.lang.String ssjsLibName, java.lang.String methodCallJS) Creates a new JavaScript background job.
IRemoteMonitoringJob	createMonitoringJob(java.lang.String jobName) Creates a job that can be used to visualize progress and status information (e.g. in a progress dialog).
IRemoteQualifiedName	createPropertyKey(java.lang.String qualifier, java.lang.String localName) Factory method to create a new IRemoteQualifiedName that can be used to pass values to a background job.
IRemoteRunUIAgentAction	createRunUIAgentAction(java.lang.String server, java.lang.String dbPath, java.lang.String agentName, java.lang.String description) Creates an action that can be registered as a job action via IRemoteJob.setProperty(IRemoteQualifiedName, Object).
IRemoteQualifiedName	getProgressConstants(IRemoteJobTools.ConstantsType type) Method to create standard IRemoteQualifiedNames of Eclipse and the Remote API
void	runUIAgent(java.lang.String server, java.lang.String dbPath, java.lang.String agentName, boolean runOnUIContext, java.util.Map<java.lang.String,java.lang.Object> params) Runs a Notes agent in the Notes UI thread (meaning that e.g.

Field Detail

ECLIPSE_PROPERTY_PREFIX

static final java.lang.String ECLIPSE_PROPERTY_PREFIX

Qualifier to be used to create and set standard Eclipse job properties

See Also:

Constant Field Values

AGENT_PROPERTY_PREFIX

static final java.lang.String AGENT_PROPERTY_PREFIX

Qualifier to be used to create and set Notes agent job properties (e.g. to pass parameters)

See Also:

Constant Field Values

JS_PROPERTY_PREFIX

static final java.lang.String JS_PROPERTY_PREFIX

Qualifier to be used to create and set JavaScript job properties (e.g. to pass parameters)

See Also:

Constant Field Values

Method Detail

getProgressConstants

IRemoteQualifiedName getProgressConstants(IRemoteJobTools.ConstantsType type)
                                          throws RemoteEclipseAPIException

Method to create standard IRemoteQualifiedNames of Eclipse and the Remote API

Parameters:

type - qualified name type

Returns:

qualified name

Throws:

RemoteEclipseAPIException

createAgentJob

IRemoteNotesBGAgentJob createAgentJob(java.lang.String server,
                                      java.lang.String dbPath,
                                      java.lang.String agentName,
                                      boolean agentReportsProgress)
                                      throws RemoteEclipseAPIException

Creates a IRemoteNotesBGAgentJob to execute a Notes agent as an Eclipse job in the background. The agent code cannot directly access NotesUIWorkspace, because it is running in the background and not in the classic Notes Client's UI thread (like UI LotusScript code). Use it to process a long running operation in a LotusScript agent with the capability of reporting progress and check for user cancellation. To report the agent's result, you can for example register a IRemoteRunUIAgentAction to be called when the background job is done. , then display the result in the UI thread, the result by using IRemoteNotesUIWorkspace.runAgent(String, String, String, Map, boolean, boolean)

Parameters:

server - agent database's server

dbPath - agent database's filepath

agentName - agent name

agentReportsProgress - true if the agent is Remote API enabled, e.g. the API methods are used to report progress; false/ to display an indetermined job progress instead

Returns:

job

Throws:

RemoteEclipseAPIException

runUIAgent

void runUIAgent(java.lang.String server,
                java.lang.String dbPath,
                java.lang.String agentName,
                boolean runOnUIContext,
                java.util.Map<java.lang.String,java.lang.Object> params)
                throws RemoteEclipseAPIException

Runs a Notes agent in the Notes UI thread (meaning that e.g. LotusScript code can access NotesUIWorkspace). Pass in false for runOnUIContext to run your agent on a temporary document. Pass in true for runOnUIContext to run your agent on the current selected document in the UI. Values passed via param map, will be added to the temporary document. Also note with this method you can run an agent from one database on a completely different database. In other words, the agent you are running does not have to run on documents from the same database. While this gives the user more flexibility it also may break some assumptions of the agent, for example what fields are on the document.

When running an agent on a temporary document it is recommended that you set the Target the in the properties dialog of the agent to be 'None'. You can do this while editing the agent in Domino Designer. This allows you to run the agent without having anything selected in the UI. To access the temporary document from your agent, you can use Session.DocumentContext in LotusScript, or Session.getAgentContext().getDocumentContext() in Java.

Formula agents must be run on the UI context. The context must also have a view in order to run formula agents. For example, running a formula agent with the Workspace as the context does not work. When running a formula agent you must pass true to this method for runOnUIContext. As a result of this limitation, formula agents cannot be run on temporary documents.

There is a limit on how large the fields that are added to the temporary document can be. If a value is added to NotesAgentData, using addItem, and it is greater than 30,000 characters in length, you may see unexpected results when running the agent.

Parameters:

server - agent's database server

dbPath - agent's database filepath

agentName - agent name

runOnUIContext - true to run the agent on the current UI context false to run the agent on the temporary document (containing the passed parameters)

params -

Throws:

RemoteEclipseAPIException

createPropertyKey

IRemoteQualifiedName createPropertyKey(java.lang.String qualifier,
                                       java.lang.String localName)
                                       throws RemoteEclipseAPIException

Factory method to create a new IRemoteQualifiedName that can be used to pass values to a background job.
IRemoteQualifiedName wraps an Eclipse org.eclipse.core.runtime.QualifiedName

Parameters:

qualifier - qualifier

localName - property local name

Returns:

property property name object

Throws:

RemoteEclipseAPIException

createRunUIAgentAction

IRemoteRunUIAgentAction createRunUIAgentAction(java.lang.String server,
                                               java.lang.String dbPath,
                                               java.lang.String agentName,
                                               java.lang.String description)
                                               throws RemoteEclipseAPIException

Creates an action that can be registered as a job action via IRemoteJob.setProperty(IRemoteQualifiedName, Object). You can either register such an action for the execution phase of a job (in this case, the user can click on a link in the progress perspective of the Notes Client) or the action may be executed automatically when the agent is done.

Action for Job execution phase
Call createPropertyKey(String, String) with type IRemoteJobTools.ConstantsType.ECLIPSE_ACTION_PROPERTY to create a IRemoteQualifiedName, then use this qualified name to call IRemoteJob.setProperty(IRemoteQualifiedName, Object) and pass the action as property value.

Action execution when job is done (JavaScript jobs)
Call createPropertyKey(String, String) with type IRemoteJobTools.ConstantsType.JOBDONE_ACTION_PROPERTY to create a IRemoteQualifiedName, then use this qualified name to call IRemoteJob.setProperty(IRemoteQualifiedName, Object) and pass the action as property value.

Parameters:

server - agent database's server

dbPath - agent database's filepath

agentName - agent name

description - text for job status link in progress perspective, null to use the default ("OK")

Returns:

job action

Throws:

RemoteEclipseAPIException

createJavaScriptInLibAction

IRemoteJavascriptAction createJavaScriptInLibAction(java.lang.String server,
                                                    java.lang.String dbPath,
                                                    java.lang.String ssjsLibName,
                                                    java.lang.String methodCallJS,
                                                    java.lang.String description)
                                                    throws RemoteEclipseAPIException

Creates an action that can be registered as a job action via IRemoteJob.setProperty(IRemoteQualifiedName, Object). You can either register such an action for the execution phase of a job (in this case, the user can click on a link in the progress perspective of the Notes Client) or the action may be executed automatically when the agent is done.

Action for Job execution phase
Call createPropertyKey(String, String) with type IRemoteJobTools.ConstantsType.ECLIPSE_ACTION_PROPERTY to create a IRemoteQualifiedName, then use this qualified name to call IRemoteJob.setProperty(IRemoteQualifiedName, Object) and pass the action as property value.

Action execution when job is done (JavaScript jobs)
Call createPropertyKey(String, String) with type IRemoteJobTools.ConstantsType.JOBDONE_ACTION_PROPERTY to create a IRemoteQualifiedName, then use this qualified name to call IRemoteJob.setProperty(IRemoteQualifiedName, Object) and pass the action as property value.


The remote api uses an alternative JavaScript engine (Rhino) to execute JavaScript in the specified SSJS library design element.

Please note that you cannot use @formula language or other classes from an XPages application. We simply used JavaScript as an easy interpreted language to schedule background jobs without the need to create and install an explicit plugin in the Notes client. However you can use any Java classes and resources that are part of the NSF project's build path.
There are also a few JavaScript variables that are automatically registered for your convenience:

session - use this to read/write data in Lotus Notes Java APIs
database - database in which the SSJS is located
progress - wraps a org.eclipse.core.runtime.IProgressMonitor to report progress and check for cancellation
context - a temporary document that is shared between the running Job and the action. Use it to transfer computation results or the current progress

Parameters:

server - SSJS lib db server

dbPath - SSJS lib db filepath

ssjsLibName - SSJS lib name

methodCallJS - JavaScript method call, e.g. "method();" - the line is appended to the SSJS lib code

description - text for job status link in progress perspective, null to use the default ("OK")

Returns:

job action

Throws:

RemoteEclipseAPIException

createMonitoringJob

IRemoteMonitoringJob createMonitoringJob(java.lang.String jobName)
                                         throws RemoteEclipseAPIException

Creates a job that can be used to visualize progress and status information (e.g. in a progress dialog). The job is running until the method IRemoteProgressMonitor.done() is called on the progress monitor returned by IRemoteMonitoringJob.getProgressMonitor()

A use case for this method is long running background code execution, e.g. XPages SSJS, that needs a visualization in the UI

Parameters:

jobName - job name

Returns:

job reference

Throws:

RemoteEclipseAPIException

createJavascriptInLibJob

IRemoteJavascriptJob createJavascriptInLibJob(java.lang.String jobName,
                                              java.lang.String server,
                                              java.lang.String filePath,
                                              java.lang.String ssjsLibName,
                                              java.lang.String methodCallJS)
                                              throws RemoteEclipseAPIException

Creates a new JavaScript background job. The remote api uses an alternative JavaScript engine (Rhino) to execute a JavaScript in the specified SSJS library design element.

Please note that you cannot use @formula language or other classes from an XPages application. We simply used JavaScript as an easy interpreted language to schedule background jobs without the need to create and install an explicit plugin in the Notes client. However you can use any Java classes and resources that are part of the NSF project's build path.
There are also a few JavaScript variables that are automatically registered for your convenience:

session - use this to read/write data in Lotus Notes Java APIs
database - database in which the SSJS is located
progress - wraps a org.eclipse.core.runtime.IProgressMonitor to report progress and check for cancellation
context - a temporary document that contains string/double/integer parameter values passed via IRemoteJavascriptJob.addJSProperty(String, Object). If you register a 'Run UI action' (createRunUIAgentAction(String, String, String, String)) for the job, this context document is also passed to this action.
Additional JavaScript variables can be defined by using IRemoteJavascriptJob.addJSProperty(String, Object)}

Parameters:

jobName - job name

server - SSJS lib db server

filePath - SSJS lib db filepath

ssjsLibName - SSJS lib name

methodCallJS - JavaScript method call, e.g. "method();" - the line is appended to the SSJS lib code

Returns:

job

Throws:

RemoteEclipseAPIException