Package com.polarion.platform.jobs

Interface IJobManager

All Superinterfaces:
IJobStateNotifier
public interface IJobManager extends IJobStateNotifier
Job manager.

Together with implementation of IJob 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 root jobs (and per javadoc of IJob also to all its children, present or future) and also to all root jobs created in the future (unless unregistered).

Unregistering IJobStateListener will unregister it from all root jobs (and per javadoc of IJob also from all its children).

Jobs (prepared, running or finished) do not survive through restarts.

Author:
Stepan Roh, Polarion Software
See Also:

  • Method Details

    • spawnJob

      IJob spawnJob(IJobUnit unit, IJob parent) throws GenericJobException
      Create new job based on given job unit.

      Returned job must be scheduled manually.

      IJobUnit.setLogger(ILogger) is called with ILogger which will record IJobLogEvents with proper job set.

      If parent job is null then IJobUnit.setWorkDir(File) is called with newly created unique working directory as an argument.

      Jobs are activated and run under Subject which was used while spawned.

      Parameters:
      unit - job unit
      parent - parent job (may be null)
      Returns:
      created IJob associated with given job unit
      Throws:
      IllegalArgumentException - if unit is null
      IllegalStateException - if job was already spawned for given unit or if parent job is not in activation phase
      IllegalStateException - if parent job is not in activation phase
      GenericJobException - if error occurs

    • getJobs

      List<IJob> getJobs()
      Return all available jobs (in any state).
      Returns:
      List of IJobs in spawn-order (not null)

    • getRootJobs

      List getRootJobs()
      Return all root jobs (in any state) = jobs without parent.
      Returns:
      List of IJobs in spawn-order (not null)

    • getJob

      @Nullable IJob getJob(String id)
      Return job with given id (if known).
      Parameters:
      id - job id
      Returns:
      job with given id or null if not found
      Throws:
      IllegalArgumentException - if id is null
      See Also:

    • finalizeFinishedRootJob

      void finalizeFinishedRootJob(IJob job)
      Finalize finished job. Called automatically upon job's finish after all state listeners were called, but before the release of all IJob.join()ed threads.

      It is illegal to finalize job which is not in a finished state or is not a root job.

      Will release any resources required for job's execution. Please note that after execution it is very little what one can do with a job apart from reading its state and log. Workdir associated with given job is NOT removed.

      It is permitted to finalize already finalized job.

      Parameters:
      job - job to finalize
      Throws:
      IllegalArgumentException - if job is null
      IllegalStateException - if job is not in a finished state or is not a root job

    • removeFinishedRootJob

      void removeFinishedRootJob(IJob job)
      Remove finished job.

      It is illegal to remove job which is not in a finished state or is not a root job.

      Workdir associated with given job is also removed.

      Parameters:
      job - job to remove
      Throws:
      IllegalArgumentException - if job is null
      IllegalStateException - if job is not in a finished state or is not a root job
      See Also:

    • isRootJobPrioritySupported

      boolean isRootJobPrioritySupported()
      Whether setting of root job's priority has some effect on who is going to run first.

      Note that even though root job's priority is not supported, priority propagation must still work (correct values are returned from IJob.getPriority().

      Returns:
      true if root job priority has full effect on scheduling, false otherwise

    • addJobStateListener

      void addJobStateListener(IJob job, IJobStateListener listener)
      Add listener for given job.
      Parameters:
      listener - listener
      Throws:
      IllegalArgumentException - if listener is null
      Since:
      3.7.3

    • removeJobStateListener

      void removeJobStateListener(IJob job, IJobStateListener listener)
      Remove listener for given job.

      Removal of already removed listener is permitted.

      Parameters:
      listener - listener
      Throws:
      IllegalArgumentException - if listener is null
      Since:
      3.7.3

    • getListeners

      Collection<IJobStateListener> getListeners(IJob job)
      Since:
      3.7.3