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

org.springframework.scheduling.commonj

## Class WorkManagerTaskExecutor

- java.lang.Object
- - org.springframework.jndi.JndiAccessor
  - - org.springframework.jndi.JndiLocatorSupport
    - - org.springframework.scheduling.commonj.WorkManagerTaskExecutor

- All Implemented Interfaces:
    WorkManager, Executor, InitializingBean, AsyncTaskExecutor, TaskExecutor, SchedulingTaskExecutor

      public class WorkManagerTaskExecutor
      extends JndiLocatorSupport
      implements SchedulingTaskExecutor, WorkManager, InitializingBean

  TaskExecutor implementation that delegates to a CommonJ WorkManager, implementing the `WorkManager` interface, which either needs to be specified as reference or through the JNDI name.

  This is the central convenience class for setting up a CommonJ WorkManager in a Spring context.

  Also implements the CommonJ 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 CommonJ WorkManager interface.

  The CommonJ WorkManager will usually be retrieved from the application server's JNDI environment, as defined in the server's management console.

  Note: At the time of this writing, the CommonJ WorkManager facility is only supported on IBM WebSphere 6.0+ and BEA WebLogic 9.0+, despite being such a crucial API for an application server. (There is a similar facility available on WebSphere 5.1 Enterprise, though, which we will discuss below.)

  On JBoss and GlassFish, a similar facility is available through the JCA WorkManager. See the `JBossWorkManagerTaskExecutor` `GlassFishWorkManagerTaskExecutor` classes which are the direct equivalent of this CommonJ adapter class.

  Since:
    2.0
  Author:
    Juergen Hoeller

- - ### 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 commonj.work.WorkManager

      `IMMEDIATE, INDEFINITE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `WorkManagerTaskExecutor()`

  - ### 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` | `execute(Runnable task)` Execute the given `task`.
    `void` | `execute(Runnable task, long startTimeout)` Execute the given `task`.
    `boolean` | `prefersShortLivedTasks()` This task executor prefers short-lived work units.
    `WorkItem` | `schedule(Work work)`
    `WorkItem` | `schedule(Work work, WorkListener workListener)`
    `void` | `setWorkListener(WorkListener workListener)` Specify a CommonJ WorkListener to apply, if any.
    `void` | `setWorkManager(WorkManager workManager)` Specify the CommonJ WorkManager to delegate to.
    `void` | `setWorkManagerName(String workManagerName)` Set the JNDI name of the CommonJ WorkManager.
    `<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.
    `boolean` | `waitForAll(Collection workItems, long timeout)`
    `Collection` | `waitForAny(Collection workItems, long timeout)`

    - ### 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()

  - ### Method Detail

    - #### setWorkManager

          public void setWorkManager(WorkManager workManager)

      Specify the CommonJ WorkManager to delegate to.

      Alternatively, you can also specify the JNDI name of the target WorkManager.

      See Also:
        `setWorkManagerName(java.lang.String)`

    - #### setWorkManagerName

          public void setWorkManagerName(String workManagerName)

      Set the JNDI name of the CommonJ 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(commonj.work.WorkManager)`, `JndiLocatorSupport.setResourceRef(boolean)`

    - #### setWorkListener

          public void setWorkListener(WorkListener workListener)

      Specify a CommonJ 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`

    - #### 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

    - #### schedule

          public WorkItem schedule(Work work)
                            throws WorkException,
                                   IllegalArgumentException

      Specified by:
        `schedule` in interface `WorkManager`
      Throws:
        `WorkException`
        `IllegalArgumentException`

    - #### schedule

          public WorkItem schedule(Work work,
                          WorkListener workListener)
                            throws WorkException,
                                   IllegalArgumentException

      Specified by:
        `schedule` in interface `WorkManager`
      Throws:
        `WorkException`
        `IllegalArgumentException`

    - #### waitForAll

          public boolean waitForAll(Collection workItems,
                           long timeout)
                             throws InterruptedException,
                                    IllegalArgumentException

      Specified by:
        `waitForAll` in interface `WorkManager`
      Throws:
        `InterruptedException`
        `IllegalArgumentException`

    - #### waitForAny

          public Collection waitForAny(Collection workItems,
                              long timeout)
                                throws InterruptedException,
                                       IllegalArgumentException

      Specified by:
        `waitForAny` in interface `WorkManager`
      Throws:
        `InterruptedException`
        `IllegalArgumentException`