Package com.polarion.platform.jobs

Interface IJobDescriptor

All Known Implementing Classes:
BasicJobDescriptor, HiddenJobDescriptor
public interface IJobDescriptor
Job (unit) descriptor.

Mainly describes what job parameters are expected when job is spawned.

Intended for usage by UI and scheduler. Jobs which are not supposed to be spawned directly by user should return true from isHidden() and may not supply some information, e.g. available parameters (available types are restricted which could complicate parameter passing between jobs).

System job parameters are not described by this descriptor.

It is perfectly legal to set job parameters which are not listed among job parameters here.

Distinction between names, labels and descriptions (this applies only to this class and its inner classes and may mean different concepts in outer world):

name
identification used in configuration files and similar places; should be alphanumeric with dots and underscores (regular expression [a-zA-Z._][0-9a-zA-Z._]*)
label
short (up to one sentence) human-readable name (arbitrary value); is always present, may be the same as name
description
long (or presumably long) human-readable description (kind of help); not required

Dynamic job descriptor is term used for IJobDescriptor with associated IJobUnit. Such descriptor will change its contents to match values placed into the unit (for unset values, their IJobDescriptor.IJobParameter.getDefaultValue() is used). Changes are visible immediately. Things which will never change are marked as such in their javadoc (if complex value is marked it means that the value will not change, but its contents may). In short: available parameters, their types and group hierarchy will stay intact, labels, descriptions and available choices may change. Note that even if job unit is passed, descriptor may choose to ignore it.

Note on required parameters and default values: required parameters can not be null, default values are values which should be presented in UI as default (and later set by UI if user does not choose different), but are not automatically set by system if parameter is left unset and are not under any circumstances used by scheduler (default value is only a hint for UI).

Mapping from IJobDescriptor.IJobParameter.getName() to set method follows Java Beans convention: first character is capitalized and set is prepended.

Author:
Stepan Roh, Polarion Software
See Also:

  • Method Details

    • getLabel

      String getLabel()
      Human-readable job label.

      Protected from dynamic change.

      Returns:
      label (not null)

    • getDescription

      String getDescription()
      Human-readable job description (if any).

      Protected from dynamic change.

      Returns:
      description or null

    • isHidden

      boolean isHidden()
      Whether this job is hidden from user (not shown in UI).

      UI may decide to show hidden jobs for administration purposes.

      Protected from dynamic change.

      Returns:
      true if this job is hidden, false otherwise

    • getRootParameterGroup

      IJobDescriptor.IJobParameterGroup getRootParameterGroup()
      Root parameter group.

      null is returned only if there are no user-visible parameters.

      Although root group must have label, UI may choose to ignore it and skip this level.

      Protected from dynamic change.

      Returns:
      root parameter group or null

    • getParameterGroup

      IJobDescriptor.IJobParameterGroup getParameterGroup(String name)
      Return parameter group of given name (if known).

      Protected from dynamic change.

      Parameters:
      name - group name
      Returns:
      group or null if unknown
      Throws:
      IllegalArgumentException - if name is null

    • getParameter

      IJobDescriptor.IJobParameter getParameter(String name)
      Return parameter description of given name (if known).

      Protected from dynamic change.

      Parameters:
      name - parameter name
      Returns:
      parameter or null if unknown
      Throws:
      IllegalArgumentException - if name is null

    • getJobUnit

      IJobUnit getJobUnit()
      Job unit used by dynamic descriptor.

      Descriptor will not make any changes in this unit, it is fully under caller's control.

      Protected from dynamic change.

      Returns:
      associated job unit or null