org.eclipse.scout.rt.client.job

Class ModelJobs

java.lang.Object

org.eclipse.scout.rt.client.job.ModelJobs

public final class ModelJobs
extends Object

Helper class to schedule model jobs.

Model jobs are used to interact with the Scout client model to read and write model values in a serial manner per session. This class is for convenience purpose to facilitate the creation and scheduling of model jobs.

By definition, a model job requires to be run on behalf of a ClientRunContext with a IClientSession set, and must have the session’s model job semaphore set as its ExecutionSemaphore. That causes all such jobs to be run in sequence in the model thread. At any given time, there is only one model thread active per client session.

Example:

 ModeJobs.schedule(new IRunnable() {

   @Override
   public void run() throws Exception {
     // do something
   }
 }, ModelJobs.newInput(ClientRunContexts.copyCurrent())
        .withName("example job")
        .withExecutionTrigger(Jobs.newExecutionTrigger()
            .withStartIn(5, TimeUnit.SECONDS));
 

The following code snippet illustrates how the job is finally run:

 BEANS.get(IJobManager.class).schedule(new IRunnable() {

     @Override
     public void run() throws Exception {
       clientRunContext.run(new IRunnable() {

         @Override
         public void run() throws Exception {
           // do some work
         }
       });
     }
   }, BEANS.get(JobInput.class)
        .withRunContext(clientRunContext)
        .withExecutionSemaphore(clientRunContext.getSession().getModelJobSemaphore()));
 

Since:

5.1

See Also:

IClientSession.getModelJobSemaphore()

Field Summary

Fields

Modifier and Type	Field and Description
static String	EXECUTION_HINT_UI_INTERACTION_REQUIRED Execution hint to signal that a model job requires interaction from the UI, which typically would be from the user, e.g.

Method Summary

Modifier and Type	Method and Description
static boolean	isModelJob(org.eclipse.scout.rt.platform.job.IFuture<?> future) Returns true if the given Future belongs to a model job.
static boolean	isModelThread() Returns true if the current thread represents the model thread for the current client session.
static boolean	isModelThread(IClientSession clientSession) Returns true if the current thread represents the model thread for the given client session.
static org.eclipse.scout.rt.platform.job.filter.event.JobEventFilterBuilder	newEventFilterBuilder() Returns a builder to create a filter for JobEvent objects originating from model jobs.
static org.eclipse.scout.rt.platform.job.filter.future.FutureFilterBuilder	newFutureFilterBuilder() Returns a builder to create a filter for IFuture objects representing a model job.
static org.eclipse.scout.rt.platform.job.JobInput	newInput(ClientRunContext clientRunContext) Creates a JobInput specific for model jobs initialized with the given ClientRunContext and the session's model job semaphore.
static <RESULT> org.eclipse.scout.rt.platform.job.IFuture<RESULT>	schedule(Callable<RESULT> callable, org.eclipse.scout.rt.platform.job.JobInput input) Runs the given Callable asynchronously in the model thread.
static org.eclipse.scout.rt.platform.job.IFuture<Void>	schedule(org.eclipse.scout.rt.platform.util.concurrent.IRunnable runnable, org.eclipse.scout.rt.platform.job.JobInput input) Runs the given IRunnable asynchronously in the model thread.
static void	yield() Instructs the job manager that the current model job is willing to temporarily yield its current model job permit.

Methods inherited from class java.lang.Object

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

Field Detail

EXECUTION_HINT_UI_INTERACTION_REQUIRED

public static final String EXECUTION_HINT_UI_INTERACTION_REQUIRED

Execution hint to signal that a model job requires interaction from the UI, which typically would be from the user, e.g. after opening a message box or dialog.

This hint is usually set just before a blocking condition is entered via 'waitFor'. Threads that are waiting for the model job to complete can then return to the UI before the job is actually done (which would never happen without the user interaction).

Usage

Code that blocks, but requires user interaction to release the lock:

 private void waitFor() {
   m_blockingCondition.waitFor(ModelJobs.EXECUTION_HINT_UI_INTERACTION_REQUIRED);
 }
 

Code that waits for the model job, but should return to the UI when user interaction is required:

   ...
   Jobs.getJobManager().awaitDone(ModelJobs.newFutureFilterBuilder()
      .andMatch(...) // any other conditions
      .andMatchNotExecutionHint(ModelJobs.EXECUTION_HINT_UI_INTERACTION_REQUIRED)
      .toFilter(), AWAIT_TIMEOUT, TimeUnit.MILLISECONDS)
   ...
 

See Also:

IJobManager#awaitDone(IFilter, long, TimeUnit)}, Constant Field Values

Method Detail

schedule

public static org.eclipse.scout.rt.platform.job.IFuture<Void> schedule(org.eclipse.scout.rt.platform.util.concurrent.IRunnable runnable,
                                                                       org.eclipse.scout.rt.platform.job.JobInput input)

Runs the given IRunnable asynchronously in the model thread. The submitter of the job continues to run in parallel.

Model jobs compete for the model permit once being fired by the associated trigger, and in the order as being scheduled. For example, if scheduling two model jobs in a row, they very likely will have the same execution time (granularity in milliseconds). However, job manager guarantees the first model job to be executed first. If no trigger is set, the model job starts competing for the model permit immediately.

Do not wait for this job to complete if being a model job yourself as this would cause a deadlock.

The job manager will use the JobInput as given to control job execution.

The IFuture returned allows to wait for the job to complete or to cancel its execution.

Usage:

 ModelJobs.schedule(new IRunnable() {

   @Override
   public void run() throws Exception {
     // do something
   }
 }, ModelJobs.newInput(ClientRunContexts.copyCurrent()));
 

Parameters:

runnable - IRunnable to be executed.

input - information about the job with execution instructions for the job manager to run the job.

Returns:

Future to interact with the job like waiting for its completion or to cancel its execution.

See Also:

IJobManager.schedule(IRunnable, JobInput)

schedule

public static <RESULT> org.eclipse.scout.rt.platform.job.IFuture<RESULT> schedule(Callable<RESULT> callable,
                                                                                  org.eclipse.scout.rt.platform.job.JobInput input)

Runs the given Callable asynchronously in the model thread. The submitter of the job continues to run in parallel.

Jobs in the form of a Callable typically return a computation result to the submitter.

Model jobs compete for the model permit once being fired by the associated trigger, and in the order as being scheduled. For example, if scheduling two model jobs in a row, they very likely will have the same execution time (granularity in milliseconds). However, job manager guarantees the first model job to be executed first. If no trigger is set, the model job starts competing for the model permit immediately.

Do not wait for this job to complete if being a model job yourself as this would cause a deadlock.

* The job manager will use the JobInput as given to control job execution.

The IFuture returned allows to wait for the job to complete or to cancel its execution. To immediately block waiting for the job to complete, you can use constructions of the following form.

Usage:

 String result = ModelJobs.schedule(new Callable() {

   @Override
   public String call() throws Exception {
     return "result";
   }
 }, ModelJobs.newInput(ClientRunContexts.copyCurrent())
     .withName("job name"))
     .awaitDoneAndGet();
 

Parameters:

callable - Callable to be executed.

input - information about the job with execution instructions for the job manager to run the job.

Returns:

Future to interact with the job like waiting for its completion, or to cancel its execution, or to get its computation result.

See Also:

IJobManager.schedule(Callable, JobInput)

newInput

public static org.eclipse.scout.rt.platform.job.JobInput newInput(ClientRunContext clientRunContext)

Creates a JobInput specific for model jobs initialized with the given ClientRunContext and the session's model job semaphore.

The job input returned can be associated with meta information about the job and with execution instructions to tell the job manager how to run the job. The input is to be given to the job manager alongside with the IRunnable or Callable to be executed.

Example:

 ModelJobs.newInput(ClientRunContexts.copyCurrent())
     .withName("example job")
     .withExecutionTrigger(Jobs.newExecutionTrigger()
         .withStartIn(5, TimeUnit.SECONDS));
 

Parameters:

clientRunContext - The ClientRunContext to be associated with the JobInput returned; must not be null.

newFutureFilterBuilder

public static org.eclipse.scout.rt.platform.job.filter.future.FutureFilterBuilder newFutureFilterBuilder()

Returns a builder to create a filter for IFuture objects representing a model job. This builder facilitates the creation of a IFuture filter and to match multiple criteria joined by logical 'AND' operation

Example usage:

 Jobs.newFutureFilterBuilder()
     .andMatch(new SessionFutureFilter(ISession.CURRENT.get()))
     .andMatch(...)
     .toFilter();
 

newEventFilterBuilder

public static org.eclipse.scout.rt.platform.job.filter.event.JobEventFilterBuilder newEventFilterBuilder()

Returns a builder to create a filter for JobEvent objects originating from model jobs. This builder facilitates the creation of a JobEvent filter and to match multiple criteria joined by logical 'AND' operation.

Example usage:

 Jobs.newEventFilterBuilder()
     .andMatchEventType(JobEventType.SCHEDULED, JobEventType.DONE)
     .andMatch(...)
     .toFilter();
 

isModelThread

public static boolean isModelThread()

Returns true if the current thread represents the model thread for the current client session. At any given time, there is only one model thread active per client session.

isModelThread

public static boolean isModelThread(IClientSession clientSession)

Returns true if the current thread represents the model thread for the given client session. At any given time, there is only one model thread active per client session.

isModelJob

public static boolean isModelJob(org.eclipse.scout.rt.platform.job.IFuture<?> future)

Returns true if the given Future belongs to a model job.

yield

public static void yield()

Instructs the job manager that the current model job is willing to temporarily yield its current model job permit.

It is rarely appropriate to use this method. It may be useful for debugging or testing purposes.