JobList

java.lang.Object
- uws.job.SerializableUWSObject
- - uws.job.JobList

All Implemented Interfaces:

java.io.Serializable, java.lang.Iterable<UWSJob>
```
public class JobList
extends SerializableUWSObject
implements java.lang.Iterable<UWSJob>
```
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(JobOwner) with a owner ID.

At each request sent to any instance of UWSService 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.

WARNING: 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: If no owner is specified (NULL value), all jobs are concerned by the function action.

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(JobOwner): 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()).

Execution management

The execution of the jobs of this jobs list is managed by an implementation of ExecutionManager. DefaultExecutionManager is used by default, but you can easily set your own implementation of this interface, either at the job list creation or with setExecutionManager(ExecutionManager).

Automatic job destruction

A job has a field - destructionTime - which indicates the date at which it must be destroyed. Remember that destroying a job consists in removing it from its jobs list and then clearing all its resources (result and input 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.

WARNING: 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).

Archiving and Job destruction policy

Since UWS-1.1, it is possible to archive a job. The behavior described in the UWS-1.1 document is that a job goes into the ARCHIVED phase when its destruction date is reached. This behavior is a destruction alternative introduced in order to keep only the metadata part of a job whenever it is automatically destroyed by the UWS service. It is not imposed in the UWS-1.1 document ; it is just a description of the ARCHIVED phase.

The UWS Library proposes 2 other strategies: always delete a job (whatever its destruction date is reached or not ; default behavior in UWS 1.0), or always archive first. Thus, it is now possible to specify on a JobList instance which policy should be used. This can be done thanks to the function setDestructionPolicy(JobDestructionPolicy) and with the enum class JobDestructionPolicy.

By default, the default behavior proposed by UWS 1.1 is set: JobDestructionPolicy.ALWAYS_DELETE, mainly for backward compatibility with former library versions but also to prevent using more and more memory for ARCHIVED jobs without the explicit approval from the UWS service manager.

Note: An archived job can be destroyed definitely by calling again destroyJob(String) (i.e. DELETE on {jobs}/{job-id} or POST ACTION=DELETE on {jobs}/{job-id}).
Version:

4.3 (10/2017)

Author:

Grégory Mantelet (CDS;ARI)

See Also:

UWSJob, Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`static JobDestructionPolicy`	`DEFAULT_JOB_DESTRUCTION_POLICY` Default policy applied to a job list when a job destruction is asked.
`protected java.util.Map<java.lang.String,UWSJob>`	`jobsList` [Required] List of jobs.
`protected java.util.Map<JobOwner,java.util.Map<java.lang.String,UWSJob>>`	`ownerJobs` [Required] List of jobs per owner.

Constructor Summary

Constructors
Constructor and Description
`JobList(java.lang.String jobListName)` Builds a jobs list with its name.
`JobList(java.lang.String jobListName, DestructionManager destructionManager)` Builds a jobs list with its name and the destruction manager to use.
`JobList(java.lang.String jobListName, ExecutionManager executionManager)` Builds a jobs list with its name and the job list manager.
`JobList(java.lang.String jobListName, ExecutionManager executionManager, DestructionManager destructionManager)` Builds a jobs list with its name, the job list manager and the destruction manager.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`java.lang.String`	`addNewJob(UWSJob j)` Add the given job to the list except if a job with the same jobID already exists.
`boolean`	`archiveJob(java.lang.String jobId)` Archive the specified job.
`boolean`	`archiveJob(java.lang.String jobId, JobOwner user)` Archive the specified job if the given user is allowed to.
`void`	`clear()` Destroys all jobs of this list.
`void`	`clear(JobOwner owner)` 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 (`UWSJob.clearResources()`.
`boolean`	`destroyJob(java.lang.String jobId, JobOwner user)` Removes the job from the list and deletes all its attached resources (`UWSJob.clearResources()`.
`JobDestructionPolicy`	`getDestroyPolicy()` Tell how this job list behaves when a job destruction is asked.
`DestructionManager`	`getDestructionManager()` Gets the used destruction manager.
`ExecutionManager`	`getExecutionManager()` Gets the used execution manager.
`UWSJob`	`getJob(java.lang.String jobID)` Gets the job whose the ID is given in parameter.
`UWSJob`	`getJob(java.lang.String jobID, JobOwner user)` Gets the job whose the ID is given in parameter ONLY IF it is the one of the specified user OR IF the specified job is owned by an anonymous user.
`java.util.Iterator<UWSJob>`	`getJobs()` Gets an iterator on the whole jobs list.
`java.util.Iterator<UWSJob>`	`getJobs(JobOwner user)` Gets an iterator on the jobs list of the specified user.
`UWSLog`	`getLogger()` Gets the logger of its UWS, or a default one if the UWS is unknown.
`java.lang.String`	`getName()` Gets the name of this jobs list.
`int`	`getNbJobs()` Gets the number of jobs into this list.
`int`	`getNbJobs(JobOwner user)` Gets the number of jobs owned by the given 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<JobOwner>`	`getUsers()` Gets all users that own at least one job in this list.
`UWS`	`getUWS()` Gets the UWS which manages this jobs list.
`java.util.Iterator<UWSJob>`	`iterator()` Gets an iterator on the jobs list.
`protected UWSJob`	`removeJob(java.lang.String jobId)` Lets removing (NOT DESTROYING) the specified job from this jobs list.
`java.util.List<UWSJob>`	`searchJobs(java.lang.String runID)` Gets all job whose the runID is equals (not case sensitive) to the given runID.
`void`	`serialize(javax.servlet.ServletOutputStream output, UWSSerializer serializer, JobOwner owner, JobListRefiner listRefiner)` Serializes the while object in the given output stream, considering the given owner, the given job filters and thanks to the given serializer.
`java.lang.String`	`serialize(UWSSerializer serializer, JobOwner user)` Serializes the whole object considering the given owner (supposed to be the current user) and thanks to the given serializer.
`void`	`setDestructionManager(DestructionManager newManager)` Sets the destruction manager to use.
`void`	`setDestructionPolicy(JobDestructionPolicy destroyPolicy)` Set how this job list must behave when a job destruction is asked.
`void`	`setExecutionManager(ExecutionManager manager)` Sets the execution manager to use.
`void`	`setUWS(UWS newUws)` Sets the UWS which aims to manage this jobs list.
`java.lang.String`	`toString()`
`void`	`updateDestruction(UWSJob 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

Methods inherited from interface java.lang.Iterable
forEach, spliterator

- Field Detail
  - DEFAULT_JOB_DESTRUCTION_POLICY
```
public static final JobDestructionPolicy DEFAULT_JOB_DESTRUCTION_POLICY
```
    Default policy applied to a job list when a job destruction is asked.
    
    Since:
    
    4.3
  - jobsList
```
protected final java.util.Map<java.lang.String,UWSJob> jobsList
```
    [Required] List of jobs.
  - ownerJobs
```
protected final java.util.Map<JobOwner,java.util.Map<java.lang.String,UWSJob>> ownerJobs
```
    [Required] List of jobs per owner.
- Constructor Detail
  - JobList
```
public JobList(java.lang.String jobListName)
        throws java.lang.NullPointerException
```
    Builds a jobs list with its name.
    
    Parameters:
    
    jobListName - The jobs list name.
    
    Throws:
    
    java.lang.NullPointerException - If the given job list name is NULL.
    
    See Also:
    
    JobList(String, ExecutionManager)
  - JobList
```
public JobList(java.lang.String jobListName,
               ExecutionManager executionManager)
        throws java.lang.NullPointerException
```
    Builds a jobs list with its name and the job list manager.
    
    Parameters:
    
    jobListName - The jobs list name.
    
    executionManager - The object which will manage the execution of all jobs of this list.
    
    Throws:
    
    java.lang.NullPointerException - If the given job list name is NULL or empty or if no execution manager is provided.
  - JobList
```
public JobList(java.lang.String jobListName,
               DestructionManager destructionManager)
        throws java.lang.NullPointerException
```
    Builds a jobs list with its name and the destruction manager to use.
    
    Parameters:
    
    jobListName - The jobs list name.
    
    destructionManager - The object which manages the automatic destruction of jobs when they have reached their destruction date.
    
    Throws:
    
    java.lang.NullPointerException - If the given job list name is NULL or empty or if no destruction manager is provided.
  - JobList
```
public JobList(java.lang.String jobListName,
               ExecutionManager executionManager,
               DestructionManager destructionManager)
        throws java.lang.NullPointerException
```
    Builds a jobs list with its name, the job list manager and the destruction manager.
    
    Parameters:
    
    jobListName - The jobs list name.
    
    executionManager - The object which will manage the execution of all jobs of this list.
    
    destructionManager - The object which manages the automatic destruction of jobs when they have reached their destruction date.
    
    Throws:
    
    java.lang.NullPointerException - If the given job list name is NULL or empty or if no execution manager and destruction manager are provided.
- Method Detail
  - getUWS
```
public final UWS getUWS()
```
    Gets the UWS which manages this jobs list.
    
    Returns:
    
    Its UWS or null if this jobs list is not yet part of a specific UWS).
  - setUWS
```
public final void setUWS(UWS newUws)
                  throws java.lang.IllegalStateException
```
    Sets the UWS which aims to manage this jobs list.
    Note: The UWS association can be changed ONLY IF the jobs list is not yet associated with a UWS OR IF it is empty.
    
    Parameters:
    
    newUws - Its new UWS. If NULL, nothing is done!
    
    Throws:
    
    java.lang.IllegalStateException - If this jobs list is already associated with a UWS (different from the given one) and contains some jobs.
  - getLogger
```
public UWSLog getLogger()
```
    Gets the logger of its UWS, or a default one if the UWS is unknown.
    
    Returns:
    
    A logger.
    
    See Also:
    
    getUWS(), UWS.getLogger(), UWSToolBox.getDefaultLogger()
  - 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.
  - 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 (MUST be different from null otherwise nothing is done).
    
    See Also:
    
    DestructionManager.remove(UWSJob), DestructionManager.update(UWSJob)
  - getExecutionManager
```
public final ExecutionManager getExecutionManager()
```
    Gets the used execution manager.
    
    Returns:
    
    The used execution manager.
  - setExecutionManager
```
public final void setExecutionManager(ExecutionManager manager)
```
    Sets the execution manager to use.
    Note: All jobs managed by the old execution manager are removed from it and added to the new manager.
    
    Parameters:
    
    manager - The execution manager to use (MUST be different from null otherwise nothing is done).
    
    See Also:
    
    ExecutionManager.remove(UWSJob), ExecutionManager.execute(UWSJob)
  - getDestroyPolicy
```
public final JobDestructionPolicy getDestroyPolicy()
```
    Tell how this job list behaves when a job destruction is asked.
    
    Returns:
    
    The job destruction policy of this job list.
    
    Since:
    
    4.3
  - setDestructionPolicy
```
public final void setDestructionPolicy(JobDestructionPolicy destroyPolicy)
```
    Set how this job list must behave when a job destruction is asked.
    
    Parameters:
    
    destroyPolicy - The job destruction policy to set. If NULL, the default policy (i.e. DEFAULT_JOB_DESTRUCTION_POLICY) will be set.
    
    Since:
    
    4.3
  - getUrl
```
public UWSUrl getUrl()
```
    Gets the UWS URL of this jobs list in function of its UWS.
    
    Returns:
    
    Its corresponding UWSUrl.
    
    See Also:
    
    UWSService.getUrlInterpreter(), UWSUrl.listJobs(String)
  - getName
```
public final java.lang.String getName()
```
    Gets the name of this jobs list.
    
    Returns:
    
    JobList name.
  - getJob
```
public final UWSJob 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.
  - getJob
```
public UWSJob getJob(java.lang.String jobID,
                     JobOwner user)
              throws UWSException
```
    Gets the job whose the ID is given in parameter ONLY IF it is the one of the specified user OR IF the specified job is owned by an anonymous user.
    
    Parameters:
    
    jobID - ID of the job to get.
    
    user - The user who asks this job (null means no particular owner => cf getJob(String)).
    
    Returns:
    
    The requested job or null if there is no job with the given ID or if the user is not allowed to get the given job.
    
    Throws:
    
    UWSException - If the given user is not allowed to read the content of this jobs list or to read the specified job.
  - getJobs
```
public final java.util.Iterator<UWSJob> getJobs()
```
    Gets an iterator on the whole jobs list.
    
    Returns:
    
    All jobs of this list.
    
    See Also:
    
    iterator()
  - getJobs
```
public java.util.Iterator<UWSJob> getJobs(JobOwner user)
```
    Gets an iterator on the jobs list of the specified user.
    
    Parameters:
    
    user - The owner/user who asks for this operation (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<UWSJob> iterator()
```
    Gets an iterator on the jobs list.
    
    Specified by:
    
    iterator in interface java.lang.Iterable<UWSJob>
    
    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(JobOwner user)
```
    Gets the number of jobs owned by the given user into this list.
    
    Parameters:
    
    user - The owner/user (may be null).
    
    Returns:
    
    Number of jobs that the given owner/user has, or the number of all jobs if user is null.
  - getUsers
```
public final java.util.Iterator<JobOwner> getUsers()
```
    Gets all users that own at least one job in this list.
    
    Returns:
    
    An iterator on owners.
  - 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.List<UWSJob> 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(UWSJob j)
                           throws UWSException
```
    Add the given job to the list except if a job with the same jobID already exists. The jobs list of the new job's owner is always updated if the job has been added.
    
    Parameters:
    
    j - The job to add.
    
    Returns:
    
    The JobID if the job has been successfully added, null otherwise.
    
    Throws:
    
    UWSException - If the owner of the given job is not allowed to add any job into this jobs list.
    
    See Also:
    
    UWSJob.setJobList(JobList), UWSService.getBackupManager(), UWSBackupManager.saveOwner(JobOwner), DestructionManager.update(UWSJob), UWSJob.applyPhaseParam(JobOwner)
  - archiveJob
```
public boolean archiveJob(java.lang.String jobId)
```
    Archive the specified job.
    Resources (i.e. threads and files) of an archived jobs are destroyed. Only the description is still available. The job can not be executed any more. It is visible in the job list ONLY IF a filter on the ARCHIVED phase is set.
    
    Parameters:
    
    jobId - The ID of the job to archive.
    
    Returns:
    
    true if it has been successfully archived, false otherwise.
    
    Since:
    
    4.3
    
    See Also:
    
    UWSJob.archive()
  - archiveJob
```
public boolean archiveJob(java.lang.String jobId,
                          JobOwner user)
                   throws UWSException
```
    Archive the specified job if the given user is allowed to.
    Resources (i.e. threads and files) of an archived jobs are destroyed. Only the description is still available. The job can not be executed any more. It is visible in the job list ONLY IF a filter on the ARCHIVED phase is set.
    
    Parameters:
    
    jobId - The ID of the job to archive.
    
    user - The user who asks to archive the specified job.
    
    Returns:
    
    true if it has been successfully archived, false otherwise.
    
    Throws:
    
    UWSException - If the given user is not allowed to update the content of this jobs list or of the specified job.
    
    Since:
    
    4.3
  - updateDestruction
```
public final void updateDestruction(UWSJob 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(UWSJob)
  - removeJob
```
protected UWSJob 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:
    
    DestructionManager.remove(UWSJob)
  - destroyJob
```
public boolean destroyJob(java.lang.String jobId)
```
    Removes the job from the list and deletes all its attached resources (UWSJob.clearResources().
    Note: The jobs list of the destroyed job's owner is always updated.
    
    Important note: This function will not destroy the job, but will archive it in the following cases:
    - the destroy policy is ALWAYS_ARCHIVE,
    - the destroy policy is ARCHIVE_ON_DATE and the destruction time has been reached,
    In all the other cases but also if the job is already in ARCHIVED phase, the specified job will be destroyed.
    Parameters:
    
    jobId - The ID of the job to destroy.
    
    Returns:
    
    true if it has been successfully destroyed, false otherwise.
    
    See Also:
    
    removeJob(String), UWSJob.clearResources(), UWSService.getBackupManager(), UWSBackupManager.saveOwner(JobOwner), archiveJob(String)
  - destroyJob
```
public boolean destroyJob(java.lang.String jobId,
                          JobOwner user)
                   throws UWSException
```
    Removes the job from the list and deletes all its attached resources (UWSJob.clearResources(). The jobs list of the new job's owner is always saved.
    
    Parameters:
    
    jobId - The ID of the job to destroy.
    
    user - The user who asks to destroy the specified job.
    
    Returns:
    
    true if it has been successfully destroyed, false otherwise.
    
    Throws:
    
    UWSException - If the given user is not allowed to update the content of this jobs list or to destroy the specified job.
  - clear
```
public void clear()
```
    Destroys all jobs of this list.
    
    See Also:
    
    destroyJob(String)
  - clear
```
public void clear(JobOwner owner)
           throws UWSException
```
    Destroys all jobs owned by the specified user.
    
    Parameters:
    
    owner - The owner/user who asks for this operation.
    
    Throws:
    
    UWSException - If the given user is not allowed to update of the content of this jobs list.
    
    See Also:
    
    clear(), destroyJob(String)
  - serialize
```
public void serialize(javax.servlet.ServletOutputStream output,
                      UWSSerializer serializer,
                      JobOwner owner,
                      JobListRefiner listRefiner)
               throws UWSException,
                      java.io.IOException,
                      java.lang.Exception
```
    Serializes the while object in the given output stream, considering the given owner, the given job filters and thanks to the given serializer.
    
    Parameters:
    
    output - The ouput stream in which this object must be serialized.
    
    serializer - The serializer to use.
    
    owner - The current user.
    
    listRefiner - Special filter able to refine the list of jobs with job filters specified by the user (i.e. filter, sort and limit).
    
    Throws:
    
    UWSException - If the owner is not allowed to see the content of the serializable object.
    
    java.io.IOException - If there is an error while writing in the given stream.
    
    java.lang.Exception - If there is any other error during the serialization.
    
    Since:
    
    4.3
    
    See Also:
    
    UWSSerializer.getJobList(JobList, JobOwner, JobListRefiner, boolean)
  - serialize
```
public java.lang.String serialize(UWSSerializer serializer,
                                  JobOwner user)
                           throws UWSException,
                                  java.lang.Exception
```
    Description copied from class: SerializableUWSObject
    
    Serializes the whole object considering the given owner (supposed to be the current user) and thanks to the given serializer.
    
    Specified by:
    
    serialize in class SerializableUWSObject
    
    Parameters:
    
    serializer - The serializer to use.
    
    user - The current user.
    
    Returns:
    
    The serialized representation of this object.
    
    Throws:
    
    UWSException - If the owner is not allowed to see the content of the serializable object.
    
    java.lang.Exception - If there is any other error during the serialization.
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object

Class JobList

General description

Jobs list by user

Searching in a jobs list

Get the users list

Execution management

Automatic job destruction

Archiving and Job destruction policy

Field Summary

Constructor Summary

Method Summary

Methods inherited from class uws.job.SerializableUWSObject

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Field Detail

DEFAULT_JOB_DESTRUCTION_POLICY

jobsList

ownerJobs

Constructor Detail

JobList

JobList

JobList

JobList

Method Detail

getUWS

setUWS

getLogger

getDestructionManager

setDestructionManager

getExecutionManager

setExecutionManager

getDestroyPolicy

setDestructionPolicy

getUrl

getName

getJob

getJob

getJobs

getJobs

iterator

getNbJobs

getNbJobs

getUsers

getNbUsers

searchJobs

addNewJob

archiveJob

archiveJob

updateDestruction

removeJob

destroyJob

destroyJob

clear

clear

serialize

serialize

toString