com.ibm.notes.java.api.util
Class NotesSessionJob

java.lang.Object
  org.eclipse.core.runtime.PlatformObject
      org.eclipse.core.internal.jobs.InternalJob
          org.eclipse.core.runtime.jobs.Job
              com.ibm.notes.java.api.util.NotesSessionJob

All Implemented Interfaces:

Comparable, IAdaptable

public abstract class NotesSessionJob
extends Job

Instances of this class allow for executing code on a Notes thread. Clients must subclass and implement the runInNotesThread method. It is important not to join this Job to the UI thread. This class replaces the NotesJob class to add better memory management and security context switching.

Field Summary

Fields inherited from class org.eclipse.core.runtime.jobs.Job

ASYNC_FINISH, BUILD, DECORATE, INTERACTIVE, LONG, NONE, RUNNING, SHORT, SLEEPING, WAITING

Fields inherited from class org.eclipse.core.internal.jobs.InternalJob

manager

Constructor Summary

NotesSessionJob(String name)
Subclasses must override the constructor to give the Job a user-readable name.

Method Summary

protected Session	createSession() Create a new session for this Job.
protected Session	getSession() Retrieve the session in which this Job is running.
protected void	handle(InterruptedException e)
protected void	handle(NotesException e) Handles Notes errors thrown during the creation or life of the Session.
protected boolean	isOnMainThread()
protected void	recycle() Recycles the session create by the createSession method.
protected IStatus	run(IProgressMonitor monitor)
protected abstract IStatus	runInNotesThread(Session session, IProgressMonitor monitor) Clients must implement this method with code that is executed on the Notes thread.

Methods inherited from class org.eclipse.core.runtime.jobs.Job

addJobChangeListener, belongsTo, cancel, canceling, done, getJobManager, getName, getPriority, getProperty, getResult, getRule, getState, getThread, isBlocking, isSystem, isUser, join, removeJobChangeListener, schedule, schedule, setName, setPriority, setProgressGroup, setProperty, setRule, setSystem, setThread, setUser, shouldRun, shouldSchedule, sleep, wakeUp, wakeUp

Methods inherited from class org.eclipse.core.internal.jobs.InternalJob

compareTo, toString

Methods inherited from class org.eclipse.core.runtime.PlatformObject

getAdapter

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.eclipse.core.runtime.IAdaptable

getAdapter

Constructor Detail

NotesSessionJob

public NotesSessionJob(String name)

Subclasses must override the constructor to give the Job a user-readable name.

Parameters:

name - name of the job

Method Detail

getSession

protected final lotus.domino.Session getSession()

Retrieve the session in which this Job is running. The session is valid after the createSession and before the recycle method.

Returns:

session current session

createSession

protected lotus.domino.Session createSession()
                                      throws NotesException 

Create a new session for this Job. NotesFactory.createSession() is used in the default implementation. Allows a subclass to create the session with different arguments.

Returns:

new session

Throws:

NotesException - error through during creation

recycle

protected void recycle()
                throws NotesException 

Recycles the session create by the createSession method. Subclasses may override to clean up other session-dependent variables, but must call the super method. Note: this will not be called if an error was thrown from runInNotesThread.

Throws:

NotesException - error while recycling

handle

protected void handle(NotesException e)

Handles Notes errors thrown during the creation or life of the Session. The default implementation logs the error. Subclasses may override to handle the error differently.

Parameters:

error - thrown

handle

protected void handle(InterruptedException e)

isOnMainThread

protected boolean isOnMainThread()

run

protected final IStatus run(IProgressMonitor monitor)

Specified by:

run in class Job

runInNotesThread

protected abstract IStatus runInNotesThread(Session session,
                                            IProgressMonitor monitor)
                                     throws NotesException 

Clients must implement this method with code that is executed on the Notes thread. Note that the given session is only valid during the life of this method. Additionally, any Notes elements accessed or created are valid only within this method. Any data used across "sessions" must be saved in formats other than those provided by the Notes back-end classes.

Parameters:

session - the Notes session to use for communicating with Notes back-end elements.

monitor - the progress monitor used for this job

Returns:

the status of the job

Throws:

NotesException - thrown when an error occurs during the operation