Package com.polarion.platform.jobs

Interface IJobUnit

All Known Subinterfaces:
IBranchDocumentsJob, ICleanJobUnit, ICleanupJobUnit, IExecuteCommandJobUnit, ILogsCleanupJobUnit, IMasterBuildJobUnit, IMultiJobUnit, IProjectManagementJobUnit, ISyncUserGroupsJobUnit, ISyncUsersJobUnit, ITestResultsImportJobUnit
All Known Implementing Classes:
AbstractJobUnit
public interface IJobUnit
Job unit.

This represents the user-implemented portion of IJob encapsulating the work done on behalf of the job.

None of the methods on this interface are intended to be called by clients.

Job unit is one-time class, once run, it is thrown away.

WARNING: If this interface is used on a cluster node other than that on which the job runs, clients can call only methods that return serializable results and take only serializable (or no) arguments. This holds also for methods on all interfaces that the custom job unit may implement. The only exception is method getLogger() which can be used remotely, but the only methods that can be used on the returned logger are ILogger.getLogFile() and ILogger.getLogFiles().

Author:
Stepan Roh, Polarion Software
See Also:

  • Field Details

  • Method Details

    • getCreator

      IJobUnitFactory getCreator()
      Return factory used for creation of this job unit.

      Job unit can not exist without factory.

      Returns:
      factory (not null)

    • getName

      String getName()
      Job name.
      Returns:
      job name (not null)

    • getJob

      IJob getJob()
      Associated IJob.

      Will be null until IJobManager.spawnJob(IJobUnit, IJob) is called.

      Returns:
      IJob or null

    • setJob

      void setJob(IJob job)
      Set associated IJob.
      Parameters:
      job - associated job
      Throws:
      IllegalArgumentException - if job is null
      IllegalStateException - if job was already associated

    • activate

      void activate() throws GenericJobException
      Activate job.

      Implementation should:

      • call getJob().addResource() for any resources it wants to lock
      • compute work length for getWorkLength()
      • spawn jobs which it depends on

      No resources which need manual destruction should be allocated.

      Throwing exception from this method will stop the scheduling process and no jobs will be run.

      Throws:
      IllegalStateException - if already called
      IllegalStateException - if no job is associated (getJob() is null)
      GenericJobException - if error occurs

    • run

      IJobStatus run(IProgressMonitor progress)
      Run job.

      Method must not return before the job completes its execution even if it handles some work in separate threads.

      Children spawned during activate() (if this job was given as their parent) will all finish prior to execution of this method.

      Supplied progress monitor should be prepared for getWorkLength() ticks. It will ignore totalWork parameter supplied to IProgressMonitor.beginTask(String, int).

      Returned status may (or may not) be multi-status (or otherwise reflect status) of getJob().getChildren().

      If progress monitor is cancelled, IJobStatus.JobStatusType.STATUS_TYPE_CANCELLED must be returned as early as possible.

      Although job manager will catch any exception thrown from this method and interpret it as IJobStatus.JobStatusType.STATUS_TYPE_FAILED it is recommended to wrap any exception (other than those listed here) as returned status.

      Parameters:
      progress - progress monitor to use
      Returns:
      IJobStatus (not null)
      Throws:
      IllegalArgumentException - if progress is null
      IllegalStateException - if called before activate()
      IllegalStateException - if already called
      IllegalStateException - if no job is associated (getJob() is null)

    • getWorkLength

      int getWorkLength()
      Return number of ticks run(IProgressMonitor) is expected to take.

      Allows for precise computation of progress bar.

      Returns:
      number of ticks (greater or equal to zero or UNKNOWN_WORK_LENGTH)
      Throws:
      IllegalStateException - if called before activate()

    • getPriority

      int getPriority()
      Return requested priority (is taken as an advise for IJob.getPriority().

      Return zero for "normal" priority.

      Returns:
      requested priority

    • setWorkDir

      void setWorkDir(File workDir)
      System job parameter: working directory.

      May be shared with other jobs with same root job. Working directory of one root job must be different from working directories of other root jobs.

      Set automatically for root job by job manager, must be set manually for jobs with parent.

      Parameters:
      workDir - working directory
      Throws:
      IllegalArgumentException - if workDir is null

    • setLogger

      void setLogger(ILogger logger)
      System job parameter: logger.

      Set automatically for all jobs by job manager.

      Logger will contain at least all logged events from child jobs when produced (but may contain more).

      It is advised to output logged messages to some file in workdir besides other targets.

      Parameters:
      logger - logger
      Throws:
      IllegalArgumentException - if logger is null
      See Also:

    • getLogger

      ILogger getLogger()
      System job parameter: logger.
      Returns:
      logger (not null if running)
      See Also:

    • setScope

      void setScope(IContext context)
      Job parameter: job scope.

      Value of null (or if it is missing) means both "global scope" and "I don't care" (depends on invoked job).

      Parameters:
      context - scope of this job (may be null)
      See Also:

    • getScope

      IContext getScope()
      Job parameter: job scope.
      Returns:
      scope of this job or null
      See Also: