uws.job
Class JobList<J extends AbstractJob>

java.lang.Object
  uws.job.SerializableUWSObject
      uws.job.JobList<J>

All Implemented Interfaces:

java.io.Serializable, java.lang.Iterable<J>

public class JobList<J extends AbstractJob>
extends SerializableUWSObject
implements java.lang.Iterable<J>

General description

An instance of this class lets listing UWS jobs (possible actions: get, add and remove).

Note:This list implements the interface Iterable which lets you iterating more easily among the jobs.

Jobs list by user

So that avoiding any user to interact on jobs of anybody else, it is possible (and strongly encouraged) to get the list of jobs only of the current user. For that you must use the function getJobs(String) with a owner ID.

At each request sent to any instance of AbstractUWS the function UserIdentifier.extractUserId(uws.service.UWSUrl, javax.servlet.http.HttpServletRequest) may extract the user ID. Thus the action GetJobList may know who is the current user. If the extracted owner ID is different from null only the jobs of the current user will be returned.
However you need to find a way to identify for each UWS request the current user and then to override correctly the function UserIdentifier.extractUserId(uws.service.UWSUrl, javax.servlet.http.HttpServletRequest).

Note: There are two special values for a owner ID:

• NULL: it is the only way to mean "all users"
• AbstractJob.ANONYMOUS_OWNER: the default value of an owner ID. It is set by default to a job if no owner is specified.

Searching in a jobs list

• getJobs() or iterator(): to get all the jobs of this jobs list.
• getJob(String): to get the job that has the given jobID.
• searchJobs(String): to search all the jobs that have the given runID.
• getJobs(String): to get the jobs of the specified user.

Get the users list

If you are interested in (probably for some statistics or for an administrator) you can ask the list of users who have at least one job in this jobs list (getUsers()) and known how many they are (getNbUsers()).

Automatic job destruction

A job has a field - destructionTime - which indicates the date at which it must destroyed. Remember that destroying a job consists in removing it from its jobs list and then clearing all its resources (result files, threads, ...). This task is done by an "instance" of the interface DestructionManager. By default a jobs list has a default implementation of this interface: DefaultDestructionManager. However when added in a UWS, the jobs list inherits the destruction manager of its UWS. Thus all jobs list of a UWS have the same destruction manager.

To use a custom destruction manager, you can use the method setDestructionManager(DestructionManager) if the jobs list is not managed by a UWS or AbstractUWS.setDestructionManager(DestructionManager) otherwise.

Version:

02/2011

Author:

Grégory Mantelet (CDS)

See Also:

AbstractJob, Serialized Form

Field Summary

protected java.util.Map<java.lang.String,J>	jobsList [Required] List of jobs.
protected java.util.Map<java.lang.String,java.util.Map<java.lang.String,J>>	ownerJobs [Required] List of jobs per ownerId/userId.

Constructor Summary

JobList(java.lang.String jobListName)
Builds a jobs list with its name.

Method Summary

java.lang.String	addNewJob(J j) Add the given job to the list except if a job with the same jobID already exists.
void	clear() Destroys all jobs of this list.
void	clear(java.lang.String ownerId) Destroys all jobs owned by the specified user.
boolean	destroyJob(java.lang.String jobId) Removes the job from the list and deletes all its attached resources (AbstractJob.clearResources().
DestructionManager	getDestructionManager() Gets the used destruction manager.
J	getJob(java.lang.String jobID) Gets the job whose the ID is given in parameter.
java.util.Iterator<J>	getJobs() Gets an iterator on the whole jobs list.
java.util.Iterator<J>	getJobs(java.lang.String ownerId) Gets an iterator on the jobs list of the specified user.
java.lang.String	getName() Gets the name of this jobs list.
int	getNbJobs() Gets the number of jobs into this list.
int	getNbJobs(java.lang.String ownerId) Gets the number of jobs owned by the specified user into this list.
int	getNbUsers() Gets the number of all users that have at least one job in this list.
UWSUrl	getUrl() Gets the UWS URL of this jobs list in function of its UWS.
java.util.Iterator<java.lang.String>	getUsers() Gets all users that own at least one job in this list.
AbstractUWS	getUWS() Gets the UWS which manages this jobs list.
java.util.Iterator<J>	iterator() Gets an iterator on the jobs list.
void	removeAll() Removes all jobs of this list.
J	removeJob(java.lang.String jobId) Lets removing (NOT DESTROYING) the specified job from this jobs list.
java.util.ArrayList<J>	searchJobs(java.lang.String runID) Gets all job whose the runID is equals (not case sensitive) to the given runID.
java.lang.String	serialize(UWSSerializer serializer, java.lang.String ownerId) Serializes the whole object considering the given owner ID (supposed to be the ID of the current user) and thanks to the given serializer.
void	setDestructionManager(DestructionManager newManager) Sets the destruction manager to use.
void	setUWS(AbstractUWS newUws) Sets the UWS which aims to manage this jobs list.
void	sync() This method is called by its UWS just after a de-serialization of the whole UWS (this jobs list included).
java.lang.String	toString()
void	updateDestruction(J job) Lets notifying the destruction manager of a possible modification of the destructionTime of the given job.

Methods inherited from class uws.job.SerializableUWSObject

serialize, serialize, serialize

Methods inherited from class java.lang.Object

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

Field Detail

jobsList

protected final java.util.Map<java.lang.String,J extends AbstractJob> jobsList

[Required] List of jobs.

ownerJobs

protected final java.util.Map<java.lang.String,java.util.Map<java.lang.String,J extends AbstractJob>> ownerJobs

[Required] List of jobs per ownerId/userId.

Constructor Detail

JobList

public JobList(java.lang.String jobListName)
        throws UWSException

Builds a jobs list with its name.

Parameters:

jobListName - The jobs list name.

Throws:

UWSException - If the given name is null or empty.

Method Detail

sync

public final void sync()

This method is called by its UWS just after a de-serialization of the whole UWS (this jobs list included). It re-initializes all the jobs of this jobs list.

If a job can not be re-initialized (AbstractJob.sync() returns false) it is destroyed and then removed from this jobs list.

See Also:

DestructionManager.refresh(), AbstractJob.sync(), destroyJob(String)

getUWS

public final AbstractUWS getUWS()

Gets the UWS which manages this jobs list.

Returns:

Its UWS (may be NULL).

setUWS

public final void setUWS(AbstractUWS newUws)

Sets the UWS which aims to manage this jobs list.

Parameters:

newUws - Its new UWS (may be null).

getDestructionManager

public final DestructionManager getDestructionManager()

Gets the used destruction manager.

Note: Remember that the destruction manager lets destroying automatically jobs only when their destructionTime has been reached.

Returns:

Its destruction manager (may be null).

setDestructionManager

public final void setDestructionManager(DestructionManager newManager)

Sets the destruction manager to use. All the jobs are removed from the former destruction manager and then added in the new one.

Note: Remember that the destruction manager lets destroying automatically jobs only when their destructionTime has been reached.

Parameters:

newManager - Its new destruction manager (may be null).

See Also:

DestructionManager.remove(AbstractJob), DestructionManager.update(AbstractJob)

getUrl

public UWSUrl getUrl()

Gets the UWS URL of this jobs list in function of its UWS.

Returns:

Its corresponding UWSUrl.

See Also:

AbstractUWS.getUrlInterpreter(), UWSUrl.listJobs(String)

getName

public final java.lang.String getName()

Gets the name of this jobs list.

Returns:

JobList name.

getJob

public final J getJob(java.lang.String jobID)

Gets the job whose the ID is given in parameter.

Parameters:

jobID - The ID of the job to get.

Returns:

The requested job or null if there is no job with the given ID.

getJobs

public final java.util.Iterator<J> getJobs()

Gets an iterator on the whole jobs list.

Returns:

All jobs of this list.

See Also:

iterator()

getJobs

public final java.util.Iterator<J> getJobs(java.lang.String ownerId)

Gets an iterator on the jobs list of the specified user.

Parameters:

ownerId - The ID of the owner/user (may be null).

Returns:

An iterator on all jobs which have been created by the specified owner/user or a NullIterator if the specified owner/user has no job or an iterator on all the jobs if ownerId is null.

iterator

public final java.util.Iterator<J> iterator()

Gets an iterator on the jobs list.

Specified by:

iterator in interface java.lang.Iterable<J extends AbstractJob>

See Also:

Iterable.iterator()

getNbJobs

public final int getNbJobs()

Gets the number of jobs into this list.

Returns:

Number of jobs.

getNbJobs

public final int getNbJobs(java.lang.String ownerId)

Gets the number of jobs owned by the specified user into this list.

Parameters:

ownerId - The ID of the owner/user (may be null).

Returns:

Number of jobs that the specified owner/user has, or the number of all jobs if ownerId is null.

getUsers

public final java.util.Iterator<java.lang.String> getUsers()

Gets all users that own at least one job in this list.

Returns:

An iterator on owner IDs.

getNbUsers

public final int getNbUsers()

Gets the number of all users that have at least one job in this list.

Returns:

The number of job owners.

searchJobs

public final java.util.ArrayList<J> searchJobs(java.lang.String runID)

Gets all job whose the runID is equals (not case sensitive) to the given runID.

Parameters:

runID - The runID of jobs to search.

Returns:

All the corresponding jobs.

addNewJob

public java.lang.String addNewJob(J j)
                           throws UWSException

Add the given job to the list except if a job with the same jobID already exists.

Parameters:

j - The job to add.

Returns:

The JobID if the job has been successfully added, null otherwise.

Throws:

UWSException

See Also:

AbstractJob.loadAdditionalParams(), AbstractJob.setJobList(JobList), DestructionManager.update(AbstractJob), AbstractJob.applyPhaseParam()

updateDestruction

public final void updateDestruction(J job)

Lets notifying the destruction manager of a possible modification of the destructionTime of the given job.

Note: This method does nothing if this jobs list has no destruction manager, if the given job is NULL or if this jobs list does not know the given job.

Parameters:

job - The job whose the destructionTime may have been modified.

See Also:

DestructionManager.update(AbstractJob)

removeJob

public J removeJob(java.lang.String jobId)

Lets removing (NOT DESTROYING) the specified job from this jobs list.

Parameters:

jobId - The ID of the job to remove.

Returns:

The removed job or null if there is no job with the given jobID.

See Also:

AbstractJob.setJobList(JobList), DestructionManager.remove(AbstractJob)

destroyJob

public boolean destroyJob(java.lang.String jobId)

Removes the job from the list and deletes all its attached resources (AbstractJob.clearResources().

Parameters:

jobId - The ID of the job to destroy.

Returns:

true if it has been successfully destroyed, false otherwise.

See Also:

removeJob(String), AbstractJob.clearResources()

removeAll

public void removeAll()

Removes all jobs of this list.

See Also:

removeJob(String)

clear

public void clear()

Destroys all jobs of this list.

See Also:

destroyJob(String)

clear

public void clear(java.lang.String ownerId)

Destroys all jobs owned by the specified user.

Parameters:

ownerId - The ID of the owner/user.

See Also:

clear(), destroyJob(String)

serialize

public java.lang.String serialize(UWSSerializer serializer,
                                  java.lang.String ownerId)
                           throws UWSException

Description copied from class: SerializableUWSObject

Serializes the whole object considering the given owner ID (supposed to be the ID of the current user) and thanks to the given serializer.

Specified by:

serialize in class SerializableUWSObject

Parameters:

serializer - The serializer to use.

ownerId - The ID of the current user.

Returns:

The serialized representation of this object.

Throws:

UWSException - If there is an error during the serialization.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object