public class JobList extends SerializableUWSObject implements java.lang.Iterable<UWSJob>
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.
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.
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.
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()
).
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)
.
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)
.
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}).
UWSJob
,
Serialized FormModifier 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 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.
|
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.
|
serialize, serialize, serialize
public static final JobDestructionPolicy DEFAULT_JOB_DESTRUCTION_POLICY
protected final java.util.Map<java.lang.String,UWSJob> jobsList
public JobList(java.lang.String jobListName) throws java.lang.NullPointerException
jobListName
- The jobs list name.java.lang.NullPointerException
- If the given job list name is NULL.JobList(String, ExecutionManager)
public JobList(java.lang.String jobListName, ExecutionManager executionManager) throws java.lang.NullPointerException
jobListName
- The jobs list name.executionManager
- The object which will manage the execution of
all jobs of this list.java.lang.NullPointerException
- If the given job list name is NULL
or empty
or if no execution manager is provided.public JobList(java.lang.String jobListName, DestructionManager destructionManager) throws java.lang.NullPointerException
jobListName
- The jobs list name.destructionManager
- The object which manages the automatic
destruction of jobs when they have reached
their destruction date.java.lang.NullPointerException
- If the given job list name is NULL
or empty
or if no destruction manager is provided.public JobList(java.lang.String jobListName, ExecutionManager executionManager, DestructionManager destructionManager) throws java.lang.NullPointerException
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.java.lang.NullPointerException
- If the given job list name is NULL or empty
or if no execution manager and destruction
manager are provided.public final UWS getUWS()
public final void setUWS(UWS newUws) throws java.lang.IllegalStateException
Note: The UWS association can be changed ONLY IF the jobs list is not yet associated with a UWS OR IF it is empty.
newUws
- Its new UWS.
If NULL, nothing is done!java.lang.IllegalStateException
- If this jobs list is already associated
with a UWS (different from the given
one) and contains some jobs.public UWSLog getLogger()
getUWS()
,
UWS.getLogger()
,
UWSToolBox.getDefaultLogger()
public final DestructionManager getDestructionManager()
Note: Remember that the destruction manager lets destroying automatically jobs only when their destructionTime has been reached.
public final void setDestructionManager(DestructionManager newManager)
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.
newManager
- Its new destruction manager (MUST be different from
null otherwise nothing is done).DestructionManager.remove(UWSJob)
,
DestructionManager.update(UWSJob)
public final ExecutionManager getExecutionManager()
public final void setExecutionManager(ExecutionManager manager)
Note: All jobs managed by the old execution manager are removed from it and added to the new manager.
manager
- The execution manager to use (MUST be different from
null otherwise nothing is done).ExecutionManager.remove(UWSJob)
,
ExecutionManager.execute(UWSJob)
public final JobDestructionPolicy getDestroyPolicy()
public final void setDestructionPolicy(JobDestructionPolicy destroyPolicy)
destroyPolicy
- The job destruction policy to set.
If NULL, the default policy (i.e.
DEFAULT_JOB_DESTRUCTION_POLICY
) will be
set.public UWSUrl getUrl()
UWSService.getUrlInterpreter()
,
UWSUrl.listJobs(String)
public final java.lang.String getName()
public final UWSJob getJob(java.lang.String jobID)
jobID
- The ID of the job to get.public UWSJob getJob(java.lang.String jobID, JobOwner user) throws UWSException
jobID
- ID of the job to get.user
- The user who asks this job (null means no particular
owner => cf getJob(String)
).UWSException
- If the given user is not allowed to read the content
of this jobs list or to read the specified job.public final java.util.Iterator<UWSJob> getJobs()
iterator()
public java.util.Iterator<UWSJob> getJobs(JobOwner user)
user
- The owner/user who asks for this operation
(may be null).public final java.util.Iterator<UWSJob> iterator()
iterator
in interface java.lang.Iterable<UWSJob>
Iterable.iterator()
public final int getNbJobs()
public final int getNbJobs(JobOwner user)
user
- The owner/user (may be null).public final java.util.Iterator<JobOwner> getUsers()
public final int getNbUsers()
public final java.util.List<UWSJob> searchJobs(java.lang.String runID)
runID
- The runID of jobs to search.public java.lang.String addNewJob(UWSJob j) throws UWSException
j
- The job to add.UWSException
- If the owner of the given job is not allowed to add
any job into this jobs list.UWSJob.setJobList(JobList)
,
UWSService.getBackupManager()
,
UWSBackupManager.saveOwner(JobOwner)
,
DestructionManager.update(UWSJob)
,
UWSJob.applyPhaseParam(JobOwner)
public boolean archiveJob(java.lang.String jobId)
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.
jobId
- The ID of the job to archive.UWSJob.archive()
public boolean archiveJob(java.lang.String jobId, JobOwner user) throws UWSException
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.
jobId
- The ID of the job to archive.user
- The user who asks to archive the specified job.UWSException
- If the given user is not allowed to update the
content of this jobs list or of the specified job.public final void updateDestruction(UWSJob 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.
job
- The job whose the destructionTime may have been modified.DestructionManager.update(UWSJob)
protected UWSJob removeJob(java.lang.String jobId)
jobId
- The ID of the job to remove.DestructionManager.remove(UWSJob)
public boolean destroyJob(java.lang.String jobId)
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:
destroy policy
is ALWAYS_ARCHIVE
,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.
jobId
- The ID of the job to destroy.removeJob(String)
,
UWSJob.clearResources()
,
UWSService.getBackupManager()
,
UWSBackupManager.saveOwner(JobOwner)
,
archiveJob(String)
public boolean destroyJob(java.lang.String jobId, JobOwner user) throws UWSException
UWSJob.clearResources()
. The jobs list of the new job's owner is
always saved.jobId
- The ID of the job to destroy.user
- The user who asks to destroy the specified job.UWSException
- If the given user is not allowed to update the
content of this jobs list or to destroy the
specified job.public void clear()
destroyJob(String)
public void clear(JobOwner owner) throws UWSException
owner
- The owner/user who asks for this operation.UWSException
- If the given user is not allowed to update of the
content of this jobs list.clear()
,
destroyJob(String)
public void serialize(javax.servlet.ServletOutputStream output, UWSSerializer serializer, JobOwner owner, JobListRefiner listRefiner) throws UWSException, java.io.IOException, java.lang.Exception
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).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.UWSSerializer.getJobList(JobList, JobOwner, JobListRefiner, boolean)
public java.lang.String serialize(UWSSerializer serializer, JobOwner user) throws UWSException, java.lang.Exception
SerializableUWSObject
serialize
in class SerializableUWSObject
serializer
- The serializer to use.user
- The current user.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.public java.lang.String toString()
toString
in class java.lang.Object