Package com.polarion.platform.jobs

Interface IJob

All Superinterfaces:

IJobStateNotifier

public interface IJob
extends IJobStateNotifier

Job.

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:

• IJobManager

Method Summary

Modifier and Type	Method	Description
void	addResource(IJobResource resource)	Add claimed resource.
void	cancel()	Cancel this job.
List	getChildren()	Return child jobs.
float	getCompletness()	Returns value between zero and one (both inclusive) indicating the completness of this job.
long	getCreationTime()	Time of job creation.
String	getCurrentTaskName()	Current task name.
long	getFinishTime()	Time of job finish.
String	getId()	Unique job id.
IJobManager	getJobManager()	Job manager.
IJobUnit	getJobUnit()	Associated job unit.
String	getName()	Job name.
String	getNodeId()
IJob	getParent()	Parent job (if any).
int	getPriority()	Job priority.
Collection<IJobResource>	getResources()	Return claimed resources.
long	getStartTime()	Time of job start.
JobState	getState()	Current job state.
IJobStatus	getStatus()	Job status (if any).
int	getWorkLength()	Sum of IJobUnit.getWorkLength() and getWorkLength() of all getChildren().
boolean	isInaccessible()	Inaccessible job is a job for which it is not possible to obtain all details, e.g.
void	join()	Wait until state changes to JobState.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 (not null)

getCreationTime

long getCreationTime()

Time of job creation.

Basically the time of IJobManager.spawnJob(IJobUnit, IJob) invocation.

Returns:

creation time in miliseconds

See Also:

• System.currentTimeMillis()

getStartTime

long getStartTime()

Time of job start.

Basically the time when getState() changed to JobState.STATE_RUNNING. Until then the value is undefined.

Returns:

start time in miliseconds

See Also:

• System.currentTimeMillis()

getFinishTime

long getFinishTime()

Time of job finish.

Basically the time when getState() changed to JobState.STATE_FINISHED. Until then the value is undefined.

Returns:

finished time in miliseconds

See Also:

• System.currentTimeMillis()

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 and 1.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.

Returns:

List of IJobs in spawn-order (not null)

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 jobs
• IJobUnit.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 to IJobStatus.JobStatusType.STATUS_TYPE_UNKNOWN for all jobs and IJobStatus.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 - see IJobManager.isRootJobPrioritySupported())
• 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 in JobState.STATE_RUNNING)

Throws:

IllegalArgumentException - if this job has parent

IllegalStateException - if already scheduled

See Also:

• cancel()

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 in JobState.STATE_RUNNING (but even then null 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 in JobState.STATE_FINISHED and may return non-null value in JobState.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 of IJobResources (not null)

addResource

void addResource(IJobResource resource)

Add claimed resource.

Called by IJobUnit.activate().

Parameters:

resource - resource to claim

Throws:

IllegalArgumentException - if resource is null

IllegalStateException - if state is not JobState.STATE_ACTIVATING

getPriority

int getPriority()

Job priority.

Unless overridden with setPriority(int) it is the value of IJobUnit.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 of IJobUnit.getWorkLength() and getWorkLength() of all getChildren().

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 before schedule()

join

void join()
   throws InterruptedException

Wait until state changes to JobState.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 from getId(), other methods can throw @link InaccessibleJobException.

Since:

3.8.0