Interface IJob
- All Superinterfaces:
IJobStateNotifier
Job is a smallest scheduling entity.
Together with implementation of IJobManager
this is the core of Jobs Framework.
Those two classes are also tightly coupled. It is not defined what happens if "foreign"
IJob
is passed to the manager (or other auxiliary classes), but it should be forbidden.
Registering IJobStateListener
will automatically add it to all
child jobs and also to all child jobs created in the future (unless unregistered).
Unregistering IJobStateListener
unregister it from
all child jobs.
It is not specified whether the listeners are executed before join()
returns or not. It
is only assured that proper state is available when join()
returns or listener is invoked.
- Author:
- Stepan Roh, Polarion Software
- See Also:
-
Method Summary
Modifier and TypeMethodDescriptionvoid
addResource
(IJobResource resource) Add claimed resource.void
cancel()
Cancel this job.Return child jobs.float
Returns value between zero and one (both inclusive) indicating the completness of this job.long
Time of job creation.Current task name.long
Time of job finish.getId()
Unique job id.Job manager.Associated job unit.getName()
Job name.Parent job (if any).int
Job priority.Return claimed resources.long
Time of job start.getState()
Current job state.Job status (if any).int
boolean
Inaccessible job is a job for which it is not possible to obtain all details, e.g.void
join()
Wait until state changes toJobState.STATE_FINISHED
or return immediately if it is already in.void
schedule()
Schedule root job (and all its children) for running.void
setPriority
(int priority) Set job priority.Methods inherited from interface com.polarion.platform.jobs.IJobStateNotifier
addJobStateListener, removeJobStateListener
-
Method Details
-
getId
String getId()Unique job id.It is ensured that no other job has the same id during lifetime of Java application.
- Returns:
- unique job id (not
null
)
-
getJobManager
IJobManager getJobManager()Job manager.- Returns:
IJobManager
(notnull
)
-
getCreationTime
long getCreationTime()Time of job creation.Basically the time of
IJobManager.spawnJob(IJobUnit, IJob)
invocation.- Returns:
- creation time in miliseconds
- See Also:
-
getStartTime
long getStartTime()Time of job start.Basically the time when
getState()
changed toJobState.STATE_RUNNING
. Until then the value is undefined.- Returns:
- start time in miliseconds
- See Also:
-
getFinishTime
long getFinishTime()Time of job finish.Basically the time when
getState()
changed toJobState.STATE_FINISHED
. Until then the value is undefined.- Returns:
- finished time in miliseconds
- See Also:
-
getCompletness
float getCompletness()Returns value between zero and one (both inclusive) indicating the completness of this job.This indicates how far the job went before it finished. Generally if it finished without an error, the value should be one.
The value will probably keep changing during
JobState.STATE_RUNNING
to reflect the progress, although this depends on used framework. If this is the case the value should only increment, never decrement.Completness of child jobs should be taken into account when calculating this value, but is not required.
- Returns:
- completness value between
0.0f
and1.0f
(both inclusive)
-
getName
String getName()Job name.Shortcut for
getJobUnit().getName()
.- Returns:
- job name (not
null
)
-
getNodeId
String getNodeId()- Returns:
- Id of node where this job is running or
null
if this information is not available - Since:
- 3.8.0
-
getJobUnit
IJobUnit getJobUnit()Associated job unit.Clients should not use it.
- Returns:
- job unit (not
null
)
-
getParent
IJob getParent()Parent job (if any).Jobs without parent are called "root jobs".
- Returns:
- parent job or
null
-
getChildren
List getChildren()Return child jobs.Only those jobs in this job's package whose
getParent() == this
are returned. -
schedule
void schedule()Schedule root job (and all its children) for running.Will return immediately.
How the implementation should behave:
JobState.STATE_ACTIVATING
for all jobsIJobUnit.activate()
called on all jobs (even those spawned during activation)- exception thrown during activation will force manager to change state of all jobs to
JobState.STATE_ABORTED
and status toIJobStatus.JobStatusType.STATUS_TYPE_UNKNOWN
for all jobs andIJobStatus.JobStatusType.STATUS_TYPE_FAILED
for the job causing the abort (with the exception attached) and abort the scheduling. JobState.STATE_WAITING
for all jobs- execution of
schedule()
is terminated, rest is done asynchronously - total getWorkLength() is calculated and system progress monitor (the one used by underlying framework) is prepared for it
- cancelling system progress monitor will cause cancelation of root job
- job manager will wait till all resources (
getResources()
) are free and then locks them atomically - if there are more root jobs which may run, the one with higher priority has precedence (optional - seeIJobManager.isRootJobPrioritySupported()
)
- exception thrown during activation will force manager to change state of all jobs to
- run loop (unless all jobs are in
JobState.STATE_FINISHED
):- jobs not yet run whose children are in
JobState.STATE_FINISHED
are scheduled to run - these jobs are factorized into groups where there are no conflicting resources between them (= jobs claiming same resource are in a same group)
- one job from each group is run (asynchronously if supported by implementation) - those with higher priorities are picked first
- job and all of its parents are switched to
JobState.STATE_RUNNING
IJobUnit.run(IProgressMonitor)
is called, supplied progress monitor should update current task name, completness etc. and should reflect job cancelation- it is up to the parent (when he is run) to inspect status of all children and react appropriately
- job is switched to
JobState.STATE_FINISHED
(parents are left inJobState.STATE_RUNNING
)
- job and all of its parents are switched to
- jobs not yet run whose children are in
- Throws:
IllegalArgumentException
- if this job has parentIllegalStateException
- if already scheduled- See Also:
-
getState
JobState getState()Current job state.- Returns:
- job state (not
null
)
-
getCurrentTaskName
String getCurrentTaskName()Current task name.This comes directly from task and subtask names set by job unit in used
IProgressMonitor
.Will return non-
null
only inJobState.STATE_RUNNING
(but even thennull
can be returned).If child is running, this mirrors its setting.
- Returns:
- current task name or
null
-
getStatus
IJobStatus getStatus()Job status (if any).Will return non-
null
value only inJobState.STATE_FINISHED
and may return non-null
value inJobState.STATE_ABORTED
.- Returns:
- job status or
null
-
getResources
Collection<IJobResource> getResources()Return claimed resources.Includes resources claimed by all children.
Once all jobs switched to
JobState.STATE_WAITING
the returned collection will not change.- Returns:
Collection
ofIJobResource
s (notnull
)
-
addResource
Add claimed resource.Called by
IJobUnit.activate()
.- Parameters:
resource
- resource to claim- Throws:
IllegalArgumentException
- if resource isnull
IllegalStateException
- if state is notJobState.STATE_ACTIVATING
-
getPriority
int getPriority()Job priority.Unless overridden with
setPriority(int)
it is the value ofIJobUnit.getPriority()
as was at the time this job was spawned.- Returns:
- job priority
-
setPriority
void setPriority(int priority) Set job priority.Smaller value means higher priority. Zero value is considered to be the normal priority.
- Parameters:
priority
- wanted job priority
-
getWorkLength
int getWorkLength()Sum ofIJobUnit.getWorkLength()
andgetWorkLength()
of allgetChildren()
.Once all jobs switched to
JobState.STATE_WAITING
the returned value will not change.If at least one child has unknown work length (
IJobUnit.UNKNOWN_WORK_LENGTH
) then this job has unknown work length too.- Returns:
- number of ticks (greater or equal to zero)
- Throws:
IllegalStateException
- if called beforeschedule()
-
join
Wait until state changes toJobState.STATE_FINISHED
or return immediately if it is already in.Will also return immediately if scheduling process was aborted or the job became inaccessible (e.g. because the cluster node on which the job was running has died).
- Throws:
InterruptedException
- if calling thread is interrupted
-
cancel
void cancel()Cancel this job.Note that cancelation is "soft" signal and job may ignore it.
This will also cancel all child jobs (running or waiting). It will also prepare for cancelation this job if it is not yet running (will be canceled through its progress monitor as soon as it is run).
-
isInaccessible
boolean isInaccessible()Inaccessible job is a job for which it is not possible to obtain all details, e.g. because a cluster node, on which the job was executed, was deactivated. Inaccessible job always returns the job id fromgetId()
, other methods can throw @linkInaccessibleJobException
.- Since:
- 3.8.0
-