org.gridgain.grid
Interface GridTaskSession

@Apache20LicenseCompatible
public interface GridTaskSession

Defines a distributed session for particular task execution.

Description

This interface defines a distributed session that exists for particular task execution. Task session is distributed across the parent task and all grid jobs spawned by it, so attributes set on a task or on a job can be viewed on other jobs. Correspondingly attributes set on any of the jobs can also be viewed on a task.

Session has 2 main features: attribute and checkpoint management. Both attributes and checkpoints can be used from task itself and from the jobs belonging to this task. Session attributes and checkpoints can be set from any task or job methods. Session attribute and checkpoint consistency is fault tolerant and is preserved whenever a job gets failed over to another node for execution. Whenever task execution ends, all checkpoints saved within session with GridCheckpointScope.SESSION_SCOPE scope will be removed from checkpoint storage. Checkpoints saved with GridCheckpointScope.GLOBAL_SCOPE will outlive the session and can be viewed by other tasks.

The sequence in which session attributes are set is consistent across the task and all job siblings within it. There will never be a case when one job sees attribute A before attribute B, and another job sees attribute B before A. Attribute order is identical across all session participants. Attribute order is also fault tolerant and is preserved whenever a job gets failed over to another node.

Connected Tasks

Note that apart from setting and getting session attributes, tasks or jobs can choose to wait for a certain attribute to be set using any of the waitForAttribute(...) methods. Tasks and jobs can also receive asynchronous notifications about a certain attribute being set through GridTaskSessionAttributeListener listener. Such feature allows grid jobs and tasks remain connected in order to synchronize their execution with each other and opens a solution for a whole new range of problems.

Imagine for example that you need to compress a very large file (let's say terabytes in size). To do that in grid environment you would split such file into multiple sections and assign every section to a remote job for execution. Every job would have to scan its section to look for repetition patterns. Once this scan is done by all jobs in parallel, jobs would need to synchronize their results with their siblings so compression would happen consistently across the whole file. This can be achieved by setting repetition patterns discovered by every job into the session. Once all patterns are synchronized, all jobs can proceed with compressing their designated file sections in parallel, taking into account repetition patterns found by all the jobs in the split. Grid task would then reduce (aggregate) all compressed sections into one compressed file. Without session attribute synchronization step this problem would be much harder to solve.

Session Injection

Session can be injected into a task or a job using IoC (dependency injection) by attaching @GridTaskSessionResource annotation to a field or a setter method inside of GridTask or GridJob implementations as follows:

 ...
 // This field will be injected with distributed task session.
 @GridTaskSessionResource
 private GridTaskSession ses = null;
 ...
 

or from a setter method:

 // This setter method will be automatically called by the system
 // to set grid task session.
 @GridTaskSessionResource
 void setSession(GridTaskSession ses) {
     this.ses = ses;
 }
 

Example

To see example on how to use GridTaskSession refer to HelloWorld Distributed Task Session Example on Wiki.



See Also:

Documentation
Email Support
Online Forums
Issue Tracking

Author: 2005-2008 Copyright © GridGain Systems. All Rights Reserved. ver. 2.0.3

	Nikita Ivanov, GridGain Systems nivanov@gridgain.com
	Dmitriy Setrakyan, GridGain Systems dsetrakyan@gridgain.com
	Alexander Magdenko, GridGain Systems amagdenko@gridgain.com
	Boris Suchodoev, GridGain Systems bsuchodoev@gridgain.com
	Denis Kharlamov, GridGain Systems dkharlamov@gridgain.com
	close

Method Summary

void	addAttributeListener(GridTaskSessionAttributeListener listener, boolean rewind) Add listener for the session attributes.
Serializable	getAttribute(Serializable key) Gets an attribute set by GridTaskSession.setAttribute(java.io.Serializable, java.io.Serializable) or GridTaskSession.setAttributes(Map) method.
Map<? extends Serializable,? extends Serializable>	getAttributes() Gets all attributes.
ClassLoader	getClassLoader() Gets class loader responsible for loading all classes within task.
long	getEndTime() Gets end of computation time for the task.
UUID	getId() Gets session ID of the task being executed.
GridJobSibling	getJobSibling(UUID jobId) Gets job sibling for a given ID.
Collection<GridJobSibling>	getJobSiblings() Gets a collection of all grid job siblings.
String	getTaskName() Gets task name of the task this session belongs to.
UUID	getTaskNodeId() Gets ID of the node on which task execution originated.
Serializable	loadCheckpoint(String key) Loads job's state previously saved via GridTaskSession.saveCheckpoint(String, Serializable, GridCheckpointScope, long) method from an underlying storage for a given key.
boolean	removeAttributeListener(GridTaskSessionAttributeListener listener) Removes given listener.
boolean	removeCheckpoint(String key) Removes previously saved job's state for a given key from an underlying storage.
void	saveCheckpoint(String key, Serializable state) Saves intermediate state of a job or task to a storage.
void	saveCheckpoint(String key, Serializable state, GridCheckpointScope scope, long timeout) Saves intermediate state of a job to a storage.
void	setAttribute(Serializable key, Serializable val) Sets session attributed.
void	setAttributes(Map<? extends Serializable,? extends Serializable> attrs) Sets task attributes.
Serializable	waitForAttribute(Serializable key) Waits for the specified attribute to be set.
Serializable	waitForAttribute(Serializable key, long timeout) Waits for the specified attribute to be set.
boolean	waitForAttribute(Serializable key, Serializable val) Waits for the specified attribute to be set or updated with given value.
boolean	waitForAttribute(Serializable key, Serializable val, long timeout) Waits for the specified attribute to be set or updated with given value.
Map<? extends Serializable,? extends Serializable>	waitForAttributes(Collection<? extends Serializable> keys) Waits for the specified attributes to be set.
Map<? extends Serializable,? extends Serializable>	waitForAttributes(Collection<? extends Serializable> keys, long timeout) Waits for the specified attributes to be set.
boolean	waitForAttributes(Map<? extends Serializable,? extends Serializable> attrs) Waits for the specified attributes to be set or updated with given values.
boolean	waitForAttributes(Map<? extends Serializable,? extends Serializable> attrs, long timeout) Waits for the specified attributes to be set or updated with given values.

Method Detail

getTaskName

String getTaskName()

Gets task name of the task this session belongs to.

Returns:

Task name of the task this session belongs to.

getTaskNodeId

UUID getTaskNodeId()

Gets ID of the node on which task execution originated.

Returns:

ID of the node on which task execution originated.

getEndTime

long getEndTime()

Gets end of computation time for the task. No job within the task will be allowed to execute passed this time.

Returns:

End of computation time for the task.

getId

UUID getId()

Gets session ID of the task being executed.

Returns:

Session ID of the task being executed.

getClassLoader

ClassLoader getClassLoader()

Gets class loader responsible for loading all classes within task.

Returns:

Class loader responsible for loading all classes within task.

getJobSiblings

Collection<GridJobSibling> getJobSiblings()

Gets a collection of all grid job siblings. Job siblings are grid jobs that are executing within the same task.

Returns:

Collection of grid job siblings executing within this task.

getJobSibling

GridJobSibling getJobSibling(UUID jobId)

Gets job sibling for a given ID.

Parameters:

jobId - Job ID to get the sibling for.

Returns:

Grid job sibling for a given ID.

setAttribute

void setAttribute(Serializable key,
                  @Nullable
                  Serializable val)
                  throws GridException

Sets session attributed. Note that task session is distributed and this attribute will be propagated to all other jobs within this task and task itself - i.e., to all accessors of this session. Other jobs then will be notified by GridTaskSessionAttributeListener callback than an attribute has changed.

This method is no-op if the session has finished.

Throws:

GridException - If sending of attribute message failed.

Parameters:

key - Attribute key.

val - Attribute value. Can be null.

getAttribute

Serializable getAttribute(Serializable key)

Gets an attribute set by GridTaskSession.setAttribute(java.io.Serializable, java.io.Serializable) or GridTaskSession.setAttributes(Map) method. Note that this attribute could have been set by another job on another node.

This method is no-op if the session has finished.

Parameters:

key - Attribute key.

Returns:

Gets task attribute for given name.

setAttributes

void setAttributes(Map<? extends Serializable,? extends Serializable> attrs)
                   throws GridException

Sets task attributes. This method exists so one distributed replication operation will take place for the whole group of attributes passed in. Use it for performance reasons, rather than GridTaskSession.setAttribute(Serializable,Serializable) method, whenever you need to set multiple attributes.

This method is no-op if the session has finished.

Throws:

GridException - If sending of attribute message failed.

Parameters:

attrs - Attributes to set.

getAttributes

Map<? extends Serializable,? extends Serializable> getAttributes()

Gets all attributes.

Returns:

All session attributes.

addAttributeListener

void addAttributeListener(GridTaskSessionAttributeListener listener,
                          boolean rewind)

Add listener for the session attributes.

Parameters:

listener - Listener to add.

rewind - true value will result in calling given listener for all already received attributes, while false value will result only in new attribute notification. Settings rewind to true allows for a simple mechanism that prevents the loss of notifications for the attributes that were previously received or received while this method was executing.

removeAttributeListener

boolean removeAttributeListener(GridTaskSessionAttributeListener listener)

Removes given listener.

Parameters:

listener - Listener to remove.

Returns:

true if listener was removed, false otherwise.

waitForAttribute

Serializable waitForAttribute(Serializable key)
                              throws InterruptedException

Waits for the specified attribute to be set. If this attribute is already in session this method will return immediately.

Throws:

InterruptedException - Thrown if wait was interrupted.

Parameters:

key - Attribute key to wait for.

Returns:

Value of newly set attribute.

waitForAttribute

boolean waitForAttribute(Serializable key,
                         @Nullable
                         Serializable val)
                         throws InterruptedException

Waits for the specified attribute to be set or updated with given value. Note that this method will block even if attribute is set for as long as its value is not equal to the specified.

Throws:

InterruptedException - Thrown if wait was interrupted.

Parameters:

key - Attribute key to wait for.

val - Attribute value to wait for. Can be null.

Returns:

Whether or not key/value pair has been received.

waitForAttribute

Serializable waitForAttribute(Serializable key,
                              long timeout)
                              throws InterruptedException

Waits for the specified attribute to be set. If this attribute is already in session this method will return immediately.

Throws:

InterruptedException - Thrown if wait was interrupted.

Parameters:

key - Attribute key to wait for.

timeout - Timeout in milliseconds to wait for. 0 means indefinite wait.

Returns:

Value of newly set attribute.

waitForAttribute

boolean waitForAttribute(Serializable key,
                         @Nullable
                         Serializable val,
                         long timeout)
                         throws InterruptedException

Waits for the specified attribute to be set or updated with given value. Note that this method will block even if attribute is set for as long as its value is not equal to the specified.

Throws:

InterruptedException - Thrown if wait was interrupted.

Parameters:

key - Attribute key to wait for.

val - Attribute value to wait for. Can be null.

timeout - Timeout in milliseconds to wait for. 0 means indefinite wait.

Returns:

Whether or not specified key/value pair has been set.

waitForAttributes

Map<? extends Serializable,? extends Serializable> waitForAttributes(Collection<? extends Serializable> keys)
                                                                     throws InterruptedException

Waits for the specified attributes to be set. If these attributes are already in session this method will return immediately.

Throws:

InterruptedException - Thrown if wait was interrupted.

Parameters:

keys - Attribute keys to wait for.

Returns:

Attribute values mapped by their keys.

waitForAttributes

boolean waitForAttributes(Map<? extends Serializable,? extends Serializable> attrs)
                          throws InterruptedException

Waits for the specified attributes to be set or updated with given values. Note that this method will block even if attributes are set for as long as their values are not equal to the specified.

Throws:

InterruptedException - Thrown if wait was interrupted.

Parameters:

attrs - Key/value pairs to wait for.

Returns:

Whether or not key/value pairs have been set.

waitForAttributes

Map<? extends Serializable,? extends Serializable> waitForAttributes(Collection<? extends Serializable> keys,
                                                                     long timeout)
                                                                     throws InterruptedException

Waits for the specified attributes to be set. If these attributes are already in session this method will return immediately.

Throws:

InterruptedException - Thrown if wait was interrupted.

Parameters:

keys - Attribute keys to wait for.

timeout - Timeout in milliseconds to wait for. 0 means indefinite wait.

Returns:

Attribute values mapped by their keys.

waitForAttributes

boolean waitForAttributes(Map<? extends Serializable,? extends Serializable> attrs,
                          long timeout)
                          throws InterruptedException

Waits for the specified attributes to be set or updated with given values. Note that this method will block even if attributes are set for as long as their values are not equal to the specified.

Throws:

InterruptedException - Thrown if wait was interrupted.

Parameters:

attrs - Key/value pairs to wait for.

timeout - Timeout in milliseconds to wait for. 0 means indefinite wait.

Returns:

Whether or not key/value pair has been set.

saveCheckpoint

void saveCheckpoint(String key,
                    Serializable state)
                    throws GridException

Saves intermediate state of a job or task to a storage. The storage implementation is defined by GridCheckpointSpi implementation used.

Long running jobs may decide to store intermediate state to protect themselves from failures. This way whenever a job fails over to another node, it can load its previously saved state via GridTaskSession.loadCheckpoint(String) method and continue with execution.

This method defaults checkpoint scope to GridCheckpointScope.SESSION_SCOPE and implementation will automatically remove the checkpoint at the end of the session. It is analogous to calling saveCheckpoint(String, Serializable, GridCheckpointScope.SESSION_SCOPE, 0.

Throws:

GridException - If failed to save intermediate job state.

Parameters:

key - Key to be used to load this checkpoint in future.

state - Intermediate job state to save.

See Also:

GridTaskSession.loadCheckpoint(String), GridTaskSession.removeCheckpoint(String), GridCheckpointSpi

saveCheckpoint

void saveCheckpoint(String key,
                    Serializable state,
                    GridCheckpointScope scope,
                    long timeout)
                    throws GridException

Saves intermediate state of a job to a storage. The storage implementation is defined by GridCheckpointSpi implementation used.

Long running jobs may decide to store intermediate state to protect themselves from failures. This way whenever a job fails over to another node, it can load its previously saved state via GridTaskSession.loadCheckpoint(String) method and continue with execution.

The life time of the checkpoint is determined by its timeout and scope. If GridCheckpointScope.GLOBAL_SCOPE is used, the checkpoint will outlive its session, and can only be removed by calling GridCheckpointSpi.removeCheckpoint(String) from Grid or another task or job.

Throws:

GridException - If failed to save intermediate job state.

Parameters:

key - Key to be used to load this checkpoint in future.

state - Intermediate job state to save.

scope - Checkpoint scope. If equal to GridCheckpointScope.SESSION_SCOPE, then state will automatically be removed at the end of task execution. Otherwise, if scope is GridCheckpointScope.GLOBAL_SCOPE then state will outlive its session and can be removed by calling removeCheckpoint(String) from another task or whenever timeout expires.

timeout - Maximum time this state should be kept by the underlying storage.

See Also:

GridTaskSession.loadCheckpoint(String), GridTaskSession.removeCheckpoint(String), GridCheckpointSpi

loadCheckpoint

Serializable loadCheckpoint(String key)
                            throws GridException

Loads job's state previously saved via GridTaskSession.saveCheckpoint(String, Serializable, GridCheckpointScope, long) method from an underlying storage for a given key. If state was not previously saved, then null will be returned. The storage implementation is defined by GridCheckpointSpi implementation used.

Long running jobs may decide to store intermediate state to protect themselves from failures. This way whenever a job starts, it can load its previously saved state and continue with execution.

Throws:

GridException - If failed to load job state.

Parameters:

key - Key for intermediate job state to load.

Returns:

Previously saved state or null if no state was found for a given key.

See Also:

GridTaskSession.loadCheckpoint(String), GridTaskSession.removeCheckpoint(String), GridCheckpointSpi

removeCheckpoint

boolean removeCheckpoint(String key)
                         throws GridException

Removes previously saved job's state for a given key from an underlying storage. The storage implementation is defined by GridCheckpointSpi implementation used.

Long running jobs may decide to store intermediate state to protect themselves from failures. This way whenever a job starts, it can load its previously saved state and continue with execution.

Throws:

GridException - If failed to remove job state.

Parameters:

key - Key for intermediate job state to load.

Returns:

true if job state was removed, false if state was not found.

See Also:

GridTaskSession.loadCheckpoint(String), GridTaskSession.removeCheckpoint(String), GridCheckpointSpi