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. Example:

 NotesSessionJob job = new NotesSessionJob("Job Name"){
 		protected IStatus runInNotesThread(Session session, IProgressMonitor monitor)
                        throws NotesException {
                        System.out.println(session.getUserName());
                        return Status.OK_STATUS;
                }
 }
 job.schedule();
 
 

Running the above code will print out the current user's user name.
You can also extend NotesSessionJob and implement it in your own class:

 public class MailNotesJob extends NotesSessionJob{
	private static final String SERVER = "";
	private String server;
	private String filePath;
	
	public MailNotesJob(String name) {
		super(name);
	}

	protected IStatus runInNotesThread(Session session, IProgressMonitor monitor)
			throws NotesException {
		DbDirectory dir = session.getDbDirectory(SERVER);
		Database mail = dir.openMailDatabase();
		server = mail.getServer();
		filePath = mail.getFilePath();
		mail.recycle();
		return Status.OK_STATUS;
	}
	
	public String getServer(){
		return this.server;
	}
	
	public String getFilePath(){
		return this.filePath;
	}
 }
 
 

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) Handles errors thrown while this job is running.
protected void	handle(NotesException e) Handles Notes errors thrown during the creation or life of the Session.
protected boolean	isOnMainThread() Determines whether this job is running on the main thread or on a background thread.
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

Since:

1.5.1

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

Since:

1.5.1

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

Since:

1.5.1

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

Since:

1.5.1

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:

e - error thrown

Since:

1.5.1

handle

protected void handle(InterruptedException e)

Handles errors thrown while this job is running.

Parameters:

e - error thrown

Since:

1.5.1

isOnMainThread

protected boolean isOnMainThread()

Determines whether this job is running on the main thread or on a background thread. This method should always return true when running on the Mac.

Returns:

true if the job is running on the main thread, false if running on a background thread

Since:

1.5.1

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

Since:

1.5.1