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