Skip navigation links

Oracle® Coherence Java API Reference
Release 3.6.1.0

E18814-01


com.tangosol.coherence.commonj
Class WorkManager

java.lang.Object
  extended by com.tangosol.util.Base
      extended by com.tangosol.coherence.commonj.WorkManager

All Implemented Interfaces:
commonj.work.WorkManager

public class WorkManager
extends Base
implements commonj.work.WorkManager

An implementation of commonj.work.WorkManager based on a joint BEA-IBM specification: "The Timer and Work Manager for Application Servers", which is a foundation of JSR 237: Work Manager for Application Servers.

Implementation notes:

Note: The WorkManager is a feature of the Coherence Enterprise Edition and Coherence Grid Edition. It cannot be used in a Coherence Standard Edition cluster.

See Also:
WorkManager and Timers: Utilities for J2EE programmers
Timer and Work Manager for Application Servers

Nested Class Summary
protected static class WorkManager.AbstractWork
          Base class for Invocable tasks related to the WorkManager.
protected static class WorkManager.CollectMembershipInfo
          Invocable task used during handshake, which has to be scheduled immediately.
protected static class WorkManager.ReleaseWork
          Invocable task that forces a release for a wrapped Work object.
protected  class WorkManager.RemoteWorkManager
          RemoteWorkManager is a delegating WorkManager wrapper.
protected static class WorkManager.RequestStatus
          Invocable task that requests a status for a given Work.
protected static class WorkManager.ScheduleWork
          Invocable task that posts a wrapped Work object to a WorkManager queue.
protected static class WorkManager.ScheduleWorkRejectedException
          The ScheduleWorkRejectedException is a WrapperException that carries the information about the rejected Work.
protected static class WorkManager.SendFeedback
          Invocable task that delivers a WorkEvent to a WorkListener.
protected  class WorkManager.ServiceListener
          The member listener for the InvocataionService used by the WorkManager.
protected  class WorkManager.WorkHolder
          A holder for a Work object that serves as a communication intermediary between a client and a [remote] service.
protected  class WorkManager.WorkObserver
          The InvocationObserver for all posted work.
protected static class WorkManager.WorkStatus
          A WorkStatus object is used to communicate a work execution status back to the caller.

 

Field Summary
protected  InvocationObserver m_workObserver
          The ScheduleWork agent observer.

 

Fields inherited from interface commonj.work.WorkManager
IMMEDIATE, INDEFINITE

 

Constructor Summary
WorkManager(java.lang.String sManagerName, ConfigurableCacheFactory factory)
          Construct the WorkManager using the specified ConfigurableCacheFactory.
WorkManager(java.lang.String sManagerName, int cThreads)
          Construct the WorkManager.

 

Method Summary
 void cancelPostedWork()
          Cancel all posted work that has not yet completed.
protected  Member chooseServer()
          Choose a Member to run a next Work at.
protected  void collectMembershipInfo()
          Inform all the members about this node's role (client or server) and collect the information regarding other nodes' roles
 void disableServer(Member member)
          Remove a Member from a list of active server nodes and terminate all work posted to that server.
protected  int generateWorkId()
          Generate a unique (for this WorkManager) work id.
 java.util.Map getAcceptedWork()
          Return a catalog of accepted ScheduleWork tasks as known by the server side keyed by the origin Member where the value is a map of ScheduleWork tasks keyed by the WorkId.
 WorkManager.WorkStatus getCurrentResult(commonj.work.WorkItem item)
          Retrieve a current WorkStatus (partial result) for a given Work.
 java.util.Map getPostedWork()
          Return a catalog of WorkHolder objects for all posted Work as known by the client side keyed by the corresponding work id.
protected  WorkManager.WorkHolder getPostedWork(long lWorkId)
          Return a WorkHolder for a posted work with a given id.
 java.util.Set getServers()
          Return a set of Members that run the same Invocation service as this WorkManager in a "server" capacity.
 InvocationService getService()
          Return an InvocationService used by this WorkManager.
protected  void init(java.lang.String sManagerName, int cThreads, ConfigurableCacheFactory factory)
          Initialization.
protected  void initWork(WorkManager.ScheduleWork workAgent)
          Initialize the remote work agent.
protected  void installMemberListener()
          Install a MemberListener.
protected  void instantiateWorkObserver()
          Instantiate a Work observer.
 boolean isServer()
          Check whether or not this node operates in a "server" mode processing remote Work requests.
static void main(java.lang.String[] asArg)
          Entry point: start a stand-alone WorkManager (server) using the specified name and thread count.
protected  void processFeedback(WorkManager.SendFeedback workFeedback)
          Process a remote work feedback.
protected  WorkManager.WorkStatus processWork(WorkManager.ScheduleWork workAgent)
          Run the remote work agent.
protected  void releaseWork(WorkManager.ReleaseWork releaseAgent)
          Release the remote work agent.
protected  WorkManager.WorkHolder removePostedWork(long lWorkId)
          Remove a WorkHolder for a posted work with a given id.
protected  WorkManager.WorkStatus requestWorkStatus(WorkManager.RequestStatus requestAgent)
          Obtain current status of the specified Work.
 commonj.work.WorkItem schedule(commonj.work.Work work)
          Dispatches a Work asynchronously.
 commonj.work.WorkItem schedule(commonj.work.Work work, commonj.work.WorkListener workListener)
          Dispatches a Work asynchronously.
protected  commonj.work.WorkItem schedule(commonj.work.Work work, commonj.work.WorkListener workListener, Member member)
          Accepts a Work instance for processing at the specified Member.
protected  boolean updateWork(WorkManager.WorkStatus status)
          Update a WorkStatus for a work.
 boolean waitForAll(java.util.Collection collWorkItems, long lTimeoutMillis)
          Wait for all WorkItems in the collection to finish.
 java.util.Collection waitForAny(java.util.Collection collWorkItems, long lTimeoutMillis)
          Wait for any of the WorkItems in the collection to finish.

 

Field Detail

m_workObserver

protected InvocationObserver m_workObserver
The ScheduleWork agent observer.

Constructor Detail

WorkManager

public WorkManager(java.lang.String sManagerName,
                   int cThreads)
Construct the WorkManager.
Parameters:
sManagerName - a unique WorkManager name
cThreads - number of threads dedicated for Work processing; zero for WorkManagers in a "client-only" role

WorkManager

public WorkManager(java.lang.String sManagerName,
                   ConfigurableCacheFactory factory)
Construct the WorkManager using the specified ConfigurableCacheFactory.
Parameters:
sManagerName - a unique WorkManager name
factory - ConfigurableCacheFactory that will be used to instantiate the corresponding InvocationService using the factory.ensureService(sManagerName) call

Method Detail

init

protected void init(java.lang.String sManagerName,
                    int cThreads,
                    ConfigurableCacheFactory factory)
Initialization.
Parameters:
sManagerName - a unique WorkManager name
cThreads - number of threads
factory - ConfigurableCacheFactory to use

installMemberListener

protected void installMemberListener()
Install a MemberListener.

instantiateWorkObserver

protected void instantiateWorkObserver()
Instantiate a Work observer.

collectMembershipInfo

protected void collectMembershipInfo()
Inform all the members about this node's role (client or server) and collect the information regarding other nodes' roles

schedule

public commonj.work.WorkItem schedule(commonj.work.Work work)
                               throws commonj.work.WorkException
Dispatches a Work asynchronously. The work is dispatched and the method returns immediately.

At-most-once semantics are provided. If the server fails then the Work will not be executed on restart.

Specified by:
schedule in interface commonj.work.WorkManager
Parameters:
work - the Work to execute.
Returns:
the WorkItem representing the asynchronous work; since the Work must be serializable, a RemoteWorkItem is always returned
Throws:
commonj.work.WorkException - thrown if queuing this up results in an exception

schedule

public commonj.work.WorkItem schedule(commonj.work.Work work,
                                      commonj.work.WorkListener workListener)
                               throws commonj.work.WorkException
Dispatches a Work asynchronously. The work is dispatched and the method returns immediately.

At-most-once semantics are provided. If the server fails then the Work will not be executed on restart.

Specified by:
schedule in interface commonj.work.WorkManager
Parameters:
work - the Work to execute
workListener - an optional WorkListener which is used to inform the application of the progress of a Work
Returns:
the WorkItem representing the asynchronous work; since the Work must be serializable, a RemoteWorkItem is always returned
Throws:
commonj.work.WorkException - thrown if queuing this up results in an exception

schedule

protected commonj.work.WorkItem schedule(commonj.work.Work work,
                                         commonj.work.WorkListener workListener,
                                         Member member)
                                  throws commonj.work.WorkException
Accepts a Work instance for processing at the specified Member.
Parameters:
work - the Work to execute
workListener - an optional WorkListener which is used to inform the application of the progress of a Work
member - the Member to execute the Work at
Returns:
a WorkItem representing scheduled Work
Throws:
commonj.work.WorkException - thrown if queuing this up results in an exception

waitForAll

public boolean waitForAll(java.util.Collection collWorkItems,
                          long lTimeoutMillis)
                   throws java.lang.InterruptedException
Wait for all WorkItems in the collection to finish. If there are no WorkItems in the list then it returns immediately indicating a timeout. WorkItems from different WorkManagers can be placed in a single collection and waited on together.

The WorkItems collection should not be altered once submitted until the method returns.

Specified by:
waitForAll in interface commonj.work.WorkManager
Parameters:
collWorkItems - the Collection of WorkItem objects to wait for
lTimeoutMillis - the timout in milliseconds. If this value is zero then this method returns immediately
Returns:
true if all WorkItems have completed; false if the timeout has expired
Throws:
java.lang.InterruptedException - thrown if the wait is interrupted
java.lang.IllegalArgumentException - thrown if workItems is null, any of the objects in the collection are not WorkItems or the timeout is negative

waitForAny

public java.util.Collection waitForAny(java.util.Collection collWorkItems,
                                       long lTimeoutMillis)
                                throws java.lang.InterruptedException
Wait for any of the WorkItems in the collection to finish. If there are no WorkItems in the list then it returns immediately indicating a timeout. WorkItems from different WorkManagers can be placed in a single collection and waited on together.

The WorkItems collection should not be altered once submitted until the method returns.

Specified by:
waitForAny in interface commonj.work.WorkManager
Parameters:
collWorkItems - the Collection of WorkItem objects to wait for
lTimeoutMillis - the timeout in ms. If this value is zero then the method returns immediately, i.e. does not block
Returns:
the WorkItems that have completed or an empty Collection if its timeout expires before any finished
Throws:
java.lang.InterruptedException - thrown if the wait is interrupted
java.lang.IllegalArgumentException - thrown if workItems is null, any of the objects in the collection are not WorkItems or the timeout is negative

getCurrentResult

public WorkManager.WorkStatus getCurrentResult(commonj.work.WorkItem item)
Retrieve a current WorkStatus (partial result) for a given Work.

If the specified work has not been rejected or completed, this method will always communicate with a remote server to retrieve the current WorkStatus.

Parameters:
item - the WorkItem to retrieve the status for
Returns:
the corresponding WorkStatus object

getService

public InvocationService getService()
Return an InvocationService used by this WorkManager.
Returns:
an InvocationService used by this WorkManager

getServers

public java.util.Set getServers()
Return a set of Members that run the same Invocation service as this WorkManager in a "server" capacity.
Returns:
a set of server Members

getPostedWork

public java.util.Map getPostedWork()
Return a catalog of WorkHolder objects for all posted Work as known by the client side keyed by the corresponding work id.
Returns:
the Map of posted WorkHolder objects

getAcceptedWork

public java.util.Map getAcceptedWork()
Return a catalog of accepted ScheduleWork tasks as known by the server side keyed by the origin Member where the value is a map of ScheduleWork tasks keyed by the WorkId.
Returns:
a catalog of started ScheduleWork tasks

isServer

public boolean isServer()
Check whether or not this node operates in a "server" mode processing remote Work requests.
Returns:
true if this node operates in a "server" mode processing remote Work requests; false otherwise

disableServer

public void disableServer(Member member)
Remove a Member from a list of active server nodes and terminate all work posted to that server. This method could be called by the client code in response to exceptions (i.e. serialization problems) thrown by a server that deem further use of that server impossible.
Parameters:
member - the Member to remove from the server list

cancelPostedWork

public void cancelPostedWork()
Cancel all posted work that has not yet completed.

chooseServer

protected Member chooseServer()
Choose a Member to run a next Work at.

Called by client threads.

Returns:
the Member to run a next Work at

getPostedWork

protected WorkManager.WorkHolder getPostedWork(long lWorkId)
Return a WorkHolder for a posted work with a given id.
Parameters:
lWorkId - a work id
Returns:
a WorkHolder for a given work id

removePostedWork

protected WorkManager.WorkHolder removePostedWork(long lWorkId)
Remove a WorkHolder for a posted work with a given id.
Parameters:
lWorkId - a work id
Returns:
a WorkHolder for a given work id

generateWorkId

protected int generateWorkId()
Generate a unique (for this WorkManager) work id.

Called by client threads.

Returns:
the generated Work id

processFeedback

protected void processFeedback(WorkManager.SendFeedback workFeedback)
Process a remote work feedback.

Called by the InvocationService on the service thread at the client VM.

Parameters:
workFeedback - the feedback Work object

updateWork

protected boolean updateWork(WorkManager.WorkStatus status)
Update a WorkStatus for a work. If the corresponding WorkHolder has already been released, no action takes place.

Called by the InvocationService on a service thread of the client VM.

Parameters:
status - a WorkStatus object with an new status
Returns:
true iff the status was updated; false if the corresponding work has already been released

initWork

protected void initWork(WorkManager.ScheduleWork workAgent)
Initialize the remote work agent.

Called by the InvocationService on the service thread of the server member.

Parameters:
workAgent - the agent Work object

processWork

protected WorkManager.WorkStatus processWork(WorkManager.ScheduleWork workAgent)
Run the remote work agent.

Called by a daemon thread of the InvocationService on a server VM.

Parameters:
workAgent - the agent Work object
Returns:
the WorkStatus object

requestWorkStatus

protected WorkManager.WorkStatus requestWorkStatus(WorkManager.RequestStatus requestAgent)
Obtain current status of the specified Work.

Called by a daemon thread of the InvocationService on a server VM.

Parameters:
requestAgent - the request status
Returns:
the corresponding WorkStatus object

releaseWork

protected void releaseWork(WorkManager.ReleaseWork releaseAgent)
Release the remote work agent.

Called by a daemon thread of the InvocationService on a server VM.

Parameters:
releaseAgent - the release work

main

public static void main(java.lang.String[] asArg)
Entry point: start a stand-alone WorkManager (server) using the specified name and thread count.
 Example:
   java com.tangosol.coherence.commonj.WorkManager Manager 5
 

Skip navigation links

Oracle® Coherence Java API Reference
Release 3.6.1.0

E18814-01


Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.