WorkManagerTaskExecutor (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.jca.work

## Class WorkManagerTaskExecutor

- java.lang.Object
- - org.springframework.jndi.JndiAccessor
  - - org.springframework.jndi.JndiLocatorSupport
    - - org.springframework.jca.work.WorkManagerTaskExecutor

- All Implemented Interfaces:
    Executor, WorkManager, Aware, InitializingBean, AsyncTaskExecutor, TaskExecutor, BootstrapContextAware, SchedulingTaskExecutor
  Direct Known Subclasses:
    GlassFishWorkManagerTaskExecutor, JBossWorkManagerTaskExecutor

      public class WorkManagerTaskExecutor
      extends JndiLocatorSupport
      implements SchedulingTaskExecutor, WorkManager, BootstrapContextAware, InitializingBean

  `TaskExecutor` implementation that delegates to a JCA 1.5 WorkManager, implementing the `WorkManager` interface.

  This is mainly intended for use within a JCA ResourceAdapter implementation, but may also be used in a standalone environment, delegating to a locally embedded WorkManager implementation (such as Geronimo's).

  Also implements the JCA 1.5 WorkManager interface itself, delegating all calls to the target WorkManager. Hence, a caller can choose whether it wants to talk to this executor through the Spring TaskExecutor interface or the JCA 1.5 WorkManager interface.

  This adapter is also capable of obtaining a JCA WorkManager from JNDI. This is for example appropriate on the Geronimo application server, where WorkManager GBeans (e.g. Geronimo's default "DefaultWorkManager" GBean) can be linked into the J2EE environment through "gbean-ref" entries in the `geronimo-web.xml` deployment descriptor.

  On JBoss and GlassFish, obtaining the default JCA WorkManager requires special lookup steps. See the `JBossWorkManagerTaskExecutor` `GlassFishWorkManagerTaskExecutor` classes which are the direct equivalent of this generic JCA adapter class.

  Since:
    2.0.3
  Author:
    Juergen Hoeller
  See Also:
    `setWorkManager(javax.resource.spi.work.WorkManager)`, `WorkManager.scheduleWork(javax.resource.spi.work.Work)`

- - ### Field Summary

    - ### Fields inherited from class org.springframework.jndi.JndiLocatorSupport

      `CONTAINER_PREFIX`

    - ### Fields inherited from class org.springframework.jndi.JndiAccessor

      `logger`

    - ### Fields inherited from interface org.springframework.core.task.AsyncTaskExecutor

      `TIMEOUT_IMMEDIATE, TIMEOUT_INDEFINITE`

    - ### Fields inherited from interface javax.resource.spi.work.WorkManager

      `IMMEDIATE, INDEFINITE, UNKNOWN`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `WorkManagerTaskExecutor()` Create a new WorkManagerTaskExecutor, expecting bean-style configuration.
    `WorkManagerTaskExecutor(WorkManager workManager)` Create a new WorkManagerTaskExecutor for the given WorkManager.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `afterPropertiesSet()` Invoked by a BeanFactory after it has set all bean properties supplied (and satisfied BeanFactoryAware and ApplicationContextAware).
    `void` | `doWork(Work work)`
    `void` | `doWork(Work work, long delay, ExecutionContext executionContext, WorkListener workListener)`
    `void` | `execute(Runnable task)` Execute the given `task`.
    `void` | `execute(Runnable task, long startTimeout)` Execute the given `task`.
    `protected WorkManager` | `getDefaultWorkManager()` Obtain a default WorkManager to delegate to.
    `boolean` | `prefersShortLivedTasks()` This task executor prefers short-lived work units.
    `void` | `scheduleWork(Work work)`
    `void` | `scheduleWork(Work work, long delay, ExecutionContext executionContext, WorkListener workListener)`
    `void` | `setBlockUntilCompleted(boolean blockUntilCompleted)` Set whether to let `execute(java.lang.Runnable)` block until the work has been completed.
    `void` | `setBlockUntilStarted(boolean blockUntilStarted)` Set whether to let `execute(java.lang.Runnable)` block until the work has been actually started.
    `void` | `setBootstrapContext(BootstrapContext bootstrapContext)` Specify the JCA BootstrapContext that contains the WorkManager to delegate to.
    `void` | `setWorkListener(WorkListener workListener)` Specify a JCA 1.5 WorkListener to apply, if any.
    `void` | `setWorkManager(WorkManager workManager)` Specify the JCA WorkManager instance to delegate to.
    `void` | `setWorkManagerName(String workManagerName)` Set the JNDI name of the JCA WorkManager.
    `long` | `startWork(Work work)`
    `long` | `startWork(Work work, long delay, ExecutionContext executionContext, WorkListener workListener)`
    `<T> Future<T>` | `submit(Callable<T> task)` Submit a Callable task for execution, receiving a Future representing that task.
    `Future<?>` | `submit(Runnable task)` Submit a Runnable task for execution, receiving a Future representing that task.

    - ### Methods inherited from class org.springframework.jndi.JndiLocatorSupport

      `convertJndiName, isResourceRef, lookup, lookup, setResourceRef`

    - ### Methods inherited from class org.springframework.jndi.JndiAccessor

      `getJndiEnvironment, getJndiTemplate, setJndiEnvironment, setJndiTemplate`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### WorkManagerTaskExecutor

          public WorkManagerTaskExecutor()

      Create a new WorkManagerTaskExecutor, expecting bean-style configuration.
      See Also:
        `setWorkManager(javax.resource.spi.work.WorkManager)`

    - #### WorkManagerTaskExecutor

          public WorkManagerTaskExecutor(WorkManager workManager)

      Create a new WorkManagerTaskExecutor for the given WorkManager.
      Parameters:
        `workManager` - the JCA WorkManager to delegate to

  - ### Method Detail

    - #### setWorkManager

          public void setWorkManager(WorkManager workManager)

      Specify the JCA WorkManager instance to delegate to.

    - #### setWorkManagerName

          public void setWorkManagerName(String workManagerName)

      Set the JNDI name of the JCA WorkManager.

      This can either be a fully qualified JNDI name, or the JNDI name relative to the current environment naming context if "resourceRef" is set to "true".

      See Also:
        `setWorkManager(javax.resource.spi.work.WorkManager)`, `JndiLocatorSupport.setResourceRef(boolean)`

    - #### setBootstrapContext

          public void setBootstrapContext(BootstrapContext bootstrapContext)

      Specify the JCA BootstrapContext that contains the WorkManager to delegate to.
      Specified by:
        `setBootstrapContext` in interface `BootstrapContextAware`
      Parameters:
        `bootstrapContext` - BootstrapContext object to be used by this object
      See Also:
        `InitializingBean.afterPropertiesSet()`, `ApplicationContextAware.setApplicationContext(org.springframework.context.ApplicationContext)`

    - #### setBlockUntilStarted

          public void setBlockUntilStarted(boolean blockUntilStarted)

      Set whether to let `execute(java.lang.Runnable)` block until the work has been actually started.

      Uses the JCA `startWork` operation underneath, instead of the default `scheduleWork`.

      See Also:
        `WorkManager.startWork(javax.resource.spi.work.Work)`, `WorkManager.scheduleWork(javax.resource.spi.work.Work)`

    - #### setBlockUntilCompleted

          public void setBlockUntilCompleted(boolean blockUntilCompleted)

      Set whether to let `execute(java.lang.Runnable)` block until the work has been completed.

      Uses the JCA `doWork` operation underneath, instead of the default `scheduleWork`.

      See Also:
        `WorkManager.doWork(javax.resource.spi.work.Work)`, `WorkManager.scheduleWork(javax.resource.spi.work.Work)`

    - #### setWorkListener

          public void setWorkListener(WorkListener workListener)

      Specify a JCA 1.5 WorkListener to apply, if any.

      This shared WorkListener instance will be passed on to the WorkManager by all `execute(java.lang.Runnable)` calls on this TaskExecutor.

    - #### afterPropertiesSet

          public void afterPropertiesSet()
                                  throws NamingException

      Description copied from interface: `InitializingBean`
      Invoked by a BeanFactory after it has set all bean properties supplied (and satisfied BeanFactoryAware and ApplicationContextAware).

      This method allows the bean instance to perform initialization only possible when all bean properties have been set and to throw an exception in the event of misconfiguration.

      Specified by:
        `afterPropertiesSet` in interface `InitializingBean`
      Throws:
        `NamingException`

    - #### getDefaultWorkManager

          protected WorkManager getDefaultWorkManager()

      Obtain a default WorkManager to delegate to. Called if no explicit WorkManager or WorkManager JNDI name has been specified.

      The default implementation returns a `SimpleTaskWorkManager`. Can be overridden in subclasses.

    - #### execute

          public void execute(Runnable task)

      Description copied from interface: `TaskExecutor`
      Execute the given `task`.

      The call might return immediately if the implementation uses an asynchronous execution strategy, or might block in the case of synchronous execution.

      Specified by:
        `execute` in interface `Executor`
      Specified by:
        `execute` in interface `TaskExecutor`
      Parameters:
        `task` - the `Runnable` to execute (never `null`)

    - #### execute

          public void execute(Runnable task,
                     long startTimeout)

      Description copied from interface: `AsyncTaskExecutor`
      Execute the given `task`.
      Specified by:
        `execute` in interface `AsyncTaskExecutor`
      Parameters:
        `task` - the `Runnable` to execute (never `null`)
        `startTimeout` - the time duration (milliseconds) within which the task is supposed to start. This is intended as a hint to the executor, allowing for preferred handling of immediate tasks. Typical values are `AsyncTaskExecutor.TIMEOUT_IMMEDIATE` or `AsyncTaskExecutor.TIMEOUT_INDEFINITE` (the default as used by `TaskExecutor.execute(Runnable)`).

    - #### submit

          public Future<?> submit(Runnable task)

      Description copied from interface: `AsyncTaskExecutor`
      Submit a Runnable task for execution, receiving a Future representing that task. The Future will return a `null` result upon completion.
      Specified by:
        `submit` in interface `AsyncTaskExecutor`
      Parameters:
        `task` - the `Runnable` to execute (never `null`)
      Returns:
        a Future representing pending completion of the task

    - #### submit

          public <T> Future<T> submit(Callable<T> task)

      Description copied from interface: `AsyncTaskExecutor`
      Submit a Callable task for execution, receiving a Future representing that task. The Future will return the Callable's result upon completion.
      Specified by:
        `submit` in interface `AsyncTaskExecutor`
      Parameters:
        `task` - the `Callable` to execute (never `null`)
      Returns:
        a Future representing pending completion of the task

    - #### prefersShortLivedTasks

          public boolean prefersShortLivedTasks()

      This task executor prefers short-lived work units.
      Specified by:
        `prefersShortLivedTasks` in interface `SchedulingTaskExecutor`
      Returns:
        `true` if this `TaskExecutor` prefers short-lived tasks

    - #### doWork

          public void doWork(Work work)
                      throws WorkException

      Specified by:
        `doWork` in interface `WorkManager`
      Throws:
        `WorkException`

    - #### doWork

          public void doWork(Work work,
                    long delay,
                    ExecutionContext executionContext,
                    WorkListener workListener)
                      throws WorkException

      Specified by:
        `doWork` in interface `WorkManager`
      Throws:
        `WorkException`

    - #### startWork

          public long startWork(Work work)
                         throws WorkException

      Specified by:
        `startWork` in interface `WorkManager`
      Throws:
        `WorkException`

    - #### startWork

          public long startWork(Work work,
                       long delay,
                       ExecutionContext executionContext,
                       WorkListener workListener)
                         throws WorkException

      Specified by:
        `startWork` in interface `WorkManager`
      Throws:
        `WorkException`

    - #### scheduleWork

          public void scheduleWork(Work work)
                            throws WorkException

      Specified by:
        `scheduleWork` in interface `WorkManager`
      Throws:
        `WorkException`

    - #### scheduleWork

          public void scheduleWork(Work work,
                          long delay,
                          ExecutionContext executionContext,
                          WorkListener workListener)
                            throws WorkException

      Specified by:
        `scheduleWork` in interface `WorkManager`
      Throws:
        `WorkException`